@esneiderbravo/speclaw 2.0.9 → 2.0.10

package/README.md

@@ -116,7 +116,7 @@ gh attestation verify <tarball> --owner esneiderbravo
 | Module | What it does |
 | :-- | :-- |
 | **Foundation** | The project's constitution: `LAWS.md` binding granular standards under `docs/standards/`, plus `CLAUDE.md` / `AGENTS.md`. **Enforced** via agent hooks (`speclaw check`), deterministic graph laws (`speclaw verify` / `laws verify`), multidialect compile (`laws compile`), and committed **`speclaw.lock`** digests + injection scan (`laws lock` / `accept` / `scan`). |
-| **Compass** | Local code graph (tree-sitter → `node:sqlite`): hybrid find (FTS5 + vectors + RRF + PageRank), impact, affected-tests, hotspots, coupling, visualize. Schema **10**. Refreshed silently at every Claude Code session start once built. No LLM — lives in `.speclaw/` (gitignored). |
+| **Compass** | Local code graph (tree-sitter → `node:sqlite`): hybrid find (FTS5 + vectors + RRF + PageRank), impact, affected-tests, hotspots, coupling, visualize. Schema **11**. Refreshed silently at every Claude Code session start once built. No LLM — lives in `.speclaw/` (gitignored). |
 | **Lawbook** | Spec-driven workflow with **adaptive ceremony** (levels 0–3), EARS linting, requirement **coverage**, sealed **drift** anchors, bugfix + `lawbook_investigate`. Artifacts under `lawbook/`. |
 | **Cortex** | **One brain. Many agents.** The multi-agent loop: durable `harness.json`, MCP tool `cortex` (`status`/`start`/`advance`/`rework`/`brief`), CLI `speclaw cortex`, skill `/lawbook/cortex`. Dispatches explorer → planner → implementer → reviewer → tester → archiver. |
 | **Team** | Declare `team.owners` in `lawbook/config.yaml`; `speclaw owners --write` compiles a managed trailing block in `.github/CODEOWNERS` (GitHub: last match wins). Doctor checks the posture. CLI-only — no MCP tool. |

package/dist/cli/commands/query.js

@@ -47,8 +47,11 @@ export async function runQuery(cmd, flags) {
                 console.log(s.source);
                 ui.heading("Callees");
                 r.callees?.forEach((c) => ui.info(`${c.name}${c.file ? ` (${c.file}:${c.line})` : ""}`));
+                if (r.unresolvedCallees && r.unresolvedCallees.count > 0) {
+                    ui.info(`+ ${r.unresolvedCallees.count} unresolved call(s): ${r.unresolvedCallees.sample.join(", ")}`);
+                }
                 ui.heading("Callers");
-                r.callers?.forEach((c) => ui.info(`${c.name} (${c.file}:${c.line})`));
+                r.callers?.forEach((c) => ui.info(`${c.kind === "file" ? "(file) " : ""}${c.name} (${c.file}:${c.line})`));
                 return;
             }
             case "search":
@@ -147,7 +150,14 @@ export async function runQuery(cmd, flags) {
                 ui.info(result.reason);
                 result.tests.forEach((t) => ui.info(t.file));
                 ui.heading("Command");
-                console.log(result.command);
+                // Covers: req~affected-test-selection~1
+                if (result.command === null) {
+                    console.log(`no command: ${result.commandReason}`);
+                }
+                else {
+                    console.log(result.command);
+                    ui.info(result.commandReason);
+                }
                 result.warnings.forEach((w) => ui.warn(w));
                 return;
             }

package/dist/cli/commands/update.js

