@snovon/solast 0.2.0

package/dist/detectors/integer-overflow-detector.js

@@ -0,0 +1,284 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntegerOverflowDetector = void 0;
+const ast_1 = require("./_common/ast");
+const index_1 = require("../index");
+/**
+ * v0.3 integer overflow / underflow detector. Narrowly scoped to arithmetic
+ * inside `unchecked { ... }` blocks (Solidity >=0.8.0 — `unchecked` does not
+ * exist below that). Issue #676 calls out Solidity 0.8.24 specifically, but
+ * the rule is version-agnostic above 0.8.0 because the runtime semantics of
+ * `unchecked` are identical across the 0.8.x series.
+ *
+ * Operators covered:
+ *   - Bare binary arithmetic: `+`, `-`, `*`
+ *   - Compound assignment forms: `+=`, `-=`, `*=`
+ *   - Increment / decrement: `++`, `--`
+ *
+ * Suppressions:
+ *   - Operations whose operands are all literal constants (constant folding)
+ *   - Bare binary arithmetic whose canonical signature matches a recognised
+ *     dominating require/assert guard from the same function (e.g.
+ *     `require(a + b >= a); unchecked { c = a + b; }` does not fire). Guards
+ *     inside conditional bodies are not treated as dominating.
+ *
+ * Coexists with the v0.2 `integer-overflow` warning rule in `index.ts`. Both
+ * may emit on the same site; the v0.3 rule emits at `error` severity with a
+ * remediation hint.
+ */
+const INCREMENT_OPERATORS = new Set(['++', '--']);
+const INCREMENT_DIRECTION = new Map([
+    ['++', 'overflow'],
+    ['--', 'underflow'],
+]);
+const REMEDIATION_HINT = new Map([
+    ['+', 'add a dominating range guard or move the addition out of `unchecked`'],
+    ['-', 'require the left operand is greater than or equal to the right operand before the unchecked block or use checked arithmetic'],
+    ['*', 'add a multiplication overflow guard or use checked arithmetic'],
+    ['+=', 'guard the equivalent addition before using unchecked compound assignment'],
+    ['-=', 'guard the equivalent subtraction before using unchecked compound assignment'],
+    ['*=', 'guard the equivalent multiplication before using unchecked compound assignment'],
+    ['++', 'guard the operand with `< type(uint256).max`, keep loop counter updates checked, or use checked increment'],
+    ['--', 'guard the operand with `> 0` or use checked decrement'],
+]);
+function operationDirection(op) {
+    return index_1.ARITH_DIRECTION.get(op) || INCREMENT_DIRECTION.get(op) || 'overflow';
+}
+function remediationFor(op) {
+    return REMEDIATION_HINT.get(op) || 'add a dominating range guard or use checked arithmetic';
+}
+class IntegerOverflowDetector {
+    id = 'integer-overflow-underflow';
+    patternKey = 'integer-overflow-underflow';
+    supportedAstKinds = ['parser', 'solc'];
+    findings = [];
+    currentFile = '';
+    currentContract = '';
+    currentFunction = '';
+    uncheckedDepth = 0;
+    inConditionalDepth = 0;
+    currentRequireSigStack = [];
+    requireGuards = new Set();
+    localSignedness = new Map();
+    stateSignedness = new Map();
+    currentLibraryIsSafeMath = false;
+    setFile(file) {
+        this.currentFile = file;
+        this.findings = [];
+        this.currentContract = '';
+        this.currentFunction = '';
+        this.uncheckedDepth = 0;
+        this.inConditionalDepth = 0;
+        this.currentRequireSigStack = [];
+        this.requireGuards.clear();
+        this.localSignedness.clear();
+        this.stateSignedness.clear();
+        this.currentLibraryIsSafeMath = false;
+    }
+    getFindings() {
+        return this.findings;
+    }
+    ContractDefinition(node) {
+        this.currentContract = node.name || '<anonymous>';
+        const kind = (node.kind || '').toLowerCase();
+        const lowered = (node.name || '').toLowerCase();
+        this.currentLibraryIsSafeMath =
+            kind === 'library' && (lowered === 'safemath' || lowered === 'math');
+        this.stateSignedness.clear();
+    }
+    ContractDefinition_post(_node) {
+        this.currentContract = '';
+        this.currentLibraryIsSafeMath = false;
+        this.stateSignedness.clear();
+    }
+    StateVariableDeclaration(node) {
+        for (const variable of node.variables || []) {
+            this.recordVariableSignedness(variable, this.stateSignedness);
+        }
+    }
+    FunctionDefinition(node) {
+        this.currentFunction = node.name || '<fallback>';
+        this.requireGuards.clear();
+        this.localSignedness.clear();
+        this.inConditionalDepth = 0;
+        this.currentRequireSigStack = [];
+        for (const parameter of node.parameters || []) {
+            this.recordVariableSignedness(parameter, this.localSignedness);
+        }
+        for (const parameter of node.returnParameters || []) {
+            this.recordVariableSignedness(parameter, this.localSignedness);
+        }
+    }
+    FunctionDefinition_post(_node) {
+        this.currentFunction = '';
+        this.requireGuards.clear();
+        this.localSignedness.clear();
+        this.inConditionalDepth = 0;
+        this.currentRequireSigStack = [];
+    }
+    ModifierDefinition(node) {
+        this.currentFunction = `modifier:${node.name || ''}`;
+        this.requireGuards.clear();
+        this.localSignedness.clear();
+        this.inConditionalDepth = 0;
+        this.currentRequireSigStack = [];
+        for (const parameter of node.parameters || []) {
+            this.recordVariableSignedness(parameter, this.localSignedness);
+        }
+    }
+    ModifierDefinition_post(_node) {
+        this.currentFunction = '';
+        this.requireGuards.clear();
+        this.localSignedness.clear();
+        this.inConditionalDepth = 0;
+        this.currentRequireSigStack = [];
+    }
+    VariableDeclarationStatement(node) {
+        for (const variable of node.variables || []) {
+            this.recordVariableSignedness(variable, this.localSignedness);
+        }
+    }
+    recordVariableSignedness(variable, target) {
+        if (!variable || !variable.name)
+            return;
+        target.set(variable.name, (0, index_1.classifyTypeName)(variable.typeName));
+    }
+    isUnsignedOperand(expr) {
+        if (!expr || typeof expr !== 'object')
+            return false;
+        if (expr.type === 'Identifier') {
+            const name = expr.name || '';
+            const local = this.localSignedness.get(name);
+            if (local !== undefined)
+                return local === 'unsigned';
+            const state = this.stateSignedness.get(name);
+            if (state !== undefined)
+                return state === 'unsigned';
+            return false;
+        }
+        return false;
+    }
+    UncheckedStatement(_node) {
+        this.uncheckedDepth++;
+    }
+    UncheckedStatement_post(_node) {
+        if (this.uncheckedDepth > 0)
+            this.uncheckedDepth--;
+    }
+    IfStatement(_node) { this.inConditionalDepth++; }
+    IfStatement_post(_node) { if (this.inConditionalDepth > 0)
+        this.inConditionalDepth--; }
+    ForStatement(_node) { this.inConditionalDepth++; }
+    ForStatement_post(_node) { if (this.inConditionalDepth > 0)
+        this.inConditionalDepth--; }
+    WhileStatement(_node) { this.inConditionalDepth++; }
+    WhileStatement_post(_node) { if (this.inConditionalDepth > 0)
+        this.inConditionalDepth--; }
+    DoWhileStatement(_node) { this.inConditionalDepth++; }
+    DoWhileStatement_post(_node) { if (this.inConditionalDepth > 0)
+        this.inConditionalDepth--; }
+    FunctionCall(node) {
+        if (!(0, index_1.isRequireFunctionCall)(node))
+            return;
+        const sigs = new Set();
+        const isUnsigned = (expr) => this.isUnsignedOperand(expr);
+        for (const arg of node.arguments || []) {
+            (0, index_1.collectGuardSignatures)(arg, sigs, isUnsigned);
+        }
+        this.currentRequireSigStack.push(sigs);
+    }
+    FunctionCall_post(node) {
+        if (!(0, index_1.isRequireFunctionCall)(node))
+            return;
+        const sigs = this.currentRequireSigStack.pop();
+        if (sigs && this.inConditionalDepth === 0) {
+            for (const s of sigs)
+                this.requireGuards.add(s);
+        }
+    }
+    BinaryOperation(node) {
+        if (this.currentLibraryIsSafeMath)
+            return;
+        if (!this.currentFunction)
+            return;
+        if (this.uncheckedDepth === 0)
+            return;
+        const isBareArith = index_1.ARITH_OPERATORS.has(node.operator);
+        const isCompoundArith = index_1.COMPOUND_ARITH_OPERATORS.has(node.operator);
+        if (!isBareArith && !isCompoundArith)
+            return;
+        if ((0, index_1.isConstantExpr)(node.left) && (0, index_1.isConstantExpr)(node.right))
+            return;
+        const lookupSig = isCompoundArith
+            ? `(${(0, index_1.expressionSignature)(node.left)}${index_1.COMPOUND_TO_BARE_ARITH.get(node.operator)}${(0, index_1.expressionSignature)(node.right)})`
+            : (0, index_1.expressionSignature)(node);
+        if (lookupSig) {
+            for (const activeSigs of this.currentRequireSigStack) {
+                if (activeSigs.has(lookupSig))
+                    return;
+            }
+            if (this.requireGuards.has(lookupSig))
+                return;
+        }
+        this.emitFinding(node, node.operator);
+    }
+    UnaryOperation(node) {
+        if (this.currentLibraryIsSafeMath)
+            return;
+        if (!this.currentFunction)
+            return;
+        if (this.uncheckedDepth === 0)
+            return;
+        if (!INCREMENT_OPERATORS.has(node.operator))
+            return;
+        this.emitFinding(node, node.operator);
+    }
+    emitFinding(node, operator) {
+        // tryLoc-with-zero-floor (roadmap 2.14.b7.x). The solc-walker can
+        // hand this detector BinaryOperation / UnaryOperation nodes whose
+        // src-derived loc has `line: 0` for constructed inner positions;
+        // assertLoc would throw and crash the scan.
+        const loc = (0, ast_1.tryLoc)(node) ?? { line: 0, endLine: 0, column: 0, endColumn: 0 };
+        const { line, endLine, column } = loc;
+        let endColumn = loc.endColumn;
+        if (node.type === 'UnaryOperation' && INCREMENT_OPERATORS.has(operator) && line === endLine) {
+            endColumn += node.isPrefix ? 1 : operator.length;
+        }
+        const direction = operationDirection(operator);
+        const remediation = remediationFor(operator);
+        this.findings.push({
+            file: this.currentFile,
+            contract: this.currentContract,
+            'function': this.currentFunction,
+            line,
+            endLine,
+            column,
+            endColumn,
+            pattern: 'integer-overflow-underflow',
+            confidence: 'high',
+            ruleId: this.id,
+            severity: 'error',
+            message: `Potential integer ${direction}: unchecked '${operator}' arithmetic in function ` +
+                `'${this.currentFunction}' — remediation: ${remediation}.`,
+            suggestedFix: remediation,
+            operationType: operator,
+            contractName: this.currentContract,
+            functionName: this.currentFunction,
+            sourceLocation: { line, column },
+            findingId: '',
+            contractHash: '',
+        });
+    }
+}
+exports.IntegerOverflowDetector = IntegerOverflowDetector;
+const _ioUnderflowProto = IntegerOverflowDetector.prototype;
+_ioUnderflowProto['ContractDefinition:exit'] = _ioUnderflowProto.ContractDefinition_post;
+_ioUnderflowProto['FunctionDefinition:exit'] = _ioUnderflowProto.FunctionDefinition_post;
+_ioUnderflowProto['ModifierDefinition:exit'] = _ioUnderflowProto.ModifierDefinition_post;
+_ioUnderflowProto['UncheckedStatement:exit'] = _ioUnderflowProto.UncheckedStatement_post;
+_ioUnderflowProto['FunctionCall:exit'] = _ioUnderflowProto.FunctionCall_post;
+_ioUnderflowProto['IfStatement:exit'] = _ioUnderflowProto.IfStatement_post;
+_ioUnderflowProto['ForStatement:exit'] = _ioUnderflowProto.ForStatement_post;
+_ioUnderflowProto['WhileStatement:exit'] = _ioUnderflowProto.WhileStatement_post;
+_ioUnderflowProto['DoWhileStatement:exit'] = _ioUnderflowProto.DoWhileStatement_post;
+//# sourceMappingURL=integer-overflow-detector.js.map

