Module Overview

symtrace v0.5.0 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 (`lint`, `tui`, `merge-driver`, `git-diff-driver`), execution timing
`cli.rs`	Positional argument defaults, flag definitions (`clap`), command parsing (`--compact`, `--full-headers`, `--format prompt`)
`config.rs`	Hierarchical `.symtracerc` / `symtrace.toml` TOML configuration loader
`git_layer.rs`	Single-handle shared reader (`SharedBlobReader`), `libgit2` rename hints (`find_similar()`), diff delta extraction
`language.rs`	Extension matching for 13 supported languages/formats (Rust 2024, C#, Ruby, PHP, TSX, etc.)
`ast_builder.rs`	Tree-sitter parsing, `BumpaloRecycler` thread-local arena pool, resource limit enforcement
`ast_cache.rs`	Two-Tier Content-Addressed Storage (CAS) diff cache (`DiffCacheKey`), 16-shard `RwLock` LRU, atomic disk storage
`incremental_parse.rs`	Bounded `TreeCache` LRU, subtree diff-window edit computation
`node_identity.rs`	4-hash BLAKE3 identity computation, 64-bit token bitset (`token_bitset`), and 16-bin SIMD frequency histograms
`tree_diff.rs`	6-stage AST matching engine, parallel Rayon global candidate indexing (`GlobalNodeIndex`)
`call_graph.rs`	Cross-file function call DAG extraction and transitive BFS downstream blast radius calculation
`data_flow.rs`	Intra-procedural def-use variable lineage verification separating renames from logic mutations
`semantic_type.rs`	Safety contract & guard violation detector (null checks, bounds guards, mutex locks, resource cleanup)
`query_dsl.rs`	Tree-Sitter `.scm` query compiler and declarative linter engine (`symtrace lint`)
`semantic_similarity.rs`	AVX2/SSE SIMD token multiset Jaccard, structural shape, displacement penalty, and complexity delta
`symbol_tracking.rs`	Deep BFS symbol extraction & hash-bucket cross-file movement tracking
`refactor_detection.rs`	Refactor pattern detection (extract method, cross-file move, rename)
`commit_classification.rs`	Commit auto-classification (`feature`, `bugfix`, `refactor`, `cleanup`, `formatting_only`)
`tui.rs`	Interactive terminal UI workspace (`ratatui` & `crossterm`), split-pane refactor view, blast radius visualizer
`merge_driver.rs`	3-way AST semantic merge engine with scope splicing and tree-sitter validation re-parsing (`has_ast_errors()`)
`pager.rs`	TTY detection and shell pager execution (`$GIT_PAGER` / `$PAGER` / `less -RFX`)
`output.rs`	Multi-format rendering engine emitting ANSI (standard & micro-compact), Prompt (LLM), JSON, JSONL, Markdown, HTML, SARIF
`types.rs`	Domain data structures, `FileDiff`, `FileChange` dual-path representations

Data Flow Architecture

cli.rs + config.rs  ──►  git_layer.rs (SharedBlobReader) ──► ast_cache.rs (Two-Tier CAS)
                                                                    │
                                                            ast_builder.rs (BumpaloRecycler)
                                                                    │
                                                            tree_diff.rs (6-Stage Matching)
                                                                    │
                                                      ┌─────────────┼─────────────┐
                                                      ▼             ▼             ▼
                                                 call_graph.rs semantic_type.rs query_dsl.rs
                                                      │             │             │
                                                      └─────────────┼─────────────┘
                                                                    ▼
                                                            tui.rs / merge_driver.rs / output.rs

Design Principles

Zero Unsafe Rust: Enforced at compile-time via #![deny(unsafe_code)].
Two-Tier CAS Diff Caching: Precomputed DiffCacheKey returns warm diff records in under 0.004 ms.
SIMD Multiset Jaccard: Hardware-vectorized token histograms accelerate candidate scoring.
Adaptive Granularity: Automatically matches output density to changeset size, lifting NSR to +85.9%.
Cross-File Blast Radius: Call graph DAG analysis surfaces downstream impact before production deployments.
Safety Invariant Enforcement: Identifies stripped concurrency locks, deleted bounds checks, and removed null guards.