StackVet (stackvet)

Universal Project Health & Static Diagnostics Engine
Rigorously examine, inspect, and evaluate modern polyglot application stacks for health, safety, concurrency hazards, and architectural soundness in milliseconds.

Table of Contents

• Overview
• Key Features
• Installation
• Quick Start
• CLI Command Guide
  • stackvet doctor (aliases: diagnose, health)
  • stackvet check (aliases: scan, audit)
  • stackvet inspect (aliases: examine, details)
  • stackvet explain
  • stackvet fix (aliases: remediate, auto-fix)
  • stackvet graph (aliases: architecture, dependencies)
  • stackvet baseline
  • stackvet init (alias: setup)
  • stackvet rules (aliases: catalog, list-rules)
• Diagnostic Rules Catalog (132 Rules)
  • Python Dependency Rules (DEP-xxx)
  • Node Dependency Rules (NDEP-xxx)
  • Import & Architecture Rules (IMP-xxx, ARC-xxx)
  • Environment & Drift Rules (ENV-xxx)
  • Docker Rules (DOC-xxx)
  • FastAPI Framework Rules (FAP-xxx)
  • SQLAlchemy Rules (SQL-xxx)
  • Django Rules (DJG-xxx)
  • Celery Rules (CEL-xxx)
  • React & Next.js Rules (RCT-xxx, NXT-xxx)
• Output Formats
• CI/CD Integration
• Publishing to npm & PyPI
• Architecture & Workspace Structure
• Contributing
• License

Overview

Modern software applications are polyglot by nature: Python backends (FastAPI, Django), Node/TypeScript frontends (React, Next.js), Docker containers, and CI/CD pipelines.

When applications break, developers often suffer from alert fatigue—facing dozens of disconnected warnings across different linters that fail to identify the single underlying root cause.

StackVet bridges this gap:

1. Parallel Static Analysis: Uses Rust with ruff_python_parser and oxc_parser to inspect ASTs without running user code.
2. Cross-Layer Drift Detection: Detects mismatches between local environments, package manifests, lockfiles, Docker images, and CI matrix definitions.
3. Correlation Engine: Groups individual symptoms into concise Root Cause Clusters.
4. Health Score & Grade: Produces an actionable 0–100 health score with letter grades (A through F).
5. Format-Preserving Auto-Fixes: Injects missing dependencies into pyproject.toml or package.json preserving user comments and indentation using toml_edit.

Key Features

• Blazing Fast: Native Rust engine with Rayon parallel processing; analyzes multi-thousand-file repositories in milliseconds.
• AST-Level Accuracy: Direct AST traversal eliminating regex false positives.
• Circular Dependency Detection: Detects import cycles using Tarjan's Strongly Connected Components (SCC) algorithm.
• Zero-Config Discovery: Automatically discovers pyproject.toml, requirements.txt, uv.lock, package.json, pnpm-lock.yaml, Dockerfiles, and GitHub workflows.
• Enterprise Reporting: Outputs rich terminal tables, machine-readable JSON, OASIS SARIF v2.1.0 for GitHub Code Scanning, and standalone responsive dark-mode HTML reports.

Installation

Via Cargo (Rust)

cargo install stackvet

Via uv / pip (Python)

# Run instantly with uvx (no install required):
uvx stackvet doctor

# Or install with pip / pipx:
pip install stackvet
# or
pipx install stackvet

Via npm / npx (Node.js)

# Run instantly with npx:
npx stackvet doctor

# Or install in your project:
pnpm add -D stackvet
# or
npm install --save-dev stackvet

Quick Start

Run a full project health check in your repository root:

stackvet doctor

Output:

=======================================================================
                StackVet Universal Project Health Report               
=======================================================================

  Health Score: 92 / 100
  Overall Grade: A (Healthy)

  Critical: 0  |  Errors: 0  |  Warnings: 2

--- Root Cause Clusters (1) ---
1. [WARN] Environment, Lockfile & Runtime Drift
   Summary: Detected 1 discrepancy(ies) between local manifests, Docker, CI matrix, or lockfiles.
   Remediation: Align runtime version declarations across pyproject, package.json, Dockerfile, and CI workflows.
   Symptoms Count: 1

CLI Command Guide

All subcommands support positional path arguments (e.g. stackvet doctor ./backend) as well as the global -p / --path option.

stackvet doctor (aliases: diagnose, health)

Runs a comprehensive health check, aggregates symptoms into root causes, and assigns a health grade (A–F).

# Run on current directory
stackvet doctor

# Run on a target directory (positional or -p)
stackvet doctor ./backend
stackvet -p ./services/api doctor

# Using intuitive aliases
stackvet health ./backend
stackvet diagnose

# Fail CI with exit code 1 if health score is below 85
stackvet doctor --min-score 85

# Output in standalone HTML report
stackvet --format html doctor > health-report.html

stackvet check (aliases: scan, audit)

A fast gate optimized for pre-commit hooks and CI pipelines. Returns exit code 0 if clean, or 1 if errors are detected.

# Normal check (fails only on ERROR and CRITICAL)
stackvet check ./backend
stackvet scan ./backend

# Strict mode (fails on WARNINGS as well)
stackvet check --strict
stackvet audit --strict

# Output machine-readable JSON in CI
stackvet --format json check

stackvet inspect (aliases: examine, details)

Deep diagnostics inspection displaying code locations, snippets, severity, and targeted remediation guides.

# Inspect all detected diagnostics
stackvet inspect ./backend
stackvet examine ./backend

