Package Exports

@bernierllc/validators-core
@bernierllc/validators-core/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@bernierllc/validators-core) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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.

JSPM