arceus-s 1.6.4

package/dist/core/ingestion/model/registration-table.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Registration Dispatch Table
+ *
+ * Behavior-grouped O(1) dispatch table for routing `SymbolTable.add()`
+ * registrations into the semantic registries. Replaces the cascading
+ * `if/else` ladder in `symbol-table.ts` with a `Map<NodeLabel, RoutingDecision>`
+ * whose entries point to closure-captured hooks.
+ *
+ * ## Ownership diagram
+ *
+ *     SemanticModel
+ *       ├── types   (TypeRegistry)    ← classLikeHook / implHook write here
+ *       ├── methods (MethodRegistry)  ← methodHook writes here
+ *       ├── fields  (FieldRegistry)   ← propertyHook writes here
+ *       └── symbols (SymbolTable)     ← owns fileIndex + callableByName,
+ *                                       calls dispatch() in add()
+ *
+ * ## Behavior groups (5 hooks, 13 table entries)
+ *
+ * | Group         | NodeLabel values                                  | Hook         | Skip callable? |
+ * |---------------|---------------------------------------------------|--------------|----------------|
+ * | class-like    | Class, Struct, Interface, Enum, Record, Trait     | classLikeHook    | no             |
+ * | method-like   | Method, Constructor                               | methodHook   | no             |
+ * | property      | Property                                          | propertyHook | YES            |
+ * | impl-block    | Impl                                              | implHook     | no             |
+ * | callable-only | Function, Macro, Delegate                         | (no entry)   | no             |
+ *
+ * Every other `NodeLabel` is "inert" — reached by `fileIndex` only. No
+ * specialized registry, no callable index append.
+ *
+ * ## How to add a new NodeLabel
+ *
+ * 1. Add the variant to the `NodeLabel` union in `arceus-shared/src/graph/types.ts`.
+ * 2. Decide which behavior group it belongs to by asking "which lookups must
+ *    return this symbol?" (not "what language feature is it?"). A new Swift
+ *    `Extension` is class-like if you want owner-scoped method lookup on it;
+ *    a new Kotlin `Object` is class-like for the same reason.
+ * 3. Either:
+ *    - Add a table entry here pointing at one of the existing hooks, OR
+ *    - Add it to `CALLABLE_ONLY_LABELS` if it is a free callable, OR
+ *    - Add it to `INERT_LABELS` if it's metadata-only (File, Folder, Decorator,
+ *      etc.) — never queried via owner/class lookups.
+ * 4. If none of the above fit — the new kind needs a brand-new registry —
+ *    design the registry first in `model/`, then add a new hook closure
+ *    and table entries. Update `DISPATCH_LABELS` / the exhaustiveness guard
+ *    accordingly.
+ *
+ * The runtime exhaustiveness guard in `symbol-table.ts` will warn if a
+ * `NodeLabel` is missing from all three sets.
+ */
+import type { NodeLabel, SymbolDefinition } from '../../../_shared/index.js';
+import type { MutableTypeRegistry } from './type-registry.js';
+import type { MutableMethodRegistry } from './method-registry.js';
+import type { MutableFieldRegistry } from './field-registry.js';
+/**
+ * Registration hook — a pure side-effectful function closed over a
+ * specific registry. Performs the specialized registry write into the
+ * appropriate owner-scoped registry for one NodeLabel.
+ *
+ * Closure capture is the isolation mechanism: `propertyHook` literally
+ * cannot call `types.registerClass` because its closure does not hold
+ * a reference to `types`. This is the runtime half of the principle of
+ * least authority — the compile-time half is enforced by TypeScript.
+ *
+ * The callable-index gate lives inside `SymbolTable.add()` via the
+ * `FREE_CALLABLE_TYPES` allowlist — the dispatch table does not
+ * participate in that decision.
+ */
+export type RegistrationHook = (name: string, def: SymbolDefinition) => void;
+/**
+ * Dependencies required to build the dispatch table. Matches the shape
+ * that `createSemanticModel()` passes into `createRegistrationTable()`.
+ */
+export interface RegistrationTableDeps {
+    readonly types: MutableTypeRegistry;
+    readonly methods: MutableMethodRegistry;
+    readonly fields: MutableFieldRegistry;
+}
+/**
+ * Behavior category for a NodeLabel during ingestion. Determines which
+ * registry (if any) receives the symbol write during `SymbolTable.add()`:
+ *
+ *   - `dispatch`     — owner-scoped registry write via the dispatch table
+ *                      (Class/Struct/Interface/Enum/Record/Trait → types.registerClass,
+ *                       Method/Constructor → methods.register,
+ *                       Property → fields.register,
+ *                       Impl → types.registerImpl)
+ *   - `callable-only` — no specialized registry; symbol appears in
+ *                      `callableByName` via `SymbolTable.add()`'s
+ *                      FREE_CALLABLE_TYPES gate (Function/Macro/Delegate)
+ *   - `inert`        — no registry, no callable index; file-index only
+ *                      (metadata / structural nodes like Project, Module,
+ *                      Import, Decorator, etc.)
+ *
+ * `Function` has a twist: `Function`-with-`ownerId` (Python `def` in a
+ * class body, Rust trait method, Kotlin companion method) is pre-normalized
+ * to `Method` in `createSemanticModel`'s `wrappedAdd` before dispatch lookup,
+ * so only free functions actually flow through the callable-only path.
+ */
+export type LabelBehavior = 'dispatch' | 'callable-only' | 'inert';
+/**
+ * All known NodeLabels, derived from the keys of `LABEL_BEHAVIOR`. The
+ * `satisfies Record<NodeLabel, LabelBehavior>` bijection above proves
+ * that `Object.keys(LABEL_BEHAVIOR)` is exactly the NodeLabel set —
+ * the cast to `NodeLabel[]` is sound, not a type-system bypass.
+ *
+ * Consumers (e.g., the semantic-model barrel re-export for tests) can
+ * rely on this list being complete by construction. No runtime drift
+ * check is needed or possible — the type system is the proof.
+ */
+export declare const ALL_NODE_LABELS: readonly NodeLabel[];
+/**
+ * NodeLabel values that are free callables — appear in `callableByName`
+ * but have no owner-scoped specialized registry. Alias of
+ * {@link FREE_CALLABLE_TYPES} exported here for taxonomy-test use. The
+ * compile-time cross-invariant on `LABEL_BEHAVIOR` above guarantees the
+ * alias and the LABEL_BEHAVIOR `callable-only` classification cannot
+ * drift.
+ */
+export declare const CALLABLE_ONLY_LABELS: ReadonlySet<NodeLabel>;
+/**
+ * NodeLabel values that touch only the file index — no specialized
+ * registry, no callable index.
+ */
+export declare const INERT_LABELS: ReadonlySet<NodeLabel>;
+/**
+ * NodeLabel values that have a dispatch table entry. `createRegistrationTable`
+ * below must provide a hook for exactly this set — the test file's behavior-
+ * group tests and the integration tests pin the hook↔label correspondence.
+ */
+export declare const DISPATCH_LABELS: ReadonlySet<NodeLabel>;
+/**
+ * Build the dispatch table. Must be called once per `createSymbolTable`
+ * invocation so each hook closes over that SymbolTable's injected
+ * registries. Reusing a single module-level instance would cause hooks
+ * to write into the wrong SemanticModel.
+ */
+export declare const createRegistrationTable: (deps: RegistrationTableDeps) => Map<NodeLabel, RegistrationHook>;

