@blumintinc/eslint-plugin-blumint 1.21.14 → 1.21.16

package/lib/index.js

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

package/lib/rules/enforce-empty-object-check.js

@@ -235,6 +235,234 @@ function isObjectLikeType(type, checker) {
     }
     return 'object';
 }
+/**
+ * Lib wrappers that hand back the shape they are given.
+ *
+ * `Readonly<T>` only adds modifiers and `Partial<T>` only removes
+ * required-ness, so a pinned `T` stays pinned through either, which is what
+ * makes `Readonly<Record<string, string>>` readable as the dictionary it is.
+ * The unwrapping applies only when the INNER type is itself pinned, so
+ * `Readonly<NextResponse>` stays unread and the class instance it names keeps
+ * its decline.
+ */
+const SHAPE_PRESERVING_TYPE_WRAPPERS = new Set(['Readonly', 'Partial']);
+/** Type keywords that contribute no shape to a union. */
+const NULLABLE_TYPE_KEYWORDS = new Set([
+    utils_1.AST_NODE_TYPES.TSNullKeyword,
+    utils_1.AST_NODE_TYPES.TSUndefinedKeyword,
+    utils_1.AST_NODE_TYPES.TSVoidKeyword,
+]);
+/** The statements a node holds directly, for a same-file declaration lookup. */
+function statementsOf(node) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.Program:
+        case utils_1.AST_NODE_TYPES.BlockStatement:
+        case utils_1.AST_NODE_TYPES.TSModuleBlock:
+            return node.body;
+        default:
+            return null;
+    }
+}
+/**
+ * The type a SAME-FILE alias stands for, walking outwards from the reference so
+ * that an inner declaration answers ahead of an outer one.
+ *
+ * Same-file is the whole boundary: an alias imported from a module this program
+ * did not load is not found here and stays unpinned, which is the line #2344
+ * drew. Following the import instead would need exactly the cross-file
+ * resolution whose absence puts this code on the fall-through in the first
+ * place.
+ *
+ * A GENERIC alias is unpinned for a related reason: its body is written against
+ * parameters this lookup does not substitute, and each parameter SHADOWS any
+ * same-file alias of the same name. Reading `type Wrapper<Cfg> = Readonly<Cfg>`
+ * against a sibling `type Cfg = Record<string, string>` calls
+ * `Wrapper<NextResponse>` a dictionary and reinstates the inverted guard.
+ */
+function resolveTypeAlias(reference, name) {
+    let current = reference;
+    while (current) {
+        const statements = statementsOf(current);
+        if (statements) {
+            for (const statement of statements) {
+                const declaration = statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+                    statement.declaration
+                    ? statement.declaration
+                    : statement;
+                if (declaration.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration &&
+                    declaration.id.name === name) {
+                    return declaration.typeParameters ? null : declaration.typeAnnotation;
+                }
+            }
+        }
+        current = current.parent;
+    }
+    return null;
+}
+/**
+ * The shape an object type literal writes out.
+ *
+ * The members answer the same question `isObjectLikeType` asks of a resolved
+ * type: a required property makes `Object.keys()` non-empty for every valid
+ * value, and a call or construct signature marks behaviour rather than data, so
+ * either one leaves the literal unpinned.
+ */
+function pinnedShapeOfMembers(members) {
+    let shape = 'optional';
+    for (const member of members) {
+        switch (member.type) {
+            case utils_1.AST_NODE_TYPES.TSIndexSignature:
+                shape = 'index';
+                break;
+            case utils_1.AST_NODE_TYPES.TSPropertySignature:
+            case utils_1.AST_NODE_TYPES.TSMethodSignature:
+                if (!member.optional) {
+                    return null;
+                }
+                break;
+            default:
+                return null;
+        }
+    }
+    return shape;
+}
+/**
+ * Whether a declared type the checker cannot resolve nonetheless SPELLS a
+ * dictionary, and with which shape.
+ *
+ * A union answers as soon as one member spells one, mirroring
+ * `isObjectLikeType`, where any object-like member makes the whole union
+ * object-like. An intersection is the opposite and needs every member pinned:
+ * `Record<string, string> & SomeClass` carries the class's required members, so
+ * a complete program calls it `non-object`, and reading it as a dictionary
+ * would recreate the inverted guard the surrounding branch exists to prevent.
+ *
+ * `expanding` holds the aliases on the current expansion PATH rather than every
+ * alias seen, so a self-referential alias terminates while an alias named twice
+ * in sibling positions is still read at each of them.
+ */
+function pinnedShapeOf(node, expanding = new Set()) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.TSTypeLiteral:
+            return pinnedShapeOfMembers(node.members);
+        case utils_1.AST_NODE_TYPES.TSUnionType: {
+            const shapes = node.types
+                .filter((member) => !NULLABLE_TYPE_KEYWORDS.has(member.type))
+                .map((member) => pinnedShapeOf(member, expanding));
+            if (!shapes.some((shape) => shape !== null)) {
+                return null;
+            }
+            return shapes.every((shape) => shape === 'index') ? 'index' : 'optional';
+        }
+        case utils_1.AST_NODE_TYPES.TSIntersectionType: {
+            const shapes = node.types.map((member) => pinnedShapeOf(member, expanding));
+            if (shapes.some((shape) => shape === null)) {
+                return null;
+            }
+            return shapes.every((shape) => shape === 'index') ? 'index' : 'optional';
+        }
+        case utils_1.AST_NODE_TYPES.TSTypeReference: {
+            if (node.typeName.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return null;
+            }
+            const { name } = node.typeName;
+            /**
+             * A same-file alias is read ahead of the lib names, so a file declaring
+             * its own `Record` or `Readonly` is answered by what it wrote.
+             */
+            const alias = resolveTypeAlias(node, name);
+            if (alias) {
+                if (expanding.has(alias)) {
+                    return null;
+                }
+                expanding.add(alias);
+                const aliased = pinnedShapeOf(alias, expanding);
+                expanding.delete(alias);
+                return aliased;
+            }
+            if (name === 'Record') {
+                return 'index';
+            }
+            const args = node.typeParameters?.params ?? [];
+            if (args.length !== 1) {
+                return null;
+            }
+            if (SHAPE_PRESERVING_TYPE_WRAPPERS.has(name)) {
+                return pinnedShapeOf(args[0], expanding);
+            }
+            /**
+             * `Required<T>` makes every named member required, so it preserves only a
+             * type whose keys come from an index signature. `Required<{ a?: string }>`
+             * carries a required property and is `non-object` to a complete program.
+             */
+            if (name === 'Required') {
+                return pinnedShapeOf(args[0], expanding) === 'index' ? 'index' : null;
+            }
+            return null;
+        }
+        default:
+            return null;
+    }
+}
+/** Wrappers whose awaited value is the single argument they carry. */
+const AWAITED_TYPE_WRAPPERS = new Set(['Promise', 'PromiseLike']);
+/**
+ * The value an `await` on this declared type produces.
+ *
+ * Without it an `async` declaration states its shape one wrapper out of reach:
+ * `Promise<Record<string, string>>` is not itself a dictionary, so the awaited
+ * dictionary would go unread and the guard the rule exists to add would be
+ * dropped. A declared type that is not a promise passes through unchanged,
+ * because awaiting a plain value yields that same value.
+ */
+function unwrapAwaitedType(node) {
+    if (node.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+        node.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+        AWAITED_TYPE_WRAPPERS.has(node.typeName.name) &&
+        node.typeParameters?.params.length === 1) {
+        return unwrapAwaitedType(node.typeParameters.params[0]);
+    }
+    return node;
+}
+/**
+ * Whether an assertion is `as const`, which pins mutability rather than shape.
+ *
+ * `const` is not a type the source names, so treating it as one would answer
+ * `load() as const` with "the source says nothing about the shape" when the
+ * asserted expression may state it perfectly well.
+ */
+function isConstAssertion(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+        node.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+        node.typeName.name === 'const');
+}
+/**
+ * The return type a class writes on the named member, when it writes one.
+ *
+ * Only the class's OWN body is read: a return type inherited through `extends`
+ * lives in whichever declaration that clause resolves to, and reaching it is
+ * the cross-file resolution whose absence puts this code on the fall-through.
+ */
+function returnTypeOfMethod(declaration, name) {
+    for (const member of declaration.body.body) {
+        if (member.type !== utils_1.AST_NODE_TYPES.MethodDefinition &&
+            member.type !== utils_1.AST_NODE_TYPES.PropertyDefinition) {
+            continue;
+        }
+        if (member.computed ||
+            member.key.type !== utils_1.AST_NODE_TYPES.Identifier ||
+            member.key.name !== name) {
+            continue;
+        }
+        const value = member.value;
+        if (value &&
+            (value.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+                value.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression)) {
+            return value.returnType?.typeAnnotation ?? null;
+        }
+    }
+    return null;
+}
 /**
  * Reads through an optional chain to the member access or call it holds.
  * `Object?.keys?.(payload)?.length` parses as a single `ChainExpression`
@@ -1404,6 +1632,197 @@ exports.enforceEmptyObjectCheck = (0, createRule_1.createRule)({
             }
             return false;
         }
+        /**
+         * The type the DECLARATION behind this value writes, if it writes one.
+         *
+         * An import is answered ahead of this by `tracesToImport`; what remains
+         * is every place the file states the type of the value a guard tests. A
+         * binding annotation is one of them and not the only one — an annotated
+         * function return, a class method's return and a type assertion state it
+         * just as directly — and reading only the binding left the naming
+         * heuristic deciding alone at six other declaration sites, which is how
+         * `const response = build()` off a `Readonly<NextResponse>` return kept
+         * being rewritten into a guard that holds for every valid value (#2346).
+         *
+         * The annotation has to sit on the BINDING rather than around it: the one
+         * on `const { config }: Props = load()` describes the container, and
+         * reading it as a verdict on a single property would need exactly the
+         * resolution that failed, so a destructured binding keeps the heuristic.
+         *
+         * `expanding` holds the bindings on the current expansion PATH, so a
+         * binding initialized from itself terminates while a binding named twice
+         * in sibling positions is still read at each of them.
+         */
+        function declaredTypeOf(identifier, expanding = new Set()) {
+            const variable = variableFor(identifier);
+            if (!variable || expanding.has(variable)) {
+                return null;
+            }
+            for (const def of variable.defs) {
+                if (def.type !== 'Parameter' && def.type !== 'Variable') {
+                    continue;
+                }
+                if (def.name.typeAnnotation) {
+                    return def.name.typeAnnotation.typeAnnotation;
+                }
+                if (def.node.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+                    def.node.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    def.node.init) {
+                    expanding.add(variable);
+                    const initialized = declaredTypeOfExpression(def.node.init, expanding);
+                    expanding.delete(variable);
+                    if (initialized) {
+                        return initialized;
+                    }
+                }
+            }
+            return null;
+        }
+        /**
+         * The type an initializer states for the value it produces.
+         *
+         * `satisfies` is deliberately absent: it checks an expression against a
+         * type without changing the type, so the value keeps whatever the
+         * expression already carried and a complete program reaches the heuristic
+         * there too. A spelling this switch does not recognize answers `null`,
+         * which leaves the guard exactly where it sat before the declaration
+         * sites were read at all.
+         */
+        function declaredTypeOfExpression(node, expanding) {
+            switch (node.type) {
+                case utils_1.AST_NODE_TYPES.TSAsExpression:
+                case utils_1.AST_NODE_TYPES.TSTypeAssertion:
+                    return isConstAssertion(node.typeAnnotation)
+                        ? declaredTypeOfExpression(node.expression, expanding)
+                        : node.typeAnnotation;
+                case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+                case utils_1.AST_NODE_TYPES.ChainExpression:
+                    return declaredTypeOfExpression(node.expression, expanding);
+                case utils_1.AST_NODE_TYPES.AwaitExpression: {
+                    const awaited = declaredTypeOfExpression(node.argument, expanding);
+                    return awaited ? unwrapAwaitedType(awaited) : null;
+                }
+                case utils_1.AST_NODE_TYPES.CallExpression:
+                    return declaredReturnTypeOf(node.callee, expanding);
+                case utils_1.AST_NODE_TYPES.Identifier:
+                    return declaredTypeOf(node, expanding);
+                default:
+                    return null;
+            }
+        }
+        /**
+         * The return type the callee's SAME-FILE declaration writes.
+         *
+         * A callee resolving into a module this program did not load is answered
+         * by `tracesToImport` before this runs, so reaching here means the
+         * declaration is one this file can be read for — the same boundary the
+         * same-file alias lookup draws.
+         */
+        function declaredReturnTypeOf(callee, expanding) {
+            if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+                const variable = variableFor(callee);
+                if (!variable) {
+                    return null;
+                }
+                for (const def of variable.defs) {
+                    if (def.type === 'FunctionName') {
+                        return def.node.returnType?.typeAnnotation ?? null;
+                    }
+                    if (def.type === 'Variable' &&
+                        def.node.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+                        (def.node.init?.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                            def.node.init?.type === utils_1.AST_NODE_TYPES.FunctionExpression)) {
+                        return def.node.init.returnType?.typeAnnotation ?? null;
+                    }
+                }
+                return null;
+            }
+            if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                !callee.computed &&
+                callee.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+                const declaration = classDeclarationOf(callee.object, expanding);
+                return declaration
+                    ? returnTypeOfMethod(declaration, callee.property.name)
+                    : null;
+            }
+            return null;
+        }
+        /**
+         * The same-file class an expression is an instance of, or names.
+         *
+         * A receiver whose class is not written in this file yields `null`, so
+         * the method's return type stays unread rather than being guessed from a
+         * same-named method on an unrelated class.
+         */
+        function classDeclarationOf(node, expanding) {
+            if (node.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return null;
+            }
+            const variable = variableFor(node);
+            if (!variable || expanding.has(variable)) {
+                return null;
+            }
+            for (const def of variable.defs) {
+                if (def.type === 'ClassName') {
+                    return def.node;
+                }
+                if (def.type !== 'Variable' ||
+                    def.node.type !== utils_1.AST_NODE_TYPES.VariableDeclarator ||
+                    !def.node.init) {
+                    continue;
+                }
+                const { init } = def.node;
+                if (init.type === utils_1.AST_NODE_TYPES.ClassExpression) {
+                    return init;
+                }
+                if (init.type === utils_1.AST_NODE_TYPES.NewExpression) {
+                    expanding.add(variable);
+                    const declaration = classDeclarationOf(init.callee, expanding);
+                    expanding.delete(variable);
+                    if (declaration) {
+                        return declaration;
+                    }
+                }
+            }
+            return null;
+        }
+        /**
+         * Whether a declared type declares NOTHING.
+         *
+         * An explicit `any` is the checker reporting what the source told it, not
+         * a resolution failure, so it leaves the value in the same position as an
+         * unannotated one and the naming heuristic keeps answering. An
+         * intersection carrying `any` reduces to `any`, so it says as little as a
+         * union carrying one. `unknown` is excluded from this reading on purpose:
+         * `Object.keys` rejects an `unknown` operand, so the fix the heuristic
+         * would attach there does not typecheck.
+         */
+        function declaresNothing(node) {
+            if (node.type === utils_1.AST_NODE_TYPES.TSUnionType ||
+                node.type === utils_1.AST_NODE_TYPES.TSIntersectionType) {
+                return node.types.some(declaresNothing);
+            }
+            return node.type === utils_1.AST_NODE_TYPES.TSAnyKeyword;
+        }
+        /**
+         * Whether a declared type the checker could not resolve nonetheless
+         * SPELLS an index-signature dictionary.
+         *
+         * `Record<K, V>` is an index signature whichever way `K` and `V` resolve,
+         * so the value is a plain data map rather than a class instance and
+         * `Object.keys` measures its emptiness correctly. Reading that from the
+         * source keeps the verdict a complete program gives — `object` — reachable
+         * without one, and the SPELLING is not what carries the guarantee: a
+         * shape-preserving wrapper, a union member, an intersection whose every
+         * member is pinned and a same-file alias each state the same index
+         * signature, and reading only the bare reference left ten such shapes
+         * silent that a complete program reports (#2345). A reference the source
+         * does not pin this way, `Readonly<NextResponse>` among them, carries no
+         * such guarantee.
+         */
+        function spellsDictionary(node) {
+            return pinnedShapeOf(node) !== null;
+        }
         function isLikelyObject(identifier) {
             if (checker && parserServices?.esTreeNodeToTSNodeMap) {
                 try {
@@ -1424,13 +1843,39 @@ exports.enforceEmptyObjectCheck = (0, createRule_1.createRule)({
                      * absence of evidence became evidence the value can be `{}`.
                      *
                      * The heuristic is still the right answer for a value with no
-                     * declaration to resolve — removing it outright silences 52 of this
-                     * rule's own 92 fixtures — so only the unresolved-IMPORT case is
-                     * carved out (#2252).
+                     * declaration to resolve — removing it outright silences 56 of this
+                     * rule's own 108 fixtures — so the fall-through is carved out only
+                     * where evidence EXISTS and went unread: a value from an unresolved
+                     * IMPORT (#2252), and a binding that DECLARES a type the checker
+                     * could not resolve (#2344). An unresolvable annotation means the
+                     * checker could not look, not that the value is loosely typed:
+                     * `response: Readonly<NextResponse>` read off its name alone
+                     * reported a class instance, whose state lives behind prototype
+                     * accessors, so the prescribed `Object.keys` clause holds for every
+                     * valid value and inverts the guard it was meant to harden.
+                     *
+                     * The carve-out costs reach, and the cost is measured rather than
+                     * assumed: across the consumer's 14,059 tracked sources it drops 8
+                     * reports, and re-running each under a real `ts.Program` — the
+                     * verdict this arm exists to preserve — agrees with 6 of them. The
+                     * remaining 2 annotate an all-optional imported type
+                     * (`Record<string, string[]>` behind a local alias, and an
+                     * `algoliasearch-helper` parameter bag), which a resolved program
+                     * calls `object` and reports. Nothing at the annotation site
+                     * separates those from `Readonly<NextResponse>`: both are bare
+                     * references into a module this program did not load, so recovering
+                     * them needs the cross-file resolution whose absence defines this
+                     * branch. Two silent true positives is the accepted price of six
+                     * guard inversions, because a fix that rewrites correct code costs
+                     * more than one the rule declines to make.
                      */
                     if (tracesToImport(identifier)) {
                         return false;
                     }
+                    const declared = declaredTypeOf(identifier);
+                    if (declared && !declaresNothing(declared)) {
+                        return spellsDictionary(declared);
+                    }
                 }
                 catch {
                     // TypeScript parser services can throw when AST-to-TS node mapping fails; fall back to naming heuristic so linting does not crash.