refactor: rename evaluator::MatchResult to disambiguate from output::MatchResult

[unclesp1d3r]

Summary

There are two distinct types named MatchResult in the codebase, causing confusion:

• evaluator::MatchResult -- Internal evaluation result with confidence: f64 (0.0-1.0)
• output::MatchResult -- Output-facing result with confidence: u8 (0-100), plus length, rule_path, mime_type

The naming collision requires context to understand which type is being used, and conversion between them involves a non-obvious confidence scale change (float to percentage).

Proposal

Rename evaluator::MatchResult to evaluator::RuleMatch (or evaluator::EvalMatch). This:

• Makes the purpose clear at a glance
• Eliminates the need for fully-qualified paths in code that uses both
• Follows the pattern of the type being an internal evaluation concept vs an output format

Affected Code

• src/evaluator/mod.rs -- Type definition and construction
• src/lib.rs -- Re-export (pub use evaluator::RuleMatch) and EvaluationResult.matches field type
• src/output/mod.rs -- Conversion from evaluator::RuleMatch to output::MatchResult
• Tests referencing the type

Acceptance Criteria

• evaluator::MatchResult renamed to evaluator::RuleMatch (or approved alternative)
• output::MatchResult unchanged
• All re-exports updated
• All tests pass
• No public API surface change beyond the rename

[traycerai]

Plan

Observations

The codebase has two distinct MatchResult types serving different purposes: evaluator::MatchResult (internal evaluation with f64 confidence 0.0-1.0) and output::MatchResult (output-facing with u8 confidence 0-100, plus additional metadata). The naming collision requires fully-qualified paths when both are used together. The conversion happens in output::MatchResult::from_evaluator_match() which scales confidence from float to percentage. The evaluator type is re-exported at crate root via file:src/lib.rs.

Approach

Rename evaluator::MatchResult to evaluator::RuleMatch to clearly distinguish it as an internal rule evaluation result. This eliminates ambiguity, removes the need for fully-qualified paths in mixed contexts, and makes the codebase more maintainable. The rename will cascade through re-exports, type annotations, method signatures, and documentation examples while preserving all functionality and public API behavior.

Implementation Steps

1. Rename Type Definition in Evaluator Module

File: file:src/evaluator/mod.rs

• Locate the struct definition at lines 205-220
• Rename pub struct MatchResult to pub struct RuleMatch
• Update the impl block at line 222: impl MatchResult → impl RuleMatch
• Update doc comment examples at lines 235-240 that reference use libmagic_rs::evaluator::MatchResult to use RuleMatch
• Update the calculate_confidence doc example to use RuleMatch::calculate_confidence

2. Update Re-exports in Library Root

File: file:src/lib.rs

• Line 129: Change pub use evaluator::{EvaluationContext, MatchResult}; to pub use evaluator::{EvaluationContext, RuleMatch};
• This makes libmagic_rs::RuleMatch the new public API name for the evaluator type

3. Update Type References in Library Root

File: file:src/lib.rs

• Line 836: Change pub matches: Vec<evaluator::MatchResult> to pub matches: Vec<evaluator::RuleMatch> in the EvaluationResult struct
• Line 655: Update method signature fn build_result(&self, matches: Vec<evaluator::MatchResult>, ...) to use Vec<evaluator::RuleMatch>
• Line 690: Update method signature fn concatenate_messages(matches: &[evaluator::MatchResult]) to use &[evaluator::RuleMatch]

4. Update Test Code in Library Root

File: file:src/lib.rs

• Lines 1216-1228: Change evaluator::MatchResult { ... } to evaluator::RuleMatch { ... } in test construction
• Lines 1239-1252: Change evaluator::MatchResult { ... } to evaluator::RuleMatch { ... } in test construction
• Search for any other test code that constructs or references the type

5. Update Conversion Method in Output Module

File: file:src/output/mod.rs

• Line 257-272: Update doc comment "Convert from an evaluator MatchResult" to "Convert from an evaluator RuleMatch"
• Line 269: Change parameter type m: &crate::evaluator::MatchResult to m: &crate::evaluator::RuleMatch
• Update any related comments that mention the evaluator type

6. Update Function Return Types in Evaluator Module

File: file:src/evaluator/mod.rs

• Review all functions that return Option<MatchResult> or Vec<MatchResult> and update to Option<RuleMatch> or Vec<RuleMatch>
• Key functions to check:
  • evaluate_single_rule (around line 247)
  • evaluate_rules (around line 312)
  • Any helper functions that construct or return the type

7. Verify No Breaking Changes to Public API

The rename should not break the public API surface beyond the type name change:

• output::MatchResult remains unchanged (this is the primary output type)
• The re-exported name changes from libmagic_rs::MatchResult to libmagic_rs::RuleMatch
• All field names, methods, and functionality remain identical
• The conversion logic in from_evaluator_match remains the same

8. Run All Tests

Execute the full test suite to ensure:

• All unit tests in file:src/evaluator/mod.rs pass (lines 530-2636)
• All unit tests in file:src/lib.rs pass (lines 841-1258)
• All unit tests in file:src/output/mod.rs pass (lines 693-1062)
• Integration tests in file:tests/ directory pass
• Doc tests compile and pass

9. Update Documentation

Ensure all documentation is consistent:

