@blumintinc/eslint-plugin-blumint 1.20.61 → 1.20.62

package/lib/index.js

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

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

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceAssertSafeObjectKey = void 0;
+const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
@@ -30,6 +31,137 @@ function isAssertSafeSpecifier(specifier) {
 function normalizeModulePath(value) {
     return value.replace(/\\/g, '/').replace(/\.(tsx?|jsx?|mts|cts)$/i, '');
 }
+/**
+ * Extensions whose module system the file name settles on its own, ahead of any
+ * package manifest: `.mjs` is ESM and `.cjs` is CommonJS by definition, while a
+ * TypeScript source — `.mts` included — is compiled before it runs and its
+ * specifiers are resolved by the compiler, which accepts the extensionless
+ * form. Only `.js` is ambiguous and has to ask the nearest manifest.
+ */
+const NATIVE_ESM_EXTENSION = /\.mjs$/i;
+const NON_NATIVE_ESM_EXTENSION = /\.(cjs|tsx?|mts|cts)$/i;
+const AMBIGUOUS_JS_EXTENSION = /\.js$/i;
+/**
+ * Whether the nearest `package.json` at or above `startDir` declares
+ * `"type": "module"`, which is what makes a `.js` file native ESM. Node consults
+ * only the first manifest found, and treats a missing `type` field as
+ * CommonJS — so the walk stops at the first manifest it can read, not at the
+ * first one that declares a type.
+ *
+ * Every filesystem touch is optional: a manifest that cannot be read is
+ * indistinguishable from an absent one and the walk continues, while a manifest
+ * that cannot be parsed declines the extension rather than guessing. Declining
+ * yields the bare specifier, which every non-ESM consumer resolves — the safer
+ * answer when the tree cannot say which kind of consumer this is.
+ */
+function nearestManifestDeclaresModule(startDir) {
+    let dir = startDir;
+    for (;;) {
+        let manifest;
+        try {
+            manifest = fs_1.default.readFileSync(path_1.default.join(dir, 'package.json'), 'utf8');
+        }
+        catch {
+            const parent = path_1.default.dirname(dir);
+            if (parent === dir) {
+                return false;
+            }
+            dir = parent;
+            continue;
+        }
+        try {
+            return (JSON.parse(manifest)?.type === 'module');
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/** Names that read as a positional sequence rather than a keyed record. */
+const ARRAY_LIKE_NAME = /^(array|arr|items|elements|list|collection|data)s?$/i;
+/**
+ * The name an indexed object is judged by. A collection reached as a field —
+ * `raster.data[i]`, `this.items[i]`, `a.b.list[i]` — carries its signal on the
+ * property rather than on the root object, so the property name is what the
+ * array-ish test sees there.
+ */
+function indexedObjectName(node) {
+    if (node.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return node.name;
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !node.computed &&
+        node.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return node.property.name;
+    }
+    return '';
+}
+/**
+ * Operators that coerce both operands with ToNumeric before operating, so the
+ * result is a number (or bigint) whatever the operands hold. `+` is absent: it
+ * keeps string concatenation, so it is judged from its operands instead.
+ */
+const NUMERIC_BINARY_OPERATORS = new Set([
+    '-',
+    '*',
+    '/',
+    '%',
+    '**',
+    '<<',
+    '>>',
+    '>>>',
+    '&',
+    '|',
+    '^',
+]);
+/** The compound assignments of NUMERIC_BINARY_OPERATORS, `+=` excluded. */
+const NUMERIC_ASSIGNMENT_OPERATORS = new Set([
+    '-=',
+    '*=',
+    '/=',
+    '%=',
+    '**=',
+    '<<=',
+    '>>=',
+    '>>>=',
+    '&=',
+    '|=',
+    '^=',
+]);
+/** Global conversions whose result is a number regardless of the argument. */
+const NUMERIC_CALLEE_NAMES = new Set(['Number', 'parseInt', 'parseFloat']);
+/**
+ * Whether the call is guaranteed to produce a number. Every `Math` member
+ * returns one, so the namespace is accepted wholesale rather than enumerated.
+ */
+function isNumericCall(node) {
+    const { callee } = node;
+    if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return NUMERIC_CALLEE_NAMES.has(callee.name);
+    }
+    return (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !callee.computed &&
+        callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
+        callee.object.name === 'Math');
+}
+/**
+ * A `: number` annotation on a binding name. Only parameters and variable
+ * declarators carry one, and a declarator is judged from its writes, so this
+ * effectively identifies a numeric parameter.
+ */
+function isNumberAnnotated(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.Identifier &&
+        node.typeAnnotation?.typeAnnotation.type === utils_1.AST_NODE_TYPES.TSNumberKeyword);
+}
+/**
+ * Whether the definition can hold a number: a declarator (whose value is proven
+ * by its writes) or a parameter annotated `: number`. Anything else — an
+ * import, a function or class name, a catch binding — is not.
+ */
+function definesNumericBinding(def) {
+    return (def.node.type === utils_1.AST_NODE_TYPES.VariableDeclarator ||
+        isNumberAnnotated(def.name));
+}
 exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
     name: 'enforce-assert-safe-object-key',
     meta: {
@@ -91,6 +223,28 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
             const fileRelToCwd = path_1.default.relative(cwd, rawFilename).replace(/\\/g, '/');
             return path_1.default.posix.dirname(fileRelToCwd);
         };
+        /**
+         * Whether the file being fixed runs as native ESM, where node's resolver
+         * takes a specifier literally and an extensionless one throws
+         * ERR_MODULE_NOT_FOUND at startup. TypeScript and bundler consumers resolve
+         * extensionless specifiers themselves, so they keep the bare form.
+         *
+         * The walk for an ambiguous `.js` file runs only while a fix is being built,
+         * costs a handful of stat-sized reads, and needs an absolute name to have a
+         * directory to start from.
+         */
+        const isNativeEsmFile = () => {
+            const filename = context.getFilename().replace(/\\/g, '/');
+            if (NATIVE_ESM_EXTENSION.test(filename)) {
+                return true;
+            }
+            if (NON_NATIVE_ESM_EXTENSION.test(filename) ||
+                !AMBIGUOUS_JS_EXTENSION.test(filename) ||
+                !path_1.default.isAbsolute(filename)) {
+                return false;
+            }
+            return nearestManifestDeclaresModule(path_1.default.dirname(filename));
+        };
         /**
          * Computes the module specifier for the injected assertSafe import.
          *
@@ -104,17 +258,22 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
          * emitted import resolves from that file's location.
          */
         const computeImportSpecifier = () => {
+            // The helper is authored as TypeScript and runs as its compiled output, so
+            // a native-ESM importer names the emitted `.js` file. TS resolves a `.js`
+            // specifier back to the `.ts` source under nodenext, which keeps the one
+            // spelling correct for both.
+            const extension = isNativeEsmFile() ? '.js' : '';
             const fileDir = fileDirFromRoot();
             // Emitting the configured path verbatim preserves the option's literal
             // value for non-file lints.
             if (fileDir === null) {
-                return importPath;
+                return `${importPath}${extension}`;
             }
             let specifier = path_1.default.posix.relative(fileDir, assertSafeTarget);
             if (!specifier.startsWith('.')) {
                 specifier = `./${specifier}`;
             }
-            return specifier;
+            return `${specifier}${extension}`;
         };
         /**
          * Whether a module specifier written in the file denotes the same helper the
@@ -245,6 +404,86 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                     init.callee.name === 'assertSafe');
             });
         };
+        /**
+         * Whether the syntax alone proves the key is a number. `__proto__`,
+         * `constructor` and `prototype` are never the string form of a number, so a
+         * numeric key cannot reach the prototype surface assertSafe exists to
+         * guard: the call would be dead weight, and in an index-heavy loop a
+         * per-iteration coercion. The judgement stays syntactic — a key the syntax
+         * does not prove numeric keeps being reported.
+         */
+        const isStaticallyNumeric = (node, seen = new Set()) => {
+            switch (node.type) {
+                case utils_1.AST_NODE_TYPES.Literal:
+                    return typeof node.value === 'number';
+                case utils_1.AST_NODE_TYPES.UpdateExpression:
+                    return true;
+                case utils_1.AST_NODE_TYPES.UnaryExpression:
+                    return (node.operator === '-' ||
+                        node.operator === '+' ||
+                        node.operator === '~');
+                case utils_1.AST_NODE_TYPES.BinaryExpression:
+                    if (NUMERIC_BINARY_OPERATORS.has(node.operator)) {
+                        return true;
+                    }
+                    return (node.operator === '+' &&
+                        isStaticallyNumeric(node.left, seen) &&
+                        isStaticallyNumeric(node.right, seen));
+                case utils_1.AST_NODE_TYPES.CallExpression:
+                    return isNumericCall(node);
+                case utils_1.AST_NODE_TYPES.MemberExpression:
+                    // `.length` is a number on arrays, typed arrays and strings alike.
+                    return (!node.computed &&
+                        node.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+                        node.property.name === 'length');
+                case utils_1.AST_NODE_TYPES.TSAsExpression:
+                case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+                    return isStaticallyNumeric(node.expression, seen);
+                case utils_1.AST_NODE_TYPES.Identifier:
+                    return isNumericIdentifier(node, seen);
+                default:
+                    return false;
+            }
+        };
+        /**
+         * Whether every declaration and every write of the resolved binding keeps it
+         * numeric. `seen` is copied per resolution step so a cycle
+         * (`let a = b; let b = a;`) terminates without a sibling occurrence of one
+         * variable (`arr[i + i]`) being mistaken for that cycle.
+         */
+        const isNumericIdentifier = (node, seen) => {
+            const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, node), node.name);
+            if (!variable || seen.has(variable)) {
+                return false;
+            }
+            const nextSeen = new Set(seen).add(variable);
+            if (variable.defs.length === 0 ||
+                !variable.defs.every(definesNumericBinding)) {
+                return false;
+            }
+            const writes = variable.references.filter((reference) => reference.isWrite());
+            const staysNumeric = writes.every((reference) => {
+                const { writeExpr } = reference;
+                // `i++`/`--i` write a number back with no expression to inspect.
+                if (!writeExpr) {
+                    return true;
+                }
+                const assignment = writeExpr.parent;
+                if (assignment?.type === utils_1.AST_NODE_TYPES.AssignmentExpression &&
+                    NUMERIC_ASSIGNMENT_OPERATORS.has(assignment.operator)) {
+                    return true;
+                }
+                return isStaticallyNumeric(writeExpr, nextSeen);
+            });
+            if (!staysNumeric) {
+                return false;
+            }
+            // A `: number` parameter is numeric from its declaration; a declarator is
+            // only proven by a write, and its initializer is one — so `let k;` with no
+            // write anywhere holds undefined and stays unproven.
+            return (writes.length > 0 ||
+                variable.defs.every((def) => isNumberAnnotated(def.name)));
+        };
         return {
             // Handle computed property in object destructuring
             Property(node) {
@@ -305,14 +544,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         return;
                     }
                     // Try to determine if this is likely an array or dictionary
-                    const objectNode = node.object;
-                    let objectName = '';
-                    let isLikelyArray = false;
-                    if (objectNode.type === utils_1.AST_NODE_TYPES.Identifier) {
-                        objectName = objectNode.name.toLowerCase();
-                        isLikelyArray =
-                            /^(array|arr|items|elements|list|collection|data)s?$/i.test(objectName);
-                    }
+                    const isLikelyArray = ARRAY_LIKE_NAME.test(indexedObjectName(node.object));
                     // Check for string literals - allow them for dictionaries but not for regular objects
                     if (property.type === utils_1.AST_NODE_TYPES.Literal &&
                         typeof property.value === 'string') {
@@ -325,6 +557,12 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         // Numeric literals are fine, no need for assertSafe
                         return;
                     }
+                    // A key the syntax proves numeric — a loop counter, an offset
+                    // computation, Math.floor(...) — cannot name a prototype field, so
+                    // validating it guards nothing.
+                    if (isStaticallyNumeric(property)) {
+                        return;
+                    }
                     // Check if we're using String(id) pattern
                     if (property.type === utils_1.AST_NODE_TYPES.CallExpression &&
                         property.callee.type === utils_1.AST_NODE_TYPES.Identifier &&

package/lib/rules/enforce-verb-noun-naming.d.ts

@@ -1 +1,7 @@
-export declare const enforceVerbNounNaming: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"functionVerbPhrase", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+type Options = [
+    {
+        readonly externallyNamedExports?: readonly string[];
+    }
+];
+export declare const enforceVerbNounNaming: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"functionVerbPhrase", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export {};

package/lib/rules/enforce-verb-noun-naming.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceVerbNounNaming = void 0;
 const utils_1 = require("@typescript-eslint/utils");
+const minimatch_1 = require("minimatch");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
 const compromise_1 = __importDefault(require("compromise"));
@@ -3776,13 +3777,87 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
             requiresTypeChecking: false,
             extendsBaseRule: false,
         },
-        schema: [],
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    externallyNamedExports: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
         messages: {
             functionVerbPhrase: 'Function "{{name}}" should start with an action verb followed by the thing it acts on. Verb-first names tell readers this symbol performs work instead of representing data, which keeps APIs predictable and prevents accidental misuse. Rename "{{name}}" to a verb-noun phrase such as "fetchUsers" or "processRequest".',
         },
     },
