@samchon/graph 0.1.0

package/src/lsp/IPosition.ts

@@ -0,0 +1,4 @@
+export interface IPosition {
+  line: number;
+  character: number;
+}

package/src/lsp/IRange.ts

@@ -0,0 +1,6 @@
+import { IPosition } from "./IPosition";
+
+export interface IRange {
+  start: IPosition;
+  end: IPosition;
+}

package/src/lsp/ISymbolInformation.ts

@@ -0,0 +1,8 @@
+import { ILocation } from "./ILocation";
+
+export interface ISymbolInformation {
+  name: string;
+  kind: number;
+  location: ILocation;
+  containerName?: string;
+}

package/src/lsp/LspClient.ts

@@ -0,0 +1,165 @@
+import { ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+
+interface IRequest {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timer: NodeJS.Timeout;
+}
+
+export class LspClient {
+  private readonly process: ChildProcessWithoutNullStreams;
+  private readonly pending = new Map<number, IRequest>();
+  private readonly events = new EventEmitter();
+  private buffer = Buffer.alloc(0);
+  private nextId = 1;
+
+  public constructor(
+    command: string,
+    args: readonly string[],
+    private readonly timeoutMs: number,
+  ) {
+    this.process = spawn(command, [...args], {
+      stdio: "pipe",
+      windowsHide: true,
+    });
+    this.process.stdout.on("data", (chunk: Buffer) => this.onData(chunk));
+    this.process.stderr.on("data", () => {
+      // Language servers often log noisy progress to stderr.
+    });
+    this.process.on("error", (error) => this.rejectAll(error));
+    this.process.on("exit", (code, signal) => {
+      this.rejectAll(
+        new Error(`Language server exited (${code ?? "null"}, ${signal ?? "null"}).`),
+      );
+    });
+  }
+
+  public async request<T>(
+    method: string,
+    params: unknown,
+    timeoutMs?: number,
+  ): Promise<T> {
+    const id = this.nextId++;
+    const payload = { jsonrpc: "2.0", id, method, params };
+    const promise = new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`LSP request timed out: ${method}`));
+      }, timeoutMs ?? this.timeoutMs);
+      this.pending.set(id, {
+        resolve: (value) => resolve(value as T),
+        reject,
+        timer,
+      });
+    });
+    this.write(payload);
+    return promise;
+  }
+
+  public notify(method: string, params: unknown): void {
+    this.write({ jsonrpc: "2.0", method, params });
+  }
+
+  public onNotification(
+    method: string,
+    listener: (params: unknown) => void,
+  ): void {
+    this.events.on(method, listener);
+  }
+
+  public async close(): Promise<void> {
+    try {
+      await this.request("shutdown", null);
+    } catch {
+      // Some servers exit before answering shutdown.
+    }
+    /* c8 ignore start */
+    try {
+      this.notify("exit", null);
+    } catch {
+      // Ignore close errors.
+    }
+    /* c8 ignore stop */
+    if (!this.process.killed) this.process.kill();
+  }
+
+  private write(payload: unknown): void {
+    const body = Buffer.from(JSON.stringify(payload), "utf8");
+    const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, "ascii");
+    this.process.stdin.write(Buffer.concat([header, body]));
+  }
+
+  private onData(chunk: Buffer): void {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    for (;;) {
+      const headerEnd = this.buffer.indexOf("\r\n\r\n");
+      if (headerEnd < 0) return;
+      const header = this.buffer.slice(0, headerEnd).toString("ascii");
+      const match = /Content-Length:\s*(\d+)/i.exec(header);
+      if (match === null) {
+        this.buffer = this.buffer.slice(headerEnd + 4);
+        continue;
+      }
+      const length = Number(match[1]);
+      const bodyStart = headerEnd + 4;
+      const bodyEnd = bodyStart + length;
+      if (this.buffer.length < bodyEnd) return;
+      const body = this.buffer.slice(bodyStart, bodyEnd).toString("utf8");
+      this.buffer = this.buffer.slice(bodyEnd);
+      // A malformed frame must not throw out of the stdout `data` listener as an
+      // uncaught exception; drop it and keep draining the buffer.
+      let message;
+      try {
+        message = JSON.parse(body) as {
+          id?: number;
+          method?: string;
+          params?: unknown;
+          result?: unknown;
+          error?: { message?: string };
+        };
+      } catch {
+        continue;
+      }
+      this.handleMessage(message);
+    }
+  }
+
+  private handleMessage(message: {
+    id?: number;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: { message?: string };
+  }): void {
+    // A server-initiated request carries both an id and a method. It must be
+    // answered or some servers block: gopls, for instance, withholds
+    // documentSymbol until its `window/workDoneProgress/create` request is
+    // acknowledged. A null result satisfies the acknowledgements we advertise.
+    if (message.id !== undefined && message.method !== undefined) {
+      this.write({ jsonrpc: "2.0", id: message.id, result: null });
+      return;
+    }
+    if (message.id !== undefined) {
+      const pending = this.pending.get(message.id);
+      if (pending === undefined) return;
+      this.pending.delete(message.id);
+      clearTimeout(pending.timer);
+      if (message.error !== undefined) {
+        pending.reject(new Error(message.error.message ?? "LSP request failed."));
+      } else {
+        pending.resolve(message.result);
+      }
+      return;
+    }
+    if (message.method !== undefined) this.events.emit(message.method, message.params);
+  }
+
+  private rejectAll(error: Error): void {
+    for (const [id, request] of this.pending) {
+      this.pending.delete(id);
+      clearTimeout(request.timer);
+      request.reject(error);
+    }
+  }
+}

