oracle-parser

Oracle Parser — Single Source of Truth

The Oracle parser converts MTGJSON Oracle text into typed AbilityDefinition structs that the engine executes. This skill is the authoritative reference for all parser work.

CR Verification Rule: Every CR number you write MUST be verified by grepping docs/MagicCompRules.txt BEFORE adding it to code. See Section 8.

---

1. Non-Negotiable Rules

These rules are defined in CLAUDE.md and are enforced without exception. Violations will be caught in review and must be fixed before merge.

⚠ RULE ZERO: Nom Combinators Are Mandatory — No Exceptions

All new parser code MUST use nom combinators from the very first line written. This is the single most important rule in the parser codebase. It has been violated repeatedly and is now enforced as a hard gate.

NEVER write any of these for parsing dispatch:

• find(), split_once(), contains(), starts_with() — for dispatch routing
• if lower.starts_with("destroy ") — use tag("destroy ").parse(lower) instead
• if lower.contains("target") — use scan_at_word_boundaries or a nom combinator instead
• text.find(' ').map(|i| &text[..i]) — use nom take_till or take_while

ALWAYS write:

• tag("destroy ").parse(lower)? — for known prefix dispatch
• alt((tag("destroy "), tag("exile "))).parse(lower)? — for multi-option dispatch
• nom_on_lower(text, lower, parser_fn) — for mixed-case text bridging to nom
• nom_on_lower_required(text, lower, parser_fn)? — same with ? propagation
• nom_parse_lower(lower, parser_fn) — when remainder is unused
• scan_at_word_boundaries(text, combinator) — for multi-position phrase matching

Nom combinator reference: See nom_combinators.md in this skill directory for the complete list of nom parsers and combinators organized by module. Consult this when choosing which combinator to use.

Copy-paste patterns + the enforcement gate: When you need to translate a string-method idiom into combinators, open crates/engine/src/parser/oracle_nom/PATTERNS.md — it indexes every common shape (strip prefix, strip suffix, optional trailing clause, alternatives, word-boundary scan, delimiter split, contains-check, peek-without-consume) with copy-pasteable code. The pre-commit hook scripts/check-parser-combinators.sh actively rejects new lines containing .strip_prefix(...), .strip_suffix(...), .contains("..."), .starts_with("..."), .ends_with("..."), .split_once(...), .find("..."), or .trim_end_matches("...") against string literals inside crates/engine/src/parser/. If a use is genuinely structural (post-tokenization punctuation cleanup, TextPair dual-string stripping, runtime char scans) annotate the line // allow-noncombinator: <one-line reason> per PATTERNS.md §9. Existing offenders are grandfathered; new code is gated.