spec-ctx 0.3.0 → 0.4.1

package/dist/gate/rerun.js

@@ -0,0 +1,169 @@
+// REQ-VER-013 REQ-VER-005 REQ-VER-006 REQ-VER-007 the rerun step: the tasks a range closed, the compare, the groups (036/D1).
+import { spawnSync } from "node:child_process";
+import { changeKey, changeOf } from "../index/scan.js";
+import { cmpStr } from "../util/pystr.js";
+function git(root, args) {
+    const r = spawnSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    return { ok: r.status === 0, out: (r.stdout ?? "").trim() };
+}
+/** REQ-VER-005 the one line of a failed merge base. A shallow clone gets a second sentence. */
+export function noMergeBaseLine(root, base) {
+    const shallow = git(root, ["rev-parse", "--is-shallow-repository"]);
+    const tail = shallow.ok && shallow.out === "true" ? ". This clone is shallow" : "";
+    return `rerun: no merge base with ${base}, fetch full history (fetch-depth: 0)${tail}`;
+}
+/** REQ-VER-005 the task ID order: the change key, then the group and the number as integers. */
+export function cmpTaskId(a, b) {
+    const [ka, na = ""] = a.split("/");
+    const [kb, nb = ""] = b.split("/");
+    const k = cmpStr(ka, kb);
+    if (k !== 0)
+        return k;
+    const pa = na.split(".").map(Number);
+    const pb = nb.split(".").map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? -1) - (pb[i] ?? -1);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** REQ-VER-005 the task lines of one tasks.md text, with the key that the index would give them. */
+export function parseTasksFile(path, text, taskRe) {
+    const key = changeKey(changeOf(path));
+    const archived = path.includes("/archive/");
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+        const m = taskRe.exec(line);
+        if (m)
+            out.push({ id: `${key}/${m[2]}`, done: m[1].toLowerCase() === "x", archived });
+    }
+    return out;
+}
+/** REQ-VER-005 one state per ID. An active copy wins over an archived copy, as findTask does. */
+export function mergeStates(states) {
+    const out = new Map();
+    for (const s of states) {
+        const had = out.get(s.id);
+        if (!had || (had.archived && !s.archived))
+            out.set(s.id, s);
+    }
+    return out;
+}
+/** REQ-VER-005 the state of every task in the tasks.md files at a commit. */
+export function tasksAt(root, sha, taskRe) {
+    const ls = git(root, ["ls-tree", "-z", "-r", "--name-only", sha, "--", "openspec/changes"]);
+    const all = [];
+    if (!ls.ok)
+        return new Map();
+    for (const p of ls.out.split("\0").filter((x) => x.endsWith("/tasks.md")).sort(cmpStr)) {
+        const show = spawnSync("git", ["show", `${sha}:${p}`], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+        if (show.status === 0)
+            all.push(...parseTasksFile(p, show.stdout, taskRe));
+    }
+    return mergeStates(all);
+}
+/** REQ-VER-005 the index entries of tasks, one per ID. The active copy wins. */
+export function headStates(entries) {
+    const out = new Map();
+    for (const e of entries) {
+        if (e.kind !== "task")
+            continue;
+        const archived = e.file.includes("/archive/");
+        const had = out.get(e.id);
+        if (!had || (had.state.archived && !archived))
+            out.set(e.id, { state: { id: e.id, done: e.status === "done", archived }, entry: e });
+    }
+    return out;
+}
+/** REQ-VER-010 the commit that HEAD names, or "" when git fails. */
+export function headSha(root) {
+    const h = git(root, ["rev-parse", "HEAD"]);
+    return h.ok ? h.out : "";
+}
+/** REQ-VER-010 the line for a merge base equal to HEAD. */
+export const HEAD_BASE_LINE = "rerun: merge base is HEAD, nothing to compare. On push, pass --base <the commit before the push>";
+/** REQ-VER-013 the line for a base of forty zeros, the `before` of a push that creates a branch. */
+export const ZERO_BASE_LINE = "rerun: base is the zero commit (a new branch), nothing to compare";
+/** REQ-VER-013 a base that ends the rerun before the merge base: the zero commit passes, an unknown commit fails. */
+export function baseProblem(root, base) {
+    if (/^0{40}$/.test(base))
+        return { ok: true, line: ZERO_BASE_LINE };
+    const known = !base.startsWith("-") && git(root, ["rev-parse", "--verify", "--quiet", `${base}^{commit}`]).ok;
+    if (known)
+        return null;
+    return { ok: false, line: `rerun: base ${base} is not in this clone. Fetch it or use fetch-depth: 0` };
+}
+/**
+ * REQ-VER-005 the tasks that are done at HEAD and open or absent at the merge base, in ID order.
+ * `entries` is the live index. `taskRe` is the task regex of the scanner.
+ */
+export function closedTasks(root, base, entries, taskRe) {
+    const mb = git(root, ["merge-base", "HEAD", base]);
+    if (!mb.ok || !mb.out)
+        return { ok: false, line: noMergeBaseLine(root, base) };
+    const before = tasksAt(root, mb.out, taskRe);
+    const tasks = [];
+    for (const [id, { state, entry }] of headStates(entries)) {
+        if (state.done && !before.get(id)?.done)
+            tasks.push(entry);
+    }
+    tasks.sort((a, b) => cmpTaskId(a.id, b.id));
+    return { ok: true, mergeBase: mb.out, tasks };
+}
+/** REQ-VER-006 compare one closed task with its evidence, in the fixed order of 036/D4. */
+export function compare(verify, evidence, strict, weak) {
+    if (evidence !== null && evidence.kind === "manual")
+        return strict ? { act: "fail", kind: "manual" } : { act: "warn", why: "manual" };
+    if (evidence === null)
+        return { act: "fail", kind: "no-evidence" };
+    const cwd = evidence.cwd ?? ".";
+    if (verify.command !== evidence.command || (verify.cwd ?? ".") !== cwd) {
+        return { act: "fail", kind: "verify-drift", detail: `tasks.md has ${verify.command ?? "no command"}${verify.cwd ? ` (cwd ${verify.cwd})` : ""}, evidence has ${evidence.command ?? "no command"}${evidence.cwd ? ` (cwd ${evidence.cwd})` : ""}` };
+    }
+    if (evidence.command === null)
+        return { act: "fail", kind: "no-evidence" };
+    if (strict && weak(evidence.command))
+        return { act: "fail", kind: "weak-verify" };
+    return { act: "run", command: evidence.command, cwd, expected: evidence.exit };
+}
+/** REQ-VER-007 the key that makes two runs the same run. */
+export const runKey = (v) => `${v.cwd}\u0000${v.command}`;
+/** REQ-VER-007 one group per frozen command and cwd, in the ID order of the first task. */
+export function groupRuns(items) {
+    const sorted = [...items].sort((a, b) => cmpTaskId(a.id, b.id));
+    const groups = new Map();
+    for (const it of sorted) {
+        const key = runKey(it);
+        const g = groups.get(key);
+        if (g)
+            g.members.push(it);
+        else
+            groups.set(key, { key, command: it.command, cwd: it.cwd, members: [it] });
+    }
+    return [...groups.values()];
+}
+/** REQ-VER-006 ok when the exit code equals the evidence. A timeout or a different code is a mismatch. */
+export function judge(expected, o) {
+    return !o.timedOut && o.exit !== null && o.exit === expected ? "ok" : "mismatch";
+}
+const shq = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+/** REQ-VER-007 the line that runs the frozen command on a developer machine as the rerun runs it. */
+export function reproduceLine(command, cwd) {
+    return `reproduce: cd ${shq(cwd)} && env CI=1 SPECCTX_RERUN=1 sh -c ${shq(command)}`;
+}
+/** REQ-VER-007 the report of a mismatch. The output tail is the last 20 lines. */
+export function formatMismatch(m) {
+    const tailLines = m.outcome.output.replace(/\n$/, "") === "" ? [] : m.outcome.output.replace(/\n$/, "").split("\n").slice(-20);
+    const actual = m.outcome.timedOut ? `timed out after ${m.timeoutS}s` : `exit ${m.outcome.exit}`;
+    return [
+        `${m.id}: mismatch`,
+        `  at ${m.file}:${m.line}`,
+        `  evidence ${m.evidence}`,
+        `  expected exit ${m.expected}`,
+        `  actual ${actual}`,
+        "  output (last 20 lines):",
+        ...tailLines.map((l) => `    ${l}`),
+        `  ${reproduceLine(m.command, m.cwd)}`,
+    ].join("\n") + "\n";
+}

package/dist/graph/bundle.js

@@ -1,9 +1,9 @@
 // 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 { canon, poolOf } 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";
+import { cmpStr, cmpTuple, cpLen, pyStrip, splitLines } from "../util/pystr.js";
+import { KIND_RANK, mainVersion, walkFound } from "./related.js";
 export class Lines {
     cache = new Map();
     root;
@@ -19,7 +19,8 @@ export class Lines {
 }
 /** 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")
+    // REQ-QRY-009 a capability or a change prints its provenance line only
+    if (e.kind === "code" || e.kind === "test" || e.kind === "cap" || e.kind === "change")
         return "";
     const lines = files.get(e.file);
     const start = e.line - 1;
@@ -44,50 +45,168 @@ function rstrip(s) {
 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) {
+/** REQ-QRY-004 the canonical blocks of requirements, joined by one blank line, with no provenance line. */
+export function reqBlocks(root, reqs) {
+    const files = new Lines(root);
+    return reqs.map((e) => blockText(e, files)).join("\n");
+}
+/** REQ-QRY-012 the budget class of a block (046/D7). A lower class keeps its place first. */
+function budgetClass(e, requested, hit) {
+    if (requested)
+        return 0;
+    if (!hit || hit.depth >= 2)
+        return 3;
+    if (e.kind === "code" || e.kind === "test")
+        return 1;
+    if (e.kind === "decision" && e.status === "archived")
+        return 3;
+    return 2;
+}
+/**
+ * REQ-QRY-016 REQ-QRY-017 the requirements that the task cites or that the file tags, and the code and test
+ * entries of each, from one pass over the pool (047/D3, 047/D7). The entries get depth 1.
+ */
+function reach(entries, ids, wanted, all) {
+    const cited = [];
+    const tagged = [];
+    const add = (list, r) => {
+        if (ids.get(r)?.kind === "req" && !cited.includes(r) && !tagged.includes(r))
+            list.push(r);
+    };
+    const pool = poolOf(entries, all);
+    for (const i of wanted) {
+        const e = ids.get(i);
+        if (e?.kind === "task")
+            for (const r of e.refs)
+                add(cited, r);
+        // a requested input that is no ID is a path. Only the tags of the file count, not a mention in a task line.
+        else if (!e)
+            for (const x of pool)
+                if (x.file === i && (x.kind === "code" || x.kind === "test"))
+                    for (const r of x.refs)
+                        add(tagged, r);
+    }
+    const lines = new Map();
+    if (!cited.length && !tagged.length)
+        return { cited, lines };
+    const want = new Set([...cited, ...tagged]);
+    const back = new Map();
+    for (const x of pool) {
+        if (x.kind !== "code" && x.kind !== "test")
+            continue;
+        for (const r of x.refs) {
+            if (!want.has(r))
+                continue;
+            let l = back.get(r);
+            if (!l)
+                back.set(r, (l = []));
+            l.push(x);
+        }
+    }
+    for (const r of [...cited, ...tagged]) {
+        for (const x of (back.get(r) ?? []).sort((a, b) => cmpStr(a.id, b.id))) {
+            if (!lines.has(x.id))
+                lines.set(x.id, { reason: `${x.kind === "code" ? "implements" : "covers"} ${r}`, depth: 1 });
+        }
+    }
+    return { cited, lines };
+}
+export function bundle(root, entries0, wanted, budget, depth, opts = {}) {
+    const all = !!opts.all;
+    // 047/D5 the entry that the caller found stands for its ID. It goes last, so canon() holds it.
+    const entries = opts.task && canon(entries0).get(opts.task.id) !== opts.task ? [...entries0.filter((e) => e !== opts.task), opts.task] : entries0;
     const ids = canon(entries);
+    // block, reason, class. The array is in print order.
     const blocks = [];
     for (const i of wanted) {
+        // REQ-QRY-005 a path has no block of its own. Its links come from related below.
+        if (!ids.has(i))
+            continue;
         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"]);
+            blocks.push([e, "requested", 0]);
+        // REQ-QRY-010 the main version of a modified requirement, also for a requested ID
+        const m = all ? undefined : mainVersion(entries, i);
+        if (m)
+            blocks.push([m, `main version of ${i}`, 0]);
     }
     const found = new Map();
     for (const i of wanted) {
-        // decisions that reference a requested ID are included at every depth
+        // decisions that reference a requested ID are included at every depth, as depth 1.
+        // REQ-QRY-016 They replace a deeper hit, which the walk for an earlier requested ID can leave (048/D1).
         for (const e of entries) {
-            if (e.kind === "decision" && e.refs.includes(i) && !found.has(e.id))
-                found.set(e.id, `decision for ${i}`);
+            if (e.kind !== "decision" || !e.refs.includes(i))
+                continue;
+            const cur = found.get(e.id);
+            if (!cur || cur.depth > 1)
+                found.set(e.id, { reason: `decision for ${i}`, depth: 1 });
         }
-        for (const [r, reason] of related(entries, i, depth, all)) {
+        for (const [r, hit] of walkFound(entries, i, depth, all)) {
             if (!wanted.includes(r) && !found.has(r))
-                found.set(r, reason);
+                found.set(r, hit);
+        }
+    }
+    // REQ-QRY-016 REQ-QRY-017 the cited requirements, their decisions, and the lines of the requirements of a task or a file
+    const r = depth >= 1 ? reach(entries, ids, wanted, all) : { cited: [], lines: new Map() };
+    const citedSet = new Set(r.cited);
+    for (const t of wanted) {
+        const te = ids.get(t);
+        if (te?.kind !== "task")
+            continue;
+        for (const c of te.refs)
+            if (citedSet.has(c) && !wanted.includes(c) && !found.has(c))
+                found.set(c, { reason: `ref from ${t}`, depth: 1 });
+    }
+    for (const c of r.cited) {
+        for (const e of entries) {
+            if (e.kind !== "decision" || !e.refs.includes(c))
+                continue;
+            const cur = found.get(e.id);
+            if (!cur || cur.depth > 1)
+                found.set(e.id, { reason: `decision for ${c}`, depth: 1 });
         }
     }
+    for (const [id, hit] of r.lines) {
+        const cur = found.get(id);
+        if (!wanted.includes(id) && (!cur || cur.depth > 1))
+            found.set(id, hit);
+    }
     // scenarios print inside their requirement
-    const tail = [...found.keys()].filter((r) => ids.has(r) && ids.get(r).kind !== "scn");
+    const tail = [...found.keys()].filter((x) => ids.has(x) && ids.get(x).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)]);
+    for (const r2 of tail) {
+        const hit = found.get(r2);
+        const e = ids.get(r2);
+        const cls = citedSet.has(r2) ? 0 : budgetClass(e, false, hit);
+        blocks.push([e, hit.reason, cls]);
+        const m = all ? undefined : mainVersion(entries, r2);
+        if (m)
+            blocks.push([m, `main version of ${r2}`, cls]);
+    }
     const files = new Lines(root);
-    const out = [];
-    const omitted = [];
-    let used = 0;
-    for (const [e, reason] of blocks) {
+    const texts = blocks.map(([e, reason]) => {
         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;
+        return provenance(e, reason) + body + (body ? "\n" : "");
+    });
+    // fill the budget class by class, in print order inside a class, and skip a block that does not fit
+    const keep = blocks.map(() => false);
+    let used = 0;
+    for (let cls = 0; cls <= 3; cls++) {
+        for (let k = 0; k < blocks.length; k++) {
+            if (blocks[k][2] !== cls)
+                continue;
+            const n = cpLen(texts[k]);
+            if (used + n > budget)
+                continue;
+            keep[k] = true;
+            used += n;
         }
-        out.push(t);
-        used += n;
     }
-    let text = out.join("");
+    const omitted = blocks.filter((_, k) => !keep[k]).map(([e]) => e.id);
+    let text = texts.filter((_, k) => keep[k]).join("");
     if (omitted.length)
         text += `truncated: ${omitted.length} entries omitted: ${omitted.join(", ")}\n`;
     return { text, omitted };

package/dist/graph/files.js

@@ -0,0 +1,31 @@
+// REQ-QRY-006 the links of one file: code tags, Covers tags, and paths that active task lines name.
+import { canon } from "../index/canonical.js";
+import { cmpStr } from "../util/pystr.js";
+/**
+ * The direct links of a repository path as [ID, reason] pairs. The order is `implements`,
+ * `covers`, `mentions`, then by ID. An ID keeps its first reason. Only canonical IDs count.
+ */
+export function fileEdges(entries, path) {
+    const ids = canon(entries);
+    const groups = [[], [], []];
+    const seen = new Set();
+    const push = (g, id, reason) => {
+        if (!ids.has(id) || seen.has(id))
+            return;
+        seen.add(id);
+        groups[g].push([id, reason]);
+    };
+    const tagged = entries
+        .filter((e) => e.file === path && (e.kind === "code" || e.kind === "test"))
+        .sort((a, b) => a.line - b.line);
+    for (const e of tagged) {
+        const g = e.kind === "code" ? 0 : 1;
+        const verb = e.kind === "code" ? "implements" : "covers";
+        for (const r of e.refs)
+            push(g, r, `${verb}, tag at ${e.file}:${e.line}`);
+    }
+    const mentions = entries.filter((e) => e.kind === "task" && e.canonical && (e.paths ?? []).includes(path));
+    for (const e of mentions)
+        push(2, e.id, "mentions, in task line");
+    return groups.flatMap((g) => g.sort((a, b) => cmpStr(a[0], b[0])));
+}

package/dist/graph/input.js

@@ -0,0 +1,37 @@
+// REQ-QRY-005 REQ-QRY-011 REQ-QRY-015 turn the inputs of bundle or context into IDs, changes, and paths (047/D2).
+import { canon } from "../index/canonical.js";
+import { changeInput, resolveFileInput } from "./path.js";
+/** An ID wins over a change, and a change wins over a path (045/D1, 046/D8). */
+export function resolveInputs(root, cwd, entries, inputs) {
+    const ids = canon(entries);
+    const wanted = [];
+    const paths = new Set();
+    const unknown = [];
+    const errors = [];
+    let taskId;
+    for (const i of inputs) {
+        if (ids.has(i)) {
+            wanted.push(i);
+            if (taskId === undefined && ids.get(i).kind === "task")
+                taskId = i;
+            continue;
+        }
+        const ch = changeInput(entries, i);
+        if (ch) {
+            wanted.push(ch);
+            continue;
+        }
+        const r = resolveFileInput(root, cwd, i);
+        if ("rel" in r) {
+            wanted.push(r.rel);
+            paths.add(r.rel);
+        }
+        else if (r.error.startsWith("unknown id "))
+            unknown.push(i);
+        else
+            errors.push(r.error);
+    }
+    if (unknown.length)
+        errors.unshift(`unknown id(s): ${unknown.join(", ")}`);
+    return { wanted, paths, errors, taskId };
+}

package/dist/graph/links.js

@@ -0,0 +1,96 @@
+import { cmpStr } from "../util/pystr.js";
+const CHANGE_DIR = /^(openspec\/changes\/(?:archive\/)?[^/]+)\//;
+const CAP_SPEC = /(?:^|\/)specs\/([^/]+)\/spec\.md$/;
+/** The change folder that holds a file, or undefined. */
+export const folderOf = (file) => CHANGE_DIR.exec(file)?.[1];
+/** The capability name of a `specs/<cap>/spec.md` path, or undefined. */
+export const capNameOf = (file) => CAP_SPEC.exec(file)?.[1];
+function push(m, k, v) {
+    const l = m.get(k);
+    if (!l)
+        m.set(k, [v]);
+    else if (!l.includes(v))
+        l.push(v);
+}
+const cache = new WeakMap();
+export function structure(entries) {
+    let s = cache.get(entries);
+    if (s)
+        return s;
+    s = { deltas: new Map(), caps: new Map(), reqsOfCap: new Map(), designs: new Map(), tasksOf: new Map(), main: new Map() };
+    const modified = new Set();
+    for (const e of entries) {
+        if (e.kind === "req" || e.kind === "scn") {
+            const dir = folderOf(e.file);
+            const cap = capNameOf(e.file);
+            if (dir && cap) {
+                push(s.deltas, dir, e.id);
+                push(s.caps, dir, cap);
+            }
+            if (e.kind === "req" && e.canonical && cap)
+                push(s.reqsOfCap, cap, e.id);
+            if (e.kind === "req" && e.canonical && e.status === "modified")
+                modified.add(e.id);
+        }
+        else if (e.kind === "task" && e.links) {
+            for (const l of e.links) {
+                if (!l.startsWith("design:"))
+                    continue;
+                const d = l.slice(7);
+                push(s.designs, e.id, d);
+                push(s.tasksOf, d, e.id);
+            }
+        }
+    }
+    for (const e of entries) {
+        if (e.kind === "req" && !e.canonical && e.status === "active" && e.change === "main" && modified.has(e.id) && !s.main.has(e.id)) {
+            s.main.set(e.id, e);
+        }
+    }
+    for (const l of [s.caps, s.reqsOfCap, s.tasksOf])
+        for (const v of l.values())
+            v.sort(cmpStr);
+    cache.set(entries, s);
+    return s;
+}
+/**
+ * The structural edges that leave one entry, as [ID, reason] pairs. A task reaches its deltas and a
+ * capability reaches its requirements only when each is the start of the walk (046/D5).
+ */
+export function structuralEdges(s, ex, x, isStart, has) {
+    const out = [];
+    const put = (id, reason) => {
+        if (has(id))
+            out.push([id, reason]);
+    };
+    if (ex.kind === "task") {
+        // like a capability, a task reaches its deltas only as the start, so depth 2 adds no sibling (046/D5)
+        const dir = folderOf(ex.file);
+        if (isStart)
+            for (const id of (dir && s.deltas.get(dir)) || [])
+                put(id, `delta in change of ${x}`);
+        for (const id of s.designs.get(x) ?? [])
+            put(id, `design named in ${x}`);
+    }
+    else if (ex.kind === "decision") {
+        for (const id of s.tasksOf.get(x) ?? [])
+            put(id, `task names ${x}`);
+    }
+    else if (ex.kind === "req") {
+        const cap = capNameOf(ex.file);
+        if (cap)
+            put(`cap/${cap}`, `capability of ${x}`);
+    }
+    else if (ex.kind === "cap" && isStart) {
+        for (const id of s.reqsOfCap.get(ex.title) ?? [])
+            put(id, `requirement in ${x}`);
+    }
+    else if (ex.kind === "change") {
+        const dir = folderOf(ex.file);
+        for (const id of (dir && s.deltas.get(dir)) || [])
+            put(id, `delta in ${x}`);
+        for (const c of (dir && s.caps.get(dir)) || [])
+            put(`cap/${c}`, `capability touched by ${x}`);
+    }
+    return out;
+}

package/dist/graph/path.js

@@ -0,0 +1,54 @@
+// REQ-QRY-005 REQ-QRY-008 REQ-QRY-011 turn the input of related or bundle into a change or a repository path.
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { changeKey, resolveChange } from "../index/scan.js";
+const ID_SHAPE = /^(?:(?:REQ|SCN)-[A-Z]{2,6}-\d{3}(?:-\d+)?|ADR-\d{3}|[^/\s]+\/(?:\d+\.\d+|D\d+)|(?:change|cap)\/[^/\s]+)$/;
+/**
+ * REQ-QRY-011 a change key or a folder name that is no ID resolves to `change/<key>`.
+ * The caller runs this after the ID check and before the path rule (046/D8).
+ */
+export function changeInput(entries, input) {
+    const folder = resolveChange(entries, input);
+    if (folder === undefined)
+        return undefined;
+    const id = `change/${changeKey(folder)}`;
+    return entries.some((e) => e.id === id) ? id : undefined;
+}
+/** An input that looks like an ID. When it is no file, the error is `unknown id`. */
+export const idShaped = (input) => ID_SHAPE.test(input);
+function real(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+/** REQ-QRY-008 the path against the root, then against the working directory. The result is a file inside the root. */
+export function resolveFileInput(root, cwd, input) {
+    const realRoot = real(root) ?? root;
+    const tries = isAbsolute(input) ? [input] : [resolve(root, input), resolve(cwd, input)];
+    let found = null;
+    for (const t of tries) {
+        const r = real(t);
+        if (r !== null) {
+            found = r;
+            break;
+        }
+    }
+    if (found === null)
+        return idShaped(input) ? { error: `unknown id ${input}` } : { error: `no such file: ${input}` };
+    const rel = relative(realRoot, found);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+        return { error: `outside the repository: ${input}` };
+    let isFile = false;
+    try {
+        isFile = statSync(found).isFile();
+    }
+    catch {
+        isFile = false;
+    }
+    if (!isFile)
+        return idShaped(input) ? { error: `unknown id ${input}` } : { error: `not a file: ${input}` };
+    return { rel: rel.split(sep).join("/") };
+}

package/dist/graph/query.js

@@ -9,6 +9,9 @@ export function query(entries, args, o = {}) {
     const kind = o.kind?.toLowerCase();
     const hits = [];
     for (const e of poolOf(entries, !!o.all)) {
+        // REQ-QRY-013 change and cap entries show only for an explicit --kind
+        if (!kind && (e.kind === "cap" || e.kind === "change"))
+            continue;
         if ((kind && e.kind !== kind) || (o.change && !matchesChange(e.change, o.change)))
             continue;
         // REQ-IDX-005 --change takes a key or a full folder name