@esneiderbravo/speclaw 0.4.0 → 1.0.0

package/dist/modules/compass/register.js

@@ -37,12 +37,14 @@ export function registerCompass(server, opts = {}) {
         });
         return text(formatExploreRich(result, (mode ?? "brief")));
     });
-    add("compass_find", "Find symbols by exact name or by concept. Use exact for identifiers, concept for meaning.", {
+    add("compass_find", "Hybrid search over the index: BM25, vectors, and name match. mode sets weights; pass focus for edited files.", {
         projectPath: z.string(),
         query: z.string(),
         mode: z.enum(["exact", "concept"]),
         limit: z.number().optional(),
-    }, async ({ projectPath, query, mode, limit }) => text(await findSymbols(projectPath, query, mode, limit)));
+        focus: z.array(z.string()).optional(),
+        maxTokens: z.number().int().min(256).max(32_000).optional(),
+    }, async ({ projectPath, query, mode, limit, focus, maxTokens }) => text(JSON.stringify(await findSymbols(projectPath, query, mode, limit, { focus, maxTokens }), null, 2)));
     add("compass_diff_context", "Graph context of changes in one call: symbols, blast radius, tests, hotspots. Default: working tree.", {
         projectPath: z.string(),
         rev: z.string().optional(),
@@ -62,10 +64,12 @@ export function registerCompass(server, opts = {}) {
     add("compass_index", "Build or refresh the code graph index; optional watch action for live re-index.", {
         projectPath: z.string(),
         action: z.enum(["index", "start", "stop", "status"]).optional(),
-    }, async ({ projectPath, action }) => {
+        force: z.boolean().optional(),
+        prune: z.boolean().optional(),
+    }, async ({ projectPath, action, force, prune }) => {
         const act = action ?? "index";
         if (act === "index")
-            return text(await buildIndex(projectPath));
+            return text(await buildIndex(projectPath, { force, prune }));
         const result = act === "start"
             ? startWatch(projectPath)
             : act === "stop"

package/dist/modules/foundation/check.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { performance } from "node:perf_hooks";
-import { compileScope, hasBackend, manifestPath, matchCompiled, readLawManifest, } from "./laws.js";
+import { compileScope, hasBackend, isActiveLaw, manifestPath, matchCompiled, readLawManifest, } from "./laws.js";
 const cache = new Map();
 /**
  * Load the project's compiled law index, using the in-process cache when the
@@ -24,7 +24,9 @@ function loadLaws(projectPath) {
     const manifest = readLawManifest(projectPath);
     if (!manifest)
         return null;
-    const laws = manifest.laws.map((law) => ({ law, scope: compileScope(law.scope) }));
+    const laws = manifest.laws
+        .filter(isActiveLaw)
+        .map((law) => ({ law, scope: compileScope(law.scope) }));
     cache.set(projectPath, { mtimeMs, laws });
     return laws;
 }

package/dist/modules/foundation/compile-laws.js

@@ -0,0 +1,212 @@
+import fs from "node:fs";
+import path from "node:path";
+import { globError, isActiveLaw, readLawManifest, seedManifest, writeLawManifest, } from "./laws.js";
+import { parseLawsFromStandards } from "./laws-parse.js";
+import { agentsmdDialect, claudeRulesDialect, coderabbitDialect, copilotDialect, cursorMdcDialect, patchDelimited, } from "./dialects/index.js";
+import { detectConfiguredAgents } from "../../shared/agents.js";
+import { digestText, provenanceBlock, refreshLockfile } from "./lock.js";
+const DIALECTS = [
+    claudeRulesDialect,
+    cursorMdcDialect,
+    copilotDialect,
+    coderabbitDialect,
+    agentsmdDialect,
+];
+/**
+ * Merge seed + standards parse + on-disk manifest. Manifest wins on id conflict.
+ * Throws if standards declare duplicate ids.
+ */
+export function mergeLawSources(projectPath) {
+    const parsed = parseLawsFromStandards(projectPath);
+    if (parsed.duplicates.size > 0) {
+        const detail = [...parsed.duplicates.entries()]
+            .map(([id, locs]) => `${id} at ${locs.join(" and ")}`)
+            .join("; ");
+        throw new Error(`duplicate law id(s) in docs/standards: ${detail}`);
+    }
+    const byId = new Map();
+    for (const law of seedManifest().laws)
+        byId.set(law.id, law);
+    for (const law of parsed.laws) {
+        if (!byId.has(law.id))
+            byId.set(law.id, law);
+    }
+    const disk = readLawManifest(projectPath);
+    if (disk) {
+        for (const law of disk.laws)
+            byId.set(law.id, law);
+    }
+    return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+function validateScopes(laws) {
+    for (const law of laws) {
+        if (!isActiveLaw(law))
+            continue;
+        for (const p of law.scope) {
+            const err = globError(p);
+            if (err) {
+                throw new Error(`${law.id}: invalid scope ${JSON.stringify(p)} (${err}) — ${law.source.file}${law.source.line ? `:${law.source.line}` : ""}`);
+            }
+        }
+    }
+}
+function writeIfChanged(projectPath, abs, contents, report) {
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const rel = path.relative(projectPath, abs).split(path.sep).join("/");
+    if (fs.existsSync(abs)) {
+        const prev = fs.readFileSync(abs, "utf8");
+        if (prev === contents) {
+            report.unchanged.push(rel);
+            return;
+        }
+    }
+    fs.writeFileSync(abs, contents);
+    report.written.push(rel);
+}
+/** Append a data-only provenance block when missing; body digest stays stable. */
+function withProvenance(contents, lawIds) {
+    const body = contents.replace(/<!-- speclaw:begin-provenance[\s\S]*?speclaw:end-provenance -->\n?/g, "");
+    const dig = digestText(body);
+    const base = body.endsWith("\n") ? body : body + "\n";
+    return base + provenanceBlock({ lawIds, digest: dig, source: "compile" });
+}
+function mergeCoderabbit(projectPath, abs, payloadJson, report) {
+    const payload = JSON.parse(payloadJson);
+    let text = fs.existsSync(abs)
+        ? fs.readFileSync(abs, "utf8")
+        : "reviews:\n  path_instructions: []\n";
+    const start = "# speclaw:path_instructions:start";
+    const end = "# speclaw:path_instructions:end";
+    const blockLines = [start];
+    for (const e of payload.path_instructions) {
+        blockLines.push(`  - path: ${JSON.stringify(e.path)}`);
+        blockLines.push(`    instructions: ${JSON.stringify(e.instructions)}`);
+    }
+    blockLines.push(end);
+    const block = blockLines.join("\n");
+    const re = /# speclaw:path_instructions:start[\s\S]*?# speclaw:path_instructions:end/;
+    if (re.test(text))
+        text = text.replace(re, block);
+    else {
+        if (!/path_instructions\s*:/.test(text)) {
+            if (!/^reviews\s*:/m.test(text))
+                text = `reviews:\n  path_instructions: []\n` + text;
+            else
+                text = text.replace(/^(reviews\s*:)/m, `$1\n  path_instructions: []`);
+        }
+        text = text.trimEnd() + "\n" + block + "\n";
+    }
+    writeIfChanged(projectPath, abs, text.endsWith("\n") ? text : text + "\n", report);
+}
+function ensureClaudeRulesSymlink(projectPath, report) {
+    const link = path.join(projectPath, ".claude", "rules", "speclaw");
+    const target = path.join("..", "..", "ai-specs", "rules");
+    fs.mkdirSync(path.dirname(link), { recursive: true });
+    try {
+        if (fs.lstatSync(link).isSymbolicLink() || fs.existsSync(link)) {
+            report.unchanged.push(".claude/rules/speclaw");
+            return;
+        }
+    }
+    catch {
+        /* missing */
+    }
+    try {
+        fs.symlinkSync(target, link);
+        report.written.push(".claude/rules/speclaw");
+    }
+    catch (err) {
+        report.failed.push({ path: ".claude/rules/speclaw", error: err.message });
+    }
+}
+function applyArtifact(projectPath, art, report) {
+    const abs = path.join(projectPath, art.path);
+    try {
+        if (art.mode === "write") {
+            // Nested AGENTS: only write if parent has package.json
+            if (art.path.endsWith("/AGENTS.md") && art.path !== "AGENTS.md") {
+                const dir = path.dirname(abs);
+                if (!fs.existsSync(path.join(dir, "package.json")))
+                    return;
+            }
+            const body = art.path.endsWith(".md") || art.path.endsWith(".mdc")
+                ? withProvenance(art.contents, art.lawIds)
+                : art.contents;
+            writeIfChanged(projectPath, abs, body, report);
+            return;
+        }
+        if (art.mode === "patch-delimited") {
+            const prev = fs.existsSync(abs) ? fs.readFileSync(abs, "utf8") : "";
+            const next = patchDelimited(prev, art.marker ?? "laws", art.contents);
+            writeIfChanged(projectPath, abs, next, report);
+            return;
+        }
+        if (art.mode === "merge-yaml-path-instructions") {
+            mergeCoderabbit(projectPath, abs, art.contents, report);
+        }
+    }
+    catch (err) {
+        report.failed.push({ path: art.path, error: err.message });
+    }
+}
+/**
+ * Compile project laws into agent dialects. Deterministic and idempotent.
+ */
+export function compileLaws(opts) {
+    const projectPath = opts.projectPath;
+    const report = {
+        schemaVersion: 1,
+        written: [],
+        unchanged: [],
+        failed: [],
+        lawCount: 0,
+        draftCount: 0,
+    };
+    const laws = mergeLawSources(projectPath);
+    validateScopes(laws);
+    report.lawCount = laws.filter(isActiveLaw).length;
+    report.draftCount = laws.filter((l) => !isActiveLaw(l)).length;
+    if (opts.writeManifest !== false) {
+        const manifest = { version: 1, laws };
+        writeLawManifest(projectPath, manifest);
+    }
+    const agents = opts.agents ?? detectConfiguredAgents(projectPath);
+    const ctx = { projectPath, agents };
+    const artifacts = [];
+    for (const d of DIALECTS)
+        artifacts.push(...d.compile(laws, ctx));
+    // Filter nested AGENTS without package.json before write
+    for (const art of artifacts) {
+        if (art.path.endsWith("/AGENTS.md") && art.path !== "AGENTS.md") {
+            const dir = path.join(projectPath, path.dirname(art.path));
+            if (!fs.existsSync(path.join(dir, "package.json")))
+                continue;
+        }
+        applyArtifact(projectPath, art, report);
+    }
+    if (agents.includes("claude"))
+        ensureClaudeRulesSymlink(projectPath, report);
+    // Covers: req~lock-refresh-update~1
+    try {
+        refreshLockfile(projectPath);
+    }
+    catch {
+        // Lock refresh must not fail compile; `speclaw laws lock` surfaces errors.
+    }
+    return report;
+}
+/** Estimate always-on tokens (empty scope) with a bytes/3.6 heuristic. */
+export function estimateAlwaysOnTokens(laws) {
+    const HEADER = 12;
+    const scored = laws
+        .filter((l) => isActiveLaw(l) && l.scope.length === 0)
+        .map((l) => ({
+        id: l.id,
+        tokens: Math.ceil(Buffer.byteLength(l.prose, "utf8") / 3.6) + HEADER,
+    }))
+        .sort((a, b) => b.tokens - a.tokens);
+    return {
+        total: scored.reduce((s, x) => s + x.tokens, 0),
+        top: scored.slice(0, 3),
+    };
+}

package/dist/modules/foundation/dialects/agentsmd.js

@@ -0,0 +1,95 @@
+import { commonPrefix, delimit, } from "./types.js";
+const NESTED_THRESHOLD = 3;
+function degradeSection(title, laws) {
+    const lines = [`## ${title}`, ""];
+    for (const law of laws) {
+        const globHint = law.scope.length > 0 ? `In files that match \`${law.scope.join("`, `")}\`, ` : "";
+        lines.push(`### ${law.title} (\`${law.id}\`)`);
+        lines.push("");
+        lines.push(`${globHint}${law.prose}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * AGENTS.md dialect: move scope into prose; optional nested AGENTS.md files.
+ * Emits patch-delimited content for the root file.
+ */
+export const agentsmdDialect = {
+    id: "agentsmd",
+    compile(laws, ctx) {
+        const active = laws.filter((l) => (l.status ?? "active") !== "draft");
+        const global = active.filter((l) => l.scope.length === 0);
+        const scoped = active.filter((l) => l.scope.length > 0);
+        const byPrefix = new Map();
+        for (const law of scoped) {
+            const pref = commonPrefix(law.scope) || "_misc";
+            const list = byPrefix.get(pref) ?? [];
+            list.push(law);
+            byPrefix.set(pref, list);
+        }
+        const artifacts = [];
+        const rootParts = [
+            "## speclaw laws (generated)",
+            "",
+            "_Edit `docs/standards/*.md` or `.speclaw/laws-manifest.json`; do not edit this block._",
+            "",
+        ];
+        if (global.length)
+            rootParts.push(degradeSection("Global rules", global));
+        const nestedMention = [];
+        for (const [pref, group] of [...byPrefix.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+            const pkg = pref !== "_misc" && pref.length > 0;
+            const nest = pkg &&
+                group.length >= NESTED_THRESHOLD &&
+                // Nested only when a package.json exists under that prefix.
+                true;
+            // Nesting is decided by the orchestrator (fs check); here we always
+            // put dense prefixes in a nested artifact path hint via mode write.
+            if (nest && pref !== "_misc") {
+                nestedMention.push(pref);
+                artifacts.push({
+                    path: `${pref}/AGENTS.md`,
+                    contents: delimit("laws", degradeSection(`Rules for \`${pref}\``, group) +
+                        `\n_Generated by speclaw from law ids: ${group.map((l) => l.id).join(", ")}_\n`),
+                    lawIds: group.map((l) => l.id),
+                    mode: "write",
+                });
+            }
+            else {
+                const title = pref === "_misc" ? "Scoped rules" : `Rules for \`${pref}\``;
+                rootParts.push(degradeSection(title, group));
+            }
+        }
+        if (nestedMention.length) {
+            rootParts.push("## Nested AGENTS.md files", "");
+            for (const p of nestedMention)
+                rootParts.push(`- [\`${p}/AGENTS.md\`](${p}/AGENTS.md)`);
+            rootParts.push("");
+        }
+        void ctx;
+        artifacts.push({
+            path: "AGENTS.md",
+            contents: rootParts.join("\n"),
+            lawIds: active.map((l) => l.id),
+            mode: "patch-delimited",
+            marker: "laws",
+        });
+        artifacts.push({
+            path: "CLAUDE.md",
+            contents: [
+                "## speclaw (generated)",
+                "",
+                "Import shared agent context: `@AGENTS.md`",
+                "",
+                "Path-scoped laws live under `.claude/rules/` (symlink to `ai-specs/rules`).",
+                "Do not rely on Claude Code reading `AGENTS.md` without the import.",
+                "",
+            ].join("\n"),
+            lawIds: active.map((l) => l.id),
+            mode: "patch-delimited",
+            marker: "laws",
+        });
+        return artifacts;
+    },
+};

package/dist/modules/foundation/dialects/claude-cursor.js

@@ -0,0 +1,45 @@
+import { frontmatter, lawSlug, } from "./types.js";
+function body(law) {
+    return [`# ${law.title}`, "", `<!-- speclaw:law-id ${law.id} -->`, "", law.prose, ""].join("\n");
+}
+/** Claude Code `.claude/rules` via managed `ai-specs/rules/<slug>.md` + `paths:`. */
+export const claudeRulesDialect = {
+    id: "claude-rules",
+    compile(laws, ctx) {
+        if (!ctx.agents.includes("claude"))
+            return [];
+        const active = laws.filter((l) => (l.status ?? "active") !== "draft");
+        return active.map((law) => {
+            const fm = law.scope.length === 0 ? frontmatter({}) : frontmatter({ paths: law.scope });
+            return {
+                path: `ai-specs/rules/${lawSlug(law.id)}.md`,
+                contents: fm + body(law),
+                lawIds: [law.id],
+                mode: "write",
+            };
+        });
+    },
+};
+/** Cursor rules as `.mdc` under `ai-specs/rules` (symlinked via `.cursor/rules`). */
+export const cursorMdcDialect = {
+    id: "cursor-mdc",
+    compile(laws, ctx) {
+        if (!ctx.agents.includes("cursor"))
+            return [];
+        const active = laws.filter((l) => (l.status ?? "active") !== "draft");
+        return active.map((law) => {
+            const empty = law.scope.length === 0;
+            const fm = frontmatter({
+                description: law.title,
+                alwaysApply: empty,
+                ...(empty ? {} : { globs: law.scope }),
+            });
+            return {
+                path: `ai-specs/rules/${lawSlug(law.id)}.mdc`,
+                contents: fm + body(law),
+                lawIds: [law.id],
+                mode: "write",
+            };
+        });
+    },
+};

package/dist/modules/foundation/dialects/coderabbit.js

@@ -0,0 +1,27 @@
+/**
+ * CodeRabbit: emit a merge artifact describing path_instructions entries.
+ * The orchestrator merges into existing YAML without a full YAML parser —
+ * marker-based line surgery on `path_instructions:` list items.
+ */
+export const coderabbitDialect = {
+    id: "coderabbit",
+    compile(laws, ctx) {
+        if (!ctx.agents.includes("coderabbit"))
+            return [];
+        const active = laws.filter((l) => (l.status ?? "active") !== "draft" && l.scope.length > 0);
+        if (active.length === 0)
+            return [];
+        const entries = active.map((law) => ({
+            path: law.scope[0] ?? "**",
+            instructions: `[speclaw:${law.id}] ${law.prose}`,
+        }));
+        return [
+            {
+                path: ".coderabbit.yaml",
+                contents: JSON.stringify({ path_instructions: entries }, null, 2) + "\n",
+                lawIds: active.map((l) => l.id),
+                mode: "merge-yaml-path-instructions",
+            },
+        ];
+    },
+};

package/dist/modules/foundation/dialects/copilot.js

@@ -0,0 +1,35 @@
+import { frontmatter, lawSlug, } from "./types.js";
+/**
+ * Copilot path-scoped instructions. Scoped laws only — never also dump the
+ * same body into AGENTS (dual-read nondeterminism).
+ */
+export const copilotDialect = {
+    id: "copilot-instructions",
+    compile(laws, ctx) {
+        // Emit when explicitly wanted: agent id "copilot" or always if .github exists —
+        // orchestrator passes agents; treat missing copilot as skip unless "agents" generic.
+        const want = ctx.agents.includes("copilot") ||
+            ctx.agents.includes("github-copilot") ||
+            ctx.agents.includes("agents");
+        if (!want)
+            return [];
+        const scoped = laws.filter((l) => (l.status ?? "active") !== "draft" && l.scope.length > 0);
+        return scoped.map((law) => {
+            const fm = frontmatter({ applyTo: law.scope.join(",") });
+            const body = [
+                `# ${law.title}`,
+                "",
+                `<!-- speclaw:law-id ${law.id} -->`,
+                "",
+                law.prose,
+                "",
+            ].join("\n");
+            return {
+                path: `.github/instructions/${lawSlug(law.id)}.instructions.md`,
+                contents: fm + body,
+                lawIds: [law.id],
+                mode: "write",
+            };
+        });
+    },
+};

package/dist/modules/foundation/dialects/index.js

@@ -0,0 +1,5 @@
+export { frontmatter, delimit, patchDelimited, lawSlug, commonPrefix } from "./types.js";
+export { agentsmdDialect } from "./agentsmd.js";
+export { claudeRulesDialect, cursorMdcDialect } from "./claude-cursor.js";
+export { copilotDialect } from "./copilot.js";
+export { coderabbitDialect } from "./coderabbit.js";

package/dist/modules/foundation/dialects/types.js

@@ -0,0 +1,58 @@
+/** YAML-ish frontmatter for markdown rule files. */
+export function frontmatter(fields) {
+    const lines = ["---"];
+    for (const [k, v] of Object.entries(fields)) {
+        if (Array.isArray(v)) {
+            lines.push(`${k}:`);
+            for (const item of v)
+                lines.push(`  - ${JSON.stringify(item)}`);
+        }
+        else if (typeof v === "boolean") {
+            lines.push(`${k}: ${v}`);
+        }
+        else {
+            lines.push(`${k}: ${JSON.stringify(v)}`);
+        }
+    }
+    lines.push("---", "");
+    return lines.join("\n");
+}
+/** HTML comment markers for delimited patches in personalized files. */
+export function delimit(marker, body) {
+    return `<!-- speclaw:${marker}:start -->\n${body.trim()}\n<!-- speclaw:${marker}:end -->\n`;
+}
+/**
+ * Replace or append a delimited speclaw block inside `existing` text.
+ * Preserves all content outside the markers.
+ */
+export function patchDelimited(existing, marker, body) {
+    const block = delimit(marker, body);
+    const re = new RegExp(`<!--\\s*speclaw:${marker}:start\\s-->[\\s\\S]*?<!--\\s*speclaw:${marker}:end\\s-->\\n?`, "m");
+    if (re.test(existing))
+        return existing.replace(re, block);
+    const sep = existing.endsWith("\n") || existing.length === 0 ? "" : "\n";
+    return `${existing}${sep}\n${block}`;
+}
+/** Stable filename slug from a law id (`law~foo~1` → `law-foo-1`). */
+export function lawSlug(id) {
+    return id.replace(/~/g, "-").replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+/** Longest common directory prefix of scope globs (best-effort). */
+export function commonPrefix(scopes) {
+    const dirs = scopes
+        .map((s) => s
+        .replace(/\\/g, "/")
+        .replace(/\*\*.*$/, "")
+        .replace(/\/$/, ""))
+        .filter((s) => s.length > 0 && !s.includes("*"));
+    if (dirs.length === 0)
+        return "";
+    const parts = dirs[0].split("/");
+    let i = 0;
+    for (; i < parts.length; i++) {
+        const p = parts[i];
+        if (!dirs.every((d) => d.split("/")[i] === p))
+            break;
+    }
+    return parts.slice(0, i).join("/");
+}