Test infrastructure, compatibility tests, and architecture improvements

.claude/instincts/ast-derive-pattern.md

@@ -0,0 +1,45 @@
+---
+id: libmagic-rs-ast-derives
+trigger: "when creating new AST types or data structures"
+confidence: 0.9
+domain: rust-types
+source: local-repo-analysis
+---
+
+# AST Type Derive Pattern
+
+## Action
+
+When creating new data structures (especially AST nodes):
+
+1. Derive: `Debug, Clone, Serialize, Deserialize, PartialEq, Eq`
+2. Add rustdoc with `# Examples` section
+3. Use `#[non_exhaustive]` on public enums
+4. Document each field/variant with `///` comments
+5. Import `serde::{Serialize, Deserialize}` (not `serde_derive`)
+
+```rust
+use serde::{Deserialize, Serialize};
+
+/// Description of the type
+///
+/// # Examples
+///
+/// ```
+/// use libmagic_rs::parser::ast::MyType;
+/// let val = MyType::Variant(42);
+/// ```
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum MyType {
+    /// Description of variant
+    Variant(i64),
+}
+```
+
+## Evidence
+
+- All types in `src/parser/ast.rs` follow this exact pattern
+- 6 enum types and 1 struct type all derive the same 6 traits
+- Every public type has rustdoc examples
+- Every variant has `///` doc comments

.claude/instincts/build-script-testing.md

@@ -0,0 +1,26 @@
+---
+id: libmagic-rs-build-testing
+trigger: "when modifying build.rs or build-time logic"
+confidence: 0.85
+domain: rust-build
+source: local-repo-analysis
+---
+
+# Build Script Testing Pattern
+
+## Action
+
+Build scripts (`build.rs`) cannot import the crate being built. To test build logic:
+
+1. Extract build logic into `src/build_helpers.rs` with `#[cfg(any(test, doc))]`
+2. Keep `build.rs` minimal - it should only call functions from the helper module
+3. Write unit tests in `build_helpers.rs` to verify all code paths
+4. Test error cases (invalid magic files, malformed input)
+
+This ensures build-time failures produce clear error messages and are properly tested.
+
+## Evidence
+
+- `src/build_helpers.rs` exists with testable parsing and code generation
+- `build.rs` delegates to functions from `build_helpers`
+- Pattern documented in AGENTS.md as a project convention

.claude/instincts/co-change-awareness.md

@@ -0,0 +1,29 @@
+---
+id: libmagic-rs-co-change
+trigger: "when modifying core source files"
+confidence: 0.85
+domain: architecture
+source: local-repo-analysis
+---
+
+# Co-Change Awareness
+
+## Action
+
+When modifying these files, check if related files also need updates:
+
+| If you change... | Also check... |
+|-------------------|--------------|
+| `src/lib.rs` | `src/main.rs`, `src/parser/ast.rs`, tests |
+| `src/evaluator/mod.rs` | `src/lib.rs`, `src/main.rs`, tests |
+| `src/parser/ast.rs` | `src/lib.rs`, `src/parser/grammar.rs`, `src/evaluator/types.rs` |
+| `src/main.rs` | `tests/cli_integration_tests.rs` |
+| `Cargo.toml` | `src/lib.rs`, `src/main.rs` |
+| `src/parser/grammar.rs` | `src/parser/mod.rs`, `tests/parser_integration_tests.rs` |
+
+## Evidence
+
+- Analyzed 34 commits for file co-change frequency
+- `src/lib.rs` + `src/main.rs` changed together 8 times (100% of main.rs changes)
+- `src/evaluator/mod.rs` + `src/lib.rs` changed together 8 times
+- API types are re-exported through `src/lib.rs`, making it a hub file

.claude/instincts/conventional-commits.md

@@ -0,0 +1,39 @@
+---
+id: libmagic-rs-commits
+trigger: "when writing a commit message"
+confidence: 0.8
+domain: git
+source: local-repo-analysis
+---
+
+# Conventional Commits Format
+
+## Action
+
+Prefix commit messages with type:
+
+- `feat:` - New features (most common)
+- `fix:` - Bug fixes
+- `chore:` - Maintenance (deps, config)
+- `docs:` - Documentation changes
+- `test:` - Test additions/changes
+- `refactor:` - Code restructuring
+- `perf:` - Performance improvements
+- `ci:` - CI/CD changes
+
+Optional scope: `chore(deps):`, `chore(ci):`
+
+PR references: Include `(#N)` suffix when applicable.
+
+Examples from this repo:
+- `feat: implement comprehensive test infrastructure`
+- `feat: evaluation enhancements with confidence, MIME, tags, metadata (#29)`
+- `chore(deps): update dependencies in mise.toml for improved tooling`
+- `feat: built-in rules build time compilation fallback (#28)`
+
+## Evidence
+
+- Analyzed 34 commits
+- 77% follow conventional commit format
+- `feat:` is the most common type (30% of commits)
+- PR numbers consistently included as `(#N)` suffix

.claude/instincts/error-handling-pattern.md

