arceus-s 1.6.4

package/dist/core/ingestion/call-routing.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared Ruby call routing logic.
+ *
+ * Ruby expresses imports and property definitions as method calls rather
+ * than syntax-level constructs. This module provides a routing function
+ * used by the CLI call-processor, CLI parse-worker, and the web
+ * call-processor so that the classification logic lives in one place.
+ *
+ * Heritage (mixins: include/extend/prepend) was previously routed here
+ * but is now handled by heritageExtractor.extractFromCall before the
+ * call router runs.  The router still returns 'skip' for these calls.
+ *
+ * NOTE: This file is intentionally duplicated in arceus-web/ because the
+ * two packages have separate build targets (Node native vs WASM/browser).
+ * Keep both copies in sync until a shared package is introduced.
+ */
+import type { SyntaxNode } from './utils/ast-helpers.js';
+/** null = this call was not routed; fall through to default call handling */
+export type CallRoutingResult = RubyCallRouting | null;
+/**
+ * Per-language call router.
+ * IMPORTANT: Call-routed imports bypass preprocessImportPath(), so any router that
+ * returns an importPath MUST validate it independently (length cap, control-char
+ * rejection). See routeRubyCall for the reference implementation.
+ */
+export type CallRouter = (calledName: string, callNode: SyntaxNode) => CallRoutingResult;
+export type RubyCallRouting = {
+    kind: 'import';
+    importPath: string;
+    isRelative: boolean;
+} | {
+    kind: 'properties';
+    items: RubyPropertyItem[];
+} | {
+    kind: 'call';
+} | {
+    kind: 'skip';
+};
+export type RubyAccessorType = 'attr_accessor' | 'attr_reader' | 'attr_writer';
+export interface RubyPropertyItem {
+    propName: string;
+    accessorType: RubyAccessorType;
+    startLine: number;
+    endLine: number;
+    /** YARD @return [Type] annotation preceding the attr_accessor call */
+    declaredType?: string;
+}
+/**
+ * Classify a Ruby call node and extract its semantic payload.
+ *
+ * @param calledName - The method name (e.g. 'require', 'include', 'attr_accessor')
+ * @param callNode   - The tree-sitter `call` AST node
+ * @returns A discriminated union describing the call's semantic role
+ */
+export declare function routeRubyCall(calledName: string, callNode: SyntaxNode): RubyCallRouting;

package/dist/core/ingestion/call-routing.js

