@samchon/graph 0.1.0

package/src/structures/IGraphOverview.ts

@@ -0,0 +1,121 @@
+import { GraphLanguage } from "./GraphLanguage";
+import { IGraphDiagnostic } from "./IGraphDiagnostic";
+import { IGraphEvidence } from "./IGraphEvidence";
+import { IGraphNext } from "./IGraphNext";
+
+/** A compact, source-read-free project map for broad orientation only. */
+export interface IGraphOverview {
+  /** Discriminator for source-free project overview. */
+  type: "overview";
+
+  /** Absolute project root. */
+  project: string;
+
+  /** Languages present in the project. */
+  languages: GraphLanguage[];
+
+  /** Size of the graph. */
+  counts: IGraphOverview.ICounts;
+
+  /** Folder layering, largest first. */
+  layers?: IGraphOverview.ILayer[];
+
+  /** Highest-dependency symbols, busiest first. */
+  hotspots?: IGraphOverview.IHotspot[];
+
+  /** Exported API symbols, most-depended-on first. */
+  publicApi?: IGraphOverview.IPublicApi[];
+
+  /** Index diagnostics, when any. */
+  diagnostics?: IGraphDiagnostic[];
+
+  /** How to use this source-free result next. */
+  next: IGraphNext;
+
+  /** Human-readable compatibility note mirroring `next`. */
+  guide: string;
+}
+
+export namespace IGraphOverview {
+  /** Which broad architecture facets `overview` should return. */
+  export interface IRequest {
+    /** Discriminator for source-free project overview. */
+    type: "overview";
+
+    /**
+     * The facet to project, or `all` for every facet. `layers` is the folder
+     * layering, `hotspots` the highest-dependency symbols, `publicApi` the
+     * exported API symbols ranked by how depended-on they are.
+     *
+     * Use this only for broad public API or layer orientation. For behavior,
+     * lifecycle, request-flow, rendering-flow, validation-flow, caller, or
+     * dependency questions, use `entrypoints` then `trace` instead.
+     *
+     * @default "all"
+     */
+    aspect?: "all" | "layers" | "hotspots" | "publicApi" | "diagnostics";
+  }
+
+  /** Size of the graph by node/edge totals and per-kind node counts. */
+  export interface ICounts {
+    /** Number of source file container nodes. */
+    files: number;
+
+    /** Total node count, including declarations and file containers. */
+    nodes: number;
+
+    /** Total edge count, including structural edges. */
+    edges: number;
+
+    /** Node count per kind. */
+    byKind: Record<string, number>;
+
+    /** Node count per language. */
+    byLanguage: Record<string, number>;
+  }
+
+  /** One folder layer: its source files and export surface. */
+  export interface ILayer {
+    /** Directory, project-relative. */
+    dir: string;
+    /** Distinct source files under it. */
+    files: number;
+    /** Exported symbols declared under it. */
+    exported: number;
+    /** Languages present under it. */
+    languages: GraphLanguage[];
+  }
+
+  /** A compact symbol coordinate that can be passed to deeper graph tools. */
+  export interface INode {
+    /** Stable handle for `details` or `trace`. */
+    id: string;
+    /** The symbol's qualified name when available. */
+    name: string;
+    /** Its declaration kind (`class`, `interface`, `function`, ...). */
+    kind: string;
+    /** Language the symbol is written in. */
+    language: GraphLanguage;
+    /** Project-relative path of the file that declares it. */
+    file: string;
+    /** 1-based declaration line, when known. */
+    line?: number;
+    /** Source span of the declaration, when known. */
+    sourceSpan?: Pick<IGraphEvidence, "file" | "startLine" | "endLine">;
+  }
+
+  /** A high-dependency symbol with its non-structural fan-in and fan-out. */
+  export interface IHotspot extends INode {
+    /** Non-structural edges pointing at this symbol. */
+    fanIn: number;
+    /** Non-structural edges leaving this symbol. */
+    fanOut: number;
+  }
+
+  /**
+   * One symbol on the project's exported public API surface. The list is ranked
+   * by how depended-on the symbol is, with test, typings, and generated files
+   * excluded.
+   */
+  export type IPublicApi = INode;
+}

package/src/structures/IGraphTour.ts

