stackvet 0.1.0__py3-none-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
Binary file
|
|
@@ -0,0 +1,522 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: stackvet
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Classifier: Development Status :: 4 - Beta
|
|
5
|
+
Classifier: Intended Audience :: Developers
|
|
6
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
7
|
+
Classifier: Programming Language :: Rust
|
|
8
|
+
Classifier: Programming Language :: Python :: 3
|
|
9
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
10
|
+
Classifier: Topic :: Software Development :: Bug Tracking
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Summary: Universal Project Health & Static Diagnostics Engine
|
|
13
|
+
Keywords: diagnostics,fastapi,sqlalchemy,django,celery,react,nextjs,docker,health,linter,ast,static-analysis
|
|
14
|
+
Author: Inzamul Hoque
|
|
15
|
+
License: MIT
|
|
16
|
+
Requires-Python: >=3.8
|
|
17
|
+
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
|
|
18
|
+
Project-URL: Documentation, https://inzamol.github.io/stackvet/
|
|
19
|
+
Project-URL: Homepage, https://github.com/inzamol/stackvet
|
|
20
|
+
Project-URL: Issues, https://github.com/inzamol/stackvet/issues
|
|
21
|
+
Project-URL: Repository, https://github.com/inzamol/stackvet
|
|
22
|
+
|
|
23
|
+
<p align="center">
|
|
24
|
+
<img src="docs/assets/logo.svg" alt="StackVet Logo" width="96" height="96" />
|
|
25
|
+
</p>
|
|
26
|
+
|
|
27
|
+
# StackVet (`stackvet`)
|
|
28
|
+
|
|
29
|
+
> **Universal Project Health & Static Diagnostics Engine**
|
|
30
|
+
> *Rigorously examine, inspect, and evaluate modern polyglot application stacks for health, safety, concurrency hazards, and architectural soundness in milliseconds.*
|
|
31
|
+
|
|
32
|
+
[](https://crates.io)
|
|
33
|
+
[](https://pypi.org)
|
|
34
|
+
[](https://npmjs.com)
|
|
35
|
+
[](LICENSE)
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Table of Contents
|
|
40
|
+
|
|
41
|
+
- [Overview](#overview)
|
|
42
|
+
- [Key Features](#key-features)
|
|
43
|
+
- [Installation](#installation)
|
|
44
|
+
- [Quick Start](#quick-start)
|
|
45
|
+
- [CLI Command Guide](#cli-command-guide)
|
|
46
|
+
- [`stackvet doctor` (aliases: `diagnose`, `health`)](#stackvet-doctor)
|
|
47
|
+
- [`stackvet check` (aliases: `scan`, `audit`)](#stackvet-check)
|
|
48
|
+
- [`stackvet inspect` (aliases: `examine`, `details`)](#stackvet-inspect)
|
|
49
|
+
- [`stackvet explain`](#stackvet-explain)
|
|
50
|
+
- [`stackvet fix` (aliases: `remediate`, `auto-fix`)](#stackvet-fix)
|
|
51
|
+
- [`stackvet graph` (aliases: `architecture`, `dependencies`)](#stackvet-graph)
|
|
52
|
+
- [`stackvet baseline`](#stackvet-baseline)
|
|
53
|
+
- [`stackvet init` (alias: `setup`)](#stackvet-init)
|
|
54
|
+
- [`stackvet rules` (aliases: `catalog`, `list-rules`)](#stackvet-rules)
|
|
55
|
+
- [Diagnostic Rules Catalog (132 Rules)](#diagnostic-rules-catalog)
|
|
56
|
+
- [Python Dependency Rules (`DEP-xxx`)](#python-dependency-rules-dep-xxx)
|
|
57
|
+
- [Node Dependency Rules (`NDEP-xxx`)](#node-dependency-rules-ndep-xxx)
|
|
58
|
+
- [Import & Architecture Rules (`IMP-xxx`, `ARC-xxx`)](#import--architecture-rules-imp-xxx-arc-xxx)
|
|
59
|
+
- [Environment & Drift Rules (`ENV-xxx`)](#environment--drift-rules-env-xxx)
|
|
60
|
+
- [Docker Rules (`DOC-xxx`)](#docker-rules-doc-xxx)
|
|
61
|
+
- [FastAPI Framework Rules (`FAP-xxx`)](#fastapi-framework-rules-fap-xxx)
|
|
62
|
+
- [SQLAlchemy Rules (`SQL-xxx`)](#sqlalchemy-rules-sql-xxx)
|
|
63
|
+
- [Django Rules (`DJG-xxx`)](#django-rules-djg-xxx)
|
|
64
|
+
- [Celery Rules (`CEL-xxx`)](#celery-rules-cel-xxx)
|
|
65
|
+
- [React & Next.js Rules (`RCT-xxx`, `NXT-xxx`)](#react--nextjs-rules-rct-xxx-nxt-xxx)
|
|
66
|
+
- [Output Formats](#output-formats)
|
|
67
|
+
- [CI/CD Integration](#cicd-integration)
|
|
68
|
+
- [Publishing to npm & PyPI](#publishing-to-npm--pypi)
|
|
69
|
+
- [Architecture & Workspace Structure](#architecture--workspace-structure)
|
|
70
|
+
- [Contributing](#contributing)
|
|
71
|
+
- [License](#license)
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Overview
|
|
76
|
+
|
|
77
|
+
Modern software applications are polyglot by nature: Python backends (FastAPI, Django), Node/TypeScript frontends (React, Next.js), Docker containers, and CI/CD pipelines.
|
|
78
|
+
|
|
79
|
+
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.
|
|
80
|
+
|
|
81
|
+
**StackVet** bridges this gap:
|
|
82
|
+
1. **Parallel Static Analysis**: Uses Rust with `ruff_python_parser` and `oxc_parser` to inspect ASTs without running user code.
|
|
83
|
+
2. **Cross-Layer Drift Detection**: Detects mismatches between local environments, package manifests, lockfiles, Docker images, and CI matrix definitions.
|
|
84
|
+
3. **Correlation Engine**: Groups individual symptoms into concise **Root Cause Clusters**.
|
|
85
|
+
4. **Health Score & Grade**: Produces an actionable 0–100 health score with letter grades (A through F).
|
|
86
|
+
5. **Format-Preserving Auto-Fixes**: Injects missing dependencies into `pyproject.toml` or `package.json` preserving user comments and indentation using `toml_edit`.
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## Key Features
|
|
91
|
+
|
|
92
|
+
- **Blazing Fast**: Native Rust engine with Rayon parallel processing; analyzes multi-thousand-file repositories in milliseconds.
|
|
93
|
+
- **AST-Level Accuracy**: Direct AST traversal eliminating regex false positives.
|
|
94
|
+
- **Circular Dependency Detection**: Detects import cycles using Tarjan's Strongly Connected Components (SCC) algorithm.
|
|
95
|
+
- **Zero-Config Discovery**: Automatically discovers `pyproject.toml`, `requirements.txt`, `uv.lock`, `package.json`, `pnpm-lock.yaml`, Dockerfiles, and GitHub workflows.
|
|
96
|
+
- **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.
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Installation
|
|
101
|
+
|
|
102
|
+
### Via Cargo (Rust)
|
|
103
|
+
```bash
|
|
104
|
+
cargo install stackvet
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Via uv / pip (Python)
|
|
108
|
+
```bash
|
|
109
|
+
# Run instantly with uvx (no install required):
|
|
110
|
+
uvx stackvet doctor
|
|
111
|
+
|
|
112
|
+
# Or install with pip / pipx:
|
|
113
|
+
pip install stackvet
|
|
114
|
+
# or
|
|
115
|
+
pipx install stackvet
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Via npm / npx (Node.js)
|
|
119
|
+
```bash
|
|
120
|
+
# Run instantly with npx:
|
|
121
|
+
npx stackvet doctor
|
|
122
|
+
|
|
123
|
+
# Or install in your project:
|
|
124
|
+
pnpm add -D stackvet
|
|
125
|
+
# or
|
|
126
|
+
npm install --save-dev stackvet
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## Quick Start
|
|
132
|
+
|
|
133
|
+
Run a full project health check in your repository root:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
stackvet doctor
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Output:
|
|
140
|
+
```text
|
|
141
|
+
=======================================================================
|
|
142
|
+
StackVet Universal Project Health Report
|
|
143
|
+
=======================================================================
|
|
144
|
+
|
|
145
|
+
Health Score: 92 / 100
|
|
146
|
+
Overall Grade: A (Healthy)
|
|
147
|
+
|
|
148
|
+
Critical: 0 | Errors: 0 | Warnings: 2
|
|
149
|
+
|
|
150
|
+
--- Root Cause Clusters (1) ---
|
|
151
|
+
1. [WARN] Environment, Lockfile & Runtime Drift
|
|
152
|
+
Summary: Detected 1 discrepancy(ies) between local manifests, Docker, CI matrix, or lockfiles.
|
|
153
|
+
Remediation: Align runtime version declarations across pyproject, package.json, Dockerfile, and CI workflows.
|
|
154
|
+
Symptoms Count: 1
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## CLI Command Guide
|
|
160
|
+
|
|
161
|
+
All subcommands support positional path arguments (e.g. `stackvet doctor ./backend`) as well as the global `-p / --path` option.
|
|
162
|
+
|
|
163
|
+
### `stackvet doctor` (aliases: `diagnose`, `health`)
|
|
164
|
+
Runs a comprehensive health check, aggregates symptoms into root causes, and assigns a health grade (A–F).
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
# Run on current directory
|
|
168
|
+
stackvet doctor
|
|
169
|
+
|
|
170
|
+
# Run on a target directory (positional or -p)
|
|
171
|
+
stackvet doctor ./backend
|
|
172
|
+
stackvet -p ./services/api doctor
|
|
173
|
+
|
|
174
|
+
# Using intuitive aliases
|
|
175
|
+
stackvet health ./backend
|
|
176
|
+
stackvet diagnose
|
|
177
|
+
|
|
178
|
+
# Fail CI with exit code 1 if health score is below 85
|
|
179
|
+
stackvet doctor --min-score 85
|
|
180
|
+
|
|
181
|
+
# Output in standalone HTML report
|
|
182
|
+
stackvet --format html doctor > health-report.html
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
### `stackvet check` (aliases: `scan`, `audit`)
|
|
188
|
+
A fast gate optimized for pre-commit hooks and CI pipelines. Returns exit code `0` if clean, or `1` if errors are detected.
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
# Normal check (fails only on ERROR and CRITICAL)
|
|
192
|
+
stackvet check ./backend
|
|
193
|
+
stackvet scan ./backend
|
|
194
|
+
|
|
195
|
+
# Strict mode (fails on WARNINGS as well)
|
|
196
|
+
stackvet check --strict
|
|
197
|
+
stackvet audit --strict
|
|
198
|
+
|
|
199
|
+
# Output machine-readable JSON in CI
|
|
200
|
+
stackvet --format json check
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
### `stackvet inspect` (aliases: `examine`, `details`)
|
|
206
|
+
Deep diagnostics inspection displaying code locations, snippets, severity, and targeted remediation guides.
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
# Inspect all detected diagnostics
|
|
210
|
+
stackvet inspect ./backend
|
|
211
|
+
stackvet examine ./backend
|
|
212
|
+
|
|
213
|
+
# Filter diagnostics by rule category prefix:
|
|
214
|
+
stackvet inspect --rule FAP # Only FastAPI rules
|
|
215
|
+
stackvet inspect --rule SQL # Only SQLAlchemy rules
|
|
216
|
+
stackvet inspect --rule DOC # Only Docker rules
|
|
217
|
+
stackvet inspect --rule RCT # Only React rules
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
### `stackvet explain`
|
|
223
|
+
Displays in-depth documentation, potential runtime consequences, code examples, and remediation steps for any diagnostic rule code.
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
# Explain any rule in detail
|
|
227
|
+
stackvet explain FAP-001
|
|
228
|
+
stackvet explain SQL-004
|
|
229
|
+
stackvet explain DOC-001
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
### `stackvet fix` (aliases: `remediate`, `auto-fix`)
|
|
235
|
+
Applies safe, format-preserving automated remediations (e.g. injecting missing packages into `pyproject.toml` or `package.json`).
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
# Preview available safe fixes
|
|
239
|
+
stackvet fix
|
|
240
|
+
stackvet remediate
|
|
241
|
+
|
|
242
|
+
# Apply all fixes automatically without prompts
|
|
243
|
+
stackvet fix --yes
|
|
244
|
+
stackvet auto-fix --yes
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
### `stackvet graph` (aliases: `architecture`, `dependencies`)
|
|
250
|
+
Visualizes project module dependencies and detects circular import cycles.
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
# Clean ASCII hierarchy
|
|
254
|
+
stackvet graph --style ascii
|
|
255
|
+
stackvet architecture
|
|
256
|
+
|
|
257
|
+
# Mermaid diagram (pasteable directly into GitHub Markdown or Notion)
|
|
258
|
+
stackvet graph --style mermaid
|
|
259
|
+
|
|
260
|
+
# Graphviz DOT format
|
|
261
|
+
stackvet graph --style dot
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
---
|
|
265
|
+
|
|
266
|
+
### `stackvet baseline`
|
|
267
|
+
Records existing issues in legacy codebases to prevent CI failures on technical debt while blocking new regressions.
|
|
268
|
+
|
|
269
|
+
```bash
|
|
270
|
+
# Record current diagnostics into baseline
|
|
271
|
+
stackvet baseline record ./backend
|
|
272
|
+
|
|
273
|
+
# Verify in CI that no new regressions were introduced
|
|
274
|
+
stackvet baseline verify ./backend
|
|
275
|
+
|
|
276
|
+
# Strict verification (fails on new warnings too)
|
|
277
|
+
stackvet baseline verify ./backend --strict
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
---
|
|
281
|
+
|
|
282
|
+
### `stackvet init` (alias: `setup`)
|
|
283
|
+
Bootstraps a recommended `.stackvet.toml` configuration and optional GitHub Actions CI workflow.
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
# Generate .stackvet.toml
|
|
287
|
+
stackvet init
|
|
288
|
+
|
|
289
|
+
# Generate configuration AND GitHub Actions CI workflow (.github/workflows/stackvet.yml)
|
|
290
|
+
stackvet init --ci
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
---
|
|
294
|
+
|
|
295
|
+
### `stackvet rules` (aliases: `catalog`, `list-rules`)
|
|
296
|
+
Displays the complete catalog of 132 supported diagnostic rules across Python, Node.js, Docker, CI/CD, and frameworks.
|
|
297
|
+
|
|
298
|
+
```bash
|
|
299
|
+
# Show all rules in a formatted table
|
|
300
|
+
stackvet rules
|
|
301
|
+
|
|
302
|
+
# Filter catalog by ecosystem or framework
|
|
303
|
+
stackvet rules docker
|
|
304
|
+
stackvet rules fastapi
|
|
305
|
+
stackvet rules sqlalchemy
|
|
306
|
+
stackvet rules react
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
---
|
|
310
|
+
|
|
311
|
+
## Diagnostic Rules Catalog
|
|
312
|
+
|
|
313
|
+
### Python Dependency Rules (`DEP-xxx`)
|
|
314
|
+
|
|
315
|
+
| Rule ID | Severity | Name | Description |
|
|
316
|
+
|---|---|---|---|
|
|
317
|
+
| `DEP-001` | `ERROR` | Version Conflict | Detects conflicting version specifiers in dependencies (e.g. `foo>=2.0` vs `foo<2.0`). |
|
|
318
|
+
| `DEP-002` | `ERROR` | Missing Declaration | Imported package is used in Python code but not declared in `pyproject.toml` or `requirements.txt`. |
|
|
319
|
+
| `DEP-003` | `WARN` | Unused Dependency | Package listed in dependencies is never imported by any Python source files. |
|
|
320
|
+
| `DEP-004` | `ERROR` | Python Version Incompatible | Package requirements target end-of-life Python runtimes (e.g. `<3.10`). |
|
|
321
|
+
| `DEP-005` | `WARN` | Lockfile Drift | Manifest file exists (`pyproject.toml`) but lockfile (`uv.lock`/`poetry.lock`) is missing. |
|
|
322
|
+
| `DEP-006` | `CRITICAL` | Vulnerability Audit | Batched security audit against OSV database for known CVEs. |
|
|
323
|
+
| `DEP-007` | `WARN` | Transitive Dependency Import | Package imported is present in lockfile but not directly declared in `pyproject.toml`. |
|
|
324
|
+
|
|
325
|
+
---
|
|
326
|
+
|
|
327
|
+
### Node Dependency Rules (`NDEP-xxx`)
|
|
328
|
+
|
|
329
|
+
| Rule ID | Severity | Name | Description |
|
|
330
|
+
|---|---|---|---|
|
|
331
|
+
| `NDEP-001` | `ERROR` | Missing Node Package | Package imported in `.ts`/`.tsx`/`.js` is missing from `package.json`. |
|
|
332
|
+
| `NDEP-002` | `WARN` | Unused Node Package | Production dependency in `package.json` is never imported in source files. |
|
|
333
|
+
| `NDEP-003` | `ERROR` | Unmet Peer Dependency | Declared dependencies conflict with peer dependency constraints. |
|
|
334
|
+
| `NDEP-004` | `WARN` | Lockfile Out of Sync | Missing lockfile (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`). |
|
|
335
|
+
| `NDEP-005` | `ERROR` | DevDependency in Production | A package from `devDependencies` is imported inside production source files (outside test files). |
|
|
336
|
+
|
|
337
|
+
---
|
|
338
|
+
|
|
339
|
+
### Import & Architecture Rules (`IMP-xxx`, `ARC-xxx`)
|
|
340
|
+
|
|
341
|
+
| Rule ID | Severity | Name | Description |
|
|
342
|
+
|---|---|---|---|
|
|
343
|
+
| `IMP-001` | `ERROR` | Circular Imports | Import cycle detected across modules (e.g. `a -> b -> c -> a`). |
|
|
344
|
+
| `IMP-002` | `ERROR` | Unresolved Local Import | Relative import path (`./utils`, `from .mod`) has no corresponding file on disk. |
|
|
345
|
+
| `IMP-003` | `WARN` | Orphan File / Dead Code | Source file has 0 incoming imports and is not an application entrypoint. |
|
|
346
|
+
| `IMP-004` | `ERROR` | PEP 594 Removed Stdlib | Importing deprecated standard library module removed in Python 3.13 (`cgi`, `pipes`, `imp`, `crypt`, etc.). |
|
|
347
|
+
| `ARC-001` | `WARN` | Layer Violation | Lower-tier persistence layer directly imports upper-tier presentation or API layers. |
|
|
348
|
+
| `ARC-002` | `WARN` | Component Cycle | Cross-boundary cycles detected between top-level feature directories. |
|
|
349
|
+
|
|
350
|
+
---
|
|
351
|
+
|
|
352
|
+
### Environment & Drift Rules (`ENV-xxx`)
|
|
353
|
+
|
|
354
|
+
| Rule ID | Severity | Name | Description |
|
|
355
|
+
|---|---|---|---|
|
|
356
|
+
| `ENV-001` | `WARN` | Runtime Drift | `.python-version` or `.nvmrc` contradicts the runtime constraint in `pyproject.toml` or `package.json`. |
|
|
357
|
+
| `ENV-002` | `ERROR` | Docker Drift | `Dockerfile` base image (e.g. `python:3.10-slim`) contradicts project requirement (`>=3.12`). |
|
|
358
|
+
| `ENV-003` | `ERROR` | CI Matrix Drift | GitHub Actions workflow matrix runs tests on unsupported runtime versions. |
|
|
359
|
+
|
|
360
|
+
---
|
|
361
|
+
|
|
362
|
+
### FastAPI Framework Rules (`FAP-xxx`)
|
|
363
|
+
|
|
364
|
+
| Rule ID | Severity | Name | Description |
|
|
365
|
+
|---|---|---|---|
|
|
366
|
+
| `FAP-001` | `CRITICAL` | Blocking Call in Async Route | Calling blocking functions (`time.sleep()`, synchronous `requests.*`, `subprocess.*`) inside `async def` routes. |
|
|
367
|
+
| `FAP-003` | `WARN` | Missing Response Model | FastAPI route handler lacks a `response_model` argument or return type annotation (`-> Model`). |
|
|
368
|
+
| `FAP-004` | `CRITICAL` | Insecure Wildcard CORS | `CORSMiddleware` configured with `allow_origins=["*"]` combined with `allow_credentials=True`. |
|
|
369
|
+
| `FAP-006` | `ERROR` | Missing Path Parameter | URL template contains a placeholder (e.g. `/{item_id}`) not present in handler arguments. |
|
|
370
|
+
| `FAP-008` | `WARN` | Deprecated on_event | Using `@app.on_event("startup")` instead of modern `lifespan` context managers. |
|
|
371
|
+
| `FAP-010` | `ERROR` | Duplicate Route Path | Multiple handlers registered for the exact same HTTP method and path template. |
|
|
372
|
+
| `FAP-011` | `ERROR` | Mutable Default Argument | Route parameter has a mutable default value (e.g. `def list_items(tags: list = []):`). |
|
|
373
|
+
| `FAP-015` | `ERROR` | Sync File I/O in Async Handler | Synchronous `open()` or `with open(...)` executed inside an `async def` route handler. |
|
|
374
|
+
|
|
375
|
+
---
|
|
376
|
+
|
|
377
|
+
### React & Next.js Rules (`RCT-xxx`, `NXT-xxx`)
|
|
378
|
+
|
|
379
|
+
| Rule ID | Severity | Name | Description |
|
|
380
|
+
|---|---|---|---|
|
|
381
|
+
| `RCT-001` | `WARN` | Missing Hook Dependencies | `useEffect` or `useCallback` missing referenced variables in dependency array. |
|
|
382
|
+
| `RCT-002` | `ERROR` | Conditional Hook Call | React hook (`useState`, `useEffect`) invoked conditionally inside an `if` block. |
|
|
383
|
+
| `RCT-003` | `ERROR` | Direct State Mutation | Modifying state directly (`state.foo = 1`) rather than calling state dispatcher. |
|
|
384
|
+
| `RCT-004` | `WARN` | Missing Key in List | JSX elements rendered inside `.map()` missing a unique `key` prop. |
|
|
385
|
+
| `RCT-005` | `WARN` | Barrel Import Bloat | Importing from root barrel exports (e.g. `from '@mui/material'`) causing bundle bloat. |
|
|
386
|
+
| `NXT-001` | `ERROR` | Server Component Client API | Browser APIs (`window`, `localStorage`) or client hooks used without `"use client"` directive. |
|
|
387
|
+
| `NXT-002` | `CRITICAL` | Client Component Private Secret | Client Component accesses private environment variable (not prefixed with `NEXT_PUBLIC_`). |
|
|
388
|
+
|
|
389
|
+
---
|
|
390
|
+
|
|
391
|
+
## Output Formats
|
|
392
|
+
|
|
393
|
+
StackVet supports 4 built-in egress formats via `--format`:
|
|
394
|
+
|
|
395
|
+
| Format | Description | Command Example |
|
|
396
|
+
|---|---|---|
|
|
397
|
+
| `text` (default) | Colored ANSI terminal output with tables and scorecard | `stackvet doctor` |
|
|
398
|
+
| `json` | Structured JSON with full diagnostics and root causes | `stackvet --format json check` |
|
|
399
|
+
| `sarif` | OASIS SARIF v2.1.0 for GitHub Code Scanning tab | `stackvet --format sarif doctor > results.sarif` |
|
|
400
|
+
| `html` | Standalone responsive dark-mode HTML report | `stackvet --format html doctor > report.html` |
|
|
401
|
+
|
|
402
|
+
---
|
|
403
|
+
|
|
404
|
+
## CI/CD Integration
|
|
405
|
+
|
|
406
|
+
### GitHub Actions (with SARIF Security Tab)
|
|
407
|
+
|
|
408
|
+
```yaml
|
|
409
|
+
name: StackVet Health Check
|
|
410
|
+
|
|
411
|
+
on:
|
|
412
|
+
push:
|
|
413
|
+
branches: [main]
|
|
414
|
+
pull_request:
|
|
415
|
+
|
|
416
|
+
jobs:
|
|
417
|
+
health:
|
|
418
|
+
runs-on: ubuntu-latest
|
|
419
|
+
steps:
|
|
420
|
+
- uses: actions/checkout@v4
|
|
421
|
+
|
|
422
|
+
- name: Install StackVet
|
|
423
|
+
run: cargo install stackvet
|
|
424
|
+
|
|
425
|
+
# Fast CI Gate (Fails on Error)
|
|
426
|
+
- name: Run StackVet Check
|
|
427
|
+
run: stackvet check --strict
|
|
428
|
+
|
|
429
|
+
# Generate SARIF report for GitHub Code Scanning
|
|
430
|
+
- name: Generate SARIF Report
|
|
431
|
+
if: always()
|
|
432
|
+
run: stackvet --format sarif doctor > stackvet-results.sarif
|
|
433
|
+
|
|
434
|
+
- name: Upload SARIF to GitHub Security Tab
|
|
435
|
+
uses: github/codeql-action/upload-sarif@v3
|
|
436
|
+
if: always()
|
|
437
|
+
with:
|
|
438
|
+
sarif_file: stackvet-results.sarif
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
### Pre-Commit Hook (`.pre-commit-config.yaml`)
|
|
442
|
+
|
|
443
|
+
```yaml
|
|
444
|
+
repos:
|
|
445
|
+
- repo: local
|
|
446
|
+
hooks:
|
|
447
|
+
- id: stackvet
|
|
448
|
+
name: stackvet check
|
|
449
|
+
entry: stackvet check
|
|
450
|
+
language: system
|
|
451
|
+
pass_filenames: false
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
---
|
|
455
|
+
|
|
456
|
+
## Publishing to npm & PyPI
|
|
457
|
+
|
|
458
|
+
StackVet includes dedicated automated GitHub Actions workflows and local build scripts for publishing to npm and PyPI:
|
|
459
|
+
|
|
460
|
+
- **npm Workflow**: [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml)
|
|
461
|
+
- **PyPI Workflow**: [`.github/workflows/publish-pypi.yml`](.github/workflows/publish-pypi.yml)
|
|
462
|
+
- **Detailed Step-by-Step Guide**: See the complete [Publishing Guide](docs/publishing_guide.md) for prerequisites, token setup, and verification.
|
|
463
|
+
|
|
464
|
+
```bash
|
|
465
|
+
# Build PyPI distribution (wheel & sdist)
|
|
466
|
+
npm run build:pypi
|
|
467
|
+
|
|
468
|
+
# Build npm package & tarball
|
|
469
|
+
npm run build:npm
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
---
|
|
473
|
+
|
|
474
|
+
## Architecture & Workspace Structure
|
|
475
|
+
|
|
476
|
+
StackVet is designed as a modular Cargo workspace:
|
|
477
|
+
|
|
478
|
+
```text
|
|
479
|
+
stackvet/
|
|
480
|
+
├── Cargo.toml # Workspace root
|
|
481
|
+
├── crates/
|
|
482
|
+
│ ├── stackvet-core/ # Core models: Diagnostic, Rule, Severity, ProjectContext, RootCause
|
|
483
|
+
│ ├── stackvet-scanner/ # Discovery engine with ignore::WalkBuilder
|
|
484
|
+
│ ├── stackvet-python/ # Python AST (ruff_python_parser), manifests & lockfiles
|
|
485
|
+
│ ├── stackvet-node/ # Node/TS AST (oxc_parser), package.json & builtins
|
|
486
|
+
│ ├── stackvet-graph/ # Tarjan's SCC cycle detection (petgraph)
|
|
487
|
+
│ ├── stackvet-analyzers/ # Core analyzers: deps, env, imports, drift
|
|
488
|
+
│ ├── stackvet-frameworks/ # Framework engines: FastAPI, React, Next.js
|
|
489
|
+
│ ├── stackvet-correlation/ # Root cause clustering and health scoring (0-100)
|
|
490
|
+
│ ├── stackvet-remediation/ # Format-preserving auto-fixes (toml_edit)
|
|
491
|
+
│ ├── stackvet-reporter/ # Terminal, SARIF v2.1.0, JSON, HTML reporters
|
|
492
|
+
│ └── stackvet-cli/ # CLI binary entrypoint (clap)
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
---
|
|
496
|
+
|
|
497
|
+
## Contributing
|
|
498
|
+
|
|
499
|
+
1. Clone repository:
|
|
500
|
+
```bash
|
|
501
|
+
git clone https://github.com/stackvet/stackvet.git
|
|
502
|
+
cd stackvet
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
2. Run test suite:
|
|
506
|
+
```bash
|
|
507
|
+
cargo test
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
3. Run locally against sample code:
|
|
511
|
+
```bash
|
|
512
|
+
cargo run -p stackvet -- doctor
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
Pull requests and rule proposals are welcome!
|
|
516
|
+
|
|
517
|
+
---
|
|
518
|
+
|
|
519
|
+
## License
|
|
520
|
+
|
|
521
|
+
StackVet is licensed under the [MIT License](LICENSE).
|
|
522
|
+
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
stackvet-0.1.0.data/scripts/stackvet.exe,sha256=HBQS9WfwnxThum_cAgduPAZC1KHw9laXkmzGNx3ppDo,6090752
|
|
2
|
+
stackvet-0.1.0.dist-info/METADATA,sha256=TwyiNPIX6QzJeVrkgI0cV6H8UseyhCQ7xD8HboWwayY,20091
|
|
3
|
+
stackvet-0.1.0.dist-info/WHEEL,sha256=8Aej0W0a6Cz6apA3IzJrTnxLRVLAt-w0Oh8SA3Con_c,94
|
|
4
|
+
stackvet-0.1.0.dist-info/licenses/LICENSE,sha256=XjDJweU6-DiAaxzPXdpkxdbDE5fEX4uYvGVjhb6GYUw,1099
|
|
5
|
+
stackvet-0.1.0.dist-info/sboms/stackvet.cyclonedx.json,sha256=n6z40ZtWTmum2niLFJ0hGB3zbCA47t0iHuLTEtG8Epg,310247
|
|
6
|
+
stackvet-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 StackVet Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|