Repository Guidelines & Conventions

Relevant source files

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

• AGENTS.md
• chemd-v0.1-architecture.md
• chemd-v0.1-spec.md
• chemd-render-profile-v0.1-spec.md
• packages/parser/src/frontmatter/parse-frontmatter.ts

The cheMD repository is structured as a pnpm workspace and Turborepo monorepo designed for a chemistry-focused Markdown domain language. These guidelines ensure consistency across the semantic language layer, the resolution/template layer, and the rendering pipeline. The project prioritizes a strict separation between semantic content (e.g., molecules, reactions) and visual rendering styles (e.g., bond lengths, colors).

Sources: AGENTS.md:10-14, chemd-v0.1-architecture.md:468-472

Project Structure & Module Organization

The codebase is organized into a monorepo layout where core logic resides in packages/* and the user interface is located in apps/web.

Directory Layout

• apps/web: Next.js 15 application providing the UI entry point.
• packages/core: Shared domain types, AST definitions, and identifier validators.
• packages/parser: Logic for reading frontmatter and detecting chemd block/inline syntax.
• packages/resolver: Handles object indexing, template expansion, and reference resolution.
• packages/render-profile: Manages visual style definitions and merges profile overrides.
• packages/renderer-*: Specific output modules (HTML, JSON, SVG, DOCX).
• docs: Specifications, architecture notes, and implementation plans.

Sources: AGENTS.md:12-20, chemd-v0.1-architecture.md:118-164

Implementation Strategy

Developers must implement logic in packages/* before integrating it into apps/web. The architecture follows a multi-stage pipeline where syntax parsing is independent of semantic resolution and visual styling.

The diagram shows the sequence of the cheMD processing pipeline from raw source to final output.
Sources: chemd-v0.1-architecture.md:94-115

Development Workflow

Build and Test Commands

All development tasks should be executed from the repository root using pnpm:

Command	Description
pnpm install	Install all workspace dependencies
pnpm dev	Start local web development via Turbo
pnpm build	Build and type-check all workspaces
pnpm test	Run all Vitest suites
pnpm typecheck	Run full TypeScript checks
pnpm --filter <pkg> test	Run tests for a specific package (e.g., @chemd/parser)

Sources: AGENTS.md:24-32

Verification Requirements

• Validation: Confirm plans before coding non-trivial changes. Validate changed scope first using filtered tests, followed by a full pnpm test and pnpm typecheck before submitting a Pull Request.
• UI Changes: Attach before/after screenshots for any modifications in apps/web.
• Sandbox Limits: If a command fails due to network/sandbox restrictions, request out-of-sandbox execution rather than skipping validation.

Sources: AGENTS.md:35-41

Coding Standards

Naming Conventions

• Variables/Functions: camelCase
• React Components: PascalCase
• Packages/Folders: kebab-case
• Database/Block Fields: snake_case (e.g., bond_length, primary_reaction)

Sources: AGENTS.md:49-51, chemd-v0.1-spec.md:144-145

Implementation Rules

• TypeScript: Strict mode is mandatory; types must be explicit at API boundaries.
• Formatting: 2-space indentation, semicolons, and double quotes.
• Exports: Public APIs must be exported from src/index.ts.
• Aliases: Prefer @chemd/* workspace aliases over deep relative paths.

Sources: AGENTS.md:46-52

Commit & Pull Request Guidelines

The project follows a structured commit format based on Conventional Commits.

Commit Format

<type>[optional scope]: <description>

[body]

[optional footer]

Core Types

• feat: New feature (minor version)
• fix: Bug fix (patch version)
• docs: Documentation only
• refactor: Code change that neither fixes a bug nor adds a feature
• test: Adding or correcting tests
• chore: Maintenance tasks

Description Rules

• Use the imperative mood (e.g., "add", not "added").
• No trailing periods.
• Maximum 30 characters for the summary.

Sources: AGENTS.md:55-83

Architectural Conventions

Semantic vs. Style Separation

A critical convention in cheMD is the "Hard Architectural Boundary" between semantic AST nodes and rendering options.

• Semantic AST: Contains molecule data (smiles), reaction components, results, and document metadata.
• Render Options: Contains visual tokens like bondLength, fontSize, and monochrome mode.

Rule: No semantic block node (e.g., :::molecule) may own style properties. Style must be managed via render_profile or render_overrides in the document frontmatter.

Sources: chemd-v0.1-architecture.md:74-92, chemd-v0.1-spec.md:94-118

Standardized Block Syntax

All structured blocks must follow the fenced directive-style:

:::block_name #optional-id
key: value
:::

Ids must start with a letter and contain only alphanumeric characters, underscores, or hyphens ([a-zA-Z][a-zA-Z0-9_-]*).

Sources: chemd-v0.1-spec.md:131-143

Frontmatter Schema

Every document should include YAML frontmatter with specific required keys:

Key	Type	Description
id	string	Unique document identifier
title	string	Experiment/document title
date	string	ISO format YYYY-MM-DD
render_profile	string	Identifier for the visual style

Sources: chemd-v0.1-spec.md:65-81, packages/parser/src/frontmatter/parse-frontmatter.ts:13-15

Diagnostics System

The repository utilizes a standardized diagnostic system to report issues during parsing and resolution.

Severity	Description	Example Codes
error	Critical issues that may stop processing for a block	E_DUPLICATE_ID, E_MISSING_REQUIRED_FIELD
warning	Non-critical issues where the system can recover	W_UNKNOWN_FIELD, W_UNRESOLVED_REFERENCE
info	Informational messages for the user	I_ADAPTER_APPROXIMATION

Sources: chemd-v0.1-architecture.md:415-430, chemd-render-profile-v0.1-spec.md:144-146

Adherence to these guidelines ensures that the cheMD project remains maintainable as the complexity of chemical rendering and experiment data modeling grows.