# Validatrix

A multi-language source code validation framework written in Nim. Validatrix uses tokenizer-based validation to check syntax correctness across 10 languages and config formats, with auto-detection, comprehensive diagnostics, and a never-crash guarantee.

## Features

- **10 languages supported**: Nim, Bash, Python, JavaScript, PHP, HTML, Jinja, JSON, YAML, TOML
- **Tokenizer-based validation** — real tokenizers that track bracket depth, string context, comments, and nesting
- **Auto-detection** — detect language from file extension or content analysis
- **Comprehensive diagnostics** — structured error reports with position, severity, hints, and debug output
- **Never-crash guarantee** — every validation path is wrapped in try/except; invalid input returns errors gracefully, never panics
- **JSON output** — machine-readable diagnostics via `toJson()` on any validation result
- **Inspection API** — extract module structure (imports, definitions, functions/classes) as JSON
- **Debug mode** — compile with `-d:validatrixDebug` for detailed tokenization logging
- **No external dependencies** — pure Nim standard library

## Quick Start

```nim
import validatrix

# Validate source code from a string
let r = validateSource("proc hello() = echo 'hi'", lfNim)
echo r.errors  # seq[ValidationError]

# Auto-detect language
let r2 = validateSource("print('hello')", lfUnknown)  # detects Python

# Validate a file
let r3 = validateFile("path/to/file.nim", lfNim)

# Get JSON diagnostics
echo r.toJson().pretty()

# Inspect source structure
let info = inspectSource("class Foo: ...", lfPython)
echo $info  # JSON with class/function info
```

## CLI Usage

When compiled as a standalone binary:

```
validatrix validate --file=source.nim
validatrix validate --source="print('hi')" --flavor=python
validatrix inspect --file=source.py
validatrix detect --file=unknown.txt
```

## API Reference

### Core Functions

| Function | Description |
|---|---|
| `validateSource(source, flavor, options, sourcePath)` | Validate source code string |
| `validateFile(filePath, flavor, options)` | Validate a file |
| `inspectSource(source, flavor, options, sourcePath)` | Return structural diagnostics as JSON |
| `inspectFile(filePath, flavor, options)` | Return structural diagnostics for a file as JSON |
| `detectFlavor(source, filePath)` | Auto-detect language flavor |
| `supportedFlavors()` | List all registered language flavors |

### Types

- **`ValidationResult`** — contains `errors: seq[ValidationError]`, `valid: bool`, `moduleInfo`, `debugOutput`, `detectionInfo`
- **`ValidationError`** — contains `code`, `message`, `severity`, `position`, `hint`, `context`
- **`ValidationOptions`** — contains `flavor`, `debugMode`, `maxErrors`, `validateAll`
- **`LanguageFlavor`** — enum: `lfUnknown`, `lfNim`, `lfBash`, `lfPython`, `lfJavaScript`, `lfPHP`, `lfHTML`, `lfJinja`, `lfJSON`, `lfYAML`, `lfTOML`

## Error Codes

| Code | Meaning |
|---|---|
| `E1000` | Unexpected/unmatched bracket |
| `E1001` | Unclosed bracket |
| `E1002` | Unmatched closing bracket |
| `E2000` | Unclosed string literal |
| `E2001` | Invalid string escape |
| `E2002` | Unclosed multi-line string |
| `E3000` | Unclosed comment |
| `E3001` | Invalid comment syntax |
| `E4000` | Invalid syntax |
| `E4001` | Reserved word misuse |
| `E5000` | Unclosed block/control structure |
| `E9999` | Internal error (never-crash fallback) |

## Supported Languages

| Language | File Extensions | Tokenizer Features |
|---|---|---|
| Nim | `.nim`, `.nims`, `.nimble` | Block comments `#[ ]#` with nesting, triple-quoted strings, raw strings, doc comments |
| Bash | `.sh`, `.bash` | Shebang detection, heredocs, command substitution, variable expansion, fi/done/esac matching |
| Python | `.py` | F-strings with nesting, triple-quoted strings, decorators, async/await, match statements |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | Template literals with nesting, regex literals, arrow functions, ESM imports |
| PHP | `.php` | `<?php` tags, heredocs/nowdocs, variable variables |
| HTML | `.html`, `.htm` | Tag balancing, self-closing tags, attributes |
| Jinja | `.j2`, `.jinja`, `.html.j2` | `{% %}`, `{{ }}`, `{# #}` block detection, nested blocks |
| JSON | `.json` | Bracket balance, string validation, comma checking |
| YAML | `.yaml`, `.yml` | Indentation tracking, key-value checking |
| TOML | `.toml` | Table headers, bracket balance, string validation |

## Building

```bash
# Build the library
nim c src/validatrix.nim

# Build with debug mode
nim c -d:validatrixDebug src/validatrix.nim

# Run all tests
nim c -r tests/test_all.nim

# Build standalone binary
nim c -d:release src/validatrix.nim
```

## Testing

The test suite covers **256 test cases** across all supported languages:

- **25-30 tests per language** including edge cases
- **Fuzz tests** — null bytes, binary data, deep nesting (100 levels), unicode bombs, empty sources
- **Mixed-file validators** — HTML+Jinja combined files
- **Config formats** — JSON, YAML, TOML validation
- **Concurrent validation** — thread safety under parallel calls
- **Never-crash guarantee** — every test verifies invalid input returns graceful errors, not crashes

## Architecture

```
src/validatrix/
  validatrix.nim          # Public API entry point
  core/
    types.nim             # Core types: ValidationResult, ValidationError, LanguageFlavor
    tokenizerbase.nim     # Abstract tokenizer base class
    validatorbase.nim     # Abstract validator base class
    detector.nim          # Language auto-detection
    debug.nim             # Debug logging infrastructure
  tokenizers/
    nim_tokenizer.nim
    bash_tokenizer.nim
    python_tokenizer.nim
    javascript_tokenizer.nim
    php_tokenizer.nim
    html_tokenizer.nim
    jinja_tokenizer.nim
  languages/
    nim_validator.nim
    bash_validator.nim
    python_validator.nim
    javascript_validator.nim
    php_validator.nim
    html_validator.nim
    jinja_validator.nim
    config_validators.nim   # JSON, YAML, TOML validators
  reporting/
    errors.nim            # Error formatting and JSON output
```

## License

MIT

## Author

molodetz — DevPlace Code