@grafema/cli 0.2.12-beta → 0.3.0-beta

package/src/commands/trace.ts

@@ -10,14 +10,15 @@
 import { Command } from 'commander';
 import { isAbsolute, resolve, join } from 'path';
 import { existsSync } from 'fs';
-import { RFDBServerBackend, parseSemanticId, parseSemanticIdV2, traceValues, type ValueSource } from '@grafema/core';
-import { formatNodeDisplay, formatNodeInline } from '../utils/formatNode.js';
+import { RFDBServerBackend, parseSemanticId, parseSemanticIdV2, traceValues, traceDataflow, renderTraceNarrative, type ValueSource, type DataflowBackend } from '@grafema/util';
+import { formatNodeDisplay } from '../utils/formatNode.js';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 interface TraceOptions {
   project: string;
   json?: boolean;
   depth: string;
+  detail?: 'summary' | 'normal' | 'full';
   to?: string;
   fromRoute?: string;
 }
@@ -73,11 +74,6 @@ interface NodeInfo {
   value?: unknown;
 }
 
-interface TraceStep {
-  node: NodeInfo;
-  edgeType: string;
-  depth: number;
-}
 
 export const traceCommand = new Command('trace')
   .description('Trace data flow for a variable or to a sink point')
@@ -85,6 +81,7 @@ export const traceCommand = new Command('trace')
   .option('-p, --project <path>', 'Project path', '.')
   .option('-j, --json', 'Output as JSON')
   .option('-d, --depth <n>', 'Max trace depth', '10')
+  .option('--detail <level>', 'Level of detail: summary, normal (default), full', 'normal')
   .option('-t, --to <sink>', 'Sink point: "fn#argIndex.property" (e.g., "addNode#0.type")')
   .option('-r, --from-route <pattern>', 'Trace from route response (e.g., "GET /status" or "/status")')
   .addHelpText('after', `
@@ -92,6 +89,7 @@ Examples:
   grafema trace "userId"                     Trace all variables named "userId"
   grafema trace "userId from authenticate"   Trace userId within authenticate function
   grafema trace "config" --depth 5           Limit trace depth to 5 levels
+  grafema trace "config" --detail full       Show complete chain (no compression)
   grafema trace "apiKey" --json              Output trace as JSON
   grafema trace --to "addNode#0.type"        Trace values reaching sink point
   grafema trace --from-route "GET /status"   Trace values from route response
@@ -106,7 +104,7 @@ Examples:
       exitWithError('No graph database found', ['Run: grafema analyze']);
     }
 
-    const backend = new RFDBServerBackend({ dbPath });
+    const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
     await backend.connect();
 
     try {
@@ -143,27 +141,23 @@ Examples:
         return;
       }
 
-      // Trace each variable
+      // Cast backend to DataflowBackend (runtime-compatible)
+      const dfDb = backend as unknown as DataflowBackend;
+
+      // Trace each variable using shared BFS
       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);
+        const results = await traceDataflow(dfDb, variable.id, {
+          direction: 'both',
+          maxDepth,
+        });
 
-        if (forwardTrace.length > 0) {
-          console.log('');
-          console.log('Data sinks (where value flows to):');
-          displayTrace(forwardTrace, projectPath, '  ');
-        }
+        const narrative = renderTraceNarrative(results, variable.name || variable.id, {
+          detail: options.detail || 'normal',
+        });
+        console.log(narrative);
 
         // Show value domain if available
         const sources = await getValueSources(backend, variable.id);
@@ -262,121 +256,6 @@ async function findVariables(
   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 seenNodes = 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;
-
-        if (seenNodes.has(targetNode.id)) continue;
-        seenNodes.add(targetNode.id);
-
-        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.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 seenNodes = 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;
-
-        if (seenNodes.has(sourceNode.id)) continue;
-        seenNodes.add(sourceNode.id);
-
-        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.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)
  */
@@ -409,27 +288,6 @@ async function getValueSources(
   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)}`);
-    }
-  }
-}
 
 // =============================================================================
 // SINK-BASED TRACE IMPLEMENTATION (REG-230)
