ast-code-cleaner

AST-based code cleanup tools and quality gates designed specifically for React Native / Expo and Web projects.

ast-code-cleaner helps you maintain a pristine codebase by statically analyzing your source code to safely strip away dead code, unused styles, dangling imports, and unreferenced assets. Rather than using brittle regex, it uses Babel's AST to guarantee 100% accurate modifications. It also serves as an automated quality gate for CI/CD pipelines.

📖 Table of Contents

• Installation
• Why ast-code-cleaner?
• Features & Commands
  • 🧹 Code Cleanup (AST Mutators)
  • 🔎 Analysis & Quality Gates (Read-Only)
  • 🛠 Utilities
• Formatting Integration
• Programmatic API

Installation

Install as a dev dependency in your React Native or Expo project:

npm install -D ast-code-cleaner

Why ast-code-cleaner?

React Native codebases tend to accumulate cruft over time:

• StyleSheet.create objects get left behind when UI components are deleted.
• Unused const declarations pollute the top of files.
• Assets (images, fonts) remain in your assets/ folder but aren't imported anywhere, increasing your app bundle size.

ast-code-cleaner understands JSX and TypeScript natively, tracking exactly what is referenced within the Babel AST, ensuring dead code is purged safely without breaking your app.

Features & Commands

💡 Tip: All directory arguments [dir] are optional. If omitted, the CLI will interactively prompt you to type the path (defaulting to the current directory .).

🧹 Code Cleanup (AST Mutators)

These commands safely modify your files by rewriting the AST. After making modifications, they automatically format the resulting code using your project's native formatter.

| Command | Description | |---------|-------------| | audit [dir] | Runs strip-consts, strip-imports, and strip-styles in a single pass. (Pass --assets <dir> to additionally check for unused media). | | strip-consts [dir] | Removes entirely unused top-level const declarations. | | strip-imports [dir] | Removes dangling and unused import specifiers. | | strip-styles [dir] | Removes unused properties from React Native StyleSheet.create blocks. | | strip-css-modules [dir] | Removes unused CSS classes from .module.css files (Web). |

Common Options:

• --no-format: Skip formatting after modifying files.
• --formatter <name>: Explicitly set the formatter (auto, biome, prettier, none).

Example Usage:

# Safely remove all unused styles, imports, and consts in the 'src' directory
npx ast-code-cleaner audit ./src

# Same as above, but also find any unused images in 'assets'
npx ast-code-cleaner audit ./src --assets ./assets

🔎 Analysis & Quality Gates (Read-Only)

These commands only analyze your code. They will exit with a non-zero status code (process.exitCode = 1) if any issues are found, making them perfect for pre-commit hooks and CI pipelines.

| Command | Description | |---------|-------------| | all [dir] | Runs audit and check:all sequentially. | | check:all [dir] | Full Quality Gate: Automatically runs your project's custom format and lint scripts. Then runs tsc --noEmit and scans for unused consts. | | unused-consts [dir] | Scans the AST and reports any const bindings that have zero references without modifying the files. | | clean-assets [dir] [assetsDir] | Scans your source code for asset references (strings or require) and compares them against files in your assetsDir to find unreferenced media. | | scan-tailwind [dir] | Scans for unknown/unused Tailwind classes in JSX className props (Web). | | deps:unused | Powered by knip: Finds unused files, unused exports, and unused npm dependencies. | | deps:circular [dir] | Powered by madge: Detects circular imports in your module graph. |

Example Usage:

# Run the full quality gate on the whole project
npx ast-code-cleaner check:all

# Scan for circular dependencies
npx ast-code-cleaner deps:circular ./src

🛠 Utilities

| Command | Description | |---------|-------------| | changelog | Generates a standard CHANGELOG.md based on your project's git history. | | init | Bootstraps husky and lint-staged for automatic pre-commit linting. |

Formatting Integration

ast-code-cleaner acts intelligently regarding your formatter and linter setup, preventing fights with your formatting rules.

1. When mutating files (e.g. audit, strip-styles): It auto-detects Biome or Prettier by inspecting your node_modules/.bin and global PATH. If detected, it seamlessly pipes the modified files through your formatter so the final output respects your stylistic choices.

2. When running the Quality Gate (check:all): It parses your package.json for custom "format", "lint", or "check" scripts and runs them natively. If they don't exist, it falls back to native Biome or Prettier execution.

Programmatic API

You can import the core AST mutators directly via Node.js for custom scripts:

import { stripImports, stripConsts, stripUnusedStyles } from "ast-code-cleaner";

// Example: Strip unused imports
const result = await stripImports({ 
  dir: "./src", 
  format: "biome",      // 'biome' | 'prettier' | 'none'
  cwd: process.cwd() 
});

console.log(`Removed ${result.totalRemoved} imports in ${result.filesModified} files`);

// The 'result' object returns detailed stats:
// {
//   files: [{ file: "src/App.tsx", removed: ["useEffect", "useState"] }, ...],
//   totalRemoved: 2,
//   filesModified: 1
// }

Requirements

• Node.js >= 20
• Babel @babel/parser, @babel/traverse, @babel/types (These are installed automatically as dependencies, and are native to Expo projects).