@am_shork/attest 0.7.1 → 0.7.3

package/README.md

@@ -29,6 +29,15 @@ together and the test stays green through any edit. Pin the expectation to
 something that does not move with the param — a fixture, a literal in the test,
 or a second independently derived value.
 
+A composite param has a second failure of its own, and it runs the other way. When
+a test **loops over** a list it read from `params`, that list is the set of cases
+the run covers: drop a member and every assertion inside the loop still passes
+over what is left, so the suite quietly tests less with nothing to show for it.
+Pin the extent beside the loop — the members against a literal when their identity
+is the promise, the length when the size is. That literal is not the copy the
+single source exists to prevent: it is not what the system is measured against,
+it is what the intent claimed to cover.
+
 ## Prerequisites
 
 - Node ≥ 20.19
@@ -157,7 +166,7 @@ Every diagnostic carries a `code`, and every code has a section in
 ```
 ERROR   registry-not-static (requirements/upload.reqs.ts:5)
     Value is not a literal.
-    → https://gitlab.com/Pseudorca/attest/-/blob/v0.7.1/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.7.3/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/cli/action.d.ts

@@ -0,0 +1,48 @@
+import { type JsonCommand, type JsonReport } from './json.js';
+/** What an action produces: the machine report plus how to render it for humans. */
+export interface Rendered {
+    report: JsonReport;
+    human: () => void;
+}
+export interface ActionOptions {
+    json?: boolean;
+}
+/**
+ * Send everything written to `process.stdout` to stderr until the returned
+ * function is called.
+ *
+ * This is what keeps the `--json` promise against output Attest does not write
+ * — the third obligation on the machine surface in design §9.1, stated there
+ * because it belongs to the command shell rather than to any emitter, and
+ * attested by ATX-64. The child Vitest run of `verify`/`archive` executes
+ * project code,
+ * and a bare `process.stdout.write` in a spec reaches this stream — `silent:
+ * true` only suppresses Vitest's *console interception*, which such a write
+ * never enters. Measured: the child's writes do arrive through the parent's
+ * `process.stdout.write` rather than through a separately inherited descriptor,
+ * which is why patching it here is sufficient and a change of Vitest pool is
+ * the thing that could quietly make it insufficient. The scenario under ATX-64
+ * runs a real child run for that reason, rather than asserting on this function
+ * with a stub.
+ *
+ * Diverted, not discarded: a human reading a red pipeline still needs the run
+ * output, and stderr is the stream no `--json` consumer parses. It is not
+ * sanitised on the way — `verify` executes project code by design, so painting
+ * the terminal is not a capability this path lacked (design §9.1 scopes its
+ * guarantee to what Attest itself writes).
+ */
+export declare function divertStdout(): () => void;
+/**
+ * Run one command's work with a single output + exit-code contract:
+ *  - success: print the JSON report (`--json`) or the human rendering, and set
+ *    the exit code from `report.ok` — the one source of the verdict.
+ *  - failure: under `--json`, still emit one parseable `internal-error`
+ *    envelope on stdout; otherwise print the stack on stderr. Exit code 1.
+ *
+ * Under `--json` the action runs with stdout diverted, so the report is the
+ * only thing on that stream. The divert is released before either rendering
+ * runs — the report has to reach the real stdout, and the human path was never
+ * under the promise.
+ */
+export declare function runAction(command: JsonCommand, opts: ActionOptions, action: () => Promise<Rendered>): Promise<void>;
+//# sourceMappingURL=action.d.ts.map

package/dist/cli/action.js

@@ -0,0 +1,100 @@
+// The convergence point every command passes through: one output, one exit
+// code (design §9). It lives here rather than in `cli/index.ts` because that
+// module calls `program.parseAsync()` at import time — importing it to test the
+// contract would run the CLI. The interface is the test surface, so the
+// contract moved to where a scenario can cross the same seam a command does.
+import { renderJson, errorReport } from './json.js';
+import { formatCrash } from './report.js';
+import { packageVersion } from '../core/version.js';
+const VERSION = packageVersion();
+/**
+ * Send everything written to `process.stdout` to stderr until the returned
+ * function is called.
+ *
+ * This is what keeps the `--json` promise against output Attest does not write
+ * — the third obligation on the machine surface in design §9.1, stated there
+ * because it belongs to the command shell rather than to any emitter, and
+ * attested by ATX-64. The child Vitest run of `verify`/`archive` executes
+ * project code,
+ * and a bare `process.stdout.write` in a spec reaches this stream — `silent:
+ * true` only suppresses Vitest's *console interception*, which such a write
+ * never enters. Measured: the child's writes do arrive through the parent's
+ * `process.stdout.write` rather than through a separately inherited descriptor,
+ * which is why patching it here is sufficient and a change of Vitest pool is
+ * the thing that could quietly make it insufficient. The scenario under ATX-64
+ * runs a real child run for that reason, rather than asserting on this function
+ * with a stub.
+ *
+ * Diverted, not discarded: a human reading a red pipeline still needs the run
+ * output, and stderr is the stream no `--json` consumer parses. It is not
+ * sanitised on the way — `verify` executes project code by design, so painting
+ * the terminal is not a capability this path lacked (design §9.1 scopes its
+ * guarantee to what Attest itself writes).
+ */
+export function divertStdout() {
+    const stream = process.stdout;
+    // The prior *state* of the property, not the function it held. `write` is
+    // inherited from `Writable.prototype`, so the patch below is a new own
+    // property and undoing it means removing that property — assigning the old
+    // function back would leave a bound copy shadowing the prototype forever, and
+    // would silently swallow anyone else's patch on a nested divert.
+    const owned = Object.getOwnPropertyDescriptor(stream, 'write');
+    const divert = (chunk, encoding, callback) => typeof encoding === 'function'
+        ? process.stderr.write(chunk, encoding)
+        : process.stderr.write(chunk, encoding, callback);
+    stream.write = divert;
+    return () => {
+        if (owned)
+            Object.defineProperty(stream, 'write', owned);
+        else
+            Reflect.deleteProperty(stream, 'write');
+    };
+}
+/**
+ * Run one command's work with a single output + exit-code contract:
+ *  - success: print the JSON report (`--json`) or the human rendering, and set
+ *    the exit code from `report.ok` — the one source of the verdict.
+ *  - failure: under `--json`, still emit one parseable `internal-error`
+ *    envelope on stdout; otherwise print the stack on stderr. Exit code 1.
+ *
+ * Under `--json` the action runs with stdout diverted, so the report is the
+ * only thing on that stream. The divert is released before either rendering
+ * runs — the report has to reach the real stdout, and the human path was never
+ * under the promise.
+ */
+export async function runAction(command, opts, action) {
+    try {
+        const { report, human } = await withStdoutDiverted(opts.json === true, action);
+        if (opts.json)
+            console.log(renderJson(report));
+        else
+            human();
+        process.exitCode = report.ok ? 0 : 1;
+    }
+    catch (err) {
+        if (opts.json) {
+            // Unsanitised on purpose: `JSON.stringify` escapes every C0 character,
+            // so these bytes cannot carry one out (see report.ts). That is a claim
+            // about what this line writes and nothing wider — what the project under
+            // test writes is the divert's business, above.
+            console.log(renderJson(errorReport(VERSION, command, err)));
+        }
+        else {
+            console.error(formatCrash(err));
+        }
+        process.exitCode = 1;
+    }
+}
+/** Run `action` with stdout diverted when `divert`, restoring on every path. */
+async function withStdoutDiverted(divert, action) {
+    if (!divert)
+        return action();
+    const release = divertStdout();
+    try {
+        return await action();
+    }
+    finally {
+        release();
+    }
+}
+//# sourceMappingURL=action.js.map

package/dist/cli/index.js

@@ -7,14 +7,22 @@
 // The exit code is always derived from that report's `ok`, so the JSON verdict
 // and the process status can never disagree — including on the crash path,
 // where the report is an `internal-error` envelope instead of a bare stack.
+//
+// Both halves of that promise are kept by `runAction` (cli/action.ts), which is
+// where the contract is stated and tested; this file only supplies the work.
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { resolve } from 'node:path';
 import { writeAtomic } from '../core/write.js';
 import { runCheck, runVerify, runCover, runArchive, runArchiveApply, runInit, runRender, runRenderCheck, runStatus, DEFAULT_TARGET, TARGET_NAMES, } from '../core/pipeline.js';
 import { hasError } from '../core/types.js';
+// The one project-derived value this shell still interpolates itself. `--out`
+// is argv, which on a fork MR pipeline is written by the repository's own CI
+// config — so it is the project's text, not the operator's (ATX-37).
+import { inline } from '../core/terminal.js';
+import { runAction } from './action.js';
 import { formatArchiveVerdict, formatCrash, formatIssues, formatScope, summarize, formatCoverage, formatStatus, } from './report.js';
-import { archiveReport, checkReport, coverReport, errorReport, initReport, renderJson, renderReport, statusReport, verifyReport, } from './json.js';
+import { archiveReport, checkReport, coverReport, initReport, renderReport, statusReport, verifyReport, } from './json.js';
 import { packageVersion } from '../core/version.js';
 const VERSION = packageVersion();
 /** `runArchive` in the shape `--apply` returns, so the two share one call site. */
@@ -47,34 +55,6 @@ const VITEST_CONFIG_HELP = 'load this Vitest config in the child run (transforms
 function vitestConfig(opts) {
     return opts.vitestConfig ? resolve(process.cwd(), opts.vitestConfig) : undefined;
 }
-/**
- * Run one command's work with a single output + exit-code contract:
- *  - success: print the JSON report (`--json`) or the human rendering, and set
- *    the exit code from `report.ok` — the one source of the verdict.
- *  - failure: under `--json`, still emit one parseable `internal-error`
- *    envelope on stdout; otherwise print the stack on stderr. Exit code 1.
- */
-async function runAction(command, opts, action) {
-    try {
-        const { report, human } = await action();
-        if (opts.json)
-            console.log(renderJson(report));
-        else
-            human();
-        process.exitCode = report.ok ? 0 : 1;
-    }
-    catch (err) {
-        if (opts.json) {
-            // Unsanitised on purpose: `JSON.stringify` escapes every C0 character, so
-            // the machine surface was never the exposed one (see report.ts).
-            console.log(renderJson(errorReport(VERSION, command, err)));
-        }
-        else {
-            console.error(formatCrash(err));
-        }
-        process.exitCode = 1;
-    }
-}
 program
     .command('check')
     .description('Static structural validation (fast CI pre-check); runs no project code.')
@@ -168,7 +148,7 @@ program
                 report: renderReport(VERSION, issues, opts.out),
                 human: () => {
                     if (issues.length === 0)
-                        console.log(chalk.green(`✓ ${opts.out} is up to date.`));
+                        console.log(chalk.green(`✓ ${inline(opts.out ?? '')} is up to date.`));
                     else {
                         console.log(formatIssues(issues));
                         console.log(summarize(issues));
@@ -188,7 +168,7 @@ program
                     console.log(summarize(issues));
                 }
                 else if (dest) {
-                    console.log(chalk.green(`✓ Wrote ${opts.out}`));
+                    console.log(chalk.green(`✓ Wrote ${inline(opts.out ?? '')}`));
                 }
                 else {
                     process.stdout.write(markdown);
@@ -261,7 +241,6 @@ program
                 console.log(summarize(result.issues));
                 return;
             }
-            console.log(chalk.bold(`Change: ${result.change}`));
             console.log(formatStatus(result));
         },
     };

package/dist/cli/json.d.ts

@@ -74,8 +74,9 @@ export declare function renderReport(version: string, issues: Issue[], outFile?:
 /**
  * `init`. Carries the paths written so a consumer learns where the instructions
  * went without hardcoding the convention. `issues` is empty on the success path
- * — `init` writes or throws — apart from an `unknown-target` ERROR, which is
- * refused before anything is written and so reports no files at all.
+ * — `init` writes or throws — apart from the two ERRORs it refuses on,
+ * `unknown-target` and `unsafe-target-path`. Both are decided before anything is
+ * written and so report no files at all.
  *
  * `outFile` survives beside `outFiles` for the one-file run, which is what the
  * default invocation still is: dropping it would break the consumer the field

package/dist/cli/json.js

@@ -92,8 +92,9 @@ export function renderReport(version, issues, outFile) {
 /**
  * `init`. Carries the paths written so a consumer learns where the instructions
  * went without hardcoding the convention. `issues` is empty on the success path
- * — `init` writes or throws — apart from an `unknown-target` ERROR, which is
- * refused before anything is written and so reports no files at all.
+ * — `init` writes or throws — apart from the two ERRORs it refuses on,
+ * `unknown-target` and `unsafe-target-path`. Both are decided before anything is
+ * written and so report no files at all.
  *
  * `outFile` survives beside `outFiles` for the one-file run, which is what the
  * default invocation still is: dropping it would break the consumer the field

package/dist/cli/report.js

@@ -166,7 +166,15 @@ const STATE_MARK = {
  * the argument that keeps `render --check` comparing documents rather than bytes.
  */
 export function formatStatus(result) {
-    const lines = [];
+    // The header is built here rather than in the CLI action, and that is a fix
+    // rather than a tidy-up. It was interpolated and printed in `cli/index.ts`,
+    // which put it past the sanitiser — three lines above a closing line that
+    // puts the same value through `inline`. `ATX-37` covers "everything the CLI
+    // writes to a terminal", and a write that lives in the shell can only be
+    // attested by spawning a process, because `cli/index.ts` runs the CLI at
+    // import. Moving the line to the module that already owns this report makes
+    // the obligation reachable by a scenario — the interface is the test surface.
+    const lines = [chalk.bold(`Change: ${inline(result.change)}`)];
     if (result.rows.length === 0) {
         lines.push(chalk.dim('(this change adds no requirements)'));
     }

package/dist/core/docs.d.ts

@@ -8,7 +8,7 @@
  * and the `##` headings of both language documents, so landing here cannot
  * produce a dead link.
  */