@@ -0,0 +1,95 @@
+/**
+ * Shared Ruby call routing logic.
+ *
+ * Ruby expresses imports and property definitions as method calls rather
+ * than syntax-level constructs. This module provides a routing function
+ * used by the CLI call-processor, CLI parse-worker, and the web
+ * call-processor so that the classification logic lives in one place.
+ *
+ * Heritage (mixins: include/extend/prepend) was previously routed here
+ * but is now handled by heritageExtractor.extractFromCall before the
+ * call router runs.  The router still returns 'skip' for these calls.
+ *
+ * NOTE: This file is intentionally duplicated in arceus-web/ because the
+ * two packages have separate build targets (Node native vs WASM/browser).
+ * Keep both copies in sync until a shared package is introduced.
+ */
+// ── Pre-allocated singletons for common return values ────────────────────────
+const CALL_RESULT = { kind: 'call' };
+const SKIP_RESULT = { kind: 'skip' };
+// ── Routing function ────────────────────────────────────────────────────────
+/**
+ * Classify a Ruby call node and extract its semantic payload.
+ *
+ * @param calledName - The method name (e.g. 'require', 'include', 'attr_accessor')
+ * @param callNode   - The tree-sitter `call` AST node
+ * @returns A discriminated union describing the call's semantic role
+ */
+export function routeRubyCall(calledName, callNode) {
+    // ── require / require_relative → import ─────────────────────────────────
+    if (calledName === 'require' || calledName === 'require_relative') {
+        const argList = callNode.childForFieldName?.('arguments');
+        const stringNode = argList?.children?.find((c) => c.type === 'string');
+        const contentNode = stringNode?.children?.find((c) => c.type === 'string_content');
+        if (!contentNode)
+            return SKIP_RESULT;
+        let importPath = contentNode.text;
+        // Validate: reject null bytes, control chars, excessively long paths
+        if (!importPath || importPath.length > 1024 || /[\x00-\x1f]/.test(importPath)) {
+            return SKIP_RESULT;
+        }
+        const isRelative = calledName === 'require_relative';
+        if (isRelative && !importPath.startsWith('.')) {
+            importPath = './' + importPath;
+        }
+        return { kind: 'import', importPath, isRelative };
+    }
+    // ── include / extend / prepend — heritage (now handled by heritageExtractor) ─
+    // Call-based heritage is intercepted by heritageExtractor.extractFromCall
+    // before the call router runs.  Return SKIP_RESULT so these calls don't
+    // fall through to normal call processing.
+    if (calledName === 'include' || calledName === 'extend' || calledName === 'prepend') {
+        return SKIP_RESULT;
+    }
+    // ── attr_accessor / attr_reader / attr_writer → property definitions ───
+    if (calledName === 'attr_accessor' ||
+        calledName === 'attr_reader' ||
+        calledName === 'attr_writer') {
+        // Extract YARD @return [Type] from preceding comment (e.g. `# @return [Address]`)
+        let yardType;
+        let sibling = callNode.previousSibling;
+        while (sibling) {
+            if (sibling.type === 'comment') {
+                const match = /@return\s+\[([^\]]+)\]/.exec(sibling.text);
+                if (match) {
+                    const raw = match[1].trim();
+                    // Extract simple type name: "User", "Array<User>" → "User"
+                    const simple = raw.match(/^([A-Z]\w*)/);
+                    if (simple)
+                        yardType = simple[1];
+                    break;
+                }
+            }
+            else if (sibling.isNamed) {
+                break; // stop at non-comment named sibling
+            }
+            sibling = sibling.previousSibling;
+        }
+        const items = [];
+        const argList = callNode.childForFieldName?.('arguments');
+        for (const arg of argList?.children ?? []) {
+            if (arg.type === 'simple_symbol') {
+                items.push({
+                    propName: arg.text.startsWith(':') ? arg.text.slice(1) : arg.text,
+                    accessorType: calledName,
+                    startLine: arg.startPosition.row,
+                    endLine: arg.endPosition.row,
+                    ...(yardType ? { declaredType: yardType } : {}),
+                });
+            }
+        }
+        return items.length > 0 ? { kind: 'properties', items } : SKIP_RESULT;
+    }
+    // ── Everything else → regular call ─────────────────────────────────────
+    return CALL_RESULT;
+}

