@grafema/core 0.2.5-beta → 0.2.7

package/src/plugins/enrichment/method-call/MethodCallErrorAnalysis.ts

@@ -0,0 +1,131 @@
+/**
+ * MethodCallErrorAnalysis - Error analysis and suggestion generation.
+ *
+ * Extracted from MethodCallResolver.ts (REG-463).
+ * Free functions that analyze resolution failures and generate
+ * context-aware suggestions for strict mode error reporting (REG-332).
+ */
+
+import type { ResolutionStep, ResolutionFailureReason } from '../../../errors/GrafemaError.js';
+import { LIBRARY_SEMANTIC_GROUPS } from './MethodCallData.js';
+import type { MethodCallNode, ClassEntry } from './MethodCallData.js';
+
+/**
+ * Analyze why method resolution failed (REG-332).
+ * Returns the failure reason and resolution chain for context-aware suggestions.
+ */
+export function analyzeResolutionFailure(
+  methodCall: MethodCallNode,
+  classMethodIndex: Map<string, ClassEntry>,
+  _variableTypes: Map<string, string>
+): { reason: ResolutionFailureReason; chain: ResolutionStep[] } {
+  const { object, method, file } = methodCall;
+  const chain: ResolutionStep[] = [];
+
+  if (!object || !method) {
+    return { reason: 'unknown', chain };
+  }
+
+  // Check if object is a known class name (static call)
+  if (classMethodIndex.has(object)) {
+    const classEntry = classMethodIndex.get(object)!;
+    chain.push({
+      step: `${object} class lookup`,
+      result: 'found',
+      file: classEntry.classNode.file as string | undefined,
+      line: classEntry.classNode.line as number | undefined,
+    });
+
+    if (!classEntry.methods.has(method)) {
+      chain.push({
+        step: `${object}.${method} method`,
+        result: 'NOT FOUND in class',
+      });
+      return { reason: 'method_not_found', chain };
+    }
+  }
+
+  // Check for local class in same file
+  const localKey = `${file}:${object}`;
+  if (classMethodIndex.has(localKey)) {
+    const classEntry = classMethodIndex.get(localKey)!;
+    chain.push({
+      step: `${object} local class`,
+      result: 'found in same file',
+    });
+
+    if (!classEntry.methods.has(method)) {
+      chain.push({
+        step: `${object}.${method} method`,
+        result: 'NOT FOUND',
+      });
+      return { reason: 'method_not_found', chain };
+    }
+  }
+
+  // Check if this is a library call
+  if (LIBRARY_SEMANTIC_GROUPS[object]) {
+    const libInfo = LIBRARY_SEMANTIC_GROUPS[object];
+    chain.push({
+      step: `${object} lookup`,
+      result: `external library (${libInfo.semantic})`,
+    });
+    return { reason: 'external_dependency', chain };
+  }
+
+  // Object type is unknown
+  chain.push({
+    step: `${object} type lookup`,
+    result: 'unknown (not in class index)',
+  });
+  chain.push({
+    step: `${object}.${method}`,
+    result: 'FAILED (no type information)',
+  });
+
+  return { reason: 'unknown_object_type', chain };
+}
+
+/**
+ * Generate context-aware suggestion based on failure reason (REG-332).
+ */
+export function generateContextualSuggestion(
+  object: string,
+  method: string,
+  reason: ResolutionFailureReason,
+  chain: ResolutionStep[]
+): string {
+  switch (reason) {
+    case 'unknown_object_type': {
+      // Find the source in chain that shows "unknown"
+      const sourceStep = chain.find(s => s.result.includes('unknown'));
+      const sourceDesc = sourceStep?.step || 'the source';
+      return `Variable "${object}" has unknown type from ${sourceDesc}. ` +
+             `Add JSDoc: /** @type {${object}Class} */ or check imports.`;
+    }
+
+    case 'class_not_imported':
+      return `Class "${object}" is not imported. Check your imports or ensure the class is defined.`;
+
+    case 'method_not_found':
+      return `Class "${object}" exists but has no method "${method}". ` +
+             `Check spelling or verify the method is defined in the class.`;
+
+    case 'external_dependency': {
+      const libInfo = LIBRARY_SEMANTIC_GROUPS[object];
+      if (libInfo?.suggestedPlugin) {
+        return `This call is to external library "${object}" (${libInfo.semantic}). ` +
+               `Consider using ${libInfo.suggestedPlugin} for semantic analysis.`;
+      }
+      return `This call is to external library "${object}". ` +
+             `Consider adding type stubs or a dedicated analyzer plugin.`;
+    }
+
+    case 'circular_reference':
+      return `Alias chain for "${object}" is too deep (possible cycle). ` +
+             `Simplify variable assignments or check for circular references.`;
+
+    default:
+      return `Check if class "${object}" is imported and has method "${method}".`;
+  }
+}

