@samchon/graph 0.1.0

package/lib/operations/runDetails.js

@@ -0,0 +1,190 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDetails = runDetails;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const common_1 = require("./common");
+const DEFAULT_NEIGHBORS = 2;
+const MAX_NEIGHBORS = 3;
+const DEFAULT_MEMBERS = 6;
+const MAX_MEMBERS = 8;
+const DEFAULT_DEPENDENCIES = 2;
+const MAX_DEPENDENCIES = 4;
+// Object literal outlines are navigation aids, not source excerpts.
+const MAX_OBJECT_MEMBER_LINES = 300;
+// Kinds whose value is their member outline, not implementation text.
+const CONTAINER_KINDS = new Set([
+    "class",
+    "interface",
+    "namespace",
+    "module",
+    "enum",
+    "file",
+]);
+const EXECUTION_KINDS = new Set(["calls", "instantiates", "accesses", "renders"]);
+const TYPE_KINDS = new Set(["type_ref", "extends", "implements", "overrides"]);
+/**
+ * Resolve each handle to its declared shape: sourceSpan anchors, signature,
+ * direct dependencies, and for containers, member outlines. It answers from the
+ * graph's resolved structure instead of inlining implementation bodies.
+ */
+function runDetails(graph, props) {
+    const neighborLimit = (0, common_1.bound)(props.neighborLimit, DEFAULT_NEIGHBORS, 1, MAX_NEIGHBORS);
+    const memberLimit = (0, common_1.bound)(props.memberLimit, DEFAULT_MEMBERS, 1, MAX_MEMBERS);
+    const dependencyLimit = (0, common_1.bound)(props.dependencyLimit, DEFAULT_DEPENDENCIES, 1, MAX_DEPENDENCIES);
+    const includeExternal = props.includeExternal === true;
+    const nodes = [];
+    const unknown = [];
+    for (const handle of props.handles.slice(0, 6)) {
+        const resolved = (0, common_1.resolveHandle)(graph, handle);
+        if (resolved.node === undefined) {
+            unknown.push(handle);
+            continue;
+        }
+        const node = resolved.node;
+        const detail = { ...(0, common_1.summaryOf)(node) };
+        const signature = (0, common_1.signatureOf)(graph.project, node);
+        if (signature !== undefined)
+            detail.signature = signature;
+        if (node.decorators !== undefined && node.decorators.length > 0) {
+            detail.decorators = node.decorators;
+        }
+        if (node.implementation !== undefined)
+            detail.implementation = (0, common_1.publicEvidence)(node.implementation);
+        const calls = (0, common_1.referencesFromEdges)(graph, graph.outgoing(node.id), "to", dependencyLimit, includeExternal, EXECUTION_KINDS);
+        if (calls.length > 0)
+            detail.calls = calls;
+        const types = (0, common_1.referencesFromEdges)(graph, graph.outgoing(node.id), "to", dependencyLimit, includeExternal, TYPE_KINDS);
+        if (types.length > 0)
+            detail.types = types;
+        if (CONTAINER_KINDS.has(node.kind)) {
+            const list = containerMembers(graph, node, memberLimit);
+            if (list.length > 0)
+                detail.members = list;
+        }
+        // A variable bound to an object literal has no `contains` members; parse its
+        // source span for the top-level property/method outline a consumer reaches
+        // for, without inlining the body.
+        if (node.kind === "variable" && detail.sourceSpan !== undefined) {
+            const list = objectLiteralMembers(graph.project, detail.sourceSpan, memberLimit);
+            if (list.length > 0)
+                detail.members = list;
+        }
+        if (props.neighbors === true) {
+            detail.dependsOn = (0, common_1.referencesFromEdges)(graph, graph.outgoing(node.id), "to", neighborLimit, includeExternal);
+            detail.dependedOnBy = (0, common_1.referencesFromEdges)(graph, graph.incoming(node.id), "from", neighborLimit, includeExternal);
+        }
+        const diagnostics = graph.diagnosticsFor(node.file);
+        if (diagnostics.length > 0)
+            detail.diagnostics = diagnostics.slice(0, 5);
+        nodes.push(detail);
+    }
+    return {
+        type: "details",
+        nodes,
+        unknown,
+        next: (0, common_1.resultNext)("answer", "Selected signatures, members, dependencies, diagnostics, and spans are enough for a shape or reading-anchor answer."),
+        guide: (0, common_1.resultGuide)("Use signatures, members, calls, types, diagnostics, and sourceSpan anchors as selected symbol facts."),
+    };
+}
+/** The members a container owns (via `contains`), each with its own signature. */
+function containerMembers(graph, node, limit) {
+    const out = [];
+    for (const edge of graph.outgoing(node.id)) {
+        if (edge.kind !== "contains")
+            continue;
+        const member = graph.node(edge.to);
+        if (member === undefined)
+            continue;
+        const signature = (0, common_1.signatureOf)(graph.project, member);
+        out.push({
+            name: member.qualifiedName ?? member.name,
+            kind: member.kind,
+            ...(member.evidence?.startLine !== undefined ? { line: member.evidence.startLine } : {}),
+            ...(signature !== undefined ? { signature } : {}),
+        });
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+/**
+ * The top-level members of an object literal, parsed from its source span by
+ * bracket depth. A member is a property (`name:`) or method (`name(`) declared
+ * directly inside the outermost `{ }`.
+ */
+function objectLiteralMembers(project, span, limit) {
+    if (span.endLine === undefined)
+        return [];
+    if (span.endLine - span.startLine > MAX_OBJECT_MEMBER_LINES)
+        return [];
+    const lines = fileLines(project, span.file);
+    if (lines === undefined)
+        return [];
+    const start = Math.max(0, span.startLine - 1);
+    const end = Math.min(lines.length - 1, span.endLine - 1);
+    const members = [];
+    let depth = 0;
+    let entered = false;
+    for (let i = start; i <= end; i++) {
+        // `end` is clamped to lines.length-1, so every index is in range; the `?? ""`
+        // is a defensive fallback that cannot be reached.
+        /* c8 ignore next */
+        const raw = lines[i] ?? "";
+        const text = stripStrings(raw);
+        if (entered && depth === 1) {
+            const member = objectMemberOf(raw, i + 1);
+            if (member !== undefined) {
+                members.push(member);
+                if (members.length >= limit)
+                    break;
+            }
+        }
+        for (const char of text) {
+            if (char === "{") {
+                depth++;
+                entered = true;
+            }
+            else if (char === "}") {
+                depth = Math.max(0, depth - 1);
+            }
+        }
+    }
+    return members;
+}
+function objectMemberOf(line, lineNumber) {
+    const text = line.trim();
+    if (text === "" || text.startsWith("//") || text.startsWith("/*") || text.startsWith("*")) {
+        return undefined;
+    }
+    const property = /^(['"]?)([A-Za-z_$][\w$-]*)\1\s*\??\s*:/.exec(text);
+    if (property !== null) {
+        return { name: property[2], kind: "property", line: lineNumber, signature: signatureLine(text) };
+    }
+    const method = /^(?:async\s+)?(?:get\s+|set\s+)?([A-Za-z_$][\w$-]*)\s*\(/.exec(text);
+    if (method !== null) {
+        return { name: method[1], kind: "method", line: lineNumber, signature: signatureLine(text) };
+    }
+    return undefined;
+}
+function signatureLine(text) {
+    return text.replace(/\s+/g, " ").replace(/,$/, "");
+}
+function stripStrings(line) {
+    return line.replace(/\/\/.*$/, "").replace(/(['"`])(?:\\.|(?!\1).)*\1/g, "");
+}
+/** Read a file's lines once, or undefined when it cannot be read. */
+function fileLines(project, file) {
+    if (file === "")
+        return undefined;
+    try {
+        return node_fs_1.default.readFileSync(node_path_1.default.join(project, file), "utf8").split(/\r?\n/);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=runDetails.js.map

package/lib/operations/runDetails.js.map

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

package/lib/operations/runEntrypoints.d.ts

@@ -0,0 +1,9 @@
+import { GraphMemory } from "../model/GraphMemory";
+import { IGraphEntrypoints } from "../structures";
+/**
+ * Build the first source-free entrypoints list for a code question. The result
+ * gives the model stable handles, declaration signatures, and direct graph
+ * context. It is deliberately not a source reader; details adds selected symbol
+ * shape and ranges, not implementation text.
+ */
+export declare function runEntrypoints(graph: GraphMemory, props: IGraphEntrypoints.IRequest): IGraphEntrypoints;

package/lib/operations/runEntrypoints.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runEntrypoints = runEntrypoints;
+const common_1 = require("./common");
+const runLookup_1 = require("./runLookup");
+const DEFAULT_LIMIT = 4;
+const MAX_LIMIT = 8;
+const MAX_SEEDS = 3;
+const NEIGHBOR_LIMIT = 2;
+/**
+ * Build the first source-free entrypoints list for a code question. The result
+ * gives the model stable handles, declaration signatures, and direct graph
+ * context. It is deliberately not a source reader; details adds selected symbol
+ * shape and ranges, not implementation text.
+ */
+function runEntrypoints(graph, props) {
+    const query = props.query.trim();
+    const limit = (0, common_1.bound)(props.limit, DEFAULT_LIMIT, 1, MAX_LIMIT);
+    const lookup = (0, runLookup_1.runLookup)(graph, {
+        type: "lookup",
+        query,
+        language: props.language,
+        limit,
+    });
+    const ranked = lookup.hits.map((hit) => ({
+        ...hit,
+        reason: reasonOf(graph, hit.id),
+    }));
+    // Code handles written directly in the query, resolved to concrete nodes.
+    const mentions = [];
+    const mentionSeen = new Set();
+    for (const handle of directMentions(graph, query)) {
+        const resolved = (0, common_1.resolveHandle)(graph, handle);
+        if (resolved.node !== undefined && !mentionSeen.has(resolved.node.id)) {
+            mentionSeen.add(resolved.node.id);
+            mentions.push(resolved.node);
+        }
+    }
+    // Seeds for dependency orientation: resolved mentions first (the user named
+    // them), then the ranked hits.
+    const seeds = [];
+    const seedSeen = new Set();
+    const addSeed = (node) => {
+        if (node === undefined || node.kind === "file" || seedSeen.has(node.id))
+            return;
+        seedSeen.add(node.id);
+        seeds.push(node);
+    };
+    for (const node of mentions)
+        addSeed(node);
+    for (const hit of ranked)
+        addSeed(graph.node(hit.id));
+    const dependencyOrientation = seeds
+        .slice(0, MAX_SEEDS)
+        .flatMap((node) => orientationLines(graph, node));
+    return {
+        type: "entrypoints",
+        query,
+        ranked,
+        mentions: mentions.map(common_1.summaryOf),
+        dependencyOrientation,
+        next: (0, common_1.resultNext)("inspect", "Use one returned handle for trace/details when the answer needs flow or selected shape.", "trace"),
+        guide: (0, common_1.resultGuide)("Use ranked hits, mentions, and dependency orientation as the code index. If they identify the relevant files and symbols, answer or make one focused trace/details call; do not search the repository to verify them."),
+    };
+}
+function reasonOf(graph, id) {
+    const fanIn = graph.incoming(id).filter((edge) => !(0, common_1.isStructural)(edge.kind)).length;
+    const fanOut = graph.outgoing(id).filter((edge) => !(0, common_1.isStructural)(edge.kind)).length;
+    if (fanOut > fanIn)
+        return "High outgoing dependency flow for this query.";
+    if (fanIn > 0)
+        return "Referenced by other indexed symbols.";
+    return "Name/path match in the resident graph.";
+}
+function orientationLines(graph, node) {
+    const dependsOn = (0, common_1.referencesFromEdges)(graph, graph.outgoing(node.id), "to", NEIGHBOR_LIMIT, false);
+    const dependedOnBy = (0, common_1.referencesFromEdges)(graph, graph.incoming(node.id), "from", NEIGHBOR_LIMIT, false);
+    const name = node.qualifiedName ?? node.name;
+    const out = [];
+    for (const ref of dependsOn)
+        out.push(`${name} -[${ref.relation}]-> ${ref.name}`);
+    for (const ref of dependedOnBy)
+        out.push(`${ref.name} -[${ref.relation}]-> ${name}`);
+    return out;
+}
+function directMentions(graph, query) {
+    const handles = new Set();
+    for (const token of query.split(/\s+/)) {
+        const handle = normalizeNodeIdToken(token);
+        if (handle !== undefined && graph.node(handle) !== undefined)
+            handles.add(handle);
+    }
+    for (const match of query.matchAll(/`([^`]+)`/g)) {
+        const raw = match[1];
+        const id = normalizeNodeIdToken(raw);
+        if (id !== undefined && graph.node(id) !== undefined) {
+            handles.add(id);
+            continue;
+        }
+        const handle = normalizeHandle(raw);
+        if (handle !== undefined)
+            handles.add(handle);
+    }
+    for (const match of query.matchAll(/\b[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+\b/g)) {
+        const handle = normalizeHandle(match[0]);
+        if (handle !== undefined)
+            handles.add(handle);
+    }
+    return [...handles];
+}
+function normalizeNodeIdToken(raw) {
+    const value = raw
+        .trim()
+        .replace(/^[`"'([{]+/, "")
+        .replace(/[`"',.;:)\]}]+$/, "");
+    return /^[^\s#]+#[^\s#]+:[a-z_]+$/.test(value) ? value : undefined;
+}
+function normalizeHandle(raw) {
+    const value = raw.trim();
+    return /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(value) ? value : undefined;
+}
+//# sourceMappingURL=runEntrypoints.js.map

package/lib/operations/runEntrypoints.js.map

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

package/lib/operations/runLookup.d.ts

@@ -0,0 +1,10 @@
+import { GraphMemory } from "../model/GraphMemory";
+import { IGraphLookup } from "../structures";
+/**
+ * Rank the graph's symbols against a natural query. Scoring blends exact and
+ * dotted-name matches, CamelCase/subword coverage, file-path terms, a prefix
+ * bonus, and dependency centrality, then dampens external, generated, and test
+ * nodes and caps per file so the result is a diverse, relevant shortlist rather
+ * than one file's roster.
+ */
+export declare function runLookup(graph: GraphMemory, props: IGraphLookup.IRequest): IGraphLookup;

package/lib/operations/runLookup.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLookup = runLookup;
+const isSupportPath_1 = require("./isSupportPath");
+const common_1 = require("./common");
+// One file should not crowd out the rest of the ranking, so cap hits per file.
+const PER_FILE = 3;
+const DEFAULT_LIMIT = 5;
+const MAX_LIMIT = 6;
+/**
+ * Rank the graph's symbols against a natural query. Scoring blends exact and
+ * dotted-name matches, CamelCase/subword coverage, file-path terms, a prefix
+ * bonus, and dependency centrality, then dampens external, generated, and test
+ * nodes and caps per file so the result is a diverse, relevant shortlist rather
+ * than one file's roster.
+ */
+function runLookup(graph, props) {
+    const terms = (0, common_1.subwords)(props.query);
+    const codeTerms = exactCodeTerms(props.query);
+    const requestedKinds = requestedSymbolKinds(props.query);
+    const queryLc = props.query.trim().toLowerCase();
+    const wantsInternal = wantsInternalSymbol(queryLc, codeTerms);
+    const wantsSupport = wantsSupportSymbol(queryLc);
+    const includeExternal = props.includeExternal === true;
+    if (terms.length === 0) {
+        return {
+            type: "lookup",
+            hits: [],
+            next: (0, common_1.resultNext)("clarify", "No symbol matched; ask for a concrete symbol or scope."),
+            guide: (0, common_1.resultGuide)("No symbol matched; answer that the graph did not resolve this name or ask for a more concrete symbol."),
+        };
+    }
+    const scored = [];
+    for (const node of graph.nodes) {
+        if (node.kind === "file")
+            continue;
+        if (!includeExternal && node.external)
+            continue;
+        if (props.language !== undefined && node.language !== props.language)
+            continue;
+        if (props.kind !== undefined && node.kind !== props.kind)
+            continue;
+        const score = scoreNode(graph, node, queryLc, terms, codeTerms, requestedKinds, wantsInternal, wantsSupport);
+        if (score <= 0)
+            continue;
+        const hit = {
+            ...(0, common_1.summaryOf)(node),
+            score: Math.round(score),
+        };
+        if (node.decorators !== undefined && node.decorators.length > 0) {
+            hit.decorators = node.decorators;
+        }
+        scored.push(hit);
+    }
+    scored.sort((a, b) => b.score - a.score);
+    // Diversity: keep at most PER_FILE hits per file while filling up to the limit.
+    const limit = (0, common_1.bound)(props.limit, DEFAULT_LIMIT, 1, MAX_LIMIT);
+    const perFile = new Map();
+    const hits = [];
+    for (const hit of scored) {
+        const used = perFile.get(hit.file) ?? 0;
+        if (used >= PER_FILE)
+            continue;
+        perFile.set(hit.file, used + 1);
+        hits.push(hit);
+        if (hits.length >= limit)
+            break;
+    }
+    // Attach each kept hit's signature only for the shortlist, so the model can
+    // often answer from lookup alone without a details call.
+    for (const hit of hits) {
+        const node = graph.node(hit.id);
+        // hits are built from real graph nodes, so the id always resolves.
+        /* c8 ignore next */
+        if (node === undefined)
+            continue;
+        const sig = (0, common_1.signatureOf)(graph.project, node);
+        if (sig !== undefined)
+            hit.signature = sig;
+    }
+    // Backtick-quoted code handles that matched nothing are worth flagging so the
+    // model does not silently assume they resolved.
+    const matched = new Set(hits.flatMap((hit) => (0, common_1.subwords)(hit.name)));
+    const unknown = codeTerms.filter((term) => !(0, common_1.subwords)(term).every((sub) => matched.has(sub)));
+    return {
+        type: "lookup",
+        hits,
+        ...(unknown.length > 0 ? { unknown } : {}),
+        next: (0, common_1.resultNext)("inspect", "Use one returned id for trace/details when the answer needs flow or shape.", "details"),
+        guide: (0, common_1.resultGuide)("Use ranked hits and signatures as symbol evidence. If the target is clear, answer or make one focused trace/details call; do not search files to verify the match."),
+    };
+}
+/** Score one node against the query; 0 means no match. */
+function scoreNode(graph, node, queryLc, terms, codeTerms, requestedKinds, wantsInternal, wantsSupport) {
+    const name = node.name.toLowerCase();
+    const qualified = (node.qualifiedName ?? node.name).toLowerCase();
+    const nameSubs = (0, common_1.subwords)(node.name);
+    const qualifiedSubs = (0, common_1.subwords)(node.qualifiedName ?? node.name);
+    const pathSubs = (0, common_1.subwords)(node.file);
+    let score = 0;
+    if (queryLc === name || queryLc === qualified) {
+        score += 100;
+    }
+    else if (qualified.includes(".") && queryLc.includes(qualified)) {
+        score += 85;
+    }
+    else if (queryLc.includes(".") && qualified.includes(queryLc)) {
+        score += 60;
+    }
+    for (const codeTerm of codeTerms) {
+        if (name === codeTerm || qualified === codeTerm) {
+            score += 110;
+        }
+        else if (qualified.endsWith(`.${codeTerm}`)) {
+            score += 95;
+        }
+        else if (codeTerm.includes(".") && qualified.endsWith(codeTerm)) {
+            score += 85;
+        }
+    }
+    if (requestedKinds.has(node.kind))
+        score += 16;
+    let covered = 0;
+    for (const term of terms) {
+        if (nameSubs.includes(term)) {
+            score += 12;
+            covered++;
+        }
+        else if (qualifiedSubs.includes(term)) {
+            score += 8;
+            covered++;
+        }
+        else if (name.includes(term)) {
+            score += 5;
+            covered++;
+        }
+        else if (pathSubs.includes(term)) {
+            score += 3;
+        }
+    }
+    // Every query term landed somewhere in the name: a strong whole-query match.
+    if (covered === terms.length)
+        score += 10;
+    if (name.startsWith(terms[0]))
+        score += 4;
+    if (score <= 0)
+        return 0;
+    // Centrality: a symbol the codebase leans on is a likelier target.
+    const fan = degree(graph, node.id);
+    score += Math.min(8, Math.log2(1 + fan) * 2);
+    // Dampen what is rarely the intended target.
+    if (node.ignored)
+        score *= 0.3;
+    if ((0, common_1.isTestPath)(node.file))
+        score *= 0.7;
+    if (!wantsSupport && (0, isSupportPath_1.isSupportPath)(node.file))
+        score *= 0.35;
+    if (!wantsInternal && isInternalish(node))
+        score *= 0.82;
+    return score;
+}
+function wantsSupportSymbol(queryLc) {
+    return /\b(test|tests|spec|fixture|fixtures|sample|samples|example|examples|generated|build|dist)\b/.test(queryLc);
+}
+function wantsInternalSymbol(queryLc, codeTerms) {
+    return (/\b(internal|private|implementation|impl)\b/.test(queryLc) ||
+        codeTerms.some((term) => term.startsWith("_") || term.includes("internal")));
+}
+function isInternalish(node) {
+    const name = node.qualifiedName ?? node.name;
+    return (name.startsWith("_") ||
+        name.includes("._") ||
+        (0, common_1.subwords)(name).some((word) => word === "internal" || word === "internals"));
+}
+function exactCodeTerms(query) {
+    const out = new Set();
+    for (const match of query.matchAll(/`([^`]+)`/g)) {
+        const normalized = normalizeCodeTerm(match[1]);
+        if (normalized !== undefined)
+            out.add(normalized);
+    }
+    for (const match of query.matchAll(/\b([A-Za-z_$][\w$]*)\s+(method|function|class|interface|type|variable)\b/gi)) {
+        const normalized = normalizeCodeTerm(match[1]);
+        if (normalized !== undefined)
+            out.add(normalized);
+    }
+    for (const match of query.matchAll(/\b[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+\b/g)) {
+        const normalized = normalizeCodeTerm(match[0]);
+        if (normalized !== undefined)
+            out.add(normalized);
+    }
+    return [...out];
+}
+function requestedSymbolKinds(query) {
+    const kinds = new Set();
+    const lc = query.toLowerCase();
+    if (/\bmethods?\b/.test(lc))
+        kinds.add("method");
+    if (/\bfunctions?\b/.test(lc)) {
+        kinds.add("function");
+        kinds.add("method");
+        kinds.add("variable");
+    }
+    if (/\bclasses?\b/.test(lc))
+        kinds.add("class");
+    if (/\binterfaces?\b/.test(lc))
+        kinds.add("interface");
+    if (/\btypes?\b/.test(lc))
+        kinds.add("type");
+    if (/\bvariables?\b|\bconst\b|\blet\b/.test(lc))
+        kinds.add("variable");
+    return kinds;
+}
+function normalizeCodeTerm(raw) {
+    const value = raw.trim().toLowerCase();
+    return /^[a-z_$][\w$]*(?:\.[a-z_$][\w$]*)*$/.test(value) ? value : undefined;
+}
+/** Non-structural in+out degree (code dependency, not nesting). */
+function degree(graph, id) {
+    let n = 0;
+    for (const edge of graph.outgoing(id))
+        if (!(0, common_1.isStructural)(edge.kind))
+            n++;
+    for (const edge of graph.incoming(id))
+        if (!(0, common_1.isStructural)(edge.kind))
+            n++;
+    return n;
+}
+//# sourceMappingURL=runLookup.js.map

package/lib/operations/runLookup.js.map

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

package/lib/operations/runOverview.d.ts

@@ -0,0 +1,10 @@
+import { GraphMemory } from "../model/GraphMemory";
+import { IGraphOverview } from "../structures";
+/**
+ * Project a compact, source-read-free architecture map: counts by kind, folder
+ * layering with export density, the highest-dependency symbols (ranked by real
+ * fan-in/out, excluding structural edges so nesting does not masquerade as
+ * dependency), and the export surface by file. Output is bounded so a model
+ * reads structure cheaply.
+ */
+export declare function runOverview(graph: GraphMemory, props: IGraphOverview.IRequest): IGraphOverview;