Skip to content

stackvet Documentation

Universal Project Health & Static Diagnostics Engine for Node.js, TypeScript, Python, Docker & CI Stacks

PyPI Version npm Version VS Code Node Versions Python Versions License: MIT

stackvet is a high-performance, polyglot diagnostic and project health engine for modern stacks (Node.js/TypeScript, Python, Docker, and CI/CD). It inspects your project manifests (package.json, pnpm-lock.yaml, package-lock.json, yarn.lock, pyproject.toml, requirements.txt, uv.lock), active runtime environments, source code ASTs, and infrastructure definitions in milliseconds to uncover broken dependencies, undeclared packages, circular import loops, and runtime drift.

1. Overview & Architecture

Unlike generic tools that only inspect a single lockfile or flat requirements list, stackvet correlates multi-layer diagnostic signals across your entire project ecosystem:

flowchart TD
    subgraph Discovery["1. Discovery & Context Ingestion"]
        A["<b>Project Manifests & Active Environment</b><br/>package.json • pnpm/npm/yarn lockfiles • pyproject.toml • requirements.txt"]
        B["<b>Source Code AST & Infrastructure</b><br/>TS/JS/Python AST imports • Dockerfile • CI workflows"]
    end

    subgraph Analyzers["2. Subsystem Analyzers"]
        C["<b>Dependencies Analyzers</b><br/>Node (NDEP) & Python (DEP) conflicts, missing & unused packages"]
        D["<b>Environment & Drift Analyzer</b><br/>Node/Python runtimes, Docker base images & CI matrix drift"]
        E["<b>Imports & Architecture Analyzer</b><br/>Circular import cycle detection & unresolvable modules"]
        F["<b>Frameworks & Packaging</b><br/>React (RCT), Next.js (NXT), FastAPI (FAP), Django (DJG), and manifests"]
    end

    subgraph Correlator["3. Root Cause Engine & Health Score"]
        G["<b>Correlated Diagnostic Model</b><br/>Evidence mapping, root causes & Health Score (0–100)"]
    end

    subgraph Output["4. Multi-Channel Output & Remediation"]
        H["<b>Interactive Terminal Dashboard</b> (`stackvet inspect`)"]
        I["<b>Standalone HTML Reports</b> (`stackvet scan --html`)"]
        J["<b>CI / SARIF & Annotations</b> (`stackvet scan --sarif`)"]
        K["<b>Automated Safe Fixes</b> (`stackvet fix -y`)"]
    end

    A --> Analyzers
    B --> Analyzers
    Analyzers --> Correlator
    Correlator --> H
    Correlator --> I
    Correlator --> J
    Correlator --> K

👉 Learn more in the comprehensive Architecture & Internal Design documentation.

2. Install & Usage

Run stackvet doctor or stackvet scan directly in any Node.js, TypeScript, Python, or polyglot repository root:

npx @inzamol/stackvet doctor

npm install --save-dev @inzamol/stackvet
npx stackvet doctor

# pnpm
pnpm add -D @inzamol/stackvet
pnpm exec stackvet doctor

# yarn
yarn add -D @inzamol/stackvet
yarn stackvet doctor

uvx stackvet doctor
# or
pipx run stackvet doctor

uv add stackvet --dev
uv run stackvet doctor

pip install stackvet
stackvet doctor

cargo install stackvet
stackvet doctor

pip install git+https://github.com/inzamol/stackvet.git
stackvet doctor

git clone https://github.com/inzamol/stackvet.git
cd stackvet
pip install -e .
# or with uv
uv pip install -e .

2.1 Live Diagnostic Output

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

  Health Score: 92 / 100
  Overall Grade: A (Healthy)
  Calculation:   Base 100 - 8 deductions (1 unique finding, 0 duplicates ignored)

  Critical: 0  |  Errors: 1  |  Warnings: 0

--- Health Score Deduction Breakdown ---
  • [ERROR] DEP-001: -8 pts (1 finding) - Dependency constraint conflict

--- Root Cause Clusters (1) ---
1. [ERROR] Rule Violation: DEP-001
   Summary: celery 5.4.0 requires kombu<5.4.0,>=5.3.0, but installed is kombu 5.5.2.
   Remediation: Upgrade celery or pin kombu to <5.4.0,>=5.3.0.
   Symptoms Count: 1

--- Diagnostic Details ---
╭─────────┬──────────┬──────────────┬──────────────────┬────────────────────────────────────────────────────────────────────────╮
│ Rule    ┆ Severity ┆ Target       ┆ File Location    ┆ Message                                                                │
╞═════════╪══════════╪══════════════╪══════════════════╪════════════════════════════════════════════════════════════════════════╡
│ DEP-001 ┆ ERROR    ┆ Dependencies ┆ requirements.txt ┆ celery 5.4.0 requires kombu<5.4.0,>=5.3.0, but installed is kombu 5.5.2 │
╰─────────┴──────────┴──────────────┴──────────────────┴────────────────────────────────────────────────────────────────────────╯