@@ -0,0 +1,68 @@
+import { GraphLanguage } from "./GraphLanguage";
+import { IGraphDiagnostic } from "./IGraphDiagnostic";
+import { IGraphEntrypoints } from "./IGraphEntrypoints";
+import { IGraphNext } from "./IGraphNext";
+import { IGraphOverview } from "./IGraphOverview";
+
+/** Answer-ready, source-free tour evidence for broad code-flow questions. */
+export interface IGraphTour {
+  /** Discriminator for code-tour indexing. */
+  type: "tour";
+
+  /** Natural code question this tour was built for. */
+  question?: string;
+
+  /** Central entrypoints selected for the tour. */
+  entrypoints: IGraphEntrypoints.IEntrypoint[];
+
+  /** Selected primary runtime flows; sufficient for an index-level tour. */
+  primaryFlow: string[];
+
+  /** Nearby dependency anchors around the selected entrypoints. */
+  nearbyPaths: IGraphOverview.INode[];
+
+  /** Test or usage anchors reached through graph impact edges. */
+  testAnchors: IGraphOverview.INode[];
+
+  /** Ordered file/line anchors to cite in the final answer, not file reads. */
+  answerAnchors: IGraphOverview.INode[];
+
+  /** Diagnostics collected while building the tour. */
+  diagnostics?: IGraphDiagnostic[];
+
+  /** How to use this source-free result next. */
+  next: IGraphNext;
+
+  /** Human-readable compatibility note mirroring `next`. */
+  guide: string;
+}
+
+export namespace IGraphTour {
+  /**
+   * Build the complete index-level answer surface for broad code tours: central
+   * entrypoints, primary flow, nearby paths, tests, and answer anchors. Use
+   * this instead of decomposing repository-orientation, read-next,
+   * architecture, or multi-phase runtime-flow questions into many
+   * lookup/details/trace calls.
+   */
+  export interface IRequest {
+    /** Discriminator for code-tour indexing. */
+    type: "tour";
+
+    /** The user's natural code-tour question. */
+    question?: string;
+
+    /** Target source language for the tour. */
+    language?: GraphLanguage;
+
+    /**
+     * Maximum central entrypoints to seed the tour.
+     *
+     * Prefer the default. Raise only when the question names several distinct
+     * public paths that must all appear in one answer.
+     *
+     * @default 4
+     */
+    limit?: number;
+  }
+}

package/src/structures/IGraphTrace.ts

