cgraphx 2.0.2 → 2.0.6

package/dist/core/code/engine/core/ingestion/model/semantic-model.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * Semantic Model
+ *
+ * Top-level orchestrator for all resolution-time data. Owns:
+ *
+ *   - Three owner-scoped registries (types, methods, fields)
+ *   - A nested SymbolTable (file + callable name indexes) wrapped so
+ *     that `add()` fans out into the registries via the dispatch table
+ *
+ * ## Dependency direction
+ *
+ *     cgraph-shared (NodeLabel)             — leaf
+ *          ↑
+ *     symbol-table.ts                         — pure file/callable index
+ *          ↑
+ *     model/type-registry / method-registry / field-registry
+ *          ↑
+ *     model/registration-table.ts             — dispatch table factory
+ *          ↑
+ *     model/semantic-model.ts                 — THIS FILE (orchestrator)
+ *          ↑
+ *     resolve.ts, call-processor.ts, ...
+ *
+ * `symbol-table.ts` is a leaf — it never imports from `./model/`. This
+ * file (semantic-model.ts) is the ONLY place where SymbolTable and the
+ * owner-scoped registries are composed. Upstream consumers pass around
+ * the `SemanticModel` interface and reach into `.symbols` for file-scoped
+ * operations or `.types` / `.methods` / `.fields` for owner-scoped ones.
+ *
+ * ## Fan-out via wrapped add()
+ *
+ * `createSemanticModel()` creates a pure SymbolTable, creates the three
+ * registries, builds a dispatch table via `createRegistrationTable`, and
+ * exposes a SymbolTable-shaped façade whose `add()`:
+ *
+ *   1. Calls `rawSymbols.add()` — writes the fileIndex + callable index
+ *      and returns the fully-built `SymbolDefinition`.
+ *   2. Runs pre-dispatch normalization (`Function`-with-`ownerId` routes
+ *      as `Method`).
+ *   3. Looks up the dispatch table and invokes the hook, which writes to
+ *      the appropriate owner-scoped registry.
+ *
+ * The wrapper is the only place where the two layers are combined. A
+ * direct `createSymbolTable()` caller (e.g. an isolated unit test) gets
+ * the pure, registry-free behavior — no surprises, no hidden side
+ * effects.
+ *
+ * ## Single-source-of-truth invariant
+ *
+ * `SemanticModel` is the authoritative symbol store for the whole
+ * ingestion pipeline. Both the legacy Call-Resolution DAG and the
+ * new scope-resolution pipeline read symbol-keyed lookups from here
+ * exclusively — no parallel owner-keyed, name-keyed, or file-keyed
+ * symbol indexes exist outside this module. The scope-resolution
+ * pipeline does carry a small `WorkspaceResolutionIndex` for
+ * `Scope`-valued maps (`classScopeByDefId`, `moduleScopeByFile`) that
+ * `SemanticModel` structurally cannot hold, but nothing else.
+ *
+ * ## Write / read phase contract
+ *
+ * Writes to the model happen in three clearly-ordered phases during a
+ * single ingestion run:
+ *
+ *   1. **Legacy parse phase** (`parsing-processor`) calls
+ *      `symbols.add(...)` per extracted symbol, which fans out via
+ *      the dispatch table into `types` / `methods` / `fields`.
+ *   2. **Scope-resolution reconciliation** (`reconcileOwnership` in
+ *      `scope-resolution/pipeline/reconcile-ownership.ts`) registers
+ *      any `parsed.localDefs[i]` with a scope-resolution-corrected
+ *      `ownerId` that the legacy pass missed (Python class-body
+ *      methods are the canonical case). Idempotent.
+ *   3. **Finalize-orchestrator** calls `attachScopeIndexes(...)` to
+ *      stamp the materialized `ScopeResolutionIndexes` bundle onto
+ *      `model.scopes`. One-shot; throws on a second call.
+ *
+ * After these three phases, the model is effectively frozen:
+ *   - `attachScopeIndexes` applied `Object.freeze` to its bundle.
+ *   - Downstream passes receive the narrowed `SemanticModel` reader
+ *     handle (not `MutableSemanticModel`), so `.register()` /
+ *     `.clear()` / `attachScopeIndexes()` are structurally absent.
+ *
+ * See `scope-resolution/contract/scope-resolver.ts` Contract
+ * Invariant I9 for the scope-resolution-side rule and
+ * `ARCHITECTURE.md` § "Semantic-model source of truth" for the
+ * overall architecture.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSemanticModel = void 0;
+const type_registry_js_1 = require("./type-registry.js");
+const method_registry_js_1 = require("./method-registry.js");
+const field_registry_js_1 = require("./field-registry.js");
+const symbol_table_js_1 = require("./symbol-table.js");
+const registration_table_js_1 = require("./registration-table.js");
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+//
+// NodeLabel taxonomy drift detection lives in `registration-table.ts` as a
+// pure compile-time check — the `LABEL_BEHAVIOR` map is
+// `Record<NodeLabel, LabelBehavior>` with `as const satisfies`, which proves
+// coverage, uniqueness, and no-extra-keys at build time. No runtime guard
+// is needed because drift is structurally impossible in the source.
+const createSemanticModel = () => {
+    // 1. Create the pure, registry-unaware SymbolTable leaf.
+    // rawSymbols is the only handle in the codebase whose type (the
+    // internal createSymbolTable return) includes `.clear()`. cascadeClear
+    // below reaches it here; no external caller receives this variable.
+    const rawSymbols = (0, symbol_table_js_1.createSymbolTable)();
+    // 2. Create the three owner-scoped registries.
+    const types = (0, type_registry_js_1.createTypeRegistry)();
+    const methods = (0, method_registry_js_1.createMethodRegistry)();
+    const fields = (0, field_registry_js_1.createFieldRegistry)();
+    // 3. Build the dispatch table, closed over THIS instance's registries.
+    const dispatchTable = (0, registration_table_js_1.createRegistrationTable)({ types, methods, fields });
+    // 4. Wrap rawSymbols so `add()` fans out into the registries via the
+    //    dispatch table. See module JSDoc for the three-step contract.
+    const wrappedAdd = (filePath, name, nodeId, type, metadata) => {
+        const def = rawSymbols.add(filePath, name, nodeId, type, metadata);
+        // Function-with-ownerId (Python `def` in a class body, Rust trait
+        // method, Kotlin companion method) routes as Method. Keeps the
+        // dispatch table single-purpose.
+        const dispatchKey = type === 'Function' && metadata?.ownerId !== undefined ? 'Method' : type;
+        const hook = dispatchTable.get(dispatchKey);
+        if (hook) {
+            hook(name, def);
+        }
+        return def;
+    };
+    // Scope-resolution bundle slot. Starts `undefined`; populated by a
+    // one-shot `attachScopeIndexes(...)` from the finalize-orchestrator.
+    // Held inside the factory closure so the returned `SemanticModel`
+    // surface exposes it as a plain `readonly` property without a setter.
+    let attachedScopes;
+    const attachScopeIndexes = (indexes) => {
+        if (attachedScopes !== undefined) {
+            throw new Error('SemanticModel: scope indexes already attached. ' + 'Call `clear()` before re-attaching.');
+        }
+        attachedScopes = Object.freeze(indexes);
+    };
+    // Cascade clear: single source of truth for "reset the entire model".
+    // Wired into both `model.clear()` AND `model.symbols.clear()` so that a
+    // caller holding only a SymbolTable reference can't leave the
+    // owner-scoped registries populated while the file/callable indexes go
+    // empty (the phantom-resolution failure mode).
+    const cascadeClear = () => {
+        types.clear();
+        methods.clear();
+        fields.clear();
+        rawSymbols.clear();
+        attachedScopes = undefined;
+    };
+    // Writer-typed facade: exposes reads + add, but NO `clear` field.
+    // Callers holding a `SemanticModel.symbols` reference cannot desync
+    // the leaf indexes from the owner-scoped registries. Consumers that
+    // only query should widen their annotation to SymbolTableReader for
+    // least-authority clarity.
+    const symbols = {
+        add: wrappedAdd,
+        lookupExact: rawSymbols.lookupExact,
+        lookupExactFull: rawSymbols.lookupExactFull,
+        lookupExactAll: rawSymbols.lookupExactAll,
+        lookupCallableByName: rawSymbols.lookupCallableByName,
+        getFiles: rawSymbols.getFiles,
+        getStats: rawSymbols.getStats,
+    };
+    return {
+        types,
+        methods,
+        fields,
+        symbols,
+        get scopes() {
+            return attachedScopes;
+        },
+        clear: cascadeClear,
+        attachScopeIndexes,
+    };
+};
+exports.createSemanticModel = createSemanticModel;

