spec-ctx 0.0.0-stage → 0.1.1

package/dist/cli/workflow.js

@@ -0,0 +1,285 @@
+// REQ-IDS-001 REQ-TASK-001 REQ-TASK-002 REQ-TASK-003 REQ-TASK-005 REQ-VER-002 REQ-HND-001 write commands.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { dumps } from "../util/json.js";
+import { paint } from "./color.js";
+import { UsageExit } from "./errors.js";
+const arg = (c, n, what) => {
+    const v = c.p.positional[n];
+    if (v === undefined)
+        throw new UsageExit(`${c.p.command} needs ${what}`);
+    return v;
+};
+const noMore = (c, n) => {
+    if (c.p.positional.length > n)
+        throw new UsageExit(`${c.p.command} takes ${n} argument(s)`);
+};
+const print = (c, v) => c.io.out(dumps(v) + "\n");
+export async function runWorkflow(c) {
+    const entries = c.data.entries;
+    const f = c.p.flags;
+    switch (c.p.command) {
+        case "id new": {
+            const { newIds } = await import("../ids/ids.js");
+            const kind = arg(c, 0, "a kind: REQ, SCN, ADR, or DEC");
+            noMore(c, 2);
+            const ids = newIds(c.root, c.cfg, entries, {
+                kind, cap: c.p.positional[1], forReq: f.for, count: f.count ?? 1,
+            });
+            if (c.json)
+                print(c, ids);
+            else
+                c.io.out(ids.map((i) => i + "\n").join(""));
+            return 0;
+        }
+        case "id retire": {
+            const { retire } = await import("../ids/ids.js");
+            const id = arg(c, 0, "an ID");
+            const reason = c.p.positional.slice(1).join(" ");
+            const row = retire(c.root, entries, id, reason);
+            if (c.json)
+                print(c, { retired: id, row });
+            else
+                c.io.out(`retired ${id} in decisions/retired-ids.md\n`);
+            return 0;
+        }
+        case "task next": {
+            noMore(c, 0);
+            const { nextTask } = await import("../tasks/tasks.js");
+            const t = nextTask(c.root, entries, f.change);
+            if (!t) {
+                if (c.json)
+                    print(c, null);
+                else {
+                    // REQ-TASK-001 name the next step. The exit code stays 1.
+                    const { activeChanges } = await import("../tasks/tasks.js");
+                    const { matchesChange } = await import("../index/scan.js");
+                    const want = f.change;
+                    const ready = activeChanges(entries).filter((x) => !want || matchesChange(x, want));
+                    c.io.out(ready.length
+                        ? `no open task. Every task in the active changes is done. Next: archive ${ready.join(", ")}.\n`
+                        : "no open task. No active change has a task.\n");
+                }
+                return 1;
+            }
+            const bundleCommand = `specctx bundle ${t.reqs.join(" ")} --budget ${c.cfg.bundle.budget}`;
+            if (c.json) {
+                print(c, { bundle_command: bundleCommand, change: t.change, id: t.id, reqs: t.reqs, text: t.text, verify: t.verify.command });
+            }
+            else {
+                c.io.out(`${t.id}  ${t.text}\nreqs: ${t.reqs.join(", ") || "none"}\nverify: ${t.verify.command ?? "manual"}\n`);
+            }
+            return 0;
+        }
+        case "task start": {
+            const { findTask } = await import("../tasks/tasks.js");
+            const t = findTask(c.root, entries, arg(c, 0, "a task ID"));
+            noMore(c, 1);
+            if (t.done)
+                throw new UsageExit(`task ${t.id} is done`);
+            if (t.archived)
+                throw new UsageExit(`task ${t.id} is in an archived change`);
+            const { canon } = await import("../index/canonical.js");
+            const { bundle } = await import("../graph/bundle.js");
+            const ids = canon(entries);
+            const known = t.reqs.filter((r) => ids.has(r));
+            for (const r of t.reqs.filter((x) => !ids.has(x)))
+                c.io.err(`warning: task ${t.id} cites ${r}, which the index does not hold\n`);
+            const b = bundle(c.root, entries, known, c.cfg.bundle.budget, c.cfg.bundle.depth);
+            const { isoNow } = await import("../util/time.js");
+            const { CURRENT_PATH } = await import("../handoff/handoff.js");
+            mkdirSync(join(c.root, ".ctx"), { recursive: true });
+            const { cpLen } = await import("../util/pystr.js");
+            // REQ-STAT-002 the bundle size goes next to the current task, so stats can compute the context ratio
+            writeFileSync(join(c.root, CURRENT_PATH), dumps({ bundle_chars: cpLen(b.text), started_at: isoNow(), task: t.id }) + "\n");
+            if (c.json)
+                print(c, { bundle: b, task: t.id });
+            else
+                c.io.out(b.text + footer(cpLen(b.text), (await import("../stats/stats.js")).specCharsOf(entries)));
+            return 0;
+        }
+        case "task verify":
+        case "task done": {
+            const { findTask, setBox, hasEvidence } = await import("../tasks/tasks.js");
+            const t = findTask(c.root, entries, arg(c, 0, "a task ID"));
+            noMore(c, 1);
+            const dry = c.p.command === "task verify";
+            const manual = f.manual;
+            if (!dry && manual !== undefined) {
+                if (!manual.trim())
+                    throw new UsageExit("--manual needs a note");
+                if (t.done && hasEvidence(c.root, t))
+                    throw new UsageExit(`task ${t.id} is done`);
+                // a manual note records evidence without a run. On a task done by hand it backfills the evidence.
+                const { writeEvidence } = await import("../tasks/evidence.js");
+                const rel = writeEvidence(c.root, t, entries, { command: t.verify.command, exit: null, stdout_sha256: null, stderr_tail: "" }, "manual", manual.trim());
+                if (!t.done)
+                    setBox(c.root, t, true);
+                clearCurrent(c.root, t.id);
+                if (c.json)
+                    print(c, { evidence: rel, kind: "manual", task: t.id });
+                else
+                    c.io.out(paint("ok", `done ${t.id} (manual). Evidence: ${rel}\n`, c.io.tty));
+                return 0;
+            }
+            if (!dry && t.done)
+                throw new UsageExit(`task ${t.id} is done`);
+            if (t.verify.command === null) {
+                throw new UsageExit(`task ${t.id} has no Verify command. ${dry ? "Nothing to run" : 'A --manual "<note>" is required'}`);
+            }
+            const { runVerify, tail } = await import("../verify/run.js");
+            const { resolve: resolvePath, relative, isAbsolute } = await import("node:path");
+            let dir = c.root;
+            if (t.verify.cwd !== undefined) {
+                // REQ-VER-004 the cwd prefix must stay inside the project root
+                dir = resolvePath(c.root, t.verify.cwd);
+                const rel = relative(c.root, dir);
+                if (rel.startsWith("..") || isAbsolute(rel))
+                    throw new UsageExit(`the Verify cwd ${t.verify.cwd} is outside the project root`);
+                const { existsSync: exists } = await import("node:fs");
+                if (!exists(dir))
+                    throw new UsageExit(`the Verify cwd ${t.verify.cwd} does not exist`);
+            }
+            const r = await runVerify(t.verify.command, dir, c.cfg.verify.timeout_s);
+            const outTail = tail(r.output);
+            if (dry) {
+                if (c.json)
+                    print(c, { command: t.verify.command, exit: r.exit, tail: outTail, timed_out: r.timedOut });
+                else
+                    c.io.out(`${outTail ? outTail + "\n" : ""}exit ${r.timedOut ? "timeout" : r.exit}\n`);
+                return r.exit === 0 ? 0 : 1;
+            }
+            if (r.timedOut || r.exit !== 0) {
+                const msg = r.timedOut ? `verify timed out after ${c.cfg.verify.timeout_s}s` : `verify failed with exit ${r.exit}`;
+                if (c.json)
+                    print(c, { command: t.verify.command, error: msg, exit: r.exit, tail: outTail, task: t.id });
+                else
+                    c.io.out(outTail ? outTail + "\n" : "");
+                // REQ-VER-003 a timeout keeps its own line on stderr
+                if (r.timedOut)
+                    c.io.err(`specctx: ${msg}. Task ${t.id} stays open.\n`);
+                // REQ-TASK-003 the refusal is the last line of the output. REQ-CLI-008 it is red on a TTY.
+                else if (!c.json)
+                    c.io.out(paint("fail", `Verify failed (exit ${r.exit}). The task stays open.\n`, c.io.tty));
+                return 1;
+            }
+            const { sha256 } = await import("../util/hash.js");
+            const { writeEvidence } = await import("../tasks/evidence.js");
+            // 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;
+            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", undefined, t.verify.cwd);
+            setBox(c.root, t, true);
+            clearCurrent(c.root, t.id);
+            if (c.json)
+                print(c, { evidence: rel, kind: "command", task: t.id });
+            else
+                c.io.out(paint("ok", `done ${t.id}. Evidence: ${rel}\n`, c.io.tty)); // REQ-CLI-008
+            return 0;
+        }
+        case "task backfill": {
+            // REQ-TASK-006 manual evidence for every ticked task that has none, through the task done --manual path
+            noMore(c, 0);
+            const note = f.manual?.trim();
+            if (!note)
+                throw new UsageExit('task backfill needs --manual "<note>"');
+            const { tasksOf, toTask, hasEvidence } = await import("../tasks/tasks.js");
+            const { matchesChange } = await import("../index/scan.js");
+            const { writeEvidence } = await import("../tasks/evidence.js");
+            const want = f.change;
+            const counts = new Map();
+            for (const e of tasksOf(entries)) {
+                if (e.status !== "done")
+                    continue;
+                if (want && !matchesChange(e.change, want))
+                    continue;
+                if (hasEvidence(c.root, e))
+                    continue;
+                const t = toTask(c.root, e);
+                writeEvidence(c.root, t, entries, { command: t.verify.command, exit: null, stdout_sha256: null, stderr_tail: "" }, "manual", note);
+                counts.set(e.change, (counts.get(e.change) ?? 0) + 1);
+            }
+            const { cmpStr } = await import("../util/pystr.js");
+            const rows = [...counts.keys()].sort(cmpStr).map((k) => ({ change: k, count: counts.get(k) }));
+            const total = rows.reduce((n, r) => n + r.count, 0);
+            if (c.json)
+                print(c, { changes: rows, total });
+            else
+                c.io.out(rows.map((r) => `${r.change}: ${r.count}\n`).join("") + `backfilled ${total} task(s)\n`);
+            return 0;
+        }
+        case "task reopen": {
+            const { findTask, setBox } = await import("../tasks/tasks.js");
+            const t = findTask(c.root, entries, arg(c, 0, "a task ID"));
+            const reason = c.p.positional.slice(1).join(" ").trim();
+            if (!reason)
+                throw new UsageExit("task reopen needs a reason");
+            if (!t.done)
+                throw new UsageExit(`task ${t.id} is open`);
+            if (t.archived)
+                throw new UsageExit(`task ${t.id} is in an archived change`);
+            const { retireEvidence } = await import("../tasks/evidence.js");
+            const { addReopened } = await import("../handoff/handoff.js");
+            setBox(c.root, t, false);
+            const moved = retireEvidence(c.root, t, reason);
+            addReopened(c.root, entries, t.id, reason);
+            if (c.json)
+                print(c, { evidence: moved, task: t.id });
+            else
+                c.io.out(`reopened ${t.id}.${moved ? ` Old evidence: ${moved}` : ""}\n`);
+            return 0;
+        }
+        case "handoff write": {
+            noMore(c, 0);
+            const { writeHandoff, HANDOFF_PATH } = await import("../handoff/handoff.js");
+            const h = writeHandoff(c.root, entries);
+            if (c.json)
+                print(c, h);
+            else
+                c.io.out(`wrote ${HANDOFF_PATH}\n`);
+            return 0;
+        }
+        case "handoff ask": {
+            const { ask } = await import("../handoff/handoff.js");
+            const h = ask(c.root, entries, c.p.positional.join(" "));
+            if (c.json)
+                print(c, { open_questions: h.open_questions });
+            else
+                c.io.out(`open question ${h.open_questions.length} added\n`);
+            return 0;
+        }
+        case "handoff resolve": {
+            const { resolve } = await import("../handoff/handoff.js");
+            const n = arg(c, 0, "a question number");
+            if (!/^\d+$/.test(n))
+                throw new UsageExit("handoff resolve needs a question number");
+            const h = resolve(c.root, entries, Number(n), c.p.positional.slice(1).join(" "));
+            if (c.json)
+                print(c, { open_questions: h.open_questions, resolved: h.resolved });
+            else
+                c.io.out(`resolved question ${n}\n`);
+            return 0;
+        }
+    }
+    throw new UsageExit(`unknown command: ${c.p.command}`);
+}
+function clearCurrent(root, task) {
+    const p = join(root, ".ctx/current.json");
+    if (!existsSync(p))
+        return;
+    try {
+        const cur = JSON.parse(readFileSync(p, "utf8"));
+        if (cur.task === task)
+            rmSync(p);
+    }
+    catch {
+        // a damaged current.json stays for the user to read
+    }
+}
+// REQ-TASK-002 the footer of task start: the bundle size and its share of the spec text. bundle never prints it.
+export function footer(n, m) {
+    const p = m > 0 ? Math.round((n / m) * 1000) / 10 : 0;
+    return `-- bundle ${n} chars, ${p}% of ${m} chars of spec text\n`;
+}

