StackVet Logo

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.

Overview
Key Features
Installation
Quick Start
Terminal UI & Interactive Scorecard
CLI Command Guide
Diagnostic Rules Catalog & Highlights
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:

Parallel Static Analysis: Uses Rust with ruff_python_parser and oxc_parser to inspect ASTs without running user code.
Cross-Layer Drift Detection: Detects mismatches between local environments, package manifests, lockfiles, Docker images, and CI matrix definitions.
Correlation Engine: Groups individual symptoms into concise Root Cause Clusters.
Health Score & Grade: Produces an actionable 0–100 health score with letter grades (A, B, C, or F).
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

╭─────────────────────────────────────────────────────────────────────╮
│              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
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:

Severity	Deduction	Description
`CRITICAL`	-20 pts	Blocking synchronous calls in async handlers, critical event loop freezes
`ERROR`	-8 pts	Missing dependencies, circular imports, unresolved modules
`WARN`	-2 pts	Lockfile drift, unused dependencies, version mismatches
`INFO` / `HINT`	0 pts	Informational architecture advice and guidance

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

Python Dependency Rules (`DEP-xxx`)

Rule ID	Severity	Name	Description
`DEP-001`	`ERROR`	Version Conflict	Detects conflicting version specifiers in dependencies (e.g. `foo>=2.0` vs `foo<2.0`).
`DEP-002`	`ERROR`	Missing Declaration	Imported package is used in Python code but not declared in `pyproject.toml` or `requirements.txt`.
`DEP-003`	`WARN`	Unused Dependency	Package listed in dependencies is never imported by any Python source files.
`DEP-004`	`ERROR`	Python Version Incompatible	Package requirements target end-of-life Python runtimes (e.g. `<3.10`).
`DEP-005`	`WARN`	Lockfile Drift	Manifest file exists (`pyproject.toml`) but lockfile (`uv.lock`/`poetry.lock`) is missing.
`DEP-006`	`CRITICAL`	Vulnerability Audit	Batched security audit against OSV database for known CVEs.
`DEP-007`	`WARN`	Transitive Dependency Import	Package imported is present in lockfile but not directly declared in `pyproject.toml`.

Node Dependency Rules (`NDEP-xxx`)

