@samchon/graph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeongho Nam
+
+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,129 @@
+# `@samchon/graph`
+
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/graph/blob/master/LICENSE) [![NPM Version](https://img.shields.io/npm/v/@samchon/graph.svg)](https://www.npmjs.com/package/@samchon/graph) [![NPM Downloads](https://img.shields.io/npm/dm/@samchon/graph.svg)](https://www.npmjs.com/package/@samchon/graph) [![Build Status](https://github.com/samchon/graph/workflows/test/badge.svg)](https://github.com/samchon/graph/actions?query=workflow%3Atest)
+
+**A code graph that answers "how does this repo work?" without your agent reading the repo.**
+
+`@samchon/graph` is an MCP server. It indexes a codebase — across **18 languages** — into a graph of declarations and their relationships, and answers an agent's orientation questions from that graph instead of from source files. The agent gets the map in one call rather than grepping and reading its way through dozens of files.
+
+That collapses the token cost. On a 12-language benchmark it cuts the agent's tokens by a **median of 96%** on onboarding questions — while [`codegraph`](https://github.com/colbymchenry/codegraph) cuts 63% and [`serena`](https://github.com/oraios/serena) makes it *worse*.
+
+![Agent token cost — onboarding, per repository](https://raw.githubusercontent.com/samchon/graph/master/assets/benchmark-common.svg)
+
+## Setup
+
+### 1. Add the MCP server
+
+```bash
+npm install -D @samchon/graph
+```
+
+```json
+{
+  "mcpServers": {
+    "samchon-graph": {
+      "command": "npx",
+      "args": ["-y", "@samchon/graph"]
+    }
+  }
+}
+```
+
+Start the client from the project root. The server builds one resident graph and answers every MCP call from memory. With no language server installed it still works — the **static indexer** parses the source directly (every language indexes in ~1–2 seconds, even on large repositories).
+
+### 2. Install a language server (optional, for compiler-grade edges)
+
+A language server sharpens the graph with semantically-resolved edges. Install the one(s) for your stack — nothing else is auto-provided (an installed editor like VS Code does **not** expose a stdio language server):
+
+| Language | Server | Install |
+|---|---|---|
+| TypeScript / JavaScript | `typescript-language-server` | `npm i -g typescript-language-server typescript` |
+| Python | `pyright-langserver` | `npm i -g pyright` |
+| Go | `gopls` | `go install golang.org/x/tools/gopls@latest` |
+| Rust | `rust-analyzer` | `rustup component add rust-analyzer` |
+| C / C++ | `clangd` | LLVM release, or your package manager |
+| Java | `jdtls` | Eclipse JDT LS (needs JDK 21+) |
+| C# | `csharp-ls` | `dotnet tool install -g csharp-ls` |
+| Kotlin | `kotlin-language-server` | fwcd/kotlin-language-server |
+| Swift | `sourcekit-lsp` | ships with the Swift toolchain |
+| Scala | `metals` | `cs install metals` |
+| Zig | `zls` | zigtools/zls |
+| Ruby | `ruby-lsp` | `gem install ruby-lsp` |
+| PHP | `intelephense` | `npm i -g intelephense` |
+| Lua | `lua-language-server` | LuaLS/lua-language-server |
+| Dart | `dart` | ships with the Dart SDK |
+| Bash | `bash-language-server` | `npm i -g bash-language-server` |
+
+Each server must be on `PATH`. If none is present for a file's language, that language falls back to the static indexer automatically.
+
+### 3. TypeScript / JavaScript — the fast path
+
+The community `typescript-language-server` is an unofficial wrapper over the classic `tsserver` and answers references one symbol at a time. For compiler-grade TS/JS graphs at native speed, point the server at **[`ttscserver`](https://github.com/samchon/ttsc)** (the `typescript-go`–backed LSP host) once it exposes the graph channel — tracked in [samchon/ttsc#335](https://github.com/samchon/ttsc/issues/335) and [#337](https://github.com/samchon/ttsc/issues/337).
+
+## Benchmark
+
+Reproduce the numbers yourself (spends real credits, never wired into CI):
+
+```bash
+pnpm --filter @samchon/graph-benchmark corpus      # 12 repos / 12 languages, pinned
+pnpm --filter @samchon/graph-benchmark preflight   # zero-spend go/no-go
+pnpm --filter @samchon/graph-benchmark suite-codex -- --runs=1
+pnpm --filter @samchon/graph-benchmark render      # results -> SVG charts
+```
+
+## How it works
+
+The whole surface is one tool with one typed contract:
+
+```typescript
+export interface ISamchonGraphApplication {
+  inspect_code_graph(
+    props: ISamchonGraphApplication.IProps,
+  ): Promise<ISamchonGraphApplication.IResult>;
+}
+
+export namespace ISamchonGraphApplication {
+  export interface IProps {
+    question: string; // restate the code question
+    draft: IDraft; //    intended request + why it is smallest
+    review: string; //   correct the draft before committing
+    request:
+      | IGraphTour.IRequest //    broad orientation / runtime flow
+      | IGraphLookup.IRequest //  find a symbol
+      | IGraphTrace.IRequest //   follow a flow
+      | IGraphDetails.IRequest // one symbol's facts
+      | IGraphEntrypoints.IRequest
+      | IGraphOverview.IRequest
+      | IGraphEscape.IRequest; // leave the graph
+  }
+
+  export interface IDraft {
+    reason: string; //                   why this is the smallest useful step
+    type: IProps["request"]["type"]; //  the request type being considered
+  }
+}
+```
+
+The other tools try to change what the agent does by *talking* to it — `serena` swaps in ~150 lines of system prompt, `codegraph` ships ~100 lines plus a skill file, both spent almost entirely on forbidding the agent from grepping anyway. `@samchon/graph` changes the **shape of the tool** instead:
+
+- **One tool, not fifty.** `serena` buries its graph behind ~50 tools and the agent never finds the right one; `@samchon/graph` has exactly one, and a union type — filled in by the chain-of-thought — routes the request by construction instead of by persuasion.
+- **CoT compliance, not a wall of rules.** A required schema field can't be skipped the way a prompt line can be ignored. `props` makes the model write `question` → `draft` → `review` before it may act — so it reasons first, and a `review`/`escape` step catches a wrong turn.
+- **Index facts, not inlined source.** The result is names, signatures, and spans — never pasted file bodies. That is where the tokens actually go: the baseline agent blows its budget dumping source into context, while the graph answers the same question from the index.
+- **It respects the agent, it doesn't cage it.** No "use this instead of Read." It states a condition, then tells the agent where to stop — so the agent reaches for the graph when it should and skips it when it shouldn't.
+
+This is the design proven by the TypeScript-only predecessor, [`@ttsc/graph`](https://ttsc.dev/blog/i-made-ts-compiler-graph-mcp) — the launch post is the full autopsy of why the tools before it don't move the token bill. `@samchon/graph` generalizes it to 18 languages over LSP, with edges built by a single linear pass per file (a 2,000-file repo indexes in **~1.6 seconds**, re-indexed incrementally as source changes).
+
+## Sponsors
+
+[![Sponsors](https://raw.githubusercontent.com/samchon/sponsor-images/refs/heads/master/public/circle.svg)](https://github.com/sponsors/samchon)
+
+Thanks for your support.
+
+Your [donation](https://github.com/sponsors/samchon) encourages `@samchon/graph` development.
+
+## References
+
+- Predecessor: [`@ttsc/graph`](https://github.com/samchon/ttsc) — the TypeScript-only, compiler-powered original this generalizes.
+- Compared against: [`codegraph`](https://github.com/colbymchenry/codegraph) and [`serena`](https://github.com/oraios/serena).
+- Protocol: the [Model Context Protocol](https://modelcontextprotocol.io) and the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/).
+- Validation & MCP surface: [`typia`](https://github.com/samchon/typia) and [`@typia/mcp`](https://github.com/samchon/typia).

package/lib/AsyncSamchonGraphSource.d.ts

@@ -0,0 +1,2 @@
+import { GraphMemory } from "./model/GraphMemory";
+export type AsyncSamchonGraphSource = GraphMemory | (() => GraphMemory | Promise<GraphMemory>);

package/lib/AsyncSamchonGraphSource.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=AsyncSamchonGraphSource.js.map

package/lib/AsyncSamchonGraphSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AsyncSamchonGraphSource.js","sourceRoot":"","sources":["../src/AsyncSamchonGraphSource.ts"],"names":[],"mappings":""}

package/lib/SamchonGraphApplication.d.ts

@@ -0,0 +1,10 @@
+import { AsyncSamchonGraphSource } from "./AsyncSamchonGraphSource";
+import { ISamchonGraphApplication } from "./structures";
+export declare class SamchonGraphApplication implements ISamchonGraphApplication {
+    private readonly graph;
+    private promise?;
+    constructor(source: AsyncSamchonGraphSource);
+    inspect_code_graph(props: ISamchonGraphApplication.IProps): Promise<ISamchonGraphApplication.IResult>;
+    private escape;
+    private load;
+}

package/lib/SamchonGraphApplication.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SamchonGraphApplication = void 0;
+const common_1 = require("./operations/common");
+const runDetails_1 = require("./operations/runDetails");
+const runEntrypoints_1 = require("./operations/runEntrypoints");
+const runLookup_1 = require("./operations/runLookup");
+const runOverview_1 = require("./operations/runOverview");
+const runTour_1 = require("./operations/runTour");
+const runTrace_1 = require("./operations/runTrace");
+class SamchonGraphApplication {
+    graph;
+    promise;
+    constructor(source) {
+        this.graph = typeof source === "function" ? source : () => source;
+    }
+    async inspect_code_graph(props) {
+        const graph = await this.load();
+        switch (props.request.type) {
+            case "entrypoints":
+                return { result: (0, runEntrypoints_1.runEntrypoints)(graph, props.request) };
+            case "lookup":
+                return { result: (0, runLookup_1.runLookup)(graph, props.request) };
+            case "trace":
+                return { result: (0, runTrace_1.runTrace)(graph, props.request) };
+            case "details":
+                return { result: (0, runDetails_1.runDetails)(graph, props.request) };
+            case "overview":
+                return { result: (0, runOverview_1.runOverview)(graph, props.request) };
+            case "tour":
+                return { result: (0, runTour_1.runTour)(graph, props.request) };
+            case "escape":
+                return { result: this.escape(props.request.reason, props.request.nextStep) };
+            default:
+                props.request;
+                throw new Error("Unknown graph request type");
+        }
+    }
+    escape(reason, nextStep) {
+        return {
+            type: "escape",
+            skipped: true,
+            reason,
+            ...(nextStep !== undefined ? { nextStep } : {}),
+            next: (0, common_1.resultNext)("outside", nextStep ?? "Graph evidence is exhausted or not the next evidence source."),
+            guide: (0, common_1.resultGuide)("Finish from existing graph evidence, state the graph gap, or ask for clarification."),
+        };
+    }
+    async load() {
+        // Cache the built graph on success only. Caching a rejected promise would
+        // brick the resident server for the whole session after one transient index
+        // failure (e.g. a slow language-server cold start); clear it so the next
+        // call rebuilds.
+        if (this.promise === undefined) {
+            this.promise = Promise.resolve(this.graph()).catch((error) => {
+                this.promise = undefined;
+                throw error;
+            });
+        }
+        return this.promise;
+    }
+}
+exports.SamchonGraphApplication = SamchonGraphApplication;
+//# sourceMappingURL=SamchonGraphApplication.js.map

package/lib/SamchonGraphApplication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SamchonGraphApplication.js","sourceRoot":"","sources":["../src/SamchonGraphApplication.ts"],"names":[],"mappings":";;;AAEA,gDAA8D;AAC9D,wDAAqD;AACrD,gEAA6D;AAC7D,sDAAmD;AACnD,0DAAuD;AACvD,kDAA+C;AAC/C,oDAAiD;AAGjD;IACmB,KAAK,CAA2C;IACzD,OAAO,CAAwB;IAEvC,YAAmB,MAA+B;QAChD,IAAI,CAAC,KAAK,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC;IACpE,CAAC;IAEM,KAAK,CAAC,kBAAkB,CAC7B,KAAsC;QAEtC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAChC,QAAQ,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAC3B,KAAK,aAAa;gBAChB,OAAO,EAAE,MAAM,EAAE,IAAA,+BAAc,EAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1D,KAAK,QAAQ;gBACX,OAAO,EAAE,MAAM,EAAE,IAAA,qBAAS,EAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACrD,KAAK,OAAO;gBACV,OAAO,EAAE,MAAM,EAAE,IAAA,mBAAQ,EAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACpD,KAAK,SAAS;gBACZ,OAAO,EAAE,MAAM,EAAE,IAAA,uBAAU,EAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACtD,KAAK,UAAU;gBACb,OAAO,EAAE,MAAM,EAAE,IAAA,yBAAW,EAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACvD,KAAK,MAAM;gBACT,OAAO,EAAE,MAAM,EAAE,IAAA,iBAAO,EAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACnD,KAAK,QAAQ;gBACX,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC/E;gBACE,KAAK,CAAC,OAAuB,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,MAAc,EAAE,QAAiB;QAC9C,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,IAAI;YACb,MAAM;YACN,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,IAAI,EAAE,IAAA,mBAAU,EACd,SAAS,EACT,QAAQ,IAAI,8DAA8D,CAC3E;YACD,KAAK,EAAE,IAAA,oBAAW,EAChB,qFAAqF,CACtF;SACF,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,IAAI;QAChB,0EAA0E;QAC1E,4EAA4E;QAC5E,yEAAyE;QACzE,iBAAiB;QACjB,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBACpE,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;gBACzB,MAAM,KAAK,CAAC;YACd,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF"}

package/lib/SamchonGraphSource.d.ts

@@ -0,0 +1,2 @@
+import { GraphMemory } from "./model/GraphMemory";
+export type SamchonGraphSource = GraphMemory | (() => GraphMemory);

package/lib/SamchonGraphSource.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=SamchonGraphSource.js.map

package/lib/SamchonGraphSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SamchonGraphSource.js","sourceRoot":"","sources":["../src/SamchonGraphSource.ts"],"names":[],"mappings":""}

package/lib/application.d.ts

@@ -0,0 +1,3 @@
+export * from "./AsyncSamchonGraphSource";
+export * from "./SamchonGraphApplication";
+export * from "./SamchonGraphSource";

package/lib/application.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./AsyncSamchonGraphSource"), exports);
+__exportStar(require("./SamchonGraphApplication"), exports);
+__exportStar(require("./SamchonGraphSource"), exports);
+//# sourceMappingURL=application.js.map

package/lib/application.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application.js","sourceRoot":"","sources":["../src/application.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4DAA0C;AAC1C,4DAA0C;AAC1C,uDAAqC"}

package/lib/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+const code = (0, index_1.runGraph)(process.argv.slice(2));
+if (typeof code === "number")
+    process.exitCode = code;
+//# sourceMappingURL=bin.js.map

package/lib/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";;;AAEA,mCAAmC;AAEnC,MAAM,IAAI,GAAG,IAAA,gBAAQ,EAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7C,IAAI,OAAO,IAAI,KAAK,QAAQ;IAAE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./application";
+export * from "./indexer/allExtensions";
+export * from "./indexer/buildGraph";
+export * from "./indexer/buildGraphDump";
+export * from "./indexer/IBuildGraphOptions";
+export * from "./indexer/IIndexerResult";
+export * from "./indexer/ILanguageSpec";
+export * from "./indexer/LANGUAGE_SPECS";
+export * from "./indexer/languageOf";
+export * from "./indexer/specOf";
+export * from "./model/GraphMemory";
+export * from "./runGraph";
+export * from "./structures";

package/lib/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./application"), exports);
+__exportStar(require("./indexer/allExtensions"), exports);
+__exportStar(require("./indexer/buildGraph"), exports);
+__exportStar(require("./indexer/buildGraphDump"), exports);
+__exportStar(require("./indexer/IBuildGraphOptions"), exports);
+__exportStar(require("./indexer/IIndexerResult"), exports);
+__exportStar(require("./indexer/ILanguageSpec"), exports);
+__exportStar(require("./indexer/LANGUAGE_SPECS"), exports);
+__exportStar(require("./indexer/languageOf"), exports);
+__exportStar(require("./indexer/specOf"), exports);
+__exportStar(require("./model/GraphMemory"), exports);
+__exportStar(require("./runGraph"), exports);
+__exportStar(require("./structures"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,0DAAwC;AACxC,uDAAqC;AACrC,2DAAyC;AACzC,+DAA6C;AAC7C,2DAAyC;AACzC,0DAAwC;AACxC,2DAAyC;AACzC,uDAAqC;AACrC,mDAAiC;AACjC,sDAAoC;AACpC,6CAA2B;AAC3B,+CAA6B"}

package/lib/indexer/IBuildGraphOptions.d.ts

@@ -0,0 +1,41 @@
+import { GraphLanguage } from "../structures";
+export interface IBuildGraphOptions {
+    cwd?: string;
+    mode?: "auto" | "lsp" | "static";
+    languages?: GraphLanguage[];
+    server?: string;
+    serverArgs?: string[];
+    initializationOptions?: unknown;
+    maxFiles?: number;
+    lspReferenceLimit?: number;
+    lspTimeoutMs?: number;
+    /**
+     * How many `textDocument/references` requests to keep in flight at once.
+     * Reference collection dominates indexing time on large repositories, and the
+     * requests are independent, so they are issued concurrently up to this bound.
+     */
+    lspConcurrency?: number;
+    /**
+     * Maximum time to wait for a language server to finish its initial indexing
+     * (reported through `$/progress`) before collecting references. Servers such
+     * as rust-analyzer, clangd, and jdtls answer reference requests with nothing
+     * until indexing completes, so skipping this wait yields zero edges.
+     */
+    lspReadyTimeoutMs?: number;
+    /**
+     * How long the server must stay silent on `$/progress` before its initial
+     * indexing is treated as settled. Also bounds the wait for servers that never
+     * report progress at all.
+     */
+    lspReadyQuietMs?: number;
+    /**
+     * How long to wait for the FIRST `textDocument/references` request, which may
+     * trigger the server to build its cross-file reference index lazily. Once that
+     * one warmup request returns, later references are cache-fast and use the
+     * normal `lspTimeoutMs`. A timeout here means the server cannot answer
+     * references at all, so only structural edges are kept. Defaults to a patient
+     * budget (slow servers like ruby-lsp need it); fast servers answer instantly
+     * and never reach it.
+     */
+    lspWarmupTimeoutMs?: number;
+}

package/lib/indexer/IBuildGraphOptions.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IBuildGraphOptions.js.map

package/lib/indexer/IBuildGraphOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IBuildGraphOptions.js","sourceRoot":"","sources":["../../src/indexer/IBuildGraphOptions.ts"],"names":[],"mappings":""}

package/lib/indexer/IIndexerResult.d.ts

@@ -0,0 +1,5 @@
+import { IGraphDump } from "../structures";
+export interface IIndexerResult {
+    dump: IGraphDump;
+    warnings: string[];
+}

package/lib/indexer/IIndexerResult.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IIndexerResult.js.map

package/lib/indexer/IIndexerResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IIndexerResult.js","sourceRoot":"","sources":["../../src/indexer/IIndexerResult.ts"],"names":[],"mappings":""}

package/lib/indexer/ILanguageSpec.d.ts

@@ -0,0 +1,10 @@
+import { GraphLanguage } from "../structures";
+export interface ILanguageSpec {
+    language: GraphLanguage;
+    extensions: string[];
+    lsp?: {
+        command: string;
+        args: string[];
+    };
+    lineComment: string;
+}

package/lib/indexer/ILanguageSpec.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ILanguageSpec.js.map

package/lib/indexer/ILanguageSpec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ILanguageSpec.js","sourceRoot":"","sources":["../../src/indexer/ILanguageSpec.ts"],"names":[],"mappings":""}

package/lib/indexer/LANGUAGE_SPECS.d.ts

@@ -0,0 +1,2 @@
+import { ILanguageSpec } from "./ILanguageSpec";
+export declare const LANGUAGE_SPECS: ILanguageSpec[];

package/lib/indexer/LANGUAGE_SPECS.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LANGUAGE_SPECS = void 0;
+exports.LANGUAGE_SPECS = [
+    {
+        language: "typescript",
+        extensions: [".ts", ".tsx", ".mts", ".cts"],
+        lsp: { command: "typescript-language-server", args: ["--stdio"] },
+        lineComment: "//",
+    },
+    {
+        language: "javascript",
+        extensions: [".js", ".jsx", ".mjs", ".cjs"],
+        lsp: { command: "typescript-language-server", args: ["--stdio"] },
+        lineComment: "//",
+    },
+    {
+        language: "go",
+        extensions: [".go"],
+        lsp: { command: "gopls", args: [] },
+        lineComment: "//",
+    },
+    {
+        language: "rust",
+        extensions: [".rs"],
+        lsp: { command: "rust-analyzer", args: [] },
+        lineComment: "//",
+    },
+    {
+        language: "cpp",
+        extensions: [".cc", ".cpp", ".cxx", ".c++", ".hh", ".hpp", ".hxx", ".h++"],
+        lsp: { command: "clangd", args: [] },
+        lineComment: "//",
+    },
+    {
+        language: "c",
+        extensions: [".c", ".h"],
+        lsp: { command: "clangd", args: [] },
+        lineComment: "//",
+    },
+    {
+        language: "java",
+        extensions: [".java"],
+        lsp: { command: "jdtls", args: [] },
+        lineComment: "//",
+    },
+    {
+        language: "csharp",
+        extensions: [".cs"],
+        lsp: { command: "csharp-ls", args: [] },
+        lineComment: "//",
+    },
+    {
+        language: "kotlin",
+        extensions: [".kt", ".kts"],
+        lsp: { command: "kotlin-language-server", args: [] },
+        lineComment: "//",
+    },
+    {
+        language: "swift",
+        extensions: [".swift"],
+        lsp: { command: "sourcekit-lsp", args: [] },
+        lineComment: "//",
+    },
+    {
+        language: "scala",
+        extensions: [".scala", ".sc"],
+        lsp: { command: "metals", args: [] },
+        lineComment: "//",
+    },
+    {
+        language: "zig",
+        extensions: [".zig"],
+        lsp: { command: "zls", args: [] },
+        lineComment: "//",
+    },
+    {
+        language: "python",
+        extensions: [".py", ".pyi"],
+        lsp: { command: "pyright-langserver", args: ["--stdio"] },
+        lineComment: "#",
+    },
+    {
+        language: "ruby",
+        extensions: [".rb", ".rake", ".gemspec"],
+        lsp: { command: "ruby-lsp", args: [] },
+        lineComment: "#",
+    },
+    {
+        language: "php",
+        extensions: [".php", ".phtml"],
+        lsp: { command: "intelephense", args: ["--stdio"] },
+        lineComment: "//",
+    },
+    {
+        language: "lua",
+        extensions: [".lua"],
+        lsp: { command: "lua-language-server", args: [] },
+        lineComment: "--",
+    },
+    {
+        language: "bash",
+        extensions: [".sh", ".bash"],
+        lsp: { command: "bash-language-server", args: ["start"] },
+        lineComment: "#",
+    },
+    {
+        language: "dart",
+        extensions: [".dart"],
+        lsp: { command: "dart", args: ["language-server"] },
+        lineComment: "//",
+    },
+];
+//# sourceMappingURL=LANGUAGE_SPECS.js.map

package/lib/indexer/LANGUAGE_SPECS.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LANGUAGE_SPECS.js","sourceRoot":"","sources":["../../src/indexer/LANGUAGE_SPECS.ts"],"names":[],"mappings":"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"}

package/lib/indexer/allExtensions.d.ts

@@ -0,0 +1,2 @@
+import { GraphLanguage } from "../structures";
+export declare function allExtensions(languages?: readonly GraphLanguage[]): Set<string>;

package/lib/indexer/allExtensions.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allExtensions = allExtensions;
+const LANGUAGE_SPECS_1 = require("./LANGUAGE_SPECS");
+function allExtensions(languages) {
+    const allowed = languages === undefined ? undefined : new Set(languages);
+    const out = new Set();
+    for (const spec of LANGUAGE_SPECS_1.LANGUAGE_SPECS) {
+        if (allowed !== undefined && !allowed.has(spec.language))
+            continue;
+        for (const ext of spec.extensions)
+            out.add(ext);
+    }
+    return out;
+}
+//# sourceMappingURL=allExtensions.js.map

package/lib/indexer/allExtensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allExtensions.js","sourceRoot":"","sources":["../../src/indexer/allExtensions.ts"],"names":[],"mappings":";;;AACA,qDAAkD;AAElD,uBAA8B,SAAoC;IAChE,MAAM,OAAO,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;IACzE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,+BAAc,EAAE,CAAC;QAClC,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC;YAAE,SAAS;QACnE,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/lib/indexer/buildGraph.d.ts

@@ -0,0 +1,3 @@
+import { GraphMemory } from "../model/GraphMemory";
+import { IBuildGraphOptions } from "./IBuildGraphOptions";
+export declare function buildGraph(options?: IBuildGraphOptions): Promise<GraphMemory>;

package/lib/indexer/buildGraph.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildGraph = buildGraph;
+const GraphMemory_1 = require("../model/GraphMemory");
+const buildGraphDump_1 = require("./buildGraphDump");
+async function buildGraph(options = {}) {
+    const dump = await (0, buildGraphDump_1.buildGraphDump)(options);
+    return GraphMemory_1.GraphMemory.from(dump);
+}
+//# sourceMappingURL=buildGraph.js.map

package/lib/indexer/buildGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildGraph.js","sourceRoot":"","sources":["../../src/indexer/buildGraph.ts"],"names":[],"mappings":";;;AAAA,sDAAmD;AACnD,qDAAkD;AAG3C,KAAK,qBACV,OAAO,GAAuB,EAAE;IAEhC,MAAM,IAAI,GAAG,MAAM,IAAA,+BAAc,EAAC,OAAO,CAAC,CAAC;IAC3C,OAAO,yBAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC"}

package/lib/indexer/buildGraphDump.d.ts

@@ -0,0 +1,3 @@
+import { IGraphDump } from "../structures";
+import { IBuildGraphOptions } from "./IBuildGraphOptions";
+export declare function buildGraphDump(options?: IBuildGraphOptions): Promise<IGraphDump>;