package/dist/cli.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// REQ-CLI-001 bin entry. tests call main() from src/main.ts in process.
+import { main } from "./main.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,
+});
+process.exitCode = code;

package/dist/config.js

@@ -0,0 +1,119 @@
+// REQ-DIST-002 spec-ctx.toml with defaults from REQ-IDX-001 and REQ-QRY-003.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "smol-toml";
+export const CONFIG_FILE = "spec-ctx.toml";
+export function defaults() {
+    return {
+        scan: {
+            specs: ["openspec/specs/**/*.md"],
+            changes: ["openspec/changes/**/*.md"],
+            decisions: ["decisions/*.md"],
+            code: ["src/**"],
+            tests: ["tests/**"],
+            ignore: [],
+        },
+        ids: { caps: [], task_pattern: "\\d+\\.\\d+", paths: {} },
+        bundle: { budget: 8000, depth: 1 },
+        verify: { timeout_s: 600 },
+    };
+}
+export class ConfigError extends Error {
+}
+function strList(v, key) {
+    if (typeof v === "string")
+        return [v];
+    if (Array.isArray(v) && v.every((x) => typeof x === "string"))
+        return v;
+    throw new ConfigError(`${CONFIG_FILE}: ${key} must be a string or a list of strings.`);
+}
+/** Read the config of a project root. A missing file gives all defaults. */
+export function loadConfig(root) {
+    const cfg = defaults();
+    const p = join(root, CONFIG_FILE);
+    if (!existsSync(p))
+        return cfg;
+    let raw;
+    try {
+        raw = parse(readFileSync(p, "utf8"));
+    }
+    catch (e) {
+        throw new ConfigError(`${CONFIG_FILE}: the file is not valid TOML. ${e.message.split("\n")[0]}`);
+    }
+    const sec = (name) => {
+        const v = raw[name];
+        return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
+    };
+    const scan = sec("scan");
+    for (const k of Object.keys(cfg.scan)) {
+        if (k in scan)
+            cfg.scan[k] = strList(scan[k], `scan.${k}`);
+    }
+    const ids = sec("ids");
+    if ("caps" in ids)
+        cfg.ids.caps = strList(ids.caps, "ids.caps");
+    if ("task_pattern" in ids) {
+        if (typeof ids.task_pattern !== "string")
+            throw new ConfigError(`${CONFIG_FILE}: ids.task_pattern must be a string.`);
+        cfg.ids.task_pattern = ids.task_pattern;
+    }
+    if ("paths" in ids) {
+        const v = ids.paths;
+        if (v === null || typeof v !== "object" || Array.isArray(v) || !Object.values(v).every((x) => typeof x === "string")) {
+            throw new ConfigError(`${CONFIG_FILE}: ids.paths must be a table of code = "capability path".`);
+        }
+        cfg.ids.paths = { ...v };
+    }
+    const bundle = sec("bundle");
+    for (const k of ["budget", "depth"]) {
+        if (k in bundle) {
+            const v = bundle[k];
+            if (typeof v !== "number" || !Number.isInteger(v) || v < 0) {
+                throw new ConfigError(`${CONFIG_FILE}: bundle.${k} must be an integer of 0 or more.`);
+            }
+            cfg.bundle[k] = v;
+        }
+    }
+    const verify = sec("verify");
+    if ("timeout_s" in verify) {
+        const v = verify.timeout_s;
+        if (typeof v !== "number" || !(v > 0))
+            throw new ConfigError(`${CONFIG_FILE}: verify.timeout_s must be a number above 0.`);
+        cfg.verify.timeout_s = v;
+    }
+    return cfg;
+}
+/** The file that `specctx init` writes. Each key has a comment above it. */
+export const INIT_TEXT = `# spec-ctx configuration. Every key is optional. A missing key takes its default.
+
+[scan]
+# Main specs. Markdown files with requirement and scenario headers.
+specs = ["openspec/specs/**/*.md"]
+# Active and archived OpenSpec changes.
+changes = ["openspec/changes/**/*.md"]
+# Decision records.
+decisions = ["decisions/*.md"]
+# Source files that carry code tags. A code tag is a comment with a REQ ID.
+code = ["src/**"]
+# Test files that carry Covers tags and scenario IDs.
+tests = ["tests/**"]
+# Paths that the scan skips.
+ignore = []
+
+[ids]
+# Capability codes. check reports a REQ whose code is not in this list. id new accepts only these codes.
+# An empty list turns the rule off, and id new accepts any code of 2 to 6 upper case letters.
+caps = []
+# Pattern of the task number in a tasks.md checkbox.
+task_pattern = '\\d+\\.\\d+'
+
+[bundle]
+# Default character budget of a bundle.
+budget = 8000
+# Default depth of related entries in a bundle.
+depth = 1
+
+[verify]
+# Seconds before task done stops a Verify command.
+timeout_s = 600
+`;

