@am_shork/attest 0.7.4 → 0.9.0

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

package/dist/cli/index.js

@@ -13,7 +13,6 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { resolve } from 'node:path';
-import { writeAtomic } from '../core/write.js';
 import { runCheck, runVerify, runCover, runArchive, runArchiveApply, runInit, runRender, runRenderCheck, runStatus, DEFAULT_TARGET, TARGET_NAMES, } from '../core/pipeline.js';
 import { hasError } from '../core/types.js';
 // The one project-derived value this shell still interpolates itself. `--out`
@@ -135,12 +134,16 @@ program
     if (opts.json && !opts.out && !opts.check) {
         cmd.error('error: --json requires --out <file> (stdout cannot carry both the document and the report)');
     }
-    const dest = opts.out ? resolve(process.cwd(), opts.out) : undefined;
+    // Both spellings of the destination, because both are needed downstream: the
+    // resolved one is what the filesystem is given, the typed one is what a
+    // diagnostic echoes. Where it may point, and the write itself, are the
+    // pipeline's — this shell decides what to print and nothing else.
+    const out = opts.out ? { file: resolve(process.cwd(), opts.out), display: opts.out } : undefined;
     return runAction('render', opts, async () => {
         if (opts.check) {
             // The fix hint has to be the command the user can actually re-run from
             // here: their own --out string, and the [dir] they passed.
-            const issues = await runRenderCheck(root(dir), dest, {
+            const issues = await runRenderCheck(root(dir), out.file, {
                 display: opts.out,
                 command: `attest render${dir ? ` ${dir}` : ''} --out ${opts.out}`,
             }, { evaluate: opts.eval });
@@ -156,10 +159,10 @@ program
                 },
             };
         }
-        const { markdown, issues } = await runRender(root(dir), { evaluate: opts.eval });
-        // Never overwrite a good document with the output of a broken registry.
-        if (!hasError(issues) && dest)
-            await writeAtomic(dest, markdown);
+        const { markdown, issues, wrote } = await runRender(root(dir), {
+            evaluate: opts.eval,
+            out,
+        });
         return {
             report: renderReport(VERSION, issues, opts.out),
             human: () => {
@@ -167,7 +170,7 @@ program
                     console.log(formatIssues(issues));
                     console.log(summarize(issues));
                 }
-                else if (dest) {
+                else if (wrote) {
                     console.log(chalk.green(`✓ Wrote ${inline(opts.out ?? '')}`));
                 }
                 else {

package/dist/cli/json.d.ts

@@ -100,6 +100,31 @@ export declare function statusReport(version: string, result: StatusResult): Jso
  * empty stdout and a stack trace on stderr.
  */
 export declare function errorReport(version: string, command: JsonCommand, err: unknown): JsonReport;
-/** Serialize a report for stdout. Pretty-printed: still one parseable document. */
+/**
+ * Serialize a report for stdout. Pretty-printed: still one parseable document.
+ *
+ * Every string in it loses its control characters first (design §9.1). The
+ * machine surface was recorded as exempt because `JSON.stringify` escapes every
+ * C0 character — true, and narrower than the rule: §9.1's class also holds DEL
+ * and the C1 range, and `JSON.stringify` emits those verbatim. `U+009B` is
+ * 8-bit CSI, the same introducer as `ESC [` on a terminal that reads
+ * UTF-8-decoded C1 as control — so a scenario name or a thrown message can
+ * drive the terminal of someone reading the JSON rather than parsing it, from
+ * `check --json`, which executes nothing.
+ *
+ * Applied here rather than at the report builders, and that is §9.1's own
+ * distinction rather than a preference: this is a *document*, not a stream. It
+ * has one point of assembly, before any of it is seen, so an obligation sitting
+ * there covers a field nobody has added yet — as `outFiles` and `docsUrl` both
+ * were. The terminal path is sanitised at each write site for the opposite
+ * reason, recorded in core/terminal.ts.
+ *
+ * A replacer rather than a walk over the fields that carry project text —
+ * `issues[].message`, `issues[].file`, `change`, `outFile`, `outFiles` today —
+ * because enumerating them is the arrangement that leaves the next one out. It
+ * costs nothing on the fields that cannot carry a control character: `control`
+ * allocates when something matches, and nothing does. Non-mutating, because a
+ * caller may render the same report for a human afterwards.
+ */
 export declare function renderJson(report: JsonReport): string;
 //# sourceMappingURL=json.d.ts.map

package/dist/cli/json.js

@@ -6,6 +6,7 @@
 // and every command emits the same envelope (tool/version/command/ok/summary/
 // issues) plus command-specific fields.
 import { docsUrl } from '../core/docs.js';
+import { control } from '../core/terminal.js';
 import { hasError } from '../core/types.js';
 /** Bumped whenever the emitted shape changes incompatibly. */
 export const SCHEMA_VERSION = 1;
@@ -156,8 +157,33 @@ export function errorReport(version, command, err) {
     const issue = { level: 'ERROR', code: 'internal-error', message };
     return envelope({ version, command, ok: false, issues: [issue] });
 }
-/** Serialize a report for stdout. Pretty-printed: still one parseable document. */
+/**
+ * Serialize a report for stdout. Pretty-printed: still one parseable document.
+ *
+ * Every string in it loses its control characters first (design §9.1). The
+ * machine surface was recorded as exempt because `JSON.stringify` escapes every
+ * C0 character — true, and narrower than the rule: §9.1's class also holds DEL
+ * and the C1 range, and `JSON.stringify` emits those verbatim. `U+009B` is
+ * 8-bit CSI, the same introducer as `ESC [` on a terminal that reads
+ * UTF-8-decoded C1 as control — so a scenario name or a thrown message can
+ * drive the terminal of someone reading the JSON rather than parsing it, from
+ * `check --json`, which executes nothing.
+ *
+ * Applied here rather than at the report builders, and that is §9.1's own
+ * distinction rather than a preference: this is a *document*, not a stream. It
+ * has one point of assembly, before any of it is seen, so an obligation sitting
+ * there covers a field nobody has added yet — as `outFiles` and `docsUrl` both
+ * were. The terminal path is sanitised at each write site for the opposite
+ * reason, recorded in core/terminal.ts.
+ *
+ * A replacer rather than a walk over the fields that carry project text —
+ * `issues[].message`, `issues[].file`, `change`, `outFile`, `outFiles` today —
+ * because enumerating them is the arrangement that leaves the next one out. It
+ * costs nothing on the fields that cannot carry a control character: `control`
+ * allocates when something matches, and nothing does. Non-mutating, because a
+ * caller may render the same report for a human afterwards.
+ */
 export function renderJson(report) {
-    return JSON.stringify(report, null, 2);
+    return JSON.stringify(report, (_key, value) => (typeof value === 'string' ? control(value) : value), 2);
 }
 //# sourceMappingURL=json.js.map

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');
 }
 /**

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/gate.js

@@ -16,7 +16,7 @@ import { RED_RECORD_FILE, hasRecordedRed, recordedOutcome, } from './red-record.
 export function declaredNotRunIssues(plan, run) {
     const issues = [];
     for (const s of plan.scenarios) {
-        if (!run.runtimeCoverage.get(s.reqId)?.has(s.name)) {
+        if (!run.runtimeCoverage.get(s.reqId)?.get(s.file)?.has(s.name)) {
             issues.push({
                 level: 'ERROR',
                 code: 'declared-not-run',
@@ -155,9 +155,9 @@ export function neverRedIssues(plan, addedIds, firstRun) {
     for (const s of plan.scenarios) {
         if (!added.has(s.reqId))
             continue;
-        if (hasRecordedRed(firstRun, s.reqId, s.name))
+        if (hasRecordedRed(firstRun, s))
             continue;
-        const outcome = recordedOutcome(firstRun, s.reqId, s.name);
+        const outcome = recordedOutcome(firstRun, s);
         issues.push({
             level: 'ERROR',
             code: 'never-red',

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

@@ -5,7 +5,7 @@ import { basename, join } from 'node:path';
 import { relativePath } from './paths.js';
 import { parseSpecFile } from './parser.js';
 import { declaredIdsFromSource, readRegistrySource } from './static-registry.js';
-import { RegistryValidationError } from './registry.js';
+import { registryValidationMessage } from './registry-issues.js';
 import { RegistrySchema } from './schema.js';
 import { byCodeUnit } from './order.js';
 import { SourceNotCompiled } from './compiler.js';
@@ -40,6 +40,44 @@ 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: this file has two
+ * unbounded fan-outs to close, one over directories and one over files, and
+ * a shape written twice is a shape one of the two copies will eventually be
+ * fixed without.
+ *
+ * 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. Both callers here do one of
+ * those, deliberately.
+ *
+ * No result is collected and none is needed — both callers write into something
+ * they already own, 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 both sites: `parseSpecs` catches per file
+ * so that one hostile spec 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 +85,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);
-            }
-            else if (e.isFile() && match(e.name)) {
-                out.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);
+                }
             }
-        }
-        await Promise.all(subdirs.map(walk));
-    };
-    await walk(root);
+        });
+        level = next;
+    }
     return out.sort(byCodeUnit);
 }
 /**
@@ -191,13 +245,13 @@ export function evalReader(loader) {
             const parsed = RegistrySchema.safeParse(exported);
             if (!parsed.success) {
                 // The same code, the same prefix and the same rendering of the field
-                // errors as `readRegistrySource` — going through RegistryValidationError
-                // keeps the message identical rather than merely similar.
+                // errors as `readRegistrySource` — sharing one formatter keeps the
+                // message identical rather than merely similar.
                 return {
                     issue: {
                         level: 'ERROR',
                         code: 'registry-invalid',
-                        message: `Failed to load registry: ${new RegistryValidationError(parsed.error.issues).message}`,
+                        message: `Failed to load registry: ${registryValidationMessage(parsed.error.issues)}`,
                     },
                 };
             }
@@ -362,10 +416,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 +429,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);