@empline/preflight 1.1.14 → 1.1.15

package/dist/checks/file-hygiene-validation.js

@@ -0,0 +1,934 @@
+#!/usr/bin/env tsx
+"use strict";
+/**
+ * File Hygiene Validation Preflight (BLOCKING)
+ *
+ * Catches file naming anti-patterns that indicate technical debt:
+ * 1. Version suffixes (-v2, -v3, etc.) - indicates unfinished migration
+ * 2. Temporary suffixes (-old, -backup, -new, -legacy, -deprecated)
+ * 3. Problematic route segments (/new/, /old/, /temp/) in app router
+ * 4. Duplicate/shadow files that should be consolidated
+ * 5. Case collisions (UserCard.tsx vs usercard.tsx)
+ * 6. Component/export name mismatches
+ * 7. Directory naming violations
+ *
+ * BLOCKING: Fails build if violations found (unless allowlisted).
+ *
+ * Usage:
+ *   pnpm preflight:file-hygiene              - BLOCKING mode
+ *   pnpm preflight:file-hygiene --warning    - Warning mode
+ *   pnpm preflight:file-hygiene --fix-preview - Show migration suggestions
+ *   pnpm preflight:file-hygiene --add-allowlist <file> - Add to allowlist
+ *   pnpm preflight:file-hygiene --check-duplicates - Check for duplicate filenames
+ *   pnpm preflight:file-hygiene --check-exports - Check component/export name match
+ */
+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;
+exports.run = run;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const console_chars_1 = require("../utils/console-chars");
+const findings_writer_1 = require("../utils/findings-writer");
+const universal_progress_reporter_1 = require("./system/universal-progress-reporter");
+const glob_1 = require("glob");
+// Check metadata
+exports.id = "misc/file-hygiene-validation";
+exports.name = "File Hygiene Validation";
+exports.category = "misc";
+exports.blocking = true;
+exports.description = "File Hygiene Validation Preflight (BLOCKING)";
+exports.tags = ["misc", "validation"];
+// CONFIGURATION
+const CONFIG = {
+    // Directories to scan
+    includeDirs: ["app", "components", "lib", "hooks", "contexts", "types", "scripts", "packages"],
+    // Files/directories to skip
+    excludePatterns: [
+        "**/node_modules/**",
+        "**/.next/**",
+        "**/dist/**",
+        "**/coverage/**",
+        "**/.git/**",
+        "**/test-results/**",
+        "**/backups/**",
+        "**/prisma/migrations/**",
+    ],
+    // Anti-patterns in filenames (version suffixes, temp markers)
+    filenameAntiPatterns: [
+        {
+            pattern: /-v\d+\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "version-suffix",
+            description: "Version suffix in filename (-v2, -v3)",
+            severity: "error",
+            suggestion: "Rename to canonical name and update all imports",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /-old\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "old-suffix",
+            description: "Old suffix indicates deprecated file",
+            severity: "error",
+            suggestion: "Delete if unused, or rename and consolidate",
+            excludePathPatterns: [],
+        },
+        {
+            // Match files ending with -backup.ts but NOT files that are backup tools
+            pattern: /[^e]-backup\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "backup-suffix",
+            description: "Backup suffix indicates temporary file",
+            severity: "error",
+            suggestion: "Delete backup files - use git for version control",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /-new\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "new-suffix",
+            description: "New suffix indicates incomplete migration",
+            severity: "error",
+            suggestion: "Complete migration: rename to canonical name",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /-legacy\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "legacy-suffix",
+            description: "Legacy suffix indicates technical debt",
+            severity: "error",
+            suggestion: "Migrate away from legacy code and delete",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /-deprecated\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "deprecated-suffix",
+            description: "Deprecated suffix indicates dead code",
+            severity: "error",
+            suggestion: "Delete deprecated files",
+            excludePathPatterns: [/preflights?\//, /validation\//],
+        },
+        {
+            pattern: /-temp\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "temp-suffix",
+            description: "Temp suffix indicates temporary file",
+            severity: "error",
+            suggestion: "Delete temporary files",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /\.bak\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "bak-extension",
+            description: "Backup extension indicates temporary file",
+            severity: "error",
+            suggestion: "Delete .bak files - use git for version control",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /copy\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "copy-suffix",
+            description: "Copy suffix indicates duplicate file",
+            severity: "error",
+            suggestion: "Delete copy files - consolidate into single source",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /-wip\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "wip-suffix",
+            description: "WIP suffix indicates incomplete work",
+            severity: "error",
+            suggestion: "Complete the work and rename to canonical name",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /-draft\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "draft-suffix",
+            description: "Draft suffix indicates incomplete work",
+            severity: "error",
+            suggestion: "Finalize and rename to canonical name",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /-final\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "final-suffix",
+            description: "Final suffix indicates version confusion",
+            severity: "error",
+            suggestion: "Rename to canonical name - there should only be one version",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /-updated\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "updated-suffix",
+            description: "Updated suffix indicates version confusion",
+            severity: "error",
+            suggestion: "Rename to canonical name and delete old version",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /-fixed\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "fixed-suffix",
+            description: "Fixed suffix indicates version confusion",
+            severity: "error",
+            suggestion: "Rename to canonical name and delete broken version",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /-original\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "original-suffix",
+            description: "Original suffix indicates version confusion",
+            severity: "error",
+            suggestion: "Delete original if no longer needed, or consolidate",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /-refactored\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "refactored-suffix",
+            description: "Refactored suffix indicates incomplete migration",
+            severity: "error",
+            suggestion: "Complete refactor: rename to canonical name",
+            excludePathPatterns: [],
+        },
+        {
+            pattern: /-test\.(ts|tsx|js|jsx|mjs)$/i,
+            name: "test-suffix-wrong-location",
+            description: "Test file outside tests directory",
+            severity: "warning",
+            suggestion: "Move to tests/ directory or rename to .test.ts",
+            // Only flag if NOT in tests directory and NOT a proper .test.ts file
+            excludePathPatterns: [/tests\//, /\.test\.(ts|tsx|js|jsx)$/, /\.spec\.(ts|tsx|js|jsx)$/],
+        },
+    ],
+    // Files that are legitimately named with patterns that look like anti-patterns
+    // These are tools/utilities, not temporary files
+    legitimateExceptions: new Set([
+        "safe-backup.ts",
+        "restore-backup.ts",
+        "deploy-with-backup.ts",
+        "convert-legacy-backup.ts",
+        "mandatory-backup.ts",
+    ]),
+    // Anti-patterns in directory/route segments
+    // NOTE: /new/ is a valid Next.js pattern for "create new" pages - not flagged
+    // NOTE: /test/ in app/api/ is valid for dev/debug endpoints - not flagged
+    routeSegmentAntiPatterns: [
+        {
+            pattern: /\/old\//,
+            name: "old-route-segment",
+            description: "'/old/' route segment indicates deprecated route",
+            severity: "error",
+            suggestion: "Remove old routes or redirect to new ones",
+            appOnly: false,
+            context: undefined,
+        },
+        {
+            pattern: /\/temp\//,
+            name: "temp-route-segment",
+            description: "'/temp/' route segment indicates temporary code",
+            severity: "error",
+            suggestion: "Remove temporary routes",
+            appOnly: false,
+            context: undefined,
+        },
+        // NOTE: /test/ in app/api/ is valid for dev/debug API endpoints - removed from checks
+    ],
+    // Directory naming rules
+    directoryNamingRules: {
+        // Directories that should be kebab-case
+        kebabCaseDirs: ["lib", "scripts", "types", "tests"],
+        // Directories that should be PascalCase (none by default - components use kebab-case folders)
+        pascalCaseDirs: [],
+        // Directories that can have any casing (Next.js route segments)
+        anyCase: ["app"],
+        // Reserved directory names that are always valid
+        reserved: new Set([
+            "_components",
+            "_hooks",
+            "_utils",
+            "_lib",
+            "__mocks__",
+            "__tests__",
+            "node_modules",
+            ".next",
+            ".git",
+            "public",
+            "prisma",
+        ]),
+    },
+    // Duplicate detection settings
+    duplicateDetection: {
+        // Directories where duplicates are expected (e.g., packages with same structure)
+        allowedDuplicatePaths: [
+            /packages\//,
+            /node_modules\//,
+            /scripts\/archived\//,
+            /scripts\/active\//,
+        ],
+        // Files that are expected to have duplicates across different contexts
+        // This includes: Next.js conventions, common utility names, step components, etc.
+        allowedDuplicateNames: new Set([
+            // Next.js App Router conventions
+            "index.ts",
+            "index.tsx",
+            "types.ts",
+            "constants.ts",
+            "utils.ts",
+            "utils.tsx",
+            "helpers.ts",
+            "page.tsx",
+            "layout.tsx",
+            "loading.tsx",
+            "error.tsx",
+            "route.ts",
+            "not-found.tsx",
+            // Common component patterns (same name in different feature areas)
+            "validation.ts",
+            "hooks.ts",
+            // Wizard/stepper patterns (each integration has its own steps)
+            "ReviewStep.tsx",
+            "ProductTypeStep.tsx",
+            "ProductSelectionStep.tsx",
+            "FieldMappingStep.tsx",
+            "ConfigurationStep.tsx",
+            // Page client components (each route has its own client)
+            "YearPageClient.tsx",
+            "BrandPageClient.tsx",
+            "FeaturedPageClient.tsx",
+            "SettingsClient.tsx",
+            "OrdersClient.tsx",
+            "ListingsPageClient.tsx",
+            // Common UI component names in different contexts
+            "StatCard.tsx",
+            "SearchBar.tsx",
+            "SearchResults.tsx",
+            "FormField.tsx",
+            "FormSection.tsx",
+            "FormBuilder.tsx",
+            "Toast.tsx",
+            "ErrorBoundary.tsx",
+            "PaginationControls.tsx",
+            "BottomPagination.tsx",
+            "BulkActionBar.tsx",
+            "ImageViewerDialog.tsx",
+            "DeleteCardDialog.tsx",
+            "ConfidenceIndicator.tsx",
+            "CardActions.tsx",
+            "TrustBadges.tsx",
+            // Feature-specific components that exist in multiple feature areas
+            "ListingFilters.tsx",
+            "ListingTableRow.tsx",
+            "CategorySelector.tsx",
+            "ImageUploadSection.tsx",
+            "CardDetailsSection.tsx",
+            "PhysicalPropertiesSection.tsx",
+            "CategorizationSection.tsx",
+            "TemplateIndicator.tsx",
+            "OnboardingWizard.tsx",
+            "EnhancedListingCard.tsx",
+            "RecognitionMethodBadge.tsx",
+            "DatabaseSuggestions.tsx",
+            "CompactFilterContainer.tsx",
+            "SmartDropdown.tsx",
+            "EnhancedDataTable.tsx",
+            "FieldMappingTable.tsx",
+            "WooCommerceWizard.tsx",
+            "UnifiedProductCard.tsx",
+            "UnifiedDialog.tsx",
+            "UnifiedHeaderBadge.tsx",
+            "BrandManagement.tsx",
+            "FocusReviewMode.tsx",
+            "PairedCardSlots.tsx",
+            "SuggestionToast.tsx",
+            // Hooks that exist in multiple contexts
+            "useMediaQuery.ts",
+            "useSwipeGesture.ts",
+            "useListingActions.ts",
+            "useDatabaseSuggestions.ts",
+            "useCardRecognition.ts",
+            "useCardEditing.ts",
+            "useWooCommerceConfig.ts",
+            "useProductSelection.ts",
+            "useCSVImport.ts",
+            // Lib files that may have context-specific versions
+            "woocommerce.ts",
+            "vision-service.ts",
+            "seo.ts",
+            "reference-data.ts",
+            "r2-storage.ts",
+            "image-optimization.ts",
+            "image-analytics.ts",
+            "image-processor.ts",
+            "error-handler.ts",
+            "categories.ts",
+            "card-validation.ts",
+            "auth.ts",
+            "csv-field-definitions.ts",
+            // Script files that may exist in different workflow contexts
+            "doctor.mjs",
+            "provision-snapshot.ts",
+            "create-storage-state.ts",
+            "maintenance.ts",
+            "fix-nextrequest-imports.ts",
+            "log-message-casing.mjs",
+            "check-ui-uniformity.ts",
+            // Workflow files (each workflow category has similar structure)
+            "ui-quality.ts",
+            "supercatch.ts",
+            "security.ts",
+            "performance.ts",
+            "images.ts",
+            "development.ts",
+            "critical.ts",
+            "database.ts",
+        ]),
+    },
+    // Allowlist file path (relative to project root)
+    allowlistPath: ".file-hygiene-allowlist.json",
+};
+// VALIDATOR CLASS
+class FileHygieneValidator {
+    violations = [];
+    warnings = [];
+    filesChecked = 0;
+    allowlist;
+    verbose;
+    warningOnly;
+    fixPreview;
+    addToAllowlist;
+    checkDuplicates;
+    checkExports;
+    constructor(options = {}) {
+        this.verbose = options.verbose || false;
+        this.warningOnly = options.warningOnly || false;
+        this.fixPreview = options.fixPreview || false;
+        this.addToAllowlist = options.addToAllowlist || null;
+        this.checkDuplicates = options.checkDuplicates ?? true; // Enable by default
+        this.checkExports = options.checkExports ?? false; // Opt-in (slower)
+        this.allowlist = this.loadAllowlist();
+    }
+    loadAllowlist() {
+        const allowlistPath = path.join(process.cwd(), CONFIG.allowlistPath);
+        if (fs.existsSync(allowlistPath)) {
+            try {
+                return JSON.parse(fs.readFileSync(allowlistPath, "utf-8"));
+            }
+            catch {
+                return { files: [], patterns: [], lastUpdated: new Date().toISOString() };
+            }
+        }
+        return { files: [], patterns: [], lastUpdated: new Date().toISOString() };
+    }
+    saveAllowlist() {
+        const allowlistPath = path.join(process.cwd(), CONFIG.allowlistPath);
+        this.allowlist.lastUpdated = new Date().toISOString();
+        fs.writeFileSync(allowlistPath, JSON.stringify(this.allowlist, null, 2));
+    }
+    isAllowlisted(filePath) {
+        const normalized = filePath.replace(/\\/g, "/");
+        // Check exact file match
+        if (this.allowlist.files.includes(normalized)) {
+            return true;
+        }
+        // Check pattern match
+        for (const pattern of this.allowlist.patterns) {
+            const regex = new RegExp(pattern);
+            if (regex.test(normalized)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    async validate() {
+        console.log("\n" + (0, console_chars_1.createDivider)(80, "double"));
+        console.log("  FILE HYGIENE VALIDATION (BLOCKING)");
+        console.log((0, console_chars_1.createDivider)(80, "double"));
+        // Handle add-to-allowlist mode
+        if (this.addToAllowlist) {
+            return this.handleAddToAllowlist(this.addToAllowlist);
+        }
+        // Collect all files first for cross-file checks
+        const allFiles = [];
+        // Scan all directories
+        for (const dir of CONFIG.includeDirs) {
+            const files = await this.scanDirectory(dir);
+            allFiles.push(...files);
+        }
+        // Run additional checks if enabled
+        if (this.checkDuplicates) {
+            this.checkDuplicateFilenames(allFiles);
+            this.checkCaseCollisions(allFiles);
+        }
+        if (this.checkExports) {
+            await this.checkExportNameMatch(allFiles);
+        }
+        // Always check directory naming
+        this.checkDirectoryNaming(allFiles);
+        // Report results
+        this.printResults();
+        // Write findings for CI
+        if (this.violations.length > 0 || this.warnings.length > 0) {
+            const findings = [
+                ...this.violations.map((v) => ({
+                    message: `${v.file}: ${v.description}`,
+                    severity: "error",
+                    file: v.file,
+                })),
+                ...this.warnings.map((v) => ({
+                    message: `${v.file}: ${v.description}`,
+                    severity: "warning",
+                    file: v.file,
+                })),
+            ];
+            (0, findings_writer_1.writeFindings)(findings);
+        }
+        // Determine exit status
+        const hasErrors = this.violations.filter((v) => v.severity === "error").length > 0;
+        if (this.warningOnly) {
+            return true;
+        }
+        return !hasErrors;
+    }
+    async scanDirectory(dir) {
+        const pattern = `${dir}/**/*.{ts,tsx,js,jsx,mjs}`;
+        const files = await (0, glob_1.glob)(pattern, {
+            ignore: CONFIG.excludePatterns,
+            nodir: true,
+        });
+        for (const file of files) {
+            this.filesChecked++;
+            this.checkFile(file);
+        }
+        return files;
+    }
+    checkFile(filePath) {
+        const normalized = filePath.replace(/\\/g, "/");
+        const filename = path.basename(filePath);
+        // Skip if allowlisted
+        if (this.isAllowlisted(normalized)) {
+            if (this.verbose) {
+                console.log(`  ${console_chars_1.emoji.skip} Skipped (allowlisted): ${normalized}`);
+            }
+            return;
+        }
+        // Skip legitimate exceptions (backup tools, etc.)
+        if (CONFIG.legitimateExceptions.has(filename)) {
+            if (this.verbose) {
+                console.log(`  ${console_chars_1.emoji.skip} Skipped (legitimate tool): ${normalized}`);
+            }
+            return;
+        }
+        // Check filename anti-patterns
+        for (const antiPattern of CONFIG.filenameAntiPatterns) {
+            if (antiPattern.pattern.test(filename)) {
+                // Check if this file path should be excluded for this pattern
+                const shouldExclude = antiPattern.excludePathPatterns.some((excludePattern) => excludePattern.test(normalized));
+                if (shouldExclude) {
+                    if (this.verbose) {
+                        console.log(`  ${console_chars_1.emoji.skip} Skipped (path exclusion): ${normalized}`);
+                    }
+                    continue;
+                }
+                const violation = {
+                    file: normalized,
+                    type: "filename",
+                    patternName: antiPattern.name,
+                    description: antiPattern.description,
+                    severity: antiPattern.severity,
+                    suggestion: antiPattern.suggestion,
+                };
+                if (antiPattern.severity === "error") {
+                    this.violations.push(violation);
+                }
+                else {
+                    this.warnings.push(violation);
+                }
+            }
+        }
+        // Check route segment anti-patterns
+        for (const antiPattern of CONFIG.routeSegmentAntiPatterns) {
+            // Skip non-app patterns if appOnly is set
+            if (antiPattern.appOnly && !normalized.startsWith("app/")) {
+                continue;
+            }
+            if (antiPattern.pattern.test(normalized)) {
+                const violation = {
+                    file: normalized,
+                    type: "route-segment",
+                    patternName: antiPattern.name,
+                    description: antiPattern.description,
+                    severity: antiPattern.severity,
+                    suggestion: antiPattern.suggestion,
+                    context: antiPattern.context,
+                };
+                if (antiPattern.severity === "error") {
+                    this.violations.push(violation);
+                }
+                else {
+                    this.warnings.push(violation);
+                }
+            }
+        }
+    }
+    handleAddToAllowlist(filePath) {
+        const normalized = filePath.replace(/\\/g, "/");
+        if (!this.allowlist.files.includes(normalized)) {
+            this.allowlist.files.push(normalized);
+            this.saveAllowlist();
+            console.log(`${console_chars_1.emoji.success} Added to allowlist: ${normalized}`);
+            console.log(`${console_chars_1.emoji.hint} Allowlist saved to: ${CONFIG.allowlistPath}`);
+        }
+        else {
+            console.log(`${console_chars_1.emoji.info} Already in allowlist: ${normalized}`);
+        }
+        return true;
+    }
+    printResults() {
+        console.log(`\n${console_chars_1.emoji.search} Scanned ${this.filesChecked} files\n`);
+        // Print errors
+        if (this.violations.length > 0) {
+            console.log((0, console_chars_1.createDivider)(60, "heavy"));
+            console.log(`${console_chars_1.emoji.error} ERRORS (${this.violations.length})`);
+            console.log((0, console_chars_1.createDivider)(60, "heavy"));
+            // Group by pattern type
+            const byPattern = new Map();
+            for (const v of this.violations) {
+                const existing = byPattern.get(v.patternName) || [];
+                existing.push(v);
+                byPattern.set(v.patternName, existing);
+            }
+            for (const [patternName, violations] of byPattern) {
+                console.log(`\n${console_chars_1.chars.bullet} ${patternName} (${violations.length} files):`);
+                for (const v of violations) {
+                    console.log(`  ${console_chars_1.chars.cross} ${v.file}`);
+                    if (this.verbose) {
+                        console.log(`    ${console_chars_1.chars.arrow} ${v.description}`);
+                        console.log(`    ${console_chars_1.emoji.hint} ${v.suggestion}`);
+                    }
+                }
+            }
+        }
+        // Print warnings
+        if (this.warnings.length > 0) {
+            console.log(`\n${(0, console_chars_1.createDivider)(60, "light")}`);
+            console.log(`${console_chars_1.emoji.warning} WARNINGS (${this.warnings.length})`);
+            console.log((0, console_chars_1.createDivider)(60, "light"));
+            for (const v of this.warnings) {
+                console.log(`  ${console_chars_1.chars.warning} ${v.file}`);
+                if (this.verbose || v.context) {
+                    console.log(`    ${console_chars_1.chars.arrow} ${v.description}`);
+                    if (v.context) {
+                        console.log(`    ${console_chars_1.chars.info} ${v.context}`);
+                    }
+                    console.log(`    ${console_chars_1.emoji.hint} ${v.suggestion}`);
+                }
+            }
+        }
+        // Print fix preview if requested
+        if (this.fixPreview && this.violations.length > 0) {
+            this.printMigrationSuggestions();
+        }
+        // Summary
+        console.log("\n" + (0, console_chars_1.createDivider)(60, "double"));
+        if (this.violations.length === 0 && this.warnings.length === 0) {
+            console.log(`${console_chars_1.emoji.success} FILE HYGIENE: PASSED`);
+        }
+        else if (this.violations.length === 0) {
+            console.log(`${console_chars_1.emoji.warning} FILE HYGIENE: PASSED WITH WARNINGS`);
+        }
+        else {
+            console.log(`${console_chars_1.emoji.error} FILE HYGIENE: FAILED`);
+            console.log(`\n${console_chars_1.emoji.hint} To allowlist a file (with justification):`);
+            console.log(`   pnpm preflight:file-hygiene --add-allowlist <file>`);
+            console.log(`\n${console_chars_1.emoji.hint} To see migration suggestions:`);
+            console.log(`   pnpm preflight:file-hygiene --fix-preview`);
+        }
+        console.log((0, console_chars_1.createDivider)(60, "double"));
+    }
+    printMigrationSuggestions() {
+        console.log(`\n${(0, console_chars_1.createDivider)(60, "heavy")}`);
+        console.log(`${console_chars_1.emoji.wrench} MIGRATION SUGGESTIONS`);
+        console.log((0, console_chars_1.createDivider)(60, "heavy"));
+        for (const v of this.violations) {
+            if (v.type === "filename" && v.patternName === "version-suffix") {
+                const suggestion = this.generateMigrationSuggestion(v.file);
+                if (suggestion) {
+                    console.log(`\n${console_chars_1.chars.bullet} ${v.file}`);
+                    console.log(`  ${console_chars_1.chars.arrow} Rename to: ${suggestion.to}`);
+                    console.log(`  ${console_chars_1.chars.info} Commands to run:`);
+                    for (const cmd of suggestion.commands) {
+                        console.log(`    $ ${cmd}`);
+                    }
+                    if (suggestion.affectedImports.length > 0) {
+                        console.log(`  ${console_chars_1.chars.warning} Files with imports to update:`);
+                        for (const imp of suggestion.affectedImports.slice(0, 5)) {
+                            console.log(`    - ${imp}`);
+                        }
+                        if (suggestion.affectedImports.length > 5) {
+                            console.log(`    ... and ${suggestion.affectedImports.length - 5} more`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Check for duplicate filenames across different directories
+     * (excluding expected duplicates like index.ts, page.tsx, etc.)
+     */
+    checkDuplicateFilenames(allFiles) {
+        const filenameMap = new Map();
+        for (const file of allFiles) {
+            const normalized = file.replace(/\\/g, "/");
+            const filename = path.basename(file);
+            // Skip allowed duplicates
+            if (CONFIG.duplicateDetection.allowedDuplicateNames.has(filename)) {
+                continue;
+            }
+            // Skip files in allowed duplicate paths
+            if (CONFIG.duplicateDetection.allowedDuplicatePaths.some((p) => p.test(normalized))) {
+                continue;
+            }
+            const existing = filenameMap.get(filename) || [];
+            existing.push(normalized);
+            filenameMap.set(filename, existing);
+        }
+        // Report duplicates
+        for (const [filename, paths] of filenameMap) {
+            if (paths.length > 1) {
+                // Check if they're in the same logical area (both in components, both in lib, etc.)
+                const rootDirs = new Set(paths.map((p) => p.split("/")[0]));
+                // Only flag if duplicates are in different root directories (more likely to be confusing)
+                if (rootDirs.size > 1 || this.verbose) {
+                    this.warnings.push({
+                        file: paths[0],
+                        type: "duplicate",
+                        patternName: "duplicate-filename",
+                        description: `Duplicate filename '${filename}' found in ${paths.length} locations`,
+                        severity: "warning",
+                        suggestion: "Consider renaming to be more specific, or consolidate into shared location",
+                        relatedFiles: paths.slice(1),
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Check for case collisions (files that differ only in casing)
+     * This can cause issues on case-insensitive file systems (Windows, macOS)
+     */
+    checkCaseCollisions(allFiles) {
+        const lowercaseMap = new Map();
+        for (const file of allFiles) {
+            const normalized = file.replace(/\\/g, "/");
+            const lowercase = normalized.toLowerCase();
+            const existing = lowercaseMap.get(lowercase) || [];
+            existing.push(normalized);
+            lowercaseMap.set(lowercase, existing);
+        }
+        // Report case collisions
+        for (const [, paths] of lowercaseMap) {
+            if (paths.length > 1) {
+                // Check if they actually differ in casing (not just duplicates)
+                const uniquePaths = new Set(paths);
+                if (uniquePaths.size > 1) {
+                    this.violations.push({
+                        file: paths[0],
+                        type: "case-collision",
+                        patternName: "case-collision",
+                        description: `Case collision: files differ only in casing`,
+                        severity: "error",
+                        suggestion: "Rename files to have distinct names - case collisions cause issues on Windows/macOS",
+                        relatedFiles: paths.slice(1),
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Check that component files export a component matching their filename
+     * e.g., UserCard.tsx should export UserCard, not ProfileCard
+     */
+    async checkExportNameMatch(allFiles) {
+        const componentFiles = allFiles.filter((f) => {
+            const normalized = f.replace(/\\/g, "/");
+            const filename = path.basename(f);
+            // Only check .tsx files in components/ or app/ that are PascalCase
+            return (/\.(tsx)$/.test(filename) &&
+                /^[A-Z]/.test(filename) &&
+                (normalized.startsWith("components/") || normalized.includes("/_components/")));
+        });
+        for (const file of componentFiles) {
+            const filename = path.basename(file, path.extname(file));
+            // Skip files with valid suffixes
+            if (/\.(stories|test|spec|examples)$/.test(filename)) {
+                continue;
+            }
+            try {
+                const content = fs.readFileSync(file, "utf-8");
+                // Look for default export
+                const defaultExportMatch = content.match(/export\s+default\s+(?:function\s+)?(\w+)|export\s*{\s*(\w+)\s+as\s+default\s*}/);
+                if (defaultExportMatch) {
+                    const exportedName = defaultExportMatch[1] || defaultExportMatch[2];
+                    // Check if exported name matches filename (allowing for minor variations)
+                    if (exportedName && exportedName !== filename) {
+                        // Allow Client suffix mismatch (e.g., UserCard.tsx exports UserCardClient)
+                        if (exportedName === `${filename}Client` || filename === `${exportedName}Client`) {
+                            continue;
+                        }
+                        this.warnings.push({
+                            file: file.replace(/\\/g, "/"),
+                            type: "export-mismatch",
+                            patternName: "export-name-mismatch",
+                            description: `File '${filename}.tsx' exports '${exportedName}' - names should match`,
+                            severity: "warning",
+                            suggestion: `Rename file to '${exportedName}.tsx' or rename export to '${filename}'`,
+                        });
+                    }
+                }
+            }
+            catch {
+                // Skip files that can't be read
+            }
+        }
+    }
+    /**
+     * Check directory naming conventions
+     */
+    checkDirectoryNaming(allFiles) {
+        const checkedDirs = new Set();
+        for (const file of allFiles) {
+            const normalized = file.replace(/\\/g, "/");
+            const parts = normalized.split("/");
+            // Check each directory in the path
+            for (let i = 0; i < parts.length - 1; i++) {
+                const dirName = parts[i];
+                const fullDirPath = parts.slice(0, i + 1).join("/");
+                // Skip if already checked
+                if (checkedDirs.has(fullDirPath))
+                    continue;
+                checkedDirs.add(fullDirPath);
+                // Skip reserved directories
+                if (CONFIG.directoryNamingRules.reserved.has(dirName))
+                    continue;
+                // Skip dynamic route segments [id], [...slug], etc.
+                if (/^\[.*\]$/.test(dirName))
+                    continue;
+                // Skip private folders starting with _
+                if (dirName.startsWith("_"))
+                    continue;
+                // Skip route groups (parentheses)
+                if (/^\(.*\)$/.test(dirName))
+                    continue;
+                // Determine which convention applies
+                const rootDir = parts[0];
+                // Skip app directory (Next.js routes can be any casing)
+                if (rootDir === "app")
+                    continue;
+                // Check for problematic patterns in directory names
+                if (/-v\d+$/.test(dirName)) {
+                    this.violations.push({
+                        file: fullDirPath,
+                        type: "directory",
+                        patternName: "directory-version-suffix",
+                        description: `Directory '${dirName}' has version suffix`,
+                        severity: "error",
+                        suggestion: "Rename directory to remove version suffix",
+                    });
+                }
+                if (/-old$|-new$|-backup$|-temp$/.test(dirName)) {
+                    this.violations.push({
+                        file: fullDirPath,
+                        type: "directory",
+                        patternName: "directory-temp-suffix",
+                        description: `Directory '${dirName}' has temporary suffix`,
+                        severity: "error",
+                        suggestion: "Rename or remove temporary directory",
+                    });
+                }
+                // Check for spaces or special characters
+                if (/\s|[^a-zA-Z0-9_\-\[\]\(\)]/.test(dirName)) {
+                    this.violations.push({
+                        file: fullDirPath,
+                        type: "directory",
+                        patternName: "directory-invalid-chars",
+                        description: `Directory '${dirName}' contains spaces or special characters`,
+                        severity: "error",
+                        suggestion: "Use only alphanumeric characters, hyphens, and underscores",
+                    });
+                }
+            }
+        }
+    }
+    generateMigrationSuggestion(filePath) {
+        const normalized = filePath.replace(/\\/g, "/");
+        const dir = path.dirname(normalized);
+        const filename = path.basename(normalized);
+        // Remove version suffix
+        const newFilename = filename.replace(/-v\d+(\.[^.]+)$/, "$1");
+        const newPath = path.join(dir, newFilename).replace(/\\/g, "/");
+        // Find files that import this
+        const affectedImports = [];
+        // This would require scanning imports - simplified for now
+        return {
+            from: normalized,
+            to: newPath,
+            affectedImports,
+            commands: [
+                `git mv "${normalized}" "${newPath}"`,
+                `# Update imports in affected files`,
+                `pnpm preflight:import-validation --fix`,
+            ],
+        };
+    }
+}
+// MAIN
+async function run() {
+    const reporter = (0, universal_progress_reporter_1.createUniversalProgressReporter)(exports.name);
+    const args = process.argv.slice(2);
+    const options = {
+        verbose: args.includes("--verbose") || args.includes("-v"),
+        warningOnly: args.includes("--warning") || args.includes("-w"),
+        fixPreview: args.includes("--fix-preview") || args.includes("--fix"),
+        addToAllowlist: args.includes("--add-allowlist")
+            ? args[args.indexOf("--add-allowlist") + 1]
+            : undefined,
+        checkDuplicates: !args.includes("--no-duplicates"),
+        checkExports: args.includes("--check-exports"),
+    };
+    const validator = new FileHygieneValidator(options);
+    const passed = await validator.validate();
+    process.exit(passed ? 0 : 1);
+}
+// Allow direct execution
+if (require.main === module) {
+    run().catch(console.error);
+}
+//# sourceMappingURL=file-hygiene-validation.js.map