package/dist/graph/bundle.js

@@ -0,0 +1,94 @@
+// REQ-QRY-003 canonical text with one provenance line per block, in a fixed order, within a budget.
+import { join } from "node:path";
+import { canon } from "../index/canonical.js";
+import { blockRange, readText } from "../index/scan.js";
+import { cmpTuple, cpLen, pyStrip, splitLines } from "../util/pystr.js";
+import { KIND_RANK, related } from "./related.js";
+export class Lines {
+    cache = new Map();
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    get(rpath) {
+        let l = this.cache.get(rpath);
+        if (!l)
+            this.cache.set(rpath, (l = splitLines(readText(join(this.root, rpath)))));
+        return l;
+    }
+}
+/** Markdown text of an entry. Code and test entries print no body, only their provenance line. */
+export function blockText(e, files) {
+    if (e.kind === "code" || e.kind === "test")
+        return "";
+    const lines = files.get(e.file);
+    const start = e.line - 1;
+    if (e.kind === "task")
+        return pyStrip(lines[start] ?? "") + "\n";
+    if (e.kind === "decision") {
+        const out = [lines[start] ?? ""];
+        for (const line of lines.slice(start + 1)) {
+            if (!pyStrip(line) || line.startsWith("- ") || line.startsWith("#"))
+                break;
+            out.push(line);
+        }
+        return rstrip(out.join("\n")) + "\n";
+    }
+    const [s, end] = blockRange(lines, start);
+    return rstrip(lines.slice(s, end).join("\n")) + "\n";
+}
+function rstrip(s) {
+    const t = pyStrip("x" + s);
+    return t.slice(1);
+}
+export function provenance(e, reason) {
+    return `-- ${e.id} | ${e.file}:${e.line} | ${e.status} | ${reason}\n`;
+}
+export function bundle(root, entries, wanted, budget, depth, all = false) {
+    const ids = canon(entries);
+    const blocks = [];
+    for (const i of wanted) {
+        const copies = [ids.get(i)];
+        if (all)
+            copies.push(...entries.filter((e) => e.id === i && !e.canonical));
+        for (const e of copies)
+            blocks.push([e, "requested"]);
+    }
+    const found = new Map();
+    for (const i of wanted) {
+        // decisions that reference a requested ID are included at every depth
+        for (const e of entries) {
+            if (e.kind === "decision" && e.refs.includes(i) && !found.has(e.id))
+                found.set(e.id, `decision for ${i}`);
+        }
+        for (const [r, reason] of related(entries, i, depth, all)) {
+            if (!wanted.includes(r) && !found.has(r))
+                found.set(r, reason);
+        }
+    }
+    // scenarios print inside their requirement
+    const tail = [...found.keys()].filter((r) => ids.has(r) && ids.get(r).kind !== "scn");
+    tail.sort((a, b) => cmpTuple([KIND_RANK[ids.get(a).kind] ?? 9, a], [KIND_RANK[ids.get(b).kind] ?? 9, b]));
+    for (const r of tail)
+        blocks.push([ids.get(r), found.get(r)]);
+    const files = new Lines(root);
+    const out = [];
+    const omitted = [];
+    let used = 0;
+    for (const [e, reason] of blocks) {
+        const body = blockText(e, files);
+        // a blank line closes a block with a body. Code and test paths stay one line each.
+        const t = provenance(e, reason) + body + (body ? "\n" : "");
+        const n = cpLen(t);
+        if (used + n > budget) {
+            omitted.push(e.id);
+            continue;
+        }
+        out.push(t);
+        used += n;
+    }
+    let text = out.join("");
+    if (omitted.length)
+        text += `truncated: ${omitted.length} entries omitted: ${omitted.join(", ")}\n`;
+    return { text, omitted };
+}

