# @bernierllc/validators-runner

Validation orchestration engine that provides a flexible framework for running validation rules against targets with advanced configuration, reporting, and error handling capabilities.

## Installation

```bash
npm install @bernierllc/validators-runner
```

## Usage

### Basic Example

```typescript
import { ValidationRunner, RunnerBuilder } from '@bernierllc/validators-runner';

// Create a validation rule
const textRule = {
  meta: { id: 'text-check', name: 'Text Check' },
  async execute(target) {
    if (target.data.includes('error')) {
      return [{ 
        level: 'error', 
        message: 'Found error in text',
        location: { line: 1, column: 0 }
      }];
    }
    return [];
  }
};

// Build and configure runner
const runner = new RunnerBuilder()
  .withRule(textRule)
  .withConcurrency(5)
  .build();

// Define targets to validate
const targets = [
  { id: 'doc1', type: 'text', data: 'This is clean content' },
  { id: 'doc2', type: 'text', data: 'This has error content' }
];

// Run validation
const result = await runner.validate(targets);

console.log(`Found ${result.problems.length} problems`);
console.log(`Processed ${result.stats.targets} targets in ${result.stats.durationMs}ms`);
```

### Advanced Configuration

```typescript
import { ConfigLoader } from '@bernierllc/validators-runner';

// Load configuration from file
const config = await ConfigLoader.fromFile('./validation.config.json');

const runner = new RunnerBuilder()
  .withConfig(config)
  .withRule(textRule)
  .withReporter(consoleReporter)
  .build();

// Configure filtering and rule options
const configuredRunner = new ValidationRunner({
  rules: [textRule],
  config: {
    include: ['**/*.ts', '**/*.js'],
    exclude: ['**/node_modules/**'],
    primitives: {
      'text-check': ['error', { maxLength: 100 }]
    }
  },
  concurrency: 10,
  timeout: 5000
});
```

### Configuration File Example

```json
{
  "include": ["**/*.ts", "**/*.js"],
  "exclude": ["**/dist/**", "**/node_modules/**"],
  "primitives": {
    "text-check": "error",
    "length-check": ["warn", { "max": 1000 }]
  },
  "timeout": 10000
}
```

## API Reference

### ValidationRunner

Main orchestration class for running validations.

#### Constructor

```typescript
new ValidationRunner(options: RunnerOptions)
```

**Options:**
- `rules: Rule[]` - Validation rules to apply
- `config?: RunnerConfig` - Configuration options
- `concurrency?: number` - Max concurrent validations (default: 5)
- `timeout?: number` - Timeout per validation in ms (default: 30000)

#### Methods

##### `validate(targets: RunnerTarget[]): Promise<RunnerResult>`

Validates all targets and returns comprehensive results.

**Parameters:**
- `targets` - Array of targets to validate

**Returns:**
- `RunnerResult` - Validation results with problems, stats, and metadata

### RunnerBuilder

Fluent API for constructing ValidationRunner instances.

#### Methods

```typescript
withRule(rule: Rule): RunnerBuilder
withReporter(reporter: Reporter): RunnerBuilder  
withConfig(config: RunnerConfig): RunnerBuilder
withConcurrency(concurrency: number): RunnerBuilder
withTimeout(timeout: number): RunnerBuilder
build(): ValidationRunner
```

### ConfigLoader

Utility for loading configuration from various sources.

#### Static Methods

```typescript
ConfigLoader.fromFile(path: string): Promise<RunnerConfig>
ConfigLoader.fromObject(obj: any): Promise<RunnerConfig>
ConfigLoader.fromEnv(prefix?: string): Promise<RunnerConfig>
```

### Types

#### RunnerTarget
```typescript
interface RunnerTarget {
  id: string;
  type: string;
  data: any;
}
```

#### RunnerResult
```typescript
interface RunnerResult {
  problems: Problem[];
  stats: {
    targets: number;
    durationMs: number;
    rulesApplied: string[];
  };
  targetResults: Map<string, ValidationResult>;
  executionMeta: ExecutionMetadata;
}
```

#### RunnerConfig
```typescript
interface RunnerConfig {
  include?: string[];
  exclude?: string[];
  primitives?: Record<string, any>;
  timeout?: number;
}
```

## Integration Status

### Logger Integration
- **Status**: not-applicable 
- **Reason**: Core validation infrastructure focuses on orchestration without introducing logging dependencies. Consumer applications should handle logging of validation results as appropriate for their context.

### Docs-Suite Integration
- **Status**: ready
- **Format**: markdown
- **Description**: Package includes comprehensive markdown documentation with TypeScript examples and API references suitable for docs-suite integration.

### NeverHub Integration  
- **Status**: not-applicable
- **Reason**: Validation runner is a foundational utility that operates synchronously on provided data. Event-driven service discovery is not applicable to this validation orchestration pattern.

## Error Handling

The package follows structured error handling patterns:

```typescript
// All operations return structured results
const result = await runner.validate(targets);

if (result.problems.length > 0) {
  console.log('Validation issues found:');
  result.problems.forEach(problem => {
    console.log(`${problem.level}: ${problem.message}`);
  });
}

// Execution metadata includes error details
if (result.executionMeta.errors.length > 0) {
  console.log('Execution errors:', result.executionMeta.errors);
}
```

## Contributing

This package follows the BernierLLC package standards:
- TypeScript strict mode
- 90%+ test coverage for core packages
- Zero linting errors
- Comprehensive documentation

## License

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