@samchon/graph 0.1.0

package/lib/structures/IGraphDecorator.d.ts

@@ -0,0 +1,22 @@
+import { IGraphEvidence } from "./IGraphEvidence";
+/**
+ * A decorator as written on a declaration, carried on the decorated
+ * {@link IGraphNode}'s `decorators`.
+ *
+ * The graph reports the decorator faithfully rather than interpreting any
+ * framework's convention: the `name` is the decorator as written (`Controller`,
+ * `Get`, `TypedRoute.Get`, ...), and statically resolvable literal arguments
+ * are preserved so a consumer can apply its own meaning without re-parsing
+ * source.
+ */
+export interface IGraphDecorator {
+    /**
+     * The decorator name as written, qualified through its access path:
+     * `Controller`, `Get`, `TypedRoute.Get`, `MessagePattern`.
+     */
+    name: string;
+    /** The literal call arguments, in source order. Empty for a bare decorator. */
+    arguments?: string[];
+    /** The decorator expression span, for display. */
+    evidence?: IGraphEvidence;
+}

package/lib/structures/IGraphDecorator.js

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

package/lib/structures/IGraphDecorator.js.map

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

package/lib/structures/IGraphDetails.d.ts

@@ -0,0 +1,126 @@
+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 declare namespace IGraphDetails {
+    /** Which selected handles to inspect, and how much of each to return. */
+    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. */
+    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. */
+    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. */
+    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/lib/structures/IGraphDetails.js

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

package/lib/structures/IGraphDetails.js.map

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

package/lib/structures/IGraphDiagnostic.d.ts

@@ -0,0 +1,23 @@
+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/lib/structures/IGraphDiagnostic.js

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

package/lib/structures/IGraphDiagnostic.js.map

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

package/lib/structures/IGraphDump.d.ts

@@ -0,0 +1,37 @@
+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/lib/structures/IGraphDump.js

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

package/lib/structures/IGraphDump.js.map

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

package/lib/structures/IGraphEdge.d.ts

@@ -0,0 +1,20 @@
+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/lib/structures/IGraphEdge.js

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

package/lib/structures/IGraphEdge.js.map

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

package/lib/structures/IGraphEntrypoints.d.ts

@@ -0,0 +1,57 @@
+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 declare 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.
+     */
+    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. */
+    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/lib/structures/IGraphEntrypoints.js

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

package/lib/structures/IGraphEntrypoints.js.map

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

package/lib/structures/IGraphEscape.d.ts

@@ -0,0 +1,40 @@
+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 declare namespace IGraphEscape {
+    /** Skip graph work when graph evidence is unnecessary or exhausted. */
+    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/lib/structures/IGraphEscape.js

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

package/lib/structures/IGraphEscape.js.map

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

package/lib/structures/IGraphEvidence.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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/lib/structures/IGraphEvidence.js

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

package/lib/structures/IGraphEvidence.js.map

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

package/lib/structures/IGraphLookup.d.ts

@@ -0,0 +1,66 @@
+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 declare namespace IGraphLookup {
+    /** Find a concrete class, method, function, property, type, or dotted handle. */
+    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`. */
+    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/lib/structures/IGraphLookup.js

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

package/lib/structures/IGraphLookup.js.map

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

package/lib/structures/IGraphNext.d.ts

@@ -0,0 +1,15 @@
+/** 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/lib/structures/IGraphNext.js

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

package/lib/structures/IGraphNext.js.map

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

package/lib/structures/IGraphNode.d.ts

@@ -0,0 +1,62 @@
+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;
+}

package/lib/structures/IGraphNode.js

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

package/lib/structures/IGraphNode.js.map

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