Compiler Package Implementation
Relevant source files
The following files were used as context for generating this wiki page:
The Compiler package serves as the central orchestration layer of the chemd ecosystem. Its primary purpose is to integrate the independent modules of parsing, resolution, and rendering into a unified pipeline that transforms plain Markdown source into structured chemical data and multi-format outputs. By abstracting the complexities of individual packages, the compiler provides a streamlined interface for both web and Node.js environments.
The compiler's scope includes managing the lifecycle of a document from initial source ingestion through semantic AST normalization, reference resolution, template expansion, and final rendering into HTML, JSON, and DOCX-compatible formats. It ensures that semantic content remains strictly separated from rendering styles by applying render profiles and overrides at the final stage of the pipeline.
Sources: chemd-v0.1-architecture.md:9-11, packages/compiler/tests/compiler.test.ts:7-10
Multi-Stage Compilation Pipeline
The compiler implements a multi-stage pipeline architecture. This separation of concerns ensures that syntax parsing is independent of semantic resolution, and style resolution is decoupled from semantic object parsing.
This pipeline allows diagnostics to be attached at every stage, providing feedback on syntax errors, missing fields, or unresolved references throughout the process.
Sources: chemd-v0.1-architecture.md:104-123, chemd-v0.1-architecture.md:143-164
Core Compilation Orchestration
The primary entry point for the package is the compileChemd function. It wires together the parser, resolver, and various renderers to produce a comprehensive CompileResult.
Key Components
| Component | Responsibility | Derived From |
|---|---|---|
| Parser | Extracts frontmatter and detects chemd blocks/inline syntax. | @chemd/parser |
| Resolver | Builds object indexes, resolves @ references, and expands templates. | @chemd/resolver |
| Render Profile | Merges default profiles with document-level overrides. | @chemd/render-profile |
| Renderers | Produces HTML, JSON, and DOCX bridge payloads. | @chemd/renderer-* |
Sources: packages/compiler/tests/compiler.test.ts:7-20, chemd-v0.1-architecture.md:126-140
CompileResult Structure
The output of the compiler includes the fully resolved semantic document, the final render options used, any diagnostics generated during the process, and the rendered strings for different formats.
interface CompileResult {
document: ResolvedChemdDocument; // Semantic AST after resolution
renderOptions: RenderOptions; // Resolved style settings
renderAdapterPayload: any; // RDKit-specific rendering data
html: string; // HTML preview content
json: string; // Serialized AST and metadata
docxBridge: string; // Payload for DOCX export pipeline
diagnostics: Diagnostic[]; // Collection of warnings and errors
}
Sources: packages/compiler/tests/compiler.test.ts:31-50, chemd-v0.1-architecture.md:273-276
Render Profile and Override Logic
A critical feature of the compiler implementation is the strict separation between semantic AST nodes and rendering style properties. Style properties such as bondLength or monochrome mode are never stored in the semantic blocks (e.g., molecule or reaction). Instead, they are resolved at compile-time.
The compiler supports three levels of style configuration:
- Default Profile: Usually
eln-default. - Document Level: Specified in YAML frontmatter via
render_profileandrender_overrides. - Runtime Selection: Passed directly to the compiler function, which takes precedence over frontmatter.
Sources: chemd-v0.1-architecture.md:204-219, packages/compiler/tests/compiler.test.ts:54-94
Node.js DOCX Export Pipeline
For server-side or CLI environments, the compiler package provides specialized utilities for exporting documents to DOCX via a Pandoc-based bridge.
Pandoc Integration
The compileChemdToDocx function generates an intermediate Markdown handoff and a structured bridge payload that Pandoc consumes. The system supports custom Pandoc arguments, including reference documents for styling.
DOCX Export Options
| Option | Type | Description |
|---|---|---|
outputPath | string | The file system path for the resulting DOCX. |
referenceDocPath | string | Path to a DOCX template for Pandoc styling. |
runner | function | Injected function to execute the Pandoc binary. |
executionTimeoutMs | number | Timeout for the Pandoc process (default handling). |
Sources: packages/compiler/tests/compiler-node.test.ts:6-23, packages/compiler/tests/compiler-node.test.ts:56-75
Diagnostic Reporting
The compiler surfaces diagnostics from all stages of the pipeline. These include:
- Parser Diagnostics:
W_UNKNOWN_BLOCK,W_UNTERMINATED_BLOCK. - Resolver Diagnostics:
E_DUPLICATE_ID,W_UNRESOLVED_REFERENCE,E_TEMPLATE_CYCLE. - Render Diagnostics:
W_UNKNOWN_RENDER_PROFILE,E_INVALID_RENDER_PROFILE_VALUE.
Sources: chemd-v0.1-architecture.md:253-268, packages/compiler/tests/compiler.test.ts:96-110
The compiler package implementation ensures that chemd remains a "plain text first" system while providing the necessary infrastructure to drive complex web previews and high-quality publication exports. By orchestrating the flow between specialized packages, it maintains a clean boundary between chemical data and its visual representation.