refactor: pre-create evaluator submodules for v0.2.0 features

[unclesp1d3r]

Summary

v0.2.0 adds comparison operators (#34), bitwise XOR/NOT (#35), indirect offsets (#37), and relative offsets (#38). These features will add significant code to files that are already oversized:

• evaluator/operators.rs (1,620 lines) will grow with comparison and bitwise operators
• evaluator/offset.rs (475 lines) will grow with indirect/relative offset evaluation

Pre-creating focused submodules prevents these files from becoming unmanageable.

Proposal

Create the following submodule structure:

evaluator/
├── mod.rs              # Public API (after #58 split)
├── engine.rs           # Core evaluation logic (after #58 split)
├── offset.rs           # Absolute + from-end offsets (existing)
├── offset_indirect.rs  # Indirect offset resolution (#37)
├── offset_relative.rs  # Relative offset resolution (#38)
├── operators.rs        # Equality + bitwise AND (existing)
├── comparison.rs       # Comparison operators: >, <, >=, <= (#34)
├── bitwise.rs          # Bitwise XOR, NOT, any-value (#35)
├── strength.rs         # Strength calculation (existing)
└── types.rs            # Type reading (existing)

Alternatively, if the split is too granular:

evaluator/
├── operators/
│   ├── mod.rs          # Re-exports
│   ├── equality.rs     # =, !=, & (existing logic)
│   ├── comparison.rs   # >, <, >=, <=
│   └── bitwise.rs      # ^, ~, any-value
├── offset/
│   ├── mod.rs          # Re-exports + resolve_offset dispatcher
│   ├── absolute.rs     # Absolute + from-end
│   ├── indirect.rs     # Indirect resolution
│   └── relative.rs     # Relative resolution

Depends On

• docs: comprehensive documentation, security, and CI hardening #58 (split evaluator/mod.rs) -- should be done first

Acceptance Criteria

• Submodule files created with appropriate module declarations
• Existing code redistributed into new submodules
• Public API unchanged (re-exports in place)
• All tests pass
• Each file under 600 lines

Blocked By

• refactor: split evaluator/mod.rs into focused submodules #59 (split evaluator/mod.rs) -- should be done first

[traycerai]

Plan

Observations

The evaluator module currently has 5 files totaling ~7,100 lines. The file:src/evaluator/mod.rs (2,636 lines) and file:src/evaluator/operators.rs (1,618 lines) are already oversized. The AST in file:src/parser/ast.rs already defines Indirect and Relative offset variants, plus the current operator set (Equal, NotEqual, BitwiseAnd, BitwiseAndMask). Future v0.2.0 features will add comparison operators (>, <, >=, <=) and bitwise XOR/NOT to the Operator enum, plus implementations for indirect/relative offset resolution. Critical: Issue #58 (splitting mod.rs into mod.rs + engine.rs) has not been completed yet, as evidenced by the absence of file:src/evaluator/engine.rs.

Approach

Since this ticket is blocked by #58, the plan assumes #58 will be completed first, creating file:src/evaluator/engine.rs with core evaluation logic. The refactoring will use the flat submodule structure (first proposal in the ticket) rather than nested directories, as it's simpler and more idiomatic for Rust. Each new submodule will be created with appropriate module declarations, existing code will be redistributed, and public APIs will be preserved through re-exports in file:src/evaluator/mod.rs. The goal is to keep each file under 600 lines while maintaining all existing functionality and tests.

Implementation Steps

1. Pre-requisite Verification

Verify that issue #58 has been completed:

• Confirm file:src/evaluator/engine.rs exists with core evaluation logic (evaluate_single_rule, evaluate_rules, EvaluationContext)
• Confirm file:src/evaluator/mod.rs has been reduced to public API re-exports and module declarations
• Ensure all existing tests still pass after the docs: comprehensive documentation, security, and CI hardening #58 split

2. Create Offset Submodules

Create file:src/evaluator/offset_indirect.rs:

• Add module documentation explaining indirect offset resolution (reading pointer values and dereferencing)
• Create placeholder function resolve_indirect_offset(base_offset: i64, pointer_type: &TypeKind, adjustment: i64, endian: &Endianness, buffer: &[u8]) -> Result<usize, OffsetError>
• Add comprehensive documentation referencing issue Evaluator: implement indirect offset resolution #37
• Include TODO comment: "Implementation pending for v0.2.0 (issue Evaluator: implement indirect offset resolution #37)"
• Add basic test structure with #[ignore] attribute for future implementation
• Keep file under 200 lines initially (will grow when Evaluator: implement indirect offset resolution #37 is implemented)

Create file:src/evaluator/offset_relative.rs:

• Add module documentation explaining relative offset resolution (offsets from previous match position)
• Create placeholder function resolve_relative_offset(relative: i64, context: &EvaluationContext, buffer: &[u8]) -> Result<usize, OffsetError>
• Add comprehensive documentation referencing issue Evaluator: implement relative offset resolution #38
• Include TODO comment: "Implementation pending for v0.2.0 (issue Evaluator: implement relative offset resolution #38)"
• Add basic test structure with #[ignore] attribute for future implementation
• Keep file under 200 lines initially (will grow when Evaluator: implement relative offset resolution #38 is implemented)

Update file:src/evaluator/offset.rs:

• Keep existing resolve_absolute_offset function and all its tests
• Keep existing OffsetError enum definition
• Update resolve_offset dispatcher function to call new submodules:
  • For OffsetSpec::Indirect: call offset_indirect::resolve_indirect_offset
  • For OffsetSpec::Relative: call offset_relative::resolve_relative_offset
• Add module declarations: mod offset_indirect; and mod offset_relative;
• Add public re-exports if needed for external API compatibility
• Ensure file stays under 500 lines after modifications

3. Create Operator Submodules

Create file:src/evaluator/comparison.rs:

• Add module documentation explaining comparison operators for v0.2.0
• Create placeholder functions:
  • apply_greater_than(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_less_than(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_greater_equal(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_less_equal(file_value: &Value, expected: &Value) -> Result<bool, String>
• Add comprehensive documentation referencing issue Parser: implement comparison operators (<, >, <=, >=) #34
• Include TODO comment: "Implementation pending for v0.2.0 (issue Parser: implement comparison operators (<, >, <=, >=) #34)"
• Add basic test structure with #[ignore] attribute for future implementation
• Keep file under 300 lines initially (will grow significantly when Parser: implement comparison operators (<, >, <=, >=) #34 is implemented)

Create file:src/evaluator/bitwise.rs:

• Add module documentation explaining bitwise XOR, NOT, and any-value operators
• Create placeholder functions:
  • apply_bitwise_xor(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_bitwise_not(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_any_value(file_value: &Value) -> Result<bool, String>
• Add comprehensive documentation referencing issue Parser: implement bitwise XOR (^), NOT (~), and any-value (x) operators #35
• Include TODO comment: "Implementation pending for v0.2.0 (issue Parser: implement bitwise XOR (^), NOT (~), and any-value (x) operators #35)"
• Add basic test structure with #[ignore] attribute for future implementation
• Keep file under 300 lines initially (will grow when Parser: implement bitwise XOR (^), NOT (~), and any-value (x) operators #35 is implemented)

Update file:src/evaluator/operators.rs:

• Keep existing functions: apply_equal, apply_not_equal, apply_bitwise_and, apply_operator
• Keep all existing tests (they should remain under 1,200 lines)
• Add module declarations: mod comparison; and mod bitwise;
• Update apply_operator dispatcher to prepare for future operators (add match arms with unimplemented!() for new operator variants when they're added to AST)
• Add public re-exports if needed for external API compatibility
• Target: reduce from 1,618 lines to under 600 lines by moving tests to separate test modules if needed

4. Update Module Structure

Update file:src/evaluator/mod.rs:

• Add module declarations for new submodules:

  mod offset_indirect;
  mod offset_relative;
  mod comparison;
  mod bitwise;

• Add public re-exports to maintain existing API:

  pub use offset::{resolve_offset, resolve_absolute_offset, OffsetError};
  pub use operators::{apply_operator, apply_equal, apply_not_equal, apply_bitwise_and};

• Ensure no breaking changes to public API
• Document the new module structure in module-level documentation
• Keep file under 200 lines (should already be small after docs: comprehensive documentation, security, and CI hardening #58 split)

5. Verification and Testing

Run comprehensive test suite:

• Execute cargo test --package libmagic-rs --lib evaluator to verify all existing tests pass
• Verify no compilation errors or warnings
• Check that all public APIs remain accessible from external modules

Verify file sizes:

• Confirm file:src/evaluator/mod.rs < 200 lines
• Confirm file:src/evaluator/engine.rs < 600 lines (from docs: comprehensive documentation, security, and CI hardening #58)
• Confirm file:src/evaluator/offset.rs < 500 lines
• Confirm file:src/evaluator/offset_indirect.rs < 200 lines
• Confirm file:src/evaluator/offset_relative.rs < 200 lines
• Confirm file:src/evaluator/operators.rs < 600 lines (may need test refactoring)
• Confirm file:src/evaluator/comparison.rs < 300 lines
• Confirm file:src/evaluator/bitwise.rs < 300 lines
• Confirm file:src/evaluator/strength.rs remains at 871 lines (unchanged)
• Confirm file:src/evaluator/types.rs remains at 1,502 lines (unchanged)

Code quality checks:

• Run cargo clippy to ensure no new warnings
• Run cargo fmt to ensure consistent formatting
• Verify documentation builds with cargo doc --no-deps
• Check that all new modules have proper module-level documentation

6. Documentation Updates

Update file:docs/src/evaluator.md (if exists):

• Document the new submodule structure
• Add section explaining the organization: offset modules, operator modules, supporting modules
• Include a module dependency diagram showing relationships
• Reference issues Parser: implement comparison operators (<, >, <=, >=) #34, Parser: implement bitwise XOR (^), NOT (~), and any-value (x) operators #35, Evaluator: implement indirect offset resolution #37, Evaluator: implement relative offset resolution #38 for future feature implementation

Update inline documentation:

• Ensure each new submodule has comprehensive module-level docs
• Add cross-references between related modules (e.g., offset.rs referencing offset_indirect.rs)
• Document the placeholder nature of unimplemented functions
• Add examples showing how the modules will be used once features are implemented

Module Organization Diagram

evaluator/
├── mod.rs                    # Public API & Re-exports (< 200 lines)
├── engine.rs                 # Core evaluation logic (< 600 lines, from #58)
├── offset.rs                 # Absolute + FromEnd (< 500 lines)
├── offset_indirect.rs        # Indirect resolution placeholder (< 200 lines, #37)
├── offset_relative.rs        # Relative resolution placeholder (< 200 lines, #38)
├── operators.rs              # Equal, NotEqual, BitwiseAnd (< 600 lines)
├── comparison.rs             # >, <, >=, <= placeholder (< 300 lines, #34)
├── bitwise.rs                # XOR, NOT, Any-Value placeholder (< 300 lines, #35)
├── strength.rs               # Strength calculation (871 lines, unchanged)
└── types.rs                  # Type reading (1,502 lines, unchanged)

Acceptance Criteria

• All new submodule files created with appropriate module declarations
• Existing code redistributed into new submodules without duplication
• Public API unchanged (re-exports in place in mod.rs)
• All existing tests pass without modification
• Each file under 600 lines (except types.rs and strength.rs which are unchanged)
• Module-level documentation added to all new submodules
• No compilation warnings or errors
• cargo clippy passes without new warnings
• cargo fmt passes
• Documentation builds successfully with cargo doc --no-deps

Import In IDE

🤖 Prompt for AI Agents

## Observations

The evaluator module currently has 5 files totaling ~7,100 lines. The `file:src/evaluator/mod.rs` (2,636 lines) and `file:src/evaluator/operators.rs` (1,618 lines) are already oversized. The AST in `file:src/parser/ast.rs` already defines `Indirect` and `Relative` offset variants, plus the current operator set (Equal, NotEqual, BitwiseAnd, BitwiseAndMask). Future v0.2.0 features will add comparison operators (>, <, >=, <=) and bitwise XOR/NOT to the `Operator` enum, plus implementations for indirect/relative offset resolution. **Critical**: Issue #58 (splitting `mod.rs` into `mod.rs` + `engine.rs`) has not been completed yet, as evidenced by the absence of `file:src/evaluator/engine.rs`.

## Approach

Since this ticket is **blocked by #58**, the plan assumes #58 will be completed first, creating `file:src/evaluator/engine.rs` with core evaluation logic. The refactoring will use the **flat submodule structure** (first proposal in the ticket) rather than nested directories, as it's simpler and more idiomatic for Rust. Each new submodule will be created with appropriate module declarations, existing code will be redistributed, and public APIs will be preserved through re-exports in `file:src/evaluator/mod.rs`. The goal is to keep each file under 600 lines while maintaining all existing functionality and tests.

## Implementation Steps

### 1. Pre-requisite Verification

Verify that issue #58 has been completed:
- Confirm `file:src/evaluator/engine.rs` exists with core evaluation logic (`evaluate_single_rule`, `evaluate_rules`, `EvaluationContext`)
- Confirm `file:src/evaluator/mod.rs` has been reduced to public API re-exports and module declarations
- Ensure all existing tests still pass after the #58 split

### 2. Create Offset Submodules

**Create `file:src/evaluator/offset_indirect.rs`:**
- Add module documentation explaining indirect offset resolution (reading pointer values and dereferencing)
- Create placeholder function `resolve_indirect_offset(base_offset: i64, pointer_type: &TypeKind, adjustment: i64, endian: &Endianness, buffer: &[u8]) -> Result<usize, OffsetError>`
- Add comprehensive documentation referencing issue #37
- Include TODO comment: "Implementation pending for v0.2.0 (issue #37)"
- Add basic test structure with `#[ignore]` attribute for future implementation
- Keep file under 200 lines initially (will grow when #37 is implemented)

**Create `file:src/evaluator/offset_relative.rs`:**
- Add module documentation explaining relative offset resolution (offsets from previous match position)
- Create placeholder function `resolve_relative_offset(relative: i64, context: &EvaluationContext, buffer: &[u8]) -> Result<usize, OffsetError>`
- Add comprehensive documentation referencing issue #38
- Include TODO comment: "Implementation pending for v0.2.0 (issue #38)"
- Add basic test structure with `#[ignore]` attribute for future implementation
- Keep file under 200 lines initially (will grow when #38 is implemented)

**Update `file:src/evaluator/offset.rs`:**
- Keep existing `resolve_absolute_offset` function and all its tests
- Keep existing `OffsetError` enum definition
- Update `resolve_offset` dispatcher function to call new submodules:
  - For `OffsetSpec::Indirect`: call `offset_indirect::resolve_indirect_offset`
  - For `OffsetSpec::Relative`: call `offset_relative::resolve_relative_offset`
- Add module declarations: `mod offset_indirect;` and `mod offset_relative;`
- Add public re-exports if needed for external API compatibility
- Ensure file stays under 500 lines after modifications

### 3. Create Operator Submodules

**Create `file:src/evaluator/comparison.rs`:**
- Add module documentation explaining comparison operators for v0.2.0
- Create placeholder functions:
  - `apply_greater_than(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_less_than(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_greater_equal(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_less_equal(file_value: &Value, expected: &Value) -> Result<bool, String>`
- Add comprehensive documentation referencing issue #34
- Include TODO comment: "Implementation pending for v0.2.0 (issue #34)"
- Add basic test structure with `#[ignore]` attribute for future implementation
- Keep file under 300 lines initially (will grow significantly when #34 is implemented)

**Create `file:src/evaluator/bitwise.rs`:**
- Add module documentation explaining bitwise XOR, NOT, and any-value operators
- Create placeholder functions:
  - `apply_bitwise_xor(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_bitwise_not(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_any_value(file_value: &Value) -> Result<bool, String>`
- Add comprehensive documentation referencing issue #35
- Include TODO comment: "Implementation pending for v0.2.0 (issue #35)"
- Add basic test structure with `#[ignore]` attribute for future implementation
- Keep file under 300 lines initially (will grow when #35 is implemented)

**Update `file:src/evaluator/operators.rs`:**
- Keep existing functions: `apply_equal`, `apply_not_equal`, `apply_bitwise_and`, `apply_operator`
- Keep all existing tests (they should remain under 1,200 lines)
- Add module declarations: `mod comparison;` and `mod bitwise;`
- Update `apply_operator` dispatcher to prepare for future operators (add match arms with `unimplemented!()` for new operator variants when they're added to AST)
- Add public re-exports if needed for external API compatibility
- Target: reduce from 1,618 lines to under 600 lines by moving tests to separate test modules if needed

### 4. Update Module Structure

**Update `file:src/evaluator/mod.rs`:**
- Add module declarations for new submodules:
  ```rust
  mod offset_indirect;
  mod offset_relative;
  mod comparison;
  mod bitwise;
  ```
- Add public re-exports to maintain existing API:
  ```rust
  pub use offset::{resolve_offset, resolve_absolute_offset, OffsetError};
  pub use operators::{apply_operator, apply_equal, apply_not_equal, apply_bitwise_and};
  ```
- Ensure no breaking changes to public API
- Document the new module structure in module-level documentation
- Keep file under 200 lines (should already be small after #58 split)

### 5. Verification and Testing

**Run comprehensive test suite:**
- Execute `cargo test --package libmagic-rs --lib evaluator` to verify all existing tests pass
- Verify no compilation errors or warnings
- Check that all public APIs remain accessible from external modules

**Verify file sizes:**
- Confirm `file:src/evaluator/mod.rs` < 200 lines
- Confirm `file:src/evaluator/engine.rs` < 600 lines (from #58)
- Confirm `file:src/evaluator/offset.rs` < 500 lines
- Confirm `file:src/evaluator/offset_indirect.rs` < 200 lines
- Confirm `file:src/evaluator/offset_relative.rs` < 200 lines
- Confirm `file:src/evaluator/operators.rs` < 600 lines (may need test refactoring)
- Confirm `file:src/evaluator/comparison.rs` < 300 lines
- Confirm `file:src/evaluator/bitwise.rs` < 300 lines
- Confirm `file:src/evaluator/strength.rs` remains at 871 lines (unchanged)
- Confirm `file:src/evaluator/types.rs` remains at 1,502 lines (unchanged)

**Code quality checks:**
- Run `cargo clippy` to ensure no new warnings
- Run `cargo fmt` to ensure consistent formatting
- Verify documentation builds with `cargo doc --no-deps`
- Check that all new modules have proper module-level documentation

### 6. Documentation Updates

**Update `file:docs/src/evaluator.md` (if exists):**
- Document the new submodule structure
- Add section explaining the organization: offset modules, operator modules, supporting modules
- Include a module dependency diagram showing relationships
- Reference issues #34, #35, #37, #38 for future feature implementation

**Update inline documentation:**
- Ensure each new submodule has comprehensive module-level docs
- Add cross-references between related modules (e.g., `offset.rs` referencing `offset_indirect.rs`)
- Document the placeholder nature of unimplemented functions
- Add examples showing how the modules will be used once features are implemented

## Module Organization Diagram

```
evaluator/
├── mod.rs                    # Public API & Re-exports (< 200 lines)
├── engine.rs                 # Core evaluation logic (< 600 lines, from #58)
├── offset.rs                 # Absolute + FromEnd (< 500 lines)
├── offset_indirect.rs        # Indirect resolution placeholder (< 200 lines, #37)
├── offset_relative.rs        # Relative resolution placeholder (< 200 lines, #38)
├── operators.rs              # Equal, NotEqual, BitwiseAnd (< 600 lines)
├── comparison.rs             # >, <, >=, <= placeholder (< 300 lines, #34)
├── bitwise.rs                # XOR, NOT, Any-Value placeholder (< 300 lines, #35)
├── strength.rs               # Strength calculation (871 lines, unchanged)
└── types.rs                  # Type reading (1,502 lines, unchanged)
```

## Acceptance Criteria

- [ ] All new submodule files created with appropriate module declarations
- [ ] Existing code redistributed into new submodules without duplication
- [ ] Public API unchanged (re-exports in place in `mod.rs`)
- [ ] All existing tests pass without modification
- [ ] Each file under 600 lines (except `types.rs` and `strength.rs` which are unchanged)
- [ ] Module-level documentation added to all new submodules
- [ ] No compilation warnings or errors
- [ ] `cargo clippy` passes without new warnings
- [ ] `cargo fmt` passes
- [ ] Documentation builds successfully with `cargo doc --no-deps`

---

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.

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

The evaluator module currently has 5 files totaling ~7,100 lines. The file:src/evaluator/mod.rs (2,636 lines) and file:src/evaluator/operators.rs (1,618 lines) are already oversized. The AST in file:src/parser/ast.rs already defines Indirect and Relative offset variants, plus the current operator set (Equal, NotEqual, BitwiseAnd, BitwiseAndMask). Future v0.2.0 features will add comparison operators (>, <, >=, <=) and bitwise XOR/NOT to the Operator enum, plus implementations for indirect/relative offset resolution. Critical: Issue #58 (splitting mod.rs into mod.rs + engine.rs) has not been completed yet, as evidenced by the absence of file:src/evaluator/engine.rs.

Approach

Since this ticket is blocked by #58, the plan assumes #58 will be completed first, creating file:src/evaluator/engine.rs with core evaluation logic. The refactoring will use the flat submodule structure (first proposal in the ticket) rather than nested directories, as it's simpler and more idiomatic for Rust. Each new submodule will be created with appropriate module declarations, existing code will be redistributed, and public APIs will be preserved through re-exports in file:src/evaluator/mod.rs. The goal is to keep each file under 600 lines while maintaining all existing functionality and tests.

Implementation Steps

1. Pre-requisite Verification

Verify that issue #58 has been completed:

• Confirm file:src/evaluator/engine.rs exists with core evaluation logic (evaluate_single_rule, evaluate_rules, EvaluationContext)
• Confirm file:src/evaluator/mod.rs has been reduced to public API re-exports and module declarations
• Ensure all existing tests still pass after the docs: comprehensive documentation, security, and CI hardening #58 split

2. Create Offset Submodules

Create file:src/evaluator/offset_indirect.rs:

• Add module documentation explaining indirect offset resolution (reading pointer values and dereferencing)
• Create placeholder function resolve_indirect_offset(base_offset: i64, pointer_type: &TypeKind, adjustment: i64, endian: &Endianness, buffer: &[u8]) -> Result<usize, OffsetError>
• Add comprehensive documentation referencing issue Evaluator: implement indirect offset resolution #37
• Include TODO comment: "Implementation pending for v0.2.0 (issue Evaluator: implement indirect offset resolution #37)"
• Add basic test structure with #[ignore] attribute for future implementation
• Keep file under 200 lines initially (will grow when Evaluator: implement indirect offset resolution #37 is implemented)

Create file:src/evaluator/offset_relative.rs:

• Add module documentation explaining relative offset resolution (offsets from previous match position)
• Create placeholder function resolve_relative_offset(relative: i64, context: &EvaluationContext, buffer: &[u8]) -> Result<usize, OffsetError>
• Add comprehensive documentation referencing issue Evaluator: implement relative offset resolution #38
• Include TODO comment: "Implementation pending for v0.2.0 (issue Evaluator: implement relative offset resolution #38)"
• Add basic test structure with #[ignore] attribute for future implementation
• Keep file under 200 lines initially (will grow when Evaluator: implement relative offset resolution #38 is implemented)

Update file:src/evaluator/offset.rs:

• Keep existing resolve_absolute_offset function and all its tests
• Keep existing OffsetError enum definition
• Update resolve_offset dispatcher function to call new submodules:
  • For OffsetSpec::Indirect: call offset_indirect::resolve_indirect_offset
  • For OffsetSpec::Relative: call offset_relative::resolve_relative_offset
• Add module declarations: mod offset_indirect; and mod offset_relative;
• Add public re-exports if needed for external API compatibility
• Ensure file stays under 500 lines after modifications

3. Create Operator Submodules

Create file:src/evaluator/comparison.rs:

• Add module documentation explaining comparison operators for v0.2.0
• Create placeholder functions:
  • apply_greater_than(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_less_than(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_greater_equal(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_less_equal(file_value: &Value, expected: &Value) -> Result<bool, String>
• Add comprehensive documentation referencing issue Parser: implement comparison operators (<, >, <=, >=) #34
• Include TODO comment: "Implementation pending for v0.2.0 (issue Parser: implement comparison operators (<, >, <=, >=) #34)"
• Add basic test structure with #[ignore] attribute for future implementation
• Keep file under 300 lines initially (will grow significantly when Parser: implement comparison operators (<, >, <=, >=) #34 is implemented)

Create file:src/evaluator/bitwise.rs:

• Add module documentation explaining bitwise XOR, NOT, and any-value operators
• Create placeholder functions:
  • apply_bitwise_xor(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_bitwise_not(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_any_value(file_value: &Value) -> Result<bool, String>
• Add comprehensive documentation referencing issue Parser: implement bitwise XOR (^), NOT (~), and any-value (x) operators #35
• Include TODO comment: "Implementation pending for v0.2.0 (issue Parser: implement bitwise XOR (^), NOT (~), and any-value (x) operators #35)"
• Add basic test structure with #[ignore] attribute for future implementation
• Keep file under 300 lines initially (will grow when Parser: implement bitwise XOR (^), NOT (~), and any-value (x) operators #35 is implemented)

Update file:src/evaluator/operators.rs:

• Keep existing functions: apply_equal, apply_not_equal, apply_bitwise_and, apply_operator
• Keep all existing tests (they should remain under 1,200 lines)
• Add module declarations: mod comparison; and mod bitwise;
• Update apply_operator dispatcher to prepare for future operators (add match arms with unimplemented!() for new operator variants when they're added to AST)
• Add public re-exports if needed for external API compatibility
• Target: reduce from 1,618 lines to under 600 lines by moving tests to separate test modules if needed

4. Update Module Structure

Update file:src/evaluator/mod.rs:

• Add module declarations for new submodules:

  mod offset_indirect;
  mod offset_relative;
  mod comparison;
  mod bitwise;

• Add public re-exports to maintain existing API:

  pub use offset::{resolve_offset, resolve_absolute_offset, OffsetError};
  pub use operators::{apply_operator, apply_equal, apply_not_equal, apply_bitwise_and};

• Ensure no breaking changes to public API
• Document the new module structure in module-level documentation
• Keep file under 200 lines (should already be small after docs: comprehensive documentation, security, and CI hardening #58 split)

5. Verification and Testing

Run comprehensive test suite:

• Execute cargo test --package libmagic-rs --lib evaluator to verify all existing tests pass
• Verify no compilation errors or warnings
• Check that all public APIs remain accessible from external modules

Verify file sizes:

• Confirm file:src/evaluator/mod.rs < 200 lines
• Confirm file:src/evaluator/engine.rs < 600 lines (from docs: comprehensive documentation, security, and CI hardening #58)
• Confirm file:src/evaluator/offset.rs < 500 lines
• Confirm file:src/evaluator/offset_indirect.rs < 200 lines
• Confirm file:src/evaluator/offset_relative.rs < 200 lines
• Confirm file:src/evaluator/operators.rs < 600 lines (may need test refactoring)
• Confirm file:src/evaluator/comparison.rs < 300 lines
• Confirm file:src/evaluator/bitwise.rs < 300 lines
• Confirm file:src/evaluator/strength.rs remains at 871 lines (unchanged)
• Confirm file:src/evaluator/types.rs remains at 1,502 lines (unchanged)

Code quality checks:

• Run cargo clippy to ensure no new warnings
• Run cargo fmt to ensure consistent formatting
• Verify documentation builds with cargo doc --no-deps
• Check that all new modules have proper module-level documentation

6. Documentation Updates

Update file:docs/src/evaluator.md (if exists):

• Document the new submodule structure
• Add section explaining the organization: offset modules, operator modules, supporting modules
• Include a module dependency diagram showing relationships
• Reference issues Parser: implement comparison operators (<, >, <=, >=) #34, Parser: implement bitwise XOR (^), NOT (~), and any-value (x) operators #35, Evaluator: implement indirect offset resolution #37, Evaluator: implement relative offset resolution #38 for future feature implementation

Update inline documentation:

• Ensure each new submodule has comprehensive module-level docs
• Add cross-references between related modules (e.g., offset.rs referencing offset_indirect.rs)
• Document the placeholder nature of unimplemented functions
• Add examples showing how the modules will be used once features are implemented

Module Organization Diagram

graph TD
    A[evaluator/mod.rs<br/>Public API & Re-exports] --> B[evaluator/engine.rs<br/>Core Evaluation Logic]
    A --> C[evaluator/offset.rs<br/>Absolute + FromEnd]
    A --> D[evaluator/offset_indirect.rs<br/>Indirect Resolution #37]
    A --> E[evaluator/offset_relative.rs<br/>Relative Resolution #38]
    A --> F[evaluator/operators.rs<br/>Equal, NotEqual, BitwiseAnd]
    A --> G[evaluator/comparison.rs<br/>>, <, >=, <= #34]
    A --> H[evaluator/bitwise.rs<br/>XOR, NOT, Any-Value #35]
    A --> I[evaluator/strength.rs<br/>Strength Calculation]
    A --> J[evaluator/types.rs<br/>Type Reading]
    
    B --> C
    B --> D
    B --> E
    B --> F
    B --> G
    B --> H
    B --> J
    
    style D fill:#f9f,stroke:#333,stroke-width:2px
    style E fill:#f9f,stroke:#333,stroke-width:2px
    style G fill:#f9f,stroke:#333,stroke-width:2px
    style H fill:#f9f,stroke:#333,stroke-width:2px

Loading

Note: Pink modules are placeholders for v0.2.0 features

Import In IDE

🤖 Prompt for AI Agents

## Observations

The evaluator module currently has 5 files totaling ~7,100 lines. The `file:src/evaluator/mod.rs` (2,636 lines) and `file:src/evaluator/operators.rs` (1,618 lines) are already oversized. The AST in `file:src/parser/ast.rs` already defines `Indirect` and `Relative` offset variants, plus the current operator set (Equal, NotEqual, BitwiseAnd, BitwiseAndMask). Future v0.2.0 features will add comparison operators (>, <, >=, <=) and bitwise XOR/NOT to the `Operator` enum, plus implementations for indirect/relative offset resolution. **Critical**: Issue #58 (splitting `mod.rs` into `mod.rs` + `engine.rs`) has not been completed yet, as evidenced by the absence of `file:src/evaluator/engine.rs`.

## Approach

Since this ticket is **blocked by #58**, the plan assumes #58 will be completed first, creating `file:src/evaluator/engine.rs` with core evaluation logic. The refactoring will use the **flat submodule structure** (first proposal in the ticket) rather than nested directories, as it's simpler and more idiomatic for Rust. Each new submodule will be created with appropriate module declarations, existing code will be redistributed, and public APIs will be preserved through re-exports in `file:src/evaluator/mod.rs`. The goal is to keep each file under 600 lines while maintaining all existing functionality and tests.

## Implementation Steps

### 1. Pre-requisite Verification

Verify that issue #58 has been completed:
- Confirm `file:src/evaluator/engine.rs` exists with core evaluation logic (`evaluate_single_rule`, `evaluate_rules`, `EvaluationContext`)
- Confirm `file:src/evaluator/mod.rs` has been reduced to public API re-exports and module declarations
- Ensure all existing tests still pass after the #58 split

### 2. Create Offset Submodules

**Create `file:src/evaluator/offset_indirect.rs`:**
- Add module documentation explaining indirect offset resolution (reading pointer values and dereferencing)
- Create placeholder function `resolve_indirect_offset(base_offset: i64, pointer_type: &TypeKind, adjustment: i64, endian: &Endianness, buffer: &[u8]) -> Result<usize, OffsetError>`
- Add comprehensive documentation referencing issue #37
- Include TODO comment: "Implementation pending for v0.2.0 (issue #37)"
- Add basic test structure with `#[ignore]` attribute for future implementation
- Keep file under 200 lines initially (will grow when #37 is implemented)

**Create `file:src/evaluator/offset_relative.rs`:**
- Add module documentation explaining relative offset resolution (offsets from previous match position)
- Create placeholder function `resolve_relative_offset(relative: i64, context: &EvaluationContext, buffer: &[u8]) -> Result<usize, OffsetError>`
- Add comprehensive documentation referencing issue #38
- Include TODO comment: "Implementation pending for v0.2.0 (issue #38)"
- Add basic test structure with `#[ignore]` attribute for future implementation
- Keep file under 200 lines initially (will grow when #38 is implemented)

**Update `file:src/evaluator/offset.rs`:**
- Keep existing `resolve_absolute_offset` function and all its tests
- Keep existing `OffsetError` enum definition
- Update `resolve_offset` dispatcher function to call new submodules:
  - For `OffsetSpec::Indirect`: call `offset_indirect::resolve_indirect_offset`
  - For `OffsetSpec::Relative`: call `offset_relative::resolve_relative_offset`
- Add module declarations: `mod offset_indirect;` and `mod offset_relative;`
- Add public re-exports if needed for external API compatibility
- Ensure file stays under 500 lines after modifications

### 3. Create Operator Submodules

**Create `file:src/evaluator/comparison.rs`:**
- Add module documentation explaining comparison operators for v0.2.0
- Create placeholder functions:
  - `apply_greater_than(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_less_than(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_greater_equal(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_less_equal(file_value: &Value, expected: &Value) -> Result<bool, String>`
- Add comprehensive documentation referencing issue #34
- Include TODO comment: "Implementation pending for v0.2.0 (issue #34)"
- Add basic test structure with `#[ignore]` attribute for future implementation
- Keep file under 300 lines initially (will grow significantly when #34 is implemented)

**Create `file:src/evaluator/bitwise.rs`:**
- Add module documentation explaining bitwise XOR, NOT, and any-value operators
- Create placeholder functions:
  - `apply_bitwise_xor(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_bitwise_not(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_any_value(file_value: &Value) -> Result<bool, String>`
- Add comprehensive documentation referencing issue #35
- Include TODO comment: "Implementation pending for v0.2.0 (issue #35)"
- Add basic test structure with `#[ignore]` attribute for future implementation
- Keep file under 300 lines initially (will grow when #35 is implemented)

**Update `file:src/evaluator/operators.rs`:**
- Keep existing functions: `apply_equal`, `apply_not_equal`, `apply_bitwise_and`, `apply_operator`
- Keep all existing tests (they should remain under 1,200 lines)
- Add module declarations: `mod comparison;` and `mod bitwise;`
- Update `apply_operator` dispatcher to prepare for future operators (add match arms with `unimplemented!()` for new operator variants when they're added to AST)
- Add public re-exports if needed for external API compatibility
- Target: reduce from 1,618 lines to under 600 lines by moving tests to separate test modules if needed

### 4. Update Module Structure

**Update `file:src/evaluator/mod.rs`:**
- Add module declarations for new submodules:
  ```rust
  mod offset_indirect;
  mod offset_relative;
  mod comparison;
  mod bitwise;
  ```
- Add public re-exports to maintain existing API:
  ```rust
  pub use offset::{resolve_offset, resolve_absolute_offset, OffsetError};
  pub use operators::{apply_operator, apply_equal, apply_not_equal, apply_bitwise_and};
  ```
- Ensure no breaking changes to public API
- Document the new module structure in module-level documentation
- Keep file under 200 lines (should already be small after #58 split)

### 5. Verification and Testing

**Run comprehensive test suite:**
- Execute `cargo test --package libmagic-rs --lib evaluator` to verify all existing tests pass
- Verify no compilation errors or warnings
- Check that all public APIs remain accessible from external modules

**Verify file sizes:**
- Confirm `file:src/evaluator/mod.rs` < 200 lines
- Confirm `file:src/evaluator/engine.rs` < 600 lines (from #58)
- Confirm `file:src/evaluator/offset.rs` < 500 lines
- Confirm `file:src/evaluator/offset_indirect.rs` < 200 lines
- Confirm `file:src/evaluator/offset_relative.rs` < 200 lines
- Confirm `file:src/evaluator/operators.rs` < 600 lines (may need test refactoring)
- Confirm `file:src/evaluator/comparison.rs` < 300 lines
- Confirm `file:src/evaluator/bitwise.rs` < 300 lines
- Confirm `file:src/evaluator/strength.rs` remains at 871 lines (unchanged)
- Confirm `file:src/evaluator/types.rs` remains at 1,502 lines (unchanged)

**Code quality checks:**
- Run `cargo clippy` to ensure no new warnings
- Run `cargo fmt` to ensure consistent formatting
- Verify documentation builds with `cargo doc --no-deps`
- Check that all new modules have proper module-level documentation

### 6. Documentation Updates

**Update `file:docs/src/evaluator.md` (if exists):**
- Document the new submodule structure
- Add section explaining the organization: offset modules, operator modules, supporting modules
- Include a module dependency diagram showing relationships
- Reference issues #34, #35, #37, #38 for future feature implementation

**Update inline documentation:**
- Ensure each new submodule has comprehensive module-level docs
- Add cross-references between related modules (e.g., `offset.rs` referencing `offset_indirect.rs`)
- Document the placeholder nature of unimplemented functions
- Add examples showing how the modules will be used once features are implemented

## Module Organization Diagram

```mermaid
graph TD
    A[evaluator/mod.rs<br/>Public API & Re-exports] --> B[evaluator/engine.rs<br/>Core Evaluation Logic]
    A --> C[evaluator/offset.rs<br/>Absolute + FromEnd]
    A --> D[evaluator/offset_indirect.rs<br/>Indirect Resolution #37]
    A --> E[evaluator/offset_relative.rs<br/>Relative Resolution #38]
    A --> F[evaluator/operators.rs<br/>Equal, NotEqual, BitwiseAnd]
    A --> G[evaluator/comparison.rs<br/>>, <, >=, <= #34]
    A --> H[evaluator/bitwise.rs<br/>XOR, NOT, Any-Value #35]
    A --> I[evaluator/strength.rs<br/>Strength Calculation]
    A --> J[evaluator/types.rs<br/>Type Reading]
    
    B --> C
    B --> D
    B --> E
    B --> F
    B --> G
    B --> H
    B --> J
    
    style D fill:#f9f,stroke:#333,stroke-width:2px
    style E fill:#f9f,stroke:#333,stroke-width:2px
    style G fill:#f9f,stroke:#333,stroke-width:2px
    style H fill:#f9f,stroke:#333,stroke-width:2px
```

*Note: Pink modules are placeholders for v0.2.0 features*

---

Execution Information

Branch: main
Commit: 36adac5

New Plan

Observations

The evaluator module currently has 5 files totaling ~7,100 lines. The file:src/evaluator/mod.rs (2,636 lines) and file:src/evaluator/operators.rs (1,618 lines) are already oversized. The AST in file:src/parser/ast.rs already defines Indirect and Relative offset variants, plus the current operator set (Equal, NotEqual, BitwiseAnd, BitwiseAndMask). Future v0.2.0 features will add comparison operators (>, <, >=, <=) and bitwise XOR/NOT to the Operator enum, plus implementations for indirect/relative offset resolution. Critical: Issue #58 (splitting mod.rs into mod.rs + engine.rs) has not been completed yet, as evidenced by the absence of file:src/evaluator/engine.rs.

Approach

Since this ticket is blocked by #58, the plan assumes #58 will be completed first, creating file:src/evaluator/engine.rs with core evaluation logic. The refactoring will use the flat submodule structure (first proposal in the ticket) rather than nested directories, as it's simpler and more idiomatic for Rust. Each new submodule will be created with appropriate module declarations, existing code will be redistributed, and public APIs will be preserved through re-exports in file:src/evaluator/mod.rs. The goal is to keep each file under 600 lines while maintaining all existing functionality and tests.

Implementation Steps

1. Pre-requisite Verification

Verify that issue #58 has been completed:

• Confirm file:src/evaluator/engine.rs exists with core evaluation logic (evaluate_single_rule, evaluate_rules, EvaluationContext)
• Confirm file:src/evaluator/mod.rs has been reduced to public API re-exports and module declarations
• Ensure all existing tests still pass after the docs: comprehensive documentation, security, and CI hardening #58 split

2. Create Offset Submodules

Create file:src/evaluator/offset_indirect.rs:

• Add module documentation explaining indirect offset resolution (reading pointer values and dereferencing)
• Create placeholder function resolve_indirect_offset(base_offset: i64, pointer_type: &TypeKind, adjustment: i64, endian: &Endianness, buffer: &[u8]) -> Result<usize, OffsetError>
• Add comprehensive documentation referencing issue Evaluator: implement indirect offset resolution #37
• Include TODO comment: "Implementation pending for v0.2.0 (issue Evaluator: implement indirect offset resolution #37)"
• Add basic test structure with #[ignore] attribute for future implementation
• Keep file under 200 lines initially (will grow when Evaluator: implement indirect offset resolution #37 is implemented)

Create file:src/evaluator/offset_relative.rs:

• Add module documentation explaining relative offset resolution (offsets from previous match position)
• Create placeholder function resolve_relative_offset(relative: i64, context: &EvaluationContext, buffer: &[u8]) -> Result<usize, OffsetError>
• Add comprehensive documentation referencing issue Evaluator: implement relative offset resolution #38
• Include TODO comment: "Implementation pending for v0.2.0 (issue Evaluator: implement relative offset resolution #38)"
• Add basic test structure with #[ignore] attribute for future implementation
• Keep file under 200 lines initially (will grow when Evaluator: implement relative offset resolution #38 is implemented)

Update file:src/evaluator/offset.rs:

• Keep existing resolve_absolute_offset function and all its tests
• Keep existing OffsetError enum definition
• Update resolve_offset dispatcher function to call new submodules:
  • For OffsetSpec::Indirect: call offset_indirect::resolve_indirect_offset
  • For OffsetSpec::Relative: call offset_relative::resolve_relative_offset
• Add module declarations: mod offset_indirect; and mod offset_relative;
• Add public re-exports if needed for external API compatibility
• Ensure file stays under 500 lines after modifications

3. Create Operator Submodules

Create file:src/evaluator/comparison.rs:

• Add module documentation explaining comparison operators for v0.2.0
• Create placeholder functions:
  • apply_greater_than(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_less_than(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_greater_equal(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_less_equal(file_value: &Value, expected: &Value) -> Result<bool, String>
• Add comprehensive documentation referencing issue Parser: implement comparison operators (<, >, <=, >=) #34
• Include TODO comment: "Implementation pending for v0.2.0 (issue Parser: implement comparison operators (<, >, <=, >=) #34)"
• Add basic test structure with #[ignore] attribute for future implementation
• Keep file under 300 lines initially (will grow significantly when Parser: implement comparison operators (<, >, <=, >=) #34 is implemented)

Create file:src/evaluator/bitwise.rs:

• Add module documentation explaining bitwise XOR, NOT, and any-value operators
• Create placeholder functions:
  • apply_bitwise_xor(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_bitwise_not(file_value: &Value, expected: &Value) -> Result<bool, String>
  • apply_any_value(file_value: &Value) -> Result<bool, String>
• Add comprehensive documentation referencing issue Parser: implement bitwise XOR (^), NOT (~), and any-value (x) operators #35
• Include TODO comment: "Implementation pending for v0.2.0 (issue Parser: implement bitwise XOR (^), NOT (~), and any-value (x) operators #35)"
• Add basic test structure with #[ignore] attribute for future implementation
• Keep file under 300 lines initially (will grow when Parser: implement bitwise XOR (^), NOT (~), and any-value (x) operators #35 is implemented)

Update file:src/evaluator/operators.rs:

• Keep existing functions: apply_equal, apply_not_equal, apply_bitwise_and, apply_operator
• Keep all existing tests (they should remain under 1,200 lines)
• Add module declarations: mod comparison; and mod bitwise;
• Update apply_operator dispatcher to prepare for future operators (add match arms with unimplemented!() for new operator variants when they're added to AST)
• Add public re-exports if needed for external API compatibility
• Target: reduce from 1,618 lines to under 600 lines by moving tests to separate test modules if needed

4. Update Module Structure

Update file:src/evaluator/mod.rs:

• Add module declarations for new submodules:

  mod offset_indirect;
  mod offset_relative;
  mod comparison;
  mod bitwise;

• Add public re-exports to maintain existing API:

  pub use offset::{resolve_offset, resolve_absolute_offset, OffsetError};
  pub use operators::{apply_operator, apply_equal, apply_not_equal, apply_bitwise_and};

• Ensure no breaking changes to public API
• Document the new module structure in module-level documentation
• Keep file under 200 lines (should already be small after docs: comprehensive documentation, security, and CI hardening #58 split)

5. Verification and Testing

Run comprehensive test suite:

• Execute cargo test --package libmagic-rs --lib evaluator to verify all existing tests pass
• Verify no compilation errors or warnings
• Check that all public APIs remain accessible from external modules

Verify file sizes:

• Confirm file:src/evaluator/mod.rs < 200 lines
• Confirm file:src/evaluator/engine.rs < 600 lines (from docs: comprehensive documentation, security, and CI hardening #58)
• Confirm file:src/evaluator/offset.rs < 500 lines
• Confirm file:src/evaluator/offset_indirect.rs < 200 lines
• Confirm file:src/evaluator/offset_relative.rs < 200 lines
• Confirm file:src/evaluator/operators.rs < 600 lines (may need test refactoring)
• Confirm file:src/evaluator/comparison.rs < 300 lines
• Confirm file:src/evaluator/bitwise.rs < 300 lines
• Confirm file:src/evaluator/strength.rs remains at 871 lines (unchanged)
• Confirm file:src/evaluator/types.rs remains at 1,502 lines (unchanged)

Code quality checks:

• Run cargo clippy to ensure no new warnings
• Run cargo fmt to ensure consistent formatting
• Verify documentation builds with cargo doc --no-deps
• Check that all new modules have proper module-level documentation

6. Documentation Updates

Update file:docs/src/evaluator.md (if exists):

• Document the new submodule structure
• Add section explaining the organization: offset modules, operator modules, supporting modules
• Include a module dependency diagram showing relationships
• Reference issues Parser: implement comparison operators (<, >, <=, >=) #34, Parser: implement bitwise XOR (^), NOT (~), and any-value (x) operators #35, Evaluator: implement indirect offset resolution #37, Evaluator: implement relative offset resolution #38 for future feature implementation

Update inline documentation:

• Ensure each new submodule has comprehensive module-level docs
• Add cross-references between related modules (e.g., offset.rs referencing offset_indirect.rs)
• Document the placeholder nature of unimplemented functions
• Add examples showing how the modules will be used once features are implemented

Module Organization Diagram

evaluator/
├── mod.rs                    # Public API & Re-exports (< 200 lines)
├── engine.rs                 # Core evaluation logic (< 600 lines, from #58)
├── offset.rs                 # Absolute + FromEnd (< 500 lines)
├── offset_indirect.rs        # Indirect resolution placeholder (< 200 lines, #37)
├── offset_relative.rs        # Relative resolution placeholder (< 200 lines, #38)
├── operators.rs              # Equal, NotEqual, BitwiseAnd (< 600 lines)
├── comparison.rs             # >, <, >=, <= placeholder (< 300 lines, #34)
├── bitwise.rs                # XOR, NOT, Any-Value placeholder (< 300 lines, #35)
├── strength.rs               # Strength calculation (871 lines, unchanged)
└── types.rs                  # Type reading (1,502 lines, unchanged)

Acceptance Criteria

• All new submodule files created with appropriate module declarations
• Existing code redistributed into new submodules without duplication
• Public API unchanged (re-exports in place in mod.rs)
• All existing tests pass without modification
• Each file under 600 lines (except types.rs and strength.rs which are unchanged)
• Module-level documentation added to all new submodules
• No compilation warnings or errors
• cargo clippy passes without new warnings
• cargo fmt passes
• Documentation builds successfully with cargo doc --no-deps

Import In IDE

🤖 Prompt for AI Agents

## Observations

The evaluator module currently has 5 files totaling ~7,100 lines. The `file:src/evaluator/mod.rs` (2,636 lines) and `file:src/evaluator/operators.rs` (1,618 lines) are already oversized. The AST in `file:src/parser/ast.rs` already defines `Indirect` and `Relative` offset variants, plus the current operator set (Equal, NotEqual, BitwiseAnd, BitwiseAndMask). Future v0.2.0 features will add comparison operators (>, <, >=, <=) and bitwise XOR/NOT to the `Operator` enum, plus implementations for indirect/relative offset resolution. **Critical**: Issue #58 (splitting `mod.rs` into `mod.rs` + `engine.rs`) has not been completed yet, as evidenced by the absence of `file:src/evaluator/engine.rs`.

## Approach

Since this ticket is **blocked by #58**, the plan assumes #58 will be completed first, creating `file:src/evaluator/engine.rs` with core evaluation logic. The refactoring will use the **flat submodule structure** (first proposal in the ticket) rather than nested directories, as it's simpler and more idiomatic for Rust. Each new submodule will be created with appropriate module declarations, existing code will be redistributed, and public APIs will be preserved through re-exports in `file:src/evaluator/mod.rs`. The goal is to keep each file under 600 lines while maintaining all existing functionality and tests.

## Implementation Steps

### 1. Pre-requisite Verification

Verify that issue #58 has been completed:
- Confirm `file:src/evaluator/engine.rs` exists with core evaluation logic (`evaluate_single_rule`, `evaluate_rules`, `EvaluationContext`)
- Confirm `file:src/evaluator/mod.rs` has been reduced to public API re-exports and module declarations
- Ensure all existing tests still pass after the #58 split

### 2. Create Offset Submodules

**Create `file:src/evaluator/offset_indirect.rs`:**
- Add module documentation explaining indirect offset resolution (reading pointer values and dereferencing)
- Create placeholder function `resolve_indirect_offset(base_offset: i64, pointer_type: &TypeKind, adjustment: i64, endian: &Endianness, buffer: &[u8]) -> Result<usize, OffsetError>`
- Add comprehensive documentation referencing issue #37
- Include TODO comment: "Implementation pending for v0.2.0 (issue #37)"
- Add basic test structure with `#[ignore]` attribute for future implementation
- Keep file under 200 lines initially (will grow when #37 is implemented)

**Create `file:src/evaluator/offset_relative.rs`:**
- Add module documentation explaining relative offset resolution (offsets from previous match position)
- Create placeholder function `resolve_relative_offset(relative: i64, context: &EvaluationContext, buffer: &[u8]) -> Result<usize, OffsetError>`
- Add comprehensive documentation referencing issue #38
- Include TODO comment: "Implementation pending for v0.2.0 (issue #38)"
- Add basic test structure with `#[ignore]` attribute for future implementation
- Keep file under 200 lines initially (will grow when #38 is implemented)

**Update `file:src/evaluator/offset.rs`:**
- Keep existing `resolve_absolute_offset` function and all its tests
- Keep existing `OffsetError` enum definition
- Update `resolve_offset` dispatcher function to call new submodules:
  - For `OffsetSpec::Indirect`: call `offset_indirect::resolve_indirect_offset`
  - For `OffsetSpec::Relative`: call `offset_relative::resolve_relative_offset`
- Add module declarations: `mod offset_indirect;` and `mod offset_relative;`
- Add public re-exports if needed for external API compatibility
- Ensure file stays under 500 lines after modifications

### 3. Create Operator Submodules

**Create `file:src/evaluator/comparison.rs`:**
- Add module documentation explaining comparison operators for v0.2.0
- Create placeholder functions:
  - `apply_greater_than(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_less_than(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_greater_equal(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_less_equal(file_value: &Value, expected: &Value) -> Result<bool, String>`
- Add comprehensive documentation referencing issue #34
- Include TODO comment: "Implementation pending for v0.2.0 (issue #34)"
- Add basic test structure with `#[ignore]` attribute for future implementation
- Keep file under 300 lines initially (will grow significantly when #34 is implemented)

**Create `file:src/evaluator/bitwise.rs`:**
- Add module documentation explaining bitwise XOR, NOT, and any-value operators
- Create placeholder functions:
  - `apply_bitwise_xor(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_bitwise_not(file_value: &Value, expected: &Value) -> Result<bool, String>`
  - `apply_any_value(file_value: &Value) -> Result<bool, String>`
- Add comprehensive documentation referencing issue #35
- Include TODO comment: "Implementation pending for v0.2.0 (issue #35)"
- Add basic test structure with `#[ignore]` attribute for future implementation
- Keep file under 300 lines initially (will grow when #35 is implemented)

**Update `file:src/evaluator/operators.rs`:**
- Keep existing functions: `apply_equal`, `apply_not_equal`, `apply_bitwise_and`, `apply_operator`
- Keep all existing tests (they should remain under 1,200 lines)
- Add module declarations: `mod comparison;` and `mod bitwise;`
- Update `apply_operator` dispatcher to prepare for future operators (add match arms with `unimplemented!()` for new operator variants when they're added to AST)
- Add public re-exports if needed for external API compatibility
- Target: reduce from 1,618 lines to under 600 lines by moving tests to separate test modules if needed

### 4. Update Module Structure

**Update `file:src/evaluator/mod.rs`:**
- Add module declarations for new submodules:
  ```rust
  mod offset_indirect;
  mod offset_relative;
  mod comparison;
  mod bitwise;
  ```
- Add public re-exports to maintain existing API:
  ```rust
  pub use offset::{resolve_offset, resolve_absolute_offset, OffsetError};
  pub use operators::{apply_operator, apply_equal, apply_not_equal, apply_bitwise_and};
  ```
- Ensure no breaking changes to public API
- Document the new module structure in module-level documentation
- Keep file under 200 lines (should already be small after #58 split)

### 5. Verification and Testing

**Run comprehensive test suite:**
- Execute `cargo test --package libmagic-rs --lib evaluator` to verify all existing tests pass
- Verify no compilation errors or warnings
- Check that all public APIs remain accessible from external modules

**Verify file sizes:**
- Confirm `file:src/evaluator/mod.rs` < 200 lines
- Confirm `file:src/evaluator/engine.rs` < 600 lines (from #58)
- Confirm `file:src/evaluator/offset.rs` < 500 lines
- Confirm `file:src/evaluator/offset_indirect.rs` < 200 lines
- Confirm `file:src/evaluator/offset_relative.rs` < 200 lines
- Confirm `file:src/evaluator/operators.rs` < 600 lines (may need test refactoring)
- Confirm `file:src/evaluator/comparison.rs` < 300 lines
- Confirm `file:src/evaluator/bitwise.rs` < 300 lines
- Confirm `file:src/evaluator/strength.rs` remains at 871 lines (unchanged)
- Confirm `file:src/evaluator/types.rs` remains at 1,502 lines (unchanged)

**Code quality checks:**
- Run `cargo clippy` to ensure no new warnings
- Run `cargo fmt` to ensure consistent formatting
- Verify documentation builds with `cargo doc --no-deps`
- Check that all new modules have proper module-level documentation

### 6. Documentation Updates

**Update `file:docs/src/evaluator.md` (if exists):**
- Document the new submodule structure
- Add section explaining the organization: offset modules, operator modules, supporting modules
- Include a module dependency diagram showing relationships
- Reference issues #34, #35, #37, #38 for future feature implementation

**Update inline documentation:**
- Ensure each new submodule has comprehensive module-level docs
- Add cross-references between related modules (e.g., `offset.rs` referencing `offset_indirect.rs`)
- Document the placeholder nature of unimplemented functions
- Add examples showing how the modules will be used once features are implemented

## Module Organization Diagram

```
evaluator/
├── mod.rs                    # Public API & Re-exports (< 200 lines)
├── engine.rs                 # Core evaluation logic (< 600 lines, from #58)
├── offset.rs                 # Absolute + FromEnd (< 500 lines)
├── offset_indirect.rs        # Indirect resolution placeholder (< 200 lines, #37)
├── offset_relative.rs        # Relative resolution placeholder (< 200 lines, #38)
├── operators.rs              # Equal, NotEqual, BitwiseAnd (< 600 lines)
├── comparison.rs             # >, <, >=, <= placeholder (< 300 lines, #34)
├── bitwise.rs                # XOR, NOT, Any-Value placeholder (< 300 lines, #35)
├── strength.rs               # Strength calculation (871 lines, unchanged)
└── types.rs                  # Type reading (1,502 lines, unchanged)
```

## Acceptance Criteria

- [ ] All new submodule files created with appropriate module declarations
- [ ] Existing code redistributed into new submodules without duplication
- [ ] Public API unchanged (re-exports in place in `mod.rs`)
- [ ] All existing tests pass without modification
- [ ] Each file under 600 lines (except `types.rs` and `strength.rs` which are unchanged)
- [ ] Module-level documentation added to all new submodules
- [ ] No compilation warnings or errors
- [ ] `cargo clippy` passes without new warnings
- [ ] `cargo fmt` passes
- [ ] Documentation builds successfully with `cargo doc --no-deps`

---

Execution Information

Branch: main
Commit: 36adac5