@samchon/graph 0.1.0

package/lib/operations/runTrace.js

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTrace = runTrace;
+const common_1 = require("./common");
+const DEFAULT_DEPTH = 2;
+const DEFAULT_MAX_NODES = 6;
+const MAX_OPEN_DEPTH = 2;
+const MAX_OPEN_NODES = 8;
+const MAX_IMPACT_DEPTH = 4;
+const MAX_IMPACT_NODES = 16;
+const MAX_HOPS_PER_NODE = 2;
+const MAX_STEPS = 6;
+const MAX_PATH_DEPTH = 12;
+/**
+ * Breadth-first trace along the dependency graph. Structural
+ * (contains/exports/imports) edges are excluded so the path is real call/type
+ * flow; forward walks callees, reverse and impact walk callers. Impact
+ * additionally tags each reached node's role so the blast radius on the public
+ * surface is legible.
+ */
+function runTrace(graph, props) {
+    const direction = props.direction ?? "forward";
+    const focus = props.focus ?? "all";
+    const impact = direction === "impact";
+    const reverse = direction === "reverse" || direction === "impact";
+    const includeExternal = props.includeExternal === true;
+    const maxDepth = (0, common_1.bound)(props.maxDepth, DEFAULT_DEPTH, 1, impact ? MAX_IMPACT_DEPTH : MAX_OPEN_DEPTH);
+    const maxNodes = (0, common_1.bound)(props.maxNodes, DEFAULT_MAX_NODES, 1, impact ? MAX_IMPACT_NODES : MAX_OPEN_NODES);
+    const maxHops = maxNodes * MAX_HOPS_PER_NODE;
+    const start = (0, common_1.resolveHandle)(graph, props.from);
+    if (start.candidates !== undefined) {
+        return {
+            type: "trace",
+            direction,
+            hops: [],
+            reached: [],
+            truncated: false,
+            candidates: start.candidates.map((node) => traceNode(graph, node)),
+            next: (0, common_1.resultNext)("clarify", "The start handle is ambiguous; choose one candidate."),
+            guide: (0, common_1.resultGuide)("Disambiguate with returned candidates."),
+        };
+    }
+    if (start.node === undefined) {
+        return {
+            type: "trace",
+            direction,
+            hops: [],
+            reached: [],
+            truncated: false,
+            next: (0, common_1.resultNext)("clarify", "The start handle did not resolve in the graph."),
+            guide: (0, common_1.resultGuide)("Answer that the graph has no trace from this handle."),
+        };
+    }
+    // Path mode: with `to`, return the dependency path from `from` to `to`, the
+    // one-call answer for "how does A reach B", instead of an open-ended trace.
+    if (props.to !== undefined && props.to.trim() !== "") {
+        const target = (0, common_1.resolveHandle)(graph, props.to);
+        const startNode = traceNode(graph, start.node);
+        // Mirror the start handle: an ambiguous or unresolved target must ask to
+        // clarify, not report an empty path with next: "answer" (which reads as
+        // "no flow exists").
+        if (target.candidates !== undefined) {
+            return {
+                type: "trace",
+                direction: "path",
+                start: startNode,
+                hops: [],
+                reached: [],
+                truncated: false,
+                candidates: target.candidates.map((node) => traceNode(graph, node)),
+                next: (0, common_1.resultNext)("clarify", "The target handle is ambiguous; choose one candidate."),
+                guide: (0, common_1.resultGuide)("Disambiguate the target with returned candidates."),
+            };
+        }
+        if (target.node === undefined) {
+            return {
+                type: "trace",
+                direction: "path",
+                start: startNode,
+                hops: [],
+                reached: [],
+                truncated: false,
+                next: (0, common_1.resultNext)("clarify", "The target handle did not resolve in the graph."),
+                guide: (0, common_1.resultGuide)("Answer that the graph has no path to this target."),
+            };
+        }
+        const found = findPath(graph, start.node.id, target.node.id, (0, common_1.bound)(props.maxDepth, MAX_PATH_DEPTH, 1, MAX_PATH_DEPTH), focus, includeExternal);
+        return {
+            type: "trace",
+            direction: "path",
+            start: startNode,
+            target: traceNode(graph, target.node),
+            path: (found?.path ?? []).map((node, depth) => traceNode(graph, node, depth, true)),
+            hops: found?.hops ?? [],
+            reached: [],
+            truncated: false,
+            steps: steps(graph, found?.hops ?? []),
+            next: (0, common_1.resultNext)("answer", "The path result is the flow answer; cite path nodes and evidence ranges."),
+            guide: (0, common_1.resultGuide)("Use path, hops, and evidence as the flow answer."),
+        };
+    }
+    const hops = [];
+    const reached = new Map();
+    const visited = new Set([start.node.id]);
+    let queue = [{ id: start.node.id, depth: 0 }];
+    let truncated = false;
+    while (queue.length > 0) {
+        const next = [];
+        for (const { id, depth } of queue) {
+            if (depth >= maxDepth) {
+                truncated = true;
+                continue;
+            }
+            const edges = orderedEdges(graph, reverse ? graph.incoming(id) : graph.outgoing(id), impact).filter((edge) => traversable(edge, focus));
+            for (const edge of edges) {
+                const otherId = reverse ? edge.from : edge.to;
+                const other = graph.node(otherId);
+                if (other === undefined || other.kind === "file")
+                    continue;
+                if (!includeExternal && other.external)
+                    continue;
+                const hop = hopOf(edge, depth + 1);
+                // A back-edge to the start or an already-reached node: record the hop;
+                // its endpoints are already represented.
+                if (visited.has(otherId)) {
+                    if (hops.length >= maxHops)
+                        truncated = true;
+                    else
+                        hops.push(hop);
+                    continue;
+                }
+                // A new node past the cap is left unrepresented, so drop its hop too:
+                // every hop's endpoints stay resolvable in `reached`/`start`.
+                if (reached.size >= maxNodes) {
+                    truncated = true;
+                    continue;
+                }
+                if (hops.length >= maxHops) {
+                    truncated = true;
+                    continue;
+                }
+                visited.add(otherId);
+                reached.set(otherId, traceNode(graph, other, depth + 1, false, impact));
+                next.push({ id: otherId, depth: depth + 1 });
+                hops.push(hop);
+            }
+        }
+        queue = next;
+    }
+    return {
+        type: "trace",
+        start: traceNode(graph, start.node),
+        direction,
+        hops,
+        reached: [...reached.values()],
+        truncated,
+        steps: steps(graph, hops),
+        next: (0, common_1.resultNext)("answer", "Steps, hops, reached nodes, and evidence ranges are the flow answer surface."),
+        guide: (0, common_1.resultGuide)("Use steps, hops, reached nodes, and evidence ranges as the flow answer."),
+    };
+}
+function findPath(graph, startId, targetId, maxDepth, focus, includeExternal) {
+    const parent = new Map();
+    const queue = [{ id: startId, depth: 0 }];
+    const visited = new Set([startId]);
+    while (queue.length > 0) {
+        const item = queue.shift();
+        /* c8 ignore next */
+        if (item.depth >= maxDepth)
+            continue;
+        for (const edge of graph.outgoing(item.id).filter((e) => traversable(e, focus)).sort(common_1.compareEdges)) {
+            const other = graph.node(edge.to);
+            if (other === undefined || other.kind === "file")
+                continue;
+            if (!includeExternal && other.external)
+                continue;
+            if (visited.has(edge.to))
+                continue;
+            visited.add(edge.to);
+            parent.set(edge.to, { from: item.id, edge });
+            if (edge.to === targetId) {
+                const ids = [targetId];
+                let cursor = targetId;
+                while (cursor !== startId) {
+                    const p = parent.get(cursor);
+                    ids.unshift(p.from);
+                    cursor = p.from;
+                }
+                const nodes = ids
+                    .map((id) => graph.node(id))
+                    .filter((node) => node !== undefined);
+                const pathHops = [];
+                for (let i = 1; i < ids.length; i++) {
+                    const p = parent.get(ids[i]);
+                    if (p !== undefined)
+                        pathHops.push(hopOf(p.edge, i));
+                }
+                return { path: nodes, hops: pathHops };
+            }
+            queue.push({ id: edge.to, depth: item.depth + 1 });
+        }
+    }
+    return null;
+}
+/**
+ * Order edges before traversal. A normal trace ranks by edge kind then
+ * evidence; an impact trace ranks reached endpoints by public-surface role
+ * first so the blast radius on the exported/test surface leads.
+ */
+// Only the impact BFS orders edges here, and it always traverses incoming
+// edges, so the ranked endpoint is the edge's `from`.
+function orderedEdges(graph, edges, impact) {
+    if (!impact)
+        return [...edges].sort(common_1.compareEdges);
+    return [...edges].sort((a, b) => impactEndpointRank(graph, a.from) - impactEndpointRank(graph, b.from) ||
+        (0, common_1.edgeRank)(a.kind) - (0, common_1.edgeRank)(b.kind) ||
+        (a.evidence?.startLine ?? 999999) - (b.evidence?.startLine ?? 999999));
+}
+function impactEndpointRank(graph, id) {
+    const node = graph.node(id);
+    // `id` is always an endpoint of a real graph edge, so it resolves.
+    /* c8 ignore next */
+    if (node === undefined)
+        return 9;
+    if ((0, common_1.isTestPath)(node.file))
+        return 0;
+    if (node.exported)
+        return 1;
+    if (node.external || node.ignored)
+        return 4;
+    return 2;
+}
+function traversable(edge, focus) {
+    if (edge.kind === "contains" || edge.kind === "exports" || edge.kind === "imports") {
+        return false;
+    }
+    if (focus === "execution")
+        return (0, common_1.isExecution)(edge.kind);
+    if (focus === "types")
+        return (0, common_1.isTypeEdge)(edge.kind);
+    return true;
+}
+function hopOf(edge, depth) {
+    return {
+        from: edge.from,
+        to: edge.to,
+        kind: edge.kind,
+        depth,
+        ...(edge.evidence !== undefined ? { evidence: (0, common_1.publicEvidence)(edge.evidence) } : {}),
+    };
+}
+function traceNode(graph, node, depth, withSignature = false, withRoles = false) {
+    const out = {
+        ...(0, common_1.summaryOf)(node),
+        ...(depth !== undefined ? { depth } : {}),
+    };
+    if (withSignature) {
+        const signature = (0, common_1.signatureOf)(graph.project, node);
+        if (signature !== undefined)
+            out.signature = signature;
+    }
+    if (withRoles) {
+        const roles = [];
+        if (node.exported)
+            roles.push("exported");
+        if ((0, common_1.isTestPath)(node.file))
+            roles.push("test");
+        if (roles.length > 0)
+            out.roles = roles;
+    }
+    return out;
+}
+function steps(graph, hops) {
+    return hops.slice(0, MAX_STEPS).map((hop) => {
+        const from = graph.node(hop.from);
+        const to = graph.node(hop.to);
+        const lhs = from.qualifiedName ?? from.name;
+        const rhs = to.qualifiedName ?? to.name;
+        const at = hop.evidence === undefined ? "" : ` at ${hop.evidence.file}:${hop.evidence.startLine}`;
+        return `${lhs} -[${hop.kind}${at}]-> ${rhs}`;
+    });
+}
+//# sourceMappingURL=runTrace.js.map

