@grafema/cli 0.2.3-beta → 0.2.5-beta

package/src/commands/analyze.ts

@@ -6,14 +6,16 @@ import { Command } from 'commander';
 import { resolve, join } from 'path';
 import { existsSync, mkdirSync, readdirSync } from 'fs';
 import { pathToFileURL } from 'url';
+import type {
+  Plugin} from '@grafema/core';
 import {
   Orchestrator,
   RFDBServerBackend,
-  Plugin,
   DiagnosticReporter,
   DiagnosticWriter,
   createLogger,
   loadConfig,
+  StrictModeFailure,
   type GrafemaConfig,
   // Discovery
   SimpleProjectDiscovery,
@@ -38,12 +40,14 @@ import {
   AliasTracker,
   ValueDomainAnalyzer,
   MountPointResolver,
+  ExpressHandlerLinker,
   PrefixEvaluator,
   InstanceOfResolver,
   ImportExportLinker,
   FunctionCallResolver,
   HTTPConnectionEnricher,
   RustFFIEnricher,
+  RejectionPropagationEnricher,
   // Validation
   CallResolverValidator,
   EvalBanValidator,
@@ -54,7 +58,22 @@ import {
   TypeScriptDeadCodeValidator,
   BrokenImportValidator,
 } from '@grafema/core';
-import type { LogLevel } from '@grafema/types';
+import type { LogLevel, GraphBackend } from '@grafema/types';
+import { ProgressRenderer } from '../utils/progressRenderer.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);
+}
 
 const BUILTIN_PLUGINS: Record<string, () => Plugin> = {
   // Discovery
@@ -80,12 +99,14 @@ const BUILTIN_PLUGINS: Record<string, () => Plugin> = {
   AliasTracker: () => new AliasTracker() as Plugin,
   ValueDomainAnalyzer: () => new ValueDomainAnalyzer() as Plugin,
   MountPointResolver: () => new MountPointResolver() as Plugin,
+  ExpressHandlerLinker: () => new ExpressHandlerLinker() as Plugin,
   PrefixEvaluator: () => new PrefixEvaluator() as Plugin,
   InstanceOfResolver: () => new InstanceOfResolver() as Plugin,
   ImportExportLinker: () => new ImportExportLinker() as Plugin,
   FunctionCallResolver: () => new FunctionCallResolver() as Plugin,
   HTTPConnectionEnricher: () => new HTTPConnectionEnricher() as Plugin,
   RustFFIEnricher: () => new RustFFIEnricher() as Plugin,
+  RejectionPropagationEnricher: () => new RejectionPropagationEnricher() as Plugin,
   // Validation
   CallResolverValidator: () => new CallResolverValidator() as Plugin,
   EvalBanValidator: () => new EvalBanValidator() as Plugin,
@@ -113,7 +134,7 @@ async function loadCustomPlugins(
 
   try {
     const files = readdirSync(pluginsDir).filter(
-      (f) => f.endsWith('.js') || f.endsWith('.mjs')
+      (f) => f.endsWith('.js') || f.endsWith('.mjs') || f.endsWith('.cjs')
     );
 
     for (const file of files) {
@@ -122,18 +143,24 @@ async function loadCustomPlugins(
         const pluginUrl = pathToFileURL(pluginPath).href;
         const module = await import(pluginUrl);
 
-        const PluginClass = module.default || module[file.replace(/\.(m?js)$/, '')];
+        const PluginClass = module.default || module[file.replace(/\.[cm]?js$/, '')];
         if (PluginClass && typeof PluginClass === 'function') {
-          const pluginName = PluginClass.name || file.replace(/\.(m?js)$/, '');
-          customPlugins[pluginName] = () => new PluginClass() as Plugin;
+          const pluginName = PluginClass.name || file.replace(/\.[cm]?js$/, '');
+          customPlugins[pluginName] = () => {
+            const instance = new PluginClass() as Plugin;
+            instance.config.sourceFile = pluginPath;
+            return instance;
+          };
           log(`Loaded custom plugin: ${pluginName}`);
         }
       } catch (err) {
-        console.warn(`Failed to load plugin ${file}: ${(err as Error).message}`);
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`Failed to load plugin ${file}: ${message}`);
       }
     }
   } catch (err) {
-    console.warn(`Error loading custom plugins: ${(err as Error).message}`);
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`Error loading custom plugins: ${message}`);
   }
 
   return customPlugins;
@@ -141,7 +168,8 @@ async function loadCustomPlugins(
 
 function createPlugins(
   config: GrafemaConfig['plugins'],
-  customPlugins: Record<string, () => Plugin> = {}
+  customPlugins: Record<string, () => Plugin> = {},
+  verbose: boolean = false
 ): Plugin[] {
   const plugins: Plugin[] = [];
   const phases: (keyof GrafemaConfig['plugins'])[] = ['discovery', 'indexing', 'analysis', 'enrichment', 'validation'];
@@ -153,8 +181,9 @@ function createPlugins(
       const factory = BUILTIN_PLUGINS[name] || customPlugins[name];
       if (factory) {
         plugins.push(factory());
-      } else {
-        console.warn(`Unknown plugin: ${name}`);
+      } else if (verbose) {
+        // Only show plugin warning in verbose mode
+        console.warn(`Plugin not found: ${name} (skipping). Check .grafema/config.yaml or add to .grafema/plugins/`);
       }
     }
   }
@@ -164,7 +193,10 @@ function createPlugins(
 
 /**
  * Determine log level from CLI options.
- * Priority: --log-level > --quiet > --verbose > default ('info')
+ * 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) {
@@ -174,8 +206,8 @@ function getLogLevel(options: { quiet?: boolean; verbose?: boolean; logLevel?: s
     }
   }
   if (options.quiet) return 'silent';
-  if (options.verbose) return 'debug';
-  return 'info';
+  if (options.verbose) return 'info';  // --verbose shows logs instead of progress UI
+  return 'silent';  // Default: silent logs, clean progress UI
 }
 
 export const analyzeCommand = new Command('analyze')
@@ -188,6 +220,7 @@ export const analyzeCommand = new Command('analyze')
   .option('-v, --verbose', 'Show verbose logging')
   .option('--debug', 'Enable debug mode (writes diagnostics.log)')
   .option('--log-level <level>', 'Set log level (silent, errors, warnings, info, debug)')
+  .option('--log-file <path>', 'Write all log output to a file')
   .option('--strict', 'Enable strict mode (fail on unresolved references)')
   .option('--auto-start', 'Auto-start RFDB server if not running')
   .addHelpText('after', `
@@ -198,12 +231,13 @@ Examples:
   grafema analyze -s api         Analyze only "api" service (monorepo)
   grafema analyze -v             Verbose output with progress details
   grafema analyze --debug        Write diagnostics.log for debugging
+  grafema analyze --log-file out.log  Write all logs to a file
   grafema analyze --strict       Fail on unresolved references (debugging)
   grafema analyze --auto-start   Auto-start server (useful for CI)
 
 Note: Start the server first with: grafema server start
 `)
-  .action(async (path: string, options: { service?: string; entrypoint?: string; clear?: boolean; quiet?: boolean; verbose?: boolean; debug?: boolean; logLevel?: string; strict?: boolean; autoStart?: boolean }) => {
+  .action(async (path: string, options: { service?: string; entrypoint?: string; clear?: boolean; quiet?: boolean; verbose?: boolean; debug?: boolean; logLevel?: string; logFile?: string; strict?: boolean; autoStart?: boolean }) => {
     const projectPath = resolve(path);
     const grafemaDir = join(projectPath, '.grafema');
     const dbPath = join(grafemaDir, 'graph.rfdb');
@@ -212,20 +246,30 @@ Note: Start the server first with: grafema server start
       mkdirSync(grafemaDir, { recursive: true });
     }
 
-    const log = options.quiet ? () => {} : console.log;
+    // 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 logger = createLogger(logLevel);
+    const logFile = options.logFile ? resolve(options.logFile) : undefined;
+    const logger = createLogger(logLevel, logFile ? { logFile } : undefined);
 
-    log(`Analyzing project: ${projectPath}`);
+    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
+      autoStart: options.autoStart ?? false,
+      silent: !options.verbose  // Silent in normal mode (show progress), verbose shows logs
     });
 
     try {
@@ -247,7 +291,7 @@ Note: Start the server first with: grafema server start
     }
 
     if (options.clear) {
-      log('Clearing existing database...');
+      debug('Clearing existing database...');
       await backend.clear();
     }
 
@@ -255,29 +299,53 @@ Note: Start the server first with: grafema server start
 
     // Extract services from config (REG-174)
     if (config.services.length > 0) {
-      log(`Loaded ${config.services.length} service(s) from config`);
+      debug(`Loaded ${config.services.length} service(s) from config`);
       for (const svc of config.services) {
         const entry = svc.entryPoint ? ` (entry: ${svc.entryPoint})` : '';
-        log(`  - ${svc.name}: ${svc.path}${entry}`);
+        debug(`  - ${svc.name}: ${svc.path}${entry}`);
       }
     }
 
     // Load custom plugins from .grafema/plugins/
-    const customPlugins = await loadCustomPlugins(projectPath, log);
-    const plugins = createPlugins(config.plugins, customPlugins);
+    const customPlugins = await loadCustomPlugins(projectPath, debug);
+    const plugins = createPlugins(config.plugins, customPlugins, options.verbose);
 
-    log(`Loaded ${plugins.length} plugins`);
+    debug(`Loaded ${plugins.length} plugins`);
 
     // Resolve strict mode: CLI flag overrides config
     const strictMode = options.strict ?? config.strict ?? false;
     if (strictMode) {
-      log('Strict mode enabled - analysis will fail on unresolved references');
+      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 import('@grafema/types').GraphBackend,
+      graph: backend as unknown as GraphBackend,
       plugins,
       serviceFilter: options.service || null,
       entrypoint: options.entrypoint,
@@ -286,9 +354,7 @@ Note: Start the server first with: grafema server start
       services: config.services.length > 0 ? config.services : undefined,  // Pass config services (REG-174)
       strictMode, // REG-330: Pass strict mode flag
       onProgress: (progress) => {
-        if (options.verbose) {
-          log(`[${progress.phase}] ${progress.message}`);
-        }
+        renderer?.update(progress);
       },
     });
 
@@ -298,13 +364,17 @@ Note: Start the server first with: grafema server start
       await orchestrator.run(projectPath);
       await backend.flush();
 
-      const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
-      const stats = await backend.getStats();
+      const elapsedSeconds = (Date.now() - startTime) / 1000;
+      const stats = await fetchNodeEdgeCounts(backend);
 
-      log('');
-      log(`Analysis complete in ${elapsed}s`);
-      log(`  Nodes: ${stats.nodeCount}`);
-      log(`  Edges: ${stats.edgeCount}`);
+      // 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();
@@ -312,13 +382,13 @@ Note: Start the server first with: grafema server start
 
       // Print summary if there are any issues
       if (diagnostics.count() > 0) {
-        log('');
-        log(reporter.categorizedSummary());
+        info('');
+        info(reporter.categorizedSummary());
 
         // In verbose mode, print full report
         if (options.verbose) {
-          log('');
-          log(reporter.report({ format: 'text', includeSummary: false }));
+          debug('');
+          debug(reporter.report({ format: 'text', includeSummary: false }));
         }
       }
 
@@ -326,7 +396,7 @@ Note: Start the server first with: grafema server start
       const writer = new DiagnosticWriter();
       await writer.write(diagnostics, grafemaDir);
       if (options.debug) {
-        log(`Diagnostics written to ${writer.getLogPath(grafemaDir)}`);
+        debug(`Diagnostics written to ${writer.getLogPath(grafemaDir)}`);
       }
 
       // Determine exit code based on severity
@@ -338,19 +408,38 @@ Note: Start the server first with: grafema server start
         exitCode = 0; // Success (maybe warnings)
       }
     } catch (e) {
-      // Orchestrator threw (fatal error stopped analysis)
-      const error = e instanceof Error ? e : new Error(String(e));
       const diagnostics = orchestrator.getDiagnostics();
       const reporter = new DiagnosticReporter(diagnostics);
 
-      console.error('');
-      console.error(`✗ Analysis failed: ${error.message}`);
-      console.error('');
-      console.error('→ Run with --debug for detailed diagnostics');
+      // Clear progress line in interactive mode
+      if (renderer && process.stdout.isTTY) {
+        process.stdout.write('\r\x1b[K');
+      }
 
-      if (diagnostics.count() > 0) {
+      // 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(reporter.report({ format: 'text', includeSummary: true }));
+        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
@@ -361,13 +450,19 @@ Note: Start the server first with: grafema server start
       }
 
       exitCode = 1;
-    }
+    } finally {
+      // Stop stats polling
+      if (statsInterval) {
+        clearInterval(statsInterval);
+        statsInterval = null;
+      }
 
-    await backend.close();
+      if (backend.connected) {
+        await backend.close();
+      }
 
-    // Exit with appropriate code
-    // 0 = success, 1 = fatal, 2 = errors
-    if (exitCode !== 0) {
-      process.exit(exitCode);
+      // 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;
       }
@@ -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}...`);

package/src/commands/doctor/checks.ts

@@ -159,8 +159,8 @@ export async function checkConfigValidity(
       return {
         name: 'config',
         status: 'warn',
-        message: `Unknown plugin(s): ${unknownPlugins.join(', ')}`,
-        recommendation: 'Check plugin names for typos. Run: grafema doctor --verbose for available plugins',
+        message: `Plugin(s) not found: ${unknownPlugins.join(', ')} (will be skipped during analysis)`,
+        recommendation: 'Check plugin names for typos or add custom plugins to .grafema/plugins/. Run: grafema doctor --verbose for available plugins',
         details: { unknownPlugins },
       };
     }
@@ -357,10 +357,11 @@ export async function checkGraphStats(
       },
     };
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
     return {
       name: 'graph_stats',
       status: 'warn',
-      message: `Could not read graph stats: ${(err as Error).message}`,
+      message: `Could not read graph stats: ${message}`,
     };
   }
 }
@@ -496,10 +497,11 @@ export async function checkConnectivity(
       details: { unreachableCount, percentage, byType },
     };
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
     return {
       name: 'connectivity',
       status: 'warn',
-      message: `Could not check connectivity: ${(err as Error).message}`,
+      message: `Could not check connectivity: ${message}`,
     };
   }
 }
@@ -547,10 +549,11 @@ export async function checkFreshness(
       },
     };
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
     return {
       name: 'freshness',
       status: 'warn',
-      message: `Could not check freshness: ${(err as Error).message}`,
+      message: `Could not check freshness: ${message}`,
     };
   }
 }