package/dist/core/ingestion/model/registration-table.js

@@ -0,0 +1,224 @@
+/**
+ * Registration Dispatch Table
+ *
+ * Behavior-grouped O(1) dispatch table for routing `SymbolTable.add()`
+ * registrations into the semantic registries. Replaces the cascading
+ * `if/else` ladder in `symbol-table.ts` with a `Map<NodeLabel, RoutingDecision>`
+ * whose entries point to closure-captured hooks.
+ *
+ * ## Ownership diagram
+ *
+ *     SemanticModel
+ *       ├── types   (TypeRegistry)    ← classLikeHook / implHook write here
+ *       ├── methods (MethodRegistry)  ← methodHook writes here
+ *       ├── fields  (FieldRegistry)   ← propertyHook writes here
+ *       └── symbols (SymbolTable)     ← owns fileIndex + callableByName,
+ *                                       calls dispatch() in add()
+ *
+ * ## Behavior groups (5 hooks, 13 table entries)
+ *
+ * | Group         | NodeLabel values                                  | Hook         | Skip callable? |
+ * |---------------|---------------------------------------------------|--------------|----------------|
+ * | class-like    | Class, Struct, Interface, Enum, Record, Trait     | classLikeHook    | no             |
+ * | method-like   | Method, Constructor                               | methodHook   | no             |
+ * | property      | Property                                          | propertyHook | YES            |
+ * | impl-block    | Impl                                              | implHook     | no             |
+ * | callable-only | Function, Macro, Delegate                         | (no entry)   | no             |
+ *
+ * Every other `NodeLabel` is "inert" — reached by `fileIndex` only. No
+ * specialized registry, no callable index append.
+ *
+ * ## How to add a new NodeLabel
+ *
+ * 1. Add the variant to the `NodeLabel` union in `arceus-shared/src/graph/types.ts`.
+ * 2. Decide which behavior group it belongs to by asking "which lookups must
+ *    return this symbol?" (not "what language feature is it?"). A new Swift
+ *    `Extension` is class-like if you want owner-scoped method lookup on it;
+ *    a new Kotlin `Object` is class-like for the same reason.
+ * 3. Either:
+ *    - Add a table entry here pointing at one of the existing hooks, OR
+ *    - Add it to `CALLABLE_ONLY_LABELS` if it is a free callable, OR
+ *    - Add it to `INERT_LABELS` if it's metadata-only (File, Folder, Decorator,
+ *      etc.) — never queried via owner/class lookups.
+ * 4. If none of the above fit — the new kind needs a brand-new registry —
+ *    design the registry first in `model/`, then add a new hook closure
+ *    and table entries. Update `DISPATCH_LABELS` / the exhaustiveness guard
+ *    accordingly.
+ *
+ * The runtime exhaustiveness guard in `symbol-table.ts` will warn if a
+ * `NodeLabel` is missing from all three sets.
+ */
+import { FREE_CALLABLE_TYPES } from './symbol-table.js';
+/**
+ * **Single source of truth** for NodeLabel classification. Every NodeLabel
+ * has exactly one behavior category — enforced at compile time by the
+ * `as const satisfies Record<NodeLabel, LabelBehavior>` combo:
+ *
+ *   - **Completeness** — `Record<NodeLabel, LabelBehavior>` requires every
+ *     NodeLabel to be a key. Missing a label fails to compile with
+ *     "Property 'X' is missing in type ..." naming the drifted label.
+ *   - **No extras** — `satisfies` performs excess-property checking on
+ *     object literals, so a non-NodeLabel string key fails to compile.
+ *   - **No duplicates** — object keys are unique by construction. A label
+ *     cannot be classified into two categories by accident.
+ *   - **Valid values** — `LabelBehavior` is a narrow union, so a typo in
+ *     the category name fails to compile.
+ *
+ * Adding a new NodeLabel to `arceus-shared`: TypeScript will flag this
+ * file as incomplete. Add the new label with its behavior category and
+ * the three `*_LABELS` Sets + `ALL_NODE_LABELS` array below are derived
+ * automatically — no separate list to update, no runtime drift detection
+ * needed.
+ *
+ * NOTE: `Type` and `CodeElement` are inert wrappers for language features
+ * that don't yet have a dedicated registry (typedefs, synthesized dynamic
+ * calls). If future work needs owner-scoped lookup for them, change their
+ * category to `'dispatch'` and add a hook in `createRegistrationTable`.
+ * Do not special-case them inside `SymbolTable.add()`.
+ */
+const LABEL_BEHAVIOR = {
+    // dispatch — owner-scoped registry writes
+    Class: 'dispatch',
+    Struct: 'dispatch',
+    Interface: 'dispatch',
+    Enum: 'dispatch',
+    Record: 'dispatch',
+    Trait: 'dispatch',
+    Method: 'dispatch',
+    Constructor: 'dispatch',
+    Property: 'dispatch',
+    Impl: 'dispatch',
+    // callable-only — file index + callableByName, no owner scope
+    Function: 'callable-only',
+    Macro: 'callable-only',
+    Delegate: 'callable-only',
+    // inert — file index only
+    Project: 'inert',
+    Package: 'inert',
+    Module: 'inert',
+    Folder: 'inert',
+    File: 'inert',
+    Variable: 'inert',
+    Decorator: 'inert',
+    Import: 'inert',
+    Type: 'inert',
+    CodeElement: 'inert',
+    Community: 'inert',
+    Process: 'inert',
+    Typedef: 'inert',
+    Union: 'inert',
+    Namespace: 'inert',
+    TypeAlias: 'inert',
+    Const: 'inert',
+    Static: 'inert',
+    Annotation: 'inert',
+    Template: 'inert',
+    Section: 'inert',
+    Route: 'inert',
+    Tool: 'inert',
+};
+// ---------------------------------------------------------------------------
+// Derived runtime collections — all keyed off LABEL_BEHAVIOR
+// ---------------------------------------------------------------------------
+/**
+ * All known NodeLabels, derived from the keys of `LABEL_BEHAVIOR`. The
+ * `satisfies Record<NodeLabel, LabelBehavior>` bijection above proves
+ * that `Object.keys(LABEL_BEHAVIOR)` is exactly the NodeLabel set —
+ * the cast to `NodeLabel[]` is sound, not a type-system bypass.
+ *
+ * Consumers (e.g., the semantic-model barrel re-export for tests) can
+ * rely on this list being complete by construction. No runtime drift
+ * check is needed or possible — the type system is the proof.
+ */
+export const ALL_NODE_LABELS = Object.keys(LABEL_BEHAVIOR);
+const labelsWithBehavior = (behavior) => ALL_NODE_LABELS.filter((label) => LABEL_BEHAVIOR[label] === behavior);
+/**
+ * NodeLabel values that are free callables — appear in `callableByName`
+ * but have no owner-scoped specialized registry. Alias of
+ * {@link FREE_CALLABLE_TYPES} exported here for taxonomy-test use. The
+ * compile-time cross-invariant on `LABEL_BEHAVIOR` above guarantees the
+ * alias and the LABEL_BEHAVIOR `callable-only` classification cannot
+ * drift.
+ */
+export const CALLABLE_ONLY_LABELS = FREE_CALLABLE_TYPES;
+/**
+ * NodeLabel values that touch only the file index — no specialized
+ * registry, no callable index.
+ */
+export const INERT_LABELS = new Set(labelsWithBehavior('inert'));
+/**
+ * NodeLabel values that have a dispatch table entry. `createRegistrationTable`
+ * below must provide a hook for exactly this set — the test file's behavior-
+ * group tests and the integration tests pin the hook↔label correspondence.
+ */
+export const DISPATCH_LABELS = new Set(labelsWithBehavior('dispatch'));
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Build the dispatch table. Must be called once per `createSymbolTable`
+ * invocation so each hook closes over that SymbolTable's injected
+ * registries. Reusing a single module-level instance would cause hooks
+ * to write into the wrong SemanticModel.
+ */
+export const createRegistrationTable = (deps) => {
+    const { types, methods, fields } = deps;
+    // Hook 1: class-like — Class, Struct, Interface, Enum, Record, Trait.
+    // Shared reference — six table entries point at this one closure.
+    const classLikeHook = (name, def) => {
+        const qualifiedKey = def.qualifiedName ?? name;
+        types.registerClass(name, qualifiedKey, def);
+    };
+    // Hook 2: method-like — Method, Constructor. Silently skipped if the
+    // caller did not provide an ownerId (Property without ownerId is
+    // treated the same way).
+    const methodHook = (name, def) => {
+        if (def.ownerId) {
+            methods.register(def.ownerId, name, def);
+        }
+    };
+    // Hook 3: property — Property. Silently skipped without ownerId.
+    // Property is not in `FREE_CALLABLE_TYPES`, so `SymbolTable.add()` already
+    // excludes it from `callableByName`; common property names like
+    // `id` / `name` / `type` never pollute the callable index.
+    const propertyHook = (name, def) => {
+        if (def.ownerId) {
+            fields.register(def.ownerId, name, def);
+        }
+    };
+    // Hook 4: impl-block — Rust `impl` blocks. Kept separate from classLikeHook
+    // because heritage resolution must not treat Impls as class candidates
+    // (an Impl is not a parent type, it's an ancillary dispatch table).
+    const implHook = (name, def) => {
+        types.registerImpl(name, def);
+    };
+    // Single source of truth for the label → hook mapping. The
+    // `satisfies Record<DispatchLabel, RegistrationHook>` intersection
+    // fails at build time if (a) any label classified as 'dispatch' in
+    // `LABEL_BEHAVIOR` is missing here, or (b) any key here is not
+    // classified as 'dispatch'. This is the compile-time twin of the
+    // runtime taxonomy — no drift possible.
+    const dispatchByLabel = {
+        // class-like — six labels share the single `classLikeHook` closure,
+        // kept in lockstep with `CLASS_TYPES_TUPLE` via the
+        // `Record<ClassLikeLabel, 'dispatch'>` cross-invariant on
+        // `LABEL_BEHAVIOR`.
+        Class: classLikeHook,
+        Struct: classLikeHook,
+        Interface: classLikeHook,
+        Enum: classLikeHook,
+        Record: classLikeHook,
+        Trait: classLikeHook,
+        // method-like — routed via dispatch-key normalization in
+        // `wrappedAdd` so Function+ownerId also reaches `methodHook`.
+        Method: methodHook,
+        Constructor: methodHook,
+        // property — callable-index exclusion is enforced by
+        // `SymbolTable.add()` (Property is not in `FREE_CALLABLE_TYPES`).
+        Property: propertyHook,
+        // impl-block — Rust `impl` blocks. Separate from classLikeHook because
+        // heritage resolution must not treat Impls as class candidates.
+        Impl: implHook,
+    };
+    return new Map(Object.entries(dispatchByLabel));
+};

