@blumintinc/eslint-plugin-blumint 1.20.193 → 1.20.195

package/lib/index.js

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

package/lib/rules/enforce-typescript-markdown-code-blocks.js

@@ -16,6 +16,10 @@ const MIN_FENCE_LENGTH = 3;
 const MAX_FENCE_INDENT_COLUMNS = 3;
 /** CommonMark advances a tab to the next multiple of four when measuring indent. */
 const TAB_STOP = 4;
+/** The three bullet characters CommonMark accepts for an unordered list item. */
+const BULLET_MARKERS = new Set(['-', '+', '*']);
+/** CommonMark caps an ordered list marker at nine digits before its delimiter. */
+const MAX_ORDERED_MARKER_DIGITS = 9;
 function splitLines(text) {
     const lines = [];
     let start = 0;
@@ -72,6 +76,106 @@ function readFence(line) {
         infoString: line.text.slice(offset + runLength),
     };
 }
+/**
+ * Reads the list marker at `offset`, including the whitespace that separates
+ * it from the item's content, or 0 when no marker starts there. CommonMark
+ * requires that separator, which is what keeps `*emphasis*` and the thematic
+ * break `***` from reading as list items.
+ */
+function readListMarker(text, offset) {
+    let cursor = offset;
+    const char = text[cursor];
+    if (char !== undefined && BULLET_MARKERS.has(char)) {
+        cursor += 1;
+    }
+    else {
+        let digits = 0;
+        while (digits < MAX_ORDERED_MARKER_DIGITS &&
+            text[cursor + digits] >= '0' &&
+            text[cursor + digits] <= '9') {
+            digits += 1;
+        }
+        const delimiter = text[cursor + digits];
+        if (digits === 0 || (delimiter !== '.' && delimiter !== ')')) {
+            return 0;
+        }
+        cursor += digits + 1;
+    }
+    if (text[cursor] !== ' ' && text[cursor] !== '\t') {
+        return 0;
+    }
+    while (text[cursor] === ' ' || text[cursor] === '\t') {
+        cursor += 1;
+    }
+    return cursor - offset;
+}
+/**
+ * Reads a fence opened on the same line as one or more list markers, as in
+ * "- ```ts". A list item's content begins after its marker, so the backticks
+ * open a block there exactly as they would at the head of a line.
+ *
+ * `readFence` cannot see one, because it stops at the first character that is
+ * neither a space nor a tab. Without this the scanner walks INTO such a block
+ * and mistakes its closing fence — which is nothing but spaces and backticks —
+ * for an opening one, appending a language to literal document content.
+ *
+ * The block is skipped whole rather than labeled: a fix would have to be
+ * written past the marker, and labeling a block this rule cannot delimit at
+ * the head of a line is the false-negative direction it deliberately keeps.
+ */
+function readListItemFence(line) {
+    let indentColumns = 0;
+    let offset = 0;
+    let sawMarker = false;
+    for (;;) {
+        while (offset < line.text.length) {
+            const char = line.text[offset];
+            if (char === ' ') {
+                indentColumns += 1;
+            }
+            else if (char === '\t') {
+                indentColumns += TAB_STOP - (indentColumns % TAB_STOP);
+            }
+            else {
+                break;
+            }
+            offset += 1;
+        }
+        if (indentColumns > MAX_FENCE_INDENT_COLUMNS) {
+            return null;
+        }
+        const markerLength = readListMarker(line.text, offset);
+        if (markerLength === 0) {
+            break;
+        }
+        offset += markerLength;
+        // The item's content starts a fresh indent budget, so a fence sitting at
+        // the content column is at indent zero however deep the nesting is.
+        indentColumns = 0;
+        sawMarker = true;
+    }
+    if (!sawMarker) {
+        return null;
+    }
+    const marker = line.text[offset];
+    if (marker !== BACKTICK && marker !== TILDE) {
+        return null;
+    }
+    let runLength = 0;
+    while (line.text[offset + runLength] === marker) {
+        runLength += 1;
+    }
+    if (runLength < MIN_FENCE_LENGTH) {
+        return null;
+    }
+    return {
+        runStart: line.start + offset,
+        marker,
+        runLength,
+        indent: line.text.slice(0, offset),
+        infoString: line.text.slice(offset + runLength),
+    };
+}
 /**
  * The line a block closes on, per CommonMark: a run of at least the opening
  * length, of the SAME marker, at a fence indent, with nothing but whitespace
@@ -131,7 +235,21 @@ exports.enforceTypescriptMarkdownCodeBlocks = (0, createRule_1.createRule)({
                     const openingLine = lines[index];
                     const fence = readFence(openingLine);
                     if (fence === null) {
-                        index += 1;
+                        const listFence = readListItemFence(openingLine);
+                        if (listFence === null) {
+                            index += 1;
+                            continue;
+                        }
+                        // A fence opened on a list marker's line is one this rule declines
+                        // to label, and declining to label a block means declining to read
+                        // it. Skipping it whole is what keeps its closing fence — spaces
+                        // and backticks, indistinguishable from an opener — out of the
+                        // walk.
+                        const listClosing = findFenceCloser(lines, index + 1, listFence);
+                        if (listClosing === null) {
+                            return;
+                        }
+                        index = listClosing.line + 1;
                         continue;
                     }
                     const closing = findFenceCloser(lines, index + 1, fence);

package/lib/rules/no-useless-fragment.js

@@ -3,16 +3,24 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.noUselessFragment = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
+const reactFragmentBinding_1 = require("../utils/reactFragmentBinding");
+const disableDirectives_1 = require("../utils/disableDirectives");
+const importRemoval_1 = require("../utils/importRemoval");
 /**
  * Normalizes JSX child node types into short descriptors used inside lint messages.
  * Keeps message phrasing consistent regardless of the specific child node shape.
+ * A long-form fragment child (`<Fragment>`, `<React.Fragment>`) is described as
+ * a fragment rather than a JSX element so the message reads the same whichever
+ * spelling the nested fragment uses.
  * @param child - The JSX child node to describe.
+ * @param isFragmentElement - Recognizes the long-form fragment spellings.
  * @returns Human-readable descriptor for the child type used in lint messages.
  */
