@samchon/graph 0.1.0

package/src/structures/IGraphDetails.ts

@@ -0,0 +1,153 @@
+import { IGraphDecorator } from "./IGraphDecorator";
+import { IGraphDiagnostic } from "./IGraphDiagnostic";
+import { IGraphEvidence } from "./IGraphEvidence";
+import { IGraphNext } from "./IGraphNext";
+import { IGraphOverview } from "./IGraphOverview";
+
+/**
+ * The source-free facts for a few selected handles.
+ *
+ * This is not a file reader. It returns signatures, member outlines, direct
+ * calls, direct types, implementation candidates, dependency summaries, and
+ * sourceSpan citation anchors.
+ */
+export interface IGraphDetails {
+  /** Discriminator for selected symbol inspection. */
+  type: "details";
+
+  /** Selected node facts, in the same order as resolved handles when possible. */
+  nodes: IGraphDetails.INode[];
+
+  /** Handles that resolved to no node, or that were ambiguous. */
+  unknown: string[];
+
+  /** How to use this source-free result next. */
+  next: IGraphNext;
+
+  /** Human-readable compatibility note mirroring `next`. */
+  guide: string;
+}
+
+export namespace IGraphDetails {
+  /** Which selected handles to inspect, and how much of each to return. */
+  export interface IRequest {
+    /** Discriminator for selected symbol inspection. */
+    type: "details";
+
+    /**
+     * Node ids from another tool, or dotted symbol handles such as
+     * `OrderService.create`. Pass the few handles you need for source-free
+     * details. Prefer one to three handles. Use `trace` when you need a path
+     * instead of widening this call.
+     */
+    handles: string[];
+
+    /**
+     * Also list each node's direct dependencies and dependents (the symbols it
+     * uses and the symbols that use it). The list is capped; raise
+     * `neighborLimit` when the first slice is truncated and the missing
+     * relation is named. This remains a relationship summary, not a file body.
+     *
+     * @default false
+     */
+    neighbors?: boolean;
+
+    /**
+     * Maximum dependencies and dependents to return per side when
+     * `neighbors:true`.
+     *
+     * Prefer the default. Values above a few neighbors are usually overfetch;
+     * call `trace` for flow instead.
+     *
+     * @default 2
+     */
+    neighborLimit?: number;
+
+    /**
+     * Maximum owned members to return for a container or object literal. Raise
+     * only when the first outline is truncated and the missing member is
+     * named.
+     *
+     * @default 6
+     */
+    memberLimit?: number;
+
+    /**
+     * Maximum direct execution and type references to return per group. Raise
+     * only when the first dependency slice is truncated and the missing
+     * dependency is named.
+     *
+     * @default 1
+     */
+    dependencyLimit?: number;
+
+    /**
+     * Include dependency-boundary references from bundled libraries. Leave
+     * false for source-architecture answers; enable only when external
+     * type/API boundaries are the question.
+     *
+     * @default false
+     */
+    includeExternal?: boolean;
+  }
+
+  /** One inspected node: its declared shape and graph coordinates. */
+  export interface INode extends IGraphOverview.INode {
+    /** The declaration signature: its first line(s) up to the body. */
+    signature?: string;
+
+    /** Decorators written on this declaration, when any. */
+    decorators?: IGraphDecorator[];
+
+    /** Assigned implementation span, when source comes from one. */
+    implementation?: IGraphEvidence;
+
+    /**
+     * For a container or object-literal variable: the owned symbol or top-level
+     * property outline a consumer reaches for, without bodies.
+     */
+    members?: IMember[];
+
+    /** Direct execution dependencies in source order, with edge evidence. */
+    calls?: IReference[];
+
+    /** Direct type dependencies in source order, with edge evidence. */
+    types?: IReference[];
+
+    /** Symbols this node uses (outgoing dependency edges). */
+    dependsOn?: IReference[];
+
+    /** Symbols that use this node (incoming dependency edges). */
+    dependedOnBy?: IReference[];
+
+    /** Diagnostics reported on this node's declaration, when any. */
+    diagnostics?: IGraphDiagnostic[];
+  }
+
+  /** One member of a container node, with its signature but not its body. */
+  export interface IMember {
+    /** Member name, qualified when the graph records an owner-qualified handle. */
+    name: string;
+
+    /** Member kind (`method`, `property`, `class`, ...). */
+    kind: string;
+
+    /** 1-based declaration line, when known. */
+    line?: number;
+
+    /** The member's declaration signature. */
+    signature?: string;
+  }
+
+  /** A dependency neighbor of an inspected node and the edge that links them. */
+  export interface IReference extends IGraphOverview.INode {
+    /** The edge kind connecting the two (`calls`, `type_ref`, ...). */
+    relation: string;
+
+    /**
+     * Source span for the expression that produced this relationship. It is
+     * repository evidence for the edge, not a file-read instruction.
+     */
+    evidence?: IGraphEvidence;
+  }
+}

