@grafema/cli 0.2.4-beta → 0.2.6-beta

package/src/commands/analyzeAction.ts

@@ -0,0 +1,284 @@
+/**
+ * Analyze command action — connects to RFDB, loads plugins, runs Orchestrator.
+ *
+ * Extracted from analyze.ts (REG-435) to keep command definition separate
+ * from execution logic.
+ */
+
+import { resolve, join } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+import {
+  Orchestrator,
+  RFDBServerBackend,
+  DiagnosticReporter,
+  DiagnosticWriter,
+  createLogger,
+  loadConfig,
+  StrictModeFailure,
+} from '@grafema/core';
+import type { LogLevel, GraphBackend } from '@grafema/types';
+import { ProgressRenderer } from '../utils/progressRenderer.js';
+import { loadCustomPlugins, createPlugins } from '../plugins/pluginLoader.js';
+
+export interface NodeEdgeCountBackend {
+  nodeCount: () => Promise<number>;
+  edgeCount: () => Promise<number>;
+}
+
+export async function fetchNodeEdgeCounts(backend: NodeEdgeCountBackend): Promise<{ nodeCount: number; edgeCount: number }> {
+  const [nodeCount, edgeCount] = await Promise.all([backend.nodeCount(), backend.edgeCount()]);
+  return { nodeCount, edgeCount };
+}
+
+export function exitWithCode(code: number, exitFn: (code: number) => void = process.exit): void {
+  exitFn(code);
+}
+
+/**
+ * Determine log level from CLI options.
+ * Priority: --log-level > --quiet > --verbose > default ('silent')
+ *
+ * By default, logs are silent to allow clean progress UI.
+ * Use --verbose to see detailed logs (disables interactive progress).
+ */
+function getLogLevel(options: { quiet?: boolean; verbose?: boolean; logLevel?: string }): LogLevel {
+  if (options.logLevel) {
+    const validLevels: LogLevel[] = ['silent', 'errors', 'warnings', 'info', 'debug'];
+    if (validLevels.includes(options.logLevel as LogLevel)) {
+      return options.logLevel as LogLevel;
+    }
+  }
+  if (options.quiet) return 'silent';
+  if (options.verbose) return 'info';  // --verbose shows logs instead of progress UI
+  return 'silent';  // Default: silent logs, clean progress UI
+}
+
+export async function analyzeAction(path: string, options: { service?: string; entrypoint?: string; clear?: boolean; quiet?: boolean; verbose?: boolean; debug?: boolean; logLevel?: string; logFile?: string; strict?: boolean; autoStart?: boolean }): Promise<void> {
+  const projectPath = resolve(path);
+  const grafemaDir = join(projectPath, '.grafema');
+  const dbPath = join(grafemaDir, 'graph.rfdb');
+
+  if (!existsSync(grafemaDir)) {
+    mkdirSync(grafemaDir, { recursive: true });
+  }
+
+  // Two log levels for CLI output:
+  // - info: important results (shows unless --quiet)
+  // - debug: verbose details (shows only with --verbose)
+  const info = options.quiet ? () => {} : console.log;
+  const debug = options.verbose ? console.log : () => {};
+
+  // Create logger based on CLI flags
+  const logLevel = getLogLevel(options);
+  const logFile = options.logFile ? resolve(options.logFile) : undefined;
+  const logger = createLogger(logLevel, logFile ? { logFile } : undefined);
+
+  if (logFile) {
+    debug(`Log file: ${logFile}`);
+  }
+  debug(`Analyzing project: ${projectPath}`);
+
+  // Connect to RFDB server
+  // Default: require explicit `grafema server start`
+  // Use --auto-start for CI or backwards compatibility
+  // In normal mode (not verbose), suppress backend logs for clean progress UI
+  const backend = new RFDBServerBackend({
+    dbPath,
+    autoStart: options.autoStart ?? false,
+    silent: !options.verbose  // Silent in normal mode (show progress), verbose shows logs
+  });
+
+  try {
+    await backend.connect();
+  } catch (err) {
+    if (!options.autoStart && err instanceof Error && err.message.includes('not running')) {
+      console.error('');
+      console.error('RFDB server is not running.');
+      console.error('');
+      console.error('Start the server first:');
+      console.error('  grafema server start');
+      console.error('');
+      console.error('Or use --auto-start flag:');
+      console.error('  grafema analyze --auto-start');
+      console.error('');
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  if (options.clear) {
+    debug('Clearing existing database...');
+    await backend.clear();
+  }
+
+  const config = loadConfig(projectPath, logger);
+
+  // Extract services from config (REG-174)
+  if (config.services.length > 0) {
+    debug(`Loaded ${config.services.length} service(s) from config`);
+    for (const svc of config.services) {
+      const entry = svc.entryPoint ? ` (entry: ${svc.entryPoint})` : '';
+      debug(`  - ${svc.name}: ${svc.path}${entry}`);
+    }
+  }
+
+  // Load custom plugins from .grafema/plugins/
+  const customPlugins = await loadCustomPlugins(projectPath, debug);
+  const plugins = createPlugins(config.plugins, customPlugins, options.verbose);
+
+  debug(`Loaded ${plugins.length} plugins`);
+
+  // Resolve strict mode: CLI flag overrides config
+  const strictMode = options.strict ?? config.strict ?? false;
+  if (strictMode) {
+    debug('Strict mode enabled - analysis will fail on unresolved references');
+  }
+
+  const startTime = Date.now();
+
+  // Create progress renderer for CLI output
+  // In quiet mode, use a no-op renderer (skip rendering)
+  // In verbose mode, use non-interactive (newlines per update)
+  // In normal mode, use interactive (spinner with line overwrite)
+  const renderer = options.quiet
+    ? null
+    : new ProgressRenderer({
+        isInteractive: !options.verbose && process.stdout.isTTY,
+      });
+
+  // Poll graph stats periodically to show node/edge counts in progress
+  let statsInterval: NodeJS.Timeout | null = null;
+  if (renderer && !options.quiet) {
+    statsInterval = setInterval(async () => {
+      try {
+        const stats = await fetchNodeEdgeCounts(backend);
+        renderer.setStats(stats.nodeCount, stats.edgeCount);
+      } catch {
+        // Ignore stats errors during analysis
+      }
+    }, 500); // Poll every 500ms
+    statsInterval.unref?.();
+  }
+
+  const orchestrator = new Orchestrator({
+    graph: backend as unknown as GraphBackend,
+    plugins,
+    serviceFilter: options.service || null,
+    entrypoint: options.entrypoint,
+    forceAnalysis: options.clear || false,
+    logger,
+    services: config.services.length > 0 ? config.services : undefined,  // Pass config services (REG-174)
+    strictMode, // REG-330: Pass strict mode flag
+    onProgress: (progress) => {
+      renderer?.update(progress);
+    },
+  });
+
+  let exitCode = 0;
+
+  try {
+    await orchestrator.run(projectPath);
+    await backend.flush();
+
+    const elapsedSeconds = (Date.now() - startTime) / 1000;
+    const stats = await fetchNodeEdgeCounts(backend);
+
+    // Clear progress line in interactive mode, then show results
+    if (renderer && process.stdout.isTTY) {
+      process.stdout.write('\r\x1b[K'); // Clear line
+    }
+    info('');
+    info(renderer ? renderer.finish(elapsedSeconds) : `Analysis complete in ${elapsedSeconds.toFixed(2)}s`);
+    info(`  Nodes: ${stats.nodeCount}`);
+    info(`  Edges: ${stats.edgeCount}`);
+
+    // Get diagnostics and report summary
+    const diagnostics = orchestrator.getDiagnostics();
+    const reporter = new DiagnosticReporter(diagnostics);
+
+    // Print summary if there are any issues
+    if (diagnostics.count() > 0) {
+      info('');
+      info(reporter.categorizedSummary());
+
+      // In verbose mode, print full report
+      if (options.verbose) {
+        debug('');
+        debug(reporter.report({ format: 'text', includeSummary: false }));
+      }
+    }
+
+    // Always write diagnostics.log (required for `grafema check` command)
+    const writer = new DiagnosticWriter();
+    await writer.write(diagnostics, grafemaDir);
+    if (options.debug) {
+      debug(`Diagnostics written to ${writer.getLogPath(grafemaDir)}`);
+    }
+
+    // Determine exit code based on severity
+    if (diagnostics.hasFatal()) {
+      exitCode = 1;
+    } else if (diagnostics.hasErrors()) {
+      exitCode = 2; // Completed with errors
+    } else {
+      exitCode = 0; // Success (maybe warnings)
+    }
+  } catch (e) {
+    const diagnostics = orchestrator.getDiagnostics();
+    const reporter = new DiagnosticReporter(diagnostics);
+
+    // Clear progress line in interactive mode
+    if (renderer && process.stdout.isTTY) {
+      process.stdout.write('\r\x1b[K');
+    }
+
+    // Check if this is a strict mode failure (REG-332: structured output)
+    if (e instanceof StrictModeFailure) {
+      // Format ONLY from diagnostics, not from error.message
+      console.error('');
+      console.error(`✗ Strict mode: ${e.count} unresolved reference(s) found during ENRICHMENT.`);
+      console.error('');
+      console.error(reporter.formatStrict(e.diagnostics, {
+        verbose: options.verbose,
+        suppressedCount: e.suppressedCount,  // REG-332
+      }));
+      console.error('');
+      console.error('Run without --strict for graceful degradation, or fix the underlying issues.');
+    } else {
+      // Generic error handling (non-strict)
+      const error = e instanceof Error ? e : new Error(String(e));
+      console.error('');
+      console.error(`✗ Analysis failed: ${error.message}`);
+      console.error('');
+      console.error('→ Run with --debug for detailed diagnostics');
+
+      if (diagnostics.count() > 0) {
+        console.error('');
+        console.error(reporter.report({ format: 'text', includeSummary: true }));
+      }
+    }
+
+    // Write diagnostics.log in debug mode even on failure
+    if (options.debug) {
+      const writer = new DiagnosticWriter();
+      await writer.write(diagnostics, grafemaDir);
+      console.error(`Diagnostics written to ${writer.getLogPath(grafemaDir)}`);
+    }
+
+    exitCode = 1;
+  } finally {
+    // Stop stats polling
+    if (statsInterval) {
+      clearInterval(statsInterval);
+      statsInterval = null;
+    }
+
+    if (backend.connected) {
+      await backend.close();
+    }
+
+    // Exit with appropriate code
+    // 0 = success, 1 = fatal, 2 = errors
+    exitWithCode(exitCode);
+  }
+}

package/src/commands/check.ts

@@ -12,69 +12,34 @@ import { existsSync, readFileSync } from 'fs';
 import {
   RFDBServerBackend,
   GuaranteeManager,
-  NodeCreationValidator,
   GraphFreshnessChecker,
-  IncrementalReanalyzer
+  IncrementalReanalyzer,
+  DIAGNOSTIC_CATEGORIES,
 } from '@grafema/core';
-import type { GuaranteeGraph } from '@grafema/core';
-import type { GraphBackend } from '@grafema/types';
+import type { GuaranteeGraph, DiagnosticCategoryKey } from '@grafema/core';
 import { exitWithError } from '../utils/errorFormatter.js';
 
-interface GuaranteeFile {
-  guarantees: Array<{
-    id: string;
-    name: string;
-    rule: string;
-    severity?: 'error' | 'warning' | 'info';
-    governs?: string[];
-  }>;
-}
 
 // Available built-in validators
-const BUILT_IN_VALIDATORS: Record<string, { name: string; description: string }> = {
-  'node-creation': {
-    name: 'NodeCreationValidator',
-    description: 'Validates that all nodes are created through NodeFactory'
-  }
+// Add new validators here as they are implemented
+const BUILT_IN_VALIDATORS: Record<string, { name: string; description: string; create: () => unknown }> = {
+  // Example:
+  // 'my-validator': {
+  //   name: 'MyValidator',
+  //   description: 'Validates something important',
+  //   create: () => new MyValidator()
+  // }
 };
 
-// Category definition for diagnostic filtering
-export interface DiagnosticCheckCategory {
-  name: string;
-  description: string;
-  codes: string[];
-}
-
-// Available diagnostic categories
-export const CHECK_CATEGORIES: Record<string, DiagnosticCheckCategory> = {
-  'connectivity': {
-    name: 'Graph Connectivity',
-    description: 'Check for disconnected nodes in the graph',
-    codes: ['ERR_DISCONNECTED_NODES', 'ERR_DISCONNECTED_NODE'],
-  },
-  'calls': {
-    name: 'Call Resolution',
-    description: 'Check for unresolved function calls',
-    codes: ['ERR_UNRESOLVED_CALL'],
-  },
-  'dataflow': {
-    name: 'Data Flow',
-    description: 'Check for missing assignments and broken references',
-    codes: ['ERR_MISSING_ASSIGNMENT', 'ERR_BROKEN_REFERENCE', 'ERR_NO_LEAF_NODE'],
-  },
-  'imports': {
-    name: 'Import Validation',
-    description: 'Check for broken imports and undefined symbols',
-    codes: ['ERR_BROKEN_IMPORT', 'ERR_UNDEFINED_SYMBOL'],
-  },
-};
+// Re-export for backward compatibility (deprecated - import from @grafema/core instead)
+export { DIAGNOSTIC_CATEGORIES as CHECK_CATEGORIES };
 
 export const checkCommand = new Command('check')
   .description('Check invariants/guarantees')
   .argument('[rule]', 'Specific rule ID to check (or "all" for all rules)')
   .option('-p, --project <path>', 'Project path', '.')
   .option('-f, --file <path>', 'Path to guarantees YAML file')
-  .option('-g, --guarantee <name>', 'Run a built-in guarantee validator (e.g., node-creation)')
+  .option('-g, --guarantee <name>', 'Run a built-in guarantee validator')
   .option('-j, --json', 'Output results as JSON')
   .option('-q, --quiet', 'Only output failures')
   .option('--list-guarantees', 'List available built-in guarantees')
@@ -88,7 +53,7 @@ Examples:
   grafema check calls                    Check call resolution
   grafema check dataflow                 Check data flow integrity
   grafema check all                      Run all diagnostic categories
-  grafema check --guarantee node-creation    Run built-in validator
+  grafema check --guarantee <name>           Run built-in validator
   grafema check --list-categories        List available categories
   grafema check --list-guarantees        List built-in guarantees
   grafema check --fail-on-stale          CI mode: fail if graph is stale
@@ -113,7 +78,7 @@ Examples:
       if (options.listCategories) {
         console.log('Available diagnostic categories:');
         console.log('');
-        for (const [key, category] of Object.entries(CHECK_CATEGORIES)) {
+        for (const [key, category] of Object.entries(DIAGNOSTIC_CATEGORIES)) {
           console.log(`  ${key}`);
           console.log(`    ${category.name}`);
           console.log(`    ${category.description}`);
@@ -136,7 +101,7 @@ Examples:
       }
 
       // Check if rule argument is a category name
-      if (rule && (rule in CHECK_CATEGORIES || rule === 'all')) {
+      if (rule && (rule in DIAGNOSTIC_CATEGORIES || rule === 'all')) {
         await runCategoryCheck(rule, options);
         return;
       }
@@ -172,7 +137,7 @@ Examples:
 
       // Check graph freshness
       const freshnessChecker = new GraphFreshnessChecker();
-      const freshness = await freshnessChecker.checkFreshness(backend);
+      const freshness = await freshnessChecker.checkFreshness(backend, projectPath);
 
       if (!freshness.isFresh) {
         if (options.failOnStale) {
@@ -327,7 +292,7 @@ async function runBuiltInValidator(
 
   // Check graph freshness
   const freshnessChecker = new GraphFreshnessChecker();
-  const freshness = await freshnessChecker.checkFreshness(backend);
+  const freshness = await freshnessChecker.checkFreshness(backend, resolvedPath);
 
   if (!freshness.isFresh) {
     if (options.failOnStale) {
@@ -366,27 +331,29 @@ async function runBuiltInValidator(
   }
 
   try {
-    let validator;
-    let validatorName: string;
-
-    switch (guaranteeName) {
-      case 'node-creation':
-        validator = new NodeCreationValidator();
-        validatorName = 'NodeCreationValidator';
-        break;
-      default:
+    const validatorInfo = BUILT_IN_VALIDATORS[guaranteeName];
+    if (!validatorInfo) {
+      const available = Object.keys(BUILT_IN_VALIDATORS);
+      if (available.length === 0) {
         exitWithError(`Unknown guarantee: ${guaranteeName}`, [
-          'Use --list-guarantees to see available options'
+          'No built-in guarantees are currently available'
         ]);
+      }
+      exitWithError(`Unknown guarantee: ${guaranteeName}`, [
+        `Available: ${available.join(', ')}`
+      ]);
     }
 
+    const validator = validatorInfo.create() as { execute: (ctx: { graph: unknown; projectPath: string }) => Promise<{ metadata?: unknown }> };
+    const validatorName = validatorInfo.name;
+
     if (!options.quiet) {
       console.log(`Running ${validatorName}...`);
       console.log('');
     }
 
     const result = await validator.execute({
-      graph: backend as unknown as GraphBackend,
+      graph: backend,
       projectPath: resolvedPath
     });
 
@@ -422,7 +389,7 @@ async function runBuiltInValidator(
         console.log('');
 
         for (const issue of issues.slice(0, 10)) {
-          const location = issue.file ? `${issue.file}${issue.line ? `:${issue.line}` : ''}` : '';
+          const _location = issue.file ? `${issue.file}${issue.line ? `:${issue.line}` : ''}` : '';
           console.log(`  \x1b[31m•\x1b[0m [${issue.type}] ${issue.message}`);
           if (issue.suggestion && !options.quiet) {
             console.log(`    Suggestion: ${issue.suggestion}`);
@@ -470,7 +437,7 @@ async function runCategoryCheck(
     .map(line => {
       try {
         return JSON.parse(line);
-      } catch (e) {
+      } catch {
         return null;
       }
     })
@@ -479,12 +446,13 @@ async function runCategoryCheck(
   // Filter diagnostics by category codes
   let filteredDiagnostics = allDiagnostics;
   if (category !== 'all') {
-    const categoryInfo = CHECK_CATEGORIES[category];
-    if (!categoryInfo) {
+    if (!(category in DIAGNOSTIC_CATEGORIES)) {
       exitWithError(`Unknown category: ${category}`, [
         'Use --list-categories to see available options'
       ]);
     }
+    const categoryKey = category as DiagnosticCategoryKey;
+    const categoryInfo = DIAGNOSTIC_CATEGORIES[categoryKey];
     filteredDiagnostics = allDiagnostics.filter((d: any) =>
       categoryInfo.codes.includes(d.code)
     );
@@ -499,7 +467,7 @@ async function runCategoryCheck(
   } else {
     const categoryName = category === 'all'
       ? 'All Categories'
-      : CHECK_CATEGORIES[category].name;
+      : DIAGNOSTIC_CATEGORIES[category as DiagnosticCategoryKey].name;
 
     if (!options.quiet) {
       console.log(`Checking ${categoryName}...`);