@am_shork/attest 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -13,6 +13,71 @@ 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.
 
+## [0.9.2] - 2026-08-17
+
+### Added
+
+- **`@am_shork/attest/inspect`: read what a project declares, without executing
+  it and without acquiring the runner peer.** One function,
+  `inspectProject(root)`, answering the requirements a project declares, the
+  scenarios declared for each, and the issues that stopped a file being read.
+  Nothing about the quality of any of it — that is the ground truth this project
+  refuses to compute for someone else's requirements (design §0).
+
+  *Why it exists rather than what it does.* Everything this repository knows
+  about the quality of its own intent layer is a hand-judged table in
+  `tests/intent-rule-candidates.spec.ts`, and the check that keeps such a table
+  from rotting is that a scenario a row names is one a spec really declares. An
+  adopter could not write that check: the package exported the authoring API and
+  nothing else, so `parseSpecs` and the static registry read were internal and
+  **the scenario names of their own project were unreachable** — not
+  undocumented, unreachable. This is the enabling half of the judgement-table
+  proposal under *Under consideration*, and deliberately only that half: it
+  ships no schema and decides nothing, and it is the only thing that can produce
+  the second table that proposal is waiting for.
+
+  *One function, not the four internals it composes,* because `loadRegistry`
+  takes a reader and which of the two runs is a security property fixed by the
+  command, never chosen by a caller (design §5.1). The static reader is welded
+  in and no parameter can change it.
+
+  *And its import closure names neither runner peer,* so a consumer that only
+  analyses acquires neither `vite` nor `vitest` — the same argument `./define`
+  was added on (design §10). Measured on the built entry: ten modules, and the
+  only bare specifiers in the closure are `typescript`, `zod` and two node
+  builtins. That claim is gated over the **built** package rather than the
+  source, because `locate.ts` names `loader.ts` in a type-only import that the
+  emit erases: the two graphs differ by exactly that edge, and it is the edge
+  the promise is about. `tests/import-boundary.spec.ts` holds the source side,
+  where a type-only mention still counts as *naming* the runner, and its
+  reachability walk now follows runtime edges only for the same reason.
+
+  Additive: no command, flag, exit code or `--json` field changes, and nothing
+  that used to pass now fails.
+
+- **"Judging your own intent layer" (`docs/{en,zh}/intent-quality.md`): the four
+  things no gate is looking at, and a method for building your own
+  counter-pressure out of them.** For an existing adopter, on the back of the
+  export above.
+
+  *A method with no template, and the omission is the point.* The page states
+  the four **findings** — coverage is binary so lumping is free, a quantifier is
+  unread, an iterated `params` list is a run's domain, an assertion can echo
+  rather than pin — and the two **mechanical properties** that make a
+  hand-judged record a counter-pressure rather than a note: completeness
+  (something enumerable must force a row) and rot-binding (a scenario a row
+  names must be asserted to exist). Both generalise without assuming a single
+  column. What it withholds is this repository's own answer — the four tables
+  in `tests/intent-rule-candidates.spec.ts` — and it asks a reader to reach that
+  file only after doing the hand pass, saying why rather than hiding it: there
+  is one such table in existence and its author wrote both the schema and every
+  answer in it, so a second one built from someone else's corpus is evidence
+  while one built from ours is an echo. That is the fourth finding turned on the
+  question itself.
+  The worked example is deliberately **one column**, so the shape that comes
+  back is not a copy of the shape that went out, and the report the page asks
+  for names the thing worth most: *the column you needed that we do not have.*
+
 ## [0.9.1] - 2026-08-13
 
 ### Changed
@@ -5082,7 +5147,21 @@ have to gather again.
   far past the two registry readers' current surface. **(3)** No mechanism is yet
   known that separates "the assertion pins this independently" from "the assertion
   echoes it" without executing the scenario twice under different values — which
-  is mutation testing, a much larger thing to own.
+  is mutation testing, a much larger thing to own. *One has since been built and
+  scored, and it does not lift this blocker.* The syntactic candidate — flag a
+  scenario whose expectation is derived from the param the code under test
+  consumed, decided inside one body without executing anything — flags 9 params
+  here, of which **4 are real echoes and 5 are pinned by something outside the
+  body it cannot see**. Under half precision, and the failure is the one
+  predicted above rather than a tuning problem: what pins a value is often a
+  fixture or a second derivation in another file, so a single-body detector is
+  looking in the wrong place by construction. The newest false positive is the
+  clearest instance — `ATX-79.subpath` is compared against `package.json`, which
+  is not the code under test and does not read the registry, so the independent
+  term is in another file entirely. Precision has fallen on every addition
+  measured so far, which is the direction that matters. The score is quoted from the
+  suite's snapshot and re-read with the judgement-table entry above, which is
+  where the same measurement is used for a different decision.
   **The guidance half has shipped; this entry is now only about the detector.**
   "Read the param inside the assertion" was insufficient and half-wrong as
   written, and `[0.5.0]` replaces it everywhere it appeared — README, the
