@am_shork/attest 0.7.3 → 0.8.0

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,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.7.3",
+  "version": "0.8.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": {
@@ -48,7 +48,7 @@
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "typescript": "^5.5.0 || ^6.0.0",
-    "zod": "^3.23.0"
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "vite": "^8.0.0",