credl-parser-evaluator/docs/API_REFERENCE.md

TypeScript-based CREDL Parser and Evaluator that processes CREDL files and outputs complete Intermediate Representations

# CREDL Parser and Evaluator - API Reference

Complete API reference for the CREDL Parser and Evaluator library.

## Core Functions

### `processFile(yamlContent, validationOptions?, irOptions?)`

Parse, validate, and generate IR from CREDL content in one step.

**Parameters:**
- `yamlContent: string` - The YAML content as a string
- `validationOptions?: ValidationOptions` - Optional validation configuration
- `irOptions?: IRBuilderOptions` - Optional IR builder configuration

**Returns:** `Promise<IR>` - Complete intermediate representation

**Example:**
```typescript
const ir = await processFile(yamlContent, {
  failFast: false,
  strictMode: true
}, {
  includeDebugInfo: true
});
```

### `parse(yamlContent)`

Parse CREDL YAML content into typed objects.

**Parameters:**
- `yamlContent: string` - The YAML content as a string

**Returns:** `Promise<CREDLFile>` - Parsed CREDL file structure

### `validate(credlFile, options?)`

Validate a parsed CREDL file structure.

**Parameters:**
- `credlFile: CREDLFile` - The parsed CREDL file
- `options?: ValidationOptions` - Optional validation configuration

**Returns:** `Promise<ValidationResult>` - Validation results with errors and warnings

### `generateIR(credlFile, options?)`

Generate complete IR from parsed and validated CREDL data.

**Parameters:**
- `credlFile: CREDLFile` - The parsed and validated CREDL file
- `options?: IRBuilderOptions` - Optional IR builder configuration

**Returns:** `Promise<IR>` - Generated intermediate representation

## File I/O Functions

### `processFileFromPath(filePath, validationOptions?, irOptions?)`

Process a CREDL file from disk using async file I/O.

**Parameters:**
- `filePath: string` - Path to the CREDL YAML file
- `validationOptions?: ValidationOptions` - Optional validation configuration
- `irOptions?: IRBuilderOptions` - Optional IR builder configuration

**Returns:** `Promise<IR>` - Complete intermediate representation

### `writeIRToFile(ir, outputPath, pretty?)`

Write IR results to a JSON file.

**Parameters:**
- `ir: IR` - The IR to write
- `outputPath: string` - Path where to write the JSON file
- `pretty?: boolean` - Whether to format JSON with indentation (default: true)

**Returns:** `Promise<void>`

### `processMultipleFiles(filePaths, validationOptions?, irOptions?, maxConcurrency?)`

Process multiple CREDL files concurrently.

**Parameters:**
- `filePaths: string[]` - Array of CREDL file paths to process
- `validationOptions?: ValidationOptions` - Optional validation configuration
- `irOptions?: IRBuilderOptions` - Optional IR builder configuration
- `maxConcurrency?: number` - Maximum concurrent files (default: 5)

**Returns:** `Promise<Array<{filePath: string; ir?: IR; error?: string}>>` - Results array

## Stream Functions

### `processStream(stream, validationOptions?, irOptions?)`

Process CREDL content from a readable stream.

**Parameters:**
- `stream: Readable` - Readable stream containing CREDL YAML content
- `validationOptions?: ValidationOptions` - Optional validation configuration
- `irOptions?: IRBuilderOptions` - Optional IR builder configuration

**Returns:** `Promise<IR>` - Complete intermediate representation

### `parseStream(stream)`

Parse CREDL content from a readable stream.

**Parameters:**
- `stream: Readable` - Readable stream containing CREDL YAML content

**Returns:** `Promise<CREDLFile>` - Parsed CREDL file structure

### `createStreamFromString(content)`

Create a readable stream from a string (utility function).

**Parameters:**
- `content: string` - String content to convert to stream

**Returns:** `Readable` - Readable stream containing the content

## Utility Functions

### `validateFile(yamlContent, options?)`

Validate CREDL content without generating full IR.

**Parameters:**
- `yamlContent: string` - The YAML content as a string
- `options?: ValidationOptions` - Optional validation configuration

**Returns:** `Promise<ValidationResult & {credlFile?: CREDLFile}>` - Validation results with parsed file

### `checkFileExists(filePath)`

Check if a file exists and is readable.

