🧹 Sweepy

Detect and eliminate unused code and leftover files in your JavaScript, TypeScript, and all your projects — including variables, modules, stylesheets, CSS selectors, config files, JSON data, HTML templates, .env keys, exports, aliases, dependencies, and media assets.

Sweepy is an all-in-one, AST-powered CLI tool for eliminating unused code. It helps you find:

• Unused JavaScript, TypeScript, CSS, and SCSS files
• Unused or unreferenced .html and .json files
• Declared but unused variables in source code
• Unused class, keyframes, and ID selectors in stylesheets
• Unused .env variables
• Unused or duplicate config files (e.g. .babelrc, tsconfig.*.json)
• Dead or misconfigured alias paths
• Orphaned image/media assets (PNG, JPG, SVG, WebP)
• Unreferenced exports and JSX components
• Dynamically loaded files and runtime imports
• Unused or undeclared npm dependencies
• Interactive safe deletion with file-type grouping and dry-run mode
• Exportable JSON, HTML, and plain-text reports

Sweepy is built for developers, teams, CI pipelines, and open-source maintainers who want to keep projects clean and efficient.

---

📦 Installation

Global

1npm install -g sweepy

Local (dev dependency)

1npm install --save-dev sweepy

If installed locally:

1npx sweepy [options]

Sweepy runs instantly with zero config — just install and run. To customize behavior:

1sweepy --init

Adds a "sweepy" block to package.json with defaults like:

• Ignore patterns for node_modules, build/test output
• Alias resolution
• Custom CSS safelist

---

🌟 Like Sweepy?

• ⭐ Star on GitHub
• 🧠 Share with your team
• 🐛 Open issues or PRs

Clean code starts with clean files. Keep it Sweepy! 🧹

---

✨ Features

• 🔍 Detect unused .js, .ts, .jsx, .tsx, .css, .scss, .html, .json, and media assets (PNG, JPG, SVG, WebP)
• ⚙️ Detect unused or duplicate config files (--detect config) such as .babelrc, .prettierrc, .editorconfig, and tsconfig.*.json
• 🔒 Detect unused .env keys in any environment
• 🕳️ Detect unused variables in JS/TS/TSX files (--detect vars)
• 🧭 Detect dead or misconfigured aliases from tsconfig, webpack, vite, and babel (--detect alias)
• 📦 Detect unused and undeclared npm dependencies (--detect deps)
• 📦 Export symbol usage tracking (export const, export default)
• 🎯 JSX component reference detection (<MyComponent />)
• 🎨 Unused CSS selector detection (class, ID, keyframes, tag-based selectors)
• 🗺️ Alias resolution across Webpack, Vite, Babel, tsconfig, and custom
• 🧠 AST-based analysis supporting static + dynamic imports (import(), require())
• 🔁 Git integration with --since <commit> for incremental analysis
• 🧼 Auto-clean with --delete --confirm, or use --interactive for grouped selection
• 💡 Interactive deletion UI grouped by file type, supports safe quit (q)
• ♻️ Files go to .sweepy-trash/ and are fully recoverable
• 📤 Export results as JSON, TXT, or styled HTML reports
• 🖌️ CSS safelist support via customCssSafelist in config
• ⚙️ CI-friendly dry-run support with JSON output

---

🧭 What Makes Sweepy Different?

Sweepy doesn’t just check imports—it analyzes ASTs, handles dynamic patterns, integrates with git, and gives you export-level insight with recovery safety. Unlike other tools, it covers your entire project: code, styles, variables, envs, and assets.

---

🔍 Why Sweepy?

Feature	🧹 Sweepy	depcheck	unimported	PurgeCSS	ts-prune	eslint-plugin-unused-imports
AST-based import/export analysis	✅	❌	❌	❌	✅	❌
JSX <Component /> detection	✅	❌	❌	❌	❌	❌
Export symbol usage analysis	✅	❌	❌	❌	✅	✅ (imports only)
Git-aware scanning (--since)	✅	❌	❌	❌	❌	❌
Unused HTML + JSON file detection	✅	❌	❌	❌	❌	❌
Unused CSS/SCSS selectors	✅	❌	❌	✅ (regex)	❌	❌
.env key usage detection	✅	❌	❌	❌	❌	❌
Unused variable detection (--detect vars)	✅	❌	❌	❌	❌	✅
Unused or duplicate config file detection	✅	❌	❌	❌	❌	❌
Dead/misconfigured alias detection	✅	❌	❌	❌	❌	❌
HTML + JSON report output	✅	❌	❌	❌	❌	❌
Safe deletion with recovery	✅	❌	❌	❌	❌	❌
Interactive file deletion UI with type grouping	✅	❌	❌	❌	❌	❌
Alias resolution (TS/Webpack/Vite/Babel)	✅	✅	✅	❌	⚠️ manual	✅
CI-friendly dry-run mode	✅	✅	❌	❌	❌	✅
Dynamic import / require() tracking	✅	❌	✅	❌	❌	❌
Glob export support (export *)	✅	❌	❌	❌	✅	❌
.scss and CSS Modules support	✅	❌	❌	❌	❌	❌
classnames, clsx handling	✅	❌	❌	❌	❌	❌
CLI + package.json config support	✅	❌	✅	❌	❌	❌
Unused + undeclared dependencies detection	✅	✅	✅	❌	❌	❌
CSS selector safelist support	✅	❌	❌	❌	❌	❌

