@blumintinc/eslint-plugin-blumint 1.20.109 → 1.20.111

package/README.md

@@ -104,7 +104,7 @@ full closed loop is documented in agora's `.claude/skills/eslint-autonomy/SKILL.
 | [enforce-exported-function-types](docs/rules/enforce-exported-function-types.md)                             | Enforce exporting types for function props and return values                                                                                                                                                                                                                                                                                                                                     | ✅  |    | 🔧 |    |    |
 | [enforce-f-extension-for-entry-points](docs/rules/enforce-f-extension-for-entry-points.md)                   | Enforce .f.ts extension for entry points                                                                                                                                                                                                                                                                                                                                                         | ✅  |    |    |    |    |
 | [enforce-fieldpath-syntax-in-docsetter](docs/rules/enforce-fieldpath-syntax-in-docsetter.md)                 | Enforce the use of Firestore FieldPath syntax when passing documentData into DocSetter. Instead of using nested object syntax, developers should use dot notation for deeply nested fields.                                                                                                                                                                                                      | ✅  |    | 🔧 |    |    |
-| [enforce-firestore-doc-ref-generic](docs/rules/enforce-firestore-doc-ref-generic.md)                         | Enforce generic argument for Firestore DocumentReference, CollectionReference and CollectionGroup                                                                                                                                                                                                                                                                                                | ✅  |    |    |    | 💭 |
+| [enforce-firestore-doc-ref-generic](docs/rules/enforce-firestore-doc-ref-generic.md)                         | Enforce generic argument for Firestore DocumentReference, CollectionReference and CollectionGroup                                                                                                                                                                                                                                                                                                | ✅  |    |    |    |    |
 | [enforce-firestore-facade](docs/rules/enforce-firestore-facade.md)                                           | Enforce usage of Firestore facades instead of direct Firestore methods                                                                                                                                                                                                                                                                                                                           | ✅  |    |    |    |    |
 | [enforce-firestore-path-utils](docs/rules/enforce-firestore-path-utils.md)                                   | Enforce usage of utility functions for Firestore paths to ensure type safety, maintainability, and consistent path construction. This prevents errors from manual string concatenation and makes path changes easier to manage.                                                                                                                                                                  | ✅  |    |    |    |    |
 | [enforce-firestore-rules-get-access](docs/rules/enforce-firestore-rules-get-access.md)                       | Ensure Firestore security rules use .get() with a default value instead of direct field access comparisons (e.g., resource.data.fieldX.fieldY != null).                                                                                                                                                                                                                                          | ✅  |    | 🔧 |    |    |

package/lib/index.js

