Module Overview

symtrace is structured as a modular Rust binary workspace with clear separation of responsibilities across pipeline components.

Module Breakdown

Module	Responsibilities
`main.rs`	CLI pipeline orchestration, subcommand routing (`git-diff-driver`), execution timing
`cli.rs`	Positional argument defaults, flag definitions (`clap`), command parsing
`config.rs`	Hierarchical `.symtracerc` / `symtrace.toml` TOML configuration loader
`git_layer.rs`	Repository resolution (`libgit2`), dual-path rename extraction, index/worktree diffs
`language.rs`	Extension matching for 9 supported languages/formats
`ast_builder.rs`	Tree-sitter parsing, arena memory allocation (`bumpalo`), resource limit enforcement
`ast_cache.rs`	Two-tier AST cache (in-memory LRU + versioned on-disk storage with limits hash keying)
`incremental_parse.rs`	Bounded `TreeCache` LRU (500 capacity), incremental edit computation
`node_identity.rs`	4-hash BLAKE3 identity computation (structural, content, identity, context)
`tree_diff.rs`	Parallel 5-phase AST node matching algorithm (`rayon`)
`semantic_similarity.rs`	Structural, token edit distance, and complexity similarity calculation
`symbol_tracking.rs`	Deep BFS symbol extraction & cross-file movement tracking
`refactor_detection.rs`	Refactor pattern detection (extract method, move, rename)
`commit_classification.rs`	Commit auto-classification (feature, bugfix, refactor, cleanup, formatting_only)
`pager.rs`	TTY detection and interactive shell pager execution (`$GIT_PAGER` / `$PAGER` / `less -RFX`)
`output.rs`	ANSI color terminal renderer and structured JSON formatter
`types.rs`	Domain data structures, `FileChange` dual-path representations

Data Flow Architecture

cli.rs + config.rs  ──►  git_layer.rs  ──►  ast_builder.rs  ──►  node_identity.rs
                                                                      │
                                                                 tree_diff.rs
                                                                      │
                                                             refactor_detection.rs
                                                                      │
                                                             symbol_tracking.rs
                                                                      │
                                                          commit_classification.rs
                                                                      │
                                                          pager.rs ◄─► output.rs

Design Principles

Zero Unsafe Rust — Enforced at compile-time via #![deny(unsafe_code)].
In-Process Git Integration — Fast repository access via libgit2 (no shell-out overhead).
Parallel Pipeline — Files and AST nodes are compared concurrently using Rayon data parallelism.
Resource Protection — Hard guards on file size, node count, recursion depth, and parse timeouts prevent hangs on malformed or adversarial inputs.