@am_shork/attest 0.4.0 → 0.4.2

package/README.md

@@ -21,8 +21,6 @@ the stronger property; noticing that it *moved* is `verify`'s job, and only when
 a scenario asserts on the value it read from `params`. Read the param inside the
 assertion, not beside it.
 
-See the authoritative design — [English](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/attest-design.md) · [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/attest-design.md) — and the rest of the [docs](https://gitlab.com/Pseudorca/attest/-/tree/main/docs).
-
 ## Prerequisites
 
 - Node ≥ 20.19
@@ -34,6 +32,14 @@ narrowed by 4, and ATX-36 — reading a registry opens no listening socket — i
 asserted against the Vite that is installed, so on any other major it is a claim
 rather than a measurement. If you are on Vitest 2 or 3, stay on `0.3.x`.
 
+The TypeScript compiler is a **bundled dependency**, not a peer — Attest reads
+your registries and specs through the compiler API, and `typescript@7` no longer
+exposes one (its AST moved behind `typescript/unstable/*`). So the supported
+range is `^5.5.0 || ^6.0.0`, both ends run in CI, and your own compiler is not
+involved: on a project already using TypeScript 5 or 6 the two resolve to one
+copy, and on TypeScript 7 you will simply have a second one that only Attest
+uses. Your project's TypeScript version is yours to choose either way.
+
 ## Getting started
 
 **Install** (the framework plus its `vitest` + `vite` peers):
@@ -43,9 +49,10 @@ pnpm add -D @am_shork/attest vitest vite
 ```
 
 **1. Declare a requirement** (`requirements/auth.reqs.ts`) — import the intent API
-from the vitest-free `/define` subpath so registry loading never touches the runtime.
-A registry is a **literal**: every value is written where you can read it (see
-[A registry is a literal](#a-registry-is-a-literal)):
+from the vitest-free `/define` subpath so registry loading never touches the
+runtime. A registry is a **literal**: every value is written where you can read
+it, because the commands below read it without executing it
+([why](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md#a-registry-is-a-literal)).
 
 ```ts
 import { defineRequirements } from '@am_shork/attest/define';
@@ -78,12 +85,6 @@ requirement('AUTH-3', () => {
 });
 ```
 
-`scenario` takes an optional third argument, a timeout in milliseconds, forwarded
-to Vitest's `it`. The run is isolated (see [What a run actually
-runs](#what-a-run-actually-runs)), so Vitest's default applies unless a scenario
-says otherwise — worth setting on anything that drives a subprocess, a container
-or a build.
-
 **3. Run the engine:**
 
 ```bash
@@ -97,31 +98,10 @@ attest archive <change>   # gate a proposed change: green + covered + no drift
 attest status <change>    # what that gate still wants, without running anything
 ```
 
-`<change>` names one directory inside `changes/` — it cannot be empty, `.`,
-`..`, or contain a path separator, since the name is interpolated into a path
-whose module the gate then loads and runs. Both commands check it before
-resolving anything on its behalf. Any other directory name is fine.
-
-`status` is the mid-flight view `archive` cannot give you: it reports each
-requirement the change adds as `no-scenario`, `unproven` (a scenario exists but
-has never been seen failing) or `proven`, reading the delta, the specs and
-`first-run.json` — no suite run, no project code. Every state is named after the
-issue the gate will raise, and it uses the gate's own predicate, so the two
-cannot disagree. What it deliberately cannot tell you is whether the tests pass:
-
-```console
-$ attest status add-2fa
-Change: add-2fa
-  ✓ AUTH-7  2 scenarios, seen red
-  ● AUTH-8  1 never run
-  ✗ AUTH-9  no scenario yet
-— 3 added requirements, 1 ready to archive
-Not a verdict: run `attest archive add-2fa` to run the suite.
-```
-
-It exits 0 there. Unmet obligations are the normal state of a change in flight,
-so they are rows, never a failing verdict — only a delta it could not read makes
-`status` fail. `archive` remains the one command that says "done".
+Every command takes the project root as an optional last argument, and `--json`
+for exactly one machine-readable document on stdout. Flags, per-command
+behaviour and the JSON shape are in the
+[CLI reference](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md).
 
 ### Working with an agent
 
@@ -130,274 +110,50 @@ agree on intent, write the delta, drive the scenarios red, then implement to
 green — and it is written for an agent to follow:
 
 ```bash
-attest init                        # .claude/skills/attest/SKILL.md
-attest init --target cursor        # .cursor/rules/attest.mdc
-attest init --target copilot       # .github/instructions/attest.instructions.md
+attest init                    # .claude/skills/attest/SKILL.md
+attest init --target cursor    # .cursor/rules/attest.mdc
+attest init --target copilot   # .github/instructions/attest.instructions.md
 ```
 
-Each target gets the same document; only the frontmatter differs, because that
-is the part the tool parses rather than the part the agent follows.
-
-That document carries the workflow: how to write a `changes/<name>/` delta, why
-its scenarios have to be red before you implement, what `attest archive` blocks
-on, and the three shortcuts that turn the gate green without changing anything.
 "Red before you implement" is enforced rather than advised: `archive` records how
 each of a change's scenarios ended on its first run, into
 `changes/<name>/first-run.json`, and blocks with `never-red` on any requirement
 the delta adds whose scenarios were never seen to fail. Commit `first-run.json`
 with the change — it is the evidence, and CI has to reach the same verdict as
 you do.
-An agent loads it on its own — its description is already in the agent's
-context, or its path matches what you have open — so nothing has to be found or
-pasted, and nothing is resident when you are working on something else.
-
-`--target` is repeatable, and a name that is not a known target writes nothing
-at all — an `unknown-target` error naming the ones that would have worked. An
-agent whose instructions live in a file your *project* owns — `AGENTS.md`,
-`CLAUDE.md` — is deliberately not a target: Attest writes whole files at paths it
-names and never edits a document you maintain, so what covers those is one line
-you add there yourself, pointing at the file above. It is cheaper than a
-generated block and it cannot go stale.
-
-There is deliberately **no `--check`**. The file is a function of the version you
-installed, so gating it would turn CI red on upgrades you did nothing to cause,
-and the remedy would be a commit containing no decision. `init` is idempotent
-instead: re-run it after upgrading, and that is the whole update mechanism.
-
-It also writes nothing else — no registry, no `package.json` scripts, no
-`changes/` skeleton. A generated registry is either empty (an `empty-spec` error
-on day one) or invented, and invented requirements are worse than none.
-
-### A registry is a literal
-
-`check`, `cover`, `render` and `status` read your `*.reqs.ts` files from their
-**source**, with the TypeScript compiler API. They never execute them. That is
-what makes `attest check` safe to run where its description implies you can —
-first in the pipeline, on an untrusted fork MR, outside whatever sandbox you give
-the tests. (`verify` and `archive` do run your suite, so they read the registry by
-evaluating it: there is nothing left to protect at that point.)
-
-The cost is a contract: every value in a registry must be written in the
-registry.
-
-```ts
-import { MAX_MB } from '../src/config.js';
-
-export default defineRequirements({
-  'UP-1': {
-    statement: 'An upload SHALL be rejected above {maxMb} MB.',
-    rationale: 'Protect the storage tier from unbounded writes.',
-    params: { maxMb: MAX_MB }, // ✗ registry-not-static
-  },
-});
-```
-
-This is reported as a `registry-not-static` ERROR pointing at the line. It is
-not only a tooling limit: the single-source rule says the requirement owns that
-number, and importing it says the application owns it. Inline the value and read
-it from the registry in your code — that is the fix. If you need the old
-behaviour instead, `--eval` restores it on every one of those commands:
-
-```bash
-attest check --eval    # reads the registry by executing every *.reqs.ts
-```
-
-`--eval` changes *how* the registry is obtained, never what counts as one: whatever
-the module exports goes through the same schema, so a malformed registry is a
-`registry-invalid` ERROR under both readers rather than a crash under one of them.
-
-**The same rule covers a change's `requirements.delta.ts`**, because `status`
-reads that file the same way — a delta built from an imported constant is the
-same `registry-not-static` ERROR, with the same `--eval` way out. The reason is
-sharper there than it is for a registry: `changes/` holds a proposal nobody has
-agreed to yet, so a command whose only job is to report on it is the last thing
-that should execute it. `archive` evaluates the delta regardless — it is about to
-run your suite anyway.
-
-One more thing to know about literals: write registry prose as **one long
-single-line string**. A template literal with no substitution reads statically and
-is accepted — but it keeps every newline and every space of indentation inside it,
-and `render` puts the statement into the Markdown exactly as written, so the
-wrapping that looked tidy in the editor lands in the generated document.
-
-### Each registry file owns its id prefix
-
-You can split intent across as many `*.reqs.ts` as you like — every one under the
-project root is read and merged. What you cannot do is have two of them declare
-the same prefix:
-
-```ts
-// requirements/auth.reqs.ts
-export default defineRequirements({ 'AUTH-3': { /* … */ } });
 
-// requirements/session.reqs.ts
-export default defineRequirements({ 'AUTH-9': { /* … */ } }); // ✗ duplicate-prefix
-```
-
-An id is `PREFIX-n` and nothing above the requirement gives that prefix a
-meaning, so two files declaring one are two owners of a single space. The ids
-above are distinct and every other check passes; what you find out later is that
-`AUTH-9` was taken the day someone's counter reached it, in a file they were not
-looking at. The ERROR names both files, and the fix is a prefix of your own —
-`SESS-1` — not a move or a rename.
-
-`duplicate-requirement` is the narrower one still there for the same id in two
-files. Nothing requires the prefix to match the file's name; `attest.reqs.ts`
-holding `ATX-*` is fine, here and in your repo.
-
-### A readable spec for humans (`attest render`)
-
-The intent layer lives in TypeScript, which means a reviewer, a QA engineer, or
-anyone doing an audit cannot read it. `render` projects the registry into one
-Markdown document — an index of every requirement, then each one with its
-statement, rationale, params and out-of-scope notes:
-
-```bash
-attest render                       # to stdout
-attest render --out docs/SPEC.md    # to a file
-attest render --out docs/SPEC.md --check   # fail if that file is out of date
-```
-
-The rendering **substitutes params into the statement**, so the document says
-"after **30** minutes" where the source says `{idleTimeoutMin}` — the number a
-reader actually wants, still from the single source.
-
-Three properties this deliberately keeps:
-
-- **One-way.** Markdown is only ever an output. Nothing reads it back, so the
-  free-form-prose drift that a Markdown *source* invites stays out.
-- **Intent only.** No coverage, no counts, no test locations, no pass/fail —
-  those are verdicts, and `cover` / `verify` recompute them on demand. So the
-  document is a pure function of your `*.reqs.ts` files and changes if and only
-  if intent changes: one readable hunk per registry edit, and never a rewrite
-  because a line moved in a test file.
-- **Gated.** A generated file you commit is a new place for drift to hide, so
-  `--check` regenerates and compares, failing with `stale-spec-doc` if the
-  committed document no longer matches the registry, or `missing-spec-doc` if it
-  was never generated. It compares the document, not the bytes: line endings are
-  a property of your checkout (`core.autocrlf` is on by default on Windows), and
-  a gate that calls a fresh clone stale is worse than no gate.
-  Put it in CI next to `attest check`. (Attest does this to itself:
-  [`self/requirements/SPEC.md`](https://gitlab.com/Pseudorca/attest/-/blob/main/self/requirements/SPEC.md)
-  is generated, and the pipeline fails if it goes stale.)
-
-The Markdown is prose for humans and its formatting is not a stable contract —
-don't parse it. `--json` is the machine surface.
-
-### What a run actually runs
-
-`verify` executes **only the spec files that declare a `requirement()`**. A repo
-that already has a test suite keeps it: those files are located, reported, and
-left alone — Attest is not a general test runner, and running someone's suite in
-a child process with no aliases and no DOM only ever produced a red about code it
-was never pointed at. `archive` uses the same scope.
-
-Every run says so, before the issues:
-
-```
-Running 12 spec files (30 without a requirement(), not run)
-✓ No issues.
-— 20 requirements / 41 scenarios, 0 error, 0 warning, 0 info
-```
+An agent loads the document on its own — its description is already in the
+agent's context, or its path matches what you have open — so nothing has to be
+found or pasted. See
+[`attest init`](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md#attest-init)
+for the targets and what `init` deliberately does not write.
 
-The gap between the two numbers is worth watching: a spec file whose
-`requirement()` call Attest cannot see statically is skipped rather than failed,
-and that is where it shows. The same four numbers are in `--json` under `counts`.
+### When something goes wrong
 
-When three or more issues in one report share a level and a code, one line above
-the counts says so, because a wall of identical codes is one rule and many sites:
+Every diagnostic carries a `code`, and every code has a section in
+**Troubleshooting** — which the diagnostic itself links to:
 
 ```
-Repeated: 6 × ERROR registry-not-static, 4 × WARNING rationale-placeholder
+ERROR   registry-not-static (requirements/upload.reqs.ts:5)
+    Value is not a literal.
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.4.2/docs/en/troubleshooting.md#registry-not-static
 ```
 
-Every per-issue line stays exactly as it is — they are what makes a diagnostic
-clickable — and the summary is terminal output only: it is not an issue, so it
-appears nowhere in `--json`, changes no count, and never moves a verdict.
+The anchor **is** the code, so the link cannot point somewhere the section
+isn't. In `--json` the same link is on each issue as `docsUrl`.
 
-A run with **no requirements** under the root is an `empty-spec` ERROR, not a
-pass. "No failing tests" is not the same claim as "the requirements hold", and
-the case that matters is not the empty directory — it is the repo whose registry
-quietly stopped being found, where the tests still run and still go green.
+## Documentation
 
-### Framework code (`.vue`, DOM, path aliases)
-
-The child run isolates from any ambient config by default, so specs run in a bare
-Vite/Vitest environment — no `.vue` transform, DOM, or `~/`/`@/` aliases. When
-your specs need that environment, point `verify` (or `archive`) at a config:
-
-```bash
-attest verify --vitest-config vitest.config.ts
-```
-
-The config supplies the environment (plugins, `resolve.alias`, `test.environment`);
-Attest still owns the run scope — `include`/`exclude`/`root` always win, so a
-config cannot pull in your existing suite or un-exclude `changes/`. Without the
-flag the run stays isolated and deterministic.
-
-### Machine-readable output
-
-Every command that produces a verdict takes `--json` and then writes exactly one
-JSON document to stdout — same work, same exit code. Branch on `ok`,
-`issues[].code` and `issues[].reqId`; never parse `message`, which is prose and
-may be reworded. (`render` is the one exception, because its own output is a
-document: there, `--json` needs `--out` or `--check`, so stdout still carries
-exactly one thing.)
-
-```bash
-attest check --json
-```
-
-```json
-{
-  "tool": "attest",
-  "schemaVersion": 1,
-  "version": "0.4.0",
-  "command": "check",
-  "ok": false,
-  "summary": { "error": 1, "warning": 0, "info": 0 },
-  "issues": [
-    {
-      "level": "ERROR",
-      "code": "orphan-test",
-      "reqId": "PLAN-2",
-      "file": "auth/session.spec.ts",
-      "line": 12,
-      "message": "scenario \"…\" attests unknown requirement \"PLAN-2\". …"
-    }
-  ]
-}
-```
+| Document | English | 中文 |
+|---|---|---|
+| **CLI reference** — every command, flag and JSON field | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/cli-reference.md) |
+| **Troubleshooting** — one section per issue code | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/troubleshooting.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/troubleshooting.md) |
+| **Design** — the authoritative design of the framework | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/attest-design.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/attest-design.md) |
+| **Feedback template** — report how adoption actually went | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/feedback.template.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/feedback.template.md) |
 
-`verify` adds `passed` (was the test run itself green, independent of the
-overall verdict) and `counts` (`requirements`, `scenarios`, `specFiles`,
-`attesting`); `cover` adds `coverage[]` — one `{ reqId, covered,
-scenarioCount }` row per requirement — plus a `requirements` roll-up;
-`archive` adds `change`; `status` adds `change`, `progress[]` — one
-`{ reqId, state, scenarios[] }` row per added requirement, each scenario
-carrying its recorded `firstRun` (`"fail"`, `"pass"`, or `null` for never
-observed) — plus an `added` roll-up; `render` and `init` add `outFile` — the
-file the command wrote, and never its contents — and `init` adds `outFiles`,
-every file it wrote, since it can be asked for more than one agent target at
-once (`outFile` is still there whenever exactly one was written).
-`schemaVersion` is bumped on any breaking change to
-the shape. The TypeScript type is exported as `JsonReport`.
-
-`ok` means the same thing everywhere: the report carries no `ERROR`. So an
-uncovered requirement reaches a `cover` report twice — as a `covered: false`
-row and as an `uncovered-requirement` issue — because the rule above is to
-branch on `issues[].code`, and a command that answered `ok: false` with an
-empty `issues` array would make you read `coverage[]` to find out why.
-
-`status` is the one report whose rows are deliberately *not* issues. Its rows
-describe a change in progress, and a change in progress has unmet obligations by
-definition; carrying them as errors would make `status` exit 1 for the whole life
-of every change, and put a second verdict beside `archive`'s. Its `issues` carry
-only the reasons the report could not be produced.
-
-Even when a command crashes, `--json` still writes one parseable envelope
-(`ok: false` with an `internal-error` issue) rather than an empty stdout — so a
-consumer can always parse stdout and branch on `ok`.
+The change workflow is not here: it is what `attest init` writes into your
+project, as a skill, a rule or an instructions file, depending on which agent
+reads it.
 
 ## Development
 
@@ -430,12 +186,12 @@ from `pnpm test`; it runs in CI and as `prepublishOnly`.
 ## Feedback
 
 Adoption reports drive the roadmap. After using Attest on a real project, fill in
-the feedback template — [English](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/feedback.template.md) · [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/feedback.template.md) —
-and open it as an issue (it is also the **Usage feedback** issue template). It
-covers greenfield and mid-project adoption alike, and ends with a prompt to run
-inside the adopting repo that fills most of the report automatically and probes
-for problems you haven't hit yet. The highest-value part is **false negatives**:
-drift the engine should have caught and didn't.
+the feedback template (linked above) and open it as an issue — it is also the
+**Usage feedback** issue template. It covers greenfield and mid-project adoption
+alike, and ends with a prompt to run inside the adopting repo that fills most of
+the report automatically and probes for problems you haven't hit yet. The
+highest-value part is **false negatives**: drift the engine should have caught
+and didn't.
 
 ## Acknowledgments
 

package/dist/cli/index.js

@@ -13,9 +13,9 @@ import { resolve } from 'node:path';
 import { writeAtomic } from '../core/write.js';
 import { runCheck, runVerify, runCover, runArchive, runInit, runRender, runRenderCheck, runStatus, DEFAULT_TARGET, TARGET_NAMES, } from '../core/pipeline.js';
 import { hasError } from '../core/types.js';
-import { formatIssues, formatScope, summarize, formatCoverage, formatStatus, } from './report.js';
+import { formatCrash, formatIssues, formatScope, summarize, formatCoverage, formatStatus, } from './report.js';
 import { archiveReport, checkReport, coverReport, errorReport, initReport, renderJson, renderReport, statusReport, verifyReport, } from './json.js';
-import { packageVersion } from './version.js';
+import { packageVersion } from '../core/version.js';
 const VERSION = packageVersion();
 const program = new Command();
 program
@@ -60,10 +60,12 @@ async function runAction(command, opts, action) {
     }
     catch (err) {
         if (opts.json) {
+            // Unsanitised on purpose: `JSON.stringify` escapes every C0 character, so
+            // the machine surface was never the exposed one (see report.ts).
             console.log(renderJson(errorReport(VERSION, command, err)));
         }
         else {
-            console.error(chalk.red(err instanceof Error ? err.stack ?? err.message : String(err)));
+            console.error(formatCrash(err));
         }
         process.exitCode = 1;
     }
@@ -284,8 +286,10 @@ program
 }));
 program.parseAsync().catch((err) => {
     // Last resort for failures outside a command action (e.g. arg parsing), which
-    // are not part of the per-command `--json` contract.
-    console.error(chalk.red(err instanceof Error ? err.stack ?? err.message : String(err)));
+    // are not part of the per-command `--json` contract. Through the same
+    // formatter as the per-command path: this one is reached with a project root
+    // already resolved, so it is no less able to carry the repository's text.
+    console.error(formatCrash(err));
     process.exitCode = 1;
 });
 //# sourceMappingURL=index.js.map

package/dist/cli/json.js

@@ -5,6 +5,7 @@
 // The shape is a contract: `schemaVersion` is bumped on any breaking change,
 // and every command emits the same envelope (tool/version/command/ok/summary/
 // issues) plus command-specific fields.
+import { docsUrl } from '../core/docs.js';
 import { hasError } from '../core/types.js';
 /** Bumped whenever the emitted shape changes incompatibly. */
 export const SCHEMA_VERSION = 1;
@@ -19,15 +20,38 @@ export function countLevels(issues) {
         summary[LEVEL_KEY[i.level]]++;
     return summary;
 }
+/**
+ * Attach the page that explains each code (design §5.3).
+ *
+ * Done here rather than at the ~20 sites that construct an `Issue`, for the
+ * reason `hasError` is one function: a property every report shares should have
+ * one place to be wrong. Every JSON report is built through this envelope —
+ * including the `internal-error` crash path — so there is no command that emits
+ * issues without going past this line.
+ *
+ * Non-mutating, and an issue that already carries a `docsUrl` keeps it: the
+ * argument arrays belong to the caller, and one of them is a pipeline result a
+ * human rendering may read afterwards.
+ */
+function withDocs(issues) {
+    return issues.map((i) => {
+        const url = i.docsUrl ?? docsUrl(i.code);
+        return url === undefined ? i : { ...i, docsUrl: url };
+    });
+}
 function envelope({ version, command, ok, issues = [] }) {
+    const documented = withDocs(issues);
     return {
         tool: 'attest',
         schemaVersion: SCHEMA_VERSION,
         version,
         command,
         ok,
+        // Counted from the input, not the decorated copy: the two have the same
+        // length by construction, and counting what was passed in keeps the summary
+        // a function of the issues rather than of the decoration.
         summary: countLevels(issues),
-        issues,
+        issues: documented,
     };
 }
 export function checkReport(version, issues) {

package/dist/cli/report.d.ts

@@ -1,5 +1,25 @@
 import type { CoverageRow, StatusResult, VerifyCounts } from '../core/pipeline.js';
 import type { Issue } from '../core/types.js';
+/**
+ * A caught error, as it may be written to a terminal.
+ *
+ * The crash path was the hole in the guarantee above, and the least obvious
+ * place for one: every diagnostic went through `block`, and then the two
+ * `catch` blocks in the CLI printed `err.stack` raw. Under `verify`, `archive`
+ * or `--eval` that stack is not Attest's prose — a module from the repository
+ * under test threw it, so its message is that repository's text, arriving at
+ * the reviewer's terminal with nothing removed. The path a hostile registry
+ * reaches most easily is the one where it throws.
+ *
+ * `block`, not a rule of its own: a stack is exactly what that function is for
+ * — a multi-line message whose continuations must not be able to occupy the
+ * column a real header sits in. Frames indent by four more spaces than they
+ * already do, which is the whole cost.
+ *
+ * Here rather than in the CLI because this file is where the decision lives.
+ * Two `catch` blocks with a copy each is how the first one came to be missed.
+ */
+export declare function formatCrash(err: unknown): string;
 export declare function formatIssues(issues: Issue[]): string;
 /**
  * A code repeating across files is one rule and many sites, and a reader looking

package/dist/cli/report.js

@@ -1,63 +1,51 @@
 // Terminal rendering of graded issues (design §5.3 levels). Pure formatting —
 // no process side effects — so it stays testable and the CLI stays thin.
 import chalk from 'chalk';
+import { docsUrl } from '../core/docs.js';
 import { byCodeUnit } from '../core/order.js';
+import { INDENT, block, inline } from '../core/terminal.js';
 const LEVEL_TAG = {
     ERROR: (s) => chalk.red.bold(s),
     WARNING: (s) => chalk.yellow.bold(s),
     INFO: (s) => chalk.blueBright(s),
 };
 const ORDER = ['ERROR', 'WARNING', 'INFO'];
-/** The one control character a report keeps: see `block`. */
-const NEWLINE = 0x0a;
-/** How far a message is indented under its header line. */
-const INDENT = '    ';
+// `block` / `inline` live in core/terminal.ts: the loader has to make the same
+// decision about Vite's log output and cannot import from this layer.
 /**
- * Text from the project, on its way to a terminal.
+ * The line under a message pointing at the section that explains the code.
  *
- * Most of what a report prints is Attest's own prose, but the parts a reader
- * actually navigates by are not: a scenario name and a file path are quoted
- * verbatim out of the repository under test (`orphan-test`, `declared-not-run`,
- * `never-red`), and the parser hands back the *cooked* string, so an ESC
- * written as an escape in a spec file is a real control byte by the time it
- * arrives here.
- *
- * That makes the human report a place where the repository being checked can
- * write to the terminal of whoever is checking it. On a fork MR the author is
- * not the reviewer, and the payload is a scenario name: erase the lines above,
- * repaint a red verdict green, rewrite the window title. The `--json` path was
- * never exposed — `JSON.stringify` escapes every C0 character — which is
- * precisely why this had to be fixed on the side people read.
- *
- * A newline survives, because one diagnostic is legitimately multi-line:
- * `registry-invalid` carries Zod's list of field errors, and flattening it
- * would cost a real reader a real thing to save a hypothetical one. It is
- * re-indented instead, so injected text lands inside the message block rather
- * than at column 0 where a forged `ERROR ...` header would be indistinguishable
- * from a real one.
+ * Dim and last, so it never competes with the file:line above it — that is what
+ * a reader navigates by, and this is what they reach for once navigating did not
+ * settle it. Not sanitised through `inline`, unlike everything else on these
+ * lines: it is derived from a fixed roster, so unlike a scenario name or a path
+ * it never contains a byte the repository under test chose.
  */
-function block(text) {
-    return control(text).replaceAll('\n', `\n${INDENT}`);
-}
-/** The same, for text that sits inline in a header and must stay one line. */
-function inline(text) {
-    return control(text).replaceAll('\n', ' ');
+function docsLine(issue) {
+    const url = issue.docsUrl ?? docsUrl(issue.code);
+    return url ? `\n${INDENT}${chalk.dim(`→ ${url}`)}` : '';
 }
 /**
- * Every C0 control except the newline, plus DEL and the C1 range, as a space.
+ * A caught error, as it may be written to a terminal.
  *
- * A space rather than deletion: removing the byte would silently splice
- * `atte` + `st` into a word that was never in the file, and a diagnostic that
- * quietly rewrites what it quotes is its own kind of wrong.
+ * The crash path was the hole in the guarantee above, and the least obvious
+ * place for one: every diagnostic went through `block`, and then the two
+ * `catch` blocks in the CLI printed `err.stack` raw. Under `verify`, `archive`
+ * or `--eval` that stack is not Attest's prose — a module from the repository
+ * under test threw it, so its message is that repository's text, arriving at
+ * the reviewer's terminal with nothing removed. The path a hostile registry
+ * reaches most easily is the one where it throws.
+ *
+ * `block`, not a rule of its own: a stack is exactly what that function is for
+ * — a multi-line message whose continuations must not be able to occupy the
+ * column a real header sits in. Frames indent by four more spaces than they
+ * already do, which is the whole cost.
+ *
+ * Here rather than in the CLI because this file is where the decision lives.
+ * Two `catch` blocks with a copy each is how the first one came to be missed.
  */
-function control(text) {
-    return [...text]
-        .map((ch) => {
-        const c = ch.codePointAt(0);
-        const isControl = (c < 0x20 && c !== NEWLINE) || (c >= 0x7f && c <= 0x9f);
-        return isControl ? ' ' : ch;
-    })
-        .join('');
+export function formatCrash(err) {
+    return chalk.red(block(err instanceof Error ? err.stack ?? err.message : String(err)));
 }
 export function formatIssues(issues) {
     if (issues.length === 0)
@@ -67,7 +55,7 @@ export function formatIssues(issues) {
         for (const i of issues.filter((x) => x.level === level)) {
             const where = i.file ? `${inline(i.file)}${i.line ? `:${i.line}` : ''}` : '';
             const loc = where ? chalk.dim(` (${where})`) : '';
-            lines.push(`${LEVEL_TAG[level](level.padEnd(7))} ${chalk.cyan(inline(i.code))}${loc}\n${INDENT}${block(i.message)}`);
+            lines.push(`${LEVEL_TAG[level](level.padEnd(7))} ${chalk.cyan(inline(i.code))}${loc}\n${INDENT}${block(i.message)}${docsLine(i)}`);
         }
     }
     const repeats = formatRepeats(issues);