spec-ctx 0.0.0-stage → 0.1.1

package/dist/handoff/handoff.js

@@ -0,0 +1,148 @@
+// REQ-HND-001 REQ-HND-002 the generated session handoff in .ctx/handoff.md.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { UsageExit } from "../cli/errors.js";
+import { changeKey } from "../index/scan.js";
+import { listEvidence } from "../tasks/evidence.js";
+import { activeChanges, nextTask } from "../tasks/tasks.js";
+import { cmpStr, splitLines } from "../util/pystr.js";
+import { isoNow, today } from "../util/time.js";
+export const HANDOFF_PATH = ".ctx/handoff.md";
+export const CURRENT_PATH = ".ctx/current.json";
+const SCALARS = ["change", "current", "base", "as_of"];
+const LISTS = ["done", "reopened", "open_questions", "resolved"];
+function empty() {
+    return { change: "none", current: "none", base: "none", as_of: "none", done: [], reopened: [], open_questions: [], resolved: [], next: "", evidence: "" };
+}
+/** Parse a handoff file. A list item keeps its indented continuation lines. */
+export function parseHandoff(text) {
+    const h = empty();
+    let list = null;
+    for (const line of splitLines(text)) {
+        if (list && line.startsWith("- ")) {
+            list.push(line.slice(2));
+            continue;
+        }
+        if (list && /^[ \t]/.test(line) && line.trim() && list.length) {
+            list[list.length - 1] += "\n" + line;
+            continue;
+        }
+        list = null;
+        const m = /^([a-z_]+):(?: (.*))?$/.exec(line);
+        if (!m)
+            continue;
+        const key = m[1];
+        if (LISTS.includes(key))
+            list = h[key];
+        else if (SCALARS.includes(key) || key === "next" || key === "evidence") {
+            h[key] = (m[2] ?? "").trim();
+        }
+    }
+    return h;
+}
+export function renderHandoff(h) {
+    const out = ["# Handoff"];
+    for (const k of SCALARS)
+        out.push(`${k}: ${h[k]}`);
+    for (const k of LISTS) {
+        out.push(`${k}:`);
+        for (const item of h[k])
+            out.push(`- ${item}`);
+    }
+    out.push(`next: ${h.next}`, `evidence: ${h.evidence}`);
+    return out.join("\n") + "\n";
+}
+export function readHandoff(root) {
+    const p = join(root, HANDOFF_PATH);
+    return existsSync(p) ? parseHandoff(readFileSync(p).toString("utf8")) : null;
+}
+function save(root, h) {
+    mkdirSync(join(root, ".ctx"), { recursive: true });
+    writeFileSync(join(root, HANDOFF_PATH), renderHandoff(h));
+}
+export function currentTask(root) {
+    try {
+        const c = JSON.parse(readFileSync(join(root, CURRENT_PATH), "utf8"));
+        return c.task ?? "none";
+    }
+    catch {
+        return "none";
+    }
+}
+function evidenceRows(root, active) {
+    // REQ-IDX-005 evidence files name the change by its key
+    const nums = new Set(active.map(changeKey));
+    const rows = [];
+    for (const rel of listEvidence(root)) {
+        try {
+            const ev = JSON.parse(readFileSync(join(root, rel), "utf8"));
+            if (typeof ev.task === "string" && nums.has(ev.task.split("/")[0]))
+                rows.push({ task: ev.task, at: String(ev.at), kind: String(ev.kind) });
+        }
+        catch {
+            // a damaged evidence file is a check finding, not a handoff error
+        }
+    }
+    return rows;
+}
+const AT = / \(at (\S+)\)$/;
+/** Generate the handoff. Two runs with no change in between write the same bytes. */
+export function writeHandoff(root, entries) {
+    const prev = readHandoff(root);
+    const active = activeChanges(entries);
+    const next = nextTask(root, entries);
+    const rows = evidenceRows(root, active);
+    const asOf = rows.length ? rows.map((r) => r.at).sort(cmpStr).pop() : "none";
+    // the done window starts where the previous handoff ended, unless no new evidence came since
+    let base = "none";
+    if (prev)
+        base = prev.as_of === asOf ? prev.base : prev.as_of;
+    const after = (at) => base === "none" || cmpStr(at, base) > 0;
+    const h = {
+        change: next ? next.change : active[0] ?? "none",
+        current: currentTask(root),
+        base,
+        as_of: asOf,
+        done: rows.filter((r) => after(r.at)).map((r) => r.task).sort(cmpStr),
+        reopened: (prev?.reopened ?? []).filter((item) => {
+            const m = AT.exec(item.split("\n")[0]);
+            return !m || after(m[1]);
+        }),
+        open_questions: prev?.open_questions ?? [],
+        resolved: prev?.resolved ?? [],
+        next: next ? `${next.id}  ${next.text}` : "no open task",
+        evidence: `${rows.length} task(s), ${rows.filter((r) => r.kind === "command").length} command, ${rows.filter((r) => r.kind === "manual").length} manual`,
+    };
+    save(root, h);
+    return h;
+}
+function ensure(root, entries) {
+    return readHandoff(root) ?? writeHandoff(root, entries);
+}
+export function ask(root, entries, text) {
+    const q = text.replace(/\s*\n\s*/g, " ").trim();
+    if (!q)
+        throw new UsageExit("handoff ask needs a question");
+    const h = ensure(root, entries);
+    h.open_questions.push(`${q} (task ${currentTask(root)}, ${today()})`);
+    save(root, h);
+    return h;
+}
+export function resolve(root, entries, n, answer) {
+    const h = ensure(root, entries);
+    if (!Number.isInteger(n) || n < 1 || n > h.open_questions.length) {
+        throw new UsageExit(`no open question ${n}. The handoff has ${h.open_questions.length}`);
+    }
+    const a = answer.replace(/\s*\n\s*/g, " ").trim();
+    if (!a)
+        throw new UsageExit("handoff resolve needs an answer");
+    const [item] = h.open_questions.splice(n - 1, 1);
+    h.resolved.push(`${item.split("\n")[0]} answer: ${a}`);
+    save(root, h);
+    return h;
+}
+export function addReopened(root, entries, task, reason) {
+    const h = ensure(root, entries);
+    h.reopened.push(`${task} ${reason.replace(/\s*\n\s*/g, " ").trim()} (at ${isoNow()})`);
+    save(root, h);
+}

