@grafema/cli 0.2.4-beta → 0.2.6-beta

package/src/commands/context.ts

@@ -0,0 +1,309 @@
+/**
+ * Context command — Show deep context for a graph node
+ *
+ * Displays the full graph neighborhood: source code + all incoming/outgoing edges
+ * with code context at each connected node's location.
+ *
+ * Works for ANY node type: FUNCTION, VARIABLE, MODULE, http:route, CALL, etc.
+ *
+ * Output is grep-friendly with stable prefixes:
+ *   -> outgoing edges
+ *   <- incoming edges
+ *   >  highlighted source lines
+ */
+
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
+import {
+  RFDBServerBackend,
+  buildNodeContext,
+  getNodeDisplayName,
+  formatEdgeMetadata,
+  STRUCTURAL_EDGE_TYPES,
+} from '@grafema/core';
+import type { NodeContext, EdgeGroup } from '@grafema/core';
+import type { BaseNodeRecord } from '@grafema/types';
+import { getCodePreview, formatCodePreview } from '../utils/codePreview.js';
+import { formatLocation } from '../utils/formatNode.js';
+import { exitWithError } from '../utils/errorFormatter.js';
+import { Spinner } from '../utils/spinner.js';
+
+interface ContextOptions {
+  project: string;
+  json?: boolean;
+  lines: string;
+  edgeType?: string;
+}
+
+/** Extended context with CLASS member expansion (REG-411) */
+interface ContextWithMembers extends NodeContext {
+  memberContexts?: NodeContext[];
+}
+
+export const contextCommand = new Command('context')
+  .description('Show deep context for a graph node: source code + graph neighborhood')
+  .argument('<semanticId>', 'Semantic ID of the node (exact match)')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-j, --json', 'Output as JSON (full dump, no filtering)')
+  .option('-l, --lines <n>', 'Context lines around each code reference', '3')
+  .option(
+    '-e, --edge-type <type>',
+    `Filter edges by type (e.g., CALLS, ASSIGNED_FROM, DEPENDS_ON)
+
+Multiple types can be comma-separated: --edge-type CALLS,ASSIGNED_FROM
+
+Examples:
+  grafema context <id> --edge-type CALLS
+  grafema context <id> -e DEPENDS_ON,IMPORTS_FROM`
+  )
+  .addHelpText('after', `
+Output format (grep-friendly):
+  ->  outgoing edge (this node points to)
+  <-  incoming edge (points to this node)
+  >   highlighted source line
+
+Examples:
+  grafema context "src/app.js->global->FUNCTION->main"
+  grafema context "http:route#POST#/api/users" --edge-type ROUTES_TO,HANDLED_BY
+  grafema context <id> --json
+  grafema context <id> | grep "CALLS"
+  grafema context <id> | grep "<-"
+`)
+  .action(async (semanticId: string, options: ContextOptions) => {
+    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();
+
+    const spinner = new Spinner('Loading context...');
+    spinner.start();
+
+    try {
+      const contextLines = parseInt(options.lines, 10);
+      const edgeTypeFilter = options.edgeType
+        ? new Set(options.edgeType.split(',').map(t => t.trim().toUpperCase()))
+        : null;
+
+      // 1. Look up node by exact semantic ID
+      const node = await backend.getNode(semanticId);
+      if (!node) {
+        spinner.stop();
+        exitWithError(`Node not found: "${semanticId}"`, [
+          'Use: grafema query "<name>" to find the correct semantic ID',
+        ]);
+      }
+
+      // 2. Build context (with CLASS member expansion)
+      const ctx = await buildContextWithMembers(backend, node, { contextLines, edgeTypeFilter });
+
+      spinner.stop();
+
+      // 3. Output
+      if (options.json) {
+        console.log(JSON.stringify(ctx, null, 2));
+      } else {
+        printContext(ctx, projectPath, contextLines);
+      }
+    } finally {
+      spinner.stop();
+      await backend.close();
+    }
+  });
+
+/**
+ * Build context with CLASS member expansion (REG-411)
+ */
+async function buildContextWithMembers(
+  backend: RFDBServerBackend,
+  node: BaseNodeRecord,
+  options: { contextLines: number; edgeTypeFilter: Set<string> | null },
+): Promise<ContextWithMembers> {
+  const ctx = await buildNodeContext(backend, node, options);
+
+  let memberContexts: NodeContext[] | undefined;
+  if (node.type === 'CLASS') {
+    const outEdges = await backend.getOutgoingEdges(node.id);
+    const containsEdges = outEdges.filter(e => e.type === 'CONTAINS');
+    const members: NodeContext[] = [];
+    for (const edge of containsEdges) {
+      const memberNode = await backend.getNode(edge.dst);
+      if (memberNode && (memberNode.type === 'FUNCTION' || memberNode.type === 'METHOD')) {
+        const memberCtx = await buildNodeContext(backend, memberNode, options);
+        members.push(memberCtx);
+      }
+    }
+    members.sort((a, b) => {
+      const lineA = (a.node.line as number | undefined) ?? 0;
+      const lineB = (b.node.line as number | undefined) ?? 0;
+      return lineA - lineB;
+    });
+    if (members.length > 0) {
+      memberContexts = members;
+    }
+  }
+
+  return { ...ctx, memberContexts };
+}
+
+/**
+ * Print context to stdout in grep-friendly format
+ */
+function printContext(ctx: ContextWithMembers, projectPath: string, contextLines: number): void {
+  const { node, source, outgoing, incoming } = ctx;
+
+  // Node header
+  const displayName = getNodeDisplayName(node);
+  console.log(`[${node.type}] ${displayName}`);
+  console.log(`  ID: ${node.id}`);
+
+  const loc = formatLocation(node.file, node.line as number | undefined, projectPath);
+  if (loc) {
+    console.log(`  Location: ${loc}`);
+  }
+
+  // Source code
+  if (source) {
+    console.log('');
+    console.log(`  Source (lines ${source.startLine}-${source.endLine}):`);
+    const formatted = formatCodePreview(
+      { lines: source.lines, startLine: source.startLine, endLine: source.endLine },
+      node.line as number | undefined,
+    );
+    for (const line of formatted) {
+      console.log(`    ${line}`);
+    }
+  }
+
+  // Outgoing edges
+  if (outgoing.length > 0) {
+    console.log('');
+    console.log('  Outgoing edges:');
+    for (const group of outgoing) {
+      printEdgeGroup(group, '->', projectPath, contextLines);
+    }
+  }
+
+  // Incoming edges
+  if (incoming.length > 0) {
+    console.log('');
+    console.log('  Incoming edges:');
+    for (const group of incoming) {
+      printEdgeGroup(group, '<-', projectPath, contextLines);
+    }
+  }
+
+  // Member methods (CLASS nodes)
+  if (ctx.memberContexts && ctx.memberContexts.length > 0) {
+    console.log('');
+    console.log(`  Methods (${ctx.memberContexts.length}):`);
+    for (const memberCtx of ctx.memberContexts) {
+      console.log('');
+      console.log(`  ── [${memberCtx.node.type}] ${getNodeDisplayName(memberCtx.node)}`);
+      const memberLoc = formatLocation(
+        memberCtx.node.file,
+        memberCtx.node.line as number | undefined,
+        projectPath,
+      );
+      if (memberLoc) {
+        console.log(`     Location: ${memberLoc}`);
+      }
+
+      // Method source code
+      if (memberCtx.source) {
+        console.log('');
+        console.log(`     Source (lines ${memberCtx.source.startLine}-${memberCtx.source.endLine}):`);
+        const formatted = formatCodePreview(
+          {
+            lines: memberCtx.source.lines,
+            startLine: memberCtx.source.startLine,
+            endLine: memberCtx.source.endLine,
+          },
+          memberCtx.node.line as number | undefined,
+        );
+        for (const line of formatted) {
+          console.log(`       ${line}`);
+        }
+      }
+
+      // Method edges (non-structural only, to avoid clutter)
+      const methodOutgoing = memberCtx.outgoing.filter(g => !STRUCTURAL_EDGE_TYPES.has(g.edgeType));
+      const methodIncoming = memberCtx.incoming.filter(g => !STRUCTURAL_EDGE_TYPES.has(g.edgeType));
+
+      if (methodOutgoing.length > 0) {
+        console.log('');
+        console.log('     Outgoing edges:');
+        for (const group of methodOutgoing) {
+          printEdgeGroup(group, '->', projectPath, contextLines, '       ');
+        }
+      }
+      if (methodIncoming.length > 0) {
+        console.log('');
+        console.log('     Incoming edges:');
+        for (const group of methodIncoming) {
+          printEdgeGroup(group, '<-', projectPath, contextLines, '       ');
+        }
+      }
+    }
+  }
+
+  // Summary if no edges and no members
+  if (outgoing.length === 0 && incoming.length === 0 && !ctx.memberContexts?.length) {
+    console.log('');
+    console.log('  No edges found.');
+  }
+}
+
+/**
+ * Print a group of edges with the same type
+ */
+function printEdgeGroup(
+  group: EdgeGroup,
+  direction: '->' | '<-',
+  projectPath: string,
+  contextLines: number,
+  indent = '    ',
+): void {
+  const isStructural = STRUCTURAL_EDGE_TYPES.has(group.edgeType);
+
+  console.log(`${indent}${group.edgeType} (${group.edges.length}):`);
+
+  for (const { edge, node } of group.edges) {
+    if (!node) {
+      const danglingId = direction === '->' ? edge.dst : edge.src;
+      console.log(`${indent}  ${direction} [dangling] ${danglingId}`);
+      continue;
+    }
+
+    const displayName = getNodeDisplayName(node);
+    const loc = formatLocation(node.file, node.line as number | undefined, projectPath);
+    const locStr = loc ? `  (${loc})` : '';
+
+    // Edge metadata inline (if present and useful)
+    const metaStr = formatEdgeMetadata(edge);
+
+    console.log(`${indent}  ${direction} [${node.type}] ${displayName}${locStr}${metaStr}`);
+
+    // Code context for non-structural edges
+    if (!isStructural && node.file && node.line && contextLines > 0) {
+      const preview = getCodePreview({
+        file: node.file,
+        line: node.line as number,
+        contextBefore: Math.min(contextLines, 2),
+        contextAfter: Math.min(contextLines, 2),
+      });
+      if (preview) {
+        const formatted = formatCodePreview(preview, node.line as number);
+        for (const line of formatted) {
+          console.log(`${indent}       ${line}`);
+        }
+      }
+    }
+  }
+}

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}`,
     };
   }
 }
@@ -525,7 +527,7 @@ export async function checkFreshness(
   try {
     await backend.connect();
     const freshnessChecker = new GraphFreshnessChecker();
-    const result = await freshnessChecker.checkFreshness(backend);
+    const result = await freshnessChecker.checkFreshness(backend, projectPath);
     await backend.close();
 
     if (result.isFresh) {
@@ -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}`,
     };
   }
 }

package/src/commands/explain.ts

@@ -15,6 +15,7 @@
 import { Command } from 'commander';
 import { resolve, join, relative, normalize } from 'path';
 import { existsSync, realpathSync } from 'fs';
+import { toRelativeDisplay } from '../utils/pathUtils.js';
 import { RFDBServerBackend, FileExplainer, type EnhancedNode } from '@grafema/core';
 import { exitWithError } from '../utils/errorFormatter.js';
 
@@ -85,8 +86,8 @@ If a file shows NOT_ANALYZED:
 
     try {
       const explainer = new FileExplainer(backend);
-      // Query with absolute path since graph stores absolute paths
-      const result = await explainer.explain(absoluteFilePath);
+      // Query with relative path since MODULE nodes store relative file paths
+      const result = await explainer.explain(relativeFilePath);
 
       // Override file in result for display purposes (show relative path)
       result.file = relativeFilePath;
@@ -166,7 +167,7 @@ function displayNode(node: EnhancedNode, type: string, projectPath: string): voi
 
   // Line 3: Location
   if (node.file) {
-    const relPath = relative(projectPath, node.file);
+    const relPath = toRelativeDisplay(node.file, projectPath);
     const loc = node.line ? `${relPath}:${node.line}` : relPath;
     console.log(`  Location: ${loc}`);
   }

package/src/commands/explore.tsx

@@ -9,7 +9,8 @@
  */
 
 import { Command } from 'commander';
-import { resolve, join, relative } from 'path';
+import { resolve, join } from 'path';
+import { toRelativeDisplay } from '../utils/pathUtils.js';
 import { existsSync } from 'fs';
 import { execSync } from 'child_process';
 import React, { useState, useEffect } from 'react';
@@ -160,9 +161,10 @@ function Explorer({ backend, startNode, projectPath }: ExplorerProps) {
           }));
         }
       } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
         setState(s => ({
           ...s,
-          error: (err as Error).message,
+          error: message,
           loading: false,
         }));
       }
@@ -233,6 +235,7 @@ function Explorer({ backend, startNode, projectPath }: ExplorerProps) {
           const preview = getCodePreview({
             file: state.currentNode.file,
             line: state.currentNode.line,
+            projectPath,
           });
           if (preview) {
             const formatted = formatCodePreview(preview, state.currentNode.line);
@@ -387,9 +390,10 @@ function Explorer({ backend, startNode, projectPath }: ExplorerProps) {
         error: results.length === 0 ? `No results for "${query}"` : null,
       }));
     } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
       setState(s => ({
         ...s,
-        error: (err as Error).message,
+        error: message,
         loading: false,
       }));
     }
@@ -408,9 +412,10 @@ function Explorer({ backend, startNode, projectPath }: ExplorerProps) {
         loading: false,
       }));
     } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
       setState(s => ({
         ...s,
-        error: (err as Error).message,
+        error: message,
         loading: false,
       }));
     }
@@ -418,7 +423,7 @@ function Explorer({ backend, startNode, projectPath }: ExplorerProps) {
 
   const formatLoc = (node: NodeInfo) => {
     if (!node.file) return '';
-    const rel = relative(projectPath, node.file);
+    const rel = toRelativeDisplay(node.file, projectPath);
     return node.line ? `${rel}:${node.line}` : rel;
   };
 
@@ -1010,7 +1015,8 @@ async function runBatchExplore(
       outputResults(callees, 'callees', useJson, projectPath, target);
     }
   } catch (err) {
-    exitWithError(`Explore failed: ${(err as Error).message}`);
+    const message = err instanceof Error ? err.message : String(err);
+    exitWithError(`Explore failed: ${message}`);
   }
 }
 
@@ -1036,7 +1042,7 @@ function outputResults(
     // Text format
     if (target) {
       console.log(`${mode === 'callers' ? 'Callers of' : 'Callees of'}: ${target.name}`);
-      console.log(`File: ${relative(projectPath, target.file)}${target.line ? `:${target.line}` : ''}`);
+      console.log(`File: ${toRelativeDisplay(target.file, projectPath)}${target.line ? `:${target.line}` : ''}`);
       console.log('');
     }
 
@@ -1044,7 +1050,7 @@ function outputResults(
       console.log(`  (no ${mode} found)`);
     } else {
       for (const node of nodes) {
-        const loc = relative(projectPath, node.file);
+        const loc = toRelativeDisplay(node.file, projectPath);
         console.log(`  ${node.type} ${node.name} (${loc}${node.line ? `:${node.line}` : ''})`);
       }
     }
@@ -1059,7 +1065,7 @@ function formatNodeForJson(node: NodeInfo, projectPath: string): object {
     id: node.id,
     type: node.type,
     name: node.name,
-    file: relative(projectPath, node.file),
+    file: toRelativeDisplay(node.file, projectPath),
     line: node.line,
     async: node.async,
     exported: node.exported,

package/src/commands/file.ts

@@ -0,0 +1,179 @@
+/**
+ * File command - Show structured overview of a file's entities and relationships
+ *
+ * Purpose: Give a file-level summary with imports, exports, classes, functions,
+ * and their key relationships (calls, extends, assigned-from).
+ *
+ * This fills the gap between:
+ * - explain (lists ALL nodes flat, no relationships)
+ * - context (shows ONE node's full neighborhood)
+ *
+ * @see REG-412
+ */
+
+import { Command } from 'commander';
+import { resolve, join, relative, normalize } from 'path';
+import { existsSync, realpathSync } from 'fs';
+import { RFDBServerBackend, FileOverview } from '@grafema/core';
+import type { FileOverviewResult, FunctionOverview } from '@grafema/core';
+import { exitWithError } from '../utils/errorFormatter.js';
+import { Spinner } from '../utils/spinner.js';
+
+interface FileOptions {
+  project: string;
+  json?: boolean;
+  edges?: boolean;
+}
+
+export const fileCommand = new Command('file')
+  .description(
+    'Show structured overview of a file: imports, exports, classes, functions with relationships'
+  )
+  .argument('<path>', 'File path to analyze')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-j, --json', 'Output as JSON')
+  .option('--no-edges', 'Skip edge resolution (faster, just list entities)')
+  .addHelpText('after', `
+Examples:
+  grafema file src/app.ts              Show file overview with relationships
+  grafema file src/app.ts --json       Output as JSON for scripting
+  grafema file src/app.ts --no-edges   Fast mode: just list entities
+  grafema file ./src/utils.js          Works with relative paths
+
+Output shows:
+  - Imports (module sources and specifiers)
+  - Exports (named and default)
+  - Classes with methods and their calls
+  - Functions with their calls
+  - Variables with assignment sources
+
+Use 'grafema context <id>' to dive deeper into any specific entity.
+`)
+  .action(async (file: string, options: FileOptions) => {
+    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 init && grafema analyze',
+      ]);
+    }
+
+    // Path resolution (same as explain command)
+    let filePath = file;
+
+    if (file.startsWith('./') || file.startsWith('../')) {
+      filePath = normalize(file).replace(/^\.\//, '');
+    } else if (resolve(file) === file) {
+      filePath = relative(projectPath, file);
+    }
+
+    const resolvedPath = resolve(projectPath, filePath);
+    if (!existsSync(resolvedPath)) {
+      exitWithError(`File not found: ${file}`, [
+        'Check the file path and try again',
+      ]);
+    }
+
+    const absoluteFilePath = realpathSync(resolvedPath);
+    const relativeFilePath = relative(projectPath, absoluteFilePath);
+
+    const backend = new RFDBServerBackend({ dbPath });
+    await backend.connect();
+
+    const spinner = new Spinner('Loading file overview...');
+    spinner.start();
+
+    try {
+      const overview = new FileOverview(backend);
+      const result = await overview.getOverview(relativeFilePath, {
+        includeEdges: options.edges !== false,
+      });
+
+      result.file = relativeFilePath;
+
+      spinner.stop();
+
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      printFileOverview(result);
+    } finally {
+      spinner.stop();
+      await backend.close();
+    }
+  });
+
+function printFileOverview(result: FileOverviewResult): void {
+  console.log(`Module: ${result.file}`);
+
+  if (result.status === 'NOT_ANALYZED') {
+    console.log('Status: NOT_ANALYZED');
+    console.log('');
+    console.log('This file has not been analyzed yet.');
+    console.log('Run: grafema analyze');
+    return;
+  }
+
+  if (result.imports.length > 0) {
+    const importSources = result.imports.map(i => i.source);
+    console.log(`Imports: ${importSources.join(', ')}`);
+  }
+
+  if (result.exports.length > 0) {
+    const exportNames = result.exports.map(e =>
+      e.isDefault ? `${e.name} (default)` : e.name
+    );
+    console.log(`Exports: ${exportNames.join(', ')}`);
+  }
+
+  if (result.classes.length > 0) {
+    console.log('');
+    console.log('Classes:');
+    for (const cls of result.classes) {
+      const extendsStr = cls.extends ? ` extends ${cls.extends}` : '';
+      const lineStr = cls.line ? ` (line ${cls.line})` : '';
+      console.log(`  ${cls.name}${extendsStr}${lineStr}`);
+
+      for (const method of cls.methods) {
+        printFunctionLine(method, '    ');
+      }
+    }
+  }
+
+  if (result.functions.length > 0) {
+    console.log('');
+    console.log('Functions:');
+    for (const fn of result.functions) {
+      printFunctionLine(fn, '  ');
+    }
+  }
+
+  if (result.variables.length > 0) {
+    console.log('');
+    console.log('Variables:');
+    for (const v of result.variables) {
+      const lineStr = v.line ? `(line ${v.line})` : '';
+      const assignStr = v.assignedFrom ? ` = ${v.assignedFrom}` : '';
+      console.log(`  ${v.kind} ${v.name}${assignStr}  ${lineStr}`);
+    }
+  }
+}
+
+function printFunctionLine(fn: FunctionOverview, indent: string): void {
+  const asyncStr = fn.async ? 'async ' : '';
+  const paramsStr = fn.params ? `(${fn.params.join(', ')})` : '()';
+  const lineStr = fn.line ? `(line ${fn.line})` : '';
+
+  let callsStr = '';
+  if (fn.calls.length > 0) {
+    callsStr = `  -> ${fn.calls.join(', ')}`;
+  }
+
+  console.log(
+    `${indent}${asyncStr}${fn.name}${paramsStr}${callsStr}  ${lineStr}`
+  );
+}