package/dist/core/ingestion/call-types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Types for the language-agnostic call extraction pipeline.
+ *
+ * Mirrors method-types.ts / field-types.ts: defines the domain interfaces
+ * consumed by createCallExtractor() and the per-language configs.
+ */
+import type { SupportedLanguages } from '../../_shared/index.js';
+import type { SyntaxNode } from './utils/ast-helpers.js';
+import type { MixedChainStep } from './utils/call-analysis.js';
+/**
+ * Per-node call extraction result.  The parse worker enriches this with
+ * file-level context (filePath, sourceId, TypeEnv lookups, arg types) to
+ * produce the final `ExtractedCall` that enters the resolution pipeline.
+ */
+export interface ExtractedCallSite {
+    calledName: string;
+    callForm?: 'free' | 'member' | 'constructor';
+    receiverName?: string;
+    argCount?: number;
+    /** Unified mixed chain for complex receivers (field + call chains). */
+    receiverMixedChain?: MixedChainStep[];
+    /** When true, the type-as-receiver heuristic applies: if receiverName
+     *  starts with an uppercase letter and has no TypeEnv binding, treat it
+     *  as a type name (e.g. Java `User::getName`). */
+    typeAsReceiverHeuristic?: boolean;
+}
+export interface CallExtractor {
+    readonly language: SupportedLanguages;
+    /**
+     * Extract a call site from captured AST nodes.
+     *
+     * @param callNode     The @call capture (call_expression, method_invocation, …)
+     * @param callNameNode The @call.name capture (identifier inside the call).
+     *                     May be undefined when the call shape has no name capture
+     *                     (e.g. Java method_reference via `::`).
+     * @returns Extracted call site, or null when no call can be derived.
+     */
+    extract(callNode: SyntaxNode, callNameNode: SyntaxNode | undefined): ExtractedCallSite | null;
+}
+export interface CallExtractionConfig {
+    language: SupportedLanguages;
+    /**
+     * Language-specific call site extraction.  Called **before** the generic
+     * path.  If it returns non-null, the generic `inferCallForm` /
+     * `extractReceiverName` path is skipped entirely.
+     *
+     * Use this for call shapes that don't follow the standard `@call` /
+     * `@call.name` pattern (e.g. Java `method_reference` via `::`).
+     */
+    extractLanguageCallSite?: (callNode: SyntaxNode) => ExtractedCallSite | null;
+    /**
+     * Whether the type-as-receiver heuristic applies for this language.
+     * When true and the receiver name starts with an uppercase letter,
+     * the receiver is treated as a type name when no TypeEnv binding exists.
+     *
+     * Applies to JVM and C# languages where `Type.method()` and `Type::method`
+     * are common patterns.
+     */
+    typeAsReceiverHeuristic?: boolean;
+}
+/**
+ * DAG stage 3 output: call record with receiver type and source discriminant.
+ *
+ * `receiverTypeName` is resolved via TypeEnv → constructor-map → class-as-receiver →
+ * mixed-chain, or synthesized by `inferImplicitReceiver`. `receiverSource` tags
+ * which path won and drives MRO strategy selection in stage 4.
+ *
+ * Invariants:
+ * - `receiverSource` MUST match how `receiverTypeName` was resolved; every
+ *   discriminant must have a live reader and writer.
+ * - `hint` is opaque to shared stages; only the same provider's `selectDispatch` reads it.
+ *
+ * @see language-provider.ts § inferImplicitReceiver, selectDispatch
+ */
+export interface ReceiverEnriched {
+    readonly calledName: string;
+    readonly callForm: 'free' | 'member' | 'constructor' | undefined;
+    readonly receiverName: string | undefined;
+    readonly receiverTypeName: string | undefined;
+    readonly receiverSource: 'none' | 'typed-binding' | 'constructor-map' | 'class-as-receiver' | 'mixed-chain' | 'implicit-self';
+    /** Free-form hint from the provider hook; opaque to shared stages. */
+    readonly hint?: string;
+}
+/**
+ * Provider hook output for `LanguageProvider.inferImplicitReceiver` (DAG stage 3).
+ *
+ * Overlay applied to `ReceiverEnriched` when an implicit receiver is synthesized.
+ * Ruby example: bare `serialize` inside `Account#call_serialize` →
+ * `{ callForm: 'member', receiverName: 'self', receiverTypeName: 'Account',
+ *   receiverSource: 'implicit-self', hint: 'instance' }`
+ *
+ * Invariants:
+ * - `receiverSource` is always `'implicit-self'` — the only variant this type produces.
+ * - `callForm` is always `'member'` — the rewrite converts bare-call to method invocation.
+ * - `hint` is opaque to shared stages; consumed by the same language's `selectDispatch`.
+ */
+export interface ImplicitReceiverOverride {
+    readonly callForm: 'free' | 'member' | 'constructor';
+    readonly receiverName: string;
+    readonly receiverTypeName: string;
+    readonly receiverSource: Extract<ReceiverEnriched['receiverSource'], 'implicit-self'>;
+    /** Free-form language tag (e.g. Ruby sets 'singleton' for `def self.foo`
+     *  method bodies). Consumed by the same language's `selectDispatch` hook. */
+    readonly hint?: string;
+}
+/**
+ * DAG stage 4 output: dispatch strategy for resolving the target method.
+ *
+ * Encodes which resolver branch to try first and an optional fallback.
+ * Stage 5 delegates to `resolveMemberCall`, `resolveFreeCall`, or
+ * `resolveStaticCall` based on `primary`.
+ *
+ * - `primary`: `'owner-scoped'` = MRO walk, `'free'` = arity-tiered global lookup,
+ *   `'constructor'` = type instantiation.
+ * - `fallback`: Only `'free-arity-narrowed'` exists; used by Ruby implicit-self
+ *   to degrade to arity-tiered free lookup when the MRO walk misses.
+ * - `ancestryView`: Ruby `'ruby-mixin'` only. `'singleton'` walks extend providers
+ *   only; a miss NEVER falls through to file-scoped lookup (enforced in
+ *   resolveCallTarget). `'instance'` is the default.
+ *
+ * Common patterns:
+ *   - `{primary: 'constructor'}` — constructor call
+ *   - `{primary: 'owner-scoped'}` — member call with known type
+ *   - `{primary: 'owner-scoped', fallback: 'free-arity-narrowed', ancestryView: 'instance'}` — Ruby implicit-self
+ *   - `{primary: 'owner-scoped', ancestryView: 'singleton'}` — Ruby class-method call
+ *
+ * @see language-provider.ts § selectDispatch
+ * @see call-processor.ts § defaultDispatchDecision, resolveCallTarget
+ */
+export interface DispatchDecision {
+    readonly primary: 'owner-scoped' | 'free' | 'constructor';
+    readonly fallback?: 'free-arity-narrowed';
+    readonly ancestryView?: 'instance' | 'singleton';
+    readonly hint?: string;
+}

