@am_shork/attest 0.7.4 → 0.9.0

package/dist/core/status.js

@@ -49,7 +49,7 @@ export function statusRows(addedIds, plan, firstRun) {
             name: s.name,
             file: s.file,
             line: s.line,
-            firstRun: recordedOutcome(firstRun, reqId, s.name) ?? null,
+            firstRun: recordedOutcome(firstRun, { reqId, file: s.file, name: s.name }) ?? null,
         }));
         return { reqId, state: obligationState(reqId, scenarios, firstRun), scenarios };
     });
@@ -59,7 +59,7 @@ function obligationState(reqId, scenarios, firstRun) {
         return 'no-scenario';
     // Every scenario, not any: the gate raises never-red per scenario, so one
     // proven scenario beside an unproven one is still a blocked change.
-    return scenarios.every((s) => hasRecordedRed(firstRun, reqId, s.name))
+    return scenarios.every((s) => hasRecordedRed(firstRun, { reqId, file: s.file, name: s.name }))
         ? 'proven'
         : 'unproven';
 }

package/dist/core/terminal.js

@@ -12,8 +12,11 @@
 // write to the terminal of whoever is checking it. On a fork MR the author is
 // not the reviewer, and the payload is a scenario name or an exception: erase
 // the lines above, repaint a red verdict green, rewrite the window title. The
-// `--json` path was never exposed — `JSON.stringify` escapes every C0
-// character — which is precisely why this has to hold on the side people read.
+// `--json` path was recorded here as never exposed, on the grounds that
+// `JSON.stringify` escapes every C0 character — true, and narrower than the
+// class below, which also holds DEL and C1. `cli/json.ts` now applies the same
+// rule at the point that document is serialised (ATX-74); this still has to
+// hold independently, because a stream has no such point.
 //
 // **In `core/` rather than in the CLI**, though the CLI is its main caller: the
 // loader has to sanitise Vite's log output for the same reason and cannot

package/dist/core/types.d.ts

@@ -1,11 +1,22 @@
 export type { Requirement, Registry, ParamValue } from './schema.js';
 export type { IssueCode } from './docs.js';
 import type { IssueCode } from './docs.js';
-/** A scenario extracted statically from a spec file (design §5.2). */
-export interface ParsedScenario {
+/**
+ * What identifies one scenario, everywhere the engine compares one (design §5.4).
+ *
+ * All three, and as a bundle rather than three positional strings: the file was
+ * missing from the key that `declared-not-run` and the first-run record are
+ * decided by, and adding it as a fourth `string` argument beside `reqId` and
+ * `name` would have made two adjacent parameters of one type that a caller can
+ * silently transpose. The compiler cannot catch that; a field name can.
+ */
+export interface ScenarioRef {
     reqId: string;
-    name: string;
     file: string;
+    name: string;
+}
+/** A scenario extracted statically from a spec file (design §5.2). */
+export interface ParsedScenario extends ScenarioRef {
     line: number;
 }
 /**
@@ -31,15 +42,33 @@ export type Outcome = 'pass' | 'fail';
 export interface RunResult {
     /** True when no test failed. */
     passed: boolean;
-    /** reqId -> set of scenario names that actually executed (from the task tree). */
-    runtimeCoverage: Map<string, Set<string>>;
     /**
-     * reqId -> scenario name -> how it ended. The same task-tree walk that fills
-     * `runtimeCoverage` already had to tell `pass` from `fail` to decide whether a
-     * scenario executed at all; this keeps that distinction instead of discarding
-     * it, which is what §6's mechanism 2 records.
+     * reqId -> spec file -> the scenario names that actually executed (from the
+     * task tree).
+     *
+     * **The file is part of the key, and its absence was a false green.** Keyed by
+     * `(reqId, name)` alone, two spec files declaring the same scenario name under
+     * the same `requirement()` are one entry, so whichever of them executed
+     * vouched for the other and `declared-not-run` stayed silent about a scenario
+     * that never ran — the one report this tool exists to refuse. The static plan
+     * carries `file` on every `ParsedScenario` and the task tree carries it on
+     * every file task, so only this map ever forgot it.
+     *
+     * Project-relative POSIX, like `unloadedFiles` and for the same reason: it is
+     * compared against a plan built that way (`paths.ts`).
+     */
+    runtimeCoverage: Map<string, Map<string, Set<string>>>;
+    /**
+     * reqId -> spec file -> scenario name -> how it ended. The same task-tree walk
+     * that fills `runtimeCoverage` already had to tell `pass` from `fail` to
+     * decide whether a scenario executed at all; this keeps that distinction
+     * instead of discarding it, which is what §6's mechanism 2 records.
+     *
+     * Keyed identically, and for the identical reason: the same collapse reaches
+     * `mergeRedRecord`, where a base scenario's recorded `fail` satisfied a
+     * same-named proposed scenario's first-red obligation.
      */
-    outcomes: Map<string, Map<string, Outcome>>;
+    outcomes: Map<string, Map<string, Map<string, Outcome>>>;
     /**
      * Spec files that failed to *load*, as project-relative POSIX paths.
      *

package/dist/core/validator.d.ts

@@ -13,6 +13,7 @@ import type { AttestPlan, Issue, ParamRef, Registry } from './types.js';
 export declare function uncoveredIssues(registry: Registry, plan: AttestPlan): Issue[];
 /**
  * Static structural validation (design §5.3). Emits ERROR-level issues for:
+ * - empty-spec: the root declares no requirements at all
  * - orphan-test: a scenario covers an unknown requirement id
  * - uncovered-requirement: a requirement has no scenario
  * - unbound-param: a statement placeholder has no matching param

package/dist/core/validator.js

@@ -28,6 +28,7 @@ export function uncoveredIssues(registry, plan) {
 }
 /**
  * Static structural validation (design §5.3). Emits ERROR-level issues for:
+ * - empty-spec: the root declares no requirements at all
  * - orphan-test: a scenario covers an unknown requirement id
  * - uncovered-requirement: a requirement has no scenario
  * - unbound-param: a statement placeholder has no matching param
@@ -47,6 +48,27 @@ export function uncoveredIssues(registry, plan) {
 export function validateStructure(registry, plan, unreadable = []) {
     const issues = [];
     const knownIds = new Set(Object.keys(registry));
+    // empty-spec: nothing under this root declares intent, so no finding below is
+    // about a requirement — and the report has no line saying why. It is stated
+    // first because everything else this function can emit against an empty
+    // registry is fallout from it: every scenario in the project is an orphan, and
+    // the diagnosis after 135 of them is a diagnosis nobody reaches.
+    //
+    // Guarded on `unreadable`, which is the same withdrawal the orphan advice
+    // makes below and for the same reason. "Point attest at the directory holding
+    // your *.reqs.ts files" is right for a root that has none, and **wrong** for
+    // one whose registry is sitting right there and failed to load: the files were
+    // found, the fix is the load error already in the report, and following the
+    // hint would move a working path. A registry that could not be read is not an
+    // absent one, and the two take different repairs.
+    if (knownIds.size === 0 && unreadable.length === 0) {
+        issues.push({
+            level: 'ERROR',
+            code: 'empty-spec',
+            message: `No requirements found under this root, so there is no intent here to attest. ` +
+                `Point attest at the directory holding your *.reqs.ts files, or add one.`,
+        });
+    }
     // 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

package/package.json

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