Concepts
Core concepts and fundamental ideas
FAQs
What is the Drift Score and how is it calculated?
The Drift Score is a metric from 0–100 that represents how far behind your codebase is relative to current stable ecosystem baselines. Lower scores mean a healthier upgrade posture — 0 means no drift (fully current) and 100 means maximum drift. Higher is worse. It's calculated from four weighted components: Runtime (Node.js/.NET version lag), Frameworks (major version distance for React, Next.js, etc.), Dependencies (age distribution across all deps), and EOL Risk (proximity to end-of-life dates).
What do the Drift Score risk levels mean?
Scores of 0–30 indicate Low risk (you're in good shape — little to no drift). Scores of 31–60 indicate Moderate risk (some attention needed). Scores of 61–100 indicate High risk (significant upgrade debt). The score is deterministic — the same inputs always produce the same score, making it suitable for CI quality gates.
What languages and ecosystems does Vibgrate support?
Vibgrate supports Node.js/TypeScript (package.json, npm/pnpm/yarn/bun lockfiles), .NET (*.csproj, *.sln, NuGet), Python (requirements.txt, pyproject.toml, Pipfile, setup.py), and Java (pom.xml for Maven, build.gradle for Gradle). Each ecosystem gets drift analysis against its respective package registry (npm, NuGet, PyPI, Maven Central).
Does Vibgrate support monorepos?
Yes. Vibgrate automatically discovers every project in your workspace (multiple package.json files, .csproj files, go.mod, etc.). For npm/pnpm/yarn workspaces, each package is scanned individually and scores aggregate up. Each project is also automatically sized for billing into a micro, small or standard tier, so a serverless monorepo of hundreds of tiny functions costs only a fraction of its raw count — we bill billable projects, not detected projects. Use exclude patterns in vibgrate.config.ts to skip directories like examples/** or legacy/**, or pass --exclude (alias -e) on the command line for a single run; CLI excludes are merged with the config list.
What are extended scanners?
Beyond core drift scoring, Vibgrate runs extended scanners: Platform Matrix (detects OS-specific dependencies), Dependency Risk (deprecated packages, native modules), TypeScript Modernity (strict mode analysis), Security Posture (lockfile presence, .gitignore coverage), Build & Deploy (CI systems, Docker, IaC detection), and more. All are read-only and can be individually toggled in config.
What data does Vibgrate collect?
Vibgrate is privacy-first. It NEVER reads source code (only manifest/config files), never scans for secrets, never reads environment values, never accesses git identity data. It DOES collect package names and versions, config structure flags (e.g., strict: true), file names/sizes (not contents), and public registry metadata. Use --max-privacy for minimal collection.
How does Vibgrate analyze TypeScript configuration?
Vibgrate reads tsconfig.json to assess TypeScript modernity: TypeScript version, strict mode flags (strict, noImplicitAny, strictNullChecks), module system (module, moduleResolution, target), and ESM vs CJS classification. Strict TypeScript configurations score higher in the modernity assessment. This is part of the extended scanners.
What are EOL (End of Life) findings?
EOL findings alert you when your runtime (Node.js, .NET, Python) is approaching or past its end-of-life date. Running unsupported runtimes poses security risks. Default threshold: error if EOL is within 180 days. Adjust in vibgrate.config.ts under thresholds.failOnError.eolDays. Check nodejs.org/en/about/releases for Node.js EOL dates.
How do I interpret scan findings?
Findings have three severity levels: error (critical issues like EOL runtime, 3+ major framework lag), warning (moderate issues like 2 major framework lag, 30%+ deps behind), and info (informational items). Each finding includes a rule ID, message, description, and location. Address error-level findings first, then warnings.
Can I use Vibgrate programmatically in my own code?
Yes. Import types from @vibgrate/cli@latest for type-safe access to scan artifacts: import type { VibgrateConfig, ScanArtifact, DriftScore, Finding } from '@vibgrate/cli@latest'. Read .vibgrate/scan_result.json as JSON and type it as ScanArtifact. Schema is versioned (schemaVersion: '1.0') for stability.
What is the baseline.json file for?
The .vibgrate/baseline.json file is a snapshot of your drift score at a point in time. It serves as a reference point for CI gates — you can fail builds if drift worsens beyond a threshold compared to baseline. Create it with vibgrate baseline . after your main branch is stable. Commit it to version control. Refresh after planned upgrade sprints.
What is the scan_result.json file?
The .vibgrate/scan_result.json file is the full output artifact from your most recent scan. It contains all raw data, scores, findings, and VCS metadata in a stable JSON schema (schemaVersion: '1.0'). Add it to .gitignore since it changes on every scan. Use it for programmatic consumption or to generate reports with vibgrate report.
What are native module warnings?
Native module warnings indicate your project depends on packages that compile native code (e.g., sharp, bcrypt, node-gyp). These can cause issues when building on different architectures (ARM vs x64) or operating systems. The Platform Matrix scanner detects these to help predict where builds might break during CI runner or container migrations.
What do deprecated package warnings mean?
Deprecated package warnings appear when the npm registry marks a package as deprecated. This usually means the package is unmaintained, has security issues, or has been replaced by a better alternative. Common examples: request, node-sass, tslint, moment. Replace these packages to improve your drift score and reduce security risk.
Do micro and small projects count for less toward my Drift Score?
No — billing weight is not risk weight. Every project, whatever its size, is fully included in your Drift Score, the portfolio view, and every risk and compliance report. Only the billing fraction is reduced. A micro project that is dangerously out of date still shows full risk on the CTO dashboard; it just costs a tenth of a standard project to govern.