recon-generate 0.0.17 → 0.0.19

package/dist/cfg/edge-mapper.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Edge Mapper - Maps bytecode PCs to CFG edge IDs
+ *
+ * Approach using AST-level information:
+ * 1. CFG edges have astId (branch condition's AST ID)
+ * 2. Source map maps PC → source location → AST ID
+ * 3. For each edge's astId, find the first PC that maps to it
+ * 4. That PC is the "branch point" for that edge
+ *
+ * At runtime:
+ * - Fuzzer hits PC X
+ * - Look up: is X a branch point for any edge?
+ * - If yes, mark that edge as covered based on which direction was taken
+ */
+/** Edge info parsed from CFG */
+export interface CfgEdge {
+    id: string;
+    from: string;
+    to: string;
+    direction: 'T' | 'F' | 'J';
+    functionName: string;
+    astId?: number;
+}
+/** Branch point mapping for runtime coverage - enhanced with line numbers and body PCs */
+export interface BranchPoint {
+    /** PC of the branch (JUMPI or first instruction of branch condition) */
+    pc: number;
+    /** AST ID of the condition */
+    astId: number;
+    /** Edge ID for true branch (condition != 0, fall through) */
+    trueEdge: string;
+    /** Edge ID for false branch (condition == 0, jump taken) */
+    falseEdge: string;
+    /** Function name */
+    function: string;
+    /** Block ID where branch occurs */
+    block: string;
+    /** Line number of the branch condition (1-based) */
+    conditionLine?: number;
+    /** Line number of the first statement in true branch (1-based) */
+    trueBodyLine?: number;
+    /** Line number of the first statement in false branch (1-based) */
+    falseBodyLine?: number;
+    /** First PC of the true branch body (for coverage tracking) */
+    trueBodyPc?: number;
+    /** First PC of the false branch body (for coverage tracking) */
+    falseBodyPc?: number;
+    /** Byte offset of condition in source */
+    offset?: number;
+    /** Length of condition in source */
+    length?: number;
+}
+/** Complete edge mapping for a contract */
+export interface EdgeMapping {
+    contract: string;
+    totalEdges: number;
+    /** Branch points - PC → (trueEdge, falseEdge) */
+    branches: BranchPoint[];
+    /** Quick lookup: PC → branch info */
+    pcToBranch: Map<number, BranchPoint>;
+    /** Quick lookup: edge ID → PC */
+    edgeToPc: Map<string, number>;
+}
+export interface EdgeMappingManifest {
+    generated: string;
+    totalContracts: number;
+    totalEdges: number;
+    contracts: {
+        name: string;
+        edges: number;
+        branches: number;
+    }[];
+}
+/**
+ * Parse CFG s-expression to extract edges
+ */
+export declare function parseCfgEdges(cfgContent: string): CfgEdge[];
+export declare class EdgeMapper {
+    private mappings;
+    /**
+     * Load CFG and source map branches, build edge mapping
+     */
+    loadContract(cfgPath: string, branchesPath: string, contractName: string): Promise<EdgeMapping>;
+    /**
+     * Get mapping for a contract
+     */
+    getMapping(contractName: string): EdgeMapping | undefined;
+    /**
+     * Look up edge from PC and branch direction
+     * @param taken - true if condition was non-zero (fall through), false if jump taken
+     */
+    pcToEdge(contractName: string, pc: number, taken: boolean): string | undefined;
+    /**
+     * Look up PC from edge ID
+     */
+    edgeToPc(contractName: string, edgeId: string): number | undefined;
+    /**
+     * Export mappings to JSON for Rust fuzzer
+     * Enhanced with line number information for LLM integration
+     */
+    exportForFuzzer(outputPath: string): void;
+}
+export declare function generateEdgeMappings(reconDir: string, contractNames: string[]): Promise<EdgeMappingManifest>;

package/dist/cfg/edge-mapper.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * Edge Mapper - Maps bytecode PCs to CFG edge IDs
+ *
+ * Approach using AST-level information:
+ * 1. CFG edges have astId (branch condition's AST ID)
+ * 2. Source map maps PC → source location → AST ID
+ * 3. For each edge's astId, find the first PC that maps to it
+ * 4. That PC is the "branch point" for that edge
+ *
+ * At runtime:
+ * - Fuzzer hits PC X
+ * - Look up: is X a branch point for any edge?
+ * - If yes, mark that edge as covered based on which direction was taken
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EdgeMapper = void 0;
+exports.parseCfgEdges = parseCfgEdges;
+exports.generateEdgeMappings = generateEdgeMappings;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ============================================================================
+// CFG Parser
+// ============================================================================
+/**
+ * Parse CFG s-expression to extract edges
+ */
+function parseCfgEdges(cfgContent) {
+    const edges = [];
+    const lines = cfgContent.split('\n');
+    for (const line of lines) {
+        // Parse edges: (edge "func_B0_T" B0 B1 condition :ast 123)
+        // Handle various formats including assert edges like "func_B0_assert0_T"
+        // Note: condition can contain nested parentheses, so we can't use [^)]
+        // Instead, match :ast at the end or allow optional :ast anywhere
+        let edgeMatch = /\(edge\s+"([^"]+)"\s+(\w+)\s+(\w+).*:ast\s+(\d+)/.exec(line);
+        if (!edgeMatch) {
+            // Try without :ast (edge might not have AST ID)
+            edgeMatch = /\(edge\s+"([^"]+)"\s+(\w+)\s+(\w+)/.exec(line);
+        }
+        if (edgeMatch) {
+            const [_, edgeId, fromBlock, toBlock, astIdStr] = edgeMatch;
+            // Parse edge ID to extract function, block, direction
+            // Patterns: "func_B0_T", "func_B0_F", "func_B0_J", "func_B0_assert0_T"
+            const parts = edgeId.match(/^(.+?)_(B\d+).*?_([TFJ])$/);
+            if (parts) {
+                const [__, funcName, blockId, dir] = parts;
+                edges.push({
+                    id: edgeId,
+                    from: fromBlock,
+                    to: toBlock,
+                    direction: dir,
+                    functionName: funcName,
+                    astId: astIdStr ? parseInt(astIdStr, 10) : undefined
+                });
+            }
+        }
+    }
+    return edges;
+}
+// ============================================================================
+// Edge Mapper Class
+// ============================================================================
+class EdgeMapper {
+    constructor() {
+        this.mappings = new Map();
+    }
+    /**
+     * Load CFG and source map branches, build edge mapping
+     */
+    async loadContract(cfgPath, branchesPath, contractName) {
+        var _a, _b, _c, _d, _e;
+        // Load and parse CFG
+        const cfgContent = fs.readFileSync(cfgPath, 'utf-8');
+        const edges = parseCfgEdges(cfgContent);
+        // Load branches manifest (from source map)
+        const branchManifest = JSON.parse(fs.readFileSync(branchesPath, 'utf-8'));
+        const contractBranches = (_b = (_a = branchManifest.contracts) === null || _a === void 0 ? void 0 : _a.find) === null || _b === void 0 ? void 0 : _b.call(_a, (c) => c.contract === contractName);
+        if (!contractBranches) {
+            throw new Error(`Contract ${contractName} not found in branches.json`);
+        }
+        // Build AST ID → first PC mapping from branches
+        // branches.json now contains: { pc, astId, allAstIds, offset, length } for each JUMPI
+        // allAstIds contains ALL AST nodes at this source location
+        const astIdToPc = new Map();
+        for (const branch of contractBranches.branches || []) {
+            // Include all AST IDs at this location
+            const allIds = branch.allAstIds || (branch.astId !== null ? [branch.astId] : []);
+            for (const astId of allIds) {
+                const existing = astIdToPc.get(astId);
+                // Keep the first (lowest) PC for each AST ID
+                if (existing === undefined || branch.pc < existing) {
+                    astIdToPc.set(astId, branch.pc);
+                }
+            }
+        }
+        // Group CFG edges by astId to find T/F pairs
+        const edgesByAstId = new Map();
+        for (const edge of edges) {
+            if (edge.astId === undefined)
+                continue;
+            if (edge.direction === 'J')
+                continue; // Skip unconditional jumps
+            if (!edgesByAstId.has(edge.astId)) {
+                edgesByAstId.set(edge.astId, {});
+            }
+            const group = edgesByAstId.get(edge.astId);
+            if (edge.direction === 'T')
+                group.T = edge;
+            if (edge.direction === 'F')
+                group.F = edge;
+        }
+        // Build branch points by correlating AST IDs
+        const branches = [];
+        const pcToBranch = new Map();
+        const edgeToPc = new Map();
+        for (const [astId, group] of edgesByAstId) {
+            const pc = astIdToPc.get(astId);
+            if (pc === undefined)
+                continue;
+            if (!group.T && !group.F)
+                continue;
+            // Use the T edge's info for function/block (they should be the same)
+            const refEdge = group.T || group.F;
+            // Find the branch info from branches.json to get line number and body PCs
+            const branchInfo = (_c = contractBranches.branches) === null || _c === void 0 ? void 0 : _c.find((b) => b.pc === pc || (b.allAstIds && b.allAstIds.includes(astId)));
+            const branchPoint = {
+                pc,
+                astId,
+                trueEdge: ((_d = group.T) === null || _d === void 0 ? void 0 : _d.id) || `${refEdge.functionName}_${refEdge.from}_T`,
+                falseEdge: ((_e = group.F) === null || _e === void 0 ? void 0 : _e.id) || `${refEdge.functionName}_${refEdge.from}_F`,
+                function: refEdge.functionName,
+                block: refEdge.from,
+                // Include line/offset info if available
+                conditionLine: branchInfo === null || branchInfo === void 0 ? void 0 : branchInfo.conditionLine,
+                trueBodyLine: branchInfo === null || branchInfo === void 0 ? void 0 : branchInfo.trueBodyLine,
+                falseBodyLine: branchInfo === null || branchInfo === void 0 ? void 0 : branchInfo.falseBodyLine,
+                trueBodyPc: branchInfo === null || branchInfo === void 0 ? void 0 : branchInfo.trueBodyPc,
+                falseBodyPc: branchInfo === null || branchInfo === void 0 ? void 0 : branchInfo.falseBodyPc,
+                offset: branchInfo === null || branchInfo === void 0 ? void 0 : branchInfo.offset,
+                length: branchInfo === null || branchInfo === void 0 ? void 0 : branchInfo.length
+            };
+            branches.push(branchPoint);
+            pcToBranch.set(pc, branchPoint);
+            // Map both edges to this PC
+            if (group.T)
+                edgeToPc.set(group.T.id, pc);
+            if (group.F)
+                edgeToPc.set(group.F.id, pc);
+        }
+        const mapping = {
+            contract: contractName,
+            totalEdges: edges.length,
+            branches,
+            pcToBranch,
+            edgeToPc
+        };
+        this.mappings.set(contractName, mapping);
+        return mapping;
+    }
+    /**
+     * Get mapping for a contract
+     */
+    getMapping(contractName) {
+        return this.mappings.get(contractName);
+    }
+    /**
+     * Look up edge from PC and branch direction
+     * @param taken - true if condition was non-zero (fall through), false if jump taken
+     */
+    pcToEdge(contractName, pc, taken) {
+        const mapping = this.mappings.get(contractName);
+        if (!mapping)
+            return undefined;
+        const branch = mapping.pcToBranch.get(pc);
+        if (!branch)
+            return undefined;
+        return taken ? branch.trueEdge : branch.falseEdge;
+    }
+    /**
+     * Look up PC from edge ID
+     */
+    edgeToPc(contractName, edgeId) {
+        const mapping = this.mappings.get(contractName);
+        return mapping === null || mapping === void 0 ? void 0 : mapping.edgeToPc.get(edgeId);
+    }
+    /**
+     * Export mappings to JSON for Rust fuzzer
+     * Enhanced with line number information for LLM integration
+     */
+    exportForFuzzer(outputPath) {
+        const output = {
+            generated: new Date().toISOString(),
+            totalContracts: 0,
+            totalEdges: 0,
+            contracts: {}
+        };
+        for (const [name, mapping] of this.mappings) {
+            output.totalContracts++;
+            output.totalEdges += mapping.totalEdges;
+            output.contracts[name] = {
+                totalEdges: mapping.totalEdges,
+                branches: mapping.branches.map(b => ({
+                    pc: b.pc,
+                    astId: b.astId,
+                    trueEdge: b.trueEdge,
+                    falseEdge: b.falseEdge,
+                    function: b.function,
+                    block: b.block,
+                    // Include line number info for LLM-friendly output
+                    ...(b.conditionLine !== undefined && { conditionLine: b.conditionLine }),
+                    ...(b.trueBodyLine !== undefined && { trueBodyLine: b.trueBodyLine }),
+                    ...(b.falseBodyLine !== undefined && { falseBodyLine: b.falseBodyLine }),
+                    // Include body PCs for coverage tracking
+                    ...(b.trueBodyPc !== undefined && { trueBodyPc: b.trueBodyPc }),
+                    ...(b.falseBodyPc !== undefined && { falseBodyPc: b.falseBodyPc }),
+                    ...(b.offset !== undefined && { offset: b.offset }),
+                    ...(b.length !== undefined && { length: b.length })
+                }))
+            };
+        }
+        fs.writeFileSync(outputPath, JSON.stringify(output, null, 2));
+    }
+}
+exports.EdgeMapper = EdgeMapper;
+// ============================================================================
+// CLI Integration
+// ============================================================================
+async function generateEdgeMappings(reconDir, contractNames) {
+    const mapper = new EdgeMapper();
+    const branchesPath = path.join(reconDir, 'branches.json');
+    if (!fs.existsSync(branchesPath)) {
+        throw new Error(`branches.json not found in ${reconDir}. Run 'recon-expander sourcemap' first.`);
+    }
+    const results = [];
+    for (const contractName of contractNames) {
+        const cfgPath = path.join(reconDir, `${contractName}.cfg.sexp`);
+        if (!fs.existsSync(cfgPath)) {
+            console.warn(`Warning: ${cfgPath} not found, skipping`);
+            continue;
+        }
+        try {
+            const mapping = await mapper.loadContract(cfgPath, branchesPath, contractName);
+            results.push({
+                name: contractName,
+                edges: mapping.totalEdges,
+                branches: mapping.branches.length
+            });
+            console.log(`  ✅ ${contractName}: ${mapping.totalEdges} edges, ${mapping.branches.length} branch points mapped`);
+        }
+        catch (err) {
+            console.warn(`Warning: Failed to map ${contractName}: ${err}`);
+        }
+    }
+    // Export combined mappings
+    const edgeMappingPath = path.join(reconDir, 'edge-mappings.json');
+    mapper.exportForFuzzer(edgeMappingPath);
+    return {
+        generated: new Date().toISOString(),
+        totalContracts: results.length,
+        totalEdges: results.reduce((sum, r) => sum + r.edges, 0),
+        contracts: results
+    };
+}

package/dist/cfg/emitter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * S-Expression Emitter - Converts CFG to s-expr format
+ *
+ * Output is designed for:
+ * - Easy parsing in Rust fuzzer
+ * - Direct translation to SMT-LIB2 for Bitwuzla
+ * - Human readability for debugging
+ */
+import { CompletePath, ContractModule, FunctionCFG } from './types';
+export declare function emitContract(module: ContractModule): string;
+export declare function emitPathToSMT(path: CompletePath, func: FunctionCFG): string;