ctxo-mcp 0.3.1 → 0.4.0

package/README.md

@@ -1,25 +1,41 @@
-# Ctxo
+<div align="center">
 
-**Code intelligence for AI agents — one call instead of hundreds.**
+[![npm version](https://img.shields.io/npm/v/ctxo-mcp.svg)](https://www.npmjs.com/package/ctxo-mcp)
+[![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)
 
-AI coding assistants waste context window reading files one by one, still missing dependencies. Ctxo gives them the full picture in a single MCP call: symbol graphs, blast radius, git intent, and risk scores.
+<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>
 
-```
-Context per query set (full codebase investigation):
+</div>
 
-Manual   ████████████████████████████████████████  140,000 tokens
-Ctxo     █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    2,900 tokens  → 48x less
+***
 
-Tool calls per query set:
+### The Problem
 
-Manual   ████████████████████████████████████████  409+ calls
-Ctxo     █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    8 calls       → 51x fewer
+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 after 10 investigation rounds:
+* **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
 
-Manual   ██████████████████████████████████████████ 140% — OOM at round 7
-Ctxo     █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 2.9% — 97% free for coding
-```
+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
 
@@ -55,22 +71,22 @@ npx ctxo-mcp index
 
 ## 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`        | BM25 + PageRank search within token budget                       |
-| `search_symbols`            | Symbol name/regex search across index                            |
-| `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                        | 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
 
@@ -162,8 +178,18 @@ See [Agentic AI Integration Guide](docs/agentic-ai-integration.md) for LangChain
 | Go                    | tree-sitter | Syntax | Structs, interfaces, functions, methods, import edges            |
 | C#                    | tree-sitter | Syntax | Classes, interfaces, methods, enums, namespace qualification     |
 
+## 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.
 
 ```

package/dist/{chunk-N6GPODUY.js → chunk-4OI75JDS.js}

@@ -146,4 +146,4 @@ export {
   DetailLevelSchema,
   JsonIndexReader
 };
-//# sourceMappingURL=chunk-N6GPODUY.js.map
+//# sourceMappingURL=chunk-4OI75JDS.js.map

package/dist/{chunk-N6GPODUY.js.map → chunk-4OI75JDS.js.map}

@@ -1 +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';\n\n// ── Symbol Kinds ────────────────────────────────────────────────\n\nexport const SYMBOL_KINDS = [\n  'function',\n  'class',\n  'interface',\n  'method',\n  'variable',\n  'type',\n] as const;\n\nexport const SymbolKindSchema = z.enum(SYMBOL_KINDS);\nexport type SymbolKind = z.infer<typeof SymbolKindSchema>;\n\n// ── Edge Kinds ──────────────────────────────────────────────────\n\nexport const EDGE_KINDS = [\n  'imports',\n  'calls',\n  'extends',\n  'implements',\n  'uses',\n] as const;\n\nexport const EdgeKindSchema = z.enum(EDGE_KINDS);\nexport type EdgeKind = z.infer<typeof EdgeKindSchema>;\n\n// ── Detail Levels ───────────────────────────────────────────────\n\nexport const DETAIL_LEVELS = [1, 2, 3, 4] as const;\n\nexport const DetailLevelSchema = z.union([\n  z.literal(1),\n  z.literal(2),\n  z.literal(3),\n  z.literal(4),\n]);\nexport type DetailLevel = z.infer<typeof DetailLevelSchema>;\n\n// ── Symbol ID ───────────────────────────────────────────────────\n\n/**\n * Format: \"<relativeFile>::<name>::<kind>\"\n * Example: \"src/foo.ts::myFn::function\"\n */\nexport const SymbolIdSchema = z\n  .string()\n  .min(1)\n  .refine(\n    (value) => {\n      const parts = value.split('::');\n      if (parts.length !== 3) return false;\n      const [file, name, kind] = parts;\n      if (!file || !name || !kind) return false;\n      return SymbolKindSchema.safeParse(kind).success;\n    },\n    { message: 'Symbol ID must match format \"<file>::<name>::<kind>\"' },\n  );\nexport type SymbolId = z.infer<typeof SymbolIdSchema>;\n\n// ── Symbol Node ─────────────────────────────────────────────────\n\nexport const SymbolNodeSchema = z\n  .object({\n    symbolId: SymbolIdSchema,\n    name: z.string().min(1),\n    kind: SymbolKindSchema,\n    startLine: z.number().int().nonnegative(),\n    endLine: z.number().int().nonnegative(),\n    startOffset: z.number().int().nonnegative().optional(),\n    endOffset: z.number().int().nonnegative().optional(),\n  })\n  .refine((node) => node.endLine >= node.startLine, {\n    message: 'endLine must be >= startLine',\n  });\nexport type SymbolNode = z.infer<typeof SymbolNodeSchema>;\n\n// ── Graph Edge ──────────────────────────────────────────────────\n\nexport const GraphEdgeSchema = z.object({\n  from: SymbolIdSchema,\n  to: SymbolIdSchema,\n  kind: EdgeKindSchema,\n  typeOnly: z.boolean().optional(),\n});\nexport type GraphEdge = z.infer<typeof GraphEdgeSchema>;\n\n// ── Commit Intent ───────────────────────────────────────────────\n\nexport const CommitIntentSchema = z.object({\n  hash: z.string().min(1),\n  message: z.string(),\n  date: z.string().min(1),\n  kind: z.literal('commit'),\n});\nexport type CommitIntent = z.infer<typeof CommitIntentSchema>;\n\n// ── Anti-Pattern ────────────────────────────────────────────────\n\nexport const AntiPatternSchema = z.object({\n  hash: z.string().min(1),\n  message: z.string(),\n  date: z.string().min(1),\n});\nexport type AntiPattern = z.infer<typeof AntiPatternSchema>;\n\n// ── File Index ──────────────────────────────────────────────────\n\nexport const ComplexityMetricsSchema = z.object({\n  symbolId: z.string().min(1),\n  cyclomatic: z.number().nonnegative(),\n});\n\nexport const FileIndexSchema = z.object({\n  file: z.string().min(1),\n  lastModified: z.number().nonnegative(),\n  contentHash: z.string().optional(),\n  symbols: z.array(SymbolNodeSchema),\n  edges: z.array(GraphEdgeSchema),\n  complexity: z.array(ComplexityMetricsSchema).optional(),\n  intent: z.array(CommitIntentSchema),\n  antiPatterns: z.array(AntiPatternSchema),\n});\nexport type FileIndex = z.infer<typeof FileIndexSchema>;\n\n// ── Logic-Slice Result ──────────────────────────────────────────\n\nexport interface LogicSliceResult {\n  readonly root: SymbolNode;\n  readonly dependencies: readonly SymbolNode[];\n  readonly edges: readonly GraphEdge[];\n}\n\n// ── Formatted Slice ─────────────────────────────────────────────\n\nexport interface TruncationInfo {\n  readonly truncated: true;\n  readonly reason: 'token_budget_exceeded';\n}\n\nexport interface FormattedSlice {\n  readonly root: SymbolNode;\n  readonly dependencies: readonly SymbolNode[];\n  readonly edges: readonly GraphEdge[];\n  readonly level: DetailLevel;\n  readonly levelDescription?: string;\n  readonly truncation?: TruncationInfo;\n}\n\n// ── Complexity & Churn ──────────────────────────────────────────\n\nexport interface ComplexityMetrics {\n  readonly symbolId: string;\n  readonly cyclomatic: number;\n}\n\nexport interface ChurnData {\n  readonly filePath: string;\n  readonly commitCount: number;\n}\n\nexport const SCORE_BANDS = ['low', 'medium', 'high'] as const;\nexport type ScoreBand = (typeof SCORE_BANDS)[number];\n\nexport interface ChangeIntelligenceScore {\n  readonly symbolId: string;\n  readonly complexity: number;\n  readonly churn: number;\n  readonly composite: number;\n  readonly band: ScoreBand;\n}\n\n// ── Why-Context Result ──────────────────────────────────────────\n\nexport interface WhyContextResult {\n  readonly commitHistory: readonly CommitIntent[];\n  readonly antiPatternWarnings: readonly AntiPattern[];\n  readonly changeIntelligence?: ChangeIntelligenceScore;\n}\n\n// ── Co-Change Analysis ─────────────────────────────────────────\n\nexport interface CoChangeEntry {\n  readonly file1: string;\n  readonly file2: string;\n  readonly sharedCommits: number;\n  readonly frequency: number;\n}\n\nexport interface CoChangeMatrix {\n  readonly version: 1;\n  readonly timestamp: number;\n  readonly entries: readonly CoChangeEntry[];\n}\n\n// ── Commit Record (from git adapter) ────────────────────────────\n\nexport interface CommitRecord {\n  readonly hash: string;\n  readonly message: string;\n  readonly date: string;\n  readonly author: string;\n}\n\n// ── Blame Line (from git adapter) ───────────────────────────────\n\nexport interface BlameLine {\n  readonly hash: string;\n  readonly lineNumber: number;\n  readonly author: string;\n  readonly date: string;\n}\n"],"mappings":"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","names":[]}
+{"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';\n\n// ── Symbol Kinds ────────────────────────────────────────────────\n\nexport const SYMBOL_KINDS = [\n  'function',\n  'class',\n  'interface',\n  'method',\n  'variable',\n  'type',\n] as const;\n\nexport const SymbolKindSchema = z.enum(SYMBOL_KINDS);\nexport type SymbolKind = z.infer<typeof SymbolKindSchema>;\n\n// ── Edge Kinds ──────────────────────────────────────────────────\n\nexport const EDGE_KINDS = [\n  'imports',\n  'calls',\n  'extends',\n  'implements',\n  'uses',\n] as const;\n\nexport const EdgeKindSchema = z.enum(EDGE_KINDS);\nexport type EdgeKind = z.infer<typeof EdgeKindSchema>;\n\n// ── Detail Levels ───────────────────────────────────────────────\n\nexport const DETAIL_LEVELS = [1, 2, 3, 4] as const;\n\nexport const DetailLevelSchema = z.union([\n  z.literal(1),\n  z.literal(2),\n  z.literal(3),\n  z.literal(4),\n]);\nexport type DetailLevel = z.infer<typeof DetailLevelSchema>;\n\n// ── Symbol ID ───────────────────────────────────────────────────\n\n/**\n * Format: \"<relativeFile>::<name>::<kind>\"\n * Example: \"src/foo.ts::myFn::function\"\n */\nexport const SymbolIdSchema = z\n  .string()\n  .min(1)\n  .refine(\n    (value) => {\n      const parts = value.split('::');\n      if (parts.length !== 3) return false;\n      const [file, name, kind] = parts;\n      if (!file || !name || !kind) return false;\n      return SymbolKindSchema.safeParse(kind).success;\n    },\n    { message: 'Symbol ID must match format \"<file>::<name>::<kind>\"' },\n  );\nexport type SymbolId = z.infer<typeof SymbolIdSchema>;\n\n// ── Symbol Node ─────────────────────────────────────────────────\n\nexport const SymbolNodeSchema = z\n  .object({\n    symbolId: SymbolIdSchema,\n    name: z.string().min(1),\n    kind: SymbolKindSchema,\n    startLine: z.number().int().nonnegative(),\n    endLine: z.number().int().nonnegative(),\n    startOffset: z.number().int().nonnegative().optional(),\n    endOffset: z.number().int().nonnegative().optional(),\n  })\n  .refine((node) => node.endLine >= node.startLine, {\n    message: 'endLine must be >= startLine',\n  });\nexport type SymbolNode = z.infer<typeof SymbolNodeSchema>;\n\n// ── Graph Edge ──────────────────────────────────────────────────\n\nexport const GraphEdgeSchema = z.object({\n  from: SymbolIdSchema,\n  to: SymbolIdSchema,\n  kind: EdgeKindSchema,\n  typeOnly: z.boolean().optional(),\n});\nexport type GraphEdge = z.infer<typeof GraphEdgeSchema>;\n\n// ── Commit Intent ───────────────────────────────────────────────\n\nexport const CommitIntentSchema = z.object({\n  hash: z.string().min(1),\n  message: z.string(),\n  date: z.string().min(1),\n  kind: z.literal('commit'),\n});\nexport type CommitIntent = z.infer<typeof CommitIntentSchema>;\n\n// ── Anti-Pattern ────────────────────────────────────────────────\n\nexport const AntiPatternSchema = z.object({\n  hash: z.string().min(1),\n  message: z.string(),\n  date: z.string().min(1),\n});\nexport type AntiPattern = z.infer<typeof AntiPatternSchema>;\n\n// ── File Index ──────────────────────────────────────────────────\n\nexport const ComplexityMetricsSchema = z.object({\n  symbolId: z.string().min(1),\n  cyclomatic: z.number().nonnegative(),\n});\n\nexport const FileIndexSchema = z.object({\n  file: z.string().min(1),\n  lastModified: z.number().nonnegative(),\n  contentHash: z.string().optional(),\n  symbols: z.array(SymbolNodeSchema),\n  edges: z.array(GraphEdgeSchema),\n  complexity: z.array(ComplexityMetricsSchema).optional(),\n  intent: z.array(CommitIntentSchema),\n  antiPatterns: z.array(AntiPatternSchema),\n});\nexport type FileIndex = z.infer<typeof FileIndexSchema>;\n\n// ── Logic-Slice Result ──────────────────────────────────────────\n\nexport interface LogicSliceResult {\n  readonly root: SymbolNode;\n  readonly dependencies: readonly SymbolNode[];\n  readonly edges: readonly GraphEdge[];\n}\n\n// ── Formatted Slice ─────────────────────────────────────────────\n\nexport interface TruncationInfo {\n  readonly truncated: true;\n  readonly reason: 'token_budget_exceeded';\n}\n\nexport interface FormattedSlice {\n  readonly root: SymbolNode;\n  readonly dependencies: readonly SymbolNode[];\n  readonly edges: readonly GraphEdge[];\n  readonly level: DetailLevel;\n  readonly levelDescription?: string;\n  readonly truncation?: TruncationInfo;\n}\n\n// ── Complexity & Churn ──────────────────────────────────────────\n\nexport interface ComplexityMetrics {\n  readonly symbolId: string;\n  readonly cyclomatic: number;\n}\n\nexport interface ChurnData {\n  readonly filePath: string;\n  readonly commitCount: number;\n}\n\nexport const SCORE_BANDS = ['low', 'medium', 'high'] as const;\nexport type ScoreBand = (typeof SCORE_BANDS)[number];\n\nexport interface ChangeIntelligenceScore {\n  readonly symbolId: string;\n  readonly complexity: number;\n  readonly churn: number;\n  readonly composite: number;\n  readonly band: ScoreBand;\n}\n\n// ── Why-Context Result ──────────────────────────────────────────\n\nexport interface WhyContextResult {\n  readonly commitHistory: readonly CommitIntent[];\n  readonly antiPatternWarnings: readonly AntiPattern[];\n  readonly changeIntelligence?: ChangeIntelligenceScore;\n}\n\n// ── Co-Change Analysis ─────────────────────────────────────────\n\nexport interface CoChangeEntry {\n  readonly file1: string;\n  readonly file2: string;\n  readonly sharedCommits: number;\n  readonly frequency: number;\n}\n\nexport interface CoChangeMatrix {\n  readonly version: 1;\n  readonly timestamp: number;\n  readonly entries: readonly CoChangeEntry[];\n}\n\n// ── Commit Record (from git adapter) ────────────────────────────\n\nexport interface CommitRecord {\n  readonly hash: string;\n  readonly message: string;\n  readonly date: string;\n  readonly author: string;\n}\n\n// ── Blame Line (from git adapter) ───────────────────────────────\n\nexport interface BlameLine {\n  readonly hash: string;\n  readonly lineNumber: number;\n  readonly author: string;\n  readonly date: string;\n}\n\n// ── Search Types ───────────────────────────────────────────────\n\nexport interface SearchResult {\n  symbolId: string;\n  name: string;\n  kind: string;\n  filePath: string;\n  /** BM25 relevance score (higher = more relevant) */\n  relevanceScore: number;\n  /** PageRank importance score (0-1) */\n  importanceScore: number;\n  /** Final combined score after all boosts */\n  combinedScore: number;\n}\n\nexport interface SearchMetrics {\n  porterHits: number;\n  trigramHits: number;\n  phase2Activated: boolean;\n  fuzzyApplied: boolean;\n  latencyMs: number;\n}\n\nexport interface FuzzyCorrection {\n  originalQuery: string;\n  correctedQuery: string;\n  corrections: Array<{\n    original: string;\n    corrected: string;\n    distance: number;\n  }>;\n}\n\nexport interface SearchResponse {\n  query: string;\n  results: SearchResult[];\n  metrics: SearchMetrics;\n  fuzzyCorrection?: FuzzyCorrection;\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-XSHNN6PU.js → chunk-BMB6SQIR.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   JsonIndexReader
-} from "./chunk-N6GPODUY.js";
+} from "./chunk-4OI75JDS.js";
 
 // src/core/logger.ts
 function isDebugEnabled(namespace) {
@@ -558,4 +558,4 @@ export {
   aggregateCoChanges,
   loadCoChangeMap
 };
-//# sourceMappingURL=chunk-XSHNN6PU.js.map
+//# sourceMappingURL=chunk-BMB6SQIR.js.map

package/dist/{cli-router-NRUGPICL.js → cli-router-Z5CSD6QN.js}

@@ -4,11 +4,11 @@ import {
   SimpleGitAdapter,
   SqliteStorageAdapter,
   aggregateCoChanges
-} from "./chunk-XSHNN6PU.js";
+} from "./chunk-BMB6SQIR.js";
 import {
   JsonIndexReader,
   SYMBOL_KINDS
-} from "./chunk-N6GPODUY.js";
+} from "./chunk-4OI75JDS.js";
 import {
   __esm,
   __export,
@@ -1400,7 +1400,7 @@ var IndexCommand = class {
     this.supportedExtensions = registry.getSupportedExtensions();
     const hasher = new ContentHasher();
     const files = this.discoverFilesIn(this.projectRoot);
-    const reader = new (await import("./json-index-reader-FCKSKA6R.js")).JsonIndexReader(this.ctxoRoot);
+    const reader = new (await import("./json-index-reader-Z6VHJ47M.js")).JsonIndexReader(this.ctxoRoot);
     const indices = reader.readAll();
     const indexedMap = new Map(indices.map((i) => [i.file, i]));
     let staleCount = 0;
@@ -1854,4 +1854,4 @@ Usage:
 export {
   CliRouter
 };
-//# sourceMappingURL=cli-router-NRUGPICL.js.map
+//# sourceMappingURL=cli-router-Z5CSD6QN.js.map