@am_shork/attest 0.5.0 → 0.7.0

package/dist/core/pipeline.js

@@ -1,29 +1,68 @@
 // 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';
 import { applyDelta, addedIds, claimedIds } from './apply.js';
 import { readDeltaSource } from './static-registry.js';
 import { statusRows, statusCounts } from './status.js';
-import { evaluateGate, declaredNotRunIssues } from './gate.js';
+import { evaluateGate, notRunIssues } from './gate.js';
 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';
 import { hasError } from './types.js';
+// The runner half of the engine, reached only when a command actually needs it.
+//
+// These two are deliberately not top-level imports. `cli/index.ts` imports this
+// module whole, so a static import here resolves and evaluates `vite`,
+// `vitest/node` and `vitest/config` before `commander` has parsed an argument —
+// measured at ~900 ms, paid by `check`, `cover`, `render`, `status` without
+// `--eval` and `init`, none of which can start a run. §11's cost model is a
+// short-lived process where cold start is the whole bill, so a fixed toll on
+// every invocation outweighs anything scaling with requirement count.
+//
+// This is *not* the core/adapter package split §11 defers, and does not
+// substitute for it: `pipeline.ts` still holds both halves, so the reachability
+// `tests/import-boundary.spec.ts` cannot assert is still unassertable. What
+// moves is when the cost is paid. The specifiers stay relative and the gate
+// reads `import(...)` from the AST alongside static imports, so the boundary is
+// checked exactly as before — that is the one property this change could have
+// silently dropped, and the reason that test looks for dynamic imports at all.
+/** {@link import('./loader.js').createLoader}, resolved on first use. */
+async function createLoader() {
+    const { createLoader: create } = await import('./loader.js');
+    return create();
+}
+/**
+ * {@link import('./runner.js').runAndCollect}, resolved on first use.
+ *
+ * `BASE_EXCLUDE` gets no such wrapper: it has one caller, which is inside the
+ * function that starts the run it belongs to, so it is destructured there
+ * alongside nothing.
+ */
+async function runAndCollect(options = {}) {
+    const { runAndCollect: run } = await import('./runner.js');
+    return run(options);
+}
 /**
  * Read every registry under root with the reader `options` asks for, and close
  * whatever that reader needed. Static reading starts no Vite server at all.
+ *
+ * `borrowed` is a loader the caller is already holding open for this command.
+ * See `withLoader` for why a command with more than one thing to evaluate owns
+ * one rather than letting each read start its own.
  */