package/src/lsp/isDocumentSymbol.ts

@@ -0,0 +1,8 @@
+import { IDocumentSymbol } from "./IDocumentSymbol";
+import { ISymbolInformation } from "./ISymbolInformation";
+
+export function isDocumentSymbol(
+  value: IDocumentSymbol | ISymbolInformation,
+): value is IDocumentSymbol {
+  return "selectionRange" in value;
+}

package/src/lsp/types.ts

@@ -0,0 +1,8 @@
+export * from "./DocumentSymbolResult";
+export * from "./IDiagnostic";
+export * from "./IDocumentSymbol";
+export * from "./ILocation";
+export * from "./IPosition";
+export * from "./IRange";
+export * from "./ISymbolInformation";
+export * from "./isDocumentSymbol";

package/src/mcp/createServer.ts

@@ -0,0 +1,23 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createMcpServer } from "@typia/mcp";
+import type { ILlmController } from "@typia/interface";
+import typia from "typia";
+
+import {
+  AsyncSamchonGraphSource,
+  SamchonGraphApplication,
+} from "../application";
+import { ISamchonGraphApplication } from "../structures";
+
+export function createServer(
+  graph: AsyncSamchonGraphSource,
+  version: string,
+): McpServer {
+  const controller: ILlmController<ISamchonGraphApplication> = {
+    protocol: "class",
+    name: "samchon-graph",
+    application: typia.llm.application<ISamchonGraphApplication>(),
+    execute: new SamchonGraphApplication(graph),
+  };
+  return createMcpServer(controller, version);
+}

package/src/mcp/startServer.ts