# Filter diagnostics by rule category prefix:
stackvet inspect --rule FAP   # Only FastAPI rules
stackvet inspect --rule SQL   # Only SQLAlchemy rules
stackvet inspect --rule DOC   # Only Docker rules
stackvet inspect --rule RCT   # Only React rules

stackvet explain

Displays in-depth documentation, potential runtime consequences, code examples, and remediation steps for any diagnostic rule code.

# Explain any rule in detail
stackvet explain FAP-001
stackvet explain SQL-004
stackvet explain DOC-001

stackvet fix (aliases: remediate, auto-fix)

Applies safe, format-preserving automated remediations (e.g. injecting missing packages into pyproject.toml or package.json).

# Preview available safe fixes
stackvet fix
stackvet remediate

# Apply all fixes automatically without prompts
stackvet fix --yes
stackvet auto-fix --yes

stackvet graph (aliases: architecture, dependencies)

Visualizes project module dependencies and detects circular import cycles.

# Clean ASCII hierarchy
stackvet graph --style ascii
stackvet architecture

# Mermaid diagram (pasteable directly into GitHub Markdown or Notion)
stackvet graph --style mermaid

# Graphviz DOT format
stackvet graph --style dot

stackvet baseline

Records existing issues in legacy codebases to prevent CI failures on technical debt while blocking new regressions.

# Record current diagnostics into baseline
stackvet baseline record ./backend

# Verify in CI that no new regressions were introduced
stackvet baseline verify ./backend

# Strict verification (fails on new warnings too)
stackvet baseline verify ./backend --strict

stackvet init (alias: setup)

Bootstraps a recommended .stackvet.toml configuration and optional GitHub Actions CI workflow.

# Generate .stackvet.toml
stackvet init

# Generate configuration AND GitHub Actions CI workflow (.github/workflows/stackvet.yml)
stackvet init --ci

stackvet rules (aliases: catalog, list-rules)

Displays the complete catalog of 132 supported diagnostic rules across Python, Node.js, Docker, CI/CD, and frameworks.

# Show all rules in a formatted table
stackvet rules

# Filter catalog by ecosystem or framework
stackvet rules docker
stackvet rules fastapi
stackvet rules sqlalchemy
stackvet rules react

Diagnostic Rules Catalog

Python Dependency Rules (DEP-xxx)

Node Dependency Rules (NDEP-xxx)

Import & Architecture Rules (IMP-xxx, ARC-xxx)

Environment & Drift Rules (ENV-xxx)

FastAPI Framework Rules (FAP-xxx)

React & Next.js Rules (RCT-xxx, NXT-xxx)

Output Formats

StackVet supports 4 built-in egress formats via --format:

CI/CD Integration

GitHub Actions (with SARIF Security Tab)

name: StackVet Health Check

on:
  push:
    branches: [main]
  pull_request:

jobs:
  health:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install StackVet
        run: cargo install stackvet

      # Fast CI Gate (Fails on Error)
      - name: Run StackVet Check
        run: stackvet check --strict

      # Generate SARIF report for GitHub Code Scanning
      - name: Generate SARIF Report
        if: always()
        run: stackvet --format sarif doctor > stackvet-results.sarif

      - name: Upload SARIF to GitHub Security Tab
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: stackvet-results.sarif

Pre-Commit Hook (.pre-commit-config.yaml)

repos:
  - repo: local
    hooks:
      - id: stackvet
        name: stackvet check
        entry: stackvet check
        language: system
        pass_filenames: false

Publishing to npm & PyPI

StackVet includes dedicated automated GitHub Actions workflows and local build scripts for publishing to npm and PyPI:

• npm Workflow: .github/workflows/publish-npm.yml
• PyPI Workflow: .github/workflows/publish-pypi.yml
• Detailed Step-by-Step Guide: See the complete Publishing Guide for prerequisites, token setup, and verification.

# Build PyPI distribution (wheel & sdist)
npm run build:pypi

# Build npm package & tarball
npm run build:npm

Architecture & Workspace Structure

StackVet is designed as a modular Cargo workspace:

stackvet/
├── Cargo.toml                      # Workspace root
├── crates/
│   ├── stackvet-core/             # Core models: Diagnostic, Rule, Severity, ProjectContext, RootCause
│   ├── stackvet-scanner/          # Discovery engine with ignore::WalkBuilder
│   ├── stackvet-python/           # Python AST (ruff_python_parser), manifests & lockfiles
│   ├── stackvet-node/             # Node/TS AST (oxc_parser), package.json & builtins
│   ├── stackvet-graph/            # Tarjan's SCC cycle detection (petgraph)
│   ├── stackvet-analyzers/        # Core analyzers: deps, env, imports, drift
│   ├── stackvet-frameworks/       # Framework engines: FastAPI, React, Next.js
│   ├── stackvet-correlation/      # Root cause clustering and health scoring (0-100)
│   ├── stackvet-remediation/      # Format-preserving auto-fixes (toml_edit)
│   ├── stackvet-reporter/         # Terminal, SARIF v2.1.0, JSON, HTML reporters
│   └── stackvet-cli/              # CLI binary entrypoint (clap)

Contributing

1. Clone repository:

   git clone https://github.com/stackvet/stackvet.git
   cd stackvet
   

2. Run test suite:

   cargo test
   

3. Run locally against sample code:

   cargo run -p stackvet -- doctor
   

Pull requests and rule proposals are welcome!

License

StackVet is licensed under the MIT License.