@@ -0,0 +1,154 @@
+import { IGraphEvidence } from "./IGraphEvidence";
+import { IGraphNext } from "./IGraphNext";
+import { IGraphOverview } from "./IGraphOverview";
+
+/** The compact dependency or caller flow returned from a selected start symbol. */
+export interface IGraphTrace {
+  /** Discriminator for dependency tracing. */
+  type: "trace";
+
+  /** The resolved start node, or undefined when `from` matched nothing. */
+  start?: IGraphTrace.INode;
+
+  /** Trace direction actually used by this result. */
+  direction: string;
+
+  /** Edges traversed, in breadth-first order. */
+  hops: IGraphTrace.IHop[];
+
+  /** Unique nodes reached (excluding the start), each with its depth and roles. */
+  reached: IGraphTrace.INode[];
+
+  /** True when the trace hit maxNodes or maxDepth and more flow exists. */
+  truncated: boolean;
+
+  /** The resolved `to` target, when a path was requested. */
+  target?: IGraphTrace.INode;
+
+  /**
+   * When `to` was given: the ordered dependency path from `from` to `to`
+   * (`from` first, `to` last), or empty when `to` is not reachable from
+   * `from`.
+   */
+  path?: IGraphTrace.INode[];
+
+  /** Compact hop summaries preserving node names and edge evidence, capped. */
+  steps?: string[];
+
+  /** When `from` was an ambiguous name, the matches to disambiguate with. */
+  candidates?: IGraphTrace.INode[];
+
+  /** How to use this source-free result next. */
+  next: IGraphNext;
+
+  /** Human-readable compatibility note mirroring `next`. */
+  guide: string;
+}
+
+export namespace IGraphTrace {
+  /** Where and how far to trace dependency flow. */
+  export interface IRequest {
+    /** Discriminator for dependency tracing. */
+    type: "trace";
+
+    /**
+     * Where to start: a node id from another tool, a simple symbol name, or a
+     * dotted member name such as `OrderService.create`. An ambiguous name
+     * returns its candidates instead of a trace.
+     */
+    from: string;
+
+    /**
+     * A target symbol: node id, simple symbol name, or dotted member name. When
+     * given, the tool returns the dependency path from `from` to this target,
+     * the one-call answer for "how does A reach B", instead of an open-ended
+     * trace. Prefer this path mode whenever both ends are known.
+     */
+    to?: string;
+
+    /**
+     * `forward` follows what the start uses (callees, instantiations, renders);
+     * `reverse` follows what uses the start (callers); `impact` is a reverse
+     * trace that prioritizes public API and test nodes a change would reach.
+     * Its test nodes are semantic usage edges, not a text-search inventory.
+     * Caller questions usually fit `reverse`.
+     *
+     * @default "forward"
+     */
+    direction?: "forward" | "reverse" | "impact";
+
+    /**
+     * Which non-structural edge family to follow: `execution` follows runtime
+     * calls, instantiations, property access, and JSX renders; `types` follows
+     * type references and inheritance; `all` preserves the full graph. Flow
+     * questions should usually choose `execution` rather than `all`.
+     *
+     * @default "all"
+     */
+    focus?: "all" | "execution" | "types";
+
+    /**
+     * How many hops deep to follow. Open forward/reverse traces are capped at
+     * 2; impact traces at 4; path mode at 12.
+     *
+     * Prefer the default for open traces. Raise only for path mode or when the
+     * previous trace named the missing next hop.
+     *
+     * @default 2
+     */
+    maxDepth?: number;
+
+    /**
+     * Cap on reached nodes; the trace stops and marks itself truncated past it.
+     * Open forward/reverse traces are capped at 8 nodes, impact at 16 nodes.
+     *
+     * Prefer the default; use larger open traces only when a named missing edge
+     * requires it.
+     *
+     * @default 6
+     */
+    maxNodes?: number;
+
+    /**
+     * Include dependency-boundary nodes from bundled libraries. Leave false for
+     * source-flow tours; enable only when the user asks about external type/API
+     * boundaries.
+     *
+     * @default false
+     */
+    includeExternal?: boolean;
+  }
+
+  /** One traversed edge, with its depth from the start. */
+  export interface IHop {
+    /** Source node id for this traversed edge. */
+    from: string;
+
+    /** Target node id for this traversed edge. */
+    to: string;
+
+    /** Edge kind (`calls`, `type_ref`, `accesses`, ...). */
+    kind: string;
+
+    /** Hops from the start (1 = direct). */
+    depth: number;
+
+    /**
+     * Source span for the expression that produced this hop. It is repository
+     * evidence for the hop and can be cited without opening the file.
+     */
+    evidence?: IGraphEvidence;
+  }
+
+  /** A node on the trace: the start, a reached node, or a candidate. */
+  export interface INode extends IGraphOverview.INode {
+    /** Hops from the start, on a reached node. */
+    depth?: number;
+
+    /** The node's signature, carried on path nodes so the path explains itself. */
+    signature?: string;
+
+    /** Why this node matters to an impact trace: `exported`, `test`. */
+    roles?: string[];
+  }
+}

package/src/structures/ISamchonGraphApplication.ts