@@ -0,0 +1,23 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import fs from "node:fs";
+
+import { buildGraph } from "../indexer/buildGraph";
+import { IBuildGraphOptions } from "../indexer/IBuildGraphOptions";
+import { GraphMemory } from "../model/GraphMemory";
+import { IGraphDump } from "../structures";
+import { createServer } from "./createServer";
+
+export async function startServer(
+  options: IBuildGraphOptions & { version: string; graphFile?: string },
+): Promise<void> {
+  // A pre-built dump (`--graph-file`) serves immediately — the expensive index
+  // was paid once, outside this process, the same way comparator tools pay
+  // their `init`. Without it the resident graph builds lazily on first use.
+  const source =
+    options.graphFile !== undefined
+      ? () => GraphMemory.from(JSON.parse(fs.readFileSync(options.graphFile!, "utf8")) as IGraphDump)
+      : () => buildGraph(options);
+  const server = createServer(source, options.version);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/model/GraphMemory.ts

@@ -0,0 +1,165 @@
+import {
+  GraphEdgeKind,
+  IGraphDiagnostic,
+  IGraphDump,
+  IGraphEdge,
+  IGraphNode,
+} from "../structures";
+import { basename } from "../utils/path";
+
+export class GraphMemory {
+  private readonly byId: Map<string, IGraphNode>;
+  private readonly outEdges: Map<string, IGraphEdge[]>;
+  private readonly inEdges: Map<string, IGraphEdge[]>;
+  private readonly byNameIndex: Map<string, IGraphNode[]>;
+  private readonly bySymbolIndex: Map<string, IGraphNode[]>;
+  private readonly diagnosticsByFile: Map<string, IGraphDiagnostic[]>;
+
+  public readonly project: string;
+  public readonly languages: readonly string[];
+  public readonly indexer: IGraphDump["indexer"];
+  public readonly nodes: readonly IGraphNode[];
+  public readonly edges: readonly IGraphEdge[];
+  public readonly diagnostics: readonly IGraphDiagnostic[];
+  public readonly warnings: readonly string[];
+
+  private constructor(dump: IGraphDump, nodes: IGraphNode[], edges: IGraphEdge[]) {
+    this.project = dump.project;
+    this.languages = dump.languages;
+    this.indexer = dump.indexer;
+    this.nodes = nodes;
+    this.edges = edges;
+    this.diagnostics = dump.diagnostics ?? [];
+    this.warnings = dump.warnings ?? [];
+
+    this.byId = new Map(nodes.map((node) => [node.id, node]));
+    this.outEdges = new Map();
+    this.inEdges = new Map();
+    this.byNameIndex = new Map();
+    this.bySymbolIndex = new Map();
+    this.diagnosticsByFile = new Map();
+
+    for (const node of nodes) {
+      push(this.byNameIndex, node.name, node);
+      if (node.kind !== "file") {
+        push(this.bySymbolIndex, node.name, node);
+        if (node.qualifiedName !== undefined) {
+          push(this.bySymbolIndex, node.qualifiedName, node);
+        }
+      }
+    }
+    for (const edge of edges) {
+      push(this.outEdges, edge.from, edge);
+      push(this.inEdges, edge.to, edge);
+    }
+    for (const diagnostic of this.diagnostics) {
+      push(this.diagnosticsByFile, diagnostic.file, diagnostic);
+    }
+  }
+
+  public static from(dump: IGraphDump): GraphMemory {
+    const { nodes, edges } = synthesize(dump.nodes, dump.edges);
+    return new GraphMemory(dump, nodes, edges);
+  }
+
+  public node(id: string): IGraphNode | undefined {
+    return this.byId.get(id);
+  }
+
+  public outgoing(id: string): readonly IGraphEdge[] {
+    return this.outEdges.get(id) ?? [];
+  }
+
+  public incoming(id: string): readonly IGraphEdge[] {
+    return this.inEdges.get(id) ?? [];
+  }
+
+  public named(name: string): readonly IGraphNode[] {
+    return this.byNameIndex.get(name) ?? [];
+  }
+
+  public symbols(handle: string): readonly IGraphNode[] {
+    return this.bySymbolIndex.get(handle) ?? [];
+  }
+
+  public exported(): IGraphNode[] {
+    return this.nodes.filter((node) => node.exported && !node.external);
+  }
+
+  public diagnosticsFor(file: string): readonly IGraphDiagnostic[] {
+    return this.diagnosticsByFile.get(file) ?? [];
+  }
+}
+
+function push<K, V>(map: Map<K, V[]>, key: K, value: V): void {
+  const bucket = map.get(key);
+  if (bucket === undefined) map.set(key, [value]);
+  else bucket.push(value);
+}
+
+function keyOf(node: IGraphNode): string {
+  return node.qualifiedName ?? node.name;
+}
+
+function ownerKey(key: string): string {
+  const dot = key.lastIndexOf(".");
+  return dot >= 0 ? key.slice(0, dot) : "";
+}
+
+function synthesize(
+  rawNodes: readonly IGraphNode[],
+  rawEdges: readonly IGraphEdge[],
+): { nodes: IGraphNode[]; edges: IGraphEdge[] } {
+  const nodes = rawNodes.map((node) => ({ ...node }));
+  const edges = rawEdges.map((edge) => ({ ...edge }));
+  const byFileKey = new Map<string, IGraphNode>();
+  const files = new Map<string, IGraphNode>();
+
+  for (const node of nodes) {
+    if (!node.external) byFileKey.set(`${node.file}\0${keyOf(node)}`, node);
+    if (!node.external && node.file !== "" && !files.has(node.file)) {
+      files.set(node.file, {
+        id: node.file,
+        kind: "file",
+        language: node.language,
+        name: basename(node.file),
+        file: node.file,
+        external: false,
+      });
+    }
+  }
+
+  const edgeKeys = new Set(
+    edges.map((edge) => `${edge.kind}\0${edge.from}\0${edge.to}`),
+  );
+  const addEdge = (edge: IGraphEdge): void => {
+    const key = `${edge.kind}\0${edge.from}\0${edge.to}`;
+    if (edgeKeys.has(key)) return;
+    edgeKeys.add(key);
+    edges.push(edge);
+  };
+
+  for (const node of nodes) {
+    if (node.external || node.file === "") continue;
+    const parentKey = ownerKey(keyOf(node));
+    const parent =
+      parentKey === "" ? undefined : byFileKey.get(`${node.file}\0${parentKey}`);
+    addEdge({
+      from: parent?.id ?? node.file,
+      to: node.id,
+      kind: "contains",
+    });
+    if (node.exported) {
+      addEdge({
+        from: node.file,
+        to: node.id,
+        kind: "exports" satisfies GraphEdgeKind,
+      });
+    }
+  }
+
+  return {
+    nodes: [...nodes, ...files.values()],
+    edges,
+  };
+}

package/src/operations/bound.ts

@@ -0,0 +1,9 @@
+export function bound(
+  value: number | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const n = value === undefined || !Number.isFinite(value) ? fallback : value;
+  return Math.max(min, Math.min(max, Math.floor(n)));
+}

package/src/operations/common.ts

@@ -0,0 +1,15 @@
+export * from "./bound";
+export * from "./compareEdges";
+export * from "./edgeRank";
+export * from "./isExecution";
+export * from "./isStructural";
+export * from "./isTestPath";
+export * from "./isTypeEdge";
+export * from "./publicEvidence";
+export * from "./referencesFromEdges";
+export * from "./resolveHandle";
+export * from "./resultGuide";
+export * from "./resultNext";
+export * from "./signatureOf";
+export * from "./subwords";
+export * from "./summaryOf";

package/src/operations/compareEdges.ts

@@ -0,0 +1,10 @@
+import { IGraphEdge } from "../structures";
+import { edgeRank } from "./edgeRank";
+
+export function compareEdges(a: IGraphEdge, b: IGraphEdge): number {
+  return (
+    edgeRank(a.kind) - edgeRank(b.kind) ||
+    (a.evidence?.startLine ?? 999_999) - (b.evidence?.startLine ?? 999_999) ||
+    (a.evidence?.startCol ?? 999) - (b.evidence?.startCol ?? 999)
+  );
+}

package/src/operations/edgeRank.ts

@@ -0,0 +1,23 @@
+import { GraphEdgeKind } from "../structures";
+
+export function edgeRank(kind: string): number {
+  switch (kind satisfies string as GraphEdgeKind | string) {
+    case "calls":
+      return 0;
+    case "instantiates":
+      return 1;
+    case "references":
+    case "accesses":
+      return 2;
+    case "type_ref":
+      return 3;
+    case "extends":
+    case "implements":
+    case "overrides":
+      return 4;
+    case "tests":
+      return 5;
+    default:
+      return 10;
+  }
+}

package/src/operations/isExecution.ts

@@ -0,0 +1,9 @@
+export function isExecution(kind: string): boolean {
+  return (
+    kind === "calls" ||
+    kind === "instantiates" ||
+    kind === "accesses" ||
+    kind === "renders" ||
+    kind === "references"
+  );
+}

package/src/operations/isPublicApiNoisePath.ts

@@ -0,0 +1,10 @@
+import { isSupportPath } from "./isSupportPath";
+
+/** True when exported symbols are unlikely to be authored public API. */
+export function isPublicApiNoisePath(file: string): boolean {
+  return (
+    isSupportPath(file) ||
+    /(^|\/|\.)typings\.[cm]?ts$/.test(file) ||
+    /(^|\/)internal\//.test(file)
+  );
+}

package/src/operations/isStructural.ts

@@ -0,0 +1,3 @@
+export function isStructural(kind: string): boolean {
+  return kind === "contains" || kind === "exports" || kind === "imports";
+}

package/src/operations/isSupportPath.ts

@@ -0,0 +1,16 @@
+/** True for tests, examples, fixtures, generated output, and build artifacts. */
+export function isSupportPath(file: string): boolean {
+  return (
+    file === "" ||
+    file.startsWith("bundled://") ||
+    /(^|\/)(node_modules|vendor|site-packages)\//.test(file) ||
+    /(^|\/)(test|tests|__tests__|spec|specs|sample|samples|fixture|fixtures|__fixtures__|example|examples)\//.test(
+      file,
+    ) ||
+    /\.(test|spec)\.[^/]+$/.test(file) ||
+    /_test\.[^/]+$/.test(file) ||
+    /(^|\/)typings\.[cm]?ts$/.test(file) ||
+    /\.d\.[cm]?ts$/.test(file) ||
+    /(^|\/)(dist|build|coverage|generated|__generated__|gen)\//.test(file)
+  );
+}

