@grafema/cli 0.1.1-alpha → 0.2.1-beta

package/src/commands/doctor/output.ts

@@ -0,0 +1,115 @@
+/**
+ * Output formatting utilities for `grafema doctor` command - REG-214
+ */
+
+import type { DoctorCheckResult, DoctorReport } from './types.js';
+
+// ANSI colors (matching existing CLI style)
+const COLORS = {
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  dim: '\x1b[2m',
+  reset: '\x1b[0m',
+};
+
+const STATUS_ICONS: Record<string, string> = {
+  pass: `${COLORS.green}✓${COLORS.reset}`,
+  warn: `${COLORS.yellow}⚠${COLORS.reset}`,
+  fail: `${COLORS.red}✗${COLORS.reset}`,
+  skip: `${COLORS.dim}○${COLORS.reset}`,
+};
+
+/**
+ * Format a single check result for console output.
+ */
+export function formatCheck(result: DoctorCheckResult, verbose: boolean): string {
+  const icon = STATUS_ICONS[result.status];
+  let output = `${icon} ${result.message}`;
+
+  if (result.recommendation) {
+    output += `\n  ${COLORS.dim}→${COLORS.reset} ${result.recommendation}`;
+  }
+
+  if (verbose && result.details) {
+    const detailStr = JSON.stringify(result.details, null, 2)
+      .split('\n')
+      .map(line => `    ${COLORS.dim}${line}${COLORS.reset}`)
+      .join('\n');
+    output += `\n${detailStr}`;
+  }
+
+  return output;
+}
+
+/**
+ * Format full report for console.
+ */
+export function formatReport(
+  checks: DoctorCheckResult[],
+  options: { quiet?: boolean; verbose?: boolean }
+): string {
+  const lines: string[] = [];
+
+  if (!options.quiet) {
+    lines.push('Checking Grafema setup...');
+    lines.push('');
+  }
+
+  for (const check of checks) {
+    if (options.quiet && check.status === 'pass') continue;
+    lines.push(formatCheck(check, options.verbose || false));
+  }
+
+  // Summary
+  const failCount = checks.filter(c => c.status === 'fail').length;
+  const warnCount = checks.filter(c => c.status === 'warn').length;
+
+  lines.push('');
+  if (failCount > 0) {
+    lines.push(`${COLORS.red}Status: ${failCount} error(s), ${warnCount} warning(s)${COLORS.reset}`);
+  } else if (warnCount > 0) {
+    lines.push(`${COLORS.yellow}Status: ${warnCount} warning(s)${COLORS.reset}`);
+  } else {
+    lines.push(`${COLORS.green}Status: All checks passed${COLORS.reset}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build JSON report structure.
+ */
+export function buildJsonReport(
+  checks: DoctorCheckResult[],
+  projectPath: string
+): DoctorReport {
+  const failCount = checks.filter(c => c.status === 'fail').length;
+  const warnCount = checks.filter(c => c.status === 'warn').length;
+
+  const status = failCount > 0 ? 'error' : warnCount > 0 ? 'warning' : 'healthy';
+  const recommendations = checks
+    .filter(c => c.recommendation)
+    .map(c => c.recommendation as string);
+
+  // Extract versions from versions check
+  const versionsCheck = checks.find(c => c.name === 'versions');
+  const versions = (versionsCheck?.details as { cli?: string; core?: string; rfdb?: string }) || {
+    cli: 'unknown',
+    core: 'unknown',
+  };
+
+  return {
+    status,
+    timestamp: new Date().toISOString(),
+    project: projectPath,
+    checks,
+    recommendations,
+    versions: {
+      cli: versions.cli || 'unknown',
+      core: versions.core || 'unknown',
+      rfdb: versions.rfdb,
+    },
+  };
+}

package/src/commands/doctor/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Type definitions for `grafema doctor` command - REG-214
+ */
+
+/**
+ * Status of a single diagnostic check
+ */
+export type CheckStatus = 'pass' | 'warn' | 'fail' | 'skip';
+
+/**
+ * Result of a single diagnostic check
+ */
+export interface DoctorCheckResult {
+  name: string;           // e.g., 'config', 'server', 'database'
+  status: CheckStatus;
+  message: string;        // Human-readable message
+  recommendation?: string; // Actionable next step if not pass
+  details?: Record<string, unknown>; // Additional data (counts, versions, etc.)
+}
+
+/**
+ * Options for the doctor command
+ */
+export interface DoctorOptions {
+  project: string;        // Project path (default: ".")
+  json?: boolean;         // Output as JSON
+  quiet?: boolean;        // Only show failures
+  verbose?: boolean;      // Show detailed diagnostics
+}
+
+/**
+ * Overall doctor report (for JSON output)
+ */
+export interface DoctorReport {
+  status: 'healthy' | 'warning' | 'error';
+  timestamp: string;      // ISO timestamp
+  project: string;        // Absolute project path
+  checks: DoctorCheckResult[];
+  recommendations: string[];
+  versions: {
+    cli: string;
+    core: string;
+    rfdb?: string;
+  };
+}

package/src/commands/doctor.ts

@@ -0,0 +1,106 @@
+/**
+ * Doctor command - Diagnose Grafema setup issues
+ *
+ * Checks (in order):
+ * 1. Initialization (.grafema directory, config file)
+ * 2. Config validity (syntax, plugin names)
+ * 3. Entrypoints (service paths exist)
+ * 4. Server status (RFDB server running)
+ * 5. Database exists and has data
+ * 6. Graph statistics
+ * 7. Graph connectivity
+ * 8. Graph freshness
+ * 9. Version information
+ */
+
+import { Command } from 'commander';
+import { resolve } from 'path';
+import {
+  checkGrafemaInitialized,
+  checkServerStatus,
+  checkConfigValidity,
+  checkEntrypoints,
+  checkDatabaseExists,
+  checkGraphStats,
+  checkConnectivity,
+  checkFreshness,
+  checkVersions,
+} from './doctor/checks.js';
+import { formatReport, buildJsonReport } from './doctor/output.js';
+import type { DoctorOptions, DoctorCheckResult } from './doctor/types.js';
+
+export const doctorCommand = new Command('doctor')
+  .description('Diagnose Grafema setup issues')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-j, --json', 'Output as JSON')
+  .option('-q, --quiet', 'Only show failures')
+  .option('-v, --verbose', 'Show detailed diagnostics')
+  .addHelpText('after', `
+Examples:
+  grafema doctor                 Run all diagnostic checks
+  grafema doctor --verbose       Show detailed diagnostics
+  grafema doctor --quiet         Only show failures
+  grafema doctor --json          Output diagnostics as JSON
+`)
+  .action(async (options: DoctorOptions) => {
+    const projectPath = resolve(options.project);
+    const checks: DoctorCheckResult[] = [];
+
+    // Level 1: Prerequisites (fail-fast)
+    const initCheck = await checkGrafemaInitialized(projectPath);
+    checks.push(initCheck);
+
+    if (initCheck.status === 'fail') {
+      // Can't continue without initialization
+      outputResults(checks, projectPath, options);
+      process.exit(1);
+    }
+
+    // Level 2: Configuration
+    checks.push(await checkConfigValidity(projectPath));
+    checks.push(await checkEntrypoints(projectPath));
+
+    // Server status (needed for Level 3 checks)
+    const serverCheck = await checkServerStatus(projectPath);
+    checks.push(serverCheck);
+
+    // Level 3: Graph Health (requires database and optionally server)
+    checks.push(await checkDatabaseExists(projectPath));
+
+    if (serverCheck.status === 'pass') {
+      // Server is running - can do full health checks
+      checks.push(await checkGraphStats(projectPath));
+      checks.push(await checkConnectivity(projectPath));
+      checks.push(await checkFreshness(projectPath));
+    }
+
+    // Level 4: Informational
+    checks.push(await checkVersions(projectPath));
+
+    // Output results
+    outputResults(checks, projectPath, options);
+
+    // Exit code
+    const failCount = checks.filter(c => c.status === 'fail').length;
+    const warnCount = checks.filter(c => c.status === 'warn').length;
+
+    if (failCount > 0) {
+      process.exit(1);  // Critical issues
+    } else if (warnCount > 0) {
+      process.exit(2);  // Warnings only
+    }
+    // Exit 0 for all pass
+  });
+
+function outputResults(
+  checks: DoctorCheckResult[],
+  projectPath: string,
+  options: DoctorOptions
+): void {
+  if (options.json) {
+    const report = buildJsonReport(checks, projectPath);
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(formatReport(checks, options));
+  }
+}

package/src/commands/explain.ts

@@ -0,0 +1,173 @@
+/**
+ * Explain command - Show what nodes exist in a file
+ *
+ * Purpose: Help users discover what nodes exist in the graph for a file,
+ * displaying semantic IDs so users can query them.
+ *
+ * Use cases:
+ * - User can't find a variable they expect to be in the graph
+ * - User wants to understand what's been analyzed for a file
+ * - User needs semantic IDs to construct queries
+ *
+ * @see _tasks/REG-177/006-don-revised-plan.md
+ */
+
+import { Command } from 'commander';
+import { resolve, join, relative, normalize } from 'path';
+import { existsSync, realpathSync } from 'fs';
+import { RFDBServerBackend, FileExplainer, type EnhancedNode } from '@grafema/core';
+import { exitWithError } from '../utils/errorFormatter.js';
+
+interface ExplainOptions {
+  project: string;
+  json?: boolean;
+}
+
+export const explainCommand = new Command('explain')
+  .description('Show what nodes exist in a file')
+  .argument('<file>', 'File path to explain')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-j, --json', 'Output as JSON')
+  .addHelpText('after', `
+Examples:
+  grafema explain src/app.ts           Show all nodes in src/app.ts
+  grafema explain src/app.ts --json    Output as JSON for scripting
+  grafema explain ./src/utils.js       Works with relative paths
+
+This command helps you:
+  1. Discover what nodes exist in the graph for a file
+  2. Find semantic IDs to use in queries
+  3. Understand scope context (try/catch, conditionals, etc.)
+
+If a file shows NOT_ANALYZED:
+  - Run: grafema analyze
+  - Check if file is excluded in config
+`)
+  .action(async (file: string, options: ExplainOptions) => {
+    const projectPath = resolve(options.project);
+    const grafemaDir = join(projectPath, '.grafema');
+    const dbPath = join(grafemaDir, 'graph.rfdb');
+
+    // Check database exists
+    if (!existsSync(dbPath)) {
+      exitWithError('No graph database found', [
+        'Run: grafema init && grafema analyze',
+      ]);
+    }
+
+    // Normalize and resolve file path
+    let filePath = file;
+
+    // Handle relative paths - convert to relative from project root
+    if (file.startsWith('./') || file.startsWith('../')) {
+      filePath = normalize(file).replace(/^\.\//, '');
+    } else if (resolve(file) === file) {
+      // Absolute path - convert to relative
+      filePath = relative(projectPath, file);
+    }
+
+    // Resolve to absolute path for graph lookup
+    const resolvedPath = resolve(projectPath, filePath);
+    if (!existsSync(resolvedPath)) {
+      exitWithError(`File not found: ${file}`, [
+        'Check the file path and try again',
+      ]);
+    }
+
+    // Use realpath to match how graph stores paths (handles symlinks like /tmp -> /private/tmp on macOS)
+    const absoluteFilePath = realpathSync(resolvedPath);
+
+    // Keep relative path for display
+    const relativeFilePath = relative(projectPath, absoluteFilePath);
+
+    const backend = new RFDBServerBackend({ dbPath });
+    await backend.connect();
+
+    try {
+      const explainer = new FileExplainer(backend);
+      // Query with absolute path since graph stores absolute paths
+      const result = await explainer.explain(absoluteFilePath);
+
+      // Override file in result for display purposes (show relative path)
+      result.file = relativeFilePath;
+
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      // Human-readable output
+      console.log(`File: ${result.file}`);
+      console.log(`Status: ${result.status}`);
+      console.log('');
+
+      if (result.status === 'NOT_ANALYZED') {
+        console.log('This file has not been analyzed yet.');
+        console.log('');
+        console.log('To analyze:');
+        console.log('  grafema analyze');
+        return;
+      }
+
+      console.log(`Nodes in graph: ${result.totalCount}`);
+      console.log('');
+
+      // Group nodes by type for display
+      const nodesByType = groupNodesByType(result.nodes);
+
+      for (const [type, nodes] of Object.entries(nodesByType)) {
+        for (const node of nodes) {
+          displayNode(node, type, projectPath);
+          console.log('');
+        }
+      }
+
+      // Show summary by type
+      console.log('Summary:');
+      for (const [type, count] of Object.entries(result.byType).sort()) {
+        console.log(`  ${type}: ${count}`);
+      }
+
+      console.log('');
+      console.log('To query a specific node by ID:');
+      console.log('  grafema query --raw \'attr(X, "id", "<semantic-id>")\'');
+    } finally {
+      await backend.close();
+    }
+  });
+
+/**
+ * Group nodes by type for organized display
+ */
+function groupNodesByType(nodes: EnhancedNode[]): Record<string, EnhancedNode[]> {
+  const grouped: Record<string, EnhancedNode[]> = {};
+
+  for (const node of nodes) {
+    const type = node.type || 'UNKNOWN';
+    if (!grouped[type]) {
+      grouped[type] = [];
+    }
+    grouped[type].push(node);
+  }
+
+  return grouped;
+}
+
+/**
+ * Display a single node in human-readable format
+ */
+function displayNode(node: EnhancedNode, type: string, projectPath: string): void {
+  // Line 1: [TYPE] name (context)
+  const contextSuffix = node.context ? ` (${node.context})` : '';
+  console.log(`[${type}] ${node.name || '<anonymous>'}${contextSuffix}`);
+
+  // Line 2: ID (semantic ID for querying)
+  console.log(`  ID: ${node.id}`);
+
+  // Line 3: Location
+  if (node.file) {
+    const relPath = relative(projectPath, node.file);
+    const loc = node.line ? `${relPath}:${node.line}` : relPath;
+    console.log(`  Location: ${loc}`);
+  }
+}