package/dist/core/ingestion/call-types.js

@@ -0,0 +1,2 @@
+// arc/src/core/ingestion/call-types.ts
+export {};

package/dist/core/ingestion/class-extractors/configs/c-cpp.d.ts

@@ -0,0 +1,3 @@
+import type { ClassExtractionConfig } from '../../class-types.js';
+export declare const cClassConfig: ClassExtractionConfig;
+export declare const cppClassConfig: ClassExtractionConfig;

package/dist/core/ingestion/class-extractors/configs/c-cpp.js

@@ -0,0 +1,11 @@
+// arc/src/core/ingestion/class-extractors/configs/c-cpp.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const cClassConfig = {
+    language: SupportedLanguages.C,
+    typeDeclarationNodes: ['struct_specifier', 'enum_specifier'],
+};
+export const cppClassConfig = {
+    language: SupportedLanguages.CPlusPlus,
+    typeDeclarationNodes: ['class_specifier', 'struct_specifier', 'enum_specifier'],
+    ancestorScopeNodeTypes: ['namespace_definition', 'class_specifier', 'struct_specifier'],
+};

package/dist/core/ingestion/class-extractors/configs/csharp.d.ts

@@ -0,0 +1,2 @@
+import type { ClassExtractionConfig } from '../../class-types.js';
+export declare const csharpClassConfig: ClassExtractionConfig;

package/dist/core/ingestion/class-extractors/configs/csharp.js

@@ -0,0 +1,21 @@
+// arc/src/core/ingestion/class-extractors/configs/csharp.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const csharpClassConfig = {
+    language: SupportedLanguages.CSharp,
+    typeDeclarationNodes: [
+        'class_declaration',
+        'interface_declaration',
+        'struct_declaration',
+        'enum_declaration',
+        'record_declaration',
+    ],
+    fileScopeNodeTypes: ['file_scoped_namespace_declaration'],
+    ancestorScopeNodeTypes: [
+        'namespace_declaration',
+        'class_declaration',
+        'interface_declaration',
+        'struct_declaration',
+        'enum_declaration',
+        'record_declaration',
+    ],
+};

package/dist/core/ingestion/class-extractors/configs/dart.d.ts

@@ -0,0 +1,2 @@
+import type { ClassExtractionConfig } from '../../class-types.js';
+export declare const dartClassConfig: ClassExtractionConfig;

package/dist/core/ingestion/class-extractors/configs/dart.js

@@ -0,0 +1,7 @@
+// arc/src/core/ingestion/class-extractors/configs/dart.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const dartClassConfig = {
+    language: SupportedLanguages.Dart,
+    typeDeclarationNodes: ['class_definition', 'extension_declaration', 'enum_declaration'],
+    ancestorScopeNodeTypes: ['class_definition', 'extension_declaration', 'enum_declaration'],
+};

