@am_shork/attest 0.5.0 → 0.7.0

package/README.md

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

package/dist/cli/index.js

@@ -11,12 +11,17 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { resolve } from 'node:path';
 import { writeAtomic } from '../core/write.js';
-import { runCheck, runVerify, runCover, runArchive, runInit, runRender, runRenderCheck, runStatus, DEFAULT_TARGET, TARGET_NAMES, } from '../core/pipeline.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';
-import { formatCrash, formatIssues, formatScope, summarize, formatCoverage, formatStatus, } from './report.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 { packageVersion } from '../core/version.js';
 const VERSION = packageVersion();
+/** `runArchive` in the shape `--apply` returns, so the two share one call site. */
+const gateOnly = async (dir, change, options) => ({
+    issues: await runArchive(dir, change, options),
+    written: [],
+});
 const program = new Command();
 program
     .name('attest')
@@ -267,20 +272,17 @@ program
     .argument('[dir]', 'project root', undefined)
     .option(JSON_FLAG, JSON_HELP)
     .option(VITEST_CONFIG_FLAG, VITEST_CONFIG_HELP)
+    .option('--apply', 'if the gate passes, merge the change: splice its ADDED requirements into the registry, rename its proposed specs, and move the change folder to archive/')
     .description('Run the archive gate; merge only if it passes.')
     .action((change, dir, opts) => runAction('archive', opts, async () => {
-    const blocking = await runArchive(root(dir), change, { vitestConfig: vitestConfig(opts) });
+    const run = opts.apply ? runArchiveApply : gateOnly;
+    const { issues: blocking, written } = await run(root(dir), change, {
+        vitestConfig: vitestConfig(opts),
+    });
     return {
         report: archiveReport(VERSION, change, blocking),
         human: () => {
-            if (blocking.length === 0) {
-                console.log(chalk.green(`✓ Gate passed: change "${change}" can be archived.`));
-            }
-            else {
-                console.log(chalk.red(`✗ Gate failed: change "${change}"`));
-                console.log(formatIssues(blocking));
-                console.log(summarize(blocking));
-            }
+            console.log(formatArchiveVerdict(change, blocking, { applied: opts.apply === true, written }));
         },
     };
 }));

package/dist/cli/json.js

