@esneiderbravo/speclaw 0.3.9 → 0.3.11

package/dist/cli/commands/query.js

@@ -1,15 +1,20 @@
 import { explore, search, recall, impact, trace } from "../../modules/compass/query.js";
+import { affectedTests } from "../../modules/compass/affected.js";
+import { hotspots, coupling } from "../../modules/compass/hotspots.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`,
+ *   `affected-tests`, `hotspots`, or `coupling`.
+ * @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 +46,119 @@ 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 "hotspots": {
+                const sortRaw = typeof flags.sort === "string" ? flags.sort : undefined;
+                const sortBy = sortRaw === "churn" || sortRaw === "complexity" || sortRaw === "combined"
+                    ? sortRaw
+                    : "combined";
+                const result = hotspots(cwd, {
+                    days: flags.days ? Number(flags.days) : undefined,
+                    since: typeof flags.since === "string" ? flags.since : undefined,
+                    sortBy,
+                    limit: flags.limit ? Number(flags.limit) : undefined,
+                });
+                if (asJson) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                ui.heading(`Hotspots (${result.window.label}, sort=${result.sortBy}): ${result.hotspots.length}`);
+                for (const h of result.hotspots) {
+                    const health = h.health
+                        ? `branches=${h.health.worstBranches} nest=${h.health.worstNesting} loc=${h.health.worstLoc}`
+                        : "health=n/a";
+                    ui.info(`${h.file}  commits=${h.activity.commits} authors=${h.activity.authors}  ${health}`);
+                }
+                result.warnings.forEach((w) => ui.warn(w));
+                return;
+            }
+            case "coupling": {
+                const file = need(args[0], "coupling <file>");
+                const result = coupling(cwd, file, {
+                    days: flags.days ? Number(flags.days) : undefined,
+                    since: typeof flags.since === "string" ? flags.since : undefined,
+                    minShared: flags["min-shared"] ? Number(flags["min-shared"]) : undefined,
+                    maxFilesPerCommit: flags["max-files"] ? Number(flags["max-files"]) : undefined,
+                    limit: flags.limit ? Number(flags.limit) : undefined,
+                });
+                if (asJson) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                ui.heading(`Coupling for ${result.file} (${result.window.label}): ${result.partners.length} partner(s)`);
+                ui.info(`scanned=${result.diagnostics.commitsScanned} skippedTooLarge=${result.diagnostics.skippedTooLarge}`);
+                for (const p of result.partners) {
+                    ui.info(`${p.file}  both=${p.both} strength=${p.strength.toFixed(3)} in_graph=${p.inGraph} isTestPair=${p.isTestPair}`);
+                }
+                result.warnings.forEach((w) => ui.warn(w));
                 return;
             }
             case "trace": {

package/dist/cli/commands/update.js

@@ -108,6 +108,23 @@ const MIGRATIONS = [
             "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.",
+    },
+    {
+        version: "0.3.11",
+        describe: "Hotspots + coupling: schema 8 node_metrics, 90d activity window",
+        agentPrompt: "- Mention `compass_hotspots` / `speclaw hotspots` and `compass_coupling` / `speclaw coupling` " +
+            "(activity × AST health; Jaccard strength + in_graph + isTestPair). Compass schema is now 8 " +
+            "(`node_metrics`) — reindex with `speclaw index`. Default history window is 90 days.\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/index.js

@@ -23,7 +23,10 @@ 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)
+  hotspots                 Rank files by recent churn × AST complexity (--json / --sort)
+  coupling <file>          Temporal co-change partners for a file (--json)
   trace <from> <to>        A call path between two nodes
   visualize [node]         Interactive HTML graph → .speclaw/graph.html
 
@@ -50,9 +53,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`/
+// `hotspots`/`coupling`, machine-consumed output), `mcp` (a long-running stdio
+// server), and `init` (already opens with the fuller `banner()`).
 const HEADER_COMMANDS = new Set([
     undefined,
     "help",
@@ -126,6 +129,9 @@ async function dispatch(cmd, flags) {
         case "recall":
         case "impact":
         case "trace":
+        case "affected-tests":
+        case "hotspots":
+        case "coupling":
             return (await import("./commands/query.js")).runQuery(cmd, flags);
         case "visualize":
             return (await import("./commands/visualize.js")).runVisualize(flags);

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] };
+}