@bernierllc/validators-reporters

Output formatters for the BernierLLC validators ecosystem - JSON, SARIF, Markdown, and other reporting formats.

Installation

npm install @bernierllc/validators-reporters

Usage

import { 
  jsonReporter, 
  markdownReporter, 
  sarifReporter, 
  junitReporter,
  getAllReporters,
  getReporter 
} from '@bernierllc/validators-reporters';
import type { ValidationResult } from '@bernierllc/validators-core';

// Example validation result
const validationResult: ValidationResult = {
  problems: [
    {
      ruleId: 'missing-field',
      message: 'Required field "name" is missing',
      severity: 'error',
      domain: 'validation',
      location: { line: 5, column: 2 }
    }
  ],
  stats: { totalFiles: 1, totalProblems: 1 }
};

// Using specific reporters
const jsonOutput = jsonReporter.format(validationResult);
const markdownOutput = markdownReporter.format(validationResult);
const sarifOutput = sarifReporter.format(validationResult);
const junitOutput = junitReporter.format(validationResult);

// Using reporter options
const compactJson = jsonReporter.format(validationResult, {
  includeStats: false,
  includeEvidence: false,
  maxProblems: 10
});

// Getting reporters dynamically
const reporter = getReporter('json');
if (reporter) {
  const output = reporter.format(validationResult);
}

// Getting all available reporters
const allReporters = getAllReporters();
console.log(`Available reporters: ${allReporters.map(r => r.name).join(', ')}`);

API Reference

Reporters

jsonReporter

Formats validation results as structured JSON with full detail.

const output = jsonReporter.format(result, {
  includeStats: true,        // Include statistics summary
  includeEvidence: true,     // Include problem evidence
  includeSuggestions: true,  // Include fix suggestions
  maxProblems: 100          // Limit number of problems
});

compactJsonReporter

Formats validation results as compact JSON without evidence or suggestions.

const output = compactJsonReporter.format(result);

markdownReporter

Formats validation results as readable Markdown with tables and formatting.

const output = markdownReporter.format(result, {
  includeStats: true,
  colorOutput: false  // Disable ANSI colors for plain text
});

sarifReporter

Formats validation results as SARIF (Static Analysis Results Interchange Format) for integration with security tools.

const output = sarifReporter.format(result);

junitReporter

Formats validation results as JUnit XML for CI/CD integration.

const output = junitReporter.format(result);

Utility Functions

getAllReporters()

Returns an array of all available reporters.

const reporters = getAllReporters();
// Returns: Reporter[]

getReporter(name: string)

Finds a reporter by name.

const reporter = getReporter('json');
// Returns: Reporter | undefined

Types

Reporter

interface Reporter {
  name: string;
  format: (result: ValidationResult, options?: ReporterOptions) => string;
}

ReporterOptions

interface ReporterOptions {
  includeStats?: boolean;      // Include statistics summary
  includeEvidence?: boolean;   // Include problem evidence
  includeSuggestions?: boolean; // Include fix suggestions
  colorOutput?: boolean;       // Enable ANSI color output
  maxProblems?: number;        // Limit number of problems reported
}

SARIF Types

Complete TypeScript interfaces for SARIF 2.1.0 specification including:

• SARIFReport, SARIFRun, SARIFResult
• SARIFTool, SARIFDriver, SARIFRule
• SARIFLocation, SARIFPhysicalLocation, SARIFRegion
• SARIFFix, SARIFArtifactChange, SARIFReplacement

JUnit Types

Complete TypeScript interfaces for JUnit XML format:

• JUnitTestSuite, JUnitTestCase
• JUnitFailure, JUnitError

Examples

Basic JSON Reporting

import { jsonReporter } from '@bernierllc/validators-reporters';

const result = await validateMyData(data);
const jsonOutput = jsonReporter.format(result, {
  includeStats: true,
  maxProblems: 50
});

console.log(jsonOutput);

Markdown Report Generation

import { markdownReporter } from '@bernierllc/validators-reporters';

const result = await validateMyFiles(files);
const markdownReport = markdownReporter.format(result, {
  includeStats: true,
  colorOutput: false
});

// Save to file or display in documentation
fs.writeFileSync('validation-report.md', markdownReport);

SARIF Integration for Security Tools

import { sarifReporter } from '@bernierllc/validators-reporters';

const result = await validateSecurityRules(codebase);
const sarifOutput = sarifReporter.format(result);

// Can be consumed by GitHub Security tab, SARIF viewers, etc.
fs.writeFileSync('security-results.sarif', sarifOutput);

CI/CD Pipeline Integration

import { junitReporter } from '@bernierllc/validators-reporters';

const result = await validateBuildArtifacts(artifacts);
const junitXml = junitReporter.format(result);

// Output for CI/CD test result processing
fs.writeFileSync('validation-results.xml', junitXml);

Dynamic Reporter Selection

import { getReporter } from '@bernierllc/validators-reporters';

const reporterName = process.env.REPORT_FORMAT || 'json';
const reporter = getReporter(reporterName);

if (!reporter) {
  throw new Error(`Unknown reporter: ${reporterName}`);
}

const output = reporter.format(validationResult);

Integration Documentation

This package provides integration documentation for all BernierLLC ecosystem components:

Logger Integration

Status: not-applicable - This package focuses on output formatting and does not perform operations that require logging. No @bernierllc/logger integration needed as reporters are stateless formatters that simply transform data structures.

NeverHub Integration

Status: not-applicable - Pure formatting utilities with no service discovery or event communication needs. No @bernierllc/neverhub-adapter integration required as this package provides stateless formatters with graceful degradation built-in. All reporters work independently without external service dependencies.

Docs-Suite Integration

Status: ready - All APIs documented with TypeScript interfaces and JSDoc comments for automated documentation generation.

Configuration

All reporters accept optional configuration through the ReporterOptions interface:

Environment Variables

None - all configuration is passed through options parameters.

Common Options

• includeStats: boolean - Include validation statistics in output
• includeEvidence: boolean - Include evidence data for problems
• includeSuggestions: boolean - Include suggested fixes
• colorOutput: boolean - Enable ANSI color codes (markdown reporter)
• maxProblems: number - Limit the number of problems included

See Also

• @bernierllc/validators-core - Core validation types and interfaces used by this package
• SARIF Specification - Static Analysis Results Interchange Format
• JUnit XML Format - XML format for test results

License

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