spec-ctx 0.0.0-stage → 0.1.1

package/dist/index/scan.js

@@ -0,0 +1,357 @@
+// REQ-IDX-001 scan of specs, changes, decisions, code, and tests.
+import { lstatSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { anyMatch, globBase, globRe } from "../util/glob.js";
+import { cmpStr, pyStrip, splitLines, squash } from "../util/pystr.js";
+// Every pattern is ASCII only. `[ \t\n\r\f\v]` is the ASCII whitespace class of the Python oracle.
+const S = "[ \\t\\n\\r\\f\\v]";
+export const ID_RE = /\b(REQ-[A-Z]{2,6}-\d{3}|SCN-[A-Z]{2,6}-\d{3}-\d+|ADR-\d{3})\b/g;
+const ID_FULL = /^(?:REQ-[A-Z]{2,6}-\d{3}|SCN-[A-Z]{2,6}-\d{3}-\d+|ADR-\d{3})$/;
+const SCN_RE = /\bSCN-[A-Z]{2,6}-\d{3}-\d+\b/g;
+const REQ_HDR = new RegExp(`^### Requirement:${S}*(REQ-[A-Z]{2,6}-\\d{3})?${S}*(.*)$`, "s");
+const SCN_HDR = new RegExp(`^#### Scenario:${S}*(SCN-[A-Z]{2,6}-\\d{3}-\\d+)?${S}*(.*)$`, "s");
+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})`);
+const COVER_TAG = new RegExp(`Covers:${S}*(REQ-[A-Z]{2,6}-\\d{3}(?:${S}*,${S}*REQ-[A-Z]{2,6}-\\d{3})*)`);
+const SENTENCE_END = new RegExp(`(?<=[.!?])${S}`);
+const COMMA = new RegExp(`${S}*,${S}*`);
+const SKIP_DIRS = new Set(["node_modules", ".git"]);
+export function scanner(root, cfg) {
+    const s = cfg.scan;
+    const all = [...s.specs, ...s.changes, ...s.decisions, ...s.code, ...s.tests];
+    return {
+        root,
+        md: [...s.specs, ...s.changes, ...s.decisions].map(globRe),
+        src: [...s.code, ...s.tests].map(globRe),
+        tests: s.tests.map(globRe),
+        ignore: s.ignore.map(globRe),
+        bases: [...new Set(all.map(globBase))].sort(cmpStr),
+        taskRe: new RegExp(`^${S}*- \\[([ xX]?)\\]${S}*(${cfg.ids.task_pattern})${S}+(.*)$`, "s"),
+    };
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Files that match the scan globs, sorted by path. The walk reads no file contents. */
+export function walk(sc) {
+    const seen = new Map();
+    const visit = (abs, rel) => {
+        let names;
+        try {
+            names = readdirSync(abs).sort(cmpStr);
+        }
+        catch {
+            return;
+        }
+        const pre = rel === "" ? "" : rel + "/";
+        const dirs = [];
+        for (const name of names) {
+            const p = join(abs, name);
+            let dir;
+            let link = false;
+            try {
+                const st = lstatSync(p);
+                link = st.isSymbolicLink();
+                dir = link ? isDir(p) : st.isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (dir) {
+                // a link to a directory is listed but not followed, as os.walk does
+                if (!link && !SKIP_DIRS.has(name) && !anyMatch(sc.ignore, `${pre}${name}/`))
+                    dirs.push(name);
+                continue;
+            }
+            const path = pre + name;
+            if (seen.has(path) || anyMatch(sc.ignore, path))
+                continue;
+            if (anyMatch(sc.md, path))
+                seen.set(path, "md");
+            else if (anyMatch(sc.src, path))
+                seen.set(path, "src");
+        }
+        for (const d of dirs)
+            visit(join(abs, d), pre + d);
+    };
+    for (const base of sc.bases) {
+        const top = base ? join(sc.root, base) : sc.root;
+        if (isDir(top))
+            visit(top, base);
+    }
+    return [...seen.keys()].sort(cmpStr).map((path) => ({ path, kind: seen.get(path) }));
+}
+/** REQ-IDX-004 count and newest mtime in integer milliseconds, from stat calls only. */
+export function scannedOf(root, files) {
+    let newest = 0;
+    for (const f of files) {
+        try {
+            const ms = Number(statSync(join(root, f.path), { bigint: true }).mtimeNs / 1000000n);
+            if (ms > newest)
+                newest = ms;
+        }
+        catch {
+            // a file removed during the walk does not count
+        }
+    }
+    return { count: files.length, newest_mtime_ms: newest };
+}
+export function changeOf(path) {
+    const m = /^openspec\/changes\/(archive\/)?([^/]+)\//.exec(path);
+    if (!m)
+        return "main";
+    let name = m[2];
+    // openspec archive prefixes the folder with a date: 2026-10-23-001-foundation
+    if (m[1])
+        name = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+    return name;
+}
+/**
+ * REQ-IDX-005 the change key: the leading digits of a folder like `003-distribution`,
+ * else the full folder name. Task and decision IDs use the key (ADR-002, 008/D1).
+ */
+export function changeKey(change) {
+    const m = /^(\d+)-/.exec(change);
+    return m ? m[1] : change;
+}
+/** REQ-IDX-005 a key or a full folder name names the same change. */
+export function matchesChange(folder, input) {
+    return folder === input || changeKey(folder) === input;
+}
+/**
+ * REQ-IDX-005 resolve a key or a full folder name to the change folder.
+ * An exact folder name wins. Unknown input returns undefined.
+ */
+export function resolveChange(entries, input) {
+    const folders = [...new Set(entries.map((e) => e.change).filter((c) => c !== "main"))];
+    if (folders.includes(input))
+        return input;
+    return folders.find((f) => changeKey(f) === input);
+}
+/** REQ-IDX-005 a task or decision ID may name its change by the full folder name: `003-distribution/3.3` is `003/3.3`. */
+export function resolveTaskId(entries, id) {
+    const i = id.indexOf("/");
+    if (i < 0)
+        return id;
+    const folder = resolveChange(entries, id.slice(0, i));
+    return folder === undefined ? id : `${changeKey(folder)}${id.slice(i)}`;
+}
+export function readText(abs) {
+    return readFileSync(abs).toString("utf8");
+}
+function fenceToggle(line) {
+    const t = pyStrip(line);
+    return t.startsWith("```") || t.startsWith("~~~");
+}
+/** Line range of a markdown block from its header to the next header of the same or a higher level. */
+export function blockRange(lines, start) {
+    const hdr = lines[start];
+    const level = hdr.startsWith("#") ? hdr.length - hdr.replace(/^#+/, "").length : 6;
+    let end = start + 1;
+    let inFence = false;
+    while (end < lines.length) {
+        const line = lines[end];
+        if (fenceToggle(line))
+            inFence = !inFence;
+        else if (!inFence && line.startsWith("#")) {
+            const lvl = line.length - line.replace(/^#+/, "").length;
+            if (lvl <= level)
+                break;
+        }
+        end++;
+    }
+    return [start, end];
+}
+function entry(e) {
+    return { text: "", canonical: false, ...e };
+}
+export function scanMarkdown(sc, rpath, entries, problems) {
+    const lines = splitLines(readText(join(sc.root, rpath)));
+    const change = changeOf(rpath);
+    const status = rpath.includes("/archive/") ? "archived" : "active";
+    const isDesign = rpath.endsWith("design.md");
+    const isTasks = rpath.endsWith("tasks.md");
+    let curReq = null;
+    let curEntry = null;
+    let inFence = false;
+    let section = "";
+    let decision = null;
+    const decisions = [];
+    const blocks = [];
+    for (let n = 0; n < lines.length; n++) {
+        const line = lines[n];
+        const i = n + 1;
+        if (fenceToggle(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        if (decision !== null) {
+            // a decision bullet runs until a blank line, the next bullet, or a header
+            if (pyStrip(line) && !line.startsWith("- ") && !line.startsWith("#")) {
+                decision._lines.push(pyStrip(line));
+                continue;
+            }
+            decision = null;
+        }
+        if (line.startsWith("## ")) {
+            // delta section of an active change: ADDED, MODIFIED, REMOVED, RENAMED. Also Decisions in design.md.
+            section = pyStrip(line.slice(3)).split(" ")[0].toUpperCase();
+            continue;
+        }
+        if (isDesign && section === "DECISIONS" && line.startsWith("- ")) {
+            decision = entry({
+                id: `${changeKey(change)}/D${decisions.length + 1}`, kind: "decision", file: rpath, line: i,
+                title: "", change, status, refs: [],
+            });
+            decision._lines = [pyStrip(line.slice(2))];
+            entries.push(decision);
+            decisions.push(decision);
+            continue;
+        }
+        let m = REQ_HDR.exec(line);
+        if (m) {
+            const rid = m[1];
+            const title = pyStrip(m[2]);
+            if (!rid) {
+                problems.push([rpath, i, "missing-id", title]);
+                curReq = null;
+                curEntry = null;
+                continue;
+            }
+            curReq = rid;
+            let st = status;
+            if (status === "active" && change !== "main") {
+                // REQ-IDX-003 a MODIFIED block in an active change is the pending version of a main-spec ID
+                if (section === "MODIFIED")
+                    st = "modified";
+                else if (section === "REMOVED")
+                    st = "removed";
+            }
+            curEntry = entry({ id: rid, kind: "req", file: rpath, line: i, title, change, status: st, refs: [], scenarios: [] });
+            entries.push(curEntry);
+            blocks.push(curEntry);
+            continue;
+        }
+        m = SCN_HDR.exec(line);
+        if (m) {
+            const sid = m[1];
+            const title = pyStrip(m[2]);
+            if (!sid) {
+                problems.push([rpath, i, "missing-id", title]);
+                continue;
+            }
+            const st = curEntry ? curEntry.status : status;
+            const e = entry({ id: sid, kind: "scn", file: rpath, line: i, title, change, status: st, refs: [] });
+            if (curReq && sid.startsWith("SCN-" + curReq.slice(4))) {
+                curEntry.scenarios.push(sid);
+                e.refs.push(curReq);
+            }
+            else if (curReq) {
+                problems.push([rpath, i, "scenario-id-mismatch", `${sid} under ${curReq}`]);
+            }
+            entries.push(e);
+            blocks.push(e);
+            continue;
+        }
+        m = ADR_HDR.exec(line);
+        if (m && i <= 3) {
+            curEntry = entry({ id: m[1], kind: "adr", file: rpath, line: i, title: pyStrip(m[2]), change: "main", status: "active", refs: [] });
+            entries.push(curEntry);
+            blocks.push(curEntry);
+            continue;
+        }
+        m = REFS_RE.exec(pyStrip(line));
+        if (m && curEntry !== null) {
+            for (const ref of pyStrip(m[1]).split(COMMA)) {
+                if (ID_FULL.test(ref))
+                    curEntry.refs.push(ref);
+                else
+                    problems.push([rpath, i, "bad-ref", ref]);
+            }
+            continue;
+        }
+        m = sc.taskRe.exec(line);
+        if (m && isTasks) {
+            const box = m[1];
+            const num = m[2];
+            const body = m[m.length - 1];
+            const tid = `${changeKey(change)}/${num}`;
+            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]);
+            // the full task body is the title, so query output shows the Verify clause
+            entries.push(entry({
+                id: tid, kind: "task", file: rpath, line: i, title: pyStrip(body), change,
+                status: pyStrip(box).toLowerCase() === "x" ? "done" : "open", refs: reqs,
+            }));
+        }
+    }
+    // REQ-IDX-002 text holds the lower-cased body of each block
+    for (const e of blocks) {
+        // text is empty for adr and task entries
+        if (e.kind === "adr")
+            continue;
+        const [s, end] = blockRange(lines, e.line - 1);
+        e.text = squash(lines.slice(s + 1, end));
+    }
+    for (const e of decisions) {
+        const body = e._lines.join(" ");
+        delete e._lines;
+        e.title = body.split(SENTENCE_END)[0];
+        e.text = squash([body]);
+        if (body.includes("Refs:")) {
+            const after = body.slice(body.indexOf("Refs:") + 5);
+            e.refs = [...after.matchAll(ID_RE)].map((x) => x[1]);
+        }
+    }
+}
+export function isTestPath(sc, rpath) {
+    const name = rpath.slice(rpath.lastIndexOf("/") + 1);
+    return anyMatch(sc.tests, rpath) || rpath.includes("/tests/") || rpath.startsWith("tests/")
+        || rpath.includes(".test.") || name.includes("test_");
+}
+export function scanSource(sc, rpath, entries, scnNamed) {
+    const isTest = isTestPath(sc, rpath);
+    let content;
+    try {
+        content = readText(join(sc.root, rpath));
+    }
+    catch {
+        return;
+    }
+    // REQ-CHK-002 a scenario is tested when a test file names it
+    if (isTest)
+        for (const m of content.matchAll(SCN_RE))
+            scnNamed.add(m[0]);
+    const lines = splitLines(content);
+    for (let n = 0; n < lines.length; n++) {
+        const line = lines[n];
+        const i = n + 1;
+        if (isTest) {
+            const m = COVER_TAG.exec(line);
+            if (m) {
+                for (const rid of m[1].split(COMMA)) {
+                    entries.push(entry({ id: `${rpath}:${i}`, kind: "test", file: rpath, line: i, title: pyStrip(line), change: "main", status: "active", refs: [rid] }));
+                }
+                continue;
+            }
+        }
+        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]] }));
+        }
+    }
+}

