@maxgfr/codeindex 2.7.0 → 2.8.0

package/README.md

@@ -24,7 +24,9 @@ ultraeval, reconstruct, construct, ultra11y).
   `mention` edges at file and module level, plus Louvain communities, PageRank/
   betweenness centrality, a tests→code map, and surprise-edge detection.
 - **Render** byte-stable `graph.json` / `symbols.json` (two builds of an
-  unchanged repo are byte-identical).
+  unchanged repo are byte-identical), plus a **SCIP** code-intelligence index
+  (`index.scip`) via a hand-rolled zero-dependency protobuf encoder — validated
+  by the official `scip` CLI (`stats`/`lint`).
 
 ## Use as a library (the vendoring model)
 
@@ -68,6 +70,7 @@ brew install maxgfr/tap/codeindex        # or: npm i -g @maxgfr/codeindex
 
 codeindex index   --repo . --out .codeindex   # graph + symbols + incremental cache
 codeindex graph   --repo . > graph.json
+codeindex scip    --repo . --out index.scip   # SCIP index (--out - for stdout)
 codeindex callers --repo .                    # per-symbol caller index
 codeindex grep    'pattern' --repo .
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxgfr/codeindex",
-  "version": "2.7.0",
+  "version": "2.8.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",
@@ -59,7 +59,7 @@
     "@semantic-release/git": "^10.0.1",
     "@tree-sitter-grammars/tree-sitter-lua": "0.4.1",
     "@types/node": "^20.14.0",
-    "semantic-release": "^24.2.0",
+    "semantic-release": "^25.0.8",
     "tree-sitter-bash": "0.25.1",
     "tree-sitter-c": "^0.24.1",
     "tree-sitter-c-sharp": "^0.23.5",

package/scripts/engine.d.mts

@@ -1,4 +1,4 @@
-declare const ENGINE_VERSION = "2.7.0";
+declare const ENGINE_VERSION = "2.8.0";
 declare const SCHEMA_VERSION = 4;
 declare const EXTRACTOR_VERSION = 6;
 type FileKind = "code" | "doc" | "config" | "asset" | "other";
@@ -415,6 +415,11 @@ declare function renderSymbolsJson(index: SymbolIndex): string;
 
 declare function renderGraphJson(graph: Graph): string;
 
