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