sourceverity 1.0.3 → 1.0.5

package/dist/analysis/arrayBoundsCore.js

@@ -0,0 +1,957 @@
+import { statementExitsControlFlow } from "./controlFlowGuards.js";
+import { unwrapExpression } from "./values.js";
+function isParamBoundedCondition(cond, paramName, arrayLength, ts, isExitGuard) {
+    const unwrapped = unwrapExpression(cond, ts);
+    if (isExitGuard) {
+        // Exit guard disjunction: param < 0 || param >= arrayLength (or param > arrayLength - 1)
+        if (ts.isBinaryExpression(unwrapped) && unwrapped.operatorToken.kind === ts.SyntaxKind.BarBarToken) {
+            let hasLowerExit = false;
+            let hasUpperExit = false;
+            const disjuncts = [];
+            function collectOrs(e) {
+                const u = unwrapExpression(e, ts);
+                if (ts.isBinaryExpression(u) && u.operatorToken.kind === ts.SyntaxKind.BarBarToken) {
+                    collectOrs(u.left);
+                    collectOrs(u.right);
+                }
+                else {
+                    disjuncts.push(u);
+                }
+            }
+            collectOrs(unwrapped);
+            for (const d of disjuncts) {
+                if (ts.isBinaryExpression(d)) {
+                    const op = d.operatorToken.kind;
+                    const left = unwrapExpression(d.left, ts);
+                    const right = unwrapExpression(d.right, ts);
+                    if (ts.isIdentifier(left) && left.text === paramName) {
+                        if (ts.isNumericLiteral(right)) {
+                            const n = Number(right.text);
+                            if ((op === ts.SyntaxKind.LessThanToken && n === 0) || (op === ts.SyntaxKind.LessThanEqualsToken && n === -1)) {
+                                hasLowerExit = true;
+                            }
+                            if ((op === ts.SyntaxKind.GreaterThanEqualsToken && n >= arrayLength) || (op === ts.SyntaxKind.GreaterThanToken && n >= arrayLength - 1)) {
+                                hasUpperExit = true;
+                            }
+                        }
+                        if (ts.isPropertyAccessExpression(right) && right.name.text === "length") {
+                            if (op === ts.SyntaxKind.GreaterThanEqualsToken || op === ts.SyntaxKind.GreaterThanToken) {
+                                hasUpperExit = true;
+                            }
+                        }
+                        if (ts.isBinaryExpression(right) && right.operatorToken.kind === ts.SyntaxKind.MinusToken) {
+                            const rLeft = unwrapExpression(right.left, ts);
+                            if (ts.isPropertyAccessExpression(rLeft) && rLeft.name.text === "length") {
+                                if (op === ts.SyntaxKind.GreaterThanToken) {
+                                    hasUpperExit = true;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            return hasLowerExit && hasUpperExit;
+        }
+    }
+    else {
+        // Entry guard conjunction: param >= 0 && param < arrayLength
+        if (ts.isBinaryExpression(unwrapped) && unwrapped.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) {
+            let hasLowerEntry = false;
+            let hasUpperEntry = false;
+            const conjuncts = [];
+            function collectAnds(e) {
+                const u = unwrapExpression(e, ts);
+                if (ts.isBinaryExpression(u) && u.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) {
+                    collectAnds(u.left);
+                    collectAnds(u.right);
+                }
+                else {
+                    conjuncts.push(u);
+                }
+            }
+            collectAnds(unwrapped);
+            for (const c of conjuncts) {
+                if (ts.isBinaryExpression(c)) {
+                    const op = c.operatorToken.kind;
+                    const left = unwrapExpression(c.left, ts);
+                    const right = unwrapExpression(c.right, ts);
+                    if (ts.isIdentifier(left) && left.text === paramName) {
+                        if (ts.isNumericLiteral(right)) {
+                            const n = Number(right.text);
+                            if ((op === ts.SyntaxKind.GreaterThanEqualsToken && n === 0) || (op === ts.SyntaxKind.GreaterThanToken && n === -1)) {
+                                hasLowerEntry = true;
+                            }
+                            if ((op === ts.SyntaxKind.LessThanToken && n <= arrayLength) || (op === ts.SyntaxKind.LessThanEqualsToken && n <= arrayLength - 1)) {
+                                hasUpperEntry = true;
+                            }
+                        }
+                        if (ts.isPropertyAccessExpression(right) && right.name.text === "length") {
+                            if (op === ts.SyntaxKind.LessThanToken || op === ts.SyntaxKind.LessThanEqualsToken) {
+                                hasUpperEntry = true;
+                            }
+                        }
+                    }
+                }
+            }
+            return hasLowerEntry && hasUpperEntry;
+        }
+    }
+    return false;
+}
+function normalizeIndexExpression(expr, ts, checker) {
+    const unwrapped = unwrapExpression(expr, ts);
+    if (ts.isIdentifier(unwrapped)) {
+        const sym = checker?.getSymbolAtLocation(unwrapped);
+        return { baseText: unwrapped.text, baseSymbol: sym, offset: 0 };
+    }
+    if (ts.isBinaryExpression(unwrapped)) {
+        const left = unwrapExpression(unwrapped.left, ts);
+        const right = unwrapExpression(unwrapped.right, ts);
+        if (ts.isIdentifier(left) && ts.isNumericLiteral(right)) {
+            const num = Number(right.text);
+            if (!Number.isNaN(num)) {
+                const sym = checker?.getSymbolAtLocation(left);
+                if (unwrapped.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+                    return { baseText: left.text, baseSymbol: sym, offset: num };
+                }
+                if (unwrapped.operatorToken.kind === ts.SyntaxKind.MinusToken) {
+                    return { baseText: left.text, baseSymbol: sym, offset: -num };
+                }
+            }
+        }
+    }
+    return undefined;
+}
+function arraysMatch(a, b) {
+    if (!a || !b)
+        return false;
+    if (a.symbol && b.symbol && a.symbol === b.symbol)
+        return true;
+    return a.text === b.text;
+}
+function isNodeDescendantOf(child, parent) {
+    let cur = child;
+    while (cur) {
+        if (cur === parent)
+            return true;
+        cur = cur.parent;
+    }
+    return false;
+}
+function normalizeArrayTarget(expr, ts, checker) {
+    const unwrapped = unwrapExpression(expr, ts);
+    if (ts.isIdentifier(unwrapped)) {
+        const sym = checker?.getSymbolAtLocation(unwrapped);
+        return { text: unwrapped.text, symbol: sym };
+    }
+    if (ts.isPropertyAccessExpression(unwrapped)) {
+        const sym = checker?.getSymbolAtLocation(unwrapped);
+        return { text: unwrapped.getText(), symbol: sym };
+    }
+    return undefined;
+}
+/**
+ * Checks if a binary condition expression guards an index lower bound (e.g. index === -1 or index < 0).
+ */
+function isLowerBoundNegativeGuard(cond, indexInfo, ts, checker) {
+    const unwrapped = unwrapExpression(cond, ts);
+    if (!ts.isBinaryExpression(unwrapped))
+        return false;
+    const left = unwrapExpression(unwrapped.left, ts);
+    const right = unwrapExpression(unwrapped.right, ts);
+    const op = unwrapped.operatorToken.kind;
+    function matchesIndex(ident) {
+        if (!ts.isIdentifier(ident))
+            return false;
+        if (ident.text !== indexInfo.baseText)
+            return false;
+        if (checker && indexInfo.baseSymbol) {
+            let sym = checker.getSymbolAtLocation(ident);
+            if (sym && (sym.flags & ts.SymbolFlags.Alias) !== 0) {
+                try {
+                    sym = checker.getAliasedSymbol(sym);
+                }
+                catch {
+                    // ignore
+                }
+            }
+            if (sym && sym !== indexInfo.baseSymbol)
+                return false;
+        }
+        return true;
+    }
+    // index === -1 or -1 === index
+    if (op === ts.SyntaxKind.EqualsEqualsToken || op === ts.SyntaxKind.EqualsEqualsEqualsToken) {
+        if (matchesIndex(left)) {
+            if (ts.isPrefixUnaryExpression(right) && right.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(right.operand) && right.operand.text === "1") {
+                return true;
+            }
+        }
+        if (matchesIndex(right)) {
+            if (ts.isPrefixUnaryExpression(left) && left.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(left.operand) && left.operand.text === "1") {
+                return true;
+            }
+        }
+    }
+    // index < 0
+    if (op === ts.SyntaxKind.LessThanToken) {
+        if (matchesIndex(left) && ts.isNumericLiteral(right) && right.text === "0") {
+            return true;
+        }
+    }
+    // 0 > index
+    if (op === ts.SyntaxKind.GreaterThanToken) {
+        if (ts.isNumericLiteral(left) && left.text === "0" && matchesIndex(right)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Checks if an expression represents `array.length` or `array.length - K`.
+ */
+function parseArrayLengthOffset(expr, arrayInfo, ts, checker) {
+    const unwrapped = unwrapExpression(expr, ts);
+    const targets = Array.isArray(arrayInfo) ? arrayInfo : [arrayInfo];
+    // array.length
+    if (ts.isPropertyAccessExpression(unwrapped) && unwrapped.name.text === "length") {
+        const objTarget = normalizeArrayTarget(unwrapped.expression, ts, checker);
+        if (objTarget && targets.some((t) => arraysMatch(objTarget, t))) {
+            return 0;
+        }
+    }
+    // array.length - K
+    if (ts.isBinaryExpression(unwrapped) && unwrapped.operatorToken.kind === ts.SyntaxKind.MinusToken) {
+        const left = unwrapExpression(unwrapped.left, ts);
+        const right = unwrapExpression(unwrapped.right, ts);
+        if (ts.isPropertyAccessExpression(left) && left.name.text === "length") {
+            const objTarget = normalizeArrayTarget(left.expression, ts, checker);
+            if (objTarget && targets.some((t) => arraysMatch(objTarget, t)) && ts.isNumericLiteral(right)) {
+                const k = Number(right.text);
+                if (!Number.isNaN(k))
+                    return k;
+            }
+        }
+    }
+    return undefined;
+}
+function parseLengthPropertyTarget(expr, ts, checker) {
+    const unwrapped = unwrapExpression(expr, ts);
+    if (ts.isPropertyAccessExpression(unwrapped) && unwrapped.name.text === "length") {
+        return normalizeArrayTarget(unwrapped.expression, ts, checker);
+    }
+    return undefined;
+}
+function parseGuardedLengthCondition(expr, arrayTarget, ts, checker) {
+    const unwrapped = unwrapExpression(expr, ts);
+    if (ts.isBinaryExpression(unwrapped)) {
+        const op = unwrapped.operatorToken.kind;
+        const left = unwrapExpression(unwrapped.left, ts);
+        const right = unwrapExpression(unwrapped.right, ts);
+        // Conjunction: A && B
+        if (op === ts.SyntaxKind.AmpersandAmpersandToken) {
+            const leftFact = parseGuardedLengthCondition(unwrapped.left, arrayTarget, ts, checker);
+            const rightFact = parseGuardedLengthCondition(unwrapped.right, arrayTarget, ts, checker);
+            if (leftFact && rightFact) {
+                return {
+                    minLength: Math.max(leftFact.minLength, rightFact.minLength),
+                    exactLength: leftFact.exactLength ?? rightFact.exactLength,
+                };
+            }
+            return leftFact ?? rightFact;
+        }
+        const leftTarget = parseLengthPropertyTarget(left, ts, checker);
+        const rightTarget = parseLengthPropertyTarget(right, ts, checker);
+        // Left is arr.length, right is number literal
+        if (arraysMatch(leftTarget, arrayTarget) && ts.isNumericLiteral(right)) {
+            const num = Number(right.text);
+            if (Number.isInteger(num) && num >= 0) {
+                if (op === ts.SyntaxKind.EqualsEqualsEqualsToken || op === ts.SyntaxKind.EqualsEqualsToken) {
+                    return { minLength: num, exactLength: num };
+                }
+                if (op === ts.SyntaxKind.GreaterThanEqualsToken) {
+                    return { minLength: num };
+                }
+                if (op === ts.SyntaxKind.GreaterThanToken) {
+                    return { minLength: num + 1 };
+                }
+            }
+        }
+        // Right is arr.length, left is number literal
+        if (arraysMatch(rightTarget, arrayTarget) && ts.isNumericLiteral(left)) {
+            const num = Number(left.text);
+            if (Number.isInteger(num) && num >= 0) {
+                if (op === ts.SyntaxKind.EqualsEqualsEqualsToken || op === ts.SyntaxKind.EqualsEqualsToken) {
+                    return { minLength: num, exactLength: num };
+                }
+                if (op === ts.SyntaxKind.LessThanEqualsToken) {
+                    return { minLength: num };
+                }
+                if (op === ts.SyntaxKind.LessThanToken) {
+                    return { minLength: num + 1 };
+                }
+            }
+        }
+    }
+    return undefined;
+}
+function parseExitGuardedLengthCondition(expr, arrayTarget, ts, checker) {
+    const unwrapped = unwrapExpression(expr, ts);
+    // Disjunction: A || B
+    if (ts.isBinaryExpression(unwrapped) && unwrapped.operatorToken.kind === ts.SyntaxKind.BarBarToken) {
+        const leftFact = parseExitGuardedLengthCondition(unwrapped.left, arrayTarget, ts, checker);
+        const rightFact = parseExitGuardedLengthCondition(unwrapped.right, arrayTarget, ts, checker);
+        if (leftFact && rightFact) {
+            return {
+                minLength: Math.max(leftFact.minLength, rightFact.minLength),
+                exactLength: leftFact.exactLength ?? rightFact.exactLength,
+            };
+        }
+        return leftFact ?? rightFact;
+    }
+    // !arr.length or !arr
+    if (ts.isPrefixUnaryExpression(unwrapped) && unwrapped.operator === ts.SyntaxKind.ExclamationToken) {
+        const inner = unwrapExpression(unwrapped.operand, ts);
+        const target = parseLengthPropertyTarget(inner, ts, checker);
+        if (arraysMatch(target, arrayTarget)) {
+            return { minLength: 1 };
+        }
+    }
+    if (ts.isBinaryExpression(unwrapped)) {
+        const op = unwrapped.operatorToken.kind;
+        const left = unwrapExpression(unwrapped.left, ts);
+        const right = unwrapExpression(unwrapped.right, ts);
+        const leftTarget = parseLengthPropertyTarget(left, ts, checker);
+        const rightTarget = parseLengthPropertyTarget(right, ts, checker);
+        // Left is arr.length, right is number
+        if (arraysMatch(leftTarget, arrayTarget) && ts.isNumericLiteral(right)) {
+            const num = Number(right.text);
+            if (Number.isInteger(num) && num >= 0) {
+                if (op === ts.SyntaxKind.ExclamationEqualsEqualsToken || op === ts.SyntaxKind.ExclamationEqualsToken) {
+                    return { minLength: num, exactLength: num };
+                }
+                if (op === ts.SyntaxKind.LessThanToken) {
+                    return { minLength: num };
+                }
+                if (op === ts.SyntaxKind.LessThanEqualsToken) {
+                    return { minLength: num + 1 };
+                }
+                if ((op === ts.SyntaxKind.EqualsEqualsEqualsToken || op === ts.SyntaxKind.EqualsEqualsToken) && num === 0) {
+                    return { minLength: 1 };
+                }
+            }
+        }
+        // Right is arr.length, left is number
+        if (arraysMatch(rightTarget, arrayTarget) && ts.isNumericLiteral(left)) {
+            const num = Number(left.text);
+            if (Number.isInteger(num) && num >= 0) {
+                if (op === ts.SyntaxKind.ExclamationEqualsEqualsToken || op === ts.SyntaxKind.ExclamationEqualsToken) {
+                    return { minLength: num, exactLength: num };
+                }
+                if (op === ts.SyntaxKind.GreaterThanToken) {
+                    return { minLength: num };
+                }
+                if (op === ts.SyntaxKind.GreaterThanEqualsToken) {
+                    return { minLength: num + 1 };
+                }
+                if ((op === ts.SyntaxKind.EqualsEqualsEqualsToken || op === ts.SyntaxKind.EqualsEqualsToken) && num === 0) {
+                    return { minLength: 1 };
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Checks if a binary condition expression guards an upper bound against array.length.
+ * e.g. `index >= array.length` or `index >= array.length - 1` or `index > array.length - 1`.
+ */
+function isUpperBoundLengthGuard(cond, indexInfo, arrayInfo, ts, checker) {
+    const unwrapped = unwrapExpression(cond, ts);
+    if (!ts.isBinaryExpression(unwrapped))
+        return { isGuard: false, maxAllowedOffset: 0 };
+    const left = unwrapExpression(unwrapped.left, ts);
+    const right = unwrapExpression(unwrapped.right, ts);
+    const op = unwrapped.operatorToken.kind;
+    function matchesIndex(ident) {
+        if (!ts.isIdentifier(ident))
+            return false;
+        if (ident.text !== indexInfo.baseText)
+            return false;
+        if (checker && indexInfo.baseSymbol) {
+            let sym = checker.getSymbolAtLocation(ident);
+            if (sym && (sym.flags & ts.SymbolFlags.Alias) !== 0) {
+                try {
+                    sym = checker.getAliasedSymbol(sym);
+                }
+                catch {
+                    // ignore
+                }
+            }
+            if (sym && sym !== indexInfo.baseSymbol)
+                return false;
+        }
+        return true;
+    }
+    // Pattern: `index >= [length expression]`
+    if (op === ts.SyntaxKind.GreaterThanEqualsToken && matchesIndex(left)) {
+        const lengthMinus = parseArrayLengthOffset(right, arrayInfo, ts, checker);
+        if (lengthMinus !== undefined) {
+            return { isGuard: true, maxAllowedOffset: lengthMinus };
+        }
+    }
+    // Pattern: `[length expression] <= index`
+    if (op === ts.SyntaxKind.LessThanEqualsToken && matchesIndex(right)) {
+        const lengthMinus = parseArrayLengthOffset(left, arrayInfo, ts, checker);
+        if (lengthMinus !== undefined) {
+            return { isGuard: true, maxAllowedOffset: lengthMinus };
+        }
+    }
+    // Pattern: `index > [length expression]`
+    if (op === ts.SyntaxKind.GreaterThanToken && matchesIndex(left)) {
+        const lengthMinus = parseArrayLengthOffset(right, arrayInfo, ts, checker);
+        if (lengthMinus !== undefined) {
+            return { isGuard: true, maxAllowedOffset: lengthMinus - 1 };
+        }
+    }
+    // Pattern: `[length expression] < index`
+    if (op === ts.SyntaxKind.LessThanToken && matchesIndex(right)) {
+        const lengthMinus = parseArrayLengthOffset(left, arrayInfo, ts, checker);
+        if (lengthMinus !== undefined) {
+            return { isGuard: true, maxAllowedOffset: lengthMinus - 1 };
+        }
+    }
+    return { isGuard: false, maxAllowedOffset: 0 };
+}
+/**
+ * Checks if an exit condition contains both a lower-bound check and an upper-bound check.
+ */
+function isCompleteBoundsExitGuard(cond, indexInfo, arrayInfo, ts, checker) {
+    // Collect all OR disjuncts: A || B || C
+    const disjuncts = [];
+    function collectOrs(e) {
+        const u = unwrapExpression(e, ts);
+        if (ts.isBinaryExpression(u) && u.operatorToken.kind === ts.SyntaxKind.BarBarToken) {
+            collectOrs(u.left);
+            collectOrs(u.right);
+        }
+        else {
+            disjuncts.push(u);
+        }
+    }
+    collectOrs(cond);
+    let hasLower = false;
+    let maxUpperOffset = -1;
+    for (const d of disjuncts) {
+        if (isLowerBoundNegativeGuard(d, indexInfo, ts, checker)) {
+            hasLower = true;
+        }
+        const upper = isUpperBoundLengthGuard(d, indexInfo, arrayInfo, ts, checker);
+        if (upper.isGuard) {
+            maxUpperOffset = Math.max(maxUpperOffset, upper.maxAllowedOffset);
+        }
+    }
+    if (hasLower && maxUpperOffset >= indexInfo.offset) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Checks if an entry condition contains both a lower-bound non-negative check and an upper-bound check against array.length.
+ * e.g. `if (i >= 0 && i < array.length - 1)`
+ */
+function isPositiveBoundsEntryGuard(cond, indexInfo, arrayInfo, ts) {
+    const conjuncts = [];
+    function collectAnds(e) {
+        const u = unwrapExpression(e, ts);
+        if (ts.isBinaryExpression(u) && u.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) {
+            collectAnds(u.left);
+            collectAnds(u.right);
+        }
+        else {
+            conjuncts.push(u);
+        }
+    }
+    collectAnds(cond);
+    let hasLower = false;
+    let maxUpperOffset = -1;
+    for (const c of conjuncts) {
+        const u = unwrapExpression(c, ts);
+        if (!ts.isBinaryExpression(u))
+            continue;
+        const left = unwrapExpression(u.left, ts);
+        const right = unwrapExpression(u.right, ts);
+        const op = u.operatorToken.kind;
+        if (op === ts.SyntaxKind.GreaterThanEqualsToken && ts.isIdentifier(left) && left.text === indexInfo.baseText && ts.isNumericLiteral(right) && right.text === "0") {
+            hasLower = true;
+        }
+        if (op === ts.SyntaxKind.LessThanEqualsToken && ts.isNumericLiteral(left) && left.text === "0" && ts.isIdentifier(right) && right.text === indexInfo.baseText) {
+            hasLower = true;
+        }
+        if (op === ts.SyntaxKind.GreaterThanToken && ts.isIdentifier(left) && left.text === indexInfo.baseText) {
+            if (ts.isPrefixUnaryExpression(right) && right.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(right.operand) && right.operand.text === "1") {
+                hasLower = true;
+            }
+        }
+        if (op === ts.SyntaxKind.LessThanToken && ts.isIdentifier(left) && left.text === indexInfo.baseText) {
+            const lengthMinus = parseArrayLengthOffset(right, arrayInfo, ts);
+            if (lengthMinus !== undefined) {
+                maxUpperOffset = Math.max(maxUpperOffset, lengthMinus);
+            }
+        }
+        if (op === ts.SyntaxKind.LessThanEqualsToken && ts.isIdentifier(left) && left.text === indexInfo.baseText) {
+            const lengthMinus = parseArrayLengthOffset(right, arrayInfo, ts);
+            if (lengthMinus !== undefined && lengthMinus >= 1) {
+                maxUpperOffset = Math.max(maxUpperOffset, lengthMinus - 1);
+            }
+        }
+    }
+    if (hasLower && indexInfo.offset >= 0 && indexInfo.offset <= maxUpperOffset) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Checks if an array target is a static, non-empty const array initialized with an array literal.
+ */
+function resolveStaticConstArrayLiteral(arrayExpr, ts, checker) {
+    if (!checker)
+        return undefined;
+    const unwrapped = unwrapExpression(arrayExpr, ts);
+    let symbol = checker.getSymbolAtLocation(unwrapped);
+    if (!symbol)
+        return undefined;
+    if (symbol.flags & ts.SymbolFlags.Alias) {
+        try {
+            symbol = checker.getAliasedSymbol(symbol);
+        }
+        catch {
+            // ignore
+        }
+    }
+    const decls = symbol.getDeclarations();
+    if (!decls || decls.length === 0)
+        return undefined;
+    for (const decl of decls) {
+        if (ts.isVariableDeclaration(decl) && decl.initializer) {
+            const init = unwrapExpression(decl.initializer, ts);
+            if (ts.isArrayLiteralExpression(init)) {
+                const isConst = decl.parent &&
+                    ts.isVariableDeclarationList(decl.parent) &&
+                    Boolean(decl.parent.flags & ts.NodeFlags.Const);
+                if (isConst) {
+                    const length = init.elements.length;
+                    if (length > 0) {
+                        return {
+                            elements: init.elements,
+                            length,
+                            name: ts.isIdentifier(decl.name) ? decl.name.text : unwrapped.getText(),
+                        };
+                    }
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Checks if a static array access has a literal integer index guaranteed to be in-bounds.
+ */
+function isStaticArrayLiteralBoundedIndex(operand, ts, checker) {
+    const staticArray = resolveStaticConstArrayLiteral(operand.expression, ts, checker);
+    if (!staticArray)
+        return undefined;
+    const indexExpr = unwrapExpression(operand.argumentExpression, ts);
+    // Case A: Literal numeric integer index e.g. tiers[0]! or colW[2]!
+    if (ts.isNumericLiteral(indexExpr)) {
+        const k = Number(indexExpr.text);
+        if (Number.isInteger(k) && k >= 0 && k < staticArray.length) {
+            return {
+                isGuarded: true,
+                evidence: `Literal index ${k} is statically in-bounds for constant array '${staticArray.name}' of length ${staticArray.length}.`,
+            };
+        }
+    }
+    // Case B: array[array.length - 1]!
+    if (ts.isBinaryExpression(indexExpr) && indexExpr.operatorToken.kind === ts.SyntaxKind.MinusToken) {
+        const left = unwrapExpression(indexExpr.left, ts);
+        const right = unwrapExpression(indexExpr.right, ts);
+        if (ts.isPropertyAccessExpression(left) &&
+            left.name.text === "length" &&
+            ts.isNumericLiteral(right) &&
+            right.text === "1") {
+            return {
+                isGuarded: true,
+                evidence: `Index 'length - 1' is statically in-bounds for non-empty constant array '${staticArray.name}' of length ${staticArray.length}.`,
+            };
+        }
+    }
+    return undefined;
+}
+/**
+ * Checks if a literal index access is proven in-bounds by a dominating fixed-length equality or comparison guard.
+ * e.g. `if (arr.length === 2) arr[0]!` or `if (arr.length >= 2) arr[1]!`
+ */
+function isFixedLengthGuardedIndex(node, operand, ts, checker) {
+    const arrayTarget = normalizeArrayTarget(operand.expression, ts, checker);
+    if (!arrayTarget)
+        return undefined;
+    const indexExpr = unwrapExpression(operand.argumentExpression, ts);
+    let k;
+    let lastElementOffset;
+    if (ts.isNumericLiteral(indexExpr)) {
+        const num = Number(indexExpr.text);
+        if (Number.isInteger(num) && num >= 0) {
+            k = num;
+        }
+    }
+    else if (ts.isBinaryExpression(indexExpr) && indexExpr.operatorToken.kind === ts.SyntaxKind.MinusToken) {
+        const left = unwrapExpression(indexExpr.left, ts);
+        const right = unwrapExpression(indexExpr.right, ts);
+        if (ts.isPropertyAccessExpression(left) && left.name.text === "length") {
+            const lengthArrayTarget = normalizeArrayTarget(left.expression, ts, checker);
+            if (lengthArrayTarget && arraysMatch(lengthArrayTarget, arrayTarget)) {
+                if (ts.isNumericLiteral(right)) {
+                    const offsetVal = Number(right.text);
+                    if (Number.isInteger(offsetVal) && offsetVal >= 1) {
+                        lastElementOffset = offsetVal;
+                    }
+                }
+            }
+        }
+    }
+    if (k === undefined && lastElementOffset === undefined)
+        return undefined;
+    function checkFactSatisfiesBound(fact) {
+        if (lastElementOffset !== undefined) {
+            return fact.minLength >= lastElementOffset && (fact.exactLength === undefined || fact.exactLength >= lastElementOffset);
+        }
+        if (k !== undefined) {
+            const maxAllowed = fact.exactLength ?? fact.minLength;
+            return k < maxAllowed;
+        }
+        return false;
+    }
+    const targetText = arrayTarget.text;
+    function formatEvidence(prefix, exprText, fact) {
+        if (lastElementOffset !== undefined) {
+            return `${prefix} '${exprText}' proves '${targetText}' has length >= ${fact.minLength}, establishing index '${targetText}.length - ${lastElementOffset}' is strictly in-bounds.`;
+        }
+        return `${prefix} '${exprText}' proves '${targetText}' has length ${fact.exactLength !== undefined ? `=== ${fact.exactLength}` : `>= ${fact.minLength}`}, establishing index ${k} is in-bounds.`;
+    }
+    // 1. Walk up enclosing AST nodes (if statements, && expressions, ternary expressions)
+    let curr = node;
+    while (curr.parent &&
+        !ts.isFunctionDeclaration(curr.parent) &&
+        !ts.isFunctionExpression(curr.parent) &&
+        !ts.isArrowFunction(curr.parent) &&
+        !ts.isSourceFile(curr.parent)) {
+        // Case A: Enclosing IfStatement
+        if (ts.isIfStatement(curr.parent)) {
+            const ifStmt = curr.parent;
+            if (ifStmt.thenStatement === curr ||
+                (ts.isBlock(ifStmt.thenStatement) && ifStmt.thenStatement.statements.includes(curr)) ||
+                isNodeDescendantOf(curr, ifStmt.thenStatement)) {
+                const fact = parseGuardedLengthCondition(ifStmt.expression, arrayTarget, ts, checker);
+                if (fact && checkFactSatisfiesBound(fact)) {
+                    if (!hasMutationBeforeNode(ifStmt.thenStatement, node, arrayTarget.text, ts, checker, arrayTarget.symbol)) {
+                        return {
+                            isGuarded: true,
+                            evidence: formatEvidence("Enclosing guard", ifStmt.expression.getText(), fact),
+                        };
+                    }
+                }
+            }
+            else if (ifStmt.elseStatement &&
+                (ifStmt.elseStatement === curr ||
+                    (ts.isBlock(ifStmt.elseStatement) && ifStmt.elseStatement.statements.includes(curr)) ||
+                    isNodeDescendantOf(curr, ifStmt.elseStatement))) {
+                const fact = parseExitGuardedLengthCondition(ifStmt.expression, arrayTarget, ts, checker);
+                if (fact && checkFactSatisfiesBound(fact)) {
+                    if (!hasMutationBeforeNode(ifStmt.elseStatement, node, arrayTarget.text, ts, checker, arrayTarget.symbol)) {
+                        return {
+                            isGuarded: true,
+                            evidence: formatEvidence("Else branch of guard", ifStmt.expression.getText(), fact),
+                        };
+                    }
+                }
+            }
+        }
+        // Case B: Logical AND expression: arr.length === 2 && arr[0]!
+        if (ts.isBinaryExpression(curr.parent) &&
+            curr.parent.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken &&
+            (curr.parent.right === curr || isNodeDescendantOf(curr, curr.parent.right))) {
+            const fact = parseGuardedLengthCondition(curr.parent.left, arrayTarget, ts, checker);
+            if (fact && checkFactSatisfiesBound(fact)) {
+                if (!hasMutationBeforeNode(curr.parent.right, node, arrayTarget.text, ts, checker, arrayTarget.symbol)) {
+                    return {
+                        isGuarded: true,
+                        evidence: formatEvidence("Logical AND guard", curr.parent.left.getText(), fact),
+                    };
+                }
+            }
+        }
+        // Case C: ConditionalExpression: arr.length === 2 ? arr[0]! : fallback
+        if (ts.isConditionalExpression(curr.parent)) {
+            const condExpr = curr.parent;
+            if (condExpr.whenTrue === curr || isNodeDescendantOf(curr, condExpr.whenTrue)) {
+                const fact = parseGuardedLengthCondition(condExpr.condition, arrayTarget, ts, checker);
+                if (fact && checkFactSatisfiesBound(fact)) {
+                    if (!hasMutationBeforeNode(condExpr.whenTrue, node, arrayTarget.text, ts, checker, arrayTarget.symbol)) {
+                        return {
+                            isGuarded: true,
+                            evidence: formatEvidence("Ternary guard", condExpr.condition.getText(), fact),
+                        };
+                    }
+                }
+            }
+            else if (condExpr.whenFalse === curr || isNodeDescendantOf(curr, condExpr.whenFalse)) {
+                const fact = parseExitGuardedLengthCondition(condExpr.condition, arrayTarget, ts, checker);
+                if (fact && checkFactSatisfiesBound(fact)) {
+                    if (!hasMutationBeforeNode(condExpr.whenFalse, node, arrayTarget.text, ts, checker, arrayTarget.symbol)) {
+                        return {
+                            isGuarded: true,
+                            evidence: formatEvidence("Ternary false branch of", condExpr.condition.getText(), fact),
+                        };
+                    }
+                }
+            }
+        }
+        curr = curr.parent;
+    }
+    // 2. Check dominating early-exit guards in prior sibling statements and ancestor blocks
+    let childBlockNode = node;
+    while (childBlockNode.parent) {
+        const container = childBlockNode.parent;
+        if (ts.isFunctionDeclaration(container) ||
+            ts.isFunctionExpression(container) ||
+            ts.isArrowFunction(container) ||
+            ts.isMethodDeclaration(container) ||
+            ts.isConstructorDeclaration(container) ||
+            ts.isGetAccessor(container) ||
+            ts.isSetAccessor(container)) {
+            break;
+        }
+        if (ts.isBlock(container) ||
+            ts.isSourceFile(container) ||
+            ts.isCaseClause(container) ||
+            ts.isDefaultClause(container)) {
+            let stmtInContainer = childBlockNode;
+            while (stmtInContainer.parent && stmtInContainer.parent !== container) {
+                stmtInContainer = stmtInContainer.parent;
+            }
+            const statements = container.statements;
+            const targetIndex = statements.indexOf(stmtInContainer);
+            if (targetIndex > 0) {
+                for (let i = 0; i < targetIndex; i++) {
+                    const prior = statements[i];
+                    if (!prior)
+                        continue;
+                    if (ts.isIfStatement(prior) && statementExitsControlFlow(prior.thenStatement, ts)) {
+                        const fact = parseExitGuardedLengthCondition(prior.expression, arrayTarget, ts, checker);
+                        if (fact && checkFactSatisfiesBound(fact)) {
+                            let hasInterveningMutation = false;
+                            for (let m = i + 1; m < targetIndex; m++) {
+                                const s = statements[m];
+                                if (s && hasArrayMutation(s, arrayTarget.text, ts, checker, arrayTarget.symbol)) {
+                                    hasInterveningMutation = true;
+                                    break;
+                                }
+                            }
+                            if (!hasInterveningMutation &&
+                                !hasMutationBeforeNode(stmtInContainer, node, arrayTarget.text, ts, checker, arrayTarget.symbol)) {
+                                // Loop check: if node is inside a loop under container, verify loop body has no mutations
+                                let loopMutated = false;
+                                let loopCheck = node;
+                                while (loopCheck.parent && loopCheck.parent !== container) {
+                                    const lp = loopCheck.parent;
+                                    if (ts.isForStatement(lp) ||
+                                        ts.isForInStatement(lp) ||
+                                        ts.isForOfStatement(lp) ||
+                                        ts.isWhileStatement(lp) ||
+                                        ts.isDoStatement(lp)) {
+                                        if (hasArrayMutation(lp.statement, arrayTarget.text, ts, checker, arrayTarget.symbol)) {
+                                            loopMutated = true;
+                                            break;
+                                        }
+                                    }
+                                    loopCheck = lp;
+                                }
+                                if (!loopMutated) {
+                                    return {
+                                        isGuarded: true,
+                                        evidence: formatEvidence("Dominating guard", prior.expression.getText(), fact),
+                                    };
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        childBlockNode = container;
+    }
+    return undefined;
+}
+export { containsControlFlowExit, countUnconditionalPushes, hasArrayMutation, hasMutationBeforeNode, isLowerBoundNegativeGuard, arraysMatch, isCompleteBoundsExitGuard, isFixedLengthGuardedIndex, isNodeDescendantOf, isParamBoundedCondition, isPositiveBoundsEntryGuard, isStaticArrayLiteralBoundedIndex, normalizeArrayTarget, normalizeIndexExpression, resolveStaticConstArrayLiteral, parseArrayLengthOffset, };
+/**
+ * Checks if a node or its subtrees contain mutating operations on the given array text/symbol.
+ */
+function hasArrayMutation(node, arrayText, ts, checker, arraySymbol) {
+    let mutated = false;
+    function check(n) {
+        if (mutated)
+            return;
+        if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression)) {
+            const target = normalizeArrayTarget(n.expression.expression, ts, checker);
+            if (target && (target.text === arrayText || (arraySymbol && target.symbol === arraySymbol))) {
+                const method = n.expression.name.text;
+                if (method === "splice" ||
+                    method === "pop" ||
+                    method === "shift" ||
+                    method === "unshift" ||
+                    method === "push" ||
+                    method === "fill" ||
+                    method === "reverse" ||
+                    method === "sort" ||
+                    method === "copyWithin") {
+                    mutated = true;
+                    return;
+                }
+            }
+        }
+        // a.length = ... or a = ...
+        if (ts.isBinaryExpression(n) && n.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+            const left = unwrapExpression(n.left, ts);
+            if (ts.isPropertyAccessExpression(left) && left.name.text === "length") {
+                const target = normalizeArrayTarget(left.expression, ts, checker);
+                if (target && (target.text === arrayText || (arraySymbol && target.symbol === arraySymbol))) {
+                    mutated = true;
+                    return;
+                }
+            }
+            if (ts.isIdentifier(left) && left.text === arrayText) {
+                mutated = true;
+                return;
+            }
+            if (ts.isPropertyAccessExpression(left) && left.getText() === arrayText) {
+                mutated = true;
+                return;
+            }
+        }
+        n.forEachChild(check);
+    }
+    check(node);
+    return mutated;
+}
+function containsControlFlowExit(body, ts) {
+    let hasExit = false;
+    function check(n) {
+        if (hasExit)
+            return;
+        if (ts.isBreakStatement(n) ||
+            ts.isContinueStatement(n) ||
+            ts.isReturnStatement(n) ||
+            ts.isThrowStatement(n) ||
+            ts.isYieldExpression(n)) {
+            hasExit = true;
+            return;
+        }
+        // Do not recurse into nested function bodies
+        if (ts.isFunctionDeclaration(n) || ts.isFunctionExpression(n) || ts.isArrowFunction(n)) {
+            return;
+        }
+        n.forEachChild(check);
+    }
+    check(body);
+    return hasExit;
+}
+function countUnconditionalPushes(body, arrayText, ts, checker, arraySymbol) {
+    let conditionalPush = false;
+    let pushCalls = 0;
+    function scanNode(n, insideConditional) {
+        if (conditionalPush)
+            return;
+        if (ts.isIfStatement(n) ||
+            ts.isSwitchStatement(n) ||
+            ts.isConditionalExpression(n) ||
+            ts.isTryStatement(n) ||
+            ts.isWhileStatement(n) ||
+            ts.isDoStatement(n) ||
+            ts.isForStatement(n) ||
+            ts.isForOfStatement(n) ||
+            ts.isForInStatement(n)) {
+            n.forEachChild((c) => scanNode(c, true));
+            return;
+        }
+        if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression)) {
+            const target = normalizeArrayTarget(n.expression.expression, ts, checker);
+            if (target && (target.text === arrayText || (arraySymbol && target.symbol === arraySymbol))) {
+                if (n.expression.name.text === "push") {
+                    if (insideConditional) {
+                        conditionalPush = true;
+                        return;
+                    }
+                    pushCalls += Math.max(1, n.arguments.length);
+                }
+            }
+        }
+        n.forEachChild((c) => scanNode(c, insideConditional));
+    }
+    scanNode(body, false);
+    if (conditionalPush)
+        return 0;
+    return pushCalls;
+}
+function hasMutationBeforeNode(statementNode, targetNode, arrayText, ts, checker, arraySymbol) {
+    if (statementNode === targetNode)
+        return false;
+    let mutatedBefore = false;
+    function check(n) {
+        if (mutatedBefore)
+            return;
+        if (n.pos >= targetNode.pos)
+            return;
+        if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression)) {
+            const target = normalizeArrayTarget(n.expression.expression, ts, checker);
+            if (target && (target.text === arrayText || (arraySymbol && target.symbol === arraySymbol))) {
+                const method = n.expression.name.text;
+                if (method === "splice" ||
+                    method === "pop" ||
+                    method === "shift" ||
+                    method === "unshift" ||
+                    method === "push" ||
+                    method === "fill" ||
+                    method === "reverse" ||
+                    method === "sort" ||
+                    method === "copyWithin") {
+                    mutatedBefore = true;
+                    return;
+                }
+            }
+        }
+        // a.length = ... or a = ...
+        if (ts.isBinaryExpression(n) && n.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+            const left = unwrapExpression(n.left, ts);
+            if (ts.isPropertyAccessExpression(left) && left.name.text === "length") {
+                const target = normalizeArrayTarget(left.expression, ts, checker);
+                if (target && (target.text === arrayText || (arraySymbol && target.symbol === arraySymbol))) {
+                    mutatedBefore = true;
+                    return;
+                }
+            }
+            if (ts.isIdentifier(left) && left.text === arrayText) {
+                mutatedBefore = true;
+                return;
+            }
+            if (ts.isPropertyAccessExpression(left) && left.getText() === arrayText) {
+                mutatedBefore = true;
+                return;
+            }
+        }
+        n.forEachChild(check);
+    }
+    check(statementNode);
+    return mutatedBefore;
+}
+//# sourceMappingURL=arrayBoundsCore.js.map