@blumintinc/eslint-plugin-blumint 1.20.45 → 1.20.46

package/lib/index.js

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

package/lib/rules/enforce-snapshot-state-narrowing.js

@@ -61,7 +61,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                     guardFunctions: {
                         type: 'array',
                         items: { type: 'string' },
-                        description: 'Canonical type guard function names',
+                        description: 'Type guard function names; the first is the one suggestions call and import',
                     },
                     excludeFiles: {
                         type: 'array',
@@ -70,23 +70,32 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                     },
                     guardImportSource: {
                         type: 'string',
-                        description: 'Module specifier the suggestion imports isSnapshotReady from',
+                        description: 'Module specifier the suggestion imports the guard from',
                     },
                 },
                 additionalProperties: false,
             },
         ],
         messages: {
-            noFalsyCheck: "Do not use boolean coercion on FirestoreSnapshotState<T>. All string states ('idle', 'loading', 'not-found') are truthy, so '{{expression}}' does not behave as intended. Use isSnapshotReady(state) to narrow to T, or compare explicitly (e.g., state === 'loading').",
-            noRawTypeof: "Do not use '{{expression}}' to narrow FirestoreSnapshotState<T> to data. Use isSnapshotReady(state) instead to maintain the abstraction boundary.",
+            // `guard` is the configured canonical guard name, so a consumer who
+            // renames it is not told to call a function their config says does not
+            // exist. Every report and suggestion supplies it.
+            noFalsyCheck: "Do not use boolean coercion on FirestoreSnapshotState<T>. All string states ('idle', 'loading', 'not-found') are truthy, so '{{expression}}' does not behave as intended. Use {{guard}}(state) to narrow to T, or compare explicitly (e.g., state === 'loading').",
+            noRawTypeof: "Do not use '{{expression}}' to narrow FirestoreSnapshotState<T> to data. Use {{guard}}(state) instead to maintain the abstraction boundary.",
         },
     },
     defaultOptions: [{}],
     create(context, [options]) {
         const snapshotHooks = new Set(options?.snapshotHooks ?? DEFAULT_SNAPSHOT_HOOKS);
-        // guardFunctions is accepted in config for documentation and future extensibility
-        // but detection is purely syntactic (by hook source), not by guard function name.
-        void (options?.guardFunctions ?? DEFAULT_GUARD_FUNCTIONS);
+        /**
+         * The name every suggestion calls, resolves in scope, and imports.
+         * `guardFunctions` may list several recognized guards; the first usable one
+         * is canonical. A list that names nothing callable — empty, or holding only
+         * blanks — falls back to the default rather than leaving the suggestion to
+         * emit `undefined(state)` or `(state)`.
+         */
+        const guardName = options?.guardFunctions?.find((name) => name.trim().length > 0) ??
+            DEFAULT_GUARD_FUNCTIONS[0];
         const excludeFiles = options?.excludeFiles ?? [
             'src/types/FirestoreSnapshotState.ts',
         ];
@@ -163,7 +172,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
          * import, or would collide with an unrelated binding of the same name.
          */
         function resolveGuardBinding(scope) {
-            const variable = utils_1.ASTUtils.findVariable(scope, GUARD_NAME);
+            const variable = utils_1.ASTUtils.findVariable(scope, guardName);
             if (!variable) {
                 return 'missing';
             }
@@ -214,14 +223,14 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
             if (reusable) {
                 const namedSpecifiers = reusable.specifiers.filter(isValueImportSpecifier);
                 const lastSpecifier = namedSpecifiers[namedSpecifiers.length - 1];
-                return fixer.insertTextAfter(lastSpecifier, `, ${GUARD_NAME}`);
+                return fixer.insertTextAfter(lastSpecifier, `, ${guardName}`);
             }
             // A namespace or type-only import of the module cannot take a named value
             // specifier, but its path is proof of how this file reaches the module.
             const source = guardDeclarations.length
                 ? String(guardDeclarations[0].source.value)
                 : guardImportSource;
-            const importText = `import { ${GUARD_NAME} } from '${source}';\n`;
+            const importText = `import { ${guardName} } from '${source}';\n`;
             const [firstImport] = declarations;
             if (firstImport) {
                 return fixer.insertTextBefore(firstImport, importText);
@@ -233,7 +242,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
         }
         /**
          * Builds the single suggestion shared by every report: swap the flagged
-         * expression for its guard-based equivalent and bring `isSnapshotReady` into
+         * expression for its guard-based equivalent and bring the guard into
          * scope. Declines (no suggestion) when the name is already taken by
          * something that is not the guard.
          */
@@ -241,7 +250,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
             return [
                 {
                     messageId,
-                    data: { expression: replacement },
+                    data: { expression: replacement, guard: guardName },
                     fix(fixer) {
                         const binding = resolveGuardBinding(scope);
                         if (binding === 'conflict') {
@@ -306,8 +315,8 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                         context.report({
                             node,
                             messageId: 'noRawTypeof',
-                            data: { expression: getText(node) },
-                            suggest: guardSuggestion('noRawTypeof', node, `${GUARD_NAME}(${operand.name})`, context.getScope()),
+                            data: { expression: getText(node), guard: guardName },
+                            suggest: guardSuggestion('noRawTypeof', node, `${guardName}(${operand.name})`, context.getScope()),
                         });
                     }
                     // typeof state === 'string' — allowed (narrows to non-data states)
@@ -327,7 +336,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
             context.report({
                 node,
                 messageId: 'noFalsyCheck',
-                data: { expression },
+                data: { expression, guard: guardName },
                 suggest: guardSuggestion('noFalsyCheck', fixNode, replacement, context.getScope()),
             });
         }
@@ -372,7 +381,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                 // stay negated or the suggestion would reverse the control flow.
                 if (argument.type === utils_1.AST_NODE_TYPES.Identifier &&
                     isSnapshotVar(argument)) {
-                    reportFalsyCheck(node, `!${argument.name}`, `!${GUARD_NAME}(${argument.name})`);
+                    reportFalsyCheck(node, `!${argument.name}`, `!${guardName}(${argument.name})`);
                 }
                 // !!state — the argument is another `!` whose argument is the snapshot var.
                 // The double negation is a truthiness coercion, so the guard is positive.
@@ -381,7 +390,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                     argument.argument.type === utils_1.AST_NODE_TYPES.Identifier &&
                     isSnapshotVar(argument.argument)) {
                     const varName = argument.argument.name;
-                    reportFalsyCheck(node, `!!${varName}`, `${GUARD_NAME}(${varName})`);
+                    reportFalsyCheck(node, `!!${varName}`, `${guardName}(${varName})`);
                 }
             },
             // IfStatement: if (state) { ... } or if (!state) { ... }
@@ -389,14 +398,14 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
             IfStatement(node) {
                 const test = node.test;
                 if (test.type === utils_1.AST_NODE_TYPES.Identifier && isSnapshotVar(test)) {
-                    reportFalsyCheck(test, test.name, `${GUARD_NAME}(${test.name})`);
+                    reportFalsyCheck(test, test.name, `${guardName}(${test.name})`);
                 }
             },
             // ConditionalExpression: state ? a : b
             ConditionalExpression(node) {
                 const test = node.test;
                 if (test.type === utils_1.AST_NODE_TYPES.Identifier && isSnapshotVar(test)) {
-                    reportFalsyCheck(test, test.name, `${GUARD_NAME}(${test.name})`);
+                    reportFalsyCheck(test, test.name, `${guardName}(${test.name})`);
                 }
             },
             // LogicalExpression: state && expr, state || expr
@@ -408,13 +417,13 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                     if (node.operator === '&&') {
                         // `state && expr` guards expr, so swapping the operand for the
                         // guard keeps both the polarity and the narrowing of `state`.
-                        reportFalsyCheck(left, left.name, `${GUARD_NAME}(${left.name})`);
+                        reportFalsyCheck(left, left.name, `${guardName}(${left.name})`);
                         return;
                     }
                     // `state || fallback` evaluates to the state itself when it is
                     // usable, so a bare operand swap would yield `true` instead of the
                     // data. Only the conditional form preserves that value.
-                    const guarded = `${GUARD_NAME}(${left.name}) ? ${left.name} : ${getText(node.right)}`;
+                    const guarded = `${guardName}(${left.name}) ? ${left.name} : ${getText(node.right)}`;
                     reportFalsyCheck(left, left.name, needsParentheses(node) ? `(${guarded})` : guarded, node);
                 }
             },
@@ -432,7 +441,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                     node.arguments[0].type === utils_1.AST_NODE_TYPES.Identifier &&
                     isSnapshotVar(node.arguments[0])) {
                     const varName = node.arguments[0].name;
-                    reportFalsyCheck(node, `Boolean(${varName})`, `${GUARD_NAME}(${varName})`);
+                    reportFalsyCheck(node, `Boolean(${varName})`, `${guardName}(${varName})`);
                 }
             },
         };

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "1.20.46",
+    "date": "2026-07-31T07:08:55.415Z",
+    "rules": [
+      {
+        "name": "enforce-snapshot-state-narrowing",
+        "changeType": "fix",
+        "issues": [
+          1505
+        ],
+        "summary": "make the guardFunctions option actually select the emitted guard name (closes #1505)"
+      }
+    ]
+  },
   {
     "version": "1.20.45",
     "date": "2026-07-31T06:37:56.216Z",