@grafema/core 0.2.5-beta → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafema/core",
-  "version": "0.2.5-beta",
+  "version": "0.2.7",
   "description": "Core analysis engine for Grafema code analysis toolkit",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,8 +42,8 @@
     "node-source-walk": "^7.0.1",
     "oxc-parser": "^0.96.0",
     "yaml": "^2.8.2",
-    "@grafema/rfdb-client": "0.2.5-beta",
-    "@grafema/types": "0.2.5-beta"
+    "@grafema/types": "0.2.7",
+    "@grafema/rfdb-client": "0.2.7"
   },
   "optionalDependencies": {
     "@grafema/rfdb": "^0.1.0-alpha.2"

package/src/DiscoveryManager.ts

@@ -0,0 +1,279 @@
+/**
+ * DiscoveryManager — handles service and entrypoint discovery.
+ * Extracted from Orchestrator.ts (REG-462).
+ *
+ * Responsibilities:
+ * - Run discovery plugins to find services/entrypoints
+ * - Handle config-provided services (REG-174)
+ * - Handle entrypoint override (bypass discovery)
+ * - Build unified list of indexing units
+ * - Topological sort of discovery plugins (REG-367)
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { resolveSourceEntrypoint } from './plugins/discovery/resolveSourceEntrypoint.js';
+import type { Plugin, PluginContext } from './plugins/Plugin.js';
+import type { GraphBackend, Logger, ServiceDefinition } from '@grafema/types';
+import { NodeFactory } from './core/NodeFactory.js';
+import { toposort } from './core/toposort.js';
+import type { ProgressCallback } from './PhaseRunner.js';
+import type {
+  OrchestratorOptions,
+  ServiceInfo,
+  EntrypointInfo,
+  DiscoveryManifest,
+  IndexingUnit,
+} from './OrchestratorTypes.js';
+
+export class DiscoveryManager {
+  constructor(
+    private plugins: Plugin[],
+    private graph: GraphBackend,
+    private config: OrchestratorOptions,
+    private logger: Logger,
+    private onProgress: ProgressCallback,
+    private configServices: ServiceDefinition[] | undefined,
+  ) {}
+
+  /**
+   * Run discovery: entrypoint override → config services → plugin discovery.
+   * Returns a DiscoveryManifest with discovered services and entrypoints.
+   */
+  async discover(projectPath: string, entrypoint?: string): Promise<DiscoveryManifest> {
+    if (entrypoint) {
+      return this.discoverFromEntrypoint(projectPath, entrypoint);
+    }
+    return this.discoverFromPluginsOrConfig(projectPath);
+  }
+
+  /**
+   * Discover services in a specific root directory.
+   * Used by multi-root workspace analysis (REG-76).
+   */
+  async discoverInRoot(rootPath: string): Promise<DiscoveryManifest> {
+    return this.discoverFromPluginsOrConfig(rootPath);
+  }
+
+  /**
+   * Build unified list of indexing units from services and entrypoints.
+   * Deduplicates by path (services take priority over entrypoints).
+   */
+  buildIndexingUnits(manifest: DiscoveryManifest): IndexingUnit[] {
+    const units: IndexingUnit[] = [];
+    const seenPaths = new Set<string>();
+
+    // 1. Add services first (they have priority)
+    for (const service of manifest.services || []) {
+      const path = service.path || service.metadata?.entrypoint;
+      if (path && !seenPaths.has(path)) {
+        seenPaths.add(path);
+        units.push({
+          ...service,  // Spread first to allow overrides
+          id: service.id,
+          name: service.name,
+          path: path,
+          type: 'service' as const,
+        });
+      }
+    }
+
+    // 2. Add entrypoints that aren't already covered by services
+    for (const ep of manifest.entrypoints || []) {
+      const path = ep.file;
+      if (path && !seenPaths.has(path)) {
+        seenPaths.add(path);
+        units.push({
+          ...ep,  // Spread first to allow overrides
+          id: ep.id,
+          name: ep.name || ep.file.split('/').pop()!,
+          path: path,
+          type: 'entrypoint' as const,
+          entrypointType: ep.type,
+          trigger: ep.trigger,
+        });
+      }
+    }
+
+    this.logger.debug('Built indexing units', {
+      total: units.length,
+      services: units.filter(u => u.type === 'service').length,
+      entrypoints: units.filter(u => u.type === 'entrypoint').length
+    });
+    return units;
+  }
+
+  /**
+   * Create synthetic manifest from entrypoint override (bypasses discovery).
+   */
+  private discoverFromEntrypoint(projectPath: string, entrypoint: string): DiscoveryManifest {
+    const entrypointPath = entrypoint.startsWith('/')
+      ? entrypoint
+      : join(projectPath, entrypoint);
+    const serviceName = entrypoint.split('/').pop()?.replace(/\.[^.]+$/, '') || 'main';
+    const manifest: DiscoveryManifest = {
+      services: [{
+        id: `service:${serviceName}`,
+        name: serviceName,
+        path: entrypointPath,
+        metadata: { entrypoint: entrypointPath }
+      }],
+      entrypoints: [],
+      projectPath: projectPath
+    };
+    this.logger.info('Using entrypoint override', { entrypoint, resolved: entrypointPath });
+    return manifest;
+  }
+
+  /**
+   * Discovery via config services or plugins.
+   * Config services (REG-174) take precedence if provided.
+   */
+  private async discoverFromPluginsOrConfig(projectPath: string): Promise<DiscoveryManifest> {
+    if (this.configServices && this.configServices.length > 0) {
+      return this.discoverFromConfig(projectPath);
+    }
+    return this.discoverFromPlugins(projectPath);
+  }
+
+  /**
+   * Use config-provided services directly (REG-174).
+   * Creates SERVICE nodes in graph and returns manifest.
+   */
+  private async discoverFromConfig(projectPath: string): Promise<DiscoveryManifest> {
+    this.logger.info('Using config-provided services (skipping discovery plugins)', {
+      serviceCount: this.configServices!.length
+    });
+
+    const services: ServiceInfo[] = [];
+    for (const configSvc of this.configServices!) {
+      const servicePath = join(projectPath, configSvc.path);
+
+      // Resolve entrypoint
+      let entrypoint: string;
+      if (configSvc.entryPoint) {
+        entrypoint = configSvc.entryPoint;
+      } else {
+        const packageJsonPath = join(servicePath, 'package.json');
+        if (existsSync(packageJsonPath)) {
+          try {
+            const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            entrypoint = resolveSourceEntrypoint(servicePath, pkg) ?? pkg.main ?? 'index.js';
+          } catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            this.logger.warn('Failed to read package.json for auto-detection', {
+              service: configSvc.name,
+              path: packageJsonPath,
+              error: message
+            });
+            entrypoint = 'index.js';
+          }
+        } else {
+          entrypoint = 'index.js';
+        }
+      }
+
+      const serviceNode = NodeFactory.createService(configSvc.name, servicePath, {
+        discoveryMethod: 'config',
+        entrypoint: entrypoint,
+      });
+      await this.graph.addNode(serviceNode);
+
+      services.push({
+        id: serviceNode.id,
+        name: configSvc.name,
+        path: servicePath,
+        metadata: {
+          entrypoint: join(servicePath, entrypoint),
+        },
+      });
+
+      this.logger.info('Registered config service', {
+        name: configSvc.name,
+        path: servicePath,
+        entrypoint: entrypoint
+      });
+    }
+
+    return {
+      services,
+      entrypoints: [],
+      projectPath: projectPath
+    };
+  }
+
+  /**
+   * Run discovery plugins (original code path).
+   * Plugins are topologically sorted by dependencies (REG-367).
+   */
+  private async discoverFromPlugins(projectPath: string): Promise<DiscoveryManifest> {
+    const context = {
+      projectPath,
+      graph: this.graph,
+      config: this.config,
+      phase: 'DISCOVERY',
+      logger: this.logger,
+    };
+
+    // Filter plugins for DISCOVERY phase
+    const discoveryPlugins = this.plugins.filter(p => p.metadata.phase === 'DISCOVERY');
+
+    // Topological sort by dependencies (REG-367)
+    const discoveryPluginMap = new Map(discoveryPlugins.map(p => [p.metadata.name, p]));
+    const sortedDiscoveryIds = toposort(
+      discoveryPlugins.map(p => ({
+        id: p.metadata.name,
+        dependencies: p.metadata.dependencies ?? [],
+      }))
+    );
+    discoveryPlugins.length = 0;
+    for (const id of sortedDiscoveryIds) {
+      const plugin = discoveryPluginMap.get(id);
+      if (plugin) discoveryPlugins.push(plugin);
+    }
+
+    const allServices: ServiceInfo[] = [];
+    const allEntrypoints: EntrypointInfo[] = [];
+
+    for (let i = 0; i < discoveryPlugins.length; i++) {
+      const plugin = discoveryPlugins[i];
+
+      this.onProgress({
+        phase: 'discovery',
+        currentPlugin: plugin.metadata.name,
+        message: `Running ${plugin.metadata.name}... (${i + 1}/${discoveryPlugins.length})`
+      });
+
+      const result = await plugin.execute(context as PluginContext);
+
+      if (result.success && result.metadata?.services) {
+        allServices.push(...(result.metadata.services as ServiceInfo[]));
+      }
+
+      if (result.success && result.metadata?.entrypoints) {
+        allEntrypoints.push(...(result.metadata.entrypoints as EntrypointInfo[]));
+      }
+
+      if (result.success && result.created.nodes > 0 &&
+          !result.metadata?.services && !result.metadata?.entrypoints) {
+        this.logger.warn('Discovery plugin created nodes but returned no services/entrypoints in metadata', {
+          plugin: plugin.metadata.name,
+          nodesCreated: result.created.nodes,
+          hint: 'Services must be returned via result.metadata.services for Orchestrator to index them'
+        });
+      }
+
+      this.onProgress({
+        phase: 'discovery',
+        currentPlugin: plugin.metadata.name,
+        message: `✓ ${plugin.metadata.name} complete`
+      });
+    }
+
+    return {
+      services: allServices,
+      entrypoints: allEntrypoints,
+      projectPath: projectPath
+    };
+  }
+}

