Codebase Cleanup

Reorganize and clean codebases without breaking functionality.

Workflow

Phase 1: Analysis

Before touching anything, understand the codebase.

1. Map the directory structure

   find . -type f -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" | head -100
   tree -L 3 -I 'node_modules|.git|__pycache__|.next|dist|build|venv|.venv' || find . -maxdepth 3 -type d | grep -v node_modules | grep -v .git
   

2. Identify entry points and config files

   • package.json, pyproject.toml, requirements.txt, Cargo.toml
   • Main entry files (index., main., app., server.)
   • Config files (.config.js, .env, tsconfig.json)

3. Run scripts/analyze_codebase.py to generate dependency report

4. Ask clarifying questions if needed

   • What is the primary tech stack?
   • Are there specific directories to preserve?
   • Any files that look dead but are actually used?

Phase 2: Identify Cleanup Targets

Safe to remove without verification:

• Empty directories
• .DS_Store, Thumbs.db, desktop.ini
• Duplicate package lock files (keep one)
• pycache, .pyc, .pyo files
• node_modules/.cache
• Coverage reports, test artifacts
• Editor configs if inconsistent (.idea, .vscode with personal settings)
• Backup files (*.bak, *.backup, *~, *.swp)
• Log files (*.log)
• Compiled outputs if source exists

Requires dependency check before removal:

• Unused source files (verify no imports)
• Orphan test files (verify not in test config)
• Unused assets/images
• Old migration files (check if applied)
• Commented-out code blocks
• Unused dependencies in package.json/requirements.txt

Never remove without explicit permission:

• Config files (might be environment-specific)
• Database files or migrations
• CI/CD configs
• License files
• README or docs

Phase 3: Reorganization Patterns

Standard directory structures by stack:

JavaScript/TypeScript:

src/
  components/    # UI components
  pages/         # Page components or routes
  hooks/         # Custom hooks
  utils/         # Helper functions
  services/      # API calls, external services
  types/         # TypeScript types
  constants/     # Constants, enums
  assets/        # Static files
tests/
  unit/
  integration/

Python:

src/<package_name>/
  __init__.py
  core/          # Core business logic
  api/           # API routes/endpoints
  models/        # Data models
  services/      # Business services
  utils/         # Utilities
tests/
  unit/
  integration/
  fixtures/

File naming conventions:

• Components: PascalCase (Button.tsx)
• Utilities: camelCase (formatDate.ts)
• Constants: UPPER_SNAKE_CASE or kebab-case file
• Tests: *.test.ts, .spec.ts, or test_.py

Phase 4: Execute Changes

1. Create backup commit before changes

   git add -A && git commit -m "Pre-cleanup snapshot" 2>/dev/null || echo "No git or nothing to commit"
   

2. Remove safe-to-delete files first

   find . -name ".DS_Store" -delete 2>/dev/null
   find . -name "*.pyc" -delete 2>/dev/null
   find . -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null
   find . -type d -empty -delete 2>/dev/null
   

3. Reorganize file structure

   • Move files in batches by category
   • Update imports after each batch
   • Run tests or type checks between batches if available

4. Update import paths

   • Check all files for old import paths
   • Use grep to find remaining references to old paths
   • Verify build still works after import updates

5. Remove dead code

   • Check for unused functions/variables with the analyzer script
   • Remove commented-out code older than current work

Phase 5: Validation

1. Run existing tests if available

   npm test 2>/dev/null || yarn test 2>/dev/null || pytest 2>/dev/null || echo "No test runner found"
   

2. Run type checker if TypeScript

   npx tsc --noEmit 2>/dev/null || echo "TypeScript check skipped"
   

3. Run linter if configured

   npm run lint 2>/dev/null || npx eslint . 2>/dev/null || echo "No linter found"
   

4. Verify the app builds

   npm run build 2>/dev/null || yarn build 2>/dev/null || echo "Build check skipped"
   

5. List manual verification needed for features that lack test coverage

Decision Rules

When to consolidate directories:

• Fewer than 3 files with no clear growth path
• Multiple directories with same purpose (utils, helpers, lib)
• Deeply nested single-file directories

When to split directories:

• More than 15-20 files in one directory
• Mixed concerns in same directory
• Files with different lifecycle

When NOT to reorganize:

• Active feature development in that area
• No test coverage for affected code
• Team conventions exist (ask first)
• Monorepo with workspace dependencies

Common Pitfalls

• Moving files breaks dynamic imports (check for require variables, import())
• Barrel files (index.ts re-exports) can hide dependency issues
• CSS/SCSS imports may use relative paths
• Asset paths in code may be hardcoded
• Environment-specific configs might reference paths