-    defaultOptions: [],
-    create(context) {
+    defaultOptions: [{}],
+    create(context, [options]) {
+        const externallyNamedExports = options?.externallyNamedExports ?? [];
+        const rawFilename = context.filename ?? context.getFilename();
+        const normalizedFilename = rawFilename.replace(/\\/g, '/');
+        // A leading `**` consumes the extra leading segments of an absolute path,
+        // so one match handles both repo-relative and absolute filenames. Malformed
+        // globs are treated as non-matching by minimatch rather than throwing, which
+        // keeps a bad pattern from aborting the whole lint run.
+        const hasExternallyNamedExports = externallyNamedExports.some((glob) => (0, minimatch_1.minimatch)(normalizedFilename, glob, { dot: true, matchBase: true }));
+        // `export { local as exported }` and `export default local` name the module
+        // binding from a distance, so the local name still belongs to the external
+        // specification. Collected once per file, and only when a glob matched.
+        let deferredExportedNames;
+        function getDeferredExportedNames() {
+            if (deferredExportedNames) {
+                return deferredExportedNames;
+            }
+            const names = new Set();
+            for (const statement of context.sourceCode.ast.body) {
+                if (statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+                    !statement.source) {
+                    for (const specifier of statement.specifiers) {
+                        const local = specifier.local;
+                        if (local.type === utils_1.AST_NODE_TYPES.Identifier) {
+                            names.add(local.name);
+                        }
+                    }
+                }
+                else if (statement.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration &&
+                    statement.declaration.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    names.add(statement.declaration.name);
+                }
+            }
+            deferredExportedNames = names;
+            return names;
+        }
+        /**
+         * Exported symbols in a file whose names are specified elsewhere (a runtime
+         * registry key, a CLI verb, an artifact path) cannot be renamed without
+         * desynchronizing them from that specification. Non-exported symbols in the
+         * same file are ordinary local code and stay checked.
+         */
+        function isExternallyNamedExport(node, name) {
+            if (!hasExternallyNamedExports) {
+                return false;
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+                const parent = node.parent;
+                if (parent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+                    parent?.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration) {
+                    return true;
+                }
+                // Only a module-level binding can be the target of a deferred export.
+                return (parent?.type === utils_1.AST_NODE_TYPES.Program &&
+                    getDeferredExportedNames().has(name));
+            }
+            const declaration = node.parent;
+            const declarationParent = declaration?.parent;
+            if (declarationParent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration) {
+                return true;
+            }
+            return (declarationParent?.type === utils_1.AST_NODE_TYPES.Program &&
+                getDeferredExportedNames().has(name));
+        }
         function extractFirstWord(name) {
             const firstChar = name.charAt(0);
             const rest = name.slice(1);
@@ -3925,6 +4000,9 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
                 if (isReactComponent(node)) {
                     return;
                 }
+                if (isExternallyNamedExport(node, node.id.name)) {
+                    return;
+                }
                 if (!isVerbPhrase(node.id.name)) {
                     context.report({
                         node: node.id,
@@ -3942,6 +4020,9 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
                     if (isReactComponent(node.init)) {
                         return;
                     }
+                    if (isExternallyNamedExport(node, node.id.name)) {
+                        return;
+                    }
                     if (!isVerbPhrase(node.id.name)) {
                         context.report({
                             node: node.id,

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,27 @@
 [
+  {
+    "version": "1.20.62",
+    "date": "2026-08-01T09:01:13.989Z",
+    "rules": [
+      {
+        "name": "enforce-assert-safe-object-key",
+        "changeType": "fix",
+        "issues": [
+          1554,
+          1556
+        ],
+        "summary": "append .js to the injected specifier for native-ESM consumers (closes #1556); exempt statically numeric keys and array-ish member objects (closes #1554)"
+      },
+      {
+        "name": "enforce-verb-noun-naming",
+        "changeType": "fix",
+        "issues": [
+          1555
+        ],
+        "summary": "add externallyNamedExports glob option for externally-specified names (closes #1555)"
+      }
+    ]
+  },
   {
     "version": "1.20.61",
     "date": "2026-08-01T06:30:50.860Z",