@@ -112,7 +112,12 @@ export function archiveReport(version, change, blocking) {
         ...envelope({
             version,
             command: 'archive',
-            ok: blocking.length === 0,
+            // `hasError`, not `blocking.length === 0` (ATX-60). The gate deliberately
+            // keeps its non-blocking output through `--apply`, so a WARNING in here
+            // is planned for — and counting one as a failure made this command answer
+            // not-ok, exit 1, and print a failed gate *after* the merge had written
+            // the files. Every other command already asks the question this way.
+            ok: !hasError(blocking),
             issues: blocking,
         }),
         change,

package/dist/cli/report.d.ts

@@ -57,5 +57,23 @@ export declare function formatScope(scope: VerifyCounts): string;
  * the argument that keeps `render --check` comparing documents rather than bytes.
  */
 export declare function formatStatus(result: StatusResult): string;
+/**
+ * The verdict `attest archive` prints, and the lines under it.
+ *
+ * Here rather than inline in the CLI action for two reasons, and the second is
+ * the one that matters. The shell is a thin veneer that renders what the core
+ * decided; and while this lived in a closure it was the *only* copy of the
+ * verdict nothing could test — so when it asked `blocking.length === 0` of its
+ * own accord, no scenario could see that the line above the issues could call
+ * the gate failed while the JSON beside it called the command ok (ATX-60).
+ *
+ * `hasError`, the same predicate `archiveReport` uses. Not a second reading of
+ * the same array so much as the same question asked once and rendered twice —
+ * which is what the requirement is about.
+ */
+export declare function formatArchiveVerdict(change: string, blocking: Issue[], merge: {
+    applied: boolean;
+    written: readonly string[];
+}): string;
 export declare function formatCoverage(rows: CoverageRow[]): string;
 //# sourceMappingURL=report.d.ts.map

package/dist/cli/report.js

@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { docsUrl } from '../core/docs.js';
 import { byCodeUnit } from '../core/order.js';
 import { INDENT, block, inline } from '../core/terminal.js';
+import { hasError } from '../core/types.js';
 const LEVEL_TAG = {
     ERROR: (s) => chalk.red.bold(s),
     WARNING: (s) => chalk.yellow.bold(s),
@@ -184,6 +185,46 @@ export function formatStatus(result) {
     lines.push(chalk.dim(`Not a verdict: run \`attest archive ${inline(result.change)}\` to run the suite.`));
     return lines.join('\n');
 }
+/**
+ * The verdict `attest archive` prints, and the lines under it.
+ *
+ * Here rather than inline in the CLI action for two reasons, and the second is
+ * the one that matters. The shell is a thin veneer that renders what the core
+ * decided; and while this lived in a closure it was the *only* copy of the
+ * verdict nothing could test — so when it asked `blocking.length === 0` of its
+ * own accord, no scenario could see that the line above the issues could call
+ * the gate failed while the JSON beside it called the command ok (ATX-60).
+ *
+ * `hasError`, the same predicate `archiveReport` uses. Not a second reading of
+ * the same array so much as the same question asked once and rendered twice —
+ * which is what the requirement is about.
+ */
+export function formatArchiveVerdict(change, blocking, merge) {
+    if (hasError(blocking)) {
+        return [
+            chalk.red(`✗ Gate failed: change "${inline(change)}"`),
+            formatIssues(blocking),
+            summarize(blocking),
+        ].join('\n');
+    }
+    const lines = [
+        chalk.green(merge.applied
+            ? `✓ Gate passed and merged: change "${inline(change)}".`
+            : `✓ Gate passed: change "${inline(change)}" can be archived.`),
+    ];
+    // Every path the merge touched, because this is the command that edits files
+    // the user cannot regenerate and they need to know which ones to read before
+    // committing. It is also what a working-tree check would only have
+    // approximated, and it works for someone not using version control at all.
+    for (const path of merge.written)
+        lines.push(chalk.dim(`  ${inline(path)}`));
+    // A WARNING that did not fail the gate still has to be shown, or `--apply`
+    // would be quieter than the same command without it — the property
+    // `runArchiveApply` keeps its non-blocking output for.
+    if (blocking.length > 0)
+        lines.push(formatIssues(blocking), summarize(blocking));
+    return lines.join('\n');
+}
 export function formatCoverage(rows) {
     if (rows.length === 0)
         return chalk.dim('(the registry contains no requirements)');

package/dist/core/compiler.d.ts

@@ -0,0 +1,40 @@
+import type { Issue } from './types.js';
+/**
+ * The range the readers are written against.
+ *
+ * Stated here rather than read from the manifest at runtime, because the
+ * manifest is not on disk beside a bundled build and a diagnostic that cannot
+ * name the range is most of the diagnostic gone. `ATX-56` keeps the two honest:
+ * its `params` carry this string, and its scenario compares them with
+ * `package.json`, so the constant cannot drift from the dependency it describes.
+ */
+export declare const SUPPORTED_TYPESCRIPT = "^5.5.0 || ^6.0.0";
+/**
+ * The part of the compiler surface every AST reader in this project touches.
+ *
+ * Deliberately the two members that are reached *first* rather than an
+ * exhaustive list: `createSourceFile` and `ScriptTarget` are what
+ * `parser.ts`, `static-registry.ts` and `splice.ts` all open with, so a compiler
+ * that has them has the shape this check is about, and one that lacks either
+ * cannot get far enough for a longer list to matter.
+ */
+interface CompilerSurface {
+    version?: unknown;
+    createSourceFile?: unknown;
+    ScriptTarget?: unknown;
+}
+/**
+ * An ERROR when the resolved compiler has no AST API, or `undefined` when it
+ * does.
+ *
+ * Takes the compiler rather than reaching for the import directly, so the
+ * refusal can be attested against a stand-in: the condition only exists on a
+ * compiler this repository cannot install alongside the one it builds with, and
+ * a check nothing can make fail is the shape `never-red` exists to catch.
+ *
+ * No `reqId` and no `file`: the finding is about the toolchain, and every
+ * requirement and every file in the project is equally unreadable because of it.
+ */
+export declare function compilerIssue(compiler?: CompilerSurface): Issue | undefined;
+export {};
+//# sourceMappingURL=compiler.d.ts.map

package/dist/core/compiler.js

@@ -0,0 +1,64 @@
+// Whether the resolved TypeScript can be read from at all (design §5.1).
+//
+// Both registry readers and the spec parser walk the AST with the compiler API,
+// which makes `typescript` the one dependency this tool cannot survive the
+// absence of — and "absent" is not the shape it arrives in. `typescript@7` is
+// the native port: its package resolves, imports cleanly, and answers `version`
+// and `versionMajorMinor`, while `createSourceFile` and every `ts.isX` guard
+// moved behind `typescript/unstable/ast*`. So the members are `undefined` rather
+// than missing, and the first thing to touch one throws.
+//
+// Measured: `attest check` on it died with
+// `TypeError: Cannot read properties of undefined (reading 'Latest')` and a raw
+// stack — no issue code, no fix hint, and nothing saying which compiler it
+// wanted, on the crash path `[0.4.2]` had just finished sanitising.
+//
+// **The declared range excludes 7, and that is not the same as being safe from
+// it.** A caret is a request, not a constraint the adopter cannot override:
+// `pnpm.overrides` and Yarn `resolutions` both pin a transitive dependency
+// across a whole tree, and a repo standardising on one compiler is exactly the
+// repo that uses them — this one has an `overrides` block of its own. So the
+// reachable case is a deliberate, reasonable act by an adopter, answered with a
+// stack trace.
+//
+// What this cannot do is make Attest work on TypeScript 7. That is a migration
+// to `typescript/unstable/ast`, against an API whose own name says not to depend
+// on it yet. The honest answer for now is that the supported range has a ceiling
+// and says so.
+import ts from 'typescript';
+/**
+ * The range the readers are written against.
+ *
+ * Stated here rather than read from the manifest at runtime, because the
+ * manifest is not on disk beside a bundled build and a diagnostic that cannot
+ * name the range is most of the diagnostic gone. `ATX-56` keeps the two honest:
+ * its `params` carry this string, and its scenario compares them with
+ * `package.json`, so the constant cannot drift from the dependency it describes.
+ */
+export const SUPPORTED_TYPESCRIPT = '^5.5.0 || ^6.0.0';
+/**
+ * An ERROR when the resolved compiler has no AST API, or `undefined` when it
+ * does.
+ *
+ * Takes the compiler rather than reaching for the import directly, so the
+ * refusal can be attested against a stand-in: the condition only exists on a
+ * compiler this repository cannot install alongside the one it builds with, and
+ * a check nothing can make fail is the shape `never-red` exists to catch.
+ *
+ * No `reqId` and no `file`: the finding is about the toolchain, and every
+ * requirement and every file in the project is equally unreadable because of it.
+ */
+export function compilerIssue(compiler = ts) {
+    if (typeof compiler.createSourceFile === 'function' && compiler.ScriptTarget !== undefined) {
+        return undefined;
+    }
+    const version = typeof compiler.version === 'string' ? compiler.version : 'unknown';
+    return {
+        level: 'ERROR',
+        code: 'compiler-unsupported',
+        message: `The resolved TypeScript (${version}) does not expose the AST API Attest reads registries and specs with. ` +
+            `Attest supports ${SUPPORTED_TYPESCRIPT}. ` +
+            `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.`,
+    };
+}
+//# 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", "change-not-found", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "orphan-test", "possible-drift", "proposed-spec-unclaimed", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "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", "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 type IssueCode = (typeof ISSUE_CODES)[number];
 /**
  * The page explaining `code`, or `undefined` when nothing explains it.

package/dist/core/docs.js

@@ -22,7 +22,10 @@ export const ISSUE_CODES = [
     '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',
@@ -35,6 +38,7 @@ export const ISSUE_CODES = [
     'never-red',
     'orphan-test',
     'possible-drift',
+    'proposed-spec-name-taken',
     'proposed-spec-unclaimed',
     'rationale-placeholder',
     'registry-invalid',
@@ -43,6 +47,8 @@ export const ISSUE_CODES = [
     'rename-source-missing',
     'rename-target-exists',
     'rename-target-invalid',
+    'spec-in-change-dir',
+    'spec-load-failed',
     'stale-spec-doc',
     'tests-red',
     'unbound-param',

package/dist/core/gate.d.ts

@@ -56,6 +56,51 @@ export declare function declaredNotRunIssues(plan: AttestPlan, run: RunResult):
  * rather than asserting a cause.
  */
 export declare function unmergedIdIssues(run: RunResult, unmergedAddedIds: readonly string[]): Issue[];
+/**
+ * A spec file the runtime could not load, with no more specific cause known
+ * (design §5.4).
+ *
+ * The general case of `unmergedIdIssues`, and it exists because that one is a
+ * conjunction: it speaks only when the change also adds an id the registry on
+ * disk lacks. Every other way a spec file fails to import — a typo in a
+ * specifier, a module that throws at load, a dependency that is not installed —
+ * produced no finding naming the file at all. What the reader got instead was a
+ * `declared-not-run` per scenario in it, saying "skipped, or excluded by an
+ * `.only`?", which is a guess at a cause and the wrong one: it sends someone to
+ * audit a file for a `skip` that is not there, while the import error that
+ * explains everything is named nowhere in the report.
+ *
+ * `already` is the files a more specific diagnosis has claimed. One file gets
+ * one finding, and the specific one wins, because `added-id-unmerged` carries a
+ * fix and this carries only a fact. That is also why this could not simply be
+ * `declared-not-run` suppression, which is what it looked like from a distance:
+ * suppressing with nothing to put in its place trades a wrong message for
+ * silence, and a wrong message beats silence. The replacement had to come first.
+ *
+ * No `reqId`. A file that never loaded has no established relationship to any
+ * requirement — the ids it *would* have attested are readable from the static
+ * plan, but stating one here would name a requirement as implicated when the
+ * failure may have nothing to do with it, and a file is what did or did not
+ * load.
+ */
+export declare function specLoadFailedIssues(run: RunResult, already?: ReadonlySet<string>): Issue[];
+/**
+ * Everything a report says about scenarios that did not run: the files that
+ * failed to load, then the absences those files do not already explain.
+ *
+ * One function because two commands ask, and the answer has an *order* in it —
+ * the cause before the absences it caused, and never the absences on their own.
+ * `verify` and the gate each spelling that out is how the two came to differ in
+ * the first place: the gate learned to withdraw a misleading line and `verify`
+ * did not, so the same run produced a different diagnosis depending on which
+ * command asked. That is the clerical agreement `declaredNotRunIssues` was
+ * extracted to stop, arriving one level up.
+ *
+ * `specific` is any more precise diagnosis the caller has already emitted for
+ * these files — `added-id-unmerged` on the gate path, nothing on `verify`'s.
+ * Those files are left alone here, so one file carries one finding.
+ */
+export declare function notRunIssues(plan: AttestPlan, run: RunResult, specific?: readonly Issue[]): Issue[];
 /**
  * Never-red: a scenario attesting a requirement this change ADDs, whose first
  * observed run did not fail (design §6, mechanism 2).
@@ -85,8 +130,9 @@ export declare function neverRedIssues(plan: AttestPlan, addedIds: readonly stri
  *   2. Executable: all tests green.
  *   3. A spec file that failed to load while the change adds an id the registry
  *      on disk lacks — the reason, named before the absences it causes.
- *   4. Static coverage vs runtime coverage: every declared scenario actually
- *      ran (catches skip/only false coverage).
+ *   4. Everything else about what did not run, from `notRunIssues`: the load
+ *      failures step 3 did not claim, then static-vs-runtime coverage for the
+ *      files that did load (catches skip/only false coverage).
  *   5. Never-red: every scenario of an ADDED requirement failed on its first
  *      recorded run (design §6, mechanism 2).
  */

package/dist/core/gate.js

@@ -66,6 +66,71 @@ export function unmergedIdIssues(run, unmergedAddedIds) {
             `Merge the added requirement into the registry and run the gate again: applying a delta whose ADDED entry already exists with identical content is a no-op, so the change still documents the intent.`,
     }));
 }
