@blumintinc/eslint-plugin-blumint 1.20.196 → 1.20.197

package/lib/index.js

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

package/lib/rules/no-entire-object-hook-deps.js

@@ -1310,6 +1310,46 @@ exports.noEntireObjectHookDeps = (0, createRule_1.createRule)({
             dependencyEntryIdentifiers = entries;
             return entries;
         }
+        /**
+         * Whether a parameter's binding comes out of a DESTRUCTURING pattern - a
+         * destructured prop rather than a positional parameter.
+         *
+         * why: this is the line `noUnusedParameters` draws, measured against the
+         * consumer's own compiler. It reports a destructured property wherever it
+         * sits, including a rest sibling and including an `_`-prefixed one; a
+         * positional parameter it reports only when the name does not start with
+         * `_`. Keying on the pattern rather than on the name is therefore the
+         * accurate test for the destructured case, and `_`-prefixing must NOT be
+         * read as an opt-out there - tsc ignores the name inside a pattern, so
+         * honouring it would readmit the strand on a binding that merely looks
+         * deliberate.
+         *
+         * The AssignmentPattern step is carried but not reachable from the report
+         * path: measured, the rule emits nothing at all for a DEFAULTED
+         * destructured prop (`({ label, revision = 0 })`), so the fixer never gets
+         * to judge one. It stays because dropping it would classify such a prop as
+         * positional the moment that reporting gap is closed, which is the strand
+         * this function exists to prevent - not because a fixture exercises it.
+         */
+        function isDestructuredParameter(name) {
+            if (name.type !== utils_1.AST_NODE_TYPES.Identifier)
+                return false;
+            let node = name.parent;
+            while (node) {
+                if (node.type === utils_1.AST_NODE_TYPES.ObjectPattern ||
+                    node.type === utils_1.AST_NODE_TYPES.ArrayPattern) {
+                    return true;
+                }
+                if (node.type === utils_1.AST_NODE_TYPES.Property ||
+                    node.type === utils_1.AST_NODE_TYPES.RestElement ||
+                    node.type === utils_1.AST_NODE_TYPES.AssignmentPattern) {
+                    node = node.parent;
+                    continue;
+                }
+                return false;
+            }
+            return false;
+        }
         /**
          * Whether removing `element`'s binding from every dependency array that
          * lists it would leave the binding with no reader in the file.
@@ -1336,11 +1376,35 @@ exports.noEntireObjectHookDeps = (0, createRule_1.createRule)({
          * inference is safe in the conservative direction — if a sibling report is
          * suppressed the cost is a withheld fix, never a dangling reference.
          *
-         * Parameters are deliberately exempt. An unread parameter is not an unused
-         * BINDING to either instrument — `no-unused-vars` runs with `args: 'none'`
-         * and `noUnusedLocals` does not cover parameters — so declining there would
-         * withhold a fix without preventing any breakage, and it would silently
-         * settle the reporting question #1621 defers.
+         * A DESTRUCTURED parameter is not exempt; a positional one still is.
+         *
+         * why: the instrument that covers a parameter is `noUnusedParameters`, not
+         * `noUnusedLocals`, and the consumer sets `noUnusedParameters: true` while
+         * setting `noUnusedLocals: false` — so a blanket parameter exemption reads
+         * the one flag the consumer has turned OFF and misses the one it has turned
+         * ON. It also cites `no-unused-vars` with `args: 'none'`, which is not the
+         * consumer's setting either. Stranding a destructured prop is therefore a
+         * red build there, from a `tsc --noEmit` gate, and `no-unused-props` cannot
+         * clean up after this fixer because that rule is report-only.
+         *
+         * Nearly every dependency entry in a React component is a destructured
+         * prop, so this is the common case rather than an edge: 21 composed
+         * findings over 13 distinct fixture shapes, every one of them a
+         * destructured prop this fixer stranded (#2236).
+         *
+         * The POSITIONAL parameter stays exempt, and deliberately so. tsc reports
+         * one too, so this IS a residue — but the composed sweep over 23,785
+         * fixtures reached zero of them on its own, and declining there would
+         * settle the reporting question #1621 defers on unmeasured ground while
+         * withholding fixes the corpus shows to be safe, including the #2208
+         * margin-comment arm whose subject is a positional parameter. The residue
+         * is carried deliberately and it is WITNESSED: the control fixture added
+         * with this fix is now the sweep's only surviving stranded parameter, so
+         * the cost of the exemption is visible in that guard's dump rather than
+         * asserted here and forgotten.
+         *
+         * The report stands either way. Only the rewrite is withheld, which is the
+         * conservative direction the rest of this function already takes.
          */
         function wouldStrandBinding(element) {
             const identifier = unwrapExpression(element);
@@ -1349,7 +1413,9 @@ exports.noEntireObjectHookDeps = (0, createRule_1.createRule)({
             const variable = resolveBinding(identifier);
             if (!variable || variable.defs.length === 0)
                 return false;
-            if (variable.defs.some((def) => def.type === 'Parameter')) {
+            const parameterDefs = variable.defs.filter((def) => def.type === 'Parameter');
+            if (parameterDefs.length === variable.defs.length &&
+                !parameterDefs.some((def) => isDestructuredParameter(def.name))) {
                 return false;
             }
             const entries = collectDependencyEntryIdentifiers();

package/lib/utils/fixtureTypeProgram.d.ts

@@ -256,8 +256,39 @@ export type DiagnosticsFn = (before: string[], after: string[]) => string[];
  * they run now match `tsconfig.json`.
  */
 export declare const introducedDiagnosticsIgnoringUnused: DiagnosticsFn;
+export declare const multisetIntersect: (lists: string[][]) => string[];
+/** The `TS####` prefix a corpus diagnostic is built with in `compileCorpus`. */
+export declare const codeOf: (diagnostic: string) => string;
+export declare const canonicalizeDiagnostic: (diagnostic: string) => string;
+export type DiagnosticIntersection = {
+    /** The shared multiset, carrying the FIRST list's original message strings. */
+    common: string[];
+    /**
+     * Everything ANY mode saw that the intersection did not keep - what the
+     * oracle silenced. Taken over every list, not just the first: the artifact
+     * class this discount exists for is the STRICT-only diagnostic, which never
+     * appears in the default mode's list and so is invisible to a counter read
+     * off `lists[0]` alone.
+     */
+    dropped: string[];
+    /**
+     * The subset of `dropped` that a code-only intersection would have KEPT: the
+     * TS code is present in every list with the multiplicity to match, and only
+     * the message text diverged. A genuinely mode-specific diagnostic is not in
+     * here, so this counter isolates exactly the silent-divergence failure and a
+     * guard can assert it to zero.
+     *
+     * Measured zero across all three consuming guards. If one ever appears, the
+     * remedy is to extend `canonicalizeDiagnostic` when it is another print-order
+     * divergence, or to record that one shape by name in the guard's own baseline
+     * when the two modes genuinely produce different diagnostics under the same
+     * TS code. Widening the comparison back toward the code alone is not a
+     * remedy: it resumes silencing, which is the defect.
+     */
+    codeMatchedDrops: string[];
+};
 /**
- * The multiset every list shares.
+ * The multiset every list shares, with an account of what it discarded.
  *
  * This is the mode discount, and it is the one place the cross-corpus oracles
  * deliberately differ from `fixer-type-safety`'s. That guard UNIONS the
@@ -286,8 +317,12 @@ export declare const introducedDiagnosticsIgnoringUnused: DiagnosticsFn;
  * The intersection only bites where both modes could judge. A pair whose input
  * compiles under one mode only has a single-element intersection, so for it
  * this is identical to the union.
+ *
+ * Because dropping is how this oracle produces a clean, every drop is counted
+ * rather than discarded in silence, and `codeMatchedDrops` separates "the modes
+ * disagree" from "the modes agree and the message merely printed differently".
  */
-export declare const multisetIntersect: (lists: string[][]) => string[];
+export declare const intersectDiagnostics: (lists: string[][]) => DiagnosticIntersection;
 /**
  * `ts.createProgram` SILENTLY drops a root file whose name it does not
  * recognize as TypeScript: `corpus.ts-7` is filtered out with no diagnostic at

package/lib/utils/fixtureTypeProgram.js

@@ -26,7 +26,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DECLARES_INTO_SHARED_SCOPE = exports.withSuffix = exports.multisetIntersect = exports.introducedDiagnosticsIgnoringUnused = exports.introducedDiagnostics = exports.isFragmentArtifact = exports.isUnusedDeclaration = exports.missingNameOf = exports.UNRESOLVED_NAME = exports.multisetDiff = exports.compileCorpus = exports.MODES = exports.STUBS = exports.SUBSTITUTION_PARTNER_STUBS = exports.FIRESTORE_CLIENT_STUB = exports.FIRESTORE_ADMIN_STUB = exports.FIRESTORE_COMMON = exports.TIMESTAMP_ADMIN = exports.REACT_STUB = void 0;
+exports.DECLARES_INTO_SHARED_SCOPE = exports.withSuffix = exports.intersectDiagnostics = exports.canonicalizeDiagnostic = exports.codeOf = exports.multisetIntersect = exports.introducedDiagnosticsIgnoringUnused = exports.introducedDiagnostics = exports.isFragmentArtifact = exports.isUnusedDeclaration = exports.missingNameOf = exports.UNRESOLVED_NAME = exports.multisetDiff = exports.compileCorpus = exports.MODES = exports.STUBS = exports.SUBSTITUTION_PARTNER_STUBS = exports.FIRESTORE_CLIENT_STUB = exports.FIRESTORE_ADMIN_STUB = exports.FIRESTORE_COMMON = exports.TIMESTAMP_ADMIN = exports.REACT_STUB = void 0;
 const path_1 = __importDefault(require("path"));
 const ts = __importStar(require("typescript"));
 /**
@@ -725,8 +725,266 @@ exports.introducedDiagnostics = introducedDiagnostics;
  */
 const introducedDiagnosticsIgnoringUnused = (before, after) => (0, exports.introducedDiagnostics)(before, after).filter((d) => !(0, exports.isUnusedDeclaration)(d));
 exports.introducedDiagnosticsIgnoringUnused = introducedDiagnosticsIgnoringUnused;
+const multisetIntersect = (lists) => intersectBy(lists, exports.canonicalizeDiagnostic);
+exports.multisetIntersect = multisetIntersect;
+/** The `TS####` prefix a corpus diagnostic is built with in `compileCorpus`. */
+const codeOf = (diagnostic) => {
+    const colon = diagnostic.indexOf(':');
+    return colon < 0 ? diagnostic : diagnostic.slice(0, colon);
+};
+exports.codeOf = codeOf;
+const OPENERS = '<([{';
+const CLOSERS = '>)]}';
+const isOpener = (char) => OPENERS.includes(char);
+const isCloser = (char) => CLOSERS.includes(char);
+/**
+ * Every scan below treats `=>` as ONE token. Its `>` is not a closing bracket,
+ * and letting it decrement the depth drives a function-typed member negative
+ * and splits the rest of the string in the wrong places.
+ */
+const skipsArrow = (text, index) => text[index] === '=' && text[index + 1] === '>';
+/** Splits on `separator` where it sits at bracket depth zero. */
+const splitTopLevel = (text, separator) => {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (skipsArrow(text, index)) {
+            index++;
+            continue;
+        }
+        if (isOpener(char))
+            depth++;
+        else if (isCloser(char))
+            depth--;
+        else if (char === separator && depth === 0) {
+            parts.push(text.slice(start, index));
+            start = index + 1;
+        }
+    }
+    parts.push(text.slice(start));
+    return parts;
+};
+/**
+ * A bracketed group's contents are an element LIST - tuple elements, type
+ * arguments, parameters, object members - separated by `,` or `;`. Splitting
+ * one as if it were a union is how `{ a: A | B; }` canonicalizes to
+ * `{B; | a: A}`: the `|` belongs to the member's type, not to the body.
+ */
+const splitListElements = (text) => {
+    const parts = [];
+    const separators = [];
+    let depth = 0;
+    let start = 0;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (skipsArrow(text, index)) {
+            index++;
+            continue;
+        }
+        if (isOpener(char))
+            depth++;
+        else if (isCloser(char))
+            depth--;
+        else if ((char === ',' || char === ';') && depth === 0) {
+            parts.push(text.slice(start, index));
+            separators.push(char);
+            start = index + 1;
+        }
+    }
+    parts.push(text.slice(start));
+    return { parts, separators };
+};
+/** Splits on a depth-zero `=>`, so `(x: A) => B | C` unions only `B | C`. */
+const splitTopLevelArrow = (text) => {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (skipsArrow(text, index)) {
+            if (depth === 0) {
+                parts.push(text.slice(start, index));
+                start = index + 2;
+            }
+            index++;
+            continue;
+        }
+        if (isOpener(char))
+            depth++;
+        else if (isCloser(char))
+            depth--;
+    }
+    parts.push(text.slice(start));
+    return parts;
+};
+/** The depth-zero `:` separating a member's name from its type, or -1. */
+const labelEnd = (text) => {
+    let depth = 0;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (skipsArrow(text, index)) {
+            index++;
+            continue;
+        }
+        if (isOpener(char))
+            depth++;
+        else if (isCloser(char))
+            depth--;
+        else if (char === ':' && depth === 0)
+            return index;
+    }
+    return -1;
+};
+/** The index of the bracket closing the one at `open`, or -1 if unbalanced. */
+const matchingBracket = (text, open) => {
+    let depth = 0;
+    for (let index = open; index < text.length; index++) {
+        const char = text[index];
+        if (skipsArrow(text, index)) {
+            index++;
+            continue;
+        }
+        if (isOpener(char))
+            depth++;
+        else if (isCloser(char)) {
+            depth--;
+            if (depth === 0)
+                return index;
+            if (depth < 0)
+                return -1;
+        }
+    }
+    return -1;
+};
+/** Rewrites the contents of every bracketed group as an element list. */
+const sortUnionsInside = (text) => {
+    let out = '';
+    let index = 0;
+    while (index < text.length) {
+        const char = text[index];
+        if (isOpener(char)) {
+            const close = matchingBracket(text, index);
+            if (close < 0) {
+                out += char;
+                index++;
+                continue;
+            }
+            out += char + sortUnionsList(text.slice(index + 1, close)) + text[close];
+            index = close + 1;
+            continue;
+        }
+        out += char;
+        index++;
+    }
+    return out;
+};
+const sortUnionsList = (text) => {
+    const { parts, separators } = splitListElements(text);
+    const sorted = parts.map((part) => sortUnionsMember(part.trim()));
+    return sorted.reduce((out, part, index) => index ? `${out}${separators[index - 1]} ${part}` : part, '');
+};
+/** `name: T` unions only `T`; the name is not a union member. */
+const sortUnionsMember = (text) => {
+    const colon = labelEnd(text);
+    if (colon < 0)
+        return sortUnions(text);
+    return `${text.slice(0, colon)}: ${sortUnions(text.slice(colon + 1).trim())}`;
+};
+/**
+ * Only UNION members are reordered. Tuple elements, type arguments, parameters
+ * and object members print in DECLARATION order, which is a property of the
+ * source and stable across programs, so sorting those would erase a real
+ * difference rather than a spurious one - they are rebuilt in place.
+ */
+const sortUnions = (text) => {
+    const arrowParts = splitTopLevelArrow(text);
+    if (arrowParts.length > 1) {
+        return arrowParts
+            .map((part, index) => index === arrowParts.length - 1
+            ? sortUnions(part.trim())
+            : sortUnionsInside(part.trim()))
+            .join(' => ');
+    }
+    if (splitListElements(text).separators.length)
+        return sortUnionsList(text);
+    const members = splitTopLevel(text, '|').map((member) => sortUnionsInside(member.trim()));
+    if (members.length === 1)
+        return members[0];
+    return [...members].sort().join(' | ');
+};
 /**
- * The multiset every list shares.
+ * A diagnostic message with every printed union in a canonical member order.
+ *
+ * TypeScript orders a union's members by type ID - the order the checker
+ * happened to CREATE those types in - not by anything in the source, and a
+ * type ID is per-program. Two programs over the same files can therefore print
+ * one union two ways:
+ *
+ *   TS2345: ... parameter of type 'Record<string, unknown> | unknown[]'.
+ *   TS2345: ... parameter of type 'unknown[] | Record<string, unknown>'.
+ *
+ * That matters because `intersectDiagnostics` is a SILENCING oracle: what it
+ * drops becomes a clean. Comparing raw messages discarded a diagnostic present
+ * in BOTH modes as strict-only, which is why `cross-fixture-fixer-type-safety`
+ * read 0 findings while `fixer-type-safety` - which unions instead of
+ * intersecting - baselines the same 4 `enforce-microdiff` TS2345 pairs (#2235).
+ *
+ * Rewriting is confined to single-quoted spans because that is where and only
+ * where TypeScript prints a type; a string-literal type nested in one is
+ * printed with double quotes, so the spans do not nest. This is a COMPARISON
+ * KEY - every diagnostic reported to a maintainer is the original string.
+ */
+const canonicalCache = new Map();
+const canonicalizeDiagnostic = (diagnostic) => {
+    const cached = canonicalCache.get(diagnostic);
+    if (cached !== undefined)
+        return cached;
+    const canonical = diagnostic.replace(/'([^']*)'/g, (_match, inner) => `'${sortUnions(inner)}'`);
+    canonicalCache.set(diagnostic, canonical);
+    return canonical;
+};
+exports.canonicalizeDiagnostic = canonicalizeDiagnostic;
+/** The entries of `list` that `kept` does not cover, compared by `keyOf`. */
+const subtractBy = (kept, list, keyOf) => {
+    const counts = new Map();
+    for (const diagnostic of kept) {
+        const key = keyOf(diagnostic);
+        counts.set(key, (counts.get(key) || 0) + 1);
+    }
+    return list.filter((diagnostic) => {
+        const key = keyOf(diagnostic);
+        const remaining = counts.get(key) || 0;
+        if (remaining <= 0)
+            return true;
+        counts.set(key, remaining - 1);
+        return false;
+    });
+};
+const intersectBy = (lists, keyOf) => {
+    if (!lists.length)
+        return [];
+    let common = [...lists[0]];
+    for (const list of lists.slice(1)) {
+        const counts = new Map();
+        for (const diagnostic of list) {
+            const key = keyOf(diagnostic);
+            counts.set(key, (counts.get(key) || 0) + 1);
+        }
+        common = common.filter((diagnostic) => {
+            const key = keyOf(diagnostic);
+            const remaining = counts.get(key) || 0;
+            if (remaining <= 0)
+                return false;
+            counts.set(key, remaining - 1);
+            return true;
+        });
+    }
+    return common;
+};
+/**
+ * The multiset every list shares, with an account of what it discarded.
  *
  * This is the mode discount, and it is the one place the cross-corpus oracles
  * deliberately differ from `fixer-type-safety`'s. That guard UNIONS the
@@ -755,27 +1013,26 @@ exports.introducedDiagnosticsIgnoringUnused = introducedDiagnosticsIgnoringUnuse
  * The intersection only bites where both modes could judge. A pair whose input
  * compiles under one mode only has a single-element intersection, so for it
  * this is identical to the union.
+ *
+ * Because dropping is how this oracle produces a clean, every drop is counted
+ * rather than discarded in silence, and `codeMatchedDrops` separates "the modes
+ * disagree" from "the modes agree and the message merely printed differently".
  */
-const multisetIntersect = (lists) => {
-    if (!lists.length)
-        return [];
-    let common = [...lists[0]];
-    for (const list of lists.slice(1)) {
-        const counts = new Map();
-        for (const diagnostic of list) {
-            counts.set(diagnostic, (counts.get(diagnostic) || 0) + 1);
-        }
-        common = common.filter((diagnostic) => {
-            const remaining = counts.get(diagnostic) || 0;
-            if (remaining <= 0)
-                return false;
-            counts.set(diagnostic, remaining - 1);
-            return true;
-        });
-    }
-    return common;
+const intersectDiagnostics = (lists) => {
+    const common = intersectBy(lists, exports.canonicalizeDiagnostic);
+    const byCode = intersectBy(lists, exports.codeOf);
+    return {
+        common,
+        // Compared by the CANONICAL key, like `common` itself: subtracting by raw
+        // string would report the other mode's spelling of a KEPT diagnostic as a
+        // drop, which is the #2235 confusion inverted.
+        dropped: lists.flatMap((list) => subtractBy(common, list, exports.canonicalizeDiagnostic)),
+        // Canonical-key equality implies code equality, so `byCode` contains
+        // `common` as a multiset and the difference is exactly the divergence.
+        codeMatchedDrops: subtractBy(common, byCode, exports.canonicalizeDiagnostic),
+    };
 };
-exports.multisetIntersect = multisetIntersect;
+exports.intersectDiagnostics = intersectDiagnostics;
 /**
  * `ts.createProgram` SILENTLY drops a root file whose name it does not
  * recognize as TypeScript: `corpus.ts-7` is filtered out with no diagnostic at

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "1.20.197",
+    "date": "2026-08-31T08:50:13.198Z",
+    "rules": [
+      {
+        "name": "no-entire-object-hook-deps",
+        "changeType": "fix",
+        "issues": [
+          2236
+        ],
+        "summary": "decline a removal that strands a destructured prop (closes #2236)"
+      }
+    ]
+  },
   {
     "version": "1.20.196",
     "date": "2026-08-31T07:14:16.368Z",