@blumintinc/eslint-plugin-blumint 1.20.152 → 1.20.154

package/lib/index.js

@@ -223,7 +223,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.20.152',
+        version: '1.20.154',
     },
     parseOptions: {
         ecmaVersion: 2020,

package/lib/rules/enforce-boolean-naming-prefixes.js

@@ -69,6 +69,111 @@ function memberNameOf(key) {
     }
     return undefined;
 }
+const EQUALITY_OPERATORS = new Set([
+    '===',
+    '!==',
+    '==',
+    '!=',
+]);
+/**
+ * The text of a literal string, written either way round: `'string'` and
+ * `` `string` `` assert the same thing about the operand beside them.
+ */
+function stringLiteralValueOf(node) {
+    if (node.type === utils_1.AST_NODE_TYPES.Literal && typeof node.value === 'string') {
+        return node.value;
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.TemplateLiteral &&
+        node.expressions.length === 0 &&
+        node.quasis.length === 1) {
+        return node.quasis[0].value.cooked;
+    }
+    return undefined;
+}
+/**
+ * The operand an equality comparison holds opposite `operand`, so operand
+ * order carries no meaning: `typeof x === 'string'` and
+ * `'string' === typeof x` are the same assertion.
+ */
+function comparedAgainst(comparison, operand) {
+    if (!EQUALITY_OPERATORS.has(comparison.operator))
+        return undefined;
+    if (comparison.left === operand)
+        return comparison.right;
+    if (comparison.right === operand)
+        return comparison.left;
+    return undefined;
+}
+/**
+ * The outermost node standing for the same value, so a contradiction written
+ * around `verdict!` or `verdict as string` is a contradiction about
+ * `verdict`.
+ */
+function passthroughValueOf(node) {
+    let current = node;
+    while (current.parent) {
+        const { parent } = current;
+        const wraps = (parent.type === utils_1.AST_NODE_TYPES.TSNonNullExpression ||
+            parent.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+            parent.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression ||
+            parent.type === utils_1.AST_NODE_TYPES.TSTypeAssertion ||
+            parent.type === utils_1.AST_NODE_TYPES.ChainExpression) &&
+            parent.expression ===
+                current;
+        if (!wraps)
+            break;
+        current = parent;
+    }
+    return current;
+}
+/** `Error`, `TypeError` and any `…Error` class take a string message. */
+function isErrorConstructor(callee) {
+    if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return callee.name.endsWith('Error');
+    }
+    if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+        const member = memberNameOf(callee.property);
+        return !!member && member.name.endsWith('Error');
+    }
+    return false;
+}
+/**
+ * Whether this reference uses the value in a way a boolean could not be
+ * used, which disproves a booleanness read off a name.
+ */
+function referenceContradictsBoolean(reference) {
+    const value = passthroughValueOf(reference);
+    const { parent } = value;
+    if (!parent)
+        return false;
+    // `typeof verdict === 'string'`. A tag of `'boolean'` AFFIRMS the boolean
+    // reading whichever equality operator carries it — `!== 'boolean'` is how
+    // a boolean guard is spelled — so only some other tag contradicts.
+    if (parent.type === utils_1.AST_NODE_TYPES.UnaryExpression &&
+        parent.operator === 'typeof' &&
+        parent.argument === value) {
+        const comparison = parent.parent;
+        if (comparison?.type !== utils_1.AST_NODE_TYPES.BinaryExpression)
+            return false;
+        const other = comparedAgainst(comparison, parent);
+        const tag = other ? stringLiteralValueOf(other) : undefined;
+        return tag !== undefined && tag !== 'boolean';
+    }
+    // `verdict === 'occupied'` — a value compared with a string is not a
+    // boolean, since no boolean is ever equal to one.
+    if (parent.type === utils_1.AST_NODE_TYPES.BinaryExpression) {
+        const other = comparedAgainst(parent, value);
+        return !!other && stringLiteralValueOf(other) !== undefined;
+    }
+    // `throw new Error(verdict)` — the message parameter is a string, so the
+    // binding carries the failure reason rather than a verdict flag.
+    if (parent.type === utils_1.AST_NODE_TYPES.NewExpression &&
+        parent.arguments[0] === value &&
+        isErrorConstructor(parent.callee)) {
+        return true;
+    }
+    return false;
+}
 exports.enforceBooleanNamingPrefixes = (0, createRule_1.createRule)({
     name: 'enforce-boolean-naming-prefixes',
     meta: {
@@ -914,6 +1019,66 @@ exports.enforceBooleanNamingPrefixes = (0, createRule_1.createRule)({
             }
             return calleeReturnEvaluation(calleeName) !== 'nonBoolean';
         }
+        /**
+         * Whether the only evidence that a binding holds a boolean is a NAME.
+         *
+         * `calleeReturnEvaluation` answers "does this callee demonstrably return a
+         * non-boolean?"; its 'indeterminate' verdict is the case where the callee's
+         * body is out of reach (an import, a parameter, a value read off a builder
+         * chain) and the callee's `is`/`has`/`can` prefix is all that is left. A
+         * boolean-sounding property (`state.isValid`) is the same kind of evidence.
+         *
+         * Everything else — an explicit `: boolean` annotation, a boolean literal, a
+         * comparison or negation, a `Boolean()` coercion, a resolvable declaration
+         * whose return classifies as boolean — is evidence about the VALUE, which no
+         * use site is allowed to outrank.
+         */
+        function booleanEvidenceIsNameOnly(declarator) {
+            if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                hasBooleanTypeAnnotation(declarator.id) ||
+                !declarator.init) {
+                return false;
+            }
+            const restsOnName = (expression) => {
+                const value = unwrapChainExpression(expression);
+                // A property name is the whole of the evidence in
+                // `isLikelyBooleanByMemberExpression`, the only path that reads one.
+                if (value.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+                    return true;
+                }
+                if (value.type === utils_1.AST_NODE_TYPES.CallExpression &&
+                    value.callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    return (!isGlobalBooleanCall(value) &&
+                        calleeReturnEvaluation(value.callee.name) === 'indeterminate');
+                }
+                // `isFoo(x) || fallback` reaches booleanness through its left operand.
+                if (value.type === utils_1.AST_NODE_TYPES.LogicalExpression &&
+                    value.operator === '||') {
+                    return restsOnName(value.left);
+                }
+                return false;
+            };
+            return restsOnName(declarator.init);
+        }
+        /**
+         * Whether any use of the binding contradicts booleanness.
+         *
+         * Validator families built on `ValidatorPipeline` return `true | string` —
+         * `true` for a pass, the failure message for a fail — while
+         * `enforce-is-prefix-validators` requires the validator itself to be
+         * `is`-prefixed. Inferring the result's booleanness from that mandated
+         * prefix makes the two rules unsatisfiable together, so a use site that
+         * reads the value as a string settles it against the name.
+         *
+         * References come from the scope manager, never from matching the name as
+         * text: a contradiction must belong to THIS binding, not to a shadowing
+         * inner one, a sibling scope's binding, or an unrelated same-named value.
+         */
+        function useSiteContradictsBoolean(declarator) {
+            return context
+                .getDeclaredVariables(declarator)
+                .some((variable) => variable.references.some((reference) => referenceContradictsBoolean(reference.identifier)));
+        }
         /**
          * Check if a variable is used in a while loop condition and is likely a DOM element or tree node
          * This helps identify variables like 'parent', 'element', 'node', etc. that are used
@@ -1233,6 +1398,14 @@ exports.enforceBooleanNamingPrefixes = (0, createRule_1.createRule)({
                     utils_1.AST_NODE_TYPES.TSBooleanKeyword) {
                 isBooleanVar = true;
             }
+            // A booleanness read off a name loses to a use site that treats the value
+            // as something else, which is what keeps this rule satisfiable alongside
+            // `enforce-is-prefix-validators` for `true | string` validator verdicts.
+            if (isBooleanVar &&
+                booleanEvidenceIsNameOnly(node) &&
+                useSiteContradictsBoolean(node)) {
+                return;
+            }
             if (isBooleanVar && !hasApprovedPrefix(variableName)) {
                 context.report({
                     node: node.id,

package/lib/rules/enforce-object-literal-as-const.js

@@ -207,25 +207,41 @@ exports.enforceObjectLiteralAsConst = (0, createRule_1.createRule)({
             return undefined;
         }
         /**
-         * `as const` turns an array literal into a readonly *tuple*, which TS4104
-         * refuses to assign to a mutable array or tuple. Where the annotation says
-         * the value must be mutable, appending `as const` breaks the build, and no
-         * edit at the literal can satisfy the rule — honouring it would mean
-         * rewriting the signature, a call the author has to make. So the rule stays
-         * silent rather than reporting something the developer cannot act on
-         * (#1526).
+         * `as const` turns an array literal into a fixed-length readonly *tuple*,
+         * strictly narrower than the mutable array the literal otherwise gets. Two
+         * separate breakages follow from that narrowing, and neither is visible at
+         * the literal:
+         *
+         * - Where the enclosing signature declares a mutable array or tuple, TS4104
+         *   refuses the assignment, so appending `as const` breaks the build. No
+         *   edit at the literal satisfies the rule — honouring it means rewriting
+         *   the signature, a call the author has to make (#1526).
+         * - Where the signature is inferred, the frozen arity becomes part of the
+         *   return type and every caller inherits it: `.length` narrows to a literal
+         *   number (TS2367 against any other length), `.includes` narrows its
+         *   parameter to the element union — `never` for `[]` — (TS2345), and the
+         *   value stops satisfying a mutable `T[]` parameter. The break lands in a
+         *   different function than the one edited, and the callers are beyond what
+         *   the rule can see (#2015).
+         *
+         * So an array literal is left alone unless the enclosing signature states a
+         * type that accepts a readonly tuple. An annotation the rule cannot resolve
+         * still counts as accepting, per `acceptsReadonlyArray`: the annotation, not
+         * the literal, is what callers read, so the arity never escapes.
          *
          * Object literals are unaffected: `readonly` property modifiers do not
          * enter assignability, so `{ a: 1 } as const` still satisfies a mutable
-         * `{ a: number }`.
+         * `{ a: number }`, and freezing one fixes no arity.
          */
-        function conflictsWithDeclaredType(literal, ancestors) {
+        function freezingArrayIsUnsafe(literal, ancestors) {
             if (!isArrayLiteral(literal)) {
                 return false;
             }
             const enclosingFunction = enclosingFunctionOf(ancestors);
-            if (!enclosingFunction) {
-                return false;
+            // With no declared return type in view, the inferred tuple is what the
+            // callers get.
+            if (!enclosingFunction || !declaredReturnTypeOf(enclosingFunction)) {
+                return true;
             }
             const returnedValueType = returnedValueTypeOf(enclosingFunction);
             return !!returnedValueType && !acceptsReadonlyArray(returnedValueType);
@@ -285,10 +301,10 @@ exports.enforceObjectLiteralAsConst = (0, createRule_1.createRule)({
                 if (isInsideReactHook(ancestors) && isArrayLiteral(literal)) {
                     return;
                 }
-                // Skip arrays the enclosing signature declares mutable: `as const`
-                // cannot compile there and the developer cannot act on the report
-                // (#1526)
-                if (conflictsWithDeclaredType(literal, ancestors)) {
+                // Skip arrays whose enclosing signature does not accept the readonly
+                // tuple `as const` produces — declared mutable (#1526) or inferred, in
+                // which case the frozen arity reaches every caller (#2015)
+                if (freezingArrayIsUnsafe(literal, ancestors)) {
                     return;
                 }
                 // Report the issue and provide a fix

package/lib/rules/global-const-style.js

@@ -108,6 +108,139 @@ const isComponentFactoryCall = (node) => {
 // the same terms as `const Row = (props) => {...}` (Issue #1681).
 const isFunctionValue = (node) => node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
     node.type === utils_1.AST_NODE_TYPES.FunctionExpression;
+// `as const` does more than pin literal types: it makes the value deeply
+// `readonly`. A binding that is written through after its declaration therefore
+// cannot carry the assertion at all — appending it turns compiling code into
+// `TS2339: Property 'push' does not exist on type 'readonly []'` for an array
+// and `TS2540: Cannot assign to 'a' because it is a read-only property` for an
+// object (Issue #2013). These are the built-in methods that mutate their
+// receiver rather than returning a fresh value, so a call to one of them is a
+// write even though no assignment target names the binding.
+const MUTATING_METHOD_NAMES = new Set([
+    'push',
+    'pop',
+    'shift',
+    'unshift',
+    'splice',
+    'sort',
+    'reverse',
+    'fill',
+    'copyWithin',
+]);
+/**
+ * Climbs out of the wrappers that denote the same value as `node` — type
+ * wrappers (`(X as any).push()`, `X!.push()`) and the `ChainExpression` an
+ * optional access hangs on the outside of the whole chain (`delete X?.a`). The
+ * role a node plays in its statement is decided by the outermost such wrapper,
+ * so a classifier that reads `node.parent` directly answers for the wrapper
+ * instead of the access.
+ */
+const outermostValueOf = (node) => {
+    let current = node;
+    for (;;) {
+        const parent = current.parent;
+        if (parent &&
+            ((isValueWrapper(parent) && parent.expression === current) ||
+                (parent.type === utils_1.AST_NODE_TYPES.ChainExpression &&
+                    parent.expression === current))) {
+            current = parent;
+            continue;
+        }
+        return current;
+    }
+};
+/**
+ * The outermost property-access path rooted at `identifier`: `X` in `X.a.b`
+ * yields the `X.a.b` member expression. Returns `null` when the identifier is
+ * not the base of any access, which is every reference that merely reads the
+ * binding as a value — `other.push(X)` passes it as an ARGUMENT, so the
+ * mutation happens to `other`, not to `X`.
+ *
+ * The climb stops at the first parent that is not a member access on the
+ * current node, so `X.map(f).push(1)` yields `X.map`: the mutated receiver
+ * there is the array `map` returned, not `X`.
+ */
+const accessPathOf = (identifier) => {
+    let current = outermostValueOf(identifier);
+    let path = null;
+    for (;;) {
+        const parent = current.parent;
+        if (!parent ||
+            parent.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+            parent.object !== current) {
+            return path;
+        }
+        path = parent;
+        current = outermostValueOf(parent);
+    }
+};
+/** The property name an access reads, for `X.push` and `X['push']` alike. */
+const accessedPropertyName = (path) => {
+    if (!path.computed && path.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return path.property.name;
+    }
+    if (path.computed &&
+        path.property.type === utils_1.AST_NODE_TYPES.Literal &&
+        typeof path.property.value === 'string') {
+        return path.property.value;
+    }
+    return null;
+};
+const isMutatingMethodCall = (path) => {
+    const propertyName = accessedPropertyName(path);
+    if (propertyName === null || !MUTATING_METHOD_NAMES.has(propertyName)) {
+        return false;
+    }
+    const callee = outermostValueOf(path);
+    return (callee.parent?.type === utils_1.AST_NODE_TYPES.CallExpression &&
+        callee.parent.callee === callee);
+};
+/**
+ * Whether `node` sits in a position that writes to it: the left of an
+ * assignment (plain or compound), the operand of `++`/`--` or `delete`, the
+ * loop variable of `for…in`/`for…of`, or a slot in a destructuring assignment
+ * target (`[X.a] = […]`, `({ p: X.a } = …)`).
+ */
+const isWriteTarget = (node) => {
+    const value = outermostValueOf(node);
+    const parent = value.parent;
+    if (!parent) {
+        return false;
+    }
+    switch (parent.type) {
+        case utils_1.AST_NODE_TYPES.AssignmentExpression:
+            return parent.left === value;
+        case utils_1.AST_NODE_TYPES.UpdateExpression:
+            return parent.argument === value;
+        case utils_1.AST_NODE_TYPES.UnaryExpression:
+            return parent.operator === 'delete' && parent.argument === value;
+        case utils_1.AST_NODE_TYPES.ForInStatement:
+        case utils_1.AST_NODE_TYPES.ForOfStatement:
+            return parent.left === value;
+        // Destructuring targets nest, so the answer belongs to the pattern's own
+        // position. The same node types appear in ObjectExpression/ArrayExpression
+        // VALUES, where the recursion reaches a non-assignment parent and stops.
+        case utils_1.AST_NODE_TYPES.ArrayPattern:
+        case utils_1.AST_NODE_TYPES.ObjectPattern:
+        case utils_1.AST_NODE_TYPES.Property:
+        case utils_1.AST_NODE_TYPES.RestElement:
+        case utils_1.AST_NODE_TYPES.AssignmentPattern:
+            return isWriteTarget(parent);
+        default:
+            return false;
+    }
+};
+/**
+ * Whether the binding is written through anywhere in the file. Answered from
+ * the scope manager's reference list rather than a textual search for the
+ * name, so a same-named binding in another scope (`const arr` shadowed inside a
+ * callback) contributes nothing, and a same-named method on an unrelated
+ * receiver (`other.push(1)`) is never even visited.
+ */
+const isBindingMutated = (variable) => variable.references.some((reference) => {
+    const path = accessPathOf(reference.identifier);
+    return path !== null && (isMutatingMethodCall(path) || isWriteTarget(path));
+});
 /**
  * Walks the scope chain upward from `scope` (inclusive) and reports whether
  * `targetName` is bound anywhere between `scope` and `stopScope` (inclusive).
@@ -366,9 +499,22 @@ exports.default = (0, createRule_1.createRule)({
                                 (target.value === null || typeof target.value === 'boolean')) {
                                 return false;
                             }
-                            return (target.type === utils_1.AST_NODE_TYPES.Literal ||
-                                target.type === utils_1.AST_NODE_TYPES.ArrayExpression ||
-                                target.type === utils_1.AST_NODE_TYPES.ObjectExpression);
+                            if (target.type !== utils_1.AST_NODE_TYPES.Literal &&
+                                target.type !== utils_1.AST_NODE_TYPES.ArrayExpression &&
+                                target.type !== utils_1.AST_NODE_TYPES.ObjectExpression) {
+                                return false;
+                            }
+                            // A binding that is mutated later can never take the assertion:
+                            // `as const` types the value `readonly`, so the appended text
+                            // turns working code into TS2339/TS2540 (Issue #2013). The
+                            // report is withheld rather than merely the fix, on the same
+                            // terms as the `null`/boolean carve-out above — a violation no
+                            // legal edit can clear is not a violation. The rename is a
+                            // separate concern and still applies.
+                            const declaredVariable = context
+                                .getDeclaredVariables(declaration)
+                                .find((variable) => variable.name === name);
+                            return !declaredVariable || !isBindingMutated(declaredVariable);
                         };
                         if (shouldHaveAsConst(init)) {
                             context.report({

package/lib/rules/no-explicit-return-type.js

@@ -713,6 +713,104 @@ function declaresVoidResult(returnType) {
     return (typeArguments?.length === 1 &&
         typeArguments[0].type === utils_1.AST_NODE_TYPES.TSVoidKeyword);
 }
+// TypeScript's built-in decorator signatures. A factory annotated with one of
+// these is the one shape where the annotation is WIDER than what inference
+// produces rather than a restatement of it: `MethodDecorator` accepts three
+// parameters, the returned closure typically declares none, and a decoration
+// site requires the declared arity. Stripping the annotation therefore turns
+// every `@Factory()` use into TS1329 (#2014).
+const DECORATOR_TYPE_NAMES = new Set([
+    'ClassDecorator',
+    'MethodDecorator',
+    'ParameterDecorator',
+    'PropertyDecorator',
+]);
+/**
+ * The identifier a type name resolves to. A qualified name (`ts.MethodDecorator`)
+ * denotes the type its right-most segment names, so that segment is what decides
+ * — a substring test over the printed annotation would equally match
+ * `MyMethodDecoratorConfig`, which is an unrelated user type.
+ */
+function rightmostTypeName(typeName) {
+    if (typeName.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return typeName.name;
+    }
+    if (typeName.type === utils_1.AST_NODE_TYPES.TSQualifiedName) {
+        return rightmostTypeName(typeName.right);
+    }
+    return undefined;
+}
+function namesDecoratorType(annotation) {
+    if (annotation.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
+        const name = rightmostTypeName(annotation.typeName);
+        return name !== undefined && DECORATOR_TYPE_NAMES.has(name);
+    }
+    // A factory usable in more than one position (`ClassDecorator &
+    // MethodDecorator`) still owes every decoration site the declared shape.
+    if (annotation.type === utils_1.AST_NODE_TYPES.TSUnionType ||
+        annotation.type === utils_1.AST_NODE_TYPES.TSIntersectionType) {
+        return annotation.types.some(namesDecoratorType);
+    }
+    return false;
+}
+/**
+ * The identifier a CALLED decorator invokes: `Log` for `@Log()` and `@Log()()`.
+ *
+ * Only a called decorator identifies a factory, and only a factory's return type
+ * is what the decoration site consumes. A bare `@Log` names the decorator
+ * itself, whose annotation restates the value it returns exactly as inference
+ * would — so it stays reportable rather than being silenced by proximity to a
+ * decorator.
+ *
+ * An owner-qualified decorator (`@registry.log()`) names a property rather than
+ * a binding, and matching it by property name alone would silence the rule on
+ * every unrelated method of the same name, so it yields nothing.
+ */
+function decoratorFactoryIdentifier(expression) {
+    if (expression.type !== utils_1.AST_NODE_TYPES.CallExpression)
+        return undefined;
+    const callee = expression.callee;
+    if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return callee;
+    }
+    return decoratorFactoryIdentifier(callee);
+}
+/**
+ * The declarations invoked by a decorator in this file.
+ *
+ * This catches the factory whose annotation is a user-defined decorator type
+ * (`type Cached = (t: object, k: string, d: PropertyDescriptor) => void`), which
+ * no name test can recognise. Each identifier is resolved through the scope
+ * manager rather than compared by name, so a same-named binding elsewhere in the
+ * file cannot silence the rule on a function no decorator actually reaches.
+ */
+function decoratorReferencedDeclarations(source, visitorKeys) {
+    const heads = new Set();
+    const stack = [source.ast];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current.type === utils_1.AST_NODE_TYPES.Decorator) {
+            const head = decoratorFactoryIdentifier(current.expression);
+            if (head) {
+                heads.add(head);
+            }
+        }
+        pushChildren(current, visitorKeys, stack);
+    }
+    const declarations = new Set();
+    if (heads.size === 0)
+        return declarations;
+    for (const scope of source.scopeManager?.scopes ?? []) {
+        for (const reference of scope.references) {
+            if (!heads.has(reference.identifier))
+                continue;
+            for (const definition of reference.resolved?.defs ?? []) {
+                declarations.add(definition.node);
+            }
+        }
+    }
+    return declarations;
+}
 function containsRange(outer, inner) {
     return inner[0] >= outer[0] && inner[1] <= outer[1];
 }
@@ -967,6 +1065,40 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
         // Edges are resolved lazily, and only for functions a direct
         // self-reference has already failed to explain.
         const participatesInReturnCycle = createReturnCycleResolver(visitorKeys);
+        // Decorators are visited after the functions they name — a class body is
+        // walked long after the top-level factory it decorates with — so the
+        // answer is computed from the whole tree rather than accumulated during
+        // the walk, and memoised because most files hold no decorator at all.
+        let decoratedDeclarations;
+        const declarationsNamedByDecorators = () => {
+            decoratedDeclarations ??= decoratorReferencedDeclarations(sourceCode, visitorKeys);
+            return decoratedDeclarations;
+        };
+        /**
+         * True when the annotation is what makes the function usable in a
+         * decorator position. TypeScript infers the concrete closure the factory
+         * returns — `() => void` for `return () => {};` — which declares fewer
+         * parameters than a decoration site passes, so removing the annotation
+         * turns every `@Factory()` use into TS1329 (#2014).
+         *
+         * The question is answered syntactically. A `RuleTester` fixture carries
+         * no `parserOptions.project`, so a type-based answer would be untestable
+         * and would silently no-op wherever consumers lint without a program.
+         */
+        function isDecoratorFactory(node, returnType) {
+            if (namesDecoratorType(returnType.typeAnnotation))
+                return true;
+            const declarations = declarationsNamedByDecorators();
+            if (declarations.size === 0)
+                return false;
+            if (declarations.has(node))
+                return true;
+            // `const Log = (): Cached => ...` is bound by its declarator, which is
+            // what a decorator's identifier resolves to.
+            const parent = node.parent;
+            return (parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+                declarations.has(parent));
+        }
         /**
          * True when TypeScript cannot infer the return type because the function
          * is referenced from within its own return expression (TS7023). Removing
@@ -1100,6 +1232,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                 if (isTypeGuardFunction(node) ||
                     isReadonlyWideningReturnType(returnType) ||
                     isAllowedVoidReturnType(returnType) ||
+                    isDecoratorFactory(node, returnType) ||
                     (mergedOptions.allowRecursiveFunctions &&
                         isRecursiveFunction(node)) ||
                     isReturnTypeRequiredByRecursion(node)) {
@@ -1117,6 +1250,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                 if (isTypeGuardFunction(node) ||
                     isReadonlyWideningReturnType(returnType) ||
                     isAllowedVoidReturnType(returnType) ||
+                    isDecoratorFactory(node, returnType) ||
                     (mergedOptions.allowRecursiveFunctions &&
                         isRecursiveFunction(node)) ||
                     isReturnTypeRequiredByRecursion(node)) {
@@ -1131,6 +1265,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                 if (isTypeGuardFunction(node) ||
                     isReadonlyWideningReturnType(returnType) ||
                     isAllowedVoidReturnType(returnType) ||
+                    isDecoratorFactory(node, returnType) ||
                     isReturnTypeRequiredByRecursion(node)) {
                     return;
                 }
@@ -1156,6 +1291,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                 if (isTypeGuardFunction(node.value) ||
                     isReadonlyWideningReturnType(returnType) ||
                     isAllowedVoidReturnType(returnType) ||
+                    isDecoratorFactory(node, returnType) ||
                     (mergedOptions.allowAbstractMethodSignatures &&
                         isInterfaceOrAbstractMethodSignature(node)) ||
                     isReturnTypeRequiredByRecursion(node)) {

package/lib/rules/parallelize-async-operations.js

@@ -1127,9 +1127,54 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
             return variable.defs.every((definition) => definition.name.range[0] >= root.range[0] &&
                 definition.name.range[1] <= root.range[1]);
         }
+        /**
+         * Records the instance slot a method call MUTATES THROUGH ITS RECEIVER.
+         * `this.accumulated.set(doc, 1)` publishes to `this.accumulated` exactly as
+         * `this.accumulated = next` does, but it is a CallExpression rather than an
+         * assignment, so the assignment-shaped visit below never sees it. A sweep
+         * that fills an accumulator through the accumulator's own API then reads as
+         * writing nothing, a later await that reads that slot is classified
+         * independent, and the rewrite runs the read against the still-empty
+         * accumulator. (#2017)
+         *
+         * ANY method invoked on the slot counts, rather than a list of known
+         * mutators. The receiver is already the unit barrier 7 treats as ordered,
+         * and a domain `append`/`record`/`write` mutates its receiver exactly as
+         * `set` does, so naming a subset would leave the same silent reorder
+         * reachable under a different spelling. Over-recording a pure
+         * `this.cache.size()` costs only a missed parallelization, which is the
+         * trade this rule takes everywhere.
+         *
+         * Only calls in DEFERRED position qualify -- those the traversal reaches by
+         * crossing into a callback or a resolved callee body. A call spelled in the
+         * operand's own text already carries a receiver key, so barriers 7 and 12
+         * order it with carve-outs calibrated against exactly this: they return no
+         * key for a call-produced receiver (`this.realtimeDb.ref(pathA).remove()`)
+         * or a varying subscript (`this.handlers[0].read()`), which is what keeps
+         * two argument-disambiguated operations on one handle parallelizable.
+         * Recording those same calls here would mint a write on the shared prefix
+         * and silently override that calibration. Behind a callback no receiver key
+         * exists at the operand level at all, so nothing is overridden -- that is
+         * the blind spot, and its whole extent.
+         *
+         * The BARE instance (`this.storeAll()`) is excluded for the same reason:
+         * recording it would mint a wildcard write overlapping every slot, turning
+         * the precise treatment those barriers give it into a blanket one.
+         */
+        function collectMutatedReceiver(call, targets) {
+            const callee = unwrapExpression(call.callee);
+            if (callee.type !== utils_1.AST_NODE_TYPES.MemberExpression) {
+                return;
+            }
+            const receiverPath = getInstancePathKey(callee.object);
+            if (receiverPath !== null && receiverPath !== INSTANCE_RECEIVER_KEY) {
+                targets.instancePaths.push(receiverPath);
+            }
+        }
         /**
          * Collects the state an awaited expression WRITES: the identifier names it
-         * assigns, and the instance paths (`this.mutator`) it assigns. (#1924)
+         * assigns, and the instance paths (`this.mutator`) it assigns or mutates
+         * through a method call. (#1924, #2017)
          *
          * The traversal deliberately crosses function boundaries, which is the
          * opposite of what containsSuspendingAwait needs: the write that matters
@@ -1144,7 +1189,7 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
          */
         function getAssignedState(node) {
             const targets = { identifiers: [], instancePaths: [] };
-            const visit = (current) => {
+            const visit = (current, deferred) => {
                 if (current.type === utils_1.AST_NODE_TYPES.AssignmentExpression) {
                     collectAssignmentTarget(current.left, targets);
                 }
@@ -1158,6 +1203,10 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
                     // iteration; only the declaration form introduces a fresh local.
                     collectAssignmentTarget(current.left, targets);
                 }
+                else if (deferred && current.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                    collectMutatedReceiver(current, targets);
+                }
+                const childrenDeferred = deferred || FUNCTION_BOUNDARY_TYPES.has(current.type);
                 for (const key in current) {
                     if (key === 'parent' || key === 'range' || key === 'loc')
                         continue;
@@ -1167,16 +1216,19 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
                     if (Array.isArray(child)) {
                         for (const item of child) {
                             if (item && typeof item === 'object' && 'type' in item) {
-                                visit(item);
+                                visit(item, childrenDeferred);
                             }
                         }
                     }
                     else if ('type' in child) {
-                        visit(child);
+                        visit(child, childrenDeferred);
                     }
                 }
             };
-            visit(node);
+            // A resolved callee body is itself deferred relative to the run, and
+            // entering it crosses its own function boundary, so the flag lifts here
+            // exactly as it does for a callback. (#1989, #2017)
+            visit(node, false);
             const names = new Set();
             for (const target of targets.identifiers) {
                 if (!isDeclaredWithin(target, node)) {
@@ -1445,11 +1497,26 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
                     ]),
                 };
             });
+            //
+            // The READ side resolves the callee body for the same reason the write
+            // side does, and the omission was the other half of #2017: `await
+            // this.storeAll()` spells only the slot `this.storeAll`, so a preceding
+            // write to `this.accumulated` -- the slot `storeAll` actually reads --
+            // compares as disjoint and the pair parallelizes. Reading the resolved
+            // body restores the edge. An unresolvable callee (inherited, computed,
+            // imported) yields null and leaves the operand keyed on its own text, as
+            // before.
             const readInstancePaths = awaitNodes.map((node) => {
                 const awaitExpr = getAwaitExpression(node);
-                return awaitExpr
-                    ? getInstancePathKeys(awaitExpr.argument)
-                    : new Set();
+                if (!awaitExpr) {
+                    return new Set();
+                }
+                const read = getInstancePathKeys(awaitExpr.argument);
+                const calleeFunction = resolveCalleeFunction(awaitExpr);
+                if (!calleeFunction) {
+                    return read;
+                }
+                return new Set([...read, ...getInstancePathKeys(calleeFunction)]);
             });
             for (let i = 1; i < awaitNodes.length; i++) {
                 const currentIds = allIdentifiers[i];

package/lib/utils/docsFixtures.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared machinery for reading the documented examples out of `docs/rules/*.md`
+ * and linting them.
+ *
+ * Extracted so that more than one guard can ask a question of the SAME parsed
+ * corpus. `docs-examples-conformance` asks whether a block satisfies its own
+ * rule; `docs-correct-block-regression` asks whether the blocks #1982 fixed
+ * still satisfy the OTHER rule that used to report on them. Hand-rolling the
+ * fence walker or the candidate-filename list a second time is how two guards
+ * come to disagree about which blocks exist — the failure `fixtureCorpus.ts`
+ * exists to prevent on the RuleTester side, and the reason four guards there
+ * inherited the same two silent losses (#1984).
+ *
+ * The filename list in particular is load-bearing and must not be duplicated:
+ * many rules key off the path, so judging a block under a path the rule was
+ * never meant to see manufactures a failure.
+ */
+export declare const PREFIX = "@blumintinc/blumint/";
+export declare const DOCS_DIR: string;
+export declare const pageExists: (rule: string) => boolean;
+export declare const readPage: (rule: string) => string | null;
+/** Fence languages that hold lintable TypeScript. */
+export declare const LINTABLE_LANGS: Set<string>;
+/**
+ * Candidate filenames, tried in order. Many rules key off the path (cloud
+ * function entry points, test-file exemptions, component directories), so a
+ * single hard-coded filename would make correct examples report for reasons the
+ * doc never claimed.
+ */
+export declare const TS_CANDIDATES: string[];
+export declare const TSX_CANDIDATES: string[];
+/**
+ * Rules that match on path segments need a rooted path — `functions/src/types/x.ts`
+ * relative does not satisfy the same check that `/repo/functions/src/types/x.ts`
+ * does, which would fail a doc example for a reason the doc never claimed.
+ */
+export declare const ROOT = "/repo/";
+export declare const anchor: (p: string) => string;
+export type Block = {
+    /**
+     * `null` for a fence under no example heading. Such blocks are kept rather
+     * than dropped: a page whose fences all come back unlabelled is a detection
+     * failure, and dropping them made it indistinguishable from a page that
+     * documents no examples at all (#1499).
+     */
+    polarity: 'correct' | 'incorrect' | null;
+    lang: string;
+    code: string;
+    line: number;
+};
+/**
+ * Classify an example heading.
+ *
+ * Only H2+ headings count: the H1 title ends with the rule id, and rule names
+ * routinely contain `prefer`, `valid`, or `no`, which would otherwise classify
+ * every block in the intro prose. The rule-id parenthetical is stripped for the
+ * same reason.
+ *
+ * Order matters — "incorrect" contains "correct" and "invalid" contains "valid",
+ * so the negative spellings must be tested first.
+ */
+export declare function headingPolarity(line: string): Block['polarity'] | null;
+/**
+ * Pull every fenced code block, tagged with the polarity of the example heading
+ * it sits under (`null` when it sits under none).
+ *
+ * Polarity is inherited by DEEPER headings, because docs routinely split an
+ * example section into named cases (`#### Option 1: …` under `### Examples of
+ * correct code`). Treating such a sub-heading as the end of the section dropped
+ * every block beneath it, which is how three whole pages asserted nothing.
+ */
+export declare function extractBlocks(md: string): Block[];
+/**
+ * Docs declare the context a snippet assumes inside the snippet itself:
+ * `// File: functions/src/...` (or a bare path comment) for path-sensitive
+ * rules, and `// eslint-options: {...}` for an example that only holds under a
+ * non-default option. Honouring both is what lets every correct block be
+ * enforced without exempting the awkward ones.
+ */
+export declare function filenameHint(code: string): string | null;
+export declare function optionsHint(code: string): unknown | null;
+export type LintResult = {
+    reports: string[];
+    /** 1-based lines of the same reports, for segment attribution (#1622). */
+    reportLines: number[];
+    skipped: boolean;
+    reason?: string;
+};
+export declare function lintBlock(ruleName: string, filename: string, code: string, options: unknown | null): LintResult;

package/lib/utils/docsFixtures.js

@@ -0,0 +1,244 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lintBlock = exports.optionsHint = exports.filenameHint = exports.extractBlocks = exports.headingPolarity = exports.anchor = exports.ROOT = exports.TSX_CANDIDATES = exports.TS_CANDIDATES = exports.LINTABLE_LANGS = exports.readPage = exports.pageExists = exports.DOCS_DIR = exports.PREFIX = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const eslint_1 = require("eslint");
+/* eslint-disable @typescript-eslint/no-var-requires */
+const plugin = require('../index');
+const tsParser = require('@typescript-eslint/parser');
+/* eslint-enable @typescript-eslint/no-var-requires */
+/**
+ * Shared machinery for reading the documented examples out of `docs/rules/*.md`
+ * and linting them.
+ *
+ * Extracted so that more than one guard can ask a question of the SAME parsed
+ * corpus. `docs-examples-conformance` asks whether a block satisfies its own
+ * rule; `docs-correct-block-regression` asks whether the blocks #1982 fixed
+ * still satisfy the OTHER rule that used to report on them. Hand-rolling the
+ * fence walker or the candidate-filename list a second time is how two guards
+ * come to disagree about which blocks exist — the failure `fixtureCorpus.ts`
+ * exists to prevent on the RuleTester side, and the reason four guards there
+ * inherited the same two silent losses (#1984).
+ *
+ * The filename list in particular is load-bearing and must not be duplicated:
+ * many rules key off the path, so judging a block under a path the rule was
+ * never meant to see manufactures a failure.
+ */
+exports.PREFIX = '@blumintinc/blumint/';
+exports.DOCS_DIR = path_1.default.join(__dirname, '../../docs/rules');
+const pageExists = (rule) => fs_1.default.existsSync(path_1.default.join(exports.DOCS_DIR, `${rule}.md`));
+exports.pageExists = pageExists;
+const readPage = (rule) => (0, exports.pageExists)(rule)
+    ? fs_1.default.readFileSync(path_1.default.join(exports.DOCS_DIR, `${rule}.md`), 'utf8')
+    : null;
+exports.readPage = readPage;
+/** Fence languages that hold lintable TypeScript. */
+exports.LINTABLE_LANGS = new Set([
+    'ts',
+    'tsx',
+    'js',
+    'jsx',
+    'typescript',
+    'javascript',
+    '',
+]);
+/**
+ * Candidate filenames, tried in order. Many rules key off the path (cloud
+ * function entry points, test-file exemptions, component directories), so a
+ * single hard-coded filename would make correct examples report for reasons the
+ * doc never claimed.
+ */
+exports.TS_CANDIDATES = [
+    'src/util/helper.ts',
+    'functions/src/callable/handler.f.ts',
+    'functions/src/util/helper.ts',
+    'src/util/helper.test.ts',
+    'src/components/Widget.tsx',
+];
+exports.TSX_CANDIDATES = [
+    'src/components/Widget.tsx',
+    'src/pages/index.tsx',
+];
+/**
+ * Rules that match on path segments need a rooted path — `functions/src/types/x.ts`
+ * relative does not satisfy the same check that `/repo/functions/src/types/x.ts`
+ * does, which would fail a doc example for a reason the doc never claimed.
+ */
+exports.ROOT = '/repo/';
+const anchor = (p) => (p.startsWith('/') ? p : exports.ROOT + p);
+exports.anchor = anchor;
+/**
+ * Classify an example heading.
+ *
+ * Only H2+ headings count: the H1 title ends with the rule id, and rule names
+ * routinely contain `prefer`, `valid`, or `no`, which would otherwise classify
+ * every block in the intro prose. The rule-id parenthetical is stripped for the
+ * same reason.
+ *
+ * Order matters — "incorrect" contains "correct" and "invalid" contains "valid",
+ * so the negative spellings must be tested first.
+ */
+function headingPolarity(line) {
+    if (!/^#{2,6}\s/.test(line))
+        return null;
+    const text = line
+        .replace(/^#{2,6}\s*/, '')
+        .replace(/\(`?@blumintinc\/blumint\/[^)]*`?\)/g, '')
+        .toLowerCase();
+    if (/❌|👎|\bincorrect\b|\binvalid\b|\bbad\b|\bwrong\b/.test(text))
+        return 'incorrect';
+    if (/✅|👍|\bcorrect\b|\bvalid\b|\bgood\b/.test(text))
+        return 'correct';
+    return null;
+}
+exports.headingPolarity = headingPolarity;
+/**
+ * Pull every fenced code block, tagged with the polarity of the example heading
+ * it sits under (`null` when it sits under none).
+ *
+ * Polarity is inherited by DEEPER headings, because docs routinely split an
+ * example section into named cases (`#### Option 1: …` under `### Examples of
+ * correct code`). Treating such a sub-heading as the end of the section dropped
+ * every block beneath it, which is how three whole pages asserted nothing.
+ */
+function extractBlocks(md) {
+    const lines = md.split('\n');
+    const blocks = [];
+    let polarity = null;
+    let polarityDepth = 0;
+    let fence = null;
+    let buf = [];
+    let lang = '';
+    let startLine = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const fenceMatch = /^\s*(`{3,}|~{3,})(.*)$/.exec(line);
+        if (fence) {
+            if (fenceMatch &&
+                fenceMatch[1][0] === fence[0] &&
+                fenceMatch[1].length >= fence.length) {
+                blocks.push({
+                    polarity,
+                    lang: lang.trim().toLowerCase(),
+                    code: buf.join('\n'),
+                    line: startLine,
+                });
+                fence = null;
+                buf = [];
+            }
+            else {
+                buf.push(line);
+            }
+            continue;
+        }
+        const heading = /^(#{1,6})\s/.exec(line);
+        if (heading) {
+            const depth = heading[1].length;
+            const own = headingPolarity(line);
+            if (own) {
+                polarity = own;
+                polarityDepth = depth;
+            }
+            else if (!(polarity && depth > polarityDepth)) {
+                // A sibling or shallower heading ends the example section; a deeper one
+                // is a named case inside it and keeps the section's polarity.
+                polarity = null;
+                polarityDepth = 0;
+            }
+            continue;
+        }
+        if (fenceMatch) {
+            fence = fenceMatch[1];
+            lang = fenceMatch[2] || '';
+            startLine = i + 1;
+            buf = [];
+        }
+    }
+    return blocks;
+}
+exports.extractBlocks = extractBlocks;
+/**
+ * Docs declare the context a snippet assumes inside the snippet itself:
+ * `// File: functions/src/...` (or a bare path comment) for path-sensitive
+ * rules, and `// eslint-options: {...}` for an example that only holds under a
+ * non-default option. Honouring both is what lets every correct block be
+ * enforced without exempting the awkward ones.
+ */
+function filenameHint(code) {
+    const explicit = /^\s*(?:\/\/|\/\*)\s*File:\s*([^\s*]+)/im.exec(code);
+    if (explicit)
+        return (0, exports.anchor)(explicit[1].replace(/^\.\//, ''));
+    const firstLine = code.split('\n').find((l) => l.trim().length > 0) || '';
+    const bare = /^\s*\/\/\s*((?:[\w.-]+\/)+[\w.-]+\.tsx?)\b/.exec(firstLine);
+    return bare ? (0, exports.anchor)(bare[1]) : null;
+}
+exports.filenameHint = filenameHint;
+function optionsHint(code) {
+    const m = /^\s*\/\/\s*eslint-options:\s*(\{.*\})\s*$/im.exec(code);
+    if (!m)
+        return null;
+    try {
+        return JSON.parse(m[1]);
+    }
+    catch {
+        throw new Error(`malformed // eslint-options: ${m[1]}`);
+    }
+}
+exports.optionsHint = optionsHint;
+const linter = new eslint_1.Linter();
+for (const [name, rule] of Object.entries(plugin.rules)) {
+    linter.defineRule(exports.PREFIX + name, rule);
+}
+linter.defineParser('ts', tsParser);
+function lintBlock(ruleName, filename, code, options) {
+    const config = {
+        parser: 'ts',
+        parserOptions: {
+            ecmaVersion: 2022,
+            sourceType: 'module',
+            ecmaFeatures: { jsx: filename.endsWith('.tsx') },
+        },
+        rules: {
+            [exports.PREFIX + ruleName]: options
+                ? ['error', options]
+                : 'error',
+        },
+    };
+    let messages;
+    try {
+        messages = linter.verify(code, config, { filename });
+    }
+    catch (error) {
+        // A rule needing type information throws without `parserOptions.project`,
+        // which the RuleTester cannot supply; such rules are out of scope here.
+        return {
+            reports: [],
+            reportLines: [],
+            skipped: true,
+            reason: `the rule threw: ${error.message}`,
+        };
+    }
+    // A block that does not parse never ran the rule. That is not a pass — see
+    // UNCHECKABLE_BLOCKS.
+    const fatal = messages.find((m) => m.fatal);
+    if (fatal) {
+        return {
+            reports: [],
+            reportLines: [],
+            skipped: true,
+            reason: `parse failure at block line ${fatal.line}: ${fatal.message}`,
+        };
+    }
+    const mine = messages.filter((m) => m.ruleId === exports.PREFIX + ruleName);
+    return {
+        reports: mine.map((m) => `line ${m.line}: ${m.message}`),
+        reportLines: mine.map((m) => m.line),
+        skipped: false,
+    };
+}
+exports.lintBlock = lintBlock;
+//# sourceMappingURL=docsFixtures.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.20.152",
+  "version": "1.20.154",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,56 @@
 [
+  {
+    "version": "1.20.154",
+    "date": "2026-08-15T03:47:51.570Z",
+    "rules": [
+      {
+        "name": "parallelize-async-operations",
+        "changeType": "fix",
+        "issues": [
+          2017
+        ],
+        "summary": "order callback-deferred instance mutations against later reads (closes #2017)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.153",
+    "date": "2026-08-14T20:21:23.691Z",
+    "rules": [
+      {
+        "name": "enforce-boolean-naming-prefixes",
+        "changeType": "fix",
+        "issues": [
+          2016
+        ],
+        "summary": "decline when the use site contradicts the callee's name (closes #2016)"
+      },
+      {
+        "name": "enforce-object-literal-as-const",
+        "changeType": "fix",
+        "issues": [
+          2015
+        ],
+        "summary": "keep an unannotated returned array unfrozen (closes #2015)"
+      },
+      {
+        "name": "global-const-style",
+        "changeType": "fix",
+        "issues": [
+          2013
+        ],
+        "summary": "decline the as const when the binding is mutated later (closes #2013)"
+      },
+      {
+        "name": "no-explicit-return-type",
+        "changeType": "fix",
+        "issues": [
+          2014
+        ],
+        "summary": "keep a decorator factory's annotation (closes #2014)"
+      }
+    ]
+  },
   {
     "version": "1.20.152",
     "date": "2026-08-14T10:28:08.765Z",