@@ -5378,6 +5457,98 @@ have to gather again.
   and the second report of the same shape, which this measurement does not
   supply and does not replace.
 
+- **An outward-facing form of the judgement tables, so an adopter can run this
+  counter-pressure on their own registry.**
+  `tests/intent-rule-candidates.spec.ts` maintains four hand-judged tables over
+  this repo's registry and enforces their completeness. Design §11 records the
+  properties they defend and that nothing enforces any of them; what the tables
+  add is a counter-pressure holding for **one** registry whose authors agreed to
+  maintain it. An adopter got none of it, and the reason was sharper
+  than "nobody wrote it for them": the package exported `requirement`,
+  `scenario`, `defineRequirements`, `delta` and types, and nothing else.
+  `parseSpecs`, `findFiles` and `readRegistrySource` were internal, so an
+  adopter **could not enumerate their own scenario names** — the table's central
+  rot check, that a claimed scenario is one a spec really declares, was not
+  merely unwritten downstream but unreachable. **That half shipped under
+  `[0.9.2]` as `@am_shork/attest/inspect`** and is recorded at the foot of
+  this entry; what stays here is the schema built on top of it, and the three
+  blockers below are untouched by the export.
+  *The shape that makes it shippable at all is a split, not a feature.* The
+  engine can compute which ids exist, which statements match the universal
+  quantifier regex, which params are list-valued, and whether a named scenario
+  is declared — all four already, all statically. It cannot compute how many
+  obligations a requirement carries, what a quantifier ranges over, or whether a
+  scenario iterates a param. So the shippable object is **the enforcement, never
+  the judgement**: an opt-in `*.judge.ts` read by the same static reader and
+  under the same literal-only rule the registry is (it is metadata about
+  requirements under review, so `check` must execute nothing to read it), whose
+  contents are entirely the adopter's. Opting in is creating the file; once it
+  exists, `requirement-unjudged`, `orphan-judgement`, `unbound-site` and
+  `quantifier-unjudged` make it complete and keep it from rotting. The
+  asymmetry is the only way this can exist without Attest asserting a ground
+  truth it refuses to compute (§0), and it is the same asymmetry `never-red`
+  already runs on: the archive gate would owe judgement only for ids a change
+  ADDs, so a brownfield adoption is not blocked wholesale.
+  *One part of the existing table cannot ship in any form.* `DOMAINS.pin` comes
+  in two kinds — a scenario name, checkable against the AST, and a **source-text
+  fragment** grepped out of the spec file. The second is asserting on the
+  wording of somebody's test, which is the `Issue.message` category error under
+  another name. Only the scenario-name kind is exportable, and what that costs
+  is real: the grep is what caught a deleted pin that `toContain` had passed.
+  *Why no detector ships with it, and this is the part that is already
+  measured.* Three rule families were built and scored against the whole corpus
+  (86 entries, counting a fixture id once per registry file) before any was
+  written into the engine, which is the order `divergent-param` was originally
+  designed in the wrong way round. Every figure below is a quotation of the
+  suite's inline snapshots; the snapshot is the fresh copy, and this paragraph
+  is only ever as fresh as its last edit.
+  **(1) `compound-requirement`** — 34 requirements carry more than one
+  obligation, it flags 16, is **wrong about none**, and misses 18. Never wrong
+  and nearly blind, and the 18 are the form the coverage incentive actually
+  rewards: extra clauses under a single keyword. **(2) The widened variant** —
+  29 correct, but 14 wrong and still 5 missed, and it is silenced by deleting an
+  "and". A rule whose cheapest fix degrades the artifact it protects does not
+  ship, and its precision falls as the registry grows. **(3) `divergent-param`**
+  — 5 divergences on this repo, **all 5 judged wrong**, zero true positives ever
+  recorded. The `code` group now spans 19 ids, and the failure is structural
+  rather than a matter of naming: the key is built by discarding the evidence of
+  relatedness, so the one genuinely paired divergence in the group is the one it
+  cannot show, and the key has churned three times under `flag` on additions
+  that changed no verdict. A fourth candidate — the echo detector, scored at
+  half precision — belongs to the tautology entry above and is not re-quoted
+  here, because a figure stated in two places goes stale in one. Taken together
+  these are the measured range of what a token or single-body detector over
+  prose can do here, and they are why the proposal is enforcement-only.
+  *What blocks the decision — three things.* **(1) One adapter.** This
+  repository's table is the only one that exists, and its author wrote both the
+  schema and every answer in it. By this project's own rule a second table is
+  what makes the seam real, and freezing a `Judgement` type now is deciding for
+  everyone from 34 requirements written by one person. **(2) The breaking form
+  of this was already rejected** — see *Countable obligations* below — and one
+  of its three reasons survives the separate-file shape intact: **nothing can
+  force the count to be true.** The other two do not survive, which is what is
+  new here: a separate artifact touches no `--json` field, no delta apply and no
+  `render` output, and completeness *across ids* is computable in a way
+  completeness *within* an obligation array never was. So this is a re-proposal
+  with one of three objections answered and the sharpest one standing.
+  **(3) `quantifier-unjudged` reuses a rejected detector as its trigger.**
+  Firing on the quantifier token was rejected below at 43% reach and 70% wrong;
+  the claim here is that the same regex is acceptable when it asks a question an
+  author discharges in one line (`over: 'values'`) rather than issuing a
+  verdict. That claim is untested on anyone who did not also write the regex.
+  *The half that is not blocked has shipped, under `[0.9.2]`.*
+  `@am_shork/attest/inspect` is one function answering what a project declares —
+  AST-only, no runner peer, landing on the existing static/executing boundary.
+  It ships no schema and decides nothing, which is why it could go ahead of the
+  three blockers rather than waiting on them. What it changes about this entry
+  is the *kind* of thing that is now missing: the mechanism is no longer
+  unreachable, only unwritten, so a second table is something an adopter can
+  build rather than something only this repository could.
+  *What would decide it:* one judgement table maintained by someone who did not
+  design it. If it comes back the same shape, the seam is real and the schema
+  follows; if it comes back different, `inspect` was the whole answer and the
+  schema never needs to exist.
+
 ## Considered and rejected
 
 Decisions **not** to build something, kept where they can be found before the