package/src/structures/IGraphDiagnostic.ts

@@ -0,0 +1,29 @@
+import { IGraphEvidence } from "./IGraphEvidence";
+
+/**
+ * A language server or plugin diagnostic, fused onto the graph so an edit-triage
+ * query can name the owning symbol of an error.
+ *
+ * The language server's semantic pass contributes numeric-coded diagnostics;
+ * lint rules and transform plugins (typia, nestia, …) contribute `plugin`/`lint`
+ * findings whose `code` is a string.
+ */
+export interface IGraphDiagnostic {
+  /** Project-relative path of the file the diagnostic is reported in. */
+  file: string;
+
+  /** The human-readable diagnostic message. */
+  message: string;
+
+  /** Severity, when the producer distinguishes it. */
+  severity: "error" | "warning" | "information" | "hint";
+
+  /** Which producer emitted the diagnostic. */
+  source?: string;
+
+  /** Numeric language server code, or string rule id for a lint/plugin finding. */
+  code?: string | number;
+
+  /** The source span the diagnostic was attributed to, when resolved. */
+  evidence?: IGraphEvidence;
+}

package/src/structures/IGraphDump.ts

@@ -0,0 +1,45 @@
+import { GraphLanguage } from "./GraphLanguage";
+import { IGraphDiagnostic } from "./IGraphDiagnostic";
+import { IGraphEdge } from "./IGraphEdge";
+import { IGraphNode } from "./IGraphNode";
+
+/**
+ * The whole-graph export `graph dump` writes and the MCP server loads — the
+ * wire contract between the fact-builder and the graph engine.
+ *
+ * It is the complete graph with none of the per-response caps the MCP tools
+ * apply: every node and edge the build resolved. The server parses it once at
+ * startup (validated) into an in-memory resident graph and answers every
+ * tool call from that warm model; the bundled 3D viewer reduces the same dump.
+ *
+ * Paths in `project` are absolute; `file` fields on nodes, edges, and
+ * diagnostics are project-relative.
+ */
+export interface IGraphDump {
+  /** Absolute path of the project root the graph was built for. */
+  project: string;
+
+  /** The source languages present in this dump. */
+  languages: GraphLanguage[];
+
+  /** ISO timestamp of when the dump was generated. */
+  generatedAt: string;
+
+  /** Which indexing strategy produced the graph. */
+  indexer: "lsp" | "static" | "hybrid";
+
+  /** Every node the build recorded. */
+  nodes: IGraphNode[];
+
+  /** Every edge the build resolved. */
+  edges: IGraphEdge[];
+
+  /**
+   * Fused language server and plugin diagnostics, when diagnostics were
+   * collected. Absent when the dump was built without a diagnostics pass.
+   */
+  diagnostics?: IGraphDiagnostic[];
+
+  /** Non-fatal problems encountered while building the graph. */
+  warnings?: string[];
+}

package/src/structures/IGraphEdge.ts

