@blumintinc/eslint-plugin-blumint 1.20.179 → 1.20.181

package/lib/index.js

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

package/lib/rules/enforce-assert-safe-object-key.js

@@ -1316,7 +1316,8 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
         const reportWrittenKey = (written) => reportUseAssertSafe(written, context.sourceCode.getText(written));
         /**
          * Returns true when the identifier was initialized directly from an
-         * assertSafe(...) call, e.g. `const safeKey = assertSafe(rawKey)`.
+         * assertSafe(...) call, e.g. `const safeKey = assertSafe(rawKey)`, with any
+         * wrappers that erase before the code runs read through.
          * Only direct, single-step initializers count — transitive aliases
          * (const b = a) are not followed so they continue to be flagged.
          * findVariableInScope returns the nearest binding, so an inner variable
@@ -1328,11 +1329,20 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
             if (!variable)
                 return false;
             return variable.defs.some((def) => {
-                // `assertSafe?.(rawKey)` produces the very same validated key as
-                // `assertSafe(rawKey)` — the chain guards only a nullish callee — so
-                // the exemption reads through it rather than re-reporting the binding.
+                // The initializer is read through the same peel the index site uses, so
+                // the two arms agree about one expression: `assertSafe(rawKey) as
+                // TokenEncoded` binds the very key `assertSafe(rawKey)` does, the
+                // assertion having erased before the code runs, and `assertSafe?.(...)`
+                // is the same validated key again since the chain guards only a nullish
+                // callee. Demanding a bare call instead rejected the shape this rule's
+                // own remedy produces in typed code, where `Object.keys` widens to
+                // `string` and the record is keyed by a branded type (#2152).
+                //
+                // That peel includes `await`. assertSafe is synchronous, so awaiting it
+                // resolves to the very value it validated — the same reason the index
+                // arm has always exempted `m[await assertSafe(k)]`.
                 const init = def.node.type === utils_1.AST_NODE_TYPES.VariableDeclarator && def.node.init
-                    ? unwrapOptionalChain(def.node.init)
+                    ? unwrapWrittenKey(def.node.init)
                     : null;
                 return (!!init &&
                     init.type === utils_1.AST_NODE_TYPES.CallExpression &&

package/lib/rules/enforce-id-capitalization.js

@@ -46,11 +46,42 @@ exports.enforceIdCapitalization = (0, createRule_1.createRule)({
         // A single identifier token — no whitespace, no punctuation. Prose is a
         // phrase, so anything matching this is a name rather than displayed text.
         const IDENTIFIER_TOKEN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+        // Every value spelled as a string-literal TYPE in this file. A value
+        // literal with the same spelling is pinned by that type, so capitalizing
+        // the value on its own contradicts it (TS2322) while the type itself is
+        // code the rule must leave alone — there is no half of the pair that can
+        // be rewritten safely, so neither is. Membership is exact: a type
+        // `'id'` pins the literal `'id'`, not the prose `'Please enter your id.'`.
+        const literalTypeValues = new Set();
+        // A `TSLiteralType` can be written after the value it pins, so the verdict
+        // is only complete once the whole file has been walked. Candidates are
+        // therefore collected during traversal and reported at `Program:exit`.
+        const candidates = [];
+        /**
+         * A string literal that spells a TYPE is code, never displayed prose. It
+         * names a property (`Match['id']`), a discriminant, or a member of a
+         * literal union, so capitalizing it renames something the program refers
+         * to by that exact spelling and the fixed file stops compiling — an
+         * indexed-access key rewritten to `Match['ID']` is a TS2339 (#2153).
+         *
+         * The question is asked about the type position itself rather than by
+         * listing parent node types: every literal in a type is wrapped in a
+         * `TSLiteralType`, so one check covers indexed-access keys, mapped-type
+         * `as` clauses, tuple members, generic defaults and conditional-type
+         * branches at once. Enumerating parents instead leaves each spelling that
+         * is not on the list unguarded, which is how this defect shipped.
+         */
+        function isTypePositionLiteral(node) {
+            return !!node.parent && node.parent.type === utils_1.AST_NODE_TYPES.TSLiteralType;
+        }
         /**
          * Check if a node is in a context that should be excluded from the rule
          * (e.g., parameter names, property names, type definitions)
          */
         function isExcludedContext(node) {
+            if (isTypePositionLiteral(node)) {
+                return true;
+            }
             // Check if the node is a property of an object pattern (destructuring)
             if (node.parent &&
                 (node.parent.type === utils_1.AST_NODE_TYPES.Property ||
@@ -240,30 +271,51 @@ exports.enforceIdCapitalization = (0, createRule_1.createRule)({
                 const fixedText = value.replace(idRegex, (_match, prefix, suffix) => {
                     return `${prefix}ID${suffix}`;
                 });
-                context.report({
-                    node,
-                    messageId: 'enforceIdCapitalization',
-                    fix: (fixer) => {
-                        // JSX text carries no delimiters, so its own text is the content.
-                        if (node.type === utils_1.AST_NODE_TYPES.JSXText) {
-                            return fixer.replaceText(node, fixedText);
-                        }
-                        if (node.type === utils_1.AST_NODE_TYPES.Literal) {
-                            const replacement = fixStringLiteral(node, fixedText);
-                            return replacement === null
-                                ? null
-                                : fixer.replaceText(node, replacement);
-                        }
-                        // Any other node kind (a TemplateElement, say) is a fragment of a
-                        // larger construct whose delimiters and `${}` expressions live
-                        // outside this node; rebuilding it from the parsed value would
-                        // destroy them, so report without a fix.
-                        return null;
-                    },
-                });
+                candidates.push({ node, fixedText });
             }
         }
+        /**
+         * A value literal whose exact spelling is also written as a type in this
+         * file is a token that type names, not prose: `const kind: 'id' = 'id'`
+         * only compiles while both halves agree, and the type half is off limits.
+         */
+        function isPinnedByLiteralType(node) {
+            return (node.type === utils_1.AST_NODE_TYPES.Literal &&
+                typeof node.value === 'string' &&
+                literalTypeValues.has(node.value));
+        }
+        function reportCandidate(node, fixedText) {
+            context.report({
+                node,
+                messageId: 'enforceIdCapitalization',
+                fix: (fixer) => {
+                    // JSX text carries no delimiters, so its own text is the content.
+                    if (node.type === utils_1.AST_NODE_TYPES.JSXText) {
+                        return fixer.replaceText(node, fixedText);
+                    }
+                    if (node.type === utils_1.AST_NODE_TYPES.Literal) {
+                        const replacement = fixStringLiteral(node, fixedText);
+                        return replacement === null
+                            ? null
+                            : fixer.replaceText(node, replacement);
+                    }
+                    // Any other node kind (a TemplateElement, say) is a fragment of a
+                    // larger construct whose delimiters and `${}` expressions live
+                    // outside this node; rebuilding it from the parsed value would
+                    // destroy them, so report without a fix.
+                    return null;
+                },
+            });
+        }
         return {
+            // Record the spellings the file's types claim before any verdict is
+            // emitted; a value literal matching one of them cannot be rewritten.
+            TSLiteralType(node) {
+                if (node.literal.type === utils_1.AST_NODE_TYPES.Literal &&
+                    typeof node.literal.value === 'string') {
+                    literalTypeValues.add(node.literal.value);
+                }
+            },
             // Check string literals
             Literal(node) {
                 if (typeof node.value === 'string') {
@@ -274,6 +326,16 @@ exports.enforceIdCapitalization = (0, createRule_1.createRule)({
             JSXText(node) {
                 checkForIdInString(node, node.value);
             },
+            'Program:exit'() {
+                for (const { node, fixedText } of candidates) {
+                    // JSX text is rendered, so no type can pin it — the check is scoped
+                    // to literals, whose spelling a type can name.
+                    if (isPinnedByLiteralType(node)) {
+                        continue;
+                    }
+                    reportCandidate(node, fixedText);
+                }
+            },
             // We don't need a separate handler for CallExpression since we already handle Literals
             // The Literal handler will catch the string arguments in t("user.profile.id")
         };

package/lib/rules/prefer-getter-over-parameterless-method.js

@@ -74,6 +74,70 @@ function isVoidishType(node) {
             return false;
     }
 }
+/**
+ * Type names whose values are awaited rather than read. `PromiseLike` counts
+ * because thenability — not the `Promise` constructor — is what makes a value
+ * an awaited one, and a `PromiseLike` member is as unconvertible as a `Promise`
+ * one.
+ */
+const THENABLE_TYPE_NAMES = new Set(['Promise', 'PromiseLike']);
+/**
+ * `Promise` statics whose result is a promise whatever they are handed, so a
+ * `return Promise.all(...)` is a promise return with no annotation to read.
+ */
+const PROMISE_STATIC_PRODUCERS = new Set([
+    'resolve',
+    'reject',
+    'all',
+    'allSettled',
+    'race',
+    'any',
+]);
+/**
+ * Methods a promise answers, whose own result is another promise. `then` is the
+ * definition of thenable; `catch`/`finally` are sugar over it.
+ */
+const THENABLE_CHAIN_METHODS = new Set(['then', 'catch', 'finally']);
+/**
+ * The final segment of a type name, so a qualified spelling
+ * (`globalThis.Promise<T>`, `bluebird.Promise<T>`) is recognized as the thenable
+ * it names rather than dismissed for not being a bare `Identifier`.
+ */
+function rightmostTypeName(typeName) {
+    if (typeName.type === utils_1.AST_NODE_TYPES.Identifier)
+        return typeName.name;
+    if (typeName.type === utils_1.AST_NODE_TYPES.TSQualifiedName) {
+        return typeName.right.name;
+    }
+    return null;
+}
+/**
+ * Whether a *written* type annotation denotes a thenable.
+ *
+ * This is deliberately syntactic and deliberately not exhaustive: the rule
+ * requests no parser services, so an alias that happens to resolve to a promise
+ * is out of reach. Failing to spot one costs a report the rule would otherwise
+ * have made, which is the safe direction — the unsafe one is prescribing (and
+ * on `private` members, applying) a getter rewrite that breaks every caller.
+ */
+function isThenableTypeNode(node) {
+    if (!node)
+        return false;
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.TSTypeReference: {
+            const name = rightmostTypeName(node.typeName);
+            return name !== null && THENABLE_TYPE_NAMES.has(name);
+        }
+        // A container that can hold a thenable still hands the caller one:
+        // `Promise<T> | undefined` is awaited at the call site exactly as `Promise<T>`
+        // is, and an intersection carries every constituent's contract.
+        case utils_1.AST_NODE_TYPES.TSUnionType:
+        case utils_1.AST_NODE_TYPES.TSIntersectionType:
+            return node.types.some(isThenableTypeNode);
+        default:
+            return false;
+    }
+}
 function isFunctionLikeNode(value) {
     return (value.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
         value.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
@@ -617,6 +681,213 @@ exports.preferGetterOverParameterlessMethod = (0, createRule_1.createRule)({
             }
             return false;
         }
+        /**
+         * The expressions the method itself returns. A `return` inside a nested
+         * function is that callback's result, not the method's, so those are skipped
+         * exactly as every other body walk here skips them.
+         */
+        function collectReturnedExpressions(body) {
+            const returned = [];
+            const stack = [...body.body];
+            while (stack.length) {
+                const current = stack.pop();
+                if (isFunctionLikeNode(current)) {
+                    continue;
+                }
+                if (current.type === utils_1.AST_NODE_TYPES.ReturnStatement &&
+                    current.argument) {
+                    returned.push(current.argument);
+                }
+                pushChildNodes(current, stack);
+            }
+            return returned;
+        }
+        /**
+         * Whether a function-valued node hands back a thenable: by its `async`
+         * keyword, by its own return annotation, or — failing both — by what its
+         * body demonstrably returns.
+         *
+         * `owner` fixes the class body that `this.<name>` resolves against. It stays
+         * the originally reported method through every recursion, because a sibling
+         * reached from that method's body lives in the same class body.
+         */
+        function functionYieldsThenable(owner, fn, seen) {
+            if (!fn)
+                return false;
+            if (fn.async)
+                return true;
+            const returnType = fn.returnType?.typeAnnotation;
+            if (returnType) {
+                return isThenableTypeNode(returnType);
+            }
+            const body = fn.body;
+            if (!body)
+                return false;
+            // A concise arrow body IS the returned expression.
+            if (body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+                return isThenableExpression(owner, body, seen);
+            }
+            return collectReturnedExpressions(body).some((expression) => isThenableExpression(owner, expression, seen));
+        }
+        /** Recurses into a sibling's body once, never revisiting a function. */
+        function siblingFunctionYieldsThenable(owner, fn, seen) {
+            // `a() { return this.b(); } b() { return this.a(); }` is legal and would
+            // otherwise recur forever; visiting each function at most once also bounds
+            // the work by the size of the class body.
+            if (!fn || seen.has(fn))
+                return false;
+            seen.add(fn);
+            return functionYieldsThenable(owner, fn, seen);
+        }
+        /**
+         * Whether `this.<name>` resolves, within the enclosing class body, to a
+         * member that yields a thenable.
+         *
+         * A promise-returning method is often written with no annotation of its own
+         * (`readEpoch() { return this.evaluate(); }`), so the sibling's declaration
+         * is the only syntactic evidence available without a type checker. The
+         * sibling's BODY is consulted when it carries no annotation either, so the
+         * exemption survives a sibling transform that strips one — `--fix` under the
+         * recommended config runs `no-explicit-return-type` over the same file, and
+         * an exemption that only an annotation can carry does not survive it.
+         *
+         * `viaCall` distinguishes `this.evaluate()` from `this.evaluate`: reading a
+         * method without calling it yields the function object, which is not a
+         * thenable however the method is annotated, while reading a getter or a
+         * field is what produces its declared type.
+         */
+        function siblingYieldsThenable(owner, name, viaCall, seen) {
+            const classBody = owner.parent;
+            if (!classBody || classBody.type !== utils_1.AST_NODE_TYPES.ClassBody) {
+                return false;
+            }
+            return classBody.body.some((member) => {
+                if (member.type === utils_1.AST_NODE_TYPES.StaticBlock)
+                    return false;
+                const memberName = memberNameOf(member.key, member.computed);
+                if (memberName !== name)
+                    return false;
+                if (member.type === utils_1.AST_NODE_TYPES.MethodDefinition ||
+                    member.type === utils_1.AST_NODE_TYPES.TSAbstractMethodDefinition) {
+                    const readsAsValue = member.kind === 'get' ? !viaCall : viaCall;
+                    return (readsAsValue &&
+                        siblingFunctionYieldsThenable(owner, member.value, seen));
+                }
+                if (member.type === utils_1.AST_NODE_TYPES.PropertyDefinition ||
+                    member.type === utils_1.AST_NODE_TYPES.TSAbstractPropertyDefinition) {
+                    const annotation = member.typeAnnotation?.typeAnnotation;
+                    const value = member.value;
+                    const isFunctionValued = !!value &&
+                        (value.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                            value.type === utils_1.AST_NODE_TYPES.FunctionExpression);
+                    if (!viaCall) {
+                        if (isThenableTypeNode(annotation))
+                            return true;
+                        // An un-annotated field initialized to a promise (`private pending =
+                        // Promise.resolve(x)`) is thenable on its own evidence. A
+                        // function-valued field is not: reading it yields the function.
+                        return (!annotation &&
+                            !isFunctionValued &&
+                            !!value &&
+                            isThenableExpression(owner, value, seen));
+                    }
+                    // A called field is function-valued, so its RETURN type is what
+                    // reaches the caller.
+                    if (annotation?.type === utils_1.AST_NODE_TYPES.TSFunctionType) {
+                        return isThenableTypeNode(annotation.returnType?.typeAnnotation);
+                    }
+                    return (isFunctionValued &&
+                        siblingFunctionYieldsThenable(owner, value, seen));
+                }
+                return false;
+            });
+        }
+        /** `Promise`, however it is qualified (`globalThis.Promise`, `bluebird.Promise`). */
+        function isPromiseNamespace(expression) {
+            if (expression.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return expression.name === 'Promise';
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+                return (memberNameOf(expression.property, expression.computed) === 'Promise');
+            }
+            return false;
+        }
+        function isThenableCall(owner, call, seen) {
+            // An optional call is a `ChainExpression` WRAPPING the call, so the
+            // callee here is always the plain member expression; the chain wrapper is
+            // unwrapped one level up.
+            const callee = call.callee;
+            if (callee.type !== utils_1.AST_NODE_TYPES.MemberExpression)
+                return false;
+            const property = memberNameOf(callee.property, callee.computed);
+            if (property === null)
+                return false;
+            if (isPromiseNamespace(callee.object) &&
+                PROMISE_STATIC_PRODUCERS.has(property)) {
+                return true;
+            }
+            if (THENABLE_CHAIN_METHODS.has(property))
+                return true;
+            if (callee.object.type === utils_1.AST_NODE_TYPES.ThisExpression) {
+                return siblingYieldsThenable(owner, property, true, seen);
+            }
+            return false;
+        }
+        /**
+         * Whether a returned expression is demonstrably a thenable. Recursion is
+         * confined to combinators that pass a value straight through (assertions,
+         * `?:`, `&&`/`||`/`??`, optional chains), so the answer always rests on one
+         * of the concrete producers above rather than on a guess about a name.
+         */
+        function isThenableExpression(owner, expression, seen, depth = 0) {
+            if (depth > 4)
+                return false;
+            switch (expression.type) {
+                // `return await x` only parses inside an `async` method, so the method
+                // itself hands the caller a promise.
+                case utils_1.AST_NODE_TYPES.AwaitExpression:
+                    return true;
+                case utils_1.AST_NODE_TYPES.TSAsExpression:
+                case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
+                    return (isThenableTypeNode(expression.typeAnnotation) ||
+                        isThenableExpression(owner, expression.expression, seen, depth + 1));
+                case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+                case utils_1.AST_NODE_TYPES.ChainExpression:
+                    return isThenableExpression(owner, expression.expression, seen, depth + 1);
+                case utils_1.AST_NODE_TYPES.ConditionalExpression:
+                    return (isThenableExpression(owner, expression.consequent, seen, depth + 1) ||
+                        isThenableExpression(owner, expression.alternate, seen, depth + 1));
+                case utils_1.AST_NODE_TYPES.LogicalExpression:
+                    return (isThenableExpression(owner, expression.left, seen, depth + 1) ||
+                        isThenableExpression(owner, expression.right, seen, depth + 1));
+                case utils_1.AST_NODE_TYPES.CallExpression:
+                    return isThenableCall(owner, expression, seen);
+                case utils_1.AST_NODE_TYPES.MemberExpression:
+                    // `return this.pending` where `pending: Promise<T>`.
+                    return (expression.object.type === utils_1.AST_NODE_TYPES.ThisExpression &&
+                        siblingYieldsThenable(owner, memberNameOf(expression.property, expression.computed) ?? '', false, seen));
+                default:
+                    return false;
+            }
+        }
+        /**
+         * Whether the method hands the caller a thenable.
+         *
+         * TypeScript does not require the `async` keyword to return a promise, so
+         * keying on the keyword alone classified `fetchToken(): Promise<string>` as
+         * synchronous and asked for a getter (#2154). A getter is never a legal
+         * remedy here: it turns a call that starts work into a property read, so
+         * `session.epoch` spawns the work on what reads as a field access and any
+         * reflective call site (`(session as any).readEpoch()`) throws outright.
+         *
+         * An explicit return annotation is the method's whole contract, so a
+         * non-thenable one settles the question without reading the body — which is
+         * what keeps an annotated `(): string` method reportable even when its body
+         * mentions promises.
+         */
+        function returnsThenable(node) {
+            return functionYieldsThenable(node, node.value, new Set([node.value]));
+        }
         /**
          * Returns true when the method body contains a ThrowStatement that is
          * directly in the method's own scope (not inside a nested function/arrow).
@@ -882,7 +1153,11 @@ exports.preferGetterOverParameterlessMethod = (0, createRule_1.createRule)({
                     node.key.type !== utils_1.AST_NODE_TYPES.PrivateIdentifier) {
                     return;
                 }
-                if (config.ignoreAsync && node.value.async)
+                // `ignoreAsync` means "ignore asynchronous methods", not "ignore
+                // methods bearing the async keyword": TypeScript does not require the
+                // keyword to return a promise, so `fetchToken(): Promise<string>` is
+                // asynchronous with no keyword written at all (#2154).
+                if (config.ignoreAsync && returnsThenable(node))
                     return;
                 if (config.ignoreAbstract &&
                     node.type === utils_1.AST_NODE_TYPES.TSAbstractMethodDefinition) {
@@ -970,7 +1245,14 @@ exports.preferGetterOverParameterlessMethod = (0, createRule_1.createRule)({
                     const hasDuplicateSuggestedName = classBody?.type === utils_1.AST_NODE_TYPES.ClassBody
                         ? (suggestedNameCounts.get(classBody)?.get(scopeKey) ?? 0) > 1
                         : false;
-                    const isAsync = node.value.async;
+                    // A thenable-returning member has no legal getter form at all: the
+                    // rewrite converts a call that starts work into a property read, and
+                    // a reflective call site (`(session as any).readEpoch()`) throws
+                    // afterwards. The eligibility gate already withholds the report for
+                    // these, so this is a second, independent lock — a future change
+                    // there must not silently re-enable a rewrite that cannot compile or
+                    // run. It subsumes the former `async`-keyword-only withhold.
+                    const isThenableReturning = returnsThenable(node);
                     // A decorator cannot be applied to an ECMA private member under
                     // `experimentalDecorators` (TS1206), so a decorated `#foo()` has no
                     // legal getter form to convert to — the fix is impossible, not merely
@@ -1001,7 +1283,7 @@ exports.preferGetterOverParameterlessMethod = (0, createRule_1.createRule)({
                         },
                         fix: !isPrivate ||
                             sideEffectReason ||
-                            isAsync ||
+                            isThenableReturning ||
                             !leftParen ||
                             !rightParen ||
                             hasCollision ||

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "1.20.181",
+    "date": "2026-08-27T06:29:43.247Z",
+    "rules": [
+      {
+        "name": "prefer-getter-over-parameterless-method",
+        "changeType": "fix",
+        "issues": [
+          2154
+        ],
+        "summary": "decide \"synchronous\" from the returned type, not the async keyword (closes #2154)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.180",
+    "date": "2026-08-27T01:52:25.340Z",
+    "rules": [
+      {
+        "name": "enforce-assert-safe-object-key",
+        "changeType": "fix",
+        "issues": [
+          2152
+        ],
+        "summary": "read the validated binding through the shared peel (closes #2152)"
+      },
+      {
+        "name": "enforce-id-capitalization",
+        "changeType": "fix",
+        "issues": [
+          2153
+        ],
+        "summary": "leave string literals that spell a type alone (closes #2153)"
+      }
+    ]
+  },
   {
     "version": "1.20.179",
     "date": "2026-08-26T23:40:36.587Z",