package/dist/core/ingestion/model/resolution-context.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Resolution Context
+ *
+ * Single implementation of tiered name resolution.
+ *
+ * Resolution tiers (highest confidence first):
+ * 1. Same file (lookupExactAll — authoritative)
+ * 2a-named. Named binding chain (walkBindingChain via NamedImportMap)
+ * 2a. Import-scoped (iterate importedFiles with lookupExactAll per file)
+ * 2b. Package-scoped (iterate indexed files matching package dir with lookupExactAll)
+ * 3. Global (lookupClassByName + lookupImplByName + lookupCallableByName — consumers must check count)
+ *
+ * Each tier queries the minimum necessary scope directly:
+ * - Tier 2a iterates the caller's import set (O(imports) × O(1) lookupExactAll).
+ * - Tier 2b iterates all indexed files filtered by package dir
+ *   (O(files) × O(1) lookupExactAll — avoids a global name scan).
+ * - Tier 3 combines lookupClassByName + lookupImplByName + lookupCallableByName
+ *   (three O(1) index lookups with a narrow, type-specific result set).
+ */
+import type { SymbolDefinition } from '../../../_shared/index.js';
+import type { MutableSemanticModel } from './semantic-model.js';
+/**
+ * A single named binding in a source file (e.g. `import { User as U }`).
+ * Stores both the resolved source path and the original exported name so
+ * that aliased imports can resolve U → User in the source file.
+ */
+export interface NamedImportBinding {
+    sourcePath: string;
+    exportedName: string;
+}
+/**
+ * Map<ImportingFilePath, Map<LocalName, NamedImportBinding>>.
+ *
+ * Tracks which specific names a file imports from which sources (TS / Python
+ * / Rust / Java-static / ...). Used to tighten Tier 2a resolution:
+ * `import { User } from './models'` means only `User` (not `Repo`) is
+ * visible from models.ts via this import.
+ */
+export type NamedImportMap = Map<string, Map<string, NamedImportBinding>>;
+/**
+ * Check if a file path is directly inside a package directory identified by
+ * its suffix. Used by Tier 2b package-scoped resolution (Go / C#).
+ */
+export declare function isFileInPackageDir(filePath: string, dirSuffix: string): boolean;
+/** Resolution tier for tracking, logging, and test assertions. */
+export type ResolutionTier = 'same-file' | 'import-scoped' | 'global';
+/** Tier-selected candidates with metadata. */
+export interface TieredCandidates {
+    readonly candidates: readonly SymbolDefinition[];
+    readonly tier: ResolutionTier;
+}
+/** Confidence scores per resolution tier. */
+export declare const TIER_CONFIDENCE: Record<ResolutionTier, number>;
+export type ImportMap = Map<string, Set<string>>;
+export type PackageMap = Map<string, Set<string>>;
+/** Maps callerFile → (moduleAlias → sourceFilePath) for Python namespace imports.
+ *  e.g. `import models` in app.py → moduleAliasMap.get('app.py')?.get('models') === 'models.py' */
+export type ModuleAliasMap = Map<string, Map<string, string>>;
+export interface ResolutionContext {
+    /**
+     * The only resolution API. Returns all candidates at the winning tier.
+     *
+     * Tier 3 ('global') returns ALL candidates regardless of count —
+     * consumers must check candidates.length and refuse ambiguous matches.
+     */
+    resolve(name: string, fromFile: string): TieredCandidates | null;
+    /** Semantic model — the top-level container for types, methods, fields,
+     *  and the nested file/callable SymbolTable. Typed as
+     *  {@link MutableSemanticModel} because `ResolutionContext` is the
+     *  lifecycle owner — the pipeline registers symbols through it during
+     *  the fan-out phase. Resolvers that only query should annotate their
+     *  own fields as {@link SemanticModel} to drop write access. */
+    readonly model: MutableSemanticModel;
+    /** Raw maps — used by import-processor to populate import data. */
+    readonly importMap: ImportMap;
+    readonly packageMap: PackageMap;
+    readonly namedImportMap: NamedImportMap;
+    /** Module-alias map for Python namespace imports: callerFile → (alias → sourceFile). */
+    readonly moduleAliasMap: ModuleAliasMap;
+    enableCache(filePath: string): void;
+    clearCache(): void;
+    getStats(): {
+        fileCount: number;
+        cacheHits: number;
+        cacheMisses: number;
+        tierSameFile: number;
+        tierImportScoped: number;
+        tierGlobal: number;
+        tierMiss: number;
+    };
+    clear(): void;
+}
+export declare const createResolutionContext: () => ResolutionContext;