package/src/operations/isTestPath.ts

@@ -0,0 +1,7 @@
+export function isTestPath(file: string): boolean {
+  return (
+    /(^|\/)(test|tests|__tests__|spec)\//.test(file) ||
+    /\.(test|spec)\./.test(file) ||
+    /_test\./.test(file)
+  );
+}

package/src/operations/isTypeEdge.ts

@@ -0,0 +1,9 @@
+export function isTypeEdge(kind: string): boolean {
+  return (
+    kind === "type_ref" ||
+    kind === "extends" ||
+    kind === "implements" ||
+    kind === "overrides" ||
+    kind === "decorates"
+  );
+}

package/src/operations/publicEvidence.ts

@@ -0,0 +1,11 @@
+import { IGraphEvidence } from "../structures";
+
+export function publicEvidence(evidence: IGraphEvidence): IGraphEvidence {
+  return {
+    file: evidence.file,
+    startLine: evidence.startLine,
+    ...(evidence.startCol !== undefined ? { startCol: evidence.startCol } : {}),
+    ...(evidence.endLine !== undefined ? { endLine: evidence.endLine } : {}),
+    ...(evidence.endCol !== undefined ? { endCol: evidence.endCol } : {}),
+  };
+}

package/src/operations/referencesFromEdges.ts

