@am_shork/attest 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -13,7 +13,319 @@ input, removes/renames a public API or `--json` field, or changes a default
 runtime behavior an existing invocation relies on — diagnostic message text is
 not API.
 
-## [Unreleased]
+## [0.4.1] - 2026-07-29
+
+Every diagnostic now links to a section that explains it, and the README is a
+README again — the reference it had grown into has a page of its own, in both
+languages, saying which version each part of it arrived in. No behaviour a CI
+step branches on changed; the human report gains one line per issue.
+
+### Added
+
+- **A troubleshooting document, with one section per issue code — and every
+  diagnostic links to its own.** A diagnostic names a rule and states a fix in
+  one line, which is the right size for a reader who already knows the rule and
+  the wrong size for the one who does not — and the second reader is the one
+  adopting Attest, who meets six codes at once on their first run. The knowledge
+  was not missing so much as filed where nobody looks during a failure: the
+  cross-platform traps (a backslash is an escape in a glob; Vitest's 5-second
+  default against a scenario that starts a subprocess) lived in `CLAUDE.md`,
+  which ships with no release, and the rationale lived in a 450-line README
+  nobody greps mid-failure. Both languages, as always
+  (`docs/{en,zh}/troubleshooting.md`).
+
+  What makes this cheap to keep true is that `code` was already the
+  machine-readable name of a rule, so the section heading is the code verbatim
+  and the link is *derived*: there is no second string to keep in step, and so
+  no way to ship a diagnostic pointing at the wrong section. The remaining
+  failure mode — a section that does not exist — is closed from the other end:
+  `Issue.code` is narrowed from `string` to the roster in `core/docs.ts`, which
+  the suite asserts against both documents. An undocumented diagnostic is now a
+  compile error. (That narrowing found two families of codes a regex over the
+  source had missed, because they are built through a helper rather than written
+  at the issue site.) The two readers that restate a *subset* of the roster —
+  `StaticReadCode`, `DeltaReadCode` — are now asserted to be subsets of it in
+  `tests/issue-code-types.spec-d.ts`. That was already caught, but downstream
+  and by accident: the failure surfaced where the code is assigned into an
+  `Issue`, several files from the two lines that disagree.
+
+  Links are pinned to `v<version>` — the tag of the build that printed the
+  diagnostic — not to `main`. The two failure modes are not the same size. An
+  unresolved tag exists only between a release commit and its push, which is a
+  version nobody has installed, so no build in anyone's `node_modules` prints
+  those links. An unpinned link is dereferenced by every installed copy forever,
+  and the first breaking change to a code turns years of shipped builds into
+  links that miss — or worse, land on a section confidently describing a rule
+  that has since been redefined. (`main` remains the fallback for the one case
+  where pinning is impossible rather than imprecise: an unreadable manifest.)
+
+- **`docsUrl` on every issue in `--json`.** Additive, so no `schemaVersion`
+  bump. It is attached in the one envelope every report is built through —
+  including the `internal-error` crash path — rather than at the ~26 sites that
+  construct an `Issue`, for the same reason `hasError` is one function. It is
+  for the human reading a CI log; a consumer should still branch on `code`,
+  which is the more precise form of the same information.
+
+### Changed
+
+- **Every issue in the human report gains a line: `→ <docs url>`, dim, under the
+  message.** The one behaviour change an existing invocation can notice. No exit
+  code moves, no verdict moves, no input that passed now fails, and `--json` is
+  untouched by it — but a snapshot test over `attest`'s stdout will need
+  re-recording. That report is prose for humans by the same rule that makes
+  `Issue.message` prose (see *Versioning* above); the machine surface is
+  `--json`, which is where a CI step should have been looking.
+
+- **`Issue.code` is typed `IssueCode`, not `string`.** Breaking only for code
+  that *constructs* an `Issue` — reading one, which is what `--json` consumers
+  do, gets strictly more type information than before. Nothing in the CLI
+  surface, the report shape or the exit codes changes.
+
+  `SCHEMA_VERSION` stays at 1 for this too, not only for `docsUrl`: the emitted
+  values are the same strings they always were, so nothing on the wire changed
+  and no consumer can tell the difference. The narrowing is a compile-time
+  constraint on this repository, not a report-shape change.
+
+- **The README is a README again; the reference moved to
+  `docs/{en,zh}/cli-reference.md`.** It had become four documents wearing one
+  hat — a pitch, a tutorial, a CLI reference and a running design argument — at
+  470 lines, which is long past the point where a newcomer reads it and well
+  past where anyone looks up a flag in it. It is now 199: the pitch, a
+  five-minute start, and a table of where everything else lives. Nothing was
+  deleted. Per-command behaviour, `--eval`, `--vitest-config`, the run scope and
+  the whole `--json` shape are in the new reference; the rationale for the
+  diagnostics that were argued through in the README (`registry-not-static`,
+  `duplicate-prefix`, `empty-spec`, `stale-spec-doc`) already had a better home
+  in the troubleshooting document, so the reference states the rule and links to
+  it rather than restating the argument a third time.
+
+  Each section of the reference that has changed since it first shipped now
+  carries a collapsed **History** table. Attest is 0.x and moves fast enough
+  that a page describes the latest build to a reader who installed an earlier
+  one, with nothing to tell them which half applies — `--vitest-config` has
+  existed since 0.1.5, the run has been scoped to attesting spec files only
+  since 0.2.0, and the registry has had to be a literal only since 0.2.0. The
+  rows were written from this file. A gate checks that every version they name
+  is a heading in it, so a row cannot cite a version that was never cut; it
+  cannot check that a row is *true*, which still needs a reader with the
+  changelog open. `Unreleased` counts as a heading while one exists — and stops
+  counting when a release removes it, which is what makes renumbering those rows
+  part of cutting the release rather than something to remember.
+
+  The two documentation gates widened with it: they scanned `README.md` alone,
+  and the JSON sample they exist to catch had just moved out from under them.
+  They now enumerate `README.md` plus every `*.md` in both language directories,
+  so a page added later is covered by default rather than by remembering.
+
+- **`packageVersion()` moved from `src/cli/version.ts` to `src/core/version.ts`.**
+  It answers "which build is this", which `core/docs.ts` now has to ask in order
+  to pin a link — not a CLI concern. Neither path is in the `exports` map, so
+  nothing installable can have been importing either.
+
+## [0.4.0] - 2026-07-28
+
+Reading a registry no longer opens a port or lets the repository under test write
+to the reader's terminal, the id prefix finally has something that notices two
+files claiming it, and the peer range now says what CI actually proves rather
+than what the tool was hoped to work on.
+
+### Added
+
+- **Two registry files claiming one id prefix is now an ERROR.** The id grammar
+  is one flat space, `^[A-Z]+-\d+$`, and the prefix inside it was habit rather
+  than scope: nothing allocated it, reserved it, or noticed that two files had
+  picked the same one (design §11). Every cross-file check there was keys on the
+  whole id, so `AUTH-3` in `auth.reqs.ts` and `AUTH-9` in `session.reqs.ts` was
+  a clean `check` — two owners of one space, and the first anyone would hear of
+  it is the `duplicate-requirement` on the day the counters happen to meet, by
+  which point both files have a history. `loadRegistry` (`locate.ts`) already
+  held the `(file, id)` pair in the fold where `duplicate-requirement` is
+  raised, so the whole mechanism is a prefix→file map in that same loop, and
+  because it is that fold, every command that reads intent gets the diagnostic:
+  `check`, `cover`, `render`, `status`, `verify`, `archive`.
+  **What the issue carries.** `file` is the file that arrived *second* in sorted
+  order, matching `duplicate-requirement`, which also files against the file
+  being folded — and the file that claimed the prefix first is named in the
+  message, because a collision is a fact about a pair, an `Issue` carries one
+  path, and an error naming only one end leaves its reader grepping the
+  repository to find the other. There is **no `reqId`**: the ids involved are
+  individually valid and it is the space above them that has two owners, so
+  there is no single requirement the issue is about. It is raised **once per
+  colliding prefix per file**, not once per requirement — a registry with forty
+  ids under a taken prefix reports one sentence, not forty. Where a duplicate id
+  is also present both fire, which is not a restatement: sharing `A-1` implies
+  sharing `A-`, and the converse — the case this exists for — does not hold.
+  Now a requirement (ATX-39).
+  **Not a behaviour change for anything that passes today**, and that was
+  checked rather than assumed: all six `*.reqs.ts` in this repo sit in six
+  separate project roots holding one registry file each, so no root has two
+  files to collide. It is still a new ERROR on input that used to pass, so an
+  adopter whose registries share a prefix goes red on upgrade with nothing else
+  changing — deliberately, since that is the state the rule exists to report,
+  and the fix is a prefix rather than a migration. `SCHEMA_VERSION` stays 1: a
+  new `code` value is additive, and neither the envelope nor the `Issue`
+  interface moved.
+  The other half of the rule this was cut from — that a prefix must match its
+  file's name — was **rejected**; see "Considered and rejected".
+
+### Security
+
+- **Reading a registry opened a network port.** The loader borrows Vite to
+  transform and evaluate a `*.reqs.ts`, and `middlewareMode` suppresses Vite's
+  HTTP server but not its HMR WebSocket server — so `verify`, `archive`, and any
+  read command under `--eval` bound port 24678 on *every* interface for the
+  length of the run, on developer machines and CI runners alike, for a channel
+  nothing here subscribes to. `server.ws` is now `false`, which is the option
+  that actually closes it: `hmr: false` does not, because the socket is created
+  before the HMR option is consulted. The visible symptom was two concurrent
+  runs colliding and printing `WebSocket server error: Port is already in use`
+  into the middle of a report, through a log level that was supposed to have
+  silenced the loader. Now a requirement (ATX-36), asserted as a count of
+  listening handles rather than a port number, because the port is Vite's to
+  change and the property Attest needs is that reading intent is not a network
+  operation.
+- **The human report let the repository under test write to the reader's
+  terminal.** Scenario names and file paths are quoted verbatim into
+  `orphan-test`, `declared-not-run` and `never-red`, and the parser hands back
+  the *cooked* string — so an escape written in a spec file arrived at the
+  terminal as a real control byte. On a fork merge request the author of that
+  string is not the person reading the report, and the payload erases lines,
+  repaints a red verdict green, or retitles the window. Every control character
+  except the newline is now replaced with a space, in the message, the file
+  path, the code, and the ids and change name a `status` report prints. The
+  newline survives, because `registry-invalid` legitimately carries a list of
+  field errors — but the continuation is indented, so injected text cannot
+  occupy the column a genuine header does. `--json` was never affected
+  (serialising escapes the same characters), which is exactly why this had to be
+  fixed on the side people read. Now a requirement (ATX-37).
+- **Dependency advisories, and a gate so the next ones are not found by hand.**
+  The dev toolchain moved to Vite 8 and Vitest 4, clearing a high-severity
+  `server.fs.deny` bypass on Windows alternate paths, an NTLMv2 hash disclosure
+  via UNC path handling, two moderate path-traversal/dev-server advisories, and
+  a critical Vitest UI advisory that this tool never reached but shipped in its
+  lockfile regardless. `brace-expansion` is pinned past its DoS advisory through
+  a `pnpm.overrides` entry, since it arrives only through ESLint. A new `audit`
+  CI job runs `pnpm audit --audit-level=high`, not `allow_failure`: it is the
+  one job here that can go red on a commit that changed nothing, which is the
+  point — a dependency becomes vulnerable on the day it is disclosed, not on the
+  day someone next edits `package.json`. This also closes a real coverage gap:
+  `peerDependencies` has claimed Vite 8 and Vitest 4 since 0.3.0 while CI only
+  ever ran Vite 5 and Vitest 2.
+
+### Fixed
+
+- **`--eval` crashed on a registry the reading path diagnoses properly.** The
+  evaluating reader called a module's default export a registry because it was
+  an object — an assertion standing in for a check, on the one path where the
+  value has not already been through `defineRequirements`. A file that
+  default-exports a plain literal instead of calling it therefore arrived at the
+  validator unchecked, where reading `.statement` off a number threw: `--eval`
+  answered with an `internal-error` carrying a raw TypeError, for a file the
+  static reader reports with a code, a line and a fix hint — and that fix hint
+  is "pass `--eval`", so the documented way out of one diagnostic led into a
+  crash. The evaluating path now hands what it loaded to the same
+  `RegistrySchema`, so both readers refuse the same file. Behaviour change for
+  anyone branching on the code: this input used to produce `internal-error` and
+  now produces `registry-invalid`; both are ERRORs, so no exit code moves. It is
+  also a stricter read than before — a registry that `--eval` accepted only
+  because nothing looked at it is now rejected, and unknown fields are stripped
+  by the schema exactly as `defineRequirements` already strips them. Now a
+  requirement (ATX-38), kept apart from ATX-17: that one promises the escape
+  hatch exists and is honest about its cost, and a reader can satisfy it
+  completely while validating nothing it evaluates — which is the state this
+  was in.
+- **A corrupt first-run record leaked a value that is not an outcome into the
+  report.** Reading `changes/<name>/first-run.json` asserted its contents rather
+  than checking them: the guard tested that `firstRun` was an object and was
+  *declared* to return the record type, so a hand-edited or half-written file
+  put an arbitrary string where `pass`/`fail` is the whole domain. It travelled
+  — out through `status`'s `progress[].scenarios[].firstRun`, whose declared
+  type is `Outcome | null`, into the `--json` contract, and into a human row
+  whose hint matched neither "passed first" nor "never run" and so printed
+  blank. The archive gate was never at risk, because `hasRecordedRed` compares
+  against `fail` and anything unrecognised blocks exactly like a missing record;
+  this closes the report, not the gate. A record that does not validate is now
+  discarded whole, which is the existing "no more permissive than a missing
+  file" rule one step further: the cost is a stage-1 run to re-observe, and
+  keeping the entries that happened to parse would present a partial history as
+  if it were the whole one. Behaviour change confined to corrupt files: that
+  `--json` field now reads `null` where it used to echo whatever was on disk.
+- **The test verdict could fail open.** `runAndCollect` read the failure count
+  through `getCountOfFailedTests?.() ?? 0`, but the method is required on
+  Vitest's state — so the guard was dead at the type level, and had it ever
+  become live it defaulted the wrong way, reading a missing API as zero failures
+  and turning a red suite green. Latent rather than observed: no released
+  version reported a wrong verdict because of it. This is the one boolean in the
+  engine that may never fail open.
+- **`archive` answered `internal-error` for a file `status` diagnoses
+  properly.** A `requirements.delta.ts` that loads but default-exports nothing
+  reached `applyDelta` as `undefined`, where reading `.renamed` off it threw a
+  TypeError — so the gate crashed out through the `--json` envelope's crash path
+  instead of reporting `change-not-found`, and the fix hint went with it.
+  `archive` now makes the same check `status` already made. Behaviour change for
+  anyone branching on the code: this input used to produce `internal-error` and
+  now produces `change-not-found`. Both are ERRORs, so no exit code moves.
+- **A sibling change directory containing a backslash silently widened the
+  archive gate.** `escapeGlob` escaped every glob metacharacter except
+  glob's *own* escape character, so a name like `a\b` — legal on POSIX — did not
+  merely go unescaped: the backslash escaped the character after it, and
+  `**/changes/a\b/**` matched `ab` and never the directory. That proposal's
+  specs then joined the run of the one check that decides whether a change is
+  done. Covered by ATX-13, which already stated the property.
+- **A self scenario that compiled a TypeScript program had no explicit
+  timeout**, so it fit inside Vitest's 5-second isolated-run default until the
+  toolchain moved and then failed as `tests-red` with no assertion behind it —
+  the failure mode the repo's other long scenarios already carry a timeout to
+  avoid.
+
+### Changed
+
+- **BREAKING: the peer range is now `vite ^8` and `vitest ^4`, down from six
+  majors.** `^5 || ^6 || ^7 || ^8` and `^2 || ^3 || ^4` was a claim about six
+  combinations that no job ever ran end to end. What it looked like from inside
+  the repo — the security entry above says as much — was that the *top* was
+  untested; the fixture told a different story. `fixtures/consumer` pinned
+  `vitest ^2.0.0` / `vite ^5.4.0`, and the consumer job is the **only** thing in
+  this pipeline that resolves peers at all, so the two ends were each proven by
+  one job apiece and `vite ^6`/`^7` and `vitest ^3` were proven by nothing.
+  Advertising a version nobody runs is the same defect the `audit` job was added
+  to close, one layer out: the failure surfaces in an adopter's repository, not
+  here.
+  **Two of them had already stopped being merely untested.** `verify` reads
+  `startVitest` as `Promise<Vitest>` — the dead null guard removed above was
+  there for the older signature — and ATX-36 asserts a listening-handle count
+  against whichever Vite is installed, so on any other major the socket
+  guarantee is a claim rather than a measurement. Neither is a defect that would
+  announce itself; both fail in the direction of looking fine.
+  `fixtures/consumer` moves to `vitest ^4` / `vite ^8` with the range, because
+  npm refuses an unmet peer and the fixture exists to install the way a user
+  does. That does cost something real and it is worth naming: the consumer job
+  no longer exercises a second Vite/Vitest pair, so this trades a spot-check of
+  one old combination for a claim that matches the tested one. A matrix is what
+  buys the breadth back, and nothing here pretends this is that.
+  **Who this breaks:** anyone on Vite 5–7 or Vitest 2–3 fails to install on
+  upgrade, with no deprecation window. Under this file's Versioning rule that is
+  a minor, which is what 0.4.0 is. The engine may well still work on some of
+  them — that is precisely the claim there is no evidence for, and `0.3.x`
+  remains the version whose manifest makes it.
+
+- **Type-aware linting, and `exactOptionalPropertyTypes`.** The three defects
+  above are one shape — an assertion standing in for a check — and the untyped
+  ESLint preset cannot see any of them, because deciding whether an `as` or a
+  `?.` is doing work needs the checker. `recommendedTypeChecked` now runs over
+  `src`, `tests` and `self`, with `no-unnecessary-condition` promoted out of the
+  strict preset; the rest of that preset is deliberately not adopted, since its
+  bulk is `no-non-null-assertion`, and here `!` is the counterpart of
+  `noUncheckedIndexedAccess` — banning it would trade a compiler-enforced
+  guarantee for a lint-enforced style. `fixtures/**` stays on the untyped preset
+  because several fixtures are invalid on purpose. Turning the rules on removed
+  a double cast that hid Vitest's task-tree shape from the compiler, a redundant
+  assertion in the delta reader that made an unvalidated value look checked, and
+  a dead `startVitest` null guard left over from an older Vitest signature.
+  `exactOptionalPropertyTypes` is now on as well: the codebase already followed
+  it by hand — the `...(x === undefined ? {} : { key: x })` idiom appears in
+  every Issue builder — so this makes an existing discipline the compiler's job
+  rather than review's. No `--json` shape changed, so `SCHEMA_VERSION` stays 1.
 
 ## [0.3.0] - 2026-07-27
 