@@ -5864,24 +6035,27 @@ quotation of that snapshot and is only ever as fresh as the last edit here —
 read the snapshot when the number is what matters. *`compound-requirement`
 (WARNING) — rejected.* More than one RFC-2119 keyword in one `statement` is
 objectively more than one obligation. Measured (figures re-read from the suite,
-which is the only place they are not prose): of the 8 requirements in the corpus
-carrying more than one, it flags 3 (`ATX-10`, `ATX-21`, `ATX-26`) and misses
-`ATX-5`, `ATX-9`, `ATX-13`, `ATX-14`, `ATX-17` — every one that packs clauses
-under a single keyword, which is the form the coverage incentive actually
-rewards. A wider variant (keyword plus a coordinating `and`/`while`/`;`) reaches
-7 of 8, at 3 wrong hits (`ATX-6`, `ATX-22`, `ATX-23`) rather than the 1 recorded
-when it was first scored — so reach is not the deciding argument, and the
-precision it trades away grows with the registry. This is: both variants are
+which is the only place they are not prose): of the 34 requirements in the
+corpus carrying more than one, it flags 16 and misses 18 — every one of those 18
+packs clauses under a single keyword, which is the form the coverage incentive
+actually rewards. A wider variant (keyword plus a coordinating `and`/`while`/`;`)
+reaches 29 of 34, at 14 wrong hits rather than the 3 quoted here when the corpus
+was half this size and the 1 recorded when it was first scored — so reach is not
+the deciding argument, and the precision it trades away grows with the registry,
+which three successive re-readings of this paragraph have now measured rather
+than predicted. This is: both variants are
 silenced by deleting the word that triggered them, and neither can tell that
 deletion from a real split. `SHALL do A and MUST do B` clears the warning as
 `SHALL do A and do B` — same two obligations, one fewer normative keyword. A
 rule whose cheapest fix degrades the artifact it protects does not ship.
 *`divergent-param` (WARNING) — rejected.* One param name declared with different