package/dist/ids/ids.js

@@ -0,0 +1,115 @@
+// REQ-IDS-001 REQ-IDS-002 REQ-IDS-003 ID allocation and retirement.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { UsageExit } from "../cli/errors.js";
+import { canon } from "../index/canonical.js";
+import { changeKey, resolveChange } from "../index/scan.js";
+import { today } from "../util/time.js";
+export const RETIRED_FILE = "decisions/retired-ids.md";
+const ANY_ID = /\b(REQ-[A-Z]{2,6}-\d{3}|SCN-[A-Z]{2,6}-\d{3}-\d+|ADR-\d{3})\b/g;
+export function retiredAll(root) {
+    const p = join(root, RETIRED_FILE);
+    if (!existsSync(p))
+        return new Set();
+    // the retired ID is the first ID of a line. A reason may name a live replacement ID.
+    const out = new Set();
+    for (const line of readFileSync(p, "utf8").split("\n")) {
+        const m = new RegExp(ANY_ID.source).exec(line);
+        if (m)
+            out.add(m[1]);
+    }
+    return out;
+}
+const pad = (n, w = 3) => String(n).padStart(w, "0");
+/** Next unused IDs. Next is one more than the highest number among all index entries and retired IDs. */
+export function newIds(root, cfg, entries, o) {
+    const kind = o.kind.toUpperCase();
+    if (!Number.isInteger(o.count) || o.count < 1)
+        throw new UsageExit("--count needs an integer of 1 or more");
+    const known = [...entries.map((e) => e.id), ...retiredAll(root)];
+    const next = (re) => {
+        let max = 0;
+        for (const id of known) {
+            const m = re.exec(id);
+            if (m)
+                max = Math.max(max, Number(m[1]));
+        }
+        return max + 1;
+    };
+    const checkCap = (cap) => {
+        if (!cap)
+            throw new UsageExit(`id new ${kind} needs a capability code`);
+        if (!/^[A-Z]{2,6}$/.test(cap))
+            throw new UsageExit(`the capability code ${cap} must be 2 to 6 upper case letters`);
+        // REQ-IDS-001 an empty caps list accepts any code. A non-empty list must hold the code.
+        if (cfg.ids.caps.length && !cfg.ids.caps.includes(cap)) {
+            throw new UsageExit(`unknown-cap ${cap}. Configured codes: ${cfg.ids.caps.join(", ")}. Add "${cap}" to caps under [ids] in spec-ctx.toml.`);
+        }
+        return cap;
+    };
+    const seq = (start, fmt) => Array.from({ length: o.count }, (_, i) => fmt(start + i));
+    switch (kind) {
+        case "REQ": {
+            const cap = checkCap(o.cap);
+            const start = next(new RegExp(`^REQ-${cap}-(\\d{3})$`));
+            if (start + o.count - 1 > 999)
+                throw new UsageExit(`no free REQ number for ${cap}`);
+            return seq(start, (n) => `REQ-${cap}-${pad(n)}`);
+        }
+        case "SCN": {
+            const cap = checkCap(o.cap);
+            if (!o.forReq)
+                throw new UsageExit("id new SCN needs --for <REQ-ID>");
+            const m = /^REQ-([A-Z]{2,6})-(\d{3})$/.exec(o.forReq);
+            if (!m || m[1] !== cap)
+                throw new UsageExit(`--for ${o.forReq} is not a REQ ID of ${cap}`);
+            const start = next(new RegExp(`^SCN-${cap}-${m[2]}-(\\d+)$`));
+            return seq(start, (n) => `SCN-${cap}-${m[2]}-${n}`);
+        }
+        case "ADR": {
+            const start = next(/^ADR-(\d{3})$/);
+            if (start + o.count - 1 > 999)
+                throw new UsageExit("no free ADR number");
+            return seq(start, (n) => `ADR-${pad(n)}`);
+        }
+        case "DEC": {
+            // REQ-IDX-005 a design decision ID is <change key>/D<n>. The CAP argument names the change by key or folder.
+            if (!o.cap)
+                throw new UsageExit("id new DEC needs a change name or key");
+            const folder = resolveChange(entries, o.cap);
+            if (folder === undefined)
+                throw new UsageExit(`no change with the key ${changeKey(o.cap)}`);
+            const num = changeKey(folder);
+            const start = next(new RegExp(`^${num.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/D(\\d+)$`));
+            return seq(start, (n) => `${num}/D${n}`);
+        }
+    }
+    throw new UsageExit(`id new needs REQ, SCN, ADR, or DEC, not ${o.kind}`);
+}
+/** Append a row to decisions/retired-ids.md. A canonical ID is still in use and stays. */
+export function retire(root, entries, id, reason) {
+    if (!/^(REQ-[A-Z]{2,6}-\d{3}|SCN-[A-Z]{2,6}-\d{3}-\d+|ADR-\d{3})$/.test(id))
+        throw new UsageExit(`${id} is not a REQ, SCN, or ADR ID`);
+    if (!reason.trim())
+        throw new UsageExit("id retire needs a reason");
+    // an archived copy is history. Only a copy in openspec/specs/ or an active change keeps the ID in use.
+    const live = canon(entries).get(id);
+    if (live && live.status !== "archived")
+        throw new UsageExit(`${id} is still in use at ${live.file}:${live.line}`);
+    if (retiredAll(root).has(id))
+        throw new UsageExit(`${id} is already retired`);
+    const p = join(root, RETIRED_FILE);
+    let text = existsSync(p) ? readFileSync(p, "utf8") : "";
+    if (!/^\| ID \| Date \| Reason \|$/m.test(text)) {
+        if (!text.trim())
+            text = "# Retired IDs\n\nIDs that were removed. Never reuse them.\n";
+        text = text.replace(/\n*$/, "\n\n") + "| ID | Date | Reason |\n| --- | --- | --- |\n";
+    }
+    else if (!text.endsWith("\n"))
+        text += "\n";
+    const row = `| ${id} | ${today()} | ${reason.trim().replace(/\|/g, "\\|").replace(/\s*\n\s*/g, " ")} |`;
+    mkdirSync(join(root, "decisions"), { recursive: true });
+    writeFileSync(p, text + row + "\n");
+    rmSync(join(root, ".ctx/index.json"), { force: true });
+    return row;
+}

