@am_shork/attest 0.7.2 → 0.7.4

package/dist/core/static-registry.js

@@ -20,6 +20,7 @@
 // value is fixed by the source text — a second walker would be a second answer
 // to "is this a literal", and those two answers must not be able to disagree.
 import ts from 'typescript';
+import { parseSource } from './compiler.js';
 import { RegistryValidationError, withProposedRequirements } from './registry.js';
 import { RegistrySchema } from './schema.js';
 /** The authoring function a registry file must default-export the result of. */
@@ -45,7 +46,20 @@ class NotStatic extends Error {
  * has to be run — and only the prose around it differs.
  */
 function extractLiteralExport(file, source, fn, noun) {
-    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    // Strict: a source that does not compile is refused here rather than read out
+    // of whatever the parser recovered from it. Before this, a registry truncated
+    // before its closing `});` came back as a complete registry.
+    const parsed = parseSource(file, source);
+    if ('error' in parsed) {
+        return {
+            ok: false,
+            reason: 'syntax',
+            message: `This ${noun} does not compile (${parsed.error.message}), so nothing in it was checked. ` +
+                `Fix the syntax error and run again.`,
+            ...(parsed.error.line === undefined ? {} : { line: parsed.error.line }),
+        };
+    }
+    const sf = parsed.sf;
     const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
     const exported = defaultExportExpression(sf);
     if (!exported) {
@@ -91,10 +105,25 @@ function failure(extracted, code) {
         ...(extracted.line === undefined ? {} : { line: extracted.line }),
     };
 }
+/**
+ * What this reader calls the three ways extraction fails; `DELTA_CODE` below is
+ * the other half.
+ *
+ * A table per reader rather than a ternary in each, because only one row
+ * differs in kind: `syntax` is the same answer for both — a file that does not
+ * compile is not a registry problem or a delta problem, it is not a file — and
+ * two readers spelling that differently is exactly the disagreement this module
+ * opens by refusing to allow.
+ */
+const REGISTRY_CODE = {
+    syntax: 'unreadable-file',
+    'no-default': 'registry-no-default',
+    'not-static': 'registry-not-static',
+};
 export function readRegistrySource(file, source) {
     const extracted = extractLiteralExport(file, source, DEFINE, 'registry');
     if (!extracted.ok) {
-        return failure(extracted, extracted.reason === 'no-default' ? 'registry-no-default' : 'registry-not-static');
+        return failure(extracted, REGISTRY_CODE[extracted.reason]);
     }
     const result = RegistrySchema.safeParse(extracted.value);
     if (!result.success) {
@@ -109,6 +138,12 @@ export function readRegistrySource(file, source) {
     }
     return { ok: true, registry: result.data };
 }
+/** The delta reader's half of the table above `readRegistrySource`. */
+const DELTA_CODE = {
+    syntax: 'unreadable-file',
+    'no-default': 'change-not-found',
+    'not-static': 'registry-not-static',
+};
 /**
  * Read a change's `delta({ … })` from its source (design §7).
  *
@@ -127,7 +162,7 @@ export function readRegistrySource(file, source) {
 export function readDeltaSource(file, source) {
     const extracted = extractLiteralExport(file, source, DELTA, 'delta');
     if (!extracted.ok) {
-        return failure(extracted, extracted.reason === 'no-default' ? 'change-not-found' : 'registry-not-static');
+        return failure(extracted, DELTA_CODE[extracted.reason]);
     }
     const value = extracted.value;
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
@@ -148,6 +183,78 @@ export function readDeltaSource(file, source) {
     // thing that would notice, and it should have nothing to notice.
     return { ok: true, delta: withProposedRequirements(value) };
 }
+/**
+ * The requirement ids a source *declares*, read from a file that could not be
+ * read as a registry (design §5.3).
+ *
+ * This is not a second registry reader and cannot become one: it returns ids and
+ * nothing else, it validates none of them, and no command builds a `Registry`
+ * from what it finds. What it exists for is the question `orphan-test` cannot
+ * otherwise answer — is this scenario attesting an id that a *broken* file
+ * declares, or one that genuinely does not exist — and the answer decides
+ * whether a finding is a fact or fallout.
+ *
+ * It reads the ids rather than the file's id *prefix*, which is what this was
+ * first framed as needing. The prefix cannot be recovered from a path: this
+ * repository's own registry is `attest.reqs.ts` holding `ATX-*`, which is the
+ * evidence that killed the prefix-matches-filename rule (see CHANGELOG,
+ * `Considered and rejected`). The ids are in the source, so nothing has to be
+ * inferred from a naming convention that nothing enforces.
+ *
+ * Recall is partial by construction, and the direction of the miss is the point:
+ * an id it does not find keeps its `orphan-test`, so the report stays noisy —
+ * never wrong. Measured over the failure modes that produce an unreadable
+ * registry: a truncated file, a missing default export, a non-literal *value*, a
+ * schema-invalid entry, a module that throws at import, and a spread of ids from
+ * another module all yield the ids written in this file; only a registry built
+ * by a call — `export default buildReqs()` — yields none, and that file contains
+ * no id to find.
+ *
+ * `ts.createSourceFile` is deliberately error-tolerant, which is what lets the
+ * first of those cases work at all: the parser recovers an object literal from a
+ * file that does not compile.
+ */
+export function declaredIdsFromSource(file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    const names = localNames(sf, DEFINE);
+    const ids = new Set();
+    // Any `defineRequirements({ … })` in the file, not only the exported one: the
+    // failure being diagnosed is often that the call is not where it should be —
+    // `export const registry = …` is a whole failure mode — and the ids are no
+    // less declared for it. Scoped to that call's argument all the same, so an
+    // id-shaped key in unrelated data is not mistaken for a requirement.
+    const visit = (node) => {
+        // `arguments.length > 0` rather than `=== 1`, which is what the reader
+        // demands: this runs on files the reader has already refused, so being
+        // stricter than it here could only lose ids it is not deciding anything by.
+        if (ts.isCallExpression(node) && node.arguments.length > 0 && callsAuthoringFn(node, names, DEFINE)) {
+            const arg = unwrap(node.arguments[0]);
+            if (ts.isObjectLiteralExpression(arg)) {
+                for (const prop of arg.properties) {
+                    const name = prop.name;
+                    if (!name)
+                        continue;
+                    if (!ts.isStringLiteral(name) && !ts.isIdentifier(name))
+                        continue;
+                    if (REQUIREMENT_ID.test(name.text))
+                        ids.add(name.text);
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return [...ids];
+}
+/**
+ * The id shape, as a bare regex rather than through `RequirementIdSchema`.
+ *
+ * Nothing is being validated here — a key that does not look like an id is
+ * simply not one, and there is no author to tell. Kept identical to the schema's
+ * pattern by `tests/static-registry.spec.ts`, which is the only place the two
+ * spellings can be held together.
+ */
+const REQUIREMENT_ID = /^[A-Z]+-\d+$/;
 /**
  * The expression a file default-exports, following one level of local binding.
  *
@@ -191,10 +298,20 @@ function constInitializer(sf, name) {
 function authoringCall(expr, sf, fn) {
     if (!ts.isCallExpression(expr) || expr.arguments.length !== 1)
         return undefined;
-    const callee = expr.expression;
-    const named = (ts.isIdentifier(callee) && localNames(sf, fn).has(callee.text)) ||
-        (ts.isPropertyAccessExpression(callee) && callee.name.text === fn);
-    return named ? expr.arguments[0] : undefined;
+    return callsAuthoringFn(expr, localNames(sf, fn), fn) ? expr.arguments[0] : undefined;
+}
+/**
+ * Whether a call is a call of `fn`, by the local names the imports bound to it.
+ *
+ * One predicate for both readers of this question — the extraction above and the
+ * id recovery below — because they must not be able to disagree about what
+ * counts as the authoring call. An alias rule taught to one and not the other
+ * would make recovery silently miss exactly the files the reader refuses.
+ */
+function callsAuthoringFn(call, names, fn) {
+    const callee = call.expression;
+    return ((ts.isIdentifier(callee) && names.has(callee.text)) ||
+        (ts.isPropertyAccessExpression(callee) && callee.name.text === fn));
 }
 /** Local names bound to the imported `fn`, including aliases. */
 function localNames(sf, fn) {
@@ -329,7 +446,15 @@ function numericValue(node) {
     return value;
 }
 export function registryInsertionPoint(file, source) {
-    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    // The write site, and the one where a recovered AST does damage rather than
+    // merely misreports: an offset taken from a file that does not compile would
+    // splice a new requirement into it. `undefined` is this function's documented
+    // refusal to guess, and a source that will not parse is the clearest case of
+    // one there is.
+    const parsed = parseSource(file, source);
+    if ('error' in parsed)
+        return undefined;
+    const sf = parsed.sf;
     const exported = defaultExportExpression(sf);
     if (!exported)
         return undefined;

package/dist/core/validator.d.ts

@@ -1,3 +1,4 @@
+import type { UnreadableRegistry } from './locate.js';
 import type { AttestPlan, Issue, ParamRef, Registry } from './types.js';
 /**
  * Uncovered requirements: intent exists but no scenario attests it (design §5.3).
@@ -20,11 +21,15 @@ 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.
+ * and one more WARNING, which exists only when a registry file failed to load:
+ * - orphan-from-failed-registry: the scenarios attesting ids that file declares
+ *
+ * `unreadable` is the `*.reqs.ts` files that failed to load, each with the ids
+ * its source still names (see `loadRegistry`). It changes no verdict — only
+ * which findings are stated per scenario and which are stated once, for the
+ * reason below.
  */
-export declare function validateStructure(registry: Registry, plan: AttestPlan, registryIncomplete?: boolean): Issue[];
+export declare function validateStructure(registry: Registry, plan: AttestPlan, unreadable?: readonly UnreadableRegistry[]): 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

@@ -1,5 +1,6 @@
 // Structural validation + anti-drift heuristic (design §5.3, §6).
 // Graded reporting: ERROR / WARNING / INFO, each with file + line + fix hint.
+import { byCodeUnit } from './order.js';
 /**
  * Uncovered requirements: intent exists but no scenario attests it (design §5.3).
  *
@@ -35,11 +36,15 @@ 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.
+ * and one more WARNING, which exists only when a registry file failed to load:
+ * - orphan-from-failed-registry: the scenarios attesting ids that file declares
+ *
+ * `unreadable` is the `*.reqs.ts` files that failed to load, each with the ids
+ * its source still names (see `loadRegistry`). It changes no verdict — only
+ * which findings are stated per scenario and which are stated once, for the
+ * reason below.
  */
-export function validateStructure(registry, plan, registryIncomplete = false) {
+export function validateStructure(registry, plan, unreadable = []) {
     const issues = [];
     const knownIds = new Set(Object.keys(registry));
     // orphan-test: covers a requirement that does not exist.
@@ -50,27 +55,75 @@ export function validateStructure(registry, plan, registryIncomplete = false) {
     // 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.
+    // the report. Measured on one broken registry of three requirements: six
+    // ERRORs, of which one was the cause and five were its shadow.
+    //
+    // Which of the two a given orphan is *can* be decided here, because
+    // `loadRegistry` brings back the ids the broken file's source still names. So
+    // the scenarios attesting those ids are not reported one by one: they are
+    // fallout from a finding already in the report, and the fallout is stated once
+    // per file that caused it. That is the same move `duplicate-prefix` makes —
+    // the fact is about the file, not about each requirement that reveals it — and
+    // the same order ATX-62 records for `spec-load-failed`: the replacement comes
+    // first, the withdrawal follows it, because suppressing with nothing in its
+    // place trades a wrong message for silence.
     //
-    // 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.`
+    // Nothing is lost by collapsing them. The replacement names the file, the
+    // count and the ids, so a reader can still see which scenarios are affected;
+    // the load failure is already an ERROR, so the verdict cannot move; and the
+    // scenarios themselves are not defective — they will be verified normally the
+    // moment the registry loads.
+    const swallowed = new Map(unreadable.map((u) => [u.file, []]));
+    const ownerOf = new Map();
+    for (const u of unreadable)
+        for (const id of u.ids)
+            ownerOf.set(id, u.file);
+    // An unreadable file whose ids could not be recovered leaves the question open
+    // for every orphan that is not claimed by another one, and the hedged advice
+    // is what an open question sounds like. When every unreadable file gave up its
+    // ids, an orphan none of them claims is genuinely unknown — and gets the plain
+    // advice it deserves, which the hedge had been withdrawing from correct
+    // findings too.
+    const someFileOpaque = unreadable.some((u) => u.ids.length === 0);
+    const orphanFix = (id) => someFileOpaque
+        ? `A registry file failed to load and its ids could not be read, so "${id}" may be one of them — fix that first, and add it 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({
-                level: 'ERROR',
-                code: 'orphan-test',
-                reqId: s.reqId,
-                file: s.file,
-                line: s.line,
-                message: `scenario "${s.name}" attests unknown requirement "${s.reqId}". ${orphanFix(s.reqId)}`,
-            });
+        if (knownIds.has(s.reqId))
+            continue;
+        const owner = ownerOf.get(s.reqId);
+        if (owner !== undefined) {
+            swallowed.get(owner).push(s.reqId);
+            continue;
         }
+        issues.push({
+            level: 'ERROR',
+            code: 'orphan-test',
+            reqId: s.reqId,
+            file: s.file,
+            line: s.line,
+            message: `scenario "${s.name}" attests unknown requirement "${s.reqId}". ${orphanFix(s.reqId)}`,
+        });
+    }
+    // WARNING, not ERROR: the defect is the load failure, which is an ERROR of its
+    // own and always present when this is. Reporting it a second time at the same
+    // level would say a broken registry is two problems.
+    //
+    // No `reqId`: the finding is about a file and the set of ids it took down with
+    // it, and no single requirement is implicated — the same reason
+    // `duplicate-prefix` and `spec-load-failed` carry none.
+    for (const u of unreadable) {
+        const ids = swallowed.get(u.file);
+        if (ids.length === 0)
+            continue;
+        const unique = [...new Set(ids)].sort(byCodeUnit);
+        issues.push({
+            level: 'WARNING',
+            code: 'orphan-from-failed-registry',
+            file: u.file,
+            message: `${ids.length} ${ids.length === 1 ? 'scenario attests' : 'scenarios attest'} ids ${u.file} declares (${unique.join(', ')}), and it failed to load — so those ids are missing from this run. ` +
+                `They are not orphans: fix the load failure reported above and they will be verified as usual.`,
+        });
     }
     // uncovered-requirement: intent exists but no scenario attests it. Shared
     // with `cover`, so the two commands cannot drift apart.

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
   "type": "module",
-  "packageManager": "pnpm@10.28.0",
   "engines": {
     "node": ">=20.19"
   },
@@ -37,24 +36,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "clean": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"",
-    "build": "pnpm run clean && tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "typecheck:all": "tsc -p tsconfig.typecheck.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:consumer": "pnpm run build && vitest run --config vitest.consumer.config.ts",
-    "lint": "eslint .",
-    "prepack": "pnpm run build",
-    "prepublishOnly": "pnpm run test:consumer",
-    "attest": "node bin/attest.js",
-    "check:self": "node bin/attest.js check self",
-    "verify:self": "node bin/attest.js verify self",
-    "cover:self": "node bin/attest.js cover self",
-    "render:self": "node bin/attest.js render self --out self/requirements/SPEC.md",
-    "render:self:check": "node bin/attest.js render self --out self/requirements/SPEC.md --check"
-  },
   "keywords": [
     "tdd",
     "spec",
@@ -81,13 +62,20 @@
     "vite": "^8.1.5",
     "vitest": "^4.1.10"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ],
-    "overrides": {
-      "brace-expansion@<5.0.9": ">=5.0.9",
-      "js-yaml@<4.3.1": ">=4.3.1"
-    }
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"",
+    "build": "pnpm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:all": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:consumer": "pnpm run build && vitest run --config vitest.consumer.config.ts",
+    "lint": "eslint .",
+    "attest": "node bin/attest.js",
+    "check:self": "node bin/attest.js check self",
+    "verify:self": "node bin/attest.js verify self",
+    "cover:self": "node bin/attest.js cover self",
+    "render:self": "node bin/attest.js render self --out self/requirements/SPEC.md",
+    "render:self:check": "node bin/attest.js render self --out self/requirements/SPEC.md --check"
   }
-}
+}