@blumintinc/eslint-plugin-blumint 1.20.58 → 1.20.60

package/lib/index.js

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

package/lib/rules/enforce-singular-type-names.js

@@ -41,19 +41,36 @@ const NON_PLURALIZABLE_SUFFIXES = [
  * the reference itself as a container.
  */
 const ARRAY_GENERIC_NAMES = new Set(['Array', 'ReadonlyArray']);
+/**
+ * Union members that only express absence. Stripping them keeps a nullable
+ * container recognisable as a container: `T[]` and `T[] | null` describe the
+ * same collection, so they must not disagree about whether a plural name fits.
+ */
+const NULLISH_TYPE_NODES = new Set([
+    utils_1.AST_NODE_TYPES.TSNullKeyword,
+    utils_1.AST_NODE_TYPES.TSUndefinedKeyword,
+]);
+/**
+ * Shared budget for wrapper peeling and union recursion. Wrapper nesting is
+ * finite in real code; the cap only guards against a pathological cycle. Every
+ * peel and every descent into a union member spends one unit, so the recursion
+ * a union introduces stays bounded by the same constant.
+ */
+const MAX_TYPE_DEPTH = 10;
 /**
  * Returns true when the type alias RHS resolves to a container shape — a
  * `TSArrayType` (`Foo[]`) or `TSTupleType` (`[A, B]`) — for which a plural name
  * is the correct, self-documenting choice. Sees through identity-ish wrappers
  * over the same shape: the `readonly` type operator, parenthesized types, and
  * the `Readonly<T>` utility type; `Array<T>`/`ReadonlyArray<T>` are containers
- * outright.
+ * outright. A union whose non-nullish members are all containers counts too.
+ *
+ * @param depth Budget already spent by an enclosing wrapper or union member.
  */
-function resolvesToContainerType(node) {
+function resolvesToContainerType(node, depth = 0) {
     let current = node;
     // Fixpoint loop: peel identity wrappers until a concrete shape is reached.
-    // Wrappers are finite; the cap only guards against a pathological cycle.
-    for (let i = 0; i < 10; i++) {
+    for (let i = depth; i < MAX_TYPE_DEPTH; i++) {
         switch (current.type) {
             case utils_1.AST_NODE_TYPES.TSArrayType:
             case utils_1.AST_NODE_TYPES.TSTupleType:
@@ -66,6 +83,18 @@ function resolvesToContainerType(node) {
                 current = operator.typeAnnotation;
                 continue;
             }
+            case utils_1.AST_NODE_TYPES.TSUnionType: {
+                const union = current;
+                const substantive = union.types.filter((member) => !NULLISH_TYPE_NODES.has(member.type));
+                // `null | undefined` holds no collection at all.
+                if (substantive.length === 0)
+                    return false;
+                // Requiring EVERY remaining member to be a container keeps the
+                // exemption conservative: a mixed union such as `Edge[] | Edge` can hold
+                // a single value, so a plural name there still misleads. Members recurse
+                // with the spent budget so nesting cannot escape the cap.
+                return substantive.every((member) => resolvesToContainerType(member, i + 1));
+            }
             case utils_1.AST_NODE_TYPES.TSTypeReference: {
                 const ref = current;
                 if (ref.typeName.type !== utils_1.AST_NODE_TYPES.Identifier)

package/lib/rules/prefer-type-over-interface.js

@@ -2,6 +2,51 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.preferTypeOverInterface = void 0;
 const createRule_1 = require("../utils/createRule");
+const utils_1 = require("@typescript-eslint/utils");
+/**
+ * A module augmentation targets either an external module
+ * (`declare module 'pkg'`, whose id is a string literal) or the global scope
+ * (`declare global`). Declaration merging is the whole point of such a block
+ * and only `interface` can merge, so the `type` rewrite does not merely change
+ * style: it drops the augmentation and collides with the original declaration
+ * (TS2300 "Duplicate identifier").
+ *
+ * A plain `namespace X` — including the ambient `declare namespace X`, whose
+ * id is an identifier — augments nothing, so interfaces inside it stay
+ * reportable and a type alias works there.
+ */
+function isModuleAugmentation(node) {
+    if (node.id.type === utils_1.AST_NODE_TYPES.Literal &&
+        typeof node.id.value === 'string') {
+        return true;
+    }
+    // `declare global` carries a dedicated flag, which also covers the bare
+    // `global { ... }` form nested inside an ambient module (that form has no
+    // `declare` of its own).
+    if (node.global === true) {
+        return true;
+    }
+    // Parser versions that predate the `global` flag spell the same block as an
+    // ambient module whose id is the `global` keyword. Requiring `declare` keeps
+    // an ordinary `namespace global { ... }` reportable.
+    return (node.declare === true &&
+        node.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+        node.id.name === 'global');
+}
+/**
+ * The interface need not be a direct child of the augmentation block; it can
+ * sit inside a nested namespace or any other container within it, so the whole
+ * ancestor chain is inspected.
+ */
+function isInsideModuleAugmentation(node) {
+    for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
+        if (ancestor.type === utils_1.AST_NODE_TYPES.TSModuleDeclaration &&
+            isModuleAugmentation(ancestor)) {
+            return true;
+        }
+    }
+    return false;
+}
 exports.preferTypeOverInterface = (0, createRule_1.createRule)({
     name: 'prefer-type-over-interface',
     meta: {
@@ -22,6 +67,9 @@ exports.preferTypeOverInterface = (0, createRule_1.createRule)({
     create(context) {
         return {
             TSInterfaceDeclaration(node) {
+                if (isInsideModuleAugmentation(node)) {
+                    return;
+                }
                 context.report({
                     node,
                     messageId: 'preferType',

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,32 @@
 [
+  {
+    "version": "1.20.60",
+    "date": "2026-08-01T05:06:58.616Z",
+    "rules": [
+      {
+        "name": "enforce-singular-type-names",
+        "changeType": "fix",
+        "issues": [
+          1550
+        ],
+        "summary": "keep the container exemption when nullable (closes #1550)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.59",
+    "date": "2026-08-01T04:43:54.837Z",
+    "rules": [
+      {
+        "name": "prefer-type-over-interface",
+        "changeType": "fix",
+        "issues": [
+          1549
+        ],
+        "summary": "exempt module augmentations (closes #1549)"
+      }
+    ]
+  },
   {
     "version": "1.20.58",
     "date": "2026-08-01T04:26:49.434Z",