Configuration File Reference

Config File Formats

A project has one config file. Vibgrate reads the first one it finds, in this order, and never merges two:

1. .vibgrate/config.yml (or .vibgrate/config.yaml)
2. vibgrate.config.ts (the file vg init writes)
3. vibgrate.config.js
4. vibgrate.config.json

YAML and JSON take exactly the same settings. vg doctor names any config file that is present but ignored.

Run vg init to generate the default config.

Drift Budget and Review Settings

driftBudget and review judge changes before they merge. Put them in .vibgrate/config.yml or vibgrate.config.json: the Vibgrate GitHub App and vg review --base read them from the base branch as data, so a pull request cannot loosen them, and they never run a .ts or .js config.

# .vibgrate/config.yml
driftBudget:
  mode: warn              # warn (default), enforce, or shadow
  maxScore: 40            # DriftScore ceiling, 0-100
  maxWorseningPercent: 5  # how much one change may worsen drift
  agents:
    maxWorseningPercent: 0  # stricter limit for bot and coding-agent pull requests

review:
  enforcement: advisory   # advisory or enforced
  failOn: fail            # none, fail, or needs_review
  targetPattern: layered  # the architecture you want

In enforce mode, vg scan exits with code 2 when a drift budget limit is breached. --drift-budget and --drift-worsening still work and take precedence over driftBudget when passed.

Full Config Example

import type { VibgrateConfig } from '@vibgrate/cli@latest';

const config: VibgrateConfig = {
  exclude: ['legacy/**', 'examples/**', 'vendor/**'],
  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 },
    securityScanners: { enabled: true },
    serviceDependencies: { enabled: true },
  },
};

export default config;

Exclude Patterns

The exclude array accepts glob patterns for directories and files to skip during scanning:

exclude: [
  'legacy/**',      // Skip a legacy directory
  'examples/**',    // Skip example code
  'vendor/**',      // Skip vendored code
  '**/test-fixtures/**',  // Skip test fixtures anywhere
]

The same patterns can be passed on the command line for one-off scans with vg scan --exclude <glob> (alias -e). CLI excludes are repeatable, accept comma/semicolon-separated values, and are additive — they're merged (and de-duplicated) with this exclude list rather than replacing it, so your committed defaults always apply.

Thresholds

Thresholds control when findings are raised and when the CLI should fail.

failOnError

warn

Scanner Toggles

Each extended scanner can be individually enabled or disabled. Set scanners: false to disable all extended scanners (the core drift scan always runs).

Disable a specific scanner

scanners: {
  securityScanners: { enabled: false },  // Disable this one
  // All others remain at their default (enabled)
}

Disable all extended scanners

scanners: false

This runs only the core drift analysis — faster but with less detail.