@grafema/cli 0.1.1-alpha → 0.2.1-beta

package/src/commands/explore.tsx

@@ -1,5 +1,11 @@
 /**
- * Explore command - Interactive TUI for graph navigation
+ * Explore command - Interactive TUI or batch mode for graph navigation
+ *
+ * Interactive mode: grafema explore [start]
+ * Batch mode:
+ *   grafema explore --query "functionName"
+ *   grafema explore --callers "functionName"
+ *   grafema explore --callees "functionName"
  */
 
 import { Command } from 'commander';
@@ -8,11 +14,22 @@ import { existsSync } from 'fs';
 import { execSync } from 'child_process';
 import React, { useState, useEffect } from 'react';
 import { render, Box, Text, useInput, useApp } from 'ink';
-import { RFDBServerBackend } from '@grafema/core';
+import { RFDBServerBackend, findContainingFunction as findContainingFunctionCore, findCallsInFunction as findCallsInFunctionCore } from '@grafema/core';
 import { getCodePreview, formatCodePreview } from '../utils/codePreview.js';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 // Types
+interface ExploreOptions {
+  project: string;
+  // Batch mode flags
+  query?: string;
+  callers?: string;
+  callees?: string;
+  depth?: string;
+  json?: boolean;
+  format?: 'json' | 'text';
+}
+
 interface NodeInfo {
   id: string;
   type: string;
@@ -769,11 +786,17 @@ async function getCallers(backend: RFDBServerBackend, nodeId: string, limit: num
       const callNode = await backend.getNode(edge.src);
       if (!callNode) continue;
 
-      const containingFunc = await findContainingFunction(backend, callNode.id);
+      const containingFunc = await findContainingFunctionCore(backend, callNode.id);
 
       if (containingFunc && !seen.has(containingFunc.id)) {
         seen.add(containingFunc.id);
-        callers.push(containingFunc);
+        callers.push({
+          id: containingFunc.id,
+          type: containingFunc.type,
+          name: containingFunc.name,
+          file: containingFunc.file || '',
+          line: containingFunc.line,
+        });
       }
     }
   } catch {
@@ -788,21 +811,22 @@ async function getCallees(backend: RFDBServerBackend, nodeId: string, limit: num
   const seen = new Set<string>();
 
   try {
-    const callNodes = await findCallsInFunction(backend, nodeId);
+    // Use shared utility from @grafema/core
+    const calls = await findCallsInFunctionCore(backend, nodeId);
 
-    for (const callNode of callNodes) {
+    for (const call of calls) {
       if (callees.length >= limit) break;
 
-      const callEdges = await backend.getOutgoingEdges(callNode.id, ['CALLS']);
-
-      for (const edge of callEdges) {
-        if (callees.length >= limit) break;
-
-        const targetNode = await backend.getNode(edge.dst);
-        if (!targetNode || seen.has(targetNode.id)) continue;
-
-        seen.add(targetNode.id);
-        callees.push(extractNodeInfo(targetNode));
+      // Only include resolved calls with targets
+      if (call.resolved && call.target && !seen.has(call.target.id)) {
+        seen.add(call.target.id);
+        callees.push({
+          id: call.target.id,
+          type: 'FUNCTION',
+          name: call.target.name || '',
+          file: call.target.file || '',
+          line: call.target.line,
+        });
       }
     }
   } catch {
@@ -812,82 +836,6 @@ async function getCallees(backend: RFDBServerBackend, nodeId: string, limit: num
   return callees;
 }
 
-async function findContainingFunction(backend: RFDBServerBackend, nodeId: string): Promise<NodeInfo | null> {
-  const visited = new Set<string>();
-  const queue: Array<{ id: string; depth: number }> = [{ id: nodeId, depth: 0 }];
-
-  while (queue.length > 0) {
-    const { id, depth } = queue.shift()!;
-    if (visited.has(id) || depth > 15) continue;
-    visited.add(id);
-
-    try {
-      const edges = await backend.getIncomingEdges(id, null);
-
-      for (const edge of edges) {
-        const edgeType = (edge as any).edgeType || (edge as any).type;
-        if (!['CONTAINS', 'HAS_SCOPE', 'DECLARES'].includes(edgeType)) continue;
-
-        const parent = await backend.getNode(edge.src);
-        if (!parent || visited.has(parent.id)) continue;
-
-        const parentType = (parent as any).type || (parent as any).nodeType;
-
-        if (parentType === 'FUNCTION' || parentType === 'CLASS' || parentType === 'MODULE') {
-          return extractNodeInfo(parent);
-        }
-
-        queue.push({ id: parent.id, depth: depth + 1 });
-      }
-    } catch {
-      // Ignore
-    }
-  }
-
-  return null;
-}
-
-async function findCallsInFunction(backend: RFDBServerBackend, nodeId: string): Promise<NodeInfo[]> {
-  const calls: NodeInfo[] = [];
-  const visited = new Set<string>();
-  const queue: Array<{ id: string; depth: number }> = [{ id: nodeId, depth: 0 }];
-
-  while (queue.length > 0) {
-    const { id, depth } = queue.shift()!;
-    if (visited.has(id) || depth > 10) continue;
-    visited.add(id);
-
-    try {
-      const edges = await backend.getOutgoingEdges(id, ['CONTAINS']);
-
-      for (const edge of edges) {
-        const child = await backend.getNode(edge.dst);
-        if (!child) continue;
-
-        const childType = (child as any).type || (child as any).nodeType;
-
-        if (childType === 'CALL') {
-          calls.push({
-            id: child.id,
-            type: 'CALL',
-            name: (child as any).name || '',
-            file: (child as any).file || '',
-            line: (child as any).line,
-          });
-        }
-
-        if (childType !== 'FUNCTION' && childType !== 'CLASS') {
-          queue.push({ id: child.id, depth: depth + 1 });
-        }
-      }
-    } catch {
-      // Ignore
-    }
-  }
-
-  return calls;
-}
-
 async function searchNode(backend: RFDBServerBackend, query: string): Promise<NodeInfo | null> {
   const results = await searchNodes(backend, query, 1);
   return results[0] || null;
@@ -1020,18 +968,199 @@ async function findStartNode(backend: RFDBServerBackend, startName: string | nul
   return bestNode;
 }
 
-// Command
+// =============================================================================
+// Batch Mode Implementation
+// =============================================================================
+
+/**
+ * Run explore in batch mode - for AI agents, CI, and scripts
+ */
+async function runBatchExplore(
+  backend: RFDBServerBackend,
+  options: ExploreOptions,
+  projectPath: string
+): Promise<void> {
+  const depth = parseInt(options.depth || '3', 10) || 3;
+  const useJson = options.json || options.format === 'json' || options.format !== 'text';
+
+  try {
+    if (options.query) {
+      // Search mode
+      const results = await searchNodes(backend, options.query, 20);
+      outputResults(results, 'search', useJson, projectPath);
+    } else if (options.callers) {
+      // Callers mode
+      const target = await searchNode(backend, options.callers);
+      if (!target) {
+        exitWithError(`Function "${options.callers}" not found`, [
+          'Try: grafema query "partial-name"',
+        ]);
+      }
+      const callers = await getCallersRecursive(backend, target.id, depth);
+      outputResults(callers, 'callers', useJson, projectPath, target);
+    } else if (options.callees) {
+      // Callees mode
+      const target = await searchNode(backend, options.callees);
+      if (!target) {
+        exitWithError(`Function "${options.callees}" not found`, [
+          'Try: grafema query "partial-name"',
+        ]);
+      }
+      const callees = await getCalleesRecursive(backend, target.id, depth);
+      outputResults(callees, 'callees', useJson, projectPath, target);
+    }
+  } catch (err) {
+    exitWithError(`Explore failed: ${(err as Error).message}`);
+  }
+}
+
+/**
+ * Output results in JSON or text format
+ */
+function outputResults(
+  nodes: NodeInfo[],
+  mode: 'search' | 'callers' | 'callees',
+  useJson: boolean,
+  projectPath: string,
+  target?: NodeInfo
+): void {
+  if (useJson) {
+    const output = {
+      mode,
+      target: target ? formatNodeForJson(target, projectPath) : undefined,
+      count: nodes.length,
+      results: nodes.map(n => formatNodeForJson(n, projectPath)),
+    };
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    // 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('');
+    }
+
+    if (nodes.length === 0) {
+      console.log(`  (no ${mode} found)`);
+    } else {
+      for (const node of nodes) {
+        const loc = relative(projectPath, node.file);
+        console.log(`  ${node.type} ${node.name} (${loc}${node.line ? `:${node.line}` : ''})`);
+      }
+    }
+
+    console.log('');
+    console.log(`Total: ${nodes.length}`);
+  }
+}
+
+function formatNodeForJson(node: NodeInfo, projectPath: string): object {
+  return {
+    id: node.id,
+    type: node.type,
+    name: node.name,
+    file: relative(projectPath, node.file),
+    line: node.line,
+    async: node.async,
+    exported: node.exported,
+  };
+}
+
+/**
+ * Get callers recursively up to specified depth
+ */
+async function getCallersRecursive(
+  backend: RFDBServerBackend,
+  nodeId: string,
+  maxDepth: number
+): Promise<NodeInfo[]> {
+  const results: NodeInfo[] = [];
+  const visited = new Set<string>();
+  const queue: Array<{ id: string; depth: number }> = [{ id: nodeId, depth: 0 }];
+
+  while (queue.length > 0) {
+    const { id, depth } = queue.shift()!;
+    if (visited.has(id) || depth > maxDepth) continue;
+    visited.add(id);
+
+    const callers = await getCallers(backend, id, 50);
+    for (const caller of callers) {
+      if (!visited.has(caller.id)) {
+        results.push(caller);
+        if (depth < maxDepth) {
+          queue.push({ id: caller.id, depth: depth + 1 });
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Get callees recursively up to specified depth
+ */
+async function getCalleesRecursive(
+  backend: RFDBServerBackend,
+  nodeId: string,
+  maxDepth: number
+): Promise<NodeInfo[]> {
+  const results: NodeInfo[] = [];
+  const visited = new Set<string>();
+  const queue: Array<{ id: string; depth: number }> = [{ id: nodeId, depth: 0 }];
+
+  while (queue.length > 0) {
+    const { id, depth } = queue.shift()!;
+    if (visited.has(id) || depth > maxDepth) continue;
+    visited.add(id);
+
+    const callees = await getCallees(backend, id, 50);
+    for (const callee of callees) {
+      if (!visited.has(callee.id)) {
+        results.push(callee);
+        if (depth < maxDepth) {
+          queue.push({ id: callee.id, depth: depth + 1 });
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+// =============================================================================
+// Command Definition
+// =============================================================================
+
 export const exploreCommand = new Command('explore')
-  .description('Interactive graph navigation')
-  .argument('[start]', 'Starting function name')
+  .description('Interactive graph navigation (TUI) or batch query mode')
+  .argument('[start]', 'Starting function name (for interactive mode)')
   .option('-p, --project <path>', 'Project path', '.')
-  .action(async (start: string | undefined, options: { project: string }) => {
+  .option('-q, --query <name>', 'Batch: search for nodes by name')
+  .option('--callers <name>', 'Batch: show callers of function')
+  .option('--callees <name>', 'Batch: show callees of function')
+  .option('-d, --depth <n>', 'Batch: traversal depth', '3')
+  .option('-j, --json', 'Output as JSON (default for batch mode)')
+  .option('--format <type>', 'Output format: json or text')
+  .addHelpText('after', `
+Examples:
+  grafema explore                        Interactive TUI mode
+  grafema explore "authenticate"         Start TUI at specific function
+  grafema explore --query "User"         Batch: search for nodes
+  grafema explore --callers "login"      Batch: show who calls login
+  grafema explore --callees "main"       Batch: show what main calls
+  grafema explore --callers "auth" -d 5  Batch: callers with depth 5
+  grafema explore --query "api" --format text   Batch: text output
+`)
+  .action(async (start: string | undefined, options: ExploreOptions) => {
     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']);
+      exitWithError('No database found', [
+        'Run: grafema analyze',
+      ]);
     }
 
     const backend = new RFDBServerBackend({ dbPath });
@@ -1039,6 +1168,27 @@ export const exploreCommand = new Command('explore')
     try {
       await backend.connect();
 
+      // Detect batch mode
+      const isBatchMode = !!(options.query || options.callers || options.callees);
+
+      if (isBatchMode) {
+        await runBatchExplore(backend, options, projectPath);
+        return;
+      }
+
+      // Interactive mode - check TTY
+      const isTTY = process.stdin.isTTY && process.stdout.isTTY;
+
+      if (!isTTY) {
+        exitWithError('Interactive mode requires a terminal', [
+          'Batch mode: grafema explore --query "functionName"',
+          'Batch mode: grafema explore --callers "functionName"',
+          'Batch mode: grafema explore --callees "functionName"',
+          'Alternative: grafema query "functionName"',
+          'Alternative: grafema impact "functionName"',
+        ]);
+      }
+
       const startNode = await findStartNode(backend, start || null);
 
       const { waitUntilExit } = render(

package/src/commands/get.ts

@@ -24,14 +24,16 @@ interface NodeInfo {
   name: string;
   file: string;
   line?: number;
+  method?: string;
+  path?: string;
+  url?: string;
   [key: string]: unknown;
 }
 
 interface Edge {
   src: string;
   dst: string;
-  edgeType: string;
-  type?: string;
+  type: string;
 }
 
 interface EdgeWithName {
@@ -45,6 +47,13 @@ export const getCommand = new Command('get')
   .argument('<semantic-id>', 'Semantic ID of the node (e.g., "file.js->scope->TYPE->name")')
   .option('-p, --project <path>', 'Project path', '.')
   .option('-j, --json', 'Output as JSON')
+  .addHelpText('after', `
+Examples:
+  grafema get "src/auth.js->authenticate->FUNCTION"      Get function node
+  grafema get "src/models/User.js->User->CLASS"          Get class node
+  grafema get "src/api.js->config->VARIABLE"             Get variable node
+  grafema get "src/auth.js->authenticate->FUNCTION" -j   Output as JSON with edges
+`)
   .action(async (semanticId: string, options: GetOptions) => {
     const projectPath = resolve(options.project);
     const grafemaDir = join(projectPath, '.grafema');
@@ -95,7 +104,7 @@ async function outputJSON(
   // Fetch target node names for all edges
   const incomingWithNames = await Promise.all(
     incomingEdges.map(async (edge) => ({
-      edgeType: edge.edgeType || edge.type || 'UNKNOWN',
+      edgeType: edge.type || 'UNKNOWN',
       targetId: edge.src,
       targetName: await getNodeName(backend, edge.src),
     }))
@@ -103,7 +112,7 @@ async function outputJSON(
 
   const outgoingWithNames = await Promise.all(
     outgoingEdges.map(async (edge) => ({
-      edgeType: edge.edgeType || edge.type || 'UNKNOWN',
+      edgeType: edge.type || 'UNKNOWN',
       targetId: edge.dst,
       targetName: await getNodeName(backend, edge.dst),
     }))
@@ -147,6 +156,9 @@ async function outputText(
     name: node.name || '',
     file: node.file || '',
     line: node.line,
+    method: node.method,
+    path: node.path,
+    url: node.url,
   };
 
   // Display node details
@@ -190,7 +202,7 @@ async function displayEdges(
   const byType = new Map<string, EdgeWithName[]>();
 
   for (const edge of edges) {
-    const edgeType = edge.edgeType || edge.type || 'UNKNOWN';
+    const edgeType = edge.type || 'UNKNOWN';
     const targetId = getTargetId(edge);
     const targetName = await getNodeName(backend, targetId);
 
@@ -246,11 +258,13 @@ async function getNodeName(backend: RFDBServerBackend, nodeId: string): Promise<
 }
 
 /**
- * Extract metadata fields (exclude standard fields)
+ * Extract metadata fields (exclude standard and display fields)
  */
 function getMetadataFields(node: any): Record<string, unknown> {
   const standardFields = new Set([
     'id', 'type', 'nodeType', 'name', 'file', 'line',
+    // Display fields shown in primary line for HTTP nodes
+    'method', 'path', 'url',
   ]);
 
   const metadata: Record<string, unknown> = {};

package/src/commands/impact.ts

@@ -10,7 +10,7 @@ import { Command } from 'commander';
 import { resolve, join, dirname } from 'path';
 import { relative } from 'path';
 import { existsSync } from 'fs';
-import { RFDBServerBackend } from '@grafema/core';
+import { RFDBServerBackend, findContainingFunction as findContainingFunctionCore, type CallerInfo } from '@grafema/core';
 import { formatNodeDisplay, formatNodeInline } from '../utils/formatNode.js';
 import { exitWithError } from '../utils/errorFormatter.js';
 
@@ -42,6 +42,14 @@ export const impactCommand = new Command('impact')
   .option('-p, --project <path>', 'Project path', '.')
   .option('-j, --json', 'Output as JSON')
   .option('-d, --depth <n>', 'Max traversal depth', '10')
+  .addHelpText('after', `
+Examples:
+  grafema impact "authenticate"          Analyze impact of changing authenticate
+  grafema impact "function login"        Impact of specific function
+  grafema impact "class UserService"     Impact of class changes
+  grafema impact "validate" -d 3         Limit analysis depth to 3 levels
+  grafema impact "auth" --json           Output impact analysis as JSON
+`)
   .action(async (pattern: string, options: ImpactOptions) => {
     const projectPath = resolve(options.project);
     const grafemaDir = join(projectPath, '.grafema');
@@ -159,10 +167,21 @@ async function analyzeImpact(
   const callChains: string[][] = [];
   const visited = new Set<string>();
 
+  // If target is a CLASS, aggregate callers from all methods
+  let targetIds: string[];
+  if (target.type === 'CLASS') {
+    const methodIds = await getClassMethods(backend, target.id);
+    targetIds = [target.id, ...methodIds];
+  } else {
+    targetIds = [target.id];
+  }
+
   // BFS to find all callers
-  const queue: Array<{ id: string; depth: number; chain: string[] }> = [
-    { id: target.id, depth: 0, chain: [target.name] }
-  ];
+  const queue: Array<{ id: string; depth: number; chain: string[] }> = targetIds.map(id => ({
+    id,
+    depth: 0,
+    chain: [target.name]
+  }));
 
   while (queue.length > 0) {
     const { id, depth, chain } = queue.shift()!;
@@ -179,14 +198,19 @@ async function analyzeImpact(
 
       for (const callNode of containingCalls) {
         // Find the function containing this call
-        const container = await findContainingFunction(backend, callNode.id);
+        const container = await findContainingFunctionCore(backend, callNode.id);
 
         if (container && !visited.has(container.id)) {
+          // Filter out internal callers (methods of the same class)
+          if (target.type === 'CLASS' && targetIds.includes(container.id)) {
+            continue;
+          }
+
           const caller: NodeInfo = {
             id: container.id,
             type: container.type,
             name: container.name,
-            file: container.file,
+            file: container.file || '',
             line: container.line,
           };
 
@@ -227,6 +251,31 @@ async function analyzeImpact(
   };
 }
 
+/**
+ * Get method IDs for a class
+ */
+async function getClassMethods(
+  backend: RFDBServerBackend,
+  classId: string
+): Promise<string[]> {
+  const methods: string[] = [];
+
+  try {
+    const edges = await backend.getOutgoingEdges(classId, ['CONTAINS']);
+
+    for (const edge of edges) {
+      const node = await backend.getNode(edge.dst);
+      if (node && node.type === 'FUNCTION') {
+        methods.push(node.id);
+      }
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  return methods;
+}
+
 /**
  * Find CALL nodes that reference a target
  */
@@ -259,61 +308,6 @@ async function findCallsToNode(
   return calls;
 }
 
-/**
- * Find the function that contains a call node
- *
- * Path: CALL → CONTAINS → SCOPE → CONTAINS → SCOPE → HAS_SCOPE → FUNCTION
- */
-async function findContainingFunction(
-  backend: RFDBServerBackend,
-  nodeId: string,
-  maxDepth: number = 15
-): Promise<NodeInfo | null> {
-  const visited = new Set<string>();
-  const queue: Array<{ id: string; depth: number }> = [{ id: nodeId, depth: 0 }];
-
-  while (queue.length > 0) {
-    const { id, depth } = queue.shift()!;
-
-    if (visited.has(id) || depth > maxDepth) continue;
-    visited.add(id);
-
-    try {
-      // Get incoming edges: CONTAINS, HAS_SCOPE
-      const edges = await backend.getIncomingEdges(id, null);
-
-      for (const edge of edges) {
-        const edgeType = (edge as any).edgeType || (edge as any).type;
-
-        // Only follow structural edges
-        if (!['CONTAINS', 'HAS_SCOPE', 'DECLARES'].includes(edgeType)) continue;
-
-        const parent = await backend.getNode(edge.src);
-        if (!parent || visited.has(parent.id)) continue;
-
-        const parentType = parent.type;
-
-        // FUNCTION, CLASS, or MODULE (for top-level calls)
-        if (parentType === 'FUNCTION' || parentType === 'CLASS' || parentType === 'MODULE') {
-          return {
-            id: parent.id,
-            type: parentType,
-            name: parent.name || '',
-            file: parent.file || '',
-            line: parent.line,
-          };
-        }
-
-        queue.push({ id: parent.id, depth: depth + 1 });
-      }
-    } catch {
-      // Ignore
-    }
-  }
-
-  return null;
-}
-
 /**
  * Get module path relative to project
  */