@esneiderbravo/speclaw 0.3.11 → 0.3.13

package/dist/modules/lawbook/levels.js

@@ -0,0 +1,468 @@
+import fs from "node:fs";
+import path from "node:path";
+import { indexExists } from "../compass/db.js";
+import { explore } from "../compass/query.js";
+import { impact } from "../compass/query.js";
+import { affectedTests } from "../compass/affected.js";
+import { hotspots } from "../compass/hotspots.js";
+import { loadAffectedConfig, matchGlob, matchesAny, inferModule, } from "../compass/affected-config.js";
+/** Default thresholds from the adaptive-ceremony roadmap. */
+export const DEFAULT_THRESHOLDS = {
+    filesTouched: [0, 1, 3, 5],
+    modulesTouched: [0, 2, 4, 6],
+    affectedTests: [0, 1, 2, 4],
+    blastRadiusNodes: [0, 1, 3, 5],
+    publicApi: 4,
+    globalFile: 5,
+    hotspot: 3,
+    hotspotFloor: 0.7,
+    cuts: [3, 8, 15],
+    globalGlobs: [
+        "package.json",
+        "package-lock.json",
+        "tsconfig*.json",
+        ".github/workflows/**",
+        "src/modules/compass/db.ts",
+        "lawbook/config.yaml",
+    ],
+    docGlobs: ["**/*.md", "docs/**", "assets/**"],
+    moduleRoots: ["src"],
+};
+const BUCKETS = {
+    filesTouched: [1, 3, 10, Infinity],
+    modulesTouched: [1, 2, 4, Infinity],
+    affectedTests: [0, 3, 15, Infinity],
+    blastRadiusNodes: [2, 10, 50, Infinity],
+};
+export function artifactNeeds(level, changeType = "feature") {
+    if (changeType === "bug") {
+        switch (level) {
+            case 0:
+                return {
+                    record: false,
+                    proposal: false,
+                    design: false,
+                    tasksFile: false,
+                    deltaSpecs: false,
+                    reports: true,
+                    designOptionalWithJustification: false,
+                    bugfix: true,
+                };
+            case 1:
+                return {
+                    record: false,
+                    proposal: false,
+                    design: false,
+                    tasksFile: true,
+                    deltaSpecs: false,
+                    reports: true,
+                    designOptionalWithJustification: false,
+                    bugfix: true,
+                };
+            case 2:
+            case 3:
+                return {
+                    record: false,
+                    proposal: false,
+                    design: true,
+                    tasksFile: true,
+                    deltaSpecs: false,
+                    reports: true,
+                    designOptionalWithJustification: false,
+                    bugfix: true,
+                };
+        }
+    }
+    switch (level) {
+        case 0:
+            return {
+                record: true,
+                proposal: false,
+                design: false,
+                tasksFile: false,
+                deltaSpecs: false,
+                reports: true,
+                designOptionalWithJustification: false,
+                bugfix: false,
+            };
+        case 1:
+            return {
+                record: true,
+                proposal: false,
+                design: false,
+                tasksFile: true,
+                deltaSpecs: true,
+                reports: true,
+                designOptionalWithJustification: false,
+                bugfix: false,
+            };
+        case 2:
+            return {
+                record: false,
+                proposal: true,
+                design: false,
+                tasksFile: true,
+                deltaSpecs: true,
+                reports: true,
+                designOptionalWithJustification: true,
+                bugfix: false,
+            };
+        case 3:
+            return {
+                record: false,
+                proposal: true,
+                design: true,
+                tasksFile: true,
+                deltaSpecs: true,
+                reports: true,
+                designOptionalWithJustification: false,
+                bugfix: false,
+            };
+    }
+}
+/** Read change type from change.json; missing ⇒ feature. */
+export function readChangeType(projectPath, change) {
+    const rec = readCeremonyRecord(projectPath, change);
+    return rec?.changeType === "bug" ? "bug" : "feature";
+}
+function bucketPoints(value, edges, points) {
+    const i = edges.findIndex((max) => value <= max);
+    return points[i < 0 ? 3 : i];
+}
+/** Pure scoring; `onlyDocs` short-circuits to 0. */
+export function scoreSignals(s, t = DEFAULT_THRESHOLDS) {
+    if (s.onlyDocs)
+        return 0;
+    let score = 0;
+    score += bucketPoints(s.filesTouched, BUCKETS.filesTouched, t.filesTouched);
+    score += bucketPoints(s.modulesTouched, BUCKETS.modulesTouched, t.modulesTouched);
+    score += bucketPoints(s.affectedTests, BUCKETS.affectedTests, t.affectedTests);
+    score += bucketPoints(s.blastRadiusNodes, BUCKETS.blastRadiusNodes, t.blastRadiusNodes);
+    if (s.touchesPublicApi)
+        score += t.publicApi;
+    if (s.touchesGlobalFile)
+        score += t.globalFile;
+    if (s.maxHotspotScore >= t.hotspotFloor)
+        score += t.hotspot;
+    return score;
+}
+export function levelFromScore(score, cuts = DEFAULT_THRESHOLDS.cuts) {
+    if (score < cuts[0])
+        return 0;
+    if (score < cuts[1])
+        return 1;
+    if (score < cuts[2])
+        return 2;
+    return 3;
+}
+export function explain(s, t, score, level) {
+    const parts = [
+        `${s.filesTouched} file(s)`,
+        `${s.modulesTouched} module(s)`,
+        `${s.affectedTests} affected test(s)`,
+        `${s.blastRadiusNodes} blast node(s)`,
+        s.touchesPublicApi ? "public API" : "no public API",
+        s.touchesGlobalFile ? "global file" : "no global file",
+        `hotspot=${s.maxHotspotScore.toFixed(2)}`,
+    ];
+    if (s.onlyDocs)
+        parts.push("docs-only");
+    if (s.degraded.length)
+        parts.push(`degraded:[${s.degraded.join(",")}]`);
+    const lvl = level === null ? "none" : String(level);
+    return `${parts.join(", ")} → score ${score} → level ${lvl} (cuts ${t.cuts.join("/")})`;
+}
+export function proposeLevel(s, t = DEFAULT_THRESHOLDS) {
+    if (s.degraded.includes("no-index") && s.filesTouched === 0 && s.blastRadiusNodes === 0) {
+        return {
+            level: null,
+            score: 0,
+            signals: s,
+            rationale: explain(s, t, 0, null),
+            degraded: s.degraded,
+        };
+    }
+    if (s.filesTouched === 0 &&
+        s.blastRadiusNodes === 0 &&
+        s.degraded.includes("unresolved-symbols")) {
+        return {
+            level: null,
+            score: 0,
+            signals: s,
+            rationale: explain(s, t, 0, null),
+            degraded: s.degraded,
+        };
+    }
+    const score = scoreSignals(s, t);
+    const level = levelFromScore(score, t.cuts);
+    return {
+        level,
+        score,
+        signals: s,
+        rationale: explain(s, t, score, level),
+        degraded: s.degraded,
+    };
+}
+function isSpecPath(rel) {
+    const n = rel.split("\\").join("/");
+    return n.startsWith("lawbook/specs/") || n.includes("/lawbook/specs/");
+}
+/** Resolve modules for paths using configured roots / inferModule. */
+export function countModules(paths) {
+    const mods = new Set(paths.map((p) => inferModule(p.split("\\").join("/")) || p.split("/")[0] || p));
+    return mods.size;
+}
+/**
+ * Build signals from an explicit target list. When the Compass index is missing,
+ * marks `no-index` and does not invent a small blast radius.
+ */
+export function gatherSignals(projectPath, targets, t = DEFAULT_THRESHOLDS) {
+    const degraded = [];
+    const paths = new Set(targets.paths.map((p) => p.replace(/^\.\//, "").split("\\").join("/")));
+    if (!indexExists(projectPath)) {
+        degraded.push("no-index");
+    }
+    else {
+        for (const sym of targets.symbols) {
+            const ex = explore(projectPath, sym);
+            if (ex.found && ex.symbol?.file)
+                paths.add(ex.symbol.file.split("\\").join("/"));
+            else
+                degraded.push("unresolved-symbols");
+        }
+    }
+    const pathList = [...paths];
+    const onlyDocs = pathList.length > 0 &&
+        pathList.every((p) => matchesAny(p, t.docGlobs)) &&
+        !pathList.some(isSpecPath);
+    let touchesGlobalFile = pathList.some((p) => matchesAny(p, t.globalGlobs));
+    try {
+        const cfg = loadAffectedConfig(projectPath);
+        if (pathList.some((p) => cfg.globalFiles.some((g) => matchGlob(p, g)))) {
+            touchesGlobalFile = true;
+        }
+    }
+    catch {
+        /* soft */
+    }
+    let blastRadiusNodes = 0;
+    let affected = 0;
+    let touchesPublicApi = false;
+    let maxHotspotScore = 0;
+    if (indexExists(projectPath) && pathList.length > 0) {
+        try {
+            const imp = impact(projectPath, { files: pathList, format: "grouped", maxDepth: 4 });
+            blastRadiusNodes = imp.totals.nodes;
+            if (imp.global)
+                touchesGlobalFile = true;
+        }
+        catch {
+            /* soft */
+        }
+        try {
+            const at = affectedTests(projectPath, { files: pathList });
+            affected = at.mode === "all" ? Math.max(at.tests.length, 50) : at.tests.length;
+        }
+        catch {
+            /* soft */
+        }
+        try {
+            const pkgPath = path.join(projectPath, "package.json");
+            if (fs.existsSync(pkgPath)) {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+                const entries = new Set();
+                if (typeof pkg.main === "string")
+                    entries.add(pkg.main.replace(/^\.\//, ""));
+                if (typeof pkg.bin === "string")
+                    entries.add(pkg.bin.replace(/^\.\//, ""));
+                else if (pkg.bin && typeof pkg.bin === "object") {
+                    for (const v of Object.values(pkg.bin))
+                        entries.add(String(v).replace(/^\.\//, ""));
+                }
+                for (const e of entries) {
+                    if (pathList.some((p) => p === e || e.endsWith(p) || p.endsWith(e))) {
+                        touchesPublicApi = true;
+                    }
+                }
+                if (pathList.some((p) => p === "src/cli/index.ts" || p === "src/server.ts")) {
+                    touchesPublicApi = true;
+                }
+            }
+        }
+        catch {
+            /* soft */
+        }
+        try {
+            const hs = hotspots(projectPath, { days: 90, sortBy: "combined", limit: 200 });
+            const byFile = new Map(hs.hotspots.map((h) => [h.file, h.combinedScore]));
+            let maxCombined = 0;
+            for (const h of hs.hotspots)
+                maxCombined = Math.max(maxCombined, h.combinedScore);
+            if (maxCombined <= 0)
+                degraded.push("no-hotspots");
+            else {
+                for (const p of pathList) {
+                    const c = byFile.get(p) ?? 0;
+                    maxHotspotScore = Math.max(maxHotspotScore, c / maxCombined);
+                }
+            }
+        }
+        catch {
+            degraded.push("no-hotspots");
+        }
+    }
+    return {
+        filesTouched: pathList.length,
+        modulesTouched: pathList.length ? countModules(pathList) : 0,
+        blastRadiusNodes,
+        affectedTests: affected,
+        touchesPublicApi,
+        maxHotspotScore,
+        touchesGlobalFile,
+        onlyDocs,
+        degraded: [...new Set(degraded)],
+    };
+}
+/** Load ceremony thresholds from lawbook/config.yaml (line-oriented). */
+export function loadCeremonyConfig(projectPath) {
+    const thresholds = structuredClone(DEFAULT_THRESHOLDS);
+    const cfgPath = path.join(projectPath, "lawbook", "config.yaml");
+    if (!fs.existsSync(cfgPath))
+        return { thresholds, invalidCuts: false };
+    const text = fs.readFileSync(cfgPath, "utf8");
+    const cuts = /^\s*cuts\s*:\s*\[([^\]]*)\]\s*$/im.exec(text);
+    let invalidCuts = false;
+    if (cuts) {
+        const nums = cuts[1]
+            .split(",")
+            .map((s) => Number(s.trim()))
+            .filter((n) => Number.isFinite(n));
+        if (nums.length === 3 && nums[0] < nums[1] && nums[1] < nums[2]) {
+            thresholds.cuts = [nums[0], nums[1], nums[2]];
+        }
+        else {
+            invalidCuts = true;
+        }
+    }
+    const floor = /^\s*hotspotFloor\s*:\s*([0-9.]+)\s*$/im.exec(text);
+    if (floor)
+        thresholds.hotspotFloor = Number(floor[1]);
+    return { thresholds, invalidCuts };
+}
+export function changeJsonPath(projectPath, change) {
+    return path.join(projectPath, "lawbook", "changes", change, "change.json");
+}
+export function readCeremonyRecord(projectPath, change) {
+    const p = changeJsonPath(projectPath, change);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Confirmed level, or 3 when change.json is missing. */
+export function confirmedLevel(projectPath, change) {
+    return readCeremonyRecord(projectPath, change)?.confirmedLevel ?? 3;
+}
+export function writeCeremonyRecord(projectPath, change, record) {
+    const p = changeJsonPath(projectPath, change);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(record, null, 2) + "\n");
+}
+export function setCeremonyLevel(projectPath, change, opts) {
+    const proposed = opts.proposal.level;
+    if (proposed !== null && opts.level < proposed && !opts.reason) {
+        throw new Error(`mode 'set' to a lower level than proposed (${proposed}) requires 'reason'`);
+    }
+    const prev = readCeremonyRecord(projectPath, change);
+    const record = {
+        ...opts.proposal,
+        confirmedLevel: opts.level,
+        confirmedBy: opts.confirmedBy,
+        confirmedAt: new Date().toISOString(),
+        overrideReason: opts.reason,
+        promotions: prev?.promotions ?? [],
+    };
+    writeCeremonyRecord(projectPath, change, record);
+    return record;
+}
+export function promoteCeremonyLevel(projectPath, change, to, reason) {
+    const prev = readCeremonyRecord(projectPath, change);
+    if (!prev)
+        throw new Error(`change "${change}" has no change.json to promote`);
+    if (to <= prev.confirmedLevel) {
+        throw new Error(`promote requires a higher level than ${prev.confirmedLevel}`);
+    }
+    const record = {
+        ...prev,
+        confirmedLevel: to,
+        confirmedAt: new Date().toISOString(),
+        promotions: [
+            ...prev.promotions,
+            { from: prev.confirmedLevel, to, at: new Date().toISOString(), reason },
+        ],
+    };
+    writeCeremonyRecord(projectPath, change, record);
+    scaffoldArtifactsForLevel(projectPath, change, to);
+    return record;
+}
+/**
+ * Create missing higher-level artifacts when promoting. Never deletes `record.md`.
+ * Seeds `proposal.md` / `tasks.md` from `record.md` when present.
+ */
+export function scaffoldArtifactsForLevel(projectPath, change, level) {
+    const changeDir = path.join(projectPath, "lawbook", "changes", change);
+    if (!fs.existsSync(changeDir))
+        return;
+    const needs = artifactNeeds(level, readChangeType(projectPath, change));
+    const recordPath = path.join(changeDir, "record.md");
+    const recordText = fs.existsSync(recordPath) ? fs.readFileSync(recordPath, "utf8") : "";
+    const ensure = (rel, content) => {
+        const abs = path.join(changeDir, rel);
+        if (!fs.existsSync(abs)) {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, content);
+        }
+    };
+    if (needs.proposal) {
+        ensure("proposal.md", `# ${change}\n\n## Why\n\n${extractWhy(recordText) || "(promoted — fill in why)"}\n\n## What\n\n(promoted from level ${level})\n`);
+    }
+    if (needs.design && !needs.designOptionalWithJustification) {
+        ensure("design.md", `# Design — ${change}\n\n## Approach\n\n(promoted — fill in)\n`);
+    }
+    if (needs.tasksFile) {
+        const steps = extractChecklist(recordText);
+        ensure("tasks.md", steps.length
+            ? steps.map((s) => `- [ ] ${s}`).join("\n") + "\n"
+            : `- [ ] Implement\n- [ ] Add or update tests\n- [ ] Write discipline report under reports/\n`);
+    }
+    ensure("reports/README.md", `# Reports — ${change}\n\nAdd at least one discipline report before archive.\n`);
+}
+function extractWhy(recordMd) {
+    const m = /\*\*Why:\*\*\s*(.+)/i.exec(recordMd);
+    return m?.[1]?.trim() ?? "";
+}
+function extractChecklist(recordMd) {
+    const out = [];
+    for (const line of recordMd.split("\n")) {
+        const m = /^\s*[-*]\s+\[[ xX]\]\s+(.+)$/.exec(line);
+        if (m)
+            out.push(m[1].trim());
+    }
+    return out;
+}
+/** Count unchecked `- [ ]` tasks in markdown (tasks.md or record.md Steps). */
+export function countUncheckedTasks(markdown) {
+    return (markdown.match(/^\s*[-*]\s+\[ \]/gm) ?? []).length;
+}
+export function hasDisciplineReport(changeDir) {
+    const reportsDir = path.join(changeDir, "reports");
+    if (!fs.existsSync(reportsDir))
+        return false;
+    return fs
+        .readdirSync(reportsDir)
+        .some((n) => n.endsWith(".md") && n.toLowerCase() !== "readme.md");
+}

package/dist/modules/lawbook/quick.js

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+import path from "node:path";
+import { gatherSignals, loadCeremonyConfig, promoteCeremonyLevel, proposeLevel, setCeremonyLevel, } from "./levels.js";
+/**
+ * Scaffold a level-0 change: `record.md`, `change.json`, and `reports/`.
+ *
+ * @param projectPath - Project root with `lawbook/`.
+ * @param name - Change folder name (kebab-case).
+ * @param targets - Optional paths/symbols used to propose the level (default empty → score 0).
+ */
+export function scaffoldQuick(projectPath, name, targets = { paths: [], symbols: [] }) {
+    const changeDir = path.join(projectPath, "lawbook", "changes", name);
+    if (fs.existsSync(changeDir)) {
+        throw new Error(`change "${name}" already exists under lawbook/changes/`);
+    }
+    const { thresholds } = loadCeremonyConfig(projectPath);
+    const signals = gatherSignals(projectPath, targets, thresholds);
+    const proposal = proposeLevel(signals, thresholds);
+    // quick always records level 0; if measurement says higher, still allow but note it.
+    const level = 0;
+    fs.mkdirSync(path.join(changeDir, "reports"), { recursive: true });
+    const rationale = proposal.level === null
+        ? proposal.rationale
+        : proposal.level > 0
+            ? `${proposal.rationale} — quick forced level 0; promote if scope grows`
+            : proposal.rationale;
+    const recordMd = `# ${name}
+
+**Level:** 0 (proposed: ${proposal.level ?? "n/a"}, confirmed by: human)
+**Why:** ${rationale}
+
+## What changes
+
+<!-- 2–5 lines: what and why. -->
+
+## Steps
+
+- [ ] Make the fix
+- [ ] Add or update a regression test
+- [ ] Record evidence under reports/
+
+## Evidence
+
+- \`reports/\` — add a discipline report before archive
+`;
+    fs.writeFileSync(path.join(changeDir, "record.md"), recordMd);
+    fs.writeFileSync(path.join(changeDir, "reports", "README.md"), `# Reports — ${name}\n\nAdd at least one discipline report before archive.\n`);
+    const record = setCeremonyLevel(projectPath, name, {
+        proposal: { ...proposal, rationale },
+        level,
+        confirmedBy: "human",
+        reason: proposal.level !== null && proposal.level > 0 ? "speclaw quick" : undefined,
+    });
+    return { change: name, proposal, record, dir: changeDir };
+}
+/**
+ * Handle `lawbook_level` modes: propose / set / promote / explain.
+ */
+export function handleLevel(args) {
+    const targets = {
+        paths: args.paths ?? [],
+        symbols: args.symbols ?? [],
+    };
+    const { thresholds } = loadCeremonyConfig(args.projectPath);
+    const signals = gatherSignals(args.projectPath, targets, thresholds);
+    const proposal = proposeLevel(signals, thresholds);
+    if (args.mode === "propose" || args.mode === "explain") {
+        return { mode: args.mode, proposal };
+    }
+    if (!args.change)
+        throw new Error(`mode '${args.mode}' requires 'change'`);
+    if (args.mode === "set") {
+        if (args.level === undefined)
+            throw new Error("mode 'set' requires 'level'");
+        return setCeremonyLevel(args.projectPath, args.change, {
+            proposal,
+            level: args.level,
+            confirmedBy: "human",
+            reason: args.reason,
+        });
+    }
+    // promote
+    if (args.level === undefined)
+        throw new Error("mode 'promote' requires 'level'");
+    return promoteCeremonyLevel(args.projectPath, args.change, args.level, args.reason ?? "scope grew");
+}

package/dist/modules/lawbook/register.js

@@ -5,6 +5,8 @@ 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 { handleLevel } from "./quick.js";
+import { investigate, formatInvestigateResult } from "./investigate.js";
 import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
 import { buildDriftReport, renderDriftAgent } from "./drift.js";
 const ASSETS = assetsDir(import.meta.url);
@@ -29,6 +31,22 @@ export function registerSpec(server, opts = {}) {
     };
     add("lawbook_init", "Create the lawbook/ workspace (specs, changes, archive, config). Idempotent.", { projectPath: z.string() }, async ({ projectPath }) => text(specInit(projectPath)));
     add("lawbook_list", "List active changes, archives, and canonical capabilities under lawbook/.", { projectPath: z.string() }, async ({ projectPath }) => text(specList(projectPath)));
+    add("lawbook_level", "Propose, set, promote, or explain a change's ceremony level (0–3).", {
+        projectPath: z.string(),
+        mode: z.enum(["propose", "set", "promote", "explain"]),
+        change: z.string().optional(),
+        paths: z.array(z.string()).optional(),
+        symbols: z.array(z.string()).optional(),
+        level: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional(),
+        reason: z.string().optional(),
+    }, async (args) => text(handleLevel(args)));
+    add("lawbook_investigate", "Rank bug origins from the graph. Pass stackTrace or symptom. Returns suspects with reasons — evidence, not a verdict.", {
+        projectPath: z.string(),
+        stackTrace: z.string().optional(),
+        symptom: z.string().optional(),
+        hintPaths: z.array(z.string()).optional(),
+        maxSuspects: z.number().int().min(1).max(25).optional(),
+    }, async (args) => text(formatInvestigateResult(await investigate(args))));
     add("lawbook_validate", "Validate a change's proposal, tasks, and delta specs before build or sync.", { projectPath: z.string(), change: z.string() }, async ({ projectPath, change }) => text(specValidate(projectPath, change)));
     add("lawbook_sync", "Promote a change's delta specs into canonical lawbook/specs/ without archiving.", { projectPath: z.string(), change: z.string() }, async ({ projectPath, change }) => text(specSync(projectPath, change)));
     add("lawbook_archive", "Sync a change into canonical specs, then move it under changes/archive/.", {