@am_shork/attest 0.5.0 → 0.6.0

package/dist/core/pipeline.js

@@ -1,7 +1,7 @@
 // High-level operations composing the core layers (design §9). These are
 // tool-agnostic; the CLI is a thin shell that calls them and renders the result.
 import { createLoader } from './loader.js';
-import { evalReader, loadRegistry, listChangeNames, parseSpecs, scanProject, staticReader, } from './locate.js';
+import { evalReader, findChangeDirSpecs, loadRegistry, listChangeNames, parseSpecs, scanProject, staticReader, } from './locate.js';
 import { validateStructure, detectPotentialDrift, uncoveredIssues } from './validator.js';
 import { byCodeUnit } from './order.js';
 import { runAndCollect, BASE_EXCLUDE } from './runner.js';
@@ -13,6 +13,8 @@ import { renderMarkdown, staleIssue } from './render.js';
 import { mergeRedRecord, readRedRecord, redRecordPath, serialiseRedRecord, } from './red-record.js';
 import { DEFAULT_TARGET, resolveTargets } from './targets.js';
 import { writeAtomic } from './write.js';
+import { applyMerge, mergedSpecPath } from './merge.js';
+import { compilerIssue } from './compiler.js';
 import { mkdir, readFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { relativePath } from './paths.js';
@@ -34,6 +36,9 @@ async function readRegistry(root, options, files) {
 }
 /** Static structural check (design §9: `attest check`). */
 export async function runCheck(root, options = {}) {
+    const unusable = compilerIssue();
+    if (unusable)
+        return [unusable];
     const scan = await scanProject(root);
     const { registry, issues } = await readRegistry(root, options, scan.reqsFiles);
     const plan = await parseSpecs(scan.specFiles, root);
@@ -42,8 +47,74 @@ export async function runCheck(root, options = {}) {
         ...validateStructure(registry, plan),
         ...detectPotentialDrift(registry, plan, plan.paramRefs),
         ...(await unclaimedProposedSpecIssues(root, scan, options)),
+        ...(await changeDirSpecIssues(root)),
+        ...proposedNameTakenIssues(root, scan),
     ];
 }
+/**
+ * A proposed spec whose merged name is already taken (design §7).
+ *
+ * Merging a proposed spec is a rename in place, so the name it will take is
+ * decided the moment the file is created — and nothing stopped that name from
+ * being one a merged spec already holds. `isSpecFile` and `isProposedSpecFile`
+ * are deliberately disjoint, so `session.spec.ts` and `session.proposed.spec.ts`
+ * sit side by side without either predicate objecting; the collision only
+ * surfaces at the rename, where it would **destroy** the merged file.
+ *
+ * It is not a corner. A proposed spec is written beside the code it attests, so
+ * a change to a module that already has tests — the ordinary kind — reaches for
+ * exactly the colliding name.
+ *
+ * Reported here rather than only refused by `--apply` because the fix is a
+ * rename at authoring time and the cost of learning late is a merge stopped
+ * halfway. `--apply` checks it again regardless: this is the one failure mode of
+ * that command that would destroy work rather than halt, and a check living in a
+ * different command is not a guard.
+ */
+function proposedNameTakenIssues(root, scan) {
+    const taken = new Set(scan.specFiles);
+    return scan.proposedSpecFiles
+        .filter((p) => taken.has(mergedSpecPath(p)))
+        .map((p) => ({
+        level: 'ERROR',
+        code: 'proposed-spec-name-taken',
+        file: relativePath(root, p),
+        message: `${relativePath(root, p)} merges to ${relativePath(root, mergedSpecPath(p))}, which already exists — the rename would overwrite it. ` +
+            `Give the proposed spec a name whose merged form is free; several spec files may sit beside one module, but only one may hold each name.`,
+    }));
+}
+/**
+ * A spec still sitting under `changes/` (design §7).
+ *
+ * The companion to `unclaimedProposedSpecIssues`, and the reason both exist is
+ * the same: a spec that runs nowhere. That one covers a file at the right path
+ * no delta reaches; this one covers a file no *scan* reaches, which is the
+ * blind spot moving specs to their merged location opened underneath it.
+ *
+ * `check` rather than the gate, for the reason ATX-47 gives about its sibling
+ * and one more of its own: the gate does speak here, but it says
+ * `uncovered-requirement` — the added ids genuinely have no scenario the plan
+ * can see — and sends an author who has written those scenarios off to write
+ * them again or defer a finished requirement. `check` is both the command a
+ * pipeline runs first and, until this, the one that said nothing at all.
+ *
+ * No `reqId`: the finding is about a file and a path, and no requirement is
+ * implicated by it — the ids the file covers are exactly what cannot be read
+ * without walking it.
+ */
+async function changeDirSpecIssues(root) {
+    const files = await findChangeDirSpecs(root);
+    return files.map((abs) => {
+        const file = relativePath(root, abs);
+        return {
+            level: 'ERROR',
+            code: 'spec-in-change-dir',
+            file,
+            message: `${file} is a spec under changes/, which no command walks: it runs in neither the base suite nor any change's gate. ` +
+                `Move it beside the code it attests and name it *.proposed.spec.ts — that is where a change's specs live, and it is what lets merging one be a rename in place.`,
+        };
+    });
+}
 /**
  * A `*.proposed.spec.ts` no change's delta claims (design §7).
  *
@@ -96,6 +167,22 @@ async function unclaimedProposedSpecIssues(root, scan, options) {
     }
     return issues;
 }
+/**
+ * A verdict reached without running anything — the shape a refusal takes.
+ *
+ * `passed` is false rather than true: nothing ran, and a result claiming the
+ * suite passed because it never started is the silent-green this tool exists to
+ * refuse. The counts are zero for the same reason `Running 0 spec files` would
+ * be honest — they report what was looked at, and nothing was.
+ */
+function emptyVerify(issues) {
+    return {
+        issues,
+        passed: false,
+        ok: false,
+        counts: { requirements: 0, scenarios: 0, specFiles: 0, attesting: 0 },
+    };
+}
 /**
  * The spec files a run should execute: the ones that declare a `requirement()`.
  *
@@ -110,6 +197,9 @@ function attestingFiles(plan) {
 }
 /** Executable verification (design §9: `attest verify`). */
 export async function runVerify(root, options = {}) {
+    const unusable = compilerIssue();
+    if (unusable)
+        return emptyVerify([unusable]);
     const scan = await scanProject(root);
     const loader = await createLoader();
     let registry;
@@ -182,6 +272,9 @@ export async function runVerify(root, options = {}) {
  * shape it can take.
  */
 export async function runCover(root, options = {}) {
+    const unusable = compilerIssue();
+    if (unusable)
+        return { rows: [], issues: [unusable] };
     const scan = await scanProject(root);
     const { registry, issues: loadIssues } = await readRegistry(root, options, scan.reqsFiles);
     if (hasError(loadIssues))
@@ -209,6 +302,9 @@ export async function runCover(root, options = {}) {
  * every time a line moves in a test file.
  */
 export async function runRender(root, options = {}) {
+    const unusable = compilerIssue();
+    if (unusable)
+        return { markdown: '', issues: [unusable] };
     const { registry, issues } = await readRegistry(root, options);
     // A registry that failed to load yields a document that silently omits
     // requirements. An incomplete spec doc is worse than none, so refuse.
@@ -370,6 +466,24 @@ async function readDelta(root, changeName, options) {
         },
     };
 }
+/**
+ * One entry per claimed proposed spec, carrying the ids it declares a scenario
+ * for — what `--apply` needs to know which registry to repoint its import at.
+ *
+ * Built from the plan rather than by re-parsing, so the files `--apply` touches
+ * are exactly the files the gate ran.
+ */
+function claimedSpecsOf(root, plan) {
+    const byFile = new Map();
+    for (const sc of plan.scenarios) {
+        const set = byFile.get(sc.file) ?? new Set();
+        set.add(sc.reqId);
+        byFile.set(sc.file, set);
+    }
+    return [...byFile.entries()]
+        .sort(([a], [b]) => byCodeUnit(a, b))
+        .map(([file, ids]) => ({ file: join(root, file), reqIds: [...ids].sort(byCodeUnit) }));
+}
 /** Split a plan over the proposed specs into the part one delta claims. */
 function claimedByDelta(proposed, delta) {
     const claimed = new Set(claimedIds(delta));
@@ -406,6 +520,7 @@ async function changeMergedPlan(root, delta, scan) {
 }
 /** Per-change progress (design §9: `attest status <change>`). */
 export async function runStatus(root, changeName, options = {}) {
+    const unusable = compilerIssue();
     const nothing = (issues) => ({
         change: changeName,
         rows: [],
@@ -416,6 +531,8 @@ export async function runStatus(root, changeName, options = {}) {
     // gate checks it: under `--eval` the name reaches a module that is executed.
     if (!isSafeChangeName(changeName))
         return nothing([invalidChangeNameIssue(changeName)]);
+    if (unusable)
+        return nothing([unusable]);
     const read = await readDelta(root, changeName, options);
     if ('issue' in read)
         return nothing([read.issue]);
@@ -427,16 +544,53 @@ export async function runStatus(root, changeName, options = {}) {
 }
 /** Archive gate for a change (design §8, §9: `attest archive <change>`). */
 export async function runArchive(root, changeName, options = {}) {
+    return (await archiveRun(root, changeName, options)).issues;
+}
+/**
+ * The gate, and — only if it passes — the merge it approved
+ * (`attest archive <change> --apply`).
+ *
+ * The gate runs first and unconditionally, in this same call. A merge acting on
+ * an earlier run's verdict would let an unfinished change be filed as done, and
+ * "done" having a hard definition is the whole claim of the tool; so a red gate
+ * writes nothing, and there is no flag that skips it.
+ */
+export async function runArchiveApply(root, changeName, options = {}) {
+    const { issues, merge } = await archiveRun(root, changeName, options);
+    if (issues.some((i) => i.level === 'ERROR') || !merge)
+        return { issues, written: [] };
+    const result = await applyMerge({ root, changeName, ...merge });
+    // The gate's non-blocking output is kept: a WARNING the gate raised is still
+    // true after the merge, and dropping it here would make `--apply` quieter than
+    // the same command without it.
+    return { issues: [...issues, ...result.issues], written: result.written };
+}
+/**
+ * The gate, plus what finishing the merge would need.
+ *
+ * One function rather than a gate and a separate `--apply` path, because the
+ * merge must act on **this** run's verdict. A second traversal could reach a
+ * different answer than the one just printed — and a command able to file a
+ * change as done against a stale verdict removes the hard definition of "done"
+ * that is this tool's whole claim.
+ *
+ * `merge` is absent exactly when there is nothing to act on: a rejected name, an
+ * unreadable delta, or a registry that would not load.
+ */
+async function archiveRun(root, changeName, options = {}) {
     // Checked before any loader starts: nothing should be resolved, let alone
     // evaluated, on behalf of a name we have already rejected.
     if (!isSafeChangeName(changeName))
-        return [invalidChangeNameIssue(changeName)];
+        return { issues: [invalidChangeNameIssue(changeName)] };
+    const unusable = compilerIssue();
+    if (unusable)
+        return { issues: [unusable] };
     const scan = await scanProject(root);
     const loader = await createLoader();
     try {
-        const { registry: base, issues } = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
+        const { registry: base, issues, prefixOwners } = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
         if (issues.some((i) => i.level === 'ERROR'))
-            return issues;
+            return { issues };
         const deltaPath = changeDeltaPath(root, changeName);
         let delta;
         try {
@@ -453,11 +607,11 @@ export async function runArchive(root, changeName, options = {}) {
             delta = mod.default;
         }
         catch (err) {
-            return [changeNotFoundIssue(root, deltaPath, changeName, err)];
+            return { issues: [changeNotFoundIssue(root, deltaPath, changeName, err)] };
         }
         const applied = applyDelta(base, delta);
         if (applied.issues.length > 0)
-            return applied.issues;
+            return { issues: applied.issues };
         // Static plan = merged base suite + this change's specs (design §8), by the
         // same function `status` reports against — a progress report computed over a
         // different spec set than the gate uses would be a report about nothing.
@@ -498,14 +652,27 @@ export async function runArchive(root, changeName, options = {}) {
         // Against `base`, not `applied`: the child run imported the registry from
         // disk, so what matters is what that file has, not what the gate computed.
         const unmergedAddedIds = added.filter((id) => !Object.hasOwn(base, id));
-        return evaluateGate({
-            registry: applied.registry,
-            plan,
-            run,
-            addedIds: added,
-            unmergedAddedIds,
-            firstRun,
-        });
+        return {
+            issues: evaluateGate({
+                registry: applied.registry,
+                plan,
+                run,
+                addedIds: added,
+                unmergedAddedIds,
+                firstRun,
+            }),
+            merge: {
+                delta,
+                base,
+                applied: applied.registry,
+                prefixOwners,
+                // The plan's proposed files, not every proposed file on disk: `--apply`
+                // renames what *this* change claims, and a sibling proposal's spec is
+                // not this change's to move.
+                claimedSpecs: claimedSpecsOf(root, claimedByDelta(await parseSpecs(scan.proposedSpecFiles, root), delta)),
+                mergedSpecs: scan.specFiles,
+            },
+        };
     }
     finally {
         await loader.close();

package/dist/core/skill.js

@@ -163,6 +163,18 @@ Writing it at its merged location is what makes merging it a rename. Its relativ
 imports resolve now exactly as they will afterwards, so \`../fog\` never becomes
 \`../../../lib/game/fog\` and back again.
 
+Two things to get right when you create the file:
+
+- **Do not put it under \`changes/\`.** Nothing walks that directory, so a spec
+  left there executes in no suite and no gate — \`spec-in-change-dir\` from
+  \`attest check\`. The change folder holds \`proposal.md\`,
+  \`requirements.delta.ts\` and \`first-run.json\`, and nothing else.
+- **Pick a name whose merged form is free.** Merging renames
+  \`fog.proposed.spec.ts\` to \`fog.spec.ts\`, so if that module already has a
+  \`fog.spec.ts\` the rename would overwrite it — \`proposed-spec-name-taken\`.
+  Name it \`fog.2fa.proposed.spec.ts\` instead. Several spec files may sit beside
+  one module; Attest attributes each by the ids it declares, not by its path.
+
 \`\`\`ts
 // changes/add-2fa/requirements.delta.ts
 import { delta } from '@am_shork/attest/define';
@@ -278,6 +290,9 @@ once. Branch on \`issues[].code\`, never on \`message\`:
 | \`registry-not-static\` | a registry file is not a literal the engine can read |
 | \`add-conflict\` | the delta adds an id that already exists with different content |
 | \`change-not-found\` | no \`requirements.delta.ts\` for that name |
+| \`proposed-spec-name-taken\` | a proposed spec's merged name is already held by another spec |
+| \`apply-unsupported-delta\` | \`--apply\` writes back ADDED only, and this delta carries more |
+| \`apply-no-prefix-owner\` | no registry file owns the prefix of an id this change adds |
 
 ### Four things you must not do
 
@@ -309,15 +324,36 @@ failure this framework exists to make visible:
 
 Then, and not before:
 
-1. Merge \`requirements.delta.ts\` into the main registry, and rename each of the
-   change's \`*.proposed.spec.ts\` to \`*.spec.ts\` **in place**. Nothing moves and
-   no import changes; if you find yourself editing a specifier, the spec was not
-   written at its merged location and stage 1 was the place to fix that.
-2. Move \`changes/<name>/\` to \`archive/<date>-<name>/\`.
-3. If the project commits a rendering, regenerate it: \`attest render --out
-   <file>\`. A committed document that no longer matches the registry is a
-   \`stale-spec-doc\` ERROR.
-4. Run \`attest verify\` on the merged result and report it.
+\`\`\`
+attest archive <name> --apply
+\`\`\`
+
+That finishes the merge the verdict just approved: it splices the change's ADDED
+requirements into the registry file owning their id prefix, repoints each proposed
+spec's import of \`requirements.delta.ts\` at that registry, renames the specs in
+place, and moves \`changes/<name>/\` to \`archive/<date>-<name>/\`. It re-runs the
+gate first and writes nothing if that fails, and it prints every path it touched.
+If it stops partway, run it again — each step is derived from the tree as it is,
+so a second run finishes the job rather than repeating it.
+
+Two things it does not do, and both are still yours:
+
+1. **Regenerate a committed rendering.** Nothing records where yours lives, so run
+   \`attest render --out <file>\` afterwards. A document that no longer matches the
+   registry is a \`stale-spec-doc\` ERROR.
+2. **Run the merged suite.** \`attest verify\`, on the result, reported.
+
+**It writes back ADDED only.** A delta also carrying RENAMED, REMOVED or MODIFIED
+is refused whole as \`apply-unsupported-delta\`, with nothing written — the gate
+still checked all four, so nothing about the change is unverified, but the rest is
+merged by hand.
+
+Merging by hand, when it refuses: splice the delta's entries into the registry
+file that owns their prefix; then for each \`*.proposed.spec.ts\`, **repoint its
+import of \`requirements.delta.ts\` at that registry** and rename it to
+\`*.spec.ts\` in place. That import is the one specifier a merge changes, and it
+changes because the delta moves to \`archive/\` — the spec file itself does not
+move, so nothing else about it does either. Then move the change folder.
 
 ## The commands
 
@@ -327,7 +363,7 @@ Then, and not before:
 | \`attest verify\` | runs the suite, then reports coverage and drift. |
 | \`attest cover\` | which requirements lack a scenario. |
 | \`attest render\` | the registry as Markdown for human readers; \`--check\` gates a committed copy. |
-| \`attest archive <change>\` | the completion gate for a proposed change. |
+| \`attest archive <change>\` | the completion gate for a proposed change; \`--apply\` also performs the merge it approves. |
 | \`attest status <change>\` | what that gate still wants, without running the suite. |
 
 \`verify\` starts the child run **isolated** — it does not read \`vitest.config.ts\`,

package/dist/core/splice.d.ts

@@ -0,0 +1,52 @@
+import type { Registry, Requirement } from './types.js';
+/**
+ * One registry entry, at `indent`, with no trailing comma.
+ *
+ * The separator is the caller's because only the caller knows what it is
+ * inserting between: continuing a list needs a comma before, opening an empty
+ * body needs one after, and putting that decision here would mean this function
+ * had to be told which case it was in anyway.
+ *
+ * `params` and `outOfScope` are omitted when empty rather than written as `{}`
+ * and `[]`. The schema defaults both, so the two spellings mean the same thing,
+ * and the shorter one is what a person writing this entry by hand would have
+ * produced — which is the standard for a file `--apply` is merging into rather
+ * than generating.
+ */
+export declare function requirementSource(id: string, req: Requirement, indent: string): string;
+/**
+ * `source` with `additions` inserted into its registry literal.
+ *
+ * `undefined` when the file holds no literal this can be inserted into — the
+ * same condition `readRegistrySource` reports, and one the caller has already
+ * checked, so it is a refusal to guess rather than a diagnosis.
+ *
+ * Ids are inserted in code-unit order for the reason they are emitted in it:
+ * the same delta must produce the same file twice.
+ */
+export declare function spliceRequirements(file: string, source: string, additions: Registry): string | undefined;
+/**
+ * `source` with every import of `from` repointed at `to`.
+ *
+ * The second edit `--apply` makes to a file it did not write, and the one the
+ * design record missed. Merging a proposed spec was described as a rename in
+ * place, which is true of its *location*: the file already sits where it lands,
+ * so no relative specifier moves. But a stage-1 scenario reads its proposed
+ * params out of the change's delta (ATX-48, and the whole reason a delta reads
+ * as the registry it proposes), and the delta is what step 3 moves into
+ * `archive/`. Renaming without this leaves a merged spec importing a path that
+ * no longer exists — a suite that loads nothing, reported as `declared-not-run`
+ * against scenarios that are perfectly good.
+ *
+ * The expression around the import needs nothing done to it: `reqs['AUTH-7']
+ * .params.x` reads the same on both sides, which is exactly what ATX-48 bought.
+ * So this replaces one string literal and touches nothing else — the same
+ * discipline as the splice, for the same reason.
+ *
+ * The extension is taken from the specifier being replaced rather than chosen
+ * here. Whether a project writes `./x.reqs.js` or `./x.reqs.ts` is a property of
+ * its module resolution, uniform across the project, and already answered by the
+ * specifier sitting in front of us.
+ */
+export declare function repointImport(file: string, source: string, from: string, to: string): string;
+//# sourceMappingURL=splice.d.ts.map

package/dist/core/splice.js

@@ -0,0 +1,189 @@
+// Writing a requirement into a registry file as text (design §7).
+//
+// This is the half of `--apply` the `AGENTS.md` rejection was about. That
+// proposal was refused because "each of its failure modes is destructive on a
+// file the user cannot regenerate", and the argument for why merging a delta is
+// different has one load-bearing clause: the result of a splice is checkable by
+// re-reading it. That clause only holds if the splice is a **pure insertion**.
+//
+// So nothing here renders a registry. Rendering one out of a `Registry` object
+// would be far easier and would silently drop every comment, every blank line
+// and every layout choice in a hand-written file — destroying exactly what
+// cannot be regenerated, while passing a re-read with flying colours because the
+// *values* all survived. Instead `registryInsertionPoint` hands back an offset,
+// and the only edit made to the file is text inserted at it. Every other byte is
+// the byte that was already there, which is a property a test can state.
+//
+// The generated text is therefore the one thing here that has to be right on its
+// own, and it is generated conservatively: strings are escaped rather than
+// interpolated, params are emitted in code-unit key order so the same delta
+// produces the same bytes twice, and anything the schema does not permit cannot
+// reach this file because the gate validated the delta before `--apply` ran.
+import ts from 'typescript';
+import { dirname, relative, resolve } from 'node:path';
+import { registryInsertionPoint } from './static-registry.js';
+import { toPosixPath } from './paths.js';
+import { byCodeUnit } from './order.js';
+/**
+ * A TypeScript single-quoted string literal holding exactly `value`.
+ *
+ * Hand-escaped rather than `JSON.stringify`, for one reason that is not style:
+ * the registries this writes into are single-quoted throughout, and a merged
+ * entry that arrives double-quoted is a diff hunk about quotation marks in the
+ * middle of a merge the reviewer is trying to read. Control characters go out as
+ * `\uXXXX` rather than raw, so a statement someone pasted a newline into cannot
+ * produce a file that no longer parses.
+ */
+function tsString(value) {
+    let out = "'";
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (ch === '\\')
+            out += '\\\\';
+        else if (ch === "'")
+            out += "\\'";
+        else if (ch === '\n')
+            out += '\\n';
+        else if (ch === '\r')
+            out += '\\r';
+        else if (ch === '\t')
+            out += '\\t';
+        else if (code < 0x20 || code === 0x7f)
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        else
+            out += ch;
+    }
+    return `${out}'`;
+}
+/** A param key, bare when it is a plain identifier and quoted when it is not. */
+function keySource(key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : tsString(key);
+}
+function paramSource(value) {
+    if (Array.isArray(value))
+        return `[${value.map((v) => paramSource(v)).join(', ')}]`;
+    return typeof value === 'string' ? tsString(value) : String(value);
+}
+/**
+ * One registry entry, at `indent`, with no trailing comma.
+ *
+ * The separator is the caller's because only the caller knows what it is
+ * inserting between: continuing a list needs a comma before, opening an empty
+ * body needs one after, and putting that decision here would mean this function
+ * had to be told which case it was in anyway.
+ *
+ * `params` and `outOfScope` are omitted when empty rather than written as `{}`
+ * and `[]`. The schema defaults both, so the two spellings mean the same thing,
+ * and the shorter one is what a person writing this entry by hand would have
+ * produced — which is the standard for a file `--apply` is merging into rather
+ * than generating.
+ */
+export function requirementSource(id, req, indent) {
+    const inner = `${indent}  `;
+    const lines = [
+        `${indent}${tsString(id)}: {`,
+        `${inner}statement: ${tsString(req.statement)},`,
+        `${inner}rationale: ${tsString(req.rationale)},`,
+    ];
+    // Code-unit key order, so one delta applied twice writes the same bytes — the
+    // property `--apply`'s re-runnability rests on, and the reason `apply.ts`
+    // sorts the same way when it canonicalises for `add-conflict`.
+    const params = Object.entries(req.params).sort(([a], [b]) => byCodeUnit(a, b));
+    if (params.length > 0) {
+        const body = params.map(([k, v]) => `${keySource(k)}: ${paramSource(v)}`).join(', ');
+        lines.push(`${inner}params: { ${body} },`);
+    }
+    if (req.outOfScope.length > 0) {
+        lines.push(`${inner}outOfScope: [${req.outOfScope.map((s) => tsString(s)).join(', ')}],`);
+    }
+    lines.push(`${indent}}`);
+    return lines.join('\n');
+}
+/**
+ * `source` with `additions` inserted into its registry literal.
+ *
+ * `undefined` when the file holds no literal this can be inserted into — the
+ * same condition `readRegistrySource` reports, and one the caller has already
+ * checked, so it is a refusal to guess rather than a diagnosis.
+ *
+ * Ids are inserted in code-unit order for the reason they are emitted in it:
+ * the same delta must produce the same file twice.
+ */
+export function spliceRequirements(file, source, additions) {
+    const ids = Object.keys(additions).sort(byCodeUnit);
+    if (ids.length === 0)
+        return source;
+    const point = registryInsertionPoint(file, source);
+    if (!point)
+        return undefined;
+    const entries = ids
+        .map((id) => requirementSource(id, additions[id], point.indent))
+        .join(',\n');
+    const text = point.leadingComma ? `,\n${entries}` : `\n${entries},\n`;
+    return source.slice(0, point.offset) + text + source.slice(point.offset);
+}
+/**
+ * `source` with every import of `from` repointed at `to`.
+ *
+ * The second edit `--apply` makes to a file it did not write, and the one the
+ * design record missed. Merging a proposed spec was described as a rename in
+ * place, which is true of its *location*: the file already sits where it lands,
+ * so no relative specifier moves. But a stage-1 scenario reads its proposed
+ * params out of the change's delta (ATX-48, and the whole reason a delta reads
+ * as the registry it proposes), and the delta is what step 3 moves into
+ * `archive/`. Renaming without this leaves a merged spec importing a path that
+ * no longer exists — a suite that loads nothing, reported as `declared-not-run`
+ * against scenarios that are perfectly good.
+ *
+ * The expression around the import needs nothing done to it: `reqs['AUTH-7']
+ * .params.x` reads the same on both sides, which is exactly what ATX-48 bought.
+ * So this replaces one string literal and touches nothing else — the same
+ * discipline as the splice, for the same reason.
+ *
+ * The extension is taken from the specifier being replaced rather than chosen
+ * here. Whether a project writes `./x.reqs.js` or `./x.reqs.ts` is a property of
+ * its module resolution, uniform across the project, and already answered by the
+ * specifier sitting in front of us.
+ */
+export function repointImport(file, source, from, to) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    const dir = dirname(file);
+    const edits = [];
+    for (const statement of sf.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        const spec = statement.moduleSpecifier;
+        if (!ts.isStringLiteral(spec))
+            continue;
+        if (!resolvesTo(dir, spec.text, from))
+            continue;
+        const ext = spec.text.endsWith('.js') ? '.js' : spec.text.endsWith('.ts') ? '.ts' : '';
+        let target = toPosixPath(relative(dir, to));
+        if (ext)
+            target = target.replace(/\.[^./]+$/, ext);
+        // A bare `x.reqs.js` is a package specifier, not a sibling file.
+        if (!target.startsWith('.'))
+            target = `./${target}`;
+        // Inside the quotes: the file's own quote style is left exactly as it was.
+        edits.push({ start: spec.getStart(sf) + 1, end: spec.getEnd() - 1, text: target });
+    }
+    let out = source;
+    for (const edit of edits.reverse()) {
+        out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
+    }
+    return out;
+}
+/**
+ * Whether `specifier`, written in a file under `dir`, names `target`.
+ *
+ * The `.js`-for-`.ts` spelling is accepted because NodeNext resolution requires
+ * it, and a project using it writes every specifier that way — including the one
+ * this is looking for.
+ */
+function resolvesTo(dir, specifier, target) {
+    if (!specifier.startsWith('.'))
+        return false;
+    const resolved = resolve(dir, specifier);
+    return resolved === target || resolved.replace(/\.js$/, '.ts') === target;
+}
+//# sourceMappingURL=splice.js.map

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

@@ -39,4 +39,34 @@ export type DeltaReadResult = {
  * (write the value inline, or `--eval`) is the same sentence either way.
  */
 export declare function readDeltaSource(file: string, source: string): DeltaReadResult;
+/**
+ * Where a new entry may be written into a registry file's literal, as an offset
+ * into its source (design §7).
+ *
+ * The insertion point rather than a rewritten file, because `--apply` must not
+ * regenerate a `*.reqs.ts`. Every registry this tool merges into is hand-written
+ * and hand-commented, and rendering one back out of a `Registry` object would
+ * silently drop every comment and every choice of layout in it — the
+ * "destructive on a file the user cannot regenerate" shape the `AGENTS.md`
+ * proposal was rejected for. An offset lets the splice be a pure insertion: every
+ * other byte of the file is the byte that was there before, which is a property
+ * that can be stated and tested rather than hoped for.
+ *
+ * Lives here because this is the module that already knows how to find the
+ * literal, and the one place `typescript` is imported for that job. A second
+ * walker would be a second answer to "where does this registry's body end".
+ *
+ * `undefined` when the file is not a registry this tool can read — the same
+ * condition `readRegistrySource` reports as `registry-not-static` or
+ * `registry-no-default`, and the caller has already run that check.
+ */
+export interface RegistryInsertion {
+    /** Offset to insert at. Everything before and after it is preserved. */
+    offset: number;
+    /** The indentation the file's existing entries use, reproduced for new ones. */
+    indent: string;
+    /** Whether the insertion has to open with a `,` — false only for an empty registry. */
+    leadingComma: boolean;
+}
+export declare function registryInsertionPoint(file: string, source: string): RegistryInsertion | undefined;
 //# sourceMappingURL=static-registry.d.ts.map