package/dist/index/build.js

@@ -0,0 +1,57 @@
+// REQ-IDX-001 REQ-IDX-002 REQ-IDX-004 build, write, and load .ctx/index.json.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { dumps } from "../util/json.js";
+import { cmpStr, cmpTuple } from "../util/pystr.js";
+import { markCanonical } from "./canonical.js";
+import { scanMarkdown, scannedOf, scanner, scanSource, walk } from "./scan.js";
+export const INDEX_PATH = ".ctx/index.json";
+export function buildIndex(root, cfg, files, sc) {
+    const s = sc ?? scanner(root, cfg);
+    const list = files ?? walk(s);
+    const entries = [];
+    const problems = [];
+    const scnNamed = new Set();
+    for (const f of list) {
+        if (f.kind === "md")
+            scanMarkdown(s, f.path, entries, problems);
+        else
+            scanSource(s, f.path, entries, scnNamed);
+    }
+    markCanonical(entries);
+    entries.sort((a, b) => cmpTuple([a.id, a.file, a.line], [b.id, b.file, b.line]));
+    const uniq = new Map();
+    for (const p of problems)
+        uniq.set(JSON.stringify(p), p);
+    const probs = [...uniq.values()].sort((a, b) => cmpTuple(a, b));
+    const data = {
+        entries,
+        problems: probs,
+        scanned: scannedOf(root, list),
+        scn_named: [...scnNamed].sort(cmpStr),
+    };
+    mkdirSync(join(root, ".ctx"), { recursive: true });
+    writeFileSync(join(root, INDEX_PATH), dumps(data) + "\n");
+    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 sc = scanner(root, cfg);
+    const files = walk(sc);
+    const p = join(root, INDEX_PATH);
+    let data = null;
+    if (existsSync(p)) {
+        try {
+            data = JSON.parse(readFileSync(p, "utf8"));
+        }
+        catch {
+            data = null;
+        }
+    }
+    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 };
+    }
+    return { data, rebuilt: false };
+}

