@immediate-diagram/parser

DSL grammar, parser (text → AST), and AST validation for the Immediate Diagram Language (IDL).

Supports all 7 diagram types: flowchart, sequence, architecture, pie, donut, block, venn.

Usage

Basic Parsing

import { parse, parseOrThrow } from "@immediate-diagram/parser";

// Result-based API (recommended)
const result = parse('flowchart\ntitle "My Flow"\nA --> B');
if (result.ok) {
  console.log(result.value.diagramType); // "flowchart"
  console.log(result.value.title); // "My Flow"
  console.log(result.value.statements); // [EdgeStatement { from: "A", to: "B", ... }]
} else {
  console.error(result.error.message);
  console.error(result.error.location); // { start: { line, column }, end: { line, column } }
}

// Throw-based API (convenience)
const doc = parseOrThrow('sequence\nactor User\nactor API\nUser -> API: "Request"');
console.log(doc.diagramType); // "sequence"

Semantic Validation

import { parseOrThrow, validate } from "@immediate-diagram/parser";

const doc = parseOrThrow('flowchart\nactor User'); // parses OK (grammar is context-free)
const result = validate(doc);
console.log(result.valid); // false
console.log(result.errors[0].message); // "ActorDeclaration is only valid in sequence diagrams"
console.log(result.errors[0].code); // "wrong-context"

Error Recovery (Multi-Error Collection)

import { parseWithRecovery, formatErrorReport } from "@immediate-diagram/parser";

const input = `flowchart
A --> B
~~~ invalid line
C --> D
??? another bad line`;

const result = parseWithRecovery(input);
console.log(result.errors.length); // 2
console.log(result.document?.statements.length); // 2 (recovered A-->B and C-->D)
console.log(result.skippedLines); // [3, 5]

// Format for LLM consumption
console.log(formatErrorReport(result, input));

Error Enhancement

import { parse, enhanceError } from "@immediate-diagram/parser";

const input = "flowcart\nA --> B"; // typo in "flowchart"
const result = parse(input);
if (!result.ok) {
  const enhanced = enhanceError(result.error, input);
  console.log(enhanced.suggestion); // 'Did you mean "flowchart"? Found "flowcart".'
}

Supported Diagram Types

| Type | Keyword | Key Constructs | |------|---------|----------------| | Flowchart | flowchart | 10 node shapes, 6 edge types, direction, inline nodes | | Sequence | sequence | actors, messages, notes, activation, alt/loop/opt/par | | Architecture | architecture | groups, components, connections | | Pie Chart | pie "title" | labeled data entries ("label": value) | | Donut Chart | donut "title" | same as pie, different rendering | | Block Diagram | block "title" | nested blocks (brace/indent), cross-level edges | | Venn Diagram | venn "title" | sets, intersections via & operator |

State System

All diagram types support the state/animation system:

@state active "Active State"
  NodeA { fill: green, glow: true }
  NodeB { fill: yellow }

@transition default -> active
  duration: 1.5s
  easing: ease-in-out

@timeline "Demo"
  default -> active: 2s
  active -> default: 1s

API Reference

parse(input: string): Result<Document, ParseError>

Parse IDL text into a typed AST. Returns a Result — either { ok: true, value: Document } or { ok: false, error: ParseError }.

parseOrThrow(input: string): Document

Parse IDL text, throwing an Error on failure. Convenience wrapper around parse().

validate(ast: Document): ValidationResult

Semantic validation of a parsed AST. Checks diagram-type-specific rules (e.g., actors only in sequence diagrams). Returns { valid, errors, warnings }.

parseWithRecovery(input: string, maxErrors?: number): RecoveryParseResult

Parse with line-skipping error recovery. Collects up to maxErrors (default: 10) errors and returns a partial AST with all recoverable statements.

enhanceError(error: ParseError, input: string): RecoveryParseError

Enhance a parse error with actionable suggestions (typo corrections, common mistakes).

formatErrorReport(result: RecoveryParseResult, input: string): string

Format recovery errors into a structured message suitable for LLM consumption.

Performance

All diagram types parse 500-line documents in under 3ms (P95 warm). Target: < 10ms.

Development

# Build grammar (generates imd.js + imd.d.ts from imd.peggy)
bun run build

# Run tests
bun test

# Run benchmarks
bun run bench

# Generate benchmark fixtures
bun run bench:generate