refactor: convert evaluator/types.rs to a types/ directory module

[unclesp1d3r]

Summary

src/evaluator/types.rs is currently 1,504 lines and handles reading/interpreting byte, short, long, and string types. v0.3.0 will add regex (#39), float/double (#40), date/timestamp (#41), and pascal string (#43) types, which would push this file well past 2,500 lines.

Proposal

Convert evaluator/types.rs into a directory module:

evaluator/types/
├── mod.rs          # Public API: read_typed_value() dispatcher, TypeReadError
├── numeric.rs      # Byte, short, long reading (existing)
├── string.rs       # String reading (existing)
├── quad.rs         # 64-bit integer types (#36, v0.2.0)
├── float.rs        # Float/double types (#40, v0.3.0)
├── date.rs         # Date/timestamp types (#41, v0.3.0)
├── regex.rs        # Regex/search types (#39, v0.3.0)
└── pascal.rs       # Pascal string type (#43, v0.3.0)

The read_typed_value() function in mod.rs would dispatch to the appropriate submodule based on TypeKind.

Why This Matters

Each new type requires:

• Reading logic (byte interpretation, endianness handling)
• Comparison logic (how values are compared)
• Tests (typically 200-400 lines per type)

Without splitting, types.rs would grow to ~3,500-4,000 lines by v0.3.0 completion.

Timing

This should be done before v0.3.0 work starts. The quad type (#36, v0.2.0) can be added to the existing file since it follows the numeric pattern, but the directory conversion should happen before float/regex/date types are added.

Acceptance Criteria

• evaluator/types.rs converted to evaluator/types/ directory module
• Existing byte/short/long/string logic split into numeric.rs and string.rs
• TypeReadError and read_typed_value() remain in mod.rs
• Public API unchanged
• All tests pass
• Each file under 600 lines

[traycerai]

Plan

Observations

The file:src/evaluator/types.rs file currently contains ~1,504 lines handling byte, short, long, and string type reading with extensive tests. The TypeReadError enum and read_typed_value() dispatcher function serve as the public API, used by file:src/evaluator/mod.rs (line 307) and file:src/error.rs (line 200). The codebase follows a directory module pattern with mod.rs files (seen in file:src/parser/mod.rs and file:src/io/mod.rs), using re-exports to maintain clean public APIs.

Approach

Convert file:src/evaluator/types.rs into a directory module evaluator/types/ with separate files for numeric and string types, while preserving the existing public API through re-exports in mod.rs. This follows the established codebase pattern and prepares the structure for future type additions (quad, float, date, regex, pascal) without creating monolithic files. The split is based on logical type categories: numeric types (byte, short, long) share endianness handling, while string types have distinct null-termination logic.

Implementation Steps

1. Create Directory Structure

Create the new src/evaluator/types/ directory to replace the existing file:src/evaluator/types.rs file:

src/evaluator/types/
├── mod.rs          # Public API and dispatcher
├── numeric.rs      # Byte, short, long reading
└── string.rs       # String reading

2. Create mod.rs - Public API Module

File: file:src/evaluator/types/mod.rs

Purpose: Maintain the public API and serve as the entry point for the types module.

Contents:

• Import and re-export TypeReadError enum (currently at lines 14-30 in types.rs)
• Import numeric and string submodules
• Re-export public functions: read_byte, read_short, read_long, read_string
• Keep read_typed_value() dispatcher function (currently at lines 351-395 in types.rs)
• Add module documentation explaining the type reading system

Key re-exports to maintain:

pub use numeric::{read_byte, read_short, read_long};
pub use string::read_string;
pub use self::TypeReadError;

Dispatcher logic:

• Match on TypeKind variants from file:src/parser/ast.rs
• Delegate to appropriate submodule functions
• Return Result<Value, TypeReadError>

3. Create numeric.rs - Numeric Type Reading

File: file:src/evaluator/types/numeric.rs

Purpose: Handle all numeric type reading (byte, short, long) with endianness support.

Contents to migrate from types.rs:

• read_byte() function (lines 78-90)
• read_short() function (lines 117-180)
• read_long() function (lines 208-271)
• All related unit tests for these functions

Shared logic:

• Endianness handling (little-endian, big-endian, native)
• Signed/unsigned interpretation
• Bounds checking using TypeReadError::BufferOverrun

Imports needed:

• use crate::parser::ast::{Endianness, Value};
• use super::TypeReadError;

Expected line count: ~400-500 lines (including tests)

4. Create string.rs - String Type Reading

File: file:src/evaluator/types/string.rs

Purpose: Handle string type reading with null-termination and length limits.

Contents to migrate from types.rs:

• read_string() function (lines 279-342)
• All related unit tests for string reading

Key features:

• Null-terminated string reading
• Optional max_length parameter support
• UTF-8 validation and handling
• Bounds checking

Imports needed:

• use crate::parser::ast::Value;
• use super::TypeReadError;

Expected line count: ~200-300 lines (including tests)

5. Update Module Declaration

File: file:src/evaluator/mod.rs

Change: The existing declaration pub mod types; (line 20) remains unchanged. Rust automatically recognizes types/mod.rs as a module.

No changes needed - the module system will automatically use types/mod.rs instead of types.rs.

6. Verify Public API Compatibility

Ensure these imports continue to work:

From file:src/evaluator/mod.rs:

• types::read_typed_value(buffer, absolute_offset, &rule.typ) (line 307)

From file:src/error.rs:

• crate::evaluator::types::TypeReadError (line 200)

From documentation examples in types.rs:

• use libmagic_rs::evaluator::types::read_byte;
• use libmagic_rs::evaluator::types::read_short;
• use libmagic_rs::evaluator::types::read_long;
• use libmagic_rs::evaluator::types::read_string;
• use libmagic_rs::evaluator::types::read_typed_value;

7. Test Migration Strategy

Unit tests:

• Move byte/short/long tests to numeric.rs test module
• Move string tests to string.rs test module
• Keep integration tests for read_typed_value() in mod.rs

Test organization:

• Each submodule should have #[cfg(test)] mod tests { ... }
• Tests should remain co-located with their implementation
• Maintain existing test coverage (no tests should be lost)

8. Validation Checklist

After refactoring, verify:

• All existing tests pass: cargo test
• Public API unchanged: all re-exports work correctly
• Documentation builds: cargo doc --no-deps
• No compilation warnings introduced
• Each file under 600 lines (as per acceptance criteria)
• file:src/error.rs still imports TypeReadError correctly
• file:src/evaluator/mod.rs still calls types::read_typed_value() correctly

9. Future Extensibility

The new structure supports adding future types:

For quad type (#36, v0.2.0):

• Add read_quad() function to file:src/evaluator/types/numeric.rs
• Update dispatcher in file:src/evaluator/types/mod.rs
• Re-export from mod.rs

For float/double (#40, v0.3.0):

• Create file:src/evaluator/types/float.rs
• Add to mod.rs with appropriate re-exports

For date/timestamp (#41, v0.3.0):

• Create file:src/evaluator/types/date.rs
• Add to mod.rs with appropriate re-exports

For regex (#39, v0.3.0):

• Create file:src/evaluator/types/regex.rs
• Add to mod.rs with appropriate re-exports

For pascal string (#43, v0.3.0):

• Create file:src/evaluator/types/pascal.rs
• Add to mod.rs with appropriate re-exports

Module Dependency Diagram

graph TD
    A[src/evaluator/mod.rs] -->|uses| B[types::read_typed_value]
    B[types/mod.rs] -->|dispatches to| C[numeric.rs]
    B -->|dispatches to| D[string.rs]
    E[src/error.rs] -->|imports| F[types::TypeReadError]
    F -->|defined in| B
    C -->|uses| F
    D -->|uses| F
    G[src/parser/ast.rs] -->|provides| H[TypeKind, Value, Endianness]
    C -->|uses| H
    D -->|uses| H
    B -->|uses| H

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `file:src/evaluator/types.rs` file currently contains ~1,504 lines handling byte, short, long, and string type reading with extensive tests. The `TypeReadError` enum and `read_typed_value()` dispatcher function serve as the public API, used by `file:src/evaluator/mod.rs` (line 307) and `file:src/error.rs` (line 200). The codebase follows a directory module pattern with `mod.rs` files (seen in `file:src/parser/mod.rs` and `file:src/io/mod.rs`), using re-exports to maintain clean public APIs.

## Approach

Convert `file:src/evaluator/types.rs` into a directory module `evaluator/types/` with separate files for numeric and string types, while preserving the existing public API through re-exports in `mod.rs`. This follows the established codebase pattern and prepares the structure for future type additions (quad, float, date, regex, pascal) without creating monolithic files. The split is based on logical type categories: numeric types (byte, short, long) share endianness handling, while string types have distinct null-termination logic.

## Implementation Steps

### 1. Create Directory Structure

Create the new `src/evaluator/types/` directory to replace the existing `file:src/evaluator/types.rs` file:

```
src/evaluator/types/
├── mod.rs          # Public API and dispatcher
├── numeric.rs      # Byte, short, long reading
└── string.rs       # String reading
```

### 2. Create `mod.rs` - Public API Module

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

**Purpose:** Maintain the public API and serve as the entry point for the types module.

**Contents:**
- Import and re-export `TypeReadError` enum (currently at lines 14-30 in types.rs)
- Import numeric and string submodules
- Re-export public functions: `read_byte`, `read_short`, `read_long`, `read_string`
- Keep `read_typed_value()` dispatcher function (currently at lines 351-395 in types.rs)
- Add module documentation explaining the type reading system

**Key re-exports to maintain:**
```rust
pub use numeric::{read_byte, read_short, read_long};
pub use string::read_string;
pub use self::TypeReadError;
```

**Dispatcher logic:**
- Match on `TypeKind` variants from `file:src/parser/ast.rs`
- Delegate to appropriate submodule functions
- Return `Result<Value, TypeReadError>`

### 3. Create `numeric.rs` - Numeric Type Reading

**File:** `file:src/evaluator/types/numeric.rs`

**Purpose:** Handle all numeric type reading (byte, short, long) with endianness support.

**Contents to migrate from types.rs:**
- `read_byte()` function (lines 78-90)
- `read_short()` function (lines 117-180)
- `read_long()` function (lines 208-271)
- All related unit tests for these functions

**Shared logic:**
- Endianness handling (little-endian, big-endian, native)
- Signed/unsigned interpretation
- Bounds checking using `TypeReadError::BufferOverrun`

**Imports needed:**
- `use crate::parser::ast::{Endianness, Value};`
- `use super::TypeReadError;`

**Expected line count:** ~400-500 lines (including tests)

### 4. Create `string.rs` - String Type Reading

**File:** `file:src/evaluator/types/string.rs`

**Purpose:** Handle string type reading with null-termination and length limits.

**Contents to migrate from types.rs:**
- `read_string()` function (lines 279-342)
- All related unit tests for string reading

**Key features:**
- Null-terminated string reading
- Optional `max_length` parameter support
- UTF-8 validation and handling
- Bounds checking

**Imports needed:**
- `use crate::parser::ast::Value;`
- `use super::TypeReadError;`

**Expected line count:** ~200-300 lines (including tests)

### 5. Update Module Declaration

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

**Change:** The existing declaration `pub mod types;` (line 20) remains unchanged. Rust automatically recognizes `types/mod.rs` as a module.

**No changes needed** - the module system will automatically use `types/mod.rs` instead of `types.rs`.

### 6. Verify Public API Compatibility

**Ensure these imports continue to work:**

From `file:src/evaluator/mod.rs`:
- `types::read_typed_value(buffer, absolute_offset, &rule.typ)` (line 307)

From `file:src/error.rs`:
- `crate::evaluator::types::TypeReadError` (line 200)

From documentation examples in types.rs:
- `use libmagic_rs::evaluator::types::read_byte;`
- `use libmagic_rs::evaluator::types::read_short;`
- `use libmagic_rs::evaluator::types::read_long;`
- `use libmagic_rs::evaluator::types::read_string;`
- `use libmagic_rs::evaluator::types::read_typed_value;`

### 7. Test Migration Strategy

**Unit tests:**
- Move byte/short/long tests to `numeric.rs` test module
- Move string tests to `string.rs` test module
- Keep integration tests for `read_typed_value()` in `mod.rs`

**Test organization:**
- Each submodule should have `#[cfg(test)] mod tests { ... }`
- Tests should remain co-located with their implementation
- Maintain existing test coverage (no tests should be lost)

### 8. Validation Checklist

After refactoring, verify:

- [ ] All existing tests pass: `cargo test`
- [ ] Public API unchanged: all re-exports work correctly
- [ ] Documentation builds: `cargo doc --no-deps`
- [ ] No compilation warnings introduced
- [ ] Each file under 600 lines (as per acceptance criteria)
- [ ] `file:src/error.rs` still imports `TypeReadError` correctly
- [ ] `file:src/evaluator/mod.rs` still calls `types::read_typed_value()` correctly

### 9. Future Extensibility

The new structure supports adding future types:

**For quad type (#36, v0.2.0):**
- Add `read_quad()` function to `file:src/evaluator/types/numeric.rs`
- Update dispatcher in `file:src/evaluator/types/mod.rs`
- Re-export from `mod.rs`

**For float/double (#40, v0.3.0):**
- Create `file:src/evaluator/types/float.rs`
- Add to `mod.rs` with appropriate re-exports

**For date/timestamp (#41, v0.3.0):**
- Create `file:src/evaluator/types/date.rs`
- Add to `mod.rs` with appropriate re-exports

**For regex (#39, v0.3.0):**
- Create `file:src/evaluator/types/regex.rs`
- Add to `mod.rs` with appropriate re-exports

**For pascal string (#43, v0.3.0):**
- Create `file:src/evaluator/types/pascal.rs`
- Add to `mod.rs` with appropriate re-exports

## Module Dependency Diagram

```mermaid
graph TD
    A[src/evaluator/mod.rs] -->|uses| B[types::read_typed_value]
    B[types/mod.rs] -->|dispatches to| C[numeric.rs]
    B -->|dispatches to| D[string.rs]
    E[src/error.rs] -->|imports| F[types::TypeReadError]
    F -->|defined in| B
    C -->|uses| F
    D -->|uses| F
    G[src/parser/ast.rs] -->|provides| H[TypeKind, Value, Endianness]
    C -->|uses| H
    D -->|uses| H
    B -->|uses| H
```

---

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.