Core AST Package
Relevant source files
The following files were used as context for generating this wiki page:
The Core AST Package (packages/core) serves as the foundational layer of the cheMD ecosystem, defining the shared domain types and data structures that represent a chemical document. Its primary purpose is to provide a standardized, machine-readable format for chemical and experimental data, ensuring consistency across the parser, resolver, and various renderers.
The package enforces a strict architectural boundary between Semantic AST (the meaning of the data) and Render Options (how the data looks). By keeping semantic definitions isolated from visual properties like bond lengths or font sizes, the package ensures that a single source document can drive multiple outputs, including HTML previews, JSON exports, and SVG structures.
Sources: chemd-v0.1-architecture.md:12-25, chemd-v0.1-architecture.md:55-60
Architectural Principles
Semantic AST vs. Render Options
A "hard architectural boundary" exists within the cheMD system. The Core AST Package is responsible for the Semantic AST, which represents the structure of the experiment and chemical objects. Visual style properties are explicitly excluded from these nodes to prevent "style pollution" of the core data.
The Semantic AST contains metadata, structured blocks (molecules, reactions), and resolution outcomes, while Render Options contain generic tokens for visual configuration.
Sources: chemd-v0.1-architecture.md:40-52, chemd-v0.1-spec.md:104-115
Document Structure
The top-level object in the AST is the ChemdDocument. It encapsulates all metadata and child nodes discovered during the parsing phase.
ChemdDocument Schema
| Field | Type | Description |
|---|---|---|
type | "document" | Fixed type identifier. |
meta | Record<string, unknown> | Extracted YAML frontmatter metadata (e.g., id, title, date). |
children | ChemdNode[] | Array of semantic blocks and markdown fragments. |
diagnostics | Diagnostic[] | Collection of errors, warnings, and info messages. |
renderSelection | RenderSelection | Metadata regarding the selected render profile and overrides. |
Sources: chemd-v0.1-architecture.md:130-140, packages/core/tests/core.test.ts:18-25
Semantic Node Types
The AST is composed of several specialized node types that extend a base block model. Every structured block can optionally include a unique identifier (#id) for cross-referencing.
Core Block Nodes
- MoleculeNode: Represents molecular structures, primarily using SMILES notation.
- ReactionNode: Defines chemical reactions, including reactants, products, and conditions.
- ResultNode: Captures experimental outcomes like yield, conversion, and purity.
- AnalysisNode: Stores characterization data (e.g., NMR, HPLC) including instrument settings.
- SampleNode: Represents physical material details like batch numbers and suppliers.
Markdown and Inline Tokens
Ordinary text is captured as MarkdownNode objects. These nodes are not just strings; they contain arrays of "tokens" that represent semantic elements found within the text.
| Token Type | Purpose | Example Syntax |
|---|---|---|
ReferenceToken | Object or field lookups | @res-main.yield |
InlineChemToken | Chemical formulas/equations | :chem[H2O] |
InlineCodeToken | Technical snippets | `@meta.project` |
MarkdownLinkToken | Hyperlinks with safety checks | [Spec](https://...) |
Sources: chemd-v0.1-spec.md:213-225, packages/core/tests/core.test.ts:33-70
Diagnostics System
The core package defines a unified diagnostic format used by all pipeline stages (parsing, resolution, rendering) to communicate issues to the user.
interface Diagnostic {
code: string; // e.g., "E_DUPLICATE_ID"
severity: "info" | "warning" | "error";
message: string;
position?: SourceRange; // Line and column information
nodeId?: string; // ID of the related block
}
Sources: chemd-v0.1-architecture.md:370-380, packages/parser/tests/parser.test.ts:255-265
Validation Logic
The Core AST Package includes shared logic for validating metadata and render overrides. This ensures that only valid configuration paths reach the renderers.
Render Override Validation
The package maintains an allowlist of valid style paths (e.g., structure.bondLineWidth) and provides hints for expected value types.
Summary
The Core AST Package provides the technical contract for the cheMD project. By defining a strict, immutable relationship between semantic data and the visual rendering pipeline, it enables the system to handle complex chemical data as first-class objects within a standard Markdown workflow. Its shared types allow the parser and resolver to build a rich, validated graph of an experiment before any rendering occurs.