Calibrate.WTF Documentation

Calibrate.WTF is a zero-config TypeScript & Next.js code quality tool that provides automated linting, accessibility auditing, performance monitoring, and pre-commit quality gates.

pnpm add -D @decoperations/calibrate

npx calibrate init --yes

npx calibrate check

pnpm add -D @decoperations/calibrate

Calibrate requires Node.js 18+ and works with TypeScript 4+ projects. It has optional peer dependencies on Next.js and React for framework-specific analysis.

After running calibrate init, a .calibrate/config.json file is created in your project root.

{
  "framework": "nextjs",
  "language": "typescript",
  "testing": {
    "framework": "vitest",
    "coverage": { "threshold": 80 }
  },
  "linting": { "rules": "recommended" },
  "formatting": { "semi": false, "singleQuote": true },
  "cicd": { "provider": "github-actions" },
  "security": { "scanning": true },
  "performance": { "budgets": true }
}

All settings are optional. Calibrate uses sensible defaults and auto-detects your project configuration.

Calibrate analyzes your code across 18 quality dimensions grouped into four categories:

Calibrate automatically checks your application against WCAG 2.1 AA standards. Issues are categorized by severity and include actionable fix suggestions.

# Run accessibility-only checks
npx calibrate check --category accessibility

# Output includes:
# - Contrast ratio failures
# - Missing alt text
# - ARIA attribute issues
# - Keyboard trap detection
# - Focus management problems

Performance monitoring tracks Core Web Vitals and provides optimization recommendations with estimated impact.

The UI analysis engine inspects your component hierarchy for design consistency, spacing issues, typography problems, and responsive layout breakage.

# Run UI analysis
npx calibrate check --category design

# Checks include:
# - Component consistency across pages
# - Spacing and alignment issues
# - Typography hierarchy validation
# - Responsive breakpoint coverage
# - Color usage consistency

Calibrate integrates with GitHub Actions for automated quality gates on pull requests.

# .github/workflows/calibrate.yml
name: Quality Check
on: [pull_request]
jobs:
  calibrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - run: pnpm install
      - run: npx calibrate check --ci
        env:
          CALIBRATE_TOKEN: ${{ secrets.CALIBRATE_TOKEN }}

The --ci flag outputs results in a format suitable for CI environments and will exit with a non-zero code if quality thresholds are not met.

Calibrate exposes a programmatic API for integration with custom tooling.

import { Calibrate } from '@decoperations/calibrate';

const calibrate = new Calibrate({
  config: '.calibrate/config.json',
});

// Run all checks
const report = await calibrate.check();

// Run specific category
const a11y = await calibrate.check({
  categories: ['accessibility'],
});

// Get score
console.log(report.overallScore); // 0-100
console.log(report.issues);       // Issue[]