+/**
+ * A spec file the runtime could not load, with no more specific cause known
+ * (design §5.4).
+ *
+ * The general case of `unmergedIdIssues`, and it exists because that one is a
+ * conjunction: it speaks only when the change also adds an id the registry on
+ * disk lacks. Every other way a spec file fails to import — a typo in a
+ * specifier, a module that throws at load, a dependency that is not installed —
+ * produced no finding naming the file at all. What the reader got instead was a
+ * `declared-not-run` per scenario in it, saying "skipped, or excluded by an
+ * `.only`?", which is a guess at a cause and the wrong one: it sends someone to
+ * audit a file for a `skip` that is not there, while the import error that
+ * explains everything is named nowhere in the report.
+ *
+ * `already` is the files a more specific diagnosis has claimed. One file gets
+ * one finding, and the specific one wins, because `added-id-unmerged` carries a
+ * fix and this carries only a fact. That is also why this could not simply be
+ * `declared-not-run` suppression, which is what it looked like from a distance:
+ * suppressing with nothing to put in its place trades a wrong message for
+ * silence, and a wrong message beats silence. The replacement had to come first.
+ *
+ * No `reqId`. A file that never loaded has no established relationship to any
+ * requirement — the ids it *would* have attested are readable from the static
+ * plan, but stating one here would name a requirement as implicated when the
+ * failure may have nothing to do with it, and a file is what did or did not
+ * load.
+ */
+export function specLoadFailedIssues(run, already = new Set()) {
+    return run.unloadedFiles
+        .filter((file) => !already.has(file))
+        .map((file) => ({
+        level: 'ERROR',
+        code: 'spec-load-failed',
+        file,
+        message: `${file} failed to load, so none of the scenarios in it ran. ` +
+            `The run output above carries the import error itself; this reports which file it stopped, because a file that never loaded reports no failures of its own. ` +
+            `Fix the import and run again — the scenarios in this file are neither passing nor failing until it loads.`,
+    }));
+}
+/**
+ * Everything a report says about scenarios that did not run: the files that
+ * failed to load, then the absences those files do not already explain.
+ *
+ * One function because two commands ask, and the answer has an *order* in it —
+ * the cause before the absences it caused, and never the absences on their own.
+ * `verify` and the gate each spelling that out is how the two came to differ in
+ * the first place: the gate learned to withdraw a misleading line and `verify`
+ * did not, so the same run produced a different diagnosis depending on which
+ * command asked. That is the clerical agreement `declaredNotRunIssues` was
+ * extracted to stop, arriving one level up.
+ *
+ * `specific` is any more precise diagnosis the caller has already emitted for
+ * these files — `added-id-unmerged` on the gate path, nothing on `verify`'s.
+ * Those files are left alone here, so one file carries one finding.
+ */
+export function notRunIssues(plan, run, specific = []) {
+    const named = new Set(specific.flatMap((i) => (i.file ? [i.file] : [])));
+    // Every unloaded file now carries a diagnosis: `specific` covers `named`, and
+    // the call below covers the rest by construction.
+    const diagnosed = new Set(run.unloadedFiles);
+    return [
+        ...specLoadFailedIssues(run, named),
+        ...declaredNotRunIssues(plan, run).filter((i) => !i.file || !diagnosed.has(i.file)),
+    ];
+}
 /**
  * Never-red: a scenario attesting a requirement this change ADDs, whose first
  * observed run did not fail (design §6, mechanism 2).
@@ -116,8 +181,9 @@ export function neverRedIssues(plan, addedIds, firstRun) {
  *   2. Executable: all tests green.
  *   3. A spec file that failed to load while the change adds an id the registry
  *      on disk lacks — the reason, named before the absences it causes.
- *   4. Static coverage vs runtime coverage: every declared scenario actually
- *      ran (catches skip/only false coverage).
+ *   4. Everything else about what did not run, from `notRunIssues`: the load
+ *      failures step 3 did not claim, then static-vs-runtime coverage for the
+ *      files that did load (catches skip/only false coverage).
  *   5. Never-red: every scenario of an ADDED requirement failed on its first
  *      recorded run (design §6, mechanism 2).
  */
