@am_shork/attest 0.7.2 → 0.7.4

package/dist/core/pipeline.js

@@ -13,9 +13,9 @@ 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 { mkdir, readFile, realpath } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
-import { relativePath } from './paths.js';
+import { isInside, relativePath } from './paths.js';
 import { hasError } from './types.js';
 // The runner half of the engine, reached only when a command actually needs it.
 //
@@ -108,7 +108,7 @@ export async function runCheck(root, options = {}) {
     // 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 { registry, issues, unreadable } = await readRegistry(root, options, scan.reqsFiles, loader);
         const { plan, issues: unreadableSpecs } = await parseSpecs(scan.specFiles, root);
         return [
             ...issues,
@@ -121,7 +121,7 @@ export async function runCheck(root, options = {}) {
             // 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),
+            ...validateStructure(registry, plan, unreadable),
             ...detectPotentialDrift(registry, plan, plan.paramRefs),
             ...(await unclaimedProposedSpecIssues(root, scan, options, loader)),
             ...(await changeDirSpecIssues(root)),
@@ -291,13 +291,13 @@ export async function runVerify(root, options = {}) {
     const loader = await createLoader();
     let registry;
     let plan;
-    let unreadableFiles;
+    let unreadable;
     const issues = [];
     try {
         const loaded = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
         registry = loaded.registry;
         issues.push(...loaded.issues);
-        unreadableFiles = loaded.unreadableFiles;
+        unreadable = loaded.unreadable;
         const parsedSpecs = await parseSpecs(scan.specFiles, root);
         plan = parsedSpecs.plan;
         issues.push(...parsedSpecs.issues);
@@ -307,7 +307,7 @@ export async function runVerify(root, options = {}) {
     }
     // 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(...validateStructure(registry, plan, unreadable));
     issues.push(...detectPotentialDrift(registry, plan, plan.paramRefs));
     const attesting = attestingFiles(plan);
     const counts = {
@@ -450,15 +450,78 @@ export async function runInit(root, names) {
     const { targets, issues } = resolveTargets(names.length > 0 ? names : [DEFAULT_TARGET]);
     if (issues.length > 0)
         return { files: [], issues };
-    const files = [];
+    // Every destination is resolved before any of them is written, for the reason
+    // `resolveTargets` refuses the whole set on one unknown name: a run that stops
+    // partway leaves a repository carrying instructions for some agents and a
+    // failing command that does not say which.
+    // A root that does not exist yet is `init <dir>` on a directory this run
+    // creates, and nothing can have been planted inside a directory that is not
+    // there — so it stands for itself and every segment below it resolves
+    // lexically, which is what the old implementation did for all of them.
+    const realRoot = await realpath(root).catch(() => root);
+    const writes = [];
+    const refusals = [];
     for (const target of targets) {
-        const dest = join(root, target.file);
+        const resolved = await resolveDest(realRoot, target.file);
+        if (resolved.ok) {
+            writes.push({ target, dest: resolved.dest });
+        }
+        else {
+            refusals.push({
+                level: 'ERROR',
+                code: 'unsafe-target-path',
+                file: target.file,
+                message: `Refusing to write ${target.file}: it resolves to ${resolved.escape}, outside the project. Remove the link at that path and re-run.`,
+            });
+        }
+    }
+    if (refusals.length > 0)
+        return { files: [], issues: refusals };
+    const files = [];
+    for (const { target, dest } of writes) {
         await mkdir(dirname(dest), { recursive: true });
         await writeAtomic(dest, target.content());
         files.push(target.file);
     }
     return { files, issues };
 }
+/**
+ * Where a target's file really goes, or the path outside the project that
+ * asking put it at (design §9: ownership of the path is checked, not assumed).
+ *
+ * `join(root, file)` answers where the path *reads* as going, and that is not
+ * the same question: a segment that is a link makes a path lexically inside the
+ * root and physically outside it, which `mkdir -p` and the write both follow.
+ * So the resolution is the check, and a lexical one would not be — `join`
+ * normalises `..`, so it is already satisfied here. `writeAtomic`'s `wx` is not
+ * the defence either and was never scoped to be: it guards the *temporary* path
+ * against a planted link, in whichever directory the destination turns out to
+ * be.
+ *
+ * So every segment is resolved, not just the leaf. A link anywhere along the
+ * way is the escape, and the leaf is checked too — `rename` replaces a symlink
+ * rather than following it, so a link there would not leak the content, but it
+ * would silently destroy a file the user made deliberately.
+ *
+ * A segment that does not exist cannot be a link, and neither can the ones
+ * below it, so `realpath` failing means the rest of the path is Attest's own
+ * `mkdir` to create. What this cannot close is a link planted between this
+ * resolution and the write; the exposure it does close is one committed to the
+ * repository, which is the one a checkout hands you.
+ */
+async function resolveDest(realRoot, file) {
+    let current = realRoot;
+    // `AgentTarget.file` is spelled with `/` on every platform (ATX-28), so the
+    // segments are the same list here as they are in the report.
+    for (const segment of file.split('/')) {
+        const next = join(current, segment);
+        const real = await realpath(next).catch(() => next);
+        if (!isInside(realRoot, real))
+            return { ok: false, escape: relativePath(realRoot, real) };
+        current = real;
+    }
+    return { ok: true, dest: current };
+}
 /**
  * A change name must name one directory inside `changes/`, and nothing else.
  *

package/dist/core/render.js

@@ -6,7 +6,7 @@
 // back, so the direction OpenSpec's pure-Markdown model went (Markdown as
 // truth, and the free-form drift that comes with it) stays closed.
 //
-// Four properties this file must keep:
+// Five properties this file must keep:
 //  - **Intent only.** The document says what the system promises, never what is
 //    proven or green: coverage and results are verdicts, and verdicts belong to
 //    `cover` / `verify`, which recompute them on demand. Putting them here also
@@ -25,6 +25,10 @@
 //    and it is a *file* — committed, served, and read again long after the run
 //    that wrote it. See `sanitised` for why the defence sits here rather than
 //    at the terminal write.
+//  - **Prose stays prose.** A string the registry owns may be marked up and may
+//    not become a tag or a heading: the document promises one section per
+//    requirement, and a rationale that opens its own breaks the only structural
+//    claim the document makes. See `prose` (design §9.1).
 import { byCodeUnit, sortDeep } from './order.js';
 import { control } from './terminal.js';
 /** Whether a value reads as words in a sentence — a scalar, or a list of them. */
@@ -199,7 +203,7 @@ function compareIds(a, b) {
 function overviewTable(registry, ids) {
     const rows = ids.map((id) => {
         const req = registry[id];
-        return `| [${id}](${anchor(id)}) | ${cell(interpolate(req.statement, req.params))} |`;
+        return `| [${id}](${anchor(id)}) | ${cell(statementText(req))} |`;
     });
     return ['| ID | Requirement |', '| --- | --- |', ...rows];
 }
@@ -207,9 +211,9 @@ function section(id, req) {
     const out = [
         `## ${id}`,
         '',
-        interpolate(req.statement, req.params),
+        statementText(req),
         '',
-        `**Why:** ${req.rationale}`,
+        `**Why:** ${prose(req.rationale)}`,
     ];
     const params = Object.entries(req.params);
     if (params.length > 0) {
@@ -225,33 +229,200 @@ function section(id, req) {
         }
     }
     if (req.outOfScope.length > 0) {
-        out.push('', '**Out of scope**', '', ...req.outOfScope.map((s) => `- ${s}`));
+        out.push('', '**Out of scope**', '', ...req.outOfScope.map((s) => `- ${prose(s)}`));
     }
     return out;
 }
+/** The statement as the document says it, with its params in place. */
+function statementText(req) {
+    return prose(req.statement, req.params);
+}
+/**
+ * Author prose as Markdown that cannot become HTML and cannot open a section,
+ * with `{param}` placeholders substituted as it goes (design §9.1).
+ *
+ * One pass rather than two because the two jobs need the same fact — which
+ * regime each character is in. Escaping first and substituting after would run
+ * the value through a scanner reading backticks as structure; substituting
+ * first and escaping after would let a value's own backtick open a code span
+ * that was never in the statement, and carry the rest of the sentence out of
+ * the defence. Knowing the position is also what lets a value be escaped
+ * *for* it, which is the difference between `emphasised` and `literal` below.
+ *
+ * Which of the three things a registry string could do here is intended, and
+ * why this escapes rather than refuses, is §9.1. What is local to this function
+ * is where it stops: **a code span is left exactly as written**, because a
+ * span's contents are literal text in every renderer and an entity written
+ * there would be visible rather than decoded. The match is therefore
+ * deliberately conservative — a backtick run opens a span only if a run of
+ * *exactly* that length closes it (CommonMark), and an unmatched run is text
+ * with the defence still applied after it. Being wrong the other way, reading
+ * text as a span the renderer will not, is the only direction that leaks.
+ */
+function prose(text, params = {}) {
+    const spans = spanReader(text);
+    const out = [];
+    let i = 0;
+    let atLineStart = true;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '`') {
+            const end = spans.spanEndAt(i);
+            out.push(substitute(text.slice(i, end), params, literal));
+            atLineStart = false;
+            i = end;
+            continue;
+        }
+        if (ch === '{') {
+            const placeholder = /^\{\w+\}/.exec(text.slice(i));
+            if (placeholder !== null) {
+                out.push(substitute(placeholder[0], params, emphasised));
+                atLineStart = false;
+                i += placeholder[0].length;
+                continue;
+            }
+        }
+        if (ch === '\n') {
+            out.push(ch);
+            atLineStart = true;
+            i += 1;
+            continue;
+        }
+        if (atLineStart) {
+            // Leading whitespace does not end the line's opening position: `   # x` is
+            // a heading, and four spaces make an indented code block where the escape
+            // is visible but harmless. Counting the indent to tell those apart would
+            // be a second Markdown reader for one cosmetic case.
+            if (ch === ' ' || ch === '\t') {
+                out.push(ch);
+                i += 1;
+                continue;
+            }
+            atLineStart = false;
+            // A heading opens a section; a line of `=` or `-` alone makes a heading
+            // out of the line *above* it, which is the same forgery approaching from
+            // behind. A backslash before either renders the character and nothing else.
+            if (ch === '#' || SETEXT.test(lineAt(text, i))) {
+                out.push('\\');
+                continue;
+            }
+        }
+        out.push(ch === '<' ? '&lt;' : ch);
+        i += 1;
+    }
+    return out.join('');
+}
+/** A line that would turn the one above it into a heading. */
+const SETEXT = /^(?:=+|-+)[ \t]*$/;
+function lineAt(text, from) {
+    const end = text.indexOf('\n', from);
+    return end === -1 ? text.slice(from) : text.slice(from, end);
+}
+/**
+ * Where each code span in `text` ends, answered in constant time per question.
+ *
+ * The obvious implementation searches forward from the opening run for a run of
+ * the same length, and it is the ATX-59 defect in a second costume: a run that
+ * closes nothing scans to the end of the string, so prose whose runs are all of
+ * *different* lengths pays that for every one of them. Measured, before this:
+ * 500 KB of such a rationale took 1.6 s and 2 MB took 15 s — from `attest
+ * render` with no flag, on text the registry chooses.
+ *
+ * So the runs are read once and indexed by length, and each length keeps a
+ * cursor into its own list. Openers are visited left to right, so a cursor only
+ * ever moves forward and the total work is bounded by the number of runs. A
+ * shorter or longer run is not a closer and is never a candidate here, which is
+ * the CommonMark rule and also what stops a scanner believing in a span the
+ * renderer does not.
+ */
+function spanReader(text) {
+    const runs = [];
+    for (let i = 0; i < text.length; i += 1) {
+        if (text[i] !== '`')
+            continue;
+        const start = i;
+        while (text[i] === '`')
+            i += 1;
+        runs.push({ at: start, length: i - start });
+        i -= 1;
+    }
+    const byLength = new Map();
+    runs.forEach((run, index) => {
+        const list = byLength.get(run.length);
+        if (list === undefined)
+            byLength.set(run.length, [index]);
+        else
+            list.push(index);
+    });
+    const cursors = new Map();
+    let nextRun = 0;
+    return {
+        /** The end of the span opening at `at`, or the end of that run if none. */
+        spanEndAt: (at) => {
+            while (runs[nextRun].at < at)
+                nextRun += 1;
+            const opener = runs[nextRun];
+            const candidates = byLength.get(opener.length);
+            let cursor = cursors.get(opener.length) ?? 0;
+            while (cursor < candidates.length && candidates[cursor] <= nextRun)
+                cursor += 1;
+            cursors.set(opener.length, cursor);
+            const closer = cursor < candidates.length ? runs[candidates[cursor]] : undefined;
+            return closer === undefined ? at + opener.length : closer.at + closer.length;
+        },
+    };
+}
 /**
- * Substitute `{param}` placeholders with the actual value, emphasised so a
- * reader can see which words in the sentence are pinned to a single source.
+ * Substitute `{param}` placeholders in one region with `render`, the spelling
+ * that region's position calls for.
+ *
  * An unbound placeholder is left verbatim — `check` already reports it as an
  * `unbound-param` error, and silently swallowing it here would hide that.
  */
-function interpolate(statement, params) {
+function substitute(region, params, render) {
     // `Object.hasOwn`, never `in`: `'toString' in {}` is true, and an `in` probe
     // would splice `function toString() { [native code] }` into a document that
     // reviewers and audit read as the system's promise.
-    return statement.replace(/\{(\w+)\}/g, (whole, name) => Object.hasOwn(params, name) ? `**${plain(params[name])}**` : whole);
+    return region.replace(/\{(\w+)\}/g, (whole, name) => Object.hasOwn(params, name) ? render(params[name]) : whole);
+}
+/**
+ * A param value in prose position: escaped, and emphasised so a reader can see
+ * which words in the sentence are pinned to a single source.
+ *
+ * Escaped unlike the statement around it, because those are prose an author may
+ * want to mark up and a value is data that must survive verbatim — an unescaped
+ * `*` would otherwise break out of the emphasis it is wrapped in. `<` and `#`
+ * are in the class for the same reason the rest of it is: they are structure
+ * *here*. A value is spliced into a sentence, so a tag in one is a tag in the
+ * document, and a value carrying a newline puts what follows at the start of a
+ * line, where `#` opens a section (design §9.1).
+ */
+function emphasised(value) {
+    const one = (v) => v.replace(/([*_`[\]\\#])/g, '\\$1').replaceAll('<', '&lt;');
+    return `**${listed(value, (v) => one(inlineText(v)))}**`;
 }
 /**
- * A param value as prose, for inline use inside a statement. Escaped, unlike
- * the statement and rationale around it: those are prose an author may want to
- * mark up, a param value is data and must survive verbatim — an unescaped `*`
- * would otherwise break out of the emphasis it is wrapped in.
+ * A param value inside the author's code span: the value, and nothing added.
+ *
+ * A code span's contents are literal in every renderer, so escaping there is
+ * not merely unnecessary, it is *visible* — Markdown does not decode `&lt;`
+ * inside one, and this repository's own `ATX-30` renders a path with `<name>`
+ * in it. Emphasis is dropped for the same reason: `**` in a code span is two
+ * asterisks, which is what the document said before this knew where it was.
+ *
+ * The exception is a value that would end the span early — a backtick, or the
+ * blank line a code span cannot contain. There the author has asked for two
+ * incompatible things, and the prose escape is the safe answer rather than the
+ * pretty one: what follows the broken span is author text this pass has already
+ * walked past.
  */
-function plain(value) {
-    const one = (v) => v.replace(/([*_`[\]\\])/g, '\\$1');
-    return Array.isArray(value)
-        ? value.map((v) => one(inlineText(v))).join(', ')
-        : one(inlineText(value));
+function literal(value) {
+    const text = listed(value, inlineText);
+    return text.includes('`') || /\n[ \t]*\n/.test(text) ? emphasised(value) : text;
+}
+/** A list param reads as its members; a scalar reads as itself. */
+function listed(value, one) {
+    return Array.isArray(value) ? value.map(one).join(', ') : one(value);
 }
 /**
  * One param value as a run of text.
@@ -273,9 +444,7 @@ function inlineText(value) {
 function formatValue(value) {
     if (!isFlat(value))
         return '_see below_';
-    return Array.isArray(value)
-        ? value.map((v) => code(inlineText(v))).join(', ')
-        : code(inlineText(value));
+    return listed(value, (v) => code(inlineText(v)));
 }
 /**
  * A structured param as a fenced JSON block.

package/dist/core/skill.js

@@ -93,6 +93,15 @@ promises is a two-stage workflow, and the stages are separate on purpose.
   through any edit. Pin the expectation to something that does not move with the
   param — a fixture, a literal in the test, or a second independently derived
   value.
+- **A param the scenario loops over is the *domain* of the run, and shortening it
+  is silent.** Drop a member and you drop a case; every assertion inside the loop
+  still passes over what is left, with the expectation as independent as it ever
+  was — so the rule above does not reach this. Pin the extent beside the loop:
+  the members against a literal when their identity is the promise, the count
+  when the size is. That literal is **not** the hardcoded value stage 2's third
+  rule forbids, and the distinction is the whole of it — that rule is about the
+  **expectation** the system is measured against; this pin asserts what the
+  **intent** is.
 
 ## Rules the engine enforces
 
@@ -313,6 +322,16 @@ failure this framework exists to make visible:
    is the drift the single source exists to prevent, and the param is typed at
    the value written in the registry, so a stale expectation stops compiling
    rather than silently passing.
+   *This forbids one literal and not the other, and the difference decides
+   whether a domain can be shortened.* Forbidden is a literal standing in for the
+   param **as the value the system is measured against** — that is the second
+   copy. Required, when a scenario **iterates** a list it read from \`params\`, is
+   a literal pinning that list or its length beside the loop: the list is then
+   the set of cases the run covers rather than a value under test, and dropping a
+   member removes a case while every assertion inside still passes. A literal is
+   the only independent term available when what is at risk is the **size** of
+   the set, so the two never collide — one asserts what the system does, the
+   other what the intent promised.
    *One thing to know before implementation code reads a param this change
    ADDs:* the suite imports your \`*.reqs.ts\` from disk, while the gate applies
    the delta in memory — so that read throws at import and the gate answers

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

@@ -1,7 +1,7 @@
 import type { RegistryDelta } from './registry.js';
 import type { Registry } from './types.js';
 /** Codes this reader can produce; each is also produced by the evaluating path. */
-export type StaticReadCode = 'registry-invalid' | 'registry-no-default' | 'registry-not-static';
+export type StaticReadCode = 'registry-invalid' | 'registry-no-default' | 'registry-not-static' | 'unreadable-file';
 export type StaticReadResult = {
     ok: true;
     registry: Registry;
@@ -13,7 +13,7 @@ export type StaticReadResult = {
 };
 export declare function readRegistrySource(file: string, source: string): StaticReadResult;
 /** Codes the delta reader can produce; both are codes `archive` already emits. */
-export type DeltaReadCode = 'change-not-found' | 'registry-not-static';
+export type DeltaReadCode = 'change-not-found' | 'registry-not-static' | 'unreadable-file';
 export type DeltaReadResult = {
     ok: true;
     delta: RegistryDelta;
@@ -39,6 +39,38 @@ export type DeltaReadResult = {
  * (write the value inline, or `--eval`) is the same sentence either way.
  */
 export declare function readDeltaSource(file: string, source: string): DeltaReadResult;
+/**
+ * The requirement ids a source *declares*, read from a file that could not be
+ * read as a registry (design §5.3).
+ *
+ * This is not a second registry reader and cannot become one: it returns ids and
+ * nothing else, it validates none of them, and no command builds a `Registry`
+ * from what it finds. What it exists for is the question `orphan-test` cannot
+ * otherwise answer — is this scenario attesting an id that a *broken* file
+ * declares, or one that genuinely does not exist — and the answer decides
+ * whether a finding is a fact or fallout.
+ *
+ * It reads the ids rather than the file's id *prefix*, which is what this was
+ * first framed as needing. The prefix cannot be recovered from a path: this
+ * repository's own registry is `attest.reqs.ts` holding `ATX-*`, which is the
+ * evidence that killed the prefix-matches-filename rule (see CHANGELOG,
+ * `Considered and rejected`). The ids are in the source, so nothing has to be
+ * inferred from a naming convention that nothing enforces.
+ *
+ * Recall is partial by construction, and the direction of the miss is the point:
+ * an id it does not find keeps its `orphan-test`, so the report stays noisy —
+ * never wrong. Measured over the failure modes that produce an unreadable
+ * registry: a truncated file, a missing default export, a non-literal *value*, a
+ * schema-invalid entry, a module that throws at import, and a spread of ids from
+ * another module all yield the ids written in this file; only a registry built
+ * by a call — `export default buildReqs()` — yields none, and that file contains
+ * no id to find.
+ *
+ * `ts.createSourceFile` is deliberately error-tolerant, which is what lets the
+ * first of those cases work at all: the parser recovers an object literal from a
+ * file that does not compile.
+ */
+export declare function declaredIdsFromSource(file: string, source: string): string[];
 /**
  * Where a new entry may be written into a registry file's literal, as an offset
  * into its source (design §7).