feat: strength calculation & documentation improvements (#21)

[unclesp1d3r]

Summary

• Implement strength calculation system for magic rules based on libmagic's apprentice_magic_strength algorithm
• Add comprehensive documentation with mdbook integration
• Update AGENTS.md with PR review learnings

Strength Calculation (Issue #21)

Adds a complete strength calculation system to prioritize more specific magic rules during evaluation:

• StrengthModifier enum: Add, Subtract, Multiply, Divide, Set operations
• !:strength directive parsing: Parse strength modifiers from magic files
• Default strength calculation: Based on type specificity, operator type, offset reliability, and value length
• Rule sorting: sort_rules_by_strength() for evaluation ordering
• Overflow protection: Safe arithmetic with clamping to [0, 255]
• 35 unit tests covering all strength calculation scenarios

Documentation Improvements

• Complete API reference (MagicDatabase, EvaluationConfig, AST types, error handling)
• Full CLI documentation (options, exit codes, magic file discovery)
• Comprehensive magic file format guide (offsets, types, operators, nested rules)
• Mermaid architecture diagrams
• Standalone quick reference documents

Files Changed

• src/evaluator/strength.rs (new) - Strength calculation module
• src/parser/grammar.rs - !:strength directive parsing
• src/parser/ast.rs - StrengthModifier enum
• build.rs, src/build_helpers.rs - Build script support
• docs/ - Comprehensive documentation updates

Test plan

• All 860 unit tests passing
• All 115 doc tests passing
• CI check suite passing
• Clippy with -D warnings passing
• cargo fmt verified

🤖 Generated with Claude Code

[coderabbitai]

Caution

Review failed

Failed to post review comments

Summary by CodeRabbit

• New Features

  • Strength modifier support to influence rule weighting during evaluations.
  • Extended per-project configuration: project_name, included_optional_tools, base_modes, default_modes, fixed_tools.

• Documentation

  • Major docs added and reorganized: comprehensive API reference, architecture guide, CLI reference, getting started, magic format, README, and multiple diagrams.

Walkthrough

Adds StrengthModifier (AST enum) and a new MagicRule field; parser support for !:strength directives; evaluator strength calculation and rule-sorting; build-time codegen/serialization for the new field; public re-exports; test/CI synchronization; new project config fields; extensive documentation additions.

Changes

Cohort / File(s)	Summary
Configuration & Project \.serena/project.yml	Added public project config fields: project_name, included_optional_tools, base_modes, default_modes, fixed_tools.
AST Types & Re-exports src/parser/ast.rs, src/lib.rs, src/parser/mod.rs	Add StrengthModifier enum and strength_modifier: Option<StrengthModifier> to MagicRule; re-export StrengthModifier via parser and crate root.
Parser Grammar & Preprocessing src/parser/grammar.rs, src/parser/mod.rs	Add parse_strength_directive() and is_strength_directive(); preprocessor recognizes !:strength directives, attaches modifier to LineInfo, and applies it to the next rule (modifier consumed; not inherited by children).
Evaluator: Strength Feature src/evaluator/mod.rs, src/evaluator/strength.rs	New strength module with constants, default-strength calculation, apply_strength_modifier, calculate_rule_strength, sorting helpers, and unit tests; evaluator integrates strength computation and sorts rules.
Build / Codegen build.rs, src/build_helpers.rs	Codegen imports/exports StrengthModifier; serialize strength_modifier via new helper; emit allow(unused_imports) for optional usage; build script rerun directive added; generated BUILTIN_RULES include strength_modifier.
Parser Tests & Initialization src/parser/*, src/evaluator/*	Updated tests and fixtures to initialize strength_modifier (commonly None); added parsing and behavior tests for strength directives and all modifier variants.
Docs / CLI / Guides docs/*, docs/src/*, docs/diagrams/*, AGENTS.md	Large documentation additions and rewrites (API reference, CLI reference, Getting Started, Architecture, Magic Format, diagrams); AGENTS.md adds Rust string handling and doc-test guidance.
CI & Test Helpers .github/workflows/ci.yml, src/main.rs	CI coverage step adds --test-threads=1; process-wide FD_MUTEX added to serialize FD operations in test helpers and skip certain stdin tests under LLVM profiling.
Build Artifacts / Generated Rules BUILTIN_RULES (generated code), build_helpers outputs	Generated MagicRule instances now include strength_modifier initialization and serialization in built-in rules output.

Sequence Diagram(s)

sequenceDiagram
    participant MF as Magic File
    participant P as Parser
    participant AST as AST
    participant E as Evaluator
    participant S as Strength Module

    MF->>P: read line "!:strength <op><n>"
    P->>P: is_strength_directive? → parse_strength_directive
    P-->>P: store pending_strength in LineInfo
    MF->>P: read next rule line
    P->>AST: construct MagicRule(strength_modifier=Some(...))
    AST-->>E: emit MagicRule(s)
    E->>S: calculate_rule_strength(rule)
    S->>S: compute default strength → apply modifier
    S-->>E: return numeric strength
    E->>S: sort_rules_by_strength(rules)
    S-->>E: rules sorted by computed strength

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• feat: built-in rules build time compilation fallback #28 — Adds StrengthModifier and related build_helpers/build.rs codegen for serializing strength modifiers.
• 12 add magic file format detection subtask 143 #25 — Implements similar AST, parsing, and strength application features affecting parser/evaluator surfaces.
• feat: Implement text magic parser (issue #11) #16 — Related parser preprocessing and hierarchy construction changes that intersect strength directive handling.

Poem

🐇 I found a tiny directive bright,
I nudge each rule to tip the fight,
A plus, a set, a gentle shove,
I sort the bytes with carrot love,
Hop, hop — magic hums beneath moonlight.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'feat: strength calculation & documentation improvements (#21)' accurately reflects the main changes: a strength calculation system for magic rules and comprehensive documentation enhancements.
Description check	✅ Passed	The PR description is well-related to the changeset, detailing the strength calculation system implementation, documentation improvements, files changed, and test plan results.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch 21-strength-calculation-libmagic-algorithm-strength-parsing

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 97.74718% with 18 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/parser/mod.rs	93.63%	7 Missing ⚠️
src/build_helpers.rs	66.66%	6 Missing ⚠️
src/main.rs	40.00%	3 Missing ⚠️
src/evaluator/strength.rs	99.49%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!