@@ -0,0 +1,37 @@
+import { GraphMemory } from "../model/GraphMemory";
+import { IGraphDetails, IGraphEdge } from "../structures";
+import { compareEdges } from "./compareEdges";
+import { isStructural } from "./isStructural";
+import { publicEvidence } from "./publicEvidence";
+import { summaryOf } from "./summaryOf";
+
+export function referencesFromEdges(
+  graph: GraphMemory,
+  edges: readonly IGraphEdge[],
+  end: "from" | "to",
+  limit: number,
+  includeExternal: boolean,
+  kinds?: ReadonlySet<string>,
+): IGraphDetails.IReference[] {
+  const out: IGraphDetails.IReference[] = [];
+  const seen = new Set<string>();
+  for (const edge of [...edges].sort(compareEdges)) {
+    if (kinds !== undefined && !kinds.has(edge.kind)) continue;
+    if (isStructural(edge.kind)) continue;
+    const node = graph.node(end === "from" ? edge.from : edge.to);
+    if (node === undefined) continue;
+    if (!includeExternal && node.external) continue;
+    // One entry per node; edges are pre-sorted by compareEdges, so the first
+    // (highest-ranked) relation to a node wins.
+    if (seen.has(node.id)) continue;
+    seen.add(node.id);
+    const ref: IGraphDetails.IReference = {
+      ...summaryOf(node),
+      relation: edge.kind,
+    };
+    if (edge.evidence !== undefined) ref.evidence = publicEvidence(edge.evidence);
+    out.push(ref);
+    if (out.length >= limit) break;
+  }
+  return out;
+}

package/src/operations/resolveHandle.ts

@@ -0,0 +1,27 @@
+import { GraphMemory } from "../model/GraphMemory";
+import { IGraphNode } from "../structures";
+
+export function resolveHandle(
+  graph: GraphMemory,
+  handle: string,
+): { node?: IGraphNode; candidates?: IGraphNode[] } {
+  const trimmed = handle.trim();
+  if (trimmed === "") return {};
+  const exact = graph.node(trimmed);
+  if (exact !== undefined) return { node: exact };
+  const symbolMatches = graph.symbols(trimmed);
+  if (symbolMatches.length === 1) return { node: symbolMatches[0] };
+  if (symbolMatches.length > 1) return { candidates: symbolMatches.slice(0, 8) };
+  const lowered = trimmed.toLowerCase();
+  const fuzzy = graph.nodes
+    .filter(
+      (node) =>
+        node.kind !== "file" &&
+        ((node.qualifiedName ?? node.name).toLowerCase().endsWith(lowered) ||
+          node.file.toLowerCase().endsWith(lowered)),
+    )
+    .slice(0, 8);
+  if (fuzzy.length === 1) return { node: fuzzy[0] };
+  if (fuzzy.length > 1) return { candidates: fuzzy };
+  return {};
+}

package/src/operations/resultGuide.ts

@@ -0,0 +1,3 @@
+export function resultGuide(message: string): string {
+  return `${message} Use graph spans as citation anchors; do not treat them as a command to read source bodies.`;
+}

package/src/operations/resultNext.ts

@@ -0,0 +1,9 @@
+import { IGraphNext } from "../structures";
+
+export function resultNext(
+  action: IGraphNext["action"],
+  reason: string,
+  request?: IGraphNext["request"],
+): IGraphNext {
+  return request === undefined ? { action, reason } : { action, request, reason };
+}