@esneiderbravo/speclaw 0.3.8 → 0.3.10

package/README.md

@@ -131,6 +131,8 @@ speclaw budget          # human table
 speclaw budget --json   # machine-readable; used by the suite gate
 speclaw coverage        # requirement → impl → test coverage (TAP / table)
 speclaw coverage --json # machine-readable coverage report
+speclaw drift           # sealed spec ↔ code drift (default --fail-on semantic)
+speclaw drift --reseal  # photograph current bodies into lawbook/anchors/
 speclaw init --minimal  # omit setup/lifecycle MCP tools from registration
 ```
 

package/dist/cli/commands/drift.js

@@ -0,0 +1,39 @@
+import { ui } from "../lib/ui.js";
+import { buildDriftReport, parseFailOn, renderDriftAgent, renderDriftTable, } from "../../modules/lawbook/drift.js";
+/**
+ * Report deterministic spec↔code drift, or reseal anchors from current bodies.
+ *
+ * Flags: `--json`, `--capability <name>`, `--fail-on <level>`, `--reverse`,
+ * `--reseal`, `--explain`. Default `--fail-on semantic`. Exit 0/1/2.
+ */
+export async function runDrift(flags) {
+    const cwd = process.cwd();
+    const failOn = parseFailOn(flags["fail-on"]);
+    if (failOn === null) {
+        ui.err(`--fail-on must be none, cosmetic, semantic, or any.`);
+        process.exitCode = 2;
+        return;
+    }
+    const capability = typeof flags.capability === "string" ? flags.capability : undefined;
+    const report = buildDriftReport(cwd, {
+        capability,
+        failOn,
+        reverse: Boolean(flags.reverse),
+        reseal: Boolean(flags.reseal),
+    });
+    if (flags.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
+    else if (!process.stdout.isTTY) {
+        process.stdout.write(renderDriftAgent(report) + "\n");
+    }
+    else {
+        ui.heading("speclaw drift");
+        console.log(renderDriftTable(report));
+        if (flags.explain) {
+            ui.plain();
+            console.log(renderDriftAgent(report, 50));
+        }
+    }
+    process.exitCode = report.summary.exitCode;
+}

package/dist/cli/commands/lawbook.js

@@ -56,6 +56,13 @@ export async function runSpec(flags) {
                 const r = specArchive(cwd, req(change, "spec archive <change>"), today());
                 ui.ok(`archived to ${r.archivedTo} (${r.promoted.length} spec(s) promoted)`);
                 r.promoted.forEach((p) => ui.info(`${r.created.includes(p) ? "created" : "updated"}: ${p}`));
+                for (const s of r.seals) {
+                    const msg = `sealed ${s.capability}: ${s.unique} unique / ${s.ambiguous} ambiguous / ${s.unresolved} unresolved → ${s.path}`;
+                    if (s.warned)
+                        ui.warn(msg + " (no resolvable anchors)");
+                    else
+                        ui.info(msg);
+                }
                 return;
             }
             default:

package/dist/cli/commands/query.js

@@ -1,15 +1,19 @@
 import { explore, search, recall, impact, trace } from "../../modules/compass/query.js";
+import { affectedTests } from "../../modules/compass/affected.js";
+import { list } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 /**
  * Run a Compass query from the shell — the same surface agents call via MCP.
  *
- * @param cmd - The query verb: `explore`, `search`, `recall`, `impact`, or `trace`.
- * @param flags - Parsed flags supplying the positional query arguments in `_`.
+ * @param cmd - Query verb: `explore`, `search`, `recall`, `impact`, `trace`, or
+ *   `affected-tests`.
+ * @param flags - Parsed flags supplying positional args and options in `_`.
  * @throws Exits the process with code 1 on missing arguments or query errors.
  */
 export async function runQuery(cmd, flags) {
     const cwd = process.cwd();
     const args = flags._;
+    const asJson = Boolean(flags.json);
     try {
         switch (cmd) {
             case "explore": {
@@ -41,9 +45,73 @@ export async function runQuery(cmd, flags) {
                 return;
             }
             case "impact": {
-                const nodes = impact(cwd, need(args[0], "impact <node>"));
-                ui.heading(`Blast radius: ${nodes.length} dependent(s)`);
-                nodes.forEach((n) => ui.info(`depth ${n.depth}: ${n.name} (${n.file}:${n.line})`));
+                const fileList = list(flags.file);
+                if (!args[0] && fileList.length === 0) {
+                    need(undefined, "impact <node> | impact --file <path>");
+                }
+                const format = flags.flat ? "flat" : "grouped";
+                const result = impact(cwd, {
+                    symbol: args[0],
+                    files: fileList.length ? fileList : undefined,
+                    maxDepth: flags.depth ? Number(flags.depth) : 4,
+                    format,
+                    target: typeof flags.target === "string" ? flags.target : "any",
+                });
+                if (asJson) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                if (result.global) {
+                    ui.heading(`Blast radius: repo-wide`);
+                    ui.warn(result.global.reason);
+                    result.warnings.forEach((w) => ui.warn(w));
+                    return;
+                }
+                ui.heading(`Blast radius: ${result.totals.nodes} node(s) in ${result.totals.modules} module(s)` +
+                    (result.limits.truncated ? " (truncated)" : ""));
+                if (result.target.kind === "symbol" && result.target.definitions.length > 1) {
+                    ui.warn(`"${result.target.symbol}" is defined in ${result.target.definitions.length} places; impact is the union`);
+                }
+                if (format === "flat" && result.nodes) {
+                    result.nodes.forEach((n) => ui.info(`depth ${n.depth} [${n.resolution}]: ${n.name} (${n.file}:${n.line})`));
+                }
+                else {
+                    for (const m of result.modules) {
+                        ui.heading(`${m.module} — ${m.nodes} node(s), ${m.files} file(s), min depth ${m.minDepth}`);
+                        m.top.forEach((n) => ui.info(`depth ${n.depth} [${n.resolution}]: ${n.name} (${n.file}:${n.line})`));
+                    }
+                }
+                if (result.resolution.byName > 0) {
+                    ui.warn(`${result.resolution.byName} result(s) resolved by name (possible collisions)`);
+                }
+                result.warnings.forEach((w) => ui.warn(w));
+                return;
+            }
+            case "affected-tests": {
+                const files = list(flags.file);
+                const fromDiff = typeof flags["from-diff"] === "string"
+                    ? flags["from-diff"]
+                    : flags["from-diff"] === true
+                        ? "HEAD"
+                        : undefined;
+                if (files.length === 0 && !fromDiff && !args[0]) {
+                    need(undefined, "affected-tests --file <path> | --from-diff <ref>");
+                }
+                const result = affectedTests(cwd, {
+                    files: files.length ? files : undefined,
+                    symbols: args[0] ? [args[0]] : undefined,
+                    fromDiff,
+                });
+                if (asJson) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                ui.heading(`Affected tests (${result.mode}): ${result.tests.length} file(s) — skipped ${result.skipped.files} (${result.skipped.percent}%)`);
+                ui.info(result.reason);
+                result.tests.forEach((t) => ui.info(t.file));
+                ui.heading("Command");
+                console.log(result.command);
+                result.warnings.forEach((w) => ui.warn(w));
                 return;
             }
             case "trace": {

package/dist/cli/commands/update.js

@@ -100,6 +100,23 @@ const MIGRATIONS = [
             "`speclaw index`. Optionally add coverage.gateArchive / defaultNeeds under lawbook/config.yaml.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "0.3.9",
+        describe: "Spec drift: speclaw drift + lawbook_drift + schema 6 dual hashes",
+        agentPrompt: "- Mention `speclaw drift` / `lawbook_drift` for sealed spec↔code drift " +
+            "(committed `lawbook/anchors/*.json`, dual body/norm hashes). Compass schema is now 6 — " +
+            "reindex with `speclaw index`, then `speclaw drift --reseal` once to photograph current bodies.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
+    {
+        version: "0.3.10",
+        describe: "Impact v2 + affected-tests: schema 7, grouped blast radius",
+        agentPrompt: "- Mention `compass_impact` (grouped by default; `format: flat` escape hatch) and " +
+            "`compass_affected_tests` / `speclaw affected-tests --from-diff`. Compass schema is now 7 " +
+            "(`files.is_test`, `files.module`) — reindex with `speclaw index`. Optional " +
+            "`.speclaw/affected.json` overrides globals/test globs.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:

package/dist/cli/commands/verify.js

@@ -8,6 +8,7 @@ import { toMarkdown } from "../../modules/foundation/report-md.js";
 import { toSarif } from "../../modules/foundation/sarif.js";
 import { loadManifestForVerify } from "../../modules/foundation/laws.js";
 import { verifyLaws } from "../../modules/foundation/verify.js";
+import { driftFindingsForVerify } from "../../modules/lawbook/drift.js";
 const FORMATS = new Set(["text", "json", "sarif", "markdown"]);
 /**
  * `speclaw verify` — the CI orchestrator over {@link verifyLaws}. Formats and
@@ -45,6 +46,19 @@ export async function runVerify(flags) {
         engines: engines.length ? engines : undefined,
         lawIds: list(flags.law).length ? list(flags.law) : undefined,
     });
+    // Structural spec↔code drift (when anchors exist) contributes semantic/deleted
+    // findings into the same report stream used by SARIF / exit codes.
+    for (const f of driftFindingsForVerify(cwd)) {
+        report.findings.push({
+            lawId: f.ruleId,
+            severity: "error",
+            engine: "graph",
+            file: f.file,
+            line: f.line,
+            message: f.message,
+        });
+        report.summary.failed += 1;
+    }
     const sarifPath = typeof flags.sarif === "string" ? flags.sarif : undefined;
     const jsonPath = typeof flags.json === "string" ? flags.json : undefined;
     if (sarifPath) {

package/dist/cli/index.js

@@ -23,7 +23,8 @@ Compass (code intelligence — the same surface agents use via MCP)
   explore <node>           A node's source + callers/callees
   search <query>           Find nodes by name/keyword
   recall "<query>"         Find code by meaning (semantic)
-  impact <node>            Blast radius: everything that (transitively) calls it
+  impact <node>            Blast radius (grouped by module; --flat / --json)
+  affected-tests           Tests affected by a change (--file / --from-diff / --json)
   trace <from> <to>        A call path between two nodes
   visualize [node]         Interactive HTML graph → .speclaw/graph.html
 
@@ -38,6 +39,7 @@ Other
   doctor                   Verify the installation (--json, --offline, --strict)
   budget                   Measure always-on context cost (tools, skills, instructions)
   coverage                 Requirement → impl → test coverage (--json, --tap, --adopt, --write)
+  drift                    Spec↔code drift (--json, --reseal, --reverse, --fail-on)
   telemetry status         Confirm speclaw ships no telemetry
   check                    Evaluate an action against the laws (hooks call this; --dry-run to preview)
   laws verify              Verify the deterministic dependency/graph laws against the index
@@ -49,9 +51,9 @@ Other
 // Commands that open with the one-line branded header. These are the
 // interactive, human-facing commands whose stdout is prose. Deliberately
 // excluded: `version`/`--version`/`-v` (bare scriptable value), the Compass
-// query family (`explore`/`search`/`recall`/`impact`/`trace`, machine-consumed
-// output), `mcp` (a long-running stdio server), and `init` (already opens with
-// the fuller `banner()`).
+// query family (`explore`/`search`/`recall`/`impact`/`trace`/`affected-tests`,
+// machine-consumed output), `mcp` (a long-running stdio server), and `init`
+// (already opens with the fuller `banner()`).
 const HEADER_COMMANDS = new Set([
     undefined,
     "help",
@@ -62,6 +64,7 @@ const HEADER_COMMANDS = new Set([
     "doctor",
     "budget",
     "coverage",
+    "drift",
     "telemetry",
     "index",
     "watch",
@@ -87,6 +90,8 @@ function maybeHeader(cmd, flags) {
         return;
     if (cmd === "coverage" && (flags.json || flags.tap))
         return;
+    if (cmd === "drift" && flags.json)
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -122,6 +127,7 @@ async function dispatch(cmd, flags) {
         case "recall":
         case "impact":
         case "trace":
+        case "affected-tests":
             return (await import("./commands/query.js")).runQuery(cmd, flags);
         case "visualize":
             return (await import("./commands/visualize.js")).runVisualize(flags);
@@ -133,6 +139,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/budget.js")).runBudget(flags);
         case "coverage":
             return (await import("./commands/coverage.js")).runCoverage(flags);
+        case "drift":
+            return (await import("./commands/drift.js")).runDrift(flags);
         case "telemetry":
             return (await import("./commands/telemetry.js")).runTelemetry(flags);
         case "check":

package/dist/modules/compass/affected-config.js

@@ -0,0 +1,238 @@
+/**
+ * Optional `.speclaw/affected.json` plus embedded defaults for global files,
+ * test globs, named targets, and ignores used by impact / affected-tests.
+ */
+import fs from "node:fs";
+import path from "node:path";
+const DEFAULT_TARGETS = {
+    build: {
+        include: ["src/**"],
+        exclude: ["**/*.{test,spec}.{ts,tsx,js,jsx,mts,cts}", "test/**", "tests/**"],
+    },
+    test: {
+        include: [
+            "src/**",
+            "test/**",
+            "tests/**",
+            "**/*.{test,spec}.{ts,tsx,js,jsx}",
+            "**/conftest.py",
+        ],
+        exclude: [],
+    },
+    lint: {
+        include: ["**/*.{ts,tsx,js,jsx,py}", ".eslintrc*", "eslint.config.*", "ruff.toml"],
+        exclude: [],
+    },
+};
+/** Embedded defaults when `.speclaw/affected.json` is absent. */
+export const DEFAULT_AFFECTED_CONFIG = {
+    version: 1,
+    globalFiles: [
+        "tsconfig*.json",
+        "package.json",
+        "package-lock.json",
+        "pnpm-lock.yaml",
+        "yarn.lock",
+        "LAWS.md",
+        "lawbook/config.yaml",
+        ".speclaw/rules.json",
+        "**/*.config.{ts,js,mjs,cjs}",
+    ],
+    testGlobs: [
+        "test/**",
+        "tests/**",
+        "**/*.test.*",
+        "**/*.spec.*",
+        "**/conftest.py",
+        "**/test_*.py",
+    ],
+    targets: DEFAULT_TARGETS,
+    ignore: [
+        "node_modules/**",
+        "dist/**",
+        "dist-test/**",
+        "vendor/**",
+        "**/generated/**",
+        ".speclaw/**",
+    ],
+};
+/**
+ * Glob match supporting `**`, `*`, and simple `{a,b}` brace lists.
+ *
+ * @param relPath - Project-relative path (either slash style).
+ * @param pattern - Glob pattern.
+ */
+export function matchGlob(relPath, pattern) {
+    const norm = relPath.split("\\").join("/");
+    for (const expanded of expandBraces(pattern.split("\\").join("/"))) {
+        if (globToRegExp(expanded).test(norm))
+            return true;
+    }
+    return false;
+}
+function expandBraces(pattern) {
+    const m = pattern.match(/\{([^{}]+)\}/);
+    if (!m || m.index === undefined)
+        return [pattern];
+    const before = pattern.slice(0, m.index);
+    const after = pattern.slice(m.index + m[0].length);
+    const alts = m[1].split(",");
+    const out = [];
+    for (const alt of alts) {
+        out.push(...expandBraces(before + alt + after));
+    }
+    return out;
+}
+function globToRegExp(pattern) {
+    let i = 0;
+    let re = "^";
+    while (i < pattern.length) {
+        if (pattern.startsWith("**/", i) || (pattern.startsWith("**", i) && i + 2 === pattern.length)) {
+            re += ".*";
+            i += pattern.startsWith("**/", i) ? 3 : 2;
+            continue;
+        }
+        if (pattern[i] === "*") {
+            re += "[^/]*";
+            i++;
+            continue;
+        }
+        const ch = pattern[i];
+        if (/[.+^${}()|[\]\\]/.test(ch))
+            re += `\\${ch}`;
+        else
+            re += ch;
+        i++;
+    }
+    re += "$";
+    return new RegExp(re);
+}
+/**
+ * Whether a relative path matches any of the given globs.
+ *
+ * @param relPath - Project-relative path.
+ * @param globs - Patterns to try.
+ */
+export function matchesAny(relPath, globs) {
+    return globs.some((g) => matchGlob(relPath, g));
+}
+/**
+ * Infer the module bucket for grouping (nearest package root or first two path segments).
+ *
+ * @param relPath - Project-relative file path.
+ */
+export function inferModule(relPath) {
+    const norm = relPath.split("\\").join("/");
+    const parts = norm.split("/").filter(Boolean);
+    if (parts.length === 0)
+        return ".";
+    if (parts.length === 1)
+        return parts[0];
+    // Prefer src/<area>, test/<area>, packages/<name>, …
+    return parts.slice(0, 2).join("/");
+}
+/**
+ * Whether a path looks like a test file under the given test globs.
+ *
+ * @param relPath - Project-relative path.
+ * @param testGlobs - Glob list (defaults from config).
+ */
+export function isTestPath(relPath, testGlobs = DEFAULT_AFFECTED_CONFIG.testGlobs) {
+    return matchesAny(relPath, testGlobs);
+}
+/**
+ * Load and validate `.speclaw/affected.json`, or return embedded defaults.
+ *
+ * @param projectPath - Absolute project root.
+ * @returns The effective config.
+ * @throws If the file exists but is malformed or has the wrong version shape.
+ */
+export function loadAffectedConfig(projectPath) {
+    const p = path.join(projectPath, ".speclaw", "affected.json");
+    if (!fs.existsSync(p))
+        return { ...DEFAULT_AFFECTED_CONFIG, targets: { ...DEFAULT_TARGETS } };
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(p, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`Invalid .speclaw/affected.json: ${err.message}`, { cause: err });
+    }
+    if (!raw || typeof raw !== "object") {
+        throw new Error("Invalid .speclaw/affected.json: expected a JSON object");
+    }
+    const doc = raw;
+    if (doc.version !== 1 && doc.version !== undefined) {
+        throw new Error(`Invalid .speclaw/affected.json: unsupported version ${String(doc.version)}`);
+    }
+    const cfg = {
+        version: 1,
+        globalFiles: asStringArray(doc.globalFiles, DEFAULT_AFFECTED_CONFIG.globalFiles),
+        testGlobs: asStringArray(doc.testGlobs, DEFAULT_AFFECTED_CONFIG.testGlobs),
+        ignore: asStringArray(doc.ignore, DEFAULT_AFFECTED_CONFIG.ignore),
+        targets: { ...DEFAULT_TARGETS },
+    };
+    if (doc.targets && typeof doc.targets === "object") {
+        const t = doc.targets;
+        for (const name of ["build", "test", "lint"]) {
+            const entry = t[name];
+            if (!entry || typeof entry !== "object")
+                continue;
+            const e = entry;
+            cfg.targets[name] = {
+                include: asStringArray(e.include, DEFAULT_TARGETS[name].include),
+                exclude: asStringArray(e.exclude, DEFAULT_TARGETS[name].exclude),
+            };
+        }
+    }
+    return cfg;
+}
+function asStringArray(value, fallback) {
+    if (!Array.isArray(value))
+        return [...fallback];
+    const out = value.filter((v) => typeof v === "string" && v.length > 0);
+    return out.length > 0 ? out : [...fallback];
+}
+/**
+ * Filter changed paths for a named target (Nx-style named inputs).
+ *
+ * @param files - Candidate relative paths.
+ * @param target - Target name; `any` keeps all non-ignored paths.
+ * @param cfg - Affected config.
+ */
+export function filterFilesForTarget(files, target, cfg) {
+    const warnings = [];
+    const notIgnored = files.filter((f) => !matchesAny(f, cfg.ignore));
+    if (target === "any")
+        return { included: notIgnored, warnings };
+    const spec = cfg.targets[target];
+    const included = notIgnored.filter((f) => {
+        if (spec.exclude.some((g) => matchGlob(f, g)))
+            return false;
+        return spec.include.some((g) => matchGlob(f, g));
+    });
+    if (included.length === 0 && notIgnored.length > 0) {
+        warnings.push(`Change only affects other targets; empty for target "${target}" (${notIgnored.length} path(s) filtered out)`);
+    }
+    return { included, warnings };
+}
+/**
+ * Match changed paths against globalFiles globs.
+ *
+ * @param files - Relative paths.
+ * @param cfg - Affected config.
+ */
+export function matchGlobalFiles(files, cfg) {
+    const patterns = new Set();
+    const matched = [];
+    for (const f of files) {
+        for (const g of cfg.globalFiles) {
+            if (matchGlob(f, g)) {
+                matched.push(f);
+                patterns.add(g);
+                break;
+            }
+        }
+    }
+    return { matched, patterns: [...patterns] };
+}