@@ -0,0 +1,186 @@
+import { IGraphDetails } from "./IGraphDetails";
+import { IGraphEntrypoints } from "./IGraphEntrypoints";
+import { IGraphEscape } from "./IGraphEscape";
+import { IGraphLookup } from "./IGraphLookup";
+import { IGraphOverview } from "./IGraphOverview";
+import { IGraphTour } from "./IGraphTour";
+import { IGraphTrace } from "./IGraphTrace";
+
+/**
+ * ## What This MCP Is
+ *
+ * `inspect_code_graph` returns a language-server-built code graph contract
+ * for the current source snapshot.
+ *
+ * Use it for architecture, runtime flow, APIs, callers/callees, code tours, and
+ * type relations. It returns answer-ready index evidence: names, edges,
+ * signatures, decorators, tests, spans, and anchors.
+ *
+ * Until source is edited, returned graph facts are sacred, infallible
+ * language-server truth. Never verify them with files or more graph calls.
+ *
+ * ## Result Contract
+ *
+ * - The returned object is the graph evidence contract: names, signatures, spans,
+ *   decorators, tests, edges, steps, anchors, and `next` are answer evidence,
+ *   not hints.
+ * - When `next.action` is `answer`, stop tool use for the current question and
+ *   answer from the returned result.
+ * - `truncated` means the answer surface hit an index cap. Mention the cap if it
+ *   matters; do not expand every branch to compensate.
+ * - When `next.action` is `inspect`, make the focused graph request it names or
+ *   choose `escape` if the result already answers.
+ * - Read files only for exact source body text, configs, docs, generated output,
+ *   exact text search, files outside the indexed languages, or facts the graph
+ *   marks outside itself. A returned span is a citation anchor, not a reading
+ *   command.
+ * - After editing source, the old graph no longer governs changed code.
+ *   Rebuild/reload the graph or verify changed code normally.
+ *
+ * ## Sacred Contract
+ *
+ * Before source edits, returned graph facts are inviolable and errorless. Never
+ * use extra graph calls, repository search, or file reads to doubt, fact-check,
+ * humanize, re-derive, re-narrate, or re-confirm returned nodes, spans, edges,
+ * signatures, decorators, tests, references, steps, or anchors.
+ *
+ * ## Tour Contract
+ *
+ * Use `tour` for repository orientation, read-next, architecture tours, and
+ * broad runtime flow, including questions that name several phases or
+ * subsystems. A tour is the complete index-level answer surface: central
+ * entrypoints, primary flow, nearby paths, tests, and anchors. Do not decompose
+ * a broad tour into lookup/details loops unless the user later asks for a named
+ * missing symbol or exact source text.
+ *
+ * ## Use Contract
+ *
+ * 1. Ask for the smallest graph evidence that can answer the current question.
+ * 2. Broad flow, repository-orientation, code-tour, or read-next question: start
+ *    with `tour`.
+ * 3. Concrete named symbol: use `lookup`, then `details` only if needed.
+ * 4. Known endpoint pair or one selected handle: use one `trace`.
+ * 5. Unknown narrow orientation: use `entrypoints` once.
+ * 6. Selected symbol shape: use `details` for one to three handles.
+ * 7. Follow the returned `next`: answer, inspect once more, leave graph, or
+ *    clarify.
+ * 8. Use `escape` when another graph call would repeat evidence or the remaining
+ *    evidence is outside the code graph.
+ *
+ * Most code structure answers need one or two graph calls.
+ *
+ * ## Request Fields
+ *
+ * Fill the visible checklist, then exactly one request.
+ *
+ * - `question`: restate the code question being considered.
+ * - `draft`: initial request type and why it seems smallest.
+ * - `review`: correct a wrong, broad, stale, or duplicate draft. If graph facts
+ *   already answer, if prior `next.action` was `answer`, or if the next
+ *   evidence is outside the indexed code graph, say so here and make
+ *   `request.type` be `escape`. If a broad flow draft is not `tour`, correct it
+ *   here.
+ * - `request`: final request after review.
+ *
+ * ## How to answer from graph evidence
+ *
+ * - Use returned node names, signatures, edges, references, evidence, and
+ *   `sourceSpan` ranges directly.
+ * - Explain the central path first, then mention important branches.
+ * - For tests, impact, or reading lists, returned nodes and ranges are the answer
+ *   evidence, not search keywords.
+ * - A returned range is a sacred citation anchor, not permission to open the
+ *   file.
+ */
+export interface ISamchonGraphApplication {
+  /**
+   * Inspect the code graph contract.
+   *
+   * Use this before repository search when an answer depends on code
+   * symbols, calls, types, decorators, references, ranges, or runtime/source
+   * relationships. For repository orientation, read-next, architecture, and
+   * broad runtime flow questions, use `tour`.
+   *
+   * Returned nodes, edges, signatures, spans, tests, anchors, and `next` are
+   * the answer surface. If `next.action` is `answer`, stop tool use and answer
+   * from that result. Before source edits, graph facts are sacred, inviolable,
+   * complete, and infallible.
+   *
+   * @param props Reasoning plus one graph request
+   * @returns Matching `result` union member
+   */
+  inspect_code_graph(
+    props: ISamchonGraphApplication.IProps,
+  ): Promise<ISamchonGraphApplication.IResult>;
+}
+
+export namespace ISamchonGraphApplication {
+  /** Draft, review, then submit exactly one graph request or escape. */
+  export interface IProps {
+    /**
+     * User's code question.
+     *
+     * Restate the code question being considered. If the next evidence is a
+     * script, config, doc, generated output, exact text, a file outside the
+     * indexed languages, or source body text, choose `escape`.
+     */
+    question: string;
+
+    /**
+     * Initial request plan before final arguments are filled.
+     *
+     * Name the intended request type in `type` and why it seems smallest in
+     * `reason`. Broad flow, architecture, repository-orientation, and read-next
+     * questions should normally draft `tour`; narrow named symbols can draft
+     * `lookup`, `trace`, or `details`.
+     */
+    draft: IDraft;
+
+    /**
+     * Final self-review before calling.
+     *
+     * Correct a stale, broad, duplicate, or wrong draft here. If broad flow was
+     * split into search/detail steps, switch to `tour`. If graph facts already
+     * answer, or prior `next.action` was `answer`, make `request.type` be
+     * `escape`; do not call graph or read files to re-confirm returned facts.
+     */
+    review: string;
+
+    /** Final graph operation chosen after review, or a no-op escape. */
+    request:
+      | IGraphEntrypoints.IRequest
+      | IGraphLookup.IRequest
+      | IGraphTrace.IRequest
+      | IGraphDetails.IRequest
+      | IGraphOverview.IRequest
+      | IGraphTour.IRequest
+      | IGraphEscape.IRequest;
+  }
+
+  /**
+   * First-pass request plan, filled before the final `request` arguments.
+   *
+   * `reason` comes before `type` so the justification is written before the
+   * choice it justifies.
+   */
+  export interface IDraft {
+    /** Why this request type looks like the smallest useful next step. */
+    reason: string;
+
+    /** The request type being considered, corrected later in `review`. */
+    type: IProps["request"]["type"];
+  }
+
+  /** The selected request's output. `result.type` mirrors `request.type`. */
+  export interface IResult {
+    /** Result branch matching the submitted `request.type`. */
+    result:
+      | IGraphEntrypoints
+      | IGraphLookup
+      | IGraphTrace
+      | IGraphDetails
+      | IGraphOverview
+      | IGraphTour
+      | IGraphEscape;
+  }
+}

