figurehead-rs: Instructions file for Codex

AI Development Guidelines

This document provides guidelines for AI agents working on the Figurehead project.

Architecture Overview

Figurehead follows a modular, plugin-based architecture inspired by mermaid.js:

Input → Detector → Parser → Database → Layout → Renderer → Output

Core Components

1. Core Traits (src/core/): Define interfaces for all components

   • Diagram: Main entry point for each diagram type
   • Detector: Identifies diagram types from markup
   • Parser: Parses markup using chumsky
   • Database: Stores nodes, edges, and diagram data
   • LayoutAlgorithm: Arranges elements in coordinate space
   • Renderer: Generates output (ASCII, SVG, etc.)

2. Plugins (src/plugins/): Implementations for specific diagram types

   • Each plugin implements all core traits
   • Currently: flowchart (basic implementation)
   • Future: sequence, class, gantt charts

3. Pipeline: Data flows through stages using the traits

Development Principles

SOLID Principles

• Single Responsibility: Each trait/component has one purpose
• Open/Closed: Extensible through plugins, closed for modification
• Liskov Substitution: All implementations can replace their interfaces
• Interface Segregation: Small, focused traits
• Dependency Inversion: Depend on abstractions, not concretions

Rust Idioms

• Use match, iterators, and &[Type] instead of Vec where possible
• Prefer Result<T, E> over exceptions
• Use trait objects (dyn Trait) for runtime polymorphism
• Leverage zero-cost abstractions and compile-time guarantees

Test-Driven Development (TDD)

1. Write failing tests first
2. Implement minimal code to make tests pass
3. Refactor while maintaining test coverage
4. Use property-based testing for complex logic

Implementation Guidelines

When Adding New Diagram Types

1. Create Plugin Structure:

   // src/plugins/newtype/mod.rs
   pub struct NewTypeDiagram;
   
   impl Diagram for NewTypeDiagram {
       type Database = NewTypeDatabase;
       type Parser = NewTypeParser;
       type Renderer = NewTypeRenderer;
       // ... implement all methods
   }