nimcheck/README.md

# 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).