package/src/structures/index.ts

@@ -0,0 +1,18 @@
+export * from "./GraphEdgeKind";
+export * from "./GraphLanguage";
+export * from "./GraphNodeKind";
+export * from "./IGraphDecorator";
+export * from "./IGraphDetails";
+export * from "./IGraphDiagnostic";
+export * from "./IGraphDump";
+export * from "./IGraphEdge";
+export * from "./IGraphEntrypoints";
+export * from "./IGraphEscape";
+export * from "./IGraphEvidence";
+export * from "./IGraphLookup";
+export * from "./IGraphNext";
+export * from "./IGraphNode";
+export * from "./IGraphOverview";
+export * from "./IGraphTour";
+export * from "./IGraphTrace";
+export * from "./ISamchonGraphApplication";

package/src/structures.ts

@@ -0,0 +1 @@
+export * from "./structures/index";

package/src/utils/DEFAULT_IGNORES.ts

@@ -0,0 +1,35 @@
+export const DEFAULT_IGNORES = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  ".idea",
+  ".vscode",
+  "node_modules",
+  "bower_components",
+  "vendor",
+  "dist",
+  "lib",
+  "build",
+  "target",
+  "out",
+  "coverage",
+  ".next",
+  ".nuxt",
+  ".turbo",
+  ".cache",
+  // Language build/cache directories for the supported languages.
+  "obj",
+  "__pycache__",
+  ".venv",
+  "venv",
+  ".pytest_cache",
+  ".mypy_cache",
+  ".tox",
+  ".gradle",
+  ".mvn",
+  ".build",
+  ".dart_tool",
+  "zig-cache",
+  "zig-out",
+  "Pods",
+]);