---

🚀 Usage Examples

1sweepy                            # Full scan
2sweepy --only js css              # Scan JS and CSS only
3sweepy --delete --interactive     # Interactive file deletion
4sweepy --export report.txt        # Export results to text file
5sweepy --html-report              # Generate HTML report
6sweepy --detect env exports       # Detect only env and exports

---

🛠 CLI Options

Option	Description
--only	Filter scan to js, css, assets
--detect	Choose detection types: html, js, css, json, assets, exports, deps, env, alias, vars, config
--delete	Delete unused files
--confirm	Delete without confirmation
--interactive	Select files to delete or recover
--dry-run	Simulate deletion (safe preview)
--export <file>	Export results to .txt or .json
--html-report	Generate styled HTML report
--recover [file]	Recover a specific file
--recover-all	Recover everything from trash
--since <commit>	Limit scan to files changed since commit
--init	Add default config to package.json
--print-config	Display merged configuration
--prune-trash	Permanently delete .sweepy-trash/ contents
--ignore <patterns>	Glob patterns to ignore (override config)

---

🧠 Export Symbol Detection

1export const unused = () => {}
2export default UnusedComponent

Sweepy will flag both if unused.

JSX detection:

1<MyComponent />  // matched to MyComponent.jsx or similar

---

🧩 Config Support

Sweepy config merges from:

1. CLI flags
2. package.json > sweepy
3. .sweepyrc.json (optional)

1"sweepy": {
2  "ignore": ["dist/**", "*.test.*"],
3  "types": ["js", "css", "assets", "deps"],
4  "customAliases": {
5    "@components": "src/components",
6    "@utils": "src/utils"
7  },
8  "customCssSafelist": [
9    "^\\.active$",
10    "^\\.dark-mode$",
11    "^\\.btn-.*"
12  ]
13}

---

♻️ Safe Deletion & Recovery

1sweepy --recover file.js  #Recover one file
2sweepy --recover-all      #Recover everything
3sweepy --prune-trash      #Delete trash permanently

---

📊 HTML Report

1sweepy --html-report

Generates a rich, visual report at sweepy-report.html.

---

🧪 Suggested CI Usage

1sweepy --since HEAD~5 --only js css --dry-run --json

---

⚙️ GitHub Actions

1name: Sweepy CI
2
3on:
4  push:
5    branches: [main]
6  pull_request:
7    branches: [main]
8
9jobs:
10  sweepy:
11    runs-on: ubuntu-latest
12    steps:
13      - uses: actions/checkout@v4
14      - uses: actions/setup-node@v4
15        with:
16          node-version: 20
17      - run: npm install
18      - run: npx sweepy --since HEAD~10 --json --dry-run

---

🌍 Links

• 🔗 GitHub Repo
• 📦 NPM Package
• 📄 License (MIT)

---

📈 Changelog

Check out the CHANGELOG.md for version history and release notes.

---

✅ Tests

Sweepy is tested using Vitest to ensure accurate detection and safe cleanup of unused files, selectors, and dependencies.

1npm test           # Run all tests once
2npm run test:watch # (optional) Watch mode for local development

Test coverage is automatically reported through GitHub Actions and Codecov.

---

🤝 Contributing

We’d love your help! Whether it’s a tiny typo, a brand‑new feature, or a nasty bug you’ve spotted, every bit counts :D

1. Fork this repo and create a branch off main
2. Run npm install then npm test to make sure everything passes
3. Open a pull request with a clear, friendly description of your change

Sweepy follows conventional commits and a clean‑code style.
Let's make the code world a little cleaner, together! 🧹✨

Contributors ✨

Thanks goes to these wonderful people (emoji key):

anthonyhalim150 💻

Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!