Skip to content

Same-file reference produces drift with a misleading message ("no longer matches any step") #117

Description

@aslakhellesoy

Follow-up to #108, which concluded: "No false drift, because a consumed oath's baseline is derived from its own (empty) plan and so records no live examples."

That holds when a whole file is referenced from elsewhere. It does not hold for a same-file reference ([The market](#the-market)), which is the shape I reached for most often — the setup belongs with the examples that use it, so splitting it into its own file would be worse documentation.

In that shape the document's plan is not empty: it contains the referring examples. The consumed section's paragraphs overlap none of them, so isLive is false, and drift fires.

Repro

Take a passing single-example oath and hoist its setup into a section the example links to:

## The market

Owen and Osiris between them have three pieces hanging, so the following people have accounts:

| email             | name       |
| ----------------- | ---------- |
| owner@example.com | Owen Owner |

## The order lists every artwork separately

[The market](#the-market)

A visitor takes a few of each and puts the following shares in the basket:
...

On 0.8.1:

Error: This paragraph was an example and no longer matches any step (drift):
  "Owen and Osiris between them have three pieces hanging, so the following people have accounts:".
Error: This paragraph was an example and no longer matches any step (drift):
  "Between them the following artworks are on the market:".

Tests  2 failed | 1 passed (3)

The example itself passes — the splice works correctly. Only drift objects.

The message is wrong

"no longer matches any step" is not what happened. Both paragraphs still match their steps perfectly; the identical step text matches in other oaths in the same run. What changed is that they are now spliced in at the reference instead of running here.

drift.js is honest about this in its comments — isLive is "overlaps a planned example", and the remedy offered is "Fix the step so it matches again, or accept it as prose". Neither applies. I lost a while looking for a broken step definition that was never broken, then re-read drift.js to understand what the diagnostic actually meant.

Suggestions

  1. A distinct diagnostic. The planner knows the section was consumed — workspace.referenced has the key. So the condition "was an example, is not live, and is consumed by a reference" is directly detectable and deserves its own message: "This section is now spliced into N reference(s); its paragraphs no longer run as an example here." That is a sentence an author can act on.
  2. Consider not gating on it. Converting an example into shared setup is a deliberate, structurally-evident refactor, not decay. Drift exists to stop a test quietly becoming documentation — but these paragraphs are still executed, just somewhere else. If you keep the gate, the message in (1) makes accepting it an informed choice rather than a shrug.
  3. Either way, reference/examples.mdx should say what happens to a section's baseline when it becomes referenced — Decide how drift works for a consumed (referenced) section #108 already suggested documenting the asymmetry, and this is the case that makes it visible.

Happy to send a PR for (1) if you'd like the shape I have in mind.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions