spec-ctx 0.0.0-stage → 0.1.0

package/dist/stats/stats.js

@@ -0,0 +1,143 @@
+// REQ-STAT-001 REQ-STAT-002 REQ-STAT-003 REQ-STAT-004 REQ-STAT-005 five metrics from files that exist, plus the gate log.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readBaseline } from "../baseline/baseline.js";
+import { changeKey, matchesChange } from "../index/scan.js";
+import { cmpStr, cpLen } from "../util/pystr.js";
+export const DEBT_RULES = ["uncovered", "scenario-untested", "done-without-evidence", "manual-evidence"];
+const NA = (n = 0) => ({ value: null, n, text: "n/a" });
+function readEvidence(root) {
+    const dir = join(root, ".ctx/evidence");
+    const live = [];
+    const reopened = [];
+    if (!existsSync(dir))
+        return { live, reopened };
+    for (const c of readdirSync(dir).sort(cmpStr)) {
+        let names;
+        try {
+            names = readdirSync(join(dir, c)).sort(cmpStr);
+        }
+        catch {
+            continue;
+        }
+        for (const n of names) {
+            if (!n.endsWith(".json"))
+                continue;
+            try {
+                const ev = JSON.parse(readFileSync(join(dir, c, n), "utf8"));
+                if (typeof ev.task !== "string")
+                    continue;
+                (n.includes(".reopened-") ? reopened : live).push(ev);
+            }
+            catch {
+                // a damaged file is a check finding
+            }
+        }
+    }
+    return { live, reopened };
+}
+export function median(xs) {
+    if (!xs.length)
+        return null;
+    const s = [...xs].sort((a, b) => a - b);
+    const m = Math.floor(s.length / 2);
+    return s.length % 2 ? s[m] : Math.round((s[m - 1] + s[m]) / 2);
+}
+const fmt = (x, d = 2) => x.toFixed(d);
+function metrics(change, live, reopened, specChars, debt) {
+    const withB = live.filter((e) => typeof e.bundle_chars === "number");
+    const ctx = withB.length && specChars > 0
+        ? (() => {
+            const v = withB.reduce((a, e) => a + e.bundle_chars / specChars, 0) / withB.length;
+            return { value: v, n: withB.length, text: `${fmt(v, 4)} (n=${withB.length})` };
+        })()
+        : NA();
+    const cmd = live.filter((e) => e.kind === "command");
+    const ev = live.length
+        ? { value: cmd.length / live.length, n: live.length, text: `${fmt(cmd.length / live.length)} (${cmd.length}/${live.length})`, tasks: cmd.map((e) => e.task).sort(cmpStr) }
+        : NA();
+    const stale = reopened.filter((e) => typeof e.reason === "string" && e.reason.includes("stale"));
+    const st = reopened.length
+        ? { value: stale.length, n: reopened.length, text: `${stale.length} (of ${reopened.length} reopens)`, tasks: stale.map((e) => e.task).sort(cmpStr) }
+        : NA();
+    const cycles = live
+        .filter((e) => typeof e.started_at === "string" && typeof e.at === "string")
+        .map((e) => Math.round((Date.parse(e.at) - Date.parse(e.started_at)) / 1000))
+        .filter((x) => Number.isFinite(x) && x >= 0);
+    const med = median(cycles);
+    const cyc = med === null ? NA() : { value: med, n: cycles.length, text: `${med} (n=${cycles.length})` };
+    return { change, context_ratio: ctx, evidence_ratio: ev, stale_catches: st, cycle_time_median_s: cyc, debt };
+}
+/** REQ-STAT-005 gate metrics over the last 100 lines of the gate log. */
+export function gateMetrics(root, last = 100) {
+    const p = join(root, ".ctx/gate-log.jsonl");
+    if (!existsSync(p))
+        return { gate_runs: NA(), gate_pass_rate: NA(), gate_failures_caught: NA() };
+    const lines = readFileSync(p, "utf8").split("\n").filter(Boolean).slice(-last);
+    const runs = lines.flatMap((l) => {
+        try {
+            return [JSON.parse(l)];
+        }
+        catch {
+            return [];
+        }
+    });
+    if (!runs.length)
+        return { gate_runs: NA(), gate_pass_rate: NA(), gate_failures_caught: NA() };
+    const ok = runs.filter((r) => r.ok === true).length;
+    const failed = runs.length - ok;
+    return {
+        gate_runs: { value: runs.length, n: runs.length, text: String(runs.length) },
+        gate_pass_rate: { value: ok / runs.length, n: runs.length, text: `${fmt(ok / runs.length)} (${ok}/${runs.length})` },
+        gate_failures_caught: { value: failed, n: runs.length, text: String(failed) },
+    };
+}
+export function computeStats(root, entries, strictFindings, warnings, only) {
+    const specChars = entries
+        .filter((e) => e.canonical && (e.kind === "req" || e.kind === "scn" || e.kind === "decision"))
+        .reduce((a, e) => a + cpLen(e.text ?? ""), 0);
+    const { live, reopened } = readEvidence(root);
+    // REQ-IDX-005 the change name of each change key, from the task entries
+    const names = new Map();
+    for (const e of entries)
+        if (e.kind === "task")
+            names.set(changeKey(e.change), e.change);
+    const nameOf = (task) => {
+        const num = task.split("/")[0];
+        return names.get(num) ?? num;
+    };
+    // REQ-STAT-004 debt: baseline entries plus current debt findings and warnings outside the baseline
+    const base = readBaseline(root) ?? new Set();
+    const current = [
+        ...strictFindings.filter((f) => DEBT_RULES.includes(f.rule)).map((f) => `${f.rule} ${f.id}`),
+        ...warnings.filter((w) => DEBT_RULES.includes(w.split(" ")[0])),
+    ];
+    const fresh = [...new Set(current)].filter((k) => !base.has(k));
+    const debtAll = { value: base.size + fresh.length, n: base.size + fresh.length, text: `${base.size + fresh.length} (${base.size} baselined + ${fresh.length} new)` };
+    // a change row counts the task scoped debt: tasks without evidence and tasks with manual evidence
+    const taskDebt = (change) => {
+        const keys = [...base, ...fresh].filter((k) => {
+            const [rule, id] = k.split(" ");
+            return (rule === "done-without-evidence" || rule === "manual-evidence") && nameOf(id ?? "") === change;
+        });
+        return { value: keys.length, n: keys.length, text: String(keys.length) };
+    };
+    const changes = [...new Set([...live, ...reopened].map((e) => nameOf(e.task)))].sort(cmpStr).filter((c) => !only || matchesChange(c, only));
+    const rows = changes.map((c) => metrics(c, live.filter((e) => nameOf(e.task) === c), reopened.filter((e) => nameOf(e.task) === c), specChars, taskDebt(c)));
+    const pick = (xs) => (only ? xs.filter((e) => changes.includes(nameOf(e.task))) : xs);
+    const total = metrics("total", pick(live), pick(reopened), specChars, debtAll);
+    return { spec_chars: specChars, rows, total, gate: gateMetrics(root) };
+}
+export const COLUMNS = ["context_ratio", "evidence_ratio", "stale_catches", "cycle_time_median_s", "debt"];
+export const STATS_FOOTER = "context_ratio = bundle chars / chars of all specs. Lower is better.";
+export function statsTable(s) {
+    const head = ["change", ...COLUMNS];
+    const body = [...s.rows, s.total].map((r) => [r.change, ...COLUMNS.map((c) => r[c].text)]);
+    const width = head.map((h, i) => Math.max(cpLen(h), ...body.map((b) => cpLen(b[i]))));
+    const line = (cells) => cells.map((c, i) => (i === cells.length - 1 ? c : c + " ".repeat(width[i] - cpLen(c)))).join("  ");
+    const out = [line(head), ...body.map(line)];
+    out.push(`gate_runs ${s.gate.gate_runs.text}`, `gate_pass_rate ${s.gate.gate_pass_rate.text}`, `gate_failures_caught ${s.gate.gate_failures_caught.text}`);
+    // REQ-STAT-005 the footer defines the context ratio
+    out.push(STATS_FOOTER);
+    return out;
+}

package/dist/stats/write.js

@@ -0,0 +1,26 @@
+// REQ-STAT-005 stats --write: docs/metrics/<YYYY-MM-DD>.md by UTC date, overwritten on the same day.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { today } from "../util/time.js";
+import { COLUMNS } from "./stats.js";
+export function statsMarkdown(s, date) {
+    const out = [
+        `# Metrics ${date}`,
+        "",
+        "`specctx stats --write` wrote this file. Each value carries the count of its inputs. A value without inputs reads n/a.",
+        "",
+        `| change | ${COLUMNS.join(" | ")} |`,
+        `| --- | ${COLUMNS.map(() => "---").join(" | ")} |`,
+    ];
+    for (const r of [...s.rows, s.total])
+        out.push(`| ${r.change} | ${COLUMNS.map((c) => r[c].text).join(" | ")} |`);
+    out.push("", "| gate metric | value |", "| --- | --- |", `| gate_runs | ${s.gate.gate_runs.text} |`, `| gate_pass_rate | ${s.gate.gate_pass_rate.text} |`, `| gate_failures_caught | ${s.gate.gate_failures_caught.text} |`, "", `The spec text in the index holds ${s.spec_chars} characters. The context ratio divides each bundle by that size.`);
+    return out.join("\n") + "\n";
+}
+export function writeStats(root, s) {
+    const date = today();
+    const rel = `docs/metrics/${date}.md`;
+    mkdirSync(join(root, "docs/metrics"), { recursive: true });
+    writeFileSync(join(root, rel), statsMarkdown(s, date));
+    return rel;
+}

package/dist/tasks/evidence.js

@@ -0,0 +1,102 @@
+// REQ-TASK-004 evidence files under .ctx/evidence/<change key>/<task>.json.
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileSha256 } from "../util/hash.js";
+import { dumps } from "../util/json.js";
+import { isoNow } from "../util/time.js";
+import { VERSION } from "../version.js";
+import { evidenceRel } from "./tasks.js";
+/** Digests of every code and test file tagged with one of the REQs. */
+export function taggedFiles(root, entries, reqs) {
+    const want = new Set(reqs);
+    const paths = new Set();
+    for (const e of entries) {
+        if ((e.kind === "code" || e.kind === "test") && e.refs.some((r) => want.has(r)))
+            paths.add(e.file);
+    }
+    const out = {};
+    for (const p of [...paths].sort()) {
+        const d = fileSha256(join(root, p));
+        if (d)
+            out[p] = d;
+    }
+    return out;
+}
+export function writeEvidence(root, t, entries, verify, kind, note, cwd) {
+    const ev = {
+        task: t.id,
+        reqs: [...t.reqs],
+        kind,
+        verify,
+        files: taggedFiles(root, entries, t.reqs),
+        at: isoNow(),
+        tool_version: VERSION,
+    };
+    if (note !== undefined)
+        ev.note = note;
+    if (cwd !== undefined)
+        ev.cwd = cwd;
+    // REQ-STAT-002 copy the bundle size and the start time that task start wrote for this task
+    try {
+        const cur = JSON.parse(readFileSync(join(root, ".ctx/current.json"), "utf8"));
+        if (cur.task === t.id) {
+            if (typeof cur.bundle_chars === "number")
+                ev.bundle_chars = cur.bundle_chars;
+            if (typeof cur.started_at === "string")
+                ev.started_at = cur.started_at;
+        }
+    }
+    catch {
+        // no current task
+    }
+    const rel = evidenceRel(t);
+    mkdirSync(dirname(join(root, rel)), { recursive: true });
+    writeFileSync(join(root, rel), dumps(ev) + "\n");
+    return rel;
+}
+/** Move the evidence of a reopened task to <task>.reopened-<n>.json. */
+export function retireEvidence(root, t, reason) {
+    const rel = evidenceRel(t);
+    const abs = join(root, rel);
+    if (!existsSync(abs))
+        return null;
+    const base = rel.slice(0, -".json".length);
+    let n = 1;
+    while (existsSync(join(root, `${base}.reopened-${n}.json`)))
+        n++;
+    const target = `${base}.reopened-${n}.json`;
+    renameSync(abs, join(root, target));
+    if (reason !== undefined) {
+        // REQ-STAT-003 the reopen reason stays with the old evidence, so stats can count stale catches
+        try {
+            const ev = JSON.parse(readFileSync(join(root, target), "utf8"));
+            ev.reason = reason;
+            writeFileSync(join(root, target), dumps(ev) + "\n");
+        }
+        catch {
+            // a damaged file moves as it is
+        }
+    }
+    return target;
+}
+/** Every live evidence file, as a path relative to the root. Reopened copies are history and stay out. */
+export function listEvidence(root) {
+    const dir = join(root, ".ctx/evidence");
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const c of readdirSync(dir).sort()) {
+        let names;
+        try {
+            names = readdirSync(join(dir, c));
+        }
+        catch {
+            continue;
+        }
+        for (const n of names.sort()) {
+            if (n.endsWith(".json") && !n.includes(".reopened-"))
+                out.push(`.ctx/evidence/${c}/${n}`);
+        }
+    }
+    return out;
+}

