@blumintinc/eslint-plugin-blumint 1.20.141 → 1.20.143

package/lib/index.js

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

package/lib/rules/no-explicit-return-type.js

@@ -846,6 +846,115 @@ function carriedText(source, range) {
             : ' ';
     return `${lead}${body}${trail}`;
 }
+/** Every character the syntactic grammar counts as a LineTerminator. */
+const LINE_TERMINATOR = /[\n\r\u2028\u2029]/;
+const textOf = (source, range) => source.text.slice(range[0], range[1]);
+/**
+ * The span an arrow's return annotation occupies between the parameter list and
+ * the `=>`, together with that arrow token.
+ *
+ * The span holds the annotation, whitespace and comments and nothing else,
+ * which is what makes it safe to rewrite wholesale: no binding reference can
+ * hide in it beyond the ones the annotation itself names.
+ */
+function arrowAnnotationGap(source, returnType) {
+    const parametersEnd = source.getTokenBefore(returnType);
+    const arrow = source.getTokenAfter(returnType, {
+        filter: (token) => token.value === '=>',
+    });
+    if (!parametersEnd || !arrow)
+        return null;
+    const gap = [parametersEnd.range[1], arrow.range[0]];
+    return containsRange(gap, returnType.range) ? { gap, arrow } : null;
+}
+/**
+ * Re-emits `comments` on the far side of the arrow, where a line terminator is
+ * inert, consuming the horizontal whitespace the arrow already had after it so
+ * the body keeps a single separator.
+ */
+function hoistPastArrow(source, arrow, comments) {
+    const indent = indentAt(source, arrow.range[0]);
+    const trailingText = source.text.slice(arrow.range[1]);
+    const [spacing] = /^[ \t]*/.exec(trailingText) ?? [''];
+    const body = (0, replacementSegments_1.joinSegmentBody)(comments.map((comment) => ({
+        text: textOf(source, comment.range),
+        breakAfter: true,
+    })), indent);
+    const rest = trailingText.slice(spacing.length);
+    const separator = LINE_TERMINATOR.test(rest.charAt(0))
+        ? ''
+        : (0, replacementSegments_1.requiresLineBreakAfter)(comments[comments.length - 1])
+            ? `\n${indent}`
+            : ' ';
+    return {
+        range: [arrow.range[1], arrow.range[1] + spacing.length],
+        text: ` ${body}${separator}`,
+    };
+}
+/**
+ * The edits that strip one annotation, carrying every comment the strip
+ * strands rather than deleting it (#1877). `null` withholds the fix, for a
+ * comment whose meaning is its position and which cannot stay where it is.
+ *
+ * An arrow is the one subject whose annotation sits inside a restricted
+ * production: `ArrowParameters [no LineTerminator here] =>` forbids a line
+ * terminator between the parameter list and the arrow, and a block comment
+ * carrying a line terminator IS one to the grammar. A comment left there — or
+ * carried there from inside the annotation — therefore turns the output into a
+ * hard SyntaxError that only V8 reports, since `@typescript-eslint/parser`
+ * accepts it (#1964). Such a comment is re-emitted past the `=>` instead, the
+ * nearest position outside the restricted gap that cannot itself begin one;
+ * hoisting it above the enclosing line would anchor an insertion at a column
+ * zero that may sit inside a template literal or JSX text, where the comment
+ * would become content rather than code.
+ *
+ * Every other subject ends its parameter list at a body or a semicolon, so its
+ * stranded comments stay where they were written.
+ */
+function planAnnotationEdits(source, entry) {
+    const range = entry.returnType.range;
+    if (entry.node.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
+        const carried = carriedText(source, range);
+        return carried === null ? null : [{ range, text: carried }];
+    }
+    const gapInfo = arrowAnnotationGap(source, entry.returnType);
+    if (!gapInfo)
+        return null;
+    const { gap, arrow } = gapInfo;
+    const comments = source
+        .getAllComments()
+        .filter((comment) => containsRange(gap, comment.range));
+    const stranded = comments.filter((comment) => containsRange(range, comment.range));
+    // What the plain deletion would leave between the parameters and the arrow.
+    // A comment left there contributes its own text, so a line comment or a
+    // multi-line block comment shows up here as the line terminator it is.
+    const residue = `${textOf(source, [gap[0], range[0]])}${textOf(source, [
+        range[1],
+        gap[1],
+    ])}`;
+    // The plain deletion is kept wherever it already lands a legal gap and
+    // strands nothing, so no output that survives today moves by a byte.
+    if (stranded.length === 0 && !LINE_TERMINATOR.test(residue)) {
+        return [{ range, text: '' }];
+    }
+    // Rewriting the gap collapses the lines it spanned, which moves the line a
+    // directive inside it points at, so the whole fix is withheld rather than
+    // retargeting one. The gap a directive can share with nothing else is left
+    // untouched by the branch above.
+    if (comments.some(isPositionalDirective))
+        return null;
+    const hoisted = comments.filter(replacementSegments_1.requiresOwnLine);
+    const inline = comments
+        .filter((comment) => !(0, replacementSegments_1.requiresOwnLine)(comment))
+        .map((comment) => textOf(source, comment.range));
+    const edits = [
+        { range: gap, text: inline.length === 0 ? ' ' : ` ${inline.join(' ')} ` },
+    ];
+    if (hoisted.length > 0) {
+        edits.push(hoistPastArrow(source, arrow, hoisted));
+    }
+    return edits;
+}
 /**
  * ESLint applies a fix whole or not at all, and rejects one whose edits
  * overlap. Two spans planned independently — an annotation and the declaration
@@ -866,14 +975,23 @@ function isDisjoint(edits) {
  * outright. The planner computes spans that reach across separators, so a
  * comment among the specifiers sits inside one; declining on that comment is no
  * remedy, since it lets a comment decide whether the annotations are stripped at
- * all, which is a comment changing the transform just the same (#1877).
+ * all, which is a comment changing the transform just the same (#1877). The
+ * annotation spans are carried the same way by {@link planAnnotationEdits},
+ * which additionally answers for the arrow whose annotation sits inside a
+ * restricted production.
  */
 function planRemoval(source, removalSource, batch) {
     const annotations = batch.map((entry) => entry.returnType.range);
     const cleanups = (0, importRemoval_1.planOrphanedBindingRemoval)(removalSource, annotations, (variables, planned) => (0, typeDeclarationRemoval_1.planTypeDeclarationRemoval)(removalSource, variables, planned));
     if (!cleanups)
         return null;
-    const edits = annotations.map((range) => ({ range, text: '' }));
+    const edits = [];
+    for (const entry of batch) {
+        const planned = planAnnotationEdits(source, entry);
+        if (planned === null)
+            return null;
+        edits.push(...planned);
+    }
     for (const range of cleanups) {
         if (removesWholeStatement(source, range)) {
             edits.push({ range, text: '' });

package/lib/rules/no-usememo-for-pass-by-value.js

@@ -551,11 +551,13 @@ exports.noUsememoForPassByValue = (0, createRule_1.createRule)({
                     // line is hoisted onto a full line of its own ABOVE the line the
                     // call starts on. That insertion can never split a token pair, and
                     // it lands a `-next-line` directive exactly one line above the
-                    // statement that now hosts its subject. Everything else stays
-                    // inline: a block comment beside the expression, and a trailing
-                    // line-bound comment followed by a line break, which is safe after
-                    // the expression has begun.
-                    const hoistedComments = leadingComments.filter(replacementSegments_1.requiresLineBreakAfter);
+                    // statement that now hosts its subject. A block comment carrying a
+                    // line terminator demands a line the same way, because the grammar
+                    // reads it AS a line terminator (#1963). Everything else stays
+                    // inline: a single-line block comment beside the expression, and a
+                    // trailing line-bound comment followed by a line break, which is
+                    // safe after the expression has begun.
+                    const hoistedComments = leadingComments.filter(replacementSegments_1.requiresOwnLine);
                     if (hoistedComments.length > 0) {
                         const lineStartIndex = sourceCode.getIndexFromLoc({
                             line: node.loc.start.line,
@@ -571,7 +573,7 @@ exports.noUsememoForPassByValue = (0, createRule_1.createRule)({
                     }
                     const segments = [
                         ...leadingComments
-                            .filter((comment) => !(0, replacementSegments_1.requiresLineBreakAfter)(comment))
+                            .filter((comment) => !(0, replacementSegments_1.requiresOwnLine)(comment))
                             .map(toSegment),
                         { text: replacementText, breakAfter: false },
                         ...trailingComments.map(toSegment),

package/lib/rules/prefer-sx-prop-over-system-props.js

@@ -146,20 +146,37 @@ const DEFAULT_MUI_COMPONENTS = new Set([
     'Toolbar',
 ]);
 /**
- * Components whose public prop API defines `color` as a closed semantic enum
- * (a palette / variant selector like `'primary' | 'secondary' | 'error' | …`),
- * not a CSS-forwarded system style prop. On these, `color` feeds
- * `ownerState.color`, selecting theme variants and MUI's internal
- * `.Mui*-color*` class selectors — moving it into `sx` both drops the variant
- * selection and produces an invalid CSS `color` value. So `color` here is a
- * first-class component prop, never a deprecated system prop.
+ * Props a component declares as its own first-class API, keyed by the
+ * (component, prop) pair. Each name below collides with a system prop, but the
+ * component *consumes* it — feeding `ownerState`, selecting a theme value and
+ * MUI's internal `.Mui*-*` class selectors — instead of forwarding it as CSS.
+ * The system-prop reading is therefore wrong for the pair whatever value is
+ * written, and moving the prop into `sx` emits a declaration whose value is not
+ * a CSS value for that property: the browser drops it, so the fix type-checks
+ * (`SxProps` accepts `string | number`), lints clean, and silently loses the
+ * styling.
+ *
+ * The keying has to be per pair, not per prop name: the same name is a genuine
+ * system prop elsewhere (`color` on `Typography`, `maxWidth` on `Box`), so
+ * exempting the bare name would blind the rule on every other component.
  */
-const COMPONENT_COLOR_IS_SEMANTIC = new Set([
-    'Button',
-    'IconButton',
-    'Chip',
-    'Badge',
+const COMPONENT_OWN_PROPS = new Map([
+    // `color` is a closed palette/variant selector (`'primary' | 'error' | …`)
+    // on these — never a CSS color (#1273). On `AppBar` it picks the *background*
+    // shade, so the system-prop reading also targets the wrong CSS property.
+    ['Button', new Set(['color'])],
+    ['IconButton', new Set(['color'])],
+    ['Chip', new Set(['color'])],
+    ['Badge', new Set(['color'])],
+    ['AppBar', new Set(['color'])],
+    // `maxWidth` is a breakpoint KEY (`'xs' | … | 'xl' | false`) that selects a
+    // width from `theme.breakpoints.values` and drives the `maxWidth*` class
+    // (#1966). As CSS, `max-width: xl` is invalid and the element unbounds.
+    ['Container', new Set(['maxWidth'])],
+    ['Dialog', new Set(['maxWidth'])],
 ]);
+/** True when `propName` belongs to `componentName`'s own prop API. */
+const componentOwnsProp = (componentName, propName) => COMPONENT_OWN_PROPS.get(componentName)?.has(propName) === true;
 /**
  * Props that must never be moved to `sx` because they are genuine component
  * API props, not MUI system styling shorthands. `direction` and `spacing` are
@@ -782,10 +799,10 @@ exports.preferSxPropOverSystemProps = (0, createRule_1.createRule)({
             return false;
         }
         function isSystemProp(name, componentName) {
-            // `color` is a semantic enum prop (not a CSS system prop) on components
-            // like Button/IconButton/Chip/Badge — exempt it there so the autofix
-            // never rewrites a variant selector into an invalid CSS color.
-            if (name === 'color' && COMPONENT_COLOR_IS_SEMANTIC.has(componentName)) {
+            // A prop the component owns is never the system prop of the same name, so
+            // the autofix must not rewrite it into a CSS declaration the browser
+            // discards.
+            if (componentOwnsProp(componentName, name)) {
                 return false;
             }
             return MUI_SYSTEM_PROPS.has(name) && !isAllowedProp(name);

package/lib/utils/harvestRuleTesterCases.js

@@ -43,7 +43,30 @@ const TESTS_DIR = path.join(__dirname, '..', 'tests');
  * (`const jsx = ruleTesterJsx`) before calling `run`, so a call-site pattern
  * drops it.
  */
-exports.IMPORTS_SHARED_TESTER = /from\s+'\.\.\/utils\/ruleTester'/;
+exports.IMPORTS_SHARED_TESTER = /from\s+'(?:\.\.\/)+utils\/ruleTester'/;
+/**
+ * Every suite file under the tests root, as a path relative to it.
+ *
+ * The enumeration is recursive because a suite in a subdirectory is still a
+ * suite: `src/tests/rules/` holds three that jest runs and that every
+ * harvest-based gate used to miss, while their rules' top-level namesakes kept
+ * the per-rule closure green — so the gap read as coverage from every angle
+ * that was checked.
+ *
+ * Paths stay relative rather than collapsing to a basename so that two suites
+ * with the same name (`no-circular-references.test.ts` exists at both depths)
+ * remain distinguishable, which is what keeps a per-file baseline or a dedupe
+ * key from silently merging them.
+ */
+function suiteFilesUnder(root) {
+    const walk = (dir) => fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            return walk(full);
+        return entry.name.endsWith('.test.ts') ? [path.relative(root, full)] : [];
+    });
+    return walk(root).sort();
+}
 /**
  * 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
@@ -156,10 +179,7 @@ function harvestRuleTesterCases() {
     const realCwd = process.cwd();
     process.chdir(scratchRoot);
     try {
-        const files = fs
-            .readdirSync(TESTS_DIR)
-            .filter((file) => file.endsWith('.test.ts'))
-            .sort();
+        const files = suiteFilesUnder(TESTS_DIR);
         for (const file of files) {
             const fullPath = path.join(TESTS_DIR, file);
             if (!exports.IMPORTS_SHARED_TESTER.test(fs.readFileSync(fullPath, 'utf8'))) {

package/lib/utils/replacementSegments.d.ts

@@ -16,6 +16,25 @@ import { TSESTree } from '@typescript-eslint/utils';
  * silently retarget one line past its subject.
  */
 export declare function requiresLineBreakAfter(comment: TSESTree.Comment): boolean;
+/**
+ * A comment that cannot be folded onto the code that follows it, so a fixer
+ * placing it ahead of an expression must give it a line of its own.
+ *
+ * Two kinds qualify. One is the line-bound comment {@link requiresLineBreakAfter}
+ * describes, whose meaning is tied to the line it occupies. The other is a block
+ * comment containing a line terminator: the syntactic grammar treats such a
+ * comment as a LineTerminator in its own right, so it triggers every restricted
+ * production a raw newline would. Measured with `node --check`, a block comment
+ * on one line between arrow parameters and their arrow parses, while the same
+ * comment broken across two lines is a SyntaxError; ahead of a `return`
+ * argument, the multi-line form is worse still — it parses, and ASI silently
+ * replaces the returned value with `undefined` (#1963).
+ *
+ * Only fixers emitting text where a newline is meaningful need this;
+ * a replacement wrapped in parentheses can never trip a restricted production
+ * and can keep such a comment inline.
+ */
+export declare function requiresOwnLine(comment: TSESTree.Comment): boolean;
 export type ReplacementSegment = {
     text: string;
     breakAfter: boolean;

package/lib/utils/replacementSegments.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.joinSegments = exports.joinSegmentBody = exports.requiresLineBreakAfter = void 0;
+exports.joinSegments = exports.joinSegmentBody = exports.requiresOwnLine = exports.requiresLineBreakAfter = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const disableDirectives_1 = require("./disableDirectives");
 /**
@@ -26,6 +26,35 @@ function requiresLineBreakAfter(comment) {
     return (0, disableDirectives_1.parseDisableDirectives)([comment]).some((directive) => directive.kind === 'disable-next-line');
 }
 exports.requiresLineBreakAfter = requiresLineBreakAfter;
+/**
+ * Whether a comment's own text carries a line terminator, which only a block
+ * comment can do.
+ */
+function spansMultipleLines(comment) {
+    return comment.loc.start.line !== comment.loc.end.line;
+}
+/**
+ * A comment that cannot be folded onto the code that follows it, so a fixer
+ * placing it ahead of an expression must give it a line of its own.
+ *
+ * Two kinds qualify. One is the line-bound comment {@link requiresLineBreakAfter}
+ * describes, whose meaning is tied to the line it occupies. The other is a block
+ * comment containing a line terminator: the syntactic grammar treats such a
+ * comment as a LineTerminator in its own right, so it triggers every restricted
+ * production a raw newline would. Measured with `node --check`, a block comment
+ * on one line between arrow parameters and their arrow parses, while the same
+ * comment broken across two lines is a SyntaxError; ahead of a `return`
+ * argument, the multi-line form is worse still — it parses, and ASI silently
+ * replaces the returned value with `undefined` (#1963).
+ *
+ * Only fixers emitting text where a newline is meaningful need this;
+ * a replacement wrapped in parentheses can never trip a restricted production
+ * and can keep such a comment inline.
+ */
+function requiresOwnLine(comment) {
+    return requiresLineBreakAfter(comment) || spansMultipleLines(comment);
+}
+exports.requiresOwnLine = requiresOwnLine;
 /**
  * Joins the inlined expression and its carried comments into one run of text,
  * keeping each comment on the side of the expression it was written on and

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "1.20.143",
+    "date": "2026-08-12T07:48:25.970Z",
+    "rules": [
+      {
+        "name": "prefer-sx-prop-over-system-props",
+        "changeType": "fix",
+        "issues": [
+          1966
+        ],
+        "summary": "key the exemption on (component, prop) (closes #1966)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.142",
+    "date": "2026-08-12T07:04:58.677Z",
+    "rules": [
+      {
+        "name": "no-explicit-return-type",
+        "changeType": "fix",
+        "issues": [
+          1964
+        ],
+        "summary": "keep the annotation's comments clear of the arrow gap (closes #1964)"
+      },
+      {
+        "name": "no-usememo-for-pass-by-value",
+        "changeType": "fix",
+        "issues": [
+          1963
+        ],
+        "summary": "hoist a carried multi-line comment clear of the return (closes #1963)"
+      }
+    ]
+  },
   {
     "version": "1.20.141",
     "date": "2026-08-12T00:57:09.340Z",