@esneiderbravo/speclaw 0.3.4 → 0.3.7

package/dist/modules/compass/register.js

@@ -1,78 +1,44 @@
 import { z } from "zod";
-import { text } from "../../shared/mcp.js";
+import { defineTool, text } from "../../shared/mcp.js";
+import { shouldExpose } from "../../shared/exposure.js";
 import { buildIndex } from "./indexer.js";
 import { explore, search, recall, impact, trace } from "./query.js";
 import { startWatch, stopWatch, watchStatus } from "./watcher.js";
 import { visualize } from "./visualize.js";
 // ─── Compass: speclaw's own code-intelligence engine (no external deps) ───
-// A local graph of the codebase (nodes = definitions, edges = calls/imports)
-// plus a local vector store for semantic recall. Lives in .speclaw/ (gitignored).
 /**
- * Register all Compass MCP tools (index, explore, search, recall, impact,
- * trace, watch) on the given server.
+ * Register Compass MCP tools on the given server.
  *
- * @param server - The MCP server to register the Compass tools on.
+ * @param server - The MCP server to register on.
+ * @param opts - Exposure options (`minimal` omits setup/specialized tools).
  */
-export function registerCompass(server) {
-    server.registerTool("compass_index", {
-        description: "Build or incrementally refresh the Compass — speclaw's local code graph (.speclaw/index.db). Parses TS/JS/Python with tree-sitter into nodes (definitions) and edges (calls/imports), and computes a local vector embedding per node for semantic recall. Files unchanged since the last run are skipped by content hash. Run once after init and whenever you want a fresh graph.",
-        inputSchema: { projectPath: z.string().describe("Absolute path to the project") },
-    }, async ({ projectPath }) => text(await buildIndex(projectPath)));
-    server.registerTool("compass_explore", {
-        description: "Explore a node in the Compass: returns its verbatim source, location, callees, and resolved callers (blast radius). Use this BEFORE grep/read when locating or understanding code. Requires compass_index to have run.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            node: z.string().describe("Exact node name to explore (function/class/method/type)"),
-        },
-    }, async ({ projectPath, node }) => text(explore(projectPath, node)));
-    server.registerTool("compass_search", {
-        description: "Structural search of the Compass: find nodes by name or keyword (substring match). Returns name, kind, and file:line per hit. Cheaper and more structural than grep. Requires compass_index to have run.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            query: z.string().describe("Name or keyword to search for"),
-            limit: z.number().optional().describe("Max results (default 25)"),
-        },
-    }, async ({ projectPath, query, limit }) => text(search(projectPath, query, limit ?? 25)));
-    server.registerTool("compass_recall", {
-        description: "Semantic search of the Compass: describe what you're looking for in natural language ('where auth tokens are validated') and get the nodes ranked by meaning, using the local vector store — even when the identifier names don't contain your words. Requires compass_index to have run.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            query: z.string().describe("Natural-language description of the code you want"),
-            limit: z.number().optional().describe("Max results (default 15)"),
-        },
-    }, async ({ projectPath, query, limit }) => text(await recall(projectPath, query, limit ?? 15)));
-    server.registerTool("compass_impact", {
-        description: "Blast radius: every node that transitively calls the target, up to a depth. Answers 'what could break if I change this?' before editing. Includes dynamic-dispatch callers (matched by name). Requires compass_index.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            node: z.string().describe("Node name whose dependents you want"),
-            maxDepth: z.number().optional().describe("Max hops to traverse (default 4)"),
-        },
-    }, async ({ projectPath, node, maxDepth }) => text(impact(projectPath, node, maxDepth ?? 4)));
-    server.registerTool("compass_trace", {
-        description: "Trace a call path from one node to another: returns the chain of calls linking them (or null if none within depth). Useful to understand how an entrypoint reaches a sink. Requires compass_index.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            from: z.string().describe("Starting node name"),
-            to: z.string().describe("Target node name"),
-            maxDepth: z.number().optional().describe("Max hops to search (default 8)"),
-        },
+export function registerCompass(server, opts = {}) {
+    const minimal = Boolean(opts.minimal);
+    const add = (name, description, inputSchema, handler) => {
+        if (!shouldExpose(name, minimal))
+            return;
+        defineTool(server, { name, description, inputSchema, handler });
+    };
+    add("compass_index", "Build or refresh the local code graph index. Run once per project, then on demand.", { projectPath: z.string() }, async ({ projectPath }) => text(await buildIndex(projectPath)));
+    add("compass_explore", "Read a symbol's source plus callers and callees. Prefer this before grep or Read.", { projectPath: z.string(), node: z.string() }, async ({ projectPath, node }) => text(explore(projectPath, node)));
+    add("compass_search", "Find symbols by name or keyword (substring). Cheaper structural search than grep.", { projectPath: z.string(), query: z.string(), limit: z.number().optional() }, async ({ projectPath, query, limit }) => text(search(projectPath, query, limit ?? 25)));
+    add("compass_recall", "Find symbols by meaning via local embeddings. Use when names are unknown.", { projectPath: z.string(), query: z.string(), limit: z.number().optional() }, async ({ projectPath, query, limit }) => text(await recall(projectPath, query, limit ?? 15)));
+    add("compass_impact", "List transitive callers of a symbol (blast radius) before editing.", { projectPath: z.string(), node: z.string(), maxDepth: z.number().optional() }, async ({ projectPath, node, maxDepth }) => text(impact(projectPath, node, maxDepth ?? 4)));
+    add("compass_trace", "Find a call path between two symbols within a depth limit.", {
+        projectPath: z.string(),
+        from: z.string(),
+        to: z.string(),
+        maxDepth: z.number().optional(),
     }, async ({ projectPath, from, to, maxDepth }) => text(trace(projectPath, from, to, maxDepth ?? 8)));
-    server.registerTool("compass_visualize", {
-        description: "Generate an interactive, offline HTML visualization of the code graph into .speclaw/graph.html (gitignored). Nodes are definitions, edges are calls; drag/zoom/hover to explore. Pass a node to focus on its neighborhood, else the most-connected nodes are shown. Requires compass_index.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            node: z.string().optional().describe("Focus on this node's neighborhood (optional)"),
-            depth: z.number().optional().describe("BFS depth around the focus node (default 2)"),
-            limit: z.number().optional().describe("Max nodes for the whole-graph view (default 300)"),
-        },
+    add("compass_visualize", "Write an offline HTML graph to .speclaw/graph.html for interactive exploration.", {
+        projectPath: z.string(),
+        node: z.string().optional(),
+        depth: z.number().optional(),
+        limit: z.number().optional(),
     }, async ({ projectPath, node, depth, limit }) => text(visualize(projectPath, { focus: node, depth, limit })));
-    server.registerTool("compass_watch", {
-        description: "Keep the Compass index fresh automatically: start/stop a file watcher that incrementally re-indexes on change (debounced). action=start|stop|status. Optional — the index is also refreshed on demand by compass_index.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            action: z.enum(["start", "stop", "status"]).describe("start, stop, or status"),
-        },
+    add("compass_watch", "Start, stop, or status a debounced file watcher that re-indexes on change.", {
+        projectPath: z.string(),
+        action: z.enum(["start", "stop", "status"]),
     }, async ({ projectPath, action }) => {
         const result = action === "start"
             ? startWatch(projectPath)

package/dist/modules/foundation/assets/docs/compass.template.md

@@ -42,6 +42,9 @@ a missing graph is not license to skip Compass. The only legitimate fallbacks
 to Grep/Read: a Compass call returned nothing useful for your query, or the
 target isn't indexed code (stylesheets, JSON/config, markdown, logs).
 
+<!-- speclaw:map:start -->
+<!-- speclaw:map:end -->
+
 ## Project-specific starting points
 
 <!-- Filled in during speclaw init: the project's real entrypoints, core

package/dist/modules/foundation/context-budget.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { registerCompass } from "../compass/register.js";
+import { registerSpec } from "../lawbook/register.js";
+import { registerTools } from "../tools/register.js";
+import { registerFoundationCore } from "./register-core.js";
+import { measureBudget } from "../../shared/budget.js";
+import { isMinimalMode, packageRoot, shouldExpose } from "../../shared/exposure.js";
+/** Mirrors the `doctor` tool surface without importing `doctor.ts` (avoids a cycle). */
+const DOCTOR_TOOL_FOR_BUDGET = {
+    name: "doctor",
+    description: "Verify the speclaw install; returns a versioned DoctorReport (schemaVersion 1).",
+    inputSchema: { projectPath: z.string() },
+};
+/**
+ * Collect tool definitions as the MCP server would register them for a profile.
+ *
+ * Uses `registerFoundationCore` plus a static `doctor` stub so budget/doctor
+ * measurement never imports the live `doctor` implementation (module cycle).
+ *
+ * @param minimal - Exposure profile.
+ */
+export function collectRegisteredTools(minimal) {
+    const tools = [];
+    const server = {
+        registerTool(name, config) {
+            tools.push({
+                name,
+                description: config.description ?? "",
+                inputSchema: config.inputSchema,
+            });
+        },
+    };
+    const opts = { minimal };
+    const stub = server;
+    registerFoundationCore(stub, opts);
+    if (shouldExpose("doctor", minimal)) {
+        tools.push(DOCTOR_TOOL_FOR_BUDGET);
+    }
+    registerSpec(stub, opts);
+    registerCompass(stub, opts);
+    registerTools(stub, opts);
+    return tools;
+}
+/**
+ * Measure context budget for an install (registered tools + project files).
+ *
+ * @param projectPath - Project root.
+ * @param minimal - Optional forced profile.
+ */
+export function measureInstallBudget(projectPath, minimal) {
+    const profile = minimal ?? isMinimalMode(projectPath);
+    return measureBudget({
+        projectPath,
+        packagePath: packageRoot(),
+        tools: collectRegisteredTools(profile),
+        minimal: profile,
+    });
+}