package/dist/tasks/tasks.js

@@ -0,0 +1,105 @@
+// REQ-TASK-001 REQ-TASK-002 REQ-TASK-003 REQ-TASK-005 the task state machine over tasks.md.
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { UsageExit } from "../cli/errors.js";
+import { matchesChange, resolveTaskId } from "../index/scan.js";
+import { cmpStr, cmpTuple, splitLines } from "../util/pystr.js";
+import { parseVerify } from "../verify/parse.js";
+/** Raw lines of a file with their line ends, so an edit keeps every other byte. */
+function rawLines(text) {
+    return text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+/** The task text without the REQ brackets and the Verify clause. */
+export function taskText(title) {
+    let t = title;
+    const v = t.indexOf("Verify:");
+    if (v >= 0)
+        t = t.slice(0, v);
+    return t.replace(/\[REQ-[A-Z]{2,6}-\d{3}(?:\s*,\s*REQ-[A-Z]{2,6}-\d{3})*\]/g, "").replace(/\s+/g, " ").trim();
+}
+export function toTask(root, e) {
+    const lines = splitLines(readFileSync(join(root, e.file)).toString("utf8"));
+    const line = lines[e.line - 1] ?? e.title;
+    const num = e.id.slice(e.id.indexOf("/") + 1);
+    return {
+        entry: e,
+        id: e.id,
+        change: e.change,
+        group: num.split(".")[0],
+        num,
+        done: e.status === "done",
+        archived: e.file.includes("/archive/"),
+        reqs: [...e.refs],
+        line,
+        text: taskText(e.title),
+        verify: parseVerify(line),
+    };
+}
+export function tasksOf(entries) {
+    return entries.filter((e) => e.kind === "task");
+}
+export function findTask(root, entries, id) {
+    // REQ-IDX-005 the full folder name works as an alias of the key
+    const want = resolveTaskId(entries, id);
+    const hits = tasksOf(entries).filter((e) => e.id === want);
+    if (hits.length === 0)
+        throw new UsageExit(`no task ${id}`);
+    // an active copy wins over an archived one with the same number
+    hits.sort((a, b) => Number(a.file.includes("/archive/")) - Number(b.file.includes("/archive/")));
+    return toTask(root, hits[0]);
+}
+export function activeChanges(entries) {
+    const s = new Set();
+    for (const e of tasksOf(entries))
+        if (!e.file.includes("/archive/") && e.change !== "main")
+            s.add(e.change);
+    return [...s].sort(cmpStr);
+}
+/** The first open task whose earlier tasks in the same group are done, in the lowest numbered active change. */
+export function nextTask(root, entries, change) {
+    const changes = activeChanges(entries).filter((c) => !change || matchesChange(c, change));
+    for (const c of changes) {
+        const ts = tasksOf(entries)
+            .filter((e) => e.change === c && !e.file.includes("/archive/"))
+            .sort((a, b) => cmpTuple([a.file, a.line], [b.file, b.line]));
+        for (const e of ts) {
+            if (e.status !== "open")
+                continue;
+            const group = e.id.slice(e.id.indexOf("/") + 1).split(".")[0];
+            const earlier = ts.filter((x) => x.line < e.line && x.file === e.file && x.id.slice(x.id.indexOf("/") + 1).split(".")[0] === group);
+            if (earlier.every((x) => x.status === "done"))
+                return toTask(root, e);
+        }
+    }
+    return null;
+}
+/** Flip only the box characters on the task line. Every other byte of tasks.md stays. */
+export function setBox(root, t, done) {
+    const p = join(root, t.entry.file);
+    const raw = rawLines(readFileSync(p).toString("utf8"));
+    const i = t.entry.line - 1;
+    const line = raw[i];
+    if (line === undefined)
+        throw new Error(`line ${t.entry.line} of ${t.entry.file} is missing`);
+    const m = /^(\s*- )\[([ xX]?)\]/.exec(line);
+    if (!m)
+        throw new Error(`${t.entry.file}:${t.entry.line} is not a task line`);
+    const box = done ? "[x]" : "[ ]";
+    raw[i] = m[1] + box + line.slice(m[0].length);
+    writeFileSync(p, raw.join(""));
+    invalidateIndex(root);
+}
+/**
+ * REQ-IDX-004 a write by specctx itself drops the index, so the next command rebuilds it
+ * even when the edit lands in the same millisecond as the last build.
+ */
+export function invalidateIndex(root) {
+    rmSync(join(root, ".ctx/index.json"), { force: true });
+}
+export function evidenceRel(t) {
+    const [num, task] = t.id.split("/");
+    return `.ctx/evidence/${num}/${task}.json`;
+}
+export function hasEvidence(root, t) {
+    return existsSync(join(root, evidenceRel(t)));
+}

package/dist/util/glob.js

@@ -0,0 +1,43 @@
+// REQ-IDX-001 glob matching for scan and ignore paths.
+const SPECIAL = ".^$+{}()[]|\\";
+/** `**\/` is zero or more directories, `**` is anything, `*` and `?` stay inside one segment. */
+export function globRe(pattern) {
+    let out = "";
+    let i = 0;
+    while (i < pattern.length) {
+        if (pattern.startsWith("**/", i)) {
+            out += "(?:.*/)?";
+            i += 3;
+            continue;
+        }
+        if (pattern.startsWith("**", i)) {
+            out += ".*";
+            i += 2;
+            continue;
+        }
+        const c = pattern[i];
+        if (c === "*")
+            out += "[^/]*";
+        else if (c === "?")
+            out += "[^/]";
+        else if (SPECIAL.includes(c))
+            out += "\\" + c;
+        else
+            out += c;
+        i++;
+    }
+    return new RegExp(`^(?:${out})$`, "s");
+}
+/** Directory part of a glob before the first wildcard segment. */
+export function globBase(pattern) {
+    const parts = [];
+    for (const seg of pattern.split("/").slice(0, -1)) {
+        if (seg.includes("*") || seg.includes("?"))
+            break;
+        parts.push(seg);
+    }
+    return parts.join("/");
+}
+export function anyMatch(globs, path) {
+    return globs.some((g) => g.test(path));
+}

package/dist/util/hash.js

@@ -0,0 +1,14 @@
+// REQ-TASK-004 sha256 hex digests.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+export function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+export function fileSha256(path) {
+    try {
+        return sha256(readFileSync(path));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/util/json.js

@@ -0,0 +1,16 @@
+// REQ-IDX-002 deterministic JSON: sorted keys, two-space indent, UTF-8 kept as is.
+import { cmpStr } from "./pystr.js";
+function sortKeys(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    if (v !== null && typeof v === "object") {
+        const out = {};
+        for (const k of Object.keys(v).sort(cmpStr))
+            out[k] = sortKeys(v[k]);
+        return out;
+    }
+    return v;
+}
+export function dumps(v) {
+    return JSON.stringify(sortKeys(v), null, 2);
+}

package/dist/util/pystr.js

@@ -0,0 +1,67 @@
+// REQ-IDX-002 string helpers with Python semantics. The goldens under tests/fixtures/parity-golden/ came from a Python engine.
+/** Characters that Python `str.isspace()` accepts. JavaScript `\s` and `trim()` use a different set. */
+const PY_WS = "\\t\\n\\v\\f\\r\\x1c-\\x1f \\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000";
+const WS_RUN = new RegExp(`[${PY_WS}]+`, "g");
+const LEAD = new RegExp(`^[${PY_WS}]+`);
+const TRAIL = new RegExp(`[${PY_WS}]+$`);
+/** Python `str.strip()`. */
+export function pyStrip(s) {
+    return s.replace(LEAD, "").replace(TRAIL, "");
+}
+/** Python `str.split()` with no argument. */
+export function pySplit(s) {
+    const t = pyStrip(s);
+    return t === "" ? [] : t.split(WS_RUN);
+}
+/** Lines split on LF only, with a trailing CR removed. */
+export function splitLines(text) {
+    const lines = text.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    return lines.map((l) => (l.endsWith("\r") ? l.slice(0, -1) : l));
+}
+/** Join, collapse whitespace, lower-case. */
+export function squash(lines) {
+    return pySplit(lines.join(" ")).join(" ").toLowerCase();
+}
+/** Length in code points, as Python `len()` counts it. */
+export function cpLen(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {
+            const d = s.charCodeAt(i + 1);
+            if (d >= 0xdc00 && d <= 0xdfff)
+                i++;
+        }
+        n++;
+    }
+    return n;
+}
+/** Compare strings by code point, as Python sorts them. */
+export function cmpStr(a, b) {
+    if (a === b)
+        return 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        const x = a.codePointAt(i);
+        const y = b.codePointAt(i);
+        if (x !== y)
+            return x < y ? -1 : 1;
+        if (x > 0xffff)
+            i++;
+    }
+    return a.length < b.length ? -1 : a.length > b.length ? 1 : 0;
+}
+/** Compare tuples of strings and numbers element by element. */
+export function cmpTuple(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        const x = a[i];
+        const y = b[i];
+        const c = typeof x === "number" && typeof y === "number" ? x - y : cmpStr(String(x), String(y));
+        if (c !== 0)
+            return c < 0 ? -1 : 1;
+    }
+    return a.length - b.length;
+}

