@am_shork/attest 0.7.3 → 0.8.0

package/dist/core/pipeline.js

@@ -14,7 +14,7 @@ import { writeAtomic } from './write.js';
 import { applyMerge, mergedSpecPath } from './merge.js';
 import { compilerIssue } from './compiler.js';
 import { mkdir, readFile, realpath } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { isInside, relativePath } from './paths.js';
 import { hasError } from './types.js';
 // The runner half of the engine, reached only when a command actually needs it.
@@ -108,7 +108,7 @@ export async function runCheck(root, options = {}) {
     // command that reads both the registry and every change's delta, so it is the
     // only one where that distinction is worth anything.
     return withLoader(options, async (loader) => {
-        const { registry, issues, unreadableFiles } = await readRegistry(root, options, scan.reqsFiles, loader);
+        const { registry, issues, unreadable } = await readRegistry(root, options, scan.reqsFiles, loader);
         const { plan, issues: unreadableSpecs } = await parseSpecs(scan.specFiles, root);
         return [
             ...issues,
@@ -121,7 +121,7 @@ export async function runCheck(root, options = {}) {
             // that *did* load are all still true. What it must not do is advise work
             // that the load failure makes wrong — see `orphan-test` in
             // `validateStructure`.
-            ...validateStructure(registry, plan, unreadableFiles.length > 0),
+            ...validateStructure(registry, plan, unreadable),
             ...detectPotentialDrift(registry, plan, plan.paramRefs),
             ...(await unclaimedProposedSpecIssues(root, scan, options, loader)),
             ...(await changeDirSpecIssues(root)),
@@ -291,13 +291,13 @@ export async function runVerify(root, options = {}) {
     const loader = await createLoader();
     let registry;
     let plan;
-    let unreadableFiles;
+    let unreadable;
     const issues = [];
     try {
         const loaded = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
         registry = loaded.registry;
         issues.push(...loaded.issues);
-        unreadableFiles = loaded.unreadableFiles;
+        unreadable = loaded.unreadable;
         const parsedSpecs = await parseSpecs(scan.specFiles, root);
         plan = parsedSpecs.plan;
         issues.push(...parsedSpecs.issues);
@@ -307,7 +307,7 @@ export async function runVerify(root, options = {}) {
     }
     // Same as `check`: everything the loaded half supports is still reported, and
     // only the advice that a load failure would make wrong is withdrawn.
-    issues.push(...validateStructure(registry, plan, unreadableFiles.length > 0));
+    issues.push(...validateStructure(registry, plan, unreadable));
     issues.push(...detectPotentialDrift(registry, plan, plan.paramRefs));
     const attesting = attestingFiles(plan);
     const counts = {
@@ -405,15 +405,38 @@ export async function runCover(root, options = {}) {
  * every time a line moves in a test file.
  */
 export async function runRender(root, options = {}) {
+    // The compiler guard stays the first statement, as it is in every other entry
+    // point (ATX-56): a TypeScript with no AST API is a refusal about the
+    // toolchain, and it outranks anything this run could say about the caller's
+    // paths or registry.
     const unusable = compilerIssue();
     if (unusable)
-        return { markdown: '', issues: [unusable] };
+        return { markdown: '', issues: [unusable], wrote: false };
+    // Then the destination, before the registry is read, so a refused path is the
+    // only thing reported: a run that cannot write anywhere has no reason to also
+    // tell the user about their registry, and the report a pipeline reads should
+    // name the one thing that has to change.
+    const dest = options.out ? await resolveOutFile(root, options.out) : undefined;
+    if (dest && !dest.ok)
+        return { markdown: '', issues: [dest.issue], wrote: false };
     const { registry, issues } = await readRegistry(root, options);
     // A registry that failed to load yields a document that silently omits
-    // requirements. An incomplete spec doc is worse than none, so refuse.
+    // requirements. An incomplete spec doc is worse than none, so refuse — and
+    // since the write is below this line, refusing is also what keeps a broken
+    // registry from overwriting a good committed document.
     if (hasError(issues))
-        return { markdown: '', issues };
-    return { markdown: renderMarkdown(registry), issues };
+        return { markdown: '', issues, wrote: false };
+    const markdown = renderMarkdown(registry);
+    // The write lives here rather than in the CLI, and that is the whole of what
+    // ATX-73 is structurally about: while it sat in the shell it was the one
+    // `writeAtomic` call outside this layer, and it reached the filesystem
+    // without the resolution `runInit` had performed since ATX-66. Resolving and
+    // writing in one function is what stops the two from coming apart again —
+    // a later caller cannot forget a step it never had to take.
+    if (!dest)
+        return { markdown, issues, wrote: false };
+    await writeAtomic(dest.dest, markdown);
+    return { markdown, issues, wrote: true };
 }
 /**
  * Freshness gate for a committed rendering (`attest render --check`).
@@ -423,10 +446,29 @@ export async function runRender(root, options = {}) {
  * alongside a gate that fails when the file no longer matches its source.
  */
 export async function runRenderCheck(root, outFile, target, options = {}) {
+    // Called here despite the delegation further down, because the resolution
+    // below it runs first: the guard has to be the first statement of an entry
+    // point (ATX-56), and delegation cannot supply that once anything precedes
+    // it. Same precedence in both, for the reason `runRender` states.
+    const unusable = compilerIssue();
+    if (unusable)
+        return [unusable];
+    // Resolved before it is read, not only before it is written. A link along the
+    // path makes this compare a fresh document against a file outside the project
+    // — and both verdicts that can produce are ones the gate reports normally, so
+    // the wrong answer is indistinguishable from a right one.
+    //
+    // `target` already carries the spelling a diagnostic must echo, so the pair
+    // `resolveOutFile` wants is assembled here rather than asked of the caller:
+    // taking a `RenderOut` beside a `RenderTarget` would make the shell pass the
+    // same string twice, which is a clump waiting to disagree with itself.
+    const dest = await resolveOutFile(root, { file: outFile, display: target.display });
+    if (!dest.ok)
+        return [dest.issue];
     const { markdown, issues } = await runRender(root, options);
     if (hasError(issues))
         return issues;
-    const current = await readFile(outFile, 'utf8').catch(() => undefined);
+    const current = await readFile(dest.dest, 'utf8').catch(() => undefined);
     const stale = staleIssue(target, current, markdown);
     return stale ? [...issues, stale] : issues;
 }
@@ -467,12 +509,7 @@ export async function runInit(root, names) {
             writes.push({ target, dest: resolved.dest });
         }
         else {
-            refusals.push({
-                level: 'ERROR',
-                code: 'unsafe-target-path',
-                file: target.file,
-                message: `Refusing to write ${target.file}: it resolves to ${resolved.escape}, outside the project. Remove the link at that path and re-run.`,
-            });
+            refusals.push(unsafeTargetPathIssue(target.file, resolved.escape));
         }
     }
     if (refusals.length > 0)
@@ -485,6 +522,61 @@ export async function runInit(root, names) {
     }
     return { files, issues };
 }
+/**
+ * Where a `render` destination really lands, or the refusal that a link
+ * redirected it (design §9: ownership of the path is checked, and who named the
+ * path decides what the refusal is about).
+ *
+ * `init` names its own destinations, so every one of them is checked; `--out`
+ * is the caller's path, and that is the whole of the difference between the two
+ * callers. A path spelled outside the project is the user asking for a file
+ * outside the project — `--out ../site/SPEC.md` is a destination, not an
+ * escape, and refusing it would be refusing the flag. What is not visible in
+ * the argument is a *link* along a path that reads as staying inside, which is
+ * the one a checkout can plant: the victim's `--out` is the string their README
+ * or CI already documents, and the content redirected is the document their
+ * repository wrote.
+ *
+ * So the check applies exactly when the destination is lexically inside the
+ * root, and it is `resolveDest`'s, unchanged. The leaf needs no separate
+ * defence and never did — `writeAtomic` lands by `rename`, which replaces a
+ * symlink rather than following it — but it is resolved with the rest anyway,
+ * because a link there is still a file the user made deliberately and this
+ * refuses rather than destroys it.
+ *
+ * Both entry points that name a destination come through here — the one that
+ * writes it and the one that reads it back to date it — which is why this is
+ * private to this module rather than something a shell is trusted to call.
+ */
+async function resolveOutFile(root, out) {
+    const dest = resolve(out.file);
+    const realRoot = await realpath(root).catch(() => root);
+    // Asked against both spellings of the root, because they differ whenever the
+    // project itself sits under a link: `dest` is built from the caller's cwd, so
+    // it is lexical, and testing only the resolved root would skip the check for
+    // every such checkout — failing open on exactly the layout that has links in
+    // it. `''` is the root itself, which is a directory and not a destination.
+    const rel = isInside(root, dest)
+        ? relativePath(root, dest)
+        : isInside(realRoot, dest)
+            ? relativePath(realRoot, dest)
+            : undefined;
+    if (rel === undefined || rel === '')
+        return { ok: true, dest };
+    const resolved = await resolveDest(realRoot, rel);
+    return resolved.ok
+        ? { ok: true, dest: resolved.dest }
+        : { ok: false, issue: unsafeTargetPathIssue(out.display, resolved.escape) };
+}
+/** The one refusal both destination checks report (design §9). */
+function unsafeTargetPathIssue(display, escape) {
+    return {
+        level: 'ERROR',
+        code: 'unsafe-target-path',
+        file: display,
+        message: `Refusing to write ${display}: it resolves to ${escape}, outside the project. Remove the link at that path and re-run.`,
+    };
+}
 /**
  * Where a target's file really goes, or the path outside the project that
  * asking put it at (design §9: ownership of the path is checked, not assumed).

package/dist/core/red-record.d.ts

@@ -1,17 +1,26 @@
-import type { AttestPlan, Outcome, RunResult } from './types.js';
+import type { AttestPlan, Outcome, RunResult, ScenarioRef } from './types.js';
 /** Where the record lives, relative to the project root. */
 export declare function redRecordPath(root: string, changeName: string): string;
 /** The file name, exported so a diagnostic can name it without rebuilding it. */
 export declare const RED_RECORD_FILE = "first-run.json";
 /**
- * reqId -> scenario name -> the outcome of its first observed run.
+ * reqId -> spec file -> scenario name -> the outcome of its first observed run.
  *
  * Deliberately not a list of "red scenarios": a scenario whose first run passed
  * is the case mechanism 2 exists to catch, so it has to be recorded as a fact
  * rather than as an absence. An absence then means only one thing — never
  * observed at all — and the gate can report the two separately.
+ *
+ * **The file level is what identifies a scenario, and it was missing.** A
+ * scenario is `(reqId, file, name)` in the static plan and was `(reqId, name)`
+ * here, so two spec files declaring the same name under one added requirement
+ * shared an entry — and because the record is monotonic toward `fail`, one of
+ * them going red satisfied the other's first-red obligation. Nested rather than
+ * a composite key string, so no separator has to be chosen that a path or a
+ * scenario name could contain, and so the committed file stays something a
+ * reviewer reads (design §6).
  */
-export type RedRecord = Record<string, Record<string, Outcome>>;
+export type RedRecord = Record<string, Record<string, Record<string, Outcome>>>;
 /**
  * Read the record for a change. A missing or unreadable file is an empty
  * record, never an error: the first stage-1 run legitimately finds nothing, and
@@ -34,7 +43,7 @@ export declare function readRedRecord(root: string, changeName: string): Promise
  * what it must not do is answer from an inherited key whoever constructed the
  * object it was handed. `record[reqId]?.[scenario]` did exactly that.
  */
-export declare function recordedOutcome(record: RedRecord, reqId: string, scenario: string): Outcome | undefined;
+export declare function recordedOutcome(record: RedRecord, ref: ScenarioRef): Outcome | undefined;
 /**
  * Whether this scenario has satisfied the first-red obligation (design §6).
  *
@@ -44,7 +53,7 @@ export declare function recordedOutcome(record: RedRecord, reqId: string, scenar
  * apart — the same argument that extracted `declaredNotRunIssues` and
  * `uncoveredIssues` from the commands that had a copy each.
  */
-export declare function hasRecordedRed(record: RedRecord, reqId: string, scenario: string): boolean;
+export declare function hasRecordedRed(record: RedRecord, ref: ScenarioRef): boolean;
 /**
  * Fold this run's outcomes into the record, for the scenarios that carry an
  * obligation — those covering a requirement this change ADDs.

package/dist/core/red-record.js

@@ -47,6 +47,32 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { z } from 'zod';
 import { byCodeUnit } from './order.js';
+import { mergedSpecPath } from './merge.js';
+import { toPosixPath } from './paths.js';
+/**
+ * The file half of a scenario's identity, as this record spells it.
+ *
+ * A scenario is `(reqId, file, name)` — but the one file this record is about
+ * is a **proposed** spec, and `--apply` renames it in place as step 2 of the
+ * merge. Keyed by the name on disk, a resume after that rename looked up
+ * `app2.spec.ts` in a record written under `app2.proposed.spec.ts`, found
+ * nothing, and blocked a change whose scenarios had been observed red — the
+ * gate refusing its own evidence. Rewriting the record beside the rename was
+ * the alternative and is worse: two files that must move together, in a design
+ * whose whole resume story is that each step is separately idempotent.
+ *
+ * So the key is the **merged** spelling from the start, which the rename cannot
+ * move. It still separates two spec files, which is the collapse this key
+ * exists to prevent; what it deliberately does not separate is one file from
+ * its own proposed name, because those are the same file.
+ *
+ * Through `toPosixPath` because `mergedSpecPath` rebuilds the path with
+ * `node:path`, which on Windows hands back a backslash — and this is a
+ * comparison key against a plan built on POSIX separators (`paths.ts`).
+ */
+function fileKey(file) {
+    return toPosixPath(mergedSpecPath(file));
+}
 /**
  * **The record is a map, so it is built without a prototype.**
  *
@@ -92,7 +118,7 @@ export const RED_RECORD_FILE = 'first-run.json';
  * The gate was never at risk — `hasRecordedRed` compares against `'fail'`, so an
  * unrecognised value blocks exactly like a missing one. This closes the report.
  */
-const RedRecordSchema = z.record(z.string(), z.record(z.string(), z.enum(['pass', 'fail'])));
+const RedRecordSchema = z.record(z.string(), z.record(z.string(), z.record(z.string(), z.enum(['pass', 'fail']))));
 /**
  * Read the record for a change. A missing or unreadable file is an empty
  * record, never an error: the first stage-1 run legitimately finds nothing, and
@@ -122,8 +148,15 @@ export async function readRedRecord(root, changeName) {
     }
     // `JSON.parse` yields `any`; nothing about the file is known until the schema
     // says so, including whether it is an object at all (`JSON.parse('null')`).
-    const firstRun = isRecord(parsed) ? parsed['firstRun'] : undefined;
-    const result = RedRecordSchema.safeParse(firstRun);
+    // The version is checked rather than inferred from whether the shape happens
+    // to parse. A version-1 record keyed `reqId -> name` would fail the schema
+    // anyway and be discarded whole, which is the safe direction — but "discarded
+    // because the format moved" and "discarded because the file is corrupt" are
+    // different facts, and reading one as the other is how a format change gets
+    // made without anyone deciding to make it.
+    if (!isRecord(parsed) || parsed['version'] !== 2)
+        return emptyMap();
+    const result = RedRecordSchema.safeParse(parsed['firstRun']);
     return result.success ? adopt(result.data) : emptyMap();
 }
 /**
@@ -139,8 +172,16 @@ export async function readRedRecord(root, changeName) {
  */
 function adopt(parsed) {
     const record = emptyMap();
-    for (const [id, outcomes] of Object.entries(parsed)) {
-        record[id] = Object.assign(emptyMap(), outcomes);
+    for (const [id, byFile] of Object.entries(parsed)) {
+        const files = emptyMap();
+        // Every level, not just the two that existed before: the file level is as
+        // much a key taken from a string this module did not choose as the other
+        // two, and a container with a prototype is what the whole comment above is
+        // about.
+        for (const [file, outcomes] of Object.entries(byFile)) {
+            files[file] = Object.assign(emptyMap(), outcomes);
+        }
+        record[id] = files;
     }
     return record;
 }
@@ -153,13 +194,17 @@ function adopt(parsed) {
  * what it must not do is answer from an inherited key whoever constructed the
  * object it was handed. `record[reqId]?.[scenario]` did exactly that.
  */
-export function recordedOutcome(record, reqId, scenario) {
-    if (!Object.hasOwn(record, reqId))
+export function recordedOutcome(record, ref) {
+    if (!Object.hasOwn(record, ref.reqId))
         return undefined;
-    const outcomes = record[reqId];
-    if (outcomes === undefined || !Object.hasOwn(outcomes, scenario))
+    const byFile = record[ref.reqId];
+    const key = fileKey(ref.file);
+    if (byFile === undefined || !Object.hasOwn(byFile, key))
         return undefined;
-    return outcomes[scenario];
+    const outcomes = byFile[key];
+    if (outcomes === undefined || !Object.hasOwn(outcomes, ref.name))
+        return undefined;
+    return outcomes[ref.name];
 }
 /**
  * Whether this scenario has satisfied the first-red obligation (design §6).
@@ -170,8 +215,8 @@ export function recordedOutcome(record, reqId, scenario) {
  * apart — the same argument that extracted `declaredNotRunIssues` and
  * `uncoveredIssues` from the commands that had a copy each.
  */
-export function hasRecordedRed(record, reqId, scenario) {
-    return recordedOutcome(record, reqId, scenario) === 'fail';
+export function hasRecordedRed(record, ref) {
+    return recordedOutcome(record, ref) === 'fail';
 }
 /**
  * Fold this run's outcomes into the record, for the scenarios that carry an
@@ -190,42 +235,55 @@ export function mergeRedRecord(existing, plan, run, addedIds) {
     // machines write byte-identical files (the same reason `render` orders ids
     // through one code-unit comparator).
     for (const id of Object.keys(existing).sort(byCodeUnit)) {
-        const outcomes = existing[id];
-        if (outcomes === undefined)
+        const byFile = existing[id];
+        if (byFile === undefined)
             continue;
-        record[id] = Object.assign(emptyMap(), outcomes);
+        const files = emptyMap();
+        for (const file of Object.keys(byFile).sort(byCodeUnit)) {
+            const outcomes = byFile[file];
+            if (outcomes === undefined)
+                continue;
+            files[file] = Object.assign(emptyMap(), outcomes);
+        }
+        record[id] = files;
     }
     let changed = false;
     for (const s of plan.scenarios) {
         if (!added.has(s.reqId))
             continue;
-        const outcome = run.outcomes.get(s.reqId)?.get(s.name);
+        const outcome = run.outcomes.get(s.reqId)?.get(s.file)?.get(s.name);
         // No outcome means the scenario did not execute. That is `declared-not-run`,
         // reported by the gate on its own terms; writing nothing here leaves the
         // obligation unobserved rather than inventing a state for it.
         if (!outcome)
             continue;
         const forId = (record[s.reqId] ??= emptyMap());
+        const forFile = (forId[fileKey(s.file)] ??= emptyMap());
         // Monotonic toward `fail`: a recorded fail is final, a recorded pass can
         // still be corrected by a real one. See the note at the top of this file.
-        if (forId[s.name] === 'fail' || forId[s.name] === outcome)
+        if (forFile[s.name] === 'fail' || forFile[s.name] === outcome)
             continue;
-        forId[s.name] = outcome;
+        forFile[s.name] = outcome;
         changed = true;
     }
-    // Sort within each requirement for the same byte-stability reason.
+    // Sort within each requirement, and within each file, for the same
+    // byte-stability reason.
     for (const id of Object.keys(record)) {
-        const sorted = emptyMap();
-        for (const name of Object.keys(record[id]).sort(byCodeUnit)) {
-            sorted[name] = record[id][name];
+        const sortedFiles = emptyMap();
+        for (const file of Object.keys(record[id]).sort(byCodeUnit)) {
+            const sorted = emptyMap();
+            for (const name of Object.keys(record[id][file]).sort(byCodeUnit)) {
+                sorted[name] = record[id][file][name];
+            }
+            sortedFiles[file] = sorted;
         }
-        record[id] = sorted;
+        record[id] = sortedFiles;
     }
     return { record, changed };
 }
 /** Serialise the record. A trailing newline, so the file is a well-formed text file. */
 export function serialiseRedRecord(changeName, record) {
-    const file = { version: 1, change: changeName, firstRun: record };
+    const file = { version: 2, change: changeName, firstRun: record };
     return `${JSON.stringify(file, null, 2)}\n`;
 }
 /** Container check only — what is *in* it is the schema's business, not this. */

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

@@ -0,0 +1,30 @@
+/**
+ * One structural failure from validating a registry.
+ *
+ * Deliberately not the validator's own issue type: `issues` is reached through
+ * the `./define` subpath, so its element type is a public contract, and §10's
+ * fourth encapsulation rule keeps a dependency's type off one. These two fields
+ * are the whole of what this project consumes — nothing reads `code`,
+ * `expected`, `received` or `fatal`.
+ *
+ * `path` is `PropertyKey[]` rather than `(string | number)[]` because that is
+ * the wider of the two spellings zod has used, so a validator issue assigns to
+ * this without a cast in either direction. Keep it the wider one: narrowing it
+ * would put the next reshape of that type back on the boundary.
+ */
+export interface RegistryValidationIssue {
+    path: PropertyKey[];
+    message: string;
+}
+/**
+ * The message `RegistryValidationError` carries, available without one.
+ *
+ * Three sites report `registry-invalid` — the throwing path in
+ * `defineRequirements`, and the two readers in `locate.ts` and
+ * `static-registry.ts` that report it without throwing — and their messages
+ * have to be identical rather than merely similar. Sharing this function is
+ * what makes that structural rather than a coincidence maintained by hand, so
+ * a new site formats through here and does not grow a fourth spelling.
+ */
+export declare function registryValidationMessage(issues: readonly RegistryValidationIssue[]): string;
+//# sourceMappingURL=registry-issues.d.ts.map

package/dist/core/registry-issues.js

@@ -0,0 +1,26 @@
+// The shape of a registry schema failure, and the one rendering of it
+// (design §5.1, §10).
+//
+// Separate from registry.ts because `./define` maps to that whole module, so
+// everything it exports is a public contract. What has to be public here is the
+// element type of `RegistryValidationError.issues`; the formatter does not, and
+// both of its callers are internal.
+/**
+ * The message `RegistryValidationError` carries, available without one.
+ *
+ * Three sites report `registry-invalid` — the throwing path in
+ * `defineRequirements`, and the two readers in `locate.ts` and
+ * `static-registry.ts` that report it without throwing — and their messages
+ * have to be identical rather than merely similar. Sharing this function is
+ * what makes that structural rather than a coincidence maintained by hand, so
+ * a new site formats through here and does not grow a fourth spelling.
+ */
+export function registryValidationMessage(issues) {
+    // `.map(String)` and not a bare `.join('.')`: under `PropertyKey[]` a segment
+    // can be a symbol, and `join` throws rather than converting one.
+    const fields = issues
+        .map((i) => `  - ${i.path.map(String).join('.') || '(root)'}: ${i.message}`)
+        .join('\n');
+    return `Invalid requirement registry:\n${fields}`;
+}
+//# sourceMappingURL=registry-issues.js.map

package/dist/core/registry.d.ts

@@ -1,10 +1,18 @@
-import { z } from 'zod';
 import { type RegistryInput, type RequirementInput } from './schema.js';
+import { type RegistryValidationIssue } from './registry-issues.js';
 import type { Registry, Requirement } from './types.js';
-/** Thrown when a registry fails structural validation (design §5.1). */
+export type { RegistryValidationIssue } from './registry-issues.js';
+/**
+ * Thrown when a registry fails structural validation (design §5.1).
+ *
+ * `issues` is typed as this project's own {@link RegistryValidationIssue} and
+ * not the validator's, because this class is reached through the `./define`
+ * subpath and the field is therefore a public contract — the same boundary
+ * `Issue.message` holds, with the difference that `Issue` was designed with it.
+ */
 export declare class RegistryValidationError extends Error {
-    readonly issues: z.ZodIssue[];
-    constructor(issues: z.ZodIssue[]);
+    readonly issues: RegistryValidationIssue[];
+    constructor(issues: RegistryValidationIssue[]);
 }
 /**
  * A `const` type parameter infers an array literal as a tuple, and would infer
@@ -139,5 +147,4 @@ export declare function delta<const T extends RegistryDelta>(d: T): DefinedDelta
  * caller wrote is still the literal they hold.
  */
 export declare function withProposedRequirements<T extends RegistryDelta>(d: T): T;
-export {};
 //# sourceMappingURL=registry.d.ts.map

package/dist/core/registry.js

@@ -1,22 +1,24 @@
 // Requirement registry authoring API (design §2, §5.1, §7).
 // defineRequirements validates against RegistrySchema and applies defaults;
 // delta() declares a change delta, applied by applyDelta (see apply.ts).
-import { z } from 'zod';
 import { RegistrySchema, } from './schema.js';
-/** Thrown when a registry fails structural validation (design §5.1). */
+import { registryValidationMessage, } from './registry-issues.js';
+/**
+ * Thrown when a registry fails structural validation (design §5.1).
+ *
+ * `issues` is typed as this project's own {@link RegistryValidationIssue} and
+ * not the validator's, because this class is reached through the `./define`
+ * subpath and the field is therefore a public contract — the same boundary
+ * `Issue.message` holds, with the difference that `Issue` was designed with it.
+ */
 export class RegistryValidationError extends Error {
     issues;
     constructor(issues) {
-        super(`Invalid requirement registry:\n${formatIssues(issues)}`);
+        super(registryValidationMessage(issues));
         this.issues = issues;
         this.name = 'RegistryValidationError';
     }
 }
-function formatIssues(issues) {
-    return issues
-        .map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)
-        .join('\n');
-}
 /**
  * Declare a requirement registry. Validates structure against RegistrySchema
  * (SHALL/MUST keyword, non-empty rationale, well-formed IDs, scalar params) and

package/dist/core/runner.js

@@ -70,12 +70,19 @@ export async function runAndCollect(options = {}) {
         const runtimeCoverage = new Map();
         const outcomes = new Map();
         // Reconstruct coverage from the task tree (not an in-process singleton).
-        const walk = (task) => {
+        //
+        // `file` is threaded down from the file task rather than read off the suite,
+        // because it is the only level that carries a path — and it is what keeps
+        // two spec files declaring the same scenario name under one `requirement()`
+        // from collapsing into a single entry that either of them could satisfy.
+        const walk = (task, file) => {
             if (task.type === 'suite') {
                 const id = requirementIdOf(task.name);
                 if (id !== undefined) {
-                    const set = runtimeCoverage.get(id) ?? new Set();
-                    const byName = outcomes.get(id) ?? new Map();
+                    const byFile = runtimeCoverage.get(id) ?? new Map();
+                    const outcomesByFile = outcomes.get(id) ?? new Map();
+                    const set = byFile.get(file) ?? new Set();
+                    const byName = outcomesByFile.get(file) ?? new Map();
                     for (const c of scenariosUnder(task)) {
                         // A scenario counts as covered only if it actually executed —
                         // skipped/todo scenarios have no run result (enables §8's
@@ -87,12 +94,14 @@ export async function runAndCollect(options = {}) {
                         set.add(c.name);
                         byName.set(c.name, outcome);
                     }
-                    runtimeCoverage.set(id, set);
-                    outcomes.set(id, byName);
+                    byFile.set(file, set);
+                    outcomesByFile.set(file, byName);
+                    runtimeCoverage.set(id, byFile);
+                    outcomes.set(id, outcomesByFile);
                 }
             }
             for (const c of task.tasks ?? [])
-                walk(c);
+                walk(c, file);
         };
         // Assigned, never cast. `TaskLike` is the narrow view this walk needs, and
         // Vitest's `File` satisfies it structurally — so the compiler is the thing
@@ -101,12 +110,15 @@ export async function runAndCollect(options = {}) {
         // exactly the change that would silently empty the runtime coverage.
         const unloadedFiles = [];
         for (const file of vitest.state.getFiles()) {
-            walk(file);
             // Relative and POSIX for the reason everything derived from the root is
             // (`paths.ts`): this becomes an `Issue.file`, which a `--json` consumer
-            // diffs across two CI runs that may not share an operating system.
+            // diffs across two CI runs that may not share an operating system — and,
+            // since the coverage maps are keyed by it, a comparison key against a plan
+            // built the same way.
+            const relative = relativePath(options.root ?? process.cwd(), file.filepath);
+            walk(file, relative);
             if (failedToLoad(file)) {
-                unloadedFiles.push(relativePath(options.root ?? process.cwd(), file.filepath));
+                unloadedFiles.push(relative);
             }
         }
         unloadedFiles.sort(byCodeUnit);