package/src/GraphInitializer.ts

@@ -0,0 +1,131 @@
+/**
+ * GraphInitializer — sets up the graph structure before analysis.
+ * Extracted from Orchestrator.ts (REG-462).
+ *
+ * Responsibilities:
+ * - Create GRAPH_META node with project metadata
+ * - Register plugin nodes (grafema:plugin) with dependency edges
+ * - Declare metadata fields for RFDB server-side indexing
+ */
+
+import type { Plugin } from './plugins/Plugin.js';
+import type { GraphBackend, Logger, FieldDeclaration, NodeRecord } from '@grafema/types';
+import { NodeFactory } from './core/NodeFactory.js';
+import { brandNodeInternal } from './core/brandNodeInternal.js';
+
+export class GraphInitializer {
+  constructor(
+    private graph: GraphBackend,
+    private plugins: Plugin[],
+    private logger: Logger,
+  ) {}
+
+  /**
+   * Initialize graph: register plugins, declare fields, create meta node.
+   * Called once at the start of analysis (before any phase).
+   */
+  async init(projectPath: string): Promise<void> {
+    await this.registerPluginNodes();
+    await this.declarePluginFields();
+    await this.createGraphMetaNode(projectPath);
+  }
+
+  /**
+   * Create GRAPH_META node with project metadata.
+   * Called once at the start of analysis (single-root or multi-root).
+   */
+  private async createGraphMetaNode(projectPath: string): Promise<void> {
+    await this.graph.addNode(brandNodeInternal({
+      id: '__graph_meta__',
+      type: 'GRAPH_META' as NodeRecord['type'],
+      name: 'graph_metadata',
+      file: '',
+      projectPath: projectPath,
+      analyzedAt: new Date().toISOString()
+    }));
+  }
+
+  /**
+   * Register all loaded plugins as grafema:plugin nodes in the graph.
+   *
+   * Creates a node for each plugin with its metadata (phase, priority,
+   * creates, dependencies). Also creates DEPENDS_ON edges between
+   * plugins that declare dependencies.
+   *
+   * Complexity: O(p) where p = number of plugins (typically 20-35).
+   */
+  private async registerPluginNodes(): Promise<void> {
+    const pluginNodes: Array<{ id: string; name: string; dependencies: string[] }> = [];
+
+    for (const plugin of this.plugins) {
+      const meta = plugin.metadata;
+      if (!meta?.name) continue;
+
+      const sourceFile = (plugin.config?.sourceFile as string) || '';
+      const isBuiltin = !sourceFile;
+
+      const node = NodeFactory.createPlugin(meta.name, meta.phase, {
+        file: sourceFile,
+        builtin: isBuiltin,
+        createsNodes: (meta.creates?.nodes as string[]) ?? [],
+        createsEdges: (meta.creates?.edges as string[]) ?? [],
+        dependencies: meta.dependencies ?? [],
+      });
+
+      await this.graph.addNode(node);
+      pluginNodes.push({
+        id: node.id,
+        name: meta.name,
+        dependencies: meta.dependencies ?? [],
+      });
+    }
+
+    // Create DEPENDS_ON edges between plugins
+    const nameToId = new Map<string, string>();
+    for (const pn of pluginNodes) {
+      nameToId.set(pn.name, pn.id);
+    }
+
+    for (const pn of pluginNodes) {
+      for (const dep of pn.dependencies) {
+        const depId = nameToId.get(dep);
+        if (depId) {
+          await this.graph.addEdge({
+            src: pn.id,
+            dst: depId,
+            type: 'DEPENDS_ON',
+          });
+        }
+      }
+    }
+
+    this.logger.debug('Registered plugin nodes', {
+      count: pluginNodes.length,
+      edges: pluginNodes.reduce((sum, pn) => sum + pn.dependencies.filter(d => nameToId.has(d)).length, 0),
+    });
+  }
+
+  /**
+   * Collect field declarations from all plugins and send to RFDB for indexing.
+   * Deduplicates by field name (last declaration wins if nodeTypes differ).
+   * Called once before analysis to enable server-side metadata indexing.
+   */
+  private async declarePluginFields(): Promise<void> {
+    if (!this.graph.declareFields) return;
+
+    const fieldMap = new Map<string, FieldDeclaration>();
+    for (const plugin of this.plugins) {
+      const fields = plugin.metadata?.fields;
+      if (!fields) continue;
+      for (const field of fields) {
+        fieldMap.set(field.name, field);
+      }
+    }
+
+    if (fieldMap.size === 0) return;
+
+    const fields = [...fieldMap.values()];
+    const count = await this.graph.declareFields(fields);
+    this.logger.debug('Declared metadata fields for indexing', { fields: count });
+  }
+}

