@vibgrate/cli 1.0.44 → 1.0.46

package/DOCS.md

@@ -1,6 +1,6 @@
 # Vibgrate CLI — Full Documentation
 
-> Continuous Drift Intelligence for Node & .NET
+> Continuous Drift Intelligence for Node, .NET, Python, and Java
 
 For a quick overview, see the [README](./README.md). This document covers everything in detail.
 
@@ -9,15 +9,18 @@ For a quick overview, see the [README](./README.md). This document covers everyt
 ## Table of Contents
 
 - [How It Works](#how-it-works)
+- [Choosing a rollout model: one-off vs CI](#choosing-a-rollout-model-one-off-vs-ci)
 - [Commands Reference](#commands-reference)
   - [vibgrate init](#vibgrate-init)
   - [vibgrate scan](#vibgrate-scan)
   - [vibgrate baseline](#vibgrate-baseline)
   - [vibgrate report](#vibgrate-report)
+  - [vibgrate sbom](#vibgrate-sbom)
   - [vibgrate push](#vibgrate-push)
   - [vibgrate dsn create](#vibgrate-dsn-create)
   - [vibgrate update](#vibgrate-update)
 - [Upgrade Drift Score](#upgrade-drift-score)
+- [Drift Baselines & Fitness Functions](#drift-baselines--fitness-functions)
   - [How the Score Is Calculated](#how-the-score-is-calculated)
   - [Risk Levels](#risk-levels)
   - [Score Components](#score-components)
@@ -34,6 +37,7 @@ For a quick overview, see the [README](./README.md). This document covers everyt
   - [Platform Matrix](#platform-matrix)
   - [Dependency Risk](#dependency-risk)
   - [Dependency Graph & Duplication](#dependency-graph--duplication)
+  - [SBOM-ready Supply Chain Inventory](#sbom-ready-supply-chain-inventory)
   - [Tooling Inventory](#tooling-inventory)
   - [Build & Deploy Surface Area](#build--deploy-surface-area)
   - [TypeScript Modernity](#typescript-modernity)
@@ -42,6 +46,9 @@ For a quick overview, see the [README](./README.md). This document covers everyt
   - [Security Posture](#security-posture)
   - [Security Scanners](#security-scanners)
   - [Service Dependencies](#service-dependencies)
+  - [Architecture Layers](#architecture-layers)
+  - [Code Quality Metrics](#code-quality-metrics)
+  - [OWASP Category Mapping](#owasp-category-mapping)
 - [CI Integration](#ci-integration)
   - [GitHub Actions](#github-actions)
   - [Azure DevOps](#azure-devops)
@@ -58,7 +65,7 @@ For a quick overview, see the [README](./README.md). This document covers everyt
 
 ## How It Works
 
-Vibgrate recursively scans your repository for `package.json` (Node/TypeScript) and `.sln`/`.csproj` (.NET) files. For each project it discovers, it:
+Vibgrate recursively scans your repository for `package.json` (Node/TypeScript), `.sln`/`.csproj` (.NET), Python manifests, and Java build manifests. For each project it discovers, it:
 
 1. **Detects** the runtime version, target framework, and all dependencies
 2. **Queries** the npm/NuGet registry for latest stable versions (with built-in caching and concurrency control)
@@ -70,6 +77,22 @@ Core drift analysis does not execute source code. Optional security scanners can
 
 ---
 
+## Choosing a rollout model: one-off vs CI
+
+Most teams adopt Vibgrate in two steps:
+
+1. **One-off scan** to establish a baseline and identify immediate upgrade priorities.
+2. **CI integration** to continuously detect drift regression on every pull request/build.
+
+| Mode               | Benefits                                                                    | Typical command                                           |
+| ------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------- |
+| One-off scan       | Fast snapshot of current upgrade debt, useful for audits and planning       | `npx @vibgrate/cli scan .`                                |
+| CI-integrated scan | Continuous governance with automated failure thresholds and SARIF surfacing | `npx @vibgrate/cli scan . --format sarif --fail-on error` |
+
+In practice, one-off scans tell you where you are today; CI keeps you from drifting back tomorrow.
+
+---
+
 ## Commands Reference
 
 ### vibgrate init
@@ -80,12 +103,13 @@ Initialise Vibgrate in a project.
 vibgrate init [path] [--baseline] [--yes]
 ```
 
-| Flag | Description |
-|------|-------------|
+| Flag         | Description                                 |
+| ------------ | ------------------------------------------- |
 | `--baseline` | Create an initial drift baseline after init |
-| `--yes` | Skip confirmation prompts |
+| `--yes`      | Skip confirmation prompts                   |
 
 Creates:
+
 - `.vibgrate/` directory
 - `vibgrate.config.ts` with sensible defaults
 
@@ -96,7 +120,7 @@ Creates:
 The primary command. Scans your project for upgrade drift.
 
 ```bash
-vibgrate scan [path] [--format text|json|sarif] [--out <file>] [--fail-on warn|error] [--baseline <file>] [--changed-only] [--concurrency <n>]
+vibgrate scan [path] [--format text|json|sarif] [--out <file>] [--fail-on warn|error] [--baseline <file>] [--drift-budget <score>] [--drift-worsening <percent>] [--changed-only] [--concurrency <n>]
 ```
 
 | Flag | Default | Description |
@@ -107,6 +131,8 @@ vibgrate scan [path] [--format text|json|sarif] [--out <file>] [--fail-on warn|e
 | `--baseline <file>` | — | Compare against a previous baseline |
 | `--changed-only` | — | Only scan changed files |
 | `--concurrency <n>` | `8` | Max concurrent npm registry calls |
+| `--drift-budget <score>` | — | Fitness gate: fail if drift score is above this budget |
+| `--drift-worsening <percent>` | — | Fitness gate: fail if drift worsens by more than % vs baseline |
 
 The scan always writes the full artifact to `.vibgrate/scan_result.json`.
 
@@ -132,10 +158,28 @@ Generate a human-readable report from a scan artifact.
 vibgrate report [--in <file>] [--format md|text|json]
 ```
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--in` | `.vibgrate/scan_result.json` | Input artifact file |
-| `--format` | `text` | Output format: `md`, `text`, or `json` |
+| Flag       | Default                      | Description                            |
+| ---------- | ---------------------------- | -------------------------------------- |
+| `--in`     | `.vibgrate/scan_result.json` | Input artifact file                    |
+| `--format` | `text`                       | Output format: `md`, `text`, or `json` |
+
+---
+
+### vibgrate sbom
+
+Export SBOMs from an existing scan artifact or compare two artifacts.
+
+```bash
+vibgrate sbom export [--in <file>] [--format cyclonedx|spdx] [--out <file>]
+vibgrate sbom delta --from <file> --to <file> [--out <file>]
+```
+
+| Command | Description |
+|---------|-------------|
+| `vibgrate sbom export` | Emit CycloneDX or SPDX JSON from a scan artifact |
+| `vibgrate sbom delta` | Compare dependencies between two artifacts (added/removed/changed + drift delta) |
+
+Use this to treat SBOMs as operational intelligence instead of static compliance output.
 
 ---
 
@@ -147,12 +191,12 @@ Upload scan results to the Vibgrate dashboard API.
 vibgrate push [--dsn <dsn>] [--file <file>] [--region <region>] [--strict]
 ```
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--dsn` | `VIBGRATE_DSN` env | DSN token for authentication |
-| `--file` | `.vibgrate/scan_result.json` | Scan artifact to upload |
-| `--region` | — | Override data residency region (`us`, `eu`) |
-| `--strict` | — | Fail hard on upload errors |
+| Flag       | Default                      | Description                                 |
+| ---------- | ---------------------------- | ------------------------------------------- |
+| `--dsn`    | `VIBGRATE_DSN` env           | DSN token for authentication                |
+| `--file`   | `.vibgrate/scan_result.json` | Scan artifact to upload                     |
+| `--region` | —                            | Override data residency region (`us`, `eu`) |
+| `--strict` | —                            | Fail hard on upload errors                  |
 
 Upload is always optional. Best-effort by default — use `--strict` in CI if you want the pipeline to fail on upload errors.
 
@@ -166,12 +210,12 @@ Generate an HMAC-signed DSN token for API authentication.
 vibgrate dsn create --workspace <id> [--region <region>] [--ingest <url>] [--write <path>]
 ```
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--workspace` | *required* | Your workspace ID |
-| `--region` | `us` | Data residency region (`us`, `eu`) |
-| `--ingest` | — | Custom ingest API URL (overrides `--region`) |
-| `--write` | — | Write DSN to a file (add to `.gitignore`!) |
+| Flag          | Default    | Description                                  |
+| ------------- | ---------- | -------------------------------------------- |
+| `--workspace` | _required_ | Your workspace ID                            |
+| `--region`    | `us`       | Data residency region (`us`, `eu`)           |
+| `--ingest`    | —          | Custom ingest API URL (overrides `--region`) |
+| `--write`     | —          | Write DSN to a file (add to `.gitignore`!)   |
 
 ---
 
@@ -183,13 +227,38 @@ Check for and install updates.
 vibgrate update [--check] [--pm <manager>]
 ```
 
-| Flag | Description |
-|------|-------------|
-| `--check` | Only check for updates, don't install |
-| `--pm` | Force a package manager (`npm`, `pnpm`, `yarn`, `bun`) |
+| Flag      | Description                                            |
+| --------- | ------------------------------------------------------ |
+| `--check` | Only check for updates, don't install                  |
+| `--pm`    | Force a package manager (`npm`, `pnpm`, `yarn`, `bun`) |
 
 ---
 
+## Drift Baselines & Fitness Functions
+
+Vibgrate stores scan state under `.vibgrate/`:
+
+- `.vibgrate/scan_result.json`: latest scan artifact
+- `.vibgrate/baseline.json`: explicit baseline snapshot (`vibgrate baseline`)
+- `<project>/.vibgrate/project_score.json`: per-project score snapshots
+
+Recommended workflow:
+
+1. Create baseline once on main branch:
+   ```bash
+   vibgrate baseline .
+   ```
+2. In CI, run scan with comparison and gates:
+   ```bash
+   vibgrate scan --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5
+   ```
+3. When planned upgrades land, refresh baseline:
+   ```bash
+   vibgrate baseline .
+   ```
+
+This makes drift a formal quality gate (fitness function), not just reporting.
+
 ## Upgrade Drift Score
 
 ### How the Score Is Calculated
@@ -200,22 +269,22 @@ The Upgrade Drift Score is a deterministic, versioned metric (0–100) that repr
 
 ### Risk Levels
 
-| Score | Risk Level |
-|-------|------------|
-| 70–100 | **Low** — You're in good shape |
-| 40–69 | **Moderate** — Some attention needed |
-| 0–39 | **High** — Significant upgrade debt |
+| Score  | Risk Level                           |
+| ------ | ------------------------------------ |
+| 70–100 | **Low** — You're in good shape       |
+| 40–69  | **Moderate** — Some attention needed |
+| 0–39   | **High** — Significant upgrade debt  |
 
 ### Score Components
 
 The overall score is a weighted combination of four components:
 
-| Component | What It Measures |
-|-----------|-----------------|
-| **Runtime** | Node.js or .NET runtime major version lag |
-| **Frameworks** | Major version distance for core frameworks (React, Next, NestJS, ASP.NET, etc.) |
+| Component        | What It Measures                                                                  |
+| ---------------- | --------------------------------------------------------------------------------- |
+| **Runtime**      | Node.js or .NET runtime major version lag                                         |
+| **Frameworks**   | Major version distance for core frameworks (React, Next, NestJS, ASP.NET, etc.)   |
 | **Dependencies** | Age distribution across all dependencies (current vs 1 major behind vs 2+ behind) |
-| **EOL Risk** | Proximity to end-of-life for runtimes and frameworks |
+| **EOL Risk**     | Proximity to end-of-life for runtimes and frameworks                              |
 
 ---
 
@@ -224,6 +293,7 @@ The overall score is a weighted combination of four components:
 ### Text
 
 The default output. A coloured, human-readable report showing:
+
 - Overall drift score and risk level
 - Score component breakdown with visual bars
 - Per-project details: runtime lag, framework versions, dependency distribution
@@ -250,10 +320,10 @@ A clean Markdown report suitable for PRs, wikis, or documentation.
 Run `vibgrate init` to generate the config file, or create one manually:
 
 ```typescript
-import type { VibgrateConfig } from '@vibgrate/cli';
+import type { VibgrateConfig } from "@vibgrate/cli";
 
 const config: VibgrateConfig = {
-  exclude: ['legacy/**'],
+  exclude: ["legacy/**"],
   thresholds: {
     failOnError: {
       eolDays: 180,
@@ -266,17 +336,17 @@ const config: VibgrateConfig = {
     },
   },
   scanners: {
-    platformMatrix:         { enabled: true },
-    dependencyRisk:         { enabled: true },
-    dependencyGraph:        { enabled: true },
-    toolingInventory:       { enabled: true },
-    buildDeploy:            { enabled: true },
-    tsModernity:            { enabled: true },
+    platformMatrix: { enabled: true },
+    dependencyRisk: { enabled: true },
+    dependencyGraph: { enabled: true },
+    toolingInventory: { enabled: true },
+    buildDeploy: { enabled: true },
+    tsModernity: { enabled: true },
     breakingChangeExposure: { enabled: true },
-    fileHotspots:           { enabled: true },
-    securityPosture:        { enabled: true },
-    securityScanners:       { enabled: true },
-    serviceDependencies:    { enabled: true },
+    fileHotspots: { enabled: true },
+    securityPosture: { enabled: true },
+    securityScanners: { enabled: true },
+    serviceDependencies: { enabled: true },
   },
 };
 
@@ -289,13 +359,13 @@ Also supports `vibgrate.config.js` and `vibgrate.config.json`.
 
 Control when findings are raised and when the CLI should fail.
 
-| Threshold | Default | Triggers |
-|-----------|---------|----------|
-| `failOnError.eolDays` | 180 | Error finding when runtime EOL is within N days |
-| `failOnError.frameworkMajorLag` | 3 | Error finding when any framework is N+ majors behind |
-| `failOnError.dependencyTwoPlusPercent` | 50 | Error finding when N+% of dependencies are 2+ majors behind |
-| `warn.frameworkMajorLag` | 2 | Warning finding when any framework is N+ majors behind |
-| `warn.dependencyTwoPlusPercent` | 30 | Warning finding when N+% of dependencies are 2+ majors behind |
+| Threshold                              | Default | Triggers                                                      |
+| -------------------------------------- | ------- | ------------------------------------------------------------- |
+| `failOnError.eolDays`                  | 180     | Error finding when runtime EOL is within N days               |
+| `failOnError.frameworkMajorLag`        | 3       | Error finding when any framework is N+ majors behind          |
+| `failOnError.dependencyTwoPlusPercent` | 50      | Error finding when N+% of dependencies are 2+ majors behind   |
+| `warn.frameworkMajorLag`               | 2       | Warning finding when any framework is N+ majors behind        |
+| `warn.dependencyTwoPlusPercent`        | 30      | Warning finding when N+% of dependencies are 2+ majors behind |
 
 ### Scanner Toggles
 
@@ -339,19 +409,30 @@ Parses lockfiles (pnpm, npm, yarn, .NET) to build a workspace-wide dependency gr
 - Duplicated packages (multiple versions of the same package)
 - Phantom dependencies (used but not declared)
 
+### SBOM-ready Supply Chain Inventory
+
+Vibgrate artifacts include dependency graph and package inventory data that can be used for supply-chain governance workflows:
+
+- Lockfile-derived package counts (`totalUnique`, `totalInstalled`)
+- Duplicate-version hotspots to prioritize remediation
+- Phantom dependency evidence (`phantomDependencies` + details)
+- Inventory metadata that pairs well with internal SBOM pipelines
+
+> Vibgrate does not currently emit CycloneDX/SPDX files directly. Instead, it provides structured inventory data in `scan_result.json` so teams can integrate with existing SBOM tooling without slowing down CI scans.
+
 ### Tooling Inventory
 
 Maps the full technology stack across your workspace by detecting package names in dependencies:
 
-| Category | Examples |
-|----------|---------|
-| Frontend | React, Vue, Angular, Svelte, Solid |
-| Meta-frameworks | Next.js, Nuxt, Astro, Remix |
-| Bundlers | Vite, webpack, esbuild, Rollup |
-| Backend | Express, Fastify, NestJS, Hono |
-| ORM / DB | Prisma, Drizzle, TypeORM, EF Core |
-| Testing | Vitest, Jest, Playwright, xUnit |
-| Observability | Sentry, OpenTelemetry, Pino, Winston |
+| Category        | Examples                             |
+| --------------- | ------------------------------------ |
+| Frontend        | React, Vue, Angular, Svelte, Solid   |
+| Meta-frameworks | Next.js, Nuxt, Astro, Remix          |
+| Bundlers        | Vite, webpack, esbuild, Rollup       |
+| Backend         | Express, Fastify, NestJS, Hono       |
+| ORM / DB        | Prisma, Drizzle, TypeORM, EF Core    |
+| Testing         | Vitest, Jest, Playwright, xUnit      |
+| Observability   | Sentry, OpenTelemetry, Pino, Winston |
 
 ### Build & Deploy Surface Area
 
@@ -400,7 +481,6 @@ Structural security hygiene indicators (not a secret scanner):
 - `.env` files tracked outside `.gitignore`
 - Audit severity counts (via `npm audit --json`)
 
-
 ### Security Scanners
 
 Security scanner orchestration and readiness analysis focused on modern SAST and secrets tooling:
@@ -417,14 +497,42 @@ Security scanner orchestration and readiness analysis focused on modern SAST and
 
 Maps external service and platform dependencies by detecting SDK packages:
 
-| Category | Examples |
-|----------|---------|
-| Payment | Stripe, Braintree, PayPal |
-| Auth | Auth0, Clerk, Firebase, Passport |
-| Cloud SDKs | AWS, Azure, Google Cloud |
-| Databases | PostgreSQL, MongoDB, Redis |
-| Messaging | SQS, SNS, Kafka, BullMQ |
-| Observability | Sentry, DataDog, New Relic |
+| Category      | Examples                         |
+| ------------- | -------------------------------- |
+| Payment       | Stripe, Braintree, PayPal        |
+| Auth          | Auth0, Clerk, Firebase, Passport |
+| Cloud SDKs    | AWS, Azure, Google Cloud         |
+| Databases     | PostgreSQL, MongoDB, Redis       |
+| Messaging     | SQS, SNS, Kafka, BullMQ          |
+| Observability | Sentry, DataDog, New Relic       |
+
+### Architecture Layers
+
+Classifies source files into architectural layers and reports drift by layer to make refactors more predictable:
+
+- Archetype detection (e.g. Next.js, NestJS, Express, serverless, monorepo, CLI)
+- Layer-level file counts and confidence scoring
+- Per-layer package drift scores and risk levels
+- Layer-specific tech stack and service dependency attribution
+
+### Code Quality Metrics
+
+Fast AST-based quality checks to identify upgrade friction hotspots:
+
+- Files/functions analyzed
+- Cyclomatic complexity averages
+- Function length and nesting depth signals
+- Circular dependencies and dead-code estimate
+- "God file" detection for oversized high-complexity modules
+
+### OWASP Category Mapping
+
+Maps Semgrep OSS findings into OWASP Top 10 categories for security triage inside existing drift reports:
+
+- Supports `fast` and `cache-input` modes
+- Categorizes findings with severity and CWE metadata
+- Emits per-category counts in JSON output
+- Designed for CI visibility without requiring a separate report format
 
 ---
 
@@ -500,10 +608,10 @@ Set `VIBGRATE_DSN` as a secret in your CI environment. Uploads are always option
 
 Vibgrate supports region-specific ingest endpoints:
 
-| Region | Endpoint |
-|--------|----------|
+| Region       | Endpoint                 |
+| ------------ | ------------------------ |
 | US (default) | `us.ingest.vibgrate.com` |
-| EU | `eu.ingest.vibgrate.com` |
+| EU           | `eu.ingest.vibgrate.com` |
 
 Use `--region eu` on `push` or `dsn create` to route data to the EU endpoint.
 
@@ -513,14 +621,14 @@ Use `--region eu` on `push` or `dsn create` to route data to the EU endpoint.
 
 Vibgrate is built with a privacy-first architecture. Here's what it **never** does:
 
-| Category | Hard guarantee |
-|----------|---------------|
-| Source code | Never read beyond config/manifest files |
-| Secrets | Never scanned for, never extracted |
+| Category           | Hard guarantee                                     |
+| ------------------ | -------------------------------------------------- |
+| Source code        | Never read beyond config/manifest files            |
+| Secrets            | Never scanned for, never extracted                 |
 | Environment values | Never read — only `.env` file existence is flagged |
-| Git identity data | Never accessed — `git log` is never invoked |
-| File contents | Only structured config fields are extracted |
-| Network endpoints | Never parsed from config files |
+| Git identity data  | Never accessed — `git log` is never invoked        |
+| File contents      | Only structured config fields are extracted        |
+| Network endpoints  | Never parsed from config files                     |
 
 What it **does** collect:
 
@@ -534,11 +642,11 @@ What it **does** collect:
 
 ## Exit Codes
 
-| Code | Meaning |
-|------|---------|
-| `0` | Success |
-| `1` | Runtime error |
-| `2` | `--fail-on` threshold exceeded |
+| Code | Meaning                        |
+| ---- | ------------------------------ |
+| `0`  | Success                        |
+| `1`  | Runtime error                  |
+| `2`  | `--fail-on` threshold exceeded |
 
 ---
 
@@ -547,7 +655,12 @@ What it **does** collect:
 The package exports its core types for programmatic use:
 
 ```typescript
-import type { VibgrateConfig, ScanArtifact, DriftScore, Finding } from '@vibgrate/cli';
+import type {
+  VibgrateConfig,
+  ScanArtifact,
+  DriftScore,
+  Finding,
+} from "@vibgrate/cli";
 ```
 
 ---