@esneiderbravo/speclaw 0.3.5 → 0.3.8

package/dist/modules/lawbook/coverage.js

@@ -0,0 +1,479 @@
+import fs from "node:fs";
+import path from "node:path";
+import { openDb, indexExists } from "../compass/db.js";
+import { formatItemId, loadSpecItems, parseItemId, parseSpecItems, } from "./spec-items.js";
+export const DEFAULT_COVERAGE_CONFIG = {
+    defaultNeeds: ["impl", "utest"],
+    gateStatuses: ["approved"],
+    gateArchive: true,
+    sources: {
+        impl: ["src/**"],
+        utest: ["test/unit/**", "test/**/*.test.ts", "test/**/*.test.js"],
+        itest: ["test/integration/**"],
+    },
+    exclude: ["**/node_modules/**", "**/dist/**", "**/.speclaw/**"],
+};
+/**
+ * Load coverage config from lawbook/config.yaml when present; otherwise defaults.
+ * Parses only a small line-oriented subset (no YAML dependency).
+ */
+export function loadCoverageConfig(projectPath) {
+    const cfg = structuredClone(DEFAULT_COVERAGE_CONFIG);
+    const cfgPath = path.join(projectPath, "lawbook", "config.yaml");
+    if (!fs.existsSync(cfgPath))
+        return cfg;
+    const text = fs.readFileSync(cfgPath, "utf8");
+    const gate = /^\s*gateArchive\s*:\s*(true|false)\s*$/im.exec(text);
+    if (gate)
+        cfg.gateArchive = gate[1].toLowerCase() === "true";
+    const needs = /^\s*defaultNeeds\s*:\s*\[([^\]]*)\]\s*$/im.exec(text);
+    if (needs) {
+        cfg.defaultNeeds = needs[1]
+            .split(",")
+            .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+            .filter(Boolean);
+    }
+    const statuses = /^\s*gateStatuses\s*:\s*\[([^\]]*)\]\s*$/im.exec(text);
+    if (statuses) {
+        cfg.gateStatuses = statuses[1]
+            .split(",")
+            .map((s) => s
+            .trim()
+            .replace(/^["']|["']$/g, "")
+            .toLowerCase())
+            .filter(Boolean);
+    }
+    return cfg;
+}
+/** Glob match supporting `**`, `*`, and path separators. */
+export function matchGlob(relPath, pattern) {
+    const norm = relPath.split("\\").join("/");
+    // Expand globs before escaping regex metacharacters so `*` is not double-escaped.
+    let i = 0;
+    let re = "^";
+    const p = pattern.split("\\").join("/");
+    while (i < p.length) {
+        if (p.startsWith("**/", i) || (p.startsWith("**", i) && i + 2 === p.length)) {
+            re += ".*";
+            i += p.startsWith("**/", i) ? 3 : 2;
+            continue;
+        }
+        if (p[i] === "*") {
+            re += "[^/]*";
+            i++;
+            continue;
+        }
+        const ch = p[i];
+        if (/[.+^${}()|[\]\\]/.test(ch))
+            re += `\\${ch}`;
+        else
+            re += ch;
+        i++;
+    }
+    re += "$";
+    return new RegExp(re).test(norm);
+}
+/** Infer artifact type from path using configured source globs. */
+export function inferArtifactType(relPath, cfg) {
+    const norm = relPath.split("\\").join("/");
+    if (cfg.exclude.some((g) => matchGlob(norm, g)))
+        return null;
+    for (const type of ["itest", "utest", "impl"]) {
+        const globs = cfg.sources[type] ?? [];
+        if (globs.some((g) => matchGlob(norm, g)))
+            return type;
+    }
+    return null;
+}
+function readIndexLinks(projectPath) {
+    if (!indexExists(projectPath))
+        return [];
+    const db = openDb(projectPath);
+    try {
+        const rows = db
+            .prepare(`SELECT artifact_type, name, revision, kind, file_path, line, node_id, source_type, origin
+         FROM coverage_links`)
+            .all();
+        return rows.map((r) => ({
+            artifactType: r.artifact_type,
+            name: r.name,
+            revision: r.revision,
+            kind: r.kind,
+            filePath: r.file_path,
+            line: r.line,
+            nodeId: r.node_id,
+            sourceType: r.source_type,
+            origin: r.origin,
+        }));
+    }
+    finally {
+        db.close();
+    }
+}
+function inlineLinksAsRaw(projectPath, items, cfg) {
+    const out = [];
+    for (const item of items) {
+        if (!item.id)
+            continue;
+        for (const inl of item.inlineLinks) {
+            const abs = path.join(projectPath, inl.targetPath);
+            const exists = fs.existsSync(abs);
+            const inferred = inferArtifactType(inl.targetPath, cfg) ?? (inl.kind === "test" ? "utest" : "impl");
+            out.push({
+                artifactType: item.id.artifactType,
+                name: item.id.name,
+                revision: item.id.revision,
+                kind: "covers",
+                filePath: inl.targetPath,
+                line: inl.line,
+                nodeId: null,
+                sourceType: inferred,
+                origin: "inline-test-link",
+                missingFile: !exists,
+            });
+        }
+    }
+    return out;
+}
+function classifyLink(link, item, idCounts, cfg) {
+    const base = {
+        artifactType: link.artifactType,
+        name: link.name,
+        revision: link.revision,
+        kind: link.kind,
+        filePath: link.filePath,
+        line: link.line,
+        nodeId: link.nodeId,
+        sourceType: link.sourceType,
+        origin: link.origin,
+        status: "Covers",
+    };
+    if (link.missingFile) {
+        return { ...base, status: "Orphaned", reason: "missing-file" };
+    }
+    if (cfg.exclude.some((g) => matchGlob(link.filePath, g))) {
+        return { ...base, status: "Orphaned", reason: "excluded-path" };
+    }
+    if (!item || !item.id) {
+        return { ...base, status: "Orphaned", reason: "unknown-item" };
+    }
+    if ((idCounts.get(item.idText) ?? 0) > 1) {
+        return { ...base, status: "Ambiguous", reason: "duplicate-id" };
+    }
+    if (item.status === "rejected") {
+        return { ...base, status: "Unwanted", reason: "item-rejected" };
+    }
+    if (link.revision < item.id.revision) {
+        return { ...base, status: "Outdated", reason: "revision-behind" };
+    }
+    if (link.revision > item.id.revision) {
+        return { ...base, status: "Predated", reason: "revision-ahead" };
+    }
+    const inferred = inferArtifactType(link.filePath, cfg);
+    if (inferred)
+        base.sourceType = inferred;
+    return base;
+}
+/**
+ * Build a full coverage report for a project (canonical specs by default).
+ *
+ * @param projectPath - Absolute project root.
+ * @param opts.change - Limit items to a change's delta specs (archive gate).
+ * @param opts.cfg - Optional preloaded config.
+ * @param opts.now - Optional fixed timestamp for deterministic JSON.
+ */
+export function buildCoverageReport(projectPath, opts = {}) {
+    const cfg = opts.cfg ?? loadCoverageConfig(projectPath);
+    const items = loadSpecItems(projectPath, { change: opts.change });
+    const identified = items.filter((i) => i.id !== null);
+    const idCounts = new Map();
+    for (const it of identified) {
+        idCounts.set(it.idText, (idCounts.get(it.idText) ?? 0) + 1);
+    }
+    const rawLinks = [
+        ...readIndexLinks(projectPath),
+        ...inlineLinksAsRaw(projectPath, identified, cfg),
+    ];
+    const results = [];
+    const matchedKeys = new Set();
+    for (const item of identified) {
+        const idText = item.idText;
+        const needs = item.needs.length > 0 ? item.needs : [...cfg.defaultNeeds];
+        const itemLinks = rawLinks
+            .filter((l) => l.artifactType === item.id.artifactType && l.name === item.id.name)
+            .map((l) => {
+            matchedKeys.add(`${l.filePath}:${l.line}:${l.revision}:${l.kind}`);
+            return classifyLink(l, item, idCounts, cfg);
+        });
+        const covering = itemLinks.filter((l) => l.status === "Covers");
+        const coveredTypes = [...new Set(covering.map((l) => l.sourceType))];
+        const uncoveredTypes = needs.filter((n) => !coveredTypes.includes(n));
+        const shallow = uncoveredTypes.length === 0 && (idCounts.get(idText) ?? 0) === 1;
+        const directDefects = [];
+        if ((idCounts.get(idText) ?? 0) > 1) {
+            directDefects.push(`duplicate id ${idText} at ${item.specPath}:${item.line}`);
+        }
+        for (const t of uncoveredTypes) {
+            directDefects.push(`missing ${t} for ${idText} at ${item.specPath}:${item.line}`);
+        }
+        for (const l of itemLinks) {
+            if (l.status === "Outdated" ||
+                l.status === "Orphaned" ||
+                l.status === "Ambiguous" ||
+                l.status === "Unwanted") {
+                directDefects.push(`${l.status} link ${l.filePath}:${l.line} → ${idText}` +
+                    (l.reason ? ` (${l.reason})` : ""));
+            }
+        }
+        results.push({
+            id: idText,
+            title: item.title,
+            status: item.status,
+            needs,
+            tags: item.tags,
+            depends: item.depends,
+            covers: item.covers,
+            specPath: item.specPath,
+            line: item.line,
+            coveredTypes,
+            uncoveredTypes,
+            shallow,
+            deep: shallow,
+            links: itemLinks,
+            directDefects,
+            transitiveDefects: [],
+        });
+    }
+    const byId = new Map(results.map((r) => [r.id, r]));
+    const visiting = new Set();
+    const visited = new Set();
+    const isDeep = (id, stack) => {
+        const r = byId.get(id);
+        if (!r)
+            return false;
+        if (!r.shallow) {
+            r.deep = false;
+            return false;
+        }
+        if (visited.has(id))
+            return r.deep;
+        if (visiting.has(id)) {
+            r.transitiveDefects.push(`cycle involving ${[...stack, id].join(" → ")}`);
+            r.deep = false;
+            return false;
+        }
+        visiting.add(id);
+        let deep = true;
+        for (const dep of [...r.depends, ...r.covers]) {
+            if (!byId.has(dep))
+                continue;
+            if (!isDeep(dep, [...stack, id]))
+                deep = false;
+        }
+        visiting.delete(id);
+        visited.add(id);
+        r.deep = deep && r.shallow;
+        return r.deep;
+    };
+    for (const r of results)
+        isDeep(r.id, []);
+    const orphans = [];
+    for (const l of rawLinks) {
+        const key = `${l.filePath}:${l.line}:${l.revision}:${l.kind}`;
+        if (matchedKeys.has(key))
+            continue;
+        orphans.push(classifyLink(l, undefined, idCounts, cfg));
+    }
+    const gated = results.filter((r) => cfg.gateStatuses.includes(r.status));
+    const directDefects = gated.reduce((n, r) => n + r.directDefects.length, 0);
+    const transitiveDefects = results.reduce((n, r) => n + r.transitiveDefects.length, 0);
+    return {
+        schemaVersion: 1,
+        generatedAt: opts.now ?? new Date().toISOString(),
+        summary: {
+            items: items.length,
+            identified: identified.length,
+            shallowCovered: results.filter((r) => r.shallow).length,
+            deepCovered: results.filter((r) => r.deep).length,
+            directDefects,
+            transitiveDefects,
+        },
+        items: results,
+        orphans,
+    };
+}
+/** Exit code for a report (0 clean / no ids, 1 gated direct defects). */
+export function coverageExitCode(report, cfg) {
+    if (report.summary.identified === 0)
+        return 0;
+    const gated = report.items.filter((i) => cfg.gateStatuses.includes(i.status));
+    const defects = gated.reduce((n, i) => n + i.directDefects.length, 0);
+    return defects > 0 ? 1 : 0;
+}
+/** TAP-compatible summary (non-TTY / --tap). */
+export function renderCoverageTap(report) {
+    if (report.summary.identified === 0) {
+        return [
+            "1..0",
+            "# no identified requirements — run: speclaw coverage --adopt",
+            "ok - 0 total",
+        ].join("\n");
+    }
+    const lines = [`1..${report.items.length}`];
+    let n = 0;
+    for (const item of report.items) {
+        n++;
+        const defects = [...item.directDefects, ...item.transitiveDefects];
+        if (defects.length === 0 && item.shallow) {
+            lines.push(`ok ${n} - ${item.id} (${item.coveredTypes.join(", ") || "covered"})`);
+        }
+        else {
+            lines.push(`not ok ${n} - ${item.id}`);
+            for (const d of defects)
+                lines.push(`  # ${d}`);
+            for (const t of item.uncoveredTypes)
+                lines.push(`  # uncovered: ${t}`);
+        }
+    }
+    const { directDefects, transitiveDefects } = report.summary;
+    if (directDefects === 0 && transitiveDefects === 0) {
+        lines.push(`ok - ${report.items.length} total`);
+    }
+    else {
+        lines.push(`not ok - ${report.items.length} total, ${directDefects} direct, ${transitiveDefects} transitive defects`);
+    }
+    return lines.join("\n");
+}
+/** Human table for TTY. */
+export function renderCoverageTable(report) {
+    if (report.summary.identified === 0) {
+        return "No identified requirements. Run `speclaw coverage --adopt` to propose ids.";
+    }
+    const rows = report.items.map((i) => {
+        const mark = i.shallow ? (i.deep ? "ok" : "shallow") : "MISS";
+        return `${mark.padEnd(8)} ${i.id.padEnd(36)} ${(i.coveredTypes.join(",") || "-").padEnd(16)} ${i.specPath}:${i.line}`;
+    });
+    const s = report.summary;
+    rows.push("");
+    rows.push(`identified ${s.identified} · shallow ${s.shallowCovered} · deep ${s.deepCovered} · direct defects ${s.directDefects} · transitive ${s.transitiveDefects}`);
+    return rows.join("\n");
+}
+/** Defect-first agent text, capped (~600 tokens ≈ 2400 chars). */
+export function renderCoverageAgent(report, onlyDefects = true) {
+    if (report.summary.identified === 0) {
+        return "No identified requirements. Next: run `speclaw coverage --adopt` then add `// Covers: req~…~1` above impl/tests.";
+    }
+    const items = onlyDefects
+        ? report.items.filter((i) => i.directDefects.length > 0 || !i.shallow)
+        : report.items;
+    if (items.length === 0) {
+        return `Coverage clean: ${report.summary.shallowCovered}/${report.summary.identified} shallow, ${report.summary.deepCovered} deep. Next: archive when tasks and reports are done.`;
+    }
+    const lines = [
+        `Coverage defects: ${report.summary.directDefects} direct, ${report.summary.transitiveDefects} transitive.`,
+    ];
+    for (const i of items.slice(0, 12)) {
+        lines.push(`- ${i.id} @ ${i.specPath}:${i.line}`);
+        for (const d of i.directDefects.slice(0, 3))
+            lines.push(`    ${d}`);
+        if (i.uncoveredTypes.length) {
+            lines.push(`    add Covers for: ${i.uncoveredTypes.join(", ")}`);
+        }
+    }
+    if (items.length > 12)
+        lines.push(`…and ${items.length - 12} more`);
+    lines.push("Next: add `// Covers: <id>` above the impl/test, reindex, re-run coverage.");
+    let text = lines.join("\n");
+    if (text.length > 2400)
+        text = text.slice(0, 2397) + "...";
+    return text;
+}
+/**
+ * Archive-gate reasons for direct defects on gated statuses.
+ * Opt-in: contributes nothing when the change's delta specs have zero ids.
+ */
+export function coverageArchiveBlockers(projectPath, change) {
+    const cfg = loadCoverageConfig(projectPath);
+    if (!cfg.gateArchive)
+        return [];
+    const report = buildCoverageReport(projectPath, { change, cfg });
+    if (report.summary.identified === 0)
+        return [];
+    const blockers = [];
+    for (const item of report.items) {
+        if (!cfg.gateStatuses.includes(item.status))
+            continue;
+        for (const d of item.directDefects)
+            blockers.push(`coverage: ${d}`);
+    }
+    return blockers;
+}
+/** Propose `req~slug~1` ids for requirements that lack them. */
+export function proposeAdopt(projectPath) {
+    const items = loadSpecItems(projectPath);
+    const used = new Set(items.filter((i) => i.idText).map((i) => i.idText));
+    const proposals = [];
+    for (const item of items) {
+        if (item.id)
+            continue;
+        const base = slugify(item.title) || "item";
+        let name = base;
+        let n = 2;
+        let id = `req~${name}~1`;
+        let collision = false;
+        while (used.has(id)) {
+            collision = true;
+            name = `${base}-${n++}`;
+            id = `req~${name}~1`;
+        }
+        used.add(id);
+        proposals.push({
+            specPath: item.specPath,
+            line: item.line,
+            title: item.title,
+            proposedId: id,
+            collision,
+        });
+    }
+    return proposals;
+}
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+}
+/**
+ * Apply adopt proposals. Writes only when `write` is true; backs up to
+ * `<file>.bak` before mutating.
+ */
+export function applyAdopt(projectPath, proposals, opts = {}) {
+    if (!opts.write)
+        return { written: [], dryRun: true };
+    const byFile = new Map();
+    for (const p of proposals) {
+        const list = byFile.get(p.specPath) ?? [];
+        list.push(p);
+        byFile.set(p.specPath, list);
+    }
+    const written = [];
+    for (const [rel, props] of byFile) {
+        const abs = path.join(projectPath, rel);
+        const original = fs.readFileSync(abs, "utf8");
+        const lines = original.split(/\r?\n/);
+        const ordered = [...props].sort((a, b) => b.line - a.line);
+        for (const p of ordered) {
+            const idx = p.line - 1;
+            const line = lines[idx];
+            if (!line || line.includes("`req~"))
+                continue;
+            lines[idx] = line.replace(/^(###\s+Requirement:\s*)(.+)$/, `$1${p.title} \`${p.proposedId}\``);
+        }
+        fs.copyFileSync(abs, abs + ".bak");
+        fs.writeFileSync(abs, lines.join("\n"));
+        written.push(rel);
+    }
+    return { written, dryRun: false };
+}
+export { parseSpecItems, parseItemId, formatItemId };

package/dist/modules/lawbook/engine.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { coverageArchiveBlockers } from "./coverage.js";
 // speclaw's own spec-driven workflow engine. Inspired by OpenSpec's model
 // (proposals, delta specs, changes, archive) but implemented from scratch and
 // deliberately simpler: a change's specs/ holds the full intended spec for each
@@ -310,6 +311,8 @@ export function specArchivePreconditions(projectPath, change) {
             blockers.push(`spec not synced: lawbook/specs/${rel} differs from the delta (run sync first)`);
         }
     }
+    // 4. Opt-in coverage gate: only when the change's delta specs declare ids.
+    blockers.push(...coverageArchiveBlockers(projectPath, change));
     return blockers;
 }
 /**

package/dist/modules/lawbook/register.js

@@ -5,6 +5,7 @@ import { shouldExpose } from "../../shared/exposure.js";
 import { assetsDir } from "../../shared/paths.js";
 import { copyRendered } from "../../shared/install.js";
 import { specInit, specValidate, specSync, specArchive, specList } from "./engine.js";
+import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
 const ASSETS = assetsDir(import.meta.url);
 /**
  * Install the spec module's workflow interface into a project's ai-specs/:
@@ -34,4 +35,16 @@ export function registerSpec(server, opts = {}) {
         change: z.string(),
         date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
     }, async ({ projectPath, change, date }) => text(specArchive(projectPath, change, date)));
+    add("lawbook_coverage", "Report which requirements lack impl/test coverage before declaring work done.", {
+        projectPath: z.string(),
+        change: z.string().optional(),
+        onlyDefects: z.boolean().optional(),
+        json: z.boolean().optional(),
+    }, async ({ projectPath, change, onlyDefects, json }) => {
+        const cfg = loadCoverageConfig(projectPath);
+        const report = buildCoverageReport(projectPath, { change, cfg });
+        if (json)
+            return text(JSON.stringify(report));
+        return text(renderCoverageAgent(report, onlyDefects !== false));
+    });
 }

package/dist/modules/lawbook/spec-items.js

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import path from "node:path";
+const RE_REQUIREMENT = /^###\s+Requirement:\s*(.+?)\s*$/;
+const RE_ID = /`([a-z]{2,6})~([A-Za-z0-9._-]+)~(\d+)`/;
+const RE_KEYWORD = /^(Status|Needs|Tags|Depends|Covers)\s*:\s*(.+?)\s*$/i;
+const RE_INLINE = /\[@(test|impl)\s+([^\]]+)\]/gi;
+const RE_ID_LOOSE = /\b([a-z]{2,6})~([A-Za-z0-9._-]+)~(\d+)\b/g;
+/** Format a SpecItemId as `type~name~rev`. */
+export function formatItemId(id) {
+    return `${id.artifactType}~${id.name}~${id.revision}`;
+}
+/** Parse a single `type~name~rev` token, or null if malformed. */
+export function parseItemId(text) {
+    const m = /^([a-z]{2,6})~([A-Za-z0-9._-]+)~(\d+)$/.exec(text.trim());
+    if (!m)
+        return null;
+    return { artifactType: m[1], name: m[2], revision: Number(m[3]) };
+}
+function splitList(value) {
+    return value
+        .split(/[, ]+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function parseIdList(value) {
+    const out = [];
+    for (const m of value.matchAll(RE_ID_LOOSE)) {
+        out.push(`${m[1]}~${m[2]}~${m[3]}`);
+    }
+    return out;
+}
+/**
+ * Parse one markdown spec file into requirement items. Headings without an
+ * inline-code identifier are returned with `id: null` (ignored by coverage).
+ *
+ * @param specPath - Project-relative path of the spec (for reporting).
+ * @param content - Full markdown source.
+ */
+export function parseSpecItems(specPath, content) {
+    const lines = content.split(/\r?\n/);
+    const items = [];
+    let current = null;
+    const flush = () => {
+        if (current)
+            items.push(current);
+        current = null;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const req = RE_REQUIREMENT.exec(line);
+        if (req) {
+            flush();
+            const rest = req[1];
+            const idMatch = RE_ID.exec(rest);
+            let title = rest;
+            let id = null;
+            let idText = null;
+            if (idMatch) {
+                id = {
+                    artifactType: idMatch[1],
+                    name: idMatch[2],
+                    revision: Number(idMatch[3]),
+                };
+                idText = formatItemId(id);
+                title = rest.replace(idMatch[0], "").replace(/\s+/g, " ").trim();
+                // Common forms: "Title `id`" or "`id` Title"
+                title = title.replace(/^[\s—–-]+|[\s—–-]+$/g, "").trim();
+            }
+            current = {
+                id,
+                idText,
+                title,
+                status: "approved",
+                needs: [],
+                tags: [],
+                depends: [],
+                covers: [],
+                inlineLinks: [],
+                specPath,
+                line: i + 1,
+            };
+            continue;
+        }
+        if (!current)
+            continue;
+        // Next ### Requirement: or # heading ends the item body for keyword purposes,
+        // but #### Scenario lines may still carry inline links.
+        if (/^###?\s+/.test(line) && !/^####\s+/.test(line)) {
+            flush();
+            // Re-process this line as a potential new requirement on next iteration
+            // by rewinding — simpler: only #### and body lines belong to current.
+            i--;
+            continue;
+        }
+        const kw = RE_KEYWORD.exec(line);
+        if (kw) {
+            const key = kw[1].toLowerCase();
+            const value = kw[2];
+            if (key === "status")
+                current.status = value.trim().toLowerCase();
+            else if (key === "needs")
+                current.needs = splitList(value).map((s) => s.toLowerCase());
+            else if (key === "tags")
+                current.tags = splitList(value);
+            else if (key === "depends")
+                current.depends = parseIdList(value);
+            else if (key === "covers")
+                current.covers = parseIdList(value);
+            continue;
+        }
+        for (const m of line.matchAll(RE_INLINE)) {
+            current.inlineLinks.push({
+                kind: m[1].toLowerCase(),
+                targetPath: m[2].trim(),
+                line: i + 1,
+            });
+        }
+    }
+    flush();
+    return items;
+}
+/**
+ * Walk `lawbook/specs/**\/spec.md` (and optionally a change's delta specs) and
+ * parse every requirement item.
+ *
+ * @param projectPath - Absolute project root.
+ * @param opts.change - When set, parse only that change's delta specs.
+ */
+export function loadSpecItems(projectPath, opts = {}) {
+    const roots = [];
+    if (opts.change) {
+        roots.push(path.join(projectPath, "lawbook", "changes", opts.change, "specs"));
+    }
+    else {
+        roots.push(path.join(projectPath, "lawbook", "specs"));
+    }
+    const items = [];
+    for (const root of roots) {
+        if (!fs.existsSync(root))
+            continue;
+        for (const file of walkSpecFiles(root)) {
+            const rel = path.relative(projectPath, file).split(path.sep).join("/");
+            const content = fs.readFileSync(file, "utf8");
+            items.push(...parseSpecItems(rel, content));
+        }
+    }
+    return items;
+}
+function* walkSpecFiles(dir) {
+    const stack = [dir];
+    while (stack.length) {
+        const cur = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = path.join(cur, e.name);
+            if (e.isDirectory())
+                stack.push(full);
+            else if (e.isFile() && e.name === "spec.md")
+                yield full;
+        }
+    }
+}

package/dist/shared/exposure.js

@@ -5,7 +5,7 @@ import { readManifest } from "./manifest.js";
 /**
  * Tools omitted when the exposure profile is `minimal`. Kept tools are the
  * discovery + law loop: compass_explore/search/recall, lawbook_validate/sync,
- * law_verify, speclaw_check.
+ * lawbook_coverage, law_verify, speclaw_check.
  */
 export const MINIMAL_OMIT = new Set([
     "compass_index",