@blumintinc/eslint-plugin-blumint 1.20.49 → 1.20.51

package/lib/index.js

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

package/lib/rules/consistent-callback-naming.js

@@ -52,7 +52,7 @@ module.exports = (0, createRule_1.createRule)({
         messages: {
             callbackPropPrefix: 'Callback prop "{{propName}}" is a function but lacks the "on" prefix. ' +
                 'Consistent "on" prefixes signal event handlers to consumers and distinguish callbacks from data props. ' +
-                'Rename to "on{{eventName}}".',
+                'Rename to "on{{eventName}}" here, in the props type that declares it, and in every reader of that prop.',
             callbackFunctionPrefix: 'Function "{{functionName}}" uses the "handle" prefix. ' +
                 'The "handle" prefix is redundant and less descriptive than action-oriented verb phrases. ' +
                 'Rename using a descriptive verb (e.g., click instead of handleClick).',
@@ -252,6 +252,18 @@ module.exports = (0, createRule_1.createRule)({
                         !isRenderFunction(node.value.expression) &&
                         !isReactComponentType(node.value.expression)) {
                         const eventName = propName.charAt(0).toUpperCase() + propName.slice(1);
+                        // Reported without an autofix (Bug #1522). A JSX attribute name is
+                        // one end of a props contract: the other end is the declaration
+                        // that binds the name — a props `type`/`interface`, a
+                        // `JSX.IntrinsicElements` augmentation for host elements — plus
+                        // every reader of that member (`props.validate`, destructuring) and
+                        // every other call site of the component. Rewriting only the
+                        // attribute yields TS2322, and renaming the local declaration
+                        // as well merely relocates the break: readers in the same file fail
+                        // with TS2551 and call sites in other files (which a single-file
+                        // fixer cannot see, let alone edit atomically) fail with TS2322.
+                        // No subset of the rename is safe to apply in isolation, so the
+                        // report carries the full instruction instead of a broken fix.
                         context.report({
                             node,
                             messageId: 'callbackPropPrefix',
@@ -259,10 +271,6 @@ module.exports = (0, createRule_1.createRule)({
                                 propName,
                                 eventName,
                             },
-                            fix(fixer) {
-                                // Convert camelCase to PascalCase for the event name
-                                return fixer.replaceText(node.name, `on${eventName}`);
-                            },
                         });
                     }
                 }

package/lib/rules/enforce-dynamic-imports.js

@@ -36,9 +36,11 @@ exports.DEFAULT_IGNORED_LIBRARIES = [
     'use-latest-callback',
     '@blumintinc/typescript-memoize',
     '@blumintinc/use-deep-compare',
+    '@blumintinc/microdiff',
     'microdiff',
     'safe-stable-stringify',
-    'fast-deep-equal', // fast-deep-equal-over-microdiff
+    '@blumintinc/fast-deep-equal',
+    'fast-deep-equal', // fast-deep-equal-over-microdiff, for files already on upstream
 ];
 exports.DEFAULT_INTERNAL_PREFIXES = ['src/', 'functions/'];
 // Pre-built set of Node.js core module names for O(1) lookup.

package/lib/rules/enforce-early-destructuring.js

@@ -407,8 +407,9 @@ function renderArrayPatternWithDefaults(pattern, sourceCode) {
             return `${leftText} = ${sourceCode.getText(element.right)}`;
         }
         if (element.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
-            const nested = renderObjectPatternWithDefaults(element, sourceCode);
-            return `${nested} = {}`;
+            // No synthesized `= {}` here either, for the reason spelled out in
+            // formatPropertyText: the default is checked against the bindings under it.
+            return renderObjectPatternWithDefaults(element, sourceCode);
         }
         if (element.type === utils_1.AST_NODE_TYPES.ArrayPattern) {
             const nested = renderArrayPatternWithDefaults(element, sourceCode);
@@ -441,10 +442,19 @@ function formatPropertyText(property, sourceCode) {
         return renderPropertyWithAssignment(property, value, keyText, sourceCode);
     }
     if (value.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
+        // A nested object pattern is re-emitted as authored, without a synthesized
+        // `= {}`. TypeScript checks such a default against every binding element
+        // beneath it, so `{ profile: { name, age } = {} }` reports TS2525 once per
+        // name: `{}` supplies no value and the names carry no defaults of their own.
+        // The default also only ever guarded a nullish parent (an explicitly `null`
+        // one still throws), so dropping it costs a partial runtime guard and buys
+        // back the invariant that compiling input yields compiling output.
         const nested = renderObjectPatternWithDefaults(value, sourceCode);
-        return `${keyText}: ${nested} = {}`;
+        return `${keyText}: ${nested}`;
     }
     if (value.type === utils_1.AST_NODE_TYPES.ArrayPattern) {
+        // An array pattern's `= []` default is safe to synthesize: TypeScript does
+        // not push it down onto the element bindings the way it does for objects.
         const nested = renderArrayPatternWithDefaults(value, sourceCode);
         return `${keyText}: ${nested} = []`;
     }

package/lib/rules/enforce-microdiff.js

@@ -5,7 +5,25 @@ const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
 const DIFF_NAME = 'diff';
-const MICRODIFF_MODULE = 'microdiff';
+/**
+ * The package the fix imports from. BluMint's fork is the dependency this
+ * codebase declares, and every call site resolves against it.
+ */
+const MICRODIFF_MODULE = '@blumintinc/microdiff';
+/**
+ * The specifiers that already satisfy this rule. The fix emits the fork, but a
+ * file importing upstream `microdiff` is diffing structurally all the same, so
+ * both are recognised on the way in: an unrecognised one would earn a second
+ * import of the same binding (TS2300).
+ */
+const MICRODIFF_MODULES = new Set([MICRODIFF_MODULE, 'microdiff']);
+/**
+ * The import the fix emits. Both packages export their diff function as the
+ * module *default* — `Difference`, `MicrodiffOptions` and the `default*`
+ * predicates are the only named exports — so a `{ diff }` specifier binds
+ * nothing (TS2305) however the module resolves.
+ */
+const MICRODIFF_IMPORT = `import ${DIFF_NAME} from '${MICRODIFF_MODULE}';`;
 /**
  * The names a competing library's diff export is conventionally bound to. They
  * are candidates for a report, never proof of one: what a call resolves to
@@ -68,7 +86,7 @@ function bindsMicrodiffDiff(specifier) {
  */
 function findMicrodiffImport(program) {
     return program.body.find((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
-        statement.source.value === MICRODIFF_MODULE &&
+        MICRODIFF_MODULES.has(String(statement.source.value)) &&
         statement.importKind !== 'type' &&
         statement.specifiers.some(bindsMicrodiffDiff));
 }
@@ -85,7 +103,7 @@ function collectClaimableSpecifiers(program) {
             return;
         }
         const source = statement.source.value;
-        if (source === MICRODIFF_MODULE) {
+        if (MICRODIFF_MODULES.has(source)) {
             statement.specifiers
                 .filter(bindsMicrodiffDiff)
                 .forEach((specifier) => claimable.add(specifier));
@@ -166,6 +184,28 @@ function toImportedDiffSource(variable, importedSpecifiers) {
     }
     return null;
 }
+/**
+ * Whether a call carries operands `diff(obj, newObj, options?)` accepts.
+ * microdiff needs both sides of the comparison, so a call supplying fewer is
+ * reported but left alone: rewriting it would trade an unresolved name for a
+ * call that does not type-check (TS2554).
+ */
+function hasRewritableArity(call) {
+    return call.arguments.length >= 2;
+}
+/**
+ * Whether a reference sits where the call fix rewrites it — as the callee of a
+ * convertible call. A reference in any other position (passed as a value,
+ * assigned to a variable, re-exported) has no rewrite of its own, so retiring
+ * the import that binds it would leave it unresolved (TS2304).
+ */
+function isRewrittenCallee(identifier) {
+    const parent = identifier.parent;
+    return (!!parent &&
+        parent.type === utils_1.AST_NODE_TYPES.CallExpression &&
+        parent.callee === identifier &&
+        hasRewritableArity(parent));
+}
 /**
  * Whether a bare `diff` written at `scope` reaches microdiff's function.
  * Resolving through the scope chain catches both failure modes: a module-scope
@@ -221,21 +261,86 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
             return canEmitDiff(ASTHelpers_1.ASTHelpers.getScope(context, node), collectClaimableSpecifiers(sourceCode.ast));
         }
         /**
-         * Whether retiring `declaration` leaves every reference it binds able to
-         * take the name `diff`. The import rewrite lands at module scope while the
-         * references it serves sit in nested scopes: one standing where `diff` is
-         * shadowed keeps the old name, because its own fix declines, so rewriting
-         * the import would strand it without a binding (TS2304).
+         * Whether the call handler rewrites the calls a specifier's references
+         * make. It fires on a specifier the import handler tracked, or on a local
+         * name a competing library conventionally binds; a specifier matching
+         * neither — `applyChange` from `deep-diff`, say — keeps its call sites, so
+         * its references survive only if the import that binds them does.
          */
-        function canRenameReferencesOf(declaration) {
+        function isRewrittenSpecifier(specifier) {
+            return (importedDiffSpecifiers.has(specifier) ||
+                DIFF_FUNCTION_NAMES.has(specifier.local.name));
+        }
+        /**
+         * Whether retiring `declaration` leaves every name it binds accounted for.
+         * The fix removes the whole declaration, so each reference it serves has to
+         * be one the call fixes rewrite to `diff` in the same pass — an import swap
+         * that strands a reference behind is the defect this guards.
+         *
+         * Two things have to hold at every reference. `diff` must reach microdiff
+         * there: the import rewrite lands at module scope while the references it
+         * serves sit in nested scopes, and one standing where `diff` is shadowed
+         * would resolve to the shadow. And the reference has to sit where a rewrite
+         * exists at all, which is the callee position of a convertible call.
+         *
+         * A specifier nothing references is vacuously safe: retiring it removes an
+         * import no code reads.
+         */
+        function canRetireImport(declaration) {
             const claimable = collectClaimableSpecifiers(sourceCode.ast);
             const declarationScope = ASTHelpers_1.ASTHelpers.getScope(context, declaration);
             return declaration.specifiers.every((specifier) => {
                 const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(declarationScope, specifier.local.name);
-                return (!variable ||
-                    variable.references.every((reference) => canEmitDiff(reference.from, claimable)));
+                if (!variable) {
+                    return true;
+                }
+                const rewritten = isRewrittenSpecifier(specifier);
+                return variable.references.every((reference) => canEmitDiff(reference.from, claimable) &&
+                    rewritten &&
+                    isRewrittenCallee(reference.identifier));
             });
         }
+        /**
+         * Whether the import fix retires `declaration` in this same pass.
+         */
+        function willRetireImport(declaration) {
+            return canEmitDiffAt(declaration) && canRetireImport(declaration);
+        }
+        /**
+         * Whether the call at `node`, whose callee `declaration` binds, may be
+         * rewritten to `diff(...)`. Separate from the decision to report: a call
+         * this rule cannot convert is still a use of a competing library, so it is
+         * reported and left for the author.
+         *
+         * The rename needs something to bind the `diff` it writes — an import the
+         * file already has, or the one that replaces `declaration` in this same
+         * pass. Renaming a callee whose import survives strands the rewritten call
+         * exactly as retiring an import whose callee survives strands that one.
+         */
+        function canRewriteCall(node, declaration) {
+            if (!canEmitDiffAt(node) || !hasRewritableArity(node)) {
+                return false;
+            }
+            if (findMicrodiffImport(sourceCode.ast)) {
+                return true;
+            }
+            return !!declaration && willRetireImport(declaration);
+        }
+        /**
+         * The fix element that puts microdiff's import at the top of the file, or
+         * null when the file already has one.
+         *
+         * It is its own element rather than text spliced into the replacement for
+         * the reported node, because the reported node is rarely at module scope: a
+         * comparison inside a function body, or a function behind an `export`,
+         * would otherwise take the import somewhere the grammar forbids it.
+         */
+        function buildMicrodiffImportFix(fixer) {
+            if (findMicrodiffImport(sourceCode.ast)) {
+                return null;
+            }
+            return fixer.insertTextBeforeRange([0, 0], `${MICRODIFF_IMPORT}\n\n`);
+        }
         // Add a specific set to track which import names are used
         const usedImportNames = new Set();
         // Check if a node is an object or array type
@@ -272,7 +377,7 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
             ImportDeclaration(node) {
                 const importSource = node.source.value;
                 // Check for microdiff import
-                if (importSource === MICRODIFF_MODULE) {
+                if (MICRODIFF_MODULES.has(importSource)) {
                     return;
                 }
                 // Track other diffing libraries
@@ -296,9 +401,10 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                         },
                         fix(fixer) {
                             // Decline rather than duplicate or shadow a `diff` this file
-                            // already binds to something else. The report stands so the
-                            // author resolves the name clash deliberately.
-                            if (!canEmitDiffAt(node) || !canRenameReferencesOf(node)) {
+                            // already binds to something else, and rather than retire an
+                            // import whose references no call fix rewrites. The report stands
+                            // either way, so the author resolves it deliberately.
+                            if (!canEmitDiffAt(node) || !canRetireImport(node)) {
                                 return null;
                             }
                             // If we already have a microdiff import, just remove this import
@@ -306,7 +412,7 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                                 return fixer.remove(node);
                             }
                             // Otherwise, replace with microdiff import
-                            return fixer.replaceText(node, `import { ${DIFF_NAME} } from '${MICRODIFF_MODULE}';`);
+                            return fixer.replaceText(node, MICRODIFF_IMPORT);
                         },
                     });
                     // Check if importing a diff function or a known equality library
@@ -346,6 +452,9 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                         // Check if this call resolves to a function we specifically
                         // imported from a diff library
                         const importSource = toImportedDiffSource(calleeVariable, importedDiffSpecifiers);
+                        // The declaration the rename depends on: retiring it is what frees
+                        // the name `diff` and imports something under it.
+                        const competingImport = toCompetingDiffImport(calleeVariable);
                         if (importSource) {
                             usedImportNames.add(name);
                             // Skip reporting if it's from fast-deep-equal
@@ -358,7 +467,7 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                                 node,
                                 messageId: 'enforceMicrodiff',
                                 fix(fixer) {
-                                    if (!canEmitDiffAt(node)) {
+                                    if (!canRewriteCall(node, competingImport)) {
                                         return null;
                                     }
                                     return fixer.replaceText(callee, DIFF_NAME);
@@ -370,29 +479,28 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                             // The name is only a candidate until the scope chain says what it
                             // binds: a local function, variable, parameter, or an import from
                             // anywhere but a competing diff library keeps its call untouched.
-                            const competingImport = toCompetingDiffImport(calleeVariable);
                             if (!competingImport) {
                                 return;
                             }
                             // Track this import name as used
                             usedImportNames.add(name);
-                            // Check if we have at least 2 arguments that are objects or arrays
-                            if (node.arguments.length >= 2 &&
-                                isObjectOrArrayType(node.arguments[0]) &&
-                                isObjectOrArrayType(node.arguments[1])) {
-                                reportedNodes.add(node);
-                                context.report({
-                                    node,
-                                    messageId: 'enforceMicrodiff',
-                                    fix(fixer) {
-                                        if (!canEmitDiffAt(node)) {
-                                            return null;
-                                        }
-                                        // When handling fast-diff and similar libraries, need to ensure the function name is replaced
-                                        return fixer.replaceText(callee, DIFF_NAME);
-                                    },
-                                });
-                            }
+                            // What the callee resolves to already settles this: the argument
+                            // shapes say nothing a competing library's own import has not.
+                            // Gating the report on them left the call behind while the import
+                            // handler retired the declaration binding it, so `deepDiff(a, b)`
+                            // came out of a fix unresolved.
+                            reportedNodes.add(node);
+                            context.report({
+                                node,
+                                messageId: 'enforceMicrodiff',
+                                fix(fixer) {
+                                    if (!canRewriteCall(node, competingImport)) {
+                                        return null;
+                                    }
+                                    // When handling fast-diff and similar libraries, need to ensure the function name is replaced
+                                    return fixer.replaceText(callee, DIFF_NAME);
+                                },
+                            });
                         }
                     }
                 }
@@ -461,28 +569,13 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                                     if (!canEmitDiffAt(node)) {
                                         return null;
                                     }
-                                    // Find the containing function to add the import
-                                    let functionNode = node;
-                                    while (functionNode &&
-                                        functionNode.type !== utils_1.AST_NODE_TYPES.FunctionDeclaration &&
-                                        functionNode.type !==
-                                            utils_1.AST_NODE_TYPES.ArrowFunctionExpression &&
-                                        functionNode.type !== utils_1.AST_NODE_TYPES.Program) {
-                                        functionNode = functionNode.parent;
-                                    }
-                                    // If we found a program node and microdiff isn't imported,
-                                    // we'll need to add the import manually
-                                    if (functionNode &&
-                                        functionNode.type === utils_1.AST_NODE_TYPES.Program &&
-                                        !findMicrodiffImport(sourceCode.ast)) {
-                                        // Need to add an import
-                                        const importFix = fixer.insertTextBeforeRange([0, 0], `import { ${DIFF_NAME} } from '${MICRODIFF_MODULE}';\n\n`);
-                                        // Replace JSON.stringify comparison
-                                        const compareFix = fixer.replaceText(node, `${DIFF_NAME}(${sourceCode.getText(leftArg)}, ${sourceCode.getText(rightArg)})${isEqual ? '.length === 0' : '.length > 0'}`);
-                                        return [importFix, compareFix];
-                                    }
-                                    // Otherwise just replace the comparison
-                                    return fixer.replaceText(node, `${DIFF_NAME}(${sourceCode.getText(leftArg)}, ${sourceCode.getText(rightArg)})${isEqual ? '.length === 0' : '.length > 0'}`);
+                                    const compareFix = fixer.replaceText(node, `${DIFF_NAME}(${sourceCode.getText(leftArg)}, ${sourceCode.getText(rightArg)})${isEqual ? '.length === 0' : '.length > 0'}`);
+                                    // The comparison this rewrites almost always sits inside a
+                                    // function, and the `diff` it emits needs an import whatever
+                                    // encloses it. Deciding on the enclosing node left every
+                                    // nested comparison calling a `diff` nothing bound.
+                                    const importFix = buildMicrodiffImportFix(fixer);
+                                    return importFix ? [importFix, compareFix] : compareFix;
                                 },
                             });
                         }
@@ -518,27 +611,31 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                             bodyText.includes('JSON.stringify') &&
                             bodyText.includes('!==')) {
                             reportedNodes.add(node);
-                            const param1 = sourceCode.getText(node.params[0]);
-                            const param2 = sourceCode.getText(node.params[1]);
+                            // The operands are the parameter *names*, not the text of the
+                            // parameters: a typed parameter's text carries its annotation,
+                            // and `diff(oldConfig: Config, ...)` does not parse. A parameter
+                            // that binds no single name — a destructuring or rest pattern —
+                            // has no operand to pass, so the report stands without a fix.
+                            const [firstParam, secondParam] = node.params;
+                            const operands = firstParam.type === utils_1.AST_NODE_TYPES.Identifier &&
+                                secondParam.type === utils_1.AST_NODE_TYPES.Identifier
+                                ? [firstParam.name, secondParam.name]
+                                : null;
                             context.report({
                                 node,
                                 messageId: 'enforceMicrodiff',
                                 fix(fixer) {
-                                    if (!canEmitDiffAt(node)) {
+                                    if (!operands || !canEmitDiffAt(node)) {
                                         return null;
                                     }
-                                    // Create a new version of the function with microdiff
-                                    const newFunctionBody = `{
-  return ${DIFF_NAME}(${param1}, ${param2}).length > 0;
-}`;
-                                    if (!findMicrodiffImport(sourceCode.ast)) {
-                                        // Create a new import statement
-                                        return fixer.replaceText(node, `import { ${DIFF_NAME} } from '${MICRODIFF_MODULE}';\n\nfunction ${node.id?.name}(${param1}, ${param2}) ${newFunctionBody}`);
-                                    }
-                                    else {
-                                        // Just replace the function body
-                                        return fixer.replaceText(body, newFunctionBody);
-                                    }
+                                    // Only the body is rewritten, so the signature keeps its type
+                                    // annotations, its modifiers, and any `export` in front of
+                                    // it. Replacing the declaration wholesale used to drop those
+                                    // and, when it prefixed the import, put an `import` inside
+                                    // whatever enclosed the function.
+                                    const bodyFix = fixer.replaceText(body, `{\n  return ${DIFF_NAME}(${operands[0]}, ${operands[1]}).length > 0;\n}`);
+                                    const importFix = buildMicrodiffImportFix(fixer);
+                                    return importFix ? [importFix, bodyFix] : bodyFix;
                                 },
                             });
                             return;