-async function readRegistry(root, options, files) {
+async function readRegistry(root, options, files, borrowed) {
     if (!options.evaluate)
         return loadRegistry(root, staticReader(), files);
+    if (borrowed)
+        return loadRegistry(root, evalReader(borrowed), files);
     const loader = await createLoader();
     try {
         return await loadRegistry(root, evalReader(loader), files);
@@ -32,17 +71,123 @@ async function readRegistry(root, options, files) {
         await loader.close();
     }
 }
+/**
+ * Run `fn` with one loader for the whole command, or with none when nothing is
+ * to be evaluated.
+ *
+ * A loader is a Vite dev server: starting one is the expensive thing on this
+ * path, and `check --eval` used to start **one per change** — `readDelta`
+ * created and closed its own on every iteration of the loop over
+ * `listChangeNames`, on top of the one `readRegistry` had already opened and
+ * closed for the same command. So the cost was 1 + N servers for a command that
+ * needs one. Ownership sits here rather than in either reader because neither
+ * of them knows how many times it is about to be called.
+ *
+ * Static commands pass `undefined` all the way down and start nothing at all,
+ * which is the property `check` without `--eval` is documented on (design §5.1)
+ * and the reason this returns an optional rather than always creating one.
+ */
+async function withLoader(options, fn) {
+    if (!options.evaluate)
+        return fn(undefined);
+    const loader = await createLoader();
+    try {
+        return await fn(loader);
+    }
+    finally {
+        await loader.close();
+    }
+}
 /** 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);
-    return [
-        ...issues,
-        ...validateStructure(registry, plan),
-        ...detectPotentialDrift(registry, plan, plan.paramRefs),
-        ...(await unclaimedProposedSpecIssues(root, scan, options)),
-    ];
+    // One loader for the command, not one per thing evaluated: this is the only
+    // command that reads both the registry and every change's delta, so it is the
+    // only one where that distinction is worth anything.
+    return withLoader(options, async (loader) => {
+        const { registry, issues, unreadableFiles } = await readRegistry(root, options, scan.reqsFiles, loader);
+        const plan = await parseSpecs(scan.specFiles, root);
+        return [
+            ...issues,
+            // `check` keeps reporting on a registry that only half-loaded,
+            // deliberately: its contract is breadth, and the findings from the files
+            // that *did* load are all still true. What it must not do is advise work
+            // that the load failure makes wrong — see `orphan-test` in
+            // `validateStructure`.
+            ...validateStructure(registry, plan, unreadableFiles.length > 0),
+            ...detectPotentialDrift(registry, plan, plan.paramRefs),
+            ...(await unclaimedProposedSpecIssues(root, scan, options, loader)),
+            ...(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).
@@ -60,13 +205,15 @@ export async function runCheck(root, options = {}) {
  * — a change delta is intent, and the commands that only report read it from
  * source (design §5.1).
  */
-async function unclaimedProposedSpecIssues(root, scan, options) {
+async function unclaimedProposedSpecIssues(root, scan, options, loader) {
     if (scan.proposedSpecFiles.length === 0)
         return [];
     const claimed = new Set();
     const issues = [];
+    // The loop `loader` exists for: under `--eval` this used to start and stop a
+    // Vite dev server per change.
     for (const name of await listChangeNames(root)) {
-        const read = await readDelta(root, name, options);
+        const read = await readDelta(root, name, options, loader);
         if ('issue' in read)
             issues.push(read.issue);
         else
@@ -96,6 +243,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,21 +273,28 @@ 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;
     let plan;
+    let unreadableFiles;
     const issues = [];
     try {
         const loaded = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
         registry = loaded.registry;
         issues.push(...loaded.issues);
+        unreadableFiles = loaded.unreadableFiles;
         plan = await parseSpecs(scan.specFiles, root);
     }
     finally {
         await loader.close();
     }
-    issues.push(...validateStructure(registry, plan));
+    // Same as `check`: everything the loaded half supports is still reported, and
+    // only the advice that a load failure would make wrong is withdrawn.
+    issues.push(...validateStructure(registry, plan, unreadableFiles.length > 0));
     issues.push(...detectPotentialDrift(registry, plan, plan.paramRefs));
     const attesting = attestingFiles(plan);
     const counts = {
@@ -167,7 +337,13 @@ export async function runVerify(root, options = {}) {
     if (!run.passed) {
         issues.push({ level: 'ERROR', code: 'tests-red', message: 'Some tests are failing.' });
     }
-    issues.push(...declaredNotRunIssues(plan, run));
+    // The load failures first, then the absences they caused — by the same
+    // function the gate calls, which is the point. `verify` used to ask only for
+    // the absences, so an ordinary broken import surfaced as a `declared-not-run`
+    // per scenario blaming a skip, with nothing anywhere naming the file that did
+    // not load. No more specific diagnosis to pass: `added-id-unmerged` is a
+    // statement about a change's delta, and `verify` has no change.
+    issues.push(...notRunIssues(plan, run));
     return { issues, passed: run.passed, ok: run.passed && !hasError(issues), counts };
 }
 /**
@@ -182,6 +358,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))
@@ -191,8 +370,12 @@ export async function runCover(root, options = {}) {
     for (const s of plan.scenarios) {
         counts.set(s.reqId, (counts.get(s.reqId) ?? 0) + 1);
     }
+    // `byCodeUnit`, not a bare `.sort()`. The two give an identical result on ids
+    // that match the grammar, and that is exactly why this is worth spelling:
+    // `order.ts` exists so ordering has one spelling across the engine, which is
+    // a property that survives an edit — an identical result is not.
     const rows = Object.keys(registry)
-        .sort()
+        .sort(byCodeUnit)
         .map((reqId) => ({
         reqId,
         covered: (counts.get(reqId) ?? 0) > 0,
@@ -209,6 +392,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.
@@ -330,10 +516,14 @@ function changeNotFoundIssue(root, deltaPath, changeName, err) {
  * under review. `archive` evaluates unconditionally because it runs the suite
  * anyway, so declining to evaluate one more module would buy it nothing.
  */
-async function readDelta(root, changeName, options) {
+async function readDelta(root, changeName, options, borrowed) {
     const deltaPath = changeDeltaPath(root, changeName);
     if (options.evaluate) {
-        const loader = await createLoader();
+        // Borrow the caller's loader when it has one, own one otherwise. The
+        // difference matters only to the caller that reads several deltas — see
+        // `withLoader` — and a lone reader should not have to build scaffolding to
+        // ask for one delta.
+        const loader = borrowed ?? (await createLoader());
         try {
             const mod = await loader.load(deltaPath);
             if (!mod.default || typeof mod.default !== 'object') {
@@ -347,7 +537,10 @@ async function readDelta(root, changeName, options) {
             return { issue: changeNotFoundIssue(root, deltaPath, changeName, err) };
         }
         finally {
-            await loader.close();
+            // Only what this call created. Closing a borrowed loader would take it
+            // out from under the caller's next iteration.
+            if (!borrowed)
+                await loader.close();
         }
     }
     let source;
@@ -370,6 +563,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));
@@ -398,14 +609,25 @@ function claimedByDelta(proposed, delta) {
 async function changeMergedPlan(root, delta, scan) {
     const basePlan = await parseSpecs(scan.specFiles, root);
     const proposed = await parseSpecs(scan.proposedSpecFiles, root);
-    const changePlan = claimedByDelta(proposed, delta);
+    const claimed = claimedByDelta(proposed, delta);
     return {
-        scenarios: [...basePlan.scenarios, ...changePlan.scenarios],
-        paramRefs: [...basePlan.paramRefs, ...changePlan.paramRefs],
+        merged: {
+            scenarios: [...basePlan.scenarios, ...claimed.scenarios],
+            paramRefs: [...basePlan.paramRefs, ...claimed.paramRefs],
+        },
+        // Returned rather than recomputed by the caller that needs it. `--apply`
+        // renames exactly the proposed specs this change claims, and deriving that
+        // set a second time — a second `parseSpecs` and a second `claimedByDelta`
+        // over the same files — is agreement by transcription: the two answers
+        // match because the same two functions ran twice, which is the thing this
+        // codebase extracts `declaredNotRunIssues` and `uncoveredIssues` to stop
+        // relying on. One parse, one split, one answer.
+        claimed,
     };
 }
 /** 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,27 +638,69 @@ 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]);
     const scan = await scanProject(root);
-    const plan = await changeMergedPlan(root, read.delta, scan);
+    const { merged: plan } = await changeMergedPlan(root, read.delta, scan);
     const firstRun = await readRedRecord(root, changeName);
     const rows = statusRows(addedIds(read.delta), plan, firstRun);
     return { change: changeName, rows, counts: statusCounts(rows), issues: [] };
 }
 /** 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);
+    // One predicate for the verdict, everywhere (ATX-60): the gate's WARNINGs
+    // survive `--apply` by design, so `some(level === 'ERROR')` spelled here by
+    // hand was a second definition of failure sitting next to the one that counts.
+    if (hasError(issues) || !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);
-        if (issues.some((i) => i.level === 'ERROR'))
-            return issues;
+        const { registry: base, issues, prefixOwners } = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
+        if (hasError(issues))
+            return { issues };
         const deltaPath = changeDeltaPath(root, changeName);
         let delta;
         try {
@@ -453,21 +717,22 @@ 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.
-        const plan = await changeMergedPlan(root, delta, scan);
+        const { merged: plan, claimed } = await changeMergedPlan(root, delta, scan);
         // Other proposals need no exclude glob of their own: the include list below
         // is the plan's own files, and the plan holds only the proposed specs this
         // delta claims. That is what replaced `**/changes/<sibling>/**` — with the
         // specs no longer living under `changes/`, a directory glob could not have
         // told two proposals apart, and one kept alongside the claim check would be
         // a second scoping rule able to disagree with it.
+        const { BASE_EXCLUDE } = await import('./runner.js');
         const exclude = [...BASE_EXCLUDE, '**/archive/**'];
         // Same run scope as `verify`: only the files that declare a requirement().
         // The gate must not go red because a repo's incumbent suite happens to sit
@@ -498,14 +763,28 @@ 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. `claimed` is the half of the plan the gate
+                // above ran, handed back by the function that built it.
+                claimedSpecs: claimedSpecsOf(root, claimed),
+                mergedSpecs: scan.specFiles,
+            },
+        };
     }
     finally {
         await loader.close();