project-cleaner-mabsr

A lightweight CLI package that helps keep JavaScript/TypeScript projects healthy by finding:

• Unused files
• Unused npm dependencies
• Missing dependencies
• Dead exports (likely unused exported symbols)

Install

Run without installing (recommended for daily checks)

npx project-cleaner-mabsr .

Install globally

npm install -g project-cleaner-mabsr
project-cleaner .

Install locally in a project

npm install --save-dev project-cleaner-mabsr
npx project-cleaner-mabsr .

Usage

project-cleaner [path] [options]

Options

• -p, --path <dir>: project path to scan (default is current directory)
• -r, --report <file>: report output file path relative to target path
• --entry <file>: add custom entry file (can be used multiple times)
• --ignore-file <file>: custom ignore patterns file (default is .project-cleaner-ignore)
• --no-ignore-file: disable ignore file processing
• --json: print report JSON to stdout
• --include-tests: include test files in analysis
• --fail-on-issues: exit with code 1 if issues are detected
• -h, --help: show CLI help

Output

Each run writes a JSON report file (default: project-cleaner-report.json) and prints a text summary.

Report fields include:

• summary
• unusedFiles
• unusedDependencies
• missingDependencies
• deadExports
• metadata (entry files, warnings, parse errors)

Ignore Patterns

Create a .project-cleaner-ignore file in your project root.

Example:

# Ignore generated source
src/generated/**

# Ignore all files in temp scripts folder
scripts/temp/

# Re-include a single file
!scripts/temp/keep.js

Pattern notes:

• * matches within a single path segment
• ** matches across nested folders
• lines starting with # are comments
• prefix with ! to negate a previous rule

Example

project-cleaner . --fail-on-issues

This is useful in CI to fail a build when new cleanup issues appear.

GitHub Action (Pull Requests)

This repository includes a workflow file at .github/workflows/project-cleaner.yml.

It runs on every pull request and:

• installs dependencies
• runs tests
• runs project-cleaner with --fail-on-issues
• uploads project-cleaner-report.json as an artifact

Publish to npm

1. Log in:

npm login

2. Make sure the package name is publishable:

• If using an unscoped name (for example project-cleaner-mabsr), you must own that package on npm.
• If the name is already taken, use a scoped package name such as @your-npm-username/project-cleaner.

3. If you keep an unscoped name that already exists and you own it, bump the version above the latest published version.

4. Publish:

npm publish --access public

Notes

• This tool uses static analysis heuristics, so results may include false positives in highly dynamic codebases.
• Use --entry to improve accuracy when your app uses non-standard entry points.