codebase-layout

name	codebase-layout
description	Codebase organization for pikru. Use when you need to find where specific functionality lives.

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