Self-Hosting

Paradox defines its own AST (Abstract Syntax Tree) in Paradox. The AST definition in lib/dox/ast/ is compiled by Paradox itself to generate TypeScript types used by the paradox-node server.

AST Source Files

The self-hosted AST is split across several .dox files in lib/dox/ast/:

File Contents

foundation.dox

SrcSpan (source locations), Annotated ann a (annotation wrapper)

primitive.dox

Primitive type identifiers and variables

type.dox

Type system: TypeInstance, TypeVar, TypeIdentifier, Kind

expression.dox

Expression AST: Expression ann, Case ann, CasePattern, operators

term.dox

Term-level identifiers

declaration.dox

Top-level declarations: Product, Union, Wrap, Const, Interface, Instance, Valid, Illuminate, Matrix, Import, Main, Declaration, Specification

Key Types

The Declaration union captures every top-level construct:

union Declaration ann
  dImport: Import ann
  dProduct: Product ann
  dUnion: Union ann
  dWrap: Wrap ann
  dMain: Main ann
  dMatrix: Matrix ann
  dConst: Const ann
  dInterface: Interface ann
  dInstance: Instance ann

A Specification is a list of commented declarations:

wrap Specification ann: [Commented ann (Declaration ann)]

Everything is parameterized over an annotation type ann — typically SrcSpan for real source files or () for tests.

How Self-Hosting Works

  1. The AST .dox files define types like Product ann, Union ann, Expression ann

  2. Paradox compiles these using paradox generate --typescript --spec

  3. The generated TypeScript types are used by node/src/ for the paradox-node server

  4. The node/src/types.ts file imports from the generated AST: import type { Product, Union } from "../dox/.dox/std/ast"

Regenerating the AST

When the AST definition changes:

nix run .#regenerate-ast

This recompiles the .dox AST files and regenerates the TypeScript output used by the Node.js server.

The Annotation Pattern

The Annotated ann a type is the core mechanism for tracking source positions:

type Annotated ann a
  annotation: ann
  unannotated: a

Every node in the AST is wrapped in Annotated ann to carry source location information for error reporting. This pattern allows the same AST to be used with or without source spans.

See Also

  • Spec Output — Exporting the typed AST as JSON

  • Types — Parametric types used throughout the AST