Programmatic API: Using Vibgrate Types in Code

Overview

The @vibgrate/cli package exports its core types for programmatic use. This allows you to build custom tools, dashboards, and integrations that consume scan artifacts with full type safety.

Available Types

import type {
  VibgrateConfig,
  ScanArtifact,
  DriftScore,
  Finding,
} from '@vibgrate/cli';

VibgrateConfig

The configuration type used by vibgrate.config.ts. Includes exclude patterns, thresholds, and scanner toggles.

ScanArtifact

The full scan result. Contains:

• Project metadata
• Drift scores (overall and per-component)
• All findings with severity and descriptions
• Extended scanner results
• VCS metadata

DriftScore

The drift score breakdown:

• Overall score (0–100)
• Component scores (runtime, frameworks, dependencies, EOL risk)
• Risk level classification

Finding

An individual finding with:

• Severity (error, warning, info)
• Rule ID
• Message and description
• Location (project path, file)

Reading Scan Artifacts

import { readFileSync } from 'fs';
import type { ScanArtifact } from '@vibgrate/cli';

const artifact: ScanArtifact = JSON.parse(
  readFileSync('.vibgrate/scan_result.json', 'utf-8')
);

console.log(`Overall score: ${artifact.score.overall}`);
console.log(`Risk level: ${artifact.score.riskLevel}`);
console.log(`Findings: ${artifact.findings.length}`);

Custom Dashboards

Read the JSON artifact to build custom visualisation:

import type { ScanArtifact, Finding } from '@vibgrate/cli';

function getErrorFindings(artifact: ScanArtifact): Finding[] {
  return artifact.findings.filter(f => f.severity === 'error');
}

function getScoreTrend(artifacts: ScanArtifact[]): number[] {
  return artifacts.map(a => a.score.overall);
}

Schema Versioning

The scan artifact uses a stable schema (schemaVersion: "1.0"). The same inputs always produce the same structure, making it safe for automated consumption.