@@ -1126,6 +1438,31 @@ it sat between 0.2.0 and 0.1.7 for two releases, where standing still meant
 sinking one version deeper each time a release was cut above it, and a rejection
 filed under a version reads as belonging to it.
 
+- **A requirement's id prefix must match its registry file's name.** The other
+  half of the rule that shipped as `duplicate-prefix` (see `[0.4.0]`), and
+  the half that does not pay for itself. What killed it is that the corpus
+  already conforms: every fixture registry matches (`auth.reqs.ts` → `AUTH-`,
+  `core.reqs.ts` → `CORE-`), so the rule would detect nothing anywhere it was
+  measured except one file — `self/requirements/attest.reqs.ts`, which holds
+  `ATX-*`. Its first act would therefore be to rename this repo's own registry
+  and every `self/*.spec.ts` that imports it, and its first act in an adopter's
+  repository would be the same thing to theirs. That is rejecting input valid
+  today, a minor bump under this file's Versioning rule, in exchange for making
+  the prefix *guessable from the path* — which matters only to a reader already
+  looking at the file, and who could have read the ids in it. The collision rule
+  delivers what the gap is actually about, which is two owners of one space, and
+  it delivers it without a rename because it fires on a relationship between
+  files rather than on a spelling. Reconsider only with evidence that a reader or
+  a tool needs the prefix before opening the file — a naming *convention* stays
+  the right shape for this, and the convention is what `init` and the docs
+  already teach.
+  What is not a reason to revisit it: the objection that stalled the collision
+  rule while both were queued together — that it guards a convention nothing had
+  yet violated — was answered by shipping it, since a rule that costs no
+  migration and no concept is worth having before the first collision rather
+  than after it. That argument does not transfer here, because this rule's cost
+  is a migration by construction.
+
 - **Two gaps in the intent layer: nothing resists a bloated requirement, and
   nothing resists a duplicated one.** The gaps themselves are described in design
   §11, which is where a permanent property of the design belongs. What is kept
