@ulpi/codemap 0.3.1 → 0.3.3

package/README.md

@@ -13,7 +13,7 @@ Code intelligence CLI — hybrid vector + BM25 semantic search, dependency analy
 - **Cycle detection** — find circular dependencies automatically
 - **Coupling metrics** — measure afferent/efferent coupling and instability per file
 - **Real-time watching** — incremental re-indexing on file changes
-- **MCP server** — 12 tools for AI agent integration (Claude, Cursor, VS Code, etc.)
+- **MCP server** — 12 tools for AI agent integration (Claude, Cursor, VS Code, Kiro, etc.)
 - **Per-branch indexing** — separate indexes for each git branch
 - **Multiple providers** — works with Ollama (free, local), OpenAI, or ULPI Cloud embeddings
 
@@ -154,6 +154,49 @@ codemap cycles
 codemap cycles --json
 ```
 
+### `codemap summary <file>`
+
+Show file overview with symbols and size.
+
+```bash
+codemap summary src/routes/auth.ts
+codemap summary src/index.ts --json
+```
+
+### `codemap coupling`
+
+Analyze afferent/efferent coupling and instability.
+
+```bash
+codemap coupling
+codemap coupling --module src/routes/ --limit 20
+codemap coupling --json
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--module <path>` | Filter to a directory prefix | — |
+| `-l, --limit <n>` | Max results | `50` |
+| `--json` | Output as JSON | — |
+
+### `codemap graph-stats`
+
+Show aggregate dependency graph statistics.
+
+```bash
+codemap graph-stats
+codemap graph-stats --json
+```
+
+### `codemap rebuild-depgraph`
+
+Rebuild dependency graph from scratch using tree-sitter tag extraction.
+
+```bash
+codemap rebuild-depgraph
+codemap rebuild-depgraph --json
+```
+
 ### `codemap ignore`
 
 Generate or reset `.codemapignore` with default exclusion patterns.

package/dist/index.js

@@ -4098,6 +4098,59 @@ function extractSymbolsFromChunks(chunks) {
   }
   return allSymbols;
 }
+var TAG_TYPE_MAP = {
+  class: "class",
+  function: "function",
+  method: "method",
+  interface: "interface",
+  type: "type",
+  enum: "enum",
+  module: "class",
+  trait: "interface",
+  struct: "class",
+  property: "variable",
+  constant: "const",
+  variable: "variable",
+  mixin: "class",
+  extension: "class",
+  union: "enum"
+};
+function symbolsFromTags(allTags, chunks) {
+  const chunksByFile = /* @__PURE__ */ new Map();
+  for (const chunk of chunks) {
+    let arr = chunksByFile.get(chunk.filePath);
+    if (!arr) {
+      arr = [];
+      chunksByFile.set(chunk.filePath, arr);
+    }
+    arr.push(chunk);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const symbols = [];
+  for (const [filePath, tags] of allTags) {
+    const fileChunks = chunksByFile.get(filePath);
+    for (const tag of tags) {
+      if (tag.kind !== "def") continue;
+      if (!tag.name || tag.name.length < 2) continue;
+      const symbolType = TAG_TYPE_MAP[tag.symbolType ?? ""] ?? "unknown";
+      const key = `${tag.name}:${filePath}:${tag.line}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const chunk = fileChunks?.find(
+        (c2) => tag.line >= c2.startLine && tag.line <= c2.endLine
+      );
+      symbols.push({
+        name: tag.name,
+        symbolType,
+        filePath,
+        startLine: tag.line,
+        endLine: chunk?.endLine ?? tag.line,
+        chunkId: chunk?.id ?? ""
+      });
+    }
+  }
+  return symbols;
+}
 function searchSymbols(symbols, query, topK = 20) {
   const q = query.toLowerCase();
   const results = [];
@@ -4512,11 +4565,13 @@ async function runInitPipelineInner(projectDir, config, branch, onProgress, data
   await store.dropTable();
   await embedAndStore(embedder, store, allChunks, onProgress);
   onProgress?.({ phase: "symbols", message: "Extracting symbols..." });
-  const symbols = extractSymbolsFromChunks(allChunks);
+  const regexSymbols = extractSymbolsFromChunks(allChunks);
+  const tagSymbols = allTags.size > 0 ? symbolsFromTags(allTags, allChunks) : [];
+  const symbols = mergeSymbols(regexSymbols, tagSymbols);
   saveSymbolIndex(metadataDir, symbols);
   onProgress?.({
     phase: "symbols",
-    message: `Extracted ${symbols.length} symbols`,
+    message: `Extracted ${symbols.length} symbols (${tagSymbols.length} from tags, ${regexSymbols.length} from regex)`,
     current: symbols.length,
     total: symbols.length
   });
@@ -4631,7 +4686,10 @@ async function runIncrementalInner(projectDir, config, branch, manifest, changed
     saveBM25Index(metadataDir, bm25Index);
     const allFilePaths2 = scannedFiles.map((f) => f.filePath);
     const allChunks = chunkFiles(projectDir, allFilePaths2, config.chunking);
-    const symbols = extractSymbolsFromChunks(allChunks);
+    const regexSymbols = extractSymbolsFromChunks(allChunks);
+    const allTags2 = await extractAllTags(projectDir, allFilePaths2, onProgress);
+    const tagSymbols = allTags2.size > 0 ? symbolsFromTags(allTags2, allChunks) : [];
+    const symbols = mergeSymbols(regexSymbols, tagSymbols);
     saveSymbolIndex(metadataDir, symbols);
   } else {
     const bm25Index = loadBM25Index(metadataDir);
@@ -4703,6 +4761,23 @@ function buildEmbeddingText(chunk) {
   return `${header}
 ${chunk.content}`;
 }
+function mergeSymbols(regexSymbols, tagSymbols) {
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const sym of tagSymbols) {
+    const key = `${sym.name}:${sym.filePath}:${sym.startLine}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(sym);
+  }
+  for (const sym of regexSymbols) {
+    const key = `${sym.name}:${sym.filePath}:${sym.startLine}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(sym);
+  }
+  return merged;
+}
 async function extractAllTags(projectDir, filePaths, onProgress) {
   const allTags = /* @__PURE__ */ new Map();
   try {
@@ -5000,6 +5075,7 @@ async function searchCode(projectDir, query, options) {
     const hybridConfig = config.hybrid;
     if (hybridConfig.enabled) {
       return await hybridSearch(
+        projectDir,
         store,
         metadataDir,
         queryVector,
@@ -5027,7 +5103,7 @@ async function searchCode(projectDir, query, options) {
     await store.close();
   }
 }
-async function hybridSearch(store, metadataDir, queryVector, query, weights, vectorK, bm25K, limit, threshold, pathPrefix, includeTests, includeDocs) {
+async function hybridSearch(projectDir, store, metadataDir, queryVector, query, weights, vectorK, bm25K, limit, threshold, pathPrefix, includeTests, includeDocs) {
   const vectorResults = await store.query(queryVector, vectorK);
   const bm25Index = loadBM25Index(metadataDir);
   const bm25Results = bm25Index ? queryBM25(bm25Index, query, bm25K) : [];
@@ -5051,6 +5127,7 @@ async function hybridSearch(store, metadataDir, queryVector, query, weights, vec
     weights,
     Math.max(limit * 3, 80)
   );
+  enrichBM25Candidates(projectDir, fused);
   return applyFilters(fused, limit, threshold, pathPrefix, includeTests, includeDocs);
 }
 async function vectorOnlySearch(store, queryVector, limit, threshold, pathPrefix, includeTests, includeDocs) {
@@ -5089,6 +5166,28 @@ function applyFilters(candidates, limit, threshold, pathPrefix, includeTests, in
     symbolScore: c2.symbolScore
   }));
 }
+function enrichBM25Candidates(projectDir, candidates) {
+  for (const c2 of candidates) {
+    if (c2.snippet !== "" || c2.startLine !== 0) continue;
+    const lastColon = c2.id.lastIndexOf(":");
+    if (lastColon === -1) continue;
+    const beforeHash = c2.id.slice(0, lastColon);
+    const secondLastColon = beforeHash.lastIndexOf(":");
+    if (secondLastColon === -1) continue;
+    const lineRange = beforeHash.slice(secondLastColon + 1);
+    const match = lineRange.match(/^(\d+)-(\d+)$/);
+    if (!match) continue;
+    c2.startLine = parseInt(match[1], 10);
+    c2.endLine = parseInt(match[2], 10);
+    try {
+      const absPath = path10.join(projectDir, c2.filePath);
+      const content = fs10.readFileSync(absPath, "utf-8");
+      const lines = content.split("\n");
+      c2.snippet = lines.slice(c2.startLine - 1, c2.endLine).join("\n").slice(0, 200);
+    } catch {
+    }
+  }
+}
 function loadGraphRanks(metadataDir) {
   try {
     const file = path10.join(metadataDir, "depgraph", "pagerank.json");
@@ -5793,8 +5892,64 @@ function registerInit(program2) {
     console.log(`  ${chalk3.cyan("codemap index")}    Index your project`);
     console.log(`  ${chalk3.cyan("codemap search")}   Search your code`);
     console.log(`  ${chalk3.cyan("codemap serve")}    Start MCP server`);
+    console.log();
+    printAgentSnippet();
   });
 }
+function printAgentSnippet() {
+  console.log(chalk3.bold("Add to your CLAUDE.md / agents.md / rules:"));
+  console.log(chalk3.dim("\u2500".repeat(60)));
+  console.log(`
+## Code Intelligence (codemap)
+
+This project is indexed with codemap for semantic code search,
+symbol lookup, dependency analysis, and PageRank file ranking.
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| \`mcp__codemap__search_code\` | Hybrid vector + BM25 semantic code search |
+| \`mcp__codemap__search_symbols\` | Find functions, classes, types by name |
+| \`mcp__codemap__get_file_summary\` | File overview with symbols and line count |
+| \`mcp__codemap__get_index_stats\` | Index statistics (files, chunks, size) |
+| \`mcp__codemap__get_dependencies\` | Files this file imports (outgoing) |
+| \`mcp__codemap__get_dependents\` | Files that import this file (incoming) |
+| \`mcp__codemap__get_file_rank\` | PageRank importance score |
+| \`mcp__codemap__find_cycles\` | Detect circular dependencies |
+| \`mcp__codemap__get_coupling_metrics\` | Afferent/efferent coupling analysis |
+| \`mcp__codemap__get_depgraph_stats\` | Aggregate dependency graph statistics |
+| \`mcp__codemap__reindex\` | Re-index the codebase |
+| \`mcp__codemap__rebuild_depgraph\` | Rebuild dependency graph |
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| \`codemap search <query>\` | Hybrid vector + BM25 semantic code search |
+| \`codemap symbols <query>\` | Find functions, classes, types by name |
+| \`codemap summary <file>\` | File overview with symbols and line count |
+| \`codemap status\` | Index statistics (files, chunks, size) |
+| \`codemap deps <file>\` | Files this file imports (outgoing) |
+| \`codemap dependents <file>\` | Files that import this file (incoming) |
+| \`codemap rank [file]\` | PageRank importance score |
+| \`codemap cycles\` | Detect circular dependencies |
+| \`codemap coupling\` | Afferent/efferent coupling analysis |
+| \`codemap graph-stats\` | Aggregate dependency graph statistics |
+| \`codemap index\` | Re-index the codebase |
+| \`codemap rebuild-depgraph\` | Rebuild dependency graph |
+
+### When to Use
+
+- **Before editing**: \`search_code\` or \`search_symbols\` to find relevant files
+- **Understanding impact**: \`get_dependents\` to see what breaks if you change a file
+- **Architecture review**: \`get_coupling_metrics\` and \`find_cycles\` for code health
+- **Navigation**: \`get_file_rank\` to identify the most important files
+`.trim());
+  console.log();
+  console.log(chalk3.dim("\u2500".repeat(60)));
+  console.log(chalk3.dim("Copy the above into your CLAUDE.md, .cursorrules, or agent config."));
+}
 var ULPI_API_BASE = "https://codemap.ulpi.io";
 var ULPI_AUTH_BASE = "https://codemap.ulpi.io/api/v1";
 function ask(prompt) {
@@ -6038,7 +6193,7 @@ function loadMetricsSafe(projectDir, branch) {
 function createCodemapMcpServer() {
   const server = new McpServer({
     name: "codemap",
-    version: "0.3.1"
+    version: "0.3.2"
   });
   const dataDir = getDataDir2();
   server.tool(
@@ -6609,12 +6764,212 @@ function registerIgnore(program2) {
   });
 }
 
+// src/commands/summary.ts
+import chalk13 from "chalk";
+import fs17 from "fs";
+function registerSummary(program2) {
+  program2.command("summary <file>").description("Show file overview with symbols and size").option("--json", "Output as JSON").action(async (file, opts) => {
+    const projectDir = program2.opts().cwd || process.cwd();
+    const branch = getCurrentBranch(projectDir);
+    const fullPath = `${projectDir}/${file}`;
+    if (!fs17.existsSync(fullPath)) {
+      console.error(chalk13.red(`File not found: ${file}`));
+      process.exit(1);
+      return;
+    }
+    const content = fs17.readFileSync(fullPath, "utf-8");
+    const lines = content.split("\n");
+    const metaDir = codemapMetadataDir(projectDir, branch, getDataDir2());
+    const symbolIndex = loadSymbolIndex(metaDir);
+    const fileSymbols = symbolIndex.filter((s) => s.filePath === file);
+    const result = {
+      filePath: file,
+      sizeBytes: Buffer.byteLength(content, "utf-8"),
+      lineCount: lines.length,
+      symbols: fileSymbols.map((s) => ({
+        name: s.name,
+        type: s.symbolType,
+        line: s.startLine
+      }))
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(chalk13.bold(`File Summary: ${chalk13.cyan(file)}`));
+    console.log(chalk13.dim("-".repeat(40)));
+    console.log(`Size:    ${formatBytes2(result.sizeBytes)}`);
+    console.log(`Lines:   ${result.lineCount}`);
+    console.log(`Symbols: ${result.symbols.length}`);
+    console.log();
+    if (result.symbols.length > 0) {
+      console.log(chalk13.bold("Symbols:"));
+      for (const sym of result.symbols) {
+        console.log(`  ${chalk13.dim(sym.type.padEnd(10))} ${chalk13.cyan(sym.name)} ${chalk13.dim(`L${sym.line}`)}`);
+      }
+    }
+  });
+}
+function formatBytes2(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+// src/commands/coupling.ts
+import chalk14 from "chalk";
+function registerCoupling(program2) {
+  program2.command("coupling").description("Analyze afferent/efferent coupling and instability").option("--module <path>", "Filter to a directory prefix (e.g. src/routes/)").option("-l, --limit <n>", "Max results", "50").option("--json", "Output as JSON").action(async (opts) => {
+    const projectDir = program2.opts().cwd || process.cwd();
+    const branch = getCurrentBranch(projectDir);
+    const graphFile = depgraphGraphFile(projectDir, branch, getDataDir2());
+    let graph;
+    try {
+      graph = loadGraph(graphFile);
+    } catch {
+      console.error(chalk14.red("Dependency graph not available. Run `codemap index` first."));
+      process.exit(1);
+      return;
+    }
+    let coupling = computeCoupling(graph);
+    if (opts.module) {
+      coupling = coupling.filter((c2) => c2.filePath.startsWith(opts.module));
+    }
+    coupling.sort((a, b) => b.instability - a.instability);
+    coupling = coupling.slice(0, parseInt(opts.limit, 10));
+    const results = coupling.map((c2) => ({
+      file: c2.filePath,
+      fanIn: c2.afferentCoupling,
+      fanOut: c2.efferentCoupling,
+      instability: Math.round(c2.instability * 1e3) / 1e3
+    }));
+    if (opts.json) {
+      console.log(JSON.stringify(results, null, 2));
+      return;
+    }
+    console.log(chalk14.bold("Coupling Metrics (sorted by instability)"));
+    console.log(chalk14.dim("-".repeat(60)));
+    console.log(
+      `${"File".padEnd(40)} ${"In".padStart(4)} ${"Out".padStart(4)} ${"Inst".padStart(6)}`
+    );
+    console.log(chalk14.dim("-".repeat(60)));
+    for (const r2 of results) {
+      const instColor = r2.instability >= 0.8 ? chalk14.red : r2.instability >= 0.5 ? chalk14.yellow : chalk14.green;
+      console.log(
+        `${chalk14.cyan(r2.file.slice(-38).padEnd(40))} ${String(r2.fanIn).padStart(4)} ${String(r2.fanOut).padStart(4)} ${instColor(String(r2.instability).padStart(6))}`
+      );
+    }
+  });
+}
+
+// src/commands/graph-stats.ts
+import chalk15 from "chalk";
+function registerGraphStats(program2) {
+  program2.command("graph-stats").description("Show aggregate dependency graph statistics").option("--json", "Output as JSON").action(async (opts) => {
+    const projectDir = program2.opts().cwd || process.cwd();
+    const branch = getCurrentBranch(projectDir);
+    let metrics;
+    try {
+      metrics = loadMetrics(depgraphMetricsFile(projectDir, branch, getDataDir2()));
+    } catch {
+      console.error(chalk15.red("Dependency metrics not available. Run `codemap index` first."));
+      process.exit(1);
+      return;
+    }
+    const result = {
+      totalFiles: metrics.totalFiles,
+      totalEdges: metrics.totalEdges,
+      totalDefinitions: metrics.totalDefinitions,
+      totalReferences: metrics.totalReferences,
+      cycleCount: metrics.cycles.length,
+      avgFanIn: Math.round(metrics.avgFanIn * 100) / 100,
+      avgFanOut: Math.round(metrics.avgFanOut * 100) / 100,
+      maxFanIn: metrics.maxFanIn,
+      maxFanOut: metrics.maxFanOut,
+      hotspots: metrics.hotspots.slice(0, 10).map((h) => ({
+        file: h.filePath,
+        connectivity: h.connectivity,
+        pageRank: Math.round(h.pageRank * 1e4) / 1e4
+      }))
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(chalk15.bold("Dependency Graph Statistics"));
+    console.log(chalk15.dim("-".repeat(40)));
+    console.log(`Files:        ${result.totalFiles}`);
+    console.log(`Edges:        ${result.totalEdges}`);
+    console.log(`Definitions:  ${result.totalDefinitions}`);
+    console.log(`References:   ${result.totalReferences}`);
+    console.log(`Cycles:       ${result.cycleCount}`);
+    console.log(`Avg fan-in:   ${result.avgFanIn}`);
+    console.log(`Avg fan-out:  ${result.avgFanOut}`);
+    console.log(`Max fan-in:   ${result.maxFanIn}`);
+    console.log(`Max fan-out:  ${result.maxFanOut}`);
+    if (result.hotspots.length > 0) {
+      console.log();
+      console.log(chalk15.bold("Top Hotspots:"));
+      for (const h of result.hotspots) {
+        console.log(
+          `  ${chalk15.cyan(h.file)} ${chalk15.dim(`connectivity=${h.connectivity} rank=${h.pageRank}`)}`
+        );
+      }
+    }
+  });
+}
+
+// src/commands/rebuild.ts
+import chalk16 from "chalk";
+function registerRebuild(program2) {
+  program2.command("rebuild-depgraph").description("Rebuild dependency graph from scratch using tree-sitter tag extraction").option("--json", "Output as JSON").action(async (opts) => {
+    const projectDir = program2.opts().cwd || process.cwd();
+    const config = loadCliConfig(projectDir);
+    bridgeEnvVars(config);
+    const branch = getCurrentBranch(projectDir);
+    const dataDir = getDataDir2();
+    try {
+      const result = await rebuildDepgraph(projectDir, { branch, dataDir });
+      if (result.taggedFiles === 0) {
+        console.error(chalk16.yellow("No tags extracted \u2014 check that the project contains supported language files."));
+        return;
+      }
+      if (opts.json) {
+        console.log(JSON.stringify({
+          message: "Dependency graph rebuilt",
+          totalFiles: result.nodeCount,
+          totalEdges: result.edgeCount,
+          definitions: result.definitionCount,
+          references: result.referenceCount,
+          cycleCount: result.cycleCount,
+          taggedFiles: result.taggedFiles,
+          durationMs: result.durationMs
+        }, null, 2));
+        return;
+      }
+      console.log(chalk16.green("Dependency graph rebuilt"));
+      console.log(chalk16.dim("-".repeat(40)));
+      console.log(`Tagged files: ${result.taggedFiles}/${result.totalFiles}`);
+      console.log(`Nodes:        ${result.nodeCount}`);
+      console.log(`Edges:        ${result.edgeCount}`);
+      console.log(`Definitions:  ${result.definitionCount}`);
+      console.log(`References:   ${result.referenceCount}`);
+      console.log(`Cycles:       ${result.cycleCount}`);
+      console.log(`Duration:     ${(result.durationMs / 1e3).toFixed(1)}s`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(chalk16.red(`Depgraph rebuild failed: ${msg}`));
+      process.exit(1);
+    }
+  });
+}
+
 // src/index.ts
 var __dirname = path13.dirname(fileURLToPath(import.meta.url));
 var grammarsDir = path13.join(__dirname, "grammars");
 setGrammarDir(grammarsDir);
 var program = new Command();
-program.name("codemap").description("Code intelligence CLI \u2014 hybrid search, dependency analysis, PageRank").version("0.3.1").option("--cwd <dir>", "Project directory (default: cwd)");
+program.name("codemap").description("Code intelligence CLI \u2014 hybrid search, dependency analysis, PageRank").version("0.3.3").option("--cwd <dir>", "Project directory (default: cwd)");
 registerSearch(program);
 registerSymbols(program);
 registerIndex(program);
@@ -6628,4 +6983,8 @@ registerCycles(program);
 registerConfig(program);
 registerInit(program);
 registerIgnore(program);
+registerSummary(program);
+registerCoupling(program);
+registerGraphStats(program);
+registerRebuild(program);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulpi/codemap",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "Standalone code intelligence CLI — hybrid vector + BM25 search, dependency analysis, PageRank",
   "bin": {