@zzzen/pyright-internal 1.2.0-dev.20261018 → 1.2.0-dev.20261108

package/dist/analyzer/tupleComparison.js

@@ -0,0 +1,731 @@
+"use strict";
+/*
+ * tupleComparison.ts
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ *
+ * Operation-local views for lexicographic tuple comparison.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTupleOrdering = isTupleOrdering;
+exports.getTupleComparisonResult = getTupleComparisonResult;
+const parseTreeUtils_1 = require("./parseTreeUtils");
+const typeUtils_1 = require("./typeUtils");
+const types_1 = require("./types");
+const comparisonMethods = {
+    [20 /* OperatorType.LessThan */]: ['__lt__', '__gt__'],
+    [21 /* OperatorType.LessThanOrEqual */]: ['__le__', '__ge__'],
+    [15 /* OperatorType.GreaterThan */]: ['__gt__', '__lt__'],
+    [16 /* OperatorType.GreaterThanOrEqual */]: ['__ge__', '__le__'],
+};
+function isTupleOrdering(operator) {
+    return comparisonMethods[operator] !== undefined;
+}
+function getTupleComparisonResult(evaluator, leftType, rightType, operator, errorNode) {
+    const type = inferTupleComparison(evaluator, leftType, rightType, operator, errorNode);
+    return type ? { type } : undefined;
+}
+// Validate lexicographic ordering without changing either operand's narrowed
+// type. Memoize repeated type pairs and visit each alignment only once.
+function inferTupleComparison(evaluator, leftType, rightType, operator, errorNode) {
+    const leftExpression = errorNode.nodeType === 7 /* ParseNodeType.BinaryOperation */ ? errorNode.d.leftExpr : undefined;
+    let rightExpression = errorNode.nodeType === 7 /* ParseNodeType.BinaryOperation */ ? errorNode.d.rightExpr : undefined;
+    if (rightExpression?.nodeType === 7 /* ParseNodeType.BinaryOperation */ &&
+        !rightExpression.d.hasParens &&
+        (0, parseTreeUtils_1.operatorSupportsChaining)(rightExpression.d.operator)) {
+        rightExpression = rightExpression.d.leftExpr;
+    }
+    const runtimeClass = (type) => {
+        if (!(0, types_1.isClass)(type))
+            return undefined;
+        const cls = types_1.TypeBase.isInstance(type) ? types_1.ClassType.cloneAsInstantiable(type) : type.shared.effectiveMetaclass;
+        return cls && (0, types_1.isInstantiableClass)(cls) ? cls : undefined;
+    };
+    const lookupMethod = (type, name, flags) => {
+        const cls = runtimeClass(type);
+        return cls ? (0, typeUtils_1.lookUpClassMember)(cls, name, flags) : undefined;
+    };
+    const isBuiltinOrderingMethod = (type, name) => {
+        const member = lookupMethod(type, name);
+        return (!!member &&
+            (0, types_1.isClass)(member.classType) &&
+            types_1.ClassType.isBuiltIn(member.classType, ['int', 'float', 'str', 'bytes', 'bytearray', 'tuple', 'list']));
+    };
+    // Presence and successful binding are separate facts. A failed call to a
+    // present user method does not mean Python will try the reflected method.
+    const callMethod = (receiver, name, argument, receiverUnexpanded = receiver, argumentUnexpanded = argument) => {
+        let result = evaluator.getTypeOfMagicMethodCall(receiverUnexpanded, name, [{ type: argumentUnexpanded }], errorNode, undefined);
+        if (!result && (0, types_1.isTypeVar)(receiverUnexpanded) && (0, types_1.isClass)(receiver)) {
+            // A union bound has no single lookup class. Bind the selected class
+            // method to the original variable rather than replacing Self with a bound.
+            result = evaluator.useSpeculativeMode(errorNode, () => {
+                const method = evaluator.getBoundMagicMethod(receiver, name, receiverUnexpanded, errorNode);
+                if (!method)
+                    return undefined;
+                const call = evaluator.validateCallArgs(errorNode, [{ argCategory: 0 /* ArgCategory.Simple */, typeResult: { type: argumentUnexpanded } }], { type: method }, undefined, true, undefined);
+                return call.argumentErrors || !call.returnType
+                    ? undefined
+                    : { type: call.returnType, isIncomplete: call.isTypeIncomplete };
+            });
+        }
+        if (!result && receiverUnexpanded !== receiver) {
+            result = evaluator.getTypeOfMagicMethodCall(receiver, name, [{ type: argumentUnexpanded }], errorNode, undefined);
+        }
+        if (!result && argumentUnexpanded !== argument) {
+            result = evaluator.getTypeOfMagicMethodCall(receiver, name, [{ type: argument }], errorNode, undefined);
+        }
+        if (result)
+            return { kind: 'success', result };
+        return { kind: lookupMethod(receiver, name, 16 /* MemberAccessFlags.SkipInstanceMembers */) ? 'invalid' : 'missing' };
+    };
+    const resultTypes = [];
+    const reflectionOrder = new Map();
+    const boolType = evaluator.getBuiltInObject(errorNode, 'bool');
+    const comparedPairs = new Map();
+    const pendingPairs = [];
+    let hasRecursiveAlias = false;
+    let recursiveBudgetExceeded = false;
+    const hasUnknownShape = [leftType, rightType].some((type) => type.priv.tupleTypeArgs?.some((arg) => arg.isUnbounded && (0, types_1.isAnyOrUnknown)(arg.type)));
+    let requiresDeclaredContract = hasUnknownShape;
+    // NotImplemented is a dispatch signal; all other return types are values
+    // of the comparison expression, including non-boolean values.
+    const classifyResult = (type, left, right) => {
+        const values = [];
+        let declines = false;
+        let preservedTypeVars;
+        let declinedTypeVars;
+        evaluator.mapSubtypesExpandTypeVars(type, { conditionFilter: [...((0, typeUtils_1.getTypeCondition)(left) ?? []), ...((0, typeUtils_1.getTypeCondition)(right) ?? [])] }, (subtype, unexpandedSubtype) => {
+            const typeVar = (0, types_1.isTypeVar)(unexpandedSubtype) &&
+                !types_1.TypeVarType.hasConstraints(unexpandedSubtype) &&
+                !unexpandedSubtype.shared.recursiveAlias
+                ? unexpandedSubtype
+                : undefined;
+            if ((0, types_1.isClassInstance)(subtype) && subtype.shared.fullName === 'types.NotImplementedType') {
+                declines = true;
+                if (typeVar) {
+                    (declinedTypeVars ?? (declinedTypeVars = new Set())).add(typeVar);
+                }
+            }
+            else {
+                if (typeVar) {
+                    (preservedTypeVars ?? (preservedTypeVars = new Map())).set(values.length, typeVar);
+                }
+                values.push(subtype);
+            }
+            return subtype;
+        });
+        preservedTypeVars?.forEach((typeVar, index) => {
+            // A bound is a classification view, not the successful return value.
+            // If the bound itself includes NotImplemented, retain only its values.
+            if (!declinedTypeVars?.has(typeVar)) {
+                values[index] = typeVar;
+            }
+        });
+        return { values, declines };
+    };
+    const getOrderingResult = (left, right, leftUnexpanded = left, rightUnexpanded = right) => {
+        const leftClass = runtimeClass(left);
+        const rightClass = runtimeClass(right);
+        let reflectedFirst = false;
+        if (leftClass && rightClass && !types_1.ClassType.isSameGenericClass(leftClass, rightClass)) {
+            let byRight = reflectionOrder.get(leftClass.shared);
+            if (!byRight) {
+                byRight = new Map();
+                reflectionOrder.set(leftClass.shared, byRight);
+            }
+            const cached = byRight.get(rightClass.shared);
+            if (cached !== undefined) {
+                reflectedFirst = cached;
+            }
+            else {
+                // MROs are already finite and shared across specializations.
+                // Reuse the same inheritance lookup across tuple positions.
+                reflectedFirst = rightClass.shared.mro.some((base) => {
+                    evaluator.checkForCancellation();
+                    return (0, types_1.isClass)(base) && types_1.ClassType.isSameGenericClass(base, leftClass);
+                });
+                byRight.set(rightClass.shared, reflectedFirst);
+            }
+        }
+        const operands = [left, right];
+        const unexpandedOperands = [leftUnexpanded, rightUnexpanded];
+        const methods = comparisonMethods[operator];
+        const values = [];
+        for (const index of reflectedFirst ? [1, 0] : [0, 1]) {
+            const receiver = operands[index];
+            const method = methods[index];
+            const call = callMethod(receiver, method, operands[1 - index], unexpandedOperands[index], unexpandedOperands[1 - index]);
+            if (call.kind !== 'success') {
+                // Invalid user arguments are errors; built-in slots can refuse.
+                if (call.kind === 'invalid' && !isBuiltinOrderingMethod(receiver, method)) {
+                    return undefined;
+                }
+                continue;
+            }
+            const result = classifyResult(call.result.type, left, right);
+            values.push(...result.values);
+            if (!result.declines)
+                return values;
+        }
+        // A refusing or missing fallback does not erase successful values.
+        return values.length ? values : undefined;
+    };
+    const getDeclaredContractResult = () => {
+        const contract = (type) => {
+            const elementType = evaluator.stripLiteralValue((0, types_1.getInferredTupleLiteralBase)(type.priv.typeArgs?.[0] ?? types_1.UnknownType.create()));
+            return types_1.ClassType.specialize(type, [elementType], true, undefined, [
+                { type: elementType, isUnbounded: true },
+            ]);
+        };
+        const values = getOrderingResult(contract(leftType), contract(rightType));
+        return values ? (0, types_1.combineTypes)(values) : undefined;
+    };
+    const getRecursiveBudgetFallback = () => {
+        const declared = getDeclaredContractResult();
+        if (!declared)
+            return undefined;
+        const isClosedResult = (type) => {
+            let size = 0;
+            const visit = (type, depth) => {
+                if (++size > types_1.maxSubtypesForInferredType ||
+                    depth > types_1.maxTypeRecursionCount ||
+                    type.props?.inferredTupleLiteral ||
+                    type.props?.typeForm ||
+                    (0, typeUtils_1.getTypeCondition)(type)?.length)
+                    return false;
+                if ((0, types_1.isAnyOrUnknown)(type) || (0, types_1.isNever)(type))
+                    return true;
+                if ((0, types_1.isUnion)(type))
+                    return type.priv.subtypes.every((subtype) => visit(subtype, depth + 1));
+                if (!(0, types_1.isClass)(type) || type.priv.typedDictNarrowedEntries)
+                    return false;
+                const argsAreClosed = type.priv.tupleTypeArgs
+                    ? type.priv.tupleTypeArgs.every((arg) => visit(arg.type, depth + 1))
+                    : type.priv.typeArgs?.every((arg) => visit(arg, depth + 1)) ?? true;
+                return (argsAreClosed && ((0, types_1.getTypeAliasInfo)(type)?.typeArgs?.every((arg) => visit(arg, depth + 1)) ?? true));
+            };
+            return visit(type, 0);
+        };
+        // Keep cheap results already reached, but never combine growing generic graphs.
+        return (0, types_1.combineTypes)([
+            ...resultTypes.filter((type) => (0, types_1.isAnyOrUnknown)(type) ||
+                ((0, types_1.isClassInstance)(type) &&
+                    !types_1.ClassType.isBuiltIn(type, 'bool') &&
+                    ((!type.priv.typeArgs?.length && !type.priv.tupleTypeArgs?.length) || isClosedResult(type)))),
+            declared,
+        ]);
+    };
+    // Earlier comparisons can mutate objects or rebind names after a middle operand is captured.
+    const isChainedMiddleOperand = errorNode.nodeType === 7 /* ParseNodeType.BinaryOperation */ &&
+        !errorNode.d.hasParens &&
+        errorNode.parent?.nodeType === 7 /* ParseNodeType.BinaryOperation */ &&
+        errorNode.parent.d.rightExpr === errorNode &&
+        (0, parseTreeUtils_1.operatorSupportsChaining)(errorNode.parent.d.operator);
+    const sameName = (left, right) => {
+        if (isChainedMiddleOperand ||
+            left?.nodeType !== 38 /* ParseNodeType.Name */ ||
+            right?.nodeType !== 38 /* ParseNodeType.Name */ ||
+            left.d.value !== right.d.value) {
+            return false;
+        }
+        const first = evaluator.lookUpSymbolRecursive(left, left.d.value, false);
+        const second = evaluator.lookUpSymbolRecursive(right, right.d.value, false);
+        return (!!first &&
+            !!second &&
+            first.scope.type !== 3 /* ScopeType.Class */ &&
+            second.scope.type !== 3 /* ScopeType.Class */ &&
+            first.symbol === second.symbol);
+    };
+    if (sameName(leftExpression, rightExpression)) {
+        return boolType;
+    }
+    let pureOperands;
+    let identityBudgetExceeded = false;
+    const sameReferenceAt = (leftIndex, rightIndex, depth) => {
+        if (depth !== 0 ||
+            leftExpression?.nodeType !== 52 /* ParseNodeType.Tuple */ ||
+            rightExpression?.nodeType !== 52 /* ParseNodeType.Tuple */ ||
+            !sameName(leftExpression.d.items[leftIndex], rightExpression.d.items[rightIndex])) {
+            return false;
+        }
+        if (pureOperands === undefined) {
+            const pending = [leftExpression, rightExpression];
+            let remaining = types_1.maxSubtypesForInferredType;
+            pureOperands = true;
+            while (pending.length) {
+                if (--remaining < 0) {
+                    identityBudgetExceeded = true;
+                    pureOperands = false;
+                    break;
+                }
+                const node = pending.pop();
+                if (node.nodeType === 38 /* ParseNodeType.Name */ ||
+                    node.nodeType === 40 /* ParseNodeType.Number */ ||
+                    node.nodeType === 14 /* ParseNodeType.Constant */) {
+                    continue;
+                }
+                if (node.nodeType === 48 /* ParseNodeType.StringList */) {
+                    if (node.d.strings.every((item) => item.nodeType === 49 /* ParseNodeType.String */)) {
+                        continue;
+                    }
+                }
+                else if (node.nodeType === 52 /* ParseNodeType.Tuple */ || node.nodeType === 34 /* ParseNodeType.List */) {
+                    if (node.d.items.length > remaining) {
+                        identityBudgetExceeded = true;
+                        pureOperands = false;
+                        break;
+                    }
+                    pending.push(...node.d.items);
+                    continue;
+                }
+                pureOperands = false;
+                break;
+            }
+        }
+        return pureOperands;
+    };
+    // Built-in containers use their declared sequence semantics; explicit
+    // subclass types use their declared methods without callee-body analysis.
+    const canOrderResolvedPair = (left, right, recursionCount, isConditional, leftUnexpanded, rightUnexpanded) => {
+        if ((0, types_1.isAnyOrUnknown)(left) || (0, types_1.isAnyOrUnknown)(right)) {
+            // Opaque shape facts use the old contract, not an additional Unknown result.
+            if (!hasUnknownShape) {
+                resultTypes.push((0, types_1.isAnyOrUnknown)(left) ? left : right);
+            }
+            return true;
+        }
+        if ((0, types_1.isClassInstance)(left) && (0, types_1.isClassInstance)(right)) {
+            if ((0, typeUtils_1.isTupleClass)(left) && (0, typeUtils_1.isTupleClass)(right) && left.priv.tupleTypeArgs && right.priv.tupleTypeArgs) {
+                return canOrderArgs(left.priv.tupleTypeArgs, right.priv.tupleTypeArgs, recursionCount, isConditional);
+            }
+            if (types_1.ClassType.isBuiltIn(left, 'list') && types_1.ClassType.isBuiltIn(right, 'list')) {
+                resultTypes.push(boolType);
+                const leftElement = left.priv.typeArgs?.[0] ?? types_1.UnknownType.create();
+                const rightElement = right.priv.typeArgs?.[0] ?? types_1.UnknownType.create();
+                return canOrderElements(leftElement, rightElement, recursionCount + 1, isConditional);
+            }
+        }
+        if (hasRecursiveAlias) {
+            const args = [left, right].flatMap((type) => ((0, types_1.isClassInstance)(type) ? type.priv.typeArgs ?? [] : []));
+            if (!(0, types_1.getTupleLiteralTypeComplexity)(args)) {
+                recursiveBudgetExceeded = true;
+                return false;
+            }
+        }
+        const values = getOrderingResult(left, right, leftUnexpanded, rightUnexpanded);
+        if (!values) {
+            // Types alone cannot determine whether equal objects skip this call.
+            // Discard optional precision instead of recovering source identities.
+            if ((0, types_1.isClassInstance)(left) &&
+                (0, types_1.isClassInstance)(right) &&
+                (types_1.ClassType.isSameGenericClass(left, right) ||
+                    types_1.ClassType.isBuiltIn(left, 'object') ||
+                    types_1.ClassType.isBuiltIn(right, 'object'))) {
+                requiresDeclaredContract = true;
+                return true;
+            }
+            return false;
+        }
+        resultTypes.push(...values);
+        return true;
+    };
+    const canOrderElementsUncached = (left, right, recursionCount, isConditional) => {
+        if ((0, types_1.exceedsInferredTupleLiteralProduct)(left, right)) {
+            left = (0, types_1.getInferredTupleLiteralBase)(left);
+            right = (0, types_1.getInferredTupleLiteralBase)(right);
+        }
+        // Primitive literals affect equality and custom overload selection,
+        // but not ordering between built-in scalar families. Collapse these
+        // operation-local views before expanding a large literal union.
+        const subtypes = (type) => ((0, types_1.isUnion)(type) ? type.priv.subtypes : [type]);
+        const primitivesOnly = (type) => subtypes(type).every((subtype) => (0, types_1.isClassInstance)(subtype) &&
+            types_1.ClassType.isBuiltIn(subtype, ['int', 'bool', 'float', 'complex', 'str', 'bytes']));
+        if (primitivesOnly(left) && primitivesOnly(right)) {
+            left = evaluator.stripLiteralValue(left);
+            right = evaluator.stripLiteralValue(right);
+        }
+        // A common bool contract proves an entire union without a Cartesian
+        // product. Require valid calls for the whole opposing union, inspect
+        // both declared dispatch directions, and retain NotImplemented fallback.
+        if ((0, types_1.isUnion)(left) || (0, types_1.isUnion)(right)) {
+            const summarize = (receiver, argument, method) => {
+                let completes = true;
+                for (const subtype of subtypes(receiver)) {
+                    evaluator.checkForCancellation();
+                    if (!runtimeClass(subtype))
+                        return undefined;
+                    const member = lookupMethod(subtype, method, 16 /* MemberAccessFlags.SkipInstanceMembers */);
+                    // Built-in container annotations do not describe the
+                    // element comparison's actual return type. Recurse below.
+                    if (member && (0, types_1.isClass)(member.classType) && types_1.ClassType.isBuiltIn(member.classType, ['tuple', 'list']))
+                        return undefined;
+                    const call = callMethod(subtype, method, argument);
+                    if (call.kind !== 'success') {
+                        if (call.kind === 'invalid')
+                            return undefined;
+                        completes = false;
+                        continue;
+                    }
+                    const result = classifyResult(call.result.type, subtype, argument);
+                    if (!result.values.every((type) => (0, types_1.isClassInstance)(type) && types_1.ClassType.isBuiltIn(type, 'bool')))
+                        return undefined;
+                    completes && (completes = !result.declines);
+                }
+                return { completes };
+            };
+            const methods = comparisonMethods[operator];
+            const forward = summarize(left, right, methods[0]);
+            const reflected = forward ? summarize(right, left, methods[1]) : undefined;
+            if (forward && reflected && (forward.completes || reflected.completes)) {
+                resultTypes.push(boolType);
+                return true;
+            }
+        }
+        // Use expanded views for dispatch and original operands for method binding.
+        // Keep the evaluator's conditions so correlated constraints are not crossed.
+        let valid = true;
+        evaluator.mapSubtypesExpandTypeVars(left, undefined, (leftSubtype, leftUnexpanded) => {
+            evaluator.mapSubtypesExpandTypeVars(right, { conditionFilter: (0, typeUtils_1.getTypeCondition)(leftSubtype) }, (rightSubtype, rightUnexpanded) => {
+                if (!valid && !isConditional) {
+                    return rightSubtype;
+                }
+                hasRecursiveAlias || (hasRecursiveAlias = ((0, types_1.isTypeVar)(leftUnexpanded) && !!leftUnexpanded.shared.recursiveAlias) ||
+                    ((0, types_1.isTypeVar)(rightUnexpanded) && !!rightUnexpanded.shared.recursiveAlias));
+                valid =
+                    canOrderResolvedPair(leftSubtype, rightSubtype, recursionCount, isConditional, leftUnexpanded, rightUnexpanded) && valid;
+                return rightSubtype;
+            });
+            return leftSubtype;
+        });
+        return valid;
+    };
+    // Recursive specialization can clone placeholders and expanded classes.
+    // Limit new obligations instead of equating different alias arguments.
+    const aliasSpecializations = new Map();
+    const canOrderElements = (left, right, depth, isConditional) => {
+        let rights = comparedPairs.get(left);
+        if (!rights) {
+            rights = new Map();
+            comparedPairs.set(left, rights);
+        }
+        const previous = rights.get(right);
+        if (previous === false || (previous === true && isConditional))
+            return true;
+        rights.set(right, isConditional);
+        const leftAlias = (0, types_1.getTypeAliasInfo)(left);
+        const rightAlias = (0, types_1.getTypeAliasInfo)(right);
+        hasRecursiveAlias || (hasRecursiveAlias = ((0, types_1.isTypeVar)(left) && !!left.shared.recursiveAlias) || ((0, types_1.isTypeVar)(right) && !!right.shared.recursiveAlias));
+        const aliases = leftAlias?.shared === rightAlias?.shared ? [leftAlias?.shared] : [leftAlias?.shared, rightAlias?.shared];
+        for (const alias of aliases) {
+            if (!alias)
+                continue;
+            const count = aliasSpecializations.get(alias) ?? 0;
+            if (count >= types_1.maxSubtypesForInferredType) {
+                recursiveBudgetExceeded = true;
+                return false;
+            }
+            aliasSpecializations.set(alias, count + 1);
+        }
+        pendingPairs.push({ left, right, depth, isConditional });
+        return true;
+    };
+    // Literal type identity differs from Python value equality: True and 1
+    // have distinct literal types, but compare equal inside a tuple.
+    const literalEquality = (left, right) => {
+        if (!(0, types_1.isClassInstance)(left) || !(0, types_1.isClassInstance)(right) || !(0, typeUtils_1.isLiteralType)(left) || !(0, typeUtils_1.isLiteralType)(right)) {
+            return undefined;
+        }
+        if (types_1.ClassType.isBuiltIn(left, ['int', 'bool']) && types_1.ClassType.isBuiltIn(right, ['int', 'bool'])) {
+            const a = left.priv.literalValue;
+            const b = right.priv.literalValue;
+            if ((typeof a === 'number' || typeof a === 'bigint' || typeof a === 'boolean') &&
+                (typeof b === 'number' || typeof b === 'bigint' || typeof b === 'boolean')) {
+                return BigInt(a) === BigInt(b);
+            }
+        }
+        if (!types_1.ClassType.isSameGenericClass(left, right) &&
+            types_1.ClassType.isBuiltIn(left, ['int', 'bool', 'str', 'bytes']) &&
+            types_1.ClassType.isBuiltIn(right, ['int', 'bool', 'str', 'bytes'])) {
+            return false;
+        }
+        return undefined;
+    };
+    const getNumericRepresentation = (type) => {
+        if ((0, types_1.isTypeVar)(type) && type.shared.recursiveAlias)
+            return undefined;
+        const concrete = (0, types_1.isTypeVar)(type) ? evaluator.makeTopLevelTypeVarsConcrete(type) : type;
+        const subtypes = (0, types_1.isUnion)(concrete) ? concrete.priv.subtypes : [concrete];
+        if (subtypes.length > types_1.maxSubtypesForInferredType)
+            return undefined;
+        let representation = 'literal';
+        for (const subtype of subtypes) {
+            if (!(0, types_1.isClassInstance)(subtype) || !types_1.ClassType.isBuiltIn(subtype, ['int', 'bool', 'float', 'complex'])) {
+                return undefined;
+            }
+            if (types_1.ClassType.isBuiltIn(subtype, ['float', 'complex']))
+                representation = 'unrepresented';
+        }
+        return representation;
+    };
+    const equalityResults = new Map();
+    const getEquality = (left, right, depth) => {
+        if (depth > types_1.maxTypeRecursionCount)
+            return undefined;
+        let rights = equalityResults.get(left);
+        if (!rights) {
+            rights = new Map();
+            equalityResults.set(left, rights);
+        }
+        const cached = rights.get(right);
+        if (cached && cached.depth <= depth)
+            return cached.value;
+        // An active cycle is unknown; a depth-limited result must not replace
+        // the more complete result of a shallower visit.
+        const entry = { depth, value: undefined };
+        rights.set(right, entry);
+        entry.value = getEqualityUncached(left, right, depth);
+        return entry.value;
+    };
+    const getEqualityUncached = (left, right, depth) => {
+        const equal = literalEquality(left, right);
+        if (equal !== undefined)
+            return equal;
+        // Compare singleton types directly, but keep tuple graphs on the
+        // memoized element path rather than unfolding them in isTypeSame.
+        if (((0, typeUtils_1.isNoneInstance)(left) ||
+            ((0, types_1.isClassInstance)(left) &&
+                ((0, typeUtils_1.isLiteralType)(left) ||
+                    ['types.EllipsisType', 'types.NotImplementedType'].includes(left.shared.fullName)))) &&
+            (0, types_1.isTypeSame)(left, right))
+            return true;
+        const leftNumeric = getNumericRepresentation(left);
+        const rightNumeric = leftNumeric ? getNumericRepresentation(right) : undefined;
+        if (leftNumeric && rightNumeric && (leftNumeric === 'unrepresented' || rightNumeric === 'unrepresented')) {
+            return 'unrepresented';
+        }
+        if (!(0, types_1.isClassInstance)(left) || !(0, types_1.isClassInstance)(right))
+            return undefined;
+        if ((0, typeUtils_1.isTupleClass)(left) && (0, typeUtils_1.isTupleClass)(right)) {
+            const leftArgs = left.priv.tupleTypeArgs;
+            const rightArgs = right.priv.tupleTypeArgs;
+            if (!leftArgs ||
+                !rightArgs ||
+                leftArgs.some((arg) => arg.isUnbounded || arg.isOptional) ||
+                rightArgs.some((arg) => arg.isUnbounded || arg.isOptional)) {
+                return undefined;
+            }
+            if (leftArgs.length !== rightArgs.length)
+                return false;
+            let allEqual = true;
+            let unrepresentedEquality = false;
+            for (let index = 0; index < leftArgs.length; index++) {
+                const equality = getEquality(leftArgs[index].type, rightArgs[index].type, depth + 1);
+                if (equality === false)
+                    return false;
+                allEqual && (allEqual = equality === true);
+                unrepresentedEquality || (unrepresentedEquality = equality === 'unrepresented');
+            }
+            return allEqual ? true : unrepresentedEquality ? 'unrepresented' : undefined;
+        }
+        if ((0, typeUtils_1.isLiteralType)(left) &&
+            (0, typeUtils_1.isLiteralType)(right) &&
+            types_1.ClassType.isSameGenericClass(left, right) &&
+            (typeof left.priv.literalValue === 'string' ||
+                typeof left.priv.literalValue === 'number' ||
+                typeof left.priv.literalValue === 'bigint' ||
+                typeof left.priv.literalValue === 'boolean') &&
+            left.priv.literalValue !== right.priv.literalValue)
+            return false;
+        return undefined;
+    };
+    const getTupleLiteralItems = (expression, args) => {
+        if (expression?.nodeType !== 52 /* ParseNodeType.Tuple */ ||
+            args.length > types_1.maxSubtypesForInferredType ||
+            expression.d.items.length !== args.length ||
+            isChainedMiddleOperand ||
+            expression.d.items.some((item, index) => item.nodeType === 56 /* ParseNodeType.Unpack */ || args[index].isUnbounded || args[index].isOptional)) {
+            return undefined;
+        }
+        return expression.d.items;
+    };
+    const canOrderArgs = (leftArgs, rightArgs, recursionCount, isConditional) => {
+        // When both tuples begin with an arbitrary run of the same literal,
+        // a fixed run of that literal immediately afterward only changes the
+        // minimum lengths. Both relative run lengths are still unbounded, so
+        // the set of reachable suffix alignments is unchanged. This does not
+        // apply when only one operand has an unbounded prefix.
+        if (leftArgs[0]?.isUnbounded &&
+            rightArgs[0]?.isUnbounded &&
+            getEquality(leftArgs[0].type, rightArgs[0].type, 0) === true) {
+            const collapse = (args) => {
+                let index = 1;
+                while (index < args.length &&
+                    !args[index].isUnbounded &&
+                    !args[index].isOptional &&
+                    getEquality(args[0].type, args[index].type, 0) === true)
+                    index++;
+                return index > 1 ? [args[0], ...args.slice(index)] : args;
+            };
+            leftArgs = collapse(leftArgs);
+            rightArgs = collapse(rightArgs);
+        }
+        // If every possible element pair has a bool contract, alignment cannot
+        // change validity or the result. Prove this before expanding a large
+        // variadic suffix into a quadratic number of positions. Only flat
+        // declared classes enter this proof, so it cannot queue nested work.
+        const flat = (type) => (0, types_1.isUnion)(type)
+            ? type.priv.subtypes.every(flat)
+            : (0, types_1.isClassInstance)(type) && !(0, typeUtils_1.isTupleClass)(type) && !types_1.ClassType.isBuiltIn(type, 'list');
+        if (leftArgs.length &&
+            rightArgs.length &&
+            leftArgs.every((arg) => flat(arg.type)) &&
+            rightArgs.every((arg) => flat(arg.type))) {
+            const start = resultTypes.length;
+            const valid = canOrderElementsUncached((0, types_1.combineTypes)(leftArgs.map((arg) => arg.type)), (0, types_1.combineTypes)(rightArgs.map((arg) => arg.type)), recursionCount + 1, isConditional);
+            if (valid && resultTypes.length > start) {
+                if (resultTypes.slice(start).every((type) => (0, types_1.isClassInstance)(type) && types_1.ClassType.isBuiltIn(type, 'bool'))) {
+                    resultTypes.length = start;
+                    resultTypes.push(boolType);
+                    return true;
+                }
+                const homogeneous = (args) => args.every((arg) => (0, types_1.isClassInstance)(arg.type) &&
+                    !arg.type.shared.typeParams.length &&
+                    !arg.type.priv.typeArgs?.length &&
+                    !arg.type.priv.tupleTypeArgs &&
+                    arg.type.priv.literalValue === undefined &&
+                    !types_1.ClassType.isTypedDictClass(arg.type) &&
+                    !(0, types_1.getTypeAliasInfo)(arg.type) &&
+                    !(0, typeUtils_1.getTypeCondition)(arg.type)?.length &&
+                    !arg.type.props?.inferredTupleLiteral &&
+                    (0, types_1.isTypeSame)(args[0].type, arg.type, { honorCallBehavior: true }));
+                if (leftArgs[0].isUnbounded &&
+                    rightArgs[0].isUnbounded &&
+                    homogeneous(leftArgs) &&
+                    homogeneous(rightArgs) &&
+                    getEquality(leftArgs[0].type, rightArgs[0].type, recursionCount + 1) === undefined) {
+                    // Every reachable pair has this same closed contract. The
+                    // unbounded prefixes can also be equal or differ in length.
+                    resultTypes.push(boolType);
+                    return true;
+                }
+            }
+            resultTypes.length = start;
+        }
+        // An unbounded argument can consume zero or more positions.
+        // Check every reachable alignment before accepting tuple ordering.
+        const leftItems = recursionCount === 0 ? getTupleLiteralItems(leftExpression, leftArgs) : undefined;
+        const rightItems = recursionCount === 0 ? getTupleLiteralItems(rightExpression, rightArgs) : undefined;
+        const pending = [[0, 0, isConditional]];
+        const visited = new Set();
+        while (pending.length > 0) {
+            evaluator.checkForCancellation();
+            const [leftIndex, rightIndex, conditional] = pending.pop();
+            const position = `${leftIndex},${rightIndex},${conditional}`;
+            if (visited.has(position)) {
+                continue;
+            }
+            visited.add(position);
+            if (leftIndex === leftArgs.length || rightIndex === rightArgs.length) {
+                resultTypes.push(boolType);
+                continue;
+            }
+            const leftArg = leftArgs[leftIndex];
+            const rightArg = rightArgs[rightIndex];
+            if (leftArg.isUnbounded || leftArg.isOptional) {
+                pending.push([leftIndex + 1, rightIndex, conditional]);
+            }
+            if (rightArg.isUnbounded || rightArg.isOptional) {
+                pending.push([leftIndex, rightIndex + 1, conditional]);
+            }
+            let equality = getEquality(leftArg.type, rightArg.type, recursionCount + 1);
+            const leftItem = equality !== true ? leftItems?.[leftIndex] : undefined;
+            const rightItem = equality !== true ? rightItems?.[rightIndex] : undefined;
+            const leftList = leftItem?.nodeType === 34 /* ParseNodeType.List */ ? leftItem : undefined;
+            const rightList = rightItem?.nodeType === 34 /* ParseNodeType.List */ ? rightItem : undefined;
+            const emptyListPair = leftList &&
+                rightList &&
+                (!leftList.d.items.length || !rightList.d.items.length) &&
+                (0, types_1.isClassInstance)(leftArg.type) &&
+                (0, types_1.isClassInstance)(rightArg.type) &&
+                types_1.ClassType.isBuiltIn(leftArg.type, 'list') &&
+                types_1.ClassType.isBuiltIn(rightArg.type, 'list');
+            if (emptyListPair) {
+                // An unpack or comprehension can still produce an empty list.
+                const firstKind = (leftList.d.items[0] ?? rightList.d.items[0])?.nodeType;
+                if (firstKind === undefined) {
+                    equality = true;
+                }
+                else if (firstKind !== 56 /* ParseNodeType.Unpack */ && firstKind !== 11 /* ParseNodeType.Comprehension */) {
+                    equality = false;
+                }
+            }
+            if (equality !== true &&
+                !leftList &&
+                !rightList &&
+                !leftArg.isUnbounded &&
+                !rightArg.isUnbounded &&
+                !leftArg.isOptional &&
+                !rightArg.isOptional &&
+                sameReferenceAt(leftIndex, rightIndex, recursionCount)) {
+                equality = true;
+            }
+            const unrepresented = equality === 'unrepresented';
+            if (equality !== true) {
+                if (emptyListPair) {
+                    // A nominal list can be a subclass whose __eq__ mutates the other operand.
+                    resultTypes.push(boolType);
+                }
+                else if (!canOrderElements(leftArg.type, rightArg.type, recursionCount + 1, conditional || (unrepresented && !!getNumericRepresentation(leftArg.type)))) {
+                    return false;
+                }
+            }
+            if (equality === false)
+                continue;
+            // Unrepresented numeric equality can still reach a custom suffix.
+            // Preserve its results, using the old contract if a conditional call fails.
+            const nextConditional = conditional || unrepresented;
+            pending.push([leftIndex + 1, rightIndex + 1, nextConditional]);
+            if (leftArg.isUnbounded) {
+                pending.push([leftIndex, rightIndex + 1, nextConditional]);
+            }
+            if (rightArg.isUnbounded) {
+                pending.push([leftIndex + 1, rightIndex, nextConditional]);
+            }
+        }
+        return true;
+    };
+    const ordered = canOrderArgs(leftType.priv.tupleTypeArgs, rightType.priv.tupleTypeArgs, 0, 
+    /* isConditional */ false);
+    if (!ordered)
+        return recursiveBudgetExceeded ? getRecursiveBudgetFallback() : undefined;
+    if (identityBudgetExceeded) {
+        return getDeclaredContractResult();
+    }
+    // Reach seed elements before expanding another recursive tail.
+    for (let index = 0; index < pendingPairs.length; index++) {
+        evaluator.checkForCancellation();
+        const pair = pendingPairs[index];
+        const valid = canOrderElementsUncached(pair.left, pair.right, pair.depth, pair.isConditional);
+        if (recursiveBudgetExceeded)
+            return getRecursiveBudgetFallback();
+        if (!valid) {
+            if (!pair.isConditional)
+                return undefined;
+            requiresDeclaredContract = true;
+        }
+    }
+    if (requiresDeclaredContract) {
+        const declaredResult = getDeclaredContractResult();
+        return declaredResult ? (0, types_1.combineTypes)([...resultTypes, declaredResult]) : undefined;
+    }
+    // A length comparison contributes an unconditional bool. It also covers
+    // conditional bool results from constrained receiver types.
+    if (resultTypes.some((type) => (0, types_1.isTypeSame)(type, boolType))) {
+        return (0, types_1.combineTypes)([
+            ...resultTypes.filter((type) => !((0, types_1.isClassInstance)(type) && types_1.ClassType.isBuiltIn(type, 'bool'))),
+            boolType,
+        ]);
+    }
+    return (0, types_1.combineTypes)(resultTypes);
+}
+//# sourceMappingURL=tupleComparison.js.map