@@ -1272,7 +1609,62 @@ filed under a version reads as belonging to it.
   answer for a Codex user, and this reopens only if Codex grows a project-scoped
   path of its own.
 
-[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.3.0...main
+- **A committed snapshot of the params, to give `check` detection power over a
+  value that moves.** Design §11 records the measurement this answers: editing a
+  param (`'main'` → `'trunk'`, one entry dropped from a nine-element list) leaves
+  `attest check` at `✓ No issues`, because the single source makes a value
+  impossible to *diverge*, which is not the claim that it is flagged when it
+  *moves*. The candidate was the shape `render --check` already proves — a
+  `params.lock` beside the registry, or `check --params-check` — and the
+  mechanism would have worked.
+  *What rejected it: the precedent is the objection.* §9 states when a freshness
+  gate earns its place, and a rendering earns it because it is a function of the
+  *user's registry*, so staleness means the user moved intent without
+  regenerating — a real signal with the fix in their hands. A params snapshot is
+  a function of the registry too, but the population it fires on is different:
+  **every legitimate param edit turns it red, and the fix is a commit containing
+  no decision.** That is precisely the chore §9 declined to ship for `init`, and
+  it is worse here because of frequency — intent is rendered rarely, while params
+  move whenever a value moves, which is the entire reason they are params. The
+  gate would spend its whole life red about correct edits, and a gate that is
+  usually wrong about staleness is the failure mode §9 names as worse than no
+  gate.
+  *What the gap keeps instead.* §6's mechanism 3 already exists to make this
+  exact absence visible: `possible-drift` fires when a requirement owns params
+  that no covering scenario reads, which is the only condition under which a
+  moved param goes unnoticed. The mechanism that guards a param is a scenario
+  reading it, not a file recording it. This reopens only on an adoption report
+  where a param moved, no scenario caught it, and `possible-drift` was **not**
+  already printing — because if it was printing, what failed was reading the
+  report, and a second gate does not fix that.
+
+- **Grouping `render`'s output by prefix, so a reviewer sees contradicting
+  requirements together.** The *detection* half of this is already rejected above
+  (every automatic candidate either saw almost nothing or was a similarity
+  matcher, which is what §0 exists to remove), leaving human review at propose
+  (§7) as the answer — and the idea was to help that review by putting
+  requirements about one subject side by side in the one document a human reads
+  end to end.
+  *What rejected it: the ordering already ships, and the adjacency it buys is not
+  where the gap is.* `compareIds` (`render.ts`) has ordered the document by
+  prefix first and number second since `render` shipped, so same-prefix
+  requirements are **already** adjacent; the candidate was never an ordering
+  change, only a heading over an ordering that already holds. And §11's own
+  example of the gap is `AUTH-3` expiring a session against `SESS-7` saying
+  sessions never expire — a contradiction **across** prefixes, which prefix
+  grouping pushes further apart rather than closer. What remains is a reader aid
+  for same-prefix contradictions, which are the pairs already adjacent and
+  therefore the ones review is least likely to miss, bought at the price of
+  changing the bytes of every committed rendering and turning `render --check`
+  red across every adopting repo on upgrade — for a change the user did not make.
+  *The gap itself stays open* and stays where it belongs, in design §11: nothing
+  resists a duplicated or contradictory requirement, and human review at propose
+  is still the whole answer. What is rejected is grouping as a way to assist it,
+  and this reopens only on a contradiction that grouping would have caught.
+
+[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.4.1...main
+[0.4.1]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.1
+[0.4.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.0
 [0.3.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.3.0
 [0.2.2]: https://gitlab.com/Pseudorca/attest/-/tags/v0.2.2
 [0.2.1]: https://gitlab.com/Pseudorca/attest/-/tags/v0.2.1