@blumintinc/eslint-plugin-blumint 1.20.175 → 1.20.177

package/lib/index.js

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

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

@@ -1302,11 +1302,18 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
          * position the author wrote it, and hands assertSafe what it produces — the
          * rewrite adds a validation, it does not move a dereference.
          *
-         * A key written without a wrapper keeps the narrower argument the fix has
-         * always emitted: `String(id)` and `` `${id}` `` collapse to `id`, whose
-         * conversion assertSafe subsumes.
+         * A coercion the author wrote is part of the key, so it is wrapped rather
+         * than replaced: `assertSafe(String(id))` and ``assertSafe(`${id}`)``, not
+         * `assertSafe(id)`. assertSafe VALIDATES a key, it does not coerce one —
+         * it throws on any argument whose `typeof` is neither `string` nor
+         * `number` — so dropping the `String()` call or the template hands it the
+         * raw operand and changes what the key evaluates to. A boolean operand
+         * turns a working `` record[`${flag}`] `` lookup into a throw (#2144).
+         * Wrapping the key exactly as written is also what makes the sole
+         * substitution behave like every other template: `` `${a}${b}` `` has
+         * always been wrapped whole.
          */
-        const reportWrittenKey = (written, unwrapped, innerText) => reportUseAssertSafe(written, written === unwrapped ? innerText : context.sourceCode.getText(written));
+        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)`.
@@ -1830,9 +1837,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                     if (key.type === utils_1.AST_NODE_TYPES.CallExpression &&
                         key.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
                         key.callee.name === 'String') {
-                        const arg = key.arguments[0];
-                        const argText = context.sourceCode.getText(arg);
-                        reportWrittenKey(written, key, argText);
+                        reportWrittenKey(written);
                     }
                     // Check for template literals like `${id}`
                     if (key.type === utils_1.AST_NODE_TYPES.TemplateLiteral &&
@@ -1840,9 +1845,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         key.quasis.length === 2 &&
                         key.quasis[0].value.raw === '' &&
                         key.quasis[1].value.raw === '') {
-                        const expr = key.expressions[0];
-                        const exprText = context.sourceCode.getText(expr);
-                        reportWrittenKey(written, key, exprText);
+                        reportWrittenKey(written);
                     }
                 }
             },
@@ -1855,9 +1858,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                     if (left.type === utils_1.AST_NODE_TYPES.CallExpression &&
                         left.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
                         left.callee.name === 'String') {
-                        const arg = left.arguments[0];
-                        const argText = context.sourceCode.getText(arg);
-                        reportWrittenKey(written, left, argText);
+                        reportWrittenKey(written);
                     }
                     // Check for template literals like `${id}`
                     if (left.type === utils_1.AST_NODE_TYPES.TemplateLiteral &&
@@ -1865,9 +1866,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         left.quasis.length === 2 &&
                         left.quasis[0].value.raw === '' &&
                         left.quasis[1].value.raw === '') {
-                        const expr = left.expressions[0];
-                        const exprText = context.sourceCode.getText(expr);
-                        reportWrittenKey(written, left, exprText);
+                        reportWrittenKey(written);
                     }
                 }
             },
@@ -1909,9 +1908,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                     if (property.type === utils_1.AST_NODE_TYPES.CallExpression &&
                         property.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
                         property.callee.name === 'String') {
-                        const arg = property.arguments[0];
-                        const argText = context.sourceCode.getText(arg);
-                        reportWrittenKey(written, property, argText);
+                        reportWrittenKey(written);
                         return;
                     }
                     // Check for template literals
@@ -1935,19 +1932,14 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (!reachesPrototype) {
                             return;
                         }
-                        // `${id}` alone is the whole key, so the remedy names the inner
-                        // expression and the fix wraps it directly. A template carrying
-                        // fixed text has no such inner key — the string it builds is the
-                        // key — so that whole template is what gets wrapped, which is the
-                        // shape the docs show for `assertSafe(`${id}_suffix`)`.
-                        const isSimpleVarInterpolation = property.expressions.length === 1 &&
-                            property.quasis.length === 2 &&
-                            property.quasis[0].value.raw === '' &&
-                            property.quasis[1].value.raw === '';
-                        const unwrapped = isSimpleVarInterpolation
-                            ? property.expressions[0]
-                            : property;
-                        reportWrittenKey(written, property, context.sourceCode.getText(unwrapped));
+                        // The string the template builds is the key, whether it carries
+                        // fixed text or is a lone substitution, so the whole template is
+                        // what gets wrapped — the shape the docs show for
+                        // `assertSafe(`${id}_suffix`)`. Reaching inside for `${id}` would
+                        // hand assertSafe the operand instead of the string the operand
+                        // widens to, and assertSafe throws on anything that is not already
+                        // a string or a number (#2144).
+                        reportWrittenKey(written);
                         return;
                     }
                     // Check for direct variable usage (identifiers)
@@ -1971,8 +1963,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (isCompilerBoundedLookup(node, property)) {
                             return;
                         }
-                        const propText = context.sourceCode.getText(property);
-                        reportWrittenKey(written, property, propText);
+                        reportWrittenKey(written);
                         return;
                     }
                     // Check for binary expressions (like index + 1)
@@ -1981,8 +1972,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (isLikelyArray) {
                             return;
                         }
-                        const propText = context.sourceCode.getText(property);
-                        reportWrittenKey(written, property, propText);
+                        reportWrittenKey(written);
                         return;
                     }
                     // Check for boolean expressions and other literals
@@ -1993,8 +1983,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (isLikelyArray) {
                             return;
                         }
-                        const propText = context.sourceCode.getText(property);
-                        reportWrittenKey(written, property, propText);
+                        reportWrittenKey(written);
                         return;
                     }
                     // Check for function calls (anything that isn't handled above)
@@ -2006,8 +1995,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (isLikelyArray) {
                             return;
                         }
-                        const propText = context.sourceCode.getText(property);
-                        reportWrittenKey(written, property, propText);
+                        reportWrittenKey(written);
                         return;
                     }
                 }

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

@@ -41,6 +41,141 @@ const NON_PLURALIZABLE_SUFFIXES = [
  * the reference itself as a container.
  */
 const ARRAY_GENERIC_NAMES = new Set(['Array', 'ReadonlyArray']);
+/**
+ * Word-final suffixes that are singular by shape. No English plural ends in
+ * `-sis` or `-ss`, so both classes are exempt wholesale rather than enumerated:
+ * every `-sis` noun (`Analysis`, `Basis`, `Thesis`, `Diagnosis`, `Synopsis`,
+ * `Chassis`) and every `-ss` noun (`Address`, `Progress`, `Class`, `Success`)
+ * is covered, including ones no list would anticipate.
+ *
+ * The neighbouring `-is`/`-us`/`-os` classes get no such blanket rule, because
+ * genuine plurals do end that way — `Emojis`, `Minis`, `Menus`, `Plateaus`,
+ * `Taxis`. Exempting those by shape would silence the rule on real collection
+ * names, so they are enumerated in SINGULAR_NOUNS_ENDING_IN_S instead.
+ */
+const SINGULAR_WORD_SUFFIXES = ['sis', 'ss'];
+/**
+ * Singular nouns that end in `s` and that `pluralize` mistakes for plurals.
+ * Stripping the trailing `s` yields a non-word — `Axis` → `Axi`, `Lens` →
+ * `Len`, `Chaos` → `Chao` — which is the tell that the identifier was singular
+ * all along. Enumeration is the only safe discriminator here: `Axis` and
+ * `Minis` share a shape, so nothing but the noun itself separates a Latin/Greek
+ * singular from an ordinary plural.
+ *
+ * Entries `pluralize` already classifies correctly (`Status`, `Corpus`) are
+ * listed too, so a change in that library's heuristics cannot quietly
+ * reintroduce the false positive.
+ */
+const SINGULAR_NOUNS_ENDING_IN_S = new Set([
+    // Latin/Greek `-is` singulars outside the `-sis` family above.
+    'axis',
+    'praxis',
+    'prophylaxis',
+    'aegis',
+    'cannabis',
+    'chrysalis',
+    'clematis',
+    'dais',
+    'dermis',
+    'epidermis',
+    'epiglottis',
+    'glottis',
+    'hubris',
+    'ibis',
+    'iris',
+    'mantis',
+    'marquis',
+    'megalopolis',
+    'metropolis',
+    'pelvis',
+    'portcullis',
+    'proboscis',
+    'tennis',
+    'trellis',
+    // `-us` singulars.
+    'alumnus',
+    'apparatus',
+    'bonus',
+    'bus',
+    'cactus',
+    'campus',
+    'census',
+    'chorus',
+    'consensus',
+    'corpus',
+    'exodus',
+    'focus',
+    'fungus',
+    'genus',
+    'hiatus',
+    'impetus',
+    'locus',
+    'minus',
+    'modulus',
+    'nexus',
+    'nucleus',
+    'octopus',
+    'opus',
+    'plus',
+    'prospectus',
+    'radius',
+    'sinus',
+    'status',
+    'stimulus',
+    'surplus',
+    'syllabus',
+    'terminus',
+    'thesaurus',
+    'versus',
+    'virus',
+    // Remaining singular nouns ending in `s`.
+    'alias',
+    'apropos',
+    'asbestos',
+    'atlas',
+    'bias',
+    'canvas',
+    'chaos',
+    'cosmos',
+    'ethos',
+    'fracas',
+    'gas',
+    'kudos',
+    'lens',
+    'news',
+    'pancreas',
+    'pathos',
+    'rhinoceros',
+    'series',
+    'species',
+    'thermos',
+]);
+/**
+ * Splits a PascalCase/camelCase identifier into its words, keeping an
+ * all-caps run together: `DeferAxis` → `Defer`/`Axis`, `HTTPStatus` →
+ * `HTTP`/`Status`.
+ */
+const IDENTIFIER_WORD_PATTERN = /[A-Z]+(?![a-z])|[A-Z]?[a-z0-9]+/g;
+/**
+ * The exemption keys on the identifier's FINAL word rather than the whole
+ * identifier so it composes with any prefix: `Axis`, `DeferAxis` and
+ * `ChartRenderAxis` all resolve to `axis`. Whole-identifier matching would
+ * exempt only the bare noun and keep reporting every compound built on it.
+ */
+function trailingWordOf(name) {
+    const words = name.match(IDENTIFIER_WORD_PATTERN);
+    return (words?.[words.length - 1] ?? name).toLowerCase();
+}
+/**
+ * True when the identifier's final word is a singular noun that merely ends in
+ * `s`. Checked before `pluralize`, whose naive trailing-`s` strip is what
+ * misreads these nouns in the first place.
+ */
+function endsWithSingularNoun(name) {
+    const trailingWord = trailingWordOf(name);
+    return (SINGULAR_NOUNS_ENDING_IN_S.has(trailingWord) ||
+        SINGULAR_WORD_SUFFIXES.some((suffix) => trailingWord.endsWith(suffix)));
+}
 /**
  * Union members that only express absence. Stripping them keeps a nullable
  * container recognisable as a container: `T[]` and `T[] | null` describe the
@@ -137,6 +272,11 @@ exports.enforceSingularTypeNames = (0, createRule_1.createRule)({
             // Skip checking if name ends with 'Props', 'Params', 'Data', etc.
             if (NON_PLURALIZABLE_SUFFIXES.some((suffix) => name.toLowerCase().endsWith(suffix.toLowerCase())))
                 return false;
+            // Singular nouns that end in `s` must be settled BEFORE pluralize sees
+            // them: its trailing-`s` strip turns `DeferAxis` into the non-word
+            // `DeferAxi` and reports a rename to it.
+            if (endsWithSingularNoun(name))
+                return false;
             // Skip checking if name is already singular according to pluralize
             if (pluralize.isSingular(name))
                 return false;

package/lib/rules/jsdoc-above-field.js

@@ -108,22 +108,62 @@ exports.jsdocAboveField = (0, createRule_1.createRule)({
                     : node.range[1],
             };
         };
+        const containerOf = (node) => {
+            const parent = node.parent;
+            if (parent?.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
+                return { node: parent, members: parent.members, separator: ';' };
+            }
+            if (parent?.type === utils_1.AST_NODE_TYPES.TSInterfaceBody) {
+                return { node: parent, members: parent.body, separator: ';' };
+            }
+            if (parent?.type === utils_1.AST_NODE_TYPES.ClassBody) {
+                return { node: parent, members: parent.body, separator: ';' };
+            }
+            if (parent?.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                return { node: parent, members: parent.properties, separator: ',' };
+            }
+            return undefined;
+        };
+        /**
+         * Whether nothing but the container's closing brace follows the block, so
+         * the field it trails is the only member it can belong to.
+         */
+        const closesContainer = (node, comment) => {
+            const container = containerOf(node);
+            if (!container) {
+                return false;
+            }
+            const closeBrace = sourceCode.getLastToken(container.node);
+            if (!closeBrace || comment.range[1] > closeBrace.range[0]) {
+                return false;
+            }
+            return !container.members.some((member) => member.range[0] >= comment.range[1]);
+        };
         /**
          * Attaches a trailing JSDoc block by token order rather than by line.
          *
-         * Prettier reflows a multi-line block that trails a field onto its own
-         * line, ahead of the member's separator: the block that followed
-         * `timeout: number;` ends up between `timeout: number` and its `;`. Keying
-         * on the comment sharing the field's line makes the rule inert on exactly
-         * the formatted source it has to police, so a block the separator still
-         * follows counts as this member's however many lines down it starts.
+         * Prettier is not idempotent on a multi-line block that trails a field. One
+         * pass reflows it onto its own line ahead of the member's separator, so the
+         * block that followed `timeout: number;` sits between `timeout: number` and
+         * its `;`; the next pass moves the separator back in front of it, and that
+         * separator-first spelling is the fixed point formatted source converges
+         * to. Both intermediates and the fixed point document the field above them,
+         * so keying on the comment sharing the field's line — or on the separator
+         * still following it — leaves the rule inert on the shape it exists to
+         * police.
+         *
+         * Past the separator the member has ended and position alone stops naming
+         * an owner: an own-line block there reads as the leading documentation of
+         * the next field. That reading needs a next field, so it is unavailable on
+         * the last member of a container, where the preceding field is the only
+         * candidate left.
          *
-         * Past the separator the member has ended and position alone no longer
-         * identifies an owner: an own-line block there is the leading documentation
-         * of the next field, or a note about the enclosing shape. Only the same-line
-         * spelling can be claimed there, which is why that arm survives.
+         * A blank line is the one signal that survives the round trip intact:
+         * prettier preserves an authored one and never inserts one while reflowing,
+         * so a block held off by an empty line is a deliberate note about the
+         * enclosing shape rather than displaced documentation.
          */
-        const trailingJSDocFor = (span) => {
+        const trailingJSDocFor = (node, span) => {
             return allComments.find((comment) => {
                 if (!isJSDocBlock(comment)) {
                     return false;
@@ -131,11 +171,13 @@ exports.jsdocAboveField = (0, createRule_1.createRule)({
                 if (comment.range[0] < span.offset) {
                     return false;
                 }
+                const between = sourceCode.text.slice(span.offset, comment.range[0]);
                 const precedesSeparator = comment.range[1] <= span.separatorEnd;
                 if (!precedesSeparator && comment.loc.start.line !== span.line) {
-                    return false;
+                    if (!closesContainer(node, comment) || /\n[^\S\n]*\n/.test(between)) {
+                        return false;
+                    }
                 }
-                const between = sourceCode.text.slice(span.offset, comment.range[0]);
                 return /^[\s;,]*$/.test(between);
             });
         };
@@ -236,22 +278,6 @@ exports.jsdocAboveField = (0, createRule_1.createRule)({
          */
         const lineIndentOf = (node) => /^[ \t]*/.exec(sourceCode.lines[node.loc.start.line - 1] ?? '')?.[0] ??
             '';
-        const containerOf = (node) => {
-            const parent = node.parent;
-            if (parent?.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
-                return { node: parent, members: parent.members, separator: ';' };
-            }
-            if (parent?.type === utils_1.AST_NODE_TYPES.TSInterfaceBody) {
-                return { node: parent, members: parent.body, separator: ';' };
-            }
-            if (parent?.type === utils_1.AST_NODE_TYPES.ClassBody) {
-                return { node: parent, members: parent.body, separator: ';' };
-            }
-            if (parent?.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
-                return { node: parent, members: parent.properties, separator: ',' };
-            }
-            return undefined;
-        };
         /**
          * A member's separator sits inside its range for type and class members
          * but outside it for object literal properties, so both spellings have to
@@ -314,7 +340,7 @@ exports.jsdocAboveField = (0, createRule_1.createRule)({
                     jsdoc: member === node
                         ? comment
                         : isRelevantNode(member)
-                            ? trailingJSDocFor(fieldSpanOf(member))
+                            ? trailingJSDocFor(member, fieldSpanOf(member))
                             : undefined,
                 };
             });
@@ -420,7 +446,7 @@ exports.jsdocAboveField = (0, createRule_1.createRule)({
                 return;
             }
             const span = fieldSpanOf(node);
-            const jsdocComment = trailingJSDocFor(span);
+            const jsdocComment = trailingJSDocFor(node, span);
             if (!jsdocComment) {
                 return;
             }

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "1.20.177",
+    "date": "2026-08-26T16:36:01.459Z",
+    "rules": [
+      {
+        "name": "jsdoc-above-field",
+        "changeType": "fix",
+        "issues": [
+          2145
+        ],
+        "summary": "claim a trailing block that closes its container (closes #2145)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.176",
+    "date": "2026-08-26T11:56:32.903Z",
+    "rules": [
+      {
+        "name": "enforce-assert-safe-object-key",
+        "changeType": "fix",
+        "issues": [
+          2144
+        ],
+        "summary": "wrap a coerced key instead of replacing it (closes #2144)"
+      },
+      {
+        "name": "enforce-singular-type-names",
+        "changeType": "fix",
+        "issues": [
+          2143
+        ],
+        "summary": "exempt singular nouns that merely end in s (closes #2143)"
+      }
+    ]
+  },
   {
     "version": "1.20.175",
     "date": "2026-08-26T06:19:14.998Z",