@grafema/cli 0.1.1-alpha

package/dist/utils/codePreview.js

@@ -0,0 +1,51 @@
+/**
+ * Code Preview Utility
+ *
+ * Reads source files and extracts code snippets around a given line number
+ * for displaying in the explorer UI.
+ */
+import { readFileSync, existsSync } from 'fs';
+/**
+ * Get a code preview snippet from a source file.
+ * Returns lines around the specified line number with context.
+ */
+export function getCodePreview(options) {
+    const { file, line, contextBefore = 2, contextAfter = 12 } = options;
+    if (!existsSync(file)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(file, 'utf-8');
+        const allLines = content.split('\n');
+        // Calculate range (1-indexed)
+        const startLine = Math.max(1, line - contextBefore);
+        const endLine = Math.min(allLines.length, line + contextAfter);
+        // Extract lines (convert to 0-indexed for array access)
+        const lines = allLines.slice(startLine - 1, endLine);
+        return {
+            lines,
+            startLine,
+            endLine
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Format code preview lines with line numbers for display.
+ * Returns an array of formatted strings like "  42 | code here"
+ */
+export function formatCodePreview(preview, highlightLine) {
+    const { lines, startLine } = preview;
+    const maxLineNum = startLine + lines.length - 1;
+    const lineNumWidth = String(maxLineNum).length;
+    return lines.map((line, index) => {
+        const lineNum = startLine + index;
+        const paddedNum = String(lineNum).padStart(lineNumWidth, ' ');
+        const prefix = highlightLine === lineNum ? '>' : ' ';
+        // Truncate very long lines
+        const displayLine = line.length > 80 ? line.slice(0, 77) + '...' : line;
+        return `${prefix}${paddedNum} | ${displayLine}`;
+    });
+}

package/dist/utils/errorFormatter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Standardized error formatting for CLI commands - REG-157
+ *
+ * Provides consistent error messages across all CLI commands.
+ * Format:
+ *   ✗ Main error message (1 line, concise)
+ *
+ *   → Next action 1
+ *   → Next action 2
+ */
+/**
+ * Print a standardized error message and exit.
+ *
+ * @param title - Main error message (should be under 80 chars)
+ * @param nextSteps - Optional array of actionable suggestions
+ * @returns never - always calls process.exit(1)
+ *
+ * @example
+ * exitWithError('No graph database found', [
+ *   'Run: grafema analyze'
+ * ]);
+ */
+export declare function exitWithError(title: string, nextSteps?: string[]): never;
+//# sourceMappingURL=errorFormatter.d.ts.map

package/dist/utils/errorFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorFormatter.d.ts","sourceRoot":"","sources":["../../src/utils/errorFormatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,CAWxE"}

package/dist/utils/errorFormatter.js

@@ -0,0 +1,32 @@
+/**
+ * Standardized error formatting for CLI commands - REG-157
+ *
+ * Provides consistent error messages across all CLI commands.
+ * Format:
+ *   ✗ Main error message (1 line, concise)
+ *
+ *   → Next action 1
+ *   → Next action 2
+ */
+/**
+ * Print a standardized error message and exit.
+ *
+ * @param title - Main error message (should be under 80 chars)
+ * @param nextSteps - Optional array of actionable suggestions
+ * @returns never - always calls process.exit(1)
+ *
+ * @example
+ * exitWithError('No graph database found', [
+ *   'Run: grafema analyze'
+ * ]);
+ */
+export function exitWithError(title, nextSteps) {
+    console.error(`✗ ${title}`);
+    if (nextSteps && nextSteps.length > 0) {
+        console.error('');
+        for (const step of nextSteps) {
+            console.error(`→ ${step}`);
+        }
+    }
+    process.exit(1);
+}

package/dist/utils/formatNode.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Node display formatting utilities - REG-125
+ *
+ * Provides consistent formatting for node display across all CLI commands.
+ * Semantic IDs are shown as the PRIMARY identifier, with location as secondary.
+ */
+/**
+ * Format options for node display
+ */
+export interface FormatNodeOptions {
+    /** Project path for relative file paths */
+    projectPath: string;
+    /** Include location line (default: true) */
+    showLocation?: boolean;
+    /** Prefix for each line (default: '') */
+    indent?: string;
+}
+/**
+ * Node information required for display
+ */
+export interface DisplayableNode {
+    /** Semantic ID (e.g., "auth/service.ts->AuthService->FUNCTION->authenticate") */
+    id: string;
+    /** Node type (e.g., "FUNCTION", "CLASS") */
+    type: string;
+    /** Human-readable name */
+    name: string;
+    /** Absolute file path */
+    file: string;
+    /** Line number (optional) */
+    line?: number;
+}
+/**
+ * Format a node for primary display (multi-line)
+ *
+ * Output format:
+ *   [FUNCTION] authenticate
+ *     ID: auth/service.ts->AuthService->FUNCTION->authenticate
+ *     Location: auth/service.ts:42
+ */
+export declare function formatNodeDisplay(node: DisplayableNode, options: FormatNodeOptions): string;
+/**
+ * Format a node for inline display in lists (semantic ID only)
+ *
+ * Output format:
+ *   auth/service.ts->AuthService->FUNCTION->authenticate
+ */
+export declare function formatNodeInline(node: DisplayableNode): string;
+/**
+ * Format file location relative to project
+ */
+export declare function formatLocation(file: string | undefined, line: number | undefined, projectPath: string): string;
+//# sourceMappingURL=formatNode.d.ts.map

package/dist/utils/formatNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatNode.d.ts","sourceRoot":"","sources":["../../src/utils/formatNode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAmB3F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,WAAW,EAAE,MAAM,GAClB,MAAM,CAIR"}

package/dist/utils/formatNode.js

@@ -0,0 +1,49 @@
+/**
+ * Node display formatting utilities - REG-125
+ *
+ * Provides consistent formatting for node display across all CLI commands.
+ * Semantic IDs are shown as the PRIMARY identifier, with location as secondary.
+ */
+import { relative } from 'path';
+/**
+ * Format a node for primary display (multi-line)
+ *
+ * Output format:
+ *   [FUNCTION] authenticate
+ *     ID: auth/service.ts->AuthService->FUNCTION->authenticate
+ *     Location: auth/service.ts:42
+ */
+export function formatNodeDisplay(node, options) {
+    const { projectPath, showLocation = true, indent = '' } = options;
+    const lines = [];
+    // Line 1: [TYPE] name
+    lines.push(`${indent}[${node.type}] ${node.name}`);
+    // Line 2: ID (semantic ID)
+    lines.push(`${indent}  ID: ${node.id}`);
+    // Line 3: Location (optional)
+    if (showLocation) {
+        const loc = formatLocation(node.file, node.line, projectPath);
+        if (loc) {
+            lines.push(`${indent}  Location: ${loc}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Format a node for inline display in lists (semantic ID only)
+ *
+ * Output format:
+ *   auth/service.ts->AuthService->FUNCTION->authenticate
+ */
+export function formatNodeInline(node) {
+    return node.id;
+}
+/**
+ * Format file location relative to project
+ */
+export function formatLocation(file, line, projectPath) {
+    if (!file)
+        return '';
+    const relPath = relative(projectPath, file);
+    return line ? `${relPath}:${line}` : relPath;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@grafema/cli",
+  "version": "0.1.1-alpha",
+  "description": "CLI for Grafema code analysis toolkit",
+  "type": "module",
+  "main": "./dist/cli.js",
+  "types": "./dist/cli.d.ts",
+  "bin": {
+    "grafema": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "grafema",
+    "cli",
+    "code-analysis",
+    "static-analysis"
+  ],
+  "license": "Apache-2.0",
+  "author": "Vadim Reshetnikov",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/grafema/grafema.git",
+    "directory": "packages/cli"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "ink": "^6.6.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^19.2.3",
+    "yaml": "^2.8.2",
+    "@grafema/core": "0.1.1-alpha",
+    "@grafema/types": "0.1.1-alpha"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "@types/react": "^19.2.9",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "start": "node dist/cli.js",
+    "test": "node --import tsx --test test/*.test.ts"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * @grafema/cli - CLI for Grafema code analysis toolkit
+ */
+
+import { Command } from 'commander';
+import { initCommand } from './commands/init.js';
+import { analyzeCommand } from './commands/analyze.js';
+import { overviewCommand } from './commands/overview.js';
+import { queryCommand } from './commands/query.js';
+import { getCommand } from './commands/get.js';
+import { traceCommand } from './commands/trace.js';
+import { impactCommand } from './commands/impact.js';
+import { exploreCommand } from './commands/explore.js';
+import { statsCommand } from './commands/stats.js';
+import { checkCommand } from './commands/check.js';
+import { serverCommand } from './commands/server.js';
+import { coverageCommand } from './commands/coverage.js';
+
+const program = new Command();
+
+program
+  .name('grafema')
+  .description('Grafema code analysis CLI')
+  .version('0.1.0-alpha.1');
+
+// Commands in logical order
+program.addCommand(initCommand);
+program.addCommand(analyzeCommand);
+program.addCommand(overviewCommand);
+program.addCommand(queryCommand);
+program.addCommand(getCommand);
+program.addCommand(traceCommand);
+program.addCommand(impactCommand);
+program.addCommand(exploreCommand);
+program.addCommand(statsCommand);  // Keep for backwards compat
+program.addCommand(coverageCommand);
+program.addCommand(checkCommand);
+program.addCommand(serverCommand);
+
+program.parse();

package/src/commands/analyze.ts

@@ -0,0 +1,271 @@
+/**
+ * Analyze command - Run project analysis via Orchestrator
+ */
+
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+import {
+  Orchestrator,
+  RFDBServerBackend,
+  Plugin,
+  DiagnosticReporter,
+  DiagnosticWriter,
+  createLogger,
+  loadConfig,
+  type GrafemaConfig,
+  // Discovery
+  SimpleProjectDiscovery,
+  MonorepoServiceDiscovery,
+  WorkspaceDiscovery,
+  // Indexing
+  JSModuleIndexer,
+  RustModuleIndexer,
+  // Analysis
+  JSASTAnalyzer,
+  ExpressRouteAnalyzer,
+  SocketIOAnalyzer,
+  DatabaseAnalyzer,
+  FetchAnalyzer,
+  ServiceLayerAnalyzer,
+  ReactAnalyzer,
+  RustAnalyzer,
+  // Enrichment
+  MethodCallResolver,
+  AliasTracker,
+  ValueDomainAnalyzer,
+  MountPointResolver,
+  PrefixEvaluator,
+  InstanceOfResolver,
+  ImportExportLinker,
+  HTTPConnectionEnricher,
+  RustFFIEnricher,
+  // Validation
+  CallResolverValidator,
+  EvalBanValidator,
+  SQLInjectionValidator,
+  ShadowingDetector,
+  GraphConnectivityValidator,
+  DataFlowValidator,
+  TypeScriptDeadCodeValidator,
+} from '@grafema/core';
+import type { LogLevel } from '@grafema/types';
+
+const BUILTIN_PLUGINS: Record<string, () => Plugin> = {
+  // Discovery
+  SimpleProjectDiscovery: () => new SimpleProjectDiscovery() as Plugin,
+  MonorepoServiceDiscovery: () => new MonorepoServiceDiscovery() as Plugin,
+  WorkspaceDiscovery: () => new WorkspaceDiscovery() as Plugin,
+  // Indexing
+  JSModuleIndexer: () => new JSModuleIndexer() as Plugin,
+  RustModuleIndexer: () => new RustModuleIndexer() as Plugin,
+  // Analysis
+  JSASTAnalyzer: () => new JSASTAnalyzer() as Plugin,
+  ExpressRouteAnalyzer: () => new ExpressRouteAnalyzer() as Plugin,
+  SocketIOAnalyzer: () => new SocketIOAnalyzer() as Plugin,
+  DatabaseAnalyzer: () => new DatabaseAnalyzer() as Plugin,
+  FetchAnalyzer: () => new FetchAnalyzer() as Plugin,
+  ServiceLayerAnalyzer: () => new ServiceLayerAnalyzer() as Plugin,
+  ReactAnalyzer: () => new ReactAnalyzer() as Plugin,
+  RustAnalyzer: () => new RustAnalyzer() as Plugin,
+  // Enrichment
+  MethodCallResolver: () => new MethodCallResolver() as Plugin,
+  AliasTracker: () => new AliasTracker() as Plugin,
+  ValueDomainAnalyzer: () => new ValueDomainAnalyzer() as Plugin,
+  MountPointResolver: () => new MountPointResolver() as Plugin,
+  PrefixEvaluator: () => new PrefixEvaluator() as Plugin,
+  InstanceOfResolver: () => new InstanceOfResolver() as Plugin,
+  ImportExportLinker: () => new ImportExportLinker() as Plugin,
+  HTTPConnectionEnricher: () => new HTTPConnectionEnricher() as Plugin,
+  RustFFIEnricher: () => new RustFFIEnricher() as Plugin,
+  // Validation
+  CallResolverValidator: () => new CallResolverValidator() as Plugin,
+  EvalBanValidator: () => new EvalBanValidator() as Plugin,
+  SQLInjectionValidator: () => new SQLInjectionValidator() as Plugin,
+  ShadowingDetector: () => new ShadowingDetector() as Plugin,
+  GraphConnectivityValidator: () => new GraphConnectivityValidator() as Plugin,
+  DataFlowValidator: () => new DataFlowValidator() as Plugin,
+  TypeScriptDeadCodeValidator: () => new TypeScriptDeadCodeValidator() as Plugin,
+};
+
+function createPlugins(config: GrafemaConfig['plugins']): Plugin[] {
+  const plugins: Plugin[] = [];
+  const phases: (keyof GrafemaConfig['plugins'])[] = ['discovery', 'indexing', 'analysis', 'enrichment', 'validation'];
+
+  for (const phase of phases) {
+    const names = config[phase] || [];
+    for (const name of names) {
+      const factory = BUILTIN_PLUGINS[name];
+      if (factory) {
+        plugins.push(factory());
+      } else {
+        console.warn(`Unknown plugin: ${name}`);
+      }
+    }
+  }
+
+  return plugins;
+}
+
+/**
+ * Determine log level from CLI options.
+ * Priority: --log-level > --quiet > --verbose > default ('info')
+ */
+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 'debug';
+  return 'info';
+}
+
+export const analyzeCommand = new Command('analyze')
+  .description('Run project analysis')
+  .argument('[path]', 'Project path to analyze', '.')
+  .option('-s, --service <name>', 'Analyze only a specific service')
+  .option('-e, --entrypoint <path>', 'Override entrypoint (bypasses auto-detection)')
+  .option('-c, --clear', 'Clear existing database before analysis')
+  .option('-q, --quiet', 'Suppress progress output')
+  .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)')
+  .action(async (path: string, options: { service?: string; entrypoint?: string; clear?: boolean; quiet?: boolean; verbose?: boolean; debug?: boolean; logLevel?: string }) => {
+    const projectPath = resolve(path);
+    const grafemaDir = join(projectPath, '.grafema');
+    const dbPath = join(grafemaDir, 'graph.rfdb');
+
+    if (!existsSync(grafemaDir)) {
+      mkdirSync(grafemaDir, { recursive: true });
+    }
+
+    const log = options.quiet ? () => {} : console.log;
+
+    // Create logger based on CLI flags
+    const logLevel = getLogLevel(options);
+    const logger = createLogger(logLevel);
+
+    log(`Analyzing project: ${projectPath}`);
+
+    const backend = new RFDBServerBackend({ dbPath });
+    await backend.connect();
+
+    if (options.clear) {
+      log('Clearing existing database...');
+      await backend.clear();
+    }
+
+    const config = loadConfig(projectPath, logger);
+
+    // Extract services from config (REG-174)
+    if (config.services.length > 0) {
+      log(`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}`);
+      }
+    }
+
+    const plugins = createPlugins(config.plugins);
+
+    log(`Loaded ${plugins.length} plugins`);
+
+    const startTime = Date.now();
+
+    const orchestrator = new Orchestrator({
+      graph: backend as unknown as import('@grafema/types').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)
+      onProgress: (progress) => {
+        if (options.verbose) {
+          log(`[${progress.phase}] ${progress.message}`);
+        }
+      },
+    });
+
+    let exitCode = 0;
+
+    try {
+      await orchestrator.run(projectPath);
+      await backend.flush();
+
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
+      const stats = await backend.getStats();
+
+      log('');
+      log(`Analysis complete in ${elapsed}s`);
+      log(`  Nodes: ${stats.nodeCount}`);
+      log(`  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) {
+        log('');
+        log(reporter.summary());
+
+        // In verbose mode, print full report
+        if (options.verbose) {
+          log('');
+          log(reporter.report({ format: 'text', includeSummary: false }));
+        }
+      }
+
+      // Write diagnostics.log in debug mode
+      if (options.debug) {
+        const writer = new DiagnosticWriter();
+        await writer.write(diagnostics, grafemaDir);
+        log(`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) {
+      // 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');
+
+      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;
+    }
+
+    await backend.close();
+
+    // Exit with appropriate code
+    // 0 = success, 1 = fatal, 2 = errors
+    if (exitCode !== 0) {
+      process.exit(exitCode);
+    }
+  });