ai-refactor-cli 0.2.0

# Architecture

## Position vs. other tools

`ai-refactor-cli` is one piece of a larger jimolab tooling stack. It is **not** an AI coding agent and is **not** a code-search engine.

| Tool                    | Layer                            | What it does                                            | Relationship                                                                 |
| ----------------------- | -------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Claude Code / Codex     | Interactive agent                | Generate & edit code with broad context                 | Calls `ai-refactor` as a CI / pre-commit step                                |
| Cursor / Windsurf / Aider | IDE-embedded AI               | Inline pair programming                                 | Same — invokes `ai-refactor` as a task runner                                |
| **zeus-code** (sibling) | Organizational code search       | "Find similar modules across our repos"                 | Library layer is sharable, **CLI surfaces stay independent** (5/8 directive) |
| **ai-refactor**         | Rule-based regularizer           | "Make this repo conform to our standards"               | This project                                                                 |

## Why Rust

1. **Single static binary** — `cargo install` or a GitHub release tarball. No npm, no pip, no JVM. Critical for OSS adoption friction.
2. **Tree-sitter is first-class in Rust** — every parser the project will need (TS, TSX, Python, Rust itself, Go) has a maintained Rust binding.
3. **Shared library layer with zeus-code** — same language, same AST query primitives. Even though the CLI surfaces stay independent (per owner directive 2026-05-08), the internal `refactor-core` crate can be lifted into `zeus-core` later without rewrites.
4. **CI cost** — Rust binary cold-start dominates Python's for short-lived CI jobs that scan thousands of files.

Considered alternatives and why they were rejected:

- **Go** — splits the toolchain from zeus-code's existing Rust modules.
- **Python** — slow cold-start, distribution headaches (pip vs. pipx vs. uv), no static binary.
- **Node** — pkg / nexe are perennial pain points; `npm install -g` UX is degraded.

## Detection pipeline (v0.1.0)

```
walkdir  →  per-file extension filter  →  per-rule regex  →  Finding{rule_id, file, line, snippet}
                                                                   │
                                                                   ▼
                                                 text  /  json  reporter  →  exit 0 / 1
```

Regex is a deliberate v0.1.0 choice. tree-sitter is wired into `Cargo.toml` so that swapping in a real grammar in v0.2.0 only touches `rules.rs` and `scanner.rs` — the CLI surface is stable.

## Transformation pipeline (v0.2.0+)

```
tree-sitter parse  →  query node set  →  edit plan  →  diff preview  →  --apply writes
                                              │
                                              ▼
                                  (optional) AI proposal via OpenRouter when the
                                  pure-AST transformation cannot decide a concrete
                                  type / shape (e.g. inferring real types for `any`)
```

The AI step is **opt-in** and never the first attempt — the goal is determinism first, AI fallback only when AST inference is insufficient.

## Module layout

| Module          | Responsibility                                          |
| --------------- | ------------------------------------------------------- |
| `src/main.rs`   | clap CLI surface, subcommand dispatch                   |
| `src/rules.rs`  | Static `RULES` registry + regex compilation             |
| `src/scanner.rs`| Filesystem traversal, per-file rule application         |
| `src/report.rs` | Text & JSON output formatters                           |

When the project grows past ~3 modules, `refactor-core` will be split into its own crate under a Cargo workspace. Per the launch plan we explicitly **avoid** a workspace at v0.1.0 to keep `cargo install` trivial.