@am_shork/attest 0.8.0 → 0.9.1

package/README.md

@@ -125,7 +125,8 @@ attest verify   # run tests + coverage + drift, graded report
 attest cover    # which requirements lack a scenario
 attest render   # the requirements as Markdown, for people who don't read TS
 attest archive <change>   # gate a proposed change: green + covered + no drift
-attest status <change>    # what that gate still wants, without running anything
+attest status <change>    # per added id: scenario written? seen red? (part of that
+                          # gate, without running anything — never a verdict)
 ```
 
 Every command takes the project root as an optional last argument, and `--json`
@@ -166,7 +167,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.8.0/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.1/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/bin/attest.js

@@ -1,3 +1,44 @@
 #!/usr/bin/env node
 // Thin launcher: delegates to the built CLI shell (src/cli -> dist/cli).
-import '../dist/cli/index.js';
+//
+// **The compile cache is enabled here because here is the only place it can
+// be.** `typescript` is the fixed toll on every invocation: measured on this
+// machine, the CLI's whole dependency graph costs ~790 ms to load and the
+// compiler is ~672 ms of it, against ~28 ms for commander, ~17 ms for chalk and
+// ~70 ms for zod. Nothing can move that by loading it later, either — every
+// command except `init` reads a registry or a spec through the AST, so the
+// import is not merely eager, it is *needed*. What a code cache changes is the
+// price of the same load: V8 keeps its compilation output between runs, and the
+// saving lands on the commands a pipeline actually repeats. Measured over two
+// independent A/B rounds, nine interleaved runs each, median: **11% to 28% off
+// every command** — `check self` 1153 -> 970 and 1106 -> 971 ms, `cover self`
+// 1122 -> 951 and 1346 -> 1195 ms, `status` 1110 -> 923 ms, `init` 904 -> 711
+// and 1365 -> 984 ms. Quoted as a range because the absolute figures move with
+// whatever else the machine is doing; the direction did not, across either
+// round or any command in them.
+//
+// **The import below has to stay dynamic, and this is the whole reason.** A
+// static `import` is hoisted and its module graph is evaluated *before* any
+// statement in this file runs — so with one, the call above happens after
+// `typescript` has already been compiled and the cache does nothing at all. It
+// still returns success, and every command still works, so there is nothing to
+// notice: measured, the static spelling came back at 873 ms against an
+// unpatched 897 ms, i.e. inside the noise, while the dynamic one is 669 ms.
+// That is this repository's dominant failure shape — a defence that reads as
+// present and is not — arriving in a three-line file.
+//
+// Optional-chained because `engines` allows Node 20 and this API arrived in
+// 22.1: on an older runtime the speed-up is absent, which is the right
+// behaviour for an optimisation and not a reason to refuse to start. It never
+// throws either — a cache directory that cannot be written comes back as a
+// status this deliberately ignores, since the only thing a failure costs is the
+// saving above.
+//
+// The cache lands under the OS temp directory, never in the project: every
+// other file Attest writes is one the user commits (see `core/write.ts`), and
+// this is the one that must not be.
+import module from 'node:module';
+
+module.enableCompileCache?.();
+
+await import('../dist/cli/index.js');

package/dist/cli/report.js

@@ -190,7 +190,15 @@ export function formatStatus(result) {
     }
     const { proven } = result.counts;
     lines.push(chalk.dim(`— ${plural(result.rows.length, 'added requirement')}, ${proven} ready to archive`));
-    lines.push(chalk.dim(`Not a verdict: run \`attest archive ${inline(result.change)}\` to run the suite.`));
+    // Two pointers, because this command answers less than a reader assumes on
+    // both sides. `archive` is the verdict it deliberately cannot give. `check` is
+    // the half it deliberately does not duplicate: a proposed spec no delta
+    // claims, or one whose merged name is taken, is a static fact about this
+    // change that `check` already reports — and reporting it here too would put a
+    // second answer to one question in the tree, which is what this project takes
+    // apart everywhere else. Naming it is the whole cost of not absorbing it.
+    lines.push(chalk.dim(`Not a verdict: run \`attest archive ${inline(result.change)}\` to run the suite, ` +
+        `\`attest check\` for the proposed specs themselves.`));
     return lines.join('\n');
 }
 /**
@@ -242,10 +250,16 @@ export function formatCoverage(rows) {
         const detail = r.covered
             ? chalk.dim(`${r.scenarioCount} scenario${r.scenarioCount === 1 ? '' : 's'}`)
             : chalk.red('no scenario');
-        // Sanitised, even though a registry id has been through the schema's
-        // `^[A-Z]+-\d+$`: that is true of the *static* reader only. Under
-        // `--eval` the registry is whatever the module exported, and `evalReader`
-        // checks that it is an object and nothing further.
+        // Sanitised even though a registry id cannot carry a control character:
+        // `^[A-Z]+-\d+$` holds on both reader paths — the static one by
+        // construction, the evaluating one since ATX-38 — so this can never fire.
+        // It stays because the grammar is held somewhere else, and a defence that
+        // lapses when the other one does is not a defence; `CoverageRow.reqId` is
+        // a `string`, and this function is exported. Same standard as
+        // `splice.ts`'s `keySource`, and the reason it is not an inconsistency
+        // with `render.ts` deciding the opposite: that one states it need *not*
+        // sanitise ids, which is true, and builds its container prototype-free
+        // anyway for exactly this reason.
         return `  ${mark} ${chalk.bold(inline(r.reqId))}  ${detail}`;
     })
         .join('\n');

package/dist/core/apply.d.ts

@@ -1,5 +1,5 @@
 import type { RegistryDelta } from './registry.js';
-import type { Issue, Registry } from './types.js';
+import type { Issue, Registry, Requirement } from './types.js';
 export interface ApplyResult {
     registry: Registry;
     issues: Issue[];
@@ -12,6 +12,14 @@ export interface ApplyResult {
  * than off `delta.added`, so the two can never be scoped differently.
  */
 export declare function addedIds(d: RegistryDelta): string[];
