@esneiderbravo/speclaw 0.3.8 → 0.3.10

package/dist/modules/compass/affected.js

@@ -0,0 +1,249 @@
+/**
+ * Static affected-test selection: reverse reachability into `files.is_test = 1`,
+ * plus a ready-to-run command string.
+ */
+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";
+/**
+ * Select a safe superset of test files affected by a change.
+ *
+ * @param projectPath - Absolute project root with a Compass index.
+ * @param query - Files, symbols, and/or a git diff base ref.
+ */
+export function affectedTests(projectPath, query = {}) {
+    if (!indexExists(projectPath)) {
+        throw new Error("No index found. Build it first with the index_build tool (creates .speclaw/index.db).");
+    }
+    const cfg = loadAffectedConfig(projectPath);
+    const warnings = [];
+    warnings.push(...warnUnindexedLanguages(projectPath));
+    let files = [...(query.files ?? [])];
+    if (query.fromDiff !== undefined) {
+        if (!isGitRepo(projectPath)) {
+            throw new Error("fromDiff requires a git repository");
+        }
+        const base = query.fromDiff === "WORKTREE" || query.fromDiff === "" ? "HEAD" : query.fromDiff;
+        // WORKTREE ≈ uncommitted: use merge-base against HEAD's first-parent via changedFiles("HEAD")
+        // when the caller passes a branch/ref; for literal WORKTREE fall back to HEAD...working tree
+        // is not in changedFiles — use the ref as merge-base target.
+        const diffFiles = query.fromDiff === "WORKTREE"
+            ? listWorktreeChanges(projectPath)
+            : changedFiles(projectPath, base);
+        files = [...new Set([...files, ...diffFiles])];
+        if (files.length === 0) {
+            return {
+                mode: "static",
+                reason: "no changed files",
+                tests: [],
+                skipped: { files: countTestFiles(projectPath), percent: 100 },
+                command: buildTestCommand(projectPath, [], cfg, "none"),
+                warnings,
+            };
+        }
+    }
+    const glob = matchGlobalFiles(files, cfg);
+    if (glob.matched.length > 0) {
+        const allTests = listTestFiles(projectPath);
+        return {
+            mode: "all",
+            reason: `global file matched (${glob.matched.join(", ")})`,
+            tests: allTests.map((file) => ({ file, nodes: 0, minDepth: 0 })),
+            skipped: { files: 0, percent: 0 },
+            command: buildTestCommand(projectPath, [], cfg, "all"),
+            warnings,
+        };
+    }
+    const impactOpts = {
+        files: files.length > 0 ? files : undefined,
+        symbol: query.symbols?.length === 1 ? query.symbols[0] : undefined,
+        maxDepth: query.maxDepth ?? 6,
+        format: "flat",
+        target: "test",
+        edgeKinds: ["call", "import"],
+    };
+    // Multiple symbols → union flat impacts.
+    const nodes = [...(impact(projectPath, impactOpts).nodes ?? [])];
+    if (query.symbols && query.symbols.length > 1) {
+        const seen = new Set(nodes.map((n) => n.nodeId));
+        for (const sym of query.symbols) {
+            for (const n of impact(projectPath, {
+                symbol: sym,
+                format: "flat",
+                maxDepth: impactOpts.maxDepth,
+            }).nodes ?? []) {
+                if (!seen.has(n.nodeId)) {
+                    seen.add(n.nodeId);
+                    nodes.push(n);
+                }
+            }
+        }
+    }
+    // Also include directly changed test files.
+    const testHits = new Map();
+    for (const f of files) {
+        const norm = f.split("\\").join("/");
+        if (matchesAny(norm, cfg.testGlobs)) {
+            testHits.set(norm, { file: norm, nodes: 0, minDepth: 0 });
+        }
+    }
+    const db = openDb(projectPath);
+    try {
+        const isTestByPath = new Map();
+        for (const row of db.prepare("SELECT path, is_test FROM files").all()) {
+            isTestByPath.set(row.path, row.is_test === 1);
+        }
+        for (const n of nodes) {
+            if (!isTestByPath.get(n.file))
+                continue;
+            const prior = testHits.get(n.file);
+            if (!prior) {
+                testHits.set(n.file, { file: n.file, nodes: 1, minDepth: n.depth });
+            }
+            else {
+                prior.nodes += 1;
+                prior.minDepth = Math.min(prior.minDepth, n.depth);
+            }
+        }
+    }
+    finally {
+        db.close();
+    }
+    const tests = [...testHits.values()].sort((a, b) => a.file.localeCompare(b.file));
+    const totalTests = countTestFiles(projectPath);
+    const skippedFiles = Math.max(0, totalTests - tests.length);
+    const percent = totalTests === 0 ? 0 : Math.round((skippedFiles / totalTests) * 100);
+    return {
+        mode: "static",
+        reason: files.length > 0
+            ? `changed ${files.length} file(s)`
+            : query.symbols?.length
+                ? `symbols ${query.symbols.join(", ")}`
+                : "empty selection",
+        tests,
+        skipped: { files: skippedFiles, percent },
+        command: buildTestCommand(projectPath, tests.map((t) => t.file), cfg, tests.length === 0 ? "none" : "subset"),
+        warnings,
+    };
+}
+function listWorktreeChanges(projectPath) {
+    // Prefer merge-base against main/master when available; else HEAD.
+    for (const base of ["main", "master", "HEAD"]) {
+        const files = changedFiles(projectPath, base);
+        if (files.length > 0 || base === "HEAD")
+            return files;
+    }
+    return [];
+}
+function countTestFiles(projectPath) {
+    if (!indexExists(projectPath))
+        return 0;
+    const db = openDb(projectPath);
+    try {
+        const row = db.prepare("SELECT COUNT(*) AS n FROM files WHERE is_test = 1").get();
+        return Number(row.n);
+    }
+    finally {
+        db.close();
+    }
+}
+function listTestFiles(projectPath) {
+    const db = openDb(projectPath);
+    try {
+        return db.prepare("SELECT path FROM files WHERE is_test = 1 ORDER BY path").all().map((r) => r.path);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Build an executable test command from package.json scripts.test when present.
+ *
+ * @param projectPath - Project root.
+ * @param tests - Selected test paths (ignored for mode `all`).
+ * @param _cfg - Reserved for future runner overrides.
+ * @param mode - `all` | `subset` | `none`.
+ */
+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 */
+        }
+    }
+    if (mode === "all") {
+        return script ? "npm test" : "node --test";
+    }
+    if (mode === "none" || tests.length === 0) {
+        return script ? "npm test -- --test-name-pattern=^$" : "node --test --test-name-pattern=^$";
+    }
+    const args = tests.map(shellQuote).join(" ");
+    if (script && /\bnode\s+--test\b/.test(script)) {
+        return `node --test ${args}`;
+    }
+    if (script) {
+        // Pass paths after `--` for npm/vitest/jest-style scripts.
+        return `npm test -- ${args}`;
+    }
+    return `node --test ${args}`;
+}
+function shellQuote(p) {
+    if (/^[A-Za-z0-9_./-]+$/.test(p))
+        return p;
+    return `'${p.replace(/'/g, `'\\''`)}'`;
+}
+/** Warn when present extensions are not in the indexed language set. */
+function warnUnindexedLanguages(projectPath) {
+    const indexedExts = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py"]);
+    const seen = new Set();
+    const warnings = [];
+    walkQuick(projectPath, (rel) => {
+        const ext = path.extname(rel).toLowerCase();
+        if (!ext || indexedExts.has(ext) || seen.has(ext))
+            return;
+        // Only flag common source extensions that Compass does not parse.
+        if (![".go", ".rs", ".java", ".kt", ".rb", ".php", ".cs"].includes(ext))
+            return;
+        seen.add(ext);
+        warnings.push(`${ext} files are present but not indexed by Compass`);
+    });
+    return warnings;
+}
+function walkQuick(root, visit) {
+    const skip = new Set([".git", "node_modules", "dist", "dist-test", ".speclaw", "vendor"]);
+    const stack = [root];
+    let n = 0;
+    while (stack.length && n < 5000) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith(".") && e.name !== ".speclaw") {
+                if (e.isDirectory() && e.name !== ".github")
+                    continue;
+            }
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!skip.has(e.name))
+                    stack.push(full);
+            }
+            else if (e.isFile()) {
+                n++;
+                visit(path.relative(root, full));
+            }
+        }
+    }
+}

package/dist/modules/compass/db.js

@@ -10,8 +10,11 @@ CREATE TABLE IF NOT EXISTS files (
   id INTEGER PRIMARY KEY,
   path TEXT UNIQUE NOT NULL,
   hash TEXT NOT NULL,
-  lang TEXT NOT NULL
+  lang TEXT NOT NULL,
+  is_test INTEGER NOT NULL DEFAULT 0,
+  module TEXT NOT NULL DEFAULT ''
 );
+CREATE INDEX IF NOT EXISTS idx_files_is_test ON files(is_test);
 -- nodes: the definitions in the codebase (functions, classes, methods, types).
 CREATE TABLE IF NOT EXISTS nodes (
   id INTEGER PRIMARY KEY,
@@ -23,10 +26,13 @@ CREATE TABLE IF NOT EXISTS nodes (
   start_byte INTEGER NOT NULL,
   end_byte INTEGER NOT NULL,
   parent_id INTEGER,
-  signature TEXT
+  signature TEXT,
+  body_hash TEXT,
+  norm_hash TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
 CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file_id);
+CREATE INDEX IF NOT EXISTS idx_nodes_norm_hash ON nodes(norm_hash);
 -- edges: a reference from one node to a named target, resolved lazily.
 CREATE TABLE IF NOT EXISTS edges (
   id INTEGER PRIMARY KEY,
@@ -73,9 +79,32 @@ CREATE TABLE IF NOT EXISTS coverage_links (
 CREATE INDEX IF NOT EXISTS idx_cov_target ON coverage_links(artifact_type, name, revision);
 CREATE INDEX IF NOT EXISTS idx_cov_file ON coverage_links(file_path);
 CREATE INDEX IF NOT EXISTS idx_cov_node ON coverage_links(node_id);
+-- spec_anchors: projection of committed lawbook/anchors/*.json (source of truth on disk).
+CREATE TABLE IF NOT EXISTS spec_anchors (
+  id INTEGER PRIMARY KEY,
+  spec_id TEXT NOT NULL,
+  capability TEXT NOT NULL,
+  requirement_id TEXT NOT NULL,
+  scenario_id TEXT NOT NULL DEFAULT '',
+  anchor_kind TEXT NOT NULL,
+  symbol_name TEXT NOT NULL,
+  file_path TEXT,
+  node_id INTEGER REFERENCES nodes(id) ON DELETE SET NULL,
+  resolution TEXT NOT NULL,
+  content_hash TEXT,
+  raw_hash TEXT,
+  archived_at TEXT NOT NULL,
+  commit_sha TEXT,
+  source TEXT NOT NULL,
+  normalizer_version INTEGER NOT NULL DEFAULT 1,
+  UNIQUE (spec_id, requirement_id, scenario_id, anchor_kind, symbol_name)
+);
+CREATE INDEX IF NOT EXISTS idx_anchors_capability ON spec_anchors(capability);
+CREATE INDEX IF NOT EXISTS idx_anchors_symbol ON spec_anchors(symbol_name);
+CREATE INDEX IF NOT EXISTS idx_anchors_node ON spec_anchors(node_id);
 `;
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "5";
+export const SCHEMA_VERSION = "7";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -101,12 +130,16 @@ function isStale(db) {
         return false;
     if (readSchemaVersion(db) !== SCHEMA_VERSION)
         return true;
-    const cols = db.prepare("PRAGMA table_info(edges)").all().map((c) => c.name);
-    return !cols.includes("src_node_id") || !cols.includes("dst_node_id");
+    const edgeCols = db.prepare("PRAGMA table_info(edges)").all().map((c) => c.name);
+    if (!edgeCols.includes("src_node_id") || !edgeCols.includes("dst_node_id"))
+        return true;
+    const fileCols = db.prepare("PRAGMA table_info(files)").all().map((c) => c.name);
+    return !fileCols.includes("is_test") || !fileCols.includes("module");
 }
 /** Drop every table (children first) so the current schema can be recreated cleanly. */
 function resetSchema(db) {
     db.exec(`
+    DROP TABLE IF EXISTS spec_anchors;
     DROP TABLE IF EXISTS coverage_links;
     DROP TABLE IF EXISTS git_history_cache;
     DROP TABLE IF EXISTS node_embeddings;
@@ -133,15 +166,61 @@ export function openDb(projectPath) {
     fs.mkdirSync(dir, { recursive: true });
     const db = new DatabaseSync(path.join(dir, "index.db"));
     db.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
-    if (isStale(db))
+    const wiped = isStale(db);
+    if (wiped)
         resetSchema(db);
     db.exec(SCHEMA);
     const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
     if (!row) {
         db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?)").run(SCHEMA_VERSION);
     }
+    if (wiped) {
+        db.prepare("INSERT INTO meta(key, value) VALUES ('needs_reindex', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+    }
+    // Projection from committed JSON — safe even when nodes are empty (node_id null).
+    rehydrateAnchors(db, projectPath);
     return db;
 }
+/**
+ * Rebuild `spec_anchors` from `lawbook/anchors/*.json`. Idempotent; called on
+ * every open so a wiped `.speclaw/` still sees committed seals.
+ */
+export function rehydrateAnchors(db, projectPath) {
+    const dir = path.join(projectPath, "lawbook", "anchors");
+    db.exec("DELETE FROM spec_anchors");
+    if (!fs.existsSync(dir))
+        return;
+    const ins = db.prepare(`INSERT OR REPLACE INTO spec_anchors(
+       spec_id, capability, requirement_id, scenario_id, anchor_kind, symbol_name,
+       file_path, node_id, resolution, content_hash, raw_hash, archived_at, commit_sha,
+       source, normalizer_version
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?, ?, ?)`);
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const capability = parsed.capability ?? name.replace(/\.json$/, "");
+        const nv = Number(parsed.normalizerVersion ?? 1);
+        for (const a of parsed.anchors ?? []) {
+            ins.run(String(a.specId ?? capability), capability, String(a.requirementId ?? ""), String(a.scenarioId ?? ""), String(a.anchorKind ?? "symbol"), String(a.symbolName ?? ""), a.filePath == null ? null : String(a.filePath), String(a.resolution ?? "unresolved"), a.contentHash == null ? null : String(a.contentHash), a.rawHash == null ? null : String(a.rawHash), String(a.archivedAt ?? new Date().toISOString()), a.commitSha == null ? null : String(a.commitSha), String(a.source ?? "backtick"), Number(a.normalizerVersion ?? nv));
+        }
+    }
+}
+/** Whether the index was wiped and must be rebuilt before hash comparisons. */
+export function needsReindex(db) {
+    const row = db.prepare("SELECT value FROM meta WHERE key = 'needs_reindex'").get();
+    return row?.value === "1";
+}
+/** Clear the needs-reindex marker after a successful index run. */
+export function clearNeedsReindex(db) {
+    db.prepare("DELETE FROM meta WHERE key = 'needs_reindex'").run();
+}
 /** Absolute path to the index database file for a project. */
 export function indexPath(projectPath) {
     return path.join(projectPath, ".speclaw", "index.db");

package/dist/modules/compass/extract.js

@@ -1,4 +1,5 @@
 import { parse } from "./parser.js";
+import { rawHash, structuralHash } from "./hash.js";
 const COMMENT_TYPES = new Set(["comment", "line_comment", "block_comment"]);
 /** `Covers:` / `Needs:` / `@covers` at the start of a comment line. */
 const RE_DIRECTIVE = /(?:^|\s|\*)\s*(?:@)?(covers|needs)\s*:?\s+([^\n*]+)/i;
@@ -113,6 +114,8 @@ export async function extract(source, lang) {
                     endByte: node.endIndex,
                     parentIndex: ownerIndex,
                     signature: signatureOf(node),
+                    bodyHash: rawHash(source, node.startIndex, node.endIndex),
+                    normHash: structuralHash(node),
                 });
                 nextOwner = index;
             }

package/dist/modules/compass/hash.js

@@ -0,0 +1,77 @@
+/**
+ * Content hashes for Compass nodes: raw body bytes vs structural (tree-sitter)
+ * normal form. Structural hashes ignore comments and insignificant whitespace
+ * while preserving string literals — the dual-hash pair powers drift classification.
+ */
+import { createHash } from "node:crypto";
+/** Bump when the structural walk changes; stored anchors become `stale-hash`. */
+export const NORMALIZER_VERSION = 1;
+const COMMENT_TYPES = new Set([
+    "comment",
+    "line_comment",
+    "block_comment",
+    "html_comment",
+    "hash_bang_line",
+]);
+/** Types whose text is emitted verbatim (spaces inside matter). */
+const VERBATIM_TYPES = new Set([
+    "string",
+    "string_literal",
+    "string_fragment",
+    "template_string",
+    "template_literal",
+    "raw_string_literal",
+    "regex",
+    "regex_pattern",
+    "concatenated_string",
+]);
+function digest(parts) {
+    const h = createHash("sha256");
+    for (const p of parts) {
+        h.update(p);
+        h.update("\u0000");
+    }
+    return h.digest("hex").slice(0, 32);
+}
+/**
+ * Hash of the exact source bytes for a symbol range (detects cosmetic edits).
+ *
+ * @param source - Full file source as UTF-8 string.
+ * @param startByte - Inclusive start offset.
+ * @param endByte - Exclusive end offset.
+ */
+export function rawHash(source, startByte, endByte) {
+    return createHash("sha256").update(source.slice(startByte, endByte)).digest("hex").slice(0, 32);
+}
+/**
+ * Structural hash of a tree-sitter subtree. Invariant to reformatting and
+ * comments; sensitive to control flow, identifiers, and string contents.
+ *
+ * @param node - Definition node from the parse tree.
+ */
+export function structuralHash(node) {
+    const parts = [`v${NORMALIZER_VERSION}`];
+    const walk = (n) => {
+        if (COMMENT_TYPES.has(n.type))
+            return;
+        if (VERBATIM_TYPES.has(n.type)) {
+            parts.push(`str:${n.text}`);
+            return;
+        }
+        if (n.namedChildCount === 0) {
+            const t = n.text.trim();
+            if (t.length > 0)
+                parts.push(t);
+            return;
+        }
+        parts.push(`(${n.type}`);
+        for (let i = 0; i < n.childCount; i++) {
+            const c = n.child(i);
+            if (c)
+                walk(c);
+        }
+        parts.push(")");
+    };
+    walk(node);
+    return digest(parts);
+}