StackVet (stackvet)

Universal Project Health & Static Diagnostics Engine
Analyze Python, JavaScript, and TypeScript projects for dependency issues, environment drift, framework pitfalls, and architectural problems—alongside Docker and CI/CD configuration.

Table of Contents

• Overview
• Key Features
• Installation
• Quick Start
• Terminal UI & Interactive Scorecard
• 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 & Highlights
  • Node & Frontend Dependency Rules (NDEP-xxx)
  • React & Next.js Rules (RCT-xxx, NXT-xxx)
  • Python Dependency Rules (DEP-xxx)
  • FastAPI Framework Rules (FAP-xxx)
  • Import & Architecture Rules (IMP-xxx, ARC-xxx)
  • Environment & Drift Rules (ENV-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: Node/TypeScript frontends (React, Next.js, Express, Vue), Python backends (FastAPI, Django, Celery), 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 native Rust with oxc_parser (JavaScript/TypeScript) and ruff_python_parser (Python) to inspect ASTs without running user code.
2. Cross-Layer Drift Detection: Detects mismatches between local environments, package manifests, lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, uv.lock), Docker images, and CI matrix definitions.
3. Correlation Engine: Groups individual symptoms across all languages into concise Root Cause Clusters.
4. Health Score & Grade: Produces an actionable 0–100 health score with letter grades (A, B, C, or F).
5. Format-Preserving Auto-Fixes: Injects missing dependencies into package.json or pyproject.toml preserving user comments and indentation using toml_edit and JSON serializers.

Key Features

• Blazing Fast: Native Rust engine with Rayon parallel processing; analyzes multi-thousand-file repositories in milliseconds.
• AST-Level Accuracy: Direct AST traversal for JavaScript, TypeScript, and Python, eliminating regex false positives.
• Universal Package Intelligence: Inspects package.json, pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, pyproject.toml, requirements.txt, and uv.lock.
• Framework-Aware Diagnostics: Built-in rules for React, Next.js (Server/Client boundary and secret leaks), FastAPI, SQLAlchemy, and Django.
• Circular Dependency Detection: Detects import cycles using Tarjan's Strongly Connected Components (SCC) algorithm.
• Zero-Config Discovery: Automatically discovers manifests, lockfiles, Dockerfiles, and GitHub workflows across monorepos and microservices.
• 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 npm / npx (Node.js & TypeScript)

# Run instantly with npx (no install required):
npx @inzamol/stackvet doctor

# Or install in your project (npm / pnpm / yarn / bun):
npm install --save-dev @inzamol/stackvet
pnpm add -D @inzamol/stackvet
yarn add -D @inzamol/stackvet
bun add -d @inzamol/stackvet

Via uv / pip (Python)

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

# Or install in your virtual environment:
pip install stackvet
# or
uv add --dev stackvet

Via Cargo (Rust)

cargo install stackvet

Official VS Code Extension

Install the official StackVet VS Code Extension from the Visual Studio Marketplace or search StackVet in the Extensions view (Ctrl+Shift+X / Cmd+Shift+X).

Quick Start

Run a full project health check in your repository root:

stackvet doctor

╭─────────────────────────────────────────────────────────────────────╮
│              StackVet Universal Project Health Report               │
╰─────────────────────────────────────────────────────────────────────╯

  Health Score:  [████████████████████] 100 / 100   [ Grade: A (Healthy) ]
  Overall Grade: A (Healthy)
  Calculation:   Base 100 - 0 deductions (0 unique findings, 0 duplicates ignored)

  Metrics:       ● 0 Critical  │  ● 0 Errors  │  ▲ 0 Warnings  │  ℹ 0 Info

No issues found! Your project stack is pristine.

Terminal UI & Interactive Scorecard

StackVet features an enterprise-grade terminal user interface designed with adaptive formatting, UTF-8 rounded box-drawing characters, ANSI color-coded severity badges, and visual health score meters.

Executive Diagnostic Report

When violations, runtime drift, or missing dependencies are discovered across your stack, stackvet doctor renders an interactive diagnostic dashboard:

╭─────────────────────────────────────────────────────────────────────╮
│              StackVet Universal Project Health Report               │
╰─────────────────────────────────────────────────────────────────────╯

  Health Score:  [█████████████████░░░] 86 / 100   [ Grade: B (Fair) ]
  Overall Grade: B (Fair)
  Calculation:   Base 100 - 14 deductions (4 unique findings, 0 duplicates ignored)

  Metrics:       ● 0 Critical  │  ● 1 Errors  │  ▲ 3 Warnings  │  ℹ 0 Info

─── Health Score Deduction Breakdown ──────────────────────────────────
  • [ERROR]    NDEP-001   -8 pts     (1 finding)  ── Missing Node Package
  • [WARN]     IMP-003    -2 pts     (1 finding)  ── Unused / orphan local module
  • [WARN]     NDEP-004   -2 pts     (1 finding)  ── Lockfile Out of Sync
  • [WARN]     SEC-001    -2 pts     (1 finding)  ── Security analysis unavailable

─── Root Cause Clusters (4) ───────────────────────────────────────────
  1. [ERROR] Missing Project Dependency: 'axios' [Verified]  (1 finding)
     Summary:      Package 'axios' is imported across 1 file location(s) but undeclared in manifests.
     Remediation:  Add 'axios' to project manifest dependencies.
     Action Plan:
       1. Add 'axios' to project manifest dependencies.
       2. Synchronize package manager lockfile.

  2. [WARN] Environment, Lockfile & Runtime Drift [Verified]  (1 finding)
     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.
     Action Plan:
       1. Synchronize dependency declarations and lockfile versions.
       2. Align target runtime specifications across Dockerfiles, CI matrices, and project manifests.

  3. [WARN] Rule Violation: IMP-003 [Verified]  (1 finding)
     Summary:      File is never imported by any other source files in the project. It may be dead code or an unexported utility.
     Remediation:  Import the module or delete it if obsolete.
     Action Plan:
       1. Import the module or delete it if obsolete.

  4. [WARN] Rule Violation: SEC-001 [Verified]  (1 finding)
     Summary:      StackVet requires a vulnerability database to detect known CVEs in project dependencies. Without a connection or local cache, vulnerability scanning cannot be performed.
     Remediation:  Connect to the internet and run 'stackvet scan --refresh-vuln-cache' to populate the local vulnerability database.
     Action Plan:
       1. Connect to the internet and run 'stackvet scan --refresh-vuln-cache' to populate the local vulnerability database.

─── Diagnostic Details ────────────────────────────────────────────────
╭──────────┬──────────┬─────────┬───────────────────────────────────┬────────────────────────────────────────────────╮
│ Rule     ┆ Severity ┆ Target  ┆ File Location                     ┆ Message                                        │
╞══════════╪══════════╪═════════╪═══════════════════════════════════╪════════════════════════════════════════════════╡
│ NDEP-001 ┆ ERROR    ┆ Node.js ┆ server.js:2:15                    ┆ Package 'axios' is imported in source code     │
│          ┆          ┆         ┆                                   ┆ but not declared in package.json               │
├╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ IMP-003  ┆ WARN     ┆ General ┆ server.js                         ┆ Orphan source file with 0 incoming imports:    │
│          ┆          ┆         ┆                                   ┆ 'server.js'                                    │
├╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ NDEP-004 ┆ WARN     ┆ Node.js ┆ package.json                      ┆ No lockfile detected (pnpm-lock.yaml /         │
│          ┆          ┆         ┆                                   ┆ package-lock.json / yarn.lock)                 │
├╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ SEC-001  ┆ WARN     ┆ General ┆ package.json                      ┆ Vulnerability advisory database cache missing  │
╰──────────┴──────────┴─────────┴───────────────────────────────────┴────────────────────────────────────────────────╯

Auto-Remediation Verification Report (stackvet fix --verify)

When executing auto-remediation with --verify, StackVet applies safe format-preserving modifications and verifies them against a clean post-fix scan:

Applied fix: Injected 'axios' into package.json dependencies
All safe fixes applied successfully (1 file(s) updated)!

--- Running Fix Verification ---

