vg scan

Overview

vg scan is the core command of the Vibgrate CLI. It recursively analyzes your repository, calculates the DriftScore, and outputs actionable findings.

Quick Start: Run npx @vibgrate/cli scan in any project directory for an instant drift assessment.

Usage

vg scan [path] [options]

Options Reference

Output Options

Flag	Default	Description
`--format <type>`	`text`	Output format: `text`, `json`, `sarif`, `md`
`--out <file>`	stdout	Write output to a file

Quality Gate Options

Flag	Default	Description
`--fail-on <level>`	—	Exit code 2 if findings at level: `error`, `warn`, `info`
`--baseline <file>`	—	Compare against a previous baseline
`--drift-budget <score>`	—	Fail if drift score exceeds this value (0-100)
`--drift-worsening <percent>`	—	Fail if drift increased by this % vs baseline

Scope Options

Flag	Default	Description
`--exclude <glob>`, `-e <glob>`	—	Exclude paths from the scan as glob patterns. Repeatable, and accepts comma/semicolon-separated values. Merged (and de-duplicated) with the config file's `exclude` list.

Performance Options

Flag	Default	Description
`--concurrency <n>`	`8`	Maximum concurrent registry API calls
`--changed-only`	—	Only scan files changed since baseline
`--project-scan-timeout <seconds>`	`180`	Per-project scan timeout in seconds
`--ui-purpose`	—	Enable optional UI purpose evidence extraction (slower)
`--offline`	—	Disable network calls (requires package manifest)
`--package-manifest <file>`	—	Offline package version data

Vibgrate Cloud Upload Options

Flag	Default	Description
`--push`	—	Upload scan artifact to dashboard
`--dsn <dsn>`	`VIBGRATE_DSN` env	DSN token for authentication
`--region <region>`	—	Data residency override: `us`, `eu`
`--repository-name <name>`	dir / package name	Override the repository name recorded for this scan
`--strict`	—	Fail pipeline if upload fails

Privacy & Security Options

Flag	Default	Description
`--max-privacy`	—	Hardened privacy mode, minimal data collection
`--no-local-artifacts`	—	Don't write `.vibgrate/*.json` files

Output Formats

Text (Default)

vg scan

Example Output:

╭─────────────────────────────────────────────╮
│  VIBGRATE DRIFT REPORT                      │
├─────────────────────────────────────────────┤
│  DriftScore: 67/100                         │
│  Projects: 4 (Node.js: 3, .NET: 1)          │
│  Findings: 12 (3 errors, 7 warnings, 2 info)│
╰─────────────────────────────────────────────╯

🔴 ERROR: Node.js 16.x is EOL
   → Upgrade to Node.js 20.x or 22.x

🟡 WARNING: 45% of dependencies are 2+ majors behind
   → Review dependency-risk findings

🔵 INFO: TypeScript 4.9 → 5.x available
   → Consider upgrade for improved type inference

JSON

vg scan --format json --out scan.json

Example Output:

{
  "meta": {
    "version": "1.0.0",
    "timestamp": "2025-01-15T10:30:00Z",
    "duration": 4520
  },
  "driftScore": 67,
  "projects": [
    {
      "path": "./",
      "ecosystem": "nodejs",
      "drift": 45,
      "runtimeVersion": "16.20.0"
    }
  ],
  "findings": [
    {
      "severity": "error",
      "scanner": "platform-matrix",
      "message": "Node.js 16.x is EOL",
      "recommendation": "Upgrade to Node.js 20.x or 22.x"
    }
  ]
}

SARIF (GitHub/Azure DevOps)

vg scan --format sarif --out vibgrate.sarif

Tip: SARIF integrates with GitHub Code Scanning and Azure DevOps for native PR annotations.

Markdown

vg scan --format md --out report.md

Use Case: Generate markdown for PR comments, wikis, or release documentation.

Quality Gates

Fail on Severity Level

# Fail on any error-level finding
vg scan --fail-on error

# Fail on warnings or worse
vg scan --fail-on warn

# Fail on any finding
vg scan --fail-on info

Level	Exit Code	Use Case
`error`	2	Block on critical issues only
`warn`	2	Stricter governance
`info`	2	Zero-tolerance policy

Drift Fitness Functions

Fitness functions enforce drift budgets over time:

vg scan \
  --baseline .vibgrate/baseline.json \
  --drift-budget 40 \
  --drift-worsening 5 \
  --fail-on error

Gate	Trigger	Purpose
`--drift-budget 40`	Score > 40	Absolute drift ceiling
`--drift-worsening 5`	Increase > 5% vs baseline	Prevent regression
`--fail-on error`	Any error finding	Catch critical issues

Warning: Fitness functions require a baseline. Create one with vg baseline first.

Special Modes

Offline Mode

For air-gapped environments or CI runners without internet:

vg scan --offline --package-manifest ./packages.zip

Privacy Mode

For maximum data minimization:

vg scan --max-privacy --no-local-artifacts

CI Pipeline Mode

Recommended CI configuration with all quality gates:

vg scan \
  --baseline .vibgrate/baseline.json \
  --drift-budget 40 \
  --drift-worsening 5 \
  --fail-on error \
  --format sarif \
  --out vibgrate.sarif \
  --push \
  --strict

Excluding Paths

Use --exclude (alias -e) to skip paths from a scan as glob patterns. This is the command-line equivalent of the exclude array in vibgrate.config.*, useful for ad-hoc, one-off scans without editing config.

The flag follows common CLI conventions for "multiple values":

Style	Example
Repeatable	`--exclude "legacy/" --exclude "vendor/"`
Comma/semicolon-separated	`--exclude "legacy/,vendor/;dist/**"`
Mixed	`-e "legacy/" -e "vendor/,dist/**"`

# Exclude a couple of directories for this run only
vg scan --exclude "legacy/**" --exclude "vendor/**"

# Same thing, comma/semicolon-separated in a single flag
vg scan -e "legacy/**,vendor/**;dist/**"

Additive, not a replacement: CLI excludes are merged (and de-duplicated) with the config file's exclude list rather than replacing it, so your committed defaults always apply. Patterns use glob syntax matched against the workspace root.

Exit Codes

Code	Meaning	Action
`0`	Success, no threshold violations	Pipeline continues
`1`	CLI error (invalid args, scan failure)	Debug command
`2`	Drift threshold exceeded	Block merge, address findings

Related Commands

vg init — Initialize project
vg baseline — Create baseline snapshot
vg report — Generate reports from artifacts
CI Integration — Full pipeline setup