Does norg provide a stable parser API for reproducible document processing?

Question

Goal: Ensure that a development team can share norg files and obtain identical parsed representations regardless of the host machine or the version of the norg parser installed.

Constraint: The norg parser is actively evolving, and recent releases have adjusted how certain constructs—such as nested heading blocks, custom macros, and link resolution—are translated into the abstract syntax tree (AST). This evolution raises uncertainty about whether a document parsed today will yield the same AST tomorrow after a minor version bump.

Question: Does the norg project expose a versioned or compatibility‑mode parser API that locks the AST output to a specific release? Are there documented guarantees or migration notes that describe which syntactic changes are considered breaking for AST compatibility? Can a project declare a parser version in a lockfile or configuration file to guarantee repeatable builds across CI agents and developer workstations?

Tasadduq Burney · Answer

Answer
No, the norg project does not expose a versioned or compatibility‑mode parser API that guarantees identical AST output across releases.
Explanation
Confirmed facts from the project’s documentation and changelogs show:

The public parser functions are updated with each release without a compatibility flag or version selector.
Release notes describe AST changes (e.g., heading block handling, macro expansion) but do not label them as breaking for parser versioning, and there is no documented guarantee of AST stability.
There is no dedicated lockfile field or version‑selection mechanism for the parser; you can only pin the overall norg crate/package version.

Practical steps for reproducible processing

Pin an exact version of the norg dependency in your build file (e.g., norg = "0.12.3" in Cargo.toml or the equivalent in your language’s package manager).
In CI, parse a representative sample document and serialize the AST (e.g., to JSON). Store this snapshot as a test artifact.
On each dependency update, compare the new AST snapshot against the stored one; any difference indicates a parser change that may affect reproducibility.
If a stable AST is required, consider wrapping the parser in a version‑specific abstraction or generating and checking in a serialized AST snapshot for verification.

Does norg provide a stable parser API for reproducible document processing?

1 answer

Answer

Explanation

Practical steps for reproducible processing

Your perspective belongs here.

0 question comments