@blumintinc/eslint-plugin-blumint 1.20.84 → 1.20.86

package/lib/index.js

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

package/lib/rules/prefer-spread-over-reassembly.js

@@ -1,6 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.preferSpreadOverReassembly = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
@@ -83,6 +88,75 @@ const ELEMENT_CALLBACK_METHODS = new Set([
     'flatMap',
 ]);
 const ARRAY_TYPE_NAMES = new Set(['Array', 'ReadonlyArray']);
+/**
+ * Type operators that are homomorphic over their argument: each one rewrites
+ * the modifiers of every member and leaves the key set identical, so a member
+ * list read through them describes the wrapped type exactly. `Readonly<{...}>`
+ * is the idiomatic spelling of a data record, and refusing to see through it
+ * makes the narrowing proof inert on the code it exists to protect (#1643).
+ *
+ * `Pick`, `Omit`, `Record`, `Exclude` and `Extract` are deliberately absent:
+ * they rewrite the key set, and a wrong proof silences a report the rule owes
+ * rather than merely failing to find one.
+ */
+const KEY_PRESERVING_TYPE_OPERATORS = new Set([
+    'Readonly',
+    'Required',
+    'Partial',
+]);
+/**
+ * Collects every name the file itself binds in a way that can stand in front of
+ * a type argument list — a type alias, an interface, a class, an enum, a
+ * namespace or an import. A file spelling `Readonly` as one of these is talking
+ * about its own declaration rather than the lib utility, so the key-preserving
+ * unwrap must not apply to it.
+ *
+ * The walk covers nested declarations too, since a `type Partial<T>` inside a
+ * function body shadows the global just as effectively as a top-level one.
+ */
+function collectLocallyBoundNames(node, names) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration:
+        case utils_1.AST_NODE_TYPES.TSInterfaceDeclaration:
+        case utils_1.AST_NODE_TYPES.TSEnumDeclaration:
+        case utils_1.AST_NODE_TYPES.TSImportEqualsDeclaration:
+            names.add(node.id.name);
+            break;
+        case utils_1.AST_NODE_TYPES.ClassDeclaration:
+        case utils_1.AST_NODE_TYPES.ClassExpression:
+            if (node.id) {
+                names.add(node.id.name);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.TSModuleDeclaration:
+            if (node.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+                names.add(node.id.name);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.ImportSpecifier:
+        case utils_1.AST_NODE_TYPES.ImportDefaultSpecifier:
+        case utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier:
+            names.add(node.local.name);
+            break;
+        default:
+            break;
+    }
+    for (const key of Object.keys(node)) {
+        if (key === 'parent')
+            continue;
+        const value = node[key];
+        if (Array.isArray(value)) {
+            for (const child of value) {
+                if (child && typeof child === 'object' && 'type' in child) {
+                    collectLocallyBoundNames(child, names);
+                }
+            }
+        }
+        else if (value && typeof value === 'object' && 'type' in value) {
+            collectLocallyBoundNames(value, names);
+        }
+    }
+}
 /**
  * Resolves `Promise<T>` to `T`, leaving anything else as it stands, which is
  * what `await` does to the type of the expression it operates on.
@@ -147,12 +221,8 @@ function namesOfMembers(members) {
     return names;
 }
 /**
- * Finds a type alias or interface declared at the top level of the file being
- * linted, including one that is exported.
- *
- * Resolution stops at the file boundary on purpose: an imported name's members
- * live in a module this rule cannot read, and guessing at them would be the
- * opposite of a proof.
+ * Finds a type alias or interface declared at the top level of a program,
+ * including one that is exported.
  */
 function findLocalTypeDeclaration(program, name) {
     for (const statement of program.body) {
@@ -168,42 +238,292 @@ function findLocalTypeDeclaration(program, name) {
     }
     return null;
 }
+/**
+ * Finds a type alias or interface a module exports by writing `export` in front
+ * of the declaration itself.
+ *
+ * Only that spelling qualifies. `export { X }` and `export { X } from './y'` are
+ * indistinguishable at the specifier — the second names a declaration in a third
+ * module — and `export * from './y'` names no declaration at all, so following
+ * either would be a guess rather than a proof.
+ */
+function findDirectlyExportedTypeDeclaration(program, name) {
+    for (const statement of program.body) {
+        if (statement.type !== utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+            !statement.declaration) {
+            continue;
+        }
+        const declaration = statement.declaration;
+        if ((declaration.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration ||
+            declaration.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration) &&
+            declaration.id.name === name) {
+            return declaration;
+        }
+    }
+    return null;
+}
+const RELATIVE_SOURCE = /^\.\.?\//;
+/**
+ * A type declaration overwhelmingly lives in a `.ts` sibling, so that extension
+ * is tried first; the rest follow a bundler's own order.
+ */
+const MODULE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+/**
+ * The resolution cache stores which path a specifier picks, never the file's
+ * contents: a resolution *miss* is safe to keep because a module created later
+ * stays unresolved, which reports. The member cache instead carries the resolved
+ * file's stamp as its VALUE, so a sibling edited under a long-lived host (the VS
+ * Code ESLint extension, eslint_d) is re-read rather than answered from a stale
+ * member list — a stale list is what would silence a report the rule owes. The
+ * stamp lives in the value so an edited file replaces its entry instead of
+ * accumulating one per revision.
+ */
+const moduleResolutionCache = new Map();
+const importedMembersCache = new Map();
+/**
+ * Stat a candidate path, returning its identity stamp when it is a file. The
+ * single stat both resolves existence and stamps the file, so reading a sibling
+ * never pays for two.
+ */
+function statModule(candidate) {
+    try {
+        const stats = fs_1.default.statSync(candidate);
+        return stats.isFile()
+            ? { filePath: candidate, mtimeMs: stats.mtimeMs, size: stats.size }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve a relative import specifier the way a bundler would: sibling file
+ * first, then the directory's index file. Package specifiers never reach here —
+ * a bare specifier names a module whose location depends on resolution settings
+ * this rule does not read, so it proves nothing.
+ */
+function resolveRelativeModule(fromDir, source) {
+    const cacheKey = JSON.stringify([fromDir, source]);
+    const cached = moduleResolutionCache.get(cacheKey);
+    if (cached !== undefined) {
+        return cached === null ? null : statModule(cached);
+    }
+    const base = path_1.default.resolve(fromDir, source);
+    let resolved = null;
+    for (const extension of MODULE_EXTENSIONS) {
+        resolved = statModule(`${base}${extension}`);
+        if (resolved) {
+            break;
+        }
+    }
+    if (!resolved) {
+        for (const extension of MODULE_EXTENSIONS) {
+            resolved = statModule(path_1.default.join(base, `index${extension}`));
+            if (resolved) {
+                break;
+            }
+        }
+    }
+    moduleResolutionCache.set(cacheKey, resolved?.filePath ?? null);
+    return resolved;
+}
+/**
+ * `undefined` means the parser has not been looked up yet; `null` means the
+ * lookup failed and must not be retried.
+ */
+let foreignParse;
+/**
+ * The sibling module is read with the parser that backs
+ * `@typescript-eslint/utils` itself, loaded lazily and memoized (failure
+ * included) so the resolution cost is paid once per process. An install that
+ * somehow lacks the parser degrades to "proves nothing", which keeps the rule
+ * reporting rather than throwing.
+ */
+function getForeignParse() {
+    if (foreignParse === undefined) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const estree = require('@typescript-eslint/typescript-estree');
+            foreignParse = estree?.parse ?? null;
+        }
+        catch {
+            foreignParse = null;
+        }
+    }
+    return foreignParse;
+}
+/**
+ * Parse a sibling module into an AST. Only a real parse can decide what a type
+ * declares: text that merely looks like a declaration — inside a string, a
+ * template literal, a comment or a nested scope — must never stand in for it. A
+ * file that cannot be read or parsed proves nothing.
+ */
+function parseModuleProgram(filePath) {
+    const parse = getForeignParse();
+    if (!parse) {
+        return null;
+    }
+    try {
+        return parse(fs_1.default.readFileSync(filePath, 'utf8'), {
+            jsx: true,
+            loc: false,
+            range: false,
+            comment: false,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Locate the relative import that introduces `localName` as a type.
+ *
+ * Only a named specifier qualifies, in either the `import type { X }` or the
+ * `import { X }` spelling. A namespace import is referenced as `Ns.X`, a
+ * qualified name this enumerator does not read, and a default-exported type has
+ * no name to look up in the sibling.
+ */
+function findRelativeTypeImport(program, localName) {
+    for (const statement of program.body) {
+        if (statement.type !== utils_1.AST_NODE_TYPES.ImportDeclaration ||
+            typeof statement.source.value !== 'string' ||
+            !RELATIVE_SOURCE.test(statement.source.value)) {
+            continue;
+        }
+        for (const specifier of statement.specifiers) {
+            if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                specifier.local.name === localName) {
+                return {
+                    source: statement.source.value,
+                    exported: specifier.imported.name,
+                };
+            }
+        }
+    }
+    return null;
+}
 /**
  * Enumerates every property name a type node declares, or null when the member
  * list cannot be established with certainty.
  *
- * Only an unambiguous, fully written-out member list qualifies. A union, an
- * intersection, a mapped or conditional type, a generic instantiation and an
- * interface with an `extends` clause all describe a member set assembled
- * elsewhere, so none of them can prove anything here.
+ * Only an unambiguous, fully written-out member list qualifies, reached either
+ * directly or through the key-preserving operators in
+ * {@link KEY_PRESERVING_TYPE_OPERATORS}. A union, an intersection, a mapped or
+ * conditional type, any other generic instantiation and an interface with an
+ * `extends` clause all describe a member set assembled elsewhere, so none of
+ * them can prove anything here.
+ *
+ * A name the file does not declare is looked up in the relative module that
+ * imports it, once; see {@link importedTypeMemberNames}.
  */
-function memberNamesOf(typeNode, program, seen = new Set()) {
+function memberNamesOf(typeNode, scope, seen = new Set()) {
     if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
         return namesOfMembers(typeNode.members);
     }
     if (typeNode.type !== utils_1.AST_NODE_TYPES.TSTypeReference ||
-        typeNode.typeName.type !== utils_1.AST_NODE_TYPES.Identifier ||
-        typeNode.typeParameters) {
+        typeNode.typeName.type !== utils_1.AST_NODE_TYPES.Identifier) {
         return null;
     }
     const name = typeNode.typeName.name;
+    if (typeNode.typeParameters) {
+        // An arity other than one is not the lib utility this name spells, so
+        // nothing about the wrapped member list follows from it.
+        if (!KEY_PRESERVING_TYPE_OPERATORS.has(name) ||
+            typeNode.typeParameters.params.length !== 1 ||
+            scope.isLocallyBound(name)) {
+            return null;
+        }
+        return memberNamesOf(typeNode.typeParameters.params[0], scope, seen);
+    }
     // A self-referential alias (`type T = T`) would otherwise recur forever.
     if (seen.has(name)) {
         return null;
     }
     seen.add(name);
-    const declaration = findLocalTypeDeclaration(program, name);
-    if (!declaration || declaration.typeParameters) {
+    const declaration = findLocalTypeDeclaration(scope.program, name);
+    if (!declaration) {
+        // The file does not declare the name, so the only remaining source of a
+        // written-down member list is the module it comes from.
+        return scope.resolveImportedMembers?.(name) ?? null;
+    }
+    return memberNamesOfDeclaration(declaration, scope, seen);
+}
+/**
+ * The member names a type alias or interface declares. A generic declaration
+ * describes a different member set per instantiation and an interface with an
+ * `extends` clause inherits members written elsewhere, so neither enumerates.
+ */
+function memberNamesOfDeclaration(declaration, scope, seen) {
+    if (declaration.typeParameters) {
         return null;
     }
     if (declaration.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
-        return memberNamesOf(declaration.typeAnnotation, program, seen);
+        return memberNamesOf(declaration.typeAnnotation, scope, seen);
     }
     if (declaration.extends && declaration.extends.length > 0) {
         return null;
     }
     return namesOfMembers(declaration.body.body);
 }
+/**
+ * The member names of a type the file under lint imports from a relative
+ * sibling, or null when the sibling proves nothing.
+ *
+ * Organising a module's types in a neighbouring `types.ts` is the ordinary
+ * layout, so a proof that stops at the file boundary misses the common case
+ * rather than the edge case (#1644). The hop is a single one: the sibling's own
+ * scope carries no `resolveImportedMembers`, so a type it in turn imports, a
+ * re-export and a barrel all stop the walk and leave the pick unproven, which
+ * reports. Within the sibling, resolution is the same enumerator the file under
+ * lint gets — alias chains, `Readonly`/`Required`/`Partial` unwrapping and the
+ * shadowing guard all behave identically there.
+ */
+function importedTypeMemberNames(program, fromDir, localName) {
+    const typeImport = findRelativeTypeImport(program, localName);
+    if (!typeImport) {
+        return null;
+    }
+    const resolved = resolveRelativeModule(fromDir, typeImport.source);
+    if (!resolved) {
+        return null;
+    }
+    const cacheKey = JSON.stringify([resolved.filePath, typeImport.exported]);
+    const cached = importedMembersCache.get(cacheKey);
+    if (cached &&
+        cached.mtimeMs === resolved.mtimeMs &&
+        cached.size === resolved.size) {
+        return cached.members;
+    }
+    const members = readExportedTypeMembers(resolved.filePath, typeImport.exported);
+    importedMembersCache.set(cacheKey, {
+        mtimeMs: resolved.mtimeMs,
+        size: resolved.size,
+        members,
+    });
+    return members;
+}
+function readExportedTypeMembers(filePath, exported) {
+    const siblingProgram = parseModuleProgram(filePath);
+    if (!siblingProgram) {
+        return null;
+    }
+    const declaration = findDirectlyExportedTypeDeclaration(siblingProgram, exported);
+    if (!declaration) {
+        return null;
+    }
+    let siblingBoundNames = null;
+    const siblingScope = {
+        program: siblingProgram,
+        isLocallyBound: (name) => {
+            if (!siblingBoundNames) {
+                siblingBoundNames = new Set();
+                collectLocallyBoundNames(siblingProgram, siblingBoundNames);
+            }
+            return siblingBoundNames.has(name);
+        },
+    };
+    return memberNamesOfDeclaration(declaration, siblingScope, new Set([exported]));
+}
 /**
  * For a JSX element, returns the set of destructured names that are forwarded
  * with identical key names (e.g. `hits={hits}`, `isLoading={isLoading}`).
@@ -627,6 +947,34 @@ exports.preferSpreadOverReassembly = (0, createRule_1.createRule)({
         const minFields = options?.minFields ?? DEFAULT_MIN_FIELDS;
         const sourceCode = context.getSourceCode();
         const program = sourceCode.ast;
+        // A relative specifier is anchored at the directory ESLint was configured
+        // with, never the node process cwd. The two differ under the VS Code ESLint
+        // extension, in monorepos and for any programmatic `new Linter({ cwd })`,
+        // and anchoring at the process cwd there reads the wrong directory — which
+        // in this rule's safe direction merely loses the proof, but loses it exactly
+        // where the sibling `types.ts` layout is most common (issue #1476).
+        const cwd = typeof context.getCwd === 'function' ? context.getCwd() : process.cwd();
+        const rawFilename = context.getFilename();
+        const containingDir = path_1.default.dirname(path_1.default.isAbsolute(rawFilename)
+            ? rawFilename
+            : path_1.default.resolve(cwd, rawFilename));
+        // The scan walks the whole file, so it is deferred until a key-preserving
+        // operator actually turns up in a position the proof depends on — most
+        // files never reach it.
+        let locallyBoundNames = null;
+        const typeScope = {
+            program,
+            isLocallyBound: (name) => {
+                if (!locallyBoundNames) {
+                    locallyBoundNames = new Set();
+                    collectLocallyBoundNames(program, locallyBoundNames);
+                }
+                return locallyBoundNames.has(name);
+            },
+            // Reached only from the about-to-report path, so a file with nothing to
+            // report never stats or reads a sibling.
+            resolveImportedMembers: (name) => importedTypeMemberNames(program, containingDir, name),
+        };
         /**
          * Walks an expression toward its syntactic root and returns the type node
          * that root declares, mirroring the receiver trace in
@@ -753,7 +1101,7 @@ exports.preferSpreadOverReassembly = (0, createRule_1.createRule)({
                 return null;
             }
             const elementType = arrayElementTypeOf(receiverType);
-            return elementType ? memberNamesOf(elementType, program) : null;
+            return elementType ? memberNamesOf(elementType, typeScope) : null;
         }
         /**
          * Reports whether the destructured pick is provably a PROPER subset of the
@@ -763,15 +1111,17 @@ exports.preferSpreadOverReassembly = (0, createRule_1.createRule)({
          *
          * The proof runs in the safe direction only. A member set that matches the
          * pick exactly is exhaustive, so the rewrite is behavior-preserving and the
-         * rule still reports; a type it cannot resolve — imported, generic, a union,
-         * an index signature — yields no proof and the rule likewise still reports.
-         * Silence is reserved for the case where the widening is demonstrated.
+         * rule still reports; a type it cannot resolve — a union, an index
+         * signature, an instantiation of anything but a key-preserving operator, or
+         * an import whose module it declines to follow — yields no proof and the
+         * rule likewise still reports. Silence is reserved for the case where the
+         * widening is demonstrated.
          */
         function isProvablyNarrowingPick(fn, param, destructuredNames) {
             // An explicit annotation overrides whatever the call site would imply,
             // so the contextual route is consulted only in its absence.
             const memberNames = param.typeAnnotation
-                ? memberNamesOf(param.typeAnnotation.typeAnnotation, program)
+                ? memberNamesOf(param.typeAnnotation.typeAnnotation, typeScope)
                 : contextualElementMemberNames(fn);
             if (!memberNames || memberNames.size <= destructuredNames.length) {
                 return false;

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,32 @@
 [
+  {
+    "version": "1.20.86",
+    "date": "2026-08-03T03:52:41.277Z",
+    "rules": [
+      {
+        "name": "prefer-spread-over-reassembly",
+        "changeType": "fix",
+        "issues": [
+          1644
+        ],
+        "summary": "prove narrowing through a relative import (closes #1644)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.85",
+    "date": "2026-08-03T03:21:29.711Z",
+    "rules": [
+      {
+        "name": "prefer-spread-over-reassembly",
+        "changeType": "fix",
+        "issues": [
+          1643
+        ],
+        "summary": "read the narrowing proof through Readonly (closes #1643)"
+      }
+    ]
+  },
   {
     "version": "1.20.84",
     "date": "2026-08-03T02:56:38.740Z",