-export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "added-id-unmerged", "apply-no-prefix-owner", "apply-unsupported-delta", "change-not-found", "compiler-unsupported", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "non-scalar-interpolation", "orphan-test", "possible-drift", "proposed-spec-name-taken", "proposed-spec-unclaimed", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "spec-in-change-dir", "spec-load-failed", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target"];
+export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "added-id-unmerged", "apply-no-prefix-owner", "apply-unsupported-delta", "change-not-found", "compiler-unsupported", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "non-scalar-interpolation", "orphan-test", "possible-drift", "proposed-spec-name-taken", "proposed-spec-unclaimed", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "spec-in-change-dir", "spec-load-failed", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target", "unreadable-file", "unsafe-target-path"];
 export type IssueCode = (typeof ISSUE_CODES)[number];
 /**
  * The page explaining `code`, or `undefined` when nothing explains it.

package/dist/core/docs.js

@@ -55,6 +55,8 @@ export const ISSUE_CODES = [
     'unbound-param',
     'uncovered-requirement',
     'unknown-target',
+    'unreadable-file',
+    'unsafe-target-path',
 ];
 const DOCUMENTED = new Set(ISSUE_CODES);
 const REPO = 'https://gitlab.com/Pseudorca/attest/-/blob';

package/dist/core/loader.js

@@ -60,38 +60,59 @@ const VITEST_STUB = 'export const describe=()=>{};export const it=()=>{};export
     'export default {};';
 export async function createLoader() {
     const dir = mkdtempSync(join(tmpdir(), 'attest-loader-'));
-    const stub = join(dir, 'vitest-stub.mjs');
-    writeFileSync(stub, VITEST_STUB);
-    const server = await createServer({
-        configFile: false,
-        logLevel: 'error',
-        // Not just quiet — sanitised. See `sanitisedLogger`: what survives
-        // `logLevel: 'error'` is exactly the message that carries the checked
-        // project's own text.
-        customLogger: sanitisedLogger(),
-        appType: 'custom',
-        // `ws: false` is load-bearing, and `middlewareMode` is not enough on its
-        // own: it suppresses the HTTP server but Vite still starts the HMR
-        // WebSocket server, which binds `::` — every interface, not loopback — on
-        // port 24678. Every `attest` command that reads a registry by evaluating it
-        // therefore opened a network port for the length of the run, on a
-        // developer's machine and on every CI runner, for a channel that does
-        // nothing here: nothing subscribes to HMR, because nothing is watching.
-        //
-        // The visible symptom was the collision. Two attest processes at once —
-        // ordinary in a CI matrix, and what this repo's own concurrent specs do —
-        // and the second printed `WebSocket server error: Port is already in use`
-        // into the middle of a report, through a `logLevel: 'error'` that was
-        // supposed to have silenced the loader entirely.
-        //
-        // `hmr: false` does *not* close it (measured, Vite 5.4): the ws server is
-        // created before the hmr option is consulted. `ws: false` is the one that
-        // leaves no listening handle at all.
-        server: { middlewareMode: true, ws: false },
-        resolve: { alias: { vitest: stub } },
-        ssr: { noExternal: ['vitest'] },
-        optimizeDeps: { noDiscovery: true },
-    });
+    // Everything between creating the directory and returning its owner runs
+    // inside this `try`, because until the caller holds the object below, nothing
+    // else can call `close` — so a throw here is the one path where the directory
+    // outlives the only code that knows about it. That is the same leak the
+    // comment on `close` records as already fixed, surviving on the other side of
+    // the same function.
+    //
+    // Stated over the window rather than over `createServer`, which is where it
+    // was found: `writeFileSync` is inside it too, and a disk that is full or a
+    // temp directory that turns read-only between the two calls reaches it without
+    // any project being involved.
+    let server;
+    try {
+        const stub = join(dir, 'vitest-stub.mjs');
+        writeFileSync(stub, VITEST_STUB);
+        server = await createServer({
+            configFile: false,
+            logLevel: 'error',
+            // Not just quiet — sanitised. See `sanitisedLogger`: what survives
+            // `logLevel: 'error'` is exactly the message that carries the checked
+            // project's own text.
+            customLogger: sanitisedLogger(),
+            appType: 'custom',
+            // `ws: false` is load-bearing, and `middlewareMode` is not enough on its
+            // own: it suppresses the HTTP server but Vite still starts the HMR
+            // WebSocket server, which binds `::` — every interface, not loopback — on
+            // port 24678. Every `attest` command that reads a registry by evaluating
+            // it therefore opened a network port for the length of the run, on a
+            // developer's machine and on every CI runner, for a channel that does
+            // nothing here: nothing subscribes to HMR, because nothing is watching.
+            //
+            // The visible symptom was the collision. Two attest processes at once —
+            // ordinary in a CI matrix, and what this repo's own concurrent specs do —
+            // and the second printed `WebSocket server error: Port is already in use`
+            // into the middle of a report, through a `logLevel: 'error'` that was
+            // supposed to have silenced the loader entirely.
+            //
+            // `hmr: false` does *not* close it (measured, Vite 5.4): the ws server is
+            // created before the hmr option is consulted. `ws: false` is the one that
+            // leaves no listening handle at all.
+            server: { middlewareMode: true, ws: false },
+            resolve: { alias: { vitest: stub } },
+            ssr: { noExternal: ['vitest'] },
+            optimizeDeps: { noDiscovery: true },
+        });
+    }
+    catch (err) {
+        // The original error is what the caller has to see, so a cleanup that fails
+        // must not replace it. `force` already forgives a directory that is not
+        // there; this forgives one that will not go.
+        await rm(dir, { recursive: true, force: true }).catch(() => { });
+        throw err;
+    }
     let closed = false;
     return {
         scratchDir: dir,
@@ -111,7 +132,16 @@ export async function createLoader() {
                 await server.close();
             }
             finally {
-                await rm(dir, { recursive: true, force: true });
+                // Swallowed for the same reason as the `rm` on the failing path above,
+                // and it counts for more here: every caller closes from a `finally`, so
+                // a throw from this line replaces whatever the block was doing — the
+                // real error on the way out, or a *successful* return turned into a
+                // crash about a temp directory. What that reader would then be handed
+                // is a misdiagnosis pointing at their own correct files, which this
+                // repository already treats as worse than the gap it fills.
+                // Given up with it: the one signal a failed cleanup could have raised,
+                // which no caller could have acted on anyway.
+                await rm(dir, { recursive: true, force: true }).catch(() => { });
             }
         },
     };

package/dist/core/locate.d.ts

@@ -152,9 +152,10 @@ export declare function idPrefix(id: string): string;
  * development platform could produce (see CHANGELOG.md, `Under consideration`).
  * The memory here needed no such evidence — it is arithmetic, and portable.
  */
