purgecode

A safe, smart, and interactive code-cleaning utility for JavaScript/TypeScript projects.

purgecode helps you maintain a clean and healthy codebase by automatically detecting and removing unused code, files, and dependencies. It's built with safety in mind, offering interactive modes, dry runs, and git awareness to prevent accidental data loss.

Why purgecode?

• ⚡ Fast Analysis: Scans your entire project in seconds using ts-morph and glob.
• 🔒 Safety First: Defaults to dry-run mode. Never deletes anything without your explicit permission.
• 🛡️ Git Aware: Automatically skips files that are modified or staged in git to prevent conflicts.
• 🧠 Smart Detection: Identifies unused imports, variables, functions, classes, files, and even package.json dependencies.
• 🎮 Interactive Mode: A user-friendly CLI interface lets you review and select exactly what to prune.
• ⚙️ Highly Configurable: Customize behavior via purgecode.config.json.

Installation

You can run purgecode directly using npx (recommended) or install it globally.

# Run with npx (no installation required)
npx purgecode --help

# Install globally
npm install -g purgecode

Quick Start

1. Initialize Configuration (Optional but recommended) Create a purgecode.config.json file with default settings.

   npx purgecode init

2. Run a Dry Run Analyze your project and see what would be removed. This is the default behavior.

   npx purgecode prune

3. Interactive Mode The safest way to clean your code. Review each item before deletion.

   npx purgecode prune --interactive

4. Apply Changes Once you are confident, run with --no-dry-run to actually delete files and code.

   npx purgecode prune --no-dry-run

Commands

init

Initializes a new purgecode.config.json file in the current directory.

npx purgecode init

prune

The main command to analyze and clean your codebase.

Options:

• -i, --interactive: Run in interactive mode (recommended).
• --preview: Run in preview mode (no changes).
• --no-dry-run: Execute the changes (delete files/code).
• --unused-imports: Remove unused imports.
• --unused-variables: Remove unused variables.
• --unused-declarations: Remove unused functions, classes, interfaces, enums.
• --unused-files: Remove unused files.
• --unused-dependencies: Check for unused dependencies in package.json.
• --remove-unused-dependencies: Remove unused dependencies from package.json.
• --remove-console: Remove console.log and other console calls.
• --remove-comments: Remove comments (except those marked with codeprune-ignore).
• --remove-empty: Remove empty files and directories.
• --format: Format modified files with Prettier.
• --restore: Restore from a backup.
• --no-backup: Disable automatic backup before pruning.
• --git-aware: Skip files with uncommitted changes (default: true in config).
• --diff: Show diff of changes in preview mode.
• --output <file>: Save the report to a file.
• --report-format <format>: Format of the report (json, html, markdown).

list

List unused files without deleting them. Useful for quick checks.

npx purgecode list
npx purgecode list --json

watch

Watch for file changes and re-run analysis automatically.

npx purgecode watch

validate

Validate your purgecode.config.json configuration file.

npx purgecode validate

Configuration

You can configure purgecode by creating a purgecode.config.json file in your project root.

{
  "include": ["src/**/*.{ts,tsx,js,jsx}"],
  "exclude": [
    "node_modules/**",
    "dist/**",
    "build/**",
    "**/*.d.ts",
    "**/*.test.ts",
    "**/*.spec.ts"
  ],
  "fileExtensions": ["ts", "tsx", "js", "jsx"],
  "entryPoints": ["src/index.ts", "src/main.tsx"],
  "dryRun": true,
  "git": {
    "respectGitignore": true,
    "skipTrackedFiles": true
  },
  "features": {
    "unusedFiles": true,
    "unusedImports": true,
    "unusedVariables": true,
    "unusedDependencies": false,
    "console": false,
    "comments": false
  }
}

Configuration Options

| Option | Type | Description | | :--- | :--- | :--- | | include | string[] | Glob patterns for files to include in the analysis. | | exclude | string[] | Glob patterns for files to exclude. | | entryPoints | string[] | Entry points of your application (used to determine unused files). | | dryRun | boolean | If true, no changes will be written to disk. | | git.respectGitignore | boolean | If true, ignores files listed in .gitignore. | | git.skipTrackedFiles | boolean | If true, skips files that have uncommitted changes. | | features | object | Toggle specific pruning features on/off by default. |

Pruning Capabilities

Unused Code

Removes unused:

• Imports: Cleans up import statements.
• Variables: Removes variables that are declared but never used.
• Declarations: Removes functions, classes, interfaces, types, and enums that are not exported and not used within the file.

Unused Files

Detects files that are not imported by any other file in your project, starting from the entryPoints defined in your config.

Unused Dependencies

Analyzes your package.json and source code to find dependencies that are listed but never imported.

Code Cleanup

• Console Removal: Removes console.log, console.error, etc.
• Comment Removal: Removes comments to clean up code density.
• Empty Files: Deletes files and directories that are empty.

Safety & Backups

Git Awareness

By default, purgecode checks your git status. If a file has uncommitted changes, it will be skipped to prevent potential merge conflicts or data loss.

Automatic Backups

Before applying any destructive changes (when --no-dry-run is used), purgecode creates a backup of the modified files. You can restore these backups using the --restore flag.

Ignoring Code

To prevent specific lines or blocks from being processed, you can use the codeprune-ignore comment.

// codeprune-ignore
const importantButUnused = "don't delete me";

License

ISC