package/src/GuaranteeChecker.ts

@@ -0,0 +1,90 @@
+/**
+ * GuaranteeChecker — runs guarantee checks after enrichment, before validation.
+ * Extracted from Orchestrator.ts (REG-462).
+ *
+ * Responsibilities:
+ * - Load and execute guarantees via GuaranteeManager (RFD-18)
+ * - Selective vs full checking based on enrichment delta
+ * - Collect violations into diagnostics
+ * - Coverage monitoring canary
+ */
+
+import type { GraphBackend, Logger } from '@grafema/types';
+import type { DiagnosticCollector } from './diagnostics/DiagnosticCollector.js';
+import type { Profiler } from './core/Profiler.js';
+import type { ProgressCallback } from './PhaseRunner.js';
+
+export class GuaranteeChecker {
+  constructor(
+    private graph: GraphBackend,
+    private diagnosticCollector: DiagnosticCollector,
+    private profiler: Profiler,
+    private onProgress: ProgressCallback,
+    private logger: Logger,
+  ) {}
+
+  /**
+   * Run guarantee checks after enrichment (RFD-18).
+   * Uses selective checking when enrichment produced type changes,
+   * falls back to checkAll when no type info is available.
+   */
+  async check(changedTypes: Set<string>, projectPath: string): Promise<void> {
+    const { GuaranteeManager } = await import('./core/GuaranteeManager.js');
+
+    const manager = new GuaranteeManager(this.graph as any, projectPath);
+    const guarantees = await manager.list();
+
+    if (guarantees.length === 0) {
+      this.logger.debug('No guarantees to check');
+      this.checkCoverageGaps(changedTypes);
+      return;
+    }
+
+    const startTime = Date.now();
+    this.profiler.start('GUARANTEE_CHECK');
+    this.onProgress({ phase: 'guarantee', currentPlugin: 'GuaranteeCheck', message: 'Checking guarantees...' });
+
+    const result = changedTypes.size > 0
+      ? await manager.checkSelective(changedTypes)
+      : await manager.checkAll();
+
+    // Collect violations into diagnostics
+    for (const r of result.results) {
+      if (!r.passed && !r.error) {
+        for (const violation of r.violations) {
+          this.diagnosticCollector.add({
+            code: 'GUARANTEE_VIOLATION',
+            severity: r.severity === 'error' ? 'fatal' : 'warning',
+            message: `Guarantee "${r.name}" violated: ${violation.type} ${violation.name || violation.nodeId}`,
+            phase: 'ENRICHMENT',
+            plugin: 'GuaranteeCheck',
+            file: violation.file,
+            line: violation.line,
+          });
+        }
+      }
+    }
+
+    this.profiler.end('GUARANTEE_CHECK');
+    this.logger.info('GUARANTEE_CHECK complete', {
+      duration: ((Date.now() - startTime) / 1000).toFixed(2),
+      total: result.total,
+      checked: result.results.length,
+      passed: result.passed,
+      failed: result.failed,
+    });
+
+    this.checkCoverageGaps(changedTypes);
+  }
+
+  /**
+   * Coverage monitoring canary (RFD-18).
+   * Logs a warning if enrichment produced no type changes at all,
+   * which may indicate a coverage gap.
+   */
+  private checkCoverageGaps(changedTypes: Set<string>): void {
+    if (changedTypes.size === 0) {
+      this.logger.debug('Coverage canary: enrichment produced no type changes');
+    }
+  }
+}