spec-ctx 0.4.0 → 0.5.0

package/dist/index/build.js

@@ -1,14 +1,39 @@
-// REQ-IDX-001 REQ-IDX-002 REQ-IDX-004 build, write, and load .ctx/index.json.
+// REQ-IDX-001 REQ-IDX-002 REQ-IDX-004 REQ-IDX-014 build, write, and load .ctx/index.json.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { fsNowMs, mtimeMsOf, pause, setMtimeMs } from "./clock.js";
 import { join } from "node:path";
 import { dumps } from "../util/json.js";
 import { cmpStr, cmpTuple } from "../util/pystr.js";
 import { markCanonical } from "./canonical.js";
+import { addStructure } from "./structure.js";
 import { scanMarkdown, scannedOf, scanner, scanSource, walk } from "./scan.js";
 export const INDEX_PATH = ".ctx/index.json";
-export function buildIndex(root, cfg, files, sc) {
+/** REQ-IDX-014 the most that a file mtime may pass the clock reading of a build and still count as a write in its tick. */
+const TICK_MS = 50;
+/** REQ-IDX-014 the most waits of 2 ms for the file clock to pass the newest mtime: 100 ms in all. */
+const MAX_PAUSES = 50;
+/**
+ * REQ-IDX-004 build and write the index. `t0` is the clock reading taken before the walk of `files`. The index file gets
+ * `t0` as its mtime, so a write in the same tick as the build, or during it, leaves a file at or after that mtime (049/D2).
+ * A newest file 0 to 50 ms after `t0` makes the build wait until the file clock passes it, then take `t0` again (049/D4).
+ * A file far after `t0`, such as one dated in the future, gets no wait. Only file clock readings enter this logic.
+ */
+export function buildIndex(root, cfg, files, sc, t0) {
     const s = sc ?? scanner(root, cfg);
+    let at = t0 ?? fsNowMs(root);
     const list = files ?? walk(s);
+    const newest = scannedOf(root, list).newest_mtime_ms;
+    if (newest >= at && newest - at <= TICK_MS) {
+        for (let i = 0; i < MAX_PAUSES; i++) {
+            at = fsNowMs(root);
+            if (at > newest)
+                break;
+            pause(2);
+        }
+    }
+    return buildOnce(root, cfg, list, s, at);
+}
+function buildOnce(root, cfg, list, s, t0) {
     const entries = [];
     const problems = [];
     const scnNamed = new Set();
@@ -18,6 +43,7 @@ export function buildIndex(root, cfg, files, sc) {
         else
             scanSource(s, f.path, entries, scnNamed);
     }
+    addStructure(entries, list);
     markCanonical(entries);
     entries.sort((a, b) => cmpTuple([a.id, a.file, a.line], [b.id, b.file, b.line]));
     const uniq = new Map();
@@ -32,10 +58,12 @@ export function buildIndex(root, cfg, files, sc) {
     };
     mkdirSync(join(root, ".ctx"), { recursive: true });
     writeFileSync(join(root, INDEX_PATH), dumps(data) + "\n");
+    setMtimeMs(join(root, INDEX_PATH), t0);
     return data;
 }
 /** REQ-IDX-004 compare the stored scan record with a fresh stat walk. Rebuild on a mismatch. */
 export function loadIndex(root, cfg) {
+    const t0 = fsNowMs(root);
     const sc = scanner(root, cfg);
     const files = walk(sc);
     const p = join(root, INDEX_PATH);
@@ -50,8 +78,9 @@ export function loadIndex(root, cfg) {
     }
     const fresh = scannedOf(root, files);
     if (data === null || !data.scanned || data.scanned.count !== fresh.count
-        || data.scanned.newest_mtime_ms !== fresh.newest_mtime_ms || Object.keys(data.scanned).length !== 2) {
-        return { data: buildIndex(root, cfg, files, sc), rebuilt: true };
+        || data.scanned.newest_mtime_ms !== fresh.newest_mtime_ms || Object.keys(data.scanned).length !== 2
+        || fresh.newest_mtime_ms >= (mtimeMsOf(p) ?? 0)) {
+        return { data: buildIndex(root, cfg, files, sc, t0), rebuilt: true };
     }
     return { data, rebuilt: false };
 }

package/dist/index/clock.js

@@ -0,0 +1,55 @@
+// REQ-IDX-014 the file system clock. A write gets its mtime from a coarse kernel clock, so two writes in one tick
+// share an mtime. The index keeps the clock reading of the start of its build as its own mtime (049/D2).
+import { closeSync, mkdirSync, openSync, statSync, unlinkSync, utimesSync } from "node:fs";
+import { join } from "node:path";
+/** Whole milliseconds of an mtime in nanoseconds. */
+export function msOf(ns) {
+    return Number(ns / 1000000n);
+}
+/**
+ * The time of the file system clock in whole milliseconds: create one file in `.ctx/`, stat it, delete it. When the
+ * clock cannot be read, the value is one second before `Date.now()`. An earlier value can only cause an extra rebuild.
+ */
+export function fsNowMs(root) {
+    const dir = join(root, ".ctx");
+    const f = join(dir, `.clock-${process.pid}`);
+    try {
+        mkdirSync(dir, { recursive: true });
+        try {
+            unlinkSync(f);
+        }
+        catch {
+            // no old file
+        }
+        closeSync(openSync(f, "wx"));
+        const ms = msOf(statSync(f, { bigint: true }).mtimeNs);
+        try {
+            unlinkSync(f);
+        }
+        catch {
+            // the reading stays
+        }
+        return ms;
+    }
+    catch {
+        return Date.now() - 1000;
+    }
+}
+/** Set the mtime of a file to a whole number of milliseconds. Half a millisecond is added so that rounding keeps the value. */
+export function setMtimeMs(path, ms) {
+    const t = (ms + 0.5) / 1000;
+    utimesSync(path, t, t);
+}
+/** The mtime of a file in whole milliseconds, or null when it is absent. */
+export function mtimeMsOf(path) {
+    try {
+        return msOf(statSync(path, { bigint: true }).mtimeNs);
+    }
+    catch {
+        return null;
+    }
+}
+/** Sleep for a few milliseconds. The engine has no timer, so this blocks on a wait cell. */
+export function pause(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}

package/dist/index/scan.js

@@ -15,13 +15,15 @@ const SCN_HDR = new RegExp(`^#### Scenario:${S}*(?:(SCN-[A-Z]{2,6}-\\d{3}-\\d+)|
 const ADR_HDR = new RegExp(`^# (ADR-\\d{3})${S}+(.*)$`, "s");
 const REFS_RE = new RegExp(`^Refs:${S}*(.+)$`, "s");
 const TASK_REQ = new RegExp(`\\[(REQ-[A-Z]{2,6}-\\d{3}(?:${S}*,${S}*REQ-[A-Z]{2,6}-\\d{3})*)\\]`, "g");
-const CODE_TAG = new RegExp(`(?://|#|/\\*|\\*)${S}*(REQ-[A-Z]{2,6}-\\d{3})`);
+// REQ-IDX-008 the first marker and ID start the tag. Every REQ ID to the end of the line counts, with word boundaries (045/D5).
+const CODE_TAG = new RegExp(`(?://|#|/\\*|\\*)${S}*(REQ-[A-Z]{2,6}-\\d{3})\\b`);
+const CODE_SPAN = /`([^`]+)`/g;
 // REQ-IDX-007 the rest of the line after Covers:, and each REQ ID in it with word boundaries (042/D4)
 const COVER_TAG = /Covers:(.*)$/s;
 const REQ_ID = /\bREQ-[A-Z]{2,6}-\d{3}\b/g;
 const SENTENCE_END = new RegExp(`(?<=[.!?])${S}`);
 const COMMA = new RegExp(`${S}*,${S}*`);
-const SKIP_DIRS = new Set(["node_modules", ".git"]);
+const SKIP_DIRS = new Set(["node_modules", ".git", ".ctx"]);
 export function scanner(root, cfg) {
     const s = cfg.scan;
     const all = [...s.specs, ...s.changes, ...s.decisions, ...s.code, ...s.tests];
@@ -295,15 +297,23 @@ export function scanMarkdown(sc, rpath, entries, problems) {
             const reqs = [];
             for (const g of body.matchAll(TASK_REQ))
                 reqs.push(...g[1].split(COMMA));
-            if (reqs.length === 0)
-                problems.push([rpath, i, "task-without-req", tid]);
-            if (!body.includes("Verify:"))
-                problems.push([rpath, i, "task-without-verify", tid]);
+            // REQ-CHK-001 an archived task is history: no citation finding
+            if (status !== "archived") {
+                if (reqs.length === 0)
+                    problems.push([rpath, i, "task-without-req", tid]);
+                if (!body.includes("Verify:"))
+                    problems.push([rpath, i, "task-without-verify", tid]);
+            }
             // the full task body is the title, so query output shows the Verify clause
-            entries.push(entry({
+            const t = entry({
                 id: tid, kind: "task", file: rpath, line: i, title: pyStrip(body), change,
                 status: pyStrip(box).toLowerCase() === "x" ? "done" : "open", refs: reqs,
-            }));
+            });
+            // REQ-IDX-009 an active task records the paths that its line names in backticks
+            const paths = status === "archived" ? [] : taskPaths(body);
+            if (paths.length)
+                t.paths = paths;
+            entries.push(t);
         }
     }
     // REQ-IDX-002 text holds the lower-cased body of each block
@@ -325,6 +335,20 @@ export function scanMarkdown(sc, rpath, entries, problems) {
         }
     }
 }
+/** REQ-IDX-009 code spans with no space and no `*` that hold a `/` or a `.`. A leading `./` is dropped. */
+export function taskPaths(body) {
+    const out = new Set();
+    for (const m of body.matchAll(CODE_SPAN)) {
+        let t = m[1];
+        if (/[ \t\n\r\f\v*]/.test(t) || !(t.includes("/") || t.includes(".")))
+            continue;
+        while (t.startsWith("./"))
+            t = t.slice(2);
+        if (t)
+            out.add(t);
+    }
+    return [...out].sort(cmpStr);
+}
 export function isTestPath(sc, rpath) {
     const name = rpath.slice(rpath.lastIndexOf("/") + 1);
     return anyMatch(sc.tests, rpath) || rpath.includes("/tests/") || rpath.startsWith("tests/")
@@ -360,7 +384,10 @@ export function scanSource(sc, rpath, entries, scnNamed) {
         }
         const m = CODE_TAG.exec(line);
         if (m && !line.includes("Covers:")) {
-            entries.push(entry({ id: `${rpath}:${i}`, kind: "code", file: rpath, line: i, title: pyStrip(line), change: "main", status: "active", refs: [m[1]] }));
+            const ids = [...new Set(line.slice(m.index).match(REQ_ID) ?? [])];
+            for (const rid of ids) {
+                entries.push(entry({ id: `${rpath}:${i}`, kind: "code", file: rpath, line: i, title: pyStrip(line), change: "main", status: "active", refs: [rid] }));
+            }
         }
     }
 }

package/dist/index/structure.js

@@ -0,0 +1,97 @@
+// REQ-IDX-010 REQ-IDX-012 REQ-IDX-013 change entries, capability entries, and the design links of tasks.
+import { cmpStr } from "../util/pystr.js";
+import { changeKey, changeOf, resolveChange, taskPaths } from "./scan.js";
+const CHANGE_DIR = /^(openspec\/changes\/(?:archive\/)?[^/]+)\//;
+const ARCHIVE_DATE = /^openspec\/changes\/archive\/(\d{4}-\d{2}-\d{2})-/;
+const CAP_SPEC = /(?:^|\/)specs\/([^/]+)\/spec\.md$/;
+// REQ-IDX-012 a full name `<key>/D<n>` or a bare `D<n>`. A bare D follows no letter, digit, slash, or hyphen.
+const FULL_DESIGN = /(?<![\w/-])([\w-]+)\/D(\d+)(?!\w)/g;
+const BARE_DESIGN = /(?<![\w/-])D(\d+)(?!\w)/g;
+function entryOf(e) {
+    return { ...e, line: 1, text: "", canonical: true, refs: [] };
+}
+/** REQ-IDX-013 the winner among folders with one key: active first, then the smaller name. Archived: newest date, then the smaller name. */
+function better(a, b) {
+    if (a.archived !== b.archived)
+        return !a.archived;
+    if (a.archived && a.date !== b.date)
+        return a.date > b.date;
+    return cmpStr(a.change, b.change) < 0;
+}
+/** REQ-IDX-010 one change entry per key and one cap entry per capability name. */
+function structureEntries(files) {
+    const folders = new Map();
+    const caps = new Map();
+    for (const f of files) {
+        const m = CHANGE_DIR.exec(f.path);
+        if (m) {
+            let fo = folders.get(m[1]);
+            if (!fo) {
+                const date = ARCHIVE_DATE.exec(f.path)?.[1] ?? "";
+                folders.set(m[1], (fo = { dir: m[1], change: changeOf(f.path), archived: f.path.includes("/archive/"), date, files: [] }));
+            }
+            fo.files.push(f.path);
+        }
+        const c = CAP_SPEC.exec(f.path);
+        if (c) {
+            let l = caps.get(c[1]);
+            if (!l)
+                caps.set(c[1], (l = []));
+            l.push(f.path);
+        }
+    }
+    const win = new Map();
+    for (const fo of folders.values()) {
+        const key = changeKey(fo.change);
+        const cur = win.get(key);
+        if (!cur || better(fo, cur))
+            win.set(key, fo);
+    }
+    const out = [];
+    for (const [key, fo] of win) {
+        const proposal = `${fo.dir}/proposal.md`;
+        const file = fo.files.includes(proposal) ? proposal : [...fo.files].sort(cmpStr)[0];
+        out.push(entryOf({ id: `change/${key}`, kind: "change", file, title: fo.change, change: fo.change, status: fo.archived ? "archived" : "active" }));
+    }
+    for (const [name, list] of caps) {
+        // the main spec, else the first active delta, else the newest archived delta
+        const sorted = [...list].sort(cmpStr);
+        const file = sorted.find((p) => p.startsWith("openspec/specs/"))
+            ?? sorted.find((p) => !p.includes("/archive/"))
+            ?? sorted[sorted.length - 1];
+        out.push(entryOf({ id: `cap/${name}`, kind: "cap", file, title: name, change: "main", status: "active" }));
+    }
+    return out;
+}
+/** REQ-IDX-012 the `design:` links of a task. The scan reads the text before `Verify:` with the path spans removed. */
+function designLinks(entries) {
+    const decisions = new Set(entries.filter((e) => e.kind === "decision").map((e) => e.id));
+    for (const t of entries) {
+        if (t.kind !== "task")
+            continue;
+        let body = t.title;
+        const v = body.indexOf("Verify:");
+        if (v >= 0)
+            body = body.slice(0, v);
+        for (const p of taskPaths(body))
+            body = body.split("`" + p + "`").join(" ");
+        const found = new Set();
+        for (const m of body.matchAll(FULL_DESIGN)) {
+            const folder = resolveChange(entries, m[1]);
+            const id = `${folder === undefined ? m[1] : changeKey(folder)}/D${m[2]}`;
+            if (decisions.has(id))
+                found.add(id);
+        }
+        const own = `${changeKey(t.change)}/D`;
+        for (const m of body.matchAll(BARE_DESIGN))
+            if (decisions.has(own + m[1]))
+                found.add(own + m[1]);
+        if (found.size)
+            t.links = [...found].sort(cmpStr).map((id) => `design:${id}`);
+    }
+}
+/** Add the structural entries and the design links. It runs after the scan and before the canonical mark. */
+export function addStructure(entries, files) {
+    designLinks(entries);
+    entries.push(...structureEntries(files));
+}

package/dist/init/init.js

@@ -6,6 +6,7 @@ import { ASSETS } from "../assets.generated.js";
 import { UsageExit } from "../cli/errors.js";
 import { CONFIG_FILE, DEFAULT_OPENSPEC, INIT_TEXT } from "../config.js";
 import { loadConfigOrExit } from "../cli/config.js";
+import { VERSION } from "../version.js";
 export const SCHEMA = "spec-driven-ids";
 /** REQ-SCH-003 where the templates land in a project. Upstream reads no project override for the stock templates, so this is a reference path (025/D4). */
 export const TEMPLATES_DIR = `openspec/templates/${SCHEMA}`;
@@ -41,7 +42,7 @@ export function detectOpenspec(timeoutMs = DETECT_TIMEOUT_MS) {
  * exists at the root. `src/**` becomes `lib/**` when only `lib/` exists. The comments stay.
  * `openspec` replaces the default command on the `openspec = ` line (022/D2).
  */