@@ -0,0 +1,24 @@
+import { GraphEdgeKind } from "./GraphEdgeKind";
+import { IGraphEvidence } from "./IGraphEvidence";
+
+/**
+ * A directed relationship from one {@link IGraphNode} to another, both named
+ * by `id`. The triple `(from, to, kind)` is unique; a repeated relationship
+ * keeps the first source-order evidence.
+ *
+ * Every edge is resolved by the language server, so there is no per-edge trust
+ * flag to carry — the whole graph is language-server-resolved fact.
+ */
+export interface IGraphEdge {
+  /** Node id the relationship originates from. */
+  from: string;
+
+  /** Node id the relationship points to. */
+  to: string;
+
+  /** The relationship kind. */
+  kind: GraphEdgeKind;
+
+  /** The source expression that produced the edge, for display and expansion. */
+  evidence?: IGraphEvidence;
+}

package/src/structures/IGraphEntrypoints.ts

@@ -0,0 +1,70 @@
+import { GraphLanguage } from "./GraphLanguage";
+import { IGraphNext } from "./IGraphNext";
+import { IGraphOverview } from "./IGraphOverview";
+
+/** The first compact source-free handle list for a code question. */
+export interface IGraphEntrypoints {
+  /** Discriminator for first-pass question indexing. */
+  type: "entrypoints";
+
+  /** The original question/search phrase the entrypoints were built for. */
+  query: string;
+
+  /** Ranked symbols relevant to the query. */
+  ranked: IGraphEntrypoints.IEntrypoint[];
+
+  /** Code handles written directly in the query, resolved when possible. */
+  mentions: IGraphOverview.INode[];
+
+  /** Direct dependency context for the resolved mentions and highest hits. */
+  dependencyOrientation: string[];
+
+  /** How to use this source-free result next. */
+  next: IGraphNext;
+
+  /** Human-readable compatibility note mirroring `next`. */
+  guide: string;
+}
+
+export namespace IGraphEntrypoints {
+  /**
+   * Ask for first handles when the question is narrow but the symbol is not yet
+   * known. For broad tours, read-next, architecture, or multi-phase runtime
+   * flow, use `tour` instead of decomposing the answer into entrypoints and
+   * follow-up calls.
+   */
+  export interface IRequest {
+    /** Discriminator for first-pass question indexing. */
+    type: "entrypoints";
+
+    /**
+     * A natural code question or search phrase. Mix prose with code handles,
+     * for example `how Repository.find loads relations` or
+     * `SelectQueryBuilder.setFindOptions join aliases`. Keep this close to the
+     * user's question; do not turn it into a broad keyword dump.
+     */
+    query: string;
+
+    /** Target source language for the entrypoints. */
+    language?: GraphLanguage;
+
+    /**
+     * Maximum ranked hits to return.
+     *
+     * Prefer the default. Raise only when the first result was truncated and
+     * the missing handle is named.
+     *
+     * @default 4
+     */
+    limit?: number;
+  }
+
+  /** One ranked search hit. */
+  export interface IEntrypoint extends IGraphOverview.INode {
+    /** Relative relevance; higher is a better match. */
+    score: number;
+
+    /** Why this entrypoint was ranked for the query. */
+    reason: string;
+  }
+}

package/src/structures/IGraphEscape.ts

