@vibgrate/cli 0.1.1 → 0.1.3

package/DOCS.md

@@ -0,0 +1,554 @@
+# Vibgrate CLI — Full Documentation
+
+> Continuous Upgrade Drift Intelligence for Node & .NET
+
+For a quick overview, see the [README](./README.md). This document covers everything in detail.
+
+---
+
+## Table of Contents
+
+- [How It Works](#how-it-works)
+- [Commands Reference](#commands-reference)
+  - [vibgrate init](#vibgrate-init)
+  - [vibgrate scan](#vibgrate-scan)
+  - [vibgrate baseline](#vibgrate-baseline)
+  - [vibgrate report](#vibgrate-report)
+  - [vibgrate push](#vibgrate-push)
+  - [vibgrate dsn create](#vibgrate-dsn-create)
+  - [vibgrate update](#vibgrate-update)
+- [Upgrade Drift Score](#upgrade-drift-score)
+  - [How the Score Is Calculated](#how-the-score-is-calculated)
+  - [Risk Levels](#risk-levels)
+  - [Score Components](#score-components)
+- [Output Formats](#output-formats)
+  - [Text](#text)
+  - [JSON Artifact](#json-artifact)
+  - [SARIF](#sarif)
+  - [Markdown](#markdown)
+- [Configuration](#configuration)
+  - [vibgrate.config.ts](#vibgrateconfigts)
+  - [Thresholds](#thresholds)
+  - [Scanner Toggles](#scanner-toggles)
+- [Extended Scanners](#extended-scanners)
+  - [Platform Matrix](#platform-matrix)
+  - [Dependency Risk](#dependency-risk)
+  - [Dependency Graph & Duplication](#dependency-graph--duplication)
+  - [Tooling Inventory](#tooling-inventory)
+  - [Build & Deploy Surface Area](#build--deploy-surface-area)
+  - [TypeScript Modernity](#typescript-modernity)
+  - [Breaking Change Exposure](#breaking-change-exposure)
+  - [File Hotspots](#file-hotspots)
+  - [Security Posture](#security-posture)
+  - [Service Dependencies](#service-dependencies)
+- [CI Integration](#ci-integration)
+  - [GitHub Actions](#github-actions)
+  - [Azure DevOps](#azure-devops)
+  - [GitLab CI](#gitlab-ci)
+  - [Generic Pipelines](#generic-pipelines)
+- [Dashboard Upload](#dashboard-upload)
+  - [DSN Tokens](#dsn-tokens)
+  - [Data Residency](#data-residency)
+- [Privacy & Security](#privacy--security)
+- [Exit Codes](#exit-codes)
+- [Programmatic API](#programmatic-api)
+
+---
+
+## How It Works
+
+Vibgrate recursively scans your repository for `package.json` (Node/TypeScript) and `.sln`/`.csproj` (.NET) files. 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)
+3. **Computes** how far behind each component is — major version lag, EOL proximity, dependency age distribution
+4. **Generates** a deterministic Upgrade Drift Score (0–100)
+5. **Produces** findings, a full JSON artifact, and optional SARIF output
+
+No source code is read. No secrets are scanned. The CLI works entirely offline — dashboard upload is optional.
+
+---
+
+## Commands Reference
+
+### vibgrate init
+
+Initialise Vibgrate in a project.
+
+```bash
+vibgrate init [path] [--baseline] [--yes]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--baseline` | Create an initial drift baseline after init |
+| `--yes` | Skip confirmation prompts |
+
+Creates:
+- `.vibgrate/` directory
+- `vibgrate.config.ts` with sensible defaults
+
+---
+
+### vibgrate scan
+
+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>]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--format` | `text` | Output format: `text`, `json`, or `sarif` |
+| `--out <file>` | — | Write output to a file |
+| `--fail-on <level>` | — | Exit with code 2 if findings at this level exist |
+| `--baseline <file>` | — | Compare against a previous baseline |
+| `--changed-only` | — | Only scan changed files |
+| `--concurrency <n>` | `8` | Max concurrent npm registry calls |
+
+The scan always writes the full artifact to `.vibgrate/scan_result.json`.
+
+---
+
+### vibgrate baseline
+
+Create a drift baseline snapshot for delta comparison.
+
+```bash
+vibgrate baseline [path]
+```
+
+Runs a full scan and saves the result to `.vibgrate/baseline.json`. Use this as the starting point for tracking drift over time.
+
+---
+
+### vibgrate report
+
+Generate a human-readable report from a scan artifact.
+
+```bash
+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` |
+
+---
+
+### vibgrate push
+
+Upload scan results to the Vibgrate dashboard API.
+
+```bash
+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 |
+
+Upload is always optional. Best-effort by default — use `--strict` in CI if you want the pipeline to fail on upload errors.
+
+---
+
+### vibgrate dsn create
+
+Generate an HMAC-signed DSN token for API authentication.
+
+```bash
+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`!) |
+
+---
+
+### vibgrate update
+
+Check for and install updates.
+
+```bash
+vibgrate update [--check] [--pm <manager>]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--check` | Only check for updates, don't install |
+| `--pm` | Force a package manager (`npm`, `pnpm`, `yarn`, `bun`) |
+
+---
+
+## Upgrade Drift Score
+
+### How the Score Is Calculated
+
+The Upgrade Drift Score is a deterministic, versioned metric (0–100) that represents how far behind your codebase is relative to the current stable ecosystem baseline.
+
+**Higher score = healthier upgrade posture.**
+
+### 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 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.) |
+| **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 |
+
+---
+
+## Output Formats
+
+### 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
+- Findings with severity icons
+
+### JSON Artifact
+
+The full scan artifact in JSON format. Contains all raw data, scores, findings, and VCS metadata. Stable schema (`schemaVersion: "1.0"`). This is the same artifact saved to `.vibgrate/scan_result.json`.
+
+### SARIF
+
+[Static Analysis Results Interchange Format](https://sarifweb.azurewebsites.net/) — compatible with GitHub Code Scanning and Azure DevOps. Contains findings only (not all metrics). Ideal for integrating drift findings directly into your PR review workflow.
+
+### Markdown
+
+A clean Markdown report suitable for PRs, wikis, or documentation.
+
+---
+
+## Configuration
+
+### vibgrate.config.ts
+
+Run `vibgrate init` to generate the config file, or create one manually:
+
+```typescript
+import type { VibgrateConfig } from '@vibgrate/cli';
+
+const config: VibgrateConfig = {
+  exclude: ['legacy/**'],
+  thresholds: {
+    failOnError: {
+      eolDays: 180,
+      frameworkMajorLag: 3,
+      dependencyTwoPlusPercent: 50,
+    },
+    warn: {
+      frameworkMajorLag: 2,
+      dependencyTwoPlusPercent: 30,
+    },
+  },
+  scanners: {
+    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 },
+    serviceDependencies:    { enabled: true },
+  },
+};
+
+export default config;
+```
+
+Also supports `vibgrate.config.js` and `vibgrate.config.json`.
+
+### Thresholds
+
+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 |
+
+### Scanner Toggles
+
+Each extended scanner can be individually disabled. Set `scanners: false` to disable all extended scanners (the core drift scan always runs).
+
+---
+
+## Extended Scanners
+
+Beyond the core drift score, Vibgrate runs a suite of extended scanners that collect high-value migration intelligence. All scanners:
+
+- Are **read-only** — they never write files or execute project code
+- Run **in parallel** — failures in one scanner never affect the others
+- Can be **individually toggled** in the config
+- Collect **zero sensitive data** — no source code, no secrets, no PII
+
+### Platform Matrix
+
+Collects platform and architecture signals that predict where builds will break when moving CI runners, containers, or CPU architectures.
+
+- `engines.node` and `engines.npm`/`engines.pnpm` ranges
+- `.nvmrc` / `.node-version` files
+- .NET `TargetFramework` and SDK versions
+- Native module risk packages (`sharp`, `bcrypt`, `node-gyp`, etc.)
+- OS-assumption scripts in `package.json`
+- Dockerfile base images (FROM lines only)
+
+### Dependency Risk
+
+Extends dependency analysis with risk classification signals:
+
+- Deprecated packages (npm `deprecated` field)
+- Native module detection
+- Platform-specific package flags
+
+### Dependency Graph & Duplication
+
+Parses lockfiles (pnpm, npm, yarn, .NET) to build a workspace-wide dependency graph:
+
+- Total unique vs. installed dependency counts
+- Duplicated packages (multiple versions of the same package)
+- Phantom dependencies (used but not declared)
+
+### 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 |
+
+### Build & Deploy Surface Area
+
+Detects CI/CD, containerisation, and infrastructure-as-code:
+
+- CI systems (GitHub Actions, GitLab CI, Azure DevOps, Jenkins, CircleCI)
+- Docker and Docker Compose
+- IaC (Terraform, Bicep, CloudFormation, Pulumi)
+- Release tooling (Changesets, semantic-release, GitVersion)
+- Package managers and monorepo tools
+
+### TypeScript Modernity
+
+Reads `tsconfig.json` compiler options to assess strictness and modernity:
+
+- TypeScript version
+- `strict`, `noImplicitAny`, `strictNullChecks` flags
+- Module system (`module`, `moduleResolution`, `target`)
+- ESM vs CJS classification
+- `exports` field presence
+
+### Breaking Change Exposure
+
+Flags packages and patterns known to cause upgrade pain:
+
+- Deprecated packages (e.g. `request`, `node-sass`, `tslint`, `moment`)
+- Legacy Node API polyfills no longer needed on Node 18+ (e.g. `node-fetch`, `abort-controller`)
+- Peer dependency conflicts
+- Exposure score (0–100)
+
+### File Hotspots
+
+Lightweight complexity analysis using filesystem metadata only (never reads file contents):
+
+- File counts by extension
+- Largest files by size (path + bytes)
+- Directory depth distribution
+- Most-used packages across the workspace
+
+### Security Posture
+
+Structural security hygiene indicators (not a secret scanner):
+
+- Lockfile presence and consistency
+- `.gitignore` coverage for `.env` files and `node_modules`
+- `.env` files tracked outside `.gitignore`
+- Audit severity counts (via `npm audit --json`)
+
+### Service Dependencies
+
+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 |
+
+---
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+steps:
+  - name: Vibgrate Scan
+    run: npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error
+
+  - name: Upload SARIF
+    uses: github/codeql-action/upload-sarif@v3
+    with:
+      sarif_file: vibgrate.sarif
+
+  # Optional: push metrics to dashboard
+  - name: Push Vibgrate Metrics
+    env:
+      VIBGRATE_DSN: ${{ secrets.VIBGRATE_DSN }}
+    run: npx @vibgrate/cli push --file .vibgrate/scan_result.json
+```
+
+### Azure DevOps
+
+```yaml
+steps:
+  - script: npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error
+    displayName: Vibgrate Scan
+
+  - task: PublishBuildArtifacts@1
+    inputs:
+      PathtoPublish: vibgrate.sarif
+      ArtifactName: VibgrateSARIF
+```
+
+### GitLab CI
+
+```yaml
+vibgrate:
+  script:
+    - npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error
+  artifacts:
+    reports:
+      sast: vibgrate.sarif
+```
+
+### Generic Pipelines
+
+Vibgrate works in any CI environment. The CLI:
+
+- Requires no login or authentication
+- Returns meaningful exit codes (see below)
+- Produces standard SARIF output
+- Works entirely offline (push is opt-in)
+
+---
+
+## Dashboard Upload
+
+### DSN Tokens
+
+Vibgrate uses HMAC-signed DSN tokens for authenticated uploads. The DSN format:
+
+```
+vibgrate+https://<key_id>:<secret>@<ingest_host>/<workspace_id>
+```
+
+Set `VIBGRATE_DSN` as a secret in your CI environment. Uploads are always optional — the CLI provides full value locally without any server connection.
+
+### Data Residency
+
+Vibgrate supports region-specific ingest endpoints:
+
+| Region | Endpoint |
+|--------|----------|
+| US (default) | `us.ingest.vibgrate.com` |
+| EU | `eu.ingest.vibgrate.com` |
+
+Use `--region eu` on `push` or `dsn create` to route data to the EU endpoint.
+
+---
+
+## Privacy & Security
+
+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 |
+| 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 |
+
+What it **does** collect:
+
+- Package names and version numbers (from `package.json`, `.csproj`, lockfiles)
+- Config structure flags (e.g. `strict: true` from `tsconfig.json`)
+- File names and sizes (paths and metadata, never contents)
+- Public npm/NuGet registry metadata (latest versions, deprecation flags)
+- CI/Docker/IaC file presence and structural counts
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Runtime error |
+| `2` | `--fail-on` threshold exceeded |
+
+---
+
+## Programmatic API
+
+The package exports its core types for programmatic use:
+
+```typescript
+import type { VibgrateConfig, ScanArtifact, DriftScore, Finding } from '@vibgrate/cli';
+```
+
+---
+
+## Requirements
+
+- **Node.js** >= 20.0.0
+- Works on macOS, Linux, and Windows
+
+---
+
+## Links
+
+- [Website](https://vibgrate.com)
+- [npm](https://www.npmjs.com/package/@vibgrate/cli)
+
+---
+
+Copyright © 2026 Vibgrate. All rights reserved. See [LICENSE](./LICENSE) for terms.

package/LICENSE

@@ -0,0 +1,45 @@
+Vibgrate Proprietary License
+
+Copyright (c) 2026 Vibgrate. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software in compiled/distributed form (the "Software"),
+to use the Software for internal business and personal purposes, subject to the
+following conditions:
+
+1. PERMITTED USE
+   You may install, run, and use the Software as provided via the npm registry
+   for the purpose of analysing upgrade drift in your own projects.
+
+2. NO MODIFICATION
+   You may not modify, adapt, translate, reverse-engineer, decompile,
+   disassemble, or create derivative works based on the Software.
+
+3. NO REDISTRIBUTION
+   You may not redistribute, sublicense, sell, lease, or otherwise transfer
+   the Software or any copy thereof to any third party, except as part of
+   your own project's development toolchain (e.g. listed as a dependency in
+   package.json).
+
+4. NO SOURCE CODE ACCESS
+   The source code of this Software is proprietary and confidential. Access
+   to source code, if provided separately, does not grant any additional
+   rights beyond those stated in this license.
+
+5. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+6. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+7. TERMINATION
+   This license is effective until terminated. It will terminate automatically
+   if you fail to comply with any of its terms. Upon termination, you must
+   destroy all copies of the Software in your possession.
+
+For licensing enquiries: ops@vibgrate.com