package/lib/operations/runTrace.js.map

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

package/lib/operations/signatureOf.d.ts

@@ -0,0 +1,2 @@
+import { IGraphNode } from "../structures";
+export declare function signatureOf(project: string, node: IGraphNode): string | undefined;

package/lib/operations/signatureOf.js

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signatureOf = signatureOf;
+const node_path_1 = __importDefault(require("node:path"));
+const fs_1 = require("../utils/fs");
+function signatureOf(project, node) {
+    if (node.signature !== undefined && node.signature.trim() !== "") {
+        return compactSignature(node.signature);
+    }
+    if (node.evidence === undefined || node.file === "")
+        return undefined;
+    const lines = (0, fs_1.readLines)(node_path_1.default.join(project, node.evidence.file));
+    if (lines === undefined)
+        return undefined;
+    const start = Math.max(0, node.evidence.startLine - 1);
+    const end = node.evidence.endLine === undefined
+        ? Math.min(lines.length, start + 4)
+        : Math.min(lines.length, node.evidence.endLine);
+    const out = [];
+    for (let i = start; i < end && out.length < 4; i++) {
+        const line = lines[i];
+        /* c8 ignore next */
+        if (line === undefined)
+            break;
+        out.push(line);
+        const trimmed = line.trimEnd();
+        if (trimmed.endsWith(";") || trimmed.endsWith("{") || trimmed.endsWith("}")) {
+            break;
+        }
+    }
+    const text = out.join("\n").trim();
+    return text === "" ? undefined : compactSignature(text);
+}
+function compactSignature(text) {
+    return text
+        .split(/\r?\n/)
+        .slice(0, 4)
+        .join("\n")
+        .replace(/\s+$/gm, "")
+        .trim();
+}
+//# sourceMappingURL=signatureOf.js.map

