@sorik-ai/sorik-spec

@sorik-ai/sorik-spec

TypeScript configuration schema and validation for Sorik a11y automation.

Installation

npm install @sorik-ai/sorik-spec@alpha

Usage

import { SorikConfig, validateSorikConfig, createSorikConfig } from '@sorik-ai/sorik-spec';

// Define your config
const config: SorikConfig = {
  project: {
    monitoredBranch: 'main'  // Required: branch to monitor for changes
  },
  build: {
    build: 'npm run build',   // Required: production build command
    start: 'npm start',       // Required: dev server start command  
    port: 3000               // Required: dev server port
  }
};

// Validate config
if (validateSorikConfig(config)) {
  console.log('Config is valid!');
}

Configuration Schema

Required Fields

project.monitoredBranch (string)

Branch to monitor for accessibility scans. Examples: 'main', 'develop', 'staging'

build.build (string)

Command to build project for production. Examples: 'npm run build', 'yarn build', 'pnpm build'

build.start (string)

Command to start development server. Examples: 'npm start', 'yarn dev', 'pnpm dev'

build.port (number)

Port where development server runs. Examples: 3000, 8080, 5173

Optional Fields

Project Configuration

• project.name (string) - Project identifier for logs and PRs
• project.releaseBranch (string) - Target branch for fix PRs (defaults to monitoredBranch)
• project.remediationBranch (string) - Prefix for fix branch names (defaults to 'sorik/fix')

Build Configuration

• build.test (string) - Test command for validation
• build.healthCheck (string) - Endpoint to verify server readiness (e.g. '/health')
• build.timeout (number) - Max startup wait time in seconds (defaults to 60)

A11y Configuration

Configure accessibility scanning and automated fixes:

a11y: {
  scanning: {
    urls?: string[];           // Specific URLs to scan: ['/home', '/about']
    includeUrls?: string[];    // URL patterns to include: ['/products/*']  
    excludeUrls?: string[];    // URL patterns to exclude: ['/admin/*']
    rules?: {                  // Rule severity overrides
      'color-contrast': 'critical',
      'image-alt': 'serious'
    },
    compliance?: {
      wcagLevel?: 'A' | 'AA' | 'AAA'  // WCAG compliance level (defaults to 'AA')
    }
  },
  remediation?: {
    maxAttempts?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7,  // Fix attempts (0 = disabled)
    autoMerge?: boolean        // Auto-merge PRs if checks pass (defaults to false)
  }
}

Rule Severities

• 'critical' - Blocks accessibility, must be fixed
• 'serious' - Impacts usability significantly
• 'moderate' - Noticeable accessibility issue
• 'minor' - Minor improvement for better experience

Example Configurations

Minimal Setup

{
  project: { monitoredBranch: 'main' },
  build: { build: 'npm run build', start: 'npm start', port: 3000 }
}

With Accessibility Scanning

{
  project: { monitoredBranch: 'main', name: 'my-app' },
  build: { build: 'npm run build', start: 'npm start', port: 3000 },
  a11y: {
    scanning: {
      urls: ['/'],
      excludeUrls: ['/admin/*']
    }
  }
}

Production E-commerce Setup

{
  project: {
    monitoredBranch: 'main',
    releaseBranch: 'develop', 
    name: 'ecommerce-platform'
  },
  build: {
    build: 'pnpm run build',
    test: 'pnpm test',
    start: 'pnpm dev',
    port: 3000,
    healthCheck: '/api/health',
    timeout: 120
  },
  a11y: {
    scanning: {
      includeUrls: ['/', '/products/*', '/cart', '/checkout/*'],
      excludeUrls: ['/admin/*', '/api/*'],
      rules: {
        'color-contrast': 'critical',
        'image-alt': 'critical', 
        'button-name': 'serious'
      },
      compliance: { wcagLevel: 'AA' }
    },
    remediation: {
      maxAttempts: 3,
      autoMerge: false
    }
  }
}

Scan-Only (No Automated Fixes)

{
  project: { monitoredBranch: 'main' },
  build: { build: 'npm run build', start: 'npm start', port: 3000 },
  a11y: {
    scanning: {
      includeUrls: ['/'],
      rules: { 'color-contrast': 'critical' }
    }
    // No remediation = scan-only mode
  }
}

Common Patterns by Project Type

Next.js/React App:

• build: 'npm run build', start: 'npm run dev', port: 3000
• Health check: '/api/health' or '/'

Vite/Vue App:

• build: 'npm run build', start: 'npm run dev', port: 5173

E-commerce Platform:

• Include: ['/products/*', '/cart', '/checkout/*']
• Exclude: ['/admin/*', '/api/*']
• Critical rules: color-contrast, image-alt, label

Content/Marketing Site:

• Include: ['/'] or ['/blog/*', '/about']
• Focus on: heading-order, image-alt, page-has-heading-one

SaaS Dashboard:

• Include: ['/dashboard/*', '/settings/*']
• Exclude: ['/auth/*', '/api/*']
• Critical rules: keyboard, focus-order, label

License

MIT