package/dist/core/ingestion/class-extractors/configs/go.d.ts

@@ -0,0 +1,2 @@
+import type { ClassExtractionConfig } from '../../class-types.js';
+export declare const goClassConfig: ClassExtractionConfig;

package/dist/core/ingestion/class-extractors/configs/go.js

@@ -0,0 +1,20 @@
+// arc/src/core/ingestion/class-extractors/configs/go.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const goClassConfig = {
+    language: SupportedLanguages.Go,
+    typeDeclarationNodes: ['type_declaration'],
+    fileScopeNodeTypes: ['package_clause'],
+    extractName(node) {
+        const typeSpec = node.namedChildren.find((child) => child.type === 'type_spec');
+        return typeSpec?.childForFieldName('name')?.text;
+    },
+    extractType(node) {
+        const typeSpec = node.namedChildren.find((child) => child.type === 'type_spec');
+        const typeNode = typeSpec?.childForFieldName('type');
+        if (typeNode?.type === 'struct_type')
+            return 'Struct';
+        if (typeNode?.type === 'interface_type')
+            return 'Interface';
+        return undefined;
+    },
+};

package/dist/core/ingestion/class-extractors/configs/jvm.d.ts

@@ -0,0 +1,3 @@
+import type { ClassExtractionConfig } from '../../class-types.js';
+export declare const javaClassConfig: ClassExtractionConfig;
+export declare const kotlinClassConfig: ClassExtractionConfig;

package/dist/core/ingestion/class-extractors/configs/jvm.js

@@ -0,0 +1,35 @@
+// arc/src/core/ingestion/class-extractors/configs/jvm.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+// ---------------------------------------------------------------------------
+// Java
+// ---------------------------------------------------------------------------
+export const javaClassConfig = {
+    language: SupportedLanguages.Java,
+    typeDeclarationNodes: [
+        'class_declaration',
+        'interface_declaration',
+        'enum_declaration',
+        'record_declaration',
+    ],
+    fileScopeNodeTypes: ['package_declaration'],
+    ancestorScopeNodeTypes: [
+        'class_declaration',
+        'interface_declaration',
+        'enum_declaration',
+        'record_declaration',
+    ],
+};
+// ---------------------------------------------------------------------------
+// Kotlin
+// ---------------------------------------------------------------------------
+export const kotlinClassConfig = {
+    language: SupportedLanguages.Kotlin,
+    typeDeclarationNodes: ['class_declaration', 'object_declaration', 'companion_object'],
+    fileScopeNodeTypes: ['package_header'],
+    ancestorScopeNodeTypes: ['class_declaration', 'object_declaration', 'companion_object'],
+    extractType(node) {
+        if (node.type !== 'class_declaration')
+            return undefined;
+        return node.children.some((child) => child?.text === 'interface') ? 'Interface' : 'Class';
+    },
+};

package/dist/core/ingestion/class-extractors/configs/php.d.ts

@@ -0,0 +1,2 @@
+import type { ClassExtractionConfig } from '../../class-types.js';
+export declare const phpClassConfig: ClassExtractionConfig;

package/dist/core/ingestion/class-extractors/configs/php.js

@@ -0,0 +1,7 @@
+// arc/src/core/ingestion/class-extractors/configs/php.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const phpClassConfig = {
+    language: SupportedLanguages.PHP,
+    typeDeclarationNodes: ['class_declaration', 'interface_declaration', 'enum_declaration'],
+    ancestorScopeNodeTypes: ['namespace_definition'],
+};

package/dist/core/ingestion/class-extractors/configs/python.d.ts

@@ -0,0 +1,2 @@
+import type { ClassExtractionConfig } from '../../class-types.js';
+export declare const pythonClassConfig: ClassExtractionConfig;

package/dist/core/ingestion/class-extractors/configs/python.js

