@blumintinc/eslint-plugin-blumint 1.20.96 → 1.20.97

package/lib/index.js

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

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

@@ -113,12 +113,25 @@ exports.enforceBooleanNamingPrefixes = (0, createRule_1.createRule)({
                     return true;
                 }
                 const nextChar = normalizedName.charAt(p.length);
-                // For SCREAMING_SNAKE_CASE or similar all-uppercase names,
-                // we require an underscore boundary.
+                // For SCREAMING_SNAKE_CASE or similar all-uppercase names the prefix must
+                // end at a separator, since case can no longer mark the word boundary
+                // (ISVALID stays unprefixed). Digits fused onto the prefix belong to that
+                // first segment rather than to the next word — ARE2_VALID is the
+                // UPPER_SNAKE spelling of are2Valid, which the camelCase branch below
+                // accepts — so a trailing digit run is consumed before the separator is
+                // examined, and the same separators the camelCase branch honours (`_`,
+                // `$`, end of name) close the segment. Only a digit run directly after
+                // the prefix qualifies: ARENA2_MAP still fails because a letter follows
+                // the prefix, and H2AS_ITEMS never reaches here because the prefix does
+                // not match the segment's start.
                 const isAllUppercase = normalizedName === normalizedName.toUpperCase() &&
                     /[a-z]/i.test(normalizedName);
                 if (isAllUppercase) {
-                    return nextChar === '_';
+                    const afterPrefix = normalizedName
+                        .slice(p.length)
+                        .replace(/^\d+/, '');
+                    const boundaryChar = afterPrefix.charAt(0);
+                    return (boundaryChar === '' || boundaryChar === '_' || boundaryChar === '$');
                 }
                 // For camelCase, the next char must be uppercase, a digit, or $
                 return (nextChar === '_' ||
@@ -710,6 +723,28 @@ exports.enforceBooleanNamingPrefixes = (0, createRule_1.createRule)({
                 expression.name === 'undefined') {
                 return 'nonBoolean';
             }
+            // A returned binding is governed by this very rule: a boolean variable,
+            // parameter or function must carry an approved prefix. So an unprefixed
+            // `id` — or the result of calling an unprefixed `compute(x)` — is not a
+            // boolean under the regime the rule enforces, and the callee's own name
+            // must not override that. Deciding here keeps the exemption in the body
+            // rather than in a return annotation, which `no-explicit-return-type`
+            // deletes (issue #1691).
+            //
+            // Member accesses (`source.flag`, `source.read()`) are deliberately
+            // excluded: property signatures are only enforced under
+            // `enforceForPropertySignatures` and third-party method names are outside
+            // this rule's reach, so an unprefixed member may legitimately yield a
+            // boolean and the callee's name keeps its say.
+            if (expression.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return identifierIsBoolean(expression) ? 'boolean' : 'nonBoolean';
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.CallExpression &&
+                expression.callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return callExpressionLooksBoolean(expression) === 'boolean'
+                    ? 'boolean'
+                    : 'nonBoolean';
+            }
             if (expression.type === utils_1.AST_NODE_TYPES.UnaryExpression) {
                 if (expression.operator === '!' || expression.operator === 'delete') {
                     return 'boolean';

package/lib/rules/enforce-positive-naming.js

@@ -973,6 +973,78 @@ function isDefinitelyNonBooleanExpression(node) {
             return false;
     }
 }
+// Operators whose result is always a boolean, regardless of operand types.
+const BOOLEAN_BINARY_OPERATORS = new Set([
+    '==',
+    '!=',
+    '===',
+    '!==',
+    '<',
+    '<=',
+    '>',
+    '>=',
+    'in',
+    'instanceof',
+]);
+/**
+ * Detects an expression that is definitively a boolean — a boolean literal, a
+ * negation, a comparison, or a branch/`Boolean()` call built from those. Opaque
+ * expressions (calls, identifiers, member accesses) yield no verdict here: they
+ * are the shapes a validator's body takes once its return annotation is gone,
+ * and assuming boolean for them is what produced the false positive in #1692.
+ */
+function isDefinitelyBooleanExpression(node) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.Literal:
+            return typeof node.value === 'boolean';
+        case utils_1.AST_NODE_TYPES.UnaryExpression:
+            return node.operator === '!' || node.operator === 'delete';
+        case utils_1.AST_NODE_TYPES.BinaryExpression:
+            return BOOLEAN_BINARY_OPERATORS.has(node.operator);
+        case utils_1.AST_NODE_TYPES.LogicalExpression:
+            return (isDefinitelyBooleanExpression(node.left) &&
+                isDefinitelyBooleanExpression(node.right));
+        case utils_1.AST_NODE_TYPES.ConditionalExpression:
+            return (isDefinitelyBooleanExpression(node.consequent) &&
+                isDefinitelyBooleanExpression(node.alternate));
+        case utils_1.AST_NODE_TYPES.CallExpression:
+            // `Boolean(x)` is the one call whose result is boolean by construction.
+            return (node.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                node.callee.name === 'Boolean');
+        case utils_1.AST_NODE_TYPES.TSAsExpression:
+        case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
+            // `x as boolean` asserts booleanness; `x as const` and other assertions
+            // say nothing, so the asserted expression decides.
+            return (isBooleanOnlyType(node.typeAnnotation) ||
+                isDefinitelyBooleanExpression(node.expression));
+        case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+            return isDefinitelyBooleanExpression(node.expression);
+        default:
+            return false;
+    }
+}
+function classifyExpression(node) {
+    // A definitively non-boolean shape wins over a boolean one: a validator's
+    // `return 'Must not be blank'` proves the function is not a predicate even
+    // though its success path returns `true`.
+    if (isDefinitelyNonBooleanExpression(node))
+        return 'nonBoolean';
+    if (isDefinitelyBooleanExpression(node))
+        return 'boolean';
+    return 'indeterminate';
+}
+/**
+ * Combines the verdicts of a body's returns under the same precedence:
+ * non-boolean beats boolean, and boolean beats no verdict at all. An empty list
+ * (a body with no returns) is `indeterminate`.
+ */
+function combineReturnKinds(kinds) {
+    if (kinds.includes('nonBoolean'))
+        return 'nonBoolean';
+    if (kinds.includes('boolean'))
+        return 'boolean';
+    return 'indeterminate';
+}
 /**
  * Yields the immediate AST-node children of `node`, skipping the `parent`
  * back-reference so traversal only walks downward.
@@ -995,10 +1067,12 @@ function childNodesOf(node) {
     return children;
 }
 /**
- * Whether any `return` statement belonging to `fn`'s own body (not a nested
- * function's) yields a definitively non-boolean value.
+ * Classifies the `return` statements belonging to `fn`'s own body (not a nested
+ * function's). A bare `return;` carries no verdict, so it neither exempts the
+ * function nor keeps a sibling boolean return from deciding.
  */
-function blockReturnsNonBoolean(block) {
+function classifyBlockReturns(block) {
+    const kinds = [];
     const stack = [block];
     while (stack.length > 0) {
         const current = stack.pop();
@@ -1009,41 +1083,54 @@ function blockReturnsNonBoolean(block) {
                 current.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression)) {
             continue;
         }
-        if (current.type === utils_1.AST_NODE_TYPES.ReturnStatement &&
-            current.argument &&
-            isDefinitelyNonBooleanExpression(current.argument)) {
-            return true;
+        if (current.type === utils_1.AST_NODE_TYPES.ReturnStatement && current.argument) {
+            kinds.push(classifyExpression(current.argument));
         }
         for (const child of childNodesOf(current)) {
             stack.push(child);
         }
     }
-    return false;
+    return combineReturnKinds(kinds);
 }
 /**
- * Whether a function backing an `is`/`has`-prefixed name actually returns a
- * non-boolean value — e.g. a validator predicate returning `string | true`. An
+ * The booleanness of a function backing an `is`/`has`-prefixed name. An
  * explicit return-type annotation is authoritative; otherwise the body's own
- * `return` statements (or the concise-arrow expression) are inspected.
+ * `return` statements (or the concise-arrow expression) decide.
  */
-function functionReturnsNonBoolean(fn) {
+function classifyFunctionReturn(fn) {
     if (fn.returnType) {
-        return !isBooleanOnlyType(fn.returnType.typeAnnotation);
+        return isBooleanOnlyType(fn.returnType.typeAnnotation)
+            ? 'boolean'
+            : 'nonBoolean';
     }
     if (fn.body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
-        return isDefinitelyNonBooleanExpression(fn.body);
+        return classifyExpression(fn.body);
     }
-    return blockReturnsNonBoolean(fn.body);
+    return classifyBlockReturns(fn.body);
+}
+/**
+ * Whether a function backing an `is`/`has`-prefixed name must be exempt from
+ * boolean negative-naming. Only a function proven to return a boolean is
+ * flagged: a validator predicate returning `string | true` is exempt, and so is
+ * one whose returns are syntactically opaque (`=> validate(value)`). That
+ * matters because `no-explicit-return-type` deletes the very annotation that
+ * spells the validator's non-boolean return, leaving nothing but the name to go
+ * on — and guessing "boolean" from the name alone reports a rename that inverts
+ * the predicate's meaning (#1692). Preferring a false negative here is the
+ * repository's stated trade-off.
+ */
+function isExemptFromBooleanNaming(fn) {
+    return classifyFunctionReturn(fn) !== 'boolean';
 }
 /**
- * When a declarator/property value is a function, whether that function is a
- * non-boolean predicate that must be exempt from boolean negative-naming.
+ * When a declarator/property value is a function, whether that function is
+ * exempt from boolean negative-naming.
  */
-function isNonBooleanFunctionValue(node) {
+function isExemptFunctionValue(node) {
     return (!!node &&
         (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
             node.type === utils_1.AST_NODE_TYPES.FunctionExpression) &&
-        functionReturnsNonBoolean(node));
+        isExemptFromBooleanNaming(node));
 }
 exports.enforcePositiveNaming = (0, createRule_1.createRule)({
     name: 'enforce-positive-naming',
@@ -1280,7 +1367,7 @@ exports.enforcePositiveNaming = (0, createRule_1.createRule)({
             // with `is`/`has` but is not a boolean, so its domain-correct negation
             // ("isNotBlank") must not be flagged. The name heuristic alone cannot
             // tell them apart; the initializer's return shape can.
-            if (isNonBooleanFunctionValue(node.init))
+            if (isExemptFunctionValue(node.init))
                 return;
             const variableName = node.id.name;
             const { isNegative, alternatives } = hasBooleanNegativeNaming(variableName);
@@ -1323,8 +1410,9 @@ exports.enforcePositiveNaming = (0, createRule_1.createRule)({
             if (!isBooleanLike(node.id || node))
                 return;
             // Skip validator predicates that return a non-boolean value (e.g.
-            // `string | true`), whose negation is the domain-correct term.
-            if (functionReturnsNonBoolean(node))
+            // `string | true`), whose negation is the domain-correct term, and any
+            // function whose returns give no syntactic verdict.
+            if (isExemptFromBooleanNaming(node))
                 return;
             const { isNegative, alternatives } = hasBooleanNegativeNaming(functionName);
             if (isNegative) {
@@ -1348,7 +1436,7 @@ exports.enforcePositiveNaming = (0, createRule_1.createRule)({
             if (!isBooleanLike(node.key))
                 return;
             // Skip validator predicates returning a non-boolean value.
-            if (isNonBooleanFunctionValue(node.value))
+            if (isExemptFunctionValue(node.value))
                 return;
             const methodName = node.key.name;
             const { isNegative, alternatives } = hasBooleanNegativeNaming(methodName);
@@ -1373,7 +1461,7 @@ exports.enforcePositiveNaming = (0, createRule_1.createRule)({
             if (!isBooleanLike(node.key))
                 return;
             // Skip validator predicates returning a non-boolean value.
-            if (isNonBooleanFunctionValue(node.value))
+            if (isExemptFunctionValue(node.value))
                 return;
             const propertyName = node.key.name;
             const { isNegative, alternatives } = hasBooleanNegativeNaming(propertyName);

package/lib/utils/harvestRuleTesterCases.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Collects every `RuleTester` case the suite declares WITHOUT executing any of
+ * them, by shadowing `run` on the shared tester instances and then loading each
+ * suite for its declarations alone.
+ *
+ * A guard that wants to exercise fixtures rather than documented snippets has no
+ * other way in. `src/tests/*.test.ts` call `RuleTester.run` at module scope, so
+ * importing one normally re-executes it — measured at 2350 tests, 2 minutes and
+ * 48 cross-file side-effect failures, which is why
+ * `recommended-config-fix-closure.test.ts` reads docs fenced blocks instead.
+ * Shadowing `run` before the load turns each of those calls into a declaration
+ * capture, so the cases are collected at the cost of loading the module and
+ * nothing more.
+ *
+ * The fixtures are worth reaching precisely because they are not the docs: a
+ * rule's `valid` list is written to sit on its carve-out boundaries, which is
+ * where a sibling fixer destroys an exemption. Every finding of that class
+ * (#1595-#1599, #1603, #1677-#1682) came from this corpus; the docs corpus
+ * caught none of them.
+ */
+/** A single `ruleTester.run(name, rule, tests)` call, captured but not run. */
+export type HarvestedSuite = {
+    /** The display name the suite passed to `run`. */
+    name: string;
+    /** Which shared tester export declared it, which fixes the parser. */
+    tester: string;
+    /** Basename of the declaring file, so a finding is reproducible by hand. */
+    file: string;
+    /**
+     * The rule object itself. Callers resolve a rule NAME from this by identity
+     * against the plugin's own map rather than from `name`: 100 of the suites
+     * pass a display name that is not a rule name (`requireMemo`,
+     * `prefer-next-dynamic (JSX scenarios)`, `no-hungarian-phone-number-test`),
+     * and name-keyed matching silently drops every one of them.
+     */
+    rule: unknown;
+    valid: readonly unknown[];
+    invalid: readonly unknown[];
+};
+export type HarvestResult = {
+    suites: HarvestedSuite[];
+    /** Files that threw while loading, `basename: message`. */
+    failures: string[];
+    /** Non-vacuity accounting: a silent drop here would fake a clean sweep. */
+    filesLoaded: number;
+    filesSkipped: number;
+};
+export declare function harvestRuleTesterCases(): HarvestResult;

package/lib/utils/harvestRuleTesterCases.js

@@ -0,0 +1,168 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.harvestRuleTesterCases = void 0;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const sharedTesters = __importStar(require("./ruleTester"));
+const TESTS_DIR = path.join(__dirname, '..', 'tests');
+/**
+ * Only suites that import the shared tester module can declare a case, since
+ * `src/tests/no-local-rule-tester.test.ts` forbids a locally-built tester. That
+ * makes the import a sound admission test rather than a heuristic, and it is
+ * what keeps this affordable: the ~28 files it excludes are the meta-suites
+ * (`fixer-type-safety`, `docs-examples-conformance`, `rule-crash-robustness`,
+ * this guard's own siblings) which run full corpus sweeps at module scope and
+ * cost more to load than every rule suite combined.
+ *
+ * Matching the import rather than a `ruleTesterTs.run(` call site is
+ * deliberate: `prefer-next-dynamic.test.ts` aliases the tester
+ * (`const jsx = ruleTesterJsx`) before calling `run`, so a call-site pattern
+ * drops it.
+ */
+const IMPORTS_SHARED_TESTER = /from\s+'\.\.\/utils\/ruleTester'/;
+/**
+ * Jest registers a test for every `describe`/`it` a loaded module calls, so
+ * loading 271 suites inside a suite would graft their entire test list onto
+ * this one. Neutralizing the registrars for the duration of the load keeps the
+ * captured declarations and discards the registrations.
+ *
+ * `describe` bodies still execute — several suites call `run` inside one, and
+ * skipping the body would drop those cases — but everything that would register
+ * or assert becomes a no-op.
+ */
+const REGISTRAR_GLOBALS = [
+    'it',
+    'test',
+    'beforeEach',
+    'afterEach',
+    'beforeAll',
+    'afterAll',
+];
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const asAny = (value) => value;
+const noop = () => undefined;
+/** `it.each(rows)(name, fn)` is a call chain, so the stub needs the same shape. */
+const withEach = (fn) => {
+    fn.each = () => () => undefined;
+    fn.only = fn;
+    fn.skip = fn;
+    fn.todo = noop;
+    fn.failing = fn;
+    fn.concurrent = fn;
+    return fn;
+};
+function harvestRuleTesterCases() {
+    const suites = [];
+    const failures = [];
+    let currentFile = '';
+    let filesLoaded = 0;
+    let filesSkipped = 0;
+    const testerEntries = Object.entries(sharedTesters).filter(([, value]) => typeof asAny(value)?.run === 'function');
+    const originalRun = new Map();
+    for (const [key, tester] of testerEntries) {
+        originalRun.set(key, tester.run);
+        tester.run = (name, rule, tests) => {
+            const bag = asAny(tests) || {};
+            suites.push({
+                name,
+                tester: key,
+                file: currentFile,
+                rule,
+                valid: bag.valid || [],
+                invalid: bag.invalid || [],
+            });
+            return undefined;
+        };
+    }
+    const globalScope = global;
+    const savedGlobals = new Map();
+    const stub = (key, value) => {
+        savedGlobals.set(key, globalScope[key]);
+        globalScope[key] = value;
+    };
+    stub('describe', withEach((_name, body) => {
+        if (typeof body === 'function')
+            body();
+    }));
+    for (const key of REGISTRAR_GLOBALS)
+        stub(key, withEach(noop));
+    /**
+     * A handful of suites write fixture files at module scope, and
+     * `test-file-location-enforcement` writes them under
+     * `path.join(process.cwd(), '.cursor/tmp/...')` — a path it also `rmSync`s in
+     * an `afterAll` that the stubs above turn into a no-op. Loading it from the
+     * real working directory would therefore race that suite when it runs
+     * concurrently in another worker (its cleanup landing between this harvest's
+     * `mkdirSync` and `writeFileSync` throws ENOENT) and would strand fixtures in
+     * the repo when it does not. Pointing the working directory at a private
+     * scratch root for the duration of the load sends every cwd-derived write
+     * somewhere no other worker can see, and it is removed below.
+     *
+     * The paths the suites *record* are unaffected: they are made relative to the
+     * same cwd they were built from, so the harvested filenames come out
+     * identical either way.
+     */
+    const scratchRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'blumint-harvest-'));
+    const realCwd = process.cwd();
+    process.chdir(scratchRoot);
+    try {
+        const files = fs
+            .readdirSync(TESTS_DIR)
+            .filter((file) => file.endsWith('.test.ts'))
+            .sort();
+        for (const file of files) {
+            const fullPath = path.join(TESTS_DIR, file);
+            if (!IMPORTS_SHARED_TESTER.test(fs.readFileSync(fullPath, 'utf8'))) {
+                filesSkipped++;
+                continue;
+            }
+            currentFile = file;
+            try {
+                require(fullPath);
+                filesLoaded++;
+            }
+            catch (error) {
+                failures.push(`${file}: ${error?.message}`);
+            }
+        }
+    }
+    finally {
+        process.chdir(realCwd);
+        fs.rmSync(scratchRoot, { recursive: true, force: true });
+        for (const [key, tester] of testerEntries) {
+            const original = originalRun.get(key);
+            if (original)
+                tester.run = original;
+        }
+        for (const [key, value] of savedGlobals)
+            globalScope[key] = value;
+    }
+    return { suites, failures, filesLoaded, filesSkipped };
+}
+exports.harvestRuleTesterCases = harvestRuleTesterCases;
+/* eslint-enable @typescript-eslint/no-explicit-any */
+//# sourceMappingURL=harvestRuleTesterCases.js.map

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,27 @@
 [
+  {
+    "version": "1.20.97",
+    "date": "2026-08-04T08:50:14.394Z",
+    "rules": [
+      {
+        "name": "enforce-boolean-naming-prefixes",
+        "changeType": "fix",
+        "issues": [
+          1690,
+          1691
+        ],
+        "summary": "infer a callee's return from its body when the annotation is absent (closes #1691); accept a digit or $ fused onto an UPPER_SNAKE prefix (closes #1690)"
+      },
+      {
+        "name": "enforce-positive-naming",
+        "changeType": "fix",
+        "issues": [
+          1692
+        ],
+        "summary": "decline when a function's returns yield no verdict (closes #1692)"
+      }
+    ]
+  },
   {
     "version": "1.20.96",
     "date": "2026-08-04T07:23:58.552Z",