|
# 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](docs/ARCHITECTURE.md).
|
|
|
|
## Quick start
|
|
|
|
### Library
|
|
|
|
```nim
|
|
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
|
|
|
|
```bash
|
|
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](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
|
|
|
|
```bash
|
|
make build # release binary → bin/nimcheck
|
|
make build-debug # -d:nimcheckDebug
|
|
nimble build # equivalent via nimble
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
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](docs/API.md) | Function reference, types, JSON schemas, CLI |
|
|
| [docs/ERRORS.md](docs/ERRORS.md) | Error codes, per-language triggers |
|
|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Pipeline layers and detection order |
|
|
| [docs/STATUS.md](docs/STATUS.md) | Release status, verification, changelog |
|
|
| [docs/GITEA.md](docs/GITEA.md) | CI setup, default branch `master` |
|
|
| [CONTRIBUTING.md](CONTRIBUTING.md) | Development workflow, adding languages |
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE). |