@grafema/core 0.1.1-alpha → 0.2.0-beta

package/dist/queries/findContainingFunction.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Find the FUNCTION, CLASS, or MODULE that contains a node.
+ *
+ * Graph structure (backward traversal):
+ * ```
+ * CALL <- CONTAINS <- SCOPE <- ... <- SCOPE <- HAS_SCOPE <- FUNCTION
+ * VARIABLE <- DECLARES <- SCOPE <- ... <- SCOPE <- HAS_SCOPE <- FUNCTION
+ * ```
+ *
+ * Algorithm:
+ * 1. BFS up the containment tree via CONTAINS and DECLARES edges
+ * 2. Also follow HAS_SCOPE edges (connects FUNCTION to its body SCOPE)
+ * 3. Stop when we find FUNCTION, CLASS, or MODULE
+ *
+ * @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;
+    }>>;
+}
+/**
+ * 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: 15)
+ * @returns CallerInfo or null if no container found
+ */
+export declare function findContainingFunction(backend: GraphBackend, nodeId: string, maxDepth?: number): Promise<CallerInfo | null>;
+export {};
+//# sourceMappingURL=findContainingFunction.d.ts.map

package/dist/queries/findContainingFunction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findContainingFunction.d.ts","sourceRoot":"","sources":["../../src/queries/findContainingFunction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAC3B,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,IAAI,CAAC,CAAC;IACV,gBAAgB,CACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,GACzB,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,MAAW,GACpB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAkC5B"}

package/dist/queries/findContainingFunction.js

@@ -0,0 +1,54 @@
+/**
+ * Find the FUNCTION, CLASS, or MODULE that contains a node.
+ *
+ * Graph structure (backward traversal):
+ * ```
+ * CALL <- CONTAINS <- SCOPE <- ... <- SCOPE <- HAS_SCOPE <- FUNCTION
+ * VARIABLE <- DECLARES <- SCOPE <- ... <- SCOPE <- HAS_SCOPE <- FUNCTION
+ * ```
+ *
+ * Algorithm:
+ * 1. BFS up the containment tree via CONTAINS and DECLARES edges
+ * 2. Also follow HAS_SCOPE edges (connects FUNCTION to its body SCOPE)
+ * 3. Stop when we find FUNCTION, CLASS, or MODULE
+ *
+ * @module queries/findContainingFunction
+ */
+/**
+ * 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: 15)
+ * @returns CallerInfo or null if no container found
+ */
+export async function findContainingFunction(backend, nodeId, maxDepth = 15) {
+    const visited = new Set();
+    const queue = [{ id: nodeId, depth: 0 }];
+    while (queue.length > 0) {
+        const { id, depth } = queue.shift();
+        if (visited.has(id) || depth > maxDepth)
+            continue;
+        visited.add(id);
+        // Get incoming edges: CONTAINS, HAS_SCOPE, and DECLARES (for variables)
+        const edges = await backend.getIncomingEdges(id, ['CONTAINS', 'HAS_SCOPE', 'DECLARES']);
+        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') {
+                return {
+                    id: parentNode.id,
+                    name: parentNode.name || '<anonymous>',
+                    type: parentNode.type,
+                    file: parentNode.file,
+                    line: parentNode.line,
+                };
+            }
+            // Continue searching
+            queue.push({ id: parentNode.id, depth: depth + 1 });
+        }
+    }
+    return null;
+}

