@empline/preflight 1.1.11 → 1.1.13

package/dist/checks/testing/e2e-best-practices.js

@@ -0,0 +1,791 @@
+#!/usr/bin/env tsx
+"use strict";
+/**
+ * E2E Best Practices Preflight
+ *
+ * Validates Playwright E2E tests follow best practices:
+ * - Proper test organization with test.describe()
+ * - Use of semantic selectors (getByRole, getByLabel, getByText)
+ * - No hardcoded waits (waitForTimeout)
+ * - Proper API stubbing for mutations
+ * - Test isolation (no shared state)
+ * - Accessibility-first selectors
+ * - Proper error handling
+ * - Mobile viewport testing
+ * - Test tagging for selective runs
+ *
+ * @see https://playwright.dev/docs/best-practices
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tags = exports.description = exports.blocking = exports.category = exports.name = exports.id = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const console_chars_1 = require("../../utils/console-chars");
+const file_cache_1 = require("../../shared/file-cache");
+const universal_progress_reporter_1 = require("../system/universal-progress-reporter");
+// Check metadata
+exports.id = "testing/e2e-best-practices";
+exports.name = "E2e Best Practices";
+exports.category = "testing";
+exports.blocking = true;
+exports.description = "E2E Best Practices Preflight";
+exports.tags = ["testing"];
+const RULES = [
+    // ERRORS - These block the build
+    {
+        name: "no-hardcoded-waits",
+        severity: "error",
+        check: (content, file) => {
+            const issues = [];
+            const lines = content.split("\n");
+            lines.forEach((line, index) => {
+                // Skip lines with ignore comment (check previous line too)
+                const prevLine = index > 0 ? lines[index - 1] : "";
+                if (line.includes("e2e-best-practices-ignore") ||
+                    prevLine.includes("e2e-best-practices-ignore")) {
+                    return;
+                }
+                // Match waitForTimeout with any number > 500ms
+                const match = line.match(/waitForTimeout\s*\(\s*(\d+)\s*\)/);
+                if (match && match[1]) {
+                    const timeout = parseInt(match[1], 10);
+                    if (timeout > 500) {
+                        issues.push({
+                            file,
+                            line: index + 1,
+                            rule: "no-hardcoded-waits",
+                            severity: "error",
+                            message: `Hardcoded wait of ${timeout}ms found. Use proper waits instead.`,
+                            suggestion: "Use waitForSelector, waitForLoadState, or expect().toBeVisible() instead of waitForTimeout",
+                        });
+                    }
+                }
+            });
+            return issues;
+        },
+    },
+    {
+        name: "no-force-click",
+        severity: "error",
+        check: (content, file) => {
+            const issues = [];
+            const lines = content.split("\n");
+            lines.forEach((line, index) => {
+                if (line.includes("force: true") && line.includes("click")) {
+                    issues.push({
+                        file,
+                        line: index + 1,
+                        rule: "no-force-click",
+                        severity: "error",
+                        message: "Using force: true bypasses actionability checks",
+                        suggestion: "Fix the element visibility/interactability issue instead of using force: true",
+                    });
+                }
+            });
+            return issues;
+        },
+    },
+    {
+        name: "no-page-pause",
+        severity: "error",
+        check: (content, file) => {
+            const issues = [];
+            const lines = content.split("\n");
+            lines.forEach((line, index) => {
+                if (line.includes("page.pause()") && !line.trim().startsWith("//")) {
+                    issues.push({
+                        file,
+                        line: index + 1,
+                        rule: "no-page-pause",
+                        severity: "error",
+                        message: "page.pause() should not be committed to tests",
+                        suggestion: "Remove page.pause() - it's only for debugging",
+                    });
+                }
+            });
+            return issues;
+        },
+    },
+    {
+        name: "no-only-tests",
+        severity: "error",
+        check: (content, file) => {
+            const issues = [];
+            const lines = content.split("\n");
+            lines.forEach((line, index) => {
+                if ((line.includes("test.only(") || line.includes(".only(")) &&
+                    !line.trim().startsWith("//")) {
+                    issues.push({
+                        file,
+                        line: index + 1,
+                        rule: "no-only-tests",
+                        severity: "error",
+                        message: "test.only() should not be committed",
+                        suggestion: "Remove .only() to run all tests in CI",
+                    });
+                }
+            });
+            return issues;
+        },
+    },
+    {
+        name: "no-skip-without-reason",
+        severity: "error",
+        check: (content, file) => {
+            const issues = [];
+            const lines = content.split("\n");
+            lines.forEach((line, index) => {
+                // Match test.skip( without a comment on same or previous line
+                if (line.includes("test.skip(") && !line.trim().startsWith("//")) {
+                    const prevLine = index > 0 ? (lines[index - 1] ?? "") : "";
+                    // Allow reasons provided as string literals, even when test.skip(...) spans multiple lines.
+                    // Examples allowed:
+                    //   test.skip(true, "reason")
+                    //   test.skip(condition, "reason")
+                    //   test.skip("reason", () => { ... })
+                    const lookahead = [
+                        lines[index] ?? "",
+                        lines[index + 1] ?? "",
+                        lines[index + 2] ?? "",
+                        lines[index + 3] ?? "",
+                    ].join("\n");
+                    const hasInlineReasonString = /test\.skip\(([\s\S]{0,240})['"`][^'"`]+['"`]/.test(lookahead);
+                    if (!line.includes("//") &&
+                        !line.includes("/*") &&
+                        !prevLine.includes("//") &&
+                        !prevLine.includes("TODO") &&
+                        !prevLine.includes("FIXME")) {
+                        if (hasInlineReasonString) {
+                            return;
+                        }
+                        issues.push({
+                            file,
+                            line: index + 1,
+                            rule: "no-skip-without-reason",
+                            severity: "error",
+                            message: "test.skip() must have a comment explaining why",
+                            suggestion: 'Add a comment: // TODO: Skip reason - or use test.skip("reason", ...)',
+                        });
+                    }
+                }
+            });
+            return issues;
+        },
+    },
+    // WARNINGS - Should be fixed but don't block
+    {
+        name: "prefer-semantic-selectors",
+        severity: "warning",
+        check: (content, file) => {
+            const issues = [];
+            const lines = content.split("\n");
+            // Patterns that indicate non-semantic selectors
+            const badPatterns = [
+                { pattern: /locator\s*\(\s*['"`]\.[\w-]+['"`]\s*\)/, name: "class selector" },
+                { pattern: /locator\s*\(\s*['"`]#[\w-]+['"`]\s*\)/, name: "ID selector" },
+                {
+                    pattern: /locator\s*\(\s*['"`]div\s*>\s*div/,
+                    name: "nested div selector",
+                },
+                {
+                    pattern: /\$\s*\(\s*['"`]\.[\w-]+['"`]\s*\)/,
+                    name: "jQuery-style selector",
+                },
+            ];
+            lines.forEach((line, index) => {
+                // Skip comments
+                if (line.trim().startsWith("//") || line.trim().startsWith("*")) {
+                    return;
+                }
+                for (const { pattern, name } of badPatterns) {
+                    if (pattern.test(line)) {
+                        // Don't flag if it's a fallback after semantic selector
+                        if (line.includes("getByRole") ||
+                            line.includes("getByLabel") ||
+                            line.includes("getByText")) {
+                            continue;
+                        }
+                        issues.push({
+                            file,
+                            line: index + 1,
+                            rule: "prefer-semantic-selectors",
+                            severity: "warning",
+                            message: `Using ${name} instead of semantic selector`,
+                            suggestion: "Use getByRole(), getByLabel(), getByText(), or getByTestId() instead",
+                        });
+                        break; // One warning per line
+                    }
+                }
+            });
+            return issues;
+        },
+    },
+    {
+        name: "require-test-describe",
+        severity: "info",
+        check: (content, file) => {
+            const issues = [];
+            // Check if file has test() calls outside of test.describe()
+            const hasDescribe = content.includes("test.describe(");
+            const hasTopLevelTest = /^test\s*\(/m.test(content);
+            if (hasTopLevelTest && !hasDescribe) {
+                issues.push({
+                    file,
+                    line: 1,
+                    rule: "require-test-describe",
+                    severity: "info",
+                    message: "Tests should be organized in test.describe() blocks",
+                    suggestion: "Wrap related tests in test.describe('Feature Name', () => { ... })",
+                });
+            }
+            return issues;
+        },
+    },
+    {
+        name: "excessive-conditional-checks",
+        severity: "info",
+        check: (content, file) => {
+            const issues = [];
+            const lines = content.split("\n");
+            // Count conditional element checks
+            let conditionalCount = 0;
+            const conditionalLines = [];
+            lines.forEach((line, index) => {
+                // Match patterns like: if (await element.count() > 0)
+                if (line.includes(".count()") && (line.includes("if (") || line.includes("if("))) {
+                    conditionalCount++;
+                    conditionalLines.push(index + 1);
+                }
+                // Match patterns like: if (await element.isVisible())
+                if (line.includes(".isVisible()") &&
+                    (line.includes("if (") || line.includes("if(")) &&
+                    line.includes("await")) {
+                    conditionalCount++;
+                    conditionalLines.push(index + 1);
+                }
+            });
+            // More than 5 conditional checks in a file is a smell
+            if (conditionalCount > 5) {
+                issues.push({
+                    file,
+                    line: conditionalLines[0],
+                    rule: "excessive-conditional-checks",
+                    severity: "info",
+                    message: `${conditionalCount} conditional element checks found. Tests may pass even when elements don't exist.`,
+                    suggestion: "Use expect().toBeVisible() for required elements. Only use conditionals for truly optional features.",
+                });
+            }
+            return issues;
+        },
+    },
+    {
+        name: "missing-api-stub",
+        severity: "info",
+        check: (content, file) => {
+            const issues = [];
+            // Check if test has form submission but no route stubbing
+            const hasFormSubmit = content.includes(".click()") &&
+                (content.includes("submit") ||
+                    content.includes("save") ||
+                    content.includes("create") ||
+                    content.includes("delete"));
+            const hasRouteStub = content.includes("page.route(") || content.includes("route.fulfill(");
+            // Only warn for files that look like they're testing mutations
+            if (hasFormSubmit &&
+                !hasRouteStub &&
+                (file.includes("form") ||
+                    file.includes("create") ||
+                    file.includes("edit") ||
+                    file.includes("registration") ||
+                    file.includes("checkout"))) {
+                issues.push({
+                    file,
+                    line: 1,
+                    rule: "missing-api-stub",
+                    severity: "info",
+                    message: "Test appears to submit forms but has no API route stubbing",
+                    suggestion: "Use page.route() to stub API calls and avoid side effects",
+                });
+            }
+            return issues;
+        },
+    },
+    {
+        name: "swallowed-catch-errors",
+        severity: "warning",
+        check: (content, file) => {
+            const issues = [];
+            const lines = content.split("\n");
+            lines.forEach((line, index) => {
+                // Match patterns like: .catch(() => {}) or .catch(() => false)
+                const hasCatch = /\.catch\s*\(\s*\(\s*\)\s*=>\s*(\{\s*\}|false|null|undefined|true)\s*\)/.test(line) ||
+                    /\.catch\s*\(\s*\(\s*\)\s*=>\s*\{\s*\}\s*\)/.test(line);
+                if (!hasCatch)
+                    return;
+                // Get previous lines for context (handle multi-line patterns)
+                const prevLine = index > 0 ? (lines[index - 1] ?? "") : "";
+                const prevPrevLine = index > 1 ? (lines[index - 2] ?? "") : "";
+                const context = prevPrevLine + " " + prevLine + " " + line;
+                // ALLOWED: .isVisible().catch(() => false) - this is a valid conditional check pattern
+                // ALLOWED: .isEnabled().catch(() => false)
+                // ALLOWED: .isChecked().catch(() => false)
+                // ALLOWED: .isDisabled().catch(() => false)
+                // ALLOWED: .waitFor().catch(() => {}) - this is a valid timeout-safe pattern
+                // ALLOWED: .waitForLoadState().catch(() => {})
+                // ALLOWED: .waitForNavigation().catch(() => {})
+                // ALLOWED: .waitForURL().catch(() => {})
+                // ALLOWED: .waitForResponse().catch(() => {})
+                // ALLOWED: .waitForSelector().catch(() => {})
+                // Also check previous lines for multi-line patterns
+                const conditionalMethods = /\.(isVisible|isEnabled|isChecked|isDisabled|isHidden|isEditable|count)\s*\(/;
+                const waitForMethods = /\.(waitFor|waitForLoadState|waitForNavigation|waitForURL|waitForResponse|waitForSelector)\s*\(/;
+                const isConditionalCheck = conditionalMethods.test(line) ||
+                    conditionalMethods.test(prevLine) ||
+                    conditionalMethods.test(prevPrevLine);
+                const isWaitForPattern = waitForMethods.test(line) ||
+                    waitForMethods.test(prevLine) ||
+                    waitForMethods.test(prevPrevLine);
+                if (isConditionalCheck || isWaitForPattern)
+                    return;
+                // BLOCKED: expect().toBeVisible().catch(() => {}) - assertions should NOT be swallowed
+                const isSwallowedAssertion = /expect\s*\(/.test(context);
+                // BLOCKED: Generic swallowed catches that aren't on isVisible-style checks
+                if (isSwallowedAssertion) {
+                    issues.push({
+                        file,
+                        line: index + 1,
+                        rule: "swallowed-catch-errors",
+                        severity: "warning",
+                        message: "Errors are silently swallowed with .catch(() => {}). Test may pass incorrectly.",
+                        suggestion: "Remove .catch() from assertions. If checking element existence, use .isVisible().catch(() => false) pattern.",
+                    });
+                }
+            });
+            return issues;
+        },
+    },
+    {
+        name: "visibility-only-test",
+        severity: "warning",
+        check: (content, file) => {
+            const issues = [];
+            // Split into individual tests
+            const testBlocks = content.split(/\btest\s*\(/);
+            testBlocks.forEach((block, blockIndex) => {
+                if (blockIndex === 0)
+                    return; // Skip before first test
+                // Extract test name from the block
+                const nameMatch = block.match(/^["'`]([^"'`]+)["'`]/);
+                const testName = nameMatch ? nameMatch[1] : `test #${blockIndex}`;
+                // Get just this test's body (up to the next test or end)
+                const testBody = block.split(/\btest\s*\(/)[0] ?? "";
+                // Count meaningful actions vs visibility-only checks
+                const hasClick = testBody.includes(".click(");
+                const hasFill = testBody.includes(".fill(");
+                const hasSelect = testBody.includes(".selectOption(");
+                const hasCheck = testBody.includes(".check(") || testBody.includes(".uncheck(");
+                const hasPress = testBody.includes(".press(");
+                const hasAction = hasClick || hasFill || hasSelect || hasCheck || hasPress;
+                // Count toBeVisible assertions
+                const visibilityAssertions = (testBody.match(/toBeVisible\s*\(/g) ?? []).length;
+                const totalExpects = (testBody.match(/expect\s*\(/g) ?? []).length;
+                // Skip if test is marked as fixme or skip
+                if (testBody.includes("test.fixme") || testBody.includes("test.skip")) {
+                    return;
+                }
+                // Flag tests that ONLY check visibility without any real interactions
+                if (!hasAction && visibilityAssertions > 0 && visibilityAssertions === totalExpects) {
+                    // Check if test name suggests it's intentionally a "display" test
+                    const isDisplayTest = /\b(display|render|show|visible|appear|load)\b/i.test(testName);
+                    if (!isDisplayTest) {
+                        issues.push({
+                            file,
+                            line: 1,
+                            rule: "visibility-only-test",
+                            severity: "info",
+                            message: `Test "${testName}" only checks visibility without any user interactions (click, fill, etc.)`,
+                            suggestion: "Add meaningful interactions (click buttons, fill forms) or rename test to indicate it's a display/render test.",
+                        });
+                    }
+                }
+            });
+            return issues;
+        },
+    },
+    {
+        name: "conditional-action-guards",
+        severity: "info",
+        check: (content, file) => {
+            const issues = [];
+            const lines = content.split("\n");
+            // Track consecutive conditional guards
+            let guardCount = 0;
+            let firstGuardLine = 0;
+            lines.forEach((line, index) => {
+                // Match patterns like: if (await element.isVisible()) or if (await btn.isVisible() && !(await btn.isDisabled()))
+                const isConditionalAction = /if\s*\(\s*await\s+[^)]+\.(isVisible|isEnabled|isDisabled|count)\s*\(/.test(line) &&
+                    !line.trim().startsWith("//");
+                if (isConditionalAction) {
+                    if (guardCount === 0) {
+                        firstGuardLine = index + 1;
+                    }
+                    guardCount++;
+                }
+            });
+            // More than 2 conditional action guards is a code smell - tests can pass without doing anything
+            if (guardCount > 2) {
+                issues.push({
+                    file,
+                    line: firstGuardLine,
+                    rule: "conditional-action-guards",
+                    severity: "info",
+                    message: `${guardCount} conditional guards found (if await isVisible/isEnabled). Tests may pass without executing core actions.`,
+                    suggestion: "Remove if-guards around expected elements. Use expect().toBeVisible() for required elements. Tests should fail if expected elements don't exist.",
+                });
+            }
+            return issues;
+        },
+    },
+    {
+        name: "fixme-test-accumulation",
+        severity: "info",
+        check: (content, file) => {
+            const issues = [];
+            // Count fixme tests
+            const fixmeCount = (content.match(/\btest\.fixme\s*\(/g) ?? []).length;
+            const totalTests = (content.match(/\btest\s*\(/g) ?? []).length + fixmeCount;
+            // Flag if more than 50% of tests are fixme
+            if (fixmeCount > 0 && totalTests > 0) {
+                const fixmePercentage = (fixmeCount / totalTests) * 100;
+                if (fixmePercentage > 50) {
+                    issues.push({
+                        file,
+                        line: 1,
+                        rule: "fixme-test-accumulation",
+                        severity: "info",
+                        message: `${fixmeCount}/${totalTests} tests (${fixmePercentage.toFixed(0)}%) are marked as fixme`,
+                        suggestion: "Fix or remove stale fixme tests. If tests are permanently broken, delete them and create new tests.",
+                    });
+                }
+                else if (fixmeCount >= 3) {
+                    issues.push({
+                        file,
+                        line: 1,
+                        rule: "fixme-test-accumulation",
+                        severity: "info",
+                        message: `${fixmeCount} tests are marked as fixme`,
+                        suggestion: "Consider fixing or removing stale fixme tests to maintain test health.",
+                    });
+                }
+            }
+            return issues;
+        },
+    },
+    {
+        name: "missing-mobile-test",
+        severity: "info",
+        check: (content, file) => {
+            const issues = [];
+            // Check if file has any viewport changes for mobile
+            const hasMobileViewport = content.includes("375") ||
+                content.includes("mobile") ||
+                content.includes("setViewportSize");
+            // Only check UI-focused test files
+            const isUITest = file.includes("user-flows") ||
+                file.includes("marketplace") ||
+                file.includes("checkout") ||
+                file.includes("content");
+            if (isUITest && !hasMobileViewport) {
+                issues.push({
+                    file,
+                    line: 1,
+                    rule: "missing-mobile-test",
+                    severity: "info",
+                    message: "No mobile viewport tests found",
+                    suggestion: 'Add at least one test with page.setViewportSize({ width: 375, height: 667 }) or test.describe("Mobile", ...)',
+                });
+            }
+            return issues;
+        },
+    },
+    {
+        name: "missing-error-state-test",
+        severity: "info",
+        check: (content, file) => {
+            const issues = [];
+            // Check if file tests error states
+            const hasErrorTest = content.includes("error") ||
+                content.includes("fail") ||
+                content.includes("invalid") ||
+                content.includes("status: 4") ||
+                content.includes("status: 5");
+            // Only check files that likely need error testing
+            const needsErrorTest = file.includes("form") ||
+                file.includes("checkout") ||
+                file.includes("registration") ||
+                file.includes("login") ||
+                file.includes("password");
+            if (needsErrorTest && !hasErrorTest) {
+                issues.push({
+                    file,
+                    line: 1,
+                    rule: "missing-error-state-test",
+                    severity: "info",
+                    message: "No error state tests found",
+                    suggestion: "Add tests for validation errors, API failures, and edge cases",
+                });
+            }
+            return issues;
+        },
+    },
+    // INFO - Best practice suggestions
+    {
+        name: "suggest-test-tags",
+        severity: "info",
+        check: (content, file) => {
+            const issues = [];
+            // Check if file uses test tags
+            const hasTestTags = content.includes("@smoke") ||
+                content.includes("@regression") ||
+                content.includes("@critical") ||
+                content.includes("test.describe.configure") ||
+                content.includes("{ tag:");
+            if (!hasTestTags) {
+                issues.push({
+                    file,
+                    line: 1,
+                    rule: "suggest-test-tags",
+                    severity: "info",
+                    message: "Consider adding test tags for selective test runs",
+                    suggestion: 'Use test("name", { tag: "@smoke" }, async () => {}) or test.describe.configure({ tag: "@regression" })',
+                });
+            }
+            return issues;
+        },
+    },
+    {
+        name: "suggest-parallel-mode",
+        severity: "info",
+        check: (content, file) => {
+            const issues = [];
+            // Check if file configures parallel mode
+            const hasParallelConfig = content.includes("test.describe.configure") && content.includes("parallel");
+            // Count number of tests
+            const testCount = (content.match(/\btest\s*\(/g) || []).length;
+            // Suggest parallel for files with many tests
+            if (testCount > 10 && !hasParallelConfig) {
+                issues.push({
+                    file,
+                    line: 1,
+                    rule: "suggest-parallel-mode",
+                    severity: "info",
+                    message: `File has ${testCount} tests but no parallel configuration`,
+                    suggestion: 'Add test.describe.configure({ mode: "parallel" }) for faster execution',
+                });
+            }
+            return issues;
+        },
+    },
+    {
+        name: "suggest-page-object",
+        severity: "info",
+        check: (content, file) => {
+            const issues = [];
+            // Count repeated locator patterns
+            const locatorPatterns = content.match(/page\.(getBy|locator)\([^)]+\)/g) || [];
+            const uniquePatterns = new Set(locatorPatterns);
+            // If same locator used 3+ times, suggest page object
+            const patternCounts = new Map();
+            locatorPatterns.forEach((p) => {
+                patternCounts.set(p, (patternCounts.get(p) || 0) + 1);
+            });
+            const repeatedPatterns = Array.from(patternCounts.entries()).filter(([, count]) => (count ?? 0) >= 3);
+            if (repeatedPatterns.length >= 3) {
+                issues.push({
+                    file,
+                    line: 1,
+                    rule: "suggest-page-object",
+                    severity: "info",
+                    message: `${repeatedPatterns.length} locators are repeated 3+ times`,
+                    suggestion: "Consider extracting to a Page Object Model for better maintainability",
+                });
+            }
+            return issues;
+        },
+    },
+    {
+        name: "missing-test-documentation",
+        severity: "info",
+        check: (content, file) => {
+            const issues = [];
+            // Check for JSDoc comment at top of file
+            const hasFileDoc = content.trimStart().startsWith("/**") || content.trimStart().startsWith("/*");
+            if (!hasFileDoc) {
+                issues.push({
+                    file,
+                    line: 1,
+                    rule: "missing-test-documentation",
+                    severity: "info",
+                    message: "Test file missing documentation header",
+                    suggestion: "Add a JSDoc comment describing what the test file covers",
+                });
+            }
+            return issues;
+        },
+    },
+];
+// CACHED FILE LISTS - Scan once, use everywhere
+let _cachedE2ESpecFiles = null;
+async function getE2ESpecFiles() {
+    if (!_cachedE2ESpecFiles) {
+        _cachedE2ESpecFiles = await file_cache_1.fileCache.getE2ESpecFiles();
+    }
+    return _cachedE2ESpecFiles;
+}
+async function main() {
+    const reporter = (0, universal_progress_reporter_1.createUniversalProgressReporter)(path.basename(__filename, ".ts"));
+    const args = process.argv.slice(2);
+    const isBlocking = !args.includes("--warn");
+    const isVerbose = args.includes("--verbose");
+    const specificRule = args.find((a) => a.startsWith("--rule="))?.split("=")[1];
+    console.log("\n🎭 E2E BEST PRACTICES PREFLIGHT");
+    console.log((0, console_chars_1.createDivider)(60, "heavy"));
+    // Find all E2E test files
+    const testFiles = await getE2ESpecFiles();
+    console.log(`Found ${testFiles.length} E2E test files\n`);
+    const allIssues = [];
+    for (const file of testFiles) {
+        const content = fs.readFileSync(file, "utf8");
+        const relativePath = path.relative(process.cwd(), file);
+        for (const rule of RULES) {
+            // Skip if specific rule requested and this isn't it
+            if (specificRule && rule.name !== specificRule) {
+                continue;
+            }
+            const issues = rule.check(content, relativePath);
+            allIssues.push(...issues);
+        }
+    }
+    // Group by severity
+    const errors = allIssues.filter((i) => i.severity === "error");
+    const warnings = allIssues.filter((i) => i.severity === "warning");
+    const infos = allIssues.filter((i) => i.severity === "info");
+    // Print results
+    if (errors.length > 0) {
+        console.log(`${console_chars_1.emoji.error} ERRORS (blocking):\n`);
+        errors.forEach((i) => {
+            console.log(`  ${i.file}:${i.line}`);
+            console.log(`    Rule: ${i.rule}`);
+            console.log(`    ${i.message}`);
+            if (i.suggestion) {
+                console.log(`    ${console_chars_1.emoji.hint} ${i.suggestion}`);
+            }
+            console.log();
+        });
+    }
+    if (warnings.length > 0) {
+        console.log(`${console_chars_1.emoji.warning}  WARNINGS:\n`);
+        if (isVerbose) {
+            warnings.forEach((i) => {
+                console.log(`  ${i.file}:${i.line}`);
+                console.log(`    Rule: ${i.rule}`);
+                console.log(`    ${i.message}`);
+                if (i.suggestion) {
+                    console.log(`    ${console_chars_1.emoji.hint} ${i.suggestion}`);
+                }
+                console.log();
+            });
+        }
+        else {
+            // Group by rule
+            const byRule = new Map();
+            warnings.forEach((i) => {
+                const list = byRule.get(i.rule) || [];
+                list.push(i);
+                byRule.set(i.rule, list);
+            });
+            byRule.forEach((issues, rule) => {
+                console.log(`  ${rule}: ${issues.length} issues`);
+                // Show first 3 examples
+                issues.slice(0, 3).forEach((i) => {
+                    console.log(`    - ${i.file}:${i.line}`);
+                });
+                if (issues.length > 3) {
+                    console.log(`    ... and ${issues.length - 3} more`);
+                }
+            });
+        }
+        console.log();
+    }
+    if (infos.length > 0 && isVerbose) {
+        console.log(`${console_chars_1.emoji.info}  INFO (suggestions):\n`);
+        // Group by rule
+        const byRule = new Map();
+        infos.forEach((i) => {
+            const list = byRule.get(i.rule) || [];
+            list.push(i);
+            byRule.set(i.rule, list);
+        });
+        byRule.forEach((issues, rule) => {
+            console.log(`  ${rule}: ${issues.length} files`);
+        });
+        console.log();
+    }
+    // Summary
+    console.log((0, console_chars_1.createDivider)(60, "heavy"));
+    console.log(`${console_chars_1.emoji.chart} SUMMARY`);
+    console.log(`   Test files scanned: ${testFiles.length}`);
+    console.log(`   Errors: ${errors.length}`);
+    console.log(`   Warnings: ${warnings.length}`);
+    console.log(`   Info: ${infos.length}`);
+    if (errors.length > 0 && isBlocking) {
+        console.log(`\n${console_chars_1.emoji.error} E2E BEST PRACTICES CHECK FAILED`);
+        console.log("   Fix the errors above before committing.\n");
+        process.exit(1);
+    }
+    if (warnings.length > 0) {
+        console.log(`\n${console_chars_1.emoji.warning}  E2E BEST PRACTICES CHECK PASSED WITH WARNINGS`);
+        console.log("   Consider fixing the warnings for better test quality.\n");
+    }
+    else {
+        console.log(`\n${console_chars_1.emoji.success} E2E BEST PRACTICES CHECK PASSED\n`);
+    }
+}
+main().catch((err) => {
+    console.error("Error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=e2e-best-practices.js.map