package/dist/index/canonical.js

@@ -0,0 +1,44 @@
+// REQ-IDX-003 one canonical entry per REQ, SCN, and ADR ID.
+import { cmpTuple } from "../util/pystr.js";
+export const SPEC_KINDS = new Set(["req", "scn", "adr"]);
+/** Canonical order: active change, then openspec/specs, then archive. A removed entry is never canonical. */
+export function tier(e) {
+    const st = e.status;
+    if (st === "removed")
+        return null;
+    if (st === "modified" || (st === "active" && e.change !== "main"))
+        return 0;
+    if (st === "active")
+        return 1;
+    return 2;
+}
+export function markCanonical(entries) {
+    const best = new Map();
+    for (const e of entries) {
+        if (!SPEC_KINDS.has(e.kind)) {
+            e.canonical = true;
+            continue;
+        }
+        e.canonical = false;
+        const t = tier(e);
+        if (t === null)
+            continue;
+        const key = [t, e.file, e.line];
+        const cur = best.get(e.id);
+        if (!cur || cmpTuple(key, cur[0]) < 0)
+            best.set(e.id, [key, e]);
+    }
+    for (const [, e] of best.values())
+        e.canonical = true;
+}
+/** Canonical entries by ID. A later entry with the same ID wins, as in the Python oracle. */
+export function canon(entries) {
+    const m = new Map();
+    for (const e of entries)
+        if (e.canonical)
+            m.set(e.id, e);
+    return m;
+}
+export function poolOf(entries, all) {
+    return all ? entries : entries.filter((e) => e.canonical);
+}