+/**
+ * The ids a delta MODIFIEs — the scope of `--apply`'s field-level write-back.
+ *
+ * Here for the reason `addedIds` is: two places ask, the merge that writes them
+ * and the refusal that checks their prefix is owned, and a delta's operations
+ * must not be enumerated twice.
+ */
+export declare function modifiedIds(d: RegistryDelta): string[];
 /**
  * The ids a delta **claims**: what it adds, renames to, or modifies.
  *
@@ -33,4 +41,13 @@ export declare function claimedIds(d: RegistryDelta): string[];
  * base registry is never mutated. Applying the same delta twice is a no-op.
  */
 export declare function applyDelta(base: Registry, d: RegistryDelta): ApplyResult;
+/**
+ * Content equality via canonical JSON (params key order does not matter).
+ *
+ * Exported because `--apply` asks the same question twice — whether a modified
+ * entry is already what the end state says, and whether the bytes it wrote read
+ * back as it — and a second spelling of "the same requirement" is a second
+ * answer the moment `Requirement` gains a field.
+ */
+export declare function sameRequirement(a: Requirement, b: Requirement): boolean;
 //# sourceMappingURL=apply.d.ts.map

package/dist/core/apply.js

@@ -14,6 +14,16 @@ import { byCodeUnit, sortDeep } from './order.js';
 export function addedIds(d) {
     return Object.keys(d.added ?? {});
 }
