@blumintinc/eslint-plugin-blumint 1.20.153 → 1.20.155

package/lib/index.js

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

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

@@ -569,32 +569,164 @@ function isOverloadedFunction(node) {
     }
     return false;
 }
-function isOverloadedTsDeclareFunction(node) {
+/**
+ * The statement list that directly holds `node`, looking through `export`.
+ *
+ * Overload signatures and their implementation are siblings of one statement
+ * list — an overload set cannot span containers — so this is the only list worth
+ * reading. Walking outward instead would let a same-named function in an
+ * enclosing scope answer for one it cannot overload.
+ */
+function siblingStatementsOf(node) {
+    const parent = node.parent;
+    if (!parent)
+        return undefined;
+    const container = parent.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+        parent.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration
+        ? parent.parent
+        : parent;
+    return container ? (0, lexicalScope_1.statementsOf)(container) : undefined;
+}
+const EMPTY_OVERLOAD_SET = { signatures: 0, implementations: 0 };
+/**
+ * How many declaration-only signatures and how many implementations the
+ * container holding `node` declares under `node`'s own name, `node` included.
+ *
+ * Every statement container is read, not just `Program` and `TSModuleBlock`: a
+ * function body, a bare block and a `switch` case each bind a name just as
+ * effectively, so reading only the top level makes the DEPTH of an overload set
+ * decide whether it exists (the same defect as #1771).
+ */
+function overloadSetOf(node) {
     const functionName = node.id?.name;
     if (!functionName)
+        return EMPTY_OVERLOAD_SET;
+    const statements = siblingStatementsOf(node);
+    if (!statements)
+        return EMPTY_OVERLOAD_SET;
+    let signatures = 0;
+    let implementations = 0;
+    for (const statement of statements) {
+        // `export function f(...)` is the same declaration one AST node deeper, and
+        // an overload set may export some of its members and not others.
+        const declaration = (0, lexicalScope_1.declarationOf)(statement);
+        if (declaration.type !== utils_1.AST_NODE_TYPES.TSDeclareFunction &&
+            declaration.type !== utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+            continue;
+        }
+        if (declaration.id?.name !== functionName)
+            continue;
+        if (declaration.type === utils_1.AST_NODE_TYPES.TSDeclareFunction ||
+            !declaration.body) {
+            signatures += 1;
+        }
+        else {
+            implementations += 1;
+        }
+    }
+    return { signatures, implementations };
+}
+/**
+ * True when `node` is the IMPLEMENTATION of an overload set — a function with a
+ * body whose container also declares the same name as one or more
+ * declaration-only signatures.
+ *
+ * Its annotation is not a restatement of what the body returns: TypeScript
+ * checks each overload signature against the IMPLEMENTATION SIGNATURE, so the
+ * annotation is what the overloads are measured against. Inference yields the
+ * body's own type, which need not accept them — stripping `: void | string`
+ * from `function get(param?: string): void | string {}` infers `void` and makes
+ * the `: string` overload above it TS2394 (#2019).
+ *
+ * This carve-out ignores `allowOverloadedFunctions`. That option governs the
+ * declaration-only signatures, whose annotations are mandatory but carry no
+ * fixer, so reporting them costs nothing but a message. Here the report ships a
+ * fix that does not compile, which no option may ask for.
+ */
+function isOverloadImplementation(node) {
+    if (!node.body)
         return false;
-    let container = node.parent;
-    while (container) {
-        if (container.type === utils_1.AST_NODE_TYPES.Program ||
-            container.type === utils_1.AST_NODE_TYPES.TSModuleBlock) {
-            const declarations = container.body
-                .map((statement) => {
-                if (statement.type === utils_1.AST_NODE_TYPES.TSDeclareFunction) {
-                    return statement;
-                }
-                if (statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
-                    statement.declaration?.type === utils_1.AST_NODE_TYPES.TSDeclareFunction) {
-                    return statement.declaration;
-                }
-                return undefined;
-            })
-                .filter((value) => Boolean(value?.id?.name))
-                .filter((decl) => decl.id.name === functionName);
-            return declarations.length > 1;
+    return overloadSetOf(node).signatures > 0;
+}
+/**
+ * True when `node` is a declaration-only signature that belongs to an overload
+ * set: another signature declares the same name, or an implementation below it
+ * does. A lone `declare function f(): number;` overloads nothing, so it stays
+ * reportable.
+ */
+function isOverloadedTsDeclareFunction(node) {
+    const { signatures, implementations } = overloadSetOf(node);
+    return signatures > 1 || implementations > 0;
+}
+/**
+ * A method's identity inside its class body. Overloads agree on all three
+ * components; `static f` and `f` merely spell the same name, and a computed key
+ * names nothing resolvable, so it yields nothing. The separator keeps a private
+ * `#log` from colliding with a string key `'#log'`.
+ */
+function methodIdentityOf(node) {
+    if (node.computed)
+        return undefined;
+    if (node.key.type === utils_1.AST_NODE_TYPES.PrivateIdentifier) {
+        return `${node.static}\u0000private\u0000${node.key.name}`;
+    }
+    if (node.key.type !== utils_1.AST_NODE_TYPES.Identifier &&
+        node.key.type !== utils_1.AST_NODE_TYPES.Literal) {
+        return undefined;
+    }
+    const name = getNameFromIdentifierOrLiteral(node.key);
+    return name === undefined
+        ? undefined
+        : `${node.static}\u0000public\u0000${name}`;
+}
+/**
+ * The overload set a class method belongs to, counted over the members of its
+ * own class body. A member without a body is an overload signature
+ * (`TSEmptyBodyFunctionExpression`); the one member with a body is the
+ * implementation.
+ */
+function classOverloadSetOf(node) {
+    const identity = methodIdentityOf(node);
+    const classBody = node.parent;
+    if (!identity || classBody?.type !== utils_1.AST_NODE_TYPES.ClassBody) {
+        return EMPTY_OVERLOAD_SET;
+    }
+    let signatures = 0;
+    let implementations = 0;
+    for (const member of classBody.body) {
+        if (member.type !== utils_1.AST_NODE_TYPES.MethodDefinition)
+            continue;
+        if (methodIdentityOf(member) !== identity)
+            continue;
+        if (member.value.body) {
+            implementations += 1;
+        }
+        else {
+            signatures += 1;
         }
-        container = container.parent;
     }
-    return false;
+    return { signatures, implementations };
+}
+/**
+ * True when the method is the implementation of an overloaded class method, for
+ * the reason {@link isOverloadImplementation} gives — a class overload set is
+ * checked exactly as a function one is (#2019).
+ */
+function isOverloadImplementationMethod(node) {
+    if (!node.value.body)
+        return false;
+    return classOverloadSetOf(node).signatures > 0;
+}
+/**
+ * True when the method is a declaration-only overload signature. A body-less
+ * method is legal only as part of an overload set, so it is exempt whenever the
+ * set holds anything else at all.
+ */
+function isOverloadedClassMethodSignature(node) {
+    if (node.value.body)
+        return false;
+    const { signatures, implementations } = classOverloadSetOf(node);
+    return signatures > 1 || implementations > 0;
 }
 function isInterfaceOrAbstractMethodSignature(node) {
     if (node.type === utils_1.AST_NODE_TYPES.TSAbstractMethodDefinition)
@@ -1233,6 +1365,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     isReadonlyWideningReturnType(returnType) ||
                     isAllowedVoidReturnType(returnType) ||
                     isDecoratorFactory(node, returnType) ||
+                    isOverloadImplementation(node) ||
                     (mergedOptions.allowRecursiveFunctions &&
                         isRecursiveFunction(node)) ||
                     isReturnTypeRequiredByRecursion(node)) {
@@ -1292,6 +1425,9 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     isReadonlyWideningReturnType(returnType) ||
                     isAllowedVoidReturnType(returnType) ||
                     isDecoratorFactory(node, returnType) ||
+                    isOverloadImplementationMethod(node) ||
+                    (mergedOptions.allowOverloadedFunctions &&
+                        isOverloadedClassMethodSignature(node)) ||
                     (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/rules/prefer-union-from-const-array.js

@@ -34,6 +34,46 @@ function isStringLiteralType(member) {
     const { literal } = member;
     return (literal.type === utils_1.AST_NODE_TYPES.Literal && typeof literal.value === 'string');
 }
+/**
+ * A declaration file is ambient in its entirety, so a declaration in one is
+ * subject to the ambient restriction even without an explicit `declare`.
+ */
+const DECLARATION_FILE = /\.d\.[cm]?ts$/i;
+/**
+ * An ambient context accepts only a string, numeric or literal-enum `const`
+ * initializer (TS1254), so the derived `as const` array cannot be emitted there
+ * at all — `as const` or not, an array literal is rejected. Declining is the
+ * remedy rather than a different rewrite, because no legal rewrite exists in
+ * that position: the rule asks for importable runtime values and an ambient
+ * declaration is precisely the promise that no runtime value is emitted.
+ *
+ * `declare` on the OUTERMOST module declaration makes every level nested below
+ * it ambient too, so the whole ancestor chain is walked rather than just the
+ * enclosing block. A module named by a string literal (`module 'x' {}`) and a
+ * `global {}` augmentation are ambient by construction, with or without the
+ * modifier.
+ */
+function isInAmbientContext(node, filename) {
+    if (DECLARATION_FILE.test(filename)) {
+        return true;
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration &&
+        node.declare === true) {
+        return true;
+    }
+    let current = node.parent;
+    while (current) {
+        if (current.type === utils_1.AST_NODE_TYPES.TSModuleDeclaration) {
+            if (current.declare === true ||
+                current.global === true ||
+                current.id.type === utils_1.AST_NODE_TYPES.Literal) {
+                return true;
+            }
+        }
+        current = current.parent;
+    }
+    return false;
+}
 /**
  * Walk the scope chain upward collecting declared variable names. Used to skip
  * the autofix (report-only) when the derived `{TYPE}_VALUES` name is already
@@ -154,6 +194,9 @@ exports.preferUnionFromConstArray = (0, createRule_1.createRule)({
                 if (!members.every(isStringLiteralType)) {
                     return;
                 }
+                if (isInAmbientContext(node, context.getFilename())) {
+                    return;
+                }
                 const typeName = node.id.name;
                 const constName = `${toUpperSnake(typeName)}_VALUES`;
                 // The type alias is exported when wrapped in `export type X = ...`

package/lib/rules/require-image-optimized.js

@@ -62,6 +62,49 @@ const isInsideComponentMock = (node, componentModule) => {
     }
     return false;
 };
+/**
+ * Name a declaration binds, for the forms a component is declared under:
+ * `const ImageOptimized = ...` (including `memo(...)`/`forwardRef(...)` around
+ * the body), `function ImageOptimized()` and `class ImageOptimized`. Anything
+ * else — an object property, a parameter — binds no declaration name the
+ * wrapper can be identified by, and treating it as one would exempt a mock
+ * factory keyed by the component name whatever module it stands in for.
+ */
+const declaredNameOf = (node) => {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.VariableDeclarator:
+            return node.id.type === utils_1.AST_NODE_TYPES.Identifier ? node.id.name : null;
+        case utils_1.AST_NODE_TYPES.FunctionDeclaration:
+        case utils_1.AST_NODE_TYPES.FunctionExpression:
+        case utils_1.AST_NODE_TYPES.ClassDeclaration:
+        case utils_1.AST_NODE_TYPES.ClassExpression:
+            return node.id ? node.id.name : null;
+        default:
+            return null;
+    }
+};
+/**
+ * Names each local binding is exported under, so a wrapper declared as
+ * `Picture` and shipped as `export { Picture as ImageOptimized }` is still
+ * recognized as the component's own definition. A specifier carrying a `from`
+ * clause re-exports another module's binding and declares nothing here.
+ */
+const exportedNamesByLocal = (program) => {
+    const exported = new Map();
+    for (const statement of program.body) {
+        if (statement.type !== utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+            statement.source ||
+            statement.exportKind === 'type') {
+            continue;
+        }
+        for (const specifier of statement.specifiers) {
+            const names = exported.get(specifier.local.name) ?? new Set();
+            names.add(specifier.exported.name);
+            exported.set(specifier.local.name, names);
+        }
+    }
+    return exported;
+};
 /**
  * A type-only specifier binds no value: it renders nothing, so it neither
  * bypasses the optimization pipeline nor can back a fix. The modifier lives
@@ -219,6 +262,40 @@ module.exports = (0, createRule_1.createRule)({
          * rule exists to centralize, not a violation of it.
          */
         const isComponentImplementationFile = moduleNameOf(context.getFilename()) === componentModule;
+        /**
+         * The wrapper is identified by the name the fixer would emit and by its
+         * module's name, which a component module's export shares by convention.
+         * Matching is exact so a distinct component whose name merely starts with
+         * it (`ImageOptimizedGallery`) stays reportable.
+         */
+        const isComponentName = (name) => name === COMPONENT_NAME || name === componentModule;
+        const exportedNames = exportedNamesByLocal(sourceCode.ast);
+        const definesComponent = (name) => {
+            if (isComponentName(name)) {
+                return true;
+            }
+            const aliases = exportedNames.get(name);
+            return !!aliases && [...aliases].some(isComponentName);
+        };
+        /**
+         * Whether the element sits inside the declaration of the component the fix
+         * points at. That declaration renders the image primitive by definition, so
+         * swapping it for the component makes the wrapper render itself: unbounded
+         * recursion, and a type error too, since the wrapper forwards only the
+         * props it destructured. The whole ancestry is walked because a helper
+         * nested inside the declaration is part of that implementation as well.
+         */
+        const isInsideComponentDefinition = (node) => {
+            let current = node.parent;
+            while (current) {
+                const declared = declaredNameOf(current);
+                if (declared && definesComponent(declared)) {
+                    return true;
+                }
+                current = current.parent;
+            }
+            return false;
+        };
         return {
             // Handle JSX img elements
             JSXElement(node) {
@@ -228,7 +305,8 @@ module.exports = (0, createRule_1.createRule)({
                     return;
                 }
                 if (isComponentImplementationFile ||
-                    isInsideComponentMock(node, componentModule)) {
+                    isInsideComponentMock(node, componentModule) ||
+                    isInsideComponentDefinition(node)) {
                     return;
                 }
                 const scope = ASTHelpers_1.ASTHelpers.getScope(context, node);

package/lib/utils/ASTHelpers.d.ts

@@ -85,6 +85,12 @@ export declare class ASTHelpers {
      * expression reads some other object.
      */
     private static classMemberNameReferencedBy;
+    /**
+     * The ECMA private names a class body declares, spelled as the graph spells
+     * them. A private name is scoped to the body that declares it, so this set
+     * is what an enclosing class must not mistake for its own members.
+     */
+    private static privateNamesDeclaredBy;
     private static walkChildNodes;
     static isNode(value: unknown): value is TSESTree.Node;
     static hasReturnStatement(node: TSESTree.Node): boolean;

package/lib/utils/ASTHelpers.js

@@ -423,7 +423,16 @@ class ASTHelpers {
             case 'ClassExpression': {
                 // Traversal continues so `<ClassName>.<member>` statics stay visible,
                 // but `this` no longer denotes the graphed instance.
-                this.walkChildNodes(node, className, false, dependencies);
+                const nested = [];
+                this.walkChildNodes(node, className, false, nested);
+                // A nested class body SHADOWS the private names it declares: its `#q`
+                // is a member of that class, distinct from an enclosing class's `#q`,
+                // so reads of it constrain the nested layout rather than this one.
+                // Private names the nested class does not declare still resolve
+                // outward, so only the declared ones are dropped. Filtering as the
+                // recursion unwinds composes across any depth of nesting.
+                const shadowed = this.privateNamesDeclaredBy(node);
+                dependencies.push(...nested.filter((name) => !shadowed.has(name)));
                 return;
             }
             case 'MemberExpression': {
@@ -447,6 +456,18 @@ class ASTHelpers {
      */
     static classMemberNameReferencedBy(node, className, isThisTheInstance) {
         const { object, property, computed } = node;
+        // A `#name` resolves LEXICALLY: it is a syntax error unless a class body
+        // enclosing the reference declares it, so the receiver it is read through
+        // cannot change which member it names. `other.#helper` and `this.#helper`
+        // reach the same member, which is why this branch precedes the receiver
+        // test that the dotted spellings need. Requiring `this`/<ClassName> here
+        // dropped the read a static initializer makes through another value of
+        // the same class, and with it the constraint that keeps the field's
+        // declaration above its reader (#2022). The `#` is part of the name so
+        // `#helper` and `helper` stay distinct members.
+        if (!computed && property?.type === 'PrivateIdentifier') {
+            return `#${property.name}`;
+        }
         const readsInstance = object?.type === 'ThisExpression' && isThisTheInstance;
         // An anonymous class expression has an empty name, which no identifier
         // can match.
@@ -457,12 +478,6 @@ class ASTHelpers {
         if (!computed && property?.type === 'Identifier') {
             return property.name;
         }
-        // `this.#helper` names a member as precisely as `this.helper` does, and it
-        // is the only spelling available for an ECMA private member. The `#` is
-        // part of the name so `#helper` and `helper` stay distinct members.
-        if (!computed && property?.type === 'PrivateIdentifier') {
-            return `#${property.name}`;
-        }
         // `this['helper']` names the member as precisely as `this.helper` does,
         // whereas `this[key]` names one only at runtime.
         if (computed &&
@@ -472,6 +487,25 @@ class ASTHelpers {
         }
         return null;
     }
+    /**
+     * The ECMA private names a class body declares, spelled as the graph spells
+     * them. A private name is scoped to the body that declares it, so this set
+     * is what an enclosing class must not mistake for its own members.
+     */
+    static privateNamesDeclaredBy(node) {
+        const names = new Set();
+        const members = node.body?.body;
+        if (!Array.isArray(members)) {
+            return names;
+        }
+        for (const member of members) {
+            const key = member?.key;
+            if (key?.type === 'PrivateIdentifier') {
+                names.add(`#${key.name}`);
+            }
+        }
+        return names;
+    }
     static walkChildNodes(node, className, isThisTheInstance, dependencies) {
         for (const [key, value] of Object.entries(node)) {
             if (ASTHelpers.NON_TRAVERSABLE_NODE_KEYS.has(key)) {

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.153",
+  "version": "1.20.155",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,56 @@
 [
+  {
+    "version": "1.20.155",
+    "date": "2026-08-15T14:21:55.491Z",
+    "rules": [
+      {
+        "name": "class-methods-read-top-to-bottom",
+        "changeType": "fix",
+        "issues": [
+          2022
+        ],
+        "summary": "pin a # field by every read of it, not just this.#x (closes #2022)"
+      },
+      {
+        "name": "no-explicit-return-type",
+        "changeType": "fix",
+        "issues": [
+          2019
+        ],
+        "summary": "spare the implementation signature of an overload set (closes #2019)"
+      },
+      {
+        "name": "prefer-union-from-const-array",
+        "changeType": "fix",
+        "issues": [
+          2020
+        ],
+        "summary": "decline in an ambient context, where no const array is legal (closes #2020)"
+      },
+      {
+        "name": "require-image-optimized",
+        "changeType": "fix",
+        "issues": [
+          2021
+        ],
+        "summary": "exempt the img inside ImageOptimized's own definition (closes #2021)"
+      }
+    ]
+  },
+  {
+    "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",