@@ -0,0 +1,49 @@
+import { IGraphNext } from "./IGraphNext";
+
+/** The no-op result for when graph is not the useful next evidence source. */
+export interface IGraphEscape {
+  /** Discriminator for the no-op escape route. */
+  type: "escape";
+
+  /** Always true so callers can distinguish an intentional no-op. */
+  skipped: true;
+
+  /** Why no graph operation should run. */
+  reason: string;
+
+  /** Optional note about the next non-graph step. */
+  nextStep?: string;
+
+  /** How to proceed after skipping graph work. */
+  next: IGraphNext;
+
+  /** Human-readable compatibility note mirroring `next`. */
+  guide: string;
+}
+
+export namespace IGraphEscape {
+  /** Skip graph work when graph evidence is unnecessary or exhausted. */
+  export interface IRequest {
+    /** Discriminator for the no-op escape route. */
+    type: "escape";
+
+    /**
+     * Why no graph operation should run.
+     *
+     * Use this only when the next evidence is outside the indexed code
+     * graph: package scripts, config files, generated output, prose docs, exact
+     * text, or exact source body text. Name the smallest returned sourceSpan
+     * when source body text is truly required.
+     */
+    reason: string;
+
+    /**
+     * The final non-graph note, if useful.
+     *
+     * Keep this short. Examples: `answer from the prior graph result`, `source
+     * body needed at returned sourceSpan`, or `ask the user for a concrete
+     * symbol`.
+     */
+    nextStep?: string;
+  }
+}

package/src/structures/IGraphEvidence.ts

@@ -0,0 +1,29 @@
+/**
+ * A source location that grounds a node or edge in real code: the declaration
+ * span for a node, or the expression range that produced an edge.
+ *
+ * Evidence is display and grounding only; it is never identity. A node's id is
+ * position-invariant (see {@link IGraphNode}), so an edit that shifts a span
+ * does not re-key anything. `startLine`/`startCol` are 1-based. MCP output
+ * keeps evidence as coordinates; consumers can read the file themselves when
+ * they truly need source text.
+ */
+export interface IGraphEvidence {
+  /** Project-relative path of the file the span lives in. */
+  file: string;
+
+  /** 1-based line where the span starts. */
+  startLine: number;
+
+  /** 1-based column where the span starts, when known. */
+  startCol?: number;
+
+  /** 1-based line where the span ends, when it differs from `startLine`. */
+  endLine?: number;
+
+  /** 1-based column where the span ends, when known. */
+  endCol?: number;
+
+  /** The source text of the span, when captured. */
+  text?: string;
+}

package/src/structures/IGraphLookup.ts

@@ -0,0 +1,80 @@
+import { GraphLanguage } from "./GraphLanguage";
+import { GraphNodeKind } from "./GraphNodeKind";
+import { IGraphDecorator } from "./IGraphDecorator";
+import { IGraphNext } from "./IGraphNext";
+import { IGraphOverview } from "./IGraphOverview";
+
+/** Targeted symbol lookup when a concrete name or handle is being resolved. */
+export interface IGraphLookup {
+  /** Discriminator for targeted symbol lookup. */
+  type: "lookup";
+
+  /** Ranked symbol matches for the query. */
+  hits: IGraphLookup.IHit[];
+
+  /** Query terms that matched nothing. */
+  unknown?: string[];
+
+  /** How to use this source-free result next. */
+  next: IGraphNext;
+
+  /** Human-readable compatibility note mirroring `next`. */
+  guide: string;
+}
+
+export namespace IGraphLookup {
+  /** Find a concrete class, method, function, property, type, or dotted handle. */
+  export interface IRequest {
+    /** Discriminator for targeted symbol lookup. */
+    type: "lookup";
+
+    /**
+     * What to find, in natural language and code vocabulary mixed freely: a
+     * symbol name, a dotted member (`Service.create`), or a short phrase
+     * (`request handler`). Exact names are not required, but this is not a
+     * second broad entrypoints call. Use it when a named handle is missing or
+     * ambiguous.
+     */
+    query: string;
+
+    /** Restrict hits to this language. */
+    language?: GraphLanguage;
+
+    /** Restrict hits to this declaration kind. */
+    kind?: GraphNodeKind;
+
+    /**
+     * Maximum hits to return.
+     *
+     * Prefer the default. Large hit lists usually mean the query is too broad;
+     * refine the name instead of raising this.
+     *
+     * @default 5
+     */
+    limit?: number;
+
+    /**
+     * Include dependency-boundary declarations from bundled libraries. Leave
+     * false for project-source answers; enable only when external type/API
+     * boundaries are the question.
+     *
+     * @default false
+     */
+    includeExternal?: boolean;
+  }
+
+  /** One ranked hit with a handle to follow via `details` or `trace`. */
+  export interface IHit extends IGraphOverview.INode {
+    /** Relative relevance; higher is a better match. */
+    score: number;
+
+    /**
+     * The hit's declaration signature, so you can often answer without
+     * requesting details.
+     */
+    signature?: string;
+
+    /** Decorators written on this declaration, when any. */
+    decorators?: IGraphDecorator[];
+  }
+}

