@grafema/core 0.1.0-alpha.5 → 0.2.0-beta

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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"}

package/dist/queries/types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared Types for Graph Query Utilities
+ *
+ * These types are used by findCallsInFunction, findContainingFunction,
+ * and other query utilities.
+ *
+ * @module queries/types
+ */
+export {};

package/dist/schema/GraphSchemaExtractor.d.ts

@@ -0,0 +1,53 @@
+/**
+ * GraphSchemaExtractor - Extracts graph node/edge type schemas
+ *
+ * Usage:
+ *   const extractor = new GraphSchemaExtractor(backend);
+ *   const schema = await extractor.extract();
+ *
+ * When to use:
+ *   - Export graph schema for contract tracking
+ *   - Track node/edge type changes via checksum
+ *   - Generate graph documentation
+ */
+import type { RFDBServerBackend } from '../storage/backends/RFDBServerBackend.js';
+export interface NodeTypeSchema {
+    category: 'base' | 'namespaced';
+    namespace?: string;
+    count: number;
+}
+export interface EdgeTypeSchema {
+    count: number;
+}
+export interface GraphSchema {
+    $schema: 'grafema-graph-v1';
+    extractedAt: string;
+    nodeTypes: Record<string, NodeTypeSchema>;
+    edgeTypes: Record<string, EdgeTypeSchema>;
+    statistics: {
+        totalNodes: number;
+        totalEdges: number;
+        nodeTypeCount: number;
+        edgeTypeCount: number;
+    };
+    checksum: string;
+}
+export interface GraphExtractOptions {
+    /** Include all defined types, not just used ones (default: false) */
+    includeAll?: boolean;
+}
+export declare class GraphSchemaExtractor {
+    private backend;
+    constructor(backend: RFDBServerBackend);
+    /**
+     * Extract graph schema from current database
+     *
+     * @param options.includeAll - If true, include all defined types even with count=0
+     */
+    extract(options?: GraphExtractOptions): Promise<GraphSchema>;
+    /**
+     * Sort object keys alphabetically for deterministic output
+     */
+    private sortObject;
+}
+//# sourceMappingURL=GraphSchemaExtractor.d.ts.map

package/dist/schema/GraphSchemaExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphSchemaExtractor.d.ts","sourceRoot":"","sources":["../../src/schema/GraphSchemaExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAMlF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,UAAU,EAAE;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,qBAAa,oBAAoB;IACnB,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,iBAAiB;IAE9C;;;;OAIG;IACG,OAAO,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IAuGlE;;OAEG;IACH,OAAO,CAAC,UAAU;CAQnB"}

package/dist/schema/GraphSchemaExtractor.js

@@ -0,0 +1,124 @@
+/**
+ * GraphSchemaExtractor - Extracts graph node/edge type schemas
+ *
+ * Usage:
+ *   const extractor = new GraphSchemaExtractor(backend);
+ *   const schema = await extractor.extract();
+ *
+ * When to use:
+ *   - Export graph schema for contract tracking
+ *   - Track node/edge type changes via checksum
+ *   - Generate graph documentation
+ */
+import { createHash } from 'crypto';
+import { NODE_TYPE, NAMESPACED_TYPE, EDGE_TYPE } from '@grafema/types';
+export class GraphSchemaExtractor {
+    backend;
+    constructor(backend) {
+        this.backend = backend;
+    }
+    /**
+     * Extract graph schema from current database
+     *
+     * @param options.includeAll - If true, include all defined types even with count=0
+     */
+    async extract(options) {
+        const includeAll = options?.includeAll ?? false;
+        // Get actual counts from graph
+        const nodeCounts = await this.backend.countNodesByType();
+        const edgeCounts = await this.backend.countEdgesByType();
+        // Build node types from definitions + counts
+        const nodeTypes = {};
+        // Base node types
+        for (const [_key, value] of Object.entries(NODE_TYPE)) {
+            nodeTypes[value] = {
+                category: 'base',
+                count: nodeCounts[value] || 0,
+            };
+        }
+        // Namespaced node types
+        for (const [_key, value] of Object.entries(NAMESPACED_TYPE)) {
+            const namespace = value.split(':')[0];
+            nodeTypes[value] = {
+                category: 'namespaced',
+                namespace,
+                count: nodeCounts[value] || 0,
+            };
+        }
+        // Add any additional types found in the graph but not in definitions
+        for (const [type, count] of Object.entries(nodeCounts)) {
+            if (!nodeTypes[type]) {
+                const namespace = type.includes(':') ? type.split(':')[0] : undefined;
+                nodeTypes[type] = {
+                    category: namespace ? 'namespaced' : 'base',
+                    namespace,
+                    count,
+                };
+            }
+        }
+        // Build edge types from definitions + counts
+        const edgeTypes = {};
+        for (const [_key, value] of Object.entries(EDGE_TYPE)) {
+            edgeTypes[value] = {
+                count: edgeCounts[value] || 0,
+            };
+        }
+        // Add any additional edge types found in the graph
+        for (const [type, count] of Object.entries(edgeCounts)) {
+            if (!edgeTypes[type]) {
+                edgeTypes[type] = { count };
+            }
+        }
+        // Calculate totals
+        const totalNodes = Object.values(nodeCounts).reduce((sum, n) => sum + n, 0);
+        const totalEdges = Object.values(edgeCounts).reduce((sum, n) => sum + n, 0);
+        // Filter out types with count=0 unless includeAll is true
+        const filteredNodeTypes = {};
+        for (const [type, info] of Object.entries(nodeTypes)) {
+            if (includeAll || info.count > 0) {
+                filteredNodeTypes[type] = info;
+            }
+        }
+        const filteredEdgeTypes = {};
+        for (const [type, info] of Object.entries(edgeTypes)) {
+            if (includeAll || info.count > 0) {
+                filteredEdgeTypes[type] = info;
+            }
+        }
+        // Sort for deterministic output
+        const sortedNodeTypes = this.sortObject(filteredNodeTypes);
+        const sortedEdgeTypes = this.sortObject(filteredEdgeTypes);
+        // Compute checksum from normalized content (based on filtered types)
+        const checksumContent = {
+            nodeTypes: Object.keys(sortedNodeTypes).sort(),
+            edgeTypes: Object.keys(sortedEdgeTypes).sort(),
+        };
+        const checksum = createHash('sha256')
+            .update(JSON.stringify(checksumContent))
+            .digest('hex');
+        return {
+            $schema: 'grafema-graph-v1',
+            extractedAt: new Date().toISOString(),
+            nodeTypes: sortedNodeTypes,
+            edgeTypes: sortedEdgeTypes,
+            statistics: {
+                totalNodes,
+                totalEdges,
+                nodeTypeCount: Object.keys(sortedNodeTypes).length,
+                edgeTypeCount: Object.keys(sortedEdgeTypes).length,
+            },
+            checksum: `sha256:${checksum}`,
+        };
+    }
+    /**
+     * Sort object keys alphabetically for deterministic output
+     */
+    sortObject(obj) {
+        const sorted = {};
+        const keys = Object.keys(obj).sort();
+        for (const key of keys) {
+            sorted[key] = obj[key];
+        }
+        return sorted;
+    }
+}