@blumintinc/eslint-plugin-blumint 1.20.49 → 1.20.51

package/lib/rules/enforce-object-literal-as-const.js

@@ -3,6 +3,143 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceObjectLiteralAsConst = void 0;
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
+const FUNCTION_TYPES = new Set([
+    'FunctionDeclaration',
+    'FunctionExpression',
+    'ArrowFunctionExpression',
+]);
+/**
+ * A `return` inside a generator yields the generator type's *second* type
+ * argument; the first types the `yield`s. `IterableIterator` and friends leave
+ * `TReturn` unparameterised, so they carry no constraint on the returned value.
+ */
+const GENERATOR_TYPE_NAMES = new Set(['Generator', 'AsyncGenerator']);
+const PROMISE_TYPE_NAMES = new Set(['Promise', 'PromiseLike']);
+/**
+ * A readonly tuple is assignable to none of these, so a union member spelled
+ * this way cannot rescue an `as const` the rest of the union rejects.
+ */
+const NON_ARRAY_KEYWORDS = new Set([
+    'TSBigIntKeyword',
+    'TSBooleanKeyword',
+    'TSLiteralType',
+    'TSNeverKeyword',
+    'TSNullKeyword',
+    'TSNumberKeyword',
+    'TSStringKeyword',
+    'TSSymbolKeyword',
+    'TSUndefinedKeyword',
+    'TSVoidKeyword',
+]);
+/**
+ * Type arguments are `typeParameters` on this parser version and
+ * `typeArguments` on newer ones; both spell the same `<T>` after the name.
+ */
+function typeArgumentsOf(node) {
+    const withTypeArgs = node;
+    return ((withTypeArgs.typeArguments ?? withTypeArgs.typeParameters)?.params ?? []);
+}
+function typeReferenceNameOf(node) {
+    if (node.type !== 'TSTypeReference' || node.typeName.type !== 'Identifier') {
+        return undefined;
+    }
+    return node.typeName.name;
+}
+/**
+ * Whether a readonly tuple — what `as const` makes of an array literal — can be
+ * assigned to this annotation, judged from syntax alone.
+ *
+ * Only shapes the annotation states outright are treated as hostile. Anything
+ * the rule cannot resolve (a type reference, a type parameter, an object type)
+ * counts as accepting, because declining on no evidence would silence the rule
+ * across most annotated code.
+ */
+function acceptsReadonlyArray(typeNode) {
+    switch (typeNode.type) {
+        // `string[]` and `[string, number]` are mutable: TS4104 rejects a readonly
+        // tuple assigned to either.
+        case 'TSArrayType':
+        case 'TSTupleType':
+            return false;
+        // `readonly string[]` / `readonly [string, number]`.
+        case 'TSTypeOperator':
+            return typeNode.operator === 'readonly';
+        case 'TSTypeReference':
+            return typeReferenceNameOf(typeNode) !== 'Array';
+        // Assignable to the union as a whole iff assignable to some member.
+        case 'TSUnionType':
+            return typeNode.types.some(acceptsReadonlyArray);
+        case 'TSIntersectionType':
+            return typeNode.types.every(acceptsReadonlyArray);
+        default:
+            return !NON_ARRAY_KEYWORDS.has(typeNode.type);
+    }
+}
+/**
+ * The type a function type annotation declares for its return value, or
+ * `undefined` when the annotation is not a function type (a type reference to
+ * an aliased signature, say) and so states nothing resolvable here.
+ */
+function returnTypeOfFunctionType(typeNode) {
+    if (typeNode?.type !== 'TSFunctionType') {
+        return undefined;
+    }
+    return typeNode.returnType?.typeAnnotation;
+}
+/**
+ * The declared return type visible for `fn`, whether written on the function
+ * itself (`function f(): string[]`) or on the site that declares it — a typed
+ * variable, a typed class property, or an assertion on the function expression.
+ *
+ * A callback passed as a call argument is deliberately not resolved: its
+ * contextual type lives on the callee's declaration, which is usually in
+ * another file, and the in-file shapes that do reach here (`useMemo`, `.map`)
+ * annotate their callbacks generically rather than with a mutable array.
+ */
+function declaredReturnTypeOf(fn) {
+    if (fn.returnType) {
+        return fn.returnType.typeAnnotation;
+    }
+    const { parent } = fn;
+    if (!parent) {
+        return undefined;
+    }
+    if (parent.type === 'VariableDeclarator') {
+        return parent.id.type === 'Identifier'
+            ? returnTypeOfFunctionType(parent.id.typeAnnotation?.typeAnnotation)
+            : undefined;
+    }
+    if (parent.type === 'PropertyDefinition') {
+        return returnTypeOfFunctionType(parent.typeAnnotation?.typeAnnotation);
+    }
+    if (parent.type === 'TSAsExpression') {
+        return returnTypeOfFunctionType(parent.typeAnnotation);
+    }
+    return undefined;
+}
+/**
+ * The type the *returned expression* must satisfy. For an async function or a
+ * generator the declared return type wraps that expression's type, so the
+ * wrapper is peeled off before the annotation is judged.
+ */
+function returnedValueTypeOf(fn) {
+    const declared = declaredReturnTypeOf(fn);
+    if (!declared) {
+        return undefined;
+    }
+    const referenceName = typeReferenceNameOf(declared);
+    if (fn.generator) {
+        return referenceName && GENERATOR_TYPE_NAMES.has(referenceName)
+            ? typeArgumentsOf(declared)[1]
+            : undefined;
+    }
+    if (fn.async) {
+        return referenceName && PROMISE_TYPE_NAMES.has(referenceName)
+            ? typeArgumentsOf(declared)[0]
+            : undefined;
+    }
+    return declared;
+}
 exports.enforceObjectLiteralAsConst = (0, createRule_1.createRule)({
     name: 'enforce-object-literal-as-const',
     meta: {
@@ -55,6 +192,44 @@ exports.enforceObjectLiteralAsConst = (0, createRule_1.createRule)({
         function isArrayLiteral(node) {
             return node.type === 'ArrayExpression';
         }
+        /**
+         * The function the `return` belongs to — the nearest one, so a `return`
+         * inside a nested callback is judged against that callback's annotation
+         * rather than the outer function's.
+         */
+        function enclosingFunctionOf(ancestors) {
+            for (let i = ancestors.length - 1; i >= 0; i--) {
+                const ancestor = ancestors[i];
+                if (FUNCTION_TYPES.has(ancestor.type)) {
+                    return ancestor;
+                }
+            }
+            return undefined;
+        }
+        /**
+         * `as const` turns an array literal into a readonly *tuple*, which TS4104
+         * refuses to assign to a mutable array or tuple. Where the annotation says
+         * the value must be mutable, appending `as const` breaks the build, and no
+         * edit at the literal can satisfy the rule — honouring it would mean
+         * rewriting the signature, a call the author has to make. So the rule stays
+         * silent rather than reporting something the developer cannot act on
+         * (#1526).
+         *
+         * Object literals are unaffected: `readonly` property modifiers do not
+         * enter assignability, so `{ a: 1 } as const` still satisfies a mutable
+         * `{ a: number }`.
+         */
+        function conflictsWithDeclaredType(literal, ancestors) {
+            if (!isArrayLiteral(literal)) {
+                return false;
+            }
+            const enclosingFunction = enclosingFunctionOf(ancestors);
+            if (!enclosingFunction) {
+                return false;
+            }
+            const returnedValueType = returnedValueTypeOf(enclosingFunction);
+            return !!returnedValueType && !acceptsReadonlyArray(returnedValueType);
+        }
         return {
             ReturnStatement(node) {
                 // Skip if there's no argument in the return statement
@@ -102,12 +277,18 @@ exports.enforceObjectLiteralAsConst = (0, createRule_1.createRule)({
                         argument.elements.some((elem) => elem !== null && elem.type === 'SpreadElement'))) {
                     return;
                 }
+                const literal = argument.type === 'TSAsExpression'
+                    ? argument.expression
+                    : argument;
                 // Skip arrays returned from React hooks (memoized data/prop lists that
                 // must not be frozen into readonly tuples — see #511 and #1324)
-                if (isInsideReactHook(ancestors) &&
-                    isArrayLiteral(argument.type === 'TSAsExpression'
-                        ? argument.expression
-                        : argument)) {
+                if (isInsideReactHook(ancestors) && isArrayLiteral(literal)) {
+                    return;
+                }
+                // Skip arrays the enclosing signature declares mutable: `as const`
+                // cannot compile there and the developer cannot act on the report
+                // (#1526)
+                if (conflictsWithDeclaredType(literal, ancestors)) {
                     return;
                 }
                 // Report the issue and provide a fix

package/lib/rules/enforce-timestamp-now.d.ts

@@ -1 +1,2 @@
-export declare const enforceTimestampNow: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"preferTimestampNow", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+import { TSESLint } from '@typescript-eslint/utils';
+export declare const enforceTimestampNow: TSESLint.RuleModule<"preferTimestampNow", [], TSESLint.RuleListener>;

package/lib/rules/enforce-timestamp-now.js

@@ -3,6 +3,31 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceTimestampNow = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const FIRESTORE_MODULES = new Set([
+    'firebase-admin/firestore',
+    'firebase/firestore',
+]);
+/**
+ * Members whose meaning survives the `new Date()` → `Timestamp.now()` rewrite,
+ * taken from the shipped typings rather than from `Date`'s surface:
+ * `@google-cloud/firestore` (what `firebase-admin/firestore` re-exports)
+ * declares `seconds`, `nanoseconds`, `toDate()`, `toMillis()`, `isEqual()` and
+ * `valueOf()`, and `@firebase/firestore` adds `toString()` and `toJSON()`.
+ *
+ * `valueOf`, `toString` and `toJSON` are excluded on purpose even though
+ * `Timestamp` declares them, because their contracts differ from `Date`'s:
+ * `Timestamp#valueOf()` returns an encoded `string` where `Date#valueOf()`
+ * returns a `number`, and the string forms render `Timestamp(seconds=…,
+ * nanoseconds=…)` instead of a date. Those call sites keep compiling while the
+ * value silently changes, which is harder to catch than a type error.
+ */
+const TIMESTAMP_COMPATIBLE_MEMBERS = new Set([
+    'toDate',
+    'toMillis',
+    'isEqual',
+    'seconds',
+    'nanoseconds',
+]);
 exports.enforceTimestampNow = (0, createRule_1.createRule)({
     name: 'enforce-timestamp-now',
     meta: {
@@ -35,8 +60,121 @@ exports.enforceTimestampNow = (0, createRule_1.createRule)({
         if (filename.includes('.test.') || filename.includes('.spec.')) {
             return {};
         }
-        // Track Timestamp imports and aliases
+        // Names that may denote the Firestore `Timestamp` class when matching
+        // `X.fromDate(new Date())` / `X.fromMillis(Date.now())`. Seeded with the
+        // default name so detection still works when the class reaches the file
+        // through a re-export or a `require()` the rule cannot see. Those reports
+        // rewrite an expression whose object identifier is already written in the
+        // source, so a seeded name can never produce an unbound reference.
         const timestampAliases = new Set(['Timestamp']);
+        // Names actually bound by an observed `Timestamp` import. Tracked apart
+        // from `timestampAliases` because the `new Date()` fix synthesizes an
+        // identifier the original code never mentions: with no real import the
+        // rewrite emits an unbound `Timestamp` and turns compiling code into
+        // TS2304 (issue #1521).
+        const importedTimestampAliases = [];
+        function recordTimestampAlias(localName) {
+            timestampAliases.add(localName);
+            if (!importedTimestampAliases.includes(localName)) {
+                importedTimestampAliases.push(localName);
+            }
+        }
+        /**
+         * Local names a static Firestore import binds to `Timestamp` as a *value*.
+         *
+         * A type-only binding is erased at emit, so referencing it from the
+         * synthesized `Timestamp.now()` turns compiling code into TS1361 (issue
+         * #1530). This is the same shape as #1521: the gate has to prove not just
+         * that a binding exists but that it is the kind of binding the emitted code
+         * requires. Both spellings are type-only and neither implies the other —
+         * `import type { Timestamp }` marks the declaration while leaving its
+         * specifier `value`, and `import { type Timestamp }` marks the specifier
+         * while leaving the declaration `value`.
+         */
+        function staticTimestampAliases(node) {
+            if (typeof node.source.value !== 'string' ||
+                !FIRESTORE_MODULES.has(node.source.value) ||
+                node.importKind === 'type') {
+                return [];
+            }
+            return node.specifiers
+                .filter((specifier) => specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                specifier.importKind !== 'type' &&
+                specifier.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+                specifier.imported.name === 'Timestamp')
+                .map((specifier) => specifier.local.name);
+        }
+        /**
+         * Local names a `const { Timestamp } = await import(...)` declarator binds
+         * to `Timestamp`.
+         *
+         * No type-only screen is needed here the way the static path needs one
+         * (#1530): a destructured `await import(...)` is a runtime value binding by
+         * construction. TypeScript spells a type-only dynamic import as the
+         * `import('...').Timestamp` type node, which never appears as a variable
+         * initializer, and `ImportExpression` carries no `importKind` to check.
+         */
+        function dynamicTimestampAliases(node) {
+            if (node.init?.type !== utils_1.AST_NODE_TYPES.AwaitExpression ||
+                node.init.argument.type !== utils_1.AST_NODE_TYPES.ImportExpression ||
+                node.id.type !== utils_1.AST_NODE_TYPES.ObjectPattern) {
+                return [];
+            }
+            const source = node.init.argument.source;
+            if (source.type !== utils_1.AST_NODE_TYPES.Literal ||
+                typeof source.value !== 'string' ||
+                !FIRESTORE_MODULES.has(source.value)) {
+                return [];
+            }
+            const aliases = [];
+            node.id.properties.forEach((prop) => {
+                if (prop.type === utils_1.AST_NODE_TYPES.Property &&
+                    prop.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    prop.key.name === 'Timestamp' &&
+                    prop.value.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    aliases.push(prop.value.name);
+                }
+            });
+            return aliases;
+        }
+        /** Whether a resolved binding is the Firestore `Timestamp` class itself. */
+        function isTimestampImportBinding(variable) {
+            return variable.defs.some((def) => {
+                if (def.node.type === utils_1.AST_NODE_TYPES.ImportSpecifier) {
+                    const declaration = def.node.parent;
+                    return (declaration?.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                        staticTimestampAliases(declaration).includes(variable.name));
+                }
+                if (def.node.type === utils_1.AST_NODE_TYPES.VariableDeclarator) {
+                    return dynamicTimestampAliases(def.node).includes(variable.name);
+                }
+                return false;
+            });
+        }
+        /** The binding a name resolves to at the node currently being visited. */
+        function resolveBinding(name) {
+            let scope = context.getScope();
+            while (scope) {
+                const binding = scope.variables.find((variable) => variable.name === name);
+                if (binding) {
+                    return binding;
+                }
+                scope = scope.upper;
+            }
+            return undefined;
+        }
+        // A synthesized `Timestamp.now()` is only safe when the alias resolves to
+        // the import at the rewrite site. Resolution has to run per name from the
+        // innermost scope outward: an alias bound by a dynamic import inside another
+        // function is unreachable here, and an inner binding of the same name would
+        // capture the emitted reference and silently swap in a different value
+        // (issues #1455/#1456).
+        function findTimestampAliasInScope() {
+            return importedTimestampAliases.find((alias) => {
+                const binding = resolveBinding(alias);
+                return !!binding && isTimestampImportBinding(binding);
+            });
+        }
         function isTimestampFromDateWithNewDate(node) {
             // Check if it's a Timestamp.fromDate(new Date()) call
             if (node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression) {
@@ -95,64 +233,77 @@ exports.enforceTimestampNow = (0, createRule_1.createRule)({
                 node.callee.name === 'Date' &&
                 node.arguments.length === 0);
         }
-        // Check if a Date object is being modified (e.g., futureDate.setDate())
-        function isDateBeingModified(dateVar) {
-            // Look through the scope to find if this variable is modified
-            const scope = context.getScope();
-            const variable = scope.variables.find((v) => v.name === dateVar);
-            if (!variable)
+        /**
+         * Whether a single use of the rewritten binding would still type-check and
+         * mean the same thing once its initializer is a `Timestamp`.
+         *
+         * Only a read of a member that `Timestamp` shares with `Date` qualifies.
+         * Every other shape — a write, an argument, a return, a comparison, an
+         * interpolation, a computed access — hands the value to a position whose
+         * expected type this rule cannot see, so it cannot be shown safe.
+         */
+        function isTimestampCompatibleReference(reference) {
+            // The declaration's own initializer write is the site being rewritten,
+            // not a use of the resulting value.
+            if (reference.init) {
+                return true;
+            }
+            // A later assignment rebinds the variable to a value typed elsewhere,
+            // which the rewritten initializer no longer matches.
+            if (!reference.isReadOnly()) {
                 return false;
-            // Check if any references to this variable are followed by property access and modification
-            return variable.references.some((ref) => {
-                const id = ref.identifier;
-                const parent = id.parent;
-                // Check for patterns like dateVar.setDate(), dateVar.setHours(), etc.
-                return (parent &&
-                    parent.type === utils_1.AST_NODE_TYPES.MemberExpression &&
-                    parent.object === id &&
-                    parent.property.type === utils_1.AST_NODE_TYPES.Identifier &&
-                    (parent.property.name.startsWith('set') ||
-                        parent.property.name === 'toISOString' ||
-                        parent.property.name === 'toLocaleString' ||
-                        parent.property.name === 'toString'));
-            });
+            }
+            const identifier = reference.identifier;
+            const parent = identifier.parent;
+            if (!parent ||
+                parent.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+                parent.object !== identifier ||
+                parent.computed ||
+                parent.property.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return false;
+            }
+            return TIMESTAMP_COMPATIBLE_MEMBERS.has(parent.property.name);
+        }
+        /**
+         * Whether every use of a `new Date()` binding survives the rewrite to
+         * `Timestamp.now()`.
+         *
+         * `Timestamp` shares almost none of `Date`'s surface, so rewriting the
+         * initializer turns each `getX`/`setX`/`toLocaleX` call on the binding into
+         * TS2339 (issue #1528). A denylist of the `Date` members `Timestamp` lacks
+         * can only ever be incomplete, so the question is inverted: the fix is
+         * offered only when the whole use set is provably part of the `Timestamp`
+         * API. Declining on an unrecognized use trades a missed rewrite for never
+         * breaking the build, which is the trade this repo prefers.
+         */
+        function usesOnlyTimestampCompatibleMembers(declarator) {
+            // An exported binding is read by files this rule never sees, so its use
+            // set cannot be enumerated and the rewrite would break importers instead.
+            if (declarator.parent?.parent?.type ===
+                utils_1.AST_NODE_TYPES.ExportNamedDeclaration) {
+                return false;
+            }
+            const [variable] = context.getDeclaredVariables(declarator);
+            if (!variable) {
+                return false;
+            }
+            return variable.references.every(isTimestampCompatibleReference);
         }
         return {
-            ImportDeclaration(node) {
-                // Track Timestamp imports from Firebase
-                if (node.source.value === 'firebase-admin/firestore' ||
-                    node.source.value === 'firebase/firestore') {
-                    node.specifiers.forEach((specifier) => {
-                        if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
-                            specifier.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
-                            specifier.imported.name === 'Timestamp') {
-                            timestampAliases.add(specifier.local.name);
-                        }
-                    });
-                }
+            Program(node) {
+                // Collect static imports before any usage is visited. An import is
+                // hoisted and module-scoped, so it binds `Timestamp` for the whole file
+                // regardless of where it sits; visiting imports in traversal order
+                // would make the guard depend on the import preceding the usage.
+                node.body.forEach((statement) => {
+                    if (statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration) {
+                        staticTimestampAliases(statement).forEach(recordTimestampAlias);
+                    }
+                });
             },
             VariableDeclarator(node) {
                 // Track dynamic imports of Timestamp
-                if (node.init?.type === utils_1.AST_NODE_TYPES.AwaitExpression &&
-                    node.init.argument.type === utils_1.AST_NODE_TYPES.ImportExpression) {
-                    const importSource = node.init.argument.source;
-                    if (importSource.type === utils_1.AST_NODE_TYPES.Literal &&
-                        (importSource.value === 'firebase-admin/firestore' ||
-                            importSource.value === 'firebase/firestore')) {
-                        // Handle destructured imports
-                        if (node.id.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
-                            node.id.properties.forEach((prop) => {
-                                if (prop.type === utils_1.AST_NODE_TYPES.Property &&
-                                    prop.key.type === utils_1.AST_NODE_TYPES.Identifier &&
-                                    prop.key.name === 'Timestamp') {
-                                    if (prop.value.type === utils_1.AST_NODE_TYPES.Identifier) {
-                                        timestampAliases.add(prop.value.name);
-                                    }
-                                }
-                            });
-                        }
-                    }
-                }
+                dynamicTimestampAliases(node).forEach(recordTimestampAlias);
             },
             CallExpression(node) {
                 if (isTimestampFromDateWithNewDate(node)) {
@@ -211,27 +362,31 @@ exports.enforceTimestampNow = (0, createRule_1.createRule)({
                             varName.includes('date') ||
                             varName.includes('created') ||
                             varName.includes('updated')) {
-                            // Check if the Date object is being modified
-                            if (isDateBeingModified(parent.id.name)) {
-                                // If the Date is being modified, don't flag it
+                            // Stay silent when any use of the binding relies on the `Date`
+                            // API, since the rewrite would strip it (issue #1528).
+                            if (!usesOnlyTimestampCompatibleMembers(parent)) {
                                 return;
                             }
-                            // Check if we have a Timestamp import before suggesting
-                            if (timestampAliases.size > 0) {
-                                const timestampName = Array.from(timestampAliases)[0];
-                                const expressionText = sourceCode.getText(node);
-                                context.report({
-                                    node,
-                                    messageId: 'preferTimestampNow',
-                                    data: {
-                                        expression: expressionText,
-                                        timestampAlias: timestampName,
-                                    },
-                                    fix(fixer) {
-                                        return fixer.replaceText(node, `${timestampName}.now()`);
-                                    },
-                                });
+                            // Stay silent unless a real `Timestamp` binding is in scope. The
+                            // rewrite names an identifier the source never mentions, and a
+                            // file with no Firestore import is almost certainly using the
+                            // `Date` for something other than a Firestore document anyway.
+                            const timestampName = findTimestampAliasInScope();
+                            if (!timestampName) {
+                                return;
                             }
+                            const expressionText = sourceCode.getText(node);
+                            context.report({
+                                node,
+                                messageId: 'preferTimestampNow',
+                                data: {
+                                    expression: expressionText,
+                                    timestampAlias: timestampName,
+                                },
+                                fix(fixer) {
+                                    return fixer.replaceText(node, `${timestampName}.now()`);
+                                },
+                            });
                         }
                     }
                 }