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

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

# 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