package/dist/detectors/integer-overflow.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Integer-overflow detector (v0.2 main rule, id `integer-overflow`).
+ * Extracted from `src/index.ts` per roadmap item 1.1 (split god-file
+ * into focused modules). Public API surface is unchanged —
+ * `src/index.ts` re-exports `IntegerOverflowDetector` so
+ * `createDefaultDetectorRegistry` and downstream consumers continue
+ * to see it at the same path.
+ *
+ * The detector flags unprotected `+`, `-`, `*` arithmetic that may
+ * overflow or underflow on a 256-bit integer in non-checked Solidity
+ * contexts. See `docs/detectors/integer-overflow.md` for the
+ * user-facing contract.
+ *
+ * Note: `src/detectors/integer-overflow-detector.ts` is a SEPARATE
+ * rule (`integer-overflow-underflow`, the v0.1 architecture-fixture
+ * detector). Filenames do not collide.
+ */
+import type { ScanResult } from '../index';
+/**
+ * Detects unprotected `+`, `-`, `*` arithmetic that may overflow or underflow
+ * on a 256-bit integer in non-checked Solidity contexts. The rule fires when
+ * either:
+ *   - The pragma allows a compiler version older than 0.8.0 (no built-in
+ *     overflow checks) and the operation is not wrapped in a SafeMath/Math
+ *     library or guarded by a prior `require(a + b >= a)` style check; or
+ *   - The pragma is `>=0.8.0` but the operation appears inside an
+ *     `unchecked { ... }` block, where built-in checks are explicitly
+ *     suppressed.
+ *
+ * Inside `unchecked { ... }` blocks the rule additionally flags compound
+ * assignment forms `+=`, `-=`, and `*=`, which share the same wrap-around
+ * runtime behavior as their bare counterparts. Compound assignments outside
+ * `unchecked` remain out of scope because Solidity >=0.8.0 still inserts the
+ * overflow check at the assignment site.
+ *
+ * Suppressions:
+ *   - SafeMath/Math library bodies — these are the guard implementation, not
+ *     the call site. Their internal `+`/`-`/`*` operations are not flagged.
+ *   - Direct calls to `SafeMath`/`Math` library methods — these never appear
+ *     as `BinaryOperation` nodes, so they are filtered out by the AST shape.
+ *   - Operations syntactically inside a `require(...)` / `assert(...)` call,
+ *     and subsequent operations whose canonical signature matches a
+ *     recognised overflow/underflow guard from an earlier `require(...)` in the
+ *     same function body. Recognised shapes include `a + b >= a` /
+ *     `a + b > a` (and operand-swapped / `<=` variants) for addition,
+ *     `a >= b` / `a > b` (and the post-check `a - b <= a`) for subtraction,
+ *     and `a == 0 || (a * b) / a == b` or `(a * b) <= MAX` for multiplication.
+ *     Ineffective predicates like `a + b > 0`, `a - b >= 0`, or `a * b != 0`
+ *     do NOT count as guards.
+ *   - Operations whose operands are all literal constants (constant folding).
+ */
+export declare class IntegerOverflowDetector {
+    readonly id = "integer-overflow";
+    readonly patternKey = "integer-overflow";
+    readonly supportedAstKinds: ("parser" | "solc")[];
+    findings: ScanResult[];
+    currentFile: string;
+    private currentContract;
+    private currentFunction;
+    private uncheckedDepth;
+    private inConditionalDepth;
+    private currentRequireSigStack;
+    private pragmaAllowsPre08;
+    private sawAnyPragmaSolidity;
+    private currentLibraryIsSafeMath;
+    private requireGuards;
+    private localSignedness;
+    private stateSignedness;
+    setFile(file: string): void;
+    getFindings(): ScanResult[];
+    PragmaDirective(node: any): void;
+    ContractDefinition(node: any): void;
+    ContractDefinition_post(_node: any): void;
+    StateVariableDeclaration(node: any): void;
+    FunctionDefinition(node: any): void;
+    FunctionDefinition_post(_node: any): void;
+    ModifierDefinition(node: any): void;
+    ModifierDefinition_post(_node: any): void;
+    VariableDeclarationStatement(node: any): void;
+    private recordVariableSignedness;
+    private isUnsignedOperand;
+    UncheckedStatement(_node: any): void;
+    UncheckedStatement_post(_node: any): void;
+    IfStatement(_node: any): void;
+    IfStatement_post(_node: any): void;
+    ForStatement(_node: any): void;
+    ForStatement_post(_node: any): void;
+    WhileStatement(_node: any): void;
+    WhileStatement_post(_node: any): void;
+    DoWhileStatement(_node: any): void;
+    DoWhileStatement_post(_node: any): void;
+    FunctionCall(node: any): void;
+    FunctionCall_post(node: any): void;
+    BinaryOperation(node: any): void;
+}