Parse Phase

The Parse phase converts IDL source text into an abstract syntax tree (AST). The parser is deterministic: for any valid IDL input, exactly one AST is produced. Parse-phase issues are all hard errors — the parser does not produce warnings, does not attempt error recovery, and produces no partial AST. Either the input is fully valid and an AST is produced, or a parse error is reported and no AST is produced.

Parse Phase Responsibilities

• Grammar validation — source text must conform to the BNF grammar for the declared grammar version.
• Module declaration validation — exactly one module declaration per file.
• Module name conformance — module names must match the file path.
• Import resolution — all imported module paths must be resolvable within the project.
• Circular import detection — import graphs must be acyclic.
• Token declaration syntax validation — all token declarations must conform to the token grammar.
• Component declaration syntax validation — all component declarations must be grammatically well-formed.

AST Schema

The AST schema is versioned independently from the IDL grammar version. The AST schema version is encoded in the root node of every AST. Plugin systems that consume the AST MUST declare the AST schema version they require; the compiler validates compatibility before invoking plugins. Breaking changes to the AST schema require a major compiler version increment.

Parse Phase and the Plugin Interface

Plugins may register an after-parse hook that receives the completed AST before Transform begins. After-parse plugins may read the AST and produce metadata; they may not modify the AST structure. AST modification is reserved for Transform-phase plugins. This constraint ensures that the AST produced by Parse is the canonical, unmodified representation of the source.