@grafema/core 0.1.0-alpha.5 → 0.2.0-beta

package/dist/plugins/analysis/ast/types.d.ts

@@ -13,7 +13,6 @@ export interface ModuleNode {
 }
 export interface FunctionInfo {
     id: string;
-    stableId: string;
     type: 'FUNCTION';
     name: string;
     file: string;
@@ -25,15 +24,19 @@ export interface FunctionInfo {
     isAssignment?: boolean;
     isCallback?: boolean;
     parentScopeId?: string;
+    controlFlow?: ControlFlowMetadata;
 }
 export interface ParameterInfo {
     id: string;
+    semanticId?: string;
     type: 'PARAMETER';
     name: string;
     file: string;
     line: number;
     index?: number;
-    functionId: string;
+    hasDefault?: boolean;
+    isRest?: boolean;
+    functionId?: string;
     parentFunctionId?: string;
 }
 export interface ScopeInfo {
@@ -56,8 +59,103 @@ export interface ScopeInfo {
         line: number;
     }>;
 }
+export interface BranchInfo {
+    id: string;
+    semanticId?: string;
+    type: 'BRANCH';
+    branchType: 'switch' | 'if' | 'ternary';
+    file: string;
+    line: number;
+    parentScopeId?: string;
+    discriminantExpressionId?: string;
+    discriminantExpressionType?: string;
+    discriminantLine?: number;
+    discriminantColumn?: number;
+    isAlternateOfBranchId?: string;
+    consequentExpressionId?: string;
+    alternateExpressionId?: string;
+}
+export interface CaseInfo {
+    id: string;
+    semanticId?: string;
+    type: 'CASE';
+    value: unknown;
+    isDefault: boolean;
+    fallsThrough: boolean;
+    isEmpty: boolean;
+    file: string;
+    line: number;
+    parentBranchId: string;
+}
+export interface LoopInfo {
+    id: string;
+    semanticId?: string;
+    type: 'LOOP';
+    loopType: 'for' | 'for-in' | 'for-of' | 'while' | 'do-while';
+    file: string;
+    line: number;
+    column?: number;
+    parentScopeId?: string;
+    iteratesOverName?: string;
+    iteratesOverLine?: number;
+    iteratesOverColumn?: number;
+    conditionExpressionId?: string;
+    conditionExpressionType?: string;
+    conditionLine?: number;
+    conditionColumn?: number;
+    initVariableName?: string;
+    initLine?: number;
+    testExpressionId?: string;
+    testExpressionType?: string;
+    testLine?: number;
+    testColumn?: number;
+    updateExpressionId?: string;
+    updateExpressionType?: string;
+    updateLine?: number;
+    updateColumn?: number;
+    async?: boolean;
+}
+export interface TryBlockInfo {
+    id: string;
+    semanticId?: string;
+    type: 'TRY_BLOCK';
+    file: string;
+    line: number;
+    column?: number;
+    parentScopeId?: string;
+}
+export interface CatchBlockInfo {
+    id: string;
+    semanticId?: string;
+    type: 'CATCH_BLOCK';
+    file: string;
+    line: number;
+    column?: number;
+    parentScopeId?: string;
+    parentTryBlockId: string;
+    parameterName?: string;
+}
+export interface FinallyBlockInfo {
+    id: string;
+    semanticId?: string;
+    type: 'FINALLY_BLOCK';
+    file: string;
+    line: number;
+    column?: number;
+    parentScopeId?: string;
+    parentTryBlockId: string;
+}
+export interface ControlFlowMetadata {
+    hasBranches: boolean;
+    hasLoops: boolean;
+    hasTryCatch: boolean;
+    hasEarlyReturn: boolean;
+    hasThrow: boolean;
+    cyclomaticComplexity: number;
+}
 export interface VariableDeclarationInfo {
     id: string;
+    semanticId?: string;
     type: 'VARIABLE' | 'CONSTANT';
     name: string;
     file: string;
@@ -68,6 +166,7 @@ export interface VariableDeclarationInfo {
 }
 export interface CallSiteInfo {
     id: string;
+    semanticId?: string;
     type: 'CALL';
     name: string;
     file: string;
@@ -79,10 +178,13 @@ export interface CallSiteInfo {
 }
 export interface MethodCallInfo {
     id: string;
+    semanticId?: string;
     type: 'CALL';
     name: string;
     object: string;
     method: string;
+    computed?: boolean;
+    computedPropertyVar?: string | null;
     file: string;
     line: number;
     column?: number;
@@ -92,6 +194,7 @@ export interface MethodCallInfo {
 }
 export interface EventListenerInfo {
     id: string;
+    semanticId?: string;
     type: 'event:listener';
     name: string;
     object: string;
@@ -107,8 +210,18 @@ export interface ClassInstantiationInfo {
     line: number;
     parentScopeId?: string;
 }
+export interface ConstructorCallInfo {
+    id: string;
+    type: 'CONSTRUCTOR_CALL';
+    className: string;
+    isBuiltin: boolean;
+    file: string;
+    line: number;
+    column: number;
+}
 export interface ClassDeclarationInfo {
     id: string;
+    semanticId?: string;
     type: 'CLASS';
     name: string;
     file: string;
@@ -119,7 +232,12 @@ export interface ClassDeclarationInfo {
     methods: string[];
 }
 export interface InterfaceDeclarationInfo {
-    id: string;
+    /**
+     * @deprecated ID is now generated by InterfaceNode.create() in GraphBuilder.
+     * This field will be removed in a future version.
+     */
+    id?: string;
+    semanticId?: string;
     type: 'INTERFACE';
     name: string;
     file: string;
@@ -135,7 +253,12 @@ export interface InterfacePropertyInfo {
     readonly?: boolean;
 }
 export interface TypeAliasInfo {
-    id: string;
+    /**
+     * @deprecated ID is now generated by NodeFactory.createType() in GraphBuilder.
+     * This field will be removed in a future version.
+     */
+    id?: string;
+    semanticId?: string;
     type: 'TYPE';
     name: string;
     file: string;
@@ -144,7 +267,12 @@ export interface TypeAliasInfo {
     aliasOf?: string;
 }
 export interface EnumDeclarationInfo {
-    id: string;
+    /**
+     * @deprecated ID is now generated by EnumNode.create() in GraphBuilder.
+     * This field will be removed in a future version.
+     */
+    id?: string;
+    semanticId?: string;
     type: 'ENUM';
     name: string;
     file: string;
@@ -159,6 +287,7 @@ export interface EnumMemberInfo {
 }
 export interface DecoratorInfo {
     id: string;
+    semanticId?: string;
     type: 'DECORATOR';
     name: string;
     file: string;
@@ -182,6 +311,10 @@ export interface CallArgumentInfo {
     targetId?: string;
     targetName?: string;
     file?: string;
+    line?: number;
+    column?: number;
+    literalValue?: unknown;
+    expressionType?: string;
     isSpread?: boolean;
     functionLine?: number;
     functionColumn?: number;
@@ -195,7 +328,11 @@ export interface ImportInfo {
     source: string;
     file: string;
     line: number;
+    column?: number;
     specifiers: ImportSpecifier[];
+    isDynamic?: boolean;
+    isResolvable?: boolean;
+    dynamicPath?: string;
 }
 export interface ImportSpecifier {
     imported: string;
@@ -225,6 +362,7 @@ export interface HttpRequestInfo {
 }
 export interface LiteralInfo {
     id: string;
+    semanticId?: string;
     type: 'LITERAL' | 'CALL';
     value?: unknown;
     valueType?: string;
@@ -238,6 +376,160 @@ export interface LiteralInfo {
     parentCallId?: string;
     argIndex?: number;
 }
+export interface ObjectLiteralInfo {
+    id: string;
+    semanticId?: string;
+    type: 'OBJECT_LITERAL';
+    file: string;
+    line: number;
+    column: number;
+    parentCallId?: string;
+    argIndex?: number;
+    isSpread?: boolean;
+}
+export interface ObjectPropertyInfo {
+    objectId: string;
+    propertyName: string;
+    valueNodeId?: string;
+    valueType: 'LITERAL' | 'VARIABLE' | 'CALL' | 'EXPRESSION' | 'OBJECT_LITERAL' | 'ARRAY_LITERAL' | 'SPREAD';
+    valueName?: string;
+    literalValue?: unknown;
+    file: string;
+    line: number;
+    column: number;
+    callLine?: number;
+    callColumn?: number;
+    nestedObjectId?: string;
+    nestedArrayId?: string;
+    valueScopePath?: string[];
+}
+export interface ArrayLiteralInfo {
+    id: string;
+    semanticId?: string;
+    type: 'ARRAY_LITERAL';
+    file: string;
+    line: number;
+    column: number;
+    parentCallId?: string;
+    argIndex?: number;
+}
+export interface ArrayElementInfo {
+    arrayId: string;
+    index: number;
+    valueNodeId?: string;
+    valueType: 'LITERAL' | 'VARIABLE' | 'CALL' | 'EXPRESSION' | 'OBJECT_LITERAL' | 'ARRAY_LITERAL' | 'SPREAD';
+    valueName?: string;
+    literalValue?: unknown;
+    file: string;
+    line: number;
+    column: number;
+    callLine?: number;
+    callColumn?: number;
+    nestedObjectId?: string;
+    nestedArrayId?: string;
+}
+/**
+ * Tracks array mutation calls (push, unshift, splice) and indexed assignments
+ * Used to create FLOWS_INTO edges in GraphBuilder
+ *
+ * IMPORTANT: This type is defined ONLY here. Import from this file everywhere.
+ */
+export interface ArrayMutationInfo {
+    id?: string;
+    arrayName: string;
+    arrayLine?: number;
+    mutationScopePath?: string[];
+    mutationMethod: 'push' | 'unshift' | 'splice' | 'indexed';
+    file: string;
+    line: number;
+    column: number;
+    insertedValues: ArrayMutationArgument[];
+    isNested?: boolean;
+    baseObjectName?: string;
+    propertyName?: string;
+}
+export interface ArrayMutationArgument {
+    argIndex: number;
+    isSpread?: boolean;
+    valueType: 'LITERAL' | 'VARIABLE' | 'CALL' | 'EXPRESSION' | 'OBJECT_LITERAL' | 'ARRAY_LITERAL';
+    valueName?: string;
+    valueNodeId?: string;
+    literalValue?: unknown;
+    callLine?: number;
+    callColumn?: number;
+}
+/**
+ * Tracks object property mutations for FLOWS_INTO edge creation in GraphBuilder.
+ * Handles: obj.prop = value, obj['prop'] = value, Object.assign(), spread in object literals.
+ *
+ * IMPORTANT: This type is defined ONLY here. Import from this file everywhere.
+ */
+export interface ObjectMutationInfo {
+    id?: string;
+    objectName: string;
+    objectLine?: number;
+    mutationScopePath?: string[];
+    enclosingClassName?: string;
+    propertyName: string;
+    mutationType: 'property' | 'computed' | 'assign' | 'spread';
+    computedPropertyVar?: string;
+    file: string;
+    line: number;
+    column: number;
+    value: ObjectMutationValue;
+}
+export interface ObjectMutationValue {
+    valueType: 'LITERAL' | 'VARIABLE' | 'CALL' | 'EXPRESSION' | 'OBJECT_LITERAL' | 'ARRAY_LITERAL';
+    valueName?: string;
+    valueNodeId?: string;
+    literalValue?: unknown;
+    callLine?: number;
+    callColumn?: number;
+    isSpread?: boolean;
+    argIndex?: number;
+}
+/**
+ * Tracks return statements for RETURNS edge creation in GraphBuilder.
+ * Used to connect returned expressions to their containing functions.
+ *
+ * Edge direction: returnExpression --RETURNS--> function
+ */
+export interface ReturnStatementInfo {
+    parentFunctionId: string;
+    file: string;
+    line: number;
+    column: number;
+    returnValueType: 'VARIABLE' | 'CALL_SITE' | 'METHOD_CALL' | 'LITERAL' | 'EXPRESSION' | 'NONE';
+    returnValueName?: string;
+    returnValueId?: string;
+    returnValueLine?: number;
+    returnValueColumn?: number;
+    returnValueCallName?: string;
+    expressionType?: string;
+    operator?: string;
+    leftSourceName?: string;
+    rightSourceName?: string;
+    consequentSourceName?: string;
+    alternateSourceName?: string;
+    object?: string;
+    property?: string;
+    computed?: boolean;
+    objectSourceName?: string;
+    expressionSourceNames?: string[];
+    unaryArgSourceName?: string;
+    isImplicitReturn?: boolean;
+}
+/**
+ * Resolution status for computed property names.
+ * Used in FLOWS_INTO edge metadata to indicate how property name was determined.
+ *
+ * - RESOLVED: Single deterministic value traced from literals
+ * - RESOLVED_CONDITIONAL: Multiple possible values (ternary, logical OR, etc.)
+ * - UNKNOWN_PARAMETER: Variable traces to function parameter
+ * - UNKNOWN_RUNTIME: Variable traces to function call result
+ * - DEFERRED_CROSS_FILE: Variable traces to import (requires cross-file analysis)
+ */
+export type ResolutionStatus = 'RESOLVED' | 'RESOLVED_CONDITIONAL' | 'UNKNOWN_PARAMETER' | 'UNKNOWN_RUNTIME' | 'DEFERRED_CROSS_FILE';
 export interface VariableAssignmentInfo {
     variableId: string;
     sourceId?: string | null;
@@ -252,6 +544,7 @@ export interface VariableAssignmentInfo {
     className?: string;
     functionName?: string;
     line?: number;
+    column?: number;
     expressionType?: string;
     object?: string;
     property?: string;
@@ -265,6 +558,137 @@ export interface VariableAssignmentInfo {
     alternateSourceName?: string | null;
     expressionSourceNames?: string[];
     file?: string;
+    path?: string;
+    baseName?: string;
+    propertyPath?: string[];
+    arrayIndex?: number;
+    callSourceLine?: number;
+    callSourceColumn?: number;
+    callSourceFile?: string;
+    callSourceName?: string;
+    sourceMetadata?: {
+        sourceType: 'call' | 'variable' | 'method-call';
+    };
+}
+/**
+ * Tracks variable reassignments for FLOWS_INTO edge creation.
+ * Used when a variable is assigned AFTER its declaration: x = y (not const x = y).
+ *
+ * Edge direction: value --FLOWS_INTO--> variable
+ *
+ * Supports:
+ * - Simple assignment: x = y
+ * - Compound operators: x += y, x -= y, x *= y, x /= y, x %= y, x **= y
+ * - Bitwise operators: x &= y, x |= y, x ^= y, x <<= y, x >>= y, x >>>= y
+ * - Logical operators: x &&= y, x ||= y, x ??= y
+ *
+ * For compound operators (operator !== '='), creates TWO edges:
+ * - READS_FROM: variable --READS_FROM--> variable (self-loop, reads current value)
+ * - FLOWS_INTO: source --FLOWS_INTO--> variable (writes new value)
+ *
+ * Distinction from VariableAssignmentInfo:
+ * - VariableAssignmentInfo: initialization (const x = y) -> ASSIGNED_FROM edge
+ * - VariableReassignmentInfo: mutation (x = y, x += y) -> FLOWS_INTO edge
+ */
+export interface VariableReassignmentInfo {
+    variableName: string;
+    variableLine: number;
+    mutationScopePath?: string[];
+    valueType: 'VARIABLE' | 'CALL_SITE' | 'METHOD_CALL' | 'LITERAL' | 'EXPRESSION';
+    valueName?: string;
+    valueId?: string | null;
+    callLine?: number;
+    callColumn?: number;
+    operator: string;
+    literalValue?: unknown;
+    expressionType?: string;
+    expressionMetadata?: {
+        object?: string;
+        property?: string;
+        computed?: boolean;
+        computedPropertyVar?: string | null;
+        operator?: string;
+        leftSourceName?: string;
+        rightSourceName?: string;
+        consequentSourceName?: string;
+        alternateSourceName?: string;
+    };
+    file: string;
+    line: number;
+    column: number;
+}
+/**
+ * Information about update expressions (increment/decrement).
+ *
+ * Supports two target types:
+ * - IDENTIFIER: Simple variable (i++, --count)
+ * - MEMBER_EXPRESSION: Object property (obj.prop++, arr[i]++, this.count++)
+ *
+ * Creates:
+ * - UPDATE_EXPRESSION node with operator and target metadata
+ * - MODIFIES edge: UPDATE_EXPRESSION -> target (VARIABLE, PARAMETER, or CLASS)
+ * - READS_FROM self-loop: target -> target (reads current value before update)
+ * - CONTAINS edge: SCOPE -> UPDATE_EXPRESSION
+ *
+ * REG-288: Initial implementation for IDENTIFIER targets
+ * REG-312: Extended for MEMBER_EXPRESSION targets (obj.prop++, arr[i]++)
+ */
+export interface UpdateExpressionInfo {
+    operator: '++' | '--';
+    prefix: boolean;
+    file: string;
+    line: number;
+    column: number;
+    parentScopeId?: string;
+    targetType: 'IDENTIFIER' | 'MEMBER_EXPRESSION';
+    variableName?: string;
+    variableLine?: number;
+    objectName?: string;
+    objectLine?: number;
+    enclosingClassName?: string;
+    propertyName?: string;
+    mutationType?: 'property' | 'computed';
+    computedPropertyVar?: string;
+}
+/**
+ * Tracks Promise executor context during analysis.
+ * Used to detect when resolve/reject calls should create RESOLVES_TO edges.
+ *
+ * Stored in collections.promiseExecutorContexts Map, keyed by executor function's start:end position.
+ */
+export interface PromiseExecutorContext {
+    /** ID of the CONSTRUCTOR_CALL node for `new Promise()` */
+    constructorCallId: string;
+    /** Name of the first parameter (typically 'resolve') */
+    resolveName: string;
+    /** Name of the second parameter (typically 'reject'), if any */
+    rejectName?: string;
+    /** File path for edge creation */
+    file: string;
+    /** Line of the Promise constructor for debugging */
+    line: number;
+}
+/**
+ * Info for Promise resolution RESOLVES_TO edges.
+ * Created when resolve(value) or reject(error) is called inside Promise executor.
+ *
+ * Graph structure:
+ * CALL[resolve(42)] --RESOLVES_TO--> CONSTRUCTOR_CALL[new Promise]
+ *
+ * Edge direction: resolve CALL -> Promise CONSTRUCTOR_CALL
+ * This allows traceValues to follow RESOLVES_TO from Promise to find data sources.
+ */
+export interface PromiseResolutionInfo {
+    /** ID of the resolve/reject CALL node */
+    callId: string;
+    /** ID of the Promise CONSTRUCTOR_CALL node */
+    constructorCallId: string;
+    /** True if this is reject(), false for resolve() */
+    isReject: boolean;
+    /** File path */
+    file: string;
+    /** Line number of resolve/reject call */
+    line: number;
 }
 export interface CounterRef {
     value: number;
@@ -285,11 +709,18 @@ export interface ASTCollections {
     functions: FunctionInfo[];
     parameters?: ParameterInfo[];
     scopes: ScopeInfo[];
+    branches?: BranchInfo[];
+    cases?: CaseInfo[];
+    loops?: LoopInfo[];
+    tryBlocks?: TryBlockInfo[];
+    catchBlocks?: CatchBlockInfo[];
+    finallyBlocks?: FinallyBlockInfo[];
     variableDeclarations: VariableDeclarationInfo[];
     callSites: CallSiteInfo[];
     methodCalls?: MethodCallInfo[];
     eventListeners?: EventListenerInfo[];
     classInstantiations?: ClassInstantiationInfo[];
+    constructorCalls?: ConstructorCallInfo[];
     classDeclarations?: ClassDeclarationInfo[];
     methodCallbacks?: MethodCallbackInfo[];
     callArguments?: CallArgumentInfo[];
@@ -298,6 +729,17 @@ export interface ASTCollections {
     httpRequests?: HttpRequestInfo[];
     literals?: LiteralInfo[];
     variableAssignments?: VariableAssignmentInfo[];
+    objectLiterals?: ObjectLiteralInfo[];
+    objectProperties?: ObjectPropertyInfo[];
+    arrayLiterals?: ArrayLiteralInfo[];
+    arrayElements?: ArrayElementInfo[];
+    arrayMutations?: ArrayMutationInfo[];
+    objectMutations?: ObjectMutationInfo[];
+    variableReassignments?: VariableReassignmentInfo[];
+    returnStatements?: ReturnStatementInfo[];
+    updateExpressions?: UpdateExpressionInfo[];
+    promiseResolutions?: PromiseResolutionInfo[];
+    promiseExecutorContexts?: Map<string, PromiseExecutorContext>;
     interfaces?: InterfaceDeclarationInfo[];
     typeAliases?: TypeAliasInfo[];
     enums?: EnumDeclarationInfo[];
@@ -309,7 +751,16 @@ export interface ASTCollections {
     functionCounterRef?: CounterRef;
     httpRequestCounterRef?: CounterRef;
     literalCounterRef?: CounterRef;
+    objectLiteralCounterRef?: CounterRef;
+    arrayLiteralCounterRef?: CounterRef;
+    branchCounterRef?: CounterRef;
+    caseCounterRef?: CounterRef;
+    loopCounterRef?: CounterRef;
+    tryBlockCounterRef?: CounterRef;
+    catchBlockCounterRef?: CounterRef;
+    finallyBlockCounterRef?: CounterRef;
     processedNodes?: ProcessedNodes;
+    scopeTracker?: import('../../../core/ScopeTracker.js').ScopeTracker;
 }
 export interface ExtractedVariable {
     name: string;
@@ -330,6 +781,11 @@ export interface GraphNode {
     file?: string;
     line?: number;
     column?: number;
+    source?: string;
+    importType?: 'default' | 'named' | 'namespace';
+    importBinding?: 'value' | 'type' | 'typeof';
+    imported?: string;
+    local?: string;
     [key: string]: unknown;
 }
 export interface GraphEdge {
@@ -337,6 +793,15 @@ export interface GraphEdge {
     src: string;
     dst: string;
     index?: number;
+    mutationMethod?: string;
+    argIndex?: number;
+    isSpread?: boolean;
+    nestedProperty?: string;
+    mutationType?: 'property' | 'computed' | 'assign' | 'spread' | 'this_property';
+    propertyName?: string;
+    computedPropertyVar?: string;
+    resolvedPropertyNames?: string[];
+    resolutionStatus?: ResolutionStatus;
     metadata?: Record<string, unknown>;
 }
 export interface BuildResult {