feat: add initial validatrix project with multi-language validator framework

Establish the Validatrix source code validation framework in Nim, including core detection, tokenization, and validation infrastructure for 10 languages (bash, HTML, JavaScript, Jinja, JSON, Nim, PHP, Python, TOML, YAML). The initial commit introduces the main validatrix.nim entry point with public API (validateSource, validateFile, inspectSource), a comprehensive test suite with per-language test files, build configuration via Makefile and .nimble, detailed LESSONS_LEARNED.md documenting 14 bug classes found during development, and a .gitignore excluding compiled binaries, logs, and build artifacts. The detector module provides extension-to-flavor mapping for 40+ file extensions and content-based language detection, while the debug module supports conditional compilation with -d:validatrixDebug for detailed tokenization logging.
2026-07-08 04:25:59 +00:00
commit 7e8917e527
71 changed files with 7726 additions and 0 deletions
@@ -0,0 +1,132 @@
+# Validatrix - Universal Source Code Validation Framework
+# Makefile
+
+NIMC = nim c
+NIMC_MACROS = 
+SRC_DIR = src
+TEST_DIR = tests
+BIN_DIR = bin
+
+.PHONY: all build test test-all test-nim test-python test-bash test-js test-php
+.PHONY: test-html test-jinja test-json test-yaml test-toml test-mixed
+.PHONY: debug lint clean rebuild coverage validate inspect help
+
+all: build
+
+# --- Build targets ---
+
+build:
+	@mkdir -p $(BIN_DIR)
+	$(NIMC) $(NIMC_MACROS) --outdir:$(BIN_DIR) $(SRC_DIR)/validatrix.nim
+
+build-debug:
+	@mkdir -p $(BIN_DIR)
+	$(NIMC) -d:validatrixDebug --outdir:$(BIN_DIR) $(SRC_DIR)/validatrix.nim
+
+# --- Test targets ---
+
+test: test-all
+
+test-all:
+	$(NIMC) -r $(TEST_DIR)/test_all.nim
+
+test-nim:
+	$(NIMC) -r $(TEST_DIR)/test_nim.nim
+
+test-python:
+	$(NIMC) -r $(TEST_DIR)/test_python.nim
+
+test-bash:
+	$(NIMC) -r $(TEST_DIR)/test_bash.nim
+
+test-js:
+	$(NIMC) -r $(TEST_DIR)/test_javascript.nim
+
+test-php:
+	$(NIMC) -r $(TEST_DIR)/test_php.nim
+
+test-html:
+	$(NIMC) -r $(TEST_DIR)/test_html.nim
+
+test-jinja:
+	$(NIMC) -r $(TEST_DIR)/test_jinja.nim
+
+test-json:
+	$(NIMC) -r $(TEST_DIR)/test_json.nim
+
+test-yaml:
+	$(NIMC) -r $(TEST_DIR)/test_yaml.nim
+
+test-toml:
+	$(NIMC) -r $(TEST_DIR)/test_toml.nim
+
+test-mixed:
+	$(NIMC) -r $(TEST_DIR)/test_mixed.nim
+
+# --- Debug mode ---
+
+debug: build-debug
+	$(NIMC) -d:validatrixDebug -r $(TEST_DIR)/test_all.nim
+
+# --- Lint / static analysis ---
+
+lint:
+	$(NIMC) --hints:on --warnings:on $(SRC_DIR)/validatrix.nim
+
+# --- Cleanup ---
+
+clean:
+	rm -rf $(BIN_DIR)
+	rm -f $(SRC_DIR)/*.exe
+	rm -f $(SRC_DIR)/*.o
+	rm -f $(TEST_DIR)/*.exe
+	rm -f $(TEST_DIR)/*.o
+	find . -name '*.exe' -delete
+	find . -name '*.o' -delete
+
+rebuild: clean build
+
+# --- Coverage (requires nim-coverage) ---
+
+coverage:
+	$(NIMC) -d:validatrixCoverage -r $(TEST_DIR)/test_all.nim
+
+# --- Validation command-line tool ---
+
+validate: build
+	@echo "Usage: echo '<source>' | $(BIN_DIR)/validatrix validate --flavor=<lang>"
+	@echo "       $(BIN_DIR)/validatrix validate --file=<path> [--flavor=<lang>]"
+
+inspect: build
+	@echo "Usage: $(BIN_DIR)/validatrix inspect --file=<path> [--flavor=<lang>]"
+	@echo "       $(BIN_DIR)/validatrix inspect --source=<code> --flavor=<lang>"
+
+# --- Help ---
+
+help:
+	@echo "Validatrix - Universal Source Code Validation Framework"
+	@echo ""
+	@echo "Targets:"
+	@echo "  build         - Compile the library"
+	@echo "  build-debug   - Compile with debug mode"
+	@echo "  test          - Run all tests (alias for test-all)"
+	@echo "  test-all      - Run all tests"
+	@echo "  test-nim      - Run Nim-specific tests"
+	@echo "  test-python   - Run Python-specific tests"
+	@echo "  test-bash     - Run Bash-specific tests"
+	@echo "  test-js       - Run JavaScript-specific tests"
+	@echo "  test-php      - Run PHP-specific tests"
+	@echo "  test-html     - Run HTML-specific tests"
+	@echo "  test-jinja    - Run Jinja-specific tests"
+	@echo "  test-json     - Run JSON-specific tests"
+	@echo "  test-yaml     - Run YAML-specific tests"
+	@echo "  test-toml     - Run TOML-specific tests"
+	@echo "  test-mixed    - Run mixed file tests"
+	@echo "  debug         - Run all tests in debug mode"
+	@echo "  lint          - Compile with full hints/warnings"
+	@echo "  clean         - Remove build artifacts"
+	@echo "  rebuild       - Clean and rebuild"
+	@echo "  coverage      - Run tests with coverage instrumentation"
+	@echo "  validate      - Validate source files"
+	@echo "  inspect       - Inspect source structure as JSON"
+	@echo "  help          - Show this help message"