@grafema/util 0.3.0-beta

package/src/queries/NodeContext.ts

@@ -0,0 +1,280 @@
+/**
+ * Node Context — shared data logic for building node neighborhood context
+ *
+ * Extracts source code preview and all incoming/outgoing edges
+ * for a given node, grouped by edge type.
+ *
+ * Used by CLI (grafema context) and MCP (get_context tool).
+ * Consumers handle their own formatting; this module provides data only.
+ *
+ * @module queries/NodeContext
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import type { BaseNodeRecord, EdgeRecord } from '@grafema/types';
+
+// ---------------------------------------------------------------------------
+// Minimal backend interface (matches project pattern — loose coupling)
+// ---------------------------------------------------------------------------
+
+interface GraphBackend {
+  getNode(id: string): Promise<BaseNodeRecord | null>;
+  getOutgoingEdges(
+    nodeId: string,
+    edgeTypes?: string[] | null,
+  ): Promise<EdgeRecord[]>;
+  getIncomingEdges(
+    nodeId: string,
+    edgeTypes?: string[] | null,
+  ): Promise<EdgeRecord[]>;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Edge types that are structural/containment — shown in compact form.
+ * These describe HOW code is nested, not WHAT it does.
+ */
+export const STRUCTURAL_EDGE_TYPES = new Set([
+  'CONTAINS',
+  'HAS_SCOPE',
+  'DECLARES',
+  'DEFINES',
+  'HAS_CONDITION',
+  'HAS_CASE',
+  'HAS_DEFAULT',
+  'HAS_CONSEQUENT',
+  'HAS_ALTERNATE',
+  'HAS_BODY',
+  'HAS_INIT',
+  'HAS_UPDATE',
+  'HAS_CATCH',
+  'HAS_FINALLY',
+  'HAS_PARAMETER',
+  'HAS_PROPERTY',
+  'HAS_ELEMENT',
+  'USES',
+  'GOVERNS',
+  'VIOLATES',
+  'AFFECTS',
+  'UNKNOWN',
+]);
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface EdgeWithNode {
+  edge: EdgeRecord;
+  node: BaseNodeRecord | null;
+}
+
+export interface EdgeGroup {
+  edgeType: string;
+  edges: EdgeWithNode[];
+}
+
+export interface SourcePreview {
+  file: string;
+  startLine: number;
+  endLine: number;
+  lines: string[];
+}
+
+export interface NodeContext {
+  node: BaseNodeRecord;
+  source: SourcePreview | null;
+  outgoing: EdgeGroup[];
+  incoming: EdgeGroup[];
+}
+
+export interface BuildNodeContextOptions {
+  /** Lines of context before the highlighted line (default: 3) */
+  contextLines?: number;
+  /** Filter to only these edge types (null = show all) */
+  edgeTypeFilter?: Set<string> | null;
+  /**
+   * DI callback for reading file content.
+   * Return file content as string, or null if file can't be read.
+   * Default uses fs.readFileSync.
+   */
+  readFileContent?: (filePath: string) => string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Default file reader
+// ---------------------------------------------------------------------------
+
+function defaultReadFileContent(filePath: string): string | null {
+  if (!existsSync(filePath)) return null;
+  try {
+    return readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core function
+// ---------------------------------------------------------------------------
+
+/**
+ * Build full node context: source preview + all edges with connected nodes.
+ *
+ * @param backend  - Graph backend for queries
+ * @param node     - The node to build context for (already looked up by caller)
+ * @param options  - Context options
+ * @returns NodeContext with source preview and grouped edges
+ */
+export async function buildNodeContext(
+  backend: GraphBackend,
+  node: BaseNodeRecord,
+  options: BuildNodeContextOptions = {},
+): Promise<NodeContext> {
+  const {
+    contextLines = 3,
+    edgeTypeFilter = null,
+    readFileContent = defaultReadFileContent,
+  } = options;
+
+  // Source code preview
+  let source: SourcePreview | null = null;
+  if (node.file && node.line) {
+    const content = readFileContent(node.file);
+    if (content) {
+      const allLines = content.split('\n');
+      const line = node.line as number;
+      const startLine = Math.max(1, line - contextLines);
+      const endLine = Math.min(allLines.length, line + contextLines + 12);
+      source = {
+        file: node.file,
+        startLine,
+        endLine,
+        lines: allLines.slice(startLine - 1, endLine),
+      };
+    }
+  }
+
+  // Outgoing edges
+  const rawOutgoing = await backend.getOutgoingEdges(node.id);
+  const outgoing = await groupEdges(backend, rawOutgoing, 'dst', edgeTypeFilter);
+
+  // Incoming edges
+  const rawIncoming = await backend.getIncomingEdges(node.id);
+  const incoming = await groupEdges(backend, rawIncoming, 'src', edgeTypeFilter);
+
+  return { node, source, outgoing, incoming };
+}
+
+// ---------------------------------------------------------------------------
+// Edge grouping
+// ---------------------------------------------------------------------------
+
+/**
+ * Group edges by type and resolve connected nodes.
+ *
+ * Sort order: non-structural edges first (alphabetical),
+ * then structural edges (alphabetical).
+ */
+async function groupEdges(
+  backend: GraphBackend,
+  edges: EdgeRecord[],
+  nodeField: 'src' | 'dst',
+  edgeTypeFilter: Set<string> | null,
+): Promise<EdgeGroup[]> {
+  const groups = new Map<string, EdgeWithNode[]>();
+
+  for (const edge of edges) {
+    const edgeType = edge.type || 'UNKNOWN';
+
+    // Apply edge type filter
+    if (edgeTypeFilter && !edgeTypeFilter.has(edgeType)) continue;
+
+    const connectedId = edge[nodeField];
+    const connectedNode = await backend.getNode(connectedId);
+
+    if (!groups.has(edgeType)) {
+      groups.set(edgeType, []);
+    }
+    groups.get(edgeType)!.push({ edge, node: connectedNode });
+  }
+
+  // Sort groups: primary edges first, then structural
+  return Array.from(groups.entries())
+    .sort(([a], [b]) => {
+      const aStructural = STRUCTURAL_EDGE_TYPES.has(a);
+      const bStructural = STRUCTURAL_EDGE_TYPES.has(b);
+      if (aStructural !== bStructural) return aStructural ? 1 : -1;
+      return a.localeCompare(b);
+    })
+    .map(([edgeType, edgeList]) => ({ edgeType, edges: edgeList }));
+}
+
+// ---------------------------------------------------------------------------
+// Display helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Get display name for a node based on its type.
+ *
+ * Special cases:
+ * - HTTP routes: "METHOD /path"
+ * - HTTP requests: "METHOD url"
+ * - Socket.IO: event name
+ * - Default: node.name or node.id
+ */
+export function getNodeDisplayName(node: BaseNodeRecord): string {
+  // HTTP nodes: method + path/url
+  if (node.type === 'http:route') {
+    const method = node.method as string | undefined;
+    const path = node.path as string | undefined;
+    if (method && path) return `${method} ${path}`;
+  }
+  if (node.type === 'http:request') {
+    const method = node.method as string | undefined;
+    const url = node.url as string | undefined;
+    if (method && url) return `${method} ${url}`;
+  }
+
+  // Socket.IO: event name
+  if (node.type === 'socketio:emit' || node.type === 'socketio:on') {
+    const event = node.event as string | undefined;
+    if (event) return event;
+  }
+
+  // Anonymous arrows/expressions → λ
+  if (node.name === '<arrow>' || node.name === '<expression>') return 'λ';
+
+  // Default: name or ID fallback
+  if (node.name && !node.name.startsWith('{')) return node.name;
+  return node.id;
+}
+
+/**
+ * Format edge metadata for inline display (only meaningful fields).
+ *
+ * Returns a string like "  [arg0]" or "" if no relevant metadata.
+ */
+export function formatEdgeMetadata(edge: EdgeRecord): string {
+  const parts: string[] = [];
+  const meta = edge.metadata || {};
+
+  if (edge.type === 'PASSES_ARGUMENT' || edge.type === 'RECEIVES_ARGUMENT') {
+    if ('argIndex' in meta) {
+      parts.push(`arg${meta.argIndex}`);
+    }
+  }
+  if (edge.type === 'FLOWS_INTO') {
+    if ('mutationMethod' in meta) parts.push(`via ${meta.mutationMethod}`);
+  }
+  if (edge.type === 'HAS_PROPERTY') {
+    if ('propertyName' in meta) parts.push(`key: ${meta.propertyName}`);
+  }
+  if (edge.type === 'ITERATES_OVER') {
+    if ('iterates' in meta) parts.push(`${meta.iterates}`);
+  }
+
+  return parts.length > 0 ? `  [${parts.join(', ')}]` : '';
+}

package/src/queries/findCallsInFunction.ts

@@ -0,0 +1,249 @@
+/**
+ * Find all CALL and METHOD_CALL nodes inside a function.
+ *
+ * Supports two graph layouts:
+ *
+ * Layout A (scope chain — legacy JS analyzer):
+ * ```
+ * FUNCTION -[HAS_SCOPE]-> SCOPE -[CONTAINS]-> CALL
+ *                         SCOPE -[CONTAINS]-> METHOD_CALL
+ *                         SCOPE -[CONTAINS]-> SCOPE (nested blocks)
+ * ```
+ *
+ * Layout B (direct edges — Rust orchestrator):
+ * ```
+ * FUNCTION -[AWAITS|RETURNS|THROWS|...]--> CALL / METHOD_CALL
+ * ```
+ * The orchestrator links functions directly to their call nodes via
+ * semantic edge types (AWAITS for async calls, RETURNS for return
+ * expressions, THROWS for throw expressions, etc.).
+ *
+ * Algorithm:
+ * 1. Try HAS_SCOPE path first (Layout A)
+ * 2. If no HAS_SCOPE edges, fall back to direct edges (Layout B):
+ *    collect all outgoing edges, keep those targeting CALL/METHOD_CALL nodes
+ * 3. For each call, check CALLS edge to determine if resolved
+ * 4. If transitive=true, recursively follow resolved CALLS edges
+ *
+ * Performance: O(S + C) where S = scopes, C = calls
+ * For functions with 100 calls, expect ~200 DB operations.
+ *
+ * @module queries/findCallsInFunction
+ */
+
+import type { CallInfo, FindCallsOptions } from './types.js';
+
+/**
+ * Graph backend interface (minimal surface)
+ */
+interface GraphBackend {
+  getNode(id: string): Promise<{
+    id: string;
+    type: string;
+    name?: string;
+    file?: string;
+    line?: number;
+    object?: string;
+  } | null>;
+  getOutgoingEdges(
+    nodeId: string,
+    edgeTypes: string[] | null
+  ): Promise<Array<{ src: string; dst: string; type: string }>>;
+}
+
+/**
+ * Maximum BFS depth for downward scope traversal.
+ *
+ * Each depth level = one CONTAINS hop through nested scopes.
+ * Typical function bodies: 2-5 scope levels (if → loop → try → ...).
+ * Set to 10 to cover deep nesting while bounding traversal in malformed graphs.
+ */
+const DEFAULT_MAX_SCOPE_DEPTH = 10;
+
+/**
+ * Find all CALL and METHOD_CALL nodes inside a function.
+ *
+ * @param backend - Graph backend for queries
+ * @param functionId - ID of the FUNCTION node
+ * @param options - Options for traversal
+ * @returns Array of CallInfo objects
+ */
+export async function findCallsInFunction(
+  backend: GraphBackend,
+  functionId: string,
+  options: FindCallsOptions = {}
+): Promise<CallInfo[]> {
+  const {
+    maxDepth = DEFAULT_MAX_SCOPE_DEPTH,
+    transitive = false,
+    transitiveDepth = 5,
+  } = options;
+
+  const calls: CallInfo[] = [];
+  const visited = new Set<string>();
+  const seenTargets = new Set<string>(); // For deduplication in transitive mode
+
+  // Add the starting function to seenTargets to prevent cycles back to it
+  if (transitive) {
+    seenTargets.add(functionId);
+  }
+
+  // Step 1: Try HAS_SCOPE path (Layout A — scope chain)
+  const hasScopeEdges = await backend.getOutgoingEdges(functionId, ['HAS_SCOPE']);
+
+  if (hasScopeEdges.length > 0) {
+    // Layout A: BFS through scope chain
+    const queue: Array<{ id: string; depth: number }> = [];
+
+    for (const edge of hasScopeEdges) {
+      queue.push({ id: edge.dst, depth: 0 });
+    }
+
+    while (queue.length > 0) {
+      const { id, depth } = queue.shift()!;
+
+      if (visited.has(id) || depth > maxDepth) continue;
+      visited.add(id);
+
+      const containsEdges = await backend.getOutgoingEdges(id, ['CONTAINS']);
+
+      for (const edge of containsEdges) {
+        const child = await backend.getNode(edge.dst);
+        if (!child) continue;
+
+        if (child.type === 'CALL' || child.type === 'METHOD_CALL') {
+          const callInfo = await buildCallInfo(backend, child, 0);
+          calls.push(callInfo);
+
+          if (transitive && callInfo.resolved && callInfo.target) {
+            await collectTransitiveCalls(
+              backend,
+              callInfo.target.id,
+              1,
+              transitiveDepth,
+              calls,
+              seenTargets
+            );
+          }
+        }
+
+        // Continue into nested scopes, but NOT into nested functions/classes
+        if (child.type === 'SCOPE') {
+          queue.push({ id: child.id, depth: depth + 1 });
+        }
+      }
+    }
+  } else {
+    // Layout B: Direct edges from FUNCTION to CALL/METHOD_CALL nodes
+    // The Rust orchestrator links functions to calls via semantic edge types
+    // (AWAITS, RETURNS, THROWS, etc.) instead of HAS_SCOPE -> CONTAINS.
+    const allOutgoing = await backend.getOutgoingEdges(functionId, null);
+
+    for (const edge of allOutgoing) {
+      const child = await backend.getNode(edge.dst);
+      if (!child) continue;
+
+      if (child.type === 'CALL' || child.type === 'METHOD_CALL') {
+        const callInfo = await buildCallInfo(backend, child, 0);
+        calls.push(callInfo);
+
+        if (transitive && callInfo.resolved && callInfo.target) {
+          await collectTransitiveCalls(
+            backend,
+            callInfo.target.id,
+            1,
+            transitiveDepth,
+            calls,
+            seenTargets
+          );
+        }
+      }
+    }
+  }
+
+  return calls;
+}
+
+/**
+ * Build CallInfo from a call node
+ */
+async function buildCallInfo(
+  backend: GraphBackend,
+  callNode: { id: string; type: string; name?: string; file?: string; line?: number; object?: string },
+  depth: number
+): Promise<CallInfo> {
+  // Check for CALLS edge (resolved target)
+  const callsEdges = await backend.getOutgoingEdges(callNode.id, ['CALLS']);
+  const isResolved = callsEdges.length > 0;
+
+  let target = undefined;
+  if (isResolved) {
+    const targetNode = await backend.getNode(callsEdges[0].dst);
+    if (targetNode) {
+      target = {
+        id: targetNode.id,
+        name: targetNode.name ?? '<anonymous>',
+        file: targetNode.file,
+        line: targetNode.line,
+      };
+    }
+  }
+
+  return {
+    id: callNode.id,
+    name: callNode.name ?? '<unknown>',
+    type: callNode.type as 'CALL' | 'METHOD_CALL',
+    object: callNode.object,
+    resolved: isResolved,
+    target,
+    file: callNode.file,
+    line: callNode.line,
+    depth,
+  };
+}
+
+/**
+ * Recursively collect transitive calls
+ *
+ * Infinite loop prevention:
+ * - Track seen function IDs in seenTargets
+ * - Stop when we've seen a function before (handles recursion)
+ * - Stop at transitiveDepth limit
+ */
+async function collectTransitiveCalls(
+  backend: GraphBackend,
+  functionId: string,
+  currentDepth: number,
+  maxTransitiveDepth: number,
+  calls: CallInfo[],
+  seenTargets: Set<string>
+): Promise<void> {
+  // Prevent infinite loops and limit depth
+  if (seenTargets.has(functionId) || currentDepth > maxTransitiveDepth) {
+    return;
+  }
+  seenTargets.add(functionId);
+
+  // Find calls in this function (non-transitive to avoid recursion)
+  const innerCalls = await findCallsInFunction(backend, functionId, {
+    maxDepth: DEFAULT_MAX_SCOPE_DEPTH,
+    transitive: false,
+  });
+
+  for (const call of innerCalls) {
+    // Add with updated depth
+    calls.push({ ...call, depth: currentDepth });
+
+    // Continue transitively if resolved
+    if (call.resolved && call.target) {
+      await collectTransitiveCalls(
+        backend,
+        call.target.id,
+        currentDepth + 1,
+        maxTransitiveDepth,
+        calls,
+        seenTargets
+      );
+    }
+  }
+}

package/src/queries/findContainingFunction.ts

@@ -0,0 +1,124 @@
+/**
+ * Find the FUNCTION, CLASS, or MODULE that contains a node.
+ *
+ * Supports two graph layouts:
+ *
+ * Layout A (scope chain — legacy JS analyzer):
+ * ```
+ * CALL <- CONTAINS <- SCOPE <- ... <- SCOPE <- HAS_SCOPE <- FUNCTION
+ * VARIABLE <- DECLARES <- SCOPE <- ... <- SCOPE <- HAS_SCOPE <- FUNCTION
+ * ```
+ *
+ * Layout B (direct edges — Rust orchestrator):
+ * ```
+ * CALL <- AWAITS|RETURNS|THROWS <- FUNCTION
+ * ```
+ * The orchestrator links functions directly to their call nodes via
+ * semantic edge types. These incoming edges on a CALL node point
+ * directly back to the containing FUNCTION.
+ *
+ * Algorithm:
+ * 1. BFS up via CONTAINS, HAS_SCOPE, DECLARES (Layout A)
+ * 2. Also follow AWAITS, RETURNS, THROWS incoming edges (Layout B)
+ * 3. Stop when we find FUNCTION, CLASS, or MODULE
+ * 4. Prefer FUNCTION over MODULE (FUNCTION is more specific)
+ *
+ * @module queries/findContainingFunction
+ */
+
+import type { CallerInfo } from './types.js';
+
+/**
+ * Graph backend interface (minimal surface)
+ */
+interface GraphBackend {
+  getNode(id: string): Promise<{
+    id: string;
+    type: string;
+    name?: string;
+    file?: string;
+    line?: number;
+  } | null>;
+  getIncomingEdges(
+    nodeId: string,
+    edgeTypes: string[] | null
+  ): Promise<Array<{ src: string; dst: string; type: string }>>;
+}
+
+/**
+ * Maximum BFS depth for upward containment traversal.
+ *
+ * Each depth level = one CONTAINS/HAS_SCOPE/DECLARES hop.
+ * Typical real-world nesting: 3-7 levels (function body → if → loop → try → ...).
+ * Set to 15 to handle pathological cases (deeply nested callbacks, complex control flow)
+ * while still bounding traversal in malformed graphs.
+ */
+const DEFAULT_MAX_DEPTH = 15;
+
+/**
+ * Find the FUNCTION, CLASS, or MODULE that contains a node.
+ *
+ * @param backend - Graph backend for queries
+ * @param nodeId - ID of the node to find container for
+ * @param maxDepth - Maximum traversal depth (default: {@link DEFAULT_MAX_DEPTH}).
+ *   Traversal visits depths 0 through maxDepth inclusive.
+ * @returns CallerInfo or null if no container found within maxDepth hops
+ */
+export async function findContainingFunction(
+  backend: GraphBackend,
+  nodeId: string,
+  maxDepth: number = DEFAULT_MAX_DEPTH
+): Promise<CallerInfo | null> {
+  const visited = new Set<string>();
+  const queue: Array<{ id: string; depth: number }> = [{ id: nodeId, depth: 0 }];
+
+  // Collect all candidates so we can prefer FUNCTION over MODULE
+  let bestCandidate: CallerInfo | null = null;
+
+  while (queue.length > 0) {
+    const { id, depth } = queue.shift()!;
+
+    if (visited.has(id) || depth > maxDepth) continue;
+    visited.add(id);
+
+    // Layout A edges: CONTAINS, HAS_SCOPE, DECLARES (scope chain traversal)
+    // Layout B edges: AWAITS, RETURNS, THROWS (direct function-to-call edges)
+    const edges = await backend.getIncomingEdges(id, [
+      'CONTAINS', 'HAS_SCOPE', 'DECLARES',
+      'AWAITS', 'RETURNS', 'THROWS',
+    ]);
+
+    for (const edge of edges) {
+      const parentNode = await backend.getNode(edge.src);
+      if (!parentNode || visited.has(parentNode.id)) continue;
+
+      // Found container!
+      if (parentNode.type === 'FUNCTION' || parentNode.type === 'CLASS' || parentNode.type === 'MODULE') {
+        const candidate: CallerInfo = {
+          id: parentNode.id,
+          name: parentNode.name || '<anonymous>',
+          type: parentNode.type,
+          file: parentNode.file,
+          line: parentNode.line,
+        };
+
+        // FUNCTION/CLASS is most specific — return immediately
+        if (parentNode.type === 'FUNCTION' || parentNode.type === 'CLASS') {
+          return candidate;
+        }
+
+        // MODULE is less specific — keep as fallback, continue searching
+        if (!bestCandidate) {
+          bestCandidate = candidate;
+        }
+
+        continue;
+      }
+
+      // Continue searching
+      queue.push({ id: parentNode.id, depth: depth + 1 });
+    }
+  }
+
+  return bestCandidate;
+}

package/src/queries/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Graph Query Utilities
+ *
+ * Shared utilities for querying the code graph.
+ * Used by MCP, CLI, and other tools.
+ *
+ * @module queries
+ */
+
+export { findCallsInFunction } from './findCallsInFunction.js';
+export { findContainingFunction } from './findContainingFunction.js';
+export { traceValues, aggregateValues, NONDETERMINISTIC_PATTERNS, NONDETERMINISTIC_OBJECTS } from './traceValues.js';
+export { traceDataflow, traceForwardBFS, traceBackwardBFS } from './traceDataflow.js';
+export {
+  buildNodeContext,
+  getNodeDisplayName,
+  formatEdgeMetadata,
+  STRUCTURAL_EDGE_TYPES,
+} from './NodeContext.js';
+
+export type { CallInfo, CallerInfo, FindCallsOptions } from './types.js';
+export type {
+  EdgeWithNode,
+  EdgeGroup,
+  SourcePreview,
+  NodeContext,
+  BuildNodeContextOptions,
+} from './NodeContext.js';
+export type {
+  TracedValue,
+  ValueSource,
+  UnknownReason,
+  TraceValuesOptions,
+  ValueSetResult,
+  TraceValuesGraphBackend,
+  NondeterministicPattern,
+} from './types.js';
+export type {
+  DataflowNode,
+  DataflowEdge,
+  DataflowBackend,
+  TraceDataflowOptions,
+  TraceDataflowResult,
+} from './traceDataflow.js';