@@ -596,7 +454,7 @@ async function extractProperty(
 
 /**
  * Trace a node to its literal values.
- * Uses shared traceValues utility from @grafema/core (REG-244).
+ * Uses shared traceValues utility from @grafema/util (REG-244).
  *
  * @param backend - RFDBServerBackend for graph queries
  * @param nodeId - Starting node ID

package/src/commands/types.ts

@@ -11,7 +11,7 @@
 import { Command } from 'commander';
 import { resolve, join } from 'path';
 import { existsSync } from 'fs';
-import { RFDBServerBackend } from '@grafema/core';
+import { RFDBServerBackend } from '@grafema/util';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 interface TypesOptions {
@@ -45,7 +45,7 @@ Use with query --type:
       exitWithError('No graph database found', ['Run: grafema analyze']);
     }
 
-    const backend = new RFDBServerBackend({ dbPath });
+    const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
     await backend.connect();
 
     try {

package/src/commands/who.ts

@@ -0,0 +1,215 @@
+/**
+ * who command — "Who uses this?"
+ *
+ * Find all callers and references to a symbol.
+ *
+ * Usage:
+ *   grafema who authenticate          # Who calls authenticate()?
+ *   grafema who UserService.findById  # Who calls this method?
+ */
+
+import { Command } from 'commander';
+import { resolve, join, isAbsolute, relative } from 'path';
+import { existsSync } from 'fs';
+import { RFDBServerBackend } from '@grafema/util';
+import { exitWithError } from '../utils/errorFormatter.js';
+import { Spinner } from '../utils/spinner.js';
+
+interface WhoCommandOptions {
+  project: string;
+  json?: boolean;
+}
+
+interface CallerInfo {
+  file: string;
+  line: number | undefined;
+  callerName: string;
+  resolved: boolean;
+}
+
+export const whoCommand = new Command('who')
+  .description('Who uses this? — find all callers/references to a symbol')
+  .argument('<symbol>', 'Function or method name')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-j, --json', 'Output as JSON')
+  .addHelpText('after', `
+Examples:
+  grafema who authenticate          Who calls authenticate()?
+  grafema who UserService.findById  Who calls this method?
+  grafema who handleRequest --json  Output as JSON
+`)
+  .action(async (symbol: string, options: WhoCommandOptions) => {
+    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, clientName: 'cli' });
+    await backend.connect();
+
+    const spinner = new Spinner('Searching for callers...');
+    spinner.start();
+
+    try {
+      const lowerSymbol = symbol.toLowerCase();
+      // If symbol has a dot, extract the part after the last dot for method matching
+      const dotIndex = symbol.lastIndexOf('.');
+      const methodPart = dotIndex >= 0 ? symbol.substring(dotIndex + 1).toLowerCase() : null;
+
+      // Strategy 1: Find CALL nodes that match the symbol name
+      // (same approach as MCP handleFindCalls)
+      const matchingCalls: CallerInfo[] = [];
+
+      for await (const node of backend.queryNodes({ type: 'CALL' as any })) {
+        const callName = (node.name || '').toLowerCase();
+
+        // Match exact name or method part after last dot
+        let isMatch = callName === lowerSymbol;
+        if (!isMatch && methodPart) {
+          const callMethodPart = callName.lastIndexOf('.') >= 0
+            ? callName.substring(callName.lastIndexOf('.') + 1)
+            : callName;
+          isMatch = callMethodPart === methodPart;
+        }
+        if (!isMatch && !methodPart) {
+          // Also match if the call name ends with the symbol (e.g., "obj.authenticate" matches "authenticate")
+          const callMethodPart = callName.lastIndexOf('.') >= 0
+            ? callName.substring(callName.lastIndexOf('.') + 1)
+            : null;
+          if (callMethodPart === lowerSymbol) isMatch = true;
+        }
+
+        if (!isMatch) continue;
+
+        // Check resolution status via CALLS edges
+        const edges = await backend.getOutgoingEdges(node.id, ['CALLS']);
+        const resolved = edges.length > 0;
+
+        // Extract caller name from semantic ID
+        // Format: "file->SCOPE->TYPE->name" — parent scope is the caller
+        const idParts = node.id.split('->');
+        let callerName = '<anonymous>';
+        // Walk up the scope chain to find a FUNCTION or METHOD parent
+        for (let i = idParts.length - 3; i >= 1; i--) {
+          if (idParts[i] === 'FUNCTION' || idParts[i] === 'METHOD') {
+            callerName = idParts[i + 1] || callerName;
+            break;
+          }
+        }
+
+        const file = node.file || '';
+
+        matchingCalls.push({
+          file,
+          line: node.line,
+          callerName,
+          resolved,
+        });
+      }
+
+      // Strategy 2: Find the target function/method node and check incoming CALLS/READS_FROM edges
+      const incomingCallers: CallerInfo[] = [];
+      let funcNode = null;
+
+      // Search for FUNCTION, METHOD, CLASS, or CONSTANT node matching the symbol
+      for (const nodeType of ['FUNCTION', 'METHOD', 'CLASS', 'CONSTANT'] as const) {
+        for await (const n of backend.queryNodes({ type: nodeType })) {
+          const name = (n.name || '').toLowerCase();
+          if (name === lowerSymbol || (methodPart && name === methodPart)) {
+            funcNode = n;
+            break;
+          }
+        }
+        if (funcNode) break;
+      }
+
+      if (funcNode) {
+        const incomingEdges = await backend.getIncomingEdges(funcNode.id, ['CALLS', 'READS_FROM', 'IMPORTS_FROM']);
+        for (const edge of incomingEdges) {
+          const srcNode = await backend.getNode(edge.src);
+          if (!srcNode) continue;
+
+          // Deduplicate — skip if we already found this call via Strategy 1
+          if (matchingCalls.some(c => c.file === (srcNode.file || '') && c.line === srcNode.line)) {
+            continue;
+          }
+
+          incomingCallers.push({
+            file: srcNode.file || '',
+            line: srcNode.line,
+            callerName: srcNode.name || '<anonymous>',
+            resolved: true,
+          });
+        }
+      }
+
+      // Strategy 3: Find IMPORT_BINDING nodes that import this symbol
+      // (for classes/exports that are imported across files/repos)
+      const importers: CallerInfo[] = [];
+      for await (const n of backend.queryNodes({ type: 'IMPORT_BINDING' as any })) {
+        const bindingName = (n.name || '').toLowerCase();
+        if (bindingName !== lowerSymbol && !(methodPart && bindingName === methodPart)) continue;
+
+        // Skip if already found via Strategy 1 or 2
+        if (matchingCalls.some(c => c.file === (n.file || '') && c.line === n.line)) continue;
+        if (incomingCallers.some(c => c.file === (n.file || '') && c.line === n.line)) continue;
+
+        importers.push({
+          file: n.file || '',
+          line: n.line,
+          callerName: `imports ${n.name || symbol}`,
+          resolved: true,
+        });
+      }
+
+      spinner.stop();
+
+      // Merge results
+      const allCallers = [...matchingCalls, ...incomingCallers, ...importers];
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          symbol,
+          targetNode: funcNode ? { id: funcNode.id, type: funcNode.type, name: funcNode.name, file: funcNode.file } : null,
+          callers: allCallers.map(c => ({
+            file: c.file,
+            line: c.line,
+            caller: c.callerName,
+            resolved: c.resolved,
+          })),
+          total: allCallers.length,
+        }, null, 2));
+        return;
+      }
+
+      if (allCallers.length === 0) {
+        console.log(`${symbol} — no callers found`);
+        console.log('');
+        console.log('Hints:');
+        console.log('  - Check the symbol name is correct');
+        console.log('  - The function may be exported but unused in analyzed code');
+        console.log('  - Use: grafema query "<name>" to verify the symbol exists');
+        return;
+      }
+
+      console.log(`${symbol} — ${allCallers.length} caller${allCallers.length === 1 ? '' : 's'}`);
+      console.log('');
+
+      for (const caller of allCallers) {
+        const relFile = isAbsolute(caller.file)
+          ? relative(projectPath, caller.file)
+          : caller.file;
+        const location = caller.line ? `${relFile}:${caller.line}` : relFile;
+        const status = caller.resolved ? '[resolved]' : '[unresolved]';
+        const paddedLocation = location.padEnd(30);
+        const paddedCaller = caller.callerName.padEnd(20);
+        console.log(`  ${paddedLocation} ${paddedCaller} ${status}`);
+      }
+    } finally {
+      spinner.stop();
+      await backend.close();
+    }
+  });

