@am_shork/attest 0.5.0 → 0.7.0

package/dist/core/static-registry.d.ts

@@ -39,4 +39,34 @@ export type DeltaReadResult = {
  * (write the value inline, or `--eval`) is the same sentence either way.
  */
 export declare function readDeltaSource(file: string, source: string): DeltaReadResult;
+/**
+ * Where a new entry may be written into a registry file's literal, as an offset
+ * into its source (design §7).
+ *
+ * The insertion point rather than a rewritten file, because `--apply` must not
+ * regenerate a `*.reqs.ts`. Every registry this tool merges into is hand-written
+ * and hand-commented, and rendering one back out of a `Registry` object would
+ * silently drop every comment and every choice of layout in it — the
+ * "destructive on a file the user cannot regenerate" shape the `AGENTS.md`
+ * proposal was rejected for. An offset lets the splice be a pure insertion: every
+ * other byte of the file is the byte that was there before, which is a property
+ * that can be stated and tested rather than hoped for.
+ *
+ * Lives here because this is the module that already knows how to find the
+ * literal, and the one place `typescript` is imported for that job. A second
+ * walker would be a second answer to "where does this registry's body end".
+ *
+ * `undefined` when the file is not a registry this tool can read — the same
+ * condition `readRegistrySource` reports as `registry-not-static` or
+ * `registry-no-default`, and the caller has already run that check.
+ */
+export interface RegistryInsertion {
+    /** Offset to insert at. Everything before and after it is preserved. */
+    offset: number;
+    /** The indentation the file's existing entries use, reproduced for new ones. */
+    indent: string;
+    /** Whether the insertion has to open with a `,` — false only for an empty registry. */
+    leadingComma: boolean;
+}
+export declare function registryInsertionPoint(file: string, source: string): RegistryInsertion | undefined;
 //# sourceMappingURL=static-registry.d.ts.map

package/dist/core/static-registry.js

@@ -322,4 +322,40 @@ function numericValue(node) {
         throw new NotStatic(node, 'a number this reader cannot spell out');
     return value;
 }
+export function registryInsertionPoint(file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    const exported = defaultExportExpression(sf);
+    if (!exported)
+        return undefined;
+    const arg = authoringCall(exported, sf, 'defineRequirements');
+    if (!arg || !ts.isObjectLiteralExpression(arg))
+        return undefined;
+    const last = arg.properties[arg.properties.length - 1];
+    if (!last) {
+        // An empty registry: open the body rather than continue it. The trailing
+        // newline is written by the caller, so `{` does not end up sharing a line
+        // with the entry and the closing `}`.
+        return { offset: arg.getStart(sf) + 1, indent: indentOf(sf, source, arg) + '  ', leadingComma: false };
+    }
+    // Deliberately the *end of the last property*, not the end of the literal:
+    // inserting here sits before any trailing comma the file already has, so one
+    // leading comma is correct whether or not that comma is present, and the
+    // file's own trailing-comma style is left exactly as it was.
+    return { offset: last.getEnd(), indent: indentOf(sf, source, last), leadingComma: true };
+}
+/**
+ * The whitespace a node's line opens with.
+ *
+ * Read out of the source rather than computed from the column, so a file
+ * indented with tabs is continued with tabs. Anything else on the line (a
+ * property sharing a line with another) falls back to two spaces, which is the
+ * only case where this guesses.
+ */
+function indentOf(sf, source, node) {
+    const start = node.getStart(sf);
+    const { line } = sf.getLineAndCharacterOfPosition(start);
+    const lineStart = sf.getPositionOfLineAndCharacter(line, 0);
+    const prefix = source.slice(lineStart, start);
+    return /^[\t ]*$/.test(prefix) ? prefix : '  ';
+}
 //# sourceMappingURL=static-registry.js.map

package/dist/core/status.js

@@ -29,10 +29,28 @@ import { hasRecordedRed, recordedOutcome } from './red-record.js';
  * author reads them in.
  */
 export function statusRows(addedIds, plan, firstRun) {
+    // Index the scenarios once, the way `validator.ts`'s `detectPotentialDrift`
+    // does and for the reason recorded there: filtering the whole plan per
+    // requirement is O(requirements x scenarios). The plan here is the *merged*
+    // one, so the inner term is the whole repository's scenario count while the
+    // outer is only what this change adds.
+    //
+    // The cost is invisible today — 20 added ids against 2000 scenarios is 40k
+    // comparisons, well under a millisecond — so this is filed as the
+    // inconsistency it is rather than as a slow path. Two functions over one
+    // shape held two beliefs about whether it is worth indexing; they hold one
+    // now. Insertion order is plan order, which is file then line, so the
+    // scenarios a row carries are still in the order their author reads them.
+    const byReqId = new Map();
+    for (const s of plan.scenarios) {
+        const group = byReqId.get(s.reqId);
+        if (group)
+            group.push(s);
+        else
+            byReqId.set(s.reqId, [s]);
+    }
     return [...addedIds].sort(byCodeUnit).map((reqId) => {
-        const scenarios = plan.scenarios
-            .filter((s) => s.reqId === reqId)
-            .map((s) => ({
+        const scenarios = (byReqId.get(reqId) ?? []).map((s) => ({
             name: s.name,
             file: s.file,
             line: s.line,

package/dist/core/terminal.d.ts

@@ -19,6 +19,29 @@ export declare function inline(text: string): string;
  * A space rather than deletion: removing the byte would silently splice
  * `atte` + `st` into a word that was never in the file, and a diagnostic that
  * quietly rewrites what it quotes is its own kind of wrong.
+ *
+ * The class is written out rather than computed per character. The previous
+ * spelling spread the string into a per-code-point array, mapped and rejoined —
+ * three allocations proportional to the input, where the engine's own scan needs
+ * none when nothing matches, which is the case every real registry is. Measured
+ * over 120,000 characters: **27x** faster on plain ASCII, **54x** with
+ * newlines, **84x** on CJK. A payload that is *entirely* control bytes is a
+ * wash (0.9x), because then there is nothing to fast-path and both spellings
+ * build a new string; both are linear either way, so this is a constant factor
+ * rather than a second ATX-59.
+ *
+ * It is worth the change because the count scales with the registry while the
+ * length scales with whatever the registry chose: `render`'s `sanitised` calls
+ * this once per statement, rationale, param key, param value and out-of-scope
+ * entry, on the same reachable `render --check` path ATX-59 came off.
+ *
+ * **Byte-identical to the spelling it replaces**, which is the only thing that
+ * mattered: checked exhaustively over every code unit in the BMP, and over
+ * 200,000 randomised strings mixing control bytes, CJK, astral characters and
+ * lone surrogates. Surrogates are the case the spread existed to get right —
+ * `D800`–`DFFF` fall outside every range below, so neither spelling touches a
+ * pair or splits one — and newlines survive here as they always did, by not
+ * being in the class.
  */
 export declare function control(text: string): string;
 //# sourceMappingURL=terminal.d.ts.map

package/dist/core/terminal.js

@@ -19,8 +19,6 @@
 // loader has to sanitise Vite's log output for the same reason and cannot
 // import from a layer above it. Two copies of this decision is how the crash
 // path came to be missed once already.
-/** The one control character that survives: see `block`. */
-const NEWLINE = 0x0a;
 /** How far a message is indented under its header line. */
 export const INDENT = '    ';
 /**
@@ -46,14 +44,32 @@ export function inline(text) {
  * A space rather than deletion: removing the byte would silently splice
  * `atte` + `st` into a word that was never in the file, and a diagnostic that
  * quietly rewrites what it quotes is its own kind of wrong.
+ *
+ * The class is written out rather than computed per character. The previous
+ * spelling spread the string into a per-code-point array, mapped and rejoined —
+ * three allocations proportional to the input, where the engine's own scan needs
+ * none when nothing matches, which is the case every real registry is. Measured
+ * over 120,000 characters: **27x** faster on plain ASCII, **54x** with
+ * newlines, **84x** on CJK. A payload that is *entirely* control bytes is a
+ * wash (0.9x), because then there is nothing to fast-path and both spellings
+ * build a new string; both are linear either way, so this is a constant factor
+ * rather than a second ATX-59.
+ *
+ * It is worth the change because the count scales with the registry while the
+ * length scales with whatever the registry chose: `render`'s `sanitised` calls
+ * this once per statement, rationale, param key, param value and out-of-scope
+ * entry, on the same reachable `render --check` path ATX-59 came off.
+ *
+ * **Byte-identical to the spelling it replaces**, which is the only thing that
+ * mattered: checked exhaustively over every code unit in the BMP, and over
+ * 200,000 randomised strings mixing control bytes, CJK, astral characters and
+ * lone surrogates. Surrogates are the case the spread existed to get right —
+ * `D800`–`DFFF` fall outside every range below, so neither spelling touches a
+ * pair or splits one — and newlines survive here as they always did, by not
+ * being in the class.
  */
 export function control(text) {
-    return [...text]
-        .map((ch) => {
-        const c = ch.codePointAt(0);
-        const isControl = (c < 0x20 && c !== NEWLINE) || (c >= 0x7f && c <= 0x9f);
-        return isControl ? ' ' : ch;
-    })
-        .join('');
+    // eslint-disable-next-line no-control-regex -- matching control characters is the whole function.
+    return text.replace(/[\x00-\x09\x0b-\x1f\x7f-\x9f]/g, ' ');
 }
 //# sourceMappingURL=terminal.js.map

package/dist/core/validator.d.ts

@@ -18,8 +18,12 @@ export declare function uncoveredIssues(registry: Registry, plan: AttestPlan): I
  *
  * and one WARNING:
  * - rationale-placeholder: a `{name}` in a rationale, which is never interpolated
+ *
+ * `registryIncomplete` says that at least one `*.reqs.ts` failed to load, so
+ * `registry` is known to be missing whatever was in it. It changes no verdict —
+ * only what `orphan-test` advises, for the reason below.
  */
-export declare function validateStructure(registry: Registry, plan: AttestPlan): Issue[];
+export declare function validateStructure(registry: Registry, plan: AttestPlan, registryIncomplete?: boolean): Issue[];
 /**
  * Weak anti-drift heuristic (design §6, mechanism 3). Evaluated per requirement,
  * not per scenario: a requirement that owns params is quiet as soon as *any* one

package/dist/core/validator.js

@@ -33,11 +33,32 @@ export function uncoveredIssues(registry, plan) {
  *
  * and one WARNING:
  * - rationale-placeholder: a `{name}` in a rationale, which is never interpolated
+ *
+ * `registryIncomplete` says that at least one `*.reqs.ts` failed to load, so
+ * `registry` is known to be missing whatever was in it. It changes no verdict —
+ * only what `orphan-test` advises, for the reason below.
  */
-export function validateStructure(registry, plan) {
+export function validateStructure(registry, plan, registryIncomplete = false) {
     const issues = [];
     const knownIds = new Set(Object.keys(registry));
     // orphan-test: covers a requirement that does not exist.
+    //
+    // "Add it to the registry, or fix the id" is the right advice for an id that
+    // is genuinely absent, and **wrong** for one already sitting in a registry
+    // file that failed to load: the id is there, the fix is the load error, and
+    // following the hint would add a duplicate. That case is not rare when it
+    // happens — one unreadable `*.reqs.ts` orphans every scenario of every
+    // requirement it declared, so the wrong advice is also the loudest thing in
+    // the report.
+    //
+    // Which of the two this is cannot be decided here: the ids of a file that
+    // never parsed are exactly what is unavailable. So the finding stands and the
+    // *advice* names the uncertainty and the order to work in — a report that is
+    // quieter about problems it can still see would be the worse trade for a
+    // command whose contract is breadth.
+    const orphanFix = (id) => registryIncomplete
+        ? `A registry file failed to load, so ids it declares are missing here — fix that first, and add "${id}" only if it is still unknown afterwards.`
+        : `Add it to the registry, or fix the id.`;
     for (const s of plan.scenarios) {
         if (!knownIds.has(s.reqId)) {
             issues.push({
@@ -46,7 +67,7 @@ export function validateStructure(registry, plan) {
                 reqId: s.reqId,
                 file: s.file,
                 line: s.line,
-                message: `scenario "${s.name}" attests unknown requirement "${s.reqId}". Add it to the registry, or fix the id.`,
+                message: `scenario "${s.name}" attests unknown requirement "${s.reqId}". ${orphanFix(s.reqId)}`,
             });
         }
     }

package/dist/runtime.d.ts

@@ -1,12 +1,32 @@
 /**
  * Group scenarios that verify one requirement. The describe block is named
  * `[id]` so runtime coverage can be reconstructed from the task tree (§5.4).
+ *
+ * The body is handed to `describe` untouched. It used to be wrapped in a
+ * set-and-restore of a module-level `currentReqId` that `scenario()` read; that
+ * variable is deleted rather than repaired — see `scenario`.
  */
 export declare function requirement(id: string, body: () => void): void;
 /**
  * Declare a single verifiable scenario. Must be nested inside requirement().
  * The assertion itself is delegated to Vitest `it` (design §3).
  *
+ * **The nesting check happens when the scenario runs, not when it is
+ * collected**, and that is what makes grouping work. Vitest defers a nested
+ * `describe`'s callback until after the parent's has returned — measured: at
+ * the end of the outer callback the inner one has not run — so a module-level
+ * `currentReqId` set and restored around `body()` was already back to `null` by
+ * the time a grouped `scenario()` ran. It threw, and a throw during collection
+ * is a *file* error: nothing in that file was collected, so every scenario in
+ * it came back `declared-not-run` — including correct ungrouped ones under
+ * other requirements — each blamed on "skipped, or excluded by an .only?".
+ * Meanwhile `check` and `cover` read the same file statically and reported full
+ * coverage, so the static half called a file green that could not execute at
+ * all.
+ *
+ * Checking here costs nothing and fails better: a scenario genuinely outside
+ * any `requirement()` now fails as one test instead of taking its file down.
+ *
  * `timeoutMs` is passed straight through to `it`. It exists because `verify`
  * runs the suite **isolated** (§5.4) — no `vitest.config.ts` unless
  * `--vitest-config` names one — so Vitest's 5-second default is what every

package/dist/runtime.js

@@ -2,27 +2,53 @@
 // Pure delegation to Vitest; no in-process coverage singleton — coverage is
 // reconstructed from the Vitest task tree instead (design §5.4).
 import { describe, it } from 'vitest';
-let currentReqId = null;
+import { requirementIdOf, requirementSuiteName } from './core/req-suite.js';
 /**
  * Group scenarios that verify one requirement. The describe block is named
  * `[id]` so runtime coverage can be reconstructed from the task tree (§5.4).
+ *
+ * The body is handed to `describe` untouched. It used to be wrapped in a
+ * set-and-restore of a module-level `currentReqId` that `scenario()` read; that
+ * variable is deleted rather than repaired — see `scenario`.
  */
 export function requirement(id, body) {
-    describe(`[${id}]`, () => {
-        const prev = currentReqId;
-        currentReqId = id;
-        try {
-            body();
-        }
-        finally {
-            currentReqId = prev;
-        }
-    });
+    describe(requirementSuiteName(id), body);
+}
+/**
+ * The requirement a scenario actually ended up inside, read from the task tree.
+ *
+ * The same source `runner.ts` attributes coverage from, which is the point: a
+ * module-level "current requirement" was a *second* answer to a question the
+ * suite name already answers, and the two disagreed exactly where it mattered.
+ */
+function owningRequirement(task) {
+    for (let s = task?.suite; s; s = s.suite) {
+        const id = requirementIdOf(s.name ?? '');
+        if (id !== undefined)
+            return id;
+    }
+    return undefined;
 }
 /**
  * Declare a single verifiable scenario. Must be nested inside requirement().
  * The assertion itself is delegated to Vitest `it` (design §3).
  *
+ * **The nesting check happens when the scenario runs, not when it is
+ * collected**, and that is what makes grouping work. Vitest defers a nested
+ * `describe`'s callback until after the parent's has returned — measured: at
+ * the end of the outer callback the inner one has not run — so a module-level
+ * `currentReqId` set and restored around `body()` was already back to `null` by
+ * the time a grouped `scenario()` ran. It threw, and a throw during collection
+ * is a *file* error: nothing in that file was collected, so every scenario in
+ * it came back `declared-not-run` — including correct ungrouped ones under
+ * other requirements — each blamed on "skipped, or excluded by an .only?".
+ * Meanwhile `check` and `cover` read the same file statically and reported full
+ * coverage, so the static half called a file green that could not execute at
+ * all.
+ *
+ * Checking here costs nothing and fails better: a scenario genuinely outside
+ * any `requirement()` now fails as one test instead of taking its file down.
+ *
  * `timeoutMs` is passed straight through to `it`. It exists because `verify`
  * runs the suite **isolated** (§5.4) — no `vitest.config.ts` unless
  * `--vitest-config` names one — so Vitest's 5-second default is what every
@@ -32,9 +58,11 @@ export function requirement(id, body) {
  * for the whole suite, sets one number for what is a property of one scenario.
  */
 export function scenario(name, fn, timeoutMs) {
-    if (!currentReqId) {
-        throw new Error(`scenario("${name}") must be nested inside requirement(...)`);
-    }
-    it(name, fn, timeoutMs);
+    it(name, async (ctx) => {
+        if (owningRequirement(ctx.task) === undefined) {
+            throw new Error(`scenario("${name}") must be nested inside requirement(...)`);
+        }
+        return fn();
+    }, timeoutMs);
 }
 //# sourceMappingURL=runtime.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "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": {