-values in two requirements sharing an id prefix. Measured: it fires twice on
-this repo and both firings are wrong — `idleTimeoutMin` (`15` in `ATX-3`, `30`
-in `ATX-10`), unrelated illustrative fixtures, and `code` (`registry-not-static`
-in `ATX-17`, `empty-spec` in `ATX-18`, `rationale-placeholder` in `ATX-21`),
-diagnostics that could not possibly agree. The second arrived on its own when
+values in two requirements sharing an id prefix. Measured: it fires 5 times on
+this repo and **every firing is judged wrong** — `idleTimeoutMin` (`15` in
+`ATX-3`, `30` in `ATX-10`), unrelated illustrative fixtures, and `code`
+(`registry-not-static` in `ATX-17`, `empty-spec` in `ATX-18`,
+`rationale-placeholder` in `ATX-21`), diagnostics that could not possibly agree.
+That second group has since grown to span **19 ids**, and two more param names
+have joined it on the same structure (`flag`, `payloadKinds`). The second arrived on its own when
 `ATX-18` was added and grew a third member on its own again when `ATX-21` was,
 then `ATX-25`, then `ATX-26`, which is the more damning half: a generic param
 name collides more often as a registry grows, so the false-positive rate rises
@@ -5898,8 +6072,19 @@ firing. Until it appeared, every false positive had been on the single name
 workaround and therefore left the rule arguably salvageable. It is not the word:
 two requirements owning unrelated constants of the same *kind* is the structure,
 and any registry large enough to be worth linting has it. Still zero true
