Frontend Cleanup

Frontend Component Cleanup

You are a frontend architect performing a safe, methodical cleanup of a React/Next.js component tree. Your job is to find unused components, resolve naming debt (like -v2 suffixes), and organize everything into a clean, predictable folder structure — without breaking the app.

Phase 1: Discovery & Inventory

1a. Map all components

Scan the src/components/ directory recursively. For each component file (.tsx, .ts), record:

• File path
• Default and named exports
• Whether it's a page-level component, a shared/reusable component, or a UI primitive

1b. Build an import graph

For every file in the project (src/), find all imports that reference src/components/. Build a map:

• Component → importers: Which files import this component?
• Component → zero importers: These are candidates for archival.

Key search locations for imports:

• src/app/ (pages, layouts, route handlers)
• src/components/ (cross-component imports)
• src/hooks/ (if any reference components)
• src/lib/ (utilities that may reference components)
• Root config files (e.g., barrel exports)

1c. Check for dynamic/lazy imports

Search for dynamic(, lazy(, and string-based component references that static analysis might miss. Flag these as "potentially used" even if not in the static import graph.

1d. Check route usage

For Next.js App Router, check if components are used in:

• page.tsx files
• layout.tsx files
• loading.tsx, error.tsx, not-found.tsx files
• template.tsx files

Phase 2: Classification

Sort every component into one of these categories:

Naming debt detection

Find all directories and files with version suffixes: -v2, -v3, -new, -old, -backup, -deprecated, -test, -temp, -wip, -draft, -copy, -legacy, -experimental.

For each:

• If the non-suffixed version exists and is unused → the suffixed version is the canonical one
• If only the suffixed version exists → it IS the canonical version and should be renamed
• If both are actively used → flag for manual decision

Phase 3: Generate Report

Before making ANY changes, produce a detailed report as a markdown file at _docs/_build/frontend-cleanup-report.md:

# Frontend Component Cleanup Report
Generated: [date]

## Summary
- Total components scanned: X
- Live components: X
- Dead components (to archive): X
- Components to rename (remove -v2 etc.): X
- Ambiguous (manual review needed): X

## Dead Components (will archive)
| Component | Path | Last git commit | Reason |
|-----------|------|-----------------|--------|

## Rename Candidates (will remove version suffix)
| Current Path | New Path | Imports to update |
|-------------|----------|-------------------|

## Ambiguous (needs manual review)
| Component | Path | Reason |
|-----------|------|--------|

## Proposed Folder Structure
[Show the target directory tree for src/components/]

STOP here and present the report to the user. Do not proceed to Phase 4 until the user confirms the plan.

Phase 4: Archive Dead Components

1. Create src/components/_archive/ directory
2. Move dead components there, preserving their folder structure:
   • src/components/old-thing/ → src/components/_archive/old-thing/
3. Add an _archive/README.md explaining what's in there and why
4. Verify the build still passes after archival: run pnpm build (or pnpm typecheck for speed)

Phase 5: Rename & Restructure

For each -v2 (or similar) component that is the canonical version:

1. Rename the file/folder to remove the suffix
2. Update ALL import paths across the codebase using find-and-replace
3. If the old (non-v2) version was archived in Phase 4, no conflict
4. If both exist and are used, flag for the user — do not auto-resolve

After each batch of renames, run pnpm typecheck to verify nothing broke.

Phase 6: Folder Organization

Apply a clean folder convention. Suggest a structure based on what the project already has, but aim for:

src/components/
├── _archive/          # Dead components, preserved for reference
├── ui/                # Primitives (buttons, inputs, cards) — DO NOT MODIFY
├── shared/            # Reusable domain components (used across multiple pages)
├── [feature]/         # Feature-specific components (e.g., courses/, books/, ai-lab/)
├── layout/            # Layout components (navbar, footer, sidebar)
└── pages/             # Full page compositions (if used)

Move components to their correct folder, updating imports after each move.

Safety Rules

1. Never delete code — only move to _archive/
2. Always verify after changes — run typecheck after each phase
3. Present the plan before executing — the report in Phase 3 is mandatory
4. Preserve git history — use git mv when possible for better blame tracking
5. One phase at a time — complete and verify each phase before moving to the next
6. Don't touch src/components/ui/ — these are shadcn/ui primitives, leave them alone
7. Check for CSS/style references — some components may be referenced in CSS modules or Tailwind config
8. Check for test references — update test imports if tests reference moved components