Symtrace for VS Code

Semantic diff viewer powered by AST analysis. Compare Git commits to see what semantically changed — functions moved, renamed, modified, inserted, or deleted — rather than just which lines changed.

Built on the symtrace CLI engine (Rust).

Features

• Semantic Operations — See MOVE, RENAME, MODIFY, INSERT, DELETE at the AST node level
• Side-by-side Diff — Click any operation to see old vs new file content in VS Code's diff editor
• Commit Classification — Automatic labeling (feature, bugfix, refactor, cleanup, formatting_only, mixed)
• Cross-file Tracking — Detect symbols that move or rename across files
• Refactor Detection — Identify extract method, move method, rename variable patterns
• Similarity Scoring — Per-operation similarity percentage with intensity rating (low/medium/high)
• Inline Decorations — See semantic annotations ([INSERTED], [DELETED], etc.) directly in your editor
• Logic-only Mode — Ignore comment and whitespace changes with --logic-only
• Performance Metrics — View parse time, diff time, and node counts in the sidebar
• Full Webview Report — Interactive HTML diff report with collapsible file cards and CSP enforcement
• Activity Bar Integration — Dedicated Symtrace panel in the VS Code sidebar with welcome view
• Git Commit Picker — Interactive QuickPick UI for selecting commits from your git history
• Auto-download Binary — 4-tier binary resolution with automatic GitHub releases download
• Cancellable Analysis — Progress notification with cancellation support during analysis

Supported Languages

Getting Started

1. Install the extension from the VS Code Marketplace
2. Open a Git repository in VS Code
3. Click the Symtrace icon in the Activity Bar (left sidebar)
4. Click "Compare Two Commits" or "Compare Commit with Parent" in the welcome view
5. Select commits from the picker
6. View results:
   • Sidebar tree — Browse operations by file, see summary, classification, refactor patterns, cross-file events, and performance
   • Diff view — Click any operation to see side-by-side file diff
   • Webview panel — Full interactive report opens automatically
   • Inline decorations — Annotations appear in the editor gutter

Requirements

The symtrace CLI binary is required. The extension resolves it using a 4-tier strategy:

You can also install manually:

cargo install symtrace

Platform Support

Auto-download supports the following targets:

Extension Settings

Commands

How It Works

Symtrace uses tree-sitter to parse source files into ASTs, then applies a 5-phase matching algorithm with BLAKE3 hashing to identify semantic changes:

1. Exact hash match — Identical subtrees (move detection)
2. Structural match — Same shape, different content (renames/modifications)
3. Similarity scoring — Composite similarity with complexity analysis
4. Leftover old nodes — Unmatched old nodes become deletes
5. Leftover new nodes — Unmatched new nodes become inserts

This produces deterministic, meaningful diffs that understand code structure rather than treating files as flat text.

Architecture

VS Code Extension (v0.2.0)
       │
       ├── extension.ts         ← Activation, command registration
       ├── binary.ts            ← 4-tier binary resolution + GitHub auto-download
       ├── runner.ts            ← Spawns symtrace CLI, parses JSON output
       ├── config.ts            ← Reads VS Code settings → CLI flags
       ├── commitPicker.ts      ← Git log QuickPick UI (two commits / with parent)
       ├── decorations.ts       ← Inline editor annotations (5 color-coded types)
       ├── gitContentProvider.ts ← TextDocumentContentProvider for diff views
       ├── treeview/
       │   ├── SymtraceTreeProvider.ts  ← TreeDataProvider for sidebar
       │   └── treeItems.ts             ← Node classes (summary, file, op, etc.)
       └── webview/
           └── DiffPanel.ts     ← Full HTML report with CSP nonce

Release Notes

0.2.0

• Activity bar integration with dedicated Symtrace panel and welcome view
• Full webview report with collapsible file cards and similarity bars
• Inline editor decorations for semantic operations (5 color-coded types)
• Git commit picker with branch/tag support (two commits or with parent)
• Auto-download binary from GitHub releases with cross-platform archive extraction
• Side-by-side diff view via git show content provider
• Content Security Policy enforcement in webview (nonce-based)
• Tree view with classification badge, summary, file nodes, cross-file events, and performance

0.1.0

• Initial release with basic commit comparison

License

MIT