@grafema/core 0.2.5-beta → 0.2.7

package/src/index.ts

@@ -37,12 +37,17 @@ export type { DiagnosticCategory, DiagnosticCategoryKey, CodeCategoryInfo } from
 export {
   loadConfig,
   DEFAULT_CONFIG,
+  validateVersion,
   validateServices,
   validatePatterns,
   validateWorkspace,
+  validateRouting,
 } from './config/index.js';
 export type { GrafemaConfig } from './config/index.js';
 
+// Version
+export { GRAFEMA_VERSION, getSchemaVersion } from './version.js';
+
 // Instructions (for AI agents)
 export { getOnboardingInstruction } from './instructions/index.js';
 
@@ -60,8 +65,9 @@ export type {
 } from './Orchestrator.js';
 
 // Plugin base
-export { Plugin } from './plugins/Plugin.js';
-export type { PluginContext } from './plugins/Plugin.js';
+export { Plugin, createSuccessResult, createErrorResult } from './plugins/Plugin.js';
+export type { PluginContext, PluginMetadata, PluginResult } from './plugins/Plugin.js';
+export { InfraAnalyzer } from './plugins/InfraAnalyzer.js';
 
 // Graph backend
 export { GraphBackend, typeToKind, edgeTypeToNumber } from './core/GraphBackend.js';
@@ -77,14 +83,19 @@ export { Profiler } from './core/Profiler.js';
 export {
   computeSemanticId,
   parseSemanticId,
-  computeDiscriminator
+  computeDiscriminator,
+  computeSemanticIdV2,
+  parseSemanticIdV2,
+  computeContentHash
 } from './core/SemanticId.js';
 export type {
   Location,
   ScopeContext,
   SemanticIdOptions,
   ParsedSemanticId,
-  LocatedItem
+  LocatedItem,
+  ParsedSemanticIdV2,
+  ContentHashHints
 } from './core/SemanticId.js';
 export { ScopeTracker } from './core/ScopeTracker.js';
 export type { ScopeEntry, CountedScopeResult } from './core/ScopeTracker.js';
@@ -94,15 +105,30 @@ export { GuaranteeManager } from './core/GuaranteeManager.js';
 export type { GuaranteeGraph } from './core/GuaranteeManager.js';
 export { toposort, CycleError } from './core/toposort.js';
 export type { ToposortItem } from './core/toposort.js';
+export { buildDependencyGraph } from './core/buildDependencyGraph.js';
+export type { EnricherDependencyInfo } from './core/buildDependencyGraph.js';
 export { clearFileNodesIfNeeded, clearServiceNodeIfExists } from './core/FileNodeManager.js';
 export { CoverageAnalyzer } from './core/CoverageAnalyzer.js';
 export type { CoverageResult } from './core/CoverageAnalyzer.js';
 export { FileExplainer } from './core/FileExplainer.js';
 export type { FileExplainResult, EnhancedNode } from './core/FileExplainer.js';
+export { FileOverview } from './core/FileOverview.js';
+export type {
+  FileOverviewResult,
+  ImportInfo,
+  ExportInfo,
+  FunctionOverview,
+  ClassOverview,
+  VariableOverview,
+} from './core/FileOverview.js';
 
 // Hash utilities
 export { calculateFileHash, calculateFileHashAsync, calculateContentHash } from './core/HashUtils.js';
 
