@blumintinc/eslint-plugin-blumint 1.20.134 → 1.20.136

package/lib/rules/no-redundant-annotation-assertion.js

@@ -77,12 +77,12 @@ function isTraversalBoundary(node) {
         node.type === utils_1.AST_NODE_TYPES.ClassDeclaration ||
         node.type === utils_1.AST_NODE_TYPES.ClassExpression);
 }
-function recordReturnStatement(node, assertions) {
+function recordReturnStatement(node, assertionSites) {
     if (!node.argument)
         return;
     const assertion = extractAssertionTypeNode(node.argument);
     if (assertion)
-        assertions.push(assertion);
+        assertionSites.push({ assertion, expression: node.argument });
 }
 function addChildNodesToStack(node, stack) {
     const keys = visitor_keys_1.visitorKeys[node.type];
@@ -103,22 +103,38 @@ function addChildNodesToStack(node, stack) {
         }
     }
 }
+function collectReturnArguments(body) {
+    const args = [];
+    const stack = [...body.body];
+    while (stack.length) {
+        const current = stack.pop();
+        if (current.type === utils_1.AST_NODE_TYPES.ReturnStatement) {
+            if (current.argument)
+                args.push(current.argument);
+            continue;
+        }
+        if (isTraversalBoundary(current))
+            continue;
+        addChildNodesToStack(current, stack);
+    }
+    return args;
+}
 function collectReturnInfo(body) {
-    const assertions = [];
+    const assertionSites = [];
     let returnCount = 0;
     const stack = [...body.body];
     while (stack.length) {
         const current = stack.pop();
         if (current.type === utils_1.AST_NODE_TYPES.ReturnStatement) {
             returnCount += 1;
-            recordReturnStatement(current, assertions);
+            recordReturnStatement(current, assertionSites);
             continue;
         }
         if (isTraversalBoundary(current))
             continue;
         addChildNodesToStack(current, stack);
     }
-    return { assertions, returnCount };
+    return { assertionSites, returnCount };
 }
 function findTypeAnnotationStart(typeAnnotation, sourceCode) {
     const start = typeAnnotation.range[0];
@@ -176,6 +192,64 @@ function unwrapAlias(type, checker) {
     }
     return type;
 }
