@am_shork/attest 0.7.2 → 0.7.4

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.2/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.7.4/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

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/core/compiler.d.ts

@@ -1,3 +1,4 @@
+import ts from 'typescript';
 import type { Issue } from './types.js';
 /**
  * The range the readers are written against.
@@ -36,5 +37,36 @@ interface CompilerSurface {
  * requirement and every file in the project is equally unreadable because of it.
  */
 export declare function compilerIssue(compiler?: CompilerSurface): Issue | undefined;
+/**
+ * A source that does not compile, thrown where a reader has no failure channel
+ * of its own.
+ *
+ * `parseSpecFile` returns a plan and nothing else, so its refusal has to be a
+ * throw — and `parseSpecs` already catches every throw per file (ATX-65). The
+ * class exists so the *line* survives that trip: without it the position is
+ * prose inside the message, and `unreadable-file` would carry `line` when a
+ * registry failed to compile and not when a spec did, for one condition.
+ */
+export declare class SourceNotCompiled extends Error {
+    readonly line?: number | undefined;
+    constructor(message: string, line?: number | undefined);
+}
+/**
+ * `ts.createSourceFile`, refusing a source that does not compile.
+ *
+ * Every reader that turns source into a *value* goes through this. The one that
+ * deliberately does not is `declaredIdsFromSource`, which runs only on files a
+ * reader has already refused — recovering the ids of a broken registry is the
+ * whole of its job, and a strict parse there would take the diagnostic that
+ * names them away again.
+ */
+export declare function parseSource(file: string, source: string): {
+    sf: ts.SourceFile;
+} | {
+    error: {
+        message: string;
+        line?: number;
+    };
+};
 export {};
 //# sourceMappingURL=compiler.d.ts.map

package/dist/core/compiler.js

@@ -61,4 +61,82 @@ export function compilerIssue(compiler = ts) {
             `If a resolution or override pins the compiler for the whole tree, exclude Attest from it or move that pin back into the supported range.`,
     };
 }
+/**
+ * The syntax error a source carries, or `undefined` when it compiles.
+ *
+ * **`ts.createSourceFile` recovers**: handed a file that does not compile it
+ * still returns a tree, built from what the parser guessed the author meant. So
+ * a tree is not evidence that a file compiles, and every reader that turns
+ * source into a value has to ask separately (ATX-69).
+ *
+ * Lives here because this module already owns what the compiler does and does
+ * not promise — it names `parser.ts`, `static-registry.ts` and `splice.ts` as
+ * the three that open with `createSourceFile`, which is exactly the set that has
+ * to ask this question.
+ *
+ * **Syntactic only, and that is the whole of what keeps it safe.**
+ * `parseDiagnostics` is populated by the parser, so a type error, an unresolved
+ * import and a name that does not exist are all *absent* from it — checking it
+ * cannot turn Attest into a typechecker of someone's project, which it is not
+ * and must not become.
+ *
+ * What "does not compile" means is "does not compile under the TypeScript Attest
+ * resolved", which is the same limit ATX-65 records about parser depth: the
+ * bound belongs to the compiler this is built on, not to a promise this project
+ * is in a position to make.
+ */
+function syntaxError(sf) {
+    // `parseDiagnostics` is not on the public `SourceFile` type — it is
+    // TypeScript's own field, which is why nothing here found it by reading the
+    // signature. Declared *optional* so reaching for it stays honest: a compiler
+    // that stops populating it degrades to reading the recovered tree rather than
+    // throwing, which is the same fail-open `compilerIssue` above is written for.
+    const diagnostics = sf.parseDiagnostics;
+    const first = diagnostics?.[0];
+    if (!first)
+        return undefined;
+    // The first error only. A syntax error cascades — a stray token measured four
+    // of them, where the truncation this was found on measured one — and the ones
+    // after the first are artefacts of the parser's recovery from it, so listing
+    // them describes the recovery rather than the file.
+    const message = ts.flattenDiagnosticMessageText(first.messageText, ' ');
+    const count = diagnostics.length;
+    const suffix = count > 1 ? ` (and ${count - 1} more)` : '';
+    return {
+        message: `${message}${suffix}`,
+        line: sf.getLineAndCharacterOfPosition(first.start).line + 1,
+    };
+}
+/**
+ * A source that does not compile, thrown where a reader has no failure channel
+ * of its own.
+ *
+ * `parseSpecFile` returns a plan and nothing else, so its refusal has to be a
+ * throw — and `parseSpecs` already catches every throw per file (ATX-65). The
+ * class exists so the *line* survives that trip: without it the position is
+ * prose inside the message, and `unreadable-file` would carry `line` when a
+ * registry failed to compile and not when a spec did, for one condition.
+ */
+export class SourceNotCompiled extends Error {
+    line;
+    constructor(message, line) {
+        super(message);
+        this.line = line;
+        this.name = 'SourceNotCompiled';
+    }
+}
+/**
+ * `ts.createSourceFile`, refusing a source that does not compile.
+ *
+ * Every reader that turns source into a *value* goes through this. The one that
+ * deliberately does not is `declaredIdsFromSource`, which runs only on files a
+ * reader has already refused — recovering the ids of a broken registry is the
+ * whole of its job, and a strict parse there would take the diagnostic that
+ * names them away again.
+ */
+export function parseSource(file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    const error = syntaxError(sf);
+    return error ? { error } : { sf };
+}
 //# sourceMappingURL=compiler.js.map

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", "unreadable-file"];
+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-from-failed-registry", "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

