@am_shork/attest 0.7.1 → 0.7.3

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.
 //
@@ -109,9 +109,13 @@ export async function runCheck(root, options = {}) {
     // 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);
+        const { plan, issues: unreadableSpecs } = await parseSpecs(scan.specFiles, root);
         return [
             ...issues,
+            // A spec the parser could not read is reported here rather than dropped:
+            // `check`'s contract is breadth, and a file silently contributing no
+            // scenarios reads as a file with no scenarios (ATX-65).
+            ...unreadableSpecs,
             // `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
@@ -220,7 +224,14 @@ async function unclaimedProposedSpecIssues(root, scan, options, loader) {
             for (const id of claimedIds(read.delta))
                 claimed.add(id);
     }
-    const proposed = await parseSpecs(scan.proposedSpecFiles, root);
+    const { plan: proposed, issues: unreadable } = await parseSpecs(scan.proposedSpecFiles, root);
+    issues.push(...unreadable);
+    // A file that would not parse declares no scenarios, so the loop below would
+    // find it claimed by nothing and call it unclaimed — a true sentence about a
+    // file whose real problem is that it could not be read, and a fix hint
+    // pointing at work that must not be done. Same shape as `orphan-test` after a
+    // registry fails to load (ATX-62), and refused here for the same reason.
+    const unreadableFiles = new Set(unreadable.map((i) => i.file));
     const claimedFiles = new Set(proposed.scenarios.filter((s) => claimed.has(s.reqId)).map((s) => s.file));
     // Reported per file, not per scenario: the file is the unit a run includes,
     // so it is the unit that did or did not execute, and one line per scenario
@@ -230,7 +241,7 @@ async function unclaimedProposedSpecIssues(root, scan, options, loader) {
     // nothing for a second reason, and reading the plan alone cannot see it.
     for (const abs of scan.proposedSpecFiles) {
         const file = relativePath(root, abs);
-        if (claimedFiles.has(file))
+        if (claimedFiles.has(file) || unreadableFiles.has(file))
             continue;
         issues.push({
             level: 'ERROR',
@@ -287,7 +298,9 @@ export async function runVerify(root, options = {}) {
         registry = loaded.registry;
         issues.push(...loaded.issues);
         unreadableFiles = loaded.unreadableFiles;
-        plan = await parseSpecs(scan.specFiles, root);
+        const parsedSpecs = await parseSpecs(scan.specFiles, root);
+        plan = parsedSpecs.plan;
+        issues.push(...parsedSpecs.issues);
     }
     finally {
         await loader.close();
@@ -365,7 +378,7 @@ export async function runCover(root, options = {}) {
     const { registry, issues: loadIssues } = await readRegistry(root, options, scan.reqsFiles);
     if (hasError(loadIssues))
         return { rows: [], issues: loadIssues };
-    const plan = await parseSpecs(scan.specFiles, root);
+    const { plan, issues: unreadableSpecs } = await parseSpecs(scan.specFiles, root);
     const counts = new Map();
     for (const s of plan.scenarios) {
         counts.set(s.reqId, (counts.get(s.reqId) ?? 0) + 1);
@@ -381,7 +394,7 @@ export async function runCover(root, options = {}) {
         covered: (counts.get(reqId) ?? 0) > 0,
         scenarioCount: counts.get(reqId) ?? 0,
     }));
-    return { rows, issues: [...loadIssues, ...uncoveredIssues(registry, plan)] };
+    return { rows, issues: [...loadIssues, ...unreadableSpecs, ...uncoveredIssues(registry, plan)] };
 }
 /**
  * Markdown projection of the intent layer (design §9: `attest render`).
@@ -437,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.
  *
@@ -607,10 +683,15 @@ function claimedByDelta(proposed, delta) {
  * walking the tree again, so a caller that already scanned does not repeat it.
  */
 async function changeMergedPlan(root, delta, scan) {
-    const basePlan = await parseSpecs(scan.specFiles, root);
-    const proposed = await parseSpecs(scan.proposedSpecFiles, root);
-    const claimed = claimedByDelta(proposed, delta);
+    const base = await parseSpecs(scan.specFiles, root);
+    const proposedSpecs = await parseSpecs(scan.proposedSpecFiles, root);
+    const basePlan = base.plan;
+    const claimed = claimedByDelta(proposedSpecs.plan, delta);
     return {
+        // A spec neither parse could read blocks the gate rather than vanishing
+        // from it: an unreadable proposed spec is a scenario the gate would
+        // otherwise report as absent (ATX-65).
+        issues: [...base.issues, ...proposedSpecs.issues],
         merged: {
             scenarios: [...basePlan.scenarios, ...claimed.scenarios],
             paramRefs: [...basePlan.paramRefs, ...claimed.paramRefs],
@@ -722,7 +803,12 @@ async function archiveRun(root, changeName, options = {}) {
         // 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 { merged: plan, claimed } = await changeMergedPlan(root, delta, scan);
+        const { merged: plan, claimed, issues: unreadableSpecs } = await changeMergedPlan(root, delta, scan);
+        // Before the run, not after: an unreadable spec means the gate cannot see
+        // what that file declared, so letting the suite start would grade the
+        // change against a plan known to be short (ATX-65).
+        if (unreadableSpecs.length > 0)
+            return { issues: unreadableSpecs };
         // 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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
   "type": "module",
   "engines": {