spec-ctx 0.4.0 → 0.4.1

package/dist/cli/workflow.js

@@ -1,9 +1,12 @@
-// REQ-IDS-001 REQ-TASK-001 REQ-TASK-002 REQ-TASK-003 REQ-TASK-005 REQ-VER-002 REQ-HND-001 REQ-LOOP-002 write commands.
+// REQ-IDS-001 REQ-TASK-001 REQ-TASK-002 REQ-TASK-007 REQ-TASK-003 REQ-TASK-005 REQ-VER-002 REQ-HND-001 REQ-LOOP-002 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";
+import { runCommand } from "../runcmd.js";
+/** REQ-CLI-010 a command to print, with the run prefix of the config (043/D1). */
+const rc = (c, args) => runCommand(c.cfg.cli.run, args);
 const arg = (c, n, what) => {
     const v = c.p.positional[n];
     if (v === undefined)
@@ -62,7 +65,8 @@ export async function runWorkflow(c) {
                 }
                 return 1;
             }
-            const bundleCommand = `specctx bundle ${t.reqs.join(" ")} --budget ${c.cfg.bundle.budget}`;
+            // REQ-TASK-007 the command names the answer that task start prints
+            const bundleCommand = rc(c, `context ${t.id} --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 });
             }
@@ -82,10 +86,10 @@ export async function runWorkflow(c) {
             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);
+            // 047/D5 the entry that findTask found goes in, so an active task wins over an archived one with its number
+            const b = bundle(c.root, entries, [t.id], c.cfg.bundle.budget, c.cfg.bundle.depth, { task: t.entry });
             const { isoNow } = await import("../util/time.js");
             const { CURRENT_PATH } = await import("../handoff/handoff.js");
             mkdirSync(join(c.root, ".ctx"), { recursive: true });
@@ -94,7 +98,7 @@ export async function runWorkflow(c) {
             // REQ-TASK-002 the Verify command is frozen here, so task done can refuse a changed one (019/D3)
             writeFileSync(join(c.root, CURRENT_PATH), dumps({ bundle_chars: cpLen(b.text), started_at: isoNow(), task: t.id, verify: t.verify.command }) + "\n");
             // REQ-TASK-002 a task that cites no REQ gets one hint line, so the agent knows what to add
-            const hint = t.reqs.length ? null : `task ${t.id} cites no REQ. Run specctx query --change ${t.change} --kind req to list its requirements, then add [REQ-<CAP>-NNN] to the task line.`;
+            const hint = t.reqs.length ? null : `task ${t.id} cites no REQ. Run ${rc(c, `query --change ${t.change} --kind req`)} to list its requirements, then add [REQ-<CAP>-NNN] to the task line.`;
             if (c.json)
                 print(c, { bundle: b, hint, task: t.id });
             else
@@ -113,7 +117,7 @@ export async function runWorkflow(c) {
                     throw new UsageExit("--manual needs a note");
                 // REQ-TASK-003 a task with a Verify command gets no manual note (019/D1, ADR-004)
                 if (t.verify.command !== null)
-                    throw new UsageExit(`task ${t.id} has a Verify command. Run it with specctx task done ${t.id}.`);
+                    throw new UsageExit(`task ${t.id} has a Verify command. Run it with ${rc(c, `task done ${t.id}`)}.`);
                 if (t.done && hasEvidence(c.root, t))
                     throw new UsageExit(`task ${t.id} is done`);
                 const { writeEvidence } = await import("../tasks/evidence.js");
@@ -137,7 +141,7 @@ export async function runWorkflow(c) {
             if (!dry) {
                 const frozen = readCurrent(c.root);
                 if (frozen && frozen.task === t.id && typeof frozen.verify === "string" && frozen.verify !== t.verify.command) {
-                    throw new UsageExit(`task ${t.id}: the Verify command changed since task start. Run specctx task start ${t.id} again.`);
+                    throw new UsageExit(`task ${t.id}: the Verify command changed since task start. Run ${rc(c, `task start ${t.id}`)} again.`);
                 }
             }
             const { runVerify, tail } = await import("../verify/run.js");
@@ -170,7 +174,7 @@ export async function runWorkflow(c) {
                 const fail = writeFail(c.root, t.id, { command: t.verify.command, exit: r.timedOut ? null : r.exit }, outTail);
                 let question = openQuestionFor(c.root, t.id)?.n ?? null;
                 if (question === null && fail.file.attempt >= c.cfg.loop.max_attempts) {
-                    question = addQuestion(c.root, t.id, capQuestion(t.id, fail.file.attempt, outTail)).n;
+                    question = addQuestion(c.root, t.id, capQuestion(t.id, fail.file.attempt, outTail), "cap").n;
                 }
                 if (c.json)
                     print(c, { attempt: fail.file.attempt, command: t.verify.command, error: msg, exit: r.exit, fail: fail.rel, question, tail: outTail, task: t.id });
@@ -184,7 +188,7 @@ export async function runWorkflow(c) {
                     c.io.out(paint("fail", `Verify failed (exit ${r.exit}). The task stays open.\n`, c.io.tty));
                 // REQ-LOOP-002 the blocked line comes after the failure text, so the last line names the way out
                 if (!c.json && question !== null)
-                    c.io.out(blockedLine(question) + "\n");
+                    c.io.out(blockedLine(question, c.cfg.cli.run) + "\n");
                 return 1;
             }
             const { sha256 } = await import("../util/hash.js");
@@ -197,6 +201,13 @@ export async function runWorkflow(c) {
             }, "command", undefined, t.verify.cwd);
             setBox(c.root, t, true);
             clearCurrent(c.root, t.id);
+            // REQ-LOOP-014 a pass closes the attempt-cap question of the task. Plan, design, and archive questions stay (044/D3).
+            const { isCapQuestion } = await import("../loop/fails.js");
+            const { readQuestions, resolveQuestion } = await import("../handoff/questions.js");
+            for (const q of readQuestions(c.root)) {
+                if (isCapQuestion(q, t.id))
+                    resolveQuestion(c.root, q.n, "Verify passed. Resolved by task done.");
+            }
             if (c.json)
                 print(c, { evidence: rel, kind: "command", task: t.id });
             else
@@ -255,7 +266,10 @@ export async function runWorkflow(c) {
             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(" "));
+            const approve = c.p.flags.approve === true;
+            const reject = c.p.flags.reject === true;
+            const verdict = approve && reject ? "both" : approve ? "approved" : reject ? "rejected" : undefined;
+            const h = resolve(c.root, entries, Number(n), c.p.positional.slice(1).join(" "), verdict);
             if (c.json)
                 print(c, { open_questions: h.open_questions, resolved: h.resolved });
             else

package/dist/config.js

@@ -21,6 +21,7 @@ export function defaults() {
         // REQ-DIST-002 the gate lints nothing unless the project opts in (022/D1, ADR-006 item 9)
         gate: { markdown: [], openspec: DEFAULT_OPENSPEC, base: "origin/main" },
         loop: { max_attempts: 3, archive: "ask" },
+        cli: { run: "specctx" },
     };
 }
 export class ConfigError extends Error {
@@ -122,6 +123,13 @@ export function loadConfig(root) {
             throw new ConfigError(`${CONFIG_FILE}: loop.archive must be "ask" or "auto".`);
         cfg.loop.archive = v;
     }
+    // REQ-CLI-010 the run prefix of printed commands (043/D1)
+    const cli = sec("cli");
+    if ("run" in cli) {
+        if (typeof cli.run !== "string" || !cli.run.trim())
+            throw new ConfigError(`${CONFIG_FILE}: cli.run must be a string that is not empty.`);
+        cfg.cli.run = cli.run.trim();
+    }
     return cfg;
 }
 /** The file that `specctx init` writes. Each key has a comment above it. */

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;
@@ -49,50 +50,163 @@ export function reqBlocks(root, reqs) {
     const files = new Lines(root);
     return reqs.map((e) => blockText(e, files)).join("\n");
 }
-export function bundle(root, entries, wanted, budget, depth, all = false) {
+/** 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