package/src/structures/IGraphNext.ts

@@ -0,0 +1,23 @@
+/** The required next step from a language-server-derived graph result. */
+export interface IGraphNext {
+  /**
+   * Answer, continue graph inspection, leave graph, or clarify.
+   *
+   * `answer` means the returned graph result already carries the evidence
+   * contract for the current question, even when the slice is capped. Do not
+   * call graph again or read files to re-check or complete it.
+   */
+  action: "answer" | "inspect" | "outside" | "clarify";
+
+  /** Smallest graph request type to use when `action` is `inspect`. */
+  request?:
+    | "entrypoints"
+    | "lookup"
+    | "trace"
+    | "details"
+    | "overview"
+    | "tour";
+
+  /** Why the returned graph evidence supports that action. */
+  reason: string;
+}

package/src/structures/IGraphNode.ts

@@ -0,0 +1,76 @@
+import { GraphLanguage } from "./GraphLanguage";
+import { GraphNodeKind } from "./GraphNodeKind";
+import { IGraphDecorator } from "./IGraphDecorator";
+import { IGraphEvidence } from "./IGraphEvidence";
+
+/**
+ * One node in the graph: a declared symbol or a structural container (file,
+ * package).
+ *
+ * The `id` is position-invariant: `path#qualifiedName:kind` (e.g.
+ * `src/order.ts#OrderService.create:method`), so inserting a line above a
+ * declaration does not re-key it. Line and span live in `evidence` and are
+ * never part of identity.
+ */
+export interface IGraphNode {
+  /** Position-invariant identity (see the interface doc for the id grammar). */
+  id: string;
+
+  /** What this node represents. */
+  kind: GraphNodeKind;
+
+  /** The source language this node was declared in. */
+  language: GraphLanguage;
+
+  /** The simple, unqualified declared name (`create`, `OrderService`, `App`). */
+  name: string;
+
+  /**
+   * The owner-qualified name, when the node lives inside another declaration:
+   * `OrderService.create`, `Shopping.ISale`. Absent for a top-level
+   * declaration.
+   */
+  qualifiedName?: string;
+
+  /** Project-relative path of the file that declares this node. */
+  file: string;
+
+  /**
+   * True when the declaration lives outside the workspace (a dependency). The
+   * graph keeps the leaf as a named endpoint but does not walk into its
+   * internals.
+   */
+  external: boolean;
+
+  /**
+   * True when `file` is git-ignored generated code (a Prisma client, a codegen
+   * output). Projections desurface these so generated nodes do not bury the
+   * authored graph.
+   */
+  ignored?: boolean;
+
+  /** True when the symbol is part of its module's export surface. */
+  exported?: boolean;
+
+  /** The declaration signature, for display. */
+  signature?: string;
+
+  /** Declaration modifiers, when the declaration pass recorded any. */
+  modifiers?: string[];
+
+  /**
+   * The decorators written on this declaration, in source order, when it has
+   * any: raw decorator facts (`@Controller`, `@Get`) a consumer can interpret
+   * without re-parsing source.
+   */
+  decorators?: IGraphDecorator[];
+
+  /** The declaration span, for display and signatures. */
+  evidence?: IGraphEvidence;
+
+  /**
+   * The implementation span when a callable/property member is implemented by a
+   * function assignment separate from its declaration.
+   */
+  implementation?: IGraphEvidence;
+}