@vibe-validate/config

Configuration system for vibe-validate with strict Zod schema validation and JSON Schema support.

Features

• ✅ Strict Schema Validation: Runtime validation with Zod (rejects unknown properties)
• ✅ JSON Schema Support: IDE autocomplete and validation for YAML configs
• ✅ YAML Configuration: Primary format with schema validation
• ✅ Type Safety: Full TypeScript definitions for programmatic use

Installation

npm install @vibe-validate/config

Usage

YAML Configuration (Recommended)

Create a vibe-validate.config.yaml file using a template:

npx vibe-validate init --template typescript-nodejs

Available templates:

• minimal - Bare-bones starting point
• typescript-library - TypeScript libraries/npm packages
• typescript-nodejs - Node.js applications
• typescript-react - React/Next.js applications

All templates: https://github.com/jdutton/vibe-validate/tree/main/packages/cli/config-templates

Example YAML Configuration

$schema: https://unpkg.com/@vibe-validate/config/config.schema.json

# Git settings
git:
  mainBranch: main
  autoSync: false
  warnIfBehind: true

# Validation configuration
validation:
  phases:
    - name: Pre-Qualification
      parallel: true
      steps:
        - name: TypeScript
          command: tsc --noEmit
          description: Type-check all code
        - name: ESLint
          command: eslint .
          description: Lint for code quality

    - name: Testing
      parallel: false
      steps:
        - name: Unit Tests
          command: npm test
          description: Run test suite

  failFast: true  # Stop all validation on first phase failure

YAML Schema Support

The $schema property enables IDE autocomplete and validation:

# Version-pinned (recommended for production)
$schema: https://unpkg.com/@vibe-validate/config@0.15.0/config.schema.json

# Latest version (auto-updates to newest)
$schema: https://unpkg.com/@vibe-validate/config/config.schema.json

Versioning Strategy:

• Version-pinned URLs - Match your installed package version, stable API
• Latest URLs - Auto-update to newest schema, good for docs/prototyping
• vibe-validate init - Automatically generates version-pinned URLs

This gives you:

• ✅ Autocomplete for all configuration properties
• ✅ Inline validation errors
• ✅ Hover documentation for each field
• ✅ Type checking for YAML configs

See Schema Documentation for complete details on versioning and all published schemas.

API (Programmatic Usage)

loadConfig(cwd?)

Load configuration from current directory:

import { loadConfig } from '@vibe-validate/config';

const config = await loadConfig(); // Searches for vibe-validate.config.yaml

loadConfigFromFile(path)

Load and validate configuration from a specific file:

import { loadConfigFromFile } from '@vibe-validate/config';

const config = await loadConfigFromFile('./vibe-validate.config.yaml');

findAndLoadConfig(cwd?)

Find and load configuration from working directory:

import { findAndLoadConfig } from '@vibe-validate/config';

const config = await findAndLoadConfig(); // Searches for config in cwd

validateConfig(rawConfig)

Validate a raw configuration object:

import { validateConfig, safeValidateConfig } from '@vibe-validate/config';

// Throws ZodError on invalid config
const config = validateConfig(rawConfig);

// Returns { success, data?, errors? }
const result = safeValidateConfig(rawConfig);
if (!result.success) {
  console.error(result.errors);
}

Configuration File Discovery

The loader searches for the config file:

• vibe-validate.config.yaml (only supported format)

Configuration Schema

See the complete configuration reference: https://github.com/jdutton/vibe-validate/blob/main/docs/configuration-reference.md

Key Sections

• git - Git repository settings (mainBranch, autoSync, etc.)
• validation - Validation phases and steps configuration
• validation.phases - Array of validation phases to execute
• validation.phases[].steps - Array of commands to run in each phase
• validation.failFast - Stop all validation on first phase failure (default: true)

Strict Validation

All Zod schemas use strict validation - unknown properties are rejected:

validation:
  phases: []
  unknownProperty: true  # ❌ ERROR: Unrecognized key 'unknownProperty'

This catches typos and prevents configuration drift.

License

MIT