package/dist/core/code/engine/core/ingestion/model/symbol-table.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Symbol Table — file-indexed + callable-name symbol storage.
+ *
+ * This module is a PURE LEAF in the ingestion dependency hierarchy. It owns
+ * two orthogonal O(1) indexes:
+ *
+ *   1. fileIndex      — Map<filePath, Map<name, SymbolDefinition[]>>
+ *                       for same-file lookups (Tier 1 resolution)
+ *   2. callableByName — Map<name, SymbolDefinition[]>
+ *                       for name-keyed callable lookups (Tier 3 widen)
+ *
+ * SymbolTable deliberately knows NOTHING about the owner-scoped registries
+ * (types, methods, fields) that sit above it in the dependency graph. Those
+ * registries live in `model/` and depend on SymbolTable, not the other way
+ * around. {@link createSemanticModel} composes this pure SymbolTable with the
+ * registries and wraps `add()` to fan out registrations into both layers.
+ *
+ * Dependency direction (strictly enforced):
+ *
+ *     cgraph-shared (NodeLabel)       — leaf type
+ *          ↑
+ *     symbol-table.ts                   — THIS FILE (pure storage)
+ *          ↑
+ *     model/type-registry.ts, method-registry.ts, field-registry.ts
+ *          ↑
+ *     model/registration-table.ts       — dispatch table factory
+ *          ↑
+ *     model/semantic-model.ts           — orchestrator, wraps add()
+ *          ↑
+ *     model/resolve.ts, call-processor.ts, ...
+ *
+ * No arrow ever points downward from this file. If you are tempted to
+ * import from `./model/` here, you are going the wrong way — move the
+ * logic up the dependency chain instead.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSymbolTable = exports.CALL_TARGET_TYPES = exports.FREE_CALLABLE_TYPES = exports.FREE_CALLABLE_TUPLE = exports.CLASS_TYPES = exports.CLASS_TYPES_TUPLE = void 0;
+/**
+ * Class-like NodeLabels — used for qualifiedName fallback inside
+ * `SymbolTable.add()` and (via import into `model/registration-table.ts`)
+ * as the single source of truth for which labels route to classHook
+ * in the dispatch table.
+ *
+ * Exported as a `readonly` tuple so that `typeof CLASS_TYPES_TUPLE[number]`
+ * yields a precise literal union (`ClassLikeLabel`). The model layer
+ * imports this tuple and uses `Record<ClassLikeLabel, 'dispatch'>` in a
+ * `satisfies` intersection to enforce at COMPILE TIME that every label
+ * listed here is also classified as dispatch in `LABEL_BEHAVIOR`. Adding
+ * a new class-like label to this tuple without updating `LABEL_BEHAVIOR`
+ * fails TypeScript.
+ *
+ * Traits are class-like for heritage resolution: PHP `use Trait;`, Rust
+ * `impl Trait for Struct`, and Scala traits all contribute methods to the
+ * hierarchy of their using/implementing type.
+ */
+exports.CLASS_TYPES_TUPLE = [
+    'Class',
+    'Struct',
+    'Interface',
+    'Enum',
+    'Record',
+    'Trait',
+];
+exports.CLASS_TYPES = new Set(exports.CLASS_TYPES_TUPLE);
+/** Free-callable labels — single source of truth for "callables that have
+ *  NO owner scope". Methods and constructors are owner-scoped and live in
+ *  `MethodRegistry`, reached via `model.methods.lookupMethodByName`. Global
+ *  by-name resolution consults both indexes (see `model/index.ts`).
+ *
+ *  Exported as a `readonly` tuple so that `typeof FREE_CALLABLE_TUPLE[number]`
+ *  yields a precise literal union (`FreeCallableLabel`). `registration-table.ts`
+ *  imports this type and uses `Record<FreeCallableLabel, 'callable-only'>` in
+ *  a `satisfies` intersection to enforce at COMPILE TIME that every label
+ *  listed here is also classified as `callable-only` in `LABEL_BEHAVIOR`.
+ *  Adding a label to this tuple without updating `LABEL_BEHAVIOR` fails
+ *  TypeScript.
+ *
+ *  Partial-state caveat: Python/Rust/Kotlin class methods are emitted by
+ *  the worker as `Function` + `ownerId` (not `Method`), so they still land
+ *  here via the `Function` entry. Collapsing those three languages onto the
+ *  `Method` label is pending a `def.type` preservation decision.
+ */
+exports.FREE_CALLABLE_TUPLE = [
+    'Function',
+    'Macro', // C/C++
+    'Delegate', // C#
+];
+exports.FREE_CALLABLE_TYPES = new Set(exports.FREE_CALLABLE_TUPLE);
+/** Symbol types that can be the TARGET of a call in the resolver's kind
+ *  filter — superset of {@link FREE_CALLABLE_TYPES} that also admits
+ *  owner-scoped methods and constructors pulled in from `MethodRegistry`.
+ *
+ *  Why the split: `FREE_CALLABLE_TYPES` now has a narrow meaning (free
+ *  callables indexed in `callableByName`), but call resolution still
+ *  needs to accept Method and Constructor candidates once they have been
+ *  unioned in from `model.methods.lookupMethodByName`. The resolver uses
+ *  this constant for kind filtering in
+ *  `filterCallableCandidates` / `countCallableCandidates`.
+ */
+exports.CALL_TARGET_TYPES = new Set([
+    ...exports.FREE_CALLABLE_TYPES,
+    'Method',
+    'Constructor',
+]);
+const createSymbolTable = () => {
+    // 1. File-Specific Index — stores full SymbolDefinition(s) for O(1) lookup.
+    // Structure: FilePath -> (SymbolName -> SymbolDefinition[])
+    // Array allows overloaded methods (same name, different signatures) to coexist.
+    const fileIndex = new Map();
+    // 2. Eagerly-populated Callable Index — maintained on add().
+    // Structure: SymbolName -> [Callable Definitions]
+    // Only Function, Method, Constructor, Macro, Delegate symbols are indexed.
+    const callableByName = new Map();
+    const add = (filePath, name, nodeId, type, metadata) => {
+        const qualifiedName = exports.CLASS_TYPES.has(type)
+            ? (metadata?.qualifiedName ?? name)
+            : metadata?.qualifiedName;
+        const def = {
+            nodeId,
+            filePath,
+            type,
+            ...(qualifiedName !== undefined ? { qualifiedName } : {}),
+            ...(metadata?.parameterCount !== undefined
+                ? { parameterCount: metadata.parameterCount }
+                : {}),
+            ...(metadata?.requiredParameterCount !== undefined
+                ? { requiredParameterCount: metadata.requiredParameterCount }
+                : {}),
+            ...(metadata?.parameterTypes !== undefined
+                ? { parameterTypes: metadata.parameterTypes }
+                : {}),
+            ...(metadata?.parameterTypeClasses !== undefined
+                ? { parameterTypeClasses: metadata.parameterTypeClasses }
+                : {}),
+            ...(metadata?.returnType !== undefined ? { returnType: metadata.returnType } : {}),
+            ...(metadata?.declaredType !== undefined ? { declaredType: metadata.declaredType } : {}),
+            ...(metadata?.templateArguments !== undefined
+                ? { templateArguments: metadata.templateArguments }
+                : {}),
+            ...(metadata?.ownerId !== undefined ? { ownerId: metadata.ownerId } : {}),
+            ...(metadata?.isDeleted === true ? { isDeleted: true } : {}),
+        };
+        // A. File Index — unconditional.
+        if (!fileIndex.has(filePath)) {
+            fileIndex.set(filePath, new Map());
+        }
+        const fileMap = fileIndex.get(filePath);
+        if (!fileMap.has(name)) {
+            fileMap.set(name, [def]);
+        }
+        else {
+            fileMap.get(name).push(def);
+        }
+        // B. Callable Index — gated by FREE_CALLABLE_TYPES.
+        //    Note: Property is NOT in FREE_CALLABLE_TYPES, so it never lands here.
+        //    This is the single source of truth for callable-index membership;
+        //    the higher-layer dispatch table only decides owner-scoped routing.
+        //
+        //    Fallback: `Method` or `Constructor` without an `ownerId` is an
+        //    extractor contract violation (AST-degraded parse, or a buggy
+        //    language extractor). The owner-scoped dispatch hook silently
+        //    skips such defs because it has no owner to key them under, so
+        //    without this fallback they would be invisible at Tier 3 global
+        //    resolution. Route them through `callableByName` so they remain
+        //    reachable by name — matching pre-dispatch-table behavior.
+        const isOrphanedOwnerScoped = (type === 'Method' || type === 'Constructor') && metadata?.ownerId === undefined;
+        if (exports.FREE_CALLABLE_TYPES.has(type) || isOrphanedOwnerScoped) {
+            const existing = callableByName.get(name);
+            if (existing) {
+                existing.push(def);
+            }
+            else {
+                callableByName.set(name, [def]);
+            }
+        }
+        return def;
+    };
+    const lookupExact = (filePath, name) => {
+        const defs = fileIndex.get(filePath)?.get(name);
+        return defs?.[0]?.nodeId;
+    };
+    const lookupExactFull = (filePath, name) => {
+        const defs = fileIndex.get(filePath)?.get(name);
+        return defs?.[0];
+    };
+    const lookupExactAll = (filePath, name) => {
+        return fileIndex.get(filePath)?.get(name) ?? [];
+    };
+    const lookupCallableByName = (name) => {
+        return callableByName.get(name) ?? [];
+    };
+    /** Returns a live iterator over all indexed file paths (fileIndex.keys()).
+     *  The iterator is invalidated if add() changes fileIndex.size during
+     *  iteration (ES2015 Map spec). Safe in the current pipeline because all
+     *  symbols are added before resolution begins. */
+    const getFiles = () => fileIndex.keys();
+    const getStats = () => ({
+        fileCount: fileIndex.size,
+    });
+    const clear = () => {
+        fileIndex.clear();
+        callableByName.clear();
+    };
+    return {
+        add,
+        lookupExact,
+        lookupExactFull,
+        lookupExactAll,
+        lookupCallableByName,
+        getFiles,
+        getStats,
+        clear,
+    };
+};
+exports.createSymbolTable = createSymbolTable;

