core-development

Core Package Development

The core package (packages/core/) is dependency-free and handles all DSL processing.

Data Flow

DSL (YAML input) → validate() → normalize() → IR → diff() → Patch

Key Files

File	Purpose	Exports
types.ts	Type definitions	DSL*, IR*, Patch, WebSocket protocol
validate.ts	YAML validation	validate(dsl): ValidationResult
normalize.ts	DSL → IR conversion	normalize(dsl): IRDocument
diff.ts	IR diff calculation	diff(prev, next): Patch

Type Hierarchy

DSL Types (user input)      IR Types (normalized)
─────────────────────       ────────────────────
DSLDocument                 IRDocument
  ├─ version: number          ├─ version: number
  ├─ docId: string            ├─ docId: string
  ├─ title?: string           ├─ title: string
  ├─ nodes: DSLNode[]         ├─ nodes: Record<string, IRNode>
  └─ edges?: DSLEdge[]        └─ edges: Record<string, IREdge>

DSLNode                     IRNode
  ├─ id: string               ├─ id: string
  ├─ provider: string         ├─ provider: string
  ├─ kind: string             ├─ kind: string
  ├─ label?: string           ├─ label: string (default: id)
  ├─ parent?: string          ├─ parent: string | null
  └─ layout: DSLLayout        └─ layout: { x, y, w, h }

DSLEdge                     IREdge
  ├─ id: string               ├─ id: string
  ├─ from: string             ├─ from: string
  ├─ to: string               ├─ to: string
  └─ label?: string           └─ label: string (default: "")

Patch Operations

type PatchOp =
  | { op: "upsertNode"; node: IRNode }
  | { op: "removeNode"; id: string }
  | { op: "upsertEdge"; edge: IREdge }
  | { op: "removeEdge"; id: string };

interface Patch {
  baseRev: number;
  nextRev: number;
  ops: PatchOp[];
}

WebSocket Protocol Types

// Plugin → CLI
interface HelloMessage {
  type: "hello";
  docId: string;
  secret?: string;
}

interface RequestFullMessage {
  type: "requestFull";
  docId: string;
}

// CLI → Plugin
interface FullMessage {
  type: "full";
  rev: number;
  ir: IRDocument;
}

interface PatchMessage {
  type: "patch";
  baseRev: number;
  nextRev: number;
  ops: PatchOp[];
}

interface ErrorMessage {
  type: "error";
  message: string;
}

Development Workflow

1. Modify types → Update types.ts
2. Update validation → Ensure validate.ts catches invalid input
3. Update normalization → Handle new fields/defaults in normalize.ts
4. Update diff → Handle new patch scenarios in diff.ts
5. Add tests → Co-located *.test.ts files
6. Run tests → bun test packages/core/

Testing

# All core tests
bun test packages/core/

# Specific test file
bun test packages/core/src/diff.test.ts
bun test packages/core/src/validate.test.ts
bun test packages/core/src/normalize.test.ts

# Watch mode
bun test --watch packages/core/

Common Patterns

Adding a new node property

1. Add to DSLNode and IRNode in types.ts
2. Add validation in validate.ts
3. Add default value handling in normalize.ts
4. Update diff logic if property affects equality
5. Add test cases for validation, normalization, and diff

Adding a new edge property

1. Add to DSLEdge and IREdge in types.ts
2. Add validation in validate.ts
3. Add default value handling in normalize.ts
4. Update diff logic for edge equality check
5. Add test cases