package/lib/operations/signatureOf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signatureOf.js","sourceRoot":"","sources":["../../src/operations/signatureOf.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAG7B,oCAAwC;AAExC,qBAA4B,OAAe,EAAE,IAAgB;IAC3D,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACjE,OAAO,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IACtE,MAAM,KAAK,GAAG,IAAA,cAAS,EAAC,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAChE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IACvD,MAAM,GAAG,GACP,IAAI,CAAC,QAAQ,CAAC,OAAO,KAAK,SAAS;QACjC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,GAAG,CAAC,CAAC;QACnC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,oBAAoB;QACpB,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM;QAC9B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACf,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5E,MAAM;QACR,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY;IACpC,OAAO,IAAI;SACR,KAAK,CAAC,OAAO,CAAC;SACd,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;SACX,IAAI,CAAC,IAAI,CAAC;SACV,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;SACrB,IAAI,EAAE,CAAC;AACZ,CAAC"}

package/lib/operations/subwords.d.ts

@@ -0,0 +1 @@
+export declare function subwords(text: string): string[];

package/lib/operations/subwords.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subwords = subwords;
+function subwords(text) {
+    return text
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .split(/[^a-zA-Z0-9_$]+/)
+        .map((word) => word.toLowerCase())
+        .filter((word) => word.length > 0);
+}
+//# sourceMappingURL=subwords.js.map