Rule ID	Severity	Name	Description
`NDEP-001`	`ERROR`	Missing Node Package	Package imported in `.ts`/`.tsx`/`.js` is missing from `package.json`.
`NDEP-002`	`WARN`	Unused Node Package	Production dependency in `package.json` is never imported in source files.
`NDEP-003`	`ERROR`	Unmet Peer Dependency	Declared dependencies conflict with peer dependency constraints.
`NDEP-004`	`WARN`	Lockfile Out of Sync	Missing lockfile (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`).
`NDEP-005`	`ERROR`	DevDependency in Production	A package from `devDependencies` is imported inside production source files (outside test files).

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

Rule ID	Severity	Name	Description
`IMP-001`	`ERROR`	Circular Imports	Import cycle detected across modules (e.g. `a -> b -> c -> a`).
`IMP-002`	`ERROR`	Unresolved Local Import	Relative import path (`./utils`, `from .mod`) has no corresponding file on disk.
`IMP-003`	`WARN`	Orphan File / Dead Code	Source file has 0 incoming imports and is not an application entrypoint.
`IMP-004`	`ERROR`	PEP 594 Removed Stdlib	Importing deprecated standard library module removed in Python 3.13 (`cgi`, `pipes`, `imp`, `crypt`, etc.).
`ARC-001`	`WARN`	Layer Violation	Lower-tier persistence layer directly imports upper-tier presentation or API layers.
`ARC-002`	`WARN`	Component Cycle	Cross-boundary cycles detected between top-level feature directories.

Environment & Drift Rules (`ENV-xxx`)

Rule ID	Severity	Name	Description
`ENV-001`	`WARN`	Runtime Drift	`.python-version` or `.nvmrc` contradicts the runtime constraint in `pyproject.toml` or `package.json`.
`ENV-002`	`ERROR`	Docker Drift	`Dockerfile` base image (e.g. `python:3.10-slim`) contradicts project requirement (`>=3.12`).
`ENV-003`	`ERROR`	CI Matrix Drift	GitHub Actions workflow matrix runs tests on unsupported runtime versions.

FastAPI Framework Rules (`FAP-xxx`)

Rule ID	Severity	Name	Description
`FAP-001`	`CRITICAL`	Blocking Call in Async Route	Calling blocking functions (`time.sleep()`, synchronous `requests.`, `subprocess.`) inside `async def` routes.
`FAP-003`	`WARN`	Missing Response Model	FastAPI route handler lacks a `response_model` argument or return type annotation (`-> Model`).
`FAP-004`	`CRITICAL`	Insecure Wildcard CORS	`CORSMiddleware` configured with `allow_origins=["*"]` combined with `allow_credentials=True`.
`FAP-006`	`ERROR`	Missing Path Parameter	URL template contains a placeholder (e.g. `/{item_id}`) not present in handler arguments.
`FAP-008`	`WARN`	Deprecated on_event	Using `@app.on_event("startup")` instead of modern `lifespan` context managers.
`FAP-010`	`ERROR`	Duplicate Route Path	Multiple handlers registered for the exact same HTTP method and path template.
`FAP-011`	`ERROR`	Mutable Default Argument	Route parameter has a mutable default value (e.g. `def list_items(tags: list = []):`).
`FAP-015`	`ERROR`	Sync File I/O in Async Handler	Synchronous `open()` or `with open(...)` executed inside an `async def` route handler.

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

Rule ID	Severity	Name	Description
`RCT-001`	`WARN`	Missing Hook Dependencies	`useEffect` or `useCallback` missing referenced variables in dependency array.
`RCT-002`	`ERROR`	Conditional Hook Call	React hook (`useState`, `useEffect`) invoked conditionally inside an `if` block.
`RCT-003`	`ERROR`	Direct State Mutation	Modifying state directly (`state.foo = 1`) rather than calling state dispatcher.
`RCT-004`	`WARN`	Missing Key in List	JSX elements rendered inside `.map()` missing a unique `key` prop.
`RCT-005`	`WARN`	Barrel Import Bloat	Importing from root barrel exports (e.g. `from '@mui/material'`) causing bundle bloat.
`NXT-001`	`ERROR`	Server Component Client API	Browser APIs (`window`, `localStorage`) or client hooks used without `"use client"` directive.
`NXT-002`	`CRITICAL`	Client Component Private Secret	Client Component accesses private environment variable (not prefixed with `NEXT_PUBLIC_`).

Output Formats

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

Format	Description	Command Example
`text` (default)	Colored ANSI terminal output with tables and scorecard	`stackvet doctor`
`json`	Structured JSON with full diagnostics and root causes	`stackvet --format json check`
`sarif`	OASIS SARIF v2.1.0 for GitHub Code Scanning tab	`stackvet --format sarif doctor > results.sarif`
`html`	Standalone responsive dark-mode HTML report	`stackvet --format html doctor > report.html`

Process Exit Codes

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

Exit Code	Classification	Trigger Condition
`0`	Success	Clean project, no findings meeting/exceeding `--fail-on` threshold, health score meets `--min-score`, or all findings are tolerated legacy baseline issues.
`1`	Findings Violation	Findings detected meeting or exceeding `--fail-on` threshold, health score below `--min-score`, or new regression findings introduced against baseline.
`2`	Configuration Error	Configuration syntax error in `stackvet.toml` or `pyproject.toml`, unknown rule ID in `[rules]`, or unsupported severity override level.
`3`	Execution / I/O Error	Target path does not exist, specified baseline file not found, or filesystem read/write error.

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

CLI Arguments (--fail-on, --strict, --min-score, --baseline) — Highest precedence.
Project Config File (stackvet.toml / .stackvet.toml / pyproject.toml) — Overrides defaults.
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

Clone repository:

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

Run test suite:
```
cargo test
```
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.

Metadata

Release files for stackvet 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for stackvet 0.3.0
File	Size	Uploaded	Provenance
stackvet-0.3.0.tar.gz	244.9 kB	Oct 24, 2026	With provenance	Details

Built distributions (wheels)

Table of built distributions (wheels) for stackvet 0.3.0
File	Interpreter	ABI	Platform	Reset
stackvet-0.3.0-py3-none-win_amd64.whl 5.4 MB Oct 24, 2026 With provenance	Python 3	none	Windows x86-64	Details
stackvet-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 5.6 MB Oct 24, 2026 With provenance	Python 3	none	Linux glibc 2.17+ x86-64	Details
stackvet-0.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 5.3 MB Oct 24, 2026 With provenance	Python 3	none	Linux glibc 2.17+ ARM64	Details
stackvet-0.3.0-py3-none-macosx_11_0_arm64.whl 5.1 MB Oct 24, 2026 With provenance	Python 3	none	macOS 11.0+ ARM64	Details
stackvet-0.3.0-py3-none-macosx_10_12_x86_64.whl 5.4 MB Oct 24, 2026 With provenance	Python 3	none	macOS 10.12+ x86-64	Details

Total release size: 27.0 MB

Release files / stackvet-0.3.0.tar.gz

Download URL	stackvet-0.3.0.tar.gz
Size	244.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`5165cc58f0aeca5d5f6b276351d15a8cd5873e2d04d817ab110088e4e3b36eb9`
BLAKE2b-256 checksum How to use checksums	`610d168c8a54acc3e55db6beaaa487319057e4a9b9137edb317c8e8323f5bc68`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/inzamol/stackvet
Publishing commit: github.com/inzamol/stackvet/tree/9acb73cfd1266c14c55127dd68f096b487d1adbb

Workflow

Publishing configuration: github.com/inzamol/stackvet/blob/9acb73cfd1266c14c55127dd68f096b487d1adbb/.github/workflows/publish-pypi.yml
Publishing logs: github.com/inzamol/stackvet/actions/runs/40051533946/attempts/1

Artifact

Subject: stackvet-0.3.0.tar.gz
SHA-256 checksum: 5165cc58f0aeca5d5f6b276351d15a8cd5873e2d04d817ab110088e4e3b36eb9 Verifying attestations

Release files / stackvet-0.3.0-py3-none-win_amd64.whl

Download URL	stackvet-0.3.0-py3-none-win_amd64.whl
Size	5.4 MB
Tags	Python 3 Windows x86-64
SHA-256 checksum How to use checksums	`981b3924eafa383fe23bc4c255aa452b0d70dafaa2d796745c8b9be71de42368`
BLAKE2b-256 checksum How to use checksums	`df2b67426a7a44a20794495c5a0f455d328645132751cc4dd8f0489c685947cb`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/inzamol/stackvet
Publishing commit: github.com/inzamol/stackvet/tree/9acb73cfd1266c14c55127dd68f096b487d1adbb

Workflow

Publishing configuration: github.com/inzamol/stackvet/blob/9acb73cfd1266c14c55127dd68f096b487d1adbb/.github/workflows/publish-pypi.yml
Publishing logs: github.com/inzamol/stackvet/actions/runs/40051533946/attempts/1

Artifact

Subject: stackvet-0.3.0-py3-none-win_amd64.whl
SHA-256 checksum: 981b3924eafa383fe23bc4c255aa452b0d70dafaa2d796745c8b9be71de42368 Verifying attestations

Release files / stackvet-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	stackvet-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	5.6 MB
Tags	Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum How to use checksums	`d9f221457d0a87295cfac26429cb736462620ccb2a9f82d6f75fe20646bb941a`
BLAKE2b-256 checksum How to use checksums	`872e56bf5ca52d469fa46360f60a3d7921ec5247bd7a2873fa1eea2e2e300f05`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/inzamol/stackvet
Publishing commit: github.com/inzamol/stackvet/tree/9acb73cfd1266c14c55127dd68f096b487d1adbb

Workflow

Publishing configuration: github.com/inzamol/stackvet/blob/9acb73cfd1266c14c55127dd68f096b487d1adbb/.github/workflows/publish-pypi.yml
Publishing logs: github.com/inzamol/stackvet/actions/runs/40051533946/attempts/1

Artifact

Subject: stackvet-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
SHA-256 checksum: d9f221457d0a87295cfac26429cb736462620ccb2a9f82d6f75fe20646bb941a Verifying attestations

Release files / stackvet-0.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	stackvet-0.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size	5.3 MB
Tags	Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum How to use checksums	`ff1bfccd9232b6d154c364043791dc8abf24a39fc0d157f00d1dd53064629c2b`
BLAKE2b-256 checksum How to use checksums	`8ce2df8b8b1d3a26f6cb7435d89334c677dcdb0b0205ceda521282dcffc9c65b`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/inzamol/stackvet
Publishing commit: github.com/inzamol/stackvet/tree/9acb73cfd1266c14c55127dd68f096b487d1adbb

Workflow

Publishing configuration: github.com/inzamol/stackvet/blob/9acb73cfd1266c14c55127dd68f096b487d1adbb/.github/workflows/publish-pypi.yml
Publishing logs: github.com/inzamol/stackvet/actions/runs/40051533946/attempts/1

Artifact

Subject: stackvet-0.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
SHA-256 checksum: ff1bfccd9232b6d154c364043791dc8abf24a39fc0d157f00d1dd53064629c2b Verifying attestations

Release files / stackvet-0.3.0-py3-none-macosx_11_0_arm64.whl

Download URL	stackvet-0.3.0-py3-none-macosx_11_0_arm64.whl
Size	5.1 MB
Tags	Python 3 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`a31fca0bdcd120b222227c5983e521e77c36ff21d57a3ff53f21addda629a35f`
BLAKE2b-256 checksum How to use checksums	`cb1e96d37e856928b45b33802e87eeecfe917ff9932b7752cd5e64e2ce046331`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/inzamol/stackvet
Publishing commit: github.com/inzamol/stackvet/tree/9acb73cfd1266c14c55127dd68f096b487d1adbb

Workflow

Publishing configuration: github.com/inzamol/stackvet/blob/9acb73cfd1266c14c55127dd68f096b487d1adbb/.github/workflows/publish-pypi.yml
Publishing logs: github.com/inzamol/stackvet/actions/runs/40051533946/attempts/1

Artifact

Subject: stackvet-0.3.0-py3-none-macosx_11_0_arm64.whl
SHA-256 checksum: a31fca0bdcd120b222227c5983e521e77c36ff21d57a3ff53f21addda629a35f Verifying attestations

Release files / stackvet-0.3.0-py3-none-macosx_10_12_x86_64.whl

Download URL	stackvet-0.3.0-py3-none-macosx_10_12_x86_64.whl
Size	5.4 MB
Tags	Python 3 macOS 10.12+ x86-64
SHA-256 checksum How to use checksums	`b5e419ca6441ee693c98752c8faab9a89b944780c2cc544b3d5dbd5143c2e3c9`
BLAKE2b-256 checksum How to use checksums	`88ac006ace3f6eb7945ec1ef0743fbb10f4dfe255b618ec6da326766aa0d290d`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/inzamol/stackvet
Publishing commit: github.com/inzamol/stackvet/tree/9acb73cfd1266c14c55127dd68f096b487d1adbb

Workflow

Publishing configuration: github.com/inzamol/stackvet/blob/9acb73cfd1266c14c55127dd68f096b487d1adbb/.github/workflows/publish-pypi.yml
Publishing logs: github.com/inzamol/stackvet/actions/runs/40051533946/attempts/1

Artifact

Subject: stackvet-0.3.0-py3-none-macosx_10_12_x86_64.whl
SHA-256 checksum: b5e419ca6441ee693c98752c8faab9a89b944780c2cc544b3d5dbd5143c2e3c9 Verifying attestations

Security for stackvet 0.3.0

Report project as malware

Provenance

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Attestation for stackvet-0.3.0.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/inzamol/stackvet
Publishing commit: github.com/inzamol/stackvet/tree/9acb73cfd1266c14c55127dd68f096b487d1adbb

Workflow

Publishing configuration: github.com/inzamol/stackvet/blob/9acb73cfd1266c14c55127dd68f096b487d1adbb/.github/workflows/publish-pypi.yml
Publishing logs: github.com/inzamol/stackvet/actions/runs/40051533946/attempts/1

Artifact

Subject: stackvet-0.3.0.tar.gz
SHA-256 checksum: 5165cc58f0aeca5d5f6b276351d15a8cd5873e2d04d817ab110088e4e3b36eb9 Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

0.3.2

Oct 24, 2026 6 release files Full provenance

0.3.1

Oct 24, 2026 6 release files Full provenance

This release

0.3.0 This release

Oct 24, 2026 6 release files Full provenance

0.2.0

Oct 22, 2026 6 release files Full provenance

0.1.2

Oct 11, 2026 6 release files Full provenance

0.1.1

Oct 11, 2026 5 release files Full provenance

0.1.0

Oct 11, 2026 5 release files Full provenance

stackvet 0.3.0

StackVet (stackvet)

Table of Contents

Overview

Key Features

Installation

Via Cargo (Rust)

Via uv / pip (Python)

Via npm / npx (Node.js)

Quick Start

Terminal UI & Interactive Scorecard

Executive Diagnostic Report

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

CLI Command Guide

stackvet doctor (aliases: diagnose, health)

Health Scoring Weights & Grading Scale

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

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

Process Exit Codes

Project Configuration

Precedence Hierarchy

Example stackvet.toml

CI/CD Integration

GitHub Actions (with SARIF Security Tab)

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

Publishing to npm & PyPI

Architecture & Workspace Structure

Contributing

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

Provenance

License

Requires

Tags

Classifiers

Metadata

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

Provenance

License

Requires

Tags

Classifiers

Release files for stackvet 0.3.0

Source distribution (sdist)

Built distributions (wheels)

Release files / stackvet-0.3.0.tar.gz

Provenance

PyPI Publish Attestation

Identity

Workflow

Artifact

Release files / stackvet-0.3.0-py3-none-win_amd64.whl

Provenance

PyPI Publish Attestation

Identity

Workflow

Artifact

Release files / stackvet-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

StackVet (`stackvet`)

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

`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`)

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`)

Example `stackvet.toml`

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