package/dist/graph/query.js

@@ -0,0 +1,31 @@
+// REQ-QRY-001 token AND over id, title, text. Score 3 for id, 2 for title, 1 for text, per term.
+import { poolOf } from "../index/canonical.js";
+import { matchesChange } from "../index/scan.js";
+import { cmpTuple, pySplit } from "../util/pystr.js";
+export function query(entries, args, o = {}) {
+    const terms = args.flatMap((a) => pySplit(a.toLowerCase()));
+    const hits = [];
+    for (const e of poolOf(entries, !!o.all)) {
+        if ((o.kind && e.kind !== o.kind) || (o.change && !matchesChange(e.change, o.change)))
+            continue;
+        // REQ-IDX-005 --change takes a key or a full folder name
+        const idl = e.id.toLowerCase();
+        const tl = e.title.toLowerCase();
+        const xl = e.text ?? "";
+        if (!terms.every((t) => idl.includes(t) || tl.includes(t) || xl.includes(t)))
+            continue;
+        let score = 0;
+        for (const t of terms)
+            score += 3 * +idl.includes(t) + 2 * +tl.includes(t) + +xl.includes(t);
+        hits.push([-score, e.id, e.file, e.line, e]);
+    }
+    hits.sort((a, b) => cmpTuple(a.slice(0, 4), b.slice(0, 4)));
+    let out = hits.map((h) => h[4]);
+    const limit = o.limit ?? 20;
+    if (limit > 0)
+        out = out.slice(0, limit);
+    return out;
+}
+export function queryLine(e) {
+    return `${e.id}  ${e.kind}  ${e.status}  ${e.file}:${e.line}  ${e.title}`;
+}

