@blumintinc/eslint-plugin-blumint 1.20.166 → 1.20.168

package/lib/index.js

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

package/lib/rules/memo-compare-deeply-complex-props.js

@@ -838,7 +838,86 @@ function isExternalDeclaration(declaration) {
         /[/\\]node_modules[/\\]/.test(fileName));
 }
 /**
- * Returns true when every declaration site of `prop` lives in a dependency.
+ * Classifies `type` itself by the declaration sites of the alias it was written
+ * as (`SystemProps`, `Readonly`) or, absent an alias, of its own symbol — an
+ * interface declaration, an object type literal, or the `MappedTypeNode` a
+ * mapped type is synthesized from.
+ */
+function classifyTypeOrigin(type) {
+    const symbol = type.aliasSymbol ??
+        type.symbol;
+    const declarations = symbol?.declarations;
+    if (!declarations || declarations.length === 0)
+        return 'unknown';
+    return declarations.every(isExternalDeclaration) ? 'external' : 'authored';
+}
+/**
+ * The sub-types of `type` that could have contributed `propName`: intersection
+ * constituents, union members, and the arguments a generic alias was
+ * instantiated with. The alias arm is what sees through a dependency's wrapper
+ * — `Readonly<X>`/`Omit<X, K>` re-synthesize members and present themselves as
+ * `lib.es5.d.ts`, while the surface they wrap may belong to either side.
+ */
+function propertyCarriersOf(type, propName, checker, ts) {
+    const candidates = [];
+    if (type.flags & (ts.TypeFlags.Union | ts.TypeFlags.Intersection)) {
+        candidates.push(...type.types);
+    }
+    const aliasTypeArguments = type
+        .aliasTypeArguments;
+    if (aliasTypeArguments)
+        candidates.push(...aliasTypeArguments);
+    return candidates.filter((candidate) => {
+        if (candidate === type)
+            return false;
+        try {
+            return Boolean(checker.getPropertyOfType?.(candidate, propName));
+        }
+        catch {
+            return false;
+        }
+    });
+}
+// Guards the descent against a self-referential alias; real props types nest a
+// handful of wrappers at most.
+const MAX_ORIGIN_SEARCH_DEPTH = 8;
+/**
+ * Answers who wrote `propName` by finding the constituent of `type` that
+ * actually carries it, rather than by asking the outermost wrapper.
+ *
+ * Ownership is decided by the innermost carrier, so a dependency's wrapper over
+ * the author's type stays authored (`Readonly<{ [K in Keys]: … }>`) and the
+ * author's wrapper over a dependency's type stays external.
+ */
+function classifyPropertyOrigin(propName, type, checker, ts, depth = 0) {
+    const carriers = depth < MAX_ORIGIN_SEARCH_DEPTH
+        ? propertyCarriersOf(type, propName, checker, ts)
+        : [];
+    if (carriers.length > 0) {
+        const origins = carriers.map((carrier) => classifyPropertyOrigin(propName, carrier, checker, ts, depth + 1));
+        // One authored carrier is enough: the author declared the prop somewhere in
+        // the composition, so the remedy is theirs to apply.
+        if (origins.some((origin) => origin === 'authored'))
+            return 'authored';
+        return origins.every((origin) => origin === 'external')
+            ? 'external'
+            : 'unknown';
+    }
+    const ownOrigin = classifyTypeOrigin(type);
+    if (ownOrigin !== 'external')
+        return ownOrigin;
+    // No carrier holds the prop, yet the type is a dependency's: a mapping
+    // construct such as `Record<OwnKeys, T>` synthesizes members from the
+    // author's inputs while presenting `lib.es5.d.ts` as its own declaration
+    // site. The library supplied the machinery, the author supplied the keys.
+    const aliasTypeArguments = type
+        .aliasTypeArguments;
+    const hasAuthoredInput = aliasTypeArguments?.some((argument) => classifyTypeOrigin(argument) === 'authored');
+    return hasAuthoredInput ? 'authored' : 'external';
+}
+/**
+ * Returns true when `prop` belongs to a dependency rather than to the component
+ * under lint.
  *
  * `checker.getPropertiesOfType` returns INHERITED members, so a props type that
  * extends or intersects a library interface (MUI's `TypographyProps`, React's
@@ -847,21 +926,27 @@ function isExternalDeclaration(declaration) {
  * the component neither declares nor receives them, and the lists run past a
  * hundred names — so the only available exit is a blanket rule disable.
  *
- * The gate is `every` rather than "first declaration", so a prop the author
- * redeclares alongside the library's (the intersection of two same-named
- * members yields one symbol carrying BOTH declarations) still counts as
- * authored and is still reported.
+ * The declaration gate is `every` rather than "first declaration", so a prop the
+ * author redeclares alongside the library's (the intersection of two same-named
+ * members yields one symbol carrying BOTH declarations) still counts as authored
+ * and is still reported.
  *
- * A prop with no declarations at all is treated as authored. Synthesized
- * symbols reach here from mapped and generic types over the component's own
- * props, and reporting them preserves the rule's core behaviour; a missing
- * declaration is not evidence of a dependency.
+ * A prop with NO declaration site cannot be answered that way at all, and a
+ * missing declaration is evidence of neither side. TypeScript propagates
+ * declarations only through HOMOMORPHIC mapped types (`Readonly<T>`,
+ * `Pick<T, K>`); a keyed mapped type (`{ [K in SystemKeys]?: … }` — the shape
+ * MUI's `SystemProps<Theme>` gives every `Box`-derived component) synthesizes
+ * fresh symbols with none, whoever wrote it. Such a prop is classified by the
+ * ORIGIN of the type that carries it, which keeps a library's ~100 style
+ * shorthands out of the report while the author's own mapped types stay in it.
  */
-function isExternallyDeclaredProperty(prop) {
+function isDependencyOwnedProperty(prop, containingType, checker, ts) {
     const declarations = prop.declarations;
-    if (!declarations || declarations.length === 0)
-        return false;
-    return declarations.every(isExternalDeclaration);
+    if (declarations && declarations.length > 0) {
+        return declarations.every(isExternalDeclaration);
+    }
+    return (classifyPropertyOrigin(prop.name, containingType, checker, ts) ===
+        'external');
 }
 function getComplexPropertiesFromType(type, checker, tsNode, ts, treatAnyAsComplex = false, parentTypeFlags = 0) {
     const properties = checker.getPropertiesOfType(type);
@@ -869,7 +954,7 @@ function getComplexPropertiesFromType(type, checker, tsNode, ts, treatAnyAsCompl
     for (const prop of properties) {
         if (isReservedReactPropName(prop.name))
             continue;
-        if (isExternallyDeclaredProperty(prop))
+        if (isDependencyOwnedProperty(prop, type, checker, ts))
             continue;
         if (isPropertyComplex(prop, checker, tsNode, ts, treatAnyAsComplex, parentTypeFlags)) {
             complexProps.push(prop.name);

package/lib/rules/prefer-nullish-coalescing-boolean-props.js

@@ -69,6 +69,122 @@ function isPossiblyNullish(type, checker) {
             ts.TypeFlags.Unknown)) !==
         0);
 }
+/**
+ * The union members of a type, following a type parameter to its constraint so a
+ * generic operand is read through the same lens as a written-out union.
+ */
+function unionMembers(type, checker) {
+    if (type.isUnion()) {
+        return type.types.flatMap((member) => unionMembers(member, checker));
+    }
+    if (type.getFlags() & ts.TypeFlags.TypeParameter) {
+        if (checker) {
+            const constraint = checker.getBaseConstraintOfType(type);
+            if (constraint && constraint !== type) {
+                return unionMembers(constraint, checker);
+            }
+        }
+        return [type];
+    }
+    return [type];
+}
+/**
+ * A member every value of which is falsy while none of them is nullish: the part
+ * of a union that `||` discards and `??` keeps.
+ */
+function isNonNullishFalsy(type) {
+    const flags = type.getFlags();
+    if (flags & ts.TypeFlags.BooleanLiteral) {
+        return (type.intrinsicName === 'false');
+    }
+    if (flags & (ts.TypeFlags.NumberLiteral | ts.TypeFlags.StringLiteral)) {
+        const { value } = type;
+        // `-0` compares equal to `0`, so both numeric zeroes are covered.
+        return value === 0 || value === '';
+    }
+    if (flags & ts.TypeFlags.BigIntLiteral) {
+        const { value } = type;
+        return typeof value === 'object' && value.base10Value === '0';
+    }
+    return false;
+}
+function isNullishMember(type) {
+    return ((type.getFlags() &
+        (ts.TypeFlags.Null |
+            ts.TypeFlags.Undefined |
+            ts.TypeFlags.Void |
+            ts.TypeFlags.Any |
+            ts.TypeFlags.Unknown)) !==
+        0);
+}
+/**
+ * The primitive domain a union member belongs to. Members of one domain form the
+ * unions the rule exists for (`string | undefined`, `boolean | undefined`,
+ * `0 | 1 | undefined`), where a falsy value is a value of the same kind as the
+ * fallback and preserving it is the point.
+ */
+function domainOf(type) {
+    const flags = type.getFlags();
+    if (flags & (ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral)) {
+        return 'boolean';
+    }
+    if (flags & (ts.TypeFlags.Number | ts.TypeFlags.NumberLiteral)) {
+        return 'number';
+    }
+    if (flags & (ts.TypeFlags.String | ts.TypeFlags.StringLiteral)) {
+        return 'string';
+    }
+    if (flags & (ts.TypeFlags.BigInt | ts.TypeFlags.BigIntLiteral)) {
+        return 'bigint';
+    }
+    return 'other';
+}
+/**
+ * Whether the `||` is load-bearing because its left operand carries a falsy
+ * sentinel from outside the payload's domain.
+ *
+ * `cond && payload` evaluates to the falsy `cond` itself when it short-circuits,
+ * so the operand's type is `false | payload` (or `0 | payload`, `'' | payload`).
+ * The trailing `||` exists to strip that sentinel; `??` strips only `null` and
+ * `undefined`, so the rewrite leaks a `false` into a position typed for the
+ * payload alone and the program stops compiling. The same union written out by
+ * hand behaves identically, so the test is a property of the type rather than of
+ * the `&&` that usually produces it.
+ *
+ * A union confined to a single domain is left alone: there the falsy member is a
+ * value of the payload's own kind, which is exactly the state the rule asks
+ * callers to preserve.
+ *
+ * Positive evidence from the checker is required. Without type information the
+ * answer is unknowable, and guessing would silence the rule across every
+ * untyped operand.
+ */
+function stripsForeignFalsyMember(node, checker, parserServices) {
+    if (!checker || !parserServices) {
+        return false;
+    }
+    let members;
+    try {
+        const tsNode = parserServices.esTreeNodeToTSNodeMap.get(node);
+        const type = checker.getTypeAtLocation(tsNode);
+        if (!type) {
+            return false;
+        }
+        members = unionMembers(type, checker);
+    }
+    catch {
+        // esTreeNodeToTSNodeMap may fail for synthetic nodes and getTypeAtLocation
+        // may throw for nodes without type information; both mean no evidence.
+        return false;
+    }
+    const sentinelDomains = new Set(members.filter(isNonNullishFalsy).map(domainOf));
+    if (sentinelDomains.size === 0) {
+        return false;
+    }
+    return members.some((member) => !isNullishMember(member) &&
+        !isNonNullishFalsy(member) &&
+        !sentinelDomains.has(domainOf(member)));
+}
 function isInJSXBooleanAttribute(node) {
     const parent = node.parent;
     if (parent?.type !== utils_1.AST_NODE_TYPES.JSXAttribute)
@@ -634,6 +750,11 @@ exports.preferNullishCoalescingBooleanProps = (0, createRule_1.createRule)({
                     // Check if this could benefit from nullish coalescing
                     // We only suggest nullish coalescing when the left operand could be nullish
                     if (couldBeNullish(node.left, checker, parserServices)) {
+                        // A `||` that strips a falsy sentinel from outside its payload's
+                        // domain cannot become `??` without changing the expression's type.
+                        if (stripsForeignFalsyMember(node.left, checker, parserServices)) {
+                            return;
+                        }
                         const sourceCode = context.getSourceCode();
                         const leftText = sourceCode.getText(node.left);
                         const rightText = sourceCode.getText(node.right);

package/lib/rules/require-props-composition.js

@@ -119,8 +119,8 @@ function getTypeReferenceName(node) {
 /**
  * Recursively check if a TS type node composes with the given propsTypeName
  * via Pick/Omit (at any level of intersection / Readonly wrapping, union arm,
- * named-alias indirection, or nested in a TSTypeLiteral property's type
- * annotation).
+ * array or tuple element, named-alias indirection, or nested in a TSTypeLiteral
+ * property's type annotation).
  *
  * `scope` (when supplied) is the node the alias lookup walks outward from, which
  * enables resolving a locally-declared named type alias to its definition, so
@@ -185,6 +185,46 @@ function typeNodeComposesWithProps(typeNode, propsTypeName, scope, seenAliases =
             // case, where every arm composes with the single shared child.
             return typeNode.types.some((t) => typeNodeComposesWithProps(t, propsTypeName, scope, seenAliases));
         }
+        case utils_1.AST_NODE_TYPES.TSArrayType: {
+            // A list renderer's composition lives in the ELEMENT type: a parent
+            // declaring `buttons: readonly ActionButtonProps[]` and spreading one
+            // element onto each child forwards the child's ENTIRE prop object, which
+            // is the same DRY guarantee a direct `Pick`/`Omit` prop gives — the
+            // composition is simply one level of indirection away, inside the array.
+            // The child's contract belongs to the element type there, so demanding a
+            // whole-props Pick/Omit on the parent would name a composition a list
+            // renderer must not have (issue #2038). This is the array analogue of the
+            // union-arm unwrapping issue #1343 established.
+            return typeNodeComposesWithProps(typeNode.elementType, propsTypeName, scope, seenAliases);
+        }
+        case utils_1.AST_NODE_TYPES.TSTupleType: {
+            // A tuple is a fixed-length list, and each slot is handed to a child
+            // exactly as an array element is, so any slot that composes composes.
+            return typeNode.elementTypes.some((element) => typeNodeComposesWithProps(element, propsTypeName, scope, seenAliases));
+        }
+        case utils_1.AST_NODE_TYPES.TSNamedTupleMember: {
+            // A tuple slot's label names the slot, never its surface.
+            return typeNodeComposesWithProps(typeNode.elementType, propsTypeName, scope, seenAliases);
+        }
+        case utils_1.AST_NODE_TYPES.TSOptionalType:
+        case utils_1.AST_NODE_TYPES.TSRestType: {
+            // `?` and `...` govern how many slots a tuple carries, not what a slot
+            // carries, so the decorated type is the surface to test.
+            return typeNodeComposesWithProps(typeNode.typeAnnotation, propsTypeName, scope, seenAliases);
+        }
+        case utils_1.AST_NODE_TYPES.TSTypeOperator: {
+            // `readonly T[]` describes the same prop surface as `T[]`: the modifier
+            // constrains mutation of the container, never the shape of its elements.
+            //
+            // Only `readonly` unwraps. `keyof ChildProps` is the child's KEY union — a
+            // set of strings that hands the child nothing — and `unique symbol` is a
+            // nominal token, so crediting either would let a parent that merely names
+            // the child's keys pass as composing with its props.
+            if (typeNode.operator !== 'readonly' || !typeNode.typeAnnotation) {
+                return false;
+            }
+            return typeNodeComposesWithProps(typeNode.typeAnnotation, propsTypeName, scope, seenAliases);
+        }
         case utils_1.AST_NODE_TYPES.TSTypeLiteral: {
             // Check property signatures for nested composition
             // e.g. { iconProps?: Omit<GradientIconButtonProps, 'IconComponent'> }

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "1.20.168",
+    "date": "2026-08-18T08:47:17.522Z",
+    "rules": [
+      {
+        "name": "memo-compare-deeply-complex-props",
+        "changeType": "fix",
+        "issues": [
+          2039
+        ],
+        "summary": "classify zero-declaration props by their carrier type (closes #2039)"
+      },
+      {
+        "name": "prefer-nullish-coalescing-boolean-props",
+        "changeType": "fix",
+        "issues": [
+          2040
+        ],
+        "summary": "keep || where it strips a short-circuit sentinel (closes #2040)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.167",
+    "date": "2026-08-18T04:28:02.499Z",
+    "rules": [
+      {
+        "name": "require-props-composition",
+        "changeType": "fix",
+        "issues": [
+          2038
+        ],
+        "summary": "credit composition through an array element (closes #2038)"
+      }
+    ]
+  },
   {
     "version": "1.20.166",
     "date": "2026-08-18T03:18:38.188Z",