@grafema/util 0.3.0-beta

package/src/queries/traceValues.ts

@@ -0,0 +1,531 @@
+/**
+ * Value Tracing Utility (REG-244)
+ *
+ * Traces a node through ASSIGNED_FROM/DERIVES_FROM edges to find
+ * all possible literal values or mark as unknown.
+ *
+ * Graph structure:
+ * ```
+ * VARIABLE -[ASSIGNED_FROM]-> LITERAL (concrete value)
+ * VARIABLE -[ASSIGNED_FROM]-> PARAMETER -[DERIVES_FROM]-> argument source (interprocedural)
+ * VARIABLE -[ASSIGNED_FROM]-> CALL (unknown: function return)
+ * VARIABLE -[DERIVES_FROM]-> EXPRESSION (check nondeterministic patterns)
+ * VARIABLE -[ASSIGNED_FROM]-> VARIABLE (chain - recurse)
+ * ```
+ *
+ * Used by:
+ * - CLI trace command (sink-based tracing)
+ * - ValueDomainAnalyzer (computed member access resolution)
+ *
+ * @module queries/traceValues
+ */
+
+import type {
+  TracedValue,
+  TraceValuesOptions,
+  TraceValuesGraphBackend,
+  ValueSetResult,
+  NondeterministicPattern,
+} from './types.js';
+
+// =============================================================================
+// NONDETERMINISTIC PATTERNS (moved from ValueDomainAnalyzer)
+// =============================================================================
+
+/**
+ * Nondeterministic MemberExpression patterns.
+ * object.property combinations that represent external/user input.
+ */
+export const NONDETERMINISTIC_PATTERNS: NondeterministicPattern[] = [
+  // Environment variables
+  { object: 'process', property: 'env' },
+  // HTTP request data (Express.js patterns)
+  { object: 'req', property: 'body' },
+  { object: 'req', property: 'query' },
+  { object: 'req', property: 'params' },
+  { object: 'req', property: 'headers' },
+  { object: 'req', property: 'cookies' },
+  { object: 'request', property: 'body' },
+  { object: 'request', property: 'query' },
+  { object: 'request', property: 'params' },
+  // Context patterns (Koa, etc.)
+  { object: 'ctx', property: 'request' },
+  { object: 'ctx', property: 'body' },
+  { object: 'ctx', property: 'query' },
+  { object: 'ctx', property: 'params' },
+];
+
+/**
+ * Nondeterministic object prefixes.
+ * Any property access on these is nondeterministic.
+ */
+export const NONDETERMINISTIC_OBJECTS: string[] = [
+  'process.env',  // process.env.ANY_VAR
+  'req.body',     // req.body.userId
+  'req.query',    // req.query.filter
+  'req.params',   // req.params.id
+  'request.body',
+  'ctx.request',
+];
+
+// =============================================================================
+// MAIN FUNCTION
+// =============================================================================
+
+/**
+ * Trace a node to all its possible literal values.
+ *
+ * Starting from the given node, follows ASSIGNED_FROM (and optionally
+ * DERIVES_FROM) edges backwards to find:
+ * - LITERAL nodes: concrete values
+ * - PARAMETER nodes: runtime inputs (unknown)
+ * - CALL nodes: function return values (unknown)
+ * - EXPRESSION nodes: checks for nondeterministic patterns
+ *
+ * @param backend - Graph backend for queries
+ * @param nodeId - Starting node ID
+ * @param options - Traversal options
+ * @returns Array of traced values with sources
+ *
+ * @example
+ * const values = await traceValues(backend, variableId);
+ * for (const v of values) {
+ *   if (v.isUnknown) {
+ *     console.log(`Unknown from ${v.source.file}:${v.source.line} (${v.reason})`);
+ *   } else {
+ *     console.log(`Value: ${v.value} from ${v.source.file}:${v.source.line}`);
+ *   }
+ * }
+ */
+export async function traceValues(
+  backend: TraceValuesGraphBackend,
+  nodeId: string,
+  options?: TraceValuesOptions
+): Promise<TracedValue[]> {
+  const results: TracedValue[] = [];
+  const visited = new Set<string>();
+
+  const maxDepth = options?.maxDepth ?? 10;
+  const followDerivesFrom = options?.followDerivesFrom ?? true;
+  const detectNondeterministic = options?.detectNondeterministic ?? true;
+  const followCallReturns = options?.followCallReturns ?? true;
+
+  await traceRecursive(
+    backend,
+    nodeId,
+    visited,
+    0,
+    maxDepth,
+    followDerivesFrom,
+    detectNondeterministic,
+    followCallReturns,
+    results
+  );
+
+  return results;
+}
+
+/**
+ * Recursive tracing function
+ */
+async function traceRecursive(
+  backend: TraceValuesGraphBackend,
+  nodeId: string,
+  visited: Set<string>,
+  depth: number,
+  maxDepth: number,
+  followDerivesFrom: boolean,
+  detectNondeterministic: boolean,
+  followCallReturns: boolean,
+  results: TracedValue[]
+): Promise<void> {
+  // Cycle protection
+  if (visited.has(nodeId)) {
+    return;
+  }
+  visited.add(nodeId);
+
+  // Get node
+  const node = await backend.getNode(nodeId);
+  if (!node) {
+    return;
+  }
+
+  const nodeType = node.type || node.nodeType;
+  const source = {
+    id: node.id,
+    file: node.file || '',
+    line: node.line || 0,
+  };
+
+  // Depth protection - check after getting node for source info
+  if (depth > maxDepth) {
+    results.push({
+      value: undefined,
+      source,
+      isUnknown: true,
+      reason: 'max_depth',
+    });
+    return;
+  }
+
+  // Terminal: LITERAL - found concrete value
+  if (nodeType === 'LITERAL') {
+    results.push({
+      value: node.value,
+      source,
+      isUnknown: false,
+    });
+    return;
+  }
+
+  // PARAMETER - try to follow DERIVES_FROM edges to call-site arguments
+  if (nodeType === 'PARAMETER') {
+    if (followDerivesFrom) {
+      const derivesEdges = await backend.getOutgoingEdges(nodeId, ['DERIVES_FROM']);
+      if (derivesEdges.length > 0) {
+        for (const edge of derivesEdges) {
+          await traceRecursive(
+            backend,
+            edge.dst,
+            visited,
+            depth + 1,
+            maxDepth,
+            followDerivesFrom,
+            detectNondeterministic,
+            followCallReturns,
+            results
+          );
+        }
+        return;
+      }
+    }
+
+    // No DERIVES_FROM edges or followDerivesFrom disabled
+    results.push({
+      value: undefined,
+      source,
+      isUnknown: true,
+      reason: 'parameter',
+    });
+    return;
+  }
+
+  // Terminal: CALL / METHOD_CALL - function return value
+  if (nodeType === 'CALL' || nodeType === 'METHOD_CALL') {
+    // REG-576: Follow CALL_RETURNS to called function's return values
+    if (followCallReturns) {
+      const callReturnsEdges = await backend.getOutgoingEdges(nodeId, ['CALL_RETURNS']);
+      if (callReturnsEdges.length > 0) {
+        for (const crEdge of callReturnsEdges) {
+          // Get RETURNS edges from the target function
+          const returnsEdges = await backend.getOutgoingEdges(crEdge.dst, ['RETURNS']);
+          if (returnsEdges.length > 0) {
+            for (const retEdge of returnsEdges) {
+              await traceRecursive(
+                backend,
+                retEdge.dst,
+                visited,
+                depth + 1,
+                maxDepth,
+                followDerivesFrom,
+                detectNondeterministic,
+                followCallReturns,
+                results
+              );
+            }
+          } else {
+            // Function has no RETURNS edges → implicit undefined
+            const fnNode = await backend.getNode(crEdge.dst);
+            results.push({
+              value: undefined,
+              source: { id: crEdge.dst, file: fnNode?.file || '', line: fnNode?.line || 0 },
+              isUnknown: true,
+              reason: 'implicit_return',
+            });
+          }
+        }
+        return;
+      }
+    }
+
+    // Check for HTTP_RECEIVES edges (cross-service data flow)
+    const httpEdges = await backend.getOutgoingEdges(nodeId, ['HTTP_RECEIVES']);
+
+    if (httpEdges.length > 0) {
+      // Follow HTTP boundary to backend response
+      for (const edge of httpEdges) {
+        await traceRecursive(
+          backend,
+          edge.dst,
+          visited,
+          depth + 1,
+          maxDepth,
+          followDerivesFrom,
+          detectNondeterministic,
+          followCallReturns,
+          results
+        );
+      }
+      return; // Traced through HTTP boundary, don't mark as unknown
+    }
+
+    // No CALL_RETURNS or HTTP_RECEIVES → mark as unknown
+    results.push({
+      value: undefined,
+      source,
+      isUnknown: true,
+      reason: 'call_result',
+    });
+    return;
+  }
+
+  // Check nondeterministic EXPRESSION patterns
+  if (nodeType === 'EXPRESSION' && detectNondeterministic) {
+    if (isNondeterministicExpression(node)) {
+      results.push({
+        value: undefined,
+        source,
+        isUnknown: true,
+        reason: 'nondeterministic',
+      });
+      return;
+    }
+  }
+
+  // REG-574: Conditional value sets — ternary expressions
+  // EXPRESSION(ternary) → follow HAS_CONSEQUENT + HAS_ALTERNATE (skip HAS_CONDITION)
+  if (nodeType === 'EXPRESSION' && node.name === 'ternary') {
+    const branches = await backend.getOutgoingEdges(nodeId, ['HAS_CONSEQUENT', 'HAS_ALTERNATE']);
+    if (branches.length > 0) {
+      for (const edge of branches) {
+        await traceRecursive(
+          backend,
+          edge.dst,
+          visited,
+          depth + 1,
+          maxDepth,
+          followDerivesFrom,
+          detectNondeterministic,
+          followCallReturns,
+          results
+        );
+      }
+      return;
+    }
+  }
+
+  // REG-574: Conditional value sets — logical expressions (||, &&, ??)
+  // These represent alternative values, follow USES edges
+  if (nodeType === 'EXPRESSION' && isLogicalOperator(node.name)) {
+    const operands = await backend.getOutgoingEdges(nodeId, ['USES']);
+    if (operands.length > 0) {
+      for (const edge of operands) {
+        await traceRecursive(
+          backend,
+          edge.dst,
+          visited,
+          depth + 1,
+          maxDepth,
+          followDerivesFrom,
+          detectNondeterministic,
+          followCallReturns,
+          results
+        );
+      }
+      return;
+    }
+  }
+
+  // Terminal: OBJECT_LITERAL - a valid structured value
+  // OBJECT_LITERAL without edges is valid (e.g., {} or {key: value})
+  if (nodeType === 'OBJECT_LITERAL') {
+    results.push({
+      value: node.value,
+      source,
+      isUnknown: false,
+    });
+    return;
+  }
+
+  // REG-334: Special case - CONSTRUCTOR_CALL for Promise
+  // Follow RESOLVES_TO edges to find actual data sources from resolve() calls
+  if (nodeType === 'CONSTRUCTOR_CALL') {
+    const className = (node as { className?: string }).className;
+
+    if (className === 'Promise') {
+      // Look for incoming RESOLVES_TO edges (resolve/reject calls)
+      const resolveEdges = await backend.getIncomingEdges(nodeId, ['RESOLVES_TO']);
+
+      if (resolveEdges.length > 0) {
+        // Follow resolve/reject calls to their arguments
+        for (const edge of resolveEdges) {
+          // edge.src is the resolve(value) CALL node
+          // We need to find what value was passed to resolve()
+          // The CALL node should have PASSES_ARGUMENT edge to the value
+          const argEdges = await backend.getOutgoingEdges(edge.src, ['PASSES_ARGUMENT']);
+
+          for (const argEdge of argEdges) {
+            // Check if this is the first argument (argIndex 0)
+            const argIndex = (argEdge.metadata as { argIndex?: number } | undefined)?.argIndex;
+            if (argIndex === 0) {
+              // Recursively trace the argument value
+              await traceRecursive(
+                backend,
+                argEdge.dst,
+                visited,
+                depth + 1,
+                maxDepth,
+                followDerivesFrom,
+                detectNondeterministic,
+                followCallReturns,
+                results
+              );
+            }
+          }
+        }
+        return; // Traced through resolve, don't mark as unknown
+      }
+    }
+
+    // Non-Promise constructor or no resolve edges - mark as unknown
+    results.push({
+      value: undefined,
+      source,
+      isUnknown: true,
+      reason: 'constructor_call',
+    });
+    return;
+  }
+
+  // Get outgoing data flow edges
+  const edgeTypes = ['ASSIGNED_FROM'];
+  if (followDerivesFrom) {
+    edgeTypes.push('DERIVES_FROM');
+  }
+
+  const edges = await backend.getOutgoingEdges(nodeId, edgeTypes);
+
+  // REG-574: Also check incoming WRITES_TO edges (if/else reassignment)
+  const writesToEdges = await backend.getIncomingEdges(nodeId, ['WRITES_TO']);
+
+  // No edges case - unknown
+  if (edges.length === 0 && writesToEdges.length === 0) {
+    results.push({
+      value: undefined,
+      source,
+      isUnknown: true,
+      reason: 'no_sources',
+    });
+    return;
+  }
+
+  // Recurse through ASSIGNED_FROM/DERIVES_FROM targets
+  for (const edge of edges) {
+    await traceRecursive(
+      backend,
+      edge.dst,
+      visited,
+      depth + 1,
+      maxDepth,
+      followDerivesFrom,
+      detectNondeterministic,
+      followCallReturns,
+      results
+    );
+  }
+
+  // REG-574: Recurse through WRITES_TO sources (the EXPRESSION(=) node,
+  // which will naturally follow its ASSIGNED_FROM to the value)
+  for (const edge of writesToEdges) {
+    await traceRecursive(
+      backend,
+      edge.src,
+      visited,
+      depth + 1,
+      maxDepth,
+      followDerivesFrom,
+      detectNondeterministic,
+      followCallReturns,
+      results
+    );
+  }
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+/**
+ * Check if an expression name is a logical operator (alternative values).
+ * Used to distinguish logical OR/AND/nullish from arithmetic operators.
+ */
+function isLogicalOperator(name: string | undefined): boolean {
+  return name === '||' || name === '&&' || name === '??';
+}
+
+/**
+ * Check if an EXPRESSION node represents a nondeterministic pattern.
+ * E.g., process.env.VAR, req.body.userId, etc.
+ */
+function isNondeterministicExpression(node: {
+  expressionType?: string;
+  object?: string;
+  property?: string;
+}): boolean {
+  if (node.expressionType !== 'MemberExpression') {
+    return false;
+  }
+
+  const object = node.object;
+  const property = node.property;
+
+  if (!object || !property) {
+    return false;
+  }
+
+  // Check exact patterns (object.property)
+  for (const pattern of NONDETERMINISTIC_PATTERNS) {
+    if (object === pattern.object && property === pattern.property) {
+      return true;
+    }
+  }
+
+  // Check if object is a known nondeterministic prefix
+  // e.g., process.env.VAR where object is 'process.env'
+  for (const prefix of NONDETERMINISTIC_OBJECTS) {
+    if (object === prefix || object.startsWith(prefix + '.')) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Aggregate traced values into a simplified result.
+ * Useful for consumers who don't need source locations.
+ *
+ * Note: null and undefined values are NOT included in the values array.
+ * If you need to detect "assigned to null", check the raw TracedValue[] instead.
+ *
+ * @param traced - Array of traced values
+ * @returns Aggregated result with unique values and hasUnknown flag
+ */
+export function aggregateValues(traced: TracedValue[]): ValueSetResult {
+  const valueSet = new Set<unknown>();
+  let hasUnknown = false;
+
+  for (const t of traced) {
+    if (t.isUnknown) {
+      hasUnknown = true;
+    } else if (t.value !== undefined && t.value !== null) {
+      valueSet.add(t.value);
+    }
+  }
+
+  return {
+    values: Array.from(valueSet),
+    hasUnknown,
+  };
+}

package/src/queries/types.ts

@@ -0,0 +1,191 @@
+/**
+ * Shared Types for Graph Query Utilities
+ *
+ * These types are used by findCallsInFunction, findContainingFunction,
+ * and other query utilities.
+ *
+ * @module queries/types
+ */
+
+/**
+ * Information about a function/method call found in code
+ */
+export interface CallInfo {
+  /** Node ID of the call site */
+  id: string;
+  /** Called function/method name */
+  name: string;
+  /** Node type: 'CALL' or 'METHOD_CALL' */
+  type: 'CALL' | 'METHOD_CALL';
+  /** Object name for method calls (e.g., 'response' for response.json()) */
+  object?: string;
+  /** Whether the call target was resolved (has CALLS edge) */
+  resolved: boolean;
+  /** Target function info if resolved */
+  target?: {
+    id: string;
+    name: string;
+    file?: string;
+    line?: number;
+  };
+  /** File where call occurs */
+  file?: string;
+  /** Line number of call */
+  line?: number;
+  /** Depth in transitive call chain (0 = direct call) */
+  depth?: number;
+}
+
+/**
+ * Information about a function that calls another function
+ */
+export interface CallerInfo {
+  /** Caller function ID */
+  id: string;
+  /** Caller function name */
+  name: string;
+  /** Caller function type (FUNCTION, CLASS, MODULE) */
+  type: string;
+  /** File containing the caller */
+  file?: string;
+  /** Line of the call site */
+  line?: number;
+}
+
+/**
+ * Options for finding calls in a function
+ */
+export interface FindCallsOptions {
+  /** Maximum depth for scope traversal (default: 10) */
+  maxDepth?: number;
+  /** Follow transitive calls (default: false) */
+  transitive?: boolean;
+  /** Maximum depth for transitive traversal (default: 5) */
+  transitiveDepth?: number;
+}
+
+// =============================================================================
+// VALUE TRACING TYPES (REG-244)
+// =============================================================================
+
+/**
+ * Location of a value source in the graph
+ */
+export interface ValueSource {
+  /** Node ID in the graph */
+  id: string;
+  /** File path */
+  file: string;
+  /** Line number (1-based) */
+  line: number;
+}
+
+/**
+ * Reason why a value could not be determined statically.
+ * Used for debugging and user-facing messages.
+ */
+export type UnknownReason =
+  | 'parameter'           // Function parameter (runtime input)
+  | 'call_result'         // Return value from function call
+  | 'implicit_return'     // Function has no return statement (void/undefined)
+  | 'constructor_call'    // Constructor call without traceable data (REG-334)
+  | 'nondeterministic'    // process.env, req.body, etc.
+  | 'max_depth'           // Hit depth limit during traversal
+  | 'no_sources';         // No ASSIGNED_FROM/DERIVES_FROM edges found
+
+/**
+ * A single traced value from the graph.
+ * Represents either a concrete value (from LITERAL) or an unknown value
+ * (from PARAMETER, CALL, nondeterministic source, etc.)
+ */
+export interface TracedValue {
+  /** The literal value (undefined if unknown) */
+  value: unknown;
+  /** Source location in the codebase */
+  source: ValueSource;
+  /** Whether value could not be determined statically */
+  isUnknown: boolean;
+  /** Why the value is unknown (for debugging/display) */
+  reason?: UnknownReason;
+}
+
+/**
+ * Options for traceValues()
+ */
+export interface TraceValuesOptions {
+  /** Maximum traversal depth (default: 10) */
+  maxDepth?: number;
+  /** Follow DERIVES_FROM edges in addition to ASSIGNED_FROM (default: true) */
+  followDerivesFrom?: boolean;
+  /** Detect nondeterministic patterns like process.env (default: true) */
+  detectNondeterministic?: boolean;
+  /** Follow CALL_RETURNS edges to trace through function calls (default: true) */
+  followCallReturns?: boolean;
+}
+
+/**
+ * Aggregated result from tracing.
+ * Convenience type for consumers who don't need individual sources.
+ */
+export interface ValueSetResult {
+  /** All unique concrete values found */
+  values: unknown[];
+  /** Whether any path led to unknown value */
+  hasUnknown: boolean;
+}
+
+/**
+ * Edge record for traceValues
+ */
+export interface TraceValuesEdge {
+  src: string;
+  dst: string;
+  type: string;
+  metadata?: { argIndex?: number; isReject?: boolean };
+}
+
+/**
+ * Node record for traceValues
+ */
+export interface TraceValuesNode {
+  id: string;
+  type?: string;
+  nodeType?: string;
+  value?: unknown;
+  file?: string;
+  line?: number;
+  expressionType?: string;
+  object?: string;
+  property?: string;
+  className?: string;
+  name?: string;
+}
+
+/**
+ * Minimal graph backend interface for traceValues().
+ * Works with both RFDBServerBackend and internal Graph interface.
+ */
+export interface TraceValuesGraphBackend {
+  getNode(id: string): Promise<TraceValuesNode | null>;
+  getOutgoingEdges(
+    nodeId: string,
+    edgeTypes: string[] | null
+  ): Promise<TraceValuesEdge[]>;
+  /**
+   * Get incoming edges to a node (REG-334: needed for RESOLVES_TO)
+   * Required for Promise tracing - must be implemented by all backends
+   */
+  getIncomingEdges(
+    nodeId: string,
+    edgeTypes: string[] | null
+  ): Promise<TraceValuesEdge[]>;
+}
+
+/**
+ * Nondeterministic MemberExpression pattern.
+ * object.property combinations that represent external/user input.
+ */
+export interface NondeterministicPattern {
+  object: string;
+  property: string;
+}