recon-generate 0.0.17 → 0.0.19

package/dist/cfg/sourcemap.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Source Map to AST Mapping
+ *
+ * Creates the chain: pc → source map → AST node ID → CFG edge
+ *
+ * Solc source map format: "s:l:f:j" where:
+ *   s = byte offset in source file
+ *   l = length in bytes
+ *   f = source file index
+ *   j = jump type (i=into, o=out, -=regular)
+ *
+ * AST node src format: "offset:length:fileIndex"
+ */
+export interface SourceMapEntry {
+    offset: number;
+    length: number;
+    fileIndex: number;
+    jump: string;
+    pc: number;
+}
+/**
+ * Source line information for LLM-friendly output
+ */
+export interface SourceLineInfo {
+    line: number;
+    column: number;
+    endLine?: number;
+    endColumn?: number;
+}
+/**
+ * Convert byte offset to line/column in source file
+ * @param source Source file content
+ * @param offset Byte offset
+ * @returns Line info (1-based line, 0-based column)
+ */
+export declare function offsetToLine(source: string, offset: number): SourceLineInfo;
+/**
+ * Convert byte offset + length to line range
+ */
+export declare function offsetToLineRange(source: string, offset: number, length: number): SourceLineInfo;
+export interface AstLocation {
+    offset: number;
+    length: number;
+    fileIndex: number;
+}
+export interface PcToAstMapping {
+    contract: string;
+    codehash: string;
+    pcToAstId: Map<number, number>;
+    astIdToEdge: Map<number, string>;
+    pcToEdge: Map<number, string>;
+}
+/**
+ * Parse a compressed source map string into entries
+ * Source maps use compression where empty fields inherit from previous entry
+ */
+export declare function parseSourceMap(sourceMapStr: string, bytecode: string): SourceMapEntry[];
+/**
+ * Parse AST node's src field
+ */
+export declare function parseAstSrc(src: string): AstLocation | null;
+/**
+ * Build a map from source location to AST node IDs
+ * Only includes nodes we care about (branch conditions, statements)
+ * Uses iterative traversal to avoid stack overflow on large ASTs
+ */
+export declare function buildAstLocationMap(ast: any): Map<string, number[]>;
+/**
+ * Find AST node ID at a specific source map entry
+ */
+export declare function findAstNodeAtLocation(entry: SourceMapEntry, locToNodes: Map<string, number[]>): number | null;
+/**
+ * Find ALL AST node IDs at a specific source map entry
+ * Returns all nodes that match exactly or contain this location
+ */
+export declare function findAllAstNodesAtLocation(entry: SourceMapEntry, locToNodes: Map<string, number[]>): number[];
+/**
+ * Identify JUMPI instructions (branch points) from bytecode
+ */
+export declare function findJumpiPcs(bytecode: string): number[];
+/**
+ * Build complete PC → Edge mapping for a contract
+ */
+export declare function buildPcToEdgeMapping(contractName: string, bytecode: string, sourceMap: string, ast: any, cfgEdges: Map<number, string>): PcToAstMapping;
+/**
+ * Load build-info and extract source maps for all contracts
+ */
+export declare function loadBuildInfoSourceMaps(buildInfoPath: string): Map<string, {
+    bytecode: string;
+    sourceMap: string;
+    sourceFile: string;
+}>;
+/**
+ * Branch statement info with line numbers for LLM-friendly output
+ */
+export interface BranchStatementInfo {
+    pc: number;
+    astId: number | null;
+    /** All AST IDs at this source location (for matching with CFG edges) */
+    allAstIds: number[];
+    offset: number;
+    length: number;
+    /** Source file index (for multi-file contracts with inheritance) */
+    fileIndex: number;
+    /** Condition line number (1-based) - the line containing the branch condition */
+    conditionLine?: number;
+    /** First line of the true branch body (1-based) */
+    trueBodyLine?: number;
+    /** First line of the false branch body (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;
+    /** Function name this branch belongs to (from AST) */
+    functionName?: string;
+}
+/**
+ * Info about an IfStatement's bodies - AST IDs, lines, and PCs
+ */
+export interface IfStatementBodyInfo {
+    conditionLine: number;
+    trueBodyLine: number;
+    trueBodyAstId?: number;
+    falseBodyLine?: number;
+    falseBodyAstId?: number;
+    trueBodyPc?: number;
+    falseBodyPc?: number;
+}
+/**
+ * Output format for the fuzzer - compact branch-focused format
+ * Enhanced with line numbers for LLM integration
+ */
+export interface BranchMapping {
+    contract: string;
+    sourceFile: string;
+    fileIndex: number;
+    branches: BranchStatementInfo[];
+    totalInstructions: number;
+    bytecode?: string;
+}
+/**
+ * Generate compact branch mapping (only JUMPI instructions)
+ * Enhanced with line numbers for LLM-friendly output
+ * @param allAsts - Map of fileIndex -> AST for all source files (for multi-file contracts)
+ * @param sourceContents - Map of fileIndex -> source file content (for line number calculation)
+ */
+export declare function generateBranchMapping(contractName: string, bytecode: string, sourceMap: string, sourceFile: string, ast: any, allAsts?: Map<number, any>, sourceContents?: Map<number, string>): BranchMapping;
+/**
+ * Output format for the fuzzer
+ */
+export interface SourceMapOutput {
+    contract: string;
+    sourceFile: string;
+    pcMappings: {
+        pc: number;
+        astId: number | null;
+        edgeId: string | null;
+        file: number;
+        offset: number;
+        length: number;
+        isJumpi: boolean;
+    }[];
+    jumpiPcs: number[];
+}
+/**
+ * Generate complete source mapping for a contract
+ */
+export declare function generateSourceMapping(contractName: string, bytecode: string, sourceMap: string, sourceFile: string, ast: any, cfgEdges?: Map<number, string>): SourceMapOutput;