refactor: split evaluator/mod.rs into focused submodules

[unclesp1d3r]

Summary

src/evaluator/mod.rs is 2,638 lines -- 4.4x the project's 500-600 line guideline. It contains multiple responsibilities that should be separated into focused submodules.

Current State

The file contains:

• EvaluationContext struct and methods (~200 lines)
• MatchResult type and methods (~50 lines)
• evaluate_single_rule() public function (~20 lines)
• evaluate_rules() recursive hierarchical evaluation (~200 lines)
• evaluate_rules_with_config() wrapper
• ~2,000 lines of colocated #[cfg(test)] tests

Proposed Split

1. evaluator/mod.rs -- Public API surface only: EvaluationContext, MatchResult, re-exports
2. evaluator/engine.rs -- Core evaluation logic: evaluate_single_rule(), evaluate_rules(), evaluate_rules_with_config(), and the recursive hierarchy processing
3. Move large test blocks to tests/evaluator_tests.rs or keep as #[cfg(test)] within each submodule

Why Before v0.2.0

v0.2.0 adds comparison operators (#34, #35), indirect offsets (#37), and relative offsets (#38). All of these will add evaluation logic to this module. Splitting now prevents the file from growing to 3,500+ lines.

Acceptance Criteria

• evaluator/mod.rs is under 600 lines
• No public API changes (all re-exports preserved)
• All existing tests pass
• cargo clippy -- -D warnings passes

[traycerai]

Plan

Observations

The file:src/evaluator/mod.rs file contains 2,636 lines with ~2,100 lines of tests (80% of the file). The core evaluation logic is well-structured with clear separation between EvaluationContext (state management), MatchResult (result representation), and three evaluation functions. The module already has four focused submodules (offset, operators, strength, types). The public API surface is minimal and re-exported in file:src/lib.rs.

Approach

Split the monolithic file:src/evaluator/mod.rs into focused submodules while preserving the public API. Create file:src/evaluator/engine.rs for core evaluation logic, keep EvaluationContext and MatchResult in file:src/evaluator/mod.rs as the public interface, and migrate tests to inline #[cfg(test)] modules within each new submodule following the project's existing pattern (as seen in file:src/evaluator/offset.rs, file:src/evaluator/operators.rs, etc.).

Implementation Steps

1. Create file:src/evaluator/engine.rs for Core Evaluation Logic

Extract the three main evaluation functions from file:src/evaluator/mod.rs (lines 246-527):

• Move evaluate_single_rule() function (~66 lines, lines 246-311)
• Move evaluate_rules() function (~160 lines, lines 312-471)
• Move evaluate_rules_with_config() function (~56 lines, lines 472-527)
• Add necessary imports: crate::parser::ast::MagicRule, crate::EvaluationConfig, crate::LibmagicError, super::{EvaluationContext, MatchResult}, and imports from submodules (offset::resolve_offset, types::read_typed_value, operators::apply_operator)
• Include module documentation explaining this contains the core recursive evaluation engine
• Add #[cfg(test)] module at the end with relevant unit tests extracted from lines 529-2636 that specifically test these three functions (tests for single rule evaluation, hierarchical evaluation, timeout handling, recursion limits, graceful error handling)

2. Refactor file:src/evaluator/mod.rs to Public API Surface

Transform file:src/evaluator/mod.rs into a clean module interface (~200-300 lines):

• Keep module-level documentation (lines 1-17)
• Declare submodules: mod offset;, mod operators;, mod strength;, mod types;, mod engine;
• Re-export submodule items: pub use offset::*;, pub use operators::*;, pub use strength::*;, pub use types::*;
• Re-export engine functions: pub use engine::{evaluate_single_rule, evaluate_rules, evaluate_rules_with_config};
• Keep EvaluationContext struct definition and implementation (lines 18-198)
• Keep MatchResult struct definition and implementation (lines 199-245)
• Add #[cfg(test)] module with tests specific to EvaluationContext and MatchResult (extract from lines 529-2636: context management tests, offset tracking tests, recursion depth tests, match result confidence calculation tests)

3. Distribute Remaining Tests

Organize the ~2,100 lines of tests from lines 529-2636:

• Tests for EvaluationContext methods → inline #[cfg(test)] in file:src/evaluator/mod.rs
• Tests for MatchResult methods → inline #[cfg(test)] in file:src/evaluator/mod.rs
• Tests for evaluate_single_rule() → inline #[cfg(test)] in file:src/evaluator/engine.rs
• Tests for evaluate_rules() and hierarchical evaluation → inline #[cfg(test)] in file:src/evaluator/engine.rs
• Tests for evaluate_rules_with_config() → inline #[cfg(test)] in file:src/evaluator/engine.rs
• Integration tests remain in existing file:tests/evaluator_tests.rs (no changes needed)

4. Verify Public API Preservation

Ensure no breaking changes to the public API:

• Confirm file:src/lib.rs re-exports still work: pub use evaluator::{EvaluationContext, MatchResult};
• Verify all three evaluation functions are accessible via use libmagic_rs::evaluator::{evaluate_single_rule, evaluate_rules, evaluate_rules_with_config};
• Check that submodule items remain accessible: use libmagic_rs::evaluator::offset::resolve_offset;, etc.
• Ensure no changes to function signatures or struct fields

5. Run Validation

Execute the following validation steps:

• Run cargo test to ensure all existing tests pass
• Run cargo clippy -- -D warnings to verify no new warnings
• Run cargo build --release to confirm compilation succeeds
• Verify file:src/evaluator/mod.rs is under 600 lines (target: ~200-300 lines)
• Verify file:src/evaluator/engine.rs is under 600 lines (target: ~400-500 lines including tests)
• Check that total line count across all evaluator files remains approximately the same

File Structure After Refactoring

src/evaluator/
├── mod.rs           (~200-300 lines: public API, EvaluationContext, MatchResult, re-exports, tests)
├── engine.rs        (~400-500 lines: evaluate_single_rule, evaluate_rules, evaluate_rules_with_config, tests)
├── offset.rs        (existing: 473 lines)
├── operators.rs     (existing: 1,618 lines)
├── strength.rs      (existing: 871 lines)
└── types.rs         (existing: 1,502 lines)

Module Dependency Flow

graph TD
    A[mod.rs<br/>Public API] --> B[engine.rs<br/>Core Evaluation]
    B --> C[offset.rs<br/>Offset Resolution]
    B --> D[types.rs<br/>Type Reading]
    B --> E[operators.rs<br/>Operator Application]
    B --> F[strength.rs<br/>Strength Calculation]
    A -.re-exports.-> C
    A -.re-exports.-> D
    A -.re-exports.-> E
    A -.re-exports.-> F

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `file:src/evaluator/mod.rs` file contains 2,636 lines with ~2,100 lines of tests (80% of the file). The core evaluation logic is well-structured with clear separation between `EvaluationContext` (state management), `MatchResult` (result representation), and three evaluation functions. The module already has four focused submodules (`offset`, `operators`, `strength`, `types`). The public API surface is minimal and re-exported in `file:src/lib.rs`.

## Approach

Split the monolithic `file:src/evaluator/mod.rs` into focused submodules while preserving the public API. Create `file:src/evaluator/engine.rs` for core evaluation logic, keep `EvaluationContext` and `MatchResult` in `file:src/evaluator/mod.rs` as the public interface, and migrate tests to inline `#[cfg(test)]` modules within each new submodule following the project's existing pattern (as seen in `file:src/evaluator/offset.rs`, `file:src/evaluator/operators.rs`, etc.).

## Implementation Steps

### 1. Create `file:src/evaluator/engine.rs` for Core Evaluation Logic

Extract the three main evaluation functions from `file:src/evaluator/mod.rs` (lines 246-527):

- Move `evaluate_single_rule()` function (~66 lines, lines 246-311)
- Move `evaluate_rules()` function (~160 lines, lines 312-471)
- Move `evaluate_rules_with_config()` function (~56 lines, lines 472-527)
- Add necessary imports: `crate::parser::ast::MagicRule`, `crate::EvaluationConfig`, `crate::LibmagicError`, `super::{EvaluationContext, MatchResult}`, and imports from submodules (`offset::resolve_offset`, `types::read_typed_value`, `operators::apply_operator`)
- Include module documentation explaining this contains the core recursive evaluation engine
- Add `#[cfg(test)]` module at the end with relevant unit tests extracted from lines 529-2636 that specifically test these three functions (tests for single rule evaluation, hierarchical evaluation, timeout handling, recursion limits, graceful error handling)

### 2. Refactor `file:src/evaluator/mod.rs` to Public API Surface

Transform `file:src/evaluator/mod.rs` into a clean module interface (~200-300 lines):

- Keep module-level documentation (lines 1-17)
- Declare submodules: `mod offset;`, `mod operators;`, `mod strength;`, `mod types;`, `mod engine;`
- Re-export submodule items: `pub use offset::*;`, `pub use operators::*;`, `pub use strength::*;`, `pub use types::*;`
- Re-export engine functions: `pub use engine::{evaluate_single_rule, evaluate_rules, evaluate_rules_with_config};`
- Keep `EvaluationContext` struct definition and implementation (lines 18-198)
- Keep `MatchResult` struct definition and implementation (lines 199-245)
- Add `#[cfg(test)]` module with tests specific to `EvaluationContext` and `MatchResult` (extract from lines 529-2636: context management tests, offset tracking tests, recursion depth tests, match result confidence calculation tests)

### 3. Distribute Remaining Tests

Organize the ~2,100 lines of tests from lines 529-2636:

- Tests for `EvaluationContext` methods → inline `#[cfg(test)]` in `file:src/evaluator/mod.rs`
- Tests for `MatchResult` methods → inline `#[cfg(test)]` in `file:src/evaluator/mod.rs`
- Tests for `evaluate_single_rule()` → inline `#[cfg(test)]` in `file:src/evaluator/engine.rs`
- Tests for `evaluate_rules()` and hierarchical evaluation → inline `#[cfg(test)]` in `file:src/evaluator/engine.rs`
- Tests for `evaluate_rules_with_config()` → inline `#[cfg(test)]` in `file:src/evaluator/engine.rs`
- Integration tests remain in existing `file:tests/evaluator_tests.rs` (no changes needed)

### 4. Verify Public API Preservation

Ensure no breaking changes to the public API:

- Confirm `file:src/lib.rs` re-exports still work: `pub use evaluator::{EvaluationContext, MatchResult};`
- Verify all three evaluation functions are accessible via `use libmagic_rs::evaluator::{evaluate_single_rule, evaluate_rules, evaluate_rules_with_config};`
- Check that submodule items remain accessible: `use libmagic_rs::evaluator::offset::resolve_offset;`, etc.
- Ensure no changes to function signatures or struct fields

### 5. Run Validation

Execute the following validation steps:

- Run `cargo test` to ensure all existing tests pass
- Run `cargo clippy -- -D warnings` to verify no new warnings
- Run `cargo build --release` to confirm compilation succeeds
- Verify `file:src/evaluator/mod.rs` is under 600 lines (target: ~200-300 lines)
- Verify `file:src/evaluator/engine.rs` is under 600 lines (target: ~400-500 lines including tests)
- Check that total line count across all evaluator files remains approximately the same

## File Structure After Refactoring

```
src/evaluator/
├── mod.rs           (~200-300 lines: public API, EvaluationContext, MatchResult, re-exports, tests)
├── engine.rs        (~400-500 lines: evaluate_single_rule, evaluate_rules, evaluate_rules_with_config, tests)
├── offset.rs        (existing: 473 lines)
├── operators.rs     (existing: 1,618 lines)
├── strength.rs      (existing: 871 lines)
└── types.rs         (existing: 1,502 lines)
```

## Module Dependency Flow

```mermaid
graph TD
    A[mod.rs<br/>Public API] --> B[engine.rs<br/>Core Evaluation]
    B --> C[offset.rs<br/>Offset Resolution]
    B --> D[types.rs<br/>Type Reading]
    B --> E[operators.rs<br/>Operator Application]
    B --> F[strength.rs<br/>Strength Calculation]
    A -.re-exports.-> C
    A -.re-exports.-> D
    A -.re-exports.-> E
    A -.re-exports.-> F
```

---

Execution Information

Branch: main
Commit: 36adac5

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.