Pikru Codebase Organization

Top-Level Structure

• •src/ - Main pikru library (parsing and rendering)
• •crates/ - Supporting crates
• •vendor/pikchr-c/ - Original C implementation and test files
• •examples/ - Example programs
• •tests/ - Integration tests

Main Library (src/)

Entry Point

• •src/lib.rs - Public API, exports key types and functions

Parsing

• •src/parse.rs - Parser implementation (statement parsing, token handling)
• •src/ast.rs - AST types (Statement, Expr, ObjectClass, etc.)
• •src/types.rs - Core types (ClassName, Direction, EdgePoint, etc.)

Rendering

• •src/render/mod.rs - Main renderer logic
  • •Object placement and geometry
  • •Text positioning (ljust/rjust logic at lines 1265-1550)
  • •Variable scope and context management
• •src/render/eval.rs - Expression evaluation (positions, scalars, variables)
• •src/render/svg.rs - SVG generation (converts shapes to SVG elements)
• •src/render/geometry.rs - Shape geometry (boxes, circles, paths, files)
• •src/render/shapes.rs - Shape rendering (specific shape implementations)
• •src/render/types.rs - Render types (PObject, Style, PositionedText, etc.)
• •src/render/path_builder.rs - Path construction (line/arrow building)
• •src/render/context.rs - Render context (variable scopes, state)
• •src/render/defaults.rs - Default values (line width, font size, etc.)

Error Handling

• •src/errors.rs - Error types and reporting
• •src/macros.rs - Helper macros

Supporting Crates

crates/pikru-compare/

SVG comparison utilities for testing

• •src/lib.rs - Core comparison logic
  • •compare_outputs() - Main comparison function
  • •CompareResult::is_match() - Determines if test passes
  • •Handles error matching, SVG parsing, tolerance
• •Used by: test harness, MCP server

crates/pikru-mcp/

MCP server for test running

• •src/tools.rs - MCP tool implementations
  • •run_pikru_test() - Run single test, returns comparison
  • •list_pikru_tests() - List available tests
  • •debug_pikru_test() - Run with trace output
• •src/main.rs - MCP server entry point

Test Files

Location

vendor/pikchr-c/tests/*.pikchr - Test input files from C implementation

Categories

• •test01-test81 - Numbered feature tests
• •autochop*.pikchr - Arrow chopping tests
• •Other specialized tests

Common Debugging Paths

Text Positioning Issues

1. •Check src/render/mod.rs:1265-1550 - ljust/rjust calculation
2. •Check src/render/svg.rs:294 - Text anchor assignment
3. •Check src/render/types.rs - PositionedText structure

Rendering Issues

1. •Check src/render/shapes.rs - Shape-specific rendering
2. •Check src/render/geometry.rs - Geometric calculations
3. •Check src/render/svg.rs - SVG element generation

Parsing Issues

1. •Check src/parse.rs - Parser logic
2. •Check src/ast.rs - AST node definitions

Test Comparison Issues

1. •Check crates/pikru-compare/src/lib.rs - Comparison logic
2. •Check tolerance constants (FLOAT_TOLERANCE, SIMILARITY_THRESHOLD)

Key Code References (cref comments)

Many functions include // cref: comments pointing to the original C implementation:

• •Format: // cref: function_name (pikchr.c:line_number)
• •Use these to cross-reference with C implementation when debugging