Introduction

symtrace is a deterministic, AST-based semantic diff engine for Git, written in Rust. Instead of comparing lines of text like standard git diff, it parses code structure with Tree-sitter and tells you what semantically changed: which functions were moved, renamed, modified, inserted, or deleted.

━━━ src/handler.rs
  + [INSERT] function_item 'handle_request' inserted (L42)
  ~ [MODIFY] function_item 'parse_body' modified (L10 -> L10) [75% similarity, medium]
  ✎ [RENAME] function_item renamed from 'process' to 'execute' (L5 -> L5) [98% similarity, low]
  - [DELETE] function_item 'deprecated_fn' deleted (L88)
  ↔ [MOVE]   function_item 'helper' moved (L20 -> L35) [100% similarity, low]
  ── Refactor Patterns ──
    ▸ 'process' renamed to 'execute' (confidence: 100%)

Why not just use git diff?

git diff operates at the plain text line level. It is fast, but structurally blind:

• Formatting & Whitespace Noises: Code reformatting or comment edits generate noisy line diffs, masking real changes.
• Relocated Functions: Moving a function to another position or file shows up as a complete deletion and insertion.
• Renames: Renaming a variable or method looks identical to rewriting the implementation.
• Refactor Blindness: Extracting a method or moving code across files cannot be verified automatically.

What symtrace does instead

symtrace parses source code into Concrete Syntax Trees (CST/AST), computes 4-hash BLAKE3 fingerprints for node identity, and executes a 6-stage matching algorithm to isolate structural operations:

Operation	Symbol	What it means
MOVE	↔ [MOVE]	Code block or entity was relocated without logical modification
RENAME	✎ [RENAME]	An entity name was changed while preserving structure
MODIFY	~ [MODIFY]	The body or structure of an entity was modified
INSERT	+ [INSERT]	A new syntactic entity was introduced
DELETE	- [DELETE]	An existing syntactic entity was removed

Each operation includes similarity metrics (structural and token similarity percentages) and change intensity levels (low, medium, high).

Key Capabilities in v0.5.0

• Adaptive Granularity Controller: Automatically switches between MicroCompact (--compact 1-3 line inline token changes), Standard, and FullStructural views, lifting Noise Suppression Ratio (NSR) to +85.9%.
• Cross-File Call Graph & Blast Radius: Constructs repository call graph DAGs to trace impacted downstream callers up to depth 5 across file boundaries when signatures change.
• Contract & Safety Guard Alerts: Detects critical security regressions: removed null/nil checks, deleted bounds guards, stripped mutex concurrency locks, or omitted resource cleanup.
• Declarative AST Semantic Linter (symtrace lint): Evaluates custom Tree-sitter .scm rules with severity tiers (ERROR, WARN, INFO), message templates, and automated CI failure thresholds (--max-warnings 0).
• LLM Context Optimization (--format prompt): Ultra-dense serialization reducing token consumption by 80% for AI coding assistants (Gemini, Claude, GPT).
• Two-Tier CAS Caching & SIMD Acceleration: Precomputed Content-Addressed Storage diff results returning warm diff records in under 0.004 ms alongside 16-bin SIMD token multiset Jaccard acceleration.
• 13 First-Class Languages & Formats: Full AST parsing support for Rust (2021 & 2024 Edition), JavaScript, TypeScript, TSX/JSX, Python, Java, C, C++, Go, C#, Ruby, PHP, and JSON.
• Interactive TUI Inspector (symtrace tui): Keyboard-driven terminal workspace built with ratatui featuring split-pane refactor navigation, symbol search, and call graph visualization.
• 3-Way AST Semantic Merge Driver (symtrace merge-driver): Native git merge-driver with AST scope splicing and tree-sitter validation re-parsing (has_ast_errors()) for zero-conflict rebases.
• White-Mode HTML & PDF Export: Generates standalone white-mode reports (symtrace_report.html) complete with a Print / Save PDF button and cryptographic BLAKE3 digital signatures.

Guarantees & Security

• Deterministic: Identical code inputs always produce identical diff operations across platforms.
• Zero Unsafe Rust: Strictly enforced via #![deny(unsafe_code)].
• Fully Offline: Zero network calls, zero telemetry, zero analytics.
• Signed Release Attestations: Build artifacts are keylessly signed via Sigstore/Cosign OIDC with SPDX SBOMs (symtrace.spdx.json) and GitHub Artifact Attestations.