Nimcheck

Universal source code validation framework for Nim. Tokenizer-based structural analysis across 28 language flavors, with extension, shebang, and content auto-detection, structured JSON diagnostics, and exception-safe validation paths.

Author: retoor retoor@molodetz.nl · Version 0.1.0 · License MIT · Nim >= 2.0.0

Capabilities

• Detector — resolves LanguageFlavor from explicit input, file extension, shebang, or content scoring with false-positive filters.
• Tokenizer — per-language lexers; position tracking, bracket stack, string and comment context.
• Validator — structural analysis per flavor; factory registry with 40+ aliases.
• Reporting — formatReport() and toJson() on all result types.
• CLI — validate, inspect, and detect subcommands.
• Library — import nimcheck for validateSource, validateFile, inspectSource.

Flavors with validators: Nim, Python, Bash, JavaScript, TypeScript, PHP, HTML, XML, Jinja, JSON, YAML, TOML, C, C++, C#, Java, Go, Rust, Ruby, Lua, Swift, Kotlin, CSS, SQL, Markdown, Dockerfile, Makefile. See supportedFlavors() or bin/nimcheck help for registered aliases.

Architecture

Source → Detector → Tokenizer → Validator → Reporting → ValidationResult

Layer detail: docs/ARCHITECTURE.md.

Quick start

Library

import nimcheck

let r = validateSource("proc hello() = echo 'hi'", lfNim)
echo r.valid
echo r.toJson().pretty()

let r2 = validateFile("src/main.nim")
let info = inspectSource("class Foo:\n    def bar(self): pass", lfPython)

CLI

make build
bin/nimcheck validate --file=source.nim
bin/nimcheck validate --source="print('hi')" --flavor=python
bin/nimcheck inspect --file=source.py
bin/nimcheck detect --file=unknown.txt
echo "var x = 1" | bin/nimcheck validate

CLI reference: docs/API.md (or bin/nimcheck help).

Requirements

• Nim >= 2.0.0
• make (optional; Makefile wraps build and test targets)

No configuration file. No environment variables. Zero setup beyond installing Nim.

Building

make build          # release binary → bin/nimcheck
make build-debug    # -d:nimcheckDebug
nimble build        # equivalent via nimble

Testing

make test           # full suite (~11 s)
make lint           # compile with all hints and warnings
nim c -r tests/test_go.nim   # single language

Suites: per-language basic and exhaustive tests, config formats, mixed files, fuzz (null bytes, deep nesting, concurrent calls). See tests/test_all.nim.

Project structure

.
├── Makefile
├── nimcheck.nimble
├── src/nimcheck.nim              # public API and CLI
├── src/nimcheck/
│   ├── core/                     # types, tokenizerbase, validatorbase, detector
│   ├── tokenizers/               # per-language lexers
│   ├── languages/                # per-language validators
│   └── reporting/                # error formatting
├── tests/                        # test_all.nim + per-language suites
├── tests/fixtures/               # valid / invalid / edge_cases per language
├── docs/                         # reference documentation
└── .gitea/workflows/ci.yml       # Gitea Actions pipeline

Documentation

Document	Contents
docs/API.md	Function reference, types, JSON schemas, CLI
docs/ERRORS.md	Error codes, per-language triggers
docs/ARCHITECTURE.md	Pipeline layers and detection order
docs/STATUS.md	Release status, verification, changelog
docs/GITEA.md	CI setup, default branch master
CONTRIBUTING.md	Development workflow, adding languages

License

MIT — see LICENSE.