@bernierllc/validators-core

Core types, interfaces, and utilities for the BernierLLC validators ecosystem. This package provides the foundational building blocks for creating atomic, composable validation primitives.

Installation

npm install @bernierllc/validators-core

Usage

Creating a Validation Rule

import { defineRule, type SharedUtils } from '@bernierllc/validators-core';

const duplicateIdRule = defineRule({
  meta: {
    id: 'html/duplicate-ids',
    title: 'HTML elements must have unique IDs',
    description: 'Duplicate IDs can cause accessibility and JavaScript issues',
    domain: 'parsing',
    docsUrl: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id',
    tags: ['html', 'accessibility'],
    fixable: false,
  },
  create: (ctx) => (htmlContent: string) => {
    const doc = ctx.utils.parseHtml(htmlContent);
    if (!doc) return;
    
    const ids = new Set<string>();
    const elements = doc.querySelectorAll('[id]');
    
    elements.forEach((element) => {
      const id = element.getAttribute('id');
      if (id && ids.has(id)) {
        ctx.report({
          message: `Duplicate ID '${id}' found`,
          severity: 'error',
          domain: 'parsing',
          location: {
            selector: `#${id}`,
          },
          suggestion: `Change one of the elements with ID '${id}' to use a unique ID`,
        });
      }
      if (id) ids.add(id);
    });
  },
});

Creating a Primitive Validator

import { createPrimitiveValidator } from '@bernierllc/validators-core';

const htmlSyntaxValidator = createPrimitiveValidator(
  'html-syntax-validator',
  'parsing',
  [
    duplicateIdRule,
    malformedTagsRule,
    invalidAttributesRule,
  ]
);

// Use the validator
const context = createRuleContext('html-validation', {}, utils);
const problems = await htmlSyntaxValidator.validate(htmlContent, context);

Working with Problems and Results

import type { Problem, ValidationResult } from '@bernierllc/validators-core';

function processValidationResult(result: ValidationResult): void {
  const { problems, stats } = result;
  
  const errors = problems.filter(p => p.severity === 'error');
  const warnings = problems.filter(p => p.severity === 'warn');
  
  console.log(`Found ${errors.length} errors and ${warnings.length} warnings`);
  console.log(`Validation took ${stats.durationMs}ms`);
  
  problems.forEach(problem => {
    console.log(`${problem.severity}: ${problem.message}`);
    if (problem.location) {
      console.log(`  Location: ${problem.location.file}:${problem.location.line}`);
    }
    if (problem.suggestion) {
      console.log(`  Suggestion: ${problem.suggestion}`);
    }
  });
}

API Reference

Types

Severity

type Severity = 'off' | 'info' | 'warn' | 'error';

ValidationDomain

type ValidationDomain = 'parsing' | 'security' | 'schema' | 'accessibility' | 
  'content' | 'workflow' | 'release' | 'compliance' | 'performance';

Problem

interface Problem {
  ruleId: string;
  message: string;
  severity: Severity;
  domain: ValidationDomain;
  location?: {
    file?: string;
    line?: number;
    column?: number;
    selector?: string;
    xpath?: string;
  };
  docUrl?: string;
  suggestion?: string;
  fixable?: boolean;
  tags?: string[];
  evidence?: {
    snippet?: string;
    screenshot?: string;
    context?: Record<string, unknown>;
  };
}

Rule<T>

interface Rule<T = unknown> {
  meta: {
    id: string;
    title: string;
    description?: string;
    domain: ValidationDomain;
    docsUrl?: string;
    tags?: string[];
    fixable?: boolean;
    owner: string;
    createdAt: string;
    deprecatedAt?: string;
  };
  create: (ctx: RuleContext<T>) => (target: T) => Promise<void> | void;
}

Functions

defineRule<T>(definition: RuleDefinition<T>): Rule<T>

Creates a new validation rule with proper metadata and timestamps.

createRuleContext<T>(ruleId, options, utils, env): RuleContext<T>

Creates a rule execution context with utilities and reporting function.

createPrimitiveValidator<T>(name, domain, rules): PrimitiveValidator<T>

Creates a primitive validator that runs multiple rules against a target.

composeRules<T>(rules: Rule<T>[]): Rule<T>[]

Utility function for composing multiple rules together.

Architecture Principles

Pure Functions

Validators are pure functions that take input and return structured problems. They never:

• Throw exceptions for validation failures
• Make enforcement decisions
• Modify the input
• Perform side effects

Tool-Agnostic Design

Rules work in any context:

• CLI tools
• Web applications
• CI/CD pipelines
• IDE plugins
• API services

Evidence-Rich Results

Problems include rich context for debugging:

• Code snippets
• Screenshots
• Fix suggestions
• Documentation links

Integration Status

• Logger integration: not-applicable - Pure validation functions with no runtime logging needs. Core validation rules are stateless and side-effect free.
• Docs-Suite: ready - TypeDoc compatible documentation format
• NeverHub integration: not-applicable - Foundation package providing core types and interfaces only. Service orchestration packages will handle NeverHub integration for validation execution.

See Also

• @bernierllc/validators-runner - Orchestration and execution
• @bernierllc/validators-reporters - Output formatting
• @bernierllc/validators-utils - Shared utilities

License

Copyright (c) 2025 Bernier LLC. All rights reserved.