Calligrapher

Calligrapher is an experimental static analysis tool written in Zig. The goal is to build enriched call graphs by combining tree-sitter based parsing with a language-agnostic resolution layer. The codebase already contains scaffolding for the core graph types, parser bindings, a Python extractor, and a CLI, but most modules still rely on stubs while we validate the architecture.

Status – October 2025: We are executing the M0 "Codebase Validation" milestone defined in PROJECT_PLAN.md. The immediate focus is on reactivating grammar-independent tests, auditing the tree-sitter bindings, and preparing fixtures for the Python MVP.

Current Capabilities

• Core graph data structures (src/core/) with lifecycle tests.
• Tree-sitter wrapper modules that currently default to a Zig stub runtime while we sort out distribution of native grammars.
• A Python extractor implementation with helper APIs that can be exercised under zig test without a grammar loaded.
• Minimal CLI entry point plus build/test wiring in build.zig.

See STATUS.md for a detailed breakdown of the M0 backlog.

Environment Setup

1. Install Zig 0.13.0 or later.

2. (Optional for now) Install the tree-sitter C library and the Python grammar. The build defaults to a stubbed implementation, but passing -Duse_tree_sitter_stub=false requires the following options:

   zig build -Duse_tree_sitter_stub=false \
     -Dtree_sitter_include=/path/to/tree-sitter/include \
     -Dtree_sitter_lib=/path/to/tree-sitter/lib
   

   The build script will fail fast with a helpful error message if the paths are missing.

3. Clone and build:

   git clone https://github.com/yourusername/calligrapher.git
   cd calligrapher
   zig build
   

Running Tests

The repository ships with several module-level test suites. They run entirely against the stubbed grammar implementation so they pass even before native bindings are available.

zig build test

To exercise a specific module:

zig test src/extractors.zig
zig test src/parser.zig

Fixtures

Fixtures live under examples/. M0 adds a minimal Python project with an accompanying golden call graph snapshot that will anchor future integration tests once the extractor is wired to the real grammar.

examples/
└── python/
    └── minimal/
        ├── project.py
        ├── expected_call_graph.json
        └── README.md

Roadmap & Planning

• PROJECT_PLAN.md – Delivery roadmap and weekly backlog.
• PLAN.md – Architectural context and long-term goals.
• STATUS.md – Live milestone tracking.
• docs/parser_binding_audit.md – Latest review of the tree-sitter bindings.

As milestones close we reconcile these documents to keep onboarding material current.

Contributing

Contributions are welcome! During M0 we are prioritising:

1. Grammar-independent unit tests that run on CI without native dependencies.
2. Documentation updates that reflect the actual state of the repository.
3. Preparatory work for bundling the Python grammar and exporting enriched call graphs.

Please open an issue or PR referencing the relevant milestone item in PROJECT_PLAN.md.

License

Calligrapher is distributed under the MIT License.