@@ -223,7 +223,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.20.109',
+        version: '1.20.111',
     },
     parseOptions: {
         ecmaVersion: 2020,
@@ -339,6 +339,11 @@ module.exports = {
                 '@blumintinc/blumint/prefer-destructuring-no-class': 'error',
                 '@blumintinc/blumint/enforce-render-hits-memoization': 'error',
                 '@blumintinc/blumint/enforce-transform-memoization': 'error',
+                // Off because it demands the opposite spelling from the enabled
+                // prefer-fragment-shorthand, and because the consumer's codebase
+                // still violates it while its sync reverts on any report. The measured
+                // impact and the criterion that graduates it to 'error' are recorded in
+                // docs/rules/prefer-fragment-component.md.
                 '@blumintinc/blumint/prefer-fragment-component': 'off',
                 '@blumintinc/blumint/react-usememo-should-be-component': 'error',
                 '@blumintinc/blumint/no-unnecessary-verb-suffix': 'error',

package/lib/rules/enforce-firestore-doc-ref-generic.js

@@ -21,7 +21,12 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
         docs: {
             description: 'Enforce generic argument for Firestore DocumentReference, CollectionReference and CollectionGroup',
             recommended: 'error',
-            requiresTypeChecking: true,
+            // Every check here is syntactic: generics are read off the AST and named
+            // generics are resolved against declarations in the same file. Declaring
+            // type information would be a false promise twice over — it tells
+            // consumers they need `parserOptions.project`, and it exempts this rule
+            // from guards that skip rules a program-less `Linter` cannot exercise.
+            requiresTypeChecking: false,
         },
         schema: [],
         messages: {

package/lib/rules/enforce-global-constants.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceGlobalConstants = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const shebang_1 = require("../utils/shebang");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
 exports.enforceGlobalConstants = (0, createRule_1.createRule)({
     name: 'enforce-global-constants',
@@ -269,7 +270,10 @@ exports.enforceGlobalConstants = (0, createRule_1.createRule)({
                         }
                         else {
                             const body = program.body;
-                            let insertPos = 0;
+                            // A shebang has to stay at character 0 or the file stops parsing
+                            // (TS18026), so it bounds the insertion the same way the
+                            // directive prologue below does.
+                            let insertPos = (0, shebang_1.afterShebang)(text);
                             let afterDirectiveIdx = -1;
                             for (let i = 0; i < body.length; i++) {
                                 const stmt = body[i];

package/lib/rules/enforce-memoize-async.js

@@ -83,6 +83,29 @@ function isInsideMockFactory(node) {
     }
     return false;
 }
+/**
+ * The class a method belongs to, reached through its `ClassBody`.
+ */
+function enclosingClass(node) {
+    const body = node.parent;
+    return body?.type === utils_1.AST_NODE_TYPES.ClassBody ? body.parent : undefined;
+}
+/**
+ * Whether the method's own class is written as an expression — `const C = class
+ * {}`, a class in argument position, a class assigned to a property — rather
+ * than as a declaration.
+ *
+ * Under `experimentalDecorators`, TypeScript accepts a member decorator only
+ * inside a class DECLARATION: the same `@Memoize()` that compiles inside `class
+ * C {}`, `export class C {}` or `export default class {}` is `TS1206:
+ * Decorators are not valid here.` inside a class expression. An emitted
+ * decorator there breaks the consumer's build, so the report stands without a
+ * fix and the author restructures deliberately — hoisting the class to a
+ * declaration makes the decorator legal.
+ */
+function isInsideClassExpression(node) {
+    return enclosingClass(node)?.type === utils_1.AST_NODE_TYPES.ClassExpression;
+}
 /**
  * Whether a declared return type annotation promises no value: `void` or
  * `Promise<void>`.
@@ -351,6 +374,14 @@ exports.enforceMemoizeAsync = (0, createRule_1.createRule)({
                         if (isInsideMockFactory(node)) {
                             return null;
                         }
+                        // A decorator is legal only on a member of a class declaration, so
+                        // decorating a class expression's method emits code the consumer's
+                        // compiler rejects outright (TS1206). Declining ahead of the import
+                        // carrier claim below leaves the import to a violation that does
+                        // fix.
+                        if (isInsideClassExpression(node)) {
+                            return null;
+                        }
                         const fixes = [];
                         const sourceCode = context.sourceCode;
                         // Determine which identifier to use for the decorator

package/lib/rules/logical-top-to-bottom-grouping.js

@@ -4,6 +4,7 @@ exports.logicalTopToBottomGrouping = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
 const createRule_1 = require("../utils/createRule");
+const shebang_1 = require("../utils/shebang");
 const TYPE_EXPRESSION_WRAPPERS = new Set([
     utils_1.AST_NODE_TYPES.TSAsExpression,
     utils_1.AST_NODE_TYPES.TSTypeAssertion,
@@ -730,7 +731,12 @@ function findEarliestSafeIndex(body, startIndex, dependencies, { allowHooks, sto
  * comments directly above it reads as its preamble.
  */
 function getLeadingComments(statement, sourceCode) {
-    const comments = sourceCode.getCommentsBefore(statement);
+    // A shebang belongs to the file, not to the statement below it. Left in the
+    // preamble, relocating the first statement carries `#!` off character 0 and
+    // the output stops parsing.
+    const comments = sourceCode
+        .getCommentsBefore(statement)
+        .filter((comment) => !(0, shebang_1.isShebangComment)(sourceCode, comment));
     const ownLine = comments.findIndex((comment) => {
         const previous = sourceCode.getTokenBefore(comment, {
             includeComments: true,

package/lib/rules/no-redundant-usecallback-wrapper.js

@@ -3,8 +3,77 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.noRedundantUseCallbackWrapper = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 const LATEST_CALLBACK_MODULE = 'use-latest-callback';
 const LATEST_CALLBACK_HOOK = 'useLatestCallback';
+const MEMO_HOOK = 'useMemo';
+/**
+ * Type-level wrappers carry no runtime value, so a callback that leaves a
+ * memoizing call through a cast is the same callback. Reading through them keeps
+ * the proof from depending on whether the author spelled an annotation.
+ */
+const TYPE_ONLY_WRAPPERS = new Set([
+    utils_1.AST_NODE_TYPES.TSAsExpression,
+    utils_1.AST_NODE_TYPES.TSSatisfiesExpression,
+    utils_1.AST_NODE_TYPES.TSNonNullExpression,
+    utils_1.AST_NODE_TYPES.TSTypeAssertion,
+    utils_1.AST_NODE_TYPES.TSInstantiationExpression,
+]);
+function unwrapValueExpression(node) {
+    let current = node;
+    while (current.type === utils_1.AST_NODE_TYPES.ChainExpression ||
+        TYPE_ONLY_WRAPPERS.has(current.type)) {
+        current = current.expression;
+    }
+    return current;
+}
+/**
+ * The bare name a callee resolves to, collapsing the namespaced spelling so
+ * `React.useCallback` and `useCallback` answer alike.
+ */
+function calleeNameOf(callee) {
+    const unwrapped = unwrapValueExpression(callee);
+    if (unwrapped.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return unwrapped.name;
+    }
+    if (unwrapped.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !unwrapped.computed &&
+        unwrapped.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return unwrapped.property.name;
+    }
+    return null;
+}
+function isFunctionLiteral(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression);
+}
+/**
+ * Whether a `useMemo` factory demonstrably yields a function.
+ *
+ * `useMemo` memoizes any value, so its result is a memoized *callback* only when
+ * the factory produces one. Only a factory that hands back a function literal
+ * proves that in-source; a factory returning a call result, a conditional or a
+ * value assembled across several statements might yield anything, and this rule
+ * prefers a false negative to guessing.
+ */
+function producesFunction(factory) {
+    if (!factory || !isFunctionLiteral(factory)) {
+        return false;
+    }
+    const fn = factory;
+    if (fn.body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+        return isFunctionLiteral(unwrapValueExpression(fn.body));
+    }
+    const statements = fn.body.body;
+    if (statements.length !== 1) {
+        return false;
+    }
+    const [only] = statements;
+    if (only.type !== utils_1.AST_NODE_TYPES.ReturnStatement || !only.argument) {
+        return false;
+    }
+    return isFunctionLiteral(unwrapValueExpression(only.argument));
+}
 function isHookLikeName(name) {
     return name.startsWith('use');
 }
@@ -142,6 +211,63 @@ exports.noRedundantUseCallbackWrapper = (0, createRule_1.createRule)({
             }
             return null;
         };
+        /**
+         * Whether the binding this identifier resolves to holds a callback whose
+         * memoization is visible in this very file.
+         *
+         * `memoizedHookNames` exists for callbacks whose stability only the consumer
+         * knows about. A `const` initialized from `useCallback`, `useLatestCallback`
+         * or a `useMemo` that yields a function needs no such knowledge: the
+         * memoizing call sits in the same source, so wrapping its result is provably
+         * redundant and the rule reports it under the default options — without
+         * which the rule can report nothing at all in a config that does not set
+         * `memoizedHookNames`.
+         *
+         * The binding is resolved through scope analysis rather than matched by
+         * name, because a name set cannot tell the memoized `inner` of one component
+         * from the `inner` prop of the next, and would report the prop — the wrapper
+         * that is the only thing making it stable.
+         */
+        const isLocallyMemoizedCallback = (identifier, wrapperCall) => {
+            const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, identifier), identifier.name);
+            if (!variable || variable.defs.length !== 1) {
+                return false;
+            }
+            const declarator = variable.defs[0].node;
+            if (declarator.type !== utils_1.AST_NODE_TYPES.VariableDeclarator ||
+                declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                !declarator.init) {
+                return false;
+            }
+            // A rebindable declaration breaks the proof: the value read at the wrapper
+            // need not be the one the memoizing call produced.
+            const declaration = declarator.parent;
+            if (declaration?.type !== utils_1.AST_NODE_TYPES.VariableDeclaration ||
+                declaration.kind !== 'const') {
+                return false;
+            }
+            // A wrapper sitting inside the initializer it reads is self-referential,
+            // and collapsing it would emit `const x = x`.
+            if (wrapperCall.range[0] >= declarator.range[0] &&
+                wrapperCall.range[1] <= declarator.range[1]) {
+                return false;
+            }
+            const init = unwrapValueExpression(declarator.init);
+            if (init.type !== utils_1.AST_NODE_TYPES.CallExpression) {
+                return false;
+            }
+            const initName = calleeNameOf(init.callee);
+            if (!initName) {
+                return false;
+            }
+            // Every wrapper this rule reports is itself a memoizing call, so the same
+            // set answers both questions: what makes a callback stable, and what
+            // redundantly re-wraps one that already is.
+            if (wrapperNames.has(initName)) {
+                return true;
+            }
+            return initName === MEMO_HOOK && producesFunction(init.arguments[0]);
+        };
         // Track identifiers coming from hook-like calls
         const hookReturnObjects = new Set(); // variables assigned to a hook call result (object or function)
         const hookReturnProps = new Set(); // properties destructured from a hook call result
@@ -214,7 +340,8 @@ exports.noRedundantUseCallbackWrapper = (0, createRule_1.createRule)({
                             unwrappedArg.type === utils_1.AST_NODE_TYPES.MemberExpression)) {
                         if ((unwrappedArg.type === utils_1.AST_NODE_TYPES.Identifier &&
                             (hookReturnProps.has(unwrappedArg.name) ||
-                                hookReturnObjects.has(unwrappedArg.name))) ||
+                                hookReturnObjects.has(unwrappedArg.name) ||
+                                isLocallyMemoizedCallback(unwrappedArg, node))) ||
                             (unwrappedArg.type === utils_1.AST_NODE_TYPES.MemberExpression &&
                                 unwrappedArg.object.type === utils_1.AST_NODE_TYPES.Identifier &&
                                 hookReturnObjects.has(unwrappedArg.object.name))) {
@@ -259,7 +386,8 @@ exports.noRedundantUseCallbackWrapper = (0, createRule_1.createRule)({
                                     isIdentifierOrMemberOn(callee, hookReturnObjects)) ||
                                     (callee &&
                                         callee.type === utils_1.AST_NODE_TYPES.Identifier &&
-                                        hookReturnProps.has(callee.name))) {
+                                        (hookReturnProps.has(callee.name) ||
+                                            isLocallyMemoizedCallback(callee, node)))) {
                                     if (bodyExpr.arguments.length > 0) {
                                         // Passing any arguments: treat as non-redundant (avoid false positives)
                                         return;
@@ -316,7 +444,8 @@ exports.noRedundantUseCallbackWrapper = (0, createRule_1.createRule)({
                                         const callee = unwrapChainExpression(expr.callee);
                                         const isHookProp = callee &&
                                             callee.type === utils_1.AST_NODE_TYPES.Identifier &&
-                                            hookReturnProps.has(callee.name);
+                                            (hookReturnProps.has(callee.name) ||
+                                                isLocallyMemoizedCallback(callee, node));
                                         const isHookObjMember = callee &&
                                             callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
                                             callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&

package/lib/rules/prefer-fragment-component.js

@@ -111,7 +111,11 @@ exports.preferFragmentComponent = (0, createRule_1.createRule)({
         type: 'suggestion',
         docs: {
             description: 'Require the Fragment named import instead of shorthand fragments or React.Fragment to keep fragments explicit and prop-friendly',
-            recommended: 'error',
+            // `RuleMetaDataDocs` admits `false | 'error' | 'strict' | 'warn'` and has
+            // no `'off'` member, so `false` is this field's spelling of the `'off'`
+            // the recommended config ships. See the docs page for why it ships off
+            // and what graduates it to 'error'.
+            recommended: false,
         },
         fixable: 'code',
         schema: [],

package/lib/rules/vertically-group-related-functions.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.verticallyGroupRelatedFunctions = void 0;
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
+const shebang_1 = require("../utils/shebang");
 const DEFAULT_OPTIONS = {
     exportPlacement: 'ignore',
     dependencyDirection: 'callers-first',
@@ -329,10 +330,15 @@ function getStatementRangeWithComments(statement, sourceCode, consumedComments,
     // below would drag an interleaved statement's own end-of-line comment along
     // when the following function is relocated. Only own-line comments count as
     // leading comments.
-    const leadingCommentsOf = (target) => filterComments(sourceCode.getCommentsBefore(target) || []).filter((comment) => {
+    const leadingCommentsOf = (target) => filterComments(sourceCode.getCommentsBefore(target) || [])
+        .filter((comment) => {
         const tokenBefore = sourceCode.getTokenBefore(comment);
         return (!tokenBefore || tokenBefore.loc.end.line !== comment.loc.start.line);
-    });
+    })
+        // A shebang belongs to the file, not to the statement below it. Left in
+        // the span, relocating the first statement carries `#!` off character 0
+        // and the output stops parsing.
+        .filter((comment) => !(0, shebang_1.isShebangComment)(sourceCode, comment));
     const commentsBefore = leadingCommentsOf(statement);
     const nextLeadingComments = nextStatement
         ? new Set(leadingCommentsOf(nextStatement))

package/lib/utils/fixtureCorpus.d.ts

@@ -0,0 +1,147 @@
+import { Linter } from 'eslint';
+import { HarvestResult } from './harvestRuleTesterCases';
+/**
+ * The one harvest a module registry gets.
+ *
+ * A second `harvestRuleTesterCases()` call in the same registry returns ZERO
+ * suites: the suite files are already in the require cache, so requiring them
+ * again re-executes nothing and their `run` calls never fire, while
+ * `filesLoaded` still counts every file. A guard that harvests twice therefore
+ * runs its second corpus over nothing and reports a clean sweep. Every consumer
+ * — including one that wants both the raw suites and the adapted corpus below —
+ * goes through this.
+ */
+export declare function harvestOnce(): HarvestResult;
+/**
+ * Which array a snippet came out of. A fixer must converge, type-check and
+ * resolve its references identically whichever it is, so the bucket is carried
+ * for reporting rather than for filtering — except that an `output` is by
+ * construction an ALREADY-FIXED state, which makes it the cheapest available
+ * probe of "does the fixer fire again on its own result".
+ */
+export type FixtureBucket = 'valid' | 'invalid' | 'output';
+export type FixtureCase = {
+    code: string;
+    /** Only when the case declares one; a guard supplies its own default. */
+    filename?: string;
+    options?: readonly unknown[];
+    parserOptions?: Record<string, unknown>;
+    /** Which shared tester declared it, which fixes the parser. */
+    tester: string;
+    /** Declaring suite file, so a finding is reproducible by hand. */
+    origin: string;
+    bucket: FixtureBucket;
+};
+export type FixtureCorpus = {
+    byRule: Map<string, FixtureCase[]>;
+    /** Suites whose rule object is not in the plugin's map, `file::name`. */
+    suitesDropped: string[];
+    /** Suites skipped for declaring under a non-TypeScript tester. */
+    suitesNonTs: string[];
+    suitesUsed: number;
+    totalCases: number;
+    /** Non-vacuity accounting: a silent drop here would fake a clean sweep. */
+    filesLoaded: number;
+    failures: string[];
+};
+/**
+ * `ruleTesterJson` and `ruleTesterMarkdown` parse a different language, so their
+ * fixtures cannot be linted by the TypeScript parser these guards configure.
+ */
+export declare const TS_TESTERS: Set<string>;
+/**
+ * Rules that ask the checker a question. Under a bare `Linter` they have no
+ * program, so they report nothing and would manufacture a false clean rather
+ * than a finding — a guard therefore has to be able to say so out loud when one
+ * of them contributes no probe, instead of filing it under "no trigger".
+ *
+ * Read from the rule sources rather than `String(rule.create)`, since
+ * `createRule` wraps `create` and stringifying it matches nothing.
+ */
+export declare const typeAwareRuleNames: Set<string>;
+/**
+ * Rule name resolved by OBJECT IDENTITY, never by the display name `run`
+ * received: ~100 of the ~310 suites pass a name that is not a rule name
+ * (`requireMemo`, `prefer-next-dynamic (JSX scenarios)`), and name-keyed
+ * matching silently drops every case they declare. Identity holds because the
+ * suites and `../index` resolve to the same module instance under jest.
+ */
+export declare const ruleNameByIdentity: Map<unknown, string>;
+/**
+ * The filename a case is probed under when it declares none.
+ *
+ * `RuleTester` passes `undefined` in that situation, which ESLint renders as
+ * `<input>` — a name with no extension, under which every path-gated rule is
+ * silent and contributes nothing. A bare `file.ts`/`react.tsx` is the smallest
+ * departure that keeps those rules reachable, and it matches the extension the
+ * fixture's own tester implies.
+ */
+export declare const defaultFilenameFor: (testCase: FixtureCase) => string;
+/**
+ * Second-chance filenames, used ONLY for a rule that produced no probe at all
+ * under the authentic one.
+ *
+ * Probing every case under every one of these is what the text-harvest guards
+ * did, and it is 3.5x the work for zero extra rules covered (measured: 8,433
+ * fix pairs over 81 rules with the fan-out, 2,652 over the same 81 without).
+ * Spending that budget on the pairs a cap would otherwise drop is worth more
+ * than re-probing the same snippet under a path its author never wrote — but a
+ * rule that would otherwise be UNPROBED is the one case where the fan-out buys
+ * something, so it is kept for exactly that.
+ */
+export declare const FALLBACK_FILENAMES: string[];
+/**
+ * The parser options a case is probed under: the harness's own, overridden by
+ * whatever the fixture declared, with `jsx` merged rather than replaced so a
+ * case that declares an unrelated `ecmaFeatures` does not silently turn JSX
+ * parsing off for itself.
+ */
+export declare const parserOptionsFor: (testCase: FixtureCase) => {
+    ecmaFeatures: {
+        jsx: boolean;
+    };
+    ecmaVersion: number;
+    sourceType: string;
+};
+/**
+ * Rules that offer suggestions. `--fix` never applies one, so a guard driving
+ * `verifyAndFix` (or reading a fixture's `output`) probes the fix channel
+ * exclusively and every transform these rules emit stays unexamined (#1733).
+ */
+export declare const suggestionRuleNames: string[];
+export type SuggestionEdit = {
+    /** Stable identity within one lint of one source, `<report>:<suggestion>`. */
+    slot: string;
+    /** Which rule offered it, so a multi-rule lint still names the culprit. */
+    ruleId: string;
+    messageId: string;
+    desc: string;
+    /** The source with THIS suggestion applied, and nothing else. */
+    output: string;
+};
+/**
+ * Every state a user can reach by accepting ONE suggestion from `messages`.
+ *
+ * Three semantics are load-bearing, and each is a way the probe would otherwise
+ * judge a suggestion against a state nobody can produce:
+ *   - ALONE. Each edit lands on the untouched source. Accepting two suggestions
+ *     from one report is not reachable — the first rewrite invalidates the
+ *     second's ranges — and neither is feeding the result back through a fix
+ *     loop, which is what `verifyAndFix` would do.
+ *   - ONE STEP. The output is a single accepted suggestion, not a fixed point.
+ *     A suggestion is an offer, so the contract is progress, not closure.
+ *   - A `fix()` returning `null` is a DECLINE, not a defect. ESLint drops those
+ *     silently before the message is built, so they never arrive here; an edit
+ *     that changes nothing is discarded for the same reason.
+ */
+export declare function suggestionEditsOf(code: string, messages: readonly Linter.LintMessage[], 
+/** Restricts to one rule; omitted, every reporting rule contributes. */
+ruleId?: string): SuggestionEdit[];
+/** A case's options must reach the FIX pass, or the finding is a fabrication. */
+export declare const severityWithOptions: (testCase: FixtureCase) => "error" | unknown[];
+/**
+ * Harvested once per process. Loading ~270 suites is the dominant cost of every
+ * consumer, and a second call would pay it again for a corpus that cannot have
+ * changed.
+ */
+export declare function harvestFixtureCorpus(): FixtureCorpus;

package/lib/utils/fixtureCorpus.js

@@ -0,0 +1,311 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.harvestFixtureCorpus = exports.severityWithOptions = exports.suggestionEditsOf = exports.suggestionRuleNames = exports.parserOptionsFor = exports.FALLBACK_FILENAMES = exports.defaultFilenameFor = exports.ruleNameByIdentity = exports.typeAwareRuleNames = exports.TS_TESTERS = exports.harvestOnce = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const harvestRuleTesterCases_1 = require("./harvestRuleTesterCases");
+/**
+ * The fixture corpus every fixer guard probes, keyed by RULE NAME.
+ *
+ * The guards used to build this by text-parsing `src/tests/<rule>.test.ts` and
+ * keeping the static string literals, which loses two things at once. A case
+ * assembled by interpolation is invisible — `no-usememo-for-pass-by-value`
+ * prepends a shared `typedPrelude` to all 64 of its cases and yielded exactly
+ * ONE snippet — and a snippet that does survive arrives stripped of the
+ * `filename` and `options` it was written for, so it is probed under a
+ * configuration its author never wrote (#1732).
+ *
+ * `harvestRuleTesterCases` loads each suite with `run` shadowed, so the real
+ * case objects are captured: interpolated code, options, filename and
+ * parserOptions together. This module is the adapter between that raw capture
+ * and what a `Linter`-based guard needs.
+ */
+/* eslint-disable @typescript-eslint/no-var-requires */
+const plugin = require('../index');
+/* eslint-enable @typescript-eslint/no-var-requires */
+const RULES_DIR = path_1.default.join(__dirname, '..', 'rules');
+let rawHarvest = null;
+/**
+ * The one harvest a module registry gets.
+ *
+ * A second `harvestRuleTesterCases()` call in the same registry returns ZERO
+ * suites: the suite files are already in the require cache, so requiring them
+ * again re-executes nothing and their `run` calls never fire, while
+ * `filesLoaded` still counts every file. A guard that harvests twice therefore
+ * runs its second corpus over nothing and reports a clean sweep. Every consumer
+ * — including one that wants both the raw suites and the adapted corpus below —
+ * goes through this.
+ */
+function harvestOnce() {
+    if (!rawHarvest)
+        rawHarvest = (0, harvestRuleTesterCases_1.harvestRuleTesterCases)();
+    return rawHarvest;
+}
+exports.harvestOnce = harvestOnce;
+/**
+ * `ruleTesterJson` and `ruleTesterMarkdown` parse a different language, so their
+ * fixtures cannot be linted by the TypeScript parser these guards configure.
+ */
+exports.TS_TESTERS = new Set(['ruleTesterTs', 'ruleTesterJsx']);
+/**
+ * Parser options that build a TypeScript PROGRAM. A guard driving a bare
+ * `Linter` has none, and honouring these would make it spend seconds per case
+ * constructing one from the repo's own tsconfig — or throw, since a fixture's
+ * relative `project` is resolved against whatever cwd the runner happens to
+ * have. Stripped rather than dropped: the snippet still exercises every
+ * syntactic path of the rule.
+ */
+const PROGRAM_OPTIONS = new Set([
+    'project',
+    'projectService',
+    'programs',
+    'tsconfigRootDir',
+    'EXPERIMENTAL_useProjectService',
+]);
+const withoutProgramOptions = (raw) => {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (PROGRAM_OPTIONS.has(key))
+            continue;
+        out[key] = value;
+    }
+    return Object.keys(out).length ? out : undefined;
+};
+/**
+ * Rules that ask the checker a question. Under a bare `Linter` they have no
+ * program, so they report nothing and would manufacture a false clean rather
+ * than a finding — a guard therefore has to be able to say so out loud when one
+ * of them contributes no probe, instead of filing it under "no trigger".
+ *
+ * Read from the rule sources rather than `String(rule.create)`, since
+ * `createRule` wraps `create` and stringifying it matches nothing.
+ */
+exports.typeAwareRuleNames = new Set(fs_1.default
+    .readdirSync(RULES_DIR)
+    .filter((file) => file.endsWith('.ts'))
+    .filter((file) => /getParserServices|getTypeChecker/.test(fs_1.default.readFileSync(path_1.default.join(RULES_DIR, file), 'utf8')))
+    .map((file) => path_1.default.basename(file, '.ts')));
+/**
+ * Rule name resolved by OBJECT IDENTITY, never by the display name `run`
+ * received: ~100 of the ~310 suites pass a name that is not a rule name
+ * (`requireMemo`, `prefer-next-dynamic (JSX scenarios)`), and name-keyed
+ * matching silently drops every case they declare. Identity holds because the
+ * suites and `../index` resolve to the same module instance under jest.
+ */
+exports.ruleNameByIdentity = new Map(Object.entries(plugin.rules).map(([name, rule]) => [rule, name]));
+/**
+ * The filename a case is probed under when it declares none.
+ *
+ * `RuleTester` passes `undefined` in that situation, which ESLint renders as
+ * `<input>` — a name with no extension, under which every path-gated rule is
+ * silent and contributes nothing. A bare `file.ts`/`react.tsx` is the smallest
+ * departure that keeps those rules reachable, and it matches the extension the
+ * fixture's own tester implies.
+ */
+const defaultFilenameFor = (testCase) => testCase.filename ??
+    (testCase.tester === 'ruleTesterJsx' ? 'react.tsx' : 'file.ts');
+exports.defaultFilenameFor = defaultFilenameFor;
+/**
+ * Second-chance filenames, used ONLY for a rule that produced no probe at all
+ * under the authentic one.
+ *
+ * Probing every case under every one of these is what the text-harvest guards
+ * did, and it is 3.5x the work for zero extra rules covered (measured: 8,433
+ * fix pairs over 81 rules with the fan-out, 2,652 over the same 81 without).
+ * Spending that budget on the pairs a cap would otherwise drop is worth more
+ * than re-probing the same snippet under a path its author never wrote — but a
+ * rule that would otherwise be UNPROBED is the one case where the fan-out buys
+ * something, so it is kept for exactly that.
+ */
+exports.FALLBACK_FILENAMES = [
+    '/repo/src/components/Widget.tsx',
+    '/repo/src/util/helper.ts',
+    '/repo/src/util/helper.test.ts',
+    '/repo/src/__tests__/helper.test.ts',
+    '/repo/functions/src/util/helper.test.ts',
+    '/repo/functions/src/callable/handler.ts',
+    '/repo/src/pages/index.tsx',
+];
+/**
+ * The parser options a case is probed under: the harness's own, overridden by
+ * whatever the fixture declared, with `jsx` merged rather than replaced so a
+ * case that declares an unrelated `ecmaFeatures` does not silently turn JSX
+ * parsing off for itself.
+ */
+const parserOptionsFor = (testCase) => {
+    const declared = testCase.parserOptions || {};
+    const features = (declared.ecmaFeatures || {});
+    return {
+        ecmaVersion: 2022,
+        sourceType: 'module',
+        ...declared,
+        ecmaFeatures: { jsx: true, ...features },
+    };
+};
+exports.parserOptionsFor = parserOptionsFor;
+/**
+ * Rules that offer suggestions. `--fix` never applies one, so a guard driving
+ * `verifyAndFix` (or reading a fixture's `output`) probes the fix channel
+ * exclusively and every transform these rules emit stays unexamined (#1733).
+ */
+exports.suggestionRuleNames = Object.entries(plugin.rules)
+    .filter(([, rule]) => rule?.meta?.hasSuggestions)
+    .map(([name]) => name)
+    .sort();
+const applyEdit = (text, fix) => text.slice(0, fix.range[0]) + fix.text + text.slice(fix.range[1]);
+/**
+ * Every state a user can reach by accepting ONE suggestion from `messages`.
+ *
+ * Three semantics are load-bearing, and each is a way the probe would otherwise
+ * judge a suggestion against a state nobody can produce:
+ *   - ALONE. Each edit lands on the untouched source. Accepting two suggestions
+ *     from one report is not reachable — the first rewrite invalidates the
+ *     second's ranges — and neither is feeding the result back through a fix
+ *     loop, which is what `verifyAndFix` would do.
+ *   - ONE STEP. The output is a single accepted suggestion, not a fixed point.
+ *     A suggestion is an offer, so the contract is progress, not closure.
+ *   - A `fix()` returning `null` is a DECLINE, not a defect. ESLint drops those
+ *     silently before the message is built, so they never arrive here; an edit
+ *     that changes nothing is discarded for the same reason.
+ */
+function suggestionEditsOf(code, messages, 
+/** Restricts to one rule; omitted, every reporting rule contributes. */
+ruleId) {
+    const edits = [];
+    messages.forEach((message, messageIndex) => {
+        if (ruleId && message.ruleId !== ruleId)
+            return;
+        (message.suggestions || []).forEach((suggestion, suggestionIndex) => {
+            if (!suggestion.fix)
+                return;
+            const output = applyEdit(code, suggestion.fix);
+            if (output === code)
+                return;
+            edits.push({
+                slot: `${messageIndex}:${suggestionIndex}`,
+                ruleId: message.ruleId || '',
+                messageId: message.messageId || message.message,
+                desc: suggestion.desc,
+                output,
+            });
+        });
+    });
+    return edits;
+}
+exports.suggestionEditsOf = suggestionEditsOf;
+/** A case's options must reach the FIX pass, or the finding is a fabrication. */
+const severityWithOptions = (testCase) => testCase.options && testCase.options.length
+    ? ['error', ...testCase.options]
+    : 'error';
+exports.severityWithOptions = severityWithOptions;
+/** Already-fixed states a case declares: its `output`, and each suggestion's. */
+const outputsOf = (testCase) => {
+    const outputs = [];
+    if (typeof testCase.output === 'string')
+        outputs.push(testCase.output);
+    if (!Array.isArray(testCase.errors))
+        return outputs;
+    for (const error of testCase.errors) {
+        const suggestions = error?.suggestions;
+        if (!Array.isArray(suggestions))
+            continue;
+        for (const suggestion of suggestions) {
+            const output = suggestion?.output;
+            if (typeof output === 'string')
+                outputs.push(output);
+        }
+    }
+    return outputs;
+};
+let cached = null;
+/**
+ * Harvested once per process. Loading ~270 suites is the dominant cost of every
+ * consumer, and a second call would pay it again for a corpus that cannot have
+ * changed.
+ */
+function harvestFixtureCorpus() {
+    if (cached)
+        return cached;
+    const harvested = harvestOnce();
+    const byRule = new Map();
+    const suitesDropped = [];
+    const suitesNonTs = [];
+    let suitesUsed = 0;
+    let totalCases = 0;
+    for (const suite of harvested.suites) {
+        const name = exports.ruleNameByIdentity.get(suite.rule);
+        if (!name) {
+            suitesDropped.push(`${suite.file}::${suite.name}`);
+            continue;
+        }
+        if (!exports.TS_TESTERS.has(suite.tester)) {
+            suitesNonTs.push(`${suite.file}::${suite.name}`);
+            continue;
+        }
+        suitesUsed++;
+        const cases = byRule.get(name) || [];
+        /**
+         * Deduped on the whole configuration, not on the code: the same snippet
+         * probed under different options is a different probe, and several suites
+         * declare exactly that pair to pin an option's effect.
+         */
+        const keyOf = (testCase) => JSON.stringify([
+            testCase.code,
+            testCase.options,
+            testCase.filename,
+            testCase.parserOptions,
+        ]);
+        const seen = new Set(cases.map(keyOf));
+        const push = (code, raw, bucket, parserOptions) => {
+            const testCase = {
+                code,
+                filename: typeof raw.filename === 'string' ? raw.filename : undefined,
+                options: Array.isArray(raw.options)
+                    ? raw.options
+                    : undefined,
+                parserOptions,
+                tester: suite.tester,
+                origin: suite.file,
+                bucket,
+            };
+            const key = keyOf(testCase);
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            cases.push(testCase);
+            totalCases++;
+        };
+        const collect = (raw, bucket) => {
+            const declared = (typeof raw === 'string' ? { code: raw } : raw);
+            if (!declared || typeof declared.code !== 'string')
+                return;
+            const parserOptions = withoutProgramOptions(declared.parserOptions);
+            push(declared.code, declared, bucket, parserOptions);
+            for (const output of outputsOf(declared)) {
+                push(output, declared, 'output', parserOptions);
+            }
+        };
+        for (const raw of suite.valid)
+            collect(raw, 'valid');
+        for (const raw of suite.invalid)
+            collect(raw, 'invalid');
+        byRule.set(name, cases);
+    }
+    cached = {
+        byRule,
+        suitesDropped,
+        suitesNonTs,
+        suitesUsed,
+        totalCases,
+        filesLoaded: harvested.filesLoaded,
+        failures: harvested.failures,
+    };
+    return cached;
+}
+exports.harvestFixtureCorpus = harvestFixtureCorpus;
+//# sourceMappingURL=fixtureCorpus.js.map

package/lib/utils/shebang.d.ts

@@ -0,0 +1,19 @@
+import { TSESLint, TSESTree } from '@typescript-eslint/utils';
+/**
+ * A shebang is only a shebang at character 0. One byte in front of it and the
+ * file stops parsing outright (`TS18026: '#!' can only be used at the start of
+ * a file`) and stops being executable.
+ *
+ * ESLint hands it to rules as an ordinary leading comment of the first
+ * statement, which is what makes it easy to lose: a fixer that relocates a
+ * statement together with its leading comments carries the shebang into the
+ * middle of the file, and one that splices at offset 0 pushes it off line 1.
+ * `importInsertion` already encodes this for the rules that add an import;
+ * these are the same rule for the ones that reorder or hoist.
+ */
+export declare function isShebangComment(sourceCode: Pick<TSESLint.SourceCode, 'text'>, comment: TSESTree.Comment): boolean;
+/**
+ * The first offset at which text may be spliced without displacing a shebang.
+ * Zero for the overwhelmingly common file that has none.
+ */
+export declare function afterShebang(text: string): number;

package/lib/utils/shebang.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.afterShebang = exports.isShebangComment = void 0;
+/**
+ * A shebang is only a shebang at character 0. One byte in front of it and the
+ * file stops parsing outright (`TS18026: '#!' can only be used at the start of
+ * a file`) and stops being executable.
+ *
+ * ESLint hands it to rules as an ordinary leading comment of the first
+ * statement, which is what makes it easy to lose: a fixer that relocates a
+ * statement together with its leading comments carries the shebang into the
+ * middle of the file, and one that splices at offset 0 pushes it off line 1.
+ * `importInsertion` already encodes this for the rules that add an import;
+ * these are the same rule for the ones that reorder or hoist.
+ */
+function isShebangComment(sourceCode, comment) {
+    return comment.range[0] === 0 && sourceCode.text.startsWith('#!');
+}
+exports.isShebangComment = isShebangComment;
+/**
+ * The first offset at which text may be spliced without displacing a shebang.
+ * Zero for the overwhelmingly common file that has none.
+ */
+function afterShebang(text) {
+    if (!text.startsWith('#!')) {
+        return 0;
+    }
+    const lineEnd = text.indexOf('\n');
+    return lineEnd === -1 ? text.length : lineEnd + 1;
+}
+exports.afterShebang = afterShebang;
+//# sourceMappingURL=shebang.js.map

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,72 @@
 [
+  {
+    "version": "1.20.111",
+    "date": "2026-08-05T13:37:20.101Z",
+    "rules": [
+      {
+        "name": "enforce-global-constants",
+        "changeType": "fix",
+        "issues": [
+          1739
+        ],
+        "summary": "hoist below a shebang, not above it (closes #1739)"
+      },
+      {
+        "name": "logical-top-to-bottom-grouping",
+        "changeType": "fix",
+        "issues": [
+          1738
+        ],
+        "summary": "keep a shebang at character 0 when reordering (closes #1738)"
+      },
+      {
+        "name": "vertically-group-related-functions",
+        "changeType": "fix",
+        "issues": [
+          1737
+        ],
+        "summary": "keep a shebang at character 0 when reordering (closes #1737)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.110",
+    "date": "2026-08-05T11:59:59.800Z",
+    "rules": [
+      {
+        "name": "enforce-firestore-doc-ref-generic",
+        "changeType": "fix",
+        "issues": [
+          1730
+        ],
+        "summary": "drop the unearned requiresTypeChecking declaration (closes #1730)"
+      },
+      {
+        "name": "enforce-memoize-async",
+        "changeType": "fix",
+        "issues": [
+          1735
+        ],
+        "summary": "decline to decorate a method of a class expression (closes #1735)"
+      },
+      {
+        "name": "no-redundant-usecallback-wrapper",
+        "changeType": "fix",
+        "issues": [
+          1729
+        ],
+        "summary": "report provably memoized wrappers under default options (closes #1729)"
+      },
+      {
+        "name": "prefer-fragment-component",
+        "changeType": "fix",
+        "issues": [
+          1736
+        ],
+        "summary": "declare the disabled severity it actually ships (closes #1736)"
+      }
+    ]
+  },
   {
     "version": "1.20.109",
     "date": "2026-08-05T07:42:30.150Z",