@maxgfr/codeindex 2.15.0 → 2.17.0

package/README.md

@@ -17,7 +17,7 @@ engine as a single file instead of taking an npm dependency.
   and count caps (`capped` flag, never silent truncation), symlink-cycle guard.
 - **Scan** every file into a `FileRecord`: classification, language, symbols,
   imports, headings, hashes — with an incremental cache fastpath.
-- **Extract symbols** via tree-sitter (10 languages, when the wasm sidecar is
+- **Extract symbols** via tree-sitter (13 languages, when the wasm sidecar is
   present) or per-language regex rules (15 languages, always available).
 - **Resolve imports** across languages: tsconfig paths, package `exports`,
   go.mod, Cargo, Java packages, PSR-4, C# namespaces.
@@ -192,17 +192,65 @@ Full details incl. the HTTP protocol (build your own server):
 
 ## Use as an MCP server
 
-`codeindex mcp` (or `node scripts/cli.mjs mcp`) serves the engine over stdio —
-tools: `scan_summary`, `graph`, `symbols`, `callers`, `workspaces`, `churn`,
-`grep`. Register it in Claude Code with:
+`codeindex mcp` (or `node scripts/cli.mjs mcp`) serves the engine over stdio.
+Register it in Claude Code with:
 
 ```sh
 claude mcp add codeindex -- codeindex mcp
 ```
 
+**26 tools**, grouped by what they answer:
+
+| group | tools |
+|---|---|
+| orient | `scan_summary`, `repo_map`, `graph`, `mermaid`, `workspaces` |
+| find | `search`, `grep`, `find_symbol`, `symbols`, `symbols_overview` |
+| impact | `find_references`, `callers`, `dead_code` |
+| risk | `hotspots`, `churn`, `coupling`, `complexity`, `check_rules` |
+| edit *(write)* | `replace_symbol_body`, `insert_after_symbol`, `insert_before_symbol` |
+| memory | `write_memory`, `read_memory`, `list_memories`, `delete_memory` *(write except reads)* |
+| embeddings | `embed_status` |
+
+### Pinning the server to one repository
+
+Every tool takes a `repo` argument. A host that runs one server per workspace
+can pin it instead, so `repo` becomes optional on every tool — the pin is
+reflected in the advertised schema, not merely tolerated at call time:
+
+```sh
+codeindex mcp --repo /path/to/workspace
+```
+
+An explicit per-call `repo` still wins, so a pinned server can still answer
+about another checkout. `--server-name <name>` overrides the announced
+`serverInfo.name` for hosts that embed the server under their own identity.
+
+**Prime the index first** and activation becomes a load, not a rebuild:
+`codeindex index --repo <dir> --out <dir>/.codeindex`. The first tool call
+deserializes those artifacts when the engine version, commit and artifact
+hashes all match.
+
 `engine.mjs` is a pure side-effect-free library (safe for consumers to inline
 into their own CLIs); `cli.mjs` is the thin standalone CLI/MCP wrapper.
 
+## Command rewriting
+
+`codeindex rewrite '<command line>'` maps an expensive tree-wide search onto
+its indexed equivalent, for agent harnesses that intercept shell commands
+(iterion's `rewriters` plugin kind, generalizing rtk):
+
+```sh
+$ codeindex rewrite 'grep -rn TODO src'
+codeindex grep TODO --scope src
+```
+
+It prints the replacement and exits `0`, or exits `1` with empty stdout when it
+has no opinion — run the original. The parser is deliberately conservative: any
+shell metacharacter (pipe, redirect, substitution, chaining), any unrecognized
+flag, a non-recursive `grep`, or more than one search path all refuse the
+rewrite. A refusal costs nothing; a wrong rewrite silently changes what the
+agent asked for.
+
 ## Versioning
 
 - `ENGINE_VERSION` — the release tag, embedded greppably in the bundle.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxgfr/codeindex",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "Self-contained, deterministic repo-indexing engine: walk + language detection + symbol/import extraction (tree-sitter AST with regex fallback) + import resolution + typed cross-file link-graph + analytics. Ships as a single zero-dependency engine.mjs that consumer tools vendor.",
   "type": "module",
   "packageManager": "pnpm@10.33.0",
@@ -77,7 +77,7 @@
     "tsup": "^8.3.0",
     "typescript": "^5.5.0",
     "vitest": "^4.1.0",
-    "web-tree-sitter": "^0.26.10"
+    "web-tree-sitter": "^0.26.11"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

package/scripts/engine.d.mts

@@ -1,4 +1,4 @@
-declare const ENGINE_VERSION = "2.15.0";
+declare const ENGINE_VERSION = "2.17.0";
 declare const SCHEMA_VERSION = 4;
 declare const EXTRACTOR_VERSION = 10;
 type FileKind = "code" | "doc" | "config" | "asset" | "other";
@@ -255,7 +255,7 @@ declare function extractAst(rel: string, ext: string, content: string, opts?: {
     maxCalls?: number;
 }): AstResult | undefined;
 
-declare const DEFAULT_GRAMMARS_URL = "https://github.com/maxgfr/codeindex/releases/download/v2.15.0/grammars-2.15.0.tar.gz";
+declare const DEFAULT_GRAMMARS_URL = "https://github.com/maxgfr/codeindex/releases/download/v2.17.0/grammars-2.17.0.tar.gz";
 interface GrammarsPullTarget {
     url: string;
     sha256Url?: string;
@@ -265,6 +265,38 @@ declare function fetchGrammarsTarball(url: string, expectedSha256?: string): Pro
 declare function fetchExpectedSha256(url: string): Promise<string>;
 declare function extractTarInto(rawTar: Uint8Array, destDir: string): string[];
 declare function extractGrammarsTarball(bytes: Uint8Array, destDir: string): string[];
+interface GrammarsPullResult {
+    ok: boolean;
+    status: "up-to-date" | "pulled" | "failed";
+    cacheDir: string;
+    /** One human-readable line; the CLI writes it to stderr, a library caller may log or drop it. */
+    message: string;
+}
+declare function pullGrammars(cacheDir: string, opts?: {
+    onNote?: (msg: string) => void;
+}): Promise<GrammarsPullResult>;
+
+interface WarmGrammarsResult {
+    /** Tier AFTER the warm-up (a successful pull moves "none" → "cache"). */
+    tier: GrammarsTierName;
+    /** True when at least one requested grammar is loaded ⇒ the AST tier is live. */
+    ready: boolean;
+    /** True when this call populated the shared cache over the network. */
+    pulled: boolean;
+    /** Everything written to `onNote`, in order — so a caller can persist the trail in its run artifacts. */
+    notes: string[];
+}
+interface WarmGrammarsOptions {
+    /** Grammars to load. Default: every shipped grammar. Narrow it with `grammarKeysForExts` when the repo's languages are known. */
+    keys?: Iterable<string>;
+    /** Fetch the wasms into the shared cache when nothing is resolvable. Default true; `CODEINDEX_NO_GRAMMARS_PULL=1` forces false. */
+    pull?: boolean;
+    /** Prefix for the diagnostics ("ultrasec: …"). Default "codeindex". */
+    label?: string;
+    /** Where diagnostics go. Default: process.stderr. Pass a sink to keep stdout/stderr clean. */
+    onNote?: (msg: string) => void;
+}
+declare function warmGrammars(opts?: WarmGrammarsOptions): Promise<WarmGrammarsResult>;
 
 type Resolution = {
     kind: "resolved";
@@ -713,9 +745,12 @@ interface McpServerOptions {
         name?: string;
         version?: string;
     };
+    defaultRepo?: string;
 }
 declare function runMcpServer(opts?: McpServerOptions): Promise<void>;
 
+declare function rewriteCommand(cmd: string, bin?: string): string | undefined;
+
 declare function sha1(s: string | Uint8Array): string;
 declare function shortHash(s: string, n?: number): string;
 
@@ -747,4 +782,4 @@ declare function rrf<T>(lists: T[][], keyOf: (item: T) => string, k?: number): M
 
 declare function runCli(argv: string[]): Promise<void>;
 
-export { type ArchRule, type BuildIndexOptions, type BuiltinRule, type CallerEntry, type CallerIndex, type CallerIndexOptions, type CallerSite, type ChangeCoupling, type CodeInfo, type CodeSymbol, type CouplingOptions, DEFAULT_GRAMMARS_URL, DEFAULT_MAX_FILES, type DeadSymbol, type DiffFile, type DiffSpec, EMBED_VERSION, ENGINE_VERSION, EXTRACTOR_VERSION, type Edge, type EdgeKind, type EditResult, type EmbedEndpointOptions, type EmbedPullTarget, type EmbeddingIndex, type EmbeddingRecord, type EmbeddingUnit, type FileCategory, type FileKind, type FileNode, type FileRecord, type FindSymbolOptions, type ForbiddenEdgeRule, type GrammarsPullTarget, type GrammarsTier, type GrammarsTierName, type Graph, type GrepOptions, type Hotspot, type Hunk, type IgnoreRule, type IndexArtifacts, MARKDOWN_EXT, type MarkdownInfo, type McpServerOptions, type MermaidOptions, type ModuleInfo, type ModuleNode, type RawCallerIndex, type RawCallerSite, type RawRef, type RenderScipOptions, type RepoMapOptions, type RepoScan, type Resolution, type ResolveContext, type RiskHotspot, type RuleSeverity, type RuleViolation, SCHEMA_VERSION, type ScanOptions, type SearchHit, type SearchOptions, type SearchResult, type SemanticSearchOptions, type SemanticSearchResult, type ShResult, type StaticEmbedModel, type SurpriseEdge, type SymbolComplexity, type SymbolIndex, type SymbolMatch, type SymbolReferences, type TestMap, type Tier, type WalkOptions, type WalkResult, type WalkedFile, type WorkspaceInfo, type WorkspaceKind, type WorkspacePackage, allGrammarKeys, applyCentrality, basicTokenize, betweennessOf, buildArtifactsFromScan, buildCallerIndex, buildEmbeddingIndex, buildEndpointIndex, buildGraph, buildIndexArtifacts, buildModules, buildRawCallerIndex, buildResolveContext, buildSymbolIndex, byKey, byStr, categorize, changeCoupling, changedSince, checkRules, classify, clip, clipInline, communityOf, compileGlobs, complexityOfSource, computeImportPairs, computeSurprises, computeSymbolRefs, computeTestMap, deleteMemory, deserializeEmbeddings, detectCommunities, detectWorkspaces, diffFiles, diffHunks, embedEndpointUrl, embedViaEndpoint, embeddingUnits, enclosingSymbol, encode, encodeQueryViaEndpoint, ensureGrammars, escapeRegExp, extToLang, extractAst, extractCode, extractGrammarsTarball, extractMarkdown, extractSymbols, extractTarInto, fetchExpectedSha256, fetchGrammarsTarball, findDeadCode, findReferences, findSymbol, foldText, gitChurn, grammarKeyForExt, grammarKeysForExts, grammarReady, grepRepo, hasEmbedModel, have, headCommit, healthzUrl, insertAfterSymbol, insertBeforeSymbol, intDot, isCode, isDoc, isGitWorktree, isIgnored, isSurprising, isTestFile, isTestPath, keywords, languageOf, listMemories, loadEmbedModel, pagerankOf, parseGitignore, parseRules, probeEndpoint, quantize, rankHotspots, rankedKeywords, readMemory, readText, renderGraphJson, renderMermaid, renderRepoMap, renderScip, renderSymbolsJson, replaceSymbolBody, resolveBaseRef, resolveCallEdges, resolveDocLink, resolveEmbedEndpoint, resolveEmbedModelDir, resolveEmbedPullUrl, resolveGrammarsDir, resolveGrammarsPullTarget, resolveGrammarsTier, resolveImport, resolveUniqueSymbol, riskHotspots, roundHalfToEven, rrf, runCli, runMcpServer, scanRepo, searchIndex, searchSemantic, serializeEmbeddings, sh, sha1, sharedGrammarsCacheDir, shortHash, slugify, subtokens, symbolComplexity, symbolsOverview, testsForModule, tierForPath, tokenize, uniqueSymbolDefs, untestedModules, untrackedFiles, walk, wordpiece, writeMemory };
+export { type ArchRule, type BuildIndexOptions, type BuiltinRule, type CallerEntry, type CallerIndex, type CallerIndexOptions, type CallerSite, type ChangeCoupling, type CodeInfo, type CodeSymbol, type CouplingOptions, DEFAULT_GRAMMARS_URL, DEFAULT_MAX_FILES, type DeadSymbol, type DiffFile, type DiffSpec, EMBED_VERSION, ENGINE_VERSION, EXTRACTOR_VERSION, type Edge, type EdgeKind, type EditResult, type EmbedEndpointOptions, type EmbedPullTarget, type EmbeddingIndex, type EmbeddingRecord, type EmbeddingUnit, type FileCategory, type FileKind, type FileNode, type FileRecord, type FindSymbolOptions, type ForbiddenEdgeRule, type GrammarsPullResult, type GrammarsPullTarget, type GrammarsTier, type GrammarsTierName, type Graph, type GrepOptions, type Hotspot, type Hunk, type IgnoreRule, type IndexArtifacts, MARKDOWN_EXT, type MarkdownInfo, type McpServerOptions, type MermaidOptions, type ModuleInfo, type ModuleNode, type RawCallerIndex, type RawCallerSite, type RawRef, type RenderScipOptions, type RepoMapOptions, type RepoScan, type Resolution, type ResolveContext, type RiskHotspot, type RuleSeverity, type RuleViolation, SCHEMA_VERSION, type ScanOptions, type SearchHit, type SearchOptions, type SearchResult, type SemanticSearchOptions, type SemanticSearchResult, type ShResult, type StaticEmbedModel, type SurpriseEdge, type SymbolComplexity, type SymbolIndex, type SymbolMatch, type SymbolReferences, type TestMap, type Tier, type WalkOptions, type WalkResult, type WalkedFile, type WarmGrammarsOptions, type WarmGrammarsResult, type WorkspaceInfo, type WorkspaceKind, type WorkspacePackage, allGrammarKeys, applyCentrality, basicTokenize, betweennessOf, buildArtifactsFromScan, buildCallerIndex, buildEmbeddingIndex, buildEndpointIndex, buildGraph, buildIndexArtifacts, buildModules, buildRawCallerIndex, buildResolveContext, buildSymbolIndex, byKey, byStr, categorize, changeCoupling, changedSince, checkRules, classify, clip, clipInline, communityOf, compileGlobs, complexityOfSource, computeImportPairs, computeSurprises, computeSymbolRefs, computeTestMap, deleteMemory, deserializeEmbeddings, detectCommunities, detectWorkspaces, diffFiles, diffHunks, embedEndpointUrl, embedViaEndpoint, embeddingUnits, enclosingSymbol, encode, encodeQueryViaEndpoint, ensureGrammars, escapeRegExp, extToLang, extractAst, extractCode, extractGrammarsTarball, extractMarkdown, extractSymbols, extractTarInto, fetchExpectedSha256, fetchGrammarsTarball, findDeadCode, findReferences, findSymbol, foldText, gitChurn, grammarKeyForExt, grammarKeysForExts, grammarReady, grepRepo, hasEmbedModel, have, headCommit, healthzUrl, insertAfterSymbol, insertBeforeSymbol, intDot, isCode, isDoc, isGitWorktree, isIgnored, isSurprising, isTestFile, isTestPath, keywords, languageOf, listMemories, loadEmbedModel, pagerankOf, parseGitignore, parseRules, probeEndpoint, pullGrammars, quantize, rankHotspots, rankedKeywords, readMemory, readText, renderGraphJson, renderMermaid, renderRepoMap, renderScip, renderSymbolsJson, replaceSymbolBody, resolveBaseRef, resolveCallEdges, resolveDocLink, resolveEmbedEndpoint, resolveEmbedModelDir, resolveEmbedPullUrl, resolveGrammarsDir, resolveGrammarsPullTarget, resolveGrammarsTier, resolveImport, resolveUniqueSymbol, rewriteCommand, riskHotspots, roundHalfToEven, rrf, runCli, runMcpServer, scanRepo, searchIndex, searchSemantic, serializeEmbeddings, sh, sha1, sharedGrammarsCacheDir, shortHash, slugify, subtokens, symbolComplexity, symbolsOverview, testsForModule, tierForPath, tokenize, uniqueSymbolDefs, untestedModules, untrackedFiles, walk, warmGrammars, wordpiece, writeMemory };