How It Works

Overview

Vibgrate is a multi-ecosystem code scanner that detects upgrade drift across your entire codebase. It recursively analyzes project manifests to identify outdated dependencies, deprecated runtimes, and technical debt indicators.

What is Upgrade Drift? The gap between your current dependency versions and the latest stable releases. High drift correlates with security vulnerabilities, missing features, and increasing upgrade complexity over time.

Supported Ecosystems

Vibgrate analyzes upgrade drift in depth across four major ecosystems:

Ecosystem	Files Detected	What's Analyzed
🟢 Node.js / TypeScript	`package.json`, `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`	Dependencies, Node.js version, TypeScript config
🔵 .NET	`.sln`, `.csproj`, `global.json`	Target framework, NuGet packages, SDK version
🟡 Python	`requirements.txt`, `pyproject.toml`, `Pipfile`, `setup.py`	Python version, pip/poetry dependencies
🔴 Java	`pom.xml`, `build.gradle`, `build.gradle.kts`	JDK version, Maven/Gradle dependencies

Known-vulnerability detection (vg scan --vulns) and dependency attribution (vg why) read each project's lockfile, so they additionally cover npm/pnpm/yarn, pip/poetry/pipenv, cargo, composer, bundler, go, pub, hex, NuGet, and Maven/Gradle.

The Scan Process

For each project discovered, Vibgrate executes a five-stage analysis pipeline:

Stage 1: Discovery

📁 Repository Root
├── 🔍 Recursive manifest detection
├── 📊 Ecosystem classification
└── 🏗️ Project structure mapping

Stage 2: Detection

Runtime version identification (Node.js, .NET, Python, Java, Go, Rust, PHP, Ruby, and more)
Target framework analysis
Complete dependency inventory

Stage 3: Registry Query

Parallel queries to npm/NuGet/PyPI/Maven registries
Built-in caching to minimize API calls
Rate limiting and retry logic

Stage 4: Drift Computation

Metric	Description
Major Version Lag	How many major versions behind current?
EOL Proximity	Distance to end-of-life for runtimes
Dependency Age	Average age distribution across dependencies
Security Debt	Known vulnerabilities in dependency tree

Stage 5: Output Generation

DriftScore: Deterministic 0–100 rating
Findings: Actionable list of upgrade priorities
Artifacts: JSON, Markdown, SARIF formats

Privacy by Design

Important: Vibgrate is designed with a privacy-first architecture. Core drift analysis never executes source code.

What Vibgrate Reads

✅ Analyzed	❌ Not Accessed
Manifest files (`package.json`, `*.csproj`, etc.)	Source code files
Configuration files	Environment variables
Lock files	Git history
Project structure	Secrets or credentials

Data Transmission

Default: All analysis runs locally with no network transmission
Opt-in: Upload to Vibgrate Cloud via --upload or vg push
Control: DSN configuration for enterprise environments

Quick Start

# Install globally (optional)
npm install -g @vibgrate/cli@latest

# Run your first scan
npx @vibgrate/cli scan

# Initialize project with baseline
npx @vibgrate/cli@latest init --baseline

# View detailed report
npx @vibgrate/cli@latest report --format md

Tip: Start with a one-off scan to understand your current drift status before integrating into CI.

Example Output

{
  "meta": {
    "version": "1.0.0",
    "timestamp": "2025-01-15T10:30:00Z"
  },
  "driftScore": 67,
  "ecosystems": {
    "nodejs": { "projects": 3, "avgDrift": 45 },
    "dotnet": { "projects": 1, "avgDrift": 72 }
  },
  "findings": [
    {
      "severity": "high",
      "message": "Node.js 16.x is EOL since September 2023",
      "recommendation": "Upgrade to Node.js 20.x or 22.x"
    }
  ]
}

Next Steps

Getting Started Guide — Installation and first scan
DriftScore Explained — Understanding the scoring algorithm
CI Integration — Automate drift monitoring