package/lib/operations/subwords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subwords.js","sourceRoot":"","sources":["../../src/operations/subwords.ts"],"names":[],"mappings":";;;AAAA,kBAAyB,IAAY;IACnC,OAAO,IAAI;SACR,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC;SACzC,KAAK,CAAC,iBAAiB,CAAC;SACxB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;SACjC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC"}

package/lib/operations/summaryOf.d.ts

@@ -0,0 +1,2 @@
+import { IGraphNode, IGraphOverview } from "../structures";
+export declare function summaryOf(node: IGraphNode): IGraphOverview.INode;

package/lib/operations/summaryOf.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summaryOf = summaryOf;
+function summaryOf(node) {
+    const out = {
+        id: node.id,
+        name: node.qualifiedName ?? node.name,
+        kind: node.kind,
+        language: node.language,
+        file: node.file,
+    };
+    if (node.evidence?.startLine !== undefined)
+        out.line = node.evidence.startLine;
+    const span = node.implementation ?? node.evidence;
+    if (span !== undefined) {
+        out.sourceSpan = {
+            file: span.file,
+            startLine: span.startLine,
+            ...(span.endLine !== undefined ? { endLine: span.endLine } : {}),
+        };
+    }
+    return out;
+}
+//# sourceMappingURL=summaryOf.js.map

package/lib/operations/summaryOf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summaryOf.js","sourceRoot":"","sources":["../../src/operations/summaryOf.ts"],"names":[],"mappings":";;;AAEA,mBAA0B,IAAgB;IACxC,MAAM,GAAG,GAAyB;QAChC,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,IAAI,EAAE,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,IAAI;QACrC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,IAAI,EAAE,IAAI,CAAC,IAAI;KAChB,CAAC;IACF,IAAI,IAAI,CAAC,QAAQ,EAAE,SAAS,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;IAC/E,MAAM,IAAI,GAAG,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,QAAQ,CAAC;IAClD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,GAAG,CAAC,UAAU,GAAG;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/lib/runGraph.d.ts

