wehub-resource-sync
a789495a98
FreeBSD Smoke / FreeBSD Smoke (x86_64) (push) Has been cancelled
CI / Quality Guardrails (push) Has been cancelled
CI / Build & Test (macos-latest) (push) Has been cancelled
CI / Build & Test (ubuntu-latest) (push) Has been cancelled
CI / Build & Test (windows-latest) (push) Has been cancelled
CI / Format (push) Has been cancelled
CI / PowerShell Syntax (push) Has been cancelled
CI / Windows Cross-Target Check (Linux) (push) Has been cancelled
78 lines
2.6 KiB
Markdown
78 lines
2.6 KiB
Markdown
# Refactoring Roadmap
|
|
|
|
This document defines the safe, incremental path for refactoring jcode while preserving behavior.
|
|
|
|
See also:
|
|
|
|
- [`docs/CODE_QUALITY_10_10_PLAN.md`](CODE_QUALITY_10_10_PLAN.md) for the code-quality target, phased uplift program, and initial hotspot refactor list.
|
|
- [`docs/COMPILE_PERFORMANCE_PLAN.md`](COMPILE_PERFORMANCE_PLAN.md) for compile-speed baselines, tactical build workflow, and the workspace/crate split roadmap.
|
|
|
|
## Goals
|
|
|
|
- Keep existing sessions and user workflows stable during refactors.
|
|
- Make regressions visible early with repeatable checks.
|
|
- Reduce architectural coupling in stages (not big-bang rewrites).
|
|
|
|
## Non-Negotiable Safety Rules
|
|
|
|
1. Use an isolated environment for refactor runs:
|
|
|
|
- `scripts/refactor_shadow.sh serve`
|
|
- `scripts/refactor_shadow.sh run`
|
|
- `scripts/refactor_shadow.sh build --release`
|
|
|
|
2. Before each refactor merge, run the phase-1 verification suite:
|
|
|
|
- `scripts/refactor_phase1_verify.sh`
|
|
|
|
3. Warning count may not increase above baseline:
|
|
|
|
- `scripts/check_warning_budget.sh`
|
|
|
|
4. Run security preflight before merges:
|
|
|
|
- `scripts/security_preflight.sh`
|
|
|
|
5. Prefer behavior-preserving moves first (extract/rename/split), then logic changes.
|
|
|
|
## Phase Plan
|
|
|
|
### Phase 1: Safety + Hygiene (current)
|
|
|
|
- Add isolated dev/run workflow for refactors.
|
|
- Add repeatable verification script.
|
|
- Add warning-budget guard to prevent warning drift.
|
|
- Clean low-risk warning debt without functional changes.
|
|
|
|
### Phase 2: CLI Decomposition
|
|
|
|
- Move `main.rs` subcommand handlers into focused `src/cli/*` modules.
|
|
- Keep top-level `main()` as parse + dispatch.
|
|
|
|
### Phase 3: Server Decomposition
|
|
|
|
- Split `server.rs` by responsibility (session lifecycle, debug API, swarm coordination, reload/update).
|
|
- Replace stringly states with typed enums where practical.
|
|
|
|
### Phase 4: Agent Turn-Loop Unification
|
|
|
|
- Consolidate duplicated turn-loop variants into one shared engine with pluggable event sink.
|
|
|
|
### Phase 5: TUI State/Reducer Split
|
|
|
|
- Separate app state, command parsing, remote-event reduction, and rendering control.
|
|
|
|
### Phase 6: Provider State Isolation
|
|
|
|
- Reduce global mutable state by moving caches into explicit state holders.
|
|
|
|
## Verification Matrix
|
|
|
|
- Compile: `cargo check -q`
|
|
- Compile timing: `scripts/bench_compile.sh check --runs 3 --touch <hot-file>` and `scripts/bench_compile.sh release-jcode --runs 3`
|
|
- Warnings: `scripts/check_warning_budget.sh`
|
|
- Security: `scripts/security_preflight.sh`
|
|
- Unit+integration tests: `cargo test -q`
|
|
- E2E tests: `cargo test --test e2e -q`
|
|
- Combined: `scripts/refactor_phase1_verify.sh`
|