@@ -237,6 +237,23 @@ const MIGRATIONS = [
             "`speclaw.lock`.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "2.0.10",
+        describe: "Compass schema 11 — truthful callers, callees, and affected-test commands",
+        agentPrompt: "- Compass is now **schema 11**: the first `speclaw index` after upgrading migrates " +
+            "10→11 and re-extracts every file once (embeddings are reused). Where the project " +
+            'mentions "Schema **10**" or "Compass (schema 10)", change it to schema 11 ' +
+            "(10→11 forces a reindex; embeddings reused).\n" +
+            "- speclaw 2.0.9 or older (including an MCP entry pinned at `@2.0.9` or a stale " +
+            "global CLI) treats a schema-11 index as incompatible and rebuilds it from scratch, " +
+            "dropping the embedding cache. Where the project documents the index or the MCP entry, " +
+            "add: run `speclaw update` so the pinned MCP entry moves to 2.0.10; an older speclaw " +
+            "opening this index rebuilds it from scratch.\n" +
+            "- Affected-test `command` may now be `null` (with `commandReason`) when no test is " +
+            "reachable, and `commands[]` lists one `{ cwd, command, files }` per package. If the " +
+            "project's docs or scripts run `command` blindly, make them handle `null`.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
  * Bring the current project up to date without a full re-init. When the npm

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

@@ -10,10 +10,15 @@ const DEFAULT_TARGETS = {
         exclude: ["**/*.{test,spec}.{ts,tsx,js,jsx,mts,cts}", "test/**", "tests/**"],
     },
     test: {
+        // The `**/` forms cover workspace packages (`apps/web/src/**`), whose
+        // changes would otherwise be filtered out before any test is selected.
         include: [
             "src/**",
             "test/**",
             "tests/**",
+            "**/src/**",
+            "**/test/**",
+            "**/tests/**",
             "**/*.{test,spec}.{ts,tsx,js,jsx}",
             "**/conftest.py",
         ],

package/dist/modules/compass/affected.js

@@ -1,13 +1,13 @@
 /**
  * Static affected-test selection: reverse reachability into `files.is_test = 1`,
- * plus a ready-to-run command string.
+ * plus ready-to-run commands per package (runner detected from `package.json`).
  */
 import fs from "node:fs";
 import path from "node:path";
 import { changedFiles, isGitRepo } from "../../shared/git.js";
 import { openDb, indexExists } from "./db.js";
 import { impact } from "./query.js";
-import { loadAffectedConfig, matchGlobalFiles, matchesAny, } from "./affected-config.js";
+import { loadAffectedConfig, matchGlobalFiles, matchesAny, matchGlob, } from "./affected-config.js";
 /**
  * Select a safe superset of test files affected by a change.
  *
@@ -40,7 +40,7 @@ export function affectedTests(projectPath, query = {}) {
                 reason: "no changed files",
                 tests: [],
                 skipped: { files: countTestFiles(projectPath), percent: 100 },
-                command: buildTestCommand(projectPath, [], cfg, "none"),
+                ...planTestCommand(projectPath, [], "none"),
                 warnings,
             };
         }
@@ -48,12 +48,13 @@ export function affectedTests(projectPath, query = {}) {
     const glob = matchGlobalFiles(files, cfg);
     if (glob.matched.length > 0) {
         const allTests = listTestFiles(projectPath);
+        const reason = `global file matched (${glob.matched.join(", ")})`;
         return {
             mode: "all",
-            reason: `global file matched (${glob.matched.join(", ")})`,
+            reason,
             tests: allTests.map((file) => ({ file, nodes: 0, minDepth: 0 })),
             skipped: { files: 0, percent: 0 },
-            command: buildTestCommand(projectPath, [], cfg, "all"),
+            ...planTestCommand(projectPath, [], "all", reason),
             warnings,
         };
     }
@@ -125,7 +126,7 @@ export function affectedTests(projectPath, query = {}) {
                 : "empty selection",
         tests,
         skipped: { files: skippedFiles, percent },
-        command: buildTestCommand(projectPath, tests.map((t) => t.file), cfg, tests.length === 0 ? "none" : "subset"),
+        ...planTestCommand(projectPath, tests.map((t) => t.file), tests.length === 0 ? "none" : "subset"),
         warnings,
     };
 }
@@ -160,43 +161,359 @@ function listTestFiles(projectPath) {
     }
 }
 /**
- * Build an executable test command from package.json scripts.test when present.
+ * Build the command for a selection as a single string (see {@link planTestCommand}).
  *
  * @param projectPath - Project root.
- * @param tests - Selected test paths (ignored for mode `all`).
+ * @param tests - Selected repo-relative test paths (ignored for mode `all`).
  * @param _cfg - Reserved for future runner overrides.
  * @param mode - `all` | `subset` | `none`.
+ * @returns The command to run from the root, or null when nothing is selected.
  */
 export function buildTestCommand(projectPath, tests, _cfg, mode) {
-    const pkgPath = path.join(projectPath, "package.json");
-    let script;
-    if (fs.existsSync(pkgPath)) {
-        try {
-            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-            script = pkg.scripts?.test;
-        }
-        catch {
-            /* ignore */
-        }
+    return planTestCommand(projectPath, tests, mode).command;
+}
+/** Read a `package.json`; null when absent or unparseable. */
+function readPackage(dir) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    }
+    catch {
+        return null;
     }
+}
+/**
+ * Turn a selection into runnable commands.
+ *
+ * - `none`: `command` is null with a reason; a run-nothing command is never emitted.
+ * - `all`: the root runner's full suite.
+ * - `subset`: files are grouped by their nearest `package.json` directory
+ *   (bounded by the root) and each group gets its own runner's command:
+ *   `npx vitest run`, `npx jest --runTestsByPath`, the `node --test` script's
+ *   flags without coverage flags (mapped onto a compiled-test glob, after
+ *   `npm run pretest`), or `npm test -- <files>` for an unrecognized script.
+ *   Several groups compose as `(cd a && …) && (cd b && …)` from the root.
+ *
+ * @param projectPath - Project root.
+ * @param tests - Selected repo-relative test paths (ignored unless `subset`).
+ * @param mode - `all` | `subset` | `none`.
+ * @param allReason - Why the full suite was selected (mode `all`).
+ * @returns The command plan; `commands` is empty exactly when `command` is null.
+ */
+export function planTestCommand(projectPath, tests, mode, allReason = "the full suite was selected") {
+    // Covers: req~affected-test-selection~1
     if (mode === "all") {
-        return script ? "npm test" : "node --test";
+        const command = fullSuiteCommand(readPackage(projectPath));
+        return {
+            command,
+            commandReason: `${allReason}; run the full suite`,
+            commands: [{ cwd: ".", command, files: [] }],
+        };
     }
     if (mode === "none" || tests.length === 0) {
-        return script ? "npm test -- --test-name-pattern=^$" : "node --test --test-name-pattern=^$";
+        return {
+            command: null,
+            commandReason: "no test file is reachable from the change; nothing to run",
+            commands: [],
+        };
+    }
+    const groups = new Map();
+    const nearest = new Map();
+    for (const t of [...tests].sort()) {
+        const cwd = nearestPackageDir(projectPath, path.posix.dirname(t), nearest);
+        const rel = cwd === "." ? t : t.slice(cwd.length + 1);
+        groups.set(cwd, [...(groups.get(cwd) ?? []), rel]);
+    }
+    const commands = [];
+    const notes = [];
+    const runners = [];
+    for (const cwd of [...groups.keys()].sort()) {
+        const files = groups.get(cwd);
+        const own = readPackage(path.join(projectPath, cwd));
+        const inherited = inheritedRunner(projectPath, cwd, own);
+        const plan = groupCommand(inherited?.pkg ?? own, files);
+        if (inherited) {
+            const from = inherited.dir === "." ? "the root package.json" : `${inherited.dir}/package.json`;
+            plan.note = [`${plan.runner} inherited from ${from}`, plan.note]
+                .filter((n) => n !== undefined)
+                .join("; ");
+        }
+        if (plan.note)
+            notes.push(cwd === "." ? plan.note : `${cwd}: ${plan.note}`);
+        if (plan.command === null)
+            continue;
+        commands.push({ cwd, command: plan.command, files: plan.kept ?? files });
+        runners.push(`${cwd}: ${plan.runner}`);
+    }
+    if (commands.length === 0) {
+        return {
+            command: null,
+            commandReason: `no runnable test file is selected; ${notes.join("; ")}`,
+            commands: [],
+        };
+    }
+    const command = commands.length === 1
+        ? commands[0].cwd === "."
+            ? commands[0].command
+            : `cd ${shellQuote(commands[0].cwd)} && ${commands[0].command}`
+        : commands
+            .map((c) => c.cwd === "." ? `(${c.command})` : `(cd ${shellQuote(c.cwd)} && ${c.command})`)
+            .join(" && ");
+    const head = commands.length === 1
+        ? `${runners[0].split(": ")[1]} in ${commands[0].cwd} for ${tests.length} selected test file(s)`
+        : `${tests.length} selected test file(s) across ${commands.length} packages (${runners.join(", ")}); run from the repository root`;
+    return {
+        command,
+        commandReason: [head, ...notes].join("; "),
+        commands,
+    };
+}
+/** Full-suite command for a package (root `all` mode). */
+function fullSuiteCommand(pkg) {
+    if (pkg?.scripts?.test)
+        return "npm test";
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    if (deps.vitest)
+        return "npx vitest run";
+    if (deps.jest)
+        return "npx jest";
+    return "node --test";
+}
+/** Nearest directory at or above `dir` (repo-relative) holding a `package.json`; `.` at worst. */
+function nearestPackageDir(root, dir, cache) {
+    const hit = cache.get(dir);
+    if (hit !== undefined)
+        return hit;
+    let found;
+    if (dir === "." || dir === "" || dir === "/")
+        found = ".";
+    else if (fs.existsSync(path.join(root, dir, "package.json")))
+        found = dir;
+    else
+        found = nearestPackageDir(root, path.posix.dirname(dir), cache);
+    cache.set(dir, found);
+    return found;
+}
+/** Whether a package declares vitest or jest as a dependency. */
+function declaresRunner(pkg) {
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    return Boolean(deps.vitest || deps.jest);
+}
+/**
+ * Runner inherited by a package that declares none (no `scripts.test`, no
+ * vitest/jest dependency): the nearest ancestor `package.json`, up to the
+ * root, that declares vitest or jest — the hoisted-monorepo layout. Returns
+ * the package to plan with (the leaf with the ancestor's runner dependencies)
+ * and the ancestor's directory, or null when nothing is inherited.
+ */
+function inheritedRunner(root, cwd, own) {
+    if (cwd === "." || own?.scripts?.test || declaresRunner(own))
+        return null;
+    let dir = cwd;
+    while (dir !== ".") {
+        dir = path.posix.dirname(dir);
+        if (dir === "" || dir === "/")
+            dir = ".";
+        const anc = readPackage(path.join(root, dir));
+        if (!declaresRunner(anc))
+            continue;
+        const deps = { ...anc?.dependencies, ...anc?.devDependencies };
+        const runnerDeps = {};
+        if (deps.vitest)
+            runnerDeps.vitest = deps.vitest;
+        if (deps.jest)
+            runnerDeps.jest = deps.jest;
+        return {
+            pkg: { ...own, devDependencies: { ...own?.devDependencies, ...runnerDeps } },
+            dir,
+        };
+    }
+    return null;
+}
+/** Flags dropped from a `node --test` script: coverage thresholds fail on a subset. */
+function isCoverageFlag(token) {
+    return token === "--experimental-test-coverage" || token.startsWith("--test-coverage-");
+}
+/** Node flags whose value may follow as a separate word (`--import ./x.mjs`). */
+const NODE_VALUE_FLAGS = new Set([
+    "--import",
+    "--require",
+    "-r",
+    "--loader",
+    "--experimental-loader",
+    "--env-file",
+    "--conditions",
+    "-C",
+    "--test-reporter",
+    "--test-reporter-destination",
+    "--test-name-pattern",
+    "--test-skip-pattern",
+    "--test-concurrency",
+    "--test-timeout",
+    "--test-shard",
+    "--test-coverage-lines",
+    "--test-coverage-branches",
+    "--test-coverage-functions",
+    "--test-coverage-include",
+    "--test-coverage-exclude",
+]);
+/**
+ * Split a `node --test` script's words (after `node`) into the flags to keep
+ * and the positional test globs. A value-taking flag keeps its value with it;
+ * coverage flags are dropped together with their values. A directory
+ * positional (no glob character, no file extension) becomes `<dir>/**`, so it
+ * matches every file under it.
+ */
+function splitNodeTestArgs(words) {
+    const flags = [];
+    const globs = [];
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i];
+        if (word.startsWith("-")) {
+            const group = [word];
+            if (!word.includes("=") && NODE_VALUE_FLAGS.has(word) && i + 1 < words.length) {
+                group.push(words[++i]);
+            }
+            if (!isCoverageFlag(word))
+                flags.push(...group);
+            continue;
+        }
+        const isDir = !/[*?{[]/.test(word) && !/\.[cm]?[jt]sx?$/.test(word);
+        globs.push(isDir ? `${word.replace(/\/+$/, "")}/**` : word);
     }
-    const args = tests.map(shellQuote).join(" ");
-    if (script && /\bnode\s+--test\b/.test(script)) {
-        return `node --test ${args}`;
+    return { flags, globs };
+}
+/** Source extensions mapped to their compiled JavaScript counterparts. */
+const COMPILED_EXT = [
+    [/\.tsx?$/, ".js"],
+    [/\.mts$/, ".mjs"],
+    [/\.cts$/, ".cjs"],
+];
+/** Source path with its TypeScript extension swapped for the compiled one. */
+function compiledPath(file) {
+    let out = file;
+    for (const [re, ext] of COMPILED_EXT)
+        out = out.replace(re, ext);
+    return out;
+}
+/**
+ * Map a source test path onto the script's globs: the path itself when a glob
+ * matches it, else `<first glob segment>/<compiled path>` when that matches.
+ * `helper` marks a file whose name no glob's last segment can match (e.g.
+ * `test/helpers/fixtures.ts` against `*.test.js`): the runner never executes it,
+ * not even in a full run, so it is left out rather than forcing the full suite.
+ * `null` means a test-shaped file that could not be mapped.
+ */
+function mapOntoGlobs(file, globs) {
+    if (globs.some((g) => matchGlob(file, g)))
+        return file;
+    const base = path.posix.basename(file);
+    const testShaped = globs.some((g) => {
+        const last = g.split("/").pop() ?? g;
+        return matchGlob(base, last) || matchGlob(compiledPath(base), last);
+    });
+    if (!testShaped)
+        return "helper";
+    for (const glob of globs) {
+        const first = glob.split("/")[0];
+        if (!first || /[*{]/.test(first))
+            continue;
+        const mapped = `${first}/${compiledPath(file)}`;
+        if (matchGlob(mapped, glob))
+            return mapped;
+    }
+    return null;
+}
+/**
+ * Command for one package group, with its detected runner and an optional note.
+ * `command` is null only when every file is a helper the runner never executes;
+ * `kept` lists the files the command runs when helpers were left out.
+ */
+function groupCommand(pkg, files) {
+    const script = pkg?.scripts?.test;
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    const args = files.map(shellQuote).join(" ");
+    const tokens = script ? shellSplit(script) : [];
+    const isNodeTest = tokens[0] === "node" && tokens.includes("--test");
+    if ((script && /\bvitest\b/.test(script)) || (!script && deps.vitest)) {
+        return { command: `npx vitest run ${args}`, runner: "vitest" };
+    }
+    if ((script && /\bjest\b/.test(script)) || (!isNodeTest && deps.jest)) {
+        return { command: `npx jest --runTestsByPath ${args}`, runner: "jest" };
+    }
+    if (isNodeTest) {
+        const { flags, globs } = splitNodeTestArgs(tokens.slice(1));
+        const base = ["node", ...flags].map(shellQuote).join(" ");
+        if (globs.length === 0)
+            return { command: `${base} ${args}`, runner: "node --test" };
+        const mapped = files.map((f) => mapOntoGlobs(f, globs));
+        if (mapped.some((m) => m === null)) {
+            return {
+                command: "npm test",
+                runner: "node --test",
+                note: "a selected test file does not fit the test script's glob, so the full suite runs (a safe superset)",
+            };
+        }
+        const runnable = mapped.filter((m) => m !== null && m !== "helper");
+        const kept = files.filter((_, i) => mapped[i] !== "helper");
+        const helpers = mapped.length - runnable.length;
+        const helperNote = helpers > 0 ? `${helpers} helper file(s) the test script never runs left out` : undefined;
+        if (runnable.length === 0)
+            return { command: null, runner: "node --test", note: helperNote };
+        const compiled = runnable.some((m) => !files.includes(m));
+        const prefix = compiled && pkg?.scripts?.pretest ? "npm run pretest && " : "";
+        const notes = [
+            compiled ? "files mapped onto the compiled test glob; coverage flags dropped" : undefined,
+            helperNote,
+        ].filter((n) => n !== undefined);
+        return {
+            command: `${prefix}${base} ${runnable.map(shellQuote).join(" ")}`,
+            runner: "node --test",
+            note: notes.length > 0 ? notes.join("; ") : undefined,
+            kept,
+        };
     }
     if (script) {
-        // Pass paths after `--` for npm/vitest/jest-style scripts.
-        return `npm test -- ${args}`;
+        return {
+            command: `npm test -- ${args}`,
+            runner: "npm test",
+            note: "unrecognized test script: paths are forwarded and it may run the full suite (a superset)",
+        };
+    }
+    return { command: `node --test ${args}`, runner: "node --test" };
+}
+/** Split a shell command line into words, honoring single and double quotes. */
+function shellSplit(line) {
+    const out = [];
+    let cur = "";
+    let quote = null;
+    let has = false;
+    for (const ch of line) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            else
+                cur += ch;
+        }
+        else if (ch === "'" || ch === '"') {
+            quote = ch;
+            has = true;
+        }
+        else if (/\s/.test(ch)) {
+            if (has || cur)
+                out.push(cur);
+            cur = "";
+            has = false;
+        }
+        else {
+            cur += ch;
+        }
     }
-    return `node --test ${args}`;
+    if (has || cur)
+        out.push(cur);
+    return out;
 }
 function shellQuote(p) {
-    if (/^[A-Za-z0-9_./-]+$/.test(p))
+    if (/^[A-Za-z0-9_./=:,@+-]+$/.test(p))
         return p;
     return `'${p.replace(/'/g, `'\\''`)}'`;
 }