@@ -37,6 +37,7 @@ export const ISSUE_CODES = [
     'modify-missing',
     'never-red',
     'non-scalar-interpolation',
+    'orphan-from-failed-registry',
     'orphan-test',
     'possible-drift',
     'proposed-spec-name-taken',
@@ -56,6 +57,7 @@ export const ISSUE_CODES = [
     '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

@@ -91,6 +91,20 @@ export declare function evalReader(loader: Loader): RegistryReader;
  * execute user code — and were advertised as static while doing exactly that.
  */
 export declare function staticReader(): RegistryReader;
+/**
+ * A registry file that contributed no ids, and the ids its source still names.
+ *
+ * `ids` is empty when nothing could be recovered — a registry the file computes
+ * rather than writes out, or a source that could not be read at all — and an
+ * empty list is the honest answer, not a failure: it says the ids of that file
+ * are unknown, which is a different thing from that file declaring none.
+ */
+export interface UnreadableRegistry {
+    /** Path relative to the project root, as every `Issue.file` is. */
+    readonly file: string;
+    /** Requirement ids recovered from the source; possibly none. */
+    readonly ids: readonly string[];
+}
 /**
  * Read and merge every `*.reqs.ts` registry under root, with the given reader.
  * A registry the reader rejects becomes its own ERROR; a duplicate id across
@@ -110,7 +124,8 @@ export declare function loadRegistry(root: string, reader: RegistryReader, files
     issues: Issue[];
     prefixOwners: Record<string, string>;
     /**
-     * Registry files that contributed **no ids**, relative to `root`.
+     * Registry files that contributed **no ids**, relative to `root`, each with
+     * whatever ids its source still says it declares.
      *
      * Not the same question as "did loading produce an ERROR": `duplicate-prefix`
      * and `duplicate-requirement` are ERRORs raised *after* a successful read, and
@@ -119,8 +134,13 @@ export declare function loadRegistry(root: string, reader: RegistryReader, files
      * re-derived that from the issue codes would be maintaining a second answer
      * to a question this loop already knows — the mistake `prefixOwners` is here
      * to avoid one shape of.
+     *
+     * The ids come with the file for the same reason: `validateStructure` has to
+     * separate a scenario attesting a *broken* file's requirement from one
+     * attesting an id that does not exist, and re-deriving which file an id
+     * belongs to somewhere else would be that same second answer.
      */
-    unreadableFiles: string[];
+    unreadable: UnreadableRegistry[];
 }>;
 /**
  * The part of an id that names the space it lives in — `AUTH` of `AUTH-3`.

package/dist/core/locate.js

@@ -4,10 +4,11 @@ import { readdir, readFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { relativePath } from './paths.js';
 import { parseSpecFile } from './parser.js';
-import { readRegistrySource } from './static-registry.js';
+import { declaredIdsFromSource, readRegistrySource } from './static-registry.js';
 import { RegistryValidationError } from './registry.js';
 import { RegistrySchema } from './schema.js';
 import { byCodeUnit } from './order.js';
+import { SourceNotCompiled } from './compiler.js';
 // Proposed changes and archived changes are excluded from normal scanning:
 // a change's requirements/specs only count once its gate passes and it is
 // merged (design §7, §8). `attest archive <name>` includes them explicitly.
@@ -107,11 +108,17 @@ function unreadableIssue(err) {
     // 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);
+    // The one throw that carries a position: a source that does not compile knows
+    // which line stopped it, and a syntax error without a line is most of the
+    // diagnostic gone. Narrowing to enrich, never to decide — everything still
+    // arrives here and still becomes this issue, which is the promise above.
+    const line = err instanceof SourceNotCompiled ? err.line : undefined;
     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.`,
+        ...(line === undefined ? {} : { line }),
     };
 }
 /**
@@ -226,6 +233,18 @@ export function staticReader() {
         },
     };
 }
+/** Ids recoverable from a registry file that would not load; none if it will not even open. */
+async function declaredIds(absPath) {
+    try {
+        return declaredIdsFromSource(basename(absPath), await readFile(absPath, 'utf8'));
+    }
+    catch {
+        // The file that failed to load is already reported. A second failure
+        // reading it changes nothing about that diagnosis and must not replace it
+        // with a crash — this path only ever *adds* precision to another finding.
+        return [];
+    }
+}
 /**
  * Read and merge every `*.reqs.ts` registry under root, with the given reader.
  * A registry the reader rejects becomes its own ERROR; a duplicate id across
@@ -247,7 +266,7 @@ export async function loadRegistry(root, reader, files) {
     const loaded = await Promise.all(paths.map(async (file) => ({ file, outcome: await readGuarded(reader, file) })));
     const registry = {};
     const issues = [];
-    const unreadableFiles = [];
+    const unreadable = [];
     // Which file first claimed each id prefix. The prefix is the only unit above
     // the requirement (design §11) and nothing allocates it, so two files
     // claiming one is the collision no command would otherwise report — the ids
@@ -263,7 +282,13 @@ export async function loadRegistry(root, reader, files) {
         const { outcome } = entry;
         if ('issue' in outcome) {
             issues.push({ ...outcome.issue, file: display });
-            unreadableFiles.push(display);
+            // Read the source again for the ids alone. Both readers land here, and the
+            // evaluating one has not read the text at all — a file that threw on
+            // import produced an exception and no bytes. One extra read of a file that
+            // is already an ERROR is not a cost worth arranging around, and sharing
+            // the reader's source instead would mean the two readers passing different
+            // things to one diagnostic.
+            unreadable.push({ file: display, ids: await declaredIds(entry.file) });
             continue;
         }
         // One issue per colliding prefix rather than per requirement: the fact is
@@ -301,7 +326,7 @@ export async function loadRegistry(root, reader, files) {
             }
         }
     }
-    return { registry, issues, prefixOwners: Object.fromEntries(prefixOwner), unreadableFiles };
+    return { registry, issues, prefixOwners: Object.fromEntries(prefixOwner), unreadable };
 }
 /**
  * The part of an id that names the space it lives in — `AUTH` of `AUTH-3`.

package/dist/core/parser.d.ts

@@ -1,3 +1,15 @@
 import type { AttestPlan } from './types.js';
+/**
+ * Throws when `source` does not compile, rather than returning a plan built out
+ * of what the parser recovered from it — a spec truncated mid-file was handing
+ * back the scenarios above the break, so the file counted as coverage while not
+ * compiling. `parseSpecs` turns the throw into the per-file `unreadable-file`
+ * its guard already produces (ATX-65), which is why this can throw at all: the
+ * loop that owns "one file's failure is not the run's failure" is already there.
+ *
+ * A throw rather than a result type, unlike the registry readers, because this
+ * returns a plan and has no failure channel of its own; adding one would change
+ * every caller to say what the guard above them already says.
+ */
 export declare function parseSpecFile(file: string, source: string): AttestPlan;
 //# sourceMappingURL=parser.d.ts.map

package/dist/core/parser.js

@@ -3,9 +3,25 @@
 // requirement()/scenario() calls with literal ids, and grabs the line number
 // at parse time — OpenSpec's "parse into strong types, capture the line now".
 import ts from 'typescript';
+import { parseSource, SourceNotCompiled } from './compiler.js';
+/**
+ * Throws when `source` does not compile, rather than returning a plan built out
+ * of what the parser recovered from it — a spec truncated mid-file was handing
+ * back the scenarios above the break, so the file counted as coverage while not
+ * compiling. `parseSpecs` turns the throw into the per-file `unreadable-file`
+ * its guard already produces (ATX-65), which is why this can throw at all: the
+ * loop that owns "one file's failure is not the run's failure" is already there.
+ *
+ * A throw rather than a result type, unlike the registry readers, because this
+ * returns a plan and has no failure channel of its own; adding one would change
+ * every caller to say what the guard above them already says.
+ */
 export function parseSpecFile(file, source) {
-    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, 
-    /* setParentNodes */ true);
+    const parsed = parseSource(file, source);
+    if ('error' in parsed) {
+        throw new SourceNotCompiled(`this file does not compile (${parsed.error.message})`, parsed.error.line);
+    }
+    const sf = parsed.sf;
     const scenarios = [];
     const paramRefs = [];
     const seenRefs = new Set(); // dedupe: one ref per (reqId, scenario)

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