@zuvia-software-solutions/code-mapper 1.4.0

package/README.md

@@ -0,0 +1,215 @@
+# Code Mapper
+
+**Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
+
+Works with **Cursor**, **Claude Code**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
+
+[![npm version](https://img.shields.io/npm/v/code-mapper.svg)](https://www.npmjs.com/package/code-mapper)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+
+---
+
+## Why?
+
+AI coding tools don't understand your codebase structure. They edit a function without knowing 47 other functions depend on it. Code Mapper fixes this by **precomputing every dependency, call chain, and relationship** into a queryable graph.
+
+**Three commands to give your AI agent full codebase awareness.**
+
+## Quick Start
+
+```bash
+# Index your repo (run from repo root)
+npx code-mapper analyze
+```
+
+That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command.
+
+To configure MCP for your editor, run `npx code-mapper setup` once — or set it up manually below.
+
+`code-mapper setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
+
+### Editor Support
+
+| Editor | MCP | Skills | Hooks (auto-augment) | Support |
+|--------|-----|--------|---------------------|---------|
+| **Claude Code** | Yes | Yes | Yes (PreToolUse) | **Full** |
+| **Cursor** | Yes | Yes | — | MCP + Skills |
+| **Windsurf** | Yes | — | — | MCP |
+| **OpenCode** | Yes | Yes | — | MCP + Skills |
+
+> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context.
+
+### Community Integrations
+
+| Agent | Install | Source |
+|-------|---------|--------|
+| [pi](https://pi.dev) | `pi install npm:pi-code-mapper` | [pi-code-mapper](https://github.com/tintinweb/pi-code-mapper) |
+
+## MCP Setup (manual)
+
+If you prefer to configure manually instead of using `code-mapper setup`:
+
+### Claude Code (full support — MCP + skills + hooks)
+
+```bash
+claude mcp add code-mapper -- npx -y code-mapper@latest mcp
+```
+
+### Cursor / Windsurf
+
+Add to `~/.cursor/mcp.json` (global — works for all projects):
+
+```json
+{
+  "mcpServers": {
+    "code-mapper": {
+      "command": "npx",
+      "args": ["-y", "code-mapper@latest", "mcp"]
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add to `~/.config/opencode/config.json`:
+
+```json
+{
+  "mcp": {
+    "code-mapper": {
+      "command": "npx",
+      "args": ["-y", "code-mapper@latest", "mcp"]
+    }
+  }
+}
+```
+
+## How It Works
+
+Code Mapper builds a complete knowledge graph of your codebase through a multi-phase indexing pipeline:
+
+1. **Structure** — Walks the file tree and maps folder/file relationships
+2. **Parsing** — Extracts functions, classes, methods, and interfaces using Tree-sitter ASTs
+3. **Resolution** — Resolves imports and function calls across files with language-aware logic
+4. **Clustering** — Groups related symbols into functional communities
+5. **Processes** — Traces execution flows from entry points through call chains
+6. **Search** — Builds hybrid search indexes for fast retrieval
+
+The result is a **LadybugDB graph database** stored locally in `.code-mapper/` with full-text search and semantic embeddings.
+
+## MCP Tools
+
+Your AI agent gets these tools automatically:
+
+| Tool | What It Does | `repo` Param |
+|------|-------------|--------------|
+| `list_repos` | Discover all indexed repositories | — |
+| `query` | Process-grouped hybrid search (BM25 + semantic + RRF) | Optional |
+| `context` | 360-degree symbol view — categorized refs, process participation | Optional |
+| `impact` | Blast radius analysis with depth grouping and confidence | Optional |
+| `detect_changes` | Git-diff impact — maps changed lines to affected processes | Optional |
+| `rename` | Multi-file coordinated rename with graph + text search | Optional |
+| `cypher` | Raw Cypher graph queries | Optional |
+
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({query: "auth", repo: "my-app"})`.
+
+## MCP Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `code-mapper://repos` | List all indexed repositories (read first) |
+| `code-mapper://repo/{name}/context` | Codebase stats, staleness check, and available tools |
+| `code-mapper://repo/{name}/clusters` | All functional clusters with cohesion scores |
+| `code-mapper://repo/{name}/cluster/{name}` | Cluster members and details |
+| `code-mapper://repo/{name}/processes` | All execution flows |
+| `code-mapper://repo/{name}/process/{name}` | Full process trace with steps |
+| `code-mapper://repo/{name}/schema` | Graph schema for Cypher queries |
+
+## MCP Prompts
+
+| Prompt | What It Does |
+|--------|-------------|
+| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level |
+| `generate_map` | Architecture documentation from the knowledge graph with mermaid diagrams |
+
+## CLI Commands
+
+```bash
+code-mapper setup                    # Configure MCP for your editors (one-time)
+code-mapper analyze [path]           # Index a repository (or update stale index)
+code-mapper analyze --force          # Force full re-index
+code-mapper analyze --embeddings     # Enable embedding generation (slower, better search)
+code-mapper analyze --verbose        # Log skipped files when parsers are unavailable
+code-mapper mcp                     # Start MCP server (stdio) — serves all indexed repos
+code-mapper serve                   # Start local HTTP server (multi-repo) for web UI
+code-mapper list                    # List all indexed repositories
+code-mapper status                  # Show index status for current repo
+code-mapper clean                   # Delete index for current repo
+code-mapper clean --all --force     # Delete all indexes
+code-mapper wiki [path]             # Generate LLM-powered docs from knowledge graph
+code-mapper wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
+```
+
+## Multi-Repo Support
+
+Code Mapper supports indexing multiple repositories. Each `code-mapper analyze` registers the repo in a global registry (`~/.code-mapper/registry.json`). The MCP server serves all indexed repos automatically.
+
+## Supported Languages
+
+TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift, Ruby
+
+### Language Feature Matrix
+
+| Language | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points |
+|----------|---------|----------------|---------|----------|-----------------|---------------------|--------|------------|-------------|
+| TypeScript | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| JavaScript | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ |
+| Python | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Java | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| Kotlin | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| C# | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Go | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Rust | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| PHP | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Ruby | ✓ | — | ✓ | ✓ | — | ✓ | — | ✓ | ✓ |
+| Swift | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| C | — | — | ✓ | — | ✓ | ✓ | — | ✓ | ✓ |
+| C++ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+
+**Imports** — cross-file import resolution · **Named Bindings** — `import { X as Y }` / re-export tracking · **Exports** — public/exported symbol detection · **Heritage** — class inheritance, interfaces, mixins · **Type Annotations** — explicit type extraction for receiver resolution · **Constructor Inference** — infer receiver type from constructor calls (`self`/`this` resolution included for all languages) · **Config** — language toolchain config parsing (tsconfig, go.mod, etc.) · **Frameworks** — AST-based framework pattern detection · **Entry Points** — entry point scoring heuristics
+
+## Agent Skills
+
+Code Mapper ships with skill files that teach AI agents how to use the tools effectively:
+
+- **Exploring** — Navigate unfamiliar code using the knowledge graph
+- **Debugging** — Trace bugs through call chains
+- **Impact Analysis** — Analyze blast radius before changes
+- **Refactoring** — Plan safe refactors using dependency mapping
+
+Installed automatically by both `code-mapper analyze` (per-repo) and `code-mapper setup` (global).
+
+## Requirements
+
+- Node.js >= 18
+- Git repository (uses git for commit tracking)
+
+## Privacy
+
+- All processing happens locally on your machine
+- No code is sent to any server
+- Index stored in `.code-mapper/` inside your repo (gitignored)
+- Global registry at `~/.code-mapper/` stores only paths and metadata
+
+## Web UI
+
+Code Mapper also has a browser-based UI at [code-mapper.vercel.app](https://code-mapper.vercel.app) — 100% client-side, your code never leaves the browser.
+
+**Local Backend Mode:** Run `code-mapper serve` and open the web UI locally — it auto-detects the server and shows all your indexed repos, with full AI chat support. No need to re-upload or re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.
+
+## License
+
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+
+Free for non-commercial use. Contact for commercial licensing.

package/dist/cli/ai-context.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file AI context generator — creates AGENTS.md and CLAUDE.md with inline Code Mapper context
+ * @description AGENTS.md is read by Cursor, Windsurf, OpenCode, Cline etc; CLAUDE.md is for Claude Code
+ */
+interface RepoStats {
+    files?: number;
+    nodes?: number;
+    edges?: number;
+    communities?: number;
+    clusters?: number;
+    processes?: number;
+}
+/**
+ * Generate AI context files after indexing
+ */
+export declare function generateAIContextFiles(repoPath: string, _storagePath: string, projectName: string, stats: RepoStats): Promise<{
+    files: string[];
+}>;
+export {};

package/dist/cli/ai-context.js

@@ -0,0 +1,168 @@
+// code-mapper/src/cli/ai-context.ts
+/**
+ * @file AI context generator — creates AGENTS.md and CLAUDE.md with inline Code Mapper context
+ * @description AGENTS.md is read by Cursor, Windsurf, OpenCode, Cline etc; CLAUDE.md is for Claude Code
+ */
+import fs from 'fs/promises';
+import path from 'path';
+const CODE_MAPPER_START_MARKER = '<!-- code-mapper:start -->';
+const CODE_MAPPER_END_MARKER = '<!-- code-mapper:end -->';
+/**
+ * Generate the full Code Mapper context content.
+ *
+ * Design principles:
+ * - Use RFC 2119 language (MUST, NEVER, ALWAYS) — models follow imperative rules
+ * - Three-tier boundaries (Always/When/Never) — proven to change model behavior
+ * - Keep under 120 lines — adherence degrades past 150 lines
+ * - Exact tool commands with parameters — vague directives get ignored
+ * - Self-review checklist — forces model to verify its own work
+ */
+function generateCodeMapperContent(projectName, stats) {
+    return `${CODE_MAPPER_START_MARKER}
+# Code Mapper — Code Intelligence
+
+This project is indexed by Code Mapper as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows). Use the Code Mapper MCP tools to understand code, assess impact, and navigate safely.
+
+> If any Code Mapper tool warns the index is stale, run \`npx code-mapper analyze\` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`code-mapper_impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run \`code-mapper_detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use \`code-mapper_query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`code-mapper_context({name: "symbolName"})\`.
+
+## When Debugging
+
+1. \`code-mapper_query({query: "<error or symptom>"})\` — find execution flows related to the issue
+2. \`code-mapper_context({name: "<suspect function>"})\` — see all callers, callees, and process participation
+3. \`READ code-mapper://repo/${projectName}/process/{processName}\` — trace the full execution flow step by step
+4. For regressions: \`code-mapper_detect_changes({scope: "compare", base_ref: "main"})\` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use \`code-mapper_rename({symbol_name: "old", new_name: "new", dry_run: true})\` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with \`dry_run: false\`.
+- **Extracting/Splitting**: MUST run \`code-mapper_context({name: "target"})\` to see all incoming/outgoing refs, then \`code-mapper_impact({target: "target", direction: "upstream"})\` to find all external callers before moving code.
+- After any refactor: run \`code-mapper_detect_changes({scope: "all"})\` to verify only expected files changed.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running \`code-mapper_impact\` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use \`code-mapper_rename\` which understands the call graph.
+- NEVER commit changes without running \`code-mapper_detect_changes()\` to check affected scope.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| \`query\` | Find code by concept | \`code-mapper_query({query: "auth validation"})\` |
+| \`context\` | 360-degree view of one symbol | \`code-mapper_context({name: "validateUser"})\` |
+| \`impact\` | Blast radius before editing | \`code-mapper_impact({target: "X", direction: "upstream"})\` |
+| \`detect_changes\` | Pre-commit scope check | \`code-mapper_detect_changes({scope: "staged"})\` |
+| \`rename\` | Safe multi-file rename | \`code-mapper_rename({symbol_name: "old", new_name: "new", dry_run: true})\` |
+| \`cypher\` | Custom graph queries | \`code-mapper_cypher({query: "MATCH ..."})\` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| \`code-mapper://repo/${projectName}/context\` | Codebase overview, check index freshness |
+| \`code-mapper://repo/${projectName}/clusters\` | All functional areas |
+| \`code-mapper://repo/${projectName}/processes\` | All execution flows |
+| \`code-mapper://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. \`code-mapper_impact\` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. \`code-mapper_detect_changes()\` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## Keeping the Index Fresh
+
+After committing code changes, the Code Mapper index becomes stale. Re-run analyze to update it:
+
+\`\`\`bash
+npx code-mapper analyze
+\`\`\`
+
+If the index previously included embeddings, preserve them by adding \`--embeddings\`:
+
+\`\`\`bash
+npx code-mapper analyze --embeddings
+\`\`\`
+
+To check whether embeddings exist, inspect \`.code-mapper/meta.json\` — the \`stats.embeddings\` field shows the count (0 means no embeddings). **Running analyze without \`--embeddings\` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after \`git commit\` and \`git merge\`.
+
+${CODE_MAPPER_END_MARKER}`;
+}
+/**
+ * Check if a file exists
+ */
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create or update Code Mapper section in a file
+ * - If file doesn't exist: create with Code Mapper content
+ * - If file exists without Code Mapper section: append
+ * - If file exists with Code Mapper section: replace that section
+ */
+async function upsertCodeMapperSection(filePath, content) {
+    const exists = await fileExists(filePath);
+    if (!exists) {
+        await fs.writeFile(filePath, content, 'utf-8');
+        return 'created';
+    }
+    const existingContent = await fs.readFile(filePath, 'utf-8');
+    // Check if Code Mapper section already exists
+    const startIdx = existingContent.indexOf(CODE_MAPPER_START_MARKER);
+    const endIdx = existingContent.indexOf(CODE_MAPPER_END_MARKER);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        // Replace existing section
+        const before = existingContent.substring(0, startIdx);
+        const after = existingContent.substring(endIdx + CODE_MAPPER_END_MARKER.length);
+        const newContent = before + content + after;
+        await fs.writeFile(filePath, newContent.trim() + '\n', 'utf-8');
+        return 'updated';
+    }
+    // Append new section
+    const newContent = existingContent.trim() + '\n\n' + content + '\n';
+    await fs.writeFile(filePath, newContent, 'utf-8');
+    return 'appended';
+}
+/**
+ * Generate AI context files after indexing
+ */
+export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats) {
+    const content = generateCodeMapperContent(projectName, stats);
+    const createdFiles = [];
+    // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Cline, etc.)
+    const agentsPath = path.join(repoPath, 'AGENTS.md');
+    const agentsResult = await upsertCodeMapperSection(agentsPath, content);
+    createdFiles.push(`AGENTS.md (${agentsResult})`);
+    // Create CLAUDE.md (for Claude Code)
+    const claudePath = path.join(repoPath, 'CLAUDE.md');
+    const claudeResult = await upsertCodeMapperSection(claudePath, content);
+    createdFiles.push(`CLAUDE.md (${claudeResult})`);
+    return { files: createdFiles };
+}

package/dist/cli/analyze.d.ts

@@ -0,0 +1,7 @@
+/** @file analyze.ts @description Indexes a repository, builds the knowledge graph, and stores it in .code-mapper/ */
+export interface AnalyzeOptions {
+    force?: boolean;
+    embeddings?: boolean;
+    verbose?: boolean;
+}
+export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;