@grafema/cli 0.1.1-alpha

package/src/commands/trace.ts

@@ -0,0 +1,341 @@
+/**
+ * Trace command - Data flow analysis
+ *
+ * Usage:
+ *   grafema trace "userId from authenticate"
+ *   grafema trace "config"
+ */
+
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
+import { RFDBServerBackend, parseSemanticId } from '@grafema/core';
+import { formatNodeDisplay, formatNodeInline } from '../utils/formatNode.js';
+import { exitWithError } from '../utils/errorFormatter.js';
+
+interface TraceOptions {
+  project: string;
+  json?: boolean;
+  depth: string;
+}
+
+interface NodeInfo {
+  id: string;
+  type: string;
+  name: string;
+  file: string;
+  line?: number;
+  value?: unknown;
+}
+
+interface TraceStep {
+  node: NodeInfo;
+  edgeType: string;
+  depth: number;
+}
+
+export const traceCommand = new Command('trace')
+  .description('Trace data flow for a variable')
+  .argument('<pattern>', 'Pattern: "varName from functionName" or just "varName"')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --depth <n>', 'Max trace depth', '10')
+  .action(async (pattern: string, options: TraceOptions) => {
+    const projectPath = resolve(options.project);
+    const grafemaDir = join(projectPath, '.grafema');
+    const dbPath = join(grafemaDir, 'graph.rfdb');
+
+    if (!existsSync(dbPath)) {
+      exitWithError('No graph database found', ['Run: grafema analyze']);
+    }
+
+    const backend = new RFDBServerBackend({ dbPath });
+    await backend.connect();
+
+    try {
+      // Parse pattern: "varName from functionName" or just "varName"
+      const { varName, scopeName } = parseTracePattern(pattern);
+      const maxDepth = parseInt(options.depth, 10);
+
+      console.log(`Tracing ${varName}${scopeName ? ` from ${scopeName}` : ''}...`);
+      console.log('');
+
+      // Find starting variable(s)
+      const variables = await findVariables(backend, varName, scopeName);
+
+      if (variables.length === 0) {
+        console.log(`No variable "${varName}" found${scopeName ? ` in ${scopeName}` : ''}`);
+        return;
+      }
+
+      // Trace each variable
+      for (const variable of variables) {
+        console.log(formatNodeDisplay(variable, { projectPath }));
+        console.log('');
+
+        // Trace backwards through ASSIGNED_FROM
+        const backwardTrace = await traceBackward(backend, variable.id, maxDepth);
+
+        if (backwardTrace.length > 0) {
+          console.log('Data sources (where value comes from):');
+          displayTrace(backwardTrace, projectPath, '  ');
+        }
+
+        // Trace forward through ASSIGNED_FROM (where this value flows to)
+        const forwardTrace = await traceForward(backend, variable.id, maxDepth);
+
+        if (forwardTrace.length > 0) {
+          console.log('');
+          console.log('Data sinks (where value flows to):');
+          displayTrace(forwardTrace, projectPath, '  ');
+        }
+
+        // Show value domain if available
+        const sources = await getValueSources(backend, variable.id);
+        if (sources.length > 0) {
+          console.log('');
+          console.log('Possible values:');
+          for (const src of sources) {
+            if (src.type === 'LITERAL' && src.value !== undefined) {
+              console.log(`  • ${JSON.stringify(src.value)} (literal)`);
+            } else if (src.type === 'PARAMETER') {
+              console.log(`  • <parameter ${src.name}> (runtime input)`);
+            } else if (src.type === 'CALL') {
+              console.log(`  • <return from ${src.name || 'call'}> (computed)`);
+            } else {
+              console.log(`  • <${src.type.toLowerCase()}> ${src.name || ''}`);
+            }
+          }
+        }
+
+        if (variables.length > 1) {
+          console.log('');
+          console.log('---');
+        }
+      }
+
+      if (options.json) {
+        // TODO: structured JSON output
+      }
+
+    } finally {
+      await backend.close();
+    }
+  });
+
+/**
+ * Parse trace pattern
+ */
+function parseTracePattern(pattern: string): { varName: string; scopeName: string | null } {
+  const fromMatch = pattern.match(/^(.+?)\s+from\s+(.+)$/i);
+  if (fromMatch) {
+    return { varName: fromMatch[1].trim(), scopeName: fromMatch[2].trim() };
+  }
+  return { varName: pattern.trim(), scopeName: null };
+}
+
+/**
+ * Find variables by name, optionally scoped to a function
+ */
+async function findVariables(
+  backend: RFDBServerBackend,
+  varName: string,
+  scopeName: string | null
+): Promise<NodeInfo[]> {
+  const results: NodeInfo[] = [];
+  const lowerScopeName = scopeName ? scopeName.toLowerCase() : null;
+
+  // Search VARIABLE, CONSTANT, PARAMETER
+  for (const nodeType of ['VARIABLE', 'CONSTANT', 'PARAMETER']) {
+    for await (const node of backend.queryNodes({ nodeType: nodeType as any })) {
+      const name = node.name || '';
+      if (name.toLowerCase() === varName.toLowerCase()) {
+        // If scope specified, check if variable is in that scope
+        if (scopeName) {
+          const parsed = parseSemanticId(node.id);
+          if (!parsed) continue; // Skip nodes with invalid IDs
+
+          // Check if scopeName appears anywhere in the scope chain
+          if (!parsed.scopePath.some(s => s.toLowerCase() === lowerScopeName)) {
+            continue;
+          }
+        }
+
+        results.push({
+          id: node.id,
+          type: node.type || nodeType,
+          name: name,
+          file: node.file || '',
+          line: node.line,
+        });
+
+        if (results.length >= 5) break;
+      }
+    }
+    if (results.length >= 5) break;
+  }
+
+  return results;
+}
+
+/**
+ * Trace backward through ASSIGNED_FROM edges
+ */
+async function traceBackward(
+  backend: RFDBServerBackend,
+  startId: string,
+  maxDepth: number
+): Promise<TraceStep[]> {
+  const trace: TraceStep[] = [];
+  const visited = new Set<string>();
+  const queue: Array<{ id: string; depth: number }> = [{ id: startId, depth: 0 }];
+
+  while (queue.length > 0) {
+    const { id, depth } = queue.shift()!;
+
+    if (visited.has(id) || depth > maxDepth) continue;
+    visited.add(id);
+
+    try {
+      const edges = await backend.getOutgoingEdges(id, ['ASSIGNED_FROM', 'DERIVES_FROM']);
+
+      for (const edge of edges) {
+        const targetNode = await backend.getNode(edge.dst);
+        if (!targetNode) continue;
+
+        const nodeInfo: NodeInfo = {
+          id: targetNode.id,
+          type: targetNode.type || 'UNKNOWN',
+          name: targetNode.name || '',
+          file: targetNode.file || '',
+          line: targetNode.line,
+          value: targetNode.value,
+        };
+
+        trace.push({
+          node: nodeInfo,
+          edgeType: edge.edgeType || edge.type,
+          depth: depth + 1,
+        });
+
+        // Continue tracing unless we hit a leaf
+        const leafTypes = ['LITERAL', 'PARAMETER', 'EXTERNAL_MODULE'];
+        if (!leafTypes.includes(nodeInfo.type)) {
+          queue.push({ id: targetNode.id, depth: depth + 1 });
+        }
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  return trace;
+}
+
+/**
+ * Trace forward - find what uses this variable
+ */
+async function traceForward(
+  backend: RFDBServerBackend,
+  startId: string,
+  maxDepth: number
+): Promise<TraceStep[]> {
+  const trace: TraceStep[] = [];
+  const visited = new Set<string>();
+  const queue: Array<{ id: string; depth: number }> = [{ id: startId, depth: 0 }];
+
+  while (queue.length > 0) {
+    const { id, depth } = queue.shift()!;
+
+    if (visited.has(id) || depth > maxDepth) continue;
+    visited.add(id);
+
+    try {
+      // Find nodes that get their value FROM this node
+      const edges = await backend.getIncomingEdges(id, ['ASSIGNED_FROM', 'DERIVES_FROM']);
+
+      for (const edge of edges) {
+        const sourceNode = await backend.getNode(edge.src);
+        if (!sourceNode) continue;
+
+        const nodeInfo: NodeInfo = {
+          id: sourceNode.id,
+          type: sourceNode.type || 'UNKNOWN',
+          name: sourceNode.name || '',
+          file: sourceNode.file || '',
+          line: sourceNode.line,
+        };
+
+        trace.push({
+          node: nodeInfo,
+          edgeType: edge.edgeType || edge.type,
+          depth: depth + 1,
+        });
+
+        // Continue forward
+        if (depth < maxDepth - 1) {
+          queue.push({ id: sourceNode.id, depth: depth + 1 });
+        }
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  return trace;
+}
+
+/**
+ * Get immediate value sources (for "possible values" display)
+ */
+async function getValueSources(
+  backend: RFDBServerBackend,
+  nodeId: string
+): Promise<NodeInfo[]> {
+  const sources: NodeInfo[] = [];
+
+  try {
+    const edges = await backend.getOutgoingEdges(nodeId, ['ASSIGNED_FROM']);
+
+    for (const edge of edges.slice(0, 5)) {
+      const node = await backend.getNode(edge.dst);
+      if (node) {
+        sources.push({
+          id: node.id,
+          type: node.type || 'UNKNOWN',
+          name: node.name || '',
+          file: node.file || '',
+          line: node.line,
+          value: node.value,
+        });
+      }
+    }
+  } catch {
+    // Ignore
+  }
+
+  return sources;
+}
+
+/**
+ * Display trace results with semantic IDs
+ */
+function displayTrace(trace: TraceStep[], _projectPath: string, indent: string): void {
+  // Group by depth
+  const byDepth = new Map<number, TraceStep[]>();
+  for (const step of trace) {
+    if (!byDepth.has(step.depth)) {
+      byDepth.set(step.depth, []);
+    }
+    byDepth.get(step.depth)!.push(step);
+  }
+
+  for (const [_depth, steps] of [...byDepth.entries()].sort((a, b) => a[0] - b[0])) {
+    for (const step of steps) {
+      const valueStr = step.node.value !== undefined ? ` = ${JSON.stringify(step.node.value)}` : '';
+      console.log(`${indent}<- ${step.node.name || step.node.type} (${step.node.type})${valueStr}`);
+      console.log(`${indent}   ${formatNodeInline(step.node)}`);
+    }
+  }
+}
+

package/src/utils/codePreview.ts

@@ -0,0 +1,77 @@
+/**
+ * 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';
+
+export interface CodePreviewOptions {
+  file: string;
+  line: number;
+  contextBefore?: number;  // default: 2
+  contextAfter?: number;   // default: 12
+}
+
+export interface CodePreviewResult {
+  lines: string[];
+  startLine: number;
+  endLine: number;
+}
+
+/**
+ * Get a code preview snippet from a source file.
+ * Returns lines around the specified line number with context.
+ */
+export function getCodePreview(options: CodePreviewOptions): CodePreviewResult | null {
+  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: CodePreviewResult,
+  highlightLine?: number
+): string[] {
+  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/src/utils/errorFormatter.ts

@@ -0,0 +1,35 @@
+/**
+ * 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: string, nextSteps?: string[]): never {
+  console.error(`✗ ${title}`);
+
+  if (nextSteps && nextSteps.length > 0) {
+    console.error('');
+    for (const step of nextSteps) {
+      console.error(`→ ${step}`);
+    }
+  }
+
+  process.exit(1);
+}

package/src/utils/formatNode.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 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 function formatNodeDisplay(node: DisplayableNode, options: FormatNodeOptions): string {
+  const { projectPath, showLocation = true, indent = '' } = options;
+  const lines: string[] = [];
+
+  // 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: DisplayableNode): string {
+  return node.id;
+}
+
+/**
+ * Format file location relative to project
+ */
+export function formatLocation(
+  file: string | undefined,
+  line: number | undefined,
+  projectPath: string
+): string {
+  if (!file) return '';
+  const relPath = relative(projectPath, file);
+  return line ? `${relPath}:${line}` : relPath;
+}