spec-ctx 0.0.0-stage → 0.1.0

package/dist/cli/commands.js

@@ -0,0 +1,275 @@
+// REQ-CLI-001 REQ-CLI-002 command actions.
+import { resolve } from "node:path";
+import { UsageExit } from "./errors.js";
+import { findRoot, requireOpenSpec } from "./root.js";
+import { hintOf } from "../check/hints.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");
+    const { applyBaseline } = await import("../baseline/baseline.js");
+    const findings = check(root, cfg, data, strict);
+    let warnings = [];
+    if (strict) {
+        const { manualWarnings } = await import("../check/evidence.js");
+        const { listEvidence } = await import("../tasks/evidence.js");
+        warnings = manualWarnings(root, data.entries, listEvidence(root));
+    }
+    return applyBaseline(root, findings, warnings);
+}
+/**
+ * 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) {
+    const body = r.findings.map((x) => `${x.file}:${x.line}  ${x.rule}  ${x.id}\n`).join("")
+        + r.warnings.map((w) => `warning: ${w}\n`).join("");
+    const base = r.baselined ? `baselined: ${r.baselined}\n` : "";
+    const n = r.findings.length + r.warnings.length;
+    if (!n)
+        return `0 findings\n${base}`;
+    const files = new Set(r.findings.map((x) => x.file));
+    const count = new Map();
+    for (const x of r.findings)
+        count.set(x.rule, (count.get(x.rule) ?? 0) + 1);
+    for (const w of r.warnings) {
+        const [rule, task] = w.split(" ");
+        count.set(rule, (count.get(rule) ?? 0) + 1);
+        // a manual-evidence warning names a task. Its file is the evidence file of the task.
+        if (task?.includes("/"))
+            files.add(`.ctx/evidence/${task}.json`);
+    }
+    const rules = [...count.keys()].sort();
+    return body
+        + `\n${n} finding${n === 1 ? "" : "s"} in ${files.size} file${files.size === 1 ? "" : "s"} (${r.findings.length} hard, ${r.warnings.length} advisory)\n`
+        + rules.map((rule) => `${rule}  ${count.get(rule)}  ${hintOf(rule)}\n`).join("")
+        + base;
+}
+export async function run(p, io) {
+    const f = p.flags;
+    const json = !!f.json;
+    const cmd = p.command;
+    if (cmd === "init")
+        return init(p, io);
+    const root = findRoot(io.cwd, f.root);
+    requireOpenSpec(root);
+    const { loadConfig, ConfigError } = await import("../config.js");
+    let cfg;
+    try {
+        cfg = loadConfig(root);
+    }
+    catch (e) {
+        if (e instanceof ConfigError)
+            throw new UsageExit(e.message);
+        throw e;
+    }
+    const { dumps } = await import("../util/json.js");
+    const print = (v) => io.out(dumps(v) + "\n");
+    if (cmd === "build") {
+        if (p.positional.length)
+            throw new UsageExit("build takes no arguments");
+        const { buildIndex, INDEX_PATH } = await import("../index/build.js");
+        const data = buildIndex(root, cfg);
+        if (json)
+            print({ entries: data.entries.length, index: INDEX_PATH, problems: data.problems.length });
+        else
+            io.out(`indexed ${data.entries.length} entries, ${data.problems.length} problem(s) -> ${INDEX_PATH}\n`);
+        return 0;
+    }
+    if (cmd === "adopt") {
+        if (p.positional.length)
+            throw new UsageExit("adopt takes no arguments");
+        const { planAdopt, planLines } = await import("../adopt/plan.js");
+        const plan = planAdopt(root, cfg);
+        if (!f["dry-run"]) {
+            const { applyAdopt } = await import("../adopt/write.js");
+            return applyAdopt(root, cfg, plan, io, json);
+        }
+        if (json)
+            print(plan);
+        else if (!plan.edits.length)
+            io.out(plan.unmatched.length ? planLines(plan).join("\n") + "\nnothing to adopt\n" : "nothing to adopt\n");
+        // REQ-CLI-007 the dry run ends with the next step. The exit code stays 1.
+        else
+            io.out(planLines(plan).join("\n") + `\n${plan.edits.length} headers need an ID. Next: specctx adopt\n`);
+        return plan.edits.length ? 1 : 0;
+    }
+    if (cmd === "baseline write" || cmd === "baseline prune") {
+        if (p.positional.length)
+            throw new UsageExit(`${cmd} takes no arguments`);
+        const { buildIndex } = await import("../index/build.js");
+        const { check } = await import("../check/check.js");
+        const { manualWarnings } = await import("../check/evidence.js");
+        const { listEvidence } = await import("../tasks/evidence.js");
+        const { writeBaseline, pruneBaseline, BASELINE_PATH } = await import("../baseline/baseline.js");
+        const data = buildIndex(root, cfg);
+        const findings = check(root, cfg, data, true);
+        const warnings = manualWarnings(root, data.entries, listEvidence(root));
+        if (cmd === "baseline write") {
+            const list = writeBaseline(root, findings, warnings);
+            if (json)
+                print({ baseline: BASELINE_PATH, entries: list.length });
+            else
+                io.out(`wrote ${BASELINE_PATH} with ${list.length} entr${list.length === 1 ? "y" : "ies"}\n`);
+        }
+        else {
+            const n = pruneBaseline(root, findings, warnings);
+            if (json)
+                print({ pruned: n });
+            else
+                io.out(`pruned ${n}\n`);
+        }
+        return 0;
+    }
+    if (cmd === "gate") {
+        if (p.positional.length)
+            throw new UsageExit("gate takes no arguments");
+        const { runGate, DEFAULT_MARKDOWN } = await import("./gate.js");
+        const strict = !!f.strict;
+        return runGate(root, {
+            strict,
+            markdown: f.markdown ?? DEFAULT_MARKDOWN,
+            check: async () => {
+                const { buildIndex } = await import("../index/build.js");
+                const { check } = await import("../check/check.js");
+                void check;
+                const data = buildIndex(root, cfg);
+                const r = await runCheck(root, cfg, data, strict);
+                return { code: r.findings.length ? 1 : 0, out: checkText(r) };
+            },
+        }, io);
+    }
+    const { loadIndex } = await import("../index/build.js");
+    const need = (n, what) => {
+        if (p.positional.length < n)
+            throw new UsageExit(`${cmd} needs ${what}`);
+    };
+    if (cmd === "query")
+        need(1, "at least one term");
+    if (cmd === "related") {
+        need(1, "one ID");
+        if (p.positional.length > 1)
+            throw new UsageExit("related takes one ID");
+    }
+    if (cmd === "bundle")
+        need(1, "at least one ID");
+    if ((cmd === "status" || cmd === "check") && p.positional.length)
+        throw new UsageExit(`${cmd} takes no arguments`);
+    const { data, rebuilt } = loadIndex(root, cfg);
+    if (rebuilt)
+        io.err("index rebuilt\n");
+    const entries = data.entries;
+    if (cmd.includes(" ")) {
+        const { runWorkflow } = await import("./workflow.js");
+        return runWorkflow({ root, cfg, data, p, io, json });
+    }
+    const all = !!f.all;
+    switch (cmd) {
+        case "status": {
+            const { statusReport, statusLines } = await import("./status.js");
+            const r = statusReport(root, entries);
+            if (json)
+                print(r);
+            else
+                io.out(statusLines(r).map((l) => l + "\n").join(""));
+            return 0;
+        }
+        case "query": {
+            const { query, queryLine } = await import("../graph/query.js");
+            const hits = query(entries, p.positional, {
+                kind: f.kind, change: f.change, all, limit: f.limit ?? 20,
+            });
+            if (json)
+                print(hits);
+            else
+                io.out(hits.map((e) => queryLine(e) + "\n").join(""));
+            return 0;
+        }
+        case "related": {
+            const { canon } = await import("../index/canonical.js");
+            const { related } = await import("../graph/related.js");
+            const id = p.positional[0];
+            const ids = canon(entries);
+            if (!ids.has(id) && !(all && entries.some((e) => e.id === id))) {
+                io.err(`unknown id ${id}\n`);
+                return 2;
+            }
+            const rows = [];
+            for (const [i, reason] of related(entries, id, f.depth ?? 1, all)) {
+                const copies = all ? entries.filter((e) => e.id === i) : ids.has(i) ? [ids.get(i)] : [];
+                // canonical copy first, the rest in index order
+                copies.sort((a, b) => Number(!a.canonical) - Number(!b.canonical));
+                for (const e of copies)
+                    rows.push([e, reason]);
+            }
+            if (json)
+                print(rows.map(([e, reason]) => ({ ...e, reason })));
+            else
+                io.out(rows.map(([e, r]) => `${e.kind}  ${e.id}  ${e.status}  ${e.file}:${e.line}  ${r}\n`).join(""));
+            return 0;
+        }
+        case "bundle": {
+            const { canon } = await import("../index/canonical.js");
+            const { bundle } = await import("../graph/bundle.js");
+            const ids = canon(entries);
+            const unknown = p.positional.filter((i) => !ids.has(i));
+            if (unknown.length) {
+                io.err(`unknown id(s): ${unknown.join(", ")}\n`);
+                return 2;
+            }
+            const b = bundle(root, entries, p.positional, f.budget ?? cfg.bundle.budget, f.depth ?? cfg.bundle.depth, all);
+            if (json)
+                print(b);
+            else
+                io.out(b.text);
+            return 0;
+        }
+        case "stats": {
+            if (p.positional.length)
+                throw new UsageExit("stats takes no arguments");
+            const { check } = await import("../check/check.js");
+            const { manualWarnings } = await import("../check/evidence.js");
+            const { listEvidence } = await import("../tasks/evidence.js");
+            const { computeStats, statsTable } = await import("../stats/stats.js");
+            const s = computeStats(root, entries, check(root, cfg, data, true), manualWarnings(root, entries, listEvidence(root)), f.change);
+            if (f.write) {
+                const { writeStats } = await import("../stats/write.js");
+                const rel = writeStats(root, s);
+                if (!json)
+                    io.out(`wrote ${rel}\n`);
+            }
+            if (json)
+                print(s);
+            else
+                io.out(statsTable(s).map((l) => l + "\n").join(""));
+            return 0;
+        }
+        case "check": {
+            const r = await runCheck(root, cfg, data, !!f.strict);
+            if (json)
+                print({ baselined: r.baselined, count: r.findings.length, findings: r.findings, warnings: r.warnings });
+            else
+                io.out(checkText(r));
+            return r.findings.length ? 1 : 0;
+        }
+    }
+    throw new UsageExit(`unknown command: ${cmd}`);
+}
+async function init(p, io) {
+    const { runInit } = await import("../init/init.js");
+    if (p.positional.length)
+        throw new UsageExit("init takes no arguments");
+    const root = resolve(io.cwd, p.flags.root ?? ".");
+    const all = !!p.flags.all;
+    const r = runInit(root, { schema: all || !!p.flags.schema, skills: all || !!p.flags.skills, force: !!p.flags.force });
+    if (p.flags.json)
+        io.out(JSON.stringify(r, null, 2) + "\n");
+    else if (r.nothing)
+        io.out("nothing to do\nnext: specctx status\n");
+    else {
+        io.out(r.written.map((w) => `wrote ${w}\n`).join(""));
+        io.out(r.kept.map((k) => `kept ${k}\n`).join(""));
+        // REQ-CLI-007 init ends with the next step
+        io.out("next: specctx status\n");
+    }
+    return 0;
+}

package/dist/cli/errors.js

@@ -0,0 +1,3 @@
+// REQ-CLI-002 a usage or missing input error exits 2.
+export class UsageExit extends Error {
+}

package/dist/cli/gate.js

@@ -0,0 +1,187 @@
+// REQ-CLI-004 specctx gate: check, both linters, openspec validate, spec length. Stops at the first failure.
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { anyMatch, globRe } from "../util/glob.js";
+import { cmpStr } from "../util/pystr.js";
+export const DEFAULT_MARKDOWN = "openspec/**/*.md decisions/*.md docs/**/*.md *.md";
+const SKIP = new Set(["node_modules", ".git", ".ctx", "dist", "build"]);
+export function markdownFiles(root, globs) {
+    const res = globs.split(/\s+/).filter(Boolean).map(globRe);
+    const out = [];
+    const walk = (abs, rel) => {
+        let names;
+        try {
+            names = readdirSync(abs).sort(cmpStr);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const p = join(abs, n);
+            const r = rel ? `${rel}/${n}` : n;
+            let dir = false;
+            try {
+                dir = statSync(p).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (dir) {
+                if (!SKIP.has(n))
+                    walk(p, r);
+            }
+            else if (anyMatch(res, r))
+                out.push(r);
+        }
+    };
+    walk(root, "");
+    return out;
+}
+export const GATE_LOG = ".ctx/gate-log.jsonl";
+/** REQ-STAT-005 the gate steps in order. The log names the step that failed. */
+export const GATE_STEPS = ["check", "lint tells", "lint ste", "validate", "spec-length"];
+/** REQ-STAT-005 one JSON line per gate run, after the last step or at the first failure. */
+export function appendGateLog(root, line) {
+    mkdirSync(join(root, ".ctx"), { recursive: true });
+    const sorted = { at: line.at, duration_s: line.duration_s, failed_step: line.failed_step, ok: line.ok, steps: line.steps };
+    appendFileSync(join(root, GATE_LOG), JSON.stringify(sorted) + "\n");
+}
+export async function runGate(root, o, io) {
+    const start = Date.now();
+    const ran = [];
+    const r = await gateSteps(root, o, io, ran);
+    const { isoNow } = await import("../util/time.js");
+    appendGateLog(root, { at: isoNow(), ok: r === null, failed_step: r, duration_s: Math.round((Date.now() - start) / 1000), steps: [...ran] });
+    return r === null ? 0 : 1;
+}
+/** The gate steps. Returns null when every step passed, else the name of the failed step. */
+async function gateSteps(root, o, io, ran) {
+    // gate 1: build and check
+    ran.push("check");
+    const c = await o.check();
+    if (c.code !== 0) {
+        io.out("check: fail\n" + c.out);
+        return "check";
+    }
+    io.out(`check: ok${o.strict ? " (strict)" : ""}\n`);
+    // gate 2: REQ-LINT-003 both linters of this package on the markdown globs. No python3.
+    const { lintSte } = await import("../lint/ste.js");
+    const { lintTells } = await import("../lint/tells.js");
+    const { steReport } = await import("../lint/cli.js");
+    const files = markdownFiles(root, o.markdown);
+    const bad = [];
+    let tellsFailed = false;
+    ran.push("lint tells", "lint ste");
+    const noRotation = new Set(["synonym-rotation"]);
+    for (const f of files) {
+        const text = readFileSync(join(root, f), "utf8").replace(/\r\n?/g, "\n");
+        const tells = lintTells(text);
+        const hard = tells.filter((x) => x.level === "hard");
+        if (hard.length)
+            tellsFailed = true;
+        if (hard.length)
+            bad.push(`${f}\n` + tells.map((x) => `${f}:${x.line}: [${x.level}] ${x.rule}: ${x.match}\n`).join("") + `${hard.length} hard finding(s), baseline 0\n`);
+        const r = lintSte(text, f);
+        const ste = r.findings.filter((x) => !noRotation.has(x.rule));
+        const steHard = ste.filter((x) => x.level === "advisory-free").length;
+        if (steHard)
+            bad.push(`${f}\n` + steReport(ste, r.words, false, steHard, 0));
+    }
+    if (bad.length) {
+        io.out("linters: fail\n" + bad.join(""));
+        return tellsFailed ? "lint tells" : "lint ste";
+    }
+    io.out(`linters: ok (${files.length} file(s))\n`);
+    ran.push("validate");
+    // gate 3: openspec validate. SPECCTX_OPENSPEC replaces the command, for tests and offline use.
+    const cmd = process.env.SPECCTX_OPENSPEC ?? "npx -y @fission-ai/openspec@latest";
+    const v = spawnSync("/bin/sh", ["-c", `${cmd} validate --all${o.strict ? " --strict" : ""} --no-interactive`], { cwd: root, encoding: "utf8" });
+    if (v.status !== 0) {
+        io.out("validate: fail\n" + (v.stdout ?? "") + (v.stderr ?? ""));
+        return "validate";
+    }
+    io.out(`validate: ok${o.strict ? " (strict)" : ""}\n`);
+    ran.push("spec-length");
+    // gate 4: the length of every requirement in the deltas of active changes
+    const long = longRequirements(root);
+    if (long.length) {
+        io.out(long.map((l) => `spec-length: fail ${l.id} ${l.chars} chars\n`).join(""));
+        return "spec-length";
+    }
+    io.out("spec-length: ok\n");
+    return null;
+}
+// REQ-CLI-005 the limit strict validate applies to a requirement after archive
+export const MAX_REQUIREMENT_CHARS = 500;
+/** Lines inside a fenced code block, fence lines included. Same rule as OpenSpec. */
+function fenceMask(lines) {
+    const mask = new Array(lines.length).fill(false);
+    let open = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!open) {
+            const m = /^\s*(`{3,}|~{3,})/.exec(line);
+            if (m) {
+                open = { ch: m[1][0], len: m[1].length };
+                mask[i] = true;
+            }
+            continue;
+        }
+        mask[i] = true;
+        const c = /^\s*(`{3,}|~{3,})\s*$/.exec(line);
+        if (c && c[1][0] === open.ch && c[1].length >= open.len)
+            open = null;
+    }
+    return mask;
+}
+/**
+ * The requirement text as OpenSpec counts it: the trimmed, non-blank lines after the header,
+ * up to the first header line, joined with a newline. Metadata lines count only when nothing else is there.
+ */
+export function requirementText(body) {
+    const mask = fenceMask(body);
+    const text = [];
+    const meta = [];
+    for (let i = 0; i < body.length; i++) {
+        if (mask[i])
+            continue;
+        if (/^#{1,6}\s/.test(body[i]))
+            break;
+        const t = body[i].trim();
+        if (!t)
+            continue;
+        if (/^\*\*[^*]+\*\*:/.test(t))
+            meta.push(t);
+        else
+            text.push(t);
+    }
+    return (text.length ? text : meta).join("\n");
+}
+/** Every requirement over the limit in openspec/changes/<active>/specs/** /spec.md. */
+export function longRequirements(root) {
+    const out = [];
+    const changes = join(root, "openspec", "changes");
+    if (!existsSync(changes))
+        return out;
+    for (const c of readdirSync(changes).sort(cmpStr)) {
+        if (c === "archive" || !statSync(join(changes, c)).isDirectory())
+            continue;
+        for (const rel of markdownFiles(join(changes, c), "specs/**/spec.md")) {
+            const lines = readFileSync(join(changes, c, rel), "utf8").split(/\r?\n/);
+            const mask = fenceMask(lines);
+            for (let i = 0; i < lines.length; i++) {
+                const h = mask[i] ? null : /^###\s+Requirement:\s*(.*)$/.exec(lines[i]);
+                if (!h)
+                    continue;
+                let end = i + 1;
+                while (end < lines.length && (mask[end] || !/^#{1,3}\s/.test(lines[end])))
+                    end++;
+                const chars = requirementText(lines.slice(i + 1, end)).length; // UTF-16 units, as OpenSpec counts
+                if (chars > MAX_REQUIREMENT_CHARS)
+                    out.push({ id: h[1].trim().split(/\s+/)[0], chars, file: `openspec/changes/${c}/${rel}` });
+            }
+        }
+    }
+    return out;
+}