package/dist/core/code/engine/core/ingestion/model/type-registry.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Type Registry
+ *
+ * Class/struct/interface index extracted from SymbolTable.
+ * Eagerly-populated indexes keyed by symbol name and qualified name.
+ * Also includes a separate index for Rust Impl blocks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTypeRegistry = void 0;
+const EMPTY = Object.freeze([]);
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+const createTypeRegistry = () => {
+    const classByName = new Map();
+    const classByQualifiedName = new Map();
+    const implByName = new Map();
+    const nestedByOwner = new Map();
+    const lookupClassByName = (name) => {
+        return classByName.get(name) ?? [];
+    };
+    const lookupClassByQualifiedName = (qualifiedName) => {
+        return classByQualifiedName.get(qualifiedName) ?? [];
+    };
+    const lookupImplByName = (name) => {
+        return implByName.get(name) ?? [];
+    };
+    const lookupAllByOwner = (ownerNodeId, simpleName) => {
+        return nestedByOwner.get(`${ownerNodeId}\0${simpleName}`) ?? EMPTY;
+    };
+    const registerClass = (name, qualifiedName, def) => {
+        const existing = classByName.get(name);
+        if (existing) {
+            existing.push(def);
+        }
+        else {
+            classByName.set(name, [def]);
+        }
+        const qualifiedMatches = classByQualifiedName.get(qualifiedName);
+        if (qualifiedMatches) {
+            qualifiedMatches.push(def);
+        }
+        else {
+            classByQualifiedName.set(qualifiedName, [def]);
+        }
+    };
+    const registerImpl = (name, def) => {
+        const existing = implByName.get(name);
+        if (existing) {
+            existing.push(def);
+        }
+        else {
+            implByName.set(name, [def]);
+        }
+    };
+    const registerByOwner = (ownerNodeId, simpleName, def) => {
+        const key = `${ownerNodeId}\0${simpleName}`;
+        const existing = nestedByOwner.get(key);
+        if (existing) {
+            existing.push(def);
+        }
+        else {
+            nestedByOwner.set(key, [def]);
+        }
+    };
+    const clear = () => {
+        classByName.clear();
+        classByQualifiedName.clear();
+        implByName.clear();
+        nestedByOwner.clear();
+    };
+    return {
+        lookupClassByName,
+        lookupClassByQualifiedName,
+        lookupImplByName,
+        lookupAllByOwner,
+        registerClass,
+        registerImpl,
+        registerByOwner,
+        clear,
+    };
+};
+exports.createTypeRegistry = createTypeRegistry;