@@ -0,0 +1 @@
+export declare function runGraph(argv?: readonly string[]): number | void;

package/lib/runGraph.js

@@ -0,0 +1,165 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGraph = runGraph;
+const buildGraphDump_1 = require("./indexer/buildGraphDump");
+const LANGUAGE_SPECS_1 = require("./indexer/LANGUAGE_SPECS");
+const startServer_1 = require("./mcp/startServer");
+const package_json_1 = __importDefault(require("../package.json"));
+const VERSION = package_json_1.default.version;
+function runGraph(argv = process.argv.slice(2)) {
+    try {
+        if (argv[0] === "dump") {
+            void runDump(argv.slice(1));
+            return;
+        }
+        if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+            process.stdout.write(helpText());
+            return 0;
+        }
+        const options = parseArgs(argv);
+        void (0, startServer_1.startServer)({ ...options, version: VERSION }).catch((error) => {
+            /* c8 ignore next 2 */
+            writeError(error);
+            process.exit(1);
+        });
+    }
+    catch (error) {
+        writeError(error);
+        return 1;
+    }
+}
+async function runDump(argv) {
+    try {
+        const dump = await (0, buildGraphDump_1.buildGraphDump)(parseArgs(argv));
+        process.stdout.write(`${JSON.stringify(dump, null, 2)}\n`);
+    }
+    catch (error) {
+        writeError(error);
+        process.exitCode = 1;
+    }
+}
+function parseArgs(argv) {
+    const options = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const next = () => {
+            const value = argv[++i];
+            if (value === undefined)
+                throw new Error(`Missing value for ${arg}`);
+            return value;
+        };
+        if (arg === "--cwd")
+            options.cwd = next();
+        else if (arg.startsWith("--cwd="))
+            options.cwd = arg.slice("--cwd=".length);
+        else if (arg === "--mode")
+            options.mode = parseMode(next());
+        else if (arg.startsWith("--mode="))
+            options.mode = parseMode(arg.slice("--mode=".length));
+        else if (arg === "--language")
+            options.languages = [...(options.languages ?? []), parseLanguage(next())];
+        else if (arg.startsWith("--language=")) {
+            options.languages = [
+                ...(options.languages ?? []),
+                parseLanguage(arg.slice("--language=".length)),
+            ];
+        }
+        else if (arg === "--server")
+            options.server = next();
+        else if (arg.startsWith("--server="))
+            options.server = arg.slice("--server=".length);
+        else if (arg === "--server-arg") {
+            options.serverArgs = [...(options.serverArgs ?? []), next()];
+        }
+        else if (arg.startsWith("--server-arg=")) {
+            options.serverArgs = [
+                ...(options.serverArgs ?? []),
+                arg.slice("--server-arg=".length),
+            ];
+        }
+        else if (arg === "--max-files")
+            options.maxFiles = parseInteger(next());
+        else if (arg.startsWith("--max-files=")) {
+            options.maxFiles = parseInteger(arg.slice("--max-files=".length));
+        }
+        else if (arg === "--lsp-timeout-ms") {
+            options.lspTimeoutMs = parseInteger(next());
+        }
+        else if (arg.startsWith("--lsp-timeout-ms=")) {
+            options.lspTimeoutMs = parseInteger(arg.slice("--lsp-timeout-ms=".length));
+        }
+        else if (arg === "--lsp-reference-limit") {
+            options.lspReferenceLimit = parseInteger(next());
+        }
+        else if (arg.startsWith("--lsp-reference-limit=")) {
+            options.lspReferenceLimit = parseInteger(arg.slice("--lsp-reference-limit=".length));
+        }
+        else if (arg === "--lsp-concurrency") {
+            options.lspConcurrency = parseInteger(next());
+        }
+        else if (arg.startsWith("--lsp-concurrency=")) {
+            options.lspConcurrency = parseInteger(arg.slice("--lsp-concurrency=".length));
+        }
+        else if (arg === "--lsp-warmup-timeout-ms") {
+            options.lspWarmupTimeoutMs = parseInteger(next());
+        }
+        else if (arg.startsWith("--lsp-warmup-timeout-ms=")) {
+            options.lspWarmupTimeoutMs = parseInteger(arg.slice("--lsp-warmup-timeout-ms=".length));
+        }
+        else if (arg === "--graph-file") {
+            options.graphFile = next();
+        }
+        else if (arg.startsWith("--graph-file=")) {
+            options.graphFile = arg.slice("--graph-file=".length);
+        }
+        else {
+            throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    return options;
+}
+function parseMode(value) {
+    if (value === "auto" || value === "lsp" || value === "static")
+        return value;
+    throw new Error(`Invalid --mode: ${value}`);
+}
+const ALLOWED_LANGUAGES = new Set([
+    ...LANGUAGE_SPECS_1.LANGUAGE_SPECS.map((spec) => spec.language),
+    "unknown",
+]);
+function parseLanguage(value) {
+    if (!ALLOWED_LANGUAGES.has(value))
+        throw new Error(`Invalid --language: ${value}`);
+    return value;
+}
+function parseInteger(value) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+        throw new Error(`Expected positive integer, got: ${value}`);
+    }
+    return Math.floor(parsed);
+}
+function helpText() {
+    return `@samchon/graph
+
+Usage:
+  samchon-graph [--cwd DIR] [--mode auto|lsp|static] [--language LANG]
+  samchon-graph dump [same options]
+
+Options:
+  --server CMD              Override the language server command.
+  --server-arg ARG          Add one language server argument.
+  --max-files N             Cap source files indexed.
+  --lsp-timeout-ms N        Per-request LSP timeout.
+  --lsp-reference-limit N   Reference targets to collect edges for.
+  --lsp-concurrency N       Concurrent reference requests.
+  --graph-file PATH         Serve a pre-built dump instead of indexing.
+`;
+}
+function writeError(error) {
+    process.stderr.write(`@samchon/graph: ${error.message}\n`);
+}
+//# sourceMappingURL=runGraph.js.map