-export function configText(root, openspec = DEFAULT_OPENSPEC) {
+export function configText(root, openspec = DEFAULT_OPENSPEC, run = null) {
     const isDir = (d) => existsSync(join(root, d)) && statSync(join(root, d)).isDirectory();
     let text = INIT_TEXT;
     if (!isDir("tests") && isDir("test"))
@@ -50,8 +51,18 @@ export function configText(root, openspec = DEFAULT_OPENSPEC) {
         text = text.replace('\ncode = ["src/**"]\n', '\ncode = ["lib/**"]\n');
     if (openspec !== DEFAULT_OPENSPEC)
         text = text.replace(`\nopenspec = "${DEFAULT_OPENSPEC}"\n`, `\nopenspec = ${JSON.stringify(openspec)}\n`);
+    // REQ-DIST-015 a run prefix adds the [cli] section at the end (043/D3)
+    if (run !== null)
+        text += `\n[cli]\n# The prefix of every command that spec-ctx prints for you to run. init wrote it because it ran under npx.\nrun = ${JSON.stringify(run)}\n`;
     return text;
 }
+/**
+ * REQ-DIST-015 the run prefix that init writes. npm sets npm_command to exec for npm exec and npx.
+ * Any other value, or none, gives null and the default applies (043/D3).
+ */
+export function runPrefixFor(env) {
+    return env.npm_command === "exec" ? `npx -y spec-ctx@${VERSION}` : null;
+}
 /**
  * REQ-SCH-006 wrap the ID after a requirement or scenario header prefix in square brackets (032/D1).
  * An ID in brackets already stays. Task citations, Refs lines, and tags have no header prefix, so they stay bare.
@@ -74,8 +85,8 @@ export function bracketsOf(root) {
     return existsSync(join(root, CONFIG_FILE)) ? loadConfigOrExit(root).ids.brackets : false;
 }
 /** Target path relative to the project root for every file that init installs, with its bytes. */
-export function plan(o, root, openspec = DEFAULT_OPENSPEC, brackets = false) {
-    const out = [[CONFIG_FILE, Buffer.from(configText(root, openspec))]];
+export function plan(o, root, openspec = DEFAULT_OPENSPEC, brackets = false, run = null) {
+    const out = [[CONFIG_FILE, Buffer.from(configText(root, openspec, run))]];
     for (const rel of Object.keys(ASSETS).sort()) {
         // REQ-SCH-003 only the four templates land in the project. The fragment merges into config.yaml. No schema folder (025/D3)
         if (o.schema && rel.startsWith(TEMPLATES_SRC)) {
@@ -416,7 +427,7 @@ export function runInit(root, o) {
     const brackets = bracketsOf(root);
     const fragment = fragmentText(brackets);
     const otherFragment = fragmentText(!brackets);
-    let files = plan(o, root, openspec, brackets);
+    let files = plan(o, root, openspec, brackets, runPrefixFor(process.env));
     // REQ-CLI-007 every file present with the same bytes and no config key to add: nothing to do
     // an existing spec-ctx.toml counts as present, because the user owns it (014/D4)
     const same = files.every(([rel, data]) => existsSync(join(root, rel)) && (rel === CONFIG_FILE || readFileSync(join(root, rel)).equals(data)));

package/dist/journal/journal.js

@@ -0,0 +1,65 @@
+// REQ-JRN-001 REQ-JRN-003 the journal write. One call, one line, no output, no throw (057/D2, 057/D3).
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { COMMANDS } from "../cli/args.js";
+import { dumps } from "../util/json.js";
+import { SIGNALS } from "./note.js";
+export const JOURNAL_DIR = ".ctx/local";
+export const JOURNAL_FILE = "runs.jsonl";
+export const ROTATED_FILE = "runs.1.jsonl";
+export const MAX_BYTES = 256 * 1024;
+export const MAX_LINE = 4096;
+/** REQ-JRN-001 the line, with sorted keys and no newline inside. It stays under 4 KB. */
+export function journalLine(sink, run) {
+    const signals = new Set(sink.signals);
+    if (run.exit === 2)
+        signals.add("usage-error");
+    if (run.exit === 3)
+        signals.add("internal-error");
+    const rec = {
+        at: run.at ?? new Date().toISOString(),
+        cmd: sink.cmd !== undefined && COMMANDS.includes(sink.cmd) ? sink.cmd : "?",
+        exit: run.exit,
+        ms: Math.max(0, Math.round(run.ms)),
+        signals: SIGNALS.filter((s) => signals.has(s)),
+        v: 1,
+        version: run.version,
+    };
+    if (sink.err && run.exit === 3)
+        rec.err = { code: sink.err.code, frames: sink.err.frames, name: sink.err.name };
+    let line = JSON.stringify(JSON.parse(dumps(rec)));
+    if (line.length > MAX_LINE && sink.err) {
+        rec.err = { code: sink.err.code, frames: sink.err.frames.slice(0, 5), name: sink.err.name };
+        line = JSON.stringify(JSON.parse(dumps(rec)));
+    }
+    if (line.length > MAX_LINE) {
+        delete rec.err;
+        line = JSON.stringify(JSON.parse(dumps(rec)));
+    }
+    return line;
+}
+/** REQ-JRN-003 append one line. Any failure stays silent. */
+export function appendRun(sink, run) {
+    try {
+        if (process.env.SPECCTX_JOURNAL === "0")
+            return;
+        const root = sink.root;
+        if (!root)
+            return;
+        const os = join(root, "openspec");
+        if (!existsSync(os) || !statSync(os).isDirectory())
+            return;
+        const dir = join(root, JOURNAL_DIR);
+        mkdirSync(dir, { recursive: true });
+        const ignore = join(dir, ".gitignore");
+        if (!existsSync(ignore))
+            writeFileSync(ignore, "*\n");
+        const file = join(dir, JOURNAL_FILE);
+        if (existsSync(file) && statSync(file).size > MAX_BYTES)
+            renameSync(file, join(dir, ROTATED_FILE));
+        appendFileSync(file, journalLine(sink, run) + "\n");
+    }
+    catch {
+        // the journal never changes the exit code or the output
+    }
+}

package/dist/journal/note.js

@@ -0,0 +1,54 @@
+// REQ-JRN-001 REQ-JRN-002 the sink that main() fills. It has no fs import, so a --version run loads no write code (057/D1).
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/** REQ-JRN-002 the closed set of signals. The line version `v` versions it. */
+export const SIGNALS = ["init-ok", "context-has-code-or-test", "empty-context", "truncated-context", "usage-error", "internal-error"];
+/** REQ-JRN-001 fill the sink. It does nothing when the caller passed no sink. */
+export function note(io, patch) {
+    const s = io.journal;
+    if (!s)
+        return;
+    if (patch.root !== undefined)
+        s.root = patch.root;
+    if (patch.cmd !== undefined)
+        s.cmd = patch.cmd;
+    if (patch.run !== undefined)
+        s.run = patch.run;
+    if (patch.signal !== undefined && SIGNALS.includes(patch.signal))
+        s.signals.add(patch.signal);
+    if (patch.err !== undefined)
+        s.err = patch.err;
+}
+/** The package root: two folders above src/journal or dist/journal. */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+/** REQ-JRN-002 name, code, and package frames of an error. Never the message (057/D4). */
+export function errInfo(e, pkgRoot = PACKAGE_ROOT) {
+    if (!(e instanceof Error))
+        return { name: "NonError", code: null, frames: [] };
+    const raw = e.code;
+    const code = typeof raw === "string" && /^[A-Z][A-Z0-9_]*$/.test(raw) ? raw : null;
+    const frames = [];
+    // stack line 1 holds the message, so it never counts
+    for (const line of (e.stack ?? "").split("\n").slice(1)) {
+        if (!/^\s+at /.test(line))
+            continue;
+        const m = /\(?((?:file:\/\/)?[^()\s]+):(\d+):\d+\)?$/.exec(line);
+        if (!m)
+            continue;
+        let file = m[1];
+        try {
+            if (file.startsWith("file://"))
+                file = fileURLToPath(file);
+        }
+        catch {
+            continue;
+        }
+        const rel = relative(pkgRoot, file);
+        if (rel === "" || rel.startsWith("..") || rel.split(/[\\/]/).includes("node_modules") || resolve(rel) === rel)
+            continue;
+        frames.push(`${rel.split("\\").join("/")}:${m[2]}`);
+        if (frames.length === 10)
+            break;
+    }
+    return { name: e.name, code, frames };
+}

package/dist/journal/report.js

@@ -0,0 +1,115 @@
+// REQ-JRN-004 REQ-JRN-005 the bug report. The only reader of the journal. It never runs gh and never uses the network (057/D6).
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "smol-toml";
+import { JOURNAL_DIR, JOURNAL_FILE, ROTATED_FILE } from "./journal.js";
+import { SIGNALS } from "./note.js";
+export const NO_JOURNAL = `no journal found under ${JOURNAL_DIR}\n`;
+function readLines(path) {
+    if (!existsSync(path))
+        return [];
+    const out = [];
+    for (const raw of readFileSync(path, "utf8").split("\n")) {
+        if (!raw.trim())
+            continue;
+        try {
+            const v = JSON.parse(raw);
+            if (v === null || typeof v !== "object" || v.v !== 1)
+                continue;
+            if (typeof v.at !== "string" || Number.isNaN(Date.parse(v.at)) || typeof v.cmd !== "string")
+                continue;
+            if (typeof v.exit !== "number" || typeof v.ms !== "number" || !Array.isArray(v.signals))
+                continue;
+            const line = { at: v.at, cmd: v.cmd, exit: v.exit, ms: v.ms, signals: v.signals.filter((s) => typeof s === "string") };
+            const e = v.err;
+            if (e && typeof e === "object") {
+                line.err = {
+                    name: typeof e.name === "string" && /^\w+$/.test(e.name) ? e.name : "?",
+                    code: typeof e.code === "string" && /^[A-Z][A-Z0-9_]*$/.test(e.code) ? e.code : null,
+                    frames: Array.isArray(e.frames) ? e.frames.filter((f) => typeof f === "string" && /^[\w./-]+:\d+$/.test(f)) : [],
+                };
+            }
+            out.push(line);
+        }
+        catch {
+            // a line that is not JSON is skipped
+        }
+    }
+    return out;
+}
+/** REQ-JRN-004 section and key names of spec-ctx.toml, with no value. */
+export function configShape(root) {
+    const path = join(root, "spec-ctx.toml");
+    if (!existsSync(path))
+        return ["none (no spec-ctx.toml)"];
+    let doc;
+    try {
+        doc = parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return ["none (spec-ctx.toml does not parse)"];
+    }
+    const rows = [];
+    const top = Object.keys(doc).filter((k) => !isTable(doc[k]));
+    if (top.length)
+        rows.push(`(top level): ${top.join(", ")}`);
+    const walk = (name, t) => {
+        const keys = Object.keys(t).filter((k) => !isTable(t[k]));
+        rows.push(`[${name}]: ${keys.length ? keys.join(", ") : "no keys"}`);
+        for (const k of Object.keys(t))
+            if (isTable(t[k]))
+                walk(`${name}.${k}`, t[k]);
+    };
+    for (const k of Object.keys(doc))
+        if (isTable(doc[k]))
+            walk(k, doc[k]);
+    return rows.length ? rows : ["none (empty file)"];
+}
+function isTable(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v) && !(v instanceof Date);
+}
+/** Nearest rank. */
+export function p95(values) {
+    const s = [...values].sort((a, b) => a - b);
+    return s[Math.max(0, Math.ceil(0.95 * s.length) - 1)];
+}
+/** REQ-JRN-004 the Markdown report. It is a pure function of the journal files and the config. */
+export function buildReport(root, now, sys) {
+    const dir = join(root, JOURNAL_DIR);
+    if (!existsSync(join(dir, JOURNAL_FILE)) && !existsSync(join(dir, ROTATED_FILE)))
+        return { found: false, text: NO_JOURNAL };
+    const lines = [...readLines(join(dir, ROTATED_FILE)), ...readLines(join(dir, JOURNAL_FILE))];
+    const md = ["# spec-ctx report", "", `Generated: ${now.toISOString()}`, ""];
+    md.push("## Versions", "", `- spec-ctx: ${sys.version}`, `- Node: ${sys.node}`, `- OS: ${sys.platform} ${sys.arch}`, "");
+    md.push("## Config shape", "", ...configShape(root).map((r) => `- ${r}`), "");
+    const i = lines.findIndex((l) => l.signals.includes("init-ok"));
+    const j = i < 0 ? -1 : lines.findIndex((l, k) => k > i && l.signals.includes("context-has-code-or-test"));
+    md.push("## North star", "");
+    if (j < 0)
+        md.push("- Minutes from the first `init-ok` to the first `context-has-code-or-test`: n/a", "- Runs between them: n/a", "");
+    else {
+        const mins = (Date.parse(lines[j].at) - Date.parse(lines[i].at)) / 60000;
+        md.push(`- Minutes from the first \`init-ok\` to the first \`context-has-code-or-test\`: ${mins.toFixed(1)}`, `- Runs between them: ${j - i}`, "");
+    }
+    md.push(`## Runs`, "", `- Total: ${lines.length}`, "");
+    const byCmd = new Map();
+    for (const l of lines)
+        byCmd.set(l.cmd, [...(byCmd.get(l.cmd) ?? []), l.ms]);
+    md.push("## Time", "", "| cmd | runs | p95 ms |", "| --- | --- | --- |");
+    for (const c of [...byCmd.keys()].sort())
+        md.push(`| ${c.replace(/[^\w ?-]/g, "?")} | ${byCmd.get(c).length} | ${p95(byCmd.get(c))} |`);
+    md.push("", "## Signals", "");
+    for (const s of SIGNALS)
+        md.push(`- ${s}: ${lines.filter((l) => l.signals.includes(s)).length}`);
+    md.push("", "## Last internal error", "");
+    const last = [...lines].reverse().find((l) => l.err !== undefined);
+    if (!last?.err)
+        md.push("- none");
+    else {
+        md.push(`- name: ${last.err.name}`, `- code: ${last.err.code ?? "none"}`, "- frames:", ...last.err.frames.map((f) => `  - ${f}`));
+        if (!last.err.frames.length)
+            md.push("  - none");
+    }
+    md.push("", "Review this text, then file it. Run: `gh issue create -R sonqh/spec-ctx --body-file <file>`", "");
+    return { found: true, text: md.join("\n") };
+}

package/dist/journal/signals.js

@@ -0,0 +1,26 @@
+// REQ-JRN-002 the signals of one context run. They read the provenance lines of the printed text (057/D3).
+import { parseProvenance } from "../graph/bundle.js";
+import { canon } from "../index/canonical.js";
+/** Only `context` calls this. No provenance line gives empty-context. A kept code or test block gives context-has-code-or-test. */
+export function contextSignals(entries, b) {
+    const ids = canon(entries);
+    const out = [];
+    let lines = 0;
+    let line = false;
+    for (const l of b.text.split("\n")) {
+        const id = parseProvenance(l);
+        if (id === null)
+            continue;
+        lines++;
+        const k = ids.get(id)?.kind;
+        if (k === "code" || k === "test")
+            line = true;
+    }
+    if (lines === 0)
+        out.push("empty-context");
+    if (line)
+        out.push("context-has-code-or-test");
+    if (!b.complete)
+        out.push("truncated-context");
+    return out;
+}