[Refactor] Modularization Phase 1: Foundation Layer Split

[EffortlessSteven]

Implement Phase 1 of the Modularization Plan. See plans/modularization-report.md Appendix C for checklist. Split xchecker-utils into xchecker-core and xchecker-runner.

[EffortlessSteven]

This is currently planned. See plans/modularization-report.md for details.

[EffortlessSteven]

Status update (2026-01-23)

Summary

The Modularization Phase 1 is ready for implementation. The goal is to split the monolithic xchecker-utils crate into two focused crates: xchecker-core (types, error handling, primitives) and xchecker-runner (process execution, Claude CLI integration). This will reduce compilation times and clarify architectural boundaries.

Current state (verified)

What exists today

• crates/xchecker-utils contains a mix of core types (error.rs, types.rs) and heavy execution logic (runner/).
• plans/modularization-report.md (Appendix C) defines the exact file split.
• Cargo.toml in xchecker-utils has dependencies for both concerns.

What’s missing / not working yet

• crates/xchecker-core does not exist.
• crates/xchecker-runner does not exist.
• Downstream crates (config, engine, llm) depend on xchecker-utils.

Evidence

• Code: crates/xchecker-utils/src/lib.rs — shows exports of both runner and types.
• Docs: plans/modularization-report.md — Appendix C lists the checklist for this specific issue.

Root cause / blocker(s)

This is a planned refactoring task, not a bug.

• Blocker 1: Requires a dedicated block of time to move files and fix imports across the workspace.

Implementation impact (telemetry)

• Change shape (expected): High. Will touch almost every file in the workspace to update imports (e.g., xchecker_utils:: -> xchecker_core::).
• Blast radius / surface area: Internal architecture only. Public CLI API is unaffected, but internal APIs will move.
• Risk class: Medium. Strictly a refactor (move/rename), but high chance of merge conflicts if other branches are active.
• Rollback: git revert of the refactor commit.
• Verification gates: just check (clippy) and just test-local (unit tests) must pass.

Options

Option A (recommended): Direct Split & Deprecate Utils

What it is

• Create xchecker-core and xchecker-runner.
• Move code accordingly.
• Update all consumers (engine, config, llm) to depend on the new crates.
• Remove xchecker-utils from the workspace.

Why it fits this codebase

• Directly achieves the "Foundation Layer Split" goal.
• Removes the temptation to use "utils" as a junk drawer.

Trade-offs

• Structure: Cleanest end state.
• Velocity: High initial churn (touching many files).
• Governance/risk: One-way door; hard to cherry-pick back if needed.

Option B: Facade Pattern

What it is

• Create xchecker-core and xchecker-runner.
• Re-export them from xchecker-utils for backward compatibility.

When to choose this instead

• If we had external consumers of the crate library (we don't; this is a binary).

Trade-offs

• Structure: Keeps xchecker-utils around unnecessarily.
• Velocity: Easier migration (can update consumers lazily).
• Governance/risk: Lower risk of breaking in-flight branches.

Recommendation

I recommend Option A.

Why

• We want to enforce strict boundaries. Keeping xchecker-utils allows loose coupling to creep back in.
• This is an application (binary), not a library, so we don't need to support external downstream consumers.

Immediate next actions

1. Scaffold new crates.
2. Move files.
3. Fix compilation.

Proposed implementation (draft)

Plan of record (ordered)

1. Create crates/xchecker-core and crates/xchecker-runner.
2. Move atomic_write.rs, error.rs, types.rs, etc. to core.
3. Move runner/ module to runner crate.
4. Update Cargo.toml in both new crates to split dependencies.
5. Update crates/xchecker-config, llm, engine to depend on core/runner.
6. Global search-and-replace for imports.
7. Remove crates/xchecker-utils.

Files / modules to change

• crates/xchecker-utils/src/* — Moved to crates/xchecker-core/src/.
• crates/xchecker-utils/src/runner/* — Moved to crates/xchecker-runner/src/.
• Cargo.toml (root) — Update workspace members.

New/changed interfaces (copy/paste level if possible)

# crates/xchecker-core/Cargo.toml
[package]
name = "xchecker-core"
version = "0.1.0"
edition = "2024"

[dependencies]
thiserror = { workspace = true }
serde = { workspace = true }
# ... other core deps (tracing, camino, etc)

# crates/xchecker-runner/Cargo.toml
[package]
name = "xchecker-runner"
version = "0.1.0"
edition = "2024"

[dependencies]
xchecker-core = { path = "../xchecker-core" }
tokio = { workspace = true }
# ... runner specific deps (sysinfo, etc)

Key logic sketch / pseudo-diff

// Old: crates/xchecker-engine/src/lib.rs
// use xchecker_utils::types::SpecId;
// use xchecker_utils::runner::Command;

// New: crates/xchecker-engine/src/lib.rs
use xchecker_core::types::SpecId;
use xchecker_runner::Command;

Tests to add / update

• No new logic, so no new tests.
• Existing tests in runner must pass in the new crate location.
• cargo test -p xchecker-core
• cargo test -p xchecker-runner

Rollout / migration / backward-compat

• N/A (Internal refactor).

Verification plan

Commands + expected signal:

• cargo build → Success
• just check → No clippy warnings
• just test-local → All tests pass (approx 30s)

Definition of done

• crates/xchecker-utils is removed.
• crates/xchecker-core contains all base types and primitives.
• crates/xchecker-runner contains all execution logic.
• CI passes.

Close / keep-open recommendation

• Recommendation: Keep open
• Criteria: Close when the PR implementing this split is merged.