core: read a sentence into a check

[jbpros]

First implementation PR after #180: the parser for spec/sentences.abnf, in ergo.rego, not yet called by ergo.report.

What it does. _sentence(text) reads a check, _for_line(text) a for line and _from_line(text) a from line, each into a JSON shape that mirrors the sentence (quantifier, path, where conditions, phrase and its arguments, or terms for count of, sum of and plus), or into {"problems": [...]} when the line is written wrong. _s_check_text and its two siblings print a parsed line back in one spelling: is before a value and equals before a field, is one of before values and is in before a path, an before object, item 3 of for a position that ends a path, single quotes for a string with a backslash when that reads back the same, one space between words. Two spellings of one check give the same parse: the dot in front of a key, brackets or words for a position, and runs of spaces are spelling only.

How. The grammar is flat, so the parser is layered regular expressions: one splits the assertions on and, one reads an assertion's parts, one reads the conditions of a where, one picks the phrase. Each split piece has to end at its separator or the end of the line, so the regex engine backtracks past a short match like false in false-positive. Rego can't recurse and this needs none.

Wasm. The first version took over two minutes for the corpus under Wasm, because Wasm rebuilds a constant rule at every reference and the patterns were a tree of constants. They're now built once per call in _s_patterns and passed down, and the phrase union is factored by argument kind. The corpus test takes 20 s under Wasm and 0.3 s with opa test.

Tests. Every one of the 306 corpus lines parses and prints back byte for byte, from spec/sentences-corpus.json, which spec/sentences_corpus.py writes from the markdown. The CI check that it's current is in #185, after this PR, so the squashed commit stays core:. Unit tests cover each phrase, each path form, the printed spellings, and the messages for sentences written wrong.

Review. A fresh Opus review found twelve things, four of them real bugs: a leading-zero index and a bad string escape stopped the evaluation, keys starting with true, false, null or empty were rejected, and the parser accepted a where on a plain path, a lone number on the left, a non-comparison after count of, and a for name given twice. All twelve are fixed in the second core: commit, with the spec changed in two places it was wrong: when a string prints in single quotes, and the is empy row of the written-wrong table, since that sentence parses as a comparison with a field.

Second review. A second review compared the parser with the ABNF, converted to a Lark grammar, on 6,000 changed corpus lines and 11,616 random sentences built from the grammar, and printed back every line the parser accepted. It found three things, fixed in the last commits:

• x is between -6 and -80e-08923553 crashed OPA with panic: illegal value. OPA (1.19.0, 1.20.2 and 1.21.2) panics when it compares a number whose exponent is beyond ±1,000,000, reported as Comparing a number whose exponent is beyond ±1,000,000 panics with "illegal value" open-policy-agent/opa#9365. The parser now works out a number's size from its text before to_number, and applies the rule a policy number already follows: 0 or a magnitude between 2.2250738585072014e-308 and 1.7976931348623157e308. Otherwise the sentence gets number out of range: <number>. sentences.md says so.
• That also fixes x is between 1 and 1e400, which failed with "doesn't parse" because OPA can't compare numbers above 1.8e308.
• The ABNF gave named by each of a left-side path, where "T" is a key. The parser and sentences.md read a right-side path, so the ABNF now says right-path.

Problems now keep their column order, so column 6 comes before column 20. A third review found that x is 1 within -1 parsed, though the spec says the number after within is 0 or more. It now gets "within" needs a number of 0 or more.

Not in this PR. Wiring into ergo.report and the semantics of each phrase. spec/sentences.md now says ergo reads sentences but runs none.

Checks run here: opa check, opa fmt, opa test with coverage (every line reached), --strict-builtin-errors, Regal, no comments, OPA 1.20.2 fmt, Wasm tests in Docker, and the Wasm JS runtime script (1009 pass, 10.5 MB). On OPA 1.19, two of the 11,616 random sentences didn't print back the same inside one big evaluation, because 1.19 thinks 0.5e-7 equals 0.5e-70. That's the known 1.19 number bug, and OPA 1.20.2 prints all of them back correctly.

🤖 Generated with Claude Code