--- Fix Verification Report ---
╭──────────────┬──────────┬──────────────┬─────────────────────────────────────────────────╮
│ Status       ┆ Rule     ┆ File         ┆ Details                                         │
╞══════════════╪══════════╪══════════════╪═════════════════════════════════════════════════╡
│ RESOLVED     ┆ NDEP-001 ┆ package.json ┆ Missing package: 'axios' imported in index.js   │
╰──────────────┴──────────┴──────────────┴─────────────────────────────────────────────────╯

Verification SUCCESS: 1 issue(s) confirmed resolved with 0 regressions.

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, B, C, or F).

# Run on current directory (auto-detects Node.js, TypeScript, Python, Docker)
stackvet doctor

# Run on a target project or subfolder
stackvet doctor ./frontend
stackvet doctor ./backend
stackvet -p ./packages/web doctor

# Using intuitive aliases
stackvet health ./frontend
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, Healthy) | B (75–89, Fair) | C (50–74, Degraded) | F (0–49, Critical Issues)
• 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 ./frontend
stackvet check ./backend
stackvet scan .

# 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 ./frontend
stackvet inspect ./backend

# Filter diagnostics by rule category prefix:
stackvet inspect --rule NDEP  # Only Node.js dependency rules
stackvet inspect --rule RCT   # Only React rules
stackvet inspect --rule NXT   # Only Next.js rules
stackvet inspect --rule FAP   # Only FastAPI rules
stackvet inspect --rule SQL   # Only SQLAlchemy rules
stackvet inspect --rule DOC   # Only Docker 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 NDEP-001
stackvet explain RCT-002
stackvet explain NXT-001
stackvet explain FAP-001
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 catalog of supported diagnostic rules across Python, Node.js, Docker, CI/CD, and frameworks. Run stackvet rules to view all rules and their metadata directly in your terminal.

# 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 & Highlights

Below is an overview of representative diagnostic rules across key categories. Run stackvet rules to browse the full catalog or stackvet explain <RULE_ID> for deep-dive remediations.

Node Dependency Rules (NDEP-xxx)

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

Python Dependency Rules (DEP-xxx)

FastAPI Framework Rules (FAP-xxx)

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

Environment & Drift Rules (ENV-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, package.json (under the "stackvet" property), 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 / package.json / 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
NDEP-001 = "error"
RCT-001 = "warning"
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", "dist/**", "build/**"]

# Configured suppressions with rule, path pattern, and expiration date
[[suppressions]]
rule = "NDEP-001"
path = "legacy/**/*.tsx"
reason = "Legacy frontend package scheduled for migration"

[[suppressions]]
rule = "DEP-001"
path = "legacy/**/*.py"
reason = "Legacy backend 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

Inline comment suppressions are supported across TypeScript, JavaScript, and Python:

TypeScript & JavaScript

// Single line suppression with rule ID and reason
import axios from 'axios'; // stackvet:ignore[NDEP-001]: bundled via CDN script

// Suppress next line
// stackvet:ignore-next-line[RCT-002]
if (condition) useState(0);

// Suppress entire file
// stackvet:ignore-file[NXT-001]: legacy client-only module exempt from server check

Python

# Single line suppression with rule ID and reason
time.sleep(1)  # stackvet:ignore[FAP-001]: intentional delay

# Suppress next line
# stackvet:ignore-next-line[DEP-001]
import optional_pkg

# Suppress entire file
# stackvet:ignore-file[DJG-001]: legacy file exempt from django check

CI/CD Integration

Node.js (package.json & lint-staged)

Add StackVet to your package.json scripts:

{
  "scripts": {
    "vet": "stackvet doctor",
    "check": "stackvet check --strict",
    "fix": "stackvet fix --yes"
  }
}

Pre-commit with Husky / lint-staged:

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,json,py}": ["stackvet check --strict"]
  }
}

GitHub Actions (Universal via npx & SARIF Security Tab)

name: StackVet Health Check

on:
  push:
    branches: [main]
  pull_request:

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

      # Fast CI Gate via npx (Zero Setup Required)
      - name: Run StackVet Check
        run: npx @inzamol/stackvet check --strict

      # Generate SARIF report for GitHub Code Scanning
      - name: Generate SARIF Report
        if: always()
        run: npx @inzamol/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

Python 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/inzamol/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.