Summary

Add a fix_guidance field to loq.toml that outputs custom instructions when loq check finds violations. This is particularly valuable for LLM-assisted development workflows where the guidance can be fed directly to an AI assistant.

Motivation

loq is an "electric fence" for file size - but when files exceed limits, users (and LLMs) need context on how to fix them. Different codebases have different conventions for splitting files:

• Some use module patterns (mod.rs + submodules)
• Some prefer extracting to separate files by concern
• Some have specific architectural patterns to follow

By allowing custom guidance in the config, the output becomes actionable - especially when piped to an LLM that can then help refactor the oversized files according to project conventions.

Proposed Config

default_max_lines = 500
fix_guidance = "Consider refactoring large files into smaller modules."

[[rules]]
path = "**/*.rs"
max_lines = 300
fix_guidance = "Rust files should be kept concise. Split using mod.rs pattern - see docs/style-guide.md."

[[rules]]
path = "tests/**/*"
max_lines = 600
# No fix_guidance - falls back to global

Proposed Output

✖   350 > 300  src/large_module.rs
✖   700 > 500  docs/readme.md
2 violations (15ms)

Guidance:
  • Rust files should be kept concise. Split using mod.rs pattern - see docs/style-guide.md.
  • Consider refactoring large files into smaller modules.

Design

• fix_guidance: Option<String> at both config root and per-rule level
• Per-rule guidance takes precedence over global
• Only shown when there are violations
• Multiple unique guidance strings displayed as a bulleted list

Implementation Notes

A detailed implementation plan exists covering:

1. Add field to LoqConfig, Rule, CompiledConfig, CompiledRule
2. Add guidance_for(&MatchBy) method to resolve rule vs global priority
3. Extend Report to collect unique guidance strings
4. Add write_guidance() output function
5. Thread config through to output layer