@ctxo/cli 0.0.1 → 0.7.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alper Hankendi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/@ctxo/cli.svg)](https://www.npmjs.com/package/@ctxo/cli)
+[![CI](https://github.com/alperhankendi/Ctxo/actions/workflows/ci.yml/badge.svg)](https://github.com/alperhankendi/Ctxo/actions/workflows/ci.yml)
+[![Release](https://github.com/alperhankendi/Ctxo/actions/workflows/release.yml/badge.svg)](https://github.com/alperhankendi/Ctxo/actions/workflows/release.yml)
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/hero-svg.svg">
+  <source media="(prefers-color-scheme: light)" srcset="docs/img/hero-svg.svg">
+  <img alt="Ctxo — Code intelligence for AI agents" src="docs/img/hero-svg.svg" width="100%">
+</picture>
+
+</div>
+
+***
+
+### The Problem
+
+AI coding assistants like Copilot, Claude Code, and Cursor rely on generic tools  `grep`, `find`, file reads to understand your codebase. On brownfield projects with thousands of files, this brute-force exploration creates a chain of problems:
+
+* **Context window saturation** The agent fills its window reading files one by one, leaving little room for actual reasoning
+* **Partial context hallucination** It sees a function but misses its dependencies, leading to wrong assumptions and broken suggestions
+* **Lost-in-the-middle** Critical information buried deep in a long context gets ignored by the model
+* **Context poisoning** Irrelevant code pulled in during exploration biases the model's output
+* **Iteration overhead** Understanding one symbol takes 10-20 tool calls, each adding more noise to the context
+* **Stale reasoning** After too many iterations, the agent contradicts its own earlier assumptions
+
+The result: more tokens burned, slower responses, higher cost, and lower quality output.
+
+### The Solution
+
+Ctxo is an **MCP server** that **enhances** your existing AI tools with dependency-aware, history-enriched code intelligence. Instead of hundreds of `grep` and `read_file` calls, your agent gets the full picture symbol graphs, blast radius, git intent, and risk scores in a **single MCP call**.
+
+* **Clean context** Only relevant symbols and their transitive dependencies, nothing more
+* **Fewer iterations** One call replaces an entire exploration cycle
+* **Higher quality** The agent reasons over structured, complete context instead of fragmented file reads
+
+> A senior developer takes \~10 minutes to gather context across files. Ctxo delivers that same context in **under 500ms**.
+
+## Quick Start
+
+Install the CLI, then run the setup wizard:
+
+```Shell
+npm i -g @ctxo/cli
+ctxo init
+```
+
+That's it. The interactive wizard detects your AI tools, registers the ctxo MCP server in the correct config file (`.mcp.json`, `.vscode/mcp.json`, etc.), generates usage rules so your assistant knows when to call each tool, and prompts to install language plugins it detects in your project (pass `--no-install` to skip).
+
+### Language Plugins
+
+As of v0.7, Ctxo discovers language support from npm packages listed in your project's `package.json`. Three official plugins ship today:
+
+```Shell
+npm i -D @ctxo/lang-typescript @ctxo/lang-go @ctxo/lang-csharp
+```
+
+Or install one at a time with the CLI shortcut: `ctxo install typescript` (supports `--yes`, `--global`, `--dry-run`, `--pm`, `--version`). Any package named `@ctxo/lang-*` or `ctxo-lang-*` in your dependencies is auto-loaded.
+
+<details>
+<summary>Manual MCP config (if not using <code>ctxo init</code>)</summary>
+
+**Claude Code / Cursor / Windsurf / Augment / Antigravity** — `.mcp.json`:
+
+```JSON
+{ "mcpServers": { "ctxo": { "command": "npx", "args": ["-y", "@ctxo/cli"] } } }
+```
+
+**VS Code (Copilot)** — `.vscode/mcp.json`:
+
+```JSON
+{ "servers": { "ctxo": { "type": "stdio", "command": "npx", "args": ["-y", "@ctxo/cli"] } } }
+```
+
+**Amazon Q** — `.amazonq/mcp.json`:
+
+```JSON
+{ "mcpServers": { "ctxo": { "command": "npx", "args": ["-y", "@ctxo/cli"] } } }
+```
+
+**Zed** — `settings.json`:
+
+```JSON
+{ "context_servers": { "ctxo": { "command": { "path": "npx", "args": ["-y", "@ctxo/cli"] } } } }
+```
+
+</details>
+
+## 14 Tools
+
+| Tool                        | What it does                                                                             |
+| --------------------------- | ---------------------------------------------------------------------------------------- |
+| `get_logic_slice`           | Symbol + transitive dependencies (L1-L4 progressive detail)                              |
+| `get_blast_radius`          | What breaks if this changes (3-tier: confirmed/likely/potential)                         |
+| `get_architectural_overlay` | Project layer map (Domain/Infrastructure/Adapter)                                        |
+| `get_why_context`           | Git commit intent + anti-pattern warnings (reverts, rollbacks)                           |
+| `get_change_intelligence`   | Complexity x churn composite score                                                       |
+| `find_dead_code`            | Unreachable symbols, unused exports, scaffolding markers                                 |
+| `get_context_for_task`      | Task-optimized context (fix/extend/refactor/understand)                                  |
+| `get_ranked_context`        | Two-phase BM25 search (camelCase-aware, fuzzy correction) + PageRank within token budget |
+| `search_symbols`            | Symbol name/regex search across index (`mode: 'fts'` for BM25)                           |
+| `get_changed_symbols`       | Symbols in recently changed files (git diff)                                             |
+| `find_importers`            | Reverse dependency lookup ("who uses this?")                                             |
+| `get_class_hierarchy`       | Class inheritance tree (ancestors + descendants)                                         |
+| `get_symbol_importance`     | PageRank centrality ranking                                                              |
+| `get_pr_impact`             | Full PR risk assessment in a single call                                                 |
+
+## Tool Selection Guide
+
+```
+Reviewing a PR?           → get_pr_impact
+About to modify code?     → get_blast_radius → get_why_context
+Understanding a symbol?   → get_context_for_task(taskType: "understand")
+Fixing a bug?             → get_context_for_task(taskType: "fix")
+Refactoring?              → get_context_for_task(taskType: "refactor")
+Don't know the name?      → search_symbols or get_ranked_context
+Finding unused code?      → find_dead_code
+Safe to delete?           → find_importers
+Onboarding?               → get_architectural_overlay → get_symbol_importance
+```
+
+## CLI Commands
+
+```Shell
+# Setup
+ctxo init                                  # Interactive setup (detects languages, prompts to install plugins, writes AI tool rules, git hooks)
+ctxo init --tools claude-code,cursor -y    # Non-interactive setup
+ctxo init --no-install                     # Skip plugin install prompt
+ctxo init --rules                          # Regenerate AI tool rules only
+ctxo init --dry-run                        # Preview what would be created
+
+# Plugins (v0.7+)
+ctxo install                               # Install plugins for all detected languages
+ctxo install typescript go csharp          # Install specific plugins
+ctxo install typescript --yes --pm pnpm    # CI-friendly, pick package manager
+ctxo install typescript --global --version 0.7.0  # Pin version, install globally
+
+# Indexing
+ctxo index                                 # Build full codebase index
+ctxo index --install-missing               # Auto-install any missing plugins first
+ctxo index --check                         # CI gate: fail if index stale
+ctxo index --skip-history                  # Fast re-index without git history
+ctxo watch                                 # File watcher for incremental re-index
+ctxo sync                                  # Rebuild SQLite cache from committed JSON
+
+# Diagnostics
+ctxo status                                # Show index manifest
+ctxo doctor                                # Health check all subsystems (--json, --quiet)
+ctxo doctor --fix                          # Dependency-ordered auto-remediation (--dry-run, --yes)
+ctxo stats                                 # Show usage statistics (--json, --days N, --clear)
+ctxo --version                             # Print CLI version (--verbose, --json)
+ctxo version                               # Verbose version subcommand (CLI + plugins + runtime)
+```
+
+**Example output:**
+
+```
+ctxo stats
+
+  Usage Summary (all time)
+  ────────────────────────────────────────
+  Total tool calls:      30
+  Total tokens served:   26.0K
+
+  Top Tools
+  ────────────────────────────────────────
+  get_logic_slice         14 calls      avg 352 tokens
+  get_blast_radius        3 calls       avg 1,279 tokens
+  get_ranked_context      3 calls       avg 898 tokens
+  find_importers          2 calls       avg 1,342 tokens
+  get_context_for_task    2 calls       avg 740 tokens
+
+  Top Queried Symbols
+  ────────────────────────────────────────
+  SymbolNode                      15 queries
+  LogicSliceQuery                 4 queries
+  SqliteStorageAdapter            2 queries
+
+  Detail Level Distribution
+  ────────────────────────────────────────
+  L1: ███░░░░░░░   25%
+  L2: ███░░░░░░░   25%
+  L3: ███░░░░░░░   25%
+  L4: ███░░░░░░░   25%
+```
+
+## CI Integration
+
+Keep the committed `.ctxo/index/` in sync with the source tree by failing PRs when the index is stale. Drop-in examples:
+
+- GitHub Actions: [examples/github-actions/ctxo-check.yml](examples/github-actions/ctxo-check.yml)
+- GitLab CI: [examples/gitlab-ci/.gitlab-ci.yml](examples/gitlab-ci/.gitlab-ci.yml)
+
+Both run `ctxo index --check` on every PR/MR. If the index is stale, the job fails and the author runs `ctxo index` locally, then commits the refreshed index. Combined with the `post-commit` hook from `ctxo init`, this keeps the index current without any webhook infrastructure.
+
+## Features
+
+**Response Envelope** All responses include `_meta` with item counts, truncation info, and drill-in hints. Large results auto-truncated at 8KB (configurable via `CTXO_RESPONSE_LIMIT`).
+
+**Intent Filtering** 4 tools accept `intent` parameter for keyword-based result filtering. `get_blast_radius(symbolId, intent: "test")` returns only test-related impacts.
+
+**Tool Annotations** All tools declare `readOnlyHint: true`, `idempotentHint: true`, `openWorldHint: false` for safe auto-approval in agent frameworks.
+
+**Privacy Masking** AWS keys, GCP service accounts, Azure connection strings, JWTs, private IPs, env secrets automatically redacted. Extensible via `.ctxo/masking.json`.
+
+**Interactive Graph** `ctxo visualize` generates a self-contained HTML with vis.js dependency graph. ForceAtlas2 layout, PageRank-based sizing, layer coloring, blast radius on click, git history per symbol, dead code and anti-pattern filters, dark/light theme.
+
+**Debug Mode** `DEBUG=ctxo:*` for all debug output, or `DEBUG=ctxo:git,ctxo:storage` for specific namespaces.
+
+**Per-tool savings vs manual approach:**
+
+```
+                        Manual Tokens   Ctxo Tokens   Savings
+get_logic_slice         ████████ 1,950  █ 150         92%
+get_blast_radius        ███ 800         ██ 600        25%
+get_overlay             ████████████ 25K██ 500        98%
+get_why_context         █ 200           █ 200          0%
+get_change_intelligence ████████ 2,100  ▏ 50          98%
+find_dead_code          █████████ 5,000 ████ 2,000    60%
+────────────────────────────────────────────────────────────
+TOTAL                   35,050 tokens   3,500 tokens  90%
+                        329+ calls      6 calls       98%
+```
+
+## Agentic AI Usage
+
+**Claude Agent SDK:**
+
+```TypeScript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+for await (const message of query({
+  prompt: "Analyze the blast radius of AuthService",
+  options: {
+    mcpServers: { ctxo: { command: "npx", args: ["-y", "@ctxo/cli"] } },
+    allowedTools: ["mcp__ctxo__*"]
+  }
+})) { /* ... */ }
+```
+
+**OpenAI Agents SDK:**
+
+```Python
+from agents import Agent, Runner
+from agents.mcp import MCPServerStdio
+
+async with MCPServerStdio(params={"command": "npx", "args": ["@ctxo/cli"]}) as ctxo:
+    agent = Agent(name="Reviewer", mcp_servers=[ctxo])
+    result = await Runner.run(agent, "Review the PR impact")
+```
+
+See [Agentic AI Integration Guide](docs/agentic-ai-integration.md) for LangChain, raw MCP client, and CI/CD examples.
+
+## Multi-Language Support
+
+Language support ships as standalone plugins. Install only what your repo needs.
+
+| Language              | Plugin Package        | Parser      | Tier   | Features                                                         |
+| --------------------- | --------------------- | ----------- | ------ | ---------------------------------------------------------------- |
+| TypeScript/JavaScript | `@ctxo/lang-typescript` | ts-morph    | Full   | Type-aware resolution, cross-file imports, `this.method()` calls |
+| Go                    | `@ctxo/lang-go`         | tree-sitter | Syntax | Structs, interfaces, functions, methods, import edges            |
+| C#                    | `@ctxo/lang-csharp`     | tree-sitter | Syntax | Classes, interfaces, methods, enums, namespace qualification     |
+
+Third-party plugins are supported via the `@ctxo/plugin-api` protocol (v1). Any package named `@ctxo/lang-*` or `ctxo-lang-*` declared in your project dependencies is auto-discovered.
+
+## Index Visualizer
+
+Ctxo ships with an interactive visualizer that renders your codebase index as a dependency graph. Explore symbols, edges, layers, and PageRank scores visually deployed automatically to GitHub Pages on every push.
+
+![1.00](docs/img/ui.png)
+
+[Open Live Visualizer](https://alperhankendi.github.io/Ctxo/ctxo-visualizer.html)
+
+## How It Works
+
+<img src="docs/img/mcp-server.png" alt="Ctxo MCP Server Architecture" width="400">
+
+Ctxo builds a **committed JSON index** (`.ctxo/index/`) that captures symbols, dependency edges, git history, and co-change data. The MCP server reads this index to answer queries no runtime parsing, no external services.
+
+The codebase is a pnpm monorepo with 5 packages: `@ctxo/cli` (this package), `@ctxo/plugin-api` (plugin protocol v1), and three official language plugins (`@ctxo/lang-typescript`, `@ctxo/lang-go`, `@ctxo/lang-csharp`).
+
+```
+.ctxo/
+  index/          ← committed (per-file JSON, reviewable in PRs)
+  .cache/         ← gitignored (local SQLite, auto-rebuilt)
+  config.yaml     ← committed (team settings)
+  masking.json    ← committed (custom masking patterns)
+```
+
+## Links
+
+* [npm](https://www.npmjs.com/package/@ctxo/cli)
+* [Changelog](CHANGELOG.md)
+* [LLM Reference](llms-full.txt)
+* [MCP Validation Runbook](docs/runbook/mcp-validation/mcp-validation.md)
+* [CLI Validation Runbook](docs/runbook/cli-validation/cli-validation.md)
+* [Architecture](docs/artifacts/architecture.md)
+* [PRD](docs/artifacts/prd.md)
+
+## License
+
+MIT

package/dist/chunk-7OCVIDC7.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export {
+  __require
+};
+//# sourceMappingURL=chunk-7OCVIDC7.js.map

package/dist/chunk-7OCVIDC7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-I4TUA7CD.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+// src/adapters/storage/json-index-reader.ts
+import { readFileSync, readdirSync, existsSync, realpathSync } from "fs";
+import { join, relative } from "path";
+
+// src/core/types.ts
+import { z } from "zod";
+var SYMBOL_KINDS = [
+  "function",
+  "class",
+  "interface",
+  "method",
+  "variable",
+  "type"
+];
+var SymbolKindSchema = z.enum(SYMBOL_KINDS);
+var EDGE_KINDS = [
+  "imports",
+  "calls",
+  "extends",
+  "implements",
+  "uses"
+];
+var EdgeKindSchema = z.enum(EDGE_KINDS);
+var DetailLevelSchema = z.union([
+  z.literal(1),
+  z.literal(2),
+  z.literal(3),
+  z.literal(4)
+]);
+var SymbolIdSchema = z.string().min(1).refine(
+  (value) => {
+    const parts = value.split("::");
+    if (parts.length !== 3) return false;
+    const [file, name, kind] = parts;
+    if (!file || !name || !kind) return false;
+    return SymbolKindSchema.safeParse(kind).success;
+  },
+  { message: 'Symbol ID must match format "<file>::<name>::<kind>"' }
+);
+var SymbolNodeSchema = z.object({
+  symbolId: SymbolIdSchema,
+  name: z.string().min(1),
+  kind: SymbolKindSchema,
+  startLine: z.number().int().nonnegative(),
+  endLine: z.number().int().nonnegative(),
+  startOffset: z.number().int().nonnegative().optional(),
+  endOffset: z.number().int().nonnegative().optional()
+}).refine((node) => node.endLine >= node.startLine, {
+  message: "endLine must be >= startLine"
+});
+var GraphEdgeSchema = z.object({
+  from: SymbolIdSchema,
+  to: SymbolIdSchema,
+  kind: EdgeKindSchema,
+  typeOnly: z.boolean().optional()
+});
+var CommitIntentSchema = z.object({
+  hash: z.string().min(1),
+  message: z.string(),
+  date: z.string().min(1),
+  kind: z.literal("commit")
+});
+var AntiPatternSchema = z.object({
+  hash: z.string().min(1),
+  message: z.string(),
+  date: z.string().min(1)
+});
+var ComplexityMetricsSchema = z.object({
+  symbolId: z.string().min(1),
+  cyclomatic: z.number().nonnegative()
+});
+var FileIndexSchema = z.object({
+  file: z.string().min(1),
+  lastModified: z.number().nonnegative(),
+  contentHash: z.string().optional(),
+  symbols: z.array(SymbolNodeSchema),
+  edges: z.array(GraphEdgeSchema),
+  complexity: z.array(ComplexityMetricsSchema).optional(),
+  intent: z.array(CommitIntentSchema),
+  antiPatterns: z.array(AntiPatternSchema)
+});
+
+// src/adapters/storage/json-index-reader.ts
+var JsonIndexReader = class {
+  indexDir;
+  constructor(ctxoRoot) {
+    this.indexDir = join(ctxoRoot, "index");
+  }
+  readAll() {
+    if (!existsSync(this.indexDir)) {
+      return [];
+    }
+    const jsonFiles = this.collectJsonFiles(this.indexDir);
+    const results = [];
+    for (const filePath of jsonFiles) {
+      const parsed = this.readSingle(filePath);
+      if (parsed) {
+        results.push(parsed);
+      }
+    }
+    return results;
+  }
+  readSingle(absolutePath) {
+    try {
+      const raw = readFileSync(absolutePath, "utf-8");
+      const data = JSON.parse(raw);
+      const result = FileIndexSchema.safeParse(data);
+      if (!result.success) {
+        const rel = relative(this.indexDir, absolutePath);
+        console.error(
+          `[ctxo:json-reader] Invalid schema in ${rel}: ${result.error.message}`
+        );
+        return void 0;
+      }
+      return result.data;
+    } catch (err) {
+      const rel = relative(this.indexDir, absolutePath);
+      console.error(
+        `[ctxo:json-reader] Failed to read ${rel}: ${err.message}`
+      );
+      return void 0;
+    }
+  }
+  collectJsonFiles(dir, visited = /* @__PURE__ */ new Set()) {
+    const realDir = realpathSync(dir);
+    if (visited.has(realDir)) return [];
+    visited.add(realDir);
+    const files = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...this.collectJsonFiles(fullPath, visited));
+      } else if (entry.name.endsWith(".json") && entry.name !== "co-changes.json") {
+        files.push(fullPath);
+      }
+    }
+    return files;
+  }
+};
+
+export {
+  DetailLevelSchema,
+  JsonIndexReader
+};
+//# sourceMappingURL=chunk-I4TUA7CD.js.map

package/dist/chunk-I4TUA7CD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/storage/json-index-reader.ts","../src/core/types.ts"],"sourcesContent":["import { readFileSync, readdirSync, existsSync, realpathSync } from 'node:fs';\nimport { join, relative } from 'node:path';\nimport { FileIndexSchema, type FileIndex } from '../../core/types.js';\n\nexport class JsonIndexReader {\n  private readonly indexDir: string;\n\n  constructor(ctxoRoot: string) {\n    this.indexDir = join(ctxoRoot, 'index');\n  }\n\n  readAll(): FileIndex[] {\n    if (!existsSync(this.indexDir)) {\n      return [];\n    }\n\n    const jsonFiles = this.collectJsonFiles(this.indexDir);\n    const results: FileIndex[] = [];\n\n    for (const filePath of jsonFiles) {\n      const parsed = this.readSingle(filePath);\n      if (parsed) {\n        results.push(parsed);\n      }\n    }\n\n    return results;\n  }\n\n  readSingle(absolutePath: string): FileIndex | undefined {\n    try {\n      const raw = readFileSync(absolutePath, 'utf-8');\n      const data: unknown = JSON.parse(raw);\n      const result = FileIndexSchema.safeParse(data);\n\n      if (!result.success) {\n        const rel = relative(this.indexDir, absolutePath);\n        console.error(\n          `[ctxo:json-reader] Invalid schema in ${rel}: ${result.error.message}`,\n        );\n        return undefined;\n      }\n\n      return result.data;\n    } catch (err) {\n      const rel = relative(this.indexDir, absolutePath);\n      console.error(\n        `[ctxo:json-reader] Failed to read ${rel}: ${(err as Error).message}`,\n      );\n      return undefined;\n    }\n  }\n\n  private collectJsonFiles(dir: string, visited: Set<string> = new Set()): string[] {\n    const realDir = realpathSync(dir);\n    if (visited.has(realDir)) return []; // Guard against symlink loops\n    visited.add(realDir);\n\n    const files: string[] = [];\n\n    for (const entry of readdirSync(dir, { withFileTypes: true })) {\n      if (entry.isSymbolicLink()) continue; // Skip symlinks entirely\n\n      const fullPath = join(dir, entry.name);\n      if (entry.isDirectory()) {\n        files.push(...this.collectJsonFiles(fullPath, visited));\n      } else if (entry.name.endsWith('.json') && entry.name !== 'co-changes.json') {\n        files.push(fullPath);\n      }\n    }\n\n    return files;\n  }\n}\n","import { z } from 'zod';\r\n\r\n// ── Symbol Kinds ────────────────────────────────────────────────\r\n\r\nexport const SYMBOL_KINDS = [\r\n  'function',\r\n  'class',\r\n  'interface',\r\n  'method',\r\n  'variable',\r\n  'type',\r\n] as const;\r\n\r\nexport const SymbolKindSchema = z.enum(SYMBOL_KINDS);\r\nexport type SymbolKind = z.infer<typeof SymbolKindSchema>;\r\n\r\n// ── Edge Kinds ──────────────────────────────────────────────────\r\n\r\nexport const EDGE_KINDS = [\r\n  'imports',\r\n  'calls',\r\n  'extends',\r\n  'implements',\r\n  'uses',\r\n] as const;\r\n\r\nexport const EdgeKindSchema = z.enum(EDGE_KINDS);\r\nexport type EdgeKind = z.infer<typeof EdgeKindSchema>;\r\n\r\n// ── Detail Levels ───────────────────────────────────────────────\r\n\r\nexport const DETAIL_LEVELS = [1, 2, 3, 4] as const;\r\n\r\nexport const DetailLevelSchema = z.union([\r\n  z.literal(1),\r\n  z.literal(2),\r\n  z.literal(3),\r\n  z.literal(4),\r\n]);\r\nexport type DetailLevel = z.infer<typeof DetailLevelSchema>;\r\n\r\n// ── Symbol ID ───────────────────────────────────────────────────\r\n\r\n/**\r\n * Format: \"<relativeFile>::<name>::<kind>\"\r\n * Example: \"src/foo.ts::myFn::function\"\r\n */\r\nexport const SymbolIdSchema = z\r\n  .string()\r\n  .min(1)\r\n  .refine(\r\n    (value) => {\r\n      const parts = value.split('::');\r\n      if (parts.length !== 3) return false;\r\n      const [file, name, kind] = parts;\r\n      if (!file || !name || !kind) return false;\r\n      return SymbolKindSchema.safeParse(kind).success;\r\n    },\r\n    { message: 'Symbol ID must match format \"<file>::<name>::<kind>\"' },\r\n  );\r\nexport type SymbolId = z.infer<typeof SymbolIdSchema>;\r\n\r\n// ── Symbol Node ─────────────────────────────────────────────────\r\n\r\nexport const SymbolNodeSchema = z\r\n  .object({\r\n    symbolId: SymbolIdSchema,\r\n    name: z.string().min(1),\r\n    kind: SymbolKindSchema,\r\n    startLine: z.number().int().nonnegative(),\r\n    endLine: z.number().int().nonnegative(),\r\n    startOffset: z.number().int().nonnegative().optional(),\r\n    endOffset: z.number().int().nonnegative().optional(),\r\n  })\r\n  .refine((node) => node.endLine >= node.startLine, {\r\n    message: 'endLine must be >= startLine',\r\n  });\r\nexport type SymbolNode = z.infer<typeof SymbolNodeSchema>;\r\n\r\n// ── Graph Edge ──────────────────────────────────────────────────\r\n\r\nexport const GraphEdgeSchema = z.object({\r\n  from: SymbolIdSchema,\r\n  to: SymbolIdSchema,\r\n  kind: EdgeKindSchema,\r\n  typeOnly: z.boolean().optional(),\r\n});\r\nexport type GraphEdge = z.infer<typeof GraphEdgeSchema>;\r\n\r\n// ── Commit Intent ───────────────────────────────────────────────\r\n\r\nexport const CommitIntentSchema = z.object({\r\n  hash: z.string().min(1),\r\n  message: z.string(),\r\n  date: z.string().min(1),\r\n  kind: z.literal('commit'),\r\n});\r\nexport type CommitIntent = z.infer<typeof CommitIntentSchema>;\r\n\r\n// ── Anti-Pattern ────────────────────────────────────────────────\r\n\r\nexport const AntiPatternSchema = z.object({\r\n  hash: z.string().min(1),\r\n  message: z.string(),\r\n  date: z.string().min(1),\r\n});\r\nexport type AntiPattern = z.infer<typeof AntiPatternSchema>;\r\n\r\n// ── File Index ──────────────────────────────────────────────────\r\n\r\nexport const ComplexityMetricsSchema = z.object({\r\n  symbolId: z.string().min(1),\r\n  cyclomatic: z.number().nonnegative(),\r\n});\r\n\r\nexport const FileIndexSchema = z.object({\r\n  file: z.string().min(1),\r\n  lastModified: z.number().nonnegative(),\r\n  contentHash: z.string().optional(),\r\n  symbols: z.array(SymbolNodeSchema),\r\n  edges: z.array(GraphEdgeSchema),\r\n  complexity: z.array(ComplexityMetricsSchema).optional(),\r\n  intent: z.array(CommitIntentSchema),\r\n  antiPatterns: z.array(AntiPatternSchema),\r\n});\r\nexport type FileIndex = z.infer<typeof FileIndexSchema>;\r\n\r\n// ── Logic-Slice Result ──────────────────────────────────────────\r\n\r\nexport interface LogicSliceResult {\r\n  readonly root: SymbolNode;\r\n  readonly dependencies: readonly SymbolNode[];\r\n  readonly edges: readonly GraphEdge[];\r\n}\r\n\r\n// ── Formatted Slice ─────────────────────────────────────────────\r\n\r\nexport interface TruncationInfo {\r\n  readonly truncated: true;\r\n  readonly reason: 'token_budget_exceeded';\r\n}\r\n\r\nexport interface FormattedSlice {\r\n  readonly root: SymbolNode;\r\n  readonly dependencies: readonly SymbolNode[];\r\n  readonly edges: readonly GraphEdge[];\r\n  readonly level: DetailLevel;\r\n  readonly levelDescription?: string;\r\n  readonly truncation?: TruncationInfo;\r\n}\r\n\r\n// ── Complexity & Churn ──────────────────────────────────────────\r\n\r\nexport interface ComplexityMetrics {\r\n  readonly symbolId: string;\r\n  readonly cyclomatic: number;\r\n}\r\n\r\nexport interface ChurnData {\r\n  readonly filePath: string;\r\n  readonly commitCount: number;\r\n}\r\n\r\nexport const SCORE_BANDS = ['low', 'medium', 'high'] as const;\r\nexport type ScoreBand = (typeof SCORE_BANDS)[number];\r\n\r\nexport interface ChangeIntelligenceScore {\r\n  readonly symbolId: string;\r\n  readonly complexity: number;\r\n  readonly churn: number;\r\n  readonly composite: number;\r\n  readonly band: ScoreBand;\r\n}\r\n\r\n// ── Why-Context Result ──────────────────────────────────────────\r\n\r\nexport interface WhyContextResult {\r\n  readonly commitHistory: readonly CommitIntent[];\r\n  readonly antiPatternWarnings: readonly AntiPattern[];\r\n  readonly changeIntelligence?: ChangeIntelligenceScore;\r\n}\r\n\r\n// ── Co-Change Analysis ─────────────────────────────────────────\r\n\r\nexport interface CoChangeEntry {\r\n  readonly file1: string;\r\n  readonly file2: string;\r\n  readonly sharedCommits: number;\r\n  readonly frequency: number;\r\n}\r\n\r\nexport interface CoChangeMatrix {\r\n  readonly version: 1;\r\n  readonly timestamp: number;\r\n  readonly entries: readonly CoChangeEntry[];\r\n}\r\n\r\n// ── Commit Record (from git adapter) ────────────────────────────\r\n\r\nexport interface CommitRecord {\r\n  readonly hash: string;\r\n  readonly message: string;\r\n  readonly date: string;\r\n  readonly author: string;\r\n}\r\n\r\n// ── Blame Line (from git adapter) ───────────────────────────────\r\n\r\nexport interface BlameLine {\r\n  readonly hash: string;\r\n  readonly lineNumber: number;\r\n  readonly author: string;\r\n  readonly date: string;\r\n}\r\n\r\n// ── Search Types ───────────────────────────────────────────────\r\n\r\nexport interface SearchResult {\r\n  symbolId: string;\r\n  name: string;\r\n  kind: string;\r\n  filePath: string;\r\n  /** BM25 relevance score (higher = more relevant) */\r\n  relevanceScore: number;\r\n  /** PageRank importance score (0-1) */\r\n  importanceScore: number;\r\n  /** Final combined score after all boosts */\r\n  combinedScore: number;\r\n}\r\n\r\nexport interface SearchMetrics {\r\n  porterHits: number;\r\n  trigramHits: number;\r\n  phase2Activated: boolean;\r\n  fuzzyApplied: boolean;\r\n  latencyMs: number;\r\n}\r\n\r\nexport interface FuzzyCorrection {\r\n  originalQuery: string;\r\n  correctedQuery: string;\r\n  corrections: Array<{\r\n    original: string;\r\n    corrected: string;\r\n    distance: number;\r\n  }>;\r\n}\r\n\r\nexport interface SearchResponse {\r\n  query: string;\r\n  results: SearchResult[];\r\n  metrics: SearchMetrics;\r\n  fuzzyCorrection?: FuzzyCorrection;\r\n}\r\n"],"mappings":"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","names":[]}