@am_shork/attest 0.5.0 → 0.7.0

package/dist/core/locate.js

@@ -196,6 +196,12 @@ export function staticReader() {
  * 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 async function loadRegistry(root, reader, files) {
     const paths = files ?? (await scanProject(root)).reqsFiles;
@@ -204,18 +210,23 @@ export async function loadRegistry(root, reader, files) {
     const loaded = await Promise.all(paths.map(async (file) => ({ file, outcome: await reader.read(file) })));
     const registry = {};
     const issues = [];
+    const unreadableFiles = [];
     // 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
     // themselves can stay distinct forever while the space they share has two
     // owners. First seen in sorted file order, so which file is called the owner
     // does not depend on I/O timing.
+    // Absolute paths, so a caller that has to *write* to the owning file does not
+    // have to turn a display path back into one; the messages below relativise at
+    // the point they are built, which is where the reader's path belongs anyway.
     const prefixOwner = new Map();
     for (const entry of loaded) {
         const display = relativePath(root, entry.file);
         const { outcome } = entry;
         if ('issue' in outcome) {
             issues.push({ ...outcome.issue, file: display });
+            unreadableFiles.push(display);
             continue;
         }
         // One issue per colliding prefix rather than per requirement: the fact is
@@ -223,13 +234,12 @@ export async function loadRegistry(root, reader, files) {
         // prefix would otherwise report the same sentence forty times.
         const reported = new Set();
         for (const [id, req] of Object.entries(outcome.registry)) {
-            const dash = id.indexOf('-');
-            const prefix = dash === -1 ? id : id.slice(0, dash);
+            const prefix = idPrefix(id);
             const owner = prefixOwner.get(prefix);
             if (owner === undefined) {
-                prefixOwner.set(prefix, display);
+                prefixOwner.set(prefix, entry.file);
             }
-            else if (owner !== display && !reported.has(prefix)) {
+            else if (owner !== entry.file && !reported.has(prefix)) {
                 reported.add(prefix);
                 // No `reqId`: this is about two files, not about any one of the
                 // requirements that happen to reveal it.
@@ -237,7 +247,7 @@ export async function loadRegistry(root, reader, files) {
                     level: 'ERROR',
                     code: 'duplicate-prefix',
                     file: display,
-                    message: `Id prefix "${prefix}-" is already declared by "${owner}". Give each registry file a prefix of its own.`,
+                    message: `Id prefix "${prefix}-" is already declared by "${relativePath(root, owner)}". Give each registry file a prefix of its own.`,
                 });
             }
             if (Object.hasOwn(registry, id)) {
@@ -254,8 +264,27 @@ export async function loadRegistry(root, reader, files) {
             }
         }
     }
-    return { registry, issues };
+    return { registry, issues, prefixOwners: Object.fromEntries(prefixOwner), unreadableFiles };
+}
+/**
+ * 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 function idPrefix(id) {
+    const dash = id.indexOf('-');
+    return dash === -1 ? id : id.slice(0, dash);
 }
+/**
+ * How many spec files are read at once. High enough that the walk stays I/O
+ * bound on any real project, low enough that the number of sources alive is a
+ * constant rather than the size of the input.
+ */
+const PARSE_CONCURRENCY = 32;
 /**
  * Parse the given spec files into one merged plan (paths shown relative to
  * `displayRoot`). Files are read concurrently; the merge follows the input
@@ -264,14 +293,37 @@ export async function loadRegistry(root, reader, 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 async function parseSpecs(files, displayRoot) {
-    const sources = await Promise.all(files.map((file) => readFile(file, 'utf8')));
+    // Indexed rather than appended, so the merge below follows the input order
+    // whatever order the reads finish in.
+    const parsed = new Array(files.length);
+    let next = 0;
+    const worker = async () => {
+        for (let i = next++; i < files.length; i = next++) {
+            const file = files[i];
+            const source = await readFile(file, 'utf8');
+            parsed[i] = parseSpecFile(relativePath(displayRoot, file), source);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(PARSE_CONCURRENCY, files.length) }, worker));
     const plan = { scenarios: [], paramRefs: [] };
-    for (const [i, file] of files.entries()) {
-        const parsed = parseSpecFile(relativePath(displayRoot, file), sources[i]);
-        plan.scenarios.push(...parsed.scenarios);
-        plan.paramRefs.push(...parsed.paramRefs);
+    for (const one of parsed) {
+        plan.scenarios.push(...one.scenarios);
+        plan.paramRefs.push(...one.paramRefs);
     }
     return plan;
 }
@@ -279,6 +331,37 @@ export async function parseSpecs(files, displayRoot) {
 export async function parseAllSpecFiles(root) {
     return parseSpecs(await findFiles(root, isSpecFile), root);
 }
+/**
+ * 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 async function findChangeDirSpecs(root) {
+    try {
+        return await findFiles(join(root, 'changes'), (n) => isSpecFile(n) || isProposedSpecFile(n));
+    }
+    catch {
+        // No `changes/` at all — the ordinary case for a project with nothing in
+        // flight, and not a finding. Swallowed the same way `listChangeNames`
+        // swallows it, so the two cannot disagree about what a missing directory
+        // means.
+        return [];
+    }
+}
 /** List the names of proposed changes under `root/changes`. */
 export async function listChangeNames(root) {
     try {

package/dist/core/merge.d.ts

@@ -0,0 +1,54 @@
+import type { RegistryDelta } from './registry.js';
+import type { Issue, Registry } from './types.js';
+/** `x.proposed.spec.ts` -> `x.spec.ts`, in place. */
+export declare function mergedSpecPath(proposed: string): string;
+export interface MergeInputs {
+    root: string;
+    changeName: string;
+    delta: RegistryDelta;
+    /** The registry on disk, as the gate read it. */
+    base: Registry;
+    /**
+     * The registry the gate reached by applying the delta — the source of what
+     * gets written.
+     *
+     * Not `delta.added`, and the difference is the point: the delta holds the
+     * *authoring* shape, where `params` and `outOfScope` may be absent, while this
+     * is the schema-parsed result the gate actually gave its verdict on. Splicing
+     * from here means the bytes written to the registry are exactly the
+     * requirement that was proved green, rather than a second normalisation of it.
+     */
+    applied: Registry;
+    /** Prefix -> the absolute registry file that owns it (see `loadRegistry`). */
+    prefixOwners: Record<string, string>;
+    /**
+     * The proposed specs this change claims, absolute, each with the requirement
+     * ids it declares a scenario for.
+     *
+     * The ids are here because the rename is not the whole of merging a spec: one
+     * import has to be repointed from the change's delta at the registry, and
+     * *which* registry is decided by the prefix of the ids that spec attests.
+     */
+    claimedSpecs: {
+        file: string;
+        reqIds: string[];
+    }[];
+    /** Every merged spec on disk, absolute — what a rename could collide with. */
+    mergedSpecs: string[];
+}
+export interface MergeResult {
+    /** Refusals. Non-empty means **nothing was written**. */
+    issues: Issue[];
+    /** Paths touched, relative to root, in the order they were touched. */
+    written: string[];
+}
+/**
+ * Perform the merge, or refuse it whole.
+ *
+ * The caller must have run the gate in the same invocation and found it green;
+ * a merge that files a change as done without re-checking is the one thing this
+ * tool must not ship, because "done" having a hard definition is the whole
+ * claim.
+ */
+export declare function applyMerge(input: MergeInputs): Promise<MergeResult>;
+//# sourceMappingURL=merge.d.ts.map

package/dist/core/merge.js

@@ -0,0 +1,257 @@
+// Finishing the merge the gate approved (design §7, §8).
+//
+// `attest archive <change>` proves a delta is green, covered and drift-free, and
+// until now a human then transcribed it by hand with nothing checking the
+// transcription. This is that step, and the whole of why it is allowed to exist
+// where the `AGENTS.md` merge tool was not: the registry is a literal Attest
+// defines, so the result of an edit is checkable by re-reading it, and the edit
+// itself is a pure insertion (`splice.ts`).
+//
+// **It is re-runnable, not atomic.** No primitive spans one edit, N renames and
+// a directory move, and a scratch copy of the project root would have to be
+// swapped back through the same non-atomic set again. So instead every step is
+// derived from the tree as it currently is rather than reconciled against a
+// fixed list: a requirement already in the registry is not spliced, a spec
+// already renamed is not in `claimedSpecs`, and a change folder already moved is
+// not there to move. Running the command again after a failure finishes it.
+//
+// **The step order is a correctness constraint, pinned at both ends.**
+//
+// - *The splice goes first.* A renamed spec joins the base plan **unfiltered**,
+//   so its scenarios are read against the merged registry. Rename before splice
+//   and every one of them is an `orphan-test` naming an id the registry does not
+//   have yet — a tree `check` calls broken for a reason that is not the real one.
+// - *The folder move goes last.* `changes/<name>/` is the **input**. Move it
+//   first and a crash leaves a half-merged registry with no delta left to
+//   re-derive from, which is the one genuinely unrecoverable state in the design.
+//
+// The two steps between them are free. Nothing enforces this ordering but the
+// code below and ATX-53, which is why it is stated here as well: it is invisible
+// at runtime on the happy path, and a later reordering would look harmless.
+import { mkdir, readFile, rename, stat } from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
+import { repointImport, spliceRequirements } from './splice.js';
+import { writeAtomic } from './write.js';
+import { idPrefix } from './locate.js';
+import { addedIds } from './apply.js';
+import { byCodeUnit } from './order.js';
+import { relativePath } from './paths.js';
+/** `x.proposed.spec.ts` -> `x.spec.ts`, in place. */
+export function mergedSpecPath(proposed) {
+    return join(dirname(proposed), basename(proposed).replace(/\.proposed\.spec\.ts$/, '.spec.ts'));
+}
+/**
+ * Why this merge cannot be performed mechanically, if it cannot.
+ *
+ * Every one of these is a refusal of the whole operation rather than a partial
+ * apply: the point of the command is that the gate's verdict now covers the step
+ * acting on it, and a merge that did the half it understood would put the file
+ * into a state no verdict describes.
+ */
+async function refusals(input, stamp) {
+    const issues = [];
+    const { delta, root, changeName } = input;
+    const archive = archivePath(input, stamp);
+    // 0) The destination already exists. Checked here, before anything is
+    // written, rather than at the move it is about: every refusal in this function
+    // leaves the tree untouched, and one that fired after two steps had landed
+    // would make "refused whole" a claim with an exception in it — which is the
+    // kind of claim nobody can rely on.
+    if (await exists(archive)) {
+        issues.push({
+            level: 'ERROR',
+            code: 'apply-unsupported-delta',
+            file: relativePath(root, archive),
+            message: `${relativePath(root, archive)} already exists, so this change cannot be archived there. ` +
+                `Move or remove that directory, then run this command again.`,
+        });
+    }
+    // 1) Operations this does not perform. The gate applies all four in memory to
+    // reach its verdict; only writing them back is limited to ADDED, because
+    // REMOVED cannot say which comments belonged to the entry it deletes and
+    // MODIFIED is a formatting-preserving edit inside an existing literal. Both
+    // are the "destructive on a file the user cannot regenerate" shape.
+    const unsupported = [
+        delta.renamed?.length ? 'renamed' : '',
+        delta.removed?.length ? 'removed' : '',
+        Object.keys(delta.modified ?? {}).length ? 'modified' : '',
+    ].filter(Boolean);
+    if (unsupported.length > 0) {
+        issues.push({
+            level: 'ERROR',
+            code: 'apply-unsupported-delta',
+            file: relativePath(root, join(root, 'changes', changeName)),
+            message: `--apply writes back ADDED requirements only, and this change's delta also carries ${unsupported.join(', ')}. ` +
+                `The gate above still checked all of it — merge the remaining operations into the registry by hand, then run this command again to confirm.`,
+        });
+    }
+    // 2) An added id whose prefix no registry file claims. Which file it belongs
+    // in — or whether a file should be created for it — is not something the gate
+    // verified, and guessing would file a requirement somewhere nobody chose.
+    for (const id of unmergedAdded(input)) {
+        if (input.prefixOwners[idPrefix(id)] === undefined) {
+            issues.push({
+                level: 'ERROR',
+                code: 'apply-no-prefix-owner',
+                reqId: id,
+                message: `No registry file declares the "${idPrefix(id)}-" prefix, so --apply cannot tell where "${id}" belongs. ` +
+                    `Create the registry file for that prefix, or give the requirement a prefix an existing file already owns, then run this command again.`,
+            });
+        }
+    }
+    // 3) A rename that would land on a file that already exists. This is the one
+    // failure mode of this command that would destroy work rather than stop, so
+    // it is checked here as well as reported statically by `check`.
+    const taken = new Set(input.mergedSpecs);
+    for (const { file: spec } of input.claimedSpecs) {
+        const dest = mergedSpecPath(spec);
+        if (taken.has(dest)) {
+            issues.push({
+                level: 'ERROR',
+                code: 'proposed-spec-name-taken',
+                file: relativePath(root, spec),
+                message: `Merging ${relativePath(root, spec)} would rename it onto ${relativePath(root, dest)}, which already exists. ` +
+                    `Rename the proposed spec so its merged name is free — two spec files may sit beside the same module, but only one may hold each name.`,
+            });
+        }
+    }
+    // 4) A spec whose ids land in more than one registry file. Its delta import
+    // has to be repointed at *a* registry, and there is no single right answer —
+    // one import cannot serve two files, so this is a change that has to be split
+    // or merged by hand rather than one this can guess at.
+    for (const { file: spec, reqIds } of input.claimedSpecs) {
+        if (registryTargets(input, reqIds).length > 1) {
+            issues.push({
+                level: 'ERROR',
+                code: 'apply-unsupported-delta',
+                file: relativePath(root, spec),
+                message: `${relativePath(root, spec)} attests requirements that this change files into more than one registry file, ` +
+                    `so its import of the delta cannot be repointed at a single one. Split the spec by registry file, or merge this change by hand.`,
+            });
+        }
+    }
+    // By code, then by file. Concatenating the two into one key would let a long
+    // code and a short one collide across the boundary, so the order of a report
+    // could depend on where that seam happened to fall.
+    return issues.sort((a, b) => byCodeUnit(a.code, b.code) || byCodeUnit(a.file ?? '', b.file ?? ''));
+}
+/** The distinct registry files the given ids belong in, by prefix ownership. */
+function registryTargets(input, reqIds) {
+    const owners = reqIds
+        .map((id) => input.prefixOwners[idPrefix(id)])
+        .filter((f) => f !== undefined);
+    return [...new Set(owners)].sort(byCodeUnit);
+}
+/** The ids this change adds that the registry on disk does not have yet. */
+function unmergedAdded(input) {
+    return addedIds(input.delta).filter((id) => !Object.hasOwn(input.base, id));
+}
+/**
+ * Perform the merge, or refuse it whole.
+ *
+ * The caller must have run the gate in the same invocation and found it green;
+ * a merge that files a change as done without re-checking is the one thing this
+ * tool must not ship, because "done" having a hard definition is the whole
+ * claim.
+ */
+export async function applyMerge(input) {
+    // Read once, here, and passed down. The comment on `archivePath` has always
+    // claimed the refusal and the move cannot disagree about the date; until this
+    // it computed a fresh `new Date()` on every call, four times per merge, so
+    // the property it named was precisely the one not provided. A merge that
+    // straddles midnight would have refused against one directory and written to
+    // another — rare, and silent when it happens, which is the combination this
+    // repository treats as worth the line.
+    const stamp = new Date().toISOString().slice(0, 10);
+    const refused = await refusals(input, stamp);
+    if (refused.length > 0)
+        return { issues: refused, written: [] };
+    const { root } = input;
+    const written = [];
+    // --- 1) Splice, first. See the note at the top of this file.
+    const byFile = new Map();
+    for (const id of unmergedAdded(input)) {
+        const file = input.prefixOwners[idPrefix(id)];
+        const group = byFile.get(file) ?? {};
+        group[id] = input.applied[id];
+        byFile.set(file, group);
+    }
+    for (const file of [...byFile.keys()].sort(byCodeUnit)) {
+        const source = await readFile(file, 'utf8');
+        const spliced = spliceRequirements(file, source, byFile.get(file));
+        if (spliced === undefined) {
+            // Unreachable through the command — the gate read this file as a literal
+            // moments ago — so it is reported as the internal inconsistency it is
+            // rather than as a diagnosis about the user's registry.
+            return {
+                issues: [
+                    {
+                        level: 'ERROR',
+                        code: 'internal-error',
+                        file: relativePath(root, file),
+                        message: `${relativePath(root, file)} read as a registry for the gate but not for the merge.`,
+                    },
+                ],
+                written,
+            };
+        }
+        if (spliced !== source) {
+            await writeAtomic(file, spliced);
+            written.push(relativePath(root, file));
+        }
+    }
+    // --- 2) Repoint each claimed spec's delta import, then rename it in place.
+    //
+    // Repoint *before* rename, and that order is resumable rather than tidy. A
+    // crash between them leaves a proposed spec — still claimed, so still in this
+    // list next run — that already reads the registry, which step 1 has just
+    // written the id into; so the re-run's gate is green and the remaining rename
+    // happens. The other order leaves a merged spec that no longer appears in
+    // `claimedSpecs` at all, with a broken import nothing would come back for.
+    const deltaPath = join(root, 'changes', input.changeName, 'requirements.delta.ts');
+    const claimed = [...input.claimedSpecs].sort((a, b) => byCodeUnit(a.file, b.file));
+    for (const { file: spec, reqIds } of claimed) {
+        const target = registryTargets(input, reqIds)[0];
+        if (target) {
+            const source = await readFile(spec, 'utf8');
+            const repointed = repointImport(spec, source, deltaPath, target);
+            if (repointed !== source)
+                await writeAtomic(spec, repointed);
+        }
+        const dest = mergedSpecPath(spec);
+        await rename(spec, dest);
+        written.push(relativePath(root, dest));
+    }
+    // --- 3) Move the change folder, last.
+    const from = join(root, 'changes', input.changeName);
+    const to = archivePath(input, stamp);
+    if (await exists(from)) {
+        await mkdir(dirname(to), { recursive: true });
+        await rename(from, to);
+        written.push(relativePath(root, to));
+    }
+    return { issues: [], written };
+}
+/**
+ * Where a change is archived to. One function because two places ask — the
+ * refusal that checks it is free, and the move that performs it — and a date
+ * computed twice could straddle midnight and disagree with itself.
+ *
+ * So the date is not computed here: `stamp` comes from `applyMerge`, which
+ * reads it once for the whole operation. A pure function of its arguments is
+ * what makes "the two places cannot disagree" a property of the code rather
+ * than of how fast it ran.
+ */
+function archivePath(input, stamp) {
+    return join(input.root, 'archive', `${stamp}-${input.changeName}`);
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=merge.js.map

package/dist/core/pipeline.d.ts

@@ -141,4 +141,17 @@ export interface StatusResult {
 export declare function runStatus(root: string, changeName: string, options?: ReadOptions): Promise<StatusResult>;
 /** Archive gate for a change (design §8, §9: `attest archive <change>`). */
 export declare function runArchive(root: string, changeName: string, options?: RunOptions): Promise<Issue[]>;
+/**
+ * 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 declare function runArchiveApply(root: string, changeName: string, options?: RunOptions): Promise<{
+    issues: Issue[];
+    written: string[];
+}>;
 //# sourceMappingURL=pipeline.d.ts.map