Skip to content

CHANGELOG.md

Latest commit

 

History

History
235 lines (184 loc) · 6.49 KB

CHANGELOG.md

File metadata and controls

235 lines (184 loc) · 6.49 KB
Raw

Changelog

All notable changes to Calligrapher will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.1.0] - 2025-10-13

Added

M1 - Core Pipeline:

  • Python function and class extraction with tree-sitter
  • Call graph construction with qualified names
  • Parameter and type annotation extraction
  • Entry point identification
  • JSON export format
  • CLI interface with enrich and languages commands
  • Comprehensive integration test suite (15 tests)
  • Vendored tree-sitter Python grammar (v0.25.9)

M2 - Python Coverage:

  • Import resolution for stdlib and relative imports
  • Class method analysis with inheritance tracking
  • Decorator extraction and preservation
  • Type annotation handling (parameters and returns)
  • Multi-module fixture support
  • 10 additional integration tests

M3 - Enrichment & Query:

  • Cyclomatic complexity computation for all functions/methods
  • Control flow metrics (loop depth, nesting level, branches)
  • Query operations:
    • callers - Find functions that call a target
    • callees - Find functions called by a caller
    • find - Search symbols by name (partial match)
    • path - Find shortest path between functions (BFS)
    • allpaths - Find all paths with depth limit (DFS)
  • DOT export format for GraphViz visualization
  • Mermaid export format for documentation
  • Project-level metrics aggregation with statistics
  • Automatic metrics display after enrichment

M4 - Polish & Release Prep:

  • GitHub Actions CI pipeline with automated testing
  • Performance baseline and benchmarking infrastructure
  • Memory leak audit (zero leaks found)
  • Error handling review (zero panics, fixed unreachable)
  • Complete user documentation (QUICKSTART.md)
  • Complete API documentation (API.md)
  • Release checklist and changelog

Documentation:

  • QUICKSTART.md (824 lines) - Complete user guide
  • API.md (1,000+ lines) - Complete developer reference
  • PERFORMANCE.md (450+ lines) - Performance baseline and scaling
  • MEMORY_AUDIT.md (750+ lines) - Memory safety analysis
  • ERROR_HANDLING_REVIEW.md (600+ lines) - Error handling patterns
  • STATUS.md - Project status tracking
  • PROJECT_PLAN.md - Development roadmap

Infrastructure:

  • Automated CI/CD with GitHub Actions
  • Benchmark script for performance testing
  • Integration test framework
  • Example fixtures for 5 Python patterns

Features

Core Capabilities:

  • Static call graph analysis for Python
  • Tree-sitter based parsing (fast, error-tolerant)
  • Scope-based name resolution
  • Symbol table with qualified names
  • Entry point detection (main functions)

Metrics & Analysis:

  • Cyclomatic complexity (1-5: low, 6-10: moderate, 11-20: high, 21+: very high)
  • Control flow analysis (loop depth, nesting, branches)
  • Project-level statistics (mean, median, std dev, distribution)
  • Top N complex symbols identification

Export Formats:

  • JSON - Structured data for programmatic analysis
  • DOT - GraphViz format with complexity coloring
  • Mermaid - Markdown-embeddable diagrams

Query Operations:

  • Caller/callee analysis
  • Symbol search
  • Path finding (BFS for shortest, DFS for all paths)
  • Depth-limited search (max 10 for safety)

Quality Assurance:

  • Zero memory leaks (comprehensive audit)
  • Zero panics in production code
  • Consistent error handling with clear messages
  • Automated testing on every commit
  • Performance benchmarks established

Technical Details

Architecture:

  • Written in Zig 0.13.0
  • Tree-sitter for parsing (vendored grammar)
  • Modular design with clear layer separation
  • Memory-safe with RAII patterns (defer/errdefer)
  • Linear time complexity for most operations

Tested Configurations:

  • macOS 14+ (Apple Silicon and Intel)
  • Ubuntu 22.04+ (x86_64)
  • Zig 0.13.0

Performance:

  • Small files (<100 LOC): <50ms
  • Medium files (100-1K LOC): 50-200ms
  • Large files (1K-10K LOC): 200ms-2s
  • Memory: <100MB for typical projects

Code Metrics:

  • ~13,000 lines of Zig code
  • 38 source files
  • 50+ tests (unit + integration)
  • 100% of major operations tested

Documentation

User Documentation:

  • Getting started in 5 minutes
  • Complete CLI command reference
  • Complexity metrics interpretation guide
  • Query operation examples
  • Troubleshooting guide
  • Advanced usage patterns

Developer Documentation:

  • Complete API reference for all 8 modules
  • Working code examples (15+)
  • Extension guides (add languages, add formats)
  • Data structure specifications
  • Error handling patterns
  • Memory management guidance

Project Documentation:

  • Performance characteristics and scaling
  • Memory safety analysis
  • Error handling review
  • Project status and milestones
  • Development roadmap

Known Limitations

  • Single-file processing (multi-file in future release)
  • Python-only (Rust, Zig, JS, TS planned)
  • Static analysis only (no dynamic/runtime analysis)
  • Import resolution limited to stdlib and relative imports
  • Query depth limited to 10 for performance

Breaking Changes

None - this is the initial release.

Security

  • No known security vulnerabilities
  • Memory-safe implementation (Zig + manual audit)
  • No unsafe code blocks
  • No panic paths in user-facing code
  • Input validation on all CLI arguments

Contributors

  • Rand Arete (primary developer)
  • Claude Code (development assistance)

Acknowledgments

  • Tree-sitter project for parsing infrastructure
  • Zig project for the programming language
  • Python community for test cases and examples

Version History

[0.1.0] - 2025-10-13

  • Initial release
  • Python call graph analysis
  • Complexity metrics
  • Multiple export formats
  • Query operations

Release Notes Format

Each release includes:

  • Added: New features
  • Changed: Changes to existing functionality
  • Deprecated: Soon-to-be removed features
  • Removed: Removed features
  • Fixed: Bug fixes
  • Security: Security fixes

Upgrade Guide

From: N/A (Initial Release)

To: 0.1.0

This is the initial release. No upgrade necessary.

Future Releases

Planned for 0.2.0

  • Multi-file project analysis
  • Cross-module dependency graphs
  • Package support (init.py)

Planned for 0.3.0

  • Rust language support
  • JavaScript/TypeScript support

Planned for 1.0.0

  • Stable API
  • Production-ready for all features
  • Complete language coverage
  • Performance optimizations

For detailed development history, see STATUS.md For future plans, see PROJECT_PLAN.md