+interface RenderScipOptions {
+    projectRoot?: string;
+}
+declare function renderScip(scan: RepoScan, opts?: RenderScipOptions): Uint8Array;
+
 interface BuildIndexOptions extends ScanOptions {
     meta?: {
         version?: string;
@@ -615,4 +620,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_MAX_FILES, type DeadSymbol, type DiffFile, type DiffSpec, ENGINE_VERSION, EXTRACTOR_VERSION, type Edge, type EdgeKind, type EditResult, type FileCategory, type FileKind, type FileNode, type FileRecord, type FindSymbolOptions, type ForbiddenEdgeRule, type Graph, type GrepOptions, type Hotspot, type Hunk, type IgnoreRule, type IndexArtifacts, MARKDOWN_EXT, type MarkdownInfo, type MermaidOptions, type ModuleInfo, type ModuleNode, type RawRef, 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 ShResult, 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, betweennessOf, buildCallerIndex, buildGraph, buildIndexArtifacts, buildModules, buildResolveContext, buildSymbolIndex, byKey, byStr, categorize, changeCoupling, changedSince, checkRules, classify, clip, clipInline, communityOf, compileGlobs, complexityOfSource, computeImportPairs, computeSurprises, computeSymbolRefs, computeTestMap, deleteMemory, detectCommunities, detectWorkspaces, diffFiles, diffHunks, enclosingSymbol, ensureGrammars, escapeRegExp, extToLang, extractAst, extractCode, extractMarkdown, extractSymbols, findDeadCode, findReferences, findSymbol, foldText, gitChurn, grammarKeyForExt, grammarReady, grepRepo, have, headCommit, insertAfterSymbol, insertBeforeSymbol, isCode, isDoc, isGitWorktree, isIgnored, isSurprising, isTestFile, isTestPath, keywords, languageOf, listMemories, pagerankOf, parseGitignore, parseRules, rankHotspots, rankedKeywords, readMemory, readText, renderGraphJson, renderMermaid, renderRepoMap, renderSymbolsJson, replaceSymbolBody, resolveBaseRef, resolveCallEdges, resolveDocLink, resolveImport, resolveUniqueSymbol, riskHotspots, rrf, runCli, runMcpServer, scanRepo, searchIndex, sh, sha1, shortHash, slugify, subtokens, symbolComplexity, symbolsOverview, testsForModule, tierForPath, uniqueSymbolDefs, untestedModules, untrackedFiles, walk, 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_MAX_FILES, type DeadSymbol, type DiffFile, type DiffSpec, ENGINE_VERSION, EXTRACTOR_VERSION, type Edge, type EdgeKind, type EditResult, type FileCategory, type FileKind, type FileNode, type FileRecord, type FindSymbolOptions, type ForbiddenEdgeRule, type Graph, type GrepOptions, type Hotspot, type Hunk, type IgnoreRule, type IndexArtifacts, MARKDOWN_EXT, type MarkdownInfo, type MermaidOptions, type ModuleInfo, type ModuleNode, 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 ShResult, 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, betweennessOf, buildCallerIndex, buildGraph, buildIndexArtifacts, buildModules, buildResolveContext, buildSymbolIndex, byKey, byStr, categorize, changeCoupling, changedSince, checkRules, classify, clip, clipInline, communityOf, compileGlobs, complexityOfSource, computeImportPairs, computeSurprises, computeSymbolRefs, computeTestMap, deleteMemory, detectCommunities, detectWorkspaces, diffFiles, diffHunks, enclosingSymbol, ensureGrammars, escapeRegExp, extToLang, extractAst, extractCode, extractMarkdown, extractSymbols, findDeadCode, findReferences, findSymbol, foldText, gitChurn, grammarKeyForExt, grammarReady, grepRepo, have, headCommit, insertAfterSymbol, insertBeforeSymbol, isCode, isDoc, isGitWorktree, isIgnored, isSurprising, isTestFile, isTestPath, keywords, languageOf, listMemories, pagerankOf, parseGitignore, parseRules, rankHotspots, rankedKeywords, readMemory, readText, renderGraphJson, renderMermaid, renderRepoMap, renderScip, renderSymbolsJson, replaceSymbolBody, resolveBaseRef, resolveCallEdges, resolveDocLink, resolveImport, resolveUniqueSymbol, riskHotspots, rrf, runCli, runMcpServer, scanRepo, searchIndex, sh, sha1, shortHash, slugify, subtokens, symbolComplexity, symbolsOverview, testsForModule, tierForPath, uniqueSymbolDefs, untestedModules, untrackedFiles, walk, writeMemory };

package/scripts/engine.mjs

@@ -14,7 +14,7 @@ var ENGINE_VERSION, SCHEMA_VERSION, EXTRACTOR_VERSION;
 var init_types = __esm({
   "src/types.ts"() {
     "use strict";
-    ENGINE_VERSION = "2.7.0";
+    ENGINE_VERSION = "2.8.0";
     SCHEMA_VERSION = 4;
     EXTRACTOR_VERSION = 6;
   }
@@ -9551,7 +9551,7 @@ function findDeadCode(scan2) {
   const callers = buildCallerIndex(scan2);
   const refs = computeSymbolRefs(scan2);
   const out2 = [];
-  const consider = (s) => s.exported && !REFERENCE_KINDS5.has(s.kind) && !isTestPath(s.file) && !ENTRYPOINT_RE.test(s.file);
+  const consider = (s) => s.exported && !REFERENCE_KINDS6.has(s.kind) && !isTestPath(s.file) && !ENTRYPOINT_RE.test(s.file);
   for (const f of scan2.files) {
     for (const s of f.symbols) {
       if (!consider(s)) continue;
@@ -9564,7 +9564,7 @@ function findDeadCode(scan2) {
   }
   return out2.sort((a, b) => byStr(a.tier, b.tier) || byStr(a.file, b.file) || a.line - b.line);
 }
-var REFERENCE_KINDS5, ENTRYPOINT_RE;
+var REFERENCE_KINDS6, ENTRYPOINT_RE;
 var init_deadcode = __esm({
   "src/deadcode.ts"() {
     "use strict";
@@ -9572,13 +9572,13 @@ var init_deadcode = __esm({
     init_symbols_json();
     init_tests_map();
     init_sort();
-    REFERENCE_KINDS5 = /* @__PURE__ */ new Set(["reexport", "reexport-all", "default"]);
+    REFERENCE_KINDS6 = /* @__PURE__ */ new Set(["reexport", "reexport-all", "default"]);
     ENTRYPOINT_RE = /(^|\/)(index|main|cli|app|server|engine)\.[a-z]+$/;
   }
 });
 
 // src/complexity.ts
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 function complexityOfSource(source) {
   return 1 + (source.match(BRANCH_RE) ?? []).length;
 }
@@ -9588,7 +9588,7 @@ function symbolComplexity(scan2, rel, top = 50) {
     if (f.kind !== "code") continue;
     if (rel && f.rel !== rel) continue;
     if (!f.symbols.length) continue;
-    const lines = readText(join9(scan2.root, f.rel)).split("\n");
+    const lines = readText(join10(scan2.root, f.rel)).split("\n");
     for (const s of f.symbols) {
       if (s.kind === "reexport" || s.kind === "reexport-all") continue;
       const end = s.endLine ?? s.line;
@@ -9603,7 +9603,7 @@ function symbolComplexity(scan2, rel, top = 50) {
 }
 function riskHotspots(scan2, churn, top = 20) {
   const out2 = scan2.files.filter((f) => f.kind === "code").map((f) => {
-    const complexity = complexityOfSource(readText(join9(scan2.root, f.rel)));
+    const complexity = complexityOfSource(readText(join10(scan2.root, f.rel)));
     const commits = churn.get(f.rel) ?? 0;
     return { file: f.rel, complexity, commits, score: (commits + 1) * complexity };
   });
@@ -10285,6 +10285,247 @@ init_tests_map();
 init_surprise();
 init_symbols_json();
 init_graph_json();
+
+// src/render/scip.ts
+init_types();
+init_walk();
+init_sort();
+import { join as join9 } from "path";
+var utf8 = new TextEncoder();
+function pushVarint(out2, n) {
+  if (n < 0) throw new Error(`pushVarint: negative input ${n} is not a valid unsigned varint`);
+  while (n > 127) {
+    out2.push(n & 127 | 128);
+    n = Math.floor(n / 128);
+  }
+  out2.push(n & 127);
+}
+function pushTag(out2, field, wire) {
+  pushVarint(out2, field * 8 + wire);
+}
+function pushVarintField(out2, field, n) {
+  pushTag(out2, field, 0);
+  pushVarint(out2, n);
+}
+function pushLenDelim(out2, field, payload) {
+  pushTag(out2, field, 2);
+  pushVarint(out2, payload.length);
+  for (let i2 = 0; i2 < payload.length; i2++) out2.push(payload[i2]);
+}
+function pushString(out2, field, s) {
+  pushLenDelim(out2, field, utf8.encode(s));
+}
+function pushPackedInt32(out2, field, values) {
+  const payload = [];
+  for (const v of values) pushVarint(payload, v);
+  pushLenDelim(out2, field, payload);
+}
+var F_INDEX_METADATA = 1;
+var F_INDEX_DOCUMENTS = 2;
+var F_META_TOOL_INFO = 2;
+var F_META_PROJECT_ROOT = 3;
+var F_META_TEXT_ENCODING = 4;
+var F_TOOL_NAME = 1;
+var F_TOOL_VERSION = 2;
+var F_DOC_RELPATH = 1;
+var F_DOC_OCCURRENCES = 2;
+var F_DOC_SYMBOLS = 3;
+var F_DOC_LANGUAGE = 4;
+var F_DOC_POSITION_ENCODING = 6;
+var F_OCC_RANGE = 1;
+var F_OCC_SYMBOL = 2;
+var F_OCC_ROLES = 3;
+var F_SI_SYMBOL = 1;
+var F_SI_KIND = 5;
+var F_SI_DISPLAY_NAME = 6;
+var F_SI_ENCLOSING = 8;
+var TEXT_ENCODING_UTF8 = 1;
+var ROLE_DEFINITION = 1;
+var POSITION_ENCODING_UTF16 = 2;
+var KIND = {
+  function: 17,
+  // Function
+  method: 26,
+  // Method
+  class: 7,
+  // Class
+  interface: 21,
+  // Interface
+  enum: 11,
+  // Enum
+  struct: 49,
+  // Struct
+  trait: 53,
+  // Trait
+  type: 54,
+  // Type
+  const: 8,
+  // Constant
+  var: 61
+  // Variable
+};
+var SYMBOL_PREFIX = "codeindex . . . ";
+var SIMPLE_ID = /^[A-Za-z0-9_+\-$]+$/;
+function escapeId(name2) {
+  return SIMPLE_ID.test(name2) ? name2 : "`" + name2.replace(/`/g, "``") + "`";
+}
+function fileNamespace(rel) {
+  return "`" + rel.replace(/`/g, "``") + "`/";
+}
+function parentDescriptor(parent) {
+  return escapeId(parent) + "#";
+}
+var TYPE_KINDS = /* @__PURE__ */ new Set(["class", "interface", "enum", "struct", "trait", "type"]);
+var METHOD_KINDS = /* @__PURE__ */ new Set(["function", "method", "def"]);
+function suffixFor(kind) {
+  if (TYPE_KINDS.has(kind)) return "#";
+  if (METHOD_KINDS.has(kind)) return "().";
+  return ".";
+}
+function baseSymbol(rel, sym) {
+  let s = SYMBOL_PREFIX + fileNamespace(rel);
+  if (sym.parent) s += parentDescriptor(sym.parent);
+  return s + escapeId(sym.name) + suffixFor(sym.kind);
+}
+function enclosingSymbolOf(rel, parent) {
+  return SYMBOL_PREFIX + fileNamespace(rel) + parentDescriptor(parent);
+}
+function makeUnique(base, line, used) {
+  if (!used.has(base)) {
+    used.add(base);
+    return base;
+  }
+  for (let n = 0; ; n++) {
+    const disambiguator = n === 0 ? String(line) : `${line}_${n}`;
+    const cand = `${base}(${disambiguator})`;
+    if (!used.has(cand)) {
+      used.add(cand);
+      return cand;
+    }
+  }
+}
+function familyOf2(lang) {
+  if (lang === "typescript" || lang === "javascript") return "js";
+  if (lang === "c" || lang === "cpp") return "c";
+  return lang;
+}
+var REFERENCE_KINDS5 = /* @__PURE__ */ new Set(["reexport", "reexport-all", "default"]);
+function isIdentByte(code) {
+  return code >= 48 && code <= 57 || // 0-9
+  code >= 65 && code <= 90 || // A-Z
+  code >= 97 && code <= 122 || // a-z
+  code === 95 || // _
+  code === 36;
+}
+function findWord(line, name2) {
+  if (!name2) return null;
+  const wordy = /^[A-Za-z_$][\w$]*$/.test(name2);
+  let from = 0;
+  for (; ; ) {
+    const idx = line.indexOf(name2, from);
+    if (idx < 0) return null;
+    if (!wordy) return [idx, idx + name2.length];
+    const before = idx > 0 ? line.charCodeAt(idx - 1) : -1;
+    const afterIdx = idx + name2.length;
+    const after = afterIdx < line.length ? line.charCodeAt(afterIdx) : -1;
+    if (!isIdentByte(before) && !isIdentByte(after)) return [idx, idx + name2.length];
+    from = idx + 1;
+  }
+}
+function renderScip(scan2, opts = {}) {
+  const projectRoot = opts.projectRoot ?? "file://" + scan2.root.replace(/\\/g, "/");
+  const docs = scan2.files.filter((f) => f.kind === "code" && f.symbols.length > 0);
+  const docDefs = /* @__PURE__ */ new Map();
+  const defByName = /* @__PURE__ */ new Map();
+  for (const f of docs) {
+    const used = /* @__PURE__ */ new Set();
+    const entries = [];
+    for (const sym of f.symbols) {
+      const symbolString = makeUnique(baseSymbol(f.rel, sym), sym.line, used);
+      entries.push({ sym, symbolString });
+      if (sym.exported && !REFERENCE_KINDS5.has(sym.kind)) {
+        let arr = defByName.get(sym.name);
+        if (!arr) defByName.set(sym.name, arr = []);
+        arr.push({ symbolString, family: familyOf2(sym.lang) });
+      }
+    }
+    docDefs.set(f.rel, entries);
+  }
+  const resolveRef = (name2, callerFamily) => {
+    const cands = defByName.get(name2);
+    if (!cands || cands.length !== 1) return void 0;
+    const only = cands[0];
+    return only.family === callerFamily ? only.symbolString : void 0;
+  };
+  const documents = [];
+  for (const f of docs) {
+    const text = readText(join9(scan2.root, f.rel));
+    const lines = text.split("\n").map((l) => l.endsWith("\r") ? l.slice(0, -1) : l);
+    const locate = (lineNo, name2) => {
+      const line = lines[lineNo - 1];
+      if (line === void 0) return [lineNo - 1, 0, 0];
+      const r = findWord(line, name2);
+      return r ? [lineNo - 1, r[0], r[1]] : [lineNo - 1, 0, line.length];
+    };
+    const entries = docDefs.get(f.rel);
+    const occs = [];
+    for (const { sym, symbolString } of entries) {
+      occs.push({ range: locate(sym.line, sym.name), symbol: symbolString, roles: ROLE_DEFINITION });
+    }
+    const callerFamily = familyOf2(f.lang);
+    for (const c2 of f.calls ?? []) {
+      const target = resolveRef(c2.name, callerFamily);
+      if (!target) continue;
+      occs.push({ range: locate(c2.line, c2.name), symbol: target, roles: 0 });
+    }
+    occs.sort(
+      (a, b) => a.range[0] - b.range[0] || a.range[1] - b.range[1] || a.range[2] - b.range[2] || a.roles - b.roles || byStr(a.symbol, b.symbol)
+    );
+    const seenOcc = /* @__PURE__ */ new Set();
+    const infos = entries.map(({ sym, symbolString }) => ({
+      symbol: symbolString,
+      displayName: sym.name,
+      kind: KIND[sym.kind],
+      enclosing: sym.parent ? enclosingSymbolOf(f.rel, sym.parent) : void 0
+    })).sort((a, b) => byStr(a.symbol, b.symbol));
+    const doc = [];
+    pushString(doc, F_DOC_RELPATH, f.rel);
+    for (const o of occs) {
+      const key = `${o.range.join(",")} ${o.roles} ${o.symbol}`;
+      if (seenOcc.has(key)) continue;
+      seenOcc.add(key);
+      const ob = [];
+      pushPackedInt32(ob, F_OCC_RANGE, o.range);
+      pushString(ob, F_OCC_SYMBOL, o.symbol);
+      if (o.roles !== 0) pushVarintField(ob, F_OCC_ROLES, o.roles);
+      pushLenDelim(doc, F_DOC_OCCURRENCES, ob);
+    }
+    for (const si of infos) {
+      const sb = [];
+      pushString(sb, F_SI_SYMBOL, si.symbol);
+      if (si.kind !== void 0) pushVarintField(sb, F_SI_KIND, si.kind);
+      pushString(sb, F_SI_DISPLAY_NAME, si.displayName);
+      if (si.enclosing) pushString(sb, F_SI_ENCLOSING, si.enclosing);
+      pushLenDelim(doc, F_DOC_SYMBOLS, sb);
+    }
+    pushString(doc, F_DOC_LANGUAGE, f.lang);
+    pushVarintField(doc, F_DOC_POSITION_ENCODING, POSITION_ENCODING_UTF16);
+    documents.push(doc);
+  }
+  const toolInfo = [];
+  pushString(toolInfo, F_TOOL_NAME, "codeindex");
+  pushString(toolInfo, F_TOOL_VERSION, ENGINE_VERSION);
+  const metadata2 = [];
+  pushLenDelim(metadata2, F_META_TOOL_INFO, toolInfo);
+  pushString(metadata2, F_META_PROJECT_ROOT, projectRoot);
+  pushVarintField(metadata2, F_META_TEXT_ENCODING, TEXT_ENCODING_UTF8);
+  const index = [];
+  pushLenDelim(index, F_INDEX_METADATA, metadata2);
+  for (const d of documents) pushLenDelim(index, F_INDEX_DOCUMENTS, d);
+  return Uint8Array.from(index);
+}
+
+// src/engine.ts
 init_pipeline();
 init_git();
 init_grep();
@@ -10307,6 +10548,8 @@ init_loader();
 init_pipeline();
 init_graph_json();
 init_symbols_json();
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+import { join as join11, resolve } from "path";
 init_scan();
 init_callers();
 init_workspaces();
@@ -10319,8 +10562,6 @@ init_complexity();
 init_viz();
 init_bm25();
 init_rules();
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
-import { join as join10, resolve } from "path";
 var HELP = `codeindex engine v${ENGINE_VERSION} \u2014 deterministic repo indexing
 
 Usage: engine.mjs <command> [flags]
@@ -10331,6 +10572,8 @@ Commands:
   scan        Scan summary: file count, language histogram, capped flag
   graph       Full link-graph (graph.json bytes) to stdout or --out
   symbols     Symbol index (symbols.json bytes) to stdout or --out
+  scip        SCIP code-intelligence index (protobuf bytes) into --out
+              (default index.scip; --out - writes to stdout)
   callers     Per-symbol caller index (JSON)
   workspaces  Monorepo packages + dependency graph (JSON)
   churn       Per-file git commit counts (JSON; --since <ref> to bound)
@@ -10349,7 +10592,10 @@ Commands:
 
 Flags:
   --repo <dir>        Repo root (default: cwd)
-  --out <file>        Write output to a file instead of stdout
+  --out <file>        Write output to a file instead of stdout (\`scip\`: --out -
+                      writes the binary index to stdout)
+  --project-root <uri> \`scip\`: override Metadata.project_root (default
+                      file://<repo>); pin it for a byte-reproducible index
   --include <glob>    Only include matching paths (repeatable)
   --exclude <glob>    Exclude matching paths (repeatable)
   --scope <dir>       Restrict to one directory (sugar for --include '<dir>/**')
@@ -10379,7 +10625,10 @@ function parseFlags(args2) {
       return n;
     };
     if (a === "--repo") flags2.repo = resolve(next());
-    else if (a === "--out") flags2.out = resolve(next());
+    else if (a === "--out") {
+      const v = next();
+      flags2.out = v === "-" ? "-" : resolve(v);
+    } else if (a === "--project-root") flags2.projectRoot = next();
     else if (a === "--include") flags2.include.push(next());
     else if (a === "--exclude") flags2.exclude.push(next());
     else if (a === "--scope") flags2.scope = next();
@@ -10435,7 +10684,7 @@ async function runCli(argv) {
     if (!flags2.out) throw new Error("index needs --out <dir>");
     const outDir = flags2.out;
     mkdirSync2(outDir, { recursive: true });
-    const cachePath = join10(outDir, "cache.json");
+    const cachePath = join11(outDir, "cache.json");
     let cache;
     try {
       const parsed = JSON.parse(readFileSync5(cachePath, "utf8"));
@@ -10445,8 +10694,8 @@ async function runCli(argv) {
     } catch {
     }
     const { scan: scan2, graph, symbols } = buildIndexArtifacts(flags2.repo, { ...scanOptions(flags2), cache, out: outDir });
-    writeFileSync3(join10(outDir, "graph.json"), renderGraphJson(graph));
-    writeFileSync3(join10(outDir, "symbols.json"), renderSymbolsJson(symbols));
+    writeFileSync3(join11(outDir, "graph.json"), renderGraphJson(graph));
+    writeFileSync3(join11(outDir, "symbols.json"), renderSymbolsJson(symbols));
     const files = {};
     for (const f of scan2.files) {
       const entry = { hash: f.hash, record: f, size: f.size };
@@ -10476,6 +10725,16 @@ async function runCli(argv) {
   } else if (cmd === "symbols") {
     const { symbols } = buildIndexArtifacts(flags2.repo, scanOptions(flags2));
     emit(renderSymbolsJson(symbols), flags2.out);
+  } else if (cmd === "scip") {
+    const scan2 = scanRepo(flags2.repo, scanOptions(flags2));
+    const bytes = renderScip(scan2, { projectRoot: flags2.projectRoot });
+    const out2 = flags2.out ?? resolve("index.scip");
+    if (out2 === "-") process.stdout.write(Buffer.from(bytes));
+    else {
+      writeFileSync3(out2, bytes);
+      process.stderr.write(`codeindex: SCIP index \u2192 ${out2} (${bytes.length} bytes)
+`);
+    }
   } else if (cmd === "callers") {
     const scan2 = scanRepo(flags2.repo, scanOptions(flags2));
     const index = buildCallerIndex(scan2, void 0, { recall: flags2.recall });
@@ -10624,6 +10883,7 @@ export {
   renderGraphJson,
   renderMermaid,
   renderRepoMap,
+  renderScip,
   renderSymbolsJson,
   replaceSymbolBody,
   resolveBaseRef,

package/src/engine-cli.ts

@@ -6,6 +6,7 @@ import { ensureGrammars, allGrammarKeys } from "./ast/loader.js";
 import { buildIndexArtifacts, type BuildIndexOptions } from "./pipeline.js";
 import { renderGraphJson } from "./render/graph-json.js";
 import { renderSymbolsJson } from "./render/symbols-json.js";
+import { renderScip } from "./render/scip.js";
 import { scanRepo } from "./scan.js";
 import { buildCallerIndex } from "./callers.js";
 import { detectWorkspaces } from "./workspaces.js";
@@ -29,6 +30,8 @@ Commands:
   scan        Scan summary: file count, language histogram, capped flag
   graph       Full link-graph (graph.json bytes) to stdout or --out
   symbols     Symbol index (symbols.json bytes) to stdout or --out
+  scip        SCIP code-intelligence index (protobuf bytes) into --out
+              (default index.scip; --out - writes to stdout)
   callers     Per-symbol caller index (JSON)
   workspaces  Monorepo packages + dependency graph (JSON)
   churn       Per-file git commit counts (JSON; --since <ref> to bound)
@@ -47,7 +50,10 @@ Commands:
 
 Flags:
   --repo <dir>        Repo root (default: cwd)
-  --out <file>        Write output to a file instead of stdout
+  --out <file>        Write output to a file instead of stdout (\`scip\`: --out -
+                      writes the binary index to stdout)
+  --project-root <uri> \`scip\`: override Metadata.project_root (default
+                      file://<repo>); pin it for a byte-reproducible index
   --include <glob>    Only include matching paths (repeatable)
   --exclude <glob>    Exclude matching paths (repeatable)
   --scope <dir>       Restrict to one directory (sugar for --include '<dir>/**')
@@ -79,6 +85,7 @@ interface CliFlags {
   config?: string; // rules config path
   limit?: number; // search result cap
   recall?: boolean; // callers: recall-oriented binding
+  projectRoot?: string; // scip: override Metadata.project_root
   positional?: string; // e.g. the grep pattern or search query
 }
 
@@ -98,7 +105,10 @@ function parseFlags(args: string[]): CliFlags {
       return n;
     };
     if (a === "--repo") flags.repo = resolve(next());
-    else if (a === "--out") flags.out = resolve(next());
+    else if (a === "--out") {
+      const v = next();
+      flags.out = v === "-" ? "-" : resolve(v); // "-" = stdout (scip binary)
+    } else if (a === "--project-root") flags.projectRoot = next();
     else if (a === "--include") flags.include.push(next());
     else if (a === "--exclude") flags.exclude.push(next());
     else if (a === "--scope") flags.scope = next();
@@ -206,6 +216,15 @@ export async function runCli(argv: string[]): Promise<void> {
   } else if (cmd === "symbols") {
     const { symbols } = buildIndexArtifacts(flags.repo, scanOptions(flags));
     emit(renderSymbolsJson(symbols), flags.out);
+  } else if (cmd === "scip") {
+    const scan = scanRepo(flags.repo, scanOptions(flags));
+    const bytes = renderScip(scan, { projectRoot: flags.projectRoot });
+    const out = flags.out ?? resolve("index.scip");
+    if (out === "-") process.stdout.write(Buffer.from(bytes));
+    else {
+      writeFileSync(out, bytes);
+      process.stderr.write(`codeindex: SCIP index → ${out} (${bytes.length} bytes)\n`);
+    }
   } else if (cmd === "callers") {
     const scan = scanRepo(flags.repo, scanOptions(flags));
     const index = buildCallerIndex(scan, undefined, { recall: flags.recall });

package/src/engine.ts

@@ -75,6 +75,8 @@ export { computeSurprises, isSurprising } from "./surprise.js";
 // Symbol index + machine renderers (render-to-string; consumers own persistence).
 export { buildSymbolIndex, computeSymbolRefs, renderSymbolsJson } from "./render/symbols-json.js";
 export { renderGraphJson } from "./render/graph-json.js";
+export { renderScip } from "./render/scip.js";
+export type { RenderScipOptions } from "./render/scip.js";
 
 // One-call pipeline.
 export { buildIndexArtifacts } from "./pipeline.js";

package/src/render/scip.ts

@@ -0,0 +1,369 @@
+// SCIP index export — a hand-rolled, zero-dependency protobuf wire-format
+// encoder plus the codeindex→SCIP mapping and `renderScip`.
+//
+// Every field number and enum value below is copied VERBATIM from the pinned
+// scip.proto (never guessed):
+//   https://raw.githubusercontent.com/sourcegraph/scip/44d39fcfc95486d066a796e2cec8c7ec5d429aae/scip.proto
+//   sourcegraph/scip @ 44d39fcfc95486d066a796e2cec8c7ec5d429aae
+//
+// Scope: we emit the classic packed `Occurrence.range` (field 1) that
+// scip-typescript emits and that `scip stats`/`scip lint` read; the typed
+// single/multi-line ranges (fields 8-11) are deliberately out of scope. The
+// symbol grammar (scheme/package/descriptors and the suffixes `/` namespace,
+// `#` type, `.` term, `().` method) is taken from the `Symbol` message comment.
+
+import { join } from "node:path";
+import { ENGINE_VERSION } from "../types.js";
+import type { CodeSymbol } from "../types.js";
+import type { RepoScan } from "../scan.js";
+import { readText } from "../walk.js";
+import { byStr } from "../sort.js";
+
+export interface RenderScipOptions {
+  // URI-encoded absolute path to the index root (SCIP `Metadata.project_root`).
+  // Overridable so a build is byte-reproducible regardless of the machine's
+  // checkout path; defaults to `file://` + the posix repo root.
+  projectRoot?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Protobuf wire-format primitives (proto3). Messages are assembled as plain
+// number[] byte buffers and embedded into their parent as length-delimited
+// (wire type 2). Only the two wire types we use are implemented: varint (0)
+// and length-delimited (2).
+// ---------------------------------------------------------------------------
+type Bytes = number[];
+const utf8 = new TextEncoder();
+
+// Unsigned LEB128. Every value we encode (field tags, enum values, ranges,
+// sub-message byte lengths) is a small non-negative integer well under 2^31.
+function pushVarint(out: Bytes, n: number): void {
+  if (n < 0) throw new Error(`pushVarint: negative input ${n} is not a valid unsigned varint`);
+  while (n > 0x7f) {
+    out.push((n & 0x7f) | 0x80);
+    n = Math.floor(n / 128);
+  }
+  out.push(n & 0x7f);
+}
+
+function pushTag(out: Bytes, field: number, wire: number): void {
+  pushVarint(out, field * 8 + wire);
+}
+
+function pushVarintField(out: Bytes, field: number, n: number): void {
+  pushTag(out, field, 0);
+  pushVarint(out, n);
+}
+
+function pushLenDelim(out: Bytes, field: number, payload: ArrayLike<number>): void {
+  pushTag(out, field, 2);
+  pushVarint(out, payload.length);
+  for (let i = 0; i < payload.length; i++) out.push(payload[i]!);
+}
+
+function pushString(out: Bytes, field: number, s: string): void {
+  pushLenDelim(out, field, utf8.encode(s));
+}
+
+// A `repeated int32` in packed encoding: a single length-delimited blob holding
+// the concatenated varints of every element (this is the piece the plain
+// per-element encoding would get wrong).
+function pushPackedInt32(out: Bytes, field: number, values: number[]): void {
+  const payload: Bytes = [];
+  for (const v of values) pushVarint(payload, v);
+  pushLenDelim(out, field, payload);
+}
+
+// ---------------------------------------------------------------------------
+// Pinned scip.proto field numbers & enum values (SHA 44d39fc…).
+// ---------------------------------------------------------------------------
+const F_INDEX_METADATA = 1;
+const F_INDEX_DOCUMENTS = 2; // Index.external_symbols = 3 (unused — always empty)
+const F_META_TOOL_INFO = 2; // Metadata.version = 1 is UnspecifiedProtocolVersion(0), omitted
+const F_META_PROJECT_ROOT = 3;
+const F_META_TEXT_ENCODING = 4;
+const F_TOOL_NAME = 1;
+const F_TOOL_VERSION = 2;
+const F_DOC_RELPATH = 1;
+const F_DOC_OCCURRENCES = 2;
+const F_DOC_SYMBOLS = 3;
+const F_DOC_LANGUAGE = 4;
+const F_DOC_POSITION_ENCODING = 6; // Document.position_encoding = 6 (Document.text = 5 is unused — we never embed source text)
+const F_OCC_RANGE = 1;
+const F_OCC_SYMBOL = 2;
+const F_OCC_ROLES = 3;
+const F_SI_SYMBOL = 1;
+const F_SI_KIND = 5;
+const F_SI_DISPLAY_NAME = 6;
+const F_SI_ENCLOSING = 8;
+
+const TEXT_ENCODING_UTF8 = 1; // TextEncoding.UTF8
+const ROLE_DEFINITION = 0x1; // SymbolRole.Definition (a reference omits the field → 0)
+
+// PositionEncoding.UTF16CodeUnitOffsetFromLineStart = 2. `locate`/`findWord`
+// below compute range offsets with JS string `indexOf`/`.length`, i.e. UTF-16
+// code units — this is the encoding that matches that computation (NOT
+// Metadata.text_document_encoding, which is the on-disk file encoding and is
+// unrelated to how `character` offsets in ranges are interpreted).
+const POSITION_ENCODING_UTF16 = 2; // PositionEncoding.UTF16CodeUnitOffsetFromLineStart
+
+// SymbolInformation.Kind — only the codeindex kinds we can map; anything else
+// leaves the field unset (UnspecifiedKind = 0).
+const KIND: Record<string, number> = {
+  function: 17, // Function
+  method: 26, // Method
+  class: 7, // Class
+  interface: 21, // Interface
+  enum: 11, // Enum
+  struct: 49, // Struct
+  trait: 53, // Trait
+  type: 54, // Type
+  const: 8, // Constant
+  var: 61, // Variable
+};
+
+// ---------------------------------------------------------------------------
+// SCIP symbol strings (the `Symbol` grammar). Local, minimal scheme:
+//   <scheme:codeindex> ' ' <manager:.> ' ' <package-name:.> ' ' <version:.> ' ' <descriptors>
+// Descriptors: the file path as a backtick-escaped namespace, an optional parent
+// type descriptor, then the symbol with a kind-dependent suffix.
+// ---------------------------------------------------------------------------
+const SYMBOL_PREFIX = "codeindex . . . ";
+const SIMPLE_ID = /^[A-Za-z0-9_+\-$]+$/; // <identifier-character> = _ + - $ letters digits
+
+function escapeId(name: string): string {
+  // A simple-identifier is used as-is; anything else is a backtick-escaped
+  // identifier (backticks doubled).
+  return SIMPLE_ID.test(name) ? name : "`" + name.replace(/`/g, "``") + "`";
+}
+
+function fileNamespace(rel: string): string {
+  // A repo path always contains '/' (and usually '.') so it is never a
+  // simple-identifier — always backtick-escape, then the namespace suffix '/'.
+  return "`" + rel.replace(/`/g, "``") + "`/";
+}
+
+// Enclosing members hang off their parent, which we model as a type descriptor.
+function parentDescriptor(parent: string): string {
+  return escapeId(parent) + "#";
+}
+
+const TYPE_KINDS = new Set(["class", "interface", "enum", "struct", "trait", "type"]);
+const METHOD_KINDS = new Set(["function", "method", "def"]);
+
+function suffixFor(kind: string): string {
+  if (TYPE_KINDS.has(kind)) return "#"; // <type>
+  if (METHOD_KINDS.has(kind)) return "()."; // <method>
+  return "."; // <term> — const/var/reexport/… default
+}
+
+function baseSymbol(rel: string, sym: CodeSymbol): string {
+  let s = SYMBOL_PREFIX + fileNamespace(rel);
+  if (sym.parent) s += parentDescriptor(sym.parent);
+  return s + escapeId(sym.name) + suffixFor(sym.kind);
+}
+
+function enclosingSymbolOf(rel: string, parent: string): string {
+  return SYMBOL_PREFIX + fileNamespace(rel) + parentDescriptor(parent);
+}
+
+// Guarantee a unique symbol string per document. On a same name+kind collision
+// we append a `(<disambiguator>)` parameter descriptor — grammar-valid after any
+// suffix (type/term/method) and deterministic (seeded by the declaration line).
+function makeUnique(base: string, line: number, used: Set<string>): string {
+  if (!used.has(base)) {
+    used.add(base);
+    return base;
+  }
+  for (let n = 0; ; n++) {
+    const disambiguator = n === 0 ? String(line) : `${line}_${n}`;
+    const cand = `${base}(${disambiguator})`;
+    if (!used.has(cand)) {
+      used.add(cand);
+      return cand;
+    }
+  }
+}
+
+// Collapse TS/JS and C/C++ into one family so a reference never binds across
+// unrelated languages (mirrors calls.ts `familyOf`).
+function familyOf(lang: string): string {
+  if (lang === "typescript" || lang === "javascript") return "js";
+  if (lang === "c" || lang === "cpp") return "c";
+  return lang;
+}
+
+// A barrel re-export / default alias is a reference to a symbol declared
+// elsewhere — never a call target (mirrors calls.ts REFERENCE_KINDS).
+const REFERENCE_KINDS = new Set(["reexport", "reexport-all", "default"]);
+
+// ---------------------------------------------------------------------------
+// Range location. CodeSymbol has no columns, so we re-read each file once and
+// locate the name on its declaration line. Deterministic: same content → same
+// bytes.
+// ---------------------------------------------------------------------------
+function isIdentByte(code: number): boolean {
+  return (
+    (code >= 48 && code <= 57) || // 0-9
+    (code >= 65 && code <= 90) || // A-Z
+    (code >= 97 && code <= 122) || // a-z
+    code === 95 || // _
+    code === 36 // $
+  );
+}
+
+// [startChar, endChar) of `name` on `line`, preferring a whole-word match for a
+// trivial identifier; null when not found.
+function findWord(line: string, name: string): [number, number] | null {
+  if (!name) return null;
+  const wordy = /^[A-Za-z_$][\w$]*$/.test(name);
+  let from = 0;
+  for (;;) {
+    const idx = line.indexOf(name, from);
+    if (idx < 0) return null;
+    if (!wordy) return [idx, idx + name.length];
+    const before = idx > 0 ? line.charCodeAt(idx - 1) : -1;
+    const afterIdx = idx + name.length;
+    const after = afterIdx < line.length ? line.charCodeAt(afterIdx) : -1;
+    if (!isIdentByte(before) && !isIdentByte(after)) return [idx, idx + name.length];
+    from = idx + 1;
+  }
+}
+
+interface Occ {
+  range: number[]; // [line0, startChar, endChar]
+  symbol: string;
+  roles: number; // 0 = reference, ROLE_DEFINITION = definition
+}
+
+interface DefEntry {
+  sym: CodeSymbol;
+  symbolString: string;
+}
+
+// ---------------------------------------------------------------------------
+// renderScip — map a RepoScan to a SCIP Index and encode it to bytes.
+// ---------------------------------------------------------------------------
+export function renderScip(scan: RepoScan, opts: RenderScipOptions = {}): Uint8Array {
+  const projectRoot = opts.projectRoot ?? "file://" + scan.root.replace(/\\/g, "/");
+
+  // One Document per `code` file that declares ≥1 symbol, in scan order (already
+  // sorted by rel).
+  const docs = scan.files.filter((f) => f.kind === "code" && f.symbols.length > 0);
+
+  // Pass 1 — assign every symbol its final (per-document-unique) symbol string,
+  // and index the exported, non-reference-kind defs by name so references can be
+  // resolved against globally-unique names.
+  const docDefs = new Map<string, DefEntry[]>();
+  const defByName = new Map<string, { symbolString: string; family: string }[]>();
+  for (const f of docs) {
+    const used = new Set<string>();
+    const entries: DefEntry[] = [];
+    for (const sym of f.symbols) {
+      const symbolString = makeUnique(baseSymbol(f.rel, sym), sym.line, used);
+      entries.push({ sym, symbolString });
+      if (sym.exported && !REFERENCE_KINDS.has(sym.kind)) {
+        let arr = defByName.get(sym.name);
+        if (!arr) defByName.set(sym.name, (arr = []));
+        arr.push({ symbolString, family: familyOf(sym.lang) });
+      }
+    }
+    docDefs.set(f.rel, entries);
+  }
+
+  // A call resolves to a reference only when the name is defined exactly once in
+  // the whole index and in the caller's language family (conservative, like
+  // resolveCallEdges — ambiguous names are skipped).
+  const resolveRef = (name: string, callerFamily: string): string | undefined => {
+    const cands = defByName.get(name);
+    if (!cands || cands.length !== 1) return undefined;
+    const only = cands[0]!;
+    return only.family === callerFamily ? only.symbolString : undefined;
+  };
+
+  // Pass 2 — encode each Document.
+  const documents: Bytes[] = [];
+  for (const f of docs) {
+    const text = readText(join(scan.root, f.rel));
+    const lines = text.split("\n").map((l) => (l.endsWith("\r") ? l.slice(0, -1) : l));
+    const locate = (lineNo: number, name: string): number[] => {
+      const line = lines[lineNo - 1];
+      if (line === undefined) return [lineNo - 1, 0, 0];
+      const r = findWord(line, name);
+      return r ? [lineNo - 1, r[0], r[1]] : [lineNo - 1, 0, line.length];
+    };
+
+    const entries = docDefs.get(f.rel)!;
+    const occs: Occ[] = [];
+    for (const { sym, symbolString } of entries) {
+      occs.push({ range: locate(sym.line, sym.name), symbol: symbolString, roles: ROLE_DEFINITION });
+    }
+    const callerFamily = familyOf(f.lang);
+    for (const c of f.calls ?? []) {
+      const target = resolveRef(c.name, callerFamily);
+      if (!target) continue;
+      occs.push({ range: locate(c.line, c.name), symbol: target, roles: 0 });
+    }
+    // Deterministic occurrence order + dedupe of exact duplicates.
+    occs.sort(
+      (a, b) =>
+        a.range[0]! - b.range[0]! ||
+        a.range[1]! - b.range[1]! ||
+        a.range[2]! - b.range[2]! ||
+        a.roles - b.roles ||
+        byStr(a.symbol, b.symbol),
+    );
+    const seenOcc = new Set<string>();
+
+    // One SymbolInformation per definition, sorted by symbol string.
+    const infos = entries
+      .map(({ sym, symbolString }) => ({
+        symbol: symbolString,
+        displayName: sym.name,
+        kind: KIND[sym.kind],
+        enclosing: sym.parent ? enclosingSymbolOf(f.rel, sym.parent) : undefined,
+      }))
+      .sort((a, b) => byStr(a.symbol, b.symbol));
+
+    const doc: Bytes = [];
+    pushString(doc, F_DOC_RELPATH, f.rel);
+    for (const o of occs) {
+      const key = `${o.range.join(",")} ${o.roles} ${o.symbol}`;
+      if (seenOcc.has(key)) continue;
+      seenOcc.add(key);
+      const ob: Bytes = [];
+      pushPackedInt32(ob, F_OCC_RANGE, o.range);
+      pushString(ob, F_OCC_SYMBOL, o.symbol);
+      if (o.roles !== 0) pushVarintField(ob, F_OCC_ROLES, o.roles);
+      pushLenDelim(doc, F_DOC_OCCURRENCES, ob);
+    }
+    for (const si of infos) {
+      const sb: Bytes = [];
+      pushString(sb, F_SI_SYMBOL, si.symbol);
+      if (si.kind !== undefined) pushVarintField(sb, F_SI_KIND, si.kind);
+      pushString(sb, F_SI_DISPLAY_NAME, si.displayName);
+      if (si.enclosing) pushString(sb, F_SI_ENCLOSING, si.enclosing);
+      pushLenDelim(doc, F_DOC_SYMBOLS, sb);
+    }
+    pushString(doc, F_DOC_LANGUAGE, f.lang);
+    pushVarintField(doc, F_DOC_POSITION_ENCODING, POSITION_ENCODING_UTF16);
+    documents.push(doc);
+  }
+
+  // Metadata { tool_info, project_root, text_document_encoding }.
+  const toolInfo: Bytes = [];
+  pushString(toolInfo, F_TOOL_NAME, "codeindex");
+  pushString(toolInfo, F_TOOL_VERSION, ENGINE_VERSION);
+
+  const metadata: Bytes = [];
+  pushLenDelim(metadata, F_META_TOOL_INFO, toolInfo);
+  pushString(metadata, F_META_PROJECT_ROOT, projectRoot);
+  pushVarintField(metadata, F_META_TEXT_ENCODING, TEXT_ENCODING_UTF8);
+
+  // Index { metadata, documents }.
+  const index: Bytes = [];
+  pushLenDelim(index, F_INDEX_METADATA, metadata);
+  for (const d of documents) pushLenDelim(index, F_INDEX_DOCUMENTS, d);
+
+  return Uint8Array.from(index);
+}

package/src/types.ts

@@ -1,7 +1,7 @@
 // Single source of truth for the engine version the bundle reports. Kept in
 // lockstep with package.json by the release pipeline. Do not edit by hand
 // outside a release.
-export const ENGINE_VERSION = "2.7.0";
+export const ENGINE_VERSION = "2.8.0";
 
 // Bumped whenever the on-disk artifact shape changes, so a consumer can reject
 // an index written by an incompatible engine instead of misreading it. The