spec-ctx 0.4.1 → 0.5.0

package/dist/cli/commands.js

@@ -6,6 +6,7 @@ import { defaults } from "../config.js";
 import { hintOf } from "../check/hints.js";
 import { paint } from "./color.js";
 import { runCommand } from "../runcmd.js";
+import { note } from "../journal/note.js";
 /** check with warnings and the baseline filter. Strict mode adds the strict rules and the warnings. */
 async function runCheck(root, cfg, data, strict) {
     const { check } = await import("../check/check.js");
@@ -28,12 +29,13 @@ async function runCheck(root, cfg, data, strict) {
  * REQ-CHK-004 the findings, then a blank line, the summary line, and one line per rule with its hint.
  * A warning counts as advisory. The `baselined` line stays last (REQ-CHK-002).
  */
-export function checkText(r, tty, run = "specctx") {
+export function checkText(r, tty, run = "specctx", deferred = []) {
     // REQ-CLI-008 every finding of check is hard, so every finding line is red. stale-evidence is one of them.
     // REQ-CHK-001 a finding with a detail, such as a retitle, carries it after the ID (021/D2)
     const body = r.findings.map((x) => paint("fail", `${x.file}:${x.line}  ${x.rule}  ${x.id}${x.detail ? `  ${x.detail}` : ""}\n`, tty)).join("")
         + r.warnings.map((w) => `warning: ${w}\n`).join("");
-    const base = r.baselined ? `baselined: ${r.baselined}\n` : "";
+    // REQ-CHK-010 a deferred line is not a finding. It comes before the baselined line, which stays last (052/D3).
+    const base = deferred.map((d) => `deferred: ${d.change}  ${d.untested} untested delta item${d.untested === 1 ? "" : "s"}, ${d.open} open task${d.open === 1 ? "" : "s"}\n`).join("") + (r.baselined ? `baselined: ${r.baselined}\n` : "");
     const n = r.findings.length + r.warnings.length;
     if (!n)
         return paint("dim", "0 findings\n", tty) + base;
@@ -75,8 +77,21 @@ export async function run(p, io) {
         return init(p, io);
     const root = findRoot(io.cwd, f.root);
     requireOpenSpec(root);
+    // REQ-JRN-001 the root is known now, so the bin entry may write the journal
+    note(io, { root });
+    // REQ-JRN-004 report runs before the config load, so a broken config still reports
+    if (cmd === "report") {
+        if (p.positional.length)
+            throw new UsageExit("report takes no arguments");
+        const { buildReport } = await import("../journal/report.js");
+        const { VERSION } = await import("../version.js");
+        io.out(buildReport(root, new Date(), { version: VERSION, node: process.version, platform: process.platform, arch: process.arch }).text);
+        return 0;
+    }
     const { loadConfigOrExit } = await import("./config.js");
     const cfg = loadConfigOrExit(root);
+    // REQ-JRN-006 the exit 3 line names the report command with this prefix
+    note(io, { run: cfg.cli.run });
     const { dumps } = await import("../util/json.js");
     const print = (v) => io.out(dumps(v) + "\n");
     if (cmd === "build") {
@@ -287,6 +302,9 @@ export async function run(p, io) {
             const { bundle } = await import("../graph/bundle.js");
             const { resolveInputs } = await import("../graph/input.js");
             const ids = canon(entries);
+            // REQ-QRY-018 a negative budget is a usage error (050/D11)
+            if (f.budget !== undefined && f.budget < 0)
+                throw new UsageExit("--budget must be 0 or more");
             // REQ-QRY-005 an input that is no known ID is a path in the repository
             const { wanted, paths, errors, taskId } = resolveInputs(root, io.cwd, entries, p.positional);
             if (errors.length) {
@@ -302,8 +320,9 @@ export async function run(p, io) {
                 }
                 const { reqBlocks } = await import("../graph/bundle.js");
                 const text = reqBlocks(root, p.positional.map((i) => ids.get(i)));
+                // REQ-QRY-019 block mode has no budget, so budget is null and the text is complete (050/D6)
                 if (json)
-                    print({ text, omitted: [] });
+                    print({ text, omitted: [], chars: (await import("../util/pystr.js")).cpLen(text), budget: null, complete: true });
                 else
                     io.out(text);
                 return 0;
@@ -311,6 +330,12 @@ export async function run(p, io) {
             // 047/D5 a task input passes the entry that findTask picks, so an active task wins over an archived one
             const task = taskId === undefined ? undefined : (await import("../tasks/tasks.js")).findTask(root, entries, taskId).entry;
             const b = bundle(root, entries, wanted, f.budget ?? cfg.bundle.budget, f.depth ?? cfg.bundle.depth, { all, task });
+            // REQ-JRN-002 only context emits the block signals. The sink is set only for the bin entry.
+            if (cmd === "context" && io.journal) {
+                const { contextSignals } = await import("../journal/signals.js");
+                for (const signal of contextSignals(entries, b))
+                    note(io, { signal });
+            }
             if (json)
                 print(b);
             else if (b.text === "" && wanted.every((w) => paths.has(w)))
@@ -343,10 +368,12 @@ export async function run(p, io) {
             const r = await runCheck(root, cfg, data, !!f.strict);
             // REQ-CHK-004 REQ-CHK-006 the JSON keeps its shape. A finding hint is for the human form only (031/D6).
             const findings = r.findings.map(({ hint: _hint, ...rest }) => rest);
+            // REQ-CHK-010 only this case computes the deferred notice. runCheck and gate stay as they are (052/D5).
+            const deferred = f.strict ? (await import("../check/check.js")).deferredOf(entries, data) : [];
             if (json)
-                print({ baselined: r.baselined, count: findings.length, findings, warnings: r.warnings });
+                print({ baselined: r.baselined, count: findings.length, findings, warnings: r.warnings, ...(f.strict ? { deferred } : {}) });
             else
-                io.out(checkText(r, io.tty, cfg.cli.run));
+                io.out(checkText(r, io.tty, cfg.cli.run, deferred));
             return r.findings.length ? 1 : 0;
         }
     }

package/dist/cli/help.js

@@ -40,7 +40,7 @@ export const TABLE = [
     {
         name: "context", group: "Read", args: "<task|ID|path|change>", summary: "Print what an agent needs before it edits a task, an ID, a file, or a change.",
         flags: [
-            ["--budget <n>", "Stop at n characters. The default is 8000."],
+            ["--budget <n>", "Keep the blocks to n characters. A requested block always prints, also when it is longer. Then the over budget line gives the size. The truncated line is not in this limit. The default is 8000."],
             ["--depth <n>", "Follow links n steps. The default is 1."],
         ],
         exit: [OK, ["2", "A usage error, an unknown ID, or a bad path. It takes one input. Use `bundle` for several inputs or for `--block`."], INTERNAL], example: "specctx context 045/2.1",
@@ -53,7 +53,7 @@ export const TABLE = [
     {
         name: "bundle", group: "Read", args: "<ID|path|change...>", summary: "Print the spec text for the IDs, files, or changes and their links.",
         flags: [
-            ["--budget <n>", "Stop at n characters. The default is 8000."],
+            ["--budget <n>", "Keep the blocks to n characters. A requested block always prints, also when it is longer. Then the over budget line gives the size. The truncated line is not in this limit. The default is 8000."],
             ["--depth <n>", "Follow links n steps. The default is 1."],
             ["--all", "Show all copies of an ID."],
             ["--block", "Print only the requirement block, as it sits in the spec file. Each ID must be a requirement."],
@@ -90,6 +90,11 @@ export const TABLE = [
         flags: [["--change <name>", "Show only this change."], ["--write", "Also write docs/metrics/<date>.md."]],
         exit: PLAIN, example: "specctx stats --write",
     },
+    {
+        name: "report", group: "Read", args: "", summary: "Print a bug report from the run journal in .ctx/local. Review it, then file it with `gh issue create`. Write nothing.",
+        flags: [],
+        exit: [OK, ["2", "A usage error."], INTERNAL], example: "specctx report > report.md",
+    },
     {
         name: "lint tells", group: "Read", args: "<file...>", summary: "Find the AI writing tells in markdown files. Read stdin when no file is given.",
         flags: LINT_FLAGS, exit: LINT_EXIT, example: "specctx lint tells --baseline 0 README.md",

package/dist/cli/workflow.js

@@ -171,10 +171,13 @@ export async function runWorkflow(c) {
                 // REQ-LOOP-002 the fail file is the retry record. At the cap, one question stops the loop (024/D4, 024/D5).
                 const { writeFail, openQuestionFor, capQuestion, blockedLine } = await import("../loop/fails.js");
                 const { addQuestion } = await import("../handoff/questions.js");
-                const fail = writeFail(c.root, t.id, { command: t.verify.command, exit: r.timedOut ? null : r.exit }, outTail);
+                // REQ-TASK-008 the fail file and the cap question hold no machine path. The printed tail stays as it is (056/D5).
+                const { redactPaths } = await import("../util/redact.js");
+                const kept = redactPaths(outTail, c.root);
+                const fail = writeFail(c.root, t.id, { command: t.verify.command, exit: r.timedOut ? null : r.exit }, kept);
                 let question = openQuestionFor(c.root, t.id)?.n ?? null;
                 if (question === null && fail.file.attempt >= c.cfg.loop.max_attempts) {
-                    question = addQuestion(c.root, t.id, capQuestion(t.id, fail.file.attempt, outTail), "cap").n;
+                    question = addQuestion(c.root, t.id, capQuestion(t.id, fail.file.attempt, kept), "cap").n;
                 }
                 if (c.json)
                     print(c, { attempt: fail.file.attempt, command: t.verify.command, error: msg, exit: r.exit, fail: fail.rel, question, tail: outTail, task: t.id });
@@ -196,8 +199,10 @@ export async function runWorkflow(c) {
             // the Verify command can change tagged files, so the digests come from the tree after the run
             const { loadIndex } = await import("../index/build.js");
             const after = loadIndex(c.root, c.cfg).data.entries;
+            // REQ-TASK-008 the stderr tail holds no machine path. verify.command stays as the task line has it (056/D5, 056/D6).
+            const { redactPaths } = await import("../util/redact.js");
             const rel = writeEvidence(c.root, t, after, {
-                command: t.verify.command, exit: 0, stdout_sha256: sha256(r.stdout), stderr_tail: tail(r.stderr.toString("utf8")),
+                command: t.verify.command, exit: 0, stdout_sha256: sha256(r.stdout), stderr_tail: redactPaths(tail(r.stderr.toString("utf8")), c.root),
             }, "command", undefined, t.verify.cwd);
             setBox(c.root, t, true);
             clearCurrent(c.root, t.id);

package/dist/cli.js

@@ -1,14 +1,53 @@
 #!/usr/bin/env node
 // REQ-CLI-001 bin entry. tests call main() from src/main.ts in process.
+// REQ-JRN-001 this entry writes the run journal after main() returns. main() only fills the sink (057/D1).
 import { main } from "./main.js";
+import { VERSION } from "./version.js";
 process.stdout.on("error", (e) => {
     if (e.code === "EPIPE")
         process.exit(0);
 });
-const code = await main(process.argv.slice(2), {
-    cwd: process.cwd(),
-    out: (s) => process.stdout.write(s),
-    err: (s) => process.stderr.write(s),
-    tty: process.stdout.isTTY === true,
-});
+const argv = process.argv.slice(2);
+const sink = { signals: new Set() };
+const t0 = performance.now();
+let code;
+let thrown;
+let failed = false;
+try {
+    code = await main(argv, {
+        cwd: process.cwd(),
+        out: (s) => process.stdout.write(s),
+        err: (s) => process.stderr.write(s),
+        tty: process.stdout.isTTY === true,
+        journal: sink,
+    });
+}
+catch (e) {
+    failed = true;
+    thrown = e;
+    code = 3;
+    try {
+        const { errInfo } = await import("./journal/note.js");
+        sink.err = errInfo(e);
+    }
+    catch {
+        // no journal detail
+    }
+}
+try {
+    // REQ-JRN-001 a usage error before the root check keeps no root. Only the "?" command with no --root looks for one (057/D2).
+    if (sink.root === undefined && sink.cmd === "?" && !argv.some((a) => a === "--root" || a.startsWith("--root="))) {
+        const { findRoot } = await import("./cli/root.js");
+        sink.root = findRoot(process.cwd());
+    }
+    if (sink.root !== undefined && process.env.SPECCTX_JOURNAL !== "0") {
+        const { appendRun } = await import("./journal/journal.js");
+        appendRun(sink, { exit: code, ms: performance.now() - t0, version: VERSION });
+    }
+}
+catch {
+    // the journal never changes the exit code or the output
+}
+if (failed)
+    throw thrown;
 process.exitCode = code;

package/dist/graph/bundle.js

@@ -45,6 +45,11 @@ function rstrip(s) {
 export function provenance(e, reason) {
     return `-- ${e.id} | ${e.file}:${e.line} | ${e.status} | ${reason}\n`;
 }
+/** REQ-JRN-002 the ID of a provenance line, or null. It anchors on the start of `provenance()` (057/D3). */
+export function parseProvenance(line) {
+    const m = /^-- (\S+) \| /.exec(line);
+    return m ? m[1] : null;
+}
 /** REQ-QRY-004 the canonical blocks of requirements, joined by one blank line, with no provenance line. */
 export function reqBlocks(root, reqs) {
     const files = new Lines(root);
@@ -132,12 +137,15 @@ export function bundle(root, entries0, wanted, budget, depth, opts = {}) {
         if (m)
             blocks.push([m, `main version of ${i}`, 0]);
     }
+    // REQ-QRY-018 the count of blocks that the loop above pushed. They print first and always stay.
+    const pinned = blocks.length;
     const found = new Map();
     for (const i of wanted) {
         // decisions that reference a requested ID are included at every depth, as depth 1.
         // REQ-QRY-016 They replace a deeper hit, which the walk for an earlier requested ID can leave (048/D1).
         for (const e of entries) {
-            if (e.kind !== "decision" || !e.refs.includes(i))
+            // REQ-QRY-014 a requested decision prints once, as requested (050/D10)
+            if (e.kind !== "decision" || !e.refs.includes(i) || wanted.includes(e.id))
                 continue;
             const cur = found.get(e.id);
             if (!cur || cur.depth > 1)
@@ -161,7 +169,7 @@ export function bundle(root, entries0, wanted, budget, depth, opts = {}) {
     }
     for (const c of r.cited) {
         for (const e of entries) {
-            if (e.kind !== "decision" || !e.refs.includes(c))
+            if (e.kind !== "decision" || !e.refs.includes(c) || wanted.includes(e.id))
                 continue;
             const cur = found.get(e.id);
             if (!cur || cur.depth > 1)
@@ -191,11 +199,14 @@ export function bundle(root, entries0, wanted, budget, depth, opts = {}) {
         // a blank line closes a block with a body. Code and test paths stay one line each.
         return provenance(e, reason) + body + (body ? "\n" : "");
     });
-    // fill the budget class by class, in print order inside a class, and skip a block that does not fit
-    const keep = blocks.map(() => false);
+    // REQ-QRY-018 the blocks of the first loop always stay: each requested block and the main version of a requested ID (050/D2, 050/D3)
+    const keep = blocks.map((_, k) => k < pinned);
     let used = 0;
+    for (let k = 0; k < pinned; k++)
+        used += cpLen(texts[k]);
+    // fill the budget class by class, in print order inside a class, and skip a block that does not fit
     for (let cls = 0; cls <= 3; cls++) {
-        for (let k = 0; k < blocks.length; k++) {
+        for (let k = pinned; k < blocks.length; k++) {
             if (blocks[k][2] !== cls)
                 continue;
             const n = cpLen(texts[k]);
@@ -209,5 +220,8 @@ export function bundle(root, entries0, wanted, budget, depth, opts = {}) {
     let text = texts.filter((_, k) => keep[k]).join("");
     if (omitted.length)
         text += `truncated: ${omitted.length} entries omitted: ${omitted.join(", ")}\n`;
-    return { text, omitted };
+    // REQ-QRY-018 the over budget line goes last, so the 0.4.1 output stays a prefix (050/D4)
+    if (used > budget)
+        text += `over budget: ${used} of ${budget} characters\n`;
+    return { text, omitted, chars: cpLen(text), budget, complete: omitted.length === 0 };
 }

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;
+}