@@ -0,0 +1,42 @@
+---
+id: libmagic-rs-error-handling
+trigger: "when adding new error types or handling errors"
+confidence: 0.9
+domain: rust-errors
+source: local-repo-analysis
+---
+
+# Error Handling with thiserror + Constructor Methods
+
+## Action
+
+When creating or extending error types:
+
+1. Use `thiserror::Error` derive macro
+2. Include contextual fields (line numbers, offsets, names)
+3. Add named constructor methods for each variant
+4. Mark constructors with `#[must_use]`
+5. Use `impl Into<String>` for string parameters
+6. Write unit tests that verify Display output
+
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum MyError {
+    #[error("Something failed at {location}: {reason}")]
+    SomethingFailed { location: usize, reason: String },
+}
+
+impl MyError {
+    #[must_use]
+    pub fn something_failed(location: usize, reason: impl Into<String>) -> Self {
+        Self::SomethingFailed { location, reason: reason.into() }
+    }
+}
+```
+
+## Evidence
+
+- `src/error.rs` defines 3 error enums with 20+ variants, all following this pattern
+- Every variant has a corresponding constructor method
+- All constructors use `impl Into<String>` and `#[must_use]`
+- Comprehensive tests verify Display formatting for each variant

.claude/instincts/just-task-runner.md

@@ -0,0 +1,35 @@
+---
+id: libmagic-rs-just-tasks
+trigger: "when running project commands or CI checks"
+confidence: 0.9
+domain: tooling
+source: local-repo-analysis
+---
+
+# Use just for Task Running
+
+## Action
+
+Use `just` (not raw cargo) for project tasks. Key commands:
+
+| Command | Purpose |
+|---------|---------|
+| `just ci-check` | Full CI parity check (run before committing) |
+| `just test` | Run tests with nextest |
+| `just lint-rust` | Clippy with `-D warnings` |
+| `just fmt` | Format Rust code |
+| `just coverage` | Generate LCOV coverage report |
+| `just coverage-report` | HTML coverage with browser open |
+| `just bench` | Run all benchmarks |
+| `just audit` | Security audit |
+| `just docs` | Build and serve documentation |
+| `just test-compatibility` | Test against original libmagic test suite |
+
+All commands use `mise exec --` prefix for tool version management.
+
+## Evidence
+
+- `justfile` has 50+ recipes organized into sections
+- All CI workflows use `just` commands
+- `mise.toml` manages tool versions (Rust, pre-commit, mdbook, etc.)
+- Cross-platform support with `[unix]`/`[windows]` annotations

.claude/instincts/strict-clippy-compliance.md

@@ -0,0 +1,30 @@
+---
+id: libmagic-rs-strict-clippy
+trigger: "when writing or modifying Rust code in this project"
+confidence: 0.95
+domain: rust-linting
+source: local-repo-analysis
+---
+
+# Strict Clippy Compliance
+
+## Action
+
+This project enforces extremely strict clippy settings. When writing code:
+
+- Never use `.unwrap()` - use `?`, `.ok()`, or match instead (clippy `unwrap_used = "deny"`)
+- Never use `panic!()` in library code (clippy `panic = "deny"`)
+- Never use `unsafe` code (workspace `unsafe_code = "forbid"`)
+- Never use direct indexing on slices/buffers - use `.get()` (clippy `indexing_slicing = "warn"`)
+- Never use `&str[n..]` - use `strip_prefix()`/`strip_suffix()` (clippy `string_slice = "warn"`)
+- Mark all constructors/getters with `#[must_use]`
+- Avoid `as` casts where possible (clippy `as_conversions = "warn"`)
+- No `dbg!()` macros (clippy `dbg_macro = "warn"`)
+- No `todo!()` macros (clippy `todo = "warn"`)
+
+## Evidence
+
+- Cargo.toml contains 80+ clippy lint configurations
+- `unsafe_code = "forbid"` and `unwrap_used = "deny"` are workspace-level
+- All 34 analyzed commits maintain zero-warning compliance
+- CI enforces `cargo clippy -- -D warnings`

.claude/instincts/testing-conventions.md

@@ -0,0 +1,39 @@
+---
+id: libmagic-rs-testing
+trigger: "when writing tests or adding new functionality"
+confidence: 0.9
+domain: testing
+source: local-repo-analysis
+---
+
+# Testing Conventions
+
+## Action
+
+Follow these testing patterns:
+
+1. **Unit tests**: Place in `#[cfg(test)] mod tests` within each source file
+2. **Integration tests**: Add to `tests/` directory with `_tests.rs` suffix
+3. **CLI tests**: Use `insta` snapshots in `tests/cli_integration_tests.rs`
+4. **Property tests**: Add to `tests/property_tests.rs` using `proptest`
+5. **Benchmarks**: Add to `benches/` using `criterion` with `harness = false`
+
+Run tests with:
+```bash
+cargo nextest run --workspace --no-capture   # Standard
+just ci-check                                 # Full CI parity
+just coverage                                 # With coverage
+```
+
+Test naming: `test_<module>_<behavior>` (e.g., `test_parse_error_display`)
+
+Coverage target: >85% with `cargo llvm-cov`
+
+## Evidence
+
+- 8 test files in `tests/` directory
+- 3 benchmark files in `benches/`
+- Every source file has inline `#[cfg(test)]` module
+- `insta` used for snapshot testing CLI output
+- `proptest` used for property-based testing
+- `criterion` used for benchmarks (not built-in bench)