@openexam/parser

Reference parser. Turns an OpenExam source file (.oex.md — Markdown + directives + YAML frontmatter) into an OEAST Document, targeting spec 0.1 (M1).

This is the conformance baseline per ADR-023 §6: where the spec text and the parser disagree, the parser wins, and the spec text is corrected in the next patch release.

Public API

import { parse } from '@openexam/parser';
import type { Document } from '@openexam/sdk';

const source = await fs.readFile('assignment.oex.md', 'utf8');
const document: Document = parse(source);

parse throws ParseError on any rejected input. The error carries line, column, and message.

Spec subset

0.1 is deliberately tiny — see spec/0.1/grammar.md. The parser rejects anything outside that subset (math, images, tables, fenced code, links, ordered lists, etc.) with location-pointing errors so authors don't accidentally rely on shapes that may change in 0.2.

Implementation choices

• Hand-written. The 0.1 subset is small enough that depending on unified/remark/remark-directive would buy us less control over rejected-construct error messages than it costs in dep weight and parser-config gymnastics.
• yaml (Eemeli Aro) for frontmatter parsing.
• No runtime JSON Schema validator: the parser produces typed OEAST nodes whose shapes match the SDK types by construction. Tests validate the output against spec/0.1/oeast.schema.json for defense-in-depth.

License

Apache-2.0. See LICENSE and the repository root ../../LICENSE.