package/dist/util/time.js

@@ -0,0 +1,11 @@
+// REQ-TASK-004 the clock. SPECCTX_NOW sets a fixed time for tests.
+export function now() {
+    const fixed = process.env.SPECCTX_NOW;
+    return fixed ? new Date(fixed) : new Date();
+}
+export function isoNow() {
+    return now().toISOString();
+}
+export function today() {
+    return isoNow().slice(0, 10);
+}

package/dist/verify/parse.js

@@ -0,0 +1,58 @@
+// REQ-VER-001 the Verify command of a task line.
+/** Code spans in a text, as CommonMark reads them: a run of N backticks closes at the next run of N. */
+export function codeSpans(text) {
+    const spans = [];
+    let i = 0;
+    while (i < text.length) {
+        if (text[i] !== "`") {
+            i++;
+            continue;
+        }
+        let n = 0;
+        while (text[i + n] === "`")
+            n++;
+        const open = i + n;
+        let j = open;
+        let close = -1;
+        while (j < text.length) {
+            if (text[j] !== "`") {
+                j++;
+                continue;
+            }
+            let m = 0;
+            while (text[j + m] === "`")
+                m++;
+            if (m === n) {
+                close = j;
+                break;
+            }
+            j += m;
+        }
+        if (close < 0) {
+            i = open;
+            continue;
+        }
+        let body = text.slice(open, close).replace(/\n/g, " ");
+        if (body.length > 2 && body.startsWith(" ") && body.endsWith(" ") && body.trim() !== "")
+            body = body.slice(1, -1);
+        if (body.trim())
+            spans.push(body);
+        i = close + n;
+    }
+    return spans;
+}
+export function parseVerify(taskLine) {
+    const at = taskLine.indexOf("Verify:");
+    if (at < 0)
+        return { kind: "manual", command: null };
+    const spans = codeSpans(taskLine.slice(at + "Verify:".length));
+    if (spans.length === 0)
+        return { kind: "manual", command: null };
+    // REQ-VER-004 the first code span may start with cwd=<path> and a space
+    const m = /^cwd=(\S+) +(.+)$/s.exec(spans[0]);
+    if (m) {
+        spans[0] = m[2];
+        return { kind: "command", command: spans.join(" && "), cwd: m[1] };
+    }
+    return { kind: "command", command: spans.join(" && ") };
+}