@@ -133,19 +199,12 @@ export function evaluateGate({ registry, plan, run, addedIds, unmergedAddedIds,
             message: 'Some tests are failing; the change cannot be archived.',
         });
     }
-    // 3) A file that failed to load, named before the absences it produces.
+    // 3) and 4) in one push, because the order between them is not this
+    // function's to choose: the gate's own diagnosis — the one with a cause and a
+    // fix attached — and then everything `notRunIssues` says about the rest. The
+    // gate's only extra input is having that more specific diagnosis to offer.
     const unmerged = unmergedIdIssues(run, unmergedAddedIds ?? []);
-    blocking.push(...unmerged);
-    // 4) Declared-not-run: static coverage claimed, runtime never executed it.
-    //
-    // Scenarios in a file diagnosed just above are left out. Not because they
-    // ran — they could not have — but because "declared but never executed
-    // (skipped, or excluded by an .only?)" is one fact restated as a guess about
-    // a cause the line above has already established. Only when that line was
-    // emitted: with no diagnosis to replace it, a wrong message still beats
-    // silence, which is why `verify` keeps reporting them.
-    const diagnosed = new Set(unmerged.map((i) => i.file));
-    blocking.push(...declaredNotRunIssues(plan, run).filter((i) => !diagnosed.has(i.file)));
+    blocking.push(...unmerged, ...notRunIssues(plan, run, unmerged));
     // 5) Never-red: the added scenarios have to have discriminated once.
     if (addedIds && addedIds.length > 0) {
         blocking.push(...neverRedIssues(plan, addedIds, firstRun ?? {}));

package/dist/core/loader.js

@@ -35,6 +35,19 @@ import { block } from './terminal.js';
 export function sanitisedLogger(base = createLogger('error')) {
     return {
         ...base,
+        // `hasWarned` is the one member of `Logger` that is state rather than
+        // behaviour, and the spread above copies it *by value* — so the wrapper was
+        // born `false` and stayed `false` however many warnings went through it,
+        // while the base it delegates to flipped to `true`. Measured: after one
+        // `warn`, base `true` / wrapper `false`. An accessor pair makes the wrapper
+        // a view of the base rather than a snapshot of it, which is what every
+        // other member already is.
+        get hasWarned() {
+            return base.hasWarned;
+        },
+        set hasWarned(value) {
+            base.hasWarned = value;
+        },
         info: (msg, opts) => base.info(block(msg), opts),
         warn: (msg, opts) => base.warn(block(msg), opts),
         warnOnce: (msg, opts) => base.warnOnce(block(msg), opts),

package/dist/core/locate.d.ts

@@ -98,11 +98,40 @@ export declare function staticReader(): RegistryReader;
  * prefix a duplicate-prefix ERROR.
  *
  * Pass `files` to reuse a {@link scanProject} result instead of re-walking.
+ *
+ * `prefixOwners` comes back with the registry because the rule deciding it —
+ * first claim wins, in sorted file order — must have exactly one spelling. It is
+ * what `duplicate-prefix` is computed from here, and what tells `--apply` which
+ * file an ADDED id belongs in (design §7); a second walk arriving at its own
+ * answer would be a second rule the moment either was edited.
  */
 export declare function loadRegistry(root: string, reader: RegistryReader, files?: string[]): Promise<{
     registry: Registry;
     issues: Issue[];
+    prefixOwners: Record<string, string>;
+    /**
+     * Registry files that contributed **no ids**, relative to `root`.
+     *
+     * Not the same question as "did loading produce an ERROR": `duplicate-prefix`
+     * and `duplicate-requirement` are ERRORs raised *after* a successful read, and
+     * the ids they are about are present. Only a file whose outcome carried an
+     * issue instead of a registry is missing from the result, and a caller that
+     * 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.
+     */
+    unreadableFiles: string[];
 }>;
+/**
+ * The part of an id that names the space it lives in — `AUTH` of `AUTH-3`.
+ *
+ * The prefix is the only unit above the requirement (design §11) and two things
+ * now depend on agreeing about it: `duplicate-prefix`, and which file `--apply`
+ * writes an ADDED requirement into. An id with no dash is its own prefix, which
+ * cannot arise from `RequirementIdSchema` and is handled anyway because this
+ * also runs over ids a delta proposed.
+ */
+export declare function idPrefix(id: string): string;
 /**
  * Parse the given spec files into one merged plan (paths shown relative to
  * `displayRoot`). Files are read concurrently; the merge follows the input
@@ -111,10 +140,43 @@ export declare function loadRegistry(root: string, reader: RegistryReader, files
  * The paths are POSIX on every platform (see `paths.ts`): they are not only
  * displayed, they become the child run's `include` globs, where a Windows
  * separator would silently match nothing.
+ *
+ * Each source is parsed as it arrives rather than after all of them. The
+ * previous `Promise.all(files.map(readFile))` held every spec file in memory at
+ * once — measured at ~47 MiB on a synthetic tree of 6000 files — for input size
+ * that is not ours to choose, since `check` is the command this project tells
+ * people to run first on an untrusted fork MR. Parsing at the point of arrival
+ * makes the peak `PARSE_CONCURRENCY` sources instead of `files.length`, and the
+ * plan is the only thing that still grows with the tree.
+ *
+ * `findFiles` above is deliberately left unbounded: its fan-out is real, but the
+ * failure it invites is descriptor exhaustion, which no measurement on either
+ * 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>;
+/**
+ * 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).
+ *
+ * Two correct decisions compose into a blind spot. `changes` is in `SKIP_DIRS`,
+ * so `scanProject` cannot reach these; and the explicit include `attest archive`
+ * once applied to `changes/<name>/specs/` went away with `changeExcludeGlobs`
+ * when specs moved to their merged location. A spec left here therefore executes
+ * in no suite and no gate, and the only command that says anything is the gate,
+ * blaming coverage for a file it cannot see.
+ *
+ * Walks through `findFiles` rather than a second walker: `SKIP_DIRS` is consulted
+ * for *sub*directories only, so starting the walk at `changes` itself both
+ * reaches these files and keeps skipping `node_modules` beneath them.
+ *
+ * Both spellings are wrong here and both are returned. A `*.spec.ts` is the
+ * pre-move layout; a `*.proposed.spec.ts` is the right marker at the wrong path,
+ * which is the half-done migration and no more visible than the other.
+ */
+export declare function findChangeDirSpecs(root: string): Promise<string[]>;
 /** List the names of proposed changes under `root/changes`. */
 export declare function listChangeNames(root: string): Promise<string[]>;
 //# sourceMappingURL=locate.d.ts.map