• Module-level docs in file:src/evaluator/mod.rs should reference RuleMatch where appropriate
• Any README or CHANGELOG entries should note the rename
• Verify that rustdoc examples compile correctly with the new name

Summary

This refactoring involves a straightforward find-and-replace operation across 3 main files (file:src/evaluator/mod.rs, file:src/lib.rs, file:src/output/mod.rs) with updates to type definitions, re-exports, method signatures, and test code. The change improves code clarity by eliminating naming ambiguity between internal evaluation results and output-facing results.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has two distinct `MatchResult` types serving different purposes: `evaluator::MatchResult` (internal evaluation with f64 confidence 0.0-1.0) and `output::MatchResult` (output-facing with u8 confidence 0-100, plus additional metadata). The naming collision requires fully-qualified paths when both are used together. The conversion happens in `output::MatchResult::from_evaluator_match()` which scales confidence from float to percentage. The evaluator type is re-exported at crate root via `file:src/lib.rs`.

## Approach

Rename `evaluator::MatchResult` to `evaluator::RuleMatch` to clearly distinguish it as an internal rule evaluation result. This eliminates ambiguity, removes the need for fully-qualified paths in mixed contexts, and makes the codebase more maintainable. The rename will cascade through re-exports, type annotations, method signatures, and documentation examples while preserving all functionality and public API behavior.

## Implementation Steps

### 1. Rename Type Definition in Evaluator Module

**File: `file:src/evaluator/mod.rs`**

- Locate the struct definition at lines 205-220
- Rename `pub struct MatchResult` to `pub struct RuleMatch`
- Update the impl block at line 222: `impl MatchResult` → `impl RuleMatch`
- Update doc comment examples at lines 235-240 that reference `use libmagic_rs::evaluator::MatchResult` to use `RuleMatch`
- Update the `calculate_confidence` doc example to use `RuleMatch::calculate_confidence`

### 2. Update Re-exports in Library Root

**File: `file:src/lib.rs`**

- Line 129: Change `pub use evaluator::{EvaluationContext, MatchResult};` to `pub use evaluator::{EvaluationContext, RuleMatch};`
- This makes `libmagic_rs::RuleMatch` the new public API name for the evaluator type

### 3. Update Type References in Library Root

**File: `file:src/lib.rs`**

- Line 836: Change `pub matches: Vec<evaluator::MatchResult>` to `pub matches: Vec<evaluator::RuleMatch>` in the `EvaluationResult` struct
- Line 655: Update method signature `fn build_result(&self, matches: Vec<evaluator::MatchResult>, ...)` to use `Vec<evaluator::RuleMatch>`
- Line 690: Update method signature `fn concatenate_messages(matches: &[evaluator::MatchResult])` to use `&[evaluator::RuleMatch]`

### 4. Update Test Code in Library Root

**File: `file:src/lib.rs`**

- Lines 1216-1228: Change `evaluator::MatchResult { ... }` to `evaluator::RuleMatch { ... }` in test construction
- Lines 1239-1252: Change `evaluator::MatchResult { ... }` to `evaluator::RuleMatch { ... }` in test construction
- Search for any other test code that constructs or references the type

### 5. Update Conversion Method in Output Module

**File: `file:src/output/mod.rs`**

- Line 257-272: Update doc comment "Convert from an evaluator `MatchResult`" to "Convert from an evaluator `RuleMatch`"
- Line 269: Change parameter type `m: &crate::evaluator::MatchResult` to `m: &crate::evaluator::RuleMatch`
- Update any related comments that mention the evaluator type

### 6. Update Function Return Types in Evaluator Module

**File: `file:src/evaluator/mod.rs`**

- Review all functions that return `Option<MatchResult>` or `Vec<MatchResult>` and update to `Option<RuleMatch>` or `Vec<RuleMatch>`
- Key functions to check:
  - `evaluate_single_rule` (around line 247)
  - `evaluate_rules` (around line 312)
  - Any helper functions that construct or return the type

### 7. Verify No Breaking Changes to Public API

The rename should not break the public API surface beyond the type name change:
- `output::MatchResult` remains unchanged (this is the primary output type)
- The re-exported name changes from `libmagic_rs::MatchResult` to `libmagic_rs::RuleMatch`
- All field names, methods, and functionality remain identical
- The conversion logic in `from_evaluator_match` remains the same

### 8. Run All Tests

Execute the full test suite to ensure:
- All unit tests in `file:src/evaluator/mod.rs` pass (lines 530-2636)
- All unit tests in `file:src/lib.rs` pass (lines 841-1258)
- All unit tests in `file:src/output/mod.rs` pass (lines 693-1062)
- Integration tests in `file:tests/` directory pass
- Doc tests compile and pass

### 9. Update Documentation

Ensure all documentation is consistent:
- Module-level docs in `file:src/evaluator/mod.rs` should reference `RuleMatch` where appropriate
- Any README or CHANGELOG entries should note the rename
- Verify that rustdoc examples compile correctly with the new name

## Summary

This refactoring involves a straightforward find-and-replace operation across 3 main files (`file:src/evaluator/mod.rs`, `file:src/lib.rs`, `file:src/output/mod.rs`) with updates to type definitions, re-exports, method signatures, and test code. The change improves code clarity by eliminating naming ambiguity between internal evaluation results and output-facing results.

---

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.