package/dist/queries/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 type { CallInfo, CallerInfo, FindCallsOptions } from './types.js';
+export type { TracedValue, ValueSource, UnknownReason, TraceValuesOptions, ValueSetResult, TraceValuesGraphBackend, NondeterministicPattern, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/queries/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/queries/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAErH,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACzE,YAAY,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/queries/index.js

@@ -0,0 +1,11 @@
+/**
+ * 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';

package/dist/queries/traceValues.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 (unknown: runtime input)
+ * 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 MemberExpression patterns.
+ * object.property combinations that represent external/user input.
+ */
+export declare const NONDETERMINISTIC_PATTERNS: NondeterministicPattern[];
+/**
+ * Nondeterministic object prefixes.
+ * Any property access on these is nondeterministic.
+ */
+export declare const NONDETERMINISTIC_OBJECTS: string[];
+/**
+ * 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 declare function traceValues(backend: TraceValuesGraphBackend, nodeId: string, options?: TraceValuesOptions): Promise<TracedValue[]>;
+/**
+ * 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 declare function aggregateValues(traced: TracedValue[]): ValueSetResult;
+//# sourceMappingURL=traceValues.d.ts.map

package/dist/queries/traceValues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceValues.d.ts","sourceRoot":"","sources":["../../src/queries/traceValues.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,uBAAuB,EACvB,cAAc,EACd,uBAAuB,EAExB,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,uBAAuB,EAiB9D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,EAO5C,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,uBAAuB,EAChC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,WAAW,EAAE,CAAC,CAoBxB;AAuPD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,cAAc,CAgBrE"}

package/dist/queries/traceValues.js

@@ -0,0 +1,299 @@
+/**
+ * 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 (unknown: runtime input)
+ * 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
+ */
+// =============================================================================
+// NONDETERMINISTIC PATTERNS (moved from ValueDomainAnalyzer)
+// =============================================================================
+/**
+ * Nondeterministic MemberExpression patterns.
+ * object.property combinations that represent external/user input.
+ */
+export const NONDETERMINISTIC_PATTERNS = [
+    // 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 = [
+    '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, nodeId, options) {
+    const results = [];
+    const visited = new Set();
+    const maxDepth = options?.maxDepth ?? 10;
+    const followDerivesFrom = options?.followDerivesFrom ?? true;
+    const detectNondeterministic = options?.detectNondeterministic ?? true;
+    await traceRecursive(backend, nodeId, visited, 0, maxDepth, followDerivesFrom, detectNondeterministic, results);
+    return results;
+}
+/**
+ * Recursive tracing function
+ */
+async function traceRecursive(backend, nodeId, visited, depth, maxDepth, followDerivesFrom, detectNondeterministic, results) {
+    // 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;
+    }
+    // Terminal: PARAMETER - runtime input
+    if (nodeType === 'PARAMETER') {
+        results.push({
+            value: undefined,
+            source,
+            isUnknown: true,
+            reason: 'parameter',
+        });
+        return;
+    }
+    // Terminal: CALL / METHOD_CALL - function return value
+    if (nodeType === 'CALL' || nodeType === 'METHOD_CALL') {
+        // 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, results);
+            }
+            return; // Traced through HTTP boundary, don't mark as unknown
+        }
+        // Original behavior - 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;
+        }
+    }
+    // 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.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?.argIndex;
+                        if (argIndex === 0) {
+                            // Recursively trace the argument value
+                            await traceRecursive(backend, argEdge.dst, visited, depth + 1, maxDepth, followDerivesFrom, detectNondeterministic, 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);
+    // No edges case - unknown
+    if (edges.length === 0) {
+        results.push({
+            value: undefined,
+            source,
+            isUnknown: true,
+            reason: 'no_sources',
+        });
+        return;
+    }
+    // Recurse through sources
+    for (const edge of edges) {
+        await traceRecursive(backend, edge.dst, visited, depth + 1, maxDepth, followDerivesFrom, detectNondeterministic, results);
+    }
+}
+// =============================================================================
+// HELPERS
+// =============================================================================
+/**
+ * Check if an EXPRESSION node represents a nondeterministic pattern.
+ * E.g., process.env.VAR, req.body.userId, etc.
+ */
+function isNondeterministicExpression(node) {
+    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) {
+    const valueSet = new Set();
+    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/dist/queries/types.d.ts

@@ -0,0 +1,163 @@
+/**
+ * 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;
+}
+/**
+ * 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' | 'call_result' | 'constructor_call' | 'nondeterministic' | 'max_depth' | 'no_sources';
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/queries/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/queries/types.ts"],"names":[],"mappings":"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"}