Skip to content

Phase 7.3 (first half): the JS parser's spec and contracts - #190

Open
atiernan wants to merge 9 commits into
claude/a64-specfrom
claude/js-syntax-spec
Open

atiernan wants to merge 9 commits into
claude/a64-specfrom
claude/js-syntax-spec

Conversation

@atiernan

Copy link
Copy Markdown
Member

Phase 7 item 7.3, first half: clazel-js-syntax, the parser's spec and contracts (rule 3). There is no parser implementation yet. The crate stays at tier 0, and its target tier is 1.

This PR is part of stack #188, on top of #186.

What's here

  • src/ast.rs: an arena AST with spans, covering scripts and modules, with about 150 node kinds named after the standard's productions.
    • Children come before their parents, and the root is last.
    • An absent optional symbol is an Absent node.
  • src/spec.rs: about 3,900 lines.
    • The grammar: the relation d(ast, toks, n, ctx, i, j), with one arm per node kind. Ctx carries [Yield], [Await], [In], [Return] and [Default].
    • Coverage:
      • all of §13 (expressions) and §14 (statements);
      • from §15: functions, async functions, generators, arrows, methods, classes, fields, static blocks and private names;
      • §16, Script and Module, with imports and exports, including attributes;
      • Annex B.3.1, B.3.3 and B.3.5.
    • ASI: §12.10.1 rules 1 to 4.
    • The depth limit: MAX_DEPTH = 1024, a listed deviation.
    • The early errors: about 40 rule groups, each cited by section. is_parse is the grammar relation, and is_valid_parse adds the early errors to it.
  • src/contract.rs and src/api.rs: JsParser::parse(src, goal), on a body-less trait with no escape hatch.
    • Ok: the arena is well formed, every span lies inside the source, the result is a valid parse, and its height is at most MAX_DEPTH.
    • Err: no valid parse exists within the limit, and Syntax means no valid parse exists at all.
  • src/examples.rs: seven small proofs.
    • Accepted: the empty script, and ;.
    • Rejected: a ?? b || c and -a ** b.
    • Early errors: break outside a loop, and with in strict code.
    • An inserted ; consumes no token.

For the spec reviewer, first

  1. The lexer is abstract. It is the trait LexerSpec, and the contract is stated relative to it. The second half of 7.3 must instantiate it with clazel-js-lexer's next_token contract.
  2. How ASI is modelled.
    • An inserted ; lives in a gap between tokens, so no span covers text that isn't in the source.
    • An insertion is justified only if no sentence of the grammar without insertion begins with the earlier tokens plus the offending token, under any goal the lexer could be using there.
    • Insertion after do-while is rule 1's third condition, which is where the pinned text puts it.
  3. EarlyEnv follows how d passes Ctx. If the two get out of step, a rule is weakened without any error showing, so this is the likeliest place for findings.
  4. Ends come from spans. A child's end token is read from its recorded span with choose, and span_ok then checks that span.
  5. Cover grammars are specified as the refined production. CoverInitializedName is always an early error.
  6. ?. followed by a template is in the grammar and is always an early error. Without it, ASI would wrongly split a?.b followed by a newline and a template (§13.3.1.1).
  7. lvl compresses the precedence chain into one number per node kind. ??, ** and #x in y are special cases.
  8. String values are carried in Tok::name. The legacy flag isn't in the lexer's Value::String.

Not covered (listed at the top of spec.rs)

  • Duplicate exported names, exported bindings that aren't declared, and well-formed Unicode in module export names.
  • Annex B.3.4's exception for for (var e of …) inside catch (e).
  • The 2^32 limit on template strings.
  • The rules for direct eval.
  • Regexp contents. These are taken as regexp_literal_valid from the lexer trait.

Nothing about the spec's totality, determinism or agreement with the standard is proven. The evidence so far is the seven examples and the line-by-line citations. The section numbers were checked against an ES2026 spec.html, but that copy was not confirmed to be the pinned commit, so a reviewer should check them against the pin.

Verification

  • Verus, on a fresh target dir in WSL: verification results:: 57 verified, 0 errors.
  • cargo xtask check: STATIC CHECKS PASSED.
  • Build, clippy -D warnings and rustfmt: clean.
  • cargo xtask verify --changed was not run locally, because the new crate changes Cargo.lock. CI's full verification is the check, and its proof jobs need approval.

🤖 Generated with Claude Code

atiernan and others added 4 commits November 17, 2026 16:09
A new tier-0 crate, item 7.3 first half (contracts before code). The AST is
an arena of nodes with spans, whose kinds are named after the productions of
ECMA-262 (§13 to §16), children before parents, optional symbols as Absent
nodes. Joins PLACES as a Renderer crate; its only dependency is vstd.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…tion, as a spec

spec.rs transcribes ECMA-262's §13 to §16 as a relation between an arena AST
and a token stream (d, one arm per node kind, the grammar parameters as Ctx),
with the lexer abstracted behind LexerSpec, and §12.10.1's rules as
gap_justified: an inserted semicolon is justified when no sentence of the
grammar without insertion begins with the tokens before it and the offending
token. The recursion limit is MAX_DEPTH, a listed deviation. The file's header
lists what is covered, what is left out, and every modelling choice.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… spec

early states each "It is a Syntax Error if" rule of the clauses it cites
(identifiers, literals, assignment targets, names declared twice, labels and
break/continue targets, strict mode, super and new.target, parameters, classes
and private names, modules) over the AST, with what a rule reads off a node's
position carried down as EarlyEnv. is_valid_parse is a parse of the source by
the grammar with no early error: the relation the parser's contract is stated
by. What is not yet specified is listed in the header.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…roven examples

contract.rs: parse_requires (none: the parser is total) and parse_ensures: an
Ok is a well-formed arena with spans inside the source, a valid parse of it,
within MAX_DEPTH; an Err means no valid parse within the limit, and Syntax
means none at all. api.rs: the body-less trait JsParser<L: LexerSpec>, with no
escape hatch. examples.rs: seven small proofs about the spec. There is no
parser yet; the tier stays 0.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
atiernan and others added 2 commits November 17, 2026 20:21
CI's proof job requires a mutations.json for every crate Verus checks.
Three mutations (`??` mixing with `||`, a unary base for `**`, the
do-while semicolon inserted anywhere), each killed by an existing
proven example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
atiernan and others added 2 commits November 18, 2026 13:35
span_ok put an empty node at the end of the token before it. An Absent
first child (`import {a} from 'm'`, the `{a}` import specifier) then
fell outside its parent whenever white space came between, so the
grammar's d and spans_wf could not both hold. An empty node may now sit
anywhere in the white space before its token.

§15.7.1's "ContainsAwait of ClassStaticBlockStatementList" rule was
missing: `await 0` or `for await` in a static block inside an async
function parsed. The static block now sets no_yield_await, which
ContainsAwait matches (it does not look inside functions or async arrow
bodies), and a `for await` is an error where it is set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch is being deployed

1 queued deployment
full-verification — 98e8bf27 Deployed Nov 20, 2026 by atiernan via Approve the proofs #618
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant