@grafema/core 0.1.0-alpha.5 → 0.1.1-alpha

package/src/Orchestrator.ts

@@ -9,10 +9,15 @@ import { fileURLToPath } from 'url';
 import { spawn, execSync, ChildProcess } from 'child_process';
 import { setTimeout as sleep } from 'timers/promises';
 import { SimpleProjectDiscovery } from './plugins/discovery/SimpleProjectDiscovery.js';
+import { resolveSourceEntrypoint } from './plugins/discovery/resolveSourceEntrypoint.js';
 import { Profiler } from './core/Profiler.js';
 import { AnalysisQueue } from './core/AnalysisQueue.js';
+import { DiagnosticCollector } from './diagnostics/DiagnosticCollector.js';
 import type { Plugin, PluginContext } from './plugins/Plugin.js';
-import type { GraphBackend } from '@grafema/types';
+import type { GraphBackend, PluginPhase, Logger, LogLevel, IssueSpec, ServiceDefinition } from '@grafema/types';
+import { createLogger } from './logging/Logger.js';
+import { NodeFactory } from './core/NodeFactory.js';
+import type { IssueSeverity } from './core/nodes/IssueNode.js';
 
 /**
  * Progress callback info
@@ -50,8 +55,19 @@ export interface OrchestratorOptions {
   onProgress?: ProgressCallback;
   forceAnalysis?: boolean;
   serviceFilter?: string | null;
+  /** Override entrypoint, bypasses auto-detection. Path relative to project root. */
+  entrypoint?: string;
   indexOnly?: boolean;
   parallel?: ParallelConfig | null;