**Parameters:**
- `filePath: string` - Path to check

**Returns:** `Promise<boolean>` - True if file exists and is readable

### `getFileStats(filePath)`

Get file stats using async file I/O.

**Parameters:**
- `filePath: string` - Path to get stats for

**Returns:** `Promise<{size: number; modified: Date} | null>` - File stats or null

### `getVersion()`

Get library version and metadata.

**Returns:** `{version: string; generator: string}` - Version information

## Configuration Options

### `ValidationOptions`

```typescript
interface ValidationOptions {
  failFast?: boolean;        // Stop on first error (default: true)
  strictMode?: boolean;      // Enable strict validation (default: false)
  maxErrors?: number;        // Maximum errors to collect (default: 100)
  enableWarnings?: boolean;  // Enable warning generation (default: true)
}
```

### `IRBuilderOptions`

```typescript
interface IRBuilderOptions {
  includeDebugInfo?: boolean;    // Include debug information (default: false)
  validateConstraints?: boolean; // Validate business constraints (default: true)
  optimizeOutput?: boolean;      // Optimize IR structure (default: true)
  maxSpaceGeneration?: number;   // Max spaces from templates (default: 1000)
}
```

## Type Definitions

### `CREDLFile`

Main CREDL file structure containing all parsed blocks.

```typescript
interface CREDLFile {
  metadata: Metadata;
  assets: Asset[];
  spaces: Space[];
  assumptions: Assumption[];
  models: Model[];
  simulation: Simulation;
  outputs: Output;
  presets?: Presets;
  templates?: Templates;
  use_templates?: UseTemplate[];
  extensions?: Extensions;
}
```

### `IR` (Intermediate Representation)

Complete intermediate representation generated from CREDL file.

```typescript
interface IR {
  metadata: IRMetadata;
  assets: Asset[];
  spaces: Space[];
  assumptions: Assumption[];
  models: Model[];
  simulation: Simulation;
  outputs: Output;
  validation: ValidationResult;
  cross_reference_resolution: CrossReferenceResolution;
  resolution_order: string[];
  presets_resolved?: boolean;
  template_generated_spaces?: Space[];
  extensions?: Extensions;
}
```

### `ValidationResult`

Validation results with errors and warnings.

```typescript
interface ValidationResult {
  isValid: boolean;
  errors: ValidationError[];
  warnings: ValidationError[];
}
```

### `ValidationError`

Individual validation error or warning.

```typescript
interface ValidationError {
  field: string;
  message: string;
  severity: 'error' | 'warning';
  line?: number;
  column?: number;
}
```

## Advanced Classes

For advanced usage, individual classes are also exported:

### `CREDLParser`

Low-level YAML parsing functionality.

```typescript
import { CREDLParser } from 'credl-parser-evaluator';

const result = CREDLParser.parseString(yamlContent);
const fileResult = CREDLParser.parseFile(filePath);
const streamResult = await CREDLParser.parseStream(stream);
```

### `SchemaValidator`

Schema validation functionality.

```typescript
import { SchemaValidator } from 'credl-parser-evaluator';

const validator = new SchemaValidator();
const result = validator.validate(credlFile, options);
```

### `IRBuilder`

IR generation functionality.

```typescript
import { IRBuilder } from 'credl-parser-evaluator';

const ir = IRBuilder.buildIR(credlFile, options);
```

### `PresetResolver`

Preset resolution functionality.

```typescript
import { PresetResolver } from 'credl-parser-evaluator';

const resolver = new PresetResolver();
resolver.parsePresets(credlFile.presets);
const resolvedValue = resolver.resolvePresetValue('lease_profiles', 'office_standard');
```

### `TemplateResolver`

Template processing functionality.

```typescript
import { TemplateResolver } from 'credl-parser-evaluator';

const resolver = new TemplateResolver();
resolver.parseTemplates(credlFile.templates);
const spaces = resolver.generateSpacesFromTemplate('office_floor', 'building-1', 100);
```

## Error Types

The library throws specific error types for different failure scenarios:

- **Parse Errors**: YAML syntax or structure errors
- **Validation Errors**: Schema validation failures
- **IR Generation Errors**: Cross-reference or constraint violations
- **File I/O Errors**: File system access issues
- **Stream Errors**: Stream processing failures

All errors include detailed messages and context information when available.