package/src/utils/IWalkOptions.ts

@@ -0,0 +1,5 @@
+export interface IWalkOptions {
+  extensions: ReadonlySet<string>;
+  ignoreDirs?: ReadonlySet<string>;
+  maxFiles?: number;
+}

package/src/utils/basename.ts

@@ -0,0 +1,7 @@
+import { normalizePath } from "./normalizePath";
+
+export function basename(file: string): string {
+  const normalized = normalizePath(file);
+  const slash = normalized.lastIndexOf("/");
+  return slash >= 0 ? normalized.slice(slash + 1) : normalized;
+}

package/src/utils/dirname.ts

@@ -0,0 +1,7 @@
+import { normalizePath } from "./normalizePath";
+
+export function dirname(file: string): string {
+  const normalized = normalizePath(file);
+  const slash = normalized.lastIndexOf("/");
+  return slash >= 0 ? normalized.slice(0, slash) : ".";
+}

package/src/utils/fileFromUri.ts

@@ -0,0 +1,14 @@
+export function fileFromUri(uri: string): string {
+  if (!uri.startsWith("file://")) return uri;
+  // Language servers encode the Windows drive-letter colon as `%3A`, which
+  // `decodeURI` leaves intact; normalize it before the drive-letter check so
+  // the path does not stay malformed and drop every reference edge.
+  const withoutScheme = uri
+    .slice("file://".length)
+    .replace(/^\/([A-Za-z])%3[Aa]/, "/$1:");
+  // `decodeURI` leaves reserved characters encoded, but `fileUri` percent-encodes
+  // `#` in real paths; restore it (and `?`) so the path round-trips.
+  const decoded = decodeURI(withoutScheme).replace(/%23/g, "#").replace(/%3[Ff]/g, "?");
+  if (/^\/[A-Za-z]:/.test(decoded)) return decoded.slice(1).replace(/\//g, "\\");
+  return decoded;
+}

package/src/utils/fileUri.ts

@@ -0,0 +1,13 @@
+import path from "node:path";
+
+export function fileUri(file: string): string {
+  // Prepend a leading slash for Windows drive paths (`C:/x` -> `/C:/x`) while
+  // leaving POSIX paths untouched. A branchless replace keeps the coverage gate
+  // reachable on every platform, since a plain `if` here is only ever taken on
+  // one OS.
+  const resolved = path
+    .resolve(file)
+    .replace(/\\/g, "/")
+    .replace(/^(?!\/)/, "/");
+  return `file://${encodeURI(resolved).replace(/#/g, "%23")}`;
+}

package/src/utils/fs.ts

@@ -0,0 +1,6 @@
+export * from "./DEFAULT_IGNORES";
+export * from "./IWalkOptions";
+export * from "./projectRelative";
+export * from "./readLines";
+export * from "./readText";
+export * from "./walkSourceFiles";

package/src/utils/isSubPath.ts

@@ -0,0 +1,9 @@
+import path from "node:path";
+
+export function isSubPath(root: string, candidate: string): boolean {
+  const rel = path.relative(path.resolve(root), path.resolve(candidate));
+  // A path that merely starts with ".." (e.g. `..foo`) is still a child; only a
+  // bare ".." or one under "../" escapes the root.
+  const escapes = rel === ".." || rel.startsWith(`..${path.sep}`);
+  return rel === "" || (!escapes && !path.isAbsolute(rel));
+}

package/src/utils/normalizePath.ts

@@ -0,0 +1,3 @@
+export function normalizePath(value: string): string {
+  return value.replace(/\\/g, "/");
+}

package/src/utils/path.ts

@@ -0,0 +1,7 @@
+export * from "./basename";
+export * from "./dirname";
+export * from "./fileFromUri";
+export * from "./fileUri";
+export * from "./isSubPath";
+export * from "./normalizePath";
+export * from "./relativePath";

package/src/utils/projectRelative.ts

@@ -0,0 +1,6 @@
+import { normalizePath } from "./normalizePath";
+import { relativePath } from "./relativePath";
+
+export function projectRelative(root: string, file: string): string {
+  return normalizePath(relativePath(root, file));
+}