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
• Process Exit Codes
• Project Configuration (stackvet.toml)
• 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 (no install required):
npx @inzamol/stackvet doctor

# Or install in your project:
npm install --save-dev @inzamol/stackvet
# or with pnpm / yarn:
pnpm add -D @inzamol/stackvet
yarn add -D @inzamol/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

# Explain which diagnostics contributed to health score deductions
stackvet doctor --explain

# Compare against an established baseline
stackvet doctor --baseline .stackvet-baseline.json

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

Health Scoring Weights & Grading Scale

StackVet computes an objective, deterministic 0–100 health score subtracted from a base of 100:

• Letter Grades: A (90–100) | B (75–89) | C (50–74) | F (0–49)
• Deduplication Safety: Duplicate findings across identical files and lines are suppressed so redundant occurrences never distort the score.

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

# Custom severity failure threshold (e.g. fail on warning or higher)
stackvet check --fail-on warning

# Strict mode (equivalent to --fail-on warning)
stackvet check --strict
stackvet audit --strict

# Baseline-aware check: tolerates legacy issues, fails only on new regressions
stackvet check --baseline .stackvet-baseline.json --fail-on error

# Update baseline to record newly accepted findings
stackvet check --baseline .stackvet-baseline.json --update-baseline

# 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.json)
stackvet baseline record ./backend

# Custom output filepath
stackvet baseline record -o ./ci/baseline.json

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

# Verify failing only on errors (tolerating new warnings)
stackvet baseline verify ./backend --fail-on error

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

# Accept resolved debt and new findings by updating the baseline file
stackvet baseline verify ./backend --update

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:

Process Exit Codes

StackVet returns stable, predictable exit codes across all commands, checks, and output formats (text, json, sarif, html):

Project Configuration

StackVet automatically discovers and loads configuration from stackvet.toml, .stackvet.toml, or pyproject.toml (under [tool.stackvet]), or from an explicit file via --config <PATH>.

Precedence Hierarchy

1. CLI Arguments (--fail-on, --strict, --min-score, --baseline) — Highest precedence.
2. Project Config File (stackvet.toml / .stackvet.toml / pyproject.toml) — Overrides defaults.
3. Built-in Defaults (fail_on = "error", min_score = None) — Fallback.

Example stackvet.toml

[project]
name = "my-application"
min_score = 80
strict = false

[thresholds]
# Minimum severity that triggers CI failure: "hint", "info", "warning", "error", "critical"
fail_on = "error"
# Minimum health score required (0-100)
min_score = 80

[ci]
baseline = ".stackvet-baseline.json"
fail_on = "error"
strict = false

[rules]
# Override rule severities or disable rules entirely
DEP-001 = "warning"
CEL-001 = "disabled"   # or "off"
ARC-001 = "error"

# Detailed table syntax with explicit enable/disable flag
[rules.FAP-001]
severity = "error"
enabled = true

# Ignore patterns (file/directory globs relative to project root)
[ignore]
patterns = ["legacy/**", "benchmarks/**", "*.generated.ts"]

# Configured suppressions with rule, path pattern, and expiration date
[[suppressions]]
rule = "DEP-001"
path = "legacy/**/*.py"
reason = "Legacy package scheduled for removal"

[[suppressions]]
rule = "SQL-001"
until = "2026-12-31"   # ISO 8601 YYYY-MM-DD expiration
reason = "Temporary bypass during query optimization"

Inline comment suppressions are also supported in Python, JavaScript, and TypeScript files:

# Inline comment suppression examples
time.sleep(1)  # stackvet:ignore[FAP-001]: intentional delay
# stackvet:ignore-next-line[DEP-001]
import optional_pkg
# stackvet:ignore-file[DJG-001]: legacy file exempt from django check

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.