@@ -0,0 +1,7 @@
+// arc/src/core/ingestion/class-extractors/configs/python.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const pythonClassConfig = {
+    language: SupportedLanguages.Python,
+    typeDeclarationNodes: ['class_definition'],
+    ancestorScopeNodeTypes: ['class_definition'],
+};

package/dist/core/ingestion/class-extractors/configs/ruby.d.ts

@@ -0,0 +1,2 @@
+import type { ClassExtractionConfig } from '../../class-types.js';
+export declare const rubyClassConfig: ClassExtractionConfig;

package/dist/core/ingestion/class-extractors/configs/ruby.js

@@ -0,0 +1,7 @@
+// arc/src/core/ingestion/class-extractors/configs/ruby.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const rubyClassConfig = {
+    language: SupportedLanguages.Ruby,
+    typeDeclarationNodes: ['class'],
+    ancestorScopeNodeTypes: ['module', 'class'],
+};

package/dist/core/ingestion/class-extractors/configs/rust.d.ts

@@ -0,0 +1,2 @@
+import type { ClassExtractionConfig } from '../../class-types.js';
+export declare const rustClassConfig: ClassExtractionConfig;

package/dist/core/ingestion/class-extractors/configs/rust.js

@@ -0,0 +1,7 @@
+// arc/src/core/ingestion/class-extractors/configs/rust.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const rustClassConfig = {
+    language: SupportedLanguages.Rust,
+    typeDeclarationNodes: ['struct_item', 'enum_item'],
+    ancestorScopeNodeTypes: ['mod_item', 'struct_item', 'enum_item'],
+};

package/dist/core/ingestion/class-extractors/configs/swift.d.ts

@@ -0,0 +1,2 @@
+import type { ClassExtractionConfig } from '../../class-types.js';
+export declare const swiftClassConfig: ClassExtractionConfig;

package/dist/core/ingestion/class-extractors/configs/swift.js

@@ -0,0 +1,18 @@
+// arc/src/core/ingestion/class-extractors/configs/swift.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const swiftClassConfig = {
+    language: SupportedLanguages.Swift,
+    typeDeclarationNodes: ['class_declaration', 'protocol_declaration'],
+    ancestorScopeNodeTypes: ['class_declaration', 'protocol_declaration'],
+    extractType(node) {
+        if (node.type === 'protocol_declaration')
+            return 'Interface';
+        if (node.type !== 'class_declaration')
+            return undefined;
+        if (node.children.some((child) => child?.text === 'struct'))
+            return 'Struct';
+        if (node.children.some((child) => child?.text === 'enum'))
+            return 'Enum';
+        return 'Class';
+    },
+};

package/dist/core/ingestion/class-extractors/configs/typescript-javascript.d.ts

@@ -0,0 +1,4 @@
+import type { ClassExtractionConfig } from '../../class-types.js';
+export declare const typescriptClassConfig: ClassExtractionConfig;
+export declare const javascriptClassConfig: ClassExtractionConfig;
+export declare const vueClassConfig: ClassExtractionConfig;

package/dist/core/ingestion/class-extractors/configs/typescript-javascript.js

@@ -0,0 +1,28 @@
+// arc/src/core/ingestion/class-extractors/configs/typescript-javascript.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+const shared = {
+    typeDeclarationNodes: [
+        'class_declaration',
+        'abstract_class_declaration',
+        'interface_declaration',
+        'enum_declaration',
+    ],
+    ancestorScopeNodeTypes: [
+        'class_declaration',
+        'abstract_class_declaration',
+        'interface_declaration',
+        'enum_declaration',
+    ],
+};
+export const typescriptClassConfig = {
+    ...shared,
+    language: SupportedLanguages.TypeScript,
+};
+export const javascriptClassConfig = {
+    ...shared,
+    language: SupportedLanguages.JavaScript,
+};
+export const vueClassConfig = {
+    ...shared,
+    language: SupportedLanguages.Vue,
+};

package/dist/core/ingestion/class-extractors/generic.d.ts

@@ -0,0 +1,2 @@
+import type { ClassExtractionConfig, ClassExtractor } from '../class-types.js';
+export declare function createClassExtractor(config: ClassExtractionConfig): ClassExtractor;