@blumintinc/eslint-plugin-blumint 1.16.2 → 1.17.0

package/lib/rules/require-server-timestamp-for-firestore-dates.js

@@ -0,0 +1,313 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireServerTimestampForFirestoreDates = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const minimatch_1 = require("minimatch");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_FIRESTORE_TYPE_PATHS = ['functions/src/types/firestore/**'];
+const DEFAULT_TARGET_PATHS = ['src/**'];
+const TEST_FILE_PATTERNS = [
+    /\.test\.[jt]sx?$/,
+    /\.spec\.[jt]sx?$/,
+    /__tests__\//,
+    /__mocks__\//,
+];
+function isTestFile(filename) {
+    return TEST_FILE_PATTERNS.some((pattern) => pattern.test(filename));
+}
+function matchesAnyGlob(value, globs) {
+    return globs.some((glob) => {
+        const mm = new minimatch_1.Minimatch(glob, { matchBase: false });
+        return mm.match(value);
+    });
+}
+/**
+ * Checks whether the import source matches any of the configured Firestore
+ * type path globs. Handles both absolute paths like
+ * `functions/src/types/firestore/TokenMetadata` and relative paths like
+ * `../../functions/src/types/firestore/TokenMetadata` by normalising the
+ * path before testing.
+ */
+function isFirestoreTypePath(source, firestoreTypePaths) {
+    // Strip leading relative segments so relative paths are tested the same way
+    // as bare module specifiers.
+    const normalized = source.replace(/^(\.\.\/|\.\/)+/, '');
+    return matchesAnyGlob(normalized, firestoreTypePaths);
+}
+/**
+ * Extracts the base type name (without generic parameters) from a
+ * TSTypeReference node. For `TokenMetadata<'offchain', Date>` this returns
+ * `TokenMetadata`.
+ */
+function getBaseTypeName(node) {
+    if (node.typeName.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return node.typeName.name;
+    }
+    // Handle qualified names like `NS.TypeName`
+    if (node.typeName.type === utils_1.AST_NODE_TYPES.TSQualifiedName) {
+        return node.typeName.right.name;
+    }
+    return null;
+}
+/**
+ * Recursively collects all TSTypeReference base names from a type node,
+ * including type parameters. This lets us detect Firestore types nested
+ * inside utility types like `Partial<TokenMetadata<...>>`.
+ */
+function collectTypeReferenceNames(typeNode) {
+    if (!typeNode)
+        return [];
+    const names = [];
+    if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
+        const base = getBaseTypeName(typeNode);
+        if (base)
+            names.push(base);
+        if (typeNode.typeParameters) {
+            for (const param of typeNode.typeParameters.params) {
+                names.push(...collectTypeReferenceNames(param));
+            }
+        }
+    }
+    else if (typeNode.type === utils_1.AST_NODE_TYPES.TSArrayType) {
+        names.push(...collectTypeReferenceNames(typeNode.elementType));
+    }
+    else if (typeNode.type === utils_1.AST_NODE_TYPES.TSUnionType ||
+        typeNode.type === utils_1.AST_NODE_TYPES.TSIntersectionType) {
+        for (const t of typeNode.types) {
+            names.push(...collectTypeReferenceNames(t));
+        }
+    }
+    else if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeOperator) {
+        names.push(...collectTypeReferenceNames(typeNode.typeAnnotation));
+    }
+    return names;
+}
+/**
+ * Determines whether a type annotation references any of the tracked Firestore
+ * type names. The check is purely syntactic — we look for type names in
+ * TSTypeReference nodes.
+ */
+function typeAnnotationReferencesFirestoreType(typeAnnotation, firestoreTypeNames) {
+    const names = collectTypeReferenceNames(typeAnnotation);
+    return names.some((n) => firestoreTypeNames.has(n));
+}
+/**
+ * Returns the inner expression, unwrapping TSAsExpression / TSSatisfiesExpression
+ * chains, so we can inspect what lies under a cast.
+ */
+function unwrapCast(node) {
+    let current = node;
+    while (current.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+        current.type ===
+            utils_1.AST_NODE_TYPES
+                .TSSatisfiesExpression) {
+        current = current.expression;
+    }
+    return current;
+}
+/**
+ * Checks whether an expression is `new Date(...)` (possibly wrapped in casts).
+ */
+function isNewDate(node) {
+    const unwrapped = unwrapCast(node);
+    if (unwrapped.type !== utils_1.AST_NODE_TYPES.NewExpression)
+        return false;
+    const callee = unwrapped.callee;
+    return callee.type === utils_1.AST_NODE_TYPES.Identifier && callee.name === 'Date';
+}
+/**
+ * Recursively visits all property values in an ObjectExpression (including
+ * nested objects) and reports any `new Date()` calls.
+ */
+function reportNewDatesInObject(obj, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+context) {
+    for (const prop of obj.properties) {
+        if (prop.type !== utils_1.AST_NODE_TYPES.Property)
+            continue;
+        const value = prop.value;
+        if (isNewDate(value)) {
+            context.report({
+                node: value,
+                messageId: 'useServerTimestamp',
+            });
+        }
+        else if (value.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+            reportNewDatesInObject(value, context);
+        }
+        else if (value.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+            value.type ===
+                utils_1.AST_NODE_TYPES
+                    .TSSatisfiesExpression) {
+            // The cast may wrap a new Date() OR an object literal we need to recurse into
+            const inner = unwrapCast(value);
+            if (isNewDate(inner)) {
+                context.report({
+                    node: value,
+                    messageId: 'useServerTimestamp',
+                });
+            }
+            else if (inner.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                reportNewDatesInObject(inner, context);
+            }
+        }
+        else if (value.type === utils_1.AST_NODE_TYPES.ConditionalExpression) {
+            // Ternary: check both branches
+            if (isNewDate(value.consequent)) {
+                context.report({
+                    node: value.consequent,
+                    messageId: 'useServerTimestamp',
+                });
+            }
+            if (isNewDate(value.alternate)) {
+                context.report({
+                    node: value.alternate,
+                    messageId: 'useServerTimestamp',
+                });
+            }
+        }
+    }
+}
+exports.requireServerTimestampForFirestoreDates = (0, createRule_1.createRule)({
+    name: 'require-server-timestamp-for-firestore-dates',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Enforce serverTimestamp() instead of new Date() for Firestore timestamp fields',
+            recommended: 'error',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    firestoreTypePaths: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    targetPaths: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    ignoreTestFiles: {
+                        type: 'boolean',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            useServerTimestamp: 'Use serverTimestamp() instead of new Date() for Firestore timestamp fields — client clocks are unreliable and spoofable.',
+        },
+    },
+    defaultOptions: [{}],
+    create(context, [options]) {
+        const firestoreTypePaths = options.firestoreTypePaths ?? DEFAULT_FIRESTORE_TYPE_PATHS;
+        const targetPaths = options.targetPaths ?? DEFAULT_TARGET_PATHS;
+        const ignoreTestFiles = options.ignoreTestFiles ?? true;
+        const filename = context.getFilename();
+        // Honour ignoreTestFiles option
+        if (ignoreTestFiles && isTestFile(filename)) {
+            return {};
+        }
+        // Only apply rule to target paths (frontend code by default).
+        // Normalise to forward slashes so Windows paths work. Test filenames are
+        // relative (e.g. `src/hooks/useExample.ts`). Real monorepo filenames are
+        // absolute (e.g. `/workspace/src/hooks/useExample.ts`); for those we also
+        // try matching the segment of the path that starts with the first literal
+        // prefix of each glob (only when the filename is an absolute path).
+        const normalizedFilename = filename.replace(/\\/g, '/');
+        const isAbsolutePath = normalizedFilename.startsWith('/');
+        const inTargetPaths = matchesAnyGlob(normalizedFilename, targetPaths) ||
+            (isAbsolutePath &&
+                targetPaths.some((glob) => {
+                    const prefix = glob.replace(/\*.*$/, ''); // e.g. 'src/'
+                    const idx = normalizedFilename.indexOf('/' + prefix);
+                    if (idx === -1)
+                        return false;
+                    const suffix = normalizedFilename.slice(idx + 1); // e.g. 'src/hooks/...'
+                    return matchesAnyGlob(suffix, [glob]);
+                }));
+        if (!inTargetPaths)
+            return {};
+        // Collect Firestore type names from imports in this file
+        const firestoreTypeNames = new Set();
+        return {
+            ImportDeclaration(node) {
+                const source = node.source.value;
+                if (!isFirestoreTypePath(source, firestoreTypePaths))
+                    return;
+                for (const specifier of node.specifiers) {
+                    if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier ||
+                        specifier.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier ||
+                        specifier.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier) {
+                        // Track the local alias name (what this file uses to refer to the type)
+                        firestoreTypeNames.add(specifier.local.name);
+                    }
+                }
+            },
+            VariableDeclarator(node) {
+                if (firestoreTypeNames.size === 0)
+                    return;
+                // Pattern: const x: FirestoreType = { ... }
+                const typeAnnotation = node.id.typeAnnotation?.typeAnnotation;
+                if (typeAnnotation &&
+                    typeAnnotationReferencesFirestoreType(typeAnnotation, firestoreTypeNames) &&
+                    node.init &&
+                    node.init.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                    reportNewDatesInObject(node.init, context);
+                }
+            },
+            // Pattern: { ... } as FirestoreType  or  { ... } satisfies FirestoreType
+            TSAsExpression(node) {
+                if (firestoreTypeNames.size === 0)
+                    return;
+                // Only check when the as-cast target type references a Firestore type
+                const typeAnnotation = node.typeAnnotation;
+                if (!typeAnnotationReferencesFirestoreType(typeAnnotation, firestoreTypeNames))
+                    return;
+                const inner = unwrapCast(node.expression);
+                if (inner.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                    reportNewDatesInObject(inner, context);
+                }
+            },
+            // Arrow functions with concise body: `const f = (): FirestoreType => ({ ... })`
+            // In this form the body is the ObjectExpression directly (no ReturnStatement).
+            ArrowFunctionExpression(node) {
+                if (firestoreTypeNames.size === 0)
+                    return;
+                if (node.body.type !== utils_1.AST_NODE_TYPES.ObjectExpression)
+                    return;
+                const returnType = node.returnType?.typeAnnotation;
+                if (returnType &&
+                    typeAnnotationReferencesFirestoreType(returnType, firestoreTypeNames)) {
+                    reportNewDatesInObject(node.body, context);
+                }
+            },
+            // Return statements in functions with explicit Firestore return type annotation
+            ReturnStatement(node) {
+                if (firestoreTypeNames.size === 0)
+                    return;
+                if (!node.argument)
+                    return;
+                if (node.argument.type !== utils_1.AST_NODE_TYPES.ObjectExpression)
+                    return;
+                // Walk up to find the enclosing function and check its return type
+                let ancestor = node.parent;
+                while (ancestor) {
+                    if (ancestor.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+                        ancestor.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+                        ancestor.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
+                        const returnType = ancestor.returnType?.typeAnnotation;
+                        if (returnType &&
+                            typeAnnotationReferencesFirestoreType(returnType, firestoreTypeNames)) {
+                            reportNewDatesInObject(node.argument, context);
+                        }
+                        break;
+                    }
+                    ancestor = ancestor.parent;
+                }
+            },
+        };
+    },
+});
+//# sourceMappingURL=require-server-timestamp-for-firestore-dates.js.map

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,194 @@
 [
+  {
+    "version": "1.17.0",
+    "date": "2026-07-01T05:16:18.225Z",
+    "rules": [
+      {
+        "name": "enforce-boolean-naming-prefixes",
+        "changeType": "fix",
+        "issues": [
+          1249
+        ],
+        "summary": "require boolean prefix at a name boundary in callExpressionLooksBoolean (closes #1249)"
+      },
+      {
+        "name": "enforce-cloud-function-id-length",
+        "changeType": "feat",
+        "issues": [
+          1222
+        ],
+        "summary": "flag .f.ts paths deriving Firebase IDs over 62 chars (closes #1222)"
+      },
+      {
+        "name": "enforce-is-prefix-validators",
+        "changeType": "feat",
+        "issues": [
+          1193
+        ],
+        "summary": "require is-prefix on exported validators (closes #1193)"
+      },
+      {
+        "name": "enforce-m3-sentence-case",
+        "changeType": "feat",
+        "issues": [
+          1190
+        ],
+        "summary": "warn on Title Case / ALL CAPS user-facing text (closes #1190)"
+      },
+      {
+        "name": "enforce-snapshot-state-narrowing",
+        "changeType": "feat",
+        "issues": [
+          1210
+        ],
+        "summary": "require isSnapshotReady over falsy/typeof checks (closes #1210)"
+      },
+      {
+        "name": "enforce-types-directory-placement",
+        "changeType": "feat",
+        "issues": [
+          1194
+        ],
+        "summary": "flag type-only files outside functions/src/types (closes #1194)"
+      },
+      {
+        "name": "no-direct-function-state",
+        "changeType": "feat",
+        "issues": [
+          1208
+        ],
+        "summary": "flag functions passed directly to useState setters (closes #1208)"
+      },
+      {
+        "name": "no-fill-template-mutation",
+        "changeType": "feat",
+        "issues": [
+          1209
+        ],
+        "summary": "forbid mutating fillTemplate() results (closes #1209)"
+      },
+      {
+        "name": "no-portal-inside-tooltip",
+        "changeType": "feat",
+        "issues": [
+          1223
+        ],
+        "summary": "flag portals nested in tooltip wrappers (closes #1223)"
+      },
+      {
+        "name": "no-redundant-boolean-callback-props",
+        "changeType": "feat",
+        "issues": [
+          1192
+        ],
+        "summary": "flag boolean props redundant with a callback's presence (closes #1192)"
+      },
+      {
+        "name": "no-satisfies-in-frontend-bundle",
+        "changeType": "feat",
+        "issues": [
+          1226
+        ],
+        "summary": "ban satisfies in webpack-bundled files (closes #1226)"
+      },
+      {
+        "name": "no-single-dismiss-dialog-button",
+        "changeType": "feat",
+        "issues": [
+          1221
+        ],
+        "summary": "flag lone dismiss button in dialog buttons array (closes #1221)"
+      },
+      {
+        "name": "no-stablehash-react-nodes",
+        "changeType": "feat",
+        "issues": [
+          1134
+        ],
+        "summary": "flag stableHash() on ReactNodes/KeyedNodes (closes #1134)"
+      },
+      {
+        "name": "parallelize-loop-awaits",
+        "changeType": "feat",
+        "issues": [
+          1184
+        ],
+        "summary": "flag sequential await in loops parallelizable via Promise.all (closes #1184)"
+      },
+      {
+        "name": "prefer-flat-transform-each-keys",
+        "changeType": "feat",
+        "issues": [
+          1212
+        ],
+        "summary": "flag nested objects in propagation transformEach returns (closes #1212)"
+      },
+      {
+        "name": "prefer-getter-over-parameterless-method",
+        "changeType": "fix",
+        "issues": [
+          1248
+        ],
+        "summary": "exempt throwing and builder/factory methods (closes #1248)"
+      },
+      {
+        "name": "prefer-spread-over-reassembly",
+        "changeType": "feat",
+        "issues": [
+          1188
+        ],
+        "summary": "flag destructure-then-reassemble prop forwarding (closes #1188)"
+      },
+      {
+        "name": "prefer-sx-prop-over-system-props",
+        "changeType": "feat",
+        "issues": [
+          1189
+        ],
+        "summary": "migrate deprecated MUI system props into sx (closes #1189)"
+      },
+      {
+        "name": "prefer-use-base62-id",
+        "changeType": "feat",
+        "issues": [
+          1206
+        ],
+        "summary": "prefer useBase62Id() over useState/useRef/useMemo + uuidv4Base62() (closes #1206)"
+      },
+      {
+        "name": "prefer-use-theme",
+        "changeType": "feat",
+        "issues": [
+          1213
+        ],
+        "summary": "flag direct theme-constant imports over useTheme() (closes #1213)"
+      },
+      {
+        "name": "prefer-utility-function-own-file",
+        "changeType": "feat",
+        "issues": [
+          1234
+        ],
+        "summary": "flag sizable co-located utility functions (closes #1234)"
+      },
+      {
+        "name": "require-props-composition",
+        "changeType": "feat",
+        "issues": [
+          1181
+        ],
+        "summary": "flag component Props that don't compose with rendered children (closes #1181)"
+      },
+      {
+        "name": "require-server-timestamp-for-firestore-dates",
+        "changeType": "feat",
+        "issues": [
+          1183
+        ],
+        "summary": "flag new Date() in Firestore-typed objects (closes #1183)"
+      }
+    ]
+  },
   {
     "version": "1.16.2",
     "date": "2026-06-30T22:17:37.457Z",