-const describeChild = (child) => {
+const describeChild = (child, isFragmentElement) => {
     switch (child.type) {
         case 'JSXElement':
-            return 'JSX element';
+            return isFragmentElement(child) ? 'fragment' : 'JSX element';
         case 'JSXFragment':
             return 'fragment';
         case 'JSXText':
@@ -112,44 +120,244 @@ const reindentPromotedChild = (sourceCode, fragment, child) => {
     })
         .join('\n');
 };
+/** The opening and closing tag spans of either fragment spelling. */
+const tagRangesOf = (node) => {
+    if (node.type === 'JSXFragment') {
+        return [node.openingFragment.range, node.closingFragment.range];
+    }
+    return node.closingElement
+        ? [node.openingElement.range, node.closingElement.range]
+        : [node.openingElement.range];
+};
+const contains = (outer, inner) => outer[0] <= inner[0] && inner[1] <= outer[1];
+/**
+ * Partitions violations into the sets whose unwraps have to travel together.
+ *
+ * A `Fragment` import read by two useless `<Fragment>` elements is orphaned only
+ * once BOTH are unwrapped, so neither unwrap may drop the import alone — and a
+ * fix may only count on the other unwrap happening if it performs that unwrap
+ * itself. Fragments that jointly hold a binding alive therefore become one
+ * batch; every other fragment is a batch of one, judged against the file as it
+ * stands. Shorthand `<>` names nothing, so it is never unioned with anything and
+ * keeps fixing independently.
+ *
+ * EVERY binding is asked about, not the imported ones alone, so that a binding
+ * no fix asks about cannot end up owned by none of them.
+ */
+function batchViolations(source, violations) {
+    const parents = violations.map((_violation, index) => index);
+    const find = (index) => {
+        let current = index;
+        while (parents[current] !== current) {
+            parents[current] = parents[parents[current]];
+            current = parents[current];
+        }
+        return current;
+    };
+    const union = (left, right) => {
+        const rootLeft = find(left);
+        const rootRight = find(right);
+        if (rootLeft !== rootRight) {
+            parents[rootRight] = rootLeft;
+        }
+    };
+    const ownerOf = (use) => violations.findIndex(({ tags }) => tags.some((tag) => use[0] >= tag[0] && use[1] <= tag[1]));
+    for (const { uses } of (0, importRemoval_1.bindingUses)(source)) {
+        if (uses.length < 2)
+            continue;
+        const owners = new Set();
+        const escapes = uses.some((use) => {
+            const owner = ownerOf(use);
+            if (owner === -1)
+                return true;
+            owners.add(owner);
+            return false;
+        });
+        // A use outside every unwrap keeps the binding alive whatever these fixes
+        // do, so their fixes owe each other nothing.
+        if (escapes || owners.size < 2)
+            continue;
+        const [first, ...rest] = [...owners];
+        for (const other of rest) {
+            union(first, other);
+        }
+    }
+    const groups = new Map();
+    violations.forEach((violation, index) => {
+        const root = find(index);
+        const group = groups.get(root);
+        if (group) {
+            group.push(violation);
+        }
+        else {
+            groups.set(root, [violation]);
+        }
+    });
+    return [...groups.values()];
+}
+/**
+ * The unwraps `batch` performs plus the import specifiers they leave bound to
+ * nothing. `null` when an orphan cannot be unbound safely — an import behind a
+ * directive comment, say — in which case the caller keeps the report and drops
+ * the fix, because unwrapping while leaving the import behind turns a clean file
+ * into one that fails `no-unused-vars`.
+ */
+function planBatch(source, batch) {
+    const unwraps = batch.map((violation) => ({
+        node: violation.node,
+        // Only fixable violations reach a plan, so the replacement is present.
+        text: violation.replacement,
+    }));
+    const cleanups = (0, importRemoval_1.planOrphanedImportRemoval)(source, batch.flatMap((violation) => violation.tags));
+    return cleanups ? { unwraps, cleanups } : null;
+}
 exports.noUselessFragment = (0, createRule_1.createRule)({
     name: 'no-useless-fragment',
     create(context) {
+        const sourceCode = context.sourceCode;
+        /**
+         * Long-form fragments are recognized through the element's own scope, so a
+         * `Fragment` shadowed by a local component is not mistaken for react's.
+         */
+        const isFragmentElement = (element) => (0, reactFragmentBinding_1.isReactFragmentElement)(element, (node) => ASTHelpers_1.ASTHelpers.getScope(context, node));
+        /**
+         * Fragments held until `Program:exit`. Whether an unwrap strands the import
+         * that names the fragment is a whole-file question, and the answer can only
+         * be given once every fragment reading that import is known.
+         */
+        const violations = [];
+        /**
+         * Whether ESLint will discard a report, resolved the way ESLint resolves it.
+         * A batched fix counts on every unwrap in its batch happening; a suppressed
+         * report never fixes, so its fragment — and the reference its tags hold —
+         * outlives the pass and must not be counted on.
+         */
+        const isSuppressed = (0, disableDirectives_1.createSuppressionChecker)(context);
+        /**
+         * The single decision every fragment spelling shares. `<>`, `<Fragment>`
+         * and `<React.Fragment>` denote the same node, so they are reported and
+         * unwrapped identically; splitting the logic per spelling is what let the
+         * long forms go unexamined in the first place.
+         */
+        const collectWhenUseless = (node) => {
+            const meaningfulChildren = node.children.filter((child) => !isFormattingWhitespace(child));
+            if (meaningfulChildren.length !== 1) {
+                return;
+            }
+            const [child] = meaningfulChildren;
+            /**
+             * A fragment whose only child is an expression container — e.g.
+             * `<>{portal}</>` — is NOT useless. Unwrapping it to a bare
+             * `{portal}` is invalid in statement/return position, and wrapping a
+             * single ReactNode expression in a fragment is the idiomatic way to
+             * render it. (Mirrors the upstream rule's `allowExpressions`.)
+             */
+            if (child.type === 'JSXExpressionContainer') {
+                return;
+            }
+            /**
+             * Unwrapping is only sound when the child is itself standalone JSX.
+             * A text child (`<>hello</>`) would become a bare identifier
+             * reference, and a spread child (`<>{...items}</>`) is not a valid
+             * expression on its own — both are report-only so the developer
+             * chooses how to restructure the surrounding code.
+             */
+            const isFixable = child.type === 'JSXElement' || child.type === 'JSXFragment';
+            violations.push({
+                node,
+                childKind: describeChild(child, isFragmentElement),
+                replacement: isFixable
+                    ? reindentPromotedChild(sourceCode, node, child)
+                    : null,
+                tags: tagRangesOf(node),
+            });
+        };
         return {
             JSXFragment(node) {
-                const meaningfulChildren = node.children.filter((child) => !isFormattingWhitespace(child));
-                if (meaningfulChildren.length !== 1) {
+                collectWhenUseless(node);
+            },
+            JSXElement(node) {
+                if (!isFragmentElement(node)) {
                     return;
                 }
-                const [child] = meaningfulChildren;
                 /**
-                 * A fragment whose only child is an expression container — e.g.
-                 * `<>{portal}</>` — is NOT useless. Unwrapping it to a bare
-                 * `{portal}` is invalid in statement/return position, and wrapping a
-                 * single ReactNode expression in a fragment is the idiomatic way to
-                 * render it. (Mirrors the upstream rule's `allowExpressions`.)
+                 * An attribute is content the shorthand cannot carry: `key` positions
+                 * the fragment in a sibling list, and unwrapping would move it onto
+                 * the promoted child, changing reconciliation. Only the long forms can
+                 * reach this branch, since `<>` admits no attributes at all.
                  */
-                if (child.type === 'JSXExpressionContainer') {
+                if (node.openingElement.attributes.length > 0) {
                     return;
                 }
+                collectWhenUseless(node);
+            },
+            /**
+             * Emits every held report, each carrying the import cleanup its own
+             * unwrap makes necessary.
+             *
+             * Orphanhood is judged against a single fix's own deletions, never
+             * against what sibling reports might also delete: ESLint may discard a
+             * sibling, and the fragment it was going to unwrap then keeps the import
+             * alive.
+             */
+            'Program:exit'() {
+                if (violations.length === 0)
+                    return;
                 /**
-                 * Unwrapping is only sound when the child is itself standalone JSX.
-                 * A text child (`<>hello</>`) would become a bare identifier
-                 * reference, and a spread child (`<>{...items}</>`) is not a valid
-                 * expression on its own — both are report-only so the developer
-                 * chooses how to restructure the surrounding code.
+                 * A fragment nested inside another fragment being unwrapped is left out
+                 * of the batching. Its tags are carried into the outer fragment's
+                 * replacement text verbatim, so its reference SURVIVES that fix — and
+                 * the two replacements would overlap besides. The outer unwrap then
+                 * finds the import still in use and leaves it, and the next `--fix`
+                 * pass unwraps what is by then a lone fragment and takes the import
+                 * with it.
                  */
-                const isFixable = child.type === 'JSXElement' || child.type === 'JSXFragment';
-                context.report({
-                    node,
-                    messageId: 'noUselessFragment',
-                    data: {
-                        childKind: describeChild(child),
-                    },
-                    fix: isFixable
-                        ? (fixer) => fixer.replaceText(node, reindentPromotedChild(context.sourceCode, node, child))
-                        : null,
-                });
+                const unwrapping = violations.filter((violation) => violation.replacement !== null && !isSuppressed(violation.node));
+                const batchable = unwrapping.filter((violation) => !unwrapping.some((other) => other !== violation &&
+                    contains(other.node.range, violation.node.range)));
+                const batchableSet = new Set(batchable);
+                const plans = new Map();
+                for (const batch of batchViolations(sourceCode, batchable)) {
+                    const plan = planBatch(sourceCode, batch);
+                    if (!plan)
+                        continue;
+                    for (const violation of batch) {
+                        plans.set(violation, plan);
+                    }
+                }
+                for (const violation of violations) {
+                    /**
+                     * A fixable fragment the batching left out fixes on its own. It is
+                     * nested inside another fragment being unwrapped — so its tags are
+                     * carried into that fragment's replacement rather than deleted, and
+                     * strand nothing — or it is suppressed, in which case ESLint discards
+                     * the report and the fix never runs. A fragment that WAS batched and
+                     * whose batch declined gets no fix at all, which is the whole point of
+                     * the decline.
+                     */
+                    const own = violation.replacement !== null && !batchableSet.has(violation)
+                        ? {
+                            unwraps: [
+                                { node: violation.node, text: violation.replacement },
+                            ],
+                            cleanups: [],
+                        }
+                        : null;
+                    const applied = plans.get(violation) ?? own;
+                    context.report({
+                        node: violation.node,
+                        messageId: 'noUselessFragment',
+                        data: { childKind: violation.childKind },
+                        ...(applied
+                            ? {
+                                fix: (fixer) => [
+                                    ...applied.unwraps.map((unwrap) => fixer.replaceText(unwrap.node, unwrap.text)),
+                                    ...applied.cleanups.map((range) => fixer.removeRange([range[0], range[1]])),
+                                ],
+                            }
+                            : {}),
+                    });
+                }
             },
         };
     },

package/lib/utils/reactFragmentBinding.d.ts

@@ -0,0 +1,27 @@
+import { TSESLint, TSESTree } from '@typescript-eslint/utils';
+/**
+ * Whether every declaration of a visible `Fragment` binding is react's Fragment
+ * import. A const/let/function/class, a parameter, a namespace or default
+ * import, an alias, or a named import from another module all mean the element
+ * spelled `<Fragment>` renders something other than react's Fragment — a
+ * user-defined component a fragment-keyed rule must leave alone.
+ *
+ * An unresolved name is not react's Fragment either: nothing in the file states
+ * what it renders, so counting it would trade a false negative for a false
+ * positive on code the rule cannot see.
+ */
+export declare function bindsReactFragment(variable: TSESLint.Scope.Variable | null): boolean;
+/**
+ * Whether a JSX element is a react fragment written in long form:
+ * `<React.Fragment>` (a member access on the React namespace) or a bare
+ * `<Fragment>` whose name resolves to react's Fragment import. The binding is
+ * resolved from the element's own scope, so a narrower shadow — a component
+ * named `Fragment` declared inside a function — answers false there while a
+ * module-level react import answers true elsewhere in the same file.
+ *
+ * The `React.Fragment` arm does not re-resolve `React`, matching how
+ * `prefer-fragment-shorthand` and `prefer-fragment-component` recognise the
+ * same spelling: a local object named `React` carrying a `Fragment` property is
+ * not a shape worth splitting the rules' answers over.
+ */
+export declare function isReactFragmentElement(element: TSESTree.JSXElement, scopeOf: (node: TSESTree.Node) => TSESLint.Scope.Scope): boolean;

package/lib/utils/reactFragmentBinding.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isReactFragmentElement = exports.bindsReactFragment = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const ASTHelpers_1 = require("./ASTHelpers");
+const REACT_MODULE = 'react';
+const FRAGMENT_NAME = 'Fragment';
+/**
+ * A named specifier that binds `Fragment` under its own name — the only shape
+ * that makes a bare `<Fragment>` element resolve to react's Fragment. An alias
+ * (`import { Fragment as Frag }`) leaves the name free for something else, and
+ * a type-only specifier binds nothing at runtime.
+ */
+function isReactFragmentSpecifier(specifier) {
+    return (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+        specifier.importKind !== 'type' &&
+        specifier.imported.name === FRAGMENT_NAME &&
+        specifier.local.name === FRAGMENT_NAME);
+}
+/**
+ * Whether every declaration of a visible `Fragment` binding is react's Fragment
+ * import. A const/let/function/class, a parameter, a namespace or default
+ * import, an alias, or a named import from another module all mean the element
+ * spelled `<Fragment>` renders something other than react's Fragment — a
+ * user-defined component a fragment-keyed rule must leave alone.
+ *
+ * An unresolved name is not react's Fragment either: nothing in the file states
+ * what it renders, so counting it would trade a false negative for a false
+ * positive on code the rule cannot see.
+ */
+function bindsReactFragment(variable) {
+    return (!!variable &&
+        variable.defs.length > 0 &&
+        variable.defs.every((def) => {
+            const specifier = def.node;
+            if (!isReactFragmentSpecifier(specifier)) {
+                return false;
+            }
+            const declaration = specifier.parent;
+            return (declaration?.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                declaration.importKind !== 'type' &&
+                declaration.source.value === REACT_MODULE);
+        }));
+}
+exports.bindsReactFragment = bindsReactFragment;
+/**
+ * Whether a JSX element is a react fragment written in long form:
+ * `<React.Fragment>` (a member access on the React namespace) or a bare
+ * `<Fragment>` whose name resolves to react's Fragment import. The binding is
+ * resolved from the element's own scope, so a narrower shadow — a component
+ * named `Fragment` declared inside a function — answers false there while a
+ * module-level react import answers true elsewhere in the same file.
+ *
+ * The `React.Fragment` arm does not re-resolve `React`, matching how
+ * `prefer-fragment-shorthand` and `prefer-fragment-component` recognise the
+ * same spelling: a local object named `React` carrying a `Fragment` property is
+ * not a shape worth splitting the rules' answers over.
+ */
+function isReactFragmentElement(element, scopeOf) {
+    const { name } = element.openingElement;
+    if (name.type === utils_1.AST_NODE_TYPES.JSXMemberExpression) {
+        return (name.object.type === utils_1.AST_NODE_TYPES.JSXIdentifier &&
+            name.object.name === 'React' &&
+            name.property.type === utils_1.AST_NODE_TYPES.JSXIdentifier &&
+            name.property.name === FRAGMENT_NAME);
+    }
+    if (name.type !== utils_1.AST_NODE_TYPES.JSXIdentifier ||
+        name.name !== FRAGMENT_NAME) {
+        return false;
+    }
+    return bindsReactFragment(ASTHelpers_1.ASTHelpers.findVariableInScope(scopeOf(element), FRAGMENT_NAME));
+}
+exports.isReactFragmentElement = isReactFragmentElement;
+//# sourceMappingURL=reactFragmentBinding.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.20.193",
+  "version": "1.20.195",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",
@@ -100,6 +100,7 @@
     "js-yaml": "4.3.1",
     "jsonc-eslint-parser": "2.3.0",
     "markdown-eslint-parser": "1.2.1",
+    "marked": "15.0.12",
     "npm-run-all": "4.1.5",
     "prettier": "2.7.1",
     "remark-cli": "10.0.1",

package/release-manifest.json

@@ -1,4 +1,32 @@
 [
+  {
+    "version": "1.20.195",
+    "date": "2026-08-31T00:29:37.037Z",
+    "rules": [
+      {
+        "name": "no-useless-fragment",
+        "changeType": "fix",
+        "issues": [
+          2227
+        ],
+        "summary": "visit JSXElement so long-form fragments are reported (closes #2227)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.194",
+    "date": "2026-08-30T09:11:52.116Z",
+    "rules": [
+      {
+        "name": "enforce-typescript-markdown-code-blocks",
+        "changeType": "fix",
+        "issues": [
+          2220
+        ],
+        "summary": "skip a fence opened on a list marker's line (closes #2220)"
+      }
+    ]
+  },
   {
     "version": "1.20.193",
     "date": "2026-08-30T05:32:04.963Z",