Refactron

Safety-first refactoring — finds, fixes, and verifies code changes are safe before touching the filesystem.

---

What is Refactron?

Refactron is a TypeScript CLI that analyzes your codebase for issues, automatically fixes what it can, and verifies every change is safe before writing a single byte to disk.

The core differentiator: Blast Radius. Every issue carries a mandatory impact score (0–100) computed from transitive import and call graphs. The verification engine scales its strictness based on this score — a one-liner fix in an isolated utility gets a quick syntax check, while a change to a widely-imported core module triggers syntax + import + full test suite verification.

refactron analyze src/
refactron autofix . --verify

---

Features

• Blast Radius Scoring — every issue gets a 0–100 impact score across 5 levels (trivial → critical), computed from transitive import and call graphs
• Verification Gate — changes are verified (syntax, imports, tests) before being written; strictness scales with blast radius
• Atomic Writes — all file writes use temp-file-then-rename; partial writes never happen
• Backup & Rollback — every session is backed up; refactron rollback restores the previous state
• 14 Auto-fixers — unused imports, trailing whitespace, dead code, missing type hints, sort imports, and more
• 7 Analyzers — security (SQL injection, eval, hardcoded secrets), complexity, code smell, dead code, type hints, dependencies, performance
• Python + TypeScript — language-agnostic engine with pluggable ILanguageAdapter
• Ink Terminal UI — interactive issue browser with blast radius graph, diff view, and verification progress

---

Installation

npm install -g refactron

Requires Node.js 18+ and (for Python analysis) Python 3.8+.

---

Quick Start

# Analyze your project
refactron analyze src/

# Preview fixes without writing anything
refactron autofix . --dry-run

# Fix with full verification gate
refactron autofix . --verify

# Check session status
refactron status

# Undo last applied fixes
refactron rollback

---

Commands

Command	Description
analyze [target]	Scan files and report issues with blast radius scores
autofix [target]	Fix issues with verification before writing
verify [file]	Verify a specific file is safe to modify
status	Show current session state and fix counts
rollback	Restore files from last session backup
diff [target]	Display unified diff for a pending fix

Options

Flag	Description
--fail-on <level>	Exit non-zero if issues at critical, high, medium, or low found
--dry-run	Preview fixes without writing to disk
--verify	Require verification gate before applying any fix
--format <fmt>	Output format: terminal (default), json, sarif

---

How Blast Radius Works

Every CodeIssue carries a mandatory BlastRadius object:

interface BlastRadius {
  affectedFiles: string[];       // files transitively depending on the changed file
  affectedFunctions: string[];   // functions in the call chain
  affectedTestFiles: string[];   // test files that cover affected code
  score: number;                 // 0–100 weighted impact score
  level: BlastLevel;             // trivial | low | medium | high | critical
}

Score formula: files (40%) + functions (40%) + test coverage gap (20%)

Verification escalation by blast level:

Level	Score	Checks Run
trivial	0	syntax only
low	1–19	syntax + imports + tests (45s timeout)
medium	20–49	syntax + imports + tests (45s timeout)
high	50–74	syntax + imports + tests (45s timeout)
critical	75–100	syntax + imports + tests (120s timeout)

---

Analyzers

Analyzer	Issues Detected
Security	SQL injection, eval(), hardcoded secrets, exec()
Complexity	Cyclomatic complexity above threshold (default: 10)
Code Smell	Long methods, god objects
Dead Code	Unreachable code after return/raise/break
Type Hints	Missing return type annotations, explicit any
Dependencies	Unused imports
Performance	List concatenation in loops, await inside loops

---

Auto-fixers

Fixer	What it fixes
unused-imports	Removes unused import statements
trailing-whitespace	Strips trailing whitespace from all lines
dead-code	Removes unreachable code
sort-imports	Sorts imports alphabetically
normalize-quotes	Normalizes quote style
type-hints	Adds -> None return type annotations
docstrings	Inserts placeholder docstrings
simplify-boolean	Simplifies x == True → x
unused-variables	Removes unused variable declarations
fix-indentation	Converts tabs to 4-space indentation
missing-commas	Adds missing trailing commas
remove-debug	Removes debug/print statements
magic-numbers	Flags magic numbers for manual review
convert-fstring	Flags %-format strings for manual conversion

---

Architecture

src/
├── core/
│   ├── models.ts          # All types — LOCKED (CodeIssue, BlastRadius, etc.)
│   ├── config.ts          # RefactronConfig + YAML loader
│   └── orchestrator.ts    # Full pipeline coordinator
├── adapters/
│   ├── interface.ts       # ILanguageAdapter — LOCKED
│   ├── registry.ts        # Language auto-detection
│   ├── python/            # Python adapter (subprocess)
│   └── typescript/        # TypeScript adapter (compiler API)
├── analysis/
│   ├── blast-radius.ts    # Transitive impact scoring
│   ├── import-graph.ts    # File-level reverse import graph
│   ├── call-graph.ts      # Function-level call graph
│   ├── temporal.ts        # Git history intelligence
│   ├── engine.ts          # Analysis orchestrator
│   └── analyzers/         # 7 language-agnostic analyzers
├── verification/
│   ├── engine.ts          # Blast-radius-aware check selection
│   ├── atomic-writer.ts   # Temp → rename safe writes
│   └── checks/            # syntax, imports, test-gate
├── autofix/
│   ├── engine.ts          # AutoFix orchestrator
│   └── fixers/            # 14 fixers
├── pipeline/
│   ├── session.ts         # State machine
│   ├── store.ts           # .refactron/ persistence
│   └── queue.ts           # Fix queue management
├── infrastructure/
│   ├── backup.ts          # Pre-write backup + rollback
│   ├── diff.ts            # Unified diff generation
│   └── git.ts             # Git log + co-change analysis
├── cli/
│   ├── index.ts           # Fast-path dispatcher (<10ms for --version)
│   ├── app.tsx            # Command router
│   └── commands/          # 6 Ink command components
└── ui/                    # Ink terminal UI components

---

Configuration

Create a refactron.yaml in your project root:

version: 2
analyzers:
  complexity:
    enabled: true
    threshold: 10        # cyclomatic complexity limit
  security:
    enabled: true
  code_smell:
    enabled: true
    max_method_lines: 50
  dead_code:
    enabled: true
  type_hints:
    enabled: true
  dependencies:
    enabled: true
  performance:
    enabled: true
verification:
  timeout_seconds: 45
  critical_timeout_seconds: 120
autofix:
  dry_run: false
  require_verification: true
output:
  format: terminal         # terminal | json | sarif
  fail_on: null            # critical | high | medium | low | null

---

Development

git clone https://github.com/Refactron-ai/Refactron_Lib_TS.git
cd Refactron_Lib_TS
npm install

npm run build          # compile TypeScript
npm test               # run 45 tests
npm run typecheck      # type check only
npm run lint           # ESLint
npm run format         # Prettier
npm run test:watch     # watch mode

Adding a Language Adapter

Implement ILanguageAdapter from src/adapters/interface.ts and register it in src/adapters/registry.ts. The interface is locked — all language-specific logic must stay inside the adapter.

Adding a Fixer

Extend BaseFixer from src/autofix/fixers/base.ts, declare supportedIssueTypes, implement fix(), and register it in src/autofix/engine.ts.

---

Contributing

See CONTRIBUTING.md.

---

Changelog

See CHANGELOG.md.

---

License

MIT — see LICENSE.