-export declare function parseSpecs(files: string[], displayRoot: string): Promise<AttestPlan>;
-/** Parse every `*.spec.ts` under root into one merged plan (file paths shown relative to root). */
-export declare function parseAllSpecFiles(root: string): Promise<AttestPlan>;
+export declare function parseSpecs(files: string[], displayRoot: string): Promise<{
+    plan: AttestPlan;
+    issues: Issue[];
+}>;
 /**
  * Spec-shaped files sitting under `root/changes` — the location a change's
  * specs used to live at, and which nothing walks any more (design §7).

package/dist/core/locate.js

@@ -95,6 +95,43 @@ export async function scanProject(root) {
     }
     return { reqsFiles, specFiles, proposedSpecFiles };
 }
+/**
+ * The message an unreadable file gets, in one place because two call sites
+ * raise it — a registry and a spec — and they must not drift into two
+ * descriptions of one condition (ATX-65).
+ */
+function unreadableIssue(err) {
+    // `RangeError` in practice, from the call stack running out inside
+    // TypeScript's recursive-descent parser. Caught as `unknown` rather than
+    // narrowed to it: the guard's promise is that *no* throw from one file ends
+    // the run, and narrowing would make that promise true only of the one trigger
+    // that has been measured.
+    const detail = err instanceof Error ? err.message : String(err);
+    return {
+        level: 'ERROR',
+        code: 'unreadable-file',
+        message: `Could not be read, so nothing in it was checked: ${detail}. ` +
+            `Everything else in this run was still reported.`,
+    };
+}
+/**
+ * `reader.read`, with a throw turned into an issue about that file.
+ *
+ * At the loop rather than inside either reader, because what is being kept is a
+ * property of the *run* — one file's failure is not the run's failure — and
+ * both readers need it. `readRegistry` folds these concurrently, so an
+ * uncaught throw here rejects the whole `Promise.all` and ends the command:
+ * measured, a 20,000-deep literal in one `params` value reduced `attest check`
+ * to a single `internal-error` (design §5.1, ATX-65).
+ */
+async function readGuarded(reader, file) {
+    try {
+        return await reader.read(file);
+    }
+    catch (err) {
+        return { issue: unreadableIssue(err) };
+    }
+}
 /**
  * Read registries by **executing** the module through the Vite loader.
  *
@@ -207,7 +244,7 @@ export async function loadRegistry(root, reader, files) {
     const paths = files ?? (await scanProject(root)).reqsFiles;
     // Read the files concurrently, then fold the results in sorted file order:
     // the issue list stays deterministic regardless of which one finished first.
-    const loaded = await Promise.all(paths.map(async (file) => ({ file, outcome: await reader.read(file) })));
+    const loaded = await Promise.all(paths.map(async (file) => ({ file, outcome: await readGuarded(reader, file) })));
     const registry = {};
     const issues = [];
     const unreadableFiles = [];
@@ -309,12 +346,24 @@ export async function parseSpecs(files, displayRoot) {
     // Indexed rather than appended, so the merge below follows the input order
     // whatever order the reads finish in.
     const parsed = new Array(files.length);
+    // Same index space, so a file contributes either a parse or an issue and the
+    // two lists cannot disagree about which file is which.
+    const failures = new Array(files.length);
     let next = 0;
     const worker = async () => {
         for (let i = next++; i < files.length; i = next++) {
             const file = files[i];
-            const source = await readFile(file, 'utf8');
-            parsed[i] = parseSpecFile(relativePath(displayRoot, file), source);
+            const display = relativePath(displayRoot, file);
+            // Per file, for the reason `readGuarded` exists above: these run
+            // concurrently, so one throw rejects the whole `Promise.all` and takes
+            // the command with it. A hostile spec scraps only itself (ATX-65).
+            try {
+                parsed[i] = parseSpecFile(display, await readFile(file, 'utf8'));
+            }
+            catch (err) {
+                parsed[i] = { scenarios: [], paramRefs: [] };
+                failures[i] = { ...unreadableIssue(err), file: display };
+            }
         }
     };
     await Promise.all(Array.from({ length: Math.min(PARSE_CONCURRENCY, files.length) }, worker));
@@ -323,11 +372,7 @@ export async function parseSpecs(files, displayRoot) {
         plan.scenarios.push(...one.scenarios);
         plan.paramRefs.push(...one.paramRefs);
     }
-    return plan;
-}
-/** Parse every `*.spec.ts` under root into one merged plan (file paths shown relative to root). */
-export async function parseAllSpecFiles(root) {
-    return parseSpecs(await findFiles(root, isSpecFile), root);
+    return { plan, issues: failures.filter((i) => i !== undefined) };
 }
 /**
  * Spec-shaped files sitting under `root/changes` — the location a change's

package/dist/core/paths.d.ts

@@ -12,4 +12,20 @@
 export declare function toPosixPath(path: string, separator?: string): string;
 /** `path.relative`, in the one spelling the rest of the engine expects. */
 export declare function relativePath(from: string, to: string): string;