package/src/commands/why.ts

@@ -0,0 +1,134 @@
+/**
+ * why command — "Why is it this way?"
+ *
+ * Query knowledge base for architectural decisions and facts about a symbol or module.
+ *
+ * Usage:
+ *   grafema why auth-middleware       # Why was auth middleware designed this way?
+ *   grafema why UserService           # Decisions about UserService
+ */
+
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
+import { KnowledgeBase } from '@grafema/util';
+import type { KBDecision, KBFact } from '@grafema/util';
+import { exitWithError } from '../utils/errorFormatter.js';
+import { Spinner } from '../utils/spinner.js';
+
+interface WhyCommandOptions {
+  project: string;
+  json?: boolean;
+}
+
+export const whyCommand = new Command('why')
+  .description('Why is it this way? — query knowledge base decisions and facts')
+  .argument('<query>', 'Search text (symbol name, module, or topic)')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-j, --json', 'Output as JSON')
+  .addHelpText('after', `
+Examples:
+  grafema why auth-middleware       Why was auth middleware designed this way?
+  grafema why UserService           Decisions about UserService
+  grafema why "error handling"      Facts about error handling approach
+  grafema why dataflow --json       Output as JSON
+`)
+  .action(async (query: string, options: WhyCommandOptions) => {
+    const projectPath = resolve(options.project);
+    const knowledgeDir = join(projectPath, 'knowledge');
+
+    if (!existsSync(knowledgeDir)) {
+      exitWithError('No knowledge base found', [
+        'Knowledge directory not found: ' + knowledgeDir,
+        'Use `add_knowledge` MCP tool to capture architectural decisions',
+      ]);
+    }
+
+    const spinner = new Spinner('Searching knowledge base...');
+    spinner.start();
+
+    try {
+      const kb = new KnowledgeBase(knowledgeDir);
+      await kb.load();
+
+      // Search DECISION nodes matching query text
+      const decisions = await kb.queryNodes({ type: 'DECISION', text: query }) as KBDecision[];
+
+      // Search FACT nodes matching query text
+      const facts = await kb.queryNodes({ type: 'FACT', text: query }) as KBFact[];
+
+      spinner.stop();
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          query,
+          decisions: decisions.map(d => ({
+            id: d.id,
+            status: d.status,
+            content: d.content,
+            applies_to: d.applies_to,
+            relates_to: d.relates_to,
+          })),
+          facts: facts.map(f => ({
+            id: f.id,
+            confidence: f.confidence,
+            content: f.content,
+            relates_to: f.relates_to,
+          })),
+          total: decisions.length + facts.length,
+        }, null, 2));
+        return;
+      }
+
+      if (decisions.length === 0 && facts.length === 0) {
+        console.log(`No knowledge found for: "${query}"`);
+        console.log('');
+        console.log('No decisions or facts recorded matching this query.');
+        console.log('Use `add_knowledge` MCP tool to capture architectural decisions.');
+        return;
+      }
+
+      // Display decisions
+      if (decisions.length > 0) {
+        console.log(`Decisions (${decisions.length}):`);
+        console.log('');
+        for (const d of decisions) {
+          console.log(`  [${d.status?.toUpperCase() || 'ACTIVE'}] ${d.id}`);
+          // Show first ~200 chars of content as summary
+          const summary = d.content.length > 200
+            ? d.content.substring(0, 200) + '...'
+            : d.content;
+          // Indent content lines
+          for (const line of summary.split('\n')) {
+            console.log(`    ${line}`);
+          }
+          if (d.applies_to && d.applies_to.length > 0) {
+            console.log(`    Applies to: ${d.applies_to.join(', ')}`);
+          }
+          console.log('');
+        }
+      }
+
+      // Display facts
+      if (facts.length > 0) {
+        console.log(`Facts (${facts.length}):`);
+        console.log('');
+        for (const f of facts) {
+          const confidence = f.confidence ? ` [${f.confidence}]` : '';
+          console.log(`  ${f.id}${confidence}`);
+          const summary = f.content.length > 200
+            ? f.content.substring(0, 200) + '...'
+            : f.content;
+          for (const line of summary.split('\n')) {
+            console.log(`    ${line}`);
+          }
+          if (f.relates_to && f.relates_to.length > 0) {
+            console.log(`    Relates to: ${f.relates_to.join(', ')}`);
+          }
+          console.log('');
+        }
+      }
+    } finally {
+      spinner.stop();
+    }
+  });