@ulpi/codemap 0.3.2 → 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

@@ -5892,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) {
@@ -6708,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.2").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);
@@ -6727,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.2",
+  "version": "0.3.3",
   "type": "module",
   "description": "Standalone code intelligence CLI — hybrid vector + BM25 search, dependency analysis, PageRank",
   "bin": {