+  /** Logger instance for structured logging. */
+  logger?: Logger;
+  /** Log level for the default logger. Ignored if logger is provided. */
+  logLevel?: LogLevel;
+  /**
+   * Config-provided services (REG-174).
+   * If provided and non-empty, discovery plugins are skipped.
+   */
+  services?: ServiceDefinition[];
 }
 
 /**
@@ -125,12 +141,17 @@ export class Orchestrator {
   private onProgress: ProgressCallback;
   private forceAnalysis: boolean;
   private serviceFilter: string | null;
+  private entrypoint: string | undefined;
   private indexOnly: boolean;
   private profiler: Profiler;
   private parallelConfig: ParallelConfig | null;
   private analysisQueue: AnalysisQueue | null;
   private rfdbServerProcess: ChildProcess | null;
   private _serverWasExternal: boolean;
+  private diagnosticCollector: DiagnosticCollector;
+  private logger: Logger;
+  /** Config-provided services (REG-174) */
+  private configServices: ServiceDefinition[] | undefined;
 
   constructor(options: OrchestratorOptions = {}) {
     this.graph = options.graph!;
@@ -140,6 +161,7 @@ export class Orchestrator {
     this.onProgress = options.onProgress || (() => {}); // Callback для прогресса
     this.forceAnalysis = options.forceAnalysis || false; // Флаг для игнорирования кэша
     this.serviceFilter = options.serviceFilter || null; // Фильтр для одного сервиса
+    this.entrypoint = options.entrypoint; // Override entrypoint, bypasses discovery
     this.indexOnly = options.indexOnly || false; // Только DISCOVERY + INDEXING (для coverage)
     this.profiler = new Profiler('Orchestrator');
 
@@ -149,9 +171,21 @@ export class Orchestrator {
     this.rfdbServerProcess = null;
     this._serverWasExternal = false;
 
-    // Auto-add default discovery if no discovery plugins provided
+    // Initialize diagnostic collector
+    this.diagnosticCollector = new DiagnosticCollector();
+
+    // Initialize logger (use provided or create default)
+    this.logger = options.logger ?? createLogger(options.logLevel ?? 'info');
+
+    // Store config-provided services (REG-174)
+    this.configServices = options.services;
+
+    // Modified auto-add logic: SKIP auto-add if config services provided (REG-174)
     const hasDiscovery = this.plugins.some(p => p.metadata?.phase === 'DISCOVERY');
-    if (!hasDiscovery) {
+    const hasConfigServices = this.configServices && this.configServices.length > 0;
+
+    if (!hasDiscovery && !hasConfigServices) {
+      // Only auto-add if NO discovery plugins AND NO config services
       this.plugins.unshift(new SimpleProjectDiscovery());
     }
   }
@@ -165,11 +199,38 @@ export class Orchestrator {
     // Resolve to absolute path
     const absoluteProjectPath = projectPath.startsWith('/') ? projectPath : resolve(projectPath);
 
+    // RADICAL SIMPLIFICATION: Clear entire graph once at the start if forceAnalysis
+    if (this.forceAnalysis && this.graph.clear) {
+      this.logger.info('Clearing entire graph (forceAnalysis=true)');
+      await this.graph.clear();
+      this.logger.info('Graph cleared successfully');
+    }
+
     this.onProgress({ phase: 'discovery', currentPlugin: 'Starting discovery...', message: 'Discovering services...', totalFiles: 0, processedFiles: 0 });
 
-    // PHASE 0: DISCOVERY - запуск плагинов фазы DISCOVERY
+    // PHASE 0: DISCOVERY - запуск плагинов фазы DISCOVERY (or use entrypoint override)
     this.profiler.start('DISCOVERY');
-    const manifest = await this.discover(absoluteProjectPath);
+    let manifest: DiscoveryManifest;
+    if (this.entrypoint) {
+      // Skip discovery, create synthetic manifest with single service
+      const entrypointPath = this.entrypoint.startsWith('/')
+        ? this.entrypoint
+        : join(absoluteProjectPath, this.entrypoint);
+      const serviceName = this.entrypoint.split('/').pop()?.replace(/\.[^.]+$/, '') || 'main';
+      manifest = {
+        services: [{
+          id: `service:${serviceName}`,
+          name: serviceName,
+          path: entrypointPath,
+          metadata: { entrypoint: entrypointPath }
+        }],
+        entrypoints: [],
+        projectPath: absoluteProjectPath
+      };
+      this.logger.info('Using entrypoint override', { entrypoint: this.entrypoint, resolved: entrypointPath });
+    } else {
+      manifest = await this.discover(absoluteProjectPath);
+    }
     this.profiler.end('DISCOVERY');
 
     const epCount = manifest.entrypoints?.length || 0;
@@ -181,7 +242,7 @@ export class Orchestrator {
       totalFiles: 0,
       processedFiles: 0
     });
-    console.log(`[Orchestrator] Discovery: ${svcCount} services, ${epCount} entrypoints`);
+    this.logger.info('Discovery complete', { services: svcCount, entrypoints: epCount });
 
     // Build unified list of indexing units from services AND entrypoints
     const indexingUnits = this.buildIndexingUnits(manifest);
@@ -195,13 +256,12 @@ export class Orchestrator {
         u.name.includes(this.serviceFilter!) ||
         u.path.includes(this.serviceFilter!)
       );
-      console.log(`[Orchestrator] Filtering: ${this.serviceFilter} (found ${unitsToProcess.length} of ${indexingUnits.length})`);
+      this.logger.info('Filtering services', { filter: this.serviceFilter, found: unitsToProcess.length, total: indexingUnits.length });
     } else {
       unitsToProcess = indexingUnits;
     }
 
-    console.log(`[Orchestrator] Processing ${unitsToProcess.length} indexing units (services + entrypoints)`);
-    console.log(`[Orchestrator] Strategy: Phase-by-phase with DFS dependency tree per entrypoint`);
+    this.logger.info('Processing indexing units', { count: unitsToProcess.length, strategy: 'Phase-by-phase with DFS' });
 
     // PHASE 1: INDEXING - каждый сервис строит своё дерево зависимостей от entrypoint
     const indexingStart = Date.now();
@@ -232,6 +292,7 @@ export class Orchestrator {
       // Параллельно обрабатываем батч units
       await Promise.all(batch.map(async (unit, idx) => {
         const unitStart = Date.now();
+
         const unitManifest: UnitManifest = {
           projectPath: manifest.projectPath,
           service: {
@@ -243,9 +304,13 @@ export class Orchestrator {
           modules: []
         };
 
-        await this.runPhase('INDEXING', { manifest: unitManifest, graph: this.graph, workerCount: 1 });
+        await this.runPhase('INDEXING', {
+          manifest: unitManifest,
+          graph: this.graph,
+          workerCount: 1,
+        });
         const unitTime = ((Date.now() - unitStart) / 1000).toFixed(2);
-        console.log(`[Orchestrator] ⏱️ INDEXING ${unit.name}: ${unitTime}s`);
+        this.logger.debug('INDEXING complete', { unit: unit.name, duration: unitTime });
 
         this.onProgress({
           phase: 'indexing',
@@ -260,13 +325,12 @@ export class Orchestrator {
       processedUnits += batch.length;
     }
     this.profiler.end('INDEXING');
-    console.log(`[Orchestrator] ⏱️ INDEXING phase total: ${((Date.now() - indexingStart) / 1000).toFixed(2)}s`);
+    this.logger.info('INDEXING phase complete', { duration: ((Date.now() - indexingStart) / 1000).toFixed(2) });
 
     // Skip remaining phases if indexOnly mode (for coverage)
     if (this.indexOnly) {
       const totalTime = ((Date.now() - totalStartTime) / 1000).toFixed(2);
-      console.log(`[Orchestrator] ⏱️ indexOnly mode - skipping ANALYSIS/ENRICHMENT/VALIDATION`);
-      console.log(`[Orchestrator] ⏱️ Total time: ${totalTime}s for ${unitsToProcess.length} units`);
+      this.logger.info('indexOnly mode - skipping remaining phases', { duration: totalTime, units: unitsToProcess.length });
       return manifest;
     }
 
@@ -313,9 +377,13 @@ export class Orchestrator {
             modules: []
           };
 
-          await this.runPhase('ANALYSIS', { manifest: unitManifest, graph: this.graph, workerCount: 1 });
+          await this.runPhase('ANALYSIS', {
+          manifest: unitManifest,
+          graph: this.graph,
+          workerCount: 1,
+        });
           const unitTime = ((Date.now() - unitStart) / 1000).toFixed(2);
-          console.log(`[Orchestrator] ⏱️ ANALYSIS ${unit.name}: ${unitTime}s`);
+          this.logger.debug('ANALYSIS complete', { unit: unit.name, duration: unitTime });
 
           this.onProgress({
             phase: 'analysis',
@@ -332,7 +400,7 @@ export class Orchestrator {
     }
 
     this.profiler.end('ANALYSIS');
-    console.log(`[Orchestrator] ⏱️ ANALYSIS phase total: ${((Date.now() - analysisStart) / 1000).toFixed(2)}s`);
+    this.logger.info('ANALYSIS phase complete', { duration: ((Date.now() - analysisStart) / 1000).toFixed(2) });
 
     // PHASE 3: ENRICHMENT - post-processing, граф traversal, вычисления (глобально)
     const enrichmentStart = Date.now();
@@ -340,7 +408,7 @@ export class Orchestrator {
     this.onProgress({ phase: 'enrichment', currentPlugin: 'Starting enrichment...', message: 'Enriching graph data...', totalFiles: 0, processedFiles: 0 });
     await this.runPhase('ENRICHMENT', { manifest, graph: this.graph, workerCount: this.workerCount });
     this.profiler.end('ENRICHMENT');
-    console.log(`[Orchestrator] ⏱️ ENRICHMENT phase: ${((Date.now() - enrichmentStart) / 1000).toFixed(2)}s`);
+    this.logger.info('ENRICHMENT phase complete', { duration: ((Date.now() - enrichmentStart) / 1000).toFixed(2) });
 
     // PHASE 4: VALIDATION - проверка корректности графа (глобально)
     const validationStart = Date.now();
@@ -348,7 +416,7 @@ export class Orchestrator {
     this.onProgress({ phase: 'validation', currentPlugin: 'Starting validation...', message: 'Validating graph structure...', totalFiles: 0, processedFiles: 0 });
     await this.runPhase('VALIDATION', { manifest, graph: this.graph, workerCount: this.workerCount });
     this.profiler.end('VALIDATION');
-    console.log(`[Orchestrator] ⏱️ VALIDATION phase: ${((Date.now() - validationStart) / 1000).toFixed(2)}s`);
+    this.logger.info('VALIDATION phase complete', { duration: ((Date.now() - validationStart) / 1000).toFixed(2) });
 
     // Flush graph to ensure all edges are persisted and queryable
     if (this.graph.flush) {
@@ -356,7 +424,7 @@ export class Orchestrator {
     }
 
     const totalTime = ((Date.now() - totalStartTime) / 1000).toFixed(2);
-    console.log(`[Orchestrator] ⏱️ Total time: ${totalTime}s for ${unitsToProcess.length} units`);
+    this.logger.info('Analysis complete', { duration: totalTime, units: unitsToProcess.length });
 
     // Print profiling summary
     this.profiler.printSummary();
@@ -409,14 +477,86 @@ export class Orchestrator {
   }
 
   /**
-   * PHASE 0: Discovery - запуск плагинов DISCOVERY фазы
+   * PHASE 0: Discovery - запуск плагинов DISCOVERY фазы.
+   * If config services are provided, they take precedence and plugins are skipped.
    */
   async discover(projectPath: string): Promise<DiscoveryManifest> {
+    // REG-174: If config provided services, use them directly instead of running discovery plugins
+    if (this.configServices && this.configServices.length > 0) {
+      this.logger.info('Using config-provided services (skipping discovery plugins)', {
+        serviceCount: this.configServices.length
+      });
+
+      const services: ServiceInfo[] = [];
+      // For each config service:
+      // 1. Resolve path relative to project root (validation ensures paths are relative)
+      // 2. Auto-detect entrypoint from package.json if not specified
+      // 3. Fall back to 'index.js' if detection fails
+      for (const configSvc of this.configServices) {
+        // All paths are relative (absolute paths rejected by ConfigLoader validation)
+        const servicePath = join(projectPath, configSvc.path);
+
+        // Resolve entrypoint
+        let entrypoint: string;
+        if (configSvc.entryPoint) {
+          entrypoint = configSvc.entryPoint;
+        } else {
+          // Auto-detect if not provided
+          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) {
+              this.logger.warn('Failed to read package.json for auto-detection', {
+                service: configSvc.name,
+                path: packageJsonPath,
+                error: (e as Error).message
+              });
+              entrypoint = 'index.js';
+            }
+          } else {
+            entrypoint = 'index.js';
+          }
+        }
+
+        // Create SERVICE node
+        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: [],  // Config services don't provide entrypoints
+        projectPath: projectPath
+      };
+    }
+
+    // ORIGINAL CODE: Run discovery plugins if no config services
     const context = {
       projectPath,
       graph: this.graph,
       config: this.config,
-      phase: 'DISCOVERY'
+      phase: 'DISCOVERY',
+      logger: this.logger,
     };
 
     // Фильтруем плагины для фазы DISCOVERY
@@ -491,9 +631,75 @@ export class Orchestrator {
       const pluginContext: PluginContext = {
         ...context,
         onProgress: this.onProgress as unknown as PluginContext['onProgress'],
-        forceAnalysis: this.forceAnalysis
+        forceAnalysis: this.forceAnalysis,
+        logger: this.logger,
       };
-      await plugin.execute(pluginContext);
+
+      // Add reportIssue for VALIDATION phase
+      if (phaseName === 'VALIDATION') {
+        pluginContext.reportIssue = async (issue: IssueSpec): Promise<string> => {
+          const node = NodeFactory.createIssue(
+            issue.category,
+            issue.severity as IssueSeverity,
+            issue.message,
+            plugin.metadata.name,
+            issue.file,
+            issue.line,
+            issue.column || 0,
+            { context: issue.context }
+          );
+          await context.graph.addNode(node);
+          if (issue.targetNodeId) {
+            await context.graph.addEdge({
+              src: node.id,
+              dst: issue.targetNodeId,
+              type: 'AFFECTS',
+            });
+          }
+          return node.id;
+        };
+      }
+
+      try {
+        const result = await plugin.execute(pluginContext);
+
+        // Collect errors into diagnostics
+        this.diagnosticCollector.addFromPluginResult(
+          phaseName as PluginPhase,
+          plugin.metadata.name,
+          result
+        );
+
+        // Log plugin completion with warning if errors occurred
+        if (!result.success) {
+          console.warn(`[Orchestrator] Plugin ${plugin.metadata.name} reported failure`, {
+            errors: result.errors.length,
+            warnings: result.warnings.length,
+          });
+        }
+
+        // Check for fatal errors - STOP immediately
+        if (this.diagnosticCollector.hasFatal()) {
+          const allDiagnostics = this.diagnosticCollector.getAll();
+          const fatal = allDiagnostics.find(d => d.severity === 'fatal');
+          throw new Error(`Fatal error in ${plugin.metadata.name}: ${fatal?.message || 'Unknown fatal error'}`);
+        }
+      } catch (e) {
+        // Plugin threw an exception (not just returned errors)
+        const error = e instanceof Error ? e : new Error(String(e));
+
+        // Don't re-add if this was already a fatal error we threw
+        if (!this.diagnosticCollector.hasFatal()) {
+          this.diagnosticCollector.add({
+            code: 'ERR_PLUGIN_THREW',
+            severity: 'fatal',
+            message: error.message,
+            phase: phaseName as PluginPhase,
+            plugin: plugin.metadata.name,
+          });
+        }
+        throw error; // Re-throw to stop analysis
+      }
 
       // Send completion for this plugin
       this.onProgress({
@@ -504,6 +710,13 @@ export class Orchestrator {
     }
   }
 
+  /**
+   * Get the diagnostic collector for retrieving all collected diagnostics
+   */
+  getDiagnostics(): DiagnosticCollector {
+    return this.diagnosticCollector;
+  }
+
   /**
    * Run queue-based parallel analysis using worker_threads and RFDB server
    *

package/src/config/ConfigLoader.ts

@@ -0,0 +1,263 @@
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { parse as parseYAML } from 'yaml';
+import type { ServiceDefinition } from '@grafema/types';
+
+/**
+ * Grafema configuration schema.
+ *
+ * YAML Location: .grafema/config.yaml (preferred) or .grafema/config.json (deprecated)
+ *
+ * Example config.yaml:
+ *
+ * ```yaml
+ * # Plugins for each analysis phase
+ * plugins:
+ *   indexing:
+ *     - JSModuleIndexer
+ *   analysis:
+ *     - JSASTAnalyzer
+ *     - ExpressRouteAnalyzer
+ *   enrichment:
+ *     - MethodCallResolver
+ *   validation:
+ *     - EvalBanValidator
+ *
+ * # Optional: Explicit service definitions (bypass auto-discovery)
+ * services:
+ *   - name: "backend"
+ *     path: "apps/backend"        # Relative to project root
+ *     entryPoint: "src/index.ts"  # Optional, auto-detected if omitted
+ *   - name: "frontend"
+ *     path: "apps/frontend"
+ * ```
+ *
+ * If 'services' is not specified or empty, auto-discovery is used (SimpleProjectDiscovery).
+ * If 'services' is specified and non-empty, auto-discovery plugins are skipped entirely.
+ */
+export interface GrafemaConfig {
+  plugins: {
+    discovery?: string[];
+    indexing: string[];
+    analysis: string[];
+    enrichment: string[];
+    validation: string[];
+  };
+  /**
+   * Optional explicit services for manual configuration.
+   * If provided and non-empty, auto-discovery is skipped.
+   */
+  services: ServiceDefinition[];
+}
+
+/**
+ * Default plugin configuration.
+ * Matches current DEFAULT_PLUGINS in analyze.ts and config.ts (MCP).
+ */
+export const DEFAULT_CONFIG: GrafemaConfig = {
+  plugins: {
+    discovery: [],
+    indexing: ['JSModuleIndexer'],
+    analysis: [
+      'JSASTAnalyzer',
+      'ExpressRouteAnalyzer',
+      'SocketIOAnalyzer',
+      'DatabaseAnalyzer',
+      'FetchAnalyzer',
+      'ServiceLayerAnalyzer',
+    ],
+    enrichment: [
+      'MethodCallResolver',
+      'AliasTracker',
+      'ValueDomainAnalyzer',
+      'MountPointResolver',
+      'PrefixEvaluator',
+      'ImportExportLinker',
+      'HTTPConnectionEnricher',
+    ],
+    validation: [
+      'CallResolverValidator',
+      'EvalBanValidator',
+      'SQLInjectionValidator',
+      'ShadowingDetector',
+      'GraphConnectivityValidator',
+      'DataFlowValidator',
+      'TypeScriptDeadCodeValidator',
+    ],
+  },
+  services: [], // Empty by default (uses auto-discovery)
+};
+
+/**
+ * Load Grafema config from project directory.
+ *
+ * Priority:
+ * 1. config.yaml (preferred)
+ * 2. config.json (deprecated, fallback)
+ * 3. DEFAULT_CONFIG (if neither exists)
+ *
+ * Warnings:
+ * - Logs deprecation warning if config.json is used
+ * - Logs parse errors but doesn't throw (returns defaults)
+ *
+ * @param projectPath - Absolute path to project root
+ * @param logger - Optional logger for warnings (defaults to console.warn)
+ * @returns Parsed config or defaults
+ */
+export function loadConfig(
+  projectPath: string,
+  logger: { warn: (msg: string) => void } = console
+): GrafemaConfig {
+  const grafemaDir = join(projectPath, '.grafema');
+  const yamlPath = join(grafemaDir, 'config.yaml');
+  const jsonPath = join(grafemaDir, 'config.json');
+
+  // 1. Try YAML first (preferred)
+  if (existsSync(yamlPath)) {
+    let parsed: Partial<GrafemaConfig>;
+
+    try {
+      const content = readFileSync(yamlPath, 'utf-8');
+      parsed = parseYAML(content) as Partial<GrafemaConfig>;
+
+      // Validate structure - ensure plugins sections are arrays if they exist
+      if (parsed.plugins) {
+        for (const phase of ['discovery', 'indexing', 'analysis', 'enrichment', 'validation'] as const) {
+          const value = parsed.plugins[phase];
+          if (value !== undefined && value !== null && !Array.isArray(value)) {
+            throw new Error(`plugins.${phase} must be an array, got ${typeof value}`);
+          }
+        }
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      logger.warn(`Failed to parse config.yaml: ${error.message}`);
+      logger.warn('Using default configuration');
+      return DEFAULT_CONFIG;
+    }
+
+    // Validate services array if present (THROWS on error per Linus review)
+    // This is OUTSIDE try-catch - config errors MUST throw
+    validateServices(parsed.services, projectPath);
+
+    // Merge with defaults (user config may be partial)
+    return mergeConfig(DEFAULT_CONFIG, parsed);
+  }
+
+  // 2. Fallback to JSON (migration path)
+  if (existsSync(jsonPath)) {
+    logger.warn('⚠ config.json is deprecated. Run "grafema init --force" to migrate to config.yaml');
+
+    let parsed: Partial<GrafemaConfig>;
+
+    try {
+      const content = readFileSync(jsonPath, 'utf-8');
+      parsed = JSON.parse(content) as Partial<GrafemaConfig>;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      logger.warn(`Failed to parse config.json: ${error.message}`);
+      logger.warn('Using default configuration');
+      return DEFAULT_CONFIG;
+    }
+
+    // Validate services array if present (THROWS on error)
+    // This is OUTSIDE try-catch - config errors MUST throw
+    validateServices(parsed.services, projectPath);
+
+    return mergeConfig(DEFAULT_CONFIG, parsed);
+  }
+
+  // 3. No config file - return defaults
+  return DEFAULT_CONFIG;
+}
+
+/**
+ * Validate services array structure.
+ * THROWS on error (fail loudly per Linus review).
+ *
+ * @param services - Parsed services array (may be undefined)
+ * @param projectPath - Project root for path validation
+ */
+function validateServices(services: unknown, projectPath: string): void {
+  // undefined/null is valid (means use defaults)
+  if (services === undefined || services === null) {
+    return;
+  }
+
+  // Must be an array
+  if (!Array.isArray(services)) {
+    throw new Error(`Config error: services must be an array, got ${typeof services}`);
+  }
+
+  // Validate each service
+  for (let i = 0; i < services.length; i++) {
+    const svc = services[i];
+
+    // Must be an object
+    if (typeof svc !== 'object' || svc === null) {
+      throw new Error(`Config error: services[${i}] must be an object`);
+    }
+
+    // Name validation - required, non-empty string
+    if (typeof svc.name !== 'string') {
+      throw new Error(`Config error: services[${i}].name must be a string, got ${typeof svc.name}`);
+    }
+    if (!svc.name.trim()) {
+      throw new Error(`Config error: services[${i}].name cannot be empty or whitespace-only`);
+    }
+
+    // Path validation - required, non-empty string
+    if (typeof svc.path !== 'string') {
+      throw new Error(`Config error: services[${i}].path must be a string, got ${typeof svc.path}`);
+    }
+    if (!svc.path.trim()) {
+      throw new Error(`Config error: services[${i}].path cannot be empty or whitespace-only`);
+    }
+
+    // Path validation - must be relative (reject absolute paths per Linus review)
+    if (svc.path.startsWith('/') || svc.path.startsWith('~')) {
+      throw new Error(`Config error: services[${i}].path must be relative to project root, got "${svc.path}"`);
+    }
+
+    // Path validation - must exist
+    const absolutePath = join(projectPath, svc.path);
+    if (!existsSync(absolutePath)) {
+      throw new Error(`Config error: services[${i}].path "${svc.path}" does not exist`);
+    }
+
+    // Path validation - must be directory
+    if (!statSync(absolutePath).isDirectory()) {
+      throw new Error(`Config error: services[${i}].path "${svc.path}" must be a directory`);
+    }
+
+    // entryPoint validation (optional field) - must be non-empty string if provided
+    if (svc.entryPoint !== undefined) {
+      if (typeof svc.entryPoint !== 'string') {
+        throw new Error(`Config error: services[${i}].entryPoint must be a string, got ${typeof svc.entryPoint}`);
+      }
+      if (!svc.entryPoint.trim()) {
+        throw new Error(`Config error: services[${i}].entryPoint cannot be empty or whitespace-only`);
+      }
+    }
+  }
+}
+
+/**
+ * Merge user config with defaults.
+ * User config takes precedence, but missing sections use defaults.
+ */
+function mergeConfig(
+  defaults: GrafemaConfig,
+  user: Partial<GrafemaConfig>
+): GrafemaConfig {
+  return {
+    plugins: {
+      discovery: user.plugins?.discovery ?? defaults.plugins.discovery,
+      indexing: user.plugins?.indexing ?? defaults.plugins.indexing,
+      analysis: user.plugins?.analysis ?? defaults.plugins.analysis,
+      enrichment: user.plugins?.enrichment ?? defaults.plugins.enrichment,
+      validation: user.plugins?.validation ?? defaults.plugins.validation,
+    },
+    services: user.services ?? defaults.services,
+  };
+}

package/src/config/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Configuration loading utilities
+ */
+export { loadConfig, DEFAULT_CONFIG } from './ConfigLoader.js';
+export type { GrafemaConfig } from './ConfigLoader.js';