3. Core Feature Pillars

  • Interactive Terminal Dashboard

    Explore findings interactively with keyboard navigation (↑/↓), expand evidence, view live dependency trees (t), and apply fixes (f) in a rich TUI.

    Open CLI Reference

  • Self-Contained HTML Reports

    Generate portable, zero-dependency HTML reports (stackvet scan --html) with circular health score gauges, real-time search, severity filters, and dark mode.

    Open HTML Report Guide

  • Safe Automated Fixes

    Compute deterministic remediation plans with stackvet fix --dry-run and safely synchronize manifests and package managers with stackvet fix --sync -y.

    Open Remediation Guide

  • Dependency & Import Trees

    Visualize direct vs transitive package trees (stackvet graph -d) and internal module import architecture with circular loops highlighted (stackvet graph -i).

    Open Tree Visualizer Guide

4. Diagnostic Subsystems

Subsystem Scope & Capabilities Key Rules
Node Dependencies Undeclared package imports in TS/JS, unused production dependencies, peer conflicts, lockfile drift (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb) NDEP-001 through NDEP-005
React & Next.js Hook dependencies, conditional hook calls, direct state mutation, missing keys in lists, barrel import bloat, Server/Client component leaks, private environment variable exposure RCT-001–RCT-005, NXT-001–NXT-002
Python Dependencies Constraint conflicts, undeclared imports, unused packages, Python runtime compatibility mismatches, lockfile drift (uv.lock, poetry.lock) DEP-001 through DEP-007
FastAPI & Python Frameworks Blocking calls in async routes, missing response models, wildcard CORS, path parameter discrepancies, SQLAlchemy N+1 queries, Django settings, Celery risks FAP-xxx, SQL-xxx, DJG-xxx, CEL-xxx
Environment & Drift Node (.nvmrc, package.json engines) and Python (.python-version, pyproject.toml) runtime drift against Dockerfile base images and CI test matrices ENV-001 through ENV-003
Architecture & Imports Circular import cycle detection, unresolvable module imports, dead orphan files, deprecated stdlib, architectural tier violations IMP-001–IMP-004, ARC-001–ARC-002
Docker & Containers Security best practices, root user risks, unpinned base images, sensitive file leaks, caching optimizations DOC-001 through DOC-014
CI Workflows Matrix mismatches, unpinned dependencies, outdated GitHub Actions, quality gates, hardcoded secrets CI-001 through CI-006

👉 Browse full rule descriptions and remediation strategies in the Rules Catalog.

5. Unified Polyglot Advantage

stackvet replaces multiple fragmented, single-ecosystem linters with a single, ultra-fast native engine producing unified health scoring across your entire stack:

Capability stackvet depcheck / knip (Node) pip check / deptry (Python) npm audit / pip-audit
Polyglot Monorepo Analysis (Node + Python) ✅ ❌ ❌ ❌
Node.js Dependency & Peer Auditing ✅ ✅ ❌ ❌
React & Next.js Architectural Rules ✅ ❌ ❌ ❌
Python Dependency & Constraint Conflicts ✅ ❌ ✅ ❌
FastAPI, Django & SQLAlchemy Hazards ✅ ❌ ❌ ❌
Circular Import Cycle Detection ✅ ⚠ (JS only) ❌ ❌
Cross-Layer Runtime & Docker/CI Drift ✅ ❌ ❌ ❌
Interactive Terminal Explorer (TUI) ✅ ❌ ❌ ❌
Standalone Interactive HTML Reports ✅ ❌ ❌ ❌
Format-Preserving Auto-Fixes (stackvet fix) ✅ ❌ ❌ ❌
SARIF v2.1.0 & GitHub PR Annotations ✅ ❌ ❌ ❌
Sub-Second Native Rust Execution ✅ ❌ (Node runtime) ❌ (Python runtime) ❌ (Network bound)

6. Explore Documentation

  • Architecture & Design

    Deep dive into discovery pipelines, immutable models, and analyzer subsystems.

    Explore Architecture

  • Getting Started Guide

    Step-by-step setup, first health scan, and baseline configuration.

    Read Getting Started

  • CLI Commands Reference

    Complete flag reference, exit codes, and output formatting options.

    Explore CLI Reference

  • Diagnostic Rules Catalog

    Exhaustive documentation for every diagnostic rule and remediation plan.

    View Rules Catalog

  • Configuration Guide

    Configure severities, ignore rules, and exclude path patterns in pyproject.toml.

    View Configuration

  • CI/CD & GitHub Actions

    Integrate with GitHub Actions, SARIF code scanning alerts, and workflows.

    View CI Integration

  • Pre-commit Integration

    Enforce clean health scans before commits reach your remote repository.

    View Pre-commit Guide

  • Contributing Guide

    Development environment setup, Tox testing matrix, and authoring new rules.

    Read Contributing