@blumintinc/eslint-plugin-blumint 1.16.2 → 1.17.1

package/lib/rules/enforce-snapshot-state-narrowing.js

@@ -0,0 +1,281 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enforceSnapshotStateNarrowing = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_SNAPSHOT_HOOKS = [
+    'useDocSnapshot',
+    'useCollectionSnapshot',
+    'useCachedDocSnapshot',
+    'useFirestore',
+];
+const DEFAULT_GUARD_FUNCTIONS = ['isSnapshotReady'];
+exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
+    name: 'enforce-snapshot-state-narrowing',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Enforce correct narrowing of FirestoreSnapshotState<T> variables. Falsy/truthy checks are semantic bugs because all string states are truthy; raw typeof narrowing to data bypasses the isSnapshotReady abstraction.',
+            recommended: 'error',
+        },
+        hasSuggestions: true,
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    snapshotHooks: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Hook names that return FirestoreSnapshotState<T>',
+                    },
+                    guardFunctions: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Canonical type guard function names',
+                    },
+                    excludeFiles: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'File patterns to exclude from this rule',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            noFalsyCheck: "Do not use boolean coercion on FirestoreSnapshotState<T>. All string states ('idle', 'loading', 'not-found') are truthy, so '{{expression}}' does not behave as intended. Use isSnapshotReady(state) to narrow to T, or compare explicitly (e.g., state === 'loading').",
+            noRawTypeof: "Do not use '{{expression}}' to narrow FirestoreSnapshotState<T> to data. Use isSnapshotReady(state) instead to maintain the abstraction boundary.",
+        },
+    },
+    defaultOptions: [{}],
+    create(context, [options]) {
+        const snapshotHooks = new Set(options?.snapshotHooks ?? DEFAULT_SNAPSHOT_HOOKS);
+        // guardFunctions is accepted in config for documentation and future extensibility
+        // but detection is purely syntactic (by hook source), not by guard function name.
+        void (options?.guardFunctions ?? DEFAULT_GUARD_FUNCTIONS);
+        const excludeFiles = options?.excludeFiles ?? [
+            'src/types/FirestoreSnapshotState.ts',
+        ];
+        // Check if the current file should be excluded
+        const filename = context.getFilename();
+        if (excludeFiles.some((pattern) => filename.endsWith(pattern))) {
+            return {};
+        }
+        // Track variable names that are assigned from snapshot hooks within each scope.
+        // We map variable name -> true (in-scope snapshot vars).
+        const snapshotVars = new Set();
+        /**
+         * Extracts the callee name from a CallExpression.
+         * Handles both simple identifiers (useDocSnapshot) and member expressions
+         * (hooks.useDocSnapshot). Returns undefined if it cannot be determined.
+         */
+        function getCalleeName(node) {
+            const callee = node.callee;
+            if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return callee.name;
+            }
+            if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                callee.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return callee.property.name;
+            }
+            return undefined;
+        }
+        /**
+         * Returns true if the identifier refers to a variable we are tracking as a
+         * snapshot state variable.
+         */
+        function isSnapshotVar(node) {
+            return snapshotVars.has(node.name);
+        }
+        /**
+         * Returns the source text of a node, falling back to a simple stringification.
+         */
+        function getText(node) {
+            try {
+                return context.getSourceCode().getText(node);
+            }
+            catch {
+                return '<expression>';
+            }
+        }
+        /**
+         * Checks a BinaryExpression for raw typeof narrowing patterns that attempt
+         * to narrow the state to data:
+         *   - typeof state === 'object'   (bad)
+         *   - typeof state !== 'string'   (bad - equivalent to isSnapshotReady)
+         *   - typeof state === 'object' && state !== null  (the combined form is
+         *     handled by visiting the BinaryExpression children individually)
+         *
+         * Allowed:
+         *   - typeof state === 'string'   (good - narrows to non-data states)
+         *   - typeof state !== 'object'   (not flagged, unusual but not a to-data check)
+         */
+        function checkTypeofBinaryExpression(node) {
+            const { operator, left, right } = node;
+            // Pattern: typeof <expr> === <literal> or typeof <expr> !== <literal>
+            if (left.type === utils_1.AST_NODE_TYPES.UnaryExpression &&
+                left.operator === 'typeof' &&
+                right.type === utils_1.AST_NODE_TYPES.Literal) {
+                const operand = left.argument;
+                const literal = right.value;
+                if (operand.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    isSnapshotVar(operand)) {
+                    // typeof state === 'object' — bad: narrows to data, use isSnapshotReady
+                    if (operator === '===' && literal === 'object') {
+                        context.report({
+                            node,
+                            messageId: 'noRawTypeof',
+                            data: { expression: getText(node) },
+                            suggest: [
+                                {
+                                    messageId: 'noRawTypeof',
+                                    data: {
+                                        expression: `isSnapshotReady(${operand.name})`,
+                                    },
+                                    fix(fixer) {
+                                        return fixer.replaceText(node, `isSnapshotReady(${operand.name})`);
+                                    },
+                                },
+                            ],
+                        });
+                    }
+                    // typeof state !== 'string' — bad: equivalent to isSnapshotReady
+                    else if (operator === '!==' && literal === 'string') {
+                        context.report({
+                            node,
+                            messageId: 'noRawTypeof',
+                            data: { expression: getText(node) },
+                            suggest: [
+                                {
+                                    messageId: 'noRawTypeof',
+                                    data: {
+                                        expression: `isSnapshotReady(${operand.name})`,
+                                    },
+                                    fix(fixer) {
+                                        return fixer.replaceText(node, `isSnapshotReady(${operand.name})`);
+                                    },
+                                },
+                            ],
+                        });
+                    }
+                    // typeof state === 'string' — allowed (narrows to non-data states)
+                    // typeof state !== 'object' — allowed
+                }
+            }
+        }
+        /**
+         * Reports a falsy/truthy check on a snapshot-state identifier.
+         */
+        function reportFalsyCheck(node, expression, varName) {
+            context.report({
+                node,
+                messageId: 'noFalsyCheck',
+                data: { expression },
+                suggest: [
+                    {
+                        messageId: 'noFalsyCheck',
+                        data: { expression: `isSnapshotReady(${varName})` },
+                        fix(fixer) {
+                            // Replace the entire flagged expression with the canonical guard
+                            return fixer.replaceText(node, `isSnapshotReady(${varName})`);
+                        },
+                    },
+                ],
+            });
+        }
+        return {
+            // Track variable declarations that come from snapshot hooks.
+            // Supports:
+            //   const state = useDocSnapshot<T>(...)         — simple assignment
+            //   const [state, setState] = useCollectionSnapshot<T>(...)   — array destructuring
+            VariableDeclarator(node) {
+                if (!node.init || node.init.type !== utils_1.AST_NODE_TYPES.CallExpression) {
+                    return;
+                }
+                const callee = getCalleeName(node.init);
+                if (!callee || !snapshotHooks.has(callee)) {
+                    return;
+                }
+                // Simple: const state = useDocSnapshot(...)
+                if (node.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    snapshotVars.add(node.id.name);
+                }
+                // Destructuring: const { state } = useDocSnapshot(...) or const [state] = ...
+                // We don't track these deeply to avoid false positives — the variable would
+                // need a different name and it is unusual to destructure a snapshot state hook result.
+            },
+            // UnaryExpression: !state or !!state
+            // For !!state: ESLint visits both the outer (!) and inner (!) nodes.
+            // We report at the outermost level only: skip when this node is the inner
+            // `!` of a `!!` expression (i.e. the parent is also a `!` UnaryExpression).
+            UnaryExpression(node) {
+                if (node.operator !== '!')
+                    return;
+                // Skip the inner `!` of a `!!state` pattern — the outer `!` will report it.
+                const parent = node.parent;
+                if (parent &&
+                    parent.type === utils_1.AST_NODE_TYPES.UnaryExpression &&
+                    parent.operator === '!') {
+                    return;
+                }
+                const argument = node.argument;
+                // !state — the argument is directly the snapshot var
+                if (argument.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    isSnapshotVar(argument)) {
+                    const expression = `!${argument.name}`;
+                    reportFalsyCheck(node, expression, argument.name);
+                }
+                // !!state — the argument is another `!` whose argument is the snapshot var
+                else if (argument.type === utils_1.AST_NODE_TYPES.UnaryExpression &&
+                    argument.operator === '!' &&
+                    argument.argument.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    isSnapshotVar(argument.argument)) {
+                    const varName = argument.argument.name;
+                    reportFalsyCheck(node, `!!${varName}`, varName);
+                }
+            },
+            // IfStatement: if (state) { ... } or if (!state) { ... }
+            // The !state case is covered by UnaryExpression. We handle if (state) here.
+            IfStatement(node) {
+                const test = node.test;
+                if (test.type === utils_1.AST_NODE_TYPES.Identifier && isSnapshotVar(test)) {
+                    reportFalsyCheck(test, test.name, test.name);
+                }
+            },
+            // ConditionalExpression: state ? a : b
+            ConditionalExpression(node) {
+                const test = node.test;
+                if (test.type === utils_1.AST_NODE_TYPES.Identifier && isSnapshotVar(test)) {
+                    reportFalsyCheck(test, test.name, test.name);
+                }
+            },
+            // LogicalExpression: state && expr, state || expr
+            LogicalExpression(node) {
+                const left = node.left;
+                if ((node.operator === '&&' || node.operator === '||') &&
+                    left.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    isSnapshotVar(left)) {
+                    reportFalsyCheck(left, left.name, left.name);
+                }
+            },
+            // BinaryExpression: typeof state === 'object', typeof state !== 'string'
+            BinaryExpression(node) {
+                checkTypeofBinaryExpression(node);
+            },
+            // CallExpression: Boolean(state)
+            CallExpression(node) {
+                const callee = node.callee;
+                // Boolean(state) — explicit coercion
+                if (callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    callee.name === 'Boolean' &&
+                    node.arguments.length === 1 &&
+                    node.arguments[0].type === utils_1.AST_NODE_TYPES.Identifier &&
+                    isSnapshotVar(node.arguments[0])) {
+                    const varName = node.arguments[0].name;
+                    reportFalsyCheck(node, `Boolean(${varName})`, varName);
+                }
+            },
+        };
+    },
+});
+//# sourceMappingURL=enforce-snapshot-state-narrowing.js.map