package/dist/verify/run.js

@@ -0,0 +1,42 @@
+// REQ-VER-001 REQ-VER-003 run a Verify command with sh -c in the project root, with a timeout.
+import { spawn } from "node:child_process";
+export const TAIL_LINES = 20;
+export function tail(text, n = TAIL_LINES) {
+    const lines = text.replace(/\n$/, "").split("\n");
+    return text === "" ? "" : lines.slice(-n).join("\n");
+}
+export function runVerify(command, cwd, timeoutS) {
+    return new Promise((resolve, reject) => {
+        // a new process group, so the timeout stops the children of sh too
+        const child = spawn("sh", ["-c", command], { cwd, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+        const out = [];
+        const err = [];
+        let output = "";
+        let timedOut = false;
+        child.stdout.on("data", (b) => {
+            out.push(b);
+            output += b.toString("utf8");
+        });
+        child.stderr.on("data", (b) => {
+            err.push(b);
+            output += b.toString("utf8");
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+        }, timeoutS * 1000);
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ exit: timedOut ? null : code, timedOut, stdout: Buffer.concat(out), stderr: Buffer.concat(err), output });
+        });
+    });
+}

package/dist/version.js

@@ -0,0 +1,2 @@
+// REQ-CLI-001 version string. tests/cli/version.test.ts keeps it equal to package.json.
+export const VERSION = "0.1.0";