Auspex

Behavioral Code Analysis & Interactive Hotspot Treemap for Visual Studio Code

📖 Overview

Most software metrics focus solely on static complexity (like Lines of Code or cyclomatic complexity). However, complex code that rarely changes is usually safe and stable. The real risk lies at the intersection of high complexity and high change frequency (Git churn) with frequent bugfixes.

Auspex brings behavioral code analysis directly into your editor:

• It automatically analyzes your workspace's Git repository and AST code structure.
• It calculates churn rates, defect frequencies, and code growth.
• It visualizes your codebase as an interactive, hierarchical Treemap where you can immediately identify true technical debt and high-risk hotspots.

✨ Features

🗺️ Interactive Hierarchical Treemap

• Deep Zoom & Hierarchy: Explore your project from folder level down to individual files, classes, and methods/functions.
• Breadcrumb Navigation: Click any box to zoom in; use the breadcrumbs at the top to navigate back up.
• Source Code Filter: Toggle between all repository files and source-code-only files with a single click.
• Top-N Limits: Filter views to Top 50, Top 100, Top 250, or show all elements.

🔥 Behavioral Hotspot Detection

• Combines Git commit churn with defect frequency (fix:, bug:, etc., or Jira bug tickets).
• Highlights risky areas using a clear thermal gradient:
  • 🟢 Green: Stable, low-risk code.
  • 🟡 Yellow: Moderate activity or complexity.
  • 🔴 Red: Critical hotspots (frequently modified files with repeated bugfixes).

🎨 Multi-Dimensional Visual Encodings

Switch sizing and coloring dimensions dynamically in the top bar:

• Box Size:
  • LOC (Lines of Code)
  • Commits (Total commit frequency)
  • Bugfixes (Number of bugfix commits)
  • +Lines (Lines added churn)
• Box Color:
  • Fehler-Hotspot / Defect Hotspot (Defect ratio × Churn score)
  • Git Churn (Relative change frequency)
  • Code-Wachstum / Code Growth (Net growth ratio)
  • Aktualität / Freshness (Recency of the latest change)
• Timeframe Filtering (Zeitraum):
  • Instantly recalculate all metrics and rescale heatmap colors within a selected time window:
  • All time (All), 1 week, 1 month, 6 months, 1 year, or 2 years.

⚡ Direct Editor Navigation & Git Diff Inspection

• Jump to Code: Click any file, class, or method in the Treemap to jump directly to that exact line in the VS Code editor.
• Commit History & Diffs:
  • View full commit history in the side panel with author, timestamp, and commit message.
  • Open Git diffs for any commit directly in the editor with one click.
  • Set as Base: Mark any commit as a base commit to compare any other commit against it in a side-by-side diff.
  • Filter Bugfixes: Toggle between all commits and bugfix-only commits.

👥 Contributor & Knowledge Map

• See author breakdown for every file and method.
• Color-coded avatars and commit percentages to understand code ownership and identify knowledge silos.

🎫 Optional Read-Only Jira Integration

• Automatically extracts Jira ticket keys (e.g. PROJ-123) from Git commit messages.
• Resolves ticket types (Bug, Defect, Story, Task, etc.) via Jira REST API.
• Automatically marks Jira-verified bugs as defect fixes (isFix = true) to enhance hotspot accuracy.
• Renders clickable Jira badges on commit cards that open the ticket in your browser.
• 100% Optional & Secure: Disabled by default; credentials stored securely in your OS Keychain via vscode.SecretStorage.

🌍 Bilingual Interface

• Fully localized in Deutsch and English.
• Respects your VS Code language preference automatically, with manual toggle option.

🚀 Getting Started

Installation

From GitHub Releases (VSIX)

1. Download the latest .vsix file from Releases.
2. In VS Code, open the Extensions view (Cmd+Shift+X / Ctrl+Shift+X).
3. Click the ... menu in the top right and select Install from VSIX....
4. Choose the downloaded .vsix file.

Opening Auspex

1. Open any Git repository workspace in VS Code.
2. Click the Auspex icon in the Activity Bar on the left.
3. Click Auspex: Open Hotspot Treemap or use the Command Palette (Cmd+Shift+P / Ctrl+Shift+P).

⌨️ Commands

Auspex contributes the following commands to the VS Code Command Palette:

⚙️ Configuration

You can customize Auspex in VS Code Settings (Cmd+, / Ctrl+, → search for auspex):

🔒 Security & Privacy

• Local Execution: All code parsing, AST extraction, and Git analysis run 100% locally on your machine.
• Zero Telemetry: No code snippets, metrics, or personal data are collected or sent to external servers.
• Keychain Security: Jira tokens are stored exclusively via vscode.SecretStorage (macOS Keychain, Windows Credential Manager, or Linux Secret Service), never in plain text or .git.
• Read-Only: Jira integration only performs GET requests and will never create, edit, or delete any tickets.

🛠️ Development & Releases

Prerequisites

• Node.js 20+
• npm 10+

Setup & Build

# Install dependencies
npm install

# Run unit tests (Vitest)
npm test

# Build extension (esbuild) and webview (Vite)
npm run build

# Watch mode for extension development
npm run watch

Creating a Release

Auspex includes an interactive release manager:

./release.sh
# or specify the version directly:
./release.sh 0.3.0

This runs tests, creates production bundles, bumps the version in package.json, tags the commit, and pushes to GitHub where the GitHub Action automatically packages and attaches the .vsix file to the GitHub Release.

📄 License

This project is licensed under the MIT License.