+/**
+ * Readonly-ness reaches a property symbol by two disjoint routes, and a key
+ * built from only one of them equates shapes that differ:
+ *
+ * - A property *written* `readonly` (interface member, type-alias member, class
+ *   field) carries the modifier on its declaration and no check flag.
+ * - A property *synthesized* as readonly — an `as const` object literal, a
+ *   `Readonly<T>` mapped type — has no declaration modifier and carries
+ *   `CheckFlags.Readonly` instead.
+ *
+ * Reading only declarations makes `as const` compare equal to a mutable
+ * annotation, and deleting that annotation changes the value's type (see #1883).
+ *
+ * `getCheckFlags` is not published in every TypeScript release's type
+ * definitions, so it is reached through a guarded lookup: where it is absent the
+ * key falls back to declaration modifiers alone, which is exactly the
+ * information available without it. The enum is dereferenced here rather than at
+ * module scope because the plugin barrel loads every rule eagerly and a missing
+ * compiler export at module scope fails the whole plugin, not just this rule.
+ */
+function isReadonlyProperty(prop) {
+    const compiler = ts;
+    const readonlyCheckFlag = compiler.CheckFlags?.Readonly;
+    if (typeof compiler.getCheckFlags === 'function' && readonlyCheckFlag) {
+        if ((compiler.getCheckFlags(prop) & readonlyCheckFlag) !== 0)
+            return true;
+    }
+    // A getter with no setter is readonly by shape rather than by modifier or
+    // check flag, so neither route above sees it — `{ get x(): number }` carries
+    // `getCheckFlags` 0 and `getCombinedModifierFlags` 0, and would otherwise
+    // format identically to a mutable `{ x: number }` (#1887).
+    const flags = prop.getFlags();
+    if ((flags & ts.SymbolFlags.Accessor) !== 0 &&
+        (flags & ts.SymbolFlags.SetAccessor) === 0) {
+        return true;
+    }
+    return (prop.declarations ?? []).some((declaration) => (ts.getCombinedModifierFlags(declaration) & ts.ModifierFlags.Readonly) !==
+        0);
+}
+/**
+ * The index signatures a type declares, with their readonly-ness.
+ *
+ * They belong in the structural key for the same reason the properties do: an
+ * index-signature-only type otherwise keys to the empty string, so every such
+ * type compares equal to every other. Readonly-ness in particular does not
+ * affect bidirectional assignability of an index signature, so a readonly one
+ * would match a mutable annotation and removing that annotation ships TS2542
+ * (#1887).
+ */
+function getFormattedIndexSignatures(type, checker) {
+    const compiler = checker;
+    if (typeof compiler.getIndexInfosOfType !== 'function')
+        return [];
+    return compiler
+        .getIndexInfosOfType(type)
+        .map((info) => `${info.isReadonly ? 'readonly ' : ''}[${typeText(info.keyType, checker)}]:${typeText(unwrapAlias(info.type, checker), checker)}`)
+        .sort();
+}
 function formatPropertySignature(prop, parentType, checker) {
     const declaration = prop.valueDeclaration ??
         prop.declarations?.[0] ??
@@ -186,7 +260,8 @@ function formatPropertySignature(prop, parentType, checker) {
     const propType = checker.getTypeOfSymbolAtLocation(prop, declaration);
     const text = typeText(unwrapAlias(propType, checker), checker);
     const isOptional = (prop.getFlags() & ts.SymbolFlags.Optional) !== 0;
-    return `${prop.getName()}${isOptional ? '?' : ''}:${text}`;
+    const readonlyPrefix = isReadonlyProperty(prop) ? 'readonly ' : '';
+    return `${readonlyPrefix}${prop.getName()}${isOptional ? '?' : ''}:${text}`;
 }
 function getFormattedTypeProperties(type, checker) {
     return checker
@@ -205,7 +280,8 @@ function structuralKey(type, checker) {
     const apparent = checker.getApparentType(type);
     const properties = getFormattedTypeProperties(apparent, checker);
     const signatures = getFormattedCallSignatures(apparent, checker);
-    return `${properties.join('|')}::${signatures.join('|')}`;
+    const indexes = getFormattedIndexSignatures(apparent, checker);
+    return `${properties.join('|')}::${signatures.join('|')}::${indexes.join('|')}`;
 }
 function getComparableType(typeNode, checker, services) {
     const tsNode = services.esTreeNodeToTSNodeMap.get(typeNode);
@@ -297,11 +373,11 @@ function haveMatchingTypes(annotation, assertion, checker, services) {
     }
     return selectMatchingTypeRepresentation(representations);
 }
-function getReturnAssertion(node) {
+function getReturnAssertionSite(node) {
     const value = node.type === utils_1.AST_NODE_TYPES.MethodDefinition ? node.value : node;
     const body = value.body;
     if (body?.type === utils_1.AST_NODE_TYPES.BlockStatement) {
-        const { assertions, returnCount } = collectReturnInfo(body);
+        const { assertionSites, returnCount } = collectReturnInfo(body);
         // Skip functions with multiple returns because different branches can assert different types.
         if (returnCount !== 1)
             return null;
@@ -311,11 +387,426 @@ function getReturnAssertion(node) {
         if (lastStatement?.type !== utils_1.AST_NODE_TYPES.ReturnStatement) {
             return null;
         }
-        return assertions[0] ?? null;
+        return assertionSites[0] ?? null;
     }
     if (!body)
         return null;
-    return extractAssertionTypeNode(body);
+    const assertion = extractAssertionTypeNode(body);
+    return assertion ? { assertion, expression: body } : null;
+}
+/**
+ * The identifiers that name `node`, in the AST. A self-reference inside the
+ * function's own return expression resolves to one of these, whichever shape
+ * the function is written in: a declaration's own name, a named function
+ * expression's name, the variable or property an anonymous function is assigned
+ * to, or a method's key.
+ */
+/**
+ * The key a member is declared under, whatever its spelling.
+ *
+ * A computed key whose key expression is a literal names exactly the member a
+ * dotted or bracketed read resolves to — `{ ['build']() {} }` declares `build`
+ * — and the reader side already resolves both spellings. Refusing the computed
+ * form left such a candidate with NO owner at all, so it could not be found
+ * circular even by a direct self-reference (#1888). A genuinely dynamic key
+ * names no member statically and still yields nothing.
+ */
+function memberKeyNameNode(node) {
+    if (!node.computed)
+        return node.key;
+    return node.key.type === utils_1.AST_NODE_TYPES.Literal &&
+        (typeof node.key.value === 'string' || typeof node.key.value === 'number')
+        ? node.key
+        : null;
+}
+/** Every binding a destructuring pattern introduces. */
+function patternBindingNames(pattern) {
+    const names = [];
+    const visit = (node) => {
+        if (!node)
+            return;
+        switch (node.type) {
+            case utils_1.AST_NODE_TYPES.Identifier:
+                names.push(node);
+                return;
+            case utils_1.AST_NODE_TYPES.ObjectPattern:
+                for (const property of node.properties) {
+                    visit(property.type === utils_1.AST_NODE_TYPES.Property
+                        ? property.value
+                        : property.argument);
+                }
+                return;
+            case utils_1.AST_NODE_TYPES.ArrayPattern:
+                for (const element of node.elements)
+                    visit(element);
+                return;
+            case utils_1.AST_NODE_TYPES.AssignmentPattern:
+                visit(node.left);
+                return;
+            case utils_1.AST_NODE_TYPES.RestElement:
+                visit(node.argument);
+                return;
+            default:
+                return;
+        }
+    };
+    visit(pattern);
+    return names;
+}
+/** A pattern carries its annotation on the pattern node itself. */
+function patternTypeAnnotation(pattern) {
+    return pattern
+        .typeAnnotation;
+}
+function ownerNameNodes(node) {
+    if (node.type === utils_1.AST_NODE_TYPES.MethodDefinition) {
+        const key = memberKeyNameNode(node);
+        return key ? [key] : [];
+    }
+    const names = [];
+    if (node.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression && node.id) {
+        names.push(node.id);
+    }
+    const parent = node.parent;
+    if (parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+        parent.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+        names.push(parent.id);
+    }
+    if (parent?.type === utils_1.AST_NODE_TYPES.PropertyDefinition ||
+        parent?.type === utils_1.AST_NODE_TYPES.Property) {
+        const key = memberKeyNameNode(parent);
+        if (key)
+            names.push(key);
+    }
+    return names;
+}
+/**
+ * A binding is identified by the declarations behind its symbol rather than by
+ * the symbol object. Reading `obj.build` yields a *clone* of the symbol declared
+ * by `build: () => {}` — widening an object literal's type rebuilds its property
+ * symbols — so symbol identity reports a self-reference as unrelated. The clone
+ * keeps the original declaration, which therefore is the stable key.
+ */
+function declarationsOfSymbol(symbol) {
+    return symbol.declarations ?? [];
+}
+function declaredAt(nodes, checker, services) {
+    const declarations = new Set();
+    for (const node of nodes) {
+        const tsNode = services.esTreeNodeToTSNodeMap.get(node);
+        const symbol = tsNode ? checker.getSymbolAtLocation(tsNode) : undefined;
+        if (!symbol)
+            continue;
+        for (const declaration of declarationsOfSymbol(symbol)) {
+            declarations.add(declaration);
+        }
+    }
+    return declarations;
+}
+/**
+ * Every binding the returned expression reads. Resolving through the checker
+ * rather than matching identifier text keeps a shadowing inner declaration of
+ * the same name from reading as a self-reference.
+ */
+function referencedDeclarationsOf(expression, checker, services, pruneTypedFunctions = false) {
+    const declarations = new Set();
+    const root = services.esTreeNodeToTSNodeMap.get(expression);
+    if (!root)
+        return declarations;
+    /**
+     * Only a VALUE read can make return-type inference circular.
+     *
+     * The returned expression subtree contains the assertion's own type node —
+     * `<Status>{…}` and `expr as Status` both carry `Status` inside it — so
+     * resolving every identifier would count that type reference as a
+     * self-reference whenever a binding and a type share a name
+     * (`type Status = …; const Status = (): Status => <Status>{…}`). TypeScript
+     * resolves a type annotation without needing any function's return type, so
+     * such a reference can never close the cycle.
+     *
+     * `typeof f` is the one type-position spelling that reads a VALUE, and it does
+     * depend on `f`'s return type, so it counts. Checking it before the general
+     * type-node test is what lets it through — a type query is itself a type node.
+     */
+    const readsAValue = (identifier) => {
+        let current = identifier.parent;
+        while (current) {
+            if (ts.isTypeQueryNode(current))
+                return true;
+            if (ts.isTypeNode(current))
+                return false;
+            if (current === root)
+                return true;
+            current = current.parent;
+        }
+        return true;
+    };
+    /**
+     * A property read spells its name as an identifier in `obj.build` and as a
+     * string in `obj['build']`, and both resolve to the same property symbol —
+     * so testing for an identifier alone recognises only one of two spellings of
+     * one reference. The literal is only a name where it indexes something;
+     * elsewhere a string is data and resolves to nothing worth following.
+     */
+    const isNameNode = (tsNode) => {
+        if (ts.isIdentifier(tsNode))
+            return true;
+        const parent = tsNode.parent;
+        return (ts.isStringLiteralLike(tsNode) &&
+            Boolean(parent) &&
+            ts.isElementAccessExpression(parent) &&
+            parent.argumentExpression === tsNode);
+    };
+    /**
+     * The name a declaration gives itself is not a read of it. Walking an object
+     * literal or a class body reaches the names of its own members, and counting
+     * those makes the literal look like it reads every function it contains —
+     * enough to close a cycle that TypeScript does not have, since it resolves an
+     * object literal's properties one at a time rather than as a whole.
+     *
+     * A shorthand property is the exception in both directions: `{ build }`
+     * declares a property and reads a binding, and it is the read that matters.
+     */
+    const isDeclarationName = (tsNode) => {
+        const parent = tsNode.parent;
+        if (!parent)
+            return false;
+        if (ts.isShorthandPropertyAssignment(parent) ||
+            ts.isPropertyAccessExpression(parent) ||
+            ts.isElementAccessExpression(parent) ||
+            ts.isQualifiedName(parent)) {
+            return false;
+        }
+        return parent.name === tsNode;
+    };
+    const symbolAt = (tsNode) => {
+        const parent = tsNode.parent;
+        // A shorthand property's own identifier resolves to the property, so the
+        // binding it abbreviates has to be asked for by name.
+        if (parent && ts.isShorthandPropertyAssignment(parent)) {
+            return checker.getShorthandAssignmentValueSymbol(parent);
+        }
+        return checker.getSymbolAtLocation(tsNode);
+    };
+    /**
+     * A nested function that writes its own return type down answers without
+     * consulting anything, so nothing beneath it can be a link in a cycle. It is
+     * already its own graph node, related to its own dependencies, and reaching
+     * through it would attribute its body to the binding that merely contains it
+     * — `const cache = { get: (): Q => build() }` does not make `cache` depend on
+     * `build`, because `get` is typed by its annotation.
+     */
+    const answersWithoutInference = (tsNode) => pruneTypedFunctions &&
+        (ts.isArrowFunction(tsNode) ||
+            ts.isFunctionExpression(tsNode) ||
+            ts.isFunctionDeclaration(tsNode) ||
+            ts.isMethodDeclaration(tsNode)) &&
+        tsNode.type !== undefined;
+    const visit = (tsNode) => {
+        if (isNameNode(tsNode) &&
+            !isDeclarationName(tsNode) &&
+            readsAValue(tsNode)) {
+            const symbol = symbolAt(tsNode);
+            if (symbol) {
+                for (const declaration of declarationsOfSymbol(symbol)) {
+                    declarations.add(declaration);
+                }
+            }
+        }
+        if (tsNode !== root && answersWithoutInference(tsNode)) {
+            return;
+        }
+        ts.forEachChild(tsNode, visit);
+    };
+    visit(root);
+    return declarations;
+}
+function isFunctionLike(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression);
+}
+/** The expressions a function's own return type is inferred from. */
+function returnExpressionsOf(node) {
+    const value = node.type === utils_1.AST_NODE_TYPES.MethodDefinition ? node.value : node;
+    const body = value.body;
+    if (!body)
+        return [];
+    return body.type === utils_1.AST_NODE_TYPES.BlockStatement
+        ? collectReturnArguments(body)
+        : [body];
+}
+function returnTypeAnnotationOf(node) {
+    return node.type === utils_1.AST_NODE_TYPES.MethodDefinition
+        ? node.value.returnType
+        : node.returnType;
+}
+/**
+ * Whether the binding this function is assigned to declares its own type. A
+ * contextually typed function is not inferred from its body — `const f: () => Q
+ * = () => g()` types `f` from the annotation regardless of what `g` returns —
+ * so it cannot carry a cycle even without a return annotation of its own.
+ */
+function ownerCarriesTypeAnnotation(node) {
+    const parent = node.parent;
+    if (parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator) {
+        return (parent.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+            Boolean(parent.id.typeAnnotation));
+    }
+    if (parent?.type === utils_1.AST_NODE_TYPES.PropertyDefinition) {
+        return Boolean(parent.typeAnnotation);
+    }
+    return false;
+}
+function addInferenceEdges(graph, owners, dependencies, needsInference) {
+    for (const owner of owners) {
+        const existing = graph.get(owner);
+        if (!existing) {
+            graph.set(owner, {
+                needsInference,
+                dependencies: new Set(dependencies),
+            });
+            continue;
+        }
+        existing.needsInference ||= needsInference;
+        for (const dependency of dependencies) {
+            existing.dependencies.add(dependency);
+        }
+    }
+}
+function unionReferences(expressions, checker, services, pruneTypedFunctions = false) {
+    const references = new Set();
+    for (const expression of expressions) {
+        for (const declaration of referencedDeclarationsOf(expression, checker, services, pruneTypedFunctions)) {
+            references.add(declaration);
+        }
+    }
+    return references;
+}
+/**
+ * Every function-like node in the file, related to the declarations its return
+ * type is inferred from. Functions the rule is not reporting on belong in the
+ * graph too: an unannotated helper is precisely the kind of node a cycle runs
+ * through, and it is invisible to a relation drawn between candidates only.
+ */
+function addFunctionNodes(graph, functions, checker, services) {
+    for (const node of functions) {
+        const owners = declaredAt(ownerNameNodes(node), checker, services);
+        if (owners.size === 0)
+            continue;
+        // A written-down type normally answers without consulting anything, which
+        // is what lets the walk stop at it — unless the annotation itself reads a
+        // value through `typeof`, which is a dependency like any other and can
+        // close the cycle it was supposed to break (#1888). Such a node keeps
+        // needing inference, and contributes what its annotation reads.
+        const annotationReads = annotationValueReads(node, checker, services);
+        const writtenDown = Boolean(returnTypeAnnotationOf(node)) || ownerCarriesTypeAnnotation(node);
+        const dependencies = unionReferences(returnExpressionsOf(node), checker, services);
+        for (const declaration of annotationReads)
+            dependencies.add(declaration);
+        addInferenceEdges(graph, owners, dependencies, !writtenDown || annotationReads.size > 0);
+    }
+}
+/**
+ * The values this function's declared type reads through `typeof`.
+ *
+ * `referencedDeclarationsOf` already treats a type query as a value read and
+ * every other type position as not one, so handing it the annotation yields
+ * exactly the `typeof` operands and nothing else.
+ */
+function annotationValueReads(node, checker, services) {
+    const reads = new Set();
+    const parent = node.parent;
+    const annotations = [
+        returnTypeAnnotationOf(node),
+        parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+            parent.id.type === utils_1.AST_NODE_TYPES.Identifier
+            ? parent.id.typeAnnotation
+            : undefined,
+        parent?.type === utils_1.AST_NODE_TYPES.PropertyDefinition
+            ? parent.typeAnnotation
+            : undefined,
+    ];
+    for (const annotation of annotations) {
+        if (!annotation)
+            continue;
+        for (const declaration of referencedDeclarationsOf(annotation.typeAnnotation, checker, services)) {
+            reads.add(declaration);
+        }
+    }
+    return reads;
+}
+function addValueNodes(graph, values, checker, services) {
+    for (const { name, init } of values) {
+        const owners = declaredAt([name], checker, services);
+        if (owners.size === 0)
+            continue;
+        addInferenceEdges(graph, owners, unionReferences([init], checker, services, true), true);
+    }
+}
+/**
+ * Whether following what this declaration's type is inferred from leads back to
+ * the declaration itself.
+ *
+ * The walk stops at any declaration whose type is written down: an annotated
+ * function, an annotated binding, an ambient declaration. Such a node answers
+ * the question it is asked without consulting anything further, which is
+ * exactly what breaks a cycle — TypeScript's own error says a type is inferred
+ * "directly or indirectly" from itself, and every link in that indirection has
+ * to be a type it must infer.
+ */
+function reachesOwnDeclaration(owners, dependencies, graph) {
+    const frontier = [...dependencies];
+    const seen = new Set();
+    while (frontier.length) {
+        const current = frontier.pop();
+        if (owners.has(current))
+            return true;
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        const node = graph.get(current);
+        if (!node?.needsInference)
+            continue;
+        for (const dependency of node.dependencies)
+            frontier.push(dependency);
+    }
+    return false;
+}
+/**
+ * The candidates whose annotation must survive because removing it would make
+ * the function's return type circular.
+ *
+ * A function that reaches itself through what its return type is inferred from
+ * can only be typed by its annotation: dropping it leaves TypeScript inferring
+ * the return type from an expression whose type depends on that same return
+ * type (TS7023/TS7022), or — where the assertion pins enough of the shape to
+ * break the cycle — silently widening a member to `any`. That circularity is
+ * invisible to the equality test that proves redundancy, because the equality
+ * only holds *while* the annotation is there.
+ *
+ * The reach is transitive rather than a hop between candidates, because a cycle
+ * closes through whatever happens to lie on it: an unannotated helper, an
+ * object holding a callback, a plain alias. Those are not candidates — they
+ * have no annotation to remove — yet they relay a dependency, and a relation
+ * drawn candidate-to-candidate cannot see them.
+ *
+ * Every candidate is treated as needing inference, since this rule's fixes ship
+ * as one batch and every annotation in it goes together. That over-approximates
+ * — declining one member of a cycle would free the rest — and the surplus costs
+ * a missed report rather than a broken fix. It also subsumes the direct
+ * self-reference case, which is a cycle of length one.
+ */
+function findCircularReturnCandidates(candidates, graph) {
+    for (const candidate of candidates) {
+        addInferenceEdges(graph, candidate.owners, candidate.references, true);
+    }
+    const circular = new Set();
+    for (const candidate of candidates) {
+        if (reachesOwnDeclaration(candidate.owners, candidate.references, graph)) {
+            circular.add(candidate.site);
+        }
+    }
+    return circular;
 }
 exports.noRedundantAnnotationAssertion = (0, createRule_1.createRule)({
     name: 'no-redundant-annotation-assertion',
@@ -355,6 +846,17 @@ exports.noRedundantAnnotationAssertion = (0, createRule_1.createRule)({
          * re-reports the debt.
          */
         const sites = [];
+        /** Return-position sites, kept with the symbols that decide circularity. */
+        const returnCandidates = [];
+        /**
+         * The nodes the inference graph is built from, gathered as AST during the
+         * traversal and resolved to symbols only if a return-position candidate
+         * turns up. Resolving every binding in the file up front would charge a
+         * type-checker query per declaration to answer a question no file without a
+         * return annotation ever asks.
+         */
+        const functionLikeNodes = [];
+        const inferredValueDeclarations = [];
         /**
          * Suppression is applied to reports after a rule emits them, so a suppressed
          * site keeps its annotation while losing its fix. Counting its removal
@@ -365,12 +867,32 @@ exports.noRedundantAnnotationAssertion = (0, createRule_1.createRule)({
         function collectIfRedundant(annotation, assertion, reportNode, fixerTarget) {
             const matchingType = haveMatchingTypes(annotation.typeAnnotation, assertion, checker, parserServices);
             if (!matchingType)
-                return;
-            sites.push({
+                return null;
+            const site = {
                 reportNode,
                 removal: annotationRemovalRange(fixerTarget, sourceCode),
                 matchingType,
-            });
+            };
+            sites.push(site);
+            return site;
+        }
+        /**
+         * The one gate every return-position visitor passes through, so a declined
+         * return annotation loses both its report and its fix whichever of the four
+         * function shapes carries it.
+         */
+        function collectReturnSite(node, annotation, reportNode) {
+            const assertionSite = getReturnAssertionSite(node);
+            if (!assertionSite)
+                return;
+            const owners = declaredAt(ownerNameNodes(node), checker, parserServices);
+            const references = referencedDeclarationsOf(assertionSite.expression, checker, parserServices);
+            // Whether the annotation is load-bearing is decided at `Program:exit`:
+            // the cycle can run through a function elsewhere in the file, and every
+            // annotation in it goes in the same batched fix.
+            const site = collectIfRedundant(annotation, assertionSite.assertion, reportNode, annotation);
+            if (site)
+                returnCandidates.push({ site, owners, references });
         }
         /**
          * The sites whose fixes actually ship. A site is excluded when its report
@@ -384,15 +906,36 @@ exports.noRedundantAnnotationAssertion = (0, createRule_1.createRule)({
          * vetoing the rest: orphanhood grows monotonically with the removed set, so
          * a site that cannot be planned alone can only ever poison the batch.
          */
-        function selectFixableSites() {
-            return sites.filter((site) => !isReportSuppressed(site.reportNode) &&
+        function selectFixableSites(candidates) {
+            return candidates.filter((site) => !isReportSuppressed(site.reportNode) &&
                 (0, importRemoval_1.planOrphanedImportRemoval)(sourceCode, [site.removal]) !== null);
         }
+        /**
+         * The file's inference graph, built only where a return annotation is at
+         * stake. Both the functions and the value bindings go in: a cycle runs
+         * through whichever of them happens to lie on it.
+         */
+        function buildInferenceGraph() {
+            const graph = new Map();
+            addFunctionNodes(graph, functionLikeNodes, checker, parserServices);
+            addValueNodes(graph, inferredValueDeclarations, checker, parserServices);
+            return graph;
+        }
         return {
             'Program:exit'() {
                 if (sites.length === 0)
                     return;
-                const fixable = selectFixableSites();
+                // Recursion only becomes circular once every annotation on the cycle is
+                // gone, which is exactly what this rule's single batched fix does, so
+                // the check has to see the whole batch — and the whole file, because
+                // what closes the cycle need not be a candidate at all.
+                const circular = returnCandidates.length > 0
+                    ? findCircularReturnCandidates(returnCandidates, buildInferenceGraph())
+                    : new Set();
+                const reportable = sites.filter((site) => !circular.has(site));
+                if (reportable.length === 0)
+                    return;
+                const fixable = selectFixableSites(reportable);
                 const removals = fixable.map((site) => site.removal);
                 // One plan over every surviving removal: an import referenced solely by
                 // annotations that all go in this pass is orphaned by their union, even
@@ -404,7 +947,7 @@ exports.noRedundantAnnotationAssertion = (0, createRule_1.createRule)({
                 // others that the import's orphanhood was judged against. The rest
                 // report without a fixer; the carrier's pass already resolves them.
                 const carrier = importRanges ? fixable[0] : undefined;
-                for (const site of sites) {
+                for (const site of reportable) {
                     context.report({
                         node: site.reportNode,
                         messageId: 'redundantAnnotationAndAssertion',
@@ -419,10 +962,29 @@ exports.noRedundantAnnotationAssertion = (0, createRule_1.createRule)({
                 }
             },
             VariableDeclarator(node) {
-                if (node.id.type !== utils_1.AST_NODE_TYPES.Identifier ||
-                    !node.id.typeAnnotation ||
-                    node.id.optional ||
-                    node.definite) {
+                // A pattern introduces bindings that relay a dependency exactly as a
+                // plain one does — `const { run } = { run: () => build() }` is the
+                // destructured spelling of a shape already covered — but the early
+                // return below skipped registering them at all (#1888). Each name gets
+                // the whole initializer, which is the same over-approximation a plain
+                // binding carries.
+                if (node.id.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                    if (node.init && !patternTypeAnnotation(node.id)) {
+                        for (const name of patternBindingNames(node.id)) {
+                            inferredValueDeclarations.push({ name, init: node.init });
+                        }
+                    }
+                    return;
+                }
+                // A binding whose initializer is a function is already related to what
+                // it reads by that function's own graph node, and by its return
+                // expressions rather than its whole body.
+                if (node.init &&
+                    !node.id.typeAnnotation &&
+                    !isFunctionLike(node.init)) {
+                    inferredValueDeclarations.push({ name: node.id, init: node.init });
+                }
+                if (!node.id.typeAnnotation || node.id.optional || node.definite) {
                     return;
                 }
                 const assertionType = extractAssertionTypeNode(node.init);
@@ -430,7 +992,26 @@ exports.noRedundantAnnotationAssertion = (0, createRule_1.createRule)({
                     return;
                 collectIfRedundant(node.id.typeAnnotation, assertionType, node.id, node.id.typeAnnotation);
             },
+            // A parameter default relays a dependency the same way a body `const`
+            // does — `function helper(seed = build())` is the parameter spelling of
+            // `const seed = build()` — and nothing visited parameters, so the link was
+            // invisible (#1888). An annotated parameter is typed without consulting
+            // its default, so it breaks the chain like any written-down type.
+            AssignmentPattern(node) {
+                if (node.parent?.type === utils_1.AST_NODE_TYPES.Property ||
+                    node.left.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                    node.left.typeAnnotation) {
+                    return;
+                }
+                inferredValueDeclarations.push({ name: node.left, init: node.right });
+            },
             PropertyDefinition(node) {
+                if (node.value &&
+                    !node.typeAnnotation &&
+                    !node.computed &&
+                    !isFunctionLike(node.value)) {
+                    inferredValueDeclarations.push({ name: node.key, init: node.value });
+                }
                 if (!node.typeAnnotation ||
                     !node.value ||
                     node.optional ||
@@ -442,39 +1023,31 @@ exports.noRedundantAnnotationAssertion = (0, createRule_1.createRule)({
                 collectIfRedundant(node.typeAnnotation, assertionType, node.key, node.typeAnnotation);
             },
             FunctionDeclaration(node) {
+                functionLikeNodes.push(node);
                 if (!node.returnType)
                     return;
-                const assertionType = getReturnAssertion(node);
-                if (!assertionType)
-                    return;
-                collectIfRedundant(node.returnType, assertionType, node.id ?? node, node.returnType);
+                collectReturnSite(node, node.returnType, node.id ?? node);
             },
             FunctionExpression(node) {
                 if (node.parent?.type === utils_1.AST_NODE_TYPES.MethodDefinition) {
                     return;
                 }
+                functionLikeNodes.push(node);
                 if (!node.returnType)
                     return;
-                const assertionType = getReturnAssertion(node);
-                if (!assertionType)
-                    return;
-                collectIfRedundant(node.returnType, assertionType, node, node.returnType);
+                collectReturnSite(node, node.returnType, node);
             },
             ArrowFunctionExpression(node) {
+                functionLikeNodes.push(node);
                 if (!node.returnType)
                     return;
-                const assertionType = getReturnAssertion(node);
-                if (!assertionType)
-                    return;
-                collectIfRedundant(node.returnType, assertionType, node, node.returnType);
+                collectReturnSite(node, node.returnType, node);
             },
             MethodDefinition(node) {
+                functionLikeNodes.push(node);
                 if (!node.value.returnType)
                     return;
-                const assertionType = getReturnAssertion(node);
-                if (!assertionType)
-                    return;
-                collectIfRedundant(node.value.returnType, assertionType, node.key, node.value.returnType);
+                collectReturnSite(node, node.value.returnType, node.key);
             },
         };
     },