package/src/plugins/enrichment/method-call/MethodCallIndexers.ts

@@ -0,0 +1,83 @@
+/**
+ * MethodCallIndexers - Index-building functions for method call resolution.
+ *
+ * Extracted from MethodCallResolver.ts (REG-463).
+ * Free functions that build class-method and variable-type indexes from the graph.
+ */
+
+import type { PluginContext } from '../../Plugin.js';
+import type { Logger } from '@grafema/types';
+import type { ClassEntry } from './MethodCallData.js';
+
+/**
+ * Builds an index of classes and their methods for fast lookup.
+ * Each class is indexed by name and by file:name for local resolution.
+ */
+export async function buildClassMethodIndex(
+  graph: PluginContext['graph'],
+  logger: Logger
+): Promise<Map<string, ClassEntry>> {
+  const index = new Map<string, ClassEntry>();
+  const startTime = Date.now();
+  let classCount = 0;
+
+  for await (const classNode of graph.queryNodes({ nodeType: 'CLASS' })) {
+    classCount++;
+    if (classCount % 50 === 0) {
+      logger.debug('Indexing classes', { count: classCount });
+    }
+
+    const className = classNode.name as string;
+    if (!className) continue;
+
+    const classEntry: ClassEntry = {
+      classNode,
+      methods: new Map()
+    };
+
+    const containsEdges = await graph.getOutgoingEdges(classNode.id, ['CONTAINS']);
+    for (const edge of containsEdges) {
+      const childNode = await graph.getNode(edge.dst);
+      if (childNode && (childNode.type === 'METHOD' || childNode.type === 'FUNCTION')) {
+        if (childNode.name) {
+          classEntry.methods.set(childNode.name as string, childNode);
+        }
+      }
+    }
+
+    index.set(className, classEntry);
+
+    // Also index by file for local resolution
+    const fileKey = `${classNode.file}:${className}`;
+    index.set(fileKey, classEntry);
+  }
+
+  const totalTime = ((Date.now() - startTime) / 1000).toFixed(1);
+  logger.debug('Indexed class entries', { count: index.size, time: `${totalTime}s` });
+
+  return index;
+}
+
+/**
+ * Builds an index of variables and their types (from INSTANCE_OF edges).
+ */
+export async function buildVariableTypeIndex(
+  graph: PluginContext['graph'],
+  logger: Logger
+): Promise<Map<string, string>> {
+  const startTime = Date.now();
+  const index = new Map<string, string>();
+
+  for await (const classNode of graph.queryNodes({ nodeType: 'CLASS' })) {
+    if (!classNode.name) continue;
+
+    const incomingEdges = await graph.getIncomingEdges(classNode.id, ['INSTANCE_OF']);
+    for (const edge of incomingEdges) {
+      index.set(edge.src.toString(), classNode.name as string);
+    }
+  }
+
+  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+  logger.debug('Built variable type index', { entries: index.size, time: `${elapsed}s` });
+  return index;
+}

package/src/plugins/enrichment/method-call/MethodCallResolution.ts