package/dist/graph/related.js

@@ -0,0 +1,76 @@
+// REQ-QRY-002 IDs reachable from a start ID, with the reason each one was included.
+import { canon, poolOf } from "../index/canonical.js";
+import { cmpStr, cmpTuple } from "../util/pystr.js";
+// REQ-QRY-003 fixed block order after the requested IDs
+export const KIND_RANK = { adr: 0, decision: 1, req: 2, scn: 2, task: 3, code: 4, test: 5 };
+export const REASONS = ["scenario of", "ref from", "ref to", "decision for", "task cites", "implements", "covers"];
+export function related(entries, start, depth, all = false) {
+    const pool = poolOf(entries, all);
+    const ids = canon(entries);
+    for (const e of pool)
+        if (!ids.has(e.id))
+            ids.set(e.id, e);
+    const back = new Map();
+    for (const e of pool) {
+        for (const r of e.refs) {
+            let s = back.get(r);
+            if (!s)
+                back.set(r, (s = new Set()));
+            s.add(e.id);
+        }
+    }
+    const found = new Map();
+    const add = (i, reason) => {
+        if (i !== start && !found.has(i)) {
+            found.set(i, reason);
+            return true;
+        }
+        return false;
+    };
+    const s = ids.get(start);
+    if (s && s.kind === "req")
+        for (const sid of s.scenarios ?? [])
+            add(sid, `scenario of ${start}`);
+    let frontier = [start];
+    for (let d = 0; d < depth; d++) {
+        const nxt = [];
+        for (const x of frontier) {
+            const ex = ids.get(x);
+            if (ex) {
+                for (const r of ex.refs)
+                    if (add(r, `ref from ${x}`))
+                        nxt.push(r);
+                if (ex.kind === "req") {
+                    for (const sid of ex.scenarios ?? [])
+                        if (add(sid, `scenario of ${x}`))
+                            nxt.push(sid);
+                }
+            }
+            for (const y of [...(back.get(x) ?? [])].sort(cmpStr)) {
+                const ey = ids.get(y);
+                const k = ey ? ey.kind : "?";
+                let reason;
+                if (k === "scn" && ex && (ex.scenarios ?? []).includes(y))
+                    reason = `scenario of ${x}`;
+                else if (k === "decision")
+                    reason = `decision for ${x}`;
+                else if (k === "task")
+                    reason = `task cites ${x}`;
+                else if (k === "code")
+                    reason = `implements ${x}`;
+                else if (k === "test")
+                    reason = `covers ${x}`;
+                else
+                    reason = `ref to ${x}`;
+                if (add(y, reason))
+                    nxt.push(y);
+            }
+        }
+        frontier = nxt;
+    }
+    const rank = (i) => {
+        const e = ids.get(i);
+        return [e ? (KIND_RANK[e.kind] ?? 9) : 9, i];
+    };
+    return [...found.keys()].sort((a, b) => cmpTuple(rank(a), rank(b))).map((i) => [i, found.get(i)]);
+}