cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/core/ingestion/scope-resolution/unresolved-receivers.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * Aggregate `receiver-unresolved` resolution outcomes into the small,
+ * index-persisted summary that `impact()` / `context()` read to decide whether
+ * their result is exact or a lower bound (#2744, the second half of #2708).
+ *
+ * **Why keyed by member name.** A dropped site's callee is unknown — that is
+ * what "unresolved" means — so the drop cannot be attributed to any target
+ * symbol. The one thing still known is the member NAME being invoked:
+ * `Service(db).do_work()` tells us a call to something called `do_work` was
+ * lost even though the receiver's type was not established. That is exactly
+ * the granularity the epistemic signal needs: a query about `do_work` can
+ * report its caller count as a lower bound, while a query about an unrelated
+ * symbol stays exact.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_UNRESOLVED_RECEIVER_MEMBERS = void 0;
+exports.summarizeUnresolvedReceivers = summarizeUnresolvedReceivers;
+exports.lookupUnresolvedCallCount = lookupUnresolvedCallCount;
+exports.lookupExternalCallCount = lookupExternalCallCount;
+exports.logUnresolvedReceiverFiles = logUnresolvedReceiverFiles;
+const logger_js_1 = require("../../logger.js");
+const utils_js_1 = require("../../../lib/utils.js");
+/** Cap on distinct member names persisted. Well above what a real repo
+ *  produces (the whole point of the signal is that drops are the exception),
+ *  but bounded so a pathological repo cannot grow the metadata file without
+ *  limit. Truncation is reported, never silent — see `truncated`. */
+exports.MAX_UNRESOLVED_RECEIVER_MEMBERS = 500;
+/**
+ * Rank a name→count map and cap it at {@link MAX_UNRESOLVED_RECEIVER_MEMBERS}.
+ *
+ * Highest count first, name as a tiebreak so the persisted map is stable across
+ * runs — an unstable ordering would churn the metadata file (and its diff) on
+ * every analyze for no behavioural reason. ONE comparator, shared by the
+ * in-program and external maps: two hand-copied comparators that must stay
+ * identical or the artifact churns on one map and not the other is exactly the
+ * drift this contract cannot tolerate.
+ *
+ * `omitted` is the number of distinct names past the cap, so the caller can
+ * report truncation rather than silently losing entries.
+ */
+function rankAndCap(counts, cap = exports.MAX_UNRESOLVED_RECEIVER_MEMBERS) {
+    const ranked = [...counts.entries()].sort(
+    // `compareCodeUnits`, not `localeCompare` (#2787). The tiebreak feeds the
+    // `.slice()` below, so locale-sensitive collation would decide WHICH
+    // entries survive the cap, not merely how they are listed — and ICU order
+    // varies by platform and ICU build, so two runs over one repo could persist
+    // different sets. Key-based lookup is unaffected either way.
+    ([aName, aCount], [bName, bCount]) => bCount - aCount || (0, utils_js_1.compareCodeUnits)(aName, bName));
+    const kept = ranked.slice(0, cap);
+    return { kept, omitted: ranked.length - kept.length };
+}
+/**
+ * A `receiver-unresolved` drop at a CALL site.
+ *
+ * ONE predicate, shared by the persisted summary and the per-file diagnostic —
+ * the same contract `rankAndCap` states for its comparator. If the two ever
+ * disagreed, the diagnostic would rank a different population than the artifact
+ * it exists to explain.
+ *
+ * Call sites only: Case 0's recorder gates on the receiver's punctuation, not on
+ * what the reference IS, so property reads (`d.source.kind`) and writes
+ * (`x.argtypes = [...]`) arrive alongside lost method calls — measured at 25 of
+ * 124 drops on the fixture corpus. Counting them made the consumer's "N call
+ * sites invoking X were dropped" literally false. A missing `siteKind` counts as
+ * a call: the only emitter always sets it, and erring toward `lower-bound` is
+ * the safe direction for an epistemic signal.
+ *
+ * Receiver ORIGIN is deliberately NOT decided here — the summary routes external
+ * drops into their own bucket while the diagnostic excludes them, and collapsing
+ * that choice into this predicate would take it away from both callers.
+ */
+function isUnresolvedReceiverCall(outcome) {
+    return (outcome.kind === 'suppressed' &&
+        outcome.reason === 'receiver-unresolved' &&
+        (outcome.siteKind === undefined || outcome.siteKind === 'call'));
+}
+/**
+ * Build the summary, or `undefined` when nothing was dropped — an index with
+ * no unresolved receivers stores no key at all, so `epistemic` keeps its
+ * existing "exact unless proven otherwise" behaviour for every repo that
+ * resolves cleanly.
+ */
+function summarizeUnresolvedReceivers(outcomes) {
+    const counts = new Map();
+    const externalCounts = new Map();
+    let totalSites = 0;
+    let externalSites = 0;
+    for (const outcome of outcomes) {
+        // CALL sites only — see `isUnresolvedReceiverCall`, which the per-file
+        // diagnostic shares so the two can never rank different populations.
+        if (!isUnresolvedReceiverCall(outcome))
+            continue;
+        if (outcome.name.length === 0)
+            continue;
+        // Routed, not discarded. External-rooted drops (`console.log(...)`,
+        // `fetch(...)`) reach code this index does not contain, so there is no node
+        // an edge could have pointed at and nothing was lost — they must not hedge.
+        // But they stay in the artifact under their own key so the split is
+        // auditable and reversible.
+        //
+        // `external` is a POSITIVE determination made by `classifyReceiverOrigin`
+        // from a language built-in match, never a fallthrough: a receiver the
+        // classifier could not place lands in `unknown`, which counts here WITH
+        // `in-program`, because assuming a completeness we cannot demonstrate is
+        // the unsafe direction.
+        if (outcome.receiverOrigin === 'external') {
+            externalSites++;
+            externalCounts.set(outcome.name, (externalCounts.get(outcome.name) ?? 0) + 1);
+            continue;
+        }
+        totalSites++;
+        counts.set(outcome.name, (counts.get(outcome.name) ?? 0) + 1);
+    }
+    // An index whose only drops were external-rooted still reports the split, so
+    // "nothing was lost" is distinguishable from "nothing was measured".
+    if (totalSites === 0 && externalSites === 0)
+        return undefined;
+    const { kept, omitted: omittedNames } = rankAndCap(counts);
+    const { kept: externalKept, omitted: externalOmittedNames } = rankAndCap(externalCounts);
+    return {
+        counts: Object.fromEntries(kept),
+        totalSites,
+        ...(omittedNames > 0 ? { omittedNames } : {}),
+        ...(externalSites > 0
+            ? {
+                externalCounts: Object.fromEntries(externalKept),
+                externalSites,
+                ...(externalOmittedNames > 0 ? { externalOmittedNames } : {}),
+            }
+            : {}),
+    };
+}
+/**
+ * Look up the dropped-CALL count for a member name.
+ *
+ * THE one place that reads `UnresolvedReceiverSummary.counts`. The map is
+ * revived from JSON, so it carries `Object.prototype`: a bare
+ * `counts[symName]` returns a FUNCTION for `constructor`, `toString`,
+ * `valueOf`, `hasOwnProperty` and friends, and a `<= 0` guard does not catch it
+ * because `Number(fn)` is `NaN` and `NaN <= 0` is false. `constructor` is an
+ * ordinary member name in a code graph, so that was reachable in normal use and
+ * interpolated a function into user-facing text.
+ *
+ * Returns `undefined` when the name was never recorded, and only ever returns a
+ * finite positive number otherwise.
+ */
+function lookupUnresolvedCallCount(summary, symName) {
+    const counts = summary?.counts;
+    if (counts === undefined || symName.length === 0)
+        return undefined;
+    if (!Object.hasOwn(counts, symName))
+        return undefined;
+    const sites = counts[symName];
+    if (typeof sites !== 'number' || !Number.isFinite(sites) || sites <= 0)
+        return undefined;
+    return sites;
+}
+/**
+ * Look up the EXTERNAL-rooted dropped-call count for a member name.
+ *
+ * Companion to `lookupUnresolvedCallCount`, and prototype-safe for the same
+ * reason: the map is revived from JSON, so `constructor` / `toString` and
+ * friends would otherwise return a function.
+ */
+function lookupExternalCallCount(summary, symName) {
+    const counts = summary?.externalCounts;
+    if (counts === undefined || symName.length === 0)
+        return undefined;
+    if (!Object.hasOwn(counts, symName))
+        return undefined;
+    const sites = counts[symName];
+    if (typeof sites !== 'number' || !Number.isFinite(sites) || sites <= 0)
+        return undefined;
+    return sites;
+}
+/**
+ * Opt-in, following the repo's established diagnostic pattern
+ * (`createLogger(name, { debugEnvVar })`). Every repository in every language
+ * drops SOME receivers, so emitting this at `info` unconditionally would add a
+ * line to every analyze anyone ever runs — the noise ADV-6 flagged. #2837's
+ * reporter turns it on deliberately:
+ *
+ *     CGRAPH_DEBUG_RECEIVER_DROPS=1 cgraph analyze
+ */
+// Built on first use, not at import. `createLogger` is eager where the `logger`
+// singleton is a lazy Proxy — it resolves `pino-pretty`, constructs a SonicBoom
+// destination and registers a `beforeExit` hook. This module is imported by
+// `mcp/local/local-backend.ts` for its lookup helpers, so an eager call would
+// put that on MCP server startup for a diagnostic that is off by default.
+let receiverDropLog;
+const dropLog = () => (receiverDropLog ??= (0, logger_js_1.createLogger)('receiver-drops', {
+    debugEnvVar: 'CGRAPH_DEBUG_RECEIVER_DROPS',
+}));
+/** Files named in the per-file receiver-drop line. Bounded: this is a signpost
+ *  pointing at where to look, not an inventory. */
+const UNRESOLVED_RECEIVER_FILE_SAMPLE = 10;
+/**
+ * Report which FILES lost the most call sites to an untyped receiver (#2837).
+ *
+ * `summarizeUnresolvedReceivers` persists the same drops keyed by member NAME,
+ * capped at 500 distinct names, and discards `filePath` — deliberately, because
+ * its consumer (`impact()`'s exact-vs-lower-bound verdict) asks "is this
+ * symbol's caller count trustworthy", a question about names.
+ *
+ * That leaves "why does THIS file resolve nothing while its sibling resolves
+ * everything" unanswerable from any artifact, which is exactly what #2837 asked
+ * for and could not run: comparing the drop records of two files with identical
+ * declared shapes separates "receiver never typed" from "typed but no edge
+ * emitted", and narrows a per-file split in one run instead of a bisect.
+ *
+ * A log line rather than a persisted field because nothing queries it — a
+ * persisted `byFile` map would be an unread field carrying its own cap and
+ * truncation semantics. When a consumer appears, `UnresolvedReceiverSummary` is
+ * already a `RepoMeta` field and can carry it with no schema change.
+ */
+function logUnresolvedReceiverFiles(outcomes) {
+    // Nothing below is observable unless the diagnostic is switched on, so skip
+    // the whole tally rather than building it and discarding it at the emit.
+    if (!dropLog().isLevelEnabled('debug'))
+        return;
+    const byFile = new Map();
+    let totalSites = 0;
+    for (const outcome of outcomes) {
+        // External-rooted drops (`fmt.Println`) reach code this index does not
+        // contain, so no node existed for an edge to point at and nothing was lost.
+        // Counting them here led the ranking with files that call `fmt` the most.
+        if (!isUnresolvedReceiverCall(outcome) || outcome.receiverOrigin === 'external')
+            continue;
+        totalSites += 1;
+        byFile.set(outcome.filePath, (byFile.get(outcome.filePath) ?? 0) + 1);
+    }
+    if (totalSites === 0)
+        return;
+    const { kept } = rankAndCap(byFile, UNRESOLVED_RECEIVER_FILE_SAMPLE);
+    dropLog().debug({
+        totalSites,
+        filesAffected: byFile.size,
+        topFiles: kept.map(([filePath, sites]) => ({ filePath, sites })),
+    }, 'receiver-unresolved call sites by file (top offenders; a file far above its ' +
+        'siblings usually means its receivers were never typed, not that it has more calls)');
+}

package/dist/core/code/engine/core/ingestion/scope-resolution/utils/definition-id.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definitionIdPosition = definitionIdPosition;
+/**
+ * Extract coordinates from `def:<filePath>#<line>:<column>:<type>:<name>`.
+ *
+ * File paths are embedded verbatim and may themselves contain fragments such
+ * as `#12:34:`, while names may themselves contain `#` (TypeScript private
+ * members). Anchor on the known file path so neither side can be mistaken for
+ * the declaration separator.
+ */
+function definitionIdPosition(nodeId, filePath) {
+    if (nodeId === undefined)
+        return undefined;
+    const prefix = `def:${filePath}#`;
+    if (!nodeId.startsWith(prefix))
+        return undefined;
+    const match = /^(\d+):(\d+):/.exec(nodeId.slice(prefix.length));
+    if (match === null)
+        return undefined;
+    return { line: Number(match[1]), column: Number(match[2]) };
+}

package/dist/core/code/engine/core/ingestion/scope-resolution/workspace-index.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * `WorkspaceResolutionIndex` — scope-tied lookup tables built ONCE
+ * per resolution run, after `populateOwners` and before any
+ * resolution pass.
+ *
+ * ## Scope (what lives here vs. what lives in `SemanticModel`)
+ *
+ * This index carries only the lookups that return a `Scope` — things
+ * `SemanticModel` structurally cannot provide:
+ *
+ *   - `classScopeByDefId` — class def `nodeId` → `Scope`. Needed so
+ *     passes can read `scope.bindings`, `scope.typeBindings`, and
+ *     `scope.ownedDefs`. SemanticModel's `TypeRegistry` carries class
+ *     metadata but not the `Scope`.
+ *   - `classScopeIdToDefId` — inverse of `classScopeByDefId`. O(1)
+ *     reverse lookup (Scope.id → class def nodeId) for the implicit-
+ *     `this` overload picker.
+ *   - `moduleScopeByFile` — file path → `Scope` of the root `Module`.
+ *     Used by cross-file return-type propagation, `findExportedDef`,
+ *     and `findExportedDefByName`'s workspace-wide fallback.
+ *     SymbolTable indexes symbols, not scopes.
+ *
+ * Symbol lookups live on `SemanticModel`:
+ *   - Owner-keyed method lookup → `model.methods.lookupAllByOwner`
+ *     (populated by the legacy parse phase via `symbolTable.add` AND
+ *     by scope-resolution's reconciliation pass in `runScopeResolution`,
+ *     which adds `parsed.localDefs[i].ownerId` entries missed by the
+ *     legacy extractor for registry-primary languages).
+ *   - Name-keyed callable lookup → `model.methods.lookupMethodByName`
+ *     and `model.symbols.lookupCallableByName`.
+ *   - File-indexed symbol lookup → `model.symbols.lookupExactAll`.
+ *
+ * This split preserves the single-source-of-truth invariant
+ * documented in `ScopeResolver`'s contract file: symbol-indexed
+ * lookups live on `SemanticModel` for the whole codebase; only
+ * scope-shaped lookups (which `SemanticModel` doesn't carry) live
+ * here.
+ *
+ * Build cost is O(totalScopes). Read-only after construction.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWorkspaceResolutionIndex = buildWorkspaceResolutionIndex;
+const walkers_js_1 = require("./scope/walkers.js");
+/**
+ * A `ReadonlyMap<K, Scope>` view backed by a `K → ScopeId` map plus a
+ * `ScopeTree`, holding **no `Scope` objects of its own** — `.get` fetches via
+ * `scopeTree.getScope(id)`. Out-of-core scope index: the previous `Map<K, Scope>` form pinned every
+ * class + module `Scope` (and its heavy `bindings` payload) through emit, which
+ * defeated the disk-backed scope seal (the scopes stayed resident via this
+ * index). Delegating to the `scopeTree` means the index pins only ids, so once
+ * the tree seals to disk the scopes become collectible. Value-identical to a
+ * stored `Scope` (`getScope` returns the same object resident, or a
+ * value-identical revived one from disk), and iteration follows the `idByKey`
+ * insertion order = the old map's order, so consumers are byte-identical.
+ */
+class ScopeByKeyView {
+    idByKey;
+    scopeTree;
+    constructor(idByKey, scopeTree) {
+        this.idByKey = idByKey;
+        this.scopeTree = scopeTree;
+    }
+    get(key) {
+        const id = this.idByKey.get(key);
+        return id === undefined ? undefined : this.scopeTree.getScope(id);
+    }
+    has(key) {
+        return this.idByKey.has(key);
+    }
+    get size() {
+        return this.idByKey.size;
+    }
+    *entries() {
+        for (const [k, id] of this.idByKey) {
+            const s = this.scopeTree.getScope(id);
+            if (s !== undefined)
+                yield [k, s];
+        }
+    }
+    keys() {
+        return this.idByKey.keys();
+    }
+    *values() {
+        for (const [, s] of this.entries())
+            yield s;
+    }
+    forEach(cb, thisArg) {
+        for (const [k, s] of this.entries())
+            cb.call(thisArg, s, k, this);
+    }
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+}
+/**
+ * Build the workspace scope-lookup index. When `scopeTree` is supplied (the live
+ * pipeline), the `Scope`-valued maps are id-backed views that delegate to it —
+ * so this index never pins `Scope` objects and the disk seal can actually
+ * reclaim them. Without it (unit tests), the legacy direct `Map<K, Scope>` form
+ * is returned unchanged.
+ */
+function buildWorkspaceResolutionIndex(parsedFiles, scopeTree) {
+    const classScopeIdByDefId = new Map();
+    const classScopeIdToDefId = new Map();
+    const moduleScopeIdByFile = new Map();
+    const exportedCallableByName = new Map();
+    // Back-compat (no scopeTree): keep the direct Scope-object maps.
+    const classScopeByDefIdDirect = scopeTree === undefined ? new Map() : undefined;
+    const moduleScopeByFileDirect = scopeTree === undefined ? new Map() : undefined;
+    for (const parsed of parsedFiles) {
+        const moduleScope = parsed.scopes.find((s) => s.kind === 'Module');
+        if (moduleScope !== undefined) {
+            moduleScopeIdByFile.set(parsed.filePath, moduleScope.id);
+            moduleScopeByFileDirect?.set(parsed.filePath, moduleScope);
+            // Precompute the findExportedDefByName workspace fallback: first
+            // module-local (origin 'local') callable per name, first file wins —
+            // read from the resident bindings here, ONCE.
+            for (const [name, refs] of moduleScope.bindings) {
+                if (exportedCallableByName.has(name))
+                    continue;
+                for (const ref of refs) {
+                    if (ref.origin !== 'local')
+                        continue;
+                    const t = ref.def.type;
+                    if (t === 'Function' || t === 'Method' || t === 'Constructor') {
+                        exportedCallableByName.set(name, ref.def);
+                        break;
+                    }
+                }
+            }
+        }
+        for (const scope of parsed.scopes) {
+            if (scope.kind !== 'Class')
+                continue;
+            const cd = scope.ownedDefs.find((d) => (0, walkers_js_1.isClassLike)(d.type));
+            if (cd !== undefined) {
+                classScopeIdByDefId.set(cd.nodeId, scope.id);
+                classScopeIdToDefId.set(scope.id, cd.nodeId);
+                classScopeByDefIdDirect?.set(cd.nodeId, scope);
+            }
+        }
+    }
+    const classScopeByDefId = scopeTree === undefined
+        ? classScopeByDefIdDirect
+        : new ScopeByKeyView(classScopeIdByDefId, scopeTree);
+    const moduleScopeByFile = scopeTree === undefined
+        ? moduleScopeByFileDirect
+        : new ScopeByKeyView(moduleScopeIdByFile, scopeTree);
+    return { classScopeByDefId, classScopeIdToDefId, moduleScopeByFile, exportedCallableByName };
+}

package/dist/core/code/engine/core/ingestion/structure-processor.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processStructure = void 0;
+const utils_js_1 = require("../../lib/utils.js");
+const processStructure = (graph, paths) => {
+    paths.forEach((path) => {
+        const parts = path.split('/');
+        let currentPath = '';
+        let parentId = '';
+        parts.forEach((part, index) => {
+            const isFile = index === parts.length - 1;
+            const label = isFile ? 'File' : 'Folder';
+            currentPath = currentPath ? `${currentPath}/${part}` : part;
+            const nodeId = (0, utils_js_1.generateId)(label, currentPath);
+            const node = {
+                id: nodeId,
+                label: label,
+                properties: {
+                    name: part,
+                    filePath: currentPath,
+                },
+            };
+            graph.addNode(node);
+            if (parentId) {
+                const relId = (0, utils_js_1.generateId)('CONTAINS', `${parentId}->${nodeId}`);
+                const relationship = {
+                    id: relId,
+                    type: 'CONTAINS',
+                    sourceId: parentId,
+                    targetId: nodeId,
+                    confidence: 1.0,
+                    reason: '',
+                };
+                graph.addRelationship(relationship);
+            }
+            parentId = nodeId;
+        });
+    });
+};
+exports.processStructure = processStructure;