@@ -0,0 +1,181 @@
+/**
+ * MethodCallResolution - Core resolution logic for method calls.
+ *
+ * Extracted from MethodCallResolver.ts (REG-463).
+ * Free functions that resolve method calls to their definitions
+ * by searching class indexes, variable types, and inheritance chains.
+ */
+
+import type { PluginContext } from '../../Plugin.js';
+import type { BaseNodeRecord } from '@grafema/types';
+import type { MethodCallNode, ClassEntry } from './MethodCallData.js';
+
+/**
+ * Attempts to resolve a method call to its definition.
+ *
+ * Resolution strategy (in order):
+ * 1. Direct class name match (static call)
+ * 2. Local class in same file
+ * 3. "this" reference to containing class
+ * 4. Variable type index (INSTANCE_OF)
+ */
+export async function resolveMethodCall(
+  methodCall: MethodCallNode,
+  classMethodIndex: Map<string, ClassEntry>,
+  variableTypes: Map<string, string>,
+  graph: PluginContext['graph'],
+  containingClassCache: Map<string, BaseNodeRecord | null>
+): Promise<BaseNodeRecord | null> {
+  const { object, method, file } = methodCall;
+
+  if (!object || !method) return null;
+
+  // 1. Check if object is a class name directly (static call)
+  if (classMethodIndex.has(object)) {
+    const classEntry = classMethodIndex.get(object)!;
+    if (classEntry.methods.has(method)) {
+      return classEntry.methods.get(method)!;
+    }
+    // REG-400: Check parent classes via DERIVES_FROM chain
+    const inherited = await findMethodInParentClasses(
+      classEntry.classNode, method, classMethodIndex, graph
+    );
+    if (inherited) return inherited;
+  }
+
+  // 2. Check local class in same file
+  const localKey = `${file}:${object}`;
+  if (classMethodIndex.has(localKey)) {
+    const classEntry = classMethodIndex.get(localKey)!;
+    if (classEntry.methods.has(method)) {
+      return classEntry.methods.get(method)!;
+    }
+    // REG-400: Check parent classes via DERIVES_FROM chain
+    const inherited = await findMethodInParentClasses(
+      classEntry.classNode, method, classMethodIndex, graph
+    );
+    if (inherited) return inherited;
+  }
+
+  // 3. Check if object is "this" (reference to containing class)
+  if (object === 'this') {
+    let containingClass = containingClassCache.get(methodCall.id);
+    if (containingClass === undefined) {
+      containingClass = await findContainingClass(methodCall, graph);
+      containingClassCache.set(methodCall.id, containingClass);
+    }
+
+    if (containingClass && classMethodIndex.has(containingClass.name as string)) {
+      const classEntry = classMethodIndex.get(containingClass.name as string)!;
+      if (classEntry.methods.has(method)) {
+        return classEntry.methods.get(method)!;
+      }
+      // REG-400: Check parent classes via DERIVES_FROM chain
+      const inherited = await findMethodInParentClasses(
+        classEntry.classNode, method, classMethodIndex, graph
+      );
+      if (inherited) return inherited;
+    }
+  }
+
+  // 4. Use variableTypes index
+  for (const [, className] of variableTypes.entries()) {
+    if (className && classMethodIndex.has(className)) {
+      const classEntry = classMethodIndex.get(className)!;
+      if (classEntry.methods.has(method)) {
+        return classEntry.methods.get(method)!;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * REG-400: Walk DERIVES_FROM inheritance chain to find inherited methods.
+ * Used when method is not found on the direct class.
+ */
+export async function findMethodInParentClasses(
+  classNode: BaseNodeRecord,
+  methodName: string,
+  classMethodIndex: Map<string, ClassEntry>,
+  graph: PluginContext['graph'],
+  maxDepth: number = 5,
+  visited: Set<string> = new Set()
+): Promise<BaseNodeRecord | null> {
+  if (maxDepth <= 0) return null;
+  if (visited.has(classNode.id.toString())) return null;
+  visited.add(classNode.id.toString());
+
+  const derivesFromEdges = await graph.getOutgoingEdges(classNode.id, ['DERIVES_FROM']);
+
+  for (const edge of derivesFromEdges) {
+    const parentClass = await graph.getNode(edge.dst);
+    if (!parentClass || !parentClass.name) continue;
+
+    const parentEntry = classMethodIndex.get(parentClass.name as string);
+    if (parentEntry && parentEntry.methods.has(methodName)) {
+      return parentEntry.methods.get(methodName)!;
+    }
+
+    // Recurse up the chain
+    const found = await findMethodInParentClasses(
+      parentClass, methodName, classMethodIndex, graph, maxDepth - 1, visited
+    );
+    if (found) return found;
+  }
+
+  return null;
+}
+
+/**
+ * Finds the class containing a given method call by traversing CONTAINS edges upward.
+ */
+export async function findContainingClass(
+  methodCall: MethodCallNode,
+  graph: PluginContext['graph']
+): Promise<BaseNodeRecord | null> {
+  const incomingEdges = await graph.getIncomingEdges(methodCall.id, ['CONTAINS']);
+
+  for (const edge of incomingEdges) {
+    const parentNode = await graph.getNode(edge.src);
+    if (!parentNode) continue;
+
+    if (parentNode.type === 'CLASS') {
+      return parentNode;
+    }
+
+    const found = await findContainingClassRecursive(parentNode, graph, new Set());
+    if (found) return found;
+  }
+
+  return null;
+}
+
+/**
+ * Recursively traverses CONTAINS edges upward to find a CLASS ancestor.
+ */
+async function findContainingClassRecursive(
+  node: BaseNodeRecord,
+  graph: PluginContext['graph'],
+  visited: Set<string>
+): Promise<BaseNodeRecord | null> {
+  if (visited.has(node.id.toString())) return null;
+  visited.add(node.id.toString());
+
+  const incomingEdges = await graph.getIncomingEdges(node.id, ['CONTAINS']);
+
+  for (const edge of incomingEdges) {
+    const parentNode = await graph.getNode(edge.src);
+    if (!parentNode) continue;
+
+    if (parentNode.type === 'CLASS') {
+      return parentNode;
+    }
+
+    const found = await findContainingClassRecursive(parentNode, graph, visited);
+    if (found) return found;
+  }
+
+  return null;
+}

package/src/plugins/indexing/IncrementalModuleIndexer.ts

@@ -13,7 +13,7 @@ import type { NodePath } from '@babel/traverse';
 import type { ImportDeclaration, CallExpression, Identifier } from '@babel/types';
 import { Plugin, createSuccessResult, createErrorResult } from '../Plugin.js';
 import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
-import type { NodeRecord } from '@grafema/types';
+import { NodeFactory } from '../../core/NodeFactory.js';
 import { resolveModulePath } from '../../utils/moduleResolution.js';
 
  
@@ -176,15 +176,10 @@ export class IncrementalModuleIndexer extends Plugin {
         const relativePath = context.rootPrefix
           ? `${context.rootPrefix}/${baseRelativePath}`
           : baseRelativePath;
-        const semanticId = `${relativePath}->global->MODULE->module`;
-
-        const moduleNode: NodeRecord = {
-          id: semanticId,
-          type: 'MODULE',
-          name: relativePath,
-          file: file,
-          contentHash: fileHash
-        } as unknown as NodeRecord;
+        const moduleNode = NodeFactory.createModuleWithContext(
+          { file: relativePath, scopePath: [] },
+          { contentHash: fileHash || '' }
+        );
 
         await graph.addNode(moduleNode);
         nodesCreated++;

package/src/plugins/indexing/JSModuleIndexer.ts

@@ -8,6 +8,7 @@ import { join, resolve, dirname, relative, basename } from 'path';
 import { createHash } from 'crypto';
 import { minimatch } from 'minimatch';
 import { Plugin, createErrorResult } from '../Plugin.js';
+import { NodeFactory } from '../../core/NodeFactory.js';
 import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
 // @ts-expect-error - no type declarations for node-source-walk
 import Walker from 'node-source-walk';
@@ -85,7 +86,7 @@ export class JSModuleIndexer extends Plugin {
   constructor() {
     super();
     this.walker = new Walker({
-      plugins: ['jsx', 'typescript']
+      plugins: ['jsx', 'typescript', 'decorators-legacy']
     });
     this.cache = new Map(); // Кеш зависимостей файла
     this.testPatterns = DEFAULT_TEST_PATTERNS;
@@ -282,10 +283,15 @@ export class JSModuleIndexer extends Plugin {
       const entrypoint = service.metadata?.entrypoint || service.path;
 
       // Резолвим entrypoint относительно projectPath
-      const absoluteEntrypoint = entrypoint.startsWith('/')
+      const rawEntrypoint = entrypoint.startsWith('/')
         ? entrypoint
         : join(projectPath, entrypoint);
 
+      // Resolve entrypoint to actual file (handles .js → .ts redirect, REG-427)
+      const absoluteEntrypoint = existsSync(rawEntrypoint)
+        ? rawEntrypoint
+        : (resolveModulePathUtil(rawEntrypoint, { useFilesystem: true }) ?? rawEntrypoint);
+
       logger.info('Building dependency tree', { service: service.name });
 
       // DFS через стек (как в file2host.js)
@@ -321,9 +327,8 @@ export class JSModuleIndexer extends Plugin {
           onProgress({
             phase: 'indexing',
             currentPlugin: 'JSModuleIndexer',
-            message: `${service.name}: indexed ${visited.size} files`,
-            processedFiles: visited.size,
-            currentService: service.name
+            message: `${service.name}: ${visited.size} modules`,
+            currentService: service.name,
           });
           lastProgressReport = visited.size;
         }
@@ -365,19 +370,12 @@ export class JSModuleIndexer extends Plugin {
         const relativePath = context.rootPrefix
           ? `${context.rootPrefix}/${baseRelativePath}`
           : baseRelativePath;
-        const semanticId = `${relativePath}->global->MODULE->module`;
-
-        // Construct MODULE node manually to preserve absolute file path for analyzers
+        // Create MODULE node via NodeFactory for proper branding
         const isTest = this.isTestFile(currentFile);
-        const moduleNode = {
-          id: semanticId,
-          type: 'MODULE' as const,
-          name: relativePath,
-          file: currentFile, // Keep absolute path for file reading in analyzers
-          line: 0,
-          contentHash: fileHash || '',
-          isTest
-        };
+        const moduleNode = NodeFactory.createModuleWithContext(
+          { file: relativePath, scopePath: [] },
+          { contentHash: fileHash || '', isTest }
+        );
         const moduleId = moduleNode.id;
 
         logger.debug('Creating MODULE node', { moduleId: moduleNode.id });
@@ -448,10 +446,8 @@ export class JSModuleIndexer extends Plugin {
         onProgress({
           phase: 'indexing',
           currentPlugin: 'JSModuleIndexer',
-          message: `${service.name}: indexed ${visited.size} files`,
-          totalFiles: visited.size,
-          processedFiles: visited.size,
-          currentService: service.name
+          message: `${service.name}: ${visited.size} modules`,
+          currentService: service.name,
         });
       }
 

package/src/plugins/indexing/RustModuleIndexer.ts

@@ -8,7 +8,7 @@ import { resolve, relative, basename, join } from 'path';
 import { createHash } from 'crypto';
 import { Plugin, createSuccessResult } from '../Plugin.js';
 import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
-import type { NodeRecord } from '@grafema/types';
+import { NodeFactory } from '../../core/NodeFactory.js';
 
 // Test file patterns for Rust
 const RUST_TEST_PATTERNS: RegExp[] = [
@@ -126,18 +126,19 @@ export class RustModuleIndexer extends Plugin {
         const prefixedPath = context.rootPrefix
           ? `${context.rootPrefix}/${baseRelativePath}`
           : baseRelativePath;
-        const nodeId = `RUST_MODULE#${moduleName}#${prefixedPath}`;
-
-        await graph.addNode({
-          id: nodeId,
-          type: 'RUST_MODULE',
-          name: moduleName,
-          file: filePath,
-          contentHash: hash,
-          isLib: basename(filePath) === 'lib.rs',
-          isMod: basename(filePath) === 'mod.rs',
-          isTest: this.isTestFile(filePath)
-        } as unknown as NodeRecord);
+
+        const node = NodeFactory.createRustModule(
+          moduleName,
+          filePath,
+          hash,
+          prefixedPath,
+          {
+            isLib: basename(filePath) === 'lib.rs',
+            isMod: basename(filePath) === 'mod.rs',
+            isTest: this.isTestFile(filePath),
+          }
+        );
+        await graph.addNode(node);
 
         nodesCreated++;
 

package/src/plugins/validation/AwaitInLoopValidator.ts

@@ -0,0 +1,91 @@
+/**
+ * AwaitInLoopValidator — detects sequential await in loops (REG-298)
+ *
+ * Performance issue: sequential `await` in a loop processes items one at a time
+ * when they could often be parallelized with `Promise.all()`.
+ *
+ * Detection: CALL nodes with `isAwaited=true AND isInsideLoop=true`
+ * (forward-registered during AST walk via `controlFlowState.loopDepth`).
+ *
+ * Creates `issue:performance` ISSUE nodes with AFFECTS edges to flagged calls.
+ *
+ * Datalog equivalent:
+ *   await_in_loop(Call) :-
+ *     node(Call, "CALL"),
+ *     attr(Call, "isAwaited", true),
+ *     attr(Call, "isInsideLoop", true).
+ */
+
+import { Plugin, createSuccessResult } from '../Plugin.js';
+import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
+
+interface CallNode {
+  id: string;
+  name?: string;
+  file?: string;
+  line?: number;
+  column?: number;
+  isAwaited?: boolean;
+  isInsideLoop?: boolean;
+}
+
+export class AwaitInLoopValidator extends Plugin {
+  get metadata(): PluginMetadata {
+    return {
+      name: 'AwaitInLoopValidator',
+      phase: 'VALIDATION',
+      dependencies: ['JSASTAnalyzer'],
+      creates: {
+        nodes: ['ISSUE'],
+        edges: ['AFFECTS']
+      }
+    };
+  }
+
+  async execute(context: PluginContext): Promise<PluginResult> {
+    const { graph } = context;
+    const logger = this.log(context);
+
+    logger.info('Starting await-in-loop detection');
+
+    let issueCount = 0;
+
+    for await (const node of graph.queryNodes({ nodeType: 'CALL' })) {
+      const call = node as unknown as CallNode;
+
+      if (call.isAwaited && call.isInsideLoop) {
+        const callName = call.name || 'unknown';
+        const location = `${call.file}:${call.line || '?'}`;
+
+        if (context.reportIssue) {
+          await context.reportIssue({
+            category: 'performance',
+            severity: 'warning',
+            message: `Sequential await in loop at ${location} — consider Promise.all() for parallel execution`,
+            file: call.file || '',
+            line: call.line || 0,
+            column: call.column || 0,
+            targetNodeId: call.id,
+            context: {
+              type: 'AWAIT_IN_LOOP',
+              callName,
+              suggestion: 'Promise.all'
+            }
+          });
+          issueCount++;
+        }
+      }
+    }
+
+    if (issueCount > 0) {
+      logger.info('Sequential await-in-loop issues found', { count: issueCount });
+    } else {
+      logger.info('No await-in-loop issues found');
+    }
+
+    return createSuccessResult(
+      { nodes: issueCount, edges: issueCount },
+      { issueCount }
+    );
+  }
+}