package/lib/rules/enforce-types-directory-placement.d.ts

@@ -0,0 +1,9 @@
+type Options = [
+    {
+        typesDirectory?: string;
+        excludePatterns?: string[];
+        includePaths?: string[];
+    }
+];
+export declare const enforceTypesDirectoryPlacement: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"typeOnlyFileOutsideTypesDir", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export {};

package/lib/rules/enforce-types-directory-placement.js

@@ -0,0 +1,276 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enforceTypesDirectoryPlacement = void 0;
+const path_1 = __importDefault(require("path"));
+const utils_1 = require("@typescript-eslint/utils");
+const minimatch_1 = require("minimatch");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_TYPES_DIRECTORY = 'functions/src/types';
+const DEFAULT_EXCLUDE_PATTERNS = [
+    '**/*.d.ts',
+    '**/*.test.ts',
+    '**/*.test.tsx',
+    '**/*.spec.ts',
+    '**/*.spec.tsx',
+    '**/__mocks__/**',
+];
+const DEFAULT_INCLUDE_PATHS = ['src/**', 'functions/src/**'];
+/**
+ * Normalizes a filesystem path to use forward slashes so that
+ * Windows paths are handled uniformly alongside POSIX paths.
+ */
+function normalizePath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+/**
+ * Returns true when the normalized path contains the given directory
+ * segment anywhere inside it (as a proper path component, not a substring).
+ * E.g. containsPathSegment('/a/functions/src/types/foo.ts', 'functions/src/types') → true
+ */
+function containsPathSegment(filePath, segment) {
+    const normalized = normalizePath(filePath);
+    const normalizedSegment = normalizePath(segment);
+    return (normalized.includes('/' + normalizedSegment + '/') ||
+        normalized.includes('/' + normalizedSegment) ||
+        normalized.endsWith('/' + normalizedSegment));
+}
+/**
+ * Derives a suggested target path under the types directory.
+ *
+ * Strategy:
+ * - For backend files (path contains `functions/src/<segment>/`): strip `functions/src/<segment>/`
+ *   and prepend `functions/src/types/`.
+ * - For frontend files (path contains `src/<segment>/`): strip `src/<segment>/`
+ *   and prepend `functions/src/types/`.
+ */
+function suggestTargetPath(filePath, typesDirectory) {
+    const normalized = normalizePath(filePath);
+    // Backend pattern: functions/src/<segment>/...
+    const backendMatch = normalized.match(/functions\/src\/([^/]+)\/(.+)/);
+    if (backendMatch) {
+        const [, , rest] = backendMatch;
+        return `${typesDirectory}/${rest}`;
+    }
+    // Frontend pattern: src/<segment>/...
+    const frontendMatch = normalized.match(/(?:^|\/)src\/([^/]+)\/(.+)/);
+    if (frontendMatch) {
+        const [, , rest] = frontendMatch;
+        return `${typesDirectory}/${rest}`;
+    }
+    return null;
+}
+/**
+ * Returns true when the given top-level statement is "type-only":
+ * - ImportDeclaration (imports alone are not runtime code)
+ * - TSTypeAliasDeclaration (bare or exported)
+ * - TSInterfaceDeclaration (bare or exported)
+ * - TSEnumDeclaration (treated as type-level per spec)
+ * - TSModuleDeclaration (declare blocks)
+ * - ExportNamedDeclaration that exports only types/interfaces/enums OR
+ *   is a pure type re-export (`export type { ... } from ...` or
+ *   `export { ... } from ...` with no local declarations carrying runtime code)
+ * - ExportAllDeclaration
+ *
+ * Anything else (FunctionDeclaration, ClassDeclaration, VariableDeclaration,
+ * ExpressionStatement, etc.) is runtime code and returns false.
+ */
+function isTypeOnlyStatement(node) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.ImportDeclaration:
+            // Imports don't count as runtime code for this rule.
+            return true;
+        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.TSModuleDeclaration:
+            return true;
+        case utils_1.AST_NODE_TYPES.ExportNamedDeclaration: {
+            const exportNode = node;
+            // `export type { Foo }` or `export type { Foo } from '...'`
+            if (exportNode.exportKind === 'type') {
+                return true;
+            }
+            // `export { Foo } from '...'` — pure re-export with no local declaration
+            if (exportNode.source !== null && exportNode.declaration === null) {
+                return true;
+            }
+            // `export type Foo = ...` / `export interface Foo { ... }` / `export enum Foo { ... }`
+            if (exportNode.declaration !== null) {
+                const decl = exportNode.declaration;
+                return (decl.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration ||
+                    decl.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration ||
+                    decl.type === utils_1.AST_NODE_TYPES.TSEnumDeclaration ||
+                    decl.type === utils_1.AST_NODE_TYPES.TSModuleDeclaration);
+            }
+            // `export { Foo }` without `from` — re-exporting local bindings.
+            // Since we cannot tell whether the local binding is a type or value
+            // without the type checker, treat this as not type-only to avoid
+            // false positives.
+            return false;
+        }
+        case utils_1.AST_NODE_TYPES.ExportAllDeclaration:
+            // `export * from '...'` or `export type * from '...'`
+            return true;
+        default:
+            // FunctionDeclaration, ClassDeclaration, VariableDeclaration,
+            // ExpressionStatement, etc. all count as runtime code.
+            return false;
+    }
+}
+/**
+ * A file is "type-only" when:
+ * 1. It has at least one top-level type declaration (not just bare imports/re-exports).
+ * 2. Every top-level statement is type-only according to isTypeOnlyStatement.
+ */
+function isTypeOnlyFile(body) {
+    if (body.length === 0) {
+        return false;
+    }
+    let hasActualTypeDeclaration = false;
+    for (const stmt of body) {
+        if (!isTypeOnlyStatement(stmt)) {
+            return false;
+        }
+        // Must have at least one "real" type construct, not just imports/re-exports.
+        if (stmt.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration ||
+            stmt.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration ||
+            stmt.type === utils_1.AST_NODE_TYPES.TSEnumDeclaration ||
+            stmt.type === utils_1.AST_NODE_TYPES.TSModuleDeclaration) {
+            hasActualTypeDeclaration = true;
+        }
+        else if (stmt.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration) {
+            const exportNode = stmt;
+            if (exportNode.declaration !== null) {
+                const decl = exportNode.declaration;
+                if (decl.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration ||
+                    decl.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration ||
+                    decl.type === utils_1.AST_NODE_TYPES.TSEnumDeclaration ||
+                    decl.type === utils_1.AST_NODE_TYPES.TSModuleDeclaration) {
+                    hasActualTypeDeclaration = true;
+                }
+            }
+            else if (
+            // `export type { ... } from '...'` or `export { ... } from '...'`
+            // counts toward type declarations only when using the type export kind
+            exportNode.exportKind === 'type') {
+                hasActualTypeDeclaration = true;
+            }
+        }
+        else if (stmt.type === utils_1.AST_NODE_TYPES.ExportAllDeclaration) {
+            const exportAllNode = stmt;
+            if (exportAllNode.exportKind === 'type') {
+                hasActualTypeDeclaration = true;
+            }
+        }
+    }
+    return hasActualTypeDeclaration;
+}
+exports.enforceTypesDirectoryPlacement = (0, createRule_1.createRule)({
+    name: 'enforce-types-directory-placement',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce that type-only files (containing only type/interface/enum declarations) live under the canonical types directory',
+            recommended: 'error',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    typesDirectory: {
+                        type: 'string',
+                        default: DEFAULT_TYPES_DIRECTORY,
+                    },
+                    excludePatterns: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: DEFAULT_EXCLUDE_PATTERNS,
+                    },
+                    includePaths: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: DEFAULT_INCLUDE_PATHS,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            typeOnlyFileOutsideTypesDir: 'Type-only file detected outside {{typesDirectory}}/.\n\nAll files containing only type definitions must live under {{typesDirectory}}/**.\n{{suggestedPath}}' +
+                'If these types are only used by a single consumer, inline them into the consumer file instead of keeping them in a separate file.\n\nSee .claude/skills/types-placement/SKILL.md for the full types placement guide.',
+        },
+    },
+    defaultOptions: [
+        {
+            typesDirectory: DEFAULT_TYPES_DIRECTORY,
+            excludePatterns: DEFAULT_EXCLUDE_PATTERNS,
+            includePaths: DEFAULT_INCLUDE_PATHS,
+        },
+    ],
+    create(context, [options]) {
+        const typesDirectory = options.typesDirectory ?? DEFAULT_TYPES_DIRECTORY;
+        const excludePatterns = options.excludePatterns ?? DEFAULT_EXCLUDE_PATTERNS;
+        const includePaths = options.includePaths ?? DEFAULT_INCLUDE_PATHS;
+        const filename = context.getFilename();
+        // Skip synthetic filenames used by RuleTester when no filename is provided.
+        if (filename === '<input>' || filename === '<text>') {
+            return {};
+        }
+        const normalizedFilename = normalizePath(filename);
+        // Skip .d.ts files first (fast path before glob matching).
+        if (normalizedFilename.endsWith('.d.ts')) {
+            return {};
+        }
+        // Skip files already inside the canonical types directory.
+        if (containsPathSegment(normalizedFilename, typesDirectory)) {
+            return {};
+        }
+        // Apply exclude patterns.
+        const excludeMatchers = excludePatterns.map((pattern) => new minimatch_1.Minimatch(pattern, { dot: true }));
+        if (excludeMatchers.some((mm) => mm.match(normalizedFilename)) ||
+            excludeMatchers.some((mm) => mm.match(path_1.default.basename(normalizedFilename)))) {
+            return {};
+        }
+        // Apply includePaths: only enforce within the configured paths.
+        if (includePaths.length > 0) {
+            const includeMatchers = includePaths.map((pattern) => new minimatch_1.Minimatch(pattern, { dot: true }));
+            const isIncluded = includeMatchers.some((mm) => mm.match(normalizedFilename) ||
+                // Also match against just the portion of the path from src/ or functions/
+                (() => {
+                    const srcIdx = normalizedFilename.indexOf('/src/');
+                    const funcIdx = normalizedFilename.indexOf('/functions/');
+                    const relStart = srcIdx !== -1 ? srcIdx + 1 : funcIdx !== -1 ? funcIdx + 1 : -1;
+                    if (relStart === -1)
+                        return false;
+                    return mm.match(normalizedFilename.slice(relStart));
+                })());
+            if (!isIncluded) {
+                return {};
+            }
+        }
+        return {
+            Program(programNode) {
+                if (!isTypeOnlyFile(programNode.body)) {
+                    return;
+                }
+                const suggested = suggestTargetPath(normalizedFilename, typesDirectory);
+                const suggestedPath = suggested
+                    ? `This file should be moved to: ${suggested}\n\n`
+                    : '';
+                const reportNode = programNode.body.length > 0 ? programNode.body[0] : programNode;
+                context.report({
+                    node: reportNode,
+                    messageId: 'typeOnlyFileOutsideTypesDir',
+                    data: {
+                        typesDirectory,
+                        suggestedPath,
+                    },
+                });
+            },
+        };
+    },
+});
+//# sourceMappingURL=enforce-types-directory-placement.js.map

package/lib/rules/no-direct-function-state.d.ts

@@ -0,0 +1,8 @@
+import { TSESLint } from '@typescript-eslint/utils';
+type Options = [
+    {
+        functionPatterns?: string[];
+    }
+];
+export declare const noDirectFunctionState: TSESLint.RuleModule<"noDirectFunctionState", Options, TSESLint.RuleListener>;
+export {};