RefineIt — Automated Codebase Refactoring Engine (Safe by Design)

Clean your repository. Remove dead code. Fix unused imports. Detect risks. Auto-PR your changes — fully automated.

❓ What is RefineIt?

RefineIt is an automated code-refactoring engine designed for modern JavaScript / TypeScript repositories.

It scans your entire repository, understands how files depend on each other, and then:

• Removes dead files (never imported anywhere)
• Cleans unused imports
• Detects circular dependencies
• Flags security-sensitive patterns
• Generates a repo health score
• Creates a backup snapshot before making any changes
• Supports UNDO (you can revert everything)
• And optionally creates automated Pull Requests in CI

RefineIt is the kind of tool you wish existed inside npx, so we built it.

⭐ Why RefineIt Exists

Every repo eventually becomes messy:

• Old files nobody uses
• Helper utilities that were replaced months ago
• TODOs scattered everywhere
• Debugging functions left behind in a rush
• Imports that remained after refactors
• Risky code paths nobody notices

Developers feel this mess, but don’t have time to fix it.

👉 RefineIt fixes the repository for you — safely, automatically, and with full reversibility.

🚀 Installation

npm install -g refineit

or run without installing:

npx refineit

🧠 How RefineIt Works (Real Explanation)

RefineIt doesn’t simply "search files". It performs a full dependency graph analysis.

🔍 1. Deep Repo Scan

RefineIt walks through your entire project, following all imports, exports, and usage references. It builds a dependency graph to understand:

• Which files are actually used
• Which imports are actually referenced
• Which exports nobody touches
• Which files only import things but never get imported
• Which utilities are duplicates
• Where circular references exist

This is why it finds true dead code, not just unused variables.

⚙️ 2. Code Intelligence Engine

RefineIt executes a real static analysis engine:

• Parses TypeScript + JavaScript
• Resolves TSConfig paths
• Resolves absolute imports
• Normalizes mixed slash/backslash paths
• Handles monorepo layouts
• Avoids false positives by using cross-file references

✨ 3. Applies Fixes (Optional)

If you run:

npx refineit --apply

It will:

• Delete dead files
• Remove unused imports
• Clean unused exports
• Fix duplicated references
• Generate a human-readable report

Before doing ANY changes, it:

🛡️ Safety First: The Safety-Lock System

RefineIt refuses to modify your repo if:

• You have uncommitted changes
• Git is not available
• Repository is in a detached HEAD state
• The user didn’t confirm --apply

Example output:

🔒 Safety Lock Engaged — you have uncommitted changes.
Commit or stash before applying fixes.

This is intentional.

👉 Our rule: RefineIt will never modify a repository unless 100% safe.

Demo:

🗃️ Automatic Backup & Undo System

Before RefineIt writes any change, it creates:

.refineit/archives/backup-YYYY-MM-DD-HH-MM-SS

This backup includes:

• Every file before modification
• A manifest.json describing what changed
• The full repo structure snapshot

Undo is simple:

refineit undo <backup-id>

Your entire repo is restored instantly.

Demo:

📊 Repo Health Score (Unique Feature)

After scanning, RefineIt generates a health score based on:

• Dead files
• Unused imports
• Circular deps
• Duplicate utilities
• Large files
• TODO accumulation
• Security patterns

Example screenshot:

🪄 Auto-PR Workflow: Fix Your Repo Automatically in CI

RefineIt ships with a GitHub Action that:

• Scans the repo
• Applies fixes
• Creates a branch
• Pushes changes
• Automatically opens a Pull Request

This means your repo can self-clean every week.

Example PR flow:

📹 assets/demos/auto-pr-demo.mp4

🧪 Example: Before / After RefineIt

Before:

• 9 dead utility files sitting in src/utils/
• Unused imports across the repo
• TODOs everywhere
• One security-sensitive code path
• Repo health score: 68/100

After:

• All dead files removed safely
• All unused imports cleaned
• Backups stored
• PR automatically created
• Health score improved

This is what modern tooling should feel like.

🔧 CLI Usage

Full scan without changing files:

npx refineit

Export report:

npx refineit --export-report refineit-report.json

Apply fixes:

npx refineit --apply --yes

Undo backup:

refineit undo <backup-id>

Enable debug mode:

npx refineit --debug

💡 RefineIt GitHub Action (Super Important)

Add this to:

.github/workflows/refineit.yml

name: RefineIt (Auto PR)

on:
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  refine:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: ./.github/actions/refineit-action
        with:
          args: '--apply --yes --export-report refineit-report.json'
          create-pr: 'true'
          push_token: ${{ secrets.PUSH_TOKEN }}

This automatically creates:

refineit/auto-fixes → Pull Request

📁 Project Structure

.
├── .github/
│   ├── actions/
│   └── workflows/
├── assets/
│   ├── banner/
│   │   └── refineit-hero-banner.png
│   ├── demos/
│   │   ├── auto-pr-demo.mp4
│   │   ├── backup-restore-demo.gif
│   │   ├── safety-lock.gif
│   │   └── main-demo.mp4
│   └── screenshots/
│       ├── before-after.png
│       └── health-score.png
├── src/
│   ├── utils/
│   │   ├── analyzer.ts
│   │   ├── fixer.ts
│   │   └── ...
│   └── index.ts
├── .eslintrc.cjs
├── .gitignore
├── .prettierrc
├── jest.config.cjs
├── package.json
├── tsconfig.json
└── README.md

📬 Contact & Community

📄 License

MIT — do whatever you want, just don’t remove attribution.

❤️ Final Note

RefineIt was built because developers deserve a tool that actually respects their codebase. No surprises. No destructive behavior. Just clean, safe, automated refactoring — with full transparency.