+/**
+ * Whether `path` is `root` or sits below it, both given as resolved paths.
+ *
+ * Asked through `relativePath` rather than by comparing prefixes, because the
+ * two ways this goes wrong are both invisible in a `startsWith`. A sibling
+ * directory shares the prefix — `/repo-backup` starts with `/repo` — and on
+ * Windows a path on another drive has *no* relative spelling at all, so
+ * `path.relative` answers with an absolute one rather than a chain of `..`.
+ * Testing the relative form catches both: an escape is either `..`-led or
+ * absolute, and nothing else is.
+ *
+ * The caller owes the resolution. Nothing here follows a symbolic link, so a
+ * path that is lexically inside can still be physically outside — that is the
+ * question `join` cannot answer and this function does not pretend to.
+ */
+export declare function isInside(root: string, path: string): boolean;
 //# sourceMappingURL=paths.d.ts.map

package/dist/core/paths.js

@@ -14,7 +14,7 @@
 // Normalising here rather than at the glob has a second dividend: a report is
 // then byte-identical across platforms, so a `--json` consumer diffing two CI
 // runs is not reading the runner's operating system.
-import { relative, sep } from 'node:path';
+import { isAbsolute, relative, sep } from 'node:path';
 /**
  * A native path as a POSIX one.
  *
@@ -33,4 +33,23 @@ export function toPosixPath(path, separator = sep) {
 export function relativePath(from, to) {
     return toPosixPath(relative(from, to));
 }
+/**
+ * Whether `path` is `root` or sits below it, both given as resolved paths.
+ *
+ * Asked through `relativePath` rather than by comparing prefixes, because the
+ * two ways this goes wrong are both invisible in a `startsWith`. A sibling
+ * directory shares the prefix — `/repo-backup` starts with `/repo` — and on
+ * Windows a path on another drive has *no* relative spelling at all, so
+ * `path.relative` answers with an absolute one rather than a chain of `..`.
+ * Testing the relative form catches both: an escape is either `..`-led or
+ * absolute, and nothing else is.
+ *
+ * The caller owes the resolution. Nothing here follows a symbolic link, so a
+ * path that is lexically inside can still be physically outside — that is the
+ * question `join` cannot answer and this function does not pretend to.
+ */
+export function isInside(root, path) {
+    const rel = relativePath(root, path);
+    return rel !== '..' && !rel.startsWith('../') && !isAbsolute(rel);
+}
 //# sourceMappingURL=paths.js.map