+/**
+ * The ids a delta MODIFIEs — the scope of `--apply`'s field-level write-back.
+ *
+ * Here for the reason `addedIds` is: two places ask, the merge that writes them
+ * and the refusal that checks their prefix is owned, and a delta's operations
+ * must not be enumerated twice.
+ */
+export function modifiedIds(d) {
+    return Object.keys(d.modified ?? {}).sort(byCodeUnit);
+}
 /**
  * The ids a delta **claims**: what it adds, renames to, or modifies.
  *
@@ -177,8 +187,15 @@ function firstMessage(error) {
     const path = first.path.map(String).join('.');
     return path ? `${path}: ${first.message}` : first.message;
 }
-/** Content equality via canonical JSON (params key order does not matter). */
-function sameRequirement(a, b) {
+/**
+ * Content equality via canonical JSON (params key order does not matter).
+ *
+ * Exported because `--apply` asks the same question twice — whether a modified
+ * entry is already what the end state says, and whether the bytes it wrote read
+ * back as it — and a second spelling of "the same requirement" is a second
+ * answer the moment `Requirement` gains a field.
+ */
+export function sameRequirement(a, b) {
     return canonical(a) === canonical(b);
 }
 function canonical(req) {

package/dist/core/locate.d.ts

@@ -27,6 +27,20 @@ export declare const isSpecFile: (name: string) => boolean;
  * serial `for await` spent one filesystem round-trip per directory, which is
  * the dominant cost of `check` on a large repo. The result is sorted, so the
  * order never depends on which `readdir` happened to resolve first.
+ *
+ * Concurrency is bounded, for the reason `parseSpecs` bounds its own: the input
+ * size is not ours to choose, `check` being what this project tells people to
+ * run first on an untrusted fork MR. What must not come back is a fan-out whose
+ * peak is the shape of the tree rather than a constant — which is what
+ * recursing through `Promise.all(subdirs)` gave, and what
+ * `tests/locate-fanout.spec.ts` pins.
+ *
+ * A level at a time, rather than one pool over a queue that grows as directories
+ * are discovered: the pool would have to keep workers alive while the queue is
+ * momentarily empty but another worker may still push to it, and that
+ * termination condition is the part worth not owning. The cost is a barrier per
+ * depth, which is paid in tree *depth* — small, and bounded by the filesystem —
+ * while the fan-out being bounded is paid in tree *width*, which is not.
  */
 export declare function findFiles(root: string, match: (name: string) => boolean): Promise<string[]>;
 /** The file sets every command needs, collected in one pass. */
@@ -167,10 +181,11 @@ export declare function idPrefix(id: string): string;
  * avoid: input size is not ours to choose here, `check` being what this project
  * tells people to run first on an untrusted fork MR. Measured in `[0.7.0]`.
  *
- * `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.
+ * `findFiles` above bounds its own fan-out the same way and through the same
+ * helper. It was left unbounded when this one was capped, on the grounds that
+ * the failure it invited — descriptor exhaustion — could not be produced on
+ * either development platform; what closed it is that the peak itself is
+ * portable arithmetic, which is the standard this half was accepted on.
  */
 export declare function parseSpecs(files: string[], displayRoot: string): Promise<{
     plan: AttestPlan;

package/dist/core/locate.js

@@ -40,6 +40,49 @@ export const isProposedSpecFile = (name) => name.endsWith('.proposed.spec.ts');
  * of them until its gate passes.
  */
 export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpecFile(name);
+/**
+ * Run `fn` over every item with at most `limit` of them in flight.
+ *
+ * Extracted at the second call site rather than the first, because a shape
+ * written N times is one a later fix reaches only some copies of.
+ *
+ * **There are three, and the third is the one to look for.** `findFiles` and
+ * `parseSpecs` are named for what they fan out over; `loadRegistry` is named for
+ * merging, and its concurrency sits under a comment about *ordering* that
+ * answers a different question convincingly. Anything here that reads a list the
+ * project's tree decides the length of belongs in this pool, whatever the
+ * function around it is called.
+ *
+ * The order `fn` is *called* in is the input order; the order it *completes* in
+ * is not, so a caller that needs a stable result either indexes into a
+ * preallocated array by `index` or sorts afterwards. All three callers here do
+ * one of those, deliberately.
+ *
+ * No result is collected and none is needed — every caller writes into something
+ * it already owns, and a version returning `T[]` would have to choose an
+ * ordering on their behalf. A throw from `fn` propagates and abandons the rest,
+ * which is the existing behaviour at all three sites: `parseSpecs` and
+ * `loadRegistry` catch per file so that one hostile source scraps only itself
+ * (ATX-65), and a failed `readdir` really does end the walk.
+ */
+async function forEachBounded(items, limit, fn) {
+    let cursor = 0;
+    const worker = async () => {
+        for (let i = cursor++; i < items.length; i = cursor++) {
+            await fn(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
+/**
+ * How many directories are open at once during the walk. The same figure as
+ * `PARSE_CONCURRENCY` and deliberately not the same constant: the two bound
+ * different resources, and sharing one would make either impossible to tune
+ * without moving the other. High enough that the walk stays I/O bound on any
+ * real project, low enough that what is in flight is a constant rather than the
+ * shape of the input.
+ */
+const WALK_CONCURRENCY = 32;
 /**
  * Recursively find files under root whose basename matches `match`.
  *
@@ -47,25 +90,41 @@ export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpec
  * serial `for await` spent one filesystem round-trip per directory, which is
  * the dominant cost of `check` on a large repo. The result is sorted, so the
  * order never depends on which `readdir` happened to resolve first.
+ *
+ * Concurrency is bounded, for the reason `parseSpecs` bounds its own: the input
+ * size is not ours to choose, `check` being what this project tells people to
+ * run first on an untrusted fork MR. What must not come back is a fan-out whose
+ * peak is the shape of the tree rather than a constant — which is what
+ * recursing through `Promise.all(subdirs)` gave, and what
+ * `tests/locate-fanout.spec.ts` pins.
+ *
+ * A level at a time, rather than one pool over a queue that grows as directories
+ * are discovered: the pool would have to keep workers alive while the queue is
+ * momentarily empty but another worker may still push to it, and that
+ * termination condition is the part worth not owning. The cost is a barrier per
+ * depth, which is paid in tree *depth* — small, and bounded by the filesystem —
+ * while the fan-out being bounded is paid in tree *width*, which is not.
  */
 export async function findFiles(root, match) {
     const out = [];
-    const walk = async (dir) => {
-        const entries = await readdir(dir, { withFileTypes: true });
-        const subdirs = [];
-        for (const e of entries) {
-            const full = join(dir, e.name);
-            if (e.isDirectory()) {
-                if (!SKIP_DIRS.has(e.name))
-                    subdirs.push(full);
+    let level = [root];
+    while (level.length > 0) {
+        const next = [];
+        await forEachBounded(level, WALK_CONCURRENCY, async (dir) => {
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const e of entries) {
+                const full = join(dir, e.name);
+                if (e.isDirectory()) {
+                    if (!SKIP_DIRS.has(e.name))
+                        next.push(full);
+                }
+                else if (e.isFile() && match(e.name)) {
+                    out.push(full);
+                }
             }
-            else if (e.isFile() && match(e.name)) {
-                out.push(full);
-            }
-        }
-        await Promise.all(subdirs.map(walk));
-    };
-    await walk(root);
+        });
+        level = next;
+    }
     return out.sort(byCodeUnit);
 }
 /**
@@ -245,6 +304,14 @@ async function declaredIds(absPath) {
         return [];
     }
 }
+/**
+ * How many registry files are read at once. A third figure equal to the other
+ * two and, for the reason `WALK_CONCURRENCY` gives, a third constant: what this
+ * bounds is neither directories nor spec sources but whatever the *reader*
+ * holds — a source and a `SourceFile` under `staticReader`, a Vite SSR module
+ * evaluation under `evalReader` — and those are not tunable together.
+ */
+const REGISTRY_CONCURRENCY = 32;
 /**
  * Read and merge every `*.reqs.ts` registry under root, with the given reader.
  * A registry the reader rejects becomes its own ERROR; a duplicate id across
@@ -263,7 +330,16 @@ export async function loadRegistry(root, reader, files) {
     const paths = files ?? (await scanProject(root)).reqsFiles;
     // Read the files concurrently, then fold the results in sorted file order:
     // the issue list stays deterministic regardless of which one finished first.
-    const loaded = await Promise.all(paths.map(async (file) => ({ file, outcome: await readGuarded(reader, file) })));
+    //
+    // Indexed rather than appended, exactly as `parseSpecs` does it and for the
+    // same reason: `forEachBounded` *calls* in input order and *completes* in
+    // whatever order the reads finish, so the fold below is driven by position.
+    const outcomes = new Array(paths.length);
+    await forEachBounded(paths, REGISTRY_CONCURRENCY, async (file, i) => {
+        // `readGuarded` catches, so nothing here can throw and abandon the rest —
+        // which is the one thing the pool does not do for its caller.
+        outcomes[i] = await readGuarded(reader, file);
+    });
     const registry = {};
     const issues = [];
     const unreadable = [];
@@ -277,9 +353,10 @@ export async function loadRegistry(root, reader, files) {
     // 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;
+    for (let i = 0; i < paths.length; i += 1) {
+        const file = paths[i];
+        const outcome = outcomes[i];
+        const display = relativePath(root, file);
         if ('issue' in outcome) {
             issues.push({ ...outcome.issue, file: display });
             // Read the source again for the ids alone. Both readers land here, and the
@@ -288,7 +365,7 @@ export async function loadRegistry(root, reader, files) {
             // is already an ERROR is not a cost worth arranging around, and sharing
             // the reader's source instead would mean the two readers passing different
             // things to one diagnostic.
-            unreadable.push({ file: display, ids: await declaredIds(entry.file) });
+            unreadable.push({ file: display, ids: await declaredIds(file) });
             continue;
         }
         // One issue per colliding prefix rather than per requirement: the fact is
@@ -299,9 +376,9 @@ export async function loadRegistry(root, reader, files) {
             const prefix = idPrefix(id);
             const owner = prefixOwner.get(prefix);
             if (owner === undefined) {
-                prefixOwner.set(prefix, entry.file);
+                prefixOwner.set(prefix, file);
             }
-            else if (owner !== entry.file && !reported.has(prefix)) {
+            else if (owner !== 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.
@@ -362,10 +439,11 @@ const PARSE_CONCURRENCY = 32;
  * avoid: input size is not ours to choose here, `check` being what this project
  * tells people to run first on an untrusted fork MR. Measured in `[0.7.0]`.
  *
- * `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.
+ * `findFiles` above bounds its own fan-out the same way and through the same
+ * helper. It was left unbounded when this one was capped, on the grounds that
+ * the failure it invited — descriptor exhaustion — could not be produced on
+ * either development platform; what closed it is that the peak itself is
+ * portable arithmetic, which is the standard this half was accepted on.
  */
 export async function parseSpecs(files, displayRoot) {
     // Indexed rather than appended, so the merge below follows the input order
@@ -374,24 +452,19 @@ export async function parseSpecs(files, displayRoot) {
     // Same index space, so a file contributes either a parse or an issue and the
     // two lists cannot disagree about which file is which.
     const failures = new Array(files.length);
-    let next = 0;
-    const worker = async () => {
-        for (let i = next++; i < files.length; i = next++) {
-            const file = files[i];
-            const display = relativePath(displayRoot, file);
-            // Per file, for the reason `readGuarded` exists above: these run
-            // concurrently, so one throw rejects the whole `Promise.all` and takes
-            // the command with it. A hostile spec scraps only itself (ATX-65).
-            try {
-                parsed[i] = parseSpecFile(display, await readFile(file, 'utf8'));
-            }
-            catch (err) {
-                parsed[i] = { scenarios: [], paramRefs: [] };
-                failures[i] = { ...unreadableIssue(err), file: display };
-            }
+    await forEachBounded(files, PARSE_CONCURRENCY, async (file, i) => {
+        const display = relativePath(displayRoot, file);
+        // Per file, for the reason `readGuarded` exists above: these run
+        // concurrently, so one throw would abandon the rest and take the command
+        // with it. A hostile spec scraps only itself (ATX-65).
+        try {
+            parsed[i] = parseSpecFile(display, await readFile(file, 'utf8'));
         }
-    };
-    await Promise.all(Array.from({ length: Math.min(PARSE_CONCURRENCY, files.length) }, worker));
+        catch (err) {
+            parsed[i] = { scenarios: [], paramRefs: [] };
+            failures[i] = { ...unreadableIssue(err), file: display };
+        }
+    });
     const plan = { scenarios: [], paramRefs: [] };
     for (const one of parsed) {
         plan.scenarios.push(...one.scenarios);