vg scan — Scan for Upgrade Drift

Usage

vg scan [path] [options]

What It Does

vg scan is the core command. It recursively scans your repository for projects, analyzes dependency drift, and produces an DriftScore with detailed findings.

All Flags

Output Formats

Text (default)

A colored, human-readable report showing the overall drift score, score component breakdown, per-project details, and findings with severity icons.

vg scan

JSON

The full scan artifact in JSON format with all raw data, scores, findings, and VCS metadata.

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

SARIF

Static Analysis Results Interchange Format — compatible with GitHub Code Scanning and Azure DevOps.

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

Markdown

A clean Markdown report suitable for PRs, wikis, or documentation.

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

Quality Gates

Use --fail-on to make the CLI exit with code 2 when findings at a certain severity exist:

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

# Fail on warnings too
vg scan --fail-on warn

Drift Fitness Functions

Combine baselines with drift budgets for precise CI enforcement:

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

This fails the scan if:

• The drift score exceeds 40 (budget gate)
• Drift has worsened by more than 5% compared to the baseline (regression gate)
• Any error-level findings are present

Scan with Vibgrate Cloud Push

vg scan --push --dsn $VIBGRATE_DSN --strict

Excluding Paths

Use --exclude (alias -e) to skip paths from a scan as glob patterns — the command-line equivalent of the exclude array in vibgrate.config.*. It's ideal for ad-hoc scans without editing config.

The flag follows common CLI conventions for multiple values. It's repeatable, accepts comma/semicolon-separated values in a single flag, and you can mix both styles:

# Repeatable
vg scan --exclude "legacy/**" --exclude "vendor/**"

# Comma/semicolon-separated within a single flag
vg scan -e "legacy/**,vendor/**;dist/**"

CLI excludes are additive: they're merged (and de-duplicated) with the config file's exclude list rather than replacing it, so committed defaults always apply.

Offline Mode

For air-gapped environments, use --offline with a pre-downloaded manifest:

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

Privacy Mode

vg scan --max-privacy

This runs minimal scanners and writes no local artifacts.

Local Artifacts

By default, the scan writes .vibgrate/scan_result.json. Suppress this with --no-local-artifacts or --max-privacy.