+// RFDB binary finder utilities (REG-410)
+export { findRfdbBinary, getBinaryNotFoundMessage, getPlatformDir } from './utils/findRfdbBinary.js';
+export type { FindBinaryOptions } from './utils/findRfdbBinary.js';
+
 // Module resolution utilities (REG-320)
 export {
   resolveModulePath,
@@ -113,6 +139,9 @@ export {
 } from './utils/moduleResolution.js';
 export type { ModuleResolutionOptions } from './utils/moduleResolution.js';
 
+// Node file path resolution (REG-408)
+export { resolveNodeFile } from './utils/resolveNodeFile.js';
+
 // Type validation and path validation
 export {
   levenshtein,
@@ -168,14 +197,20 @@ export { MethodNode } from './core/nodes/MethodNode.js';
 export { ExportNode } from './core/nodes/ExportNode.js';
 export { VariableDeclarationNode } from './core/nodes/VariableDeclarationNode.js';
 export { ExternalModuleNode } from './core/nodes/ExternalModuleNode.js';
+export { ExternalFunctionNode, type ExternalFunctionNodeRecord, type ExternalFunctionOptions } from './core/nodes/ExternalFunctionNode.js';
 export { NetworkRequestNode } from './core/nodes/NetworkRequestNode.js';
 export { InterfaceNode, type InterfacePropertyRecord } from './core/nodes/InterfaceNode.js';
 export { TypeNode } from './core/nodes/TypeNode.js';
+export { TypeParameterNode, type TypeParameterNodeRecord, type TypeParameterNodeOptions } from './core/nodes/TypeParameterNode.js';
 export { EnumNode, type EnumMemberRecord } from './core/nodes/EnumNode.js';
 export { DecoratorNode, type DecoratorTargetType } from './core/nodes/DecoratorNode.js';
 export { ExpressionNode, type ExpressionNodeOptions } from './core/nodes/ExpressionNode.js';
 export { ArgumentExpressionNode, type ArgumentExpressionNodeRecord, type ArgumentExpressionNodeOptions } from './core/nodes/ArgumentExpressionNode.js';
 
+// AST CollisionResolver (v2 semantic ID disambiguation)
+export { CollisionResolver } from './plugins/analysis/ast/CollisionResolver.js';
+export type { PendingNode } from './plugins/analysis/ast/CollisionResolver.js';
+
 // AST Visitors (for advanced usage)
 export {
   ASTVisitor,
@@ -218,10 +253,12 @@ export { RustModuleIndexer } from './plugins/indexing/RustModuleIndexer.js';
 export { JSASTAnalyzer } from './plugins/analysis/JSASTAnalyzer.js';
 export { ExpressRouteAnalyzer } from './plugins/analysis/ExpressRouteAnalyzer.js';
 export { ExpressResponseAnalyzer } from './plugins/analysis/ExpressResponseAnalyzer.js';
+export { NestJSRouteAnalyzer } from './plugins/analysis/NestJSRouteAnalyzer.js';
 export { ExpressAnalyzer } from './plugins/analysis/ExpressAnalyzer.js';
 export { SocketIOAnalyzer } from './plugins/analysis/SocketIOAnalyzer.js';
 export { DatabaseAnalyzer } from './plugins/analysis/DatabaseAnalyzer.js';
 export { FetchAnalyzer } from './plugins/analysis/FetchAnalyzer.js';
+export { SocketAnalyzer } from './plugins/analysis/SocketAnalyzer.js';
 export { ServiceLayerAnalyzer } from './plugins/analysis/ServiceLayerAnalyzer.js';
 export { ReactAnalyzer } from './plugins/analysis/ReactAnalyzer.js';
 export { RustAnalyzer } from './plugins/analysis/RustAnalyzer.js';
@@ -239,6 +276,7 @@ export { MountPointResolver } from './plugins/enrichment/MountPointResolver.js';
 export { PrefixEvaluator } from './plugins/enrichment/PrefixEvaluator.js';
 export { InstanceOfResolver } from './plugins/enrichment/InstanceOfResolver.js';
 export { HTTPConnectionEnricher } from './plugins/enrichment/HTTPConnectionEnricher.js';
+export { SocketConnectionEnricher } from './plugins/enrichment/SocketConnectionEnricher.js';
 export { ImportExportLinker } from './plugins/enrichment/ImportExportLinker.js';
 export { FunctionCallResolver } from './plugins/enrichment/FunctionCallResolver.js';
 export { RustFFIEnricher } from './plugins/enrichment/RustFFIEnricher.js';
@@ -247,6 +285,14 @@ export { ExternalCallResolver } from './plugins/enrichment/ExternalCallResolver.
 export { ClosureCaptureEnricher } from './plugins/enrichment/ClosureCaptureEnricher.js';
 export { ExpressHandlerLinker } from './plugins/enrichment/ExpressHandlerLinker.js';
 export { RejectionPropagationEnricher } from './plugins/enrichment/RejectionPropagationEnricher.js';
+export { CallbackCallResolver } from './plugins/enrichment/CallbackCallResolver.js';
+export { ConfigRoutingMapBuilder } from './plugins/enrichment/ConfigRoutingMapBuilder.js';
+export { ServiceConnectionEnricher } from './plugins/enrichment/ServiceConnectionEnricher.js';
+
+// Resource system (REG-256)
+export { ResourceRegistryImpl } from './core/ResourceRegistry.js';
+export { RoutingMapImpl, createRoutingMap } from './resources/RoutingMapImpl.js';
+export { InfraResourceMapImpl, createInfraResourceMap } from './resources/InfraResourceMapImpl.js';
 
 // Builtin registry
 export { BuiltinRegistry } from './data/builtins/index.js';
@@ -259,11 +305,15 @@ export { GlobalsRegistry, ALL_GLOBALS } from './data/globals/index.js';
 export { CallResolverValidator } from './plugins/validation/CallResolverValidator.js';
 export { EvalBanValidator } from './plugins/validation/EvalBanValidator.js';
 export { SQLInjectionValidator } from './plugins/validation/SQLInjectionValidator.js';
+export { AwaitInLoopValidator } from './plugins/validation/AwaitInLoopValidator.js';
 export { ShadowingDetector } from './plugins/validation/ShadowingDetector.js';
 export { GraphConnectivityValidator } from './plugins/validation/GraphConnectivityValidator.js';
 export { DataFlowValidator } from './plugins/validation/DataFlowValidator.js';
 export { TypeScriptDeadCodeValidator } from './plugins/validation/TypeScriptDeadCodeValidator.js';
 export { BrokenImportValidator } from './plugins/validation/BrokenImportValidator.js';
+export { UnconnectedRouteValidator } from './plugins/validation/UnconnectedRouteValidator.js';
+export { PackageCoverageValidator, COVERED_PACKAGES_RESOURCE_ID, createCoveredPackagesResource } from './plugins/validation/PackageCoverageValidator.js';
+export type { CoveredPackagesResource } from './plugins/validation/PackageCoverageValidator.js';
 
 // Discovery plugins
 export { SimpleProjectDiscovery } from './plugins/discovery/SimpleProjectDiscovery.js';
@@ -314,6 +364,7 @@ export type {
 
 // Graph Query Utilities
 export { findCallsInFunction, findContainingFunction, traceValues, aggregateValues, NONDETERMINISTIC_PATTERNS, NONDETERMINISTIC_OBJECTS } from './queries/index.js';
+export { buildNodeContext, getNodeDisplayName, formatEdgeMetadata, STRUCTURAL_EDGE_TYPES } from './queries/index.js';
 export type {
   CallInfo,
   CallerInfo,
@@ -325,6 +376,11 @@ export type {
   ValueSetResult,
   TraceValuesGraphBackend,
   NondeterministicPattern,
+  EdgeWithNode,
+  EdgeGroup,
+  SourcePreview,
+  NodeContext,
+  BuildNodeContextOptions,
 } from './queries/index.js';
 
 // Re-export types for convenience

package/src/plugins/InfraAnalyzer.ts

@@ -0,0 +1,208 @@
+import { readFileSync } from 'fs';
+import { Plugin } from './Plugin.js';
+import type { PluginContext, PluginResult, PluginMetadata } from './Plugin.js';
+import { createSuccessResult, createErrorResult } from './Plugin.js';
+import type { InfraResource, ResourceMapping, InfraResourceMap } from '@grafema/types';
+import { INFRA_RESOURCE_MAP_ID } from '@grafema/types';
+import { createInfraResourceMap } from '../resources/InfraResourceMapImpl.js';
+
+/**
+ * InfraAnalyzer — Base class for infrastructure analysis plugins.
+ *
+ * AGENT DOCUMENTATION:
+ *
+ * Extend this class to analyze infrastructure-as-code files:
+ * - Kubernetes YAML manifests
+ * - Terraform .tf files
+ * - Docker Compose files
+ * - Helm charts
+ * - Cloud resource configs (CloudFormation, ARM, Bicep)
+ * - Observability configs (Prometheus, Grafana)
+ *
+ * THREE-LAYER PATTERN:
+ *
+ * 1. Your analyzer creates CONCRETE nodes (infra:k8s:deployment:api)
+ * 2. mapToAbstract() maps concrete -> abstract (compute:service:api)
+ * 3. Enrichers (Phase 2) create abstract nodes + cross-layer edges
+ *
+ * LIFECYCLE:
+ *
+ * 1. discoverFiles(context)  — find infrastructure files
+ * 2. parseFile(filePath, content) — extract InfraResource[] (pure, no side effects)
+ * 3. execute() creates concrete graph nodes from resources
+ * 4. mapToAbstract(resource) — map each resource to abstract type
+ * 5. Mappings registered in InfraResourceMap for enrichers
+ *
+ * EXAMPLE:
+ *
+ * ```typescript
+ * class K8sYamlAnalyzer extends InfraAnalyzer {
+ *   declareNodeTypes() { return ['infra:k8s:deployment', 'infra:k8s:service']; }
+ *   declareEdgeTypes() { return []; }  // Enrichers create cross-layer edges
+ *
+ *   async discoverFiles(context) {
+ *     const config = context.config?.infrastructure?.kubernetes;
+ *     if (!config?.enabled) return [];
+ *     return glob(config.paths, { cwd: context.projectPath });
+ *   }
+ *
+ *   parseFile(filePath, content) {
+ *     return YAML.parseAllDocuments(content).map(doc => ({
+ *       id: `infra:k8s:${doc.kind.toLowerCase()}:${doc.metadata.name}`,
+ *       type: `infra:k8s:${doc.kind.toLowerCase()}`,
+ *       name: doc.metadata.name,
+ *       file: filePath,
+ *       tool: 'kubernetes',
+ *       env: doc.metadata.labels?.env,
+ *       metadata: { namespace: doc.metadata.namespace },
+ *     }));
+ *   }
+ *
+ *   mapToAbstract(resource) {
+ *     const KIND_MAP = {
+ *       'infra:k8s:deployment': 'compute:service',
+ *       'infra:k8s:cronjob': 'compute:job',
+ *       'infra:k8s:service': 'networking:service',
+ *       'infra:k8s:ingress': 'networking:ingress',
+ *       'infra:k8s:configmap': 'config:map',
+ *       'infra:k8s:secret': 'config:secret',
+ *     };
+ *     const abstractType = KIND_MAP[resource.type];
+ *     if (!abstractType) return null;
+ *     return {
+ *       concreteId: resource.id,
+ *       concreteType: resource.type,
+ *       abstractType,
+ *       abstractId: `${abstractType}:${resource.name}`,
+ *       name: resource.name,
+ *       metadata: resource.metadata ?? {},
+ *       env: resource.env,
+ *       sourceFile: resource.file,
+ *       sourceTool: resource.tool,
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export abstract class InfraAnalyzer extends Plugin {
+  /**
+   * Plugin metadata — auto-generated from declare*() methods.
+   * Override if you need custom dependencies.
+   */
+  get metadata(): PluginMetadata {
+    return {
+      name: this.constructor.name,
+      phase: 'ANALYSIS',
+      creates: {
+        nodes: this.declareNodeTypes(),
+        edges: this.declareEdgeTypes(),
+      },
+    };
+  }
+
+  /** Declare concrete node types this analyzer creates. */
+  abstract declareNodeTypes(): string[];
+
+  /** Declare edge types this analyzer creates (usually empty — enrichers create edges). */
+  abstract declareEdgeTypes(): string[];
+
+  /** Find infrastructure files to analyze. */
+  abstract discoverFiles(context: PluginContext): Promise<string[]>;
+
+  /**
+   * Parse a single file into concrete resources.
+   * Pure function — no side effects, no graph operations.
+   */
+  abstract parseFile(filePath: string, content: string): InfraResource[];
+
+  /**
+   * Map concrete resource to abstract type.
+   * Returns null if resource type has no abstract mapping.
+   */
+  abstract mapToAbstract(resource: InfraResource): ResourceMapping | null;
+
+  /**
+   * Execute infrastructure analysis.
+   * Orchestrates: discover -> parse -> create nodes -> register mappings.
+   */
+  async execute(context: PluginContext): Promise<PluginResult> {
+    const logger = this.log(context);
+
+    try {
+      const { graph } = context;
+
+      // Step 1: Discover files
+      const files = await this.discoverFiles(context);
+      logger.info(`Discovered ${files.length} infrastructure files`);
+
+      if (files.length === 0) {
+        return createSuccessResult();
+      }
+
+      // Get or create InfraResourceMap
+      const infraMap = context.resources?.getOrCreate<InfraResourceMap>(
+        INFRA_RESOURCE_MAP_ID,
+        createInfraResourceMap,
+      );
+
+      let nodesCreated = 0;
+      let mappingsRegistered = 0;
+      const errors: Error[] = [];
+
+      // Step 2: Process each file
+      for (const filePath of files) {
+        try {
+          const content = readFileSync(filePath, 'utf-8');
+          const resources = this.parseFile(filePath, content);
+
+          // Step 3: Create concrete graph nodes
+          for (const resource of resources) {
+            try {
+              await graph.addNode({
+                id: resource.id,
+                type: resource.type,
+                name: resource.name,
+                file: resource.file,
+                line: resource.line,
+                metadata: {
+                  ...resource.metadata,
+                  env: resource.env,
+                  tool: resource.tool,
+                },
+              } as any); // Concrete infra nodes don't have branded types yet
+              nodesCreated++;
+
+              // Step 4: Register abstract mapping
+              if (infraMap) {
+                const mapping = this.mapToAbstract(resource);
+                if (mapping) {
+                  infraMap.register(mapping);
+                  mappingsRegistered++;
+                }
+              }
+            } catch (error) {
+              const err = error instanceof Error ? error : new Error(String(error));
+              logger.warn(`Failed to process resource ${resource.id}: ${err.message}`);
+              errors.push(err);
+            }
+          }
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          logger.warn(`Failed to process file ${filePath}: ${err.message}`);
+          errors.push(err);
+        }
+      }
+
+      logger.info(`Analysis complete: ${nodesCreated} nodes, ${mappingsRegistered} mappings`);
+
+      return createSuccessResult(
+        { nodes: nodesCreated, edges: 0 },
+        { filesProcessed: files.length, mappingsRegistered },
+        errors,
+      );
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      return createErrorResult(err);
+    }
+  }
+}

package/src/plugins/analysis/DatabaseAnalyzer.ts

@@ -11,9 +11,11 @@ import type { CallExpression, Identifier } from '@babel/types';
 import type { NodePath } from '@babel/traverse';
 import { Plugin, createSuccessResult, createErrorResult } from '../Plugin.js';
 import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
-import type { NodeRecord } from '@grafema/types';
+import type { NodeRecord, AnyBrandedNode } from '@grafema/types';
 import { getLine, getColumn } from './ast/utils/location.js';
 import { getTraverseFunction } from './ast/utils/babelTraverse.js';
+import { resolveNodeFile } from '../../utils/resolveNodeFile.js';
+import { NodeFactory } from '../../core/NodeFactory.js';
 
 const traverse = getTraverseFunction(traverseModule);
 
@@ -61,6 +63,7 @@ export class DatabaseAnalyzer extends Plugin {
 
     try {
       const { graph } = context;
+      const projectPath = (context.manifest as { projectPath?: string })?.projectPath ?? '';
 
       // Получаем все MODULE ноды
       const modules = await this.getModules(graph);
@@ -77,7 +80,7 @@ export class DatabaseAnalyzer extends Plugin {
       // Анализируем каждый модуль
       for (let i = 0; i < modules.length; i++) {
         const module = modules[i];
-        const result = await this.analyzeModule(module, functions, graph);
+        const result = await this.analyzeModule(module, functions, graph, projectPath);
         queriesCreated += result.queries;
         tablesCreated += result.tables;
         edgesCreated += result.edges;
@@ -131,7 +134,8 @@ export class DatabaseAnalyzer extends Plugin {
   private async analyzeModule(
     module: NodeRecord,
     functions: NodeRecord[],
-    graph: PluginContext['graph']
+    graph: PluginContext['graph'],
+    projectPath: string
   ): Promise<AnalysisResult> {
     let queriesCreated = 0;
     let tablesCreated = 0;
@@ -139,7 +143,7 @@ export class DatabaseAnalyzer extends Plugin {
 
     try {
       // Читаем и парсим файл
-      const code = readFileSync(module.file!, 'utf-8');
+      const code = readFileSync(resolveNodeFile(module.file!, projectPath), 'utf-8');
       const ast = parse(code, {
         sourceType: 'module',
         plugins: ['jsx'] as ParserPlugin[]
@@ -238,21 +242,31 @@ export class DatabaseAnalyzer extends Plugin {
       // Collect all nodes and edges for batch operations
       if (databaseQueries.length > 0) {
         const databaseId = 'EXTERNAL_DATABASE:__database__';
-        const nodes: NodeRecord[] = [];
+        const nodes: AnyBrandedNode[] = [];
         const edges: Array<{ type: string; src: string; dst: string }> = [];
 
         const existingDb = await graph.getNode(databaseId);
         if (!existingDb) {
-          nodes.push({
-            id: databaseId,
-            type: 'db:connection',
-            name: '__database__'
-          } as NodeRecord);
+          nodes.push(NodeFactory.createDbConnection('__database__'));
         }
 
         // Prepare DATABASE_QUERY and TABLE nodes
-        for (const query of databaseQueries) {
-          nodes.push(query as unknown as NodeRecord);
+        for (let qi = 0; qi < databaseQueries.length; qi++) {
+          const query = databaseQueries[qi];
+          nodes.push(NodeFactory.createDbQuery(
+            query.file,
+            qi,
+            query.sql,
+            query.operation,
+            {
+              sqlSnippet: query.sqlSnippet,
+              tableName: query.tableName,
+              object: query.object,
+              method: query.method,
+              line: query.line,
+              column: query.column,
+            }
+          ));
           queriesCreated++;
 
           // Prepare TABLE node if has tableName
@@ -260,11 +274,7 @@ export class DatabaseAnalyzer extends Plugin {
             const tableId = `TABLE:${query.tableName}`;
 
             if (!createdTables.has(tableId)) {
-              nodes.push({
-                id: tableId,
-                type: 'db:table',
-                name: query.tableName
-              } as NodeRecord);
+              nodes.push(NodeFactory.createDbTable(query.tableName));
               tablesCreated++;
               createdTables.add(tableId);
             }