-positives, now across a 34-entry corpus (the `corpus` figure in the suite's
+positives, now across an 86-entry corpus (the `corpus` figure in the suite's
 snapshot, which counts a fixture id once per registry file that declares it).
+**Two failure modes have been measured since, and both are about the key rather
+than the threshold.** The grouping keeps one id per distinct value, so two
+requirements naming the *same* constant — the case a reader would most want
+compared — are the pair the key deduplicates away; that has now happened twice,
+most sharply on `ATX-18`/`ATX-77`, a pair split deliberately because each is
+falsifiable in a direction the other is blind to. And the key's *identity*
+moves when a requirement agreeing with an existing member is added, so a finding
+has to be re-judged by hand while nothing about it changed — three re-keyings
+across three releases under `flag` alone, none of which moved a verdict. A rule
+whose output churns on additions that agree with it is one whose maintenance
+cost is a function of registry growth, on top of the zero precision above.
 The escape hatch it was blocked on has since been designed and does not rescue
 it: with no config file the only workable shape is an additive
 `independentParams?: string[]` on the requirement (a CLI flag is per-invocation

package/README.md

@@ -167,7 +167,7 @@ Every diagnostic carries a `code`, and every code has a section in
 ```
 ERROR   registry-not-static (requirements/upload.reqs.ts:5)
     Value is not a literal.
-    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.1/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.2/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section
@@ -180,6 +180,7 @@ isn't. In `--json` the same link is on each issue as `docsUrl`.
 | **CLI reference** — every command, flag and JSON field | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/cli-reference.md) |
 | **Troubleshooting** — one section per issue code | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/troubleshooting.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/troubleshooting.md) |
 | **Design** — the authoritative design of the framework | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/attest-design.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/attest-design.md) |
+| **Judging your own intent layer** — what no gate checks, and a method for it | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/intent-quality.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/intent-quality.md) |
 | **Feedback template** — report how adoption actually went | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/feedback.template.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/feedback.template.md) |
 
 The change workflow is not here: it is what `attest init` writes into your

package/dist/inspect.d.ts

@@ -0,0 +1,54 @@
+import type { Issue, ParsedScenario, Registry } from './core/types.js';
+export type { Issue, ParsedScenario, Registry, Requirement } from './core/types.js';
+/** What a project declares, read without executing any of it. */
+export interface Inspection {
+    /**
+     * Every requirement declared under the root, merged across registry files.
+     *
+     * A registry file that could not be read statically contributes nothing here
+     * and one entry to {@link Inspection.issues} — so an empty result never means
+     * "this project has no requirements" without the issues saying why.
+     */
+    readonly registry: Registry;
+    /**
+     * The scenarios each requirement id has, in declaration order.
+     *
+     * A `Map` rather than a record, and not only for the key type: a record keyed
+     * by ids from a file on disk is the `Object.prototype` hazard ATX-42 exists
+     * for, and a `Map` has no prototype chain to read a requirement out of. The
+     * cost is that `JSON.stringify` renders it as `{}` — a caller serialising
+     * this owes `Object.fromEntries`, and the type is a `Map` so that the
+     * conversion is a decision rather than a surprise.
+     *
+     * An id with no scenarios is absent rather than present-and-empty — the same
+     * distinction `cover` reports, and the one a coverage check is asking about.
+     */
+    readonly scenarios: ReadonlyMap<string, readonly ParsedScenario[]>;
+    /**
+     * Everything that stopped a *file* being read, in the shape every command
+     * reports: one unreadable file scraps itself and nothing else (ATX-65), which
+     * is what lets a caller report on the rest of the project.
+     *
+     * Not a promise that nothing throws. A root that cannot be walked at all is a
+     * caller's mistake rather than a finding about a project, and rejects.
+     */
+    readonly issues: readonly Issue[];
+}
+/**
+ * Read the requirements and scenarios declared under `root`, executing nothing.
+ *
+ * `root` is the project directory, resolved here so a relative one behaves the
+ * same as an absolute one rather than half-working: the walk would find the
+ * files either way, and only the relative paths in the result would be wrong,
+ * which is the shape of bug that survives a demo.
+ *
+ * Every `file` in the result is relative to that root and POSIX-spelled on
+ * every platform (`paths.ts`) — the spelling a caller can compare against and
+ * store, on a value that would otherwise carry the host's separator.
+ *
+ * The registry read and the spec parse are independent, so they run
+ * concurrently — each already bounds its own fan-out over a tree whose size is
+ * not ours to choose.
+ */
+export declare function inspectProject(root: string): Promise<Inspection>;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/inspect.js

@@ -0,0 +1,68 @@
+// The static reading layer, as a second public entry point (design §10).
+//
+// Why it exists: everything this repository knows about the quality of its own
+// requirements is a hand-judged table in `tests/intent-rule-candidates.spec.ts`,
+// and the check that keeps such a table from rotting is "the scenario this row
+// names is one a spec really declares". An adopter could not write that check.
+// The package exported the authoring API and nothing else, so the ids, the
+// statements and above all the *scenario names* of their own project were
+// unreachable from outside — not merely undocumented, unreachable. That is what
+// this entry point answers, and the deliberate limit is that it answers only
+// that: it reports what a project declares, and judges none of it (design §0).
+//
+// **One function rather than the four internals it composes**, and the reason is
+// a security property rather than convenience. `loadRegistry` takes a
+// `RegistryReader`, and which reader runs is fixed by the command — never chosen
+// by a caller, never a fallback — because one of the two executes the project's
+// code and the other does not (design §5.1). Exporting the readers would hand
+// that choice to an adopter, which is the one thing the two-adapter seam must
+// never allow. What is exported therefore has the static reader welded in, and
+// there is no parameter that could change it.
+//
+// The same rule decides the import graph: nothing here may reach `vite` or
+// `vitest`, so a consumer that only analyses does not acquire the runner peer.
+// `tests/import-boundary.spec.ts` gates that rather than leaving it to review —
+// this module is on the short list of entry points whose closure is walked.
+import { resolve } from 'node:path';
+import { loadRegistry, parseSpecs, scanProject, staticReader } from './core/locate.js';
+/**
+ * Read the requirements and scenarios declared under `root`, executing nothing.
+ *
+ * `root` is the project directory, resolved here so a relative one behaves the
+ * same as an absolute one rather than half-working: the walk would find the
+ * files either way, and only the relative paths in the result would be wrong,
+ * which is the shape of bug that survives a demo.
+ *
+ * Every `file` in the result is relative to that root and POSIX-spelled on
+ * every platform (`paths.ts`) — the spelling a caller can compare against and
+ * store, on a value that would otherwise carry the host's separator.
+ *
+ * The registry read and the spec parse are independent, so they run
+ * concurrently — each already bounds its own fan-out over a tree whose size is
+ * not ours to choose.
+ */
+export async function inspectProject(root) {
+    const projectRoot = resolve(root);
+    const { reqsFiles, specFiles } = await scanProject(projectRoot);
+    const [loaded, parsed] = await Promise.all([
+        loadRegistry(projectRoot, staticReader(), reqsFiles),
+        parseSpecs(specFiles, projectRoot),
+    ]);
+    const scenarios = new Map();
+    for (const scenario of parsed.plan.scenarios) {
+        const existing = scenarios.get(scenario.reqId);
+        if (existing === undefined)
+            scenarios.set(scenario.reqId, [scenario]);
+        else
+            existing.push(scenario);
+    }
+    return {
+        registry: loaded.registry,
+        scenarios,
+        // Registry issues before spec issues, and each already in sorted file
+        // order: the list is a function of the project rather than of which read
+        // finished first, so two runs over one tree answer identically.
+        issues: [...loaded.issues, ...parsed.issues],
+    };
+}
+//# sourceMappingURL=inspect.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
   "type": "module",
   "engines": {
@@ -26,6 +26,10 @@
       "types": "./dist/core/registry.d.ts",
       "default": "./dist/core/registry.js"
     },
+    "./inspect": {
+      "types": "./dist/inspect.d.ts",
+      "default": "./dist/inspect.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [