@blumintinc/eslint-plugin-blumint 1.20.85 → 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.85',
+        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");
@@ -216,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) {
@@ -237,6 +238,170 @@ 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.
@@ -247,6 +412,9 @@ function findLocalTypeDeclaration(program, name) {
  * 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, scope, seen = new Set()) {
     if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
@@ -273,7 +441,20 @@ function memberNamesOf(typeNode, scope, seen = new Set()) {
     }
     seen.add(name);
     const declaration = findLocalTypeDeclaration(scope.program, name);
-    if (!declaration || declaration.typeParameters) {
+    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) {
@@ -284,6 +465,65 @@ function memberNamesOf(typeNode, scope, seen = new Set()) {
     }
     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}`).
@@ -707,6 +947,17 @@ 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.
@@ -720,6 +971,9 @@ exports.preferSpreadOverReassembly = (0, createRule_1.createRule)({
                 }
                 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
@@ -857,10 +1111,11 @@ 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, a union, an
-         * index signature, or an instantiation of anything but a key-preserving
-         * operator — 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,

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,18 @@
 [
+  {
+    "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",