package/dist/index/types.js

@@ -0,0 +1,2 @@
+// REQ-IDX-002 record shape of .ctx/index.json.
+export {};

package/dist/init/init.js

@@ -0,0 +1,169 @@
+// REQ-DIST-002 REQ-SCH-003 REQ-SKL-002 specctx init: config file, schema bundle, skills.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ASSETS } from "../assets.generated.js";
+import { UsageExit } from "../cli/errors.js";
+import { CONFIG_FILE, INIT_TEXT } from "../config.js";
+export const SCHEMA = "spec-driven-ids";
+export const SKILL_DIRS = [".claude/skills", ".agents/skills"];
+function asset(rel) {
+    const b64 = ASSETS[rel];
+    if (b64 === undefined)
+        throw new Error(`asset ${rel} is missing from the package`);
+    return Buffer.from(b64, "base64");
+}
+/** Target path relative to the project root for every file that init installs, with its bytes. */
+export function plan(o) {
+    const out = [[CONFIG_FILE, Buffer.from(INIT_TEXT)]];
+    for (const rel of Object.keys(ASSETS).sort()) {
+        if (o.schema && rel.startsWith(`schemas/${SCHEMA}/`) && !rel.endsWith("/config-fragment.yaml")) {
+            out.push([`openspec/${rel}`, asset(rel)]);
+        }
+        if (o.skills && rel.startsWith("skills/")) {
+            for (const d of SKILL_DIRS)
+                out.push([`${d}/${rel.slice("skills/".length)}`, asset(rel)]);
+        }
+    }
+    return out;
+}
+const TOP_KEY = /^([A-Za-z_][\w-]*):/;
+function topKeys(text) {
+    const keys = new Set();
+    for (const line of text.split("\n")) {
+        const m = TOP_KEY.exec(line);
+        if (m)
+            keys.add(m[1]);
+    }
+    return keys;
+}
+/** Top-level blocks of a YAML file, keyed by name, as raw text. Comment lines before a block stay out. */
+function topBlocks(text) {
+    const blocks = new Map();
+    let key = null;
+    let buf = [];
+    const flush = () => {
+        if (key)
+            blocks.set(key, buf.join("\n").replace(/\n+$/, "") + "\n");
+    };
+    for (const line of text.split("\n")) {
+        const m = TOP_KEY.exec(line);
+        if (m) {
+            flush();
+            key = m[1];
+            buf = [line];
+        }
+        else if (key && (line.startsWith(" ") || line.startsWith("\t") || line.trim() === ""))
+            buf.push(line);
+        else if (key && line.startsWith("#"))
+            continue;
+        else if (key) {
+            flush();
+            key = null;
+        }
+    }
+    flush();
+    return blocks;
+}
+/**
+ * REQ-SCH-003 quote list items under `rules` and `operations` that hold `: ` and are not quoted.
+ * YAML reads such an item as a one key mapping. Every other line stays byte for byte.
+ */
+export function repairItems(text) {
+    let inBlock = false;
+    let fixed = 0;
+    const out = text.split("\n").map((line) => {
+        const top = TOP_KEY.exec(line);
+        if (top) {
+            inBlock = top[1] === "rules" || top[1] === "operations";
+            return line;
+        }
+        if (!inBlock)
+            return line;
+        const m = /^(\s+- )(.*?)(\s*)$/.exec(line);
+        if (!m || /^['"]/.test(m[2]) || !/:(\s|$)/.test(m[2]))
+            return line;
+        fixed++;
+        return `${m[1]}'${m[2].replace(/'/g, "''")}'${m[3]}`;
+    });
+    return { text: out.join("\n"), fixed };
+}
+/**
+ * REQ-SCH-003 add each top-level key of the fragment that the project config lacks.
+ * Keys that exist stay as they are. The schema key names the installed bundle.
+ */
+export function mergeConfig(current, fragment) {
+    let text = current ?? "";
+    const added = [];
+    const kept = [];
+    const schemaLine = `schema: ${SCHEMA}`;
+    if (/^schema:.*$/m.test(text)) {
+        if (!new RegExp(`^${schemaLine}\\s*$`, "m").test(text)) {
+            text = text.replace(/^schema:.*$/m, schemaLine);
+            added.push("schema");
+        }
+    }
+    else {
+        text = schemaLine + "\n" + (text ? "\n" + text : "");
+        added.push("schema");
+    }
+    const have = topKeys(text);
+    for (const [key, block] of topBlocks(fragment)) {
+        if (have.has(key)) {
+            kept.push(key);
+            continue;
+        }
+        text = text.replace(/\n*$/, "\n\n") + block;
+        added.push(key);
+    }
+    const r = repairItems(text);
+    if (r.fixed) {
+        text = r.text;
+        added.push("repaired items");
+    }
+    return { text, added, kept };
+}
+export function runInit(root, o) {
+    const res = { written: [], kept: [], notes: [] };
+    let files = plan(o);
+    // REQ-CLI-007 every file present with the same bytes and no config key to add: nothing to do
+    const same = files.every(([rel, data]) => existsSync(join(root, rel)) && readFileSync(join(root, rel)).equals(data));
+    if (same && !o.force) {
+        const cfgPath = join(root, "openspec/config.yaml");
+        const cur = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : null;
+        if (!o.schema || !mergeConfig(cur, asset(`schemas/${SCHEMA}/config-fragment.yaml`).toString("utf8")).added.length) {
+            res.nothing = true;
+            return res;
+        }
+    }
+    if (existsSync(join(root, CONFIG_FILE))) {
+        if (!o.force)
+            throw new UsageExit(`${CONFIG_FILE} exists. Use --force to install the other files over it`);
+        // --force never replaces a config that the user wrote
+        files = files.filter(([rel]) => rel !== CONFIG_FILE);
+        res.kept.push(CONFIG_FILE);
+    }
+    if (!o.force) {
+        const clash = files.filter(([rel, data]) => existsSync(join(root, rel)) && !readFileSync(join(root, rel)).equals(data));
+        if (clash.length)
+            throw new UsageExit(`these files exist with other content: ${clash.map(([r]) => r).join(", ")}. Use --force to replace them`);
+    }
+    for (const [rel, data] of files) {
+        const p = join(root, rel);
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, data);
+        res.written.push(rel);
+    }
+    if (o.schema) {
+        const cfgPath = join(root, "openspec/config.yaml");
+        const cur = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : null;
+        const m = mergeConfig(cur, asset(`schemas/${SCHEMA}/config-fragment.yaml`).toString("utf8"));
+        if (m.added.length) {
+            mkdirSync(dirname(cfgPath), { recursive: true });
+            writeFileSync(cfgPath, m.text);
+            res.written.push(`openspec/config.yaml (${m.added.join(", ")})`);
+        }
+        for (const k of m.kept)
+            res.kept.push(`openspec/config.yaml ${k}`);
+    }
+    return res;
+}