Parsing & Resolution Pipeline

Relevant source files

The following files were used as context for generating this wiki page:

• chemd-v0.1-architecture.md
• chemd-v0.1-spec.md
• packages/parser/src/frontmatter/parse-frontmatter.ts
• packages/resolver/tests/resolver.test.ts
• packages/parser/tests/parser.test.ts
• packages/compiler/tests/compiler.test.ts

The Parsing & Resolution Pipeline is the core engine of chemd, responsible for transforming plain Markdown and structured chemical blocks into a validated, semantic Abstract Syntax Tree (AST). This pipeline separates semantic content from visual rendering, ensuring that chemical data remains portable and machine-readable while supporting human-friendly previews.

The pipeline operates in multiple stages, beginning with frontmatter extraction and syntax parsing, followed by a resolution phase where templates are expanded, and references (such as @id.field) are linked to their source objects. This architecture allows chemd to support complex features like lightweight references and reusable templates within a simple Markdown-based document model.

Sources: chemd-v0.1-architecture.md:52-70, chemd-v0.1-spec.md:21-42

Pipeline Architecture Overview

The system is designed as a multi-stage pipeline rather than a single render pass. This separation of concerns ensures that syntax parsing is independent of semantic resolution, and style resolution remains independent of semantic object parsing.

The diagram above illustrates the sequential transformation of a source document into a fully resolved semantic AST.
Sources: chemd-v0.1-architecture.md:120-143, chemd-v0.1-spec.md:275-290

Stage 1: Frontmatter and Syntax Parsing

The initial phase involves dissecting the UTF-8 source file into its primary components. The parser first extracts YAML frontmatter to identify document metadata and render settings.

Frontmatter Extraction

The frontmatter parser identifies metadata such as the document ID, title, and render_profile. It uses strict validation for required keys and ISO date formats.

Key	Purpose	Required
id	Unique identifier for the document	Yes
title	Human-readable title of the experiment	Yes
date	ISO 8601 date (YYYY-MM-DD)	Yes
render_profile	Identifier for visual style configurations	No
primary_reaction	Default reaction ID for alias resolution	No

Sources: chemd-v0.1-spec.md:52-87, packages/parser/src/frontmatter/parse-frontmatter.ts:13-25

Markdown and Block Detection

The parser identifies standard Markdown nodes and intercepts chemd specific blocks (e.g., :::molecule, :::reaction). It also tokenizes inline chemistry syntax (:chem[...]) and reference tokens (@id).

Sources: chemd-v0.1-architecture.md:167-175, packages/parser/tests/parser.test.ts:70-110

Stage 2: Resolution and Template Expansion

Once the initial AST is constructed, the resolver package processes the document to link references and expand templates.

Object Indexing and Reference Resolution

The resolver builds an index of all objects with IDs (e.g., #mol-1). References are then resolved according to specific lookup rules:

1. Explicit Lookup: @id.field resolves directly against the object index.
2. Alias Resolution: Aliases like @reaction.temperature follow a hierarchy:
   • Explicit use block override.
   • Template bind definition.
   • Frontmatter primary_reaction key.
   • Fallback to the first object of that type in the document.

Sources: chemd-v0.1-architecture.md:225-240, chemd-v0.1-spec.md:387-405, packages/resolver/tests/resolver.test.ts:15-35

Template Engine

Templates allow for re-usable Markdown fragments with parameter injection. The resolution process expands :::use blocks into standard Markdown and semantic nodes before the final rendering stage.

The sequence diagram shows how the resolver interacts with the template index to replace placeholder use nodes with actual content.
Sources: chemd-v0.1-architecture.md:242-260, chemd-v0.1-spec.md:415-465

Stage 3: Validation and Diagnostics

Throughout the pipeline, the system attaches diagnostics to nodes. Errors are localized so that a single broken block does not crash the entire document processing.

Diagnostic Severities and Codes

Code	Severity	Description
E_DUPLICATE_ID	Error	Multiple blocks share the same ID
E_TEMPLATE_CYCLE	Error	Circular dependency in template expansion
W_UNRESOLVED_REFERENCE	Warning	Reference target not found in index or meta
W_UNKNOWN_FIELD	Warning	Field present in block but not in schema

Sources: chemd-v0.1-architecture.md:345-365, packages/parser/tests/parser.test.ts:255-275

Conclusion

The Parsing & Resolution Pipeline ensures that chemd documents are more than just text; they are structured data sources. By separating the initial syntax parse from the semantic resolution, the architecture remains flexible enough to support multiple output formats (HTML, JSON, SVG, DOCX) while maintaining strict data integrity and providing detailed developer diagnostics.

Sources: chemd-v0.1-architecture.md:395-410, chemd-v0.1-spec.md:600-610