npm package: @immediate-diagram/parser
Description: DSL grammar, parser (text → AST), and AST validation for the Immediate Diagram Language (IDL).
Latest version: 1.2.3

# @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

```typescript
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

```typescript
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)

```typescript
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

```typescript
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

```bash
# 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
```