package/lib/runGraph.js.map

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

package/lib/structures/GraphEdgeKind.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The relationship a directed edge encodes between two {@link IGraphNode}s.
+ *
+ * Structural edges (`contains`, `exports`, `imports`) come from the declaration
+ * pass. Value and type edges (`calls`, `accesses`, `instantiates`, `type_ref`,
+ * `extends`, `implements`, `overrides`, `renders`) are resolved by the language
+ * server — `renders` is a component use. `decorates` carries a decorator fact
+ * and `tests` a test-to-subject relationship.
+ */
+export type GraphEdgeKind = "contains" | "exports" | "imports" | "calls" | "accesses" | "instantiates" | "type_ref" | "extends" | "implements" | "overrides" | "decorates" | "renders" | "tests" | "references";

package/lib/structures/GraphEdgeKind.js

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

package/lib/structures/GraphEdgeKind.js.map

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

package/lib/structures/GraphLanguage.d.ts

@@ -0,0 +1,2 @@
+/** A source language a graph node can be declared in. */
+export type GraphLanguage = "typescript" | "javascript" | "go" | "rust" | "cpp" | "c" | "java" | "csharp" | "kotlin" | "swift" | "scala" | "zig" | "python" | "ruby" | "php" | "lua" | "bash" | "dart" | "unknown";

package/lib/structures/GraphLanguage.js

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

package/lib/structures/GraphLanguage.js.map

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

package/lib/structures/GraphNodeKind.d.ts

@@ -0,0 +1,11 @@
+/**
+ * What a graph node represents.
+ *
+ * The symbol kinds (`file` through `constructor`) are declarations the language
+ * server owns and resolves. `external_symbol` is a dependency-boundary leaf the
+ * workspace references but does not declare. The graph keeps it as a named
+ * endpoint without walking into the dependency's internals.
+ *
+ * Used as the `kind` discriminant on {@link IGraphNode}.
+ */
+export type GraphNodeKind = "file" | "package" | "namespace" | "module" | "function" | "class" | "interface" | "type" | "enum" | "variable" | "method" | "property" | "parameter" | "field" | "constructor" | "external_symbol";

package/lib/structures/GraphNodeKind.js

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

package/lib/structures/GraphNodeKind.js.map

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