--- name: lisp-validator description: Validate Lisp code (Clojure, Racket, Scheme, Common Lisp) for syntax errors, parenthesis balance, and semantic issues. This skill should be used when validating Lisp code files, checking for syntax errors before execution, or validating LLM-generated Lisp code including incomplete or partial expressions. Provides structured JSON output optimized for automated workflows. license: AGPL 3.0 - Complete terms in LICENSE --- # Lisp Validator ## Overview This skill validates Lisp code across multiple dialects (Clojure, Racket, Scheme, Common Lisp) using dialect-specific tools optimized for LLM workflows. Critical for validating incomplete or partially-generated code during LLM-guided editing, it provides structured error output with precise file:line:col information for targeted fixes. **Key capabilities:** - Auto-detects Lisp dialect from file extension and content - Handles incomplete code via tree-sitter (critical for LLM workflows) - Provides structured JSON output for machine parsing - Multi-tool validation for comprehensive error detection - Installation detection and guidance for missing tools ## When to Use This Skill Use this skill to: - Validate Lisp code files before execution or commit - Check LLM-generated Lisp code for syntax errors - Validate incomplete or partial expressions during code generation - Detect unbalanced parentheses and structural issues - Lint entire projects for style and semantic issues - Determine which validation tools are available on the system ## Workflow Decision Tree ``` ┌─ Code complete? ────┐ │ │ YES NO (incomplete\/partial) │ │ ├─ Detect dialect └─ Use tree-sitter │ (handles incomplete) ├─ Clojure? ──→ clj-kondo + joker ├─ Racket\/Scheme? ──→ raco tools ├─ Common Lisp? ──→ SBLint + SBCL ├─ Elisp? ──→ tree-sitter └─ Unknown? ──→ tree-sitter fallback ``` ## Quick Start ### Check Available Tools Before validating, check which tools are installed: ```bash python3 scripts\/check_tools.py ``` This shows: - Which validation tools are available - Tool installation status per dialect - Installation commands for missing tools - Recommendations based on detected tools ### Validate Any Lisp File (Auto-Detect) ```bash # Auto-detects dialect and uses appropriate validator python3 scripts\/validate.py # Examples python3 scripts\/validate.py src\/core.clj python3 scripts\/validate.py project\/src\/ ``` **Output:** JSON with findings, severity, file:line:col locations ### Format Options ```bash # JSON output (default, best for parsing) python3 scripts\/validate.py file.clj --format json # Human-readable text python3 scripts\/validate.py file.clj --format text # Summary only python3 scripts\/validate.py file.clj --format summary ``` ## Quick Reference | Task | Command | |------|---------| | Check available tools | `python3 scripts\/check_tools.py` | | Auto-detect & validate | `python3 scripts\/validate.py src\/` | | Validate incomplete code | `python3 scripts\/validate.py file.clj --tree-sitter` | | Force specific dialect | `python3 scripts\/validate.py file.scm --dialect scheme` | | Clojure-specific | `python3 scripts\/validate_clojure.py src\/` | | Racket\/Scheme-specific | `python3 scripts\/validate_scheme.py src\/` | | Common Lisp-specific | `python3 scripts\/validate_common_lisp.py src\/` | | Human-readable output | `python3 scripts\/validate.py src\/ --format text` | | JSON output (default) | `python3 scripts\/validate.py src\/ --format json` | | Summary only | `python3 scripts\/validate.py src\/ --format summary` | **Exit Codes:** - `0` - No issues found - `2` - Warnings only (code should run) - `3` - Errors present (code may not run) ## Examples ### Example 1: Validating During Code Generation When generating Clojure code incrementally with an LLM: ```bash # After each edit, validate with tree-sitter (handles incomplete code) python3 scripts\/validate.py partial.clj --tree-sitter --format summary # Once complete, run comprehensive validation python3 scripts\/validate.py complete.clj --format text ``` **Output** (incomplete code): ``` 0 errors, 1 warnings (tree-sitter) ``` **Output** (complete code): ``` Target: complete.clj Dialect: clojure No issues found! Summary: 0 errors, 0 warnings Tools used: clj-kondo, joker ``` ### Example 2: CI\/CD Integration ```yaml # .github\/workflows\/validate-lisp.yml name: Validate Lisp Code on: [push, pull_request] jobs: validate: runs-on: ubuntu-latest steps: - uses: actions\/checkout@v3 - name: Install validation tools run: | curl -sLO https:\/\/raw.githubusercontent.com\/borkdude\/clj-kondo\/master\/script\/install-clj-kondo chmod +x install-clj-kondo && .\/install-clj-kondo - name: Check available tools run: python3 scripts\/check_tools.py - name: Validate Clojure code run: | python3 scripts\/validate.py src\/ --format json > validation-results.json cat validation-results.json | jq - name: Fail on errors run: | errors=$(jq '.summary.total_errors' validation-results.json) if [ "$errors" -gt 0 ]; then echo "❌ Found $errors errors" exit 1 fi echo "✅ Validation passed" ``` ### Example 3: Progressive Validation Workflow ```bash # Stage 1: Fast structural check (< 1s) python3 scripts\/validate_tree_sitter.py src\/core.clj # Stage 2: Comprehensive validation (if stage 1 passes) python3 scripts\/validate_clojure.py src\/core.clj # Stage 3: Auto-format (only if validation passes) if [ $? -eq 0 ]; then cljfmt fix src\/core.clj fi ``` ### Example 4: Pre-Commit Hook ```bash # .git\/hooks\/pre-commit #!\/bin\/bash echo "Validating Lisp files..." # Get staged .clj files STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.clj$') if [ -z "$STAGED_FILES" ]; then exit 0 fi # Validate each file for FILE in $STAGED_FILES; do python3 scripts\/validate.py "$FILE" --format summary if [ $? -eq 3 ]; then echo "❌ Validation failed for $FILE" echo "Fix errors before committing" exit 1 fi done echo "✅ All files validated successfully" exit 0 ``` ### Example 5: Handling Validation Errors in Scripts ```python import subprocess import json def validate_and_report(file_path): """Validate a file and provide structured feedback.""" result = subprocess.run( ["python3", "scripts\/validate.py", file_path, "--format", "json"], capture_output=True, text=True ) data = json.loads(result.stdout) if data["summary"]["total_errors"] > 0: print(f"⚠️ Found {data['summary']['total_errors']} errors in {file_path}:") for finding in data["findings"]: if finding["severity"] == "error": location = f"{finding['file']}:{finding['line']}:{finding['col']}" print(f" {location}: {finding['message']}") return False print(f"✅ {file_path} validated successfully") return True # Use it if not validate_and_report("src\/main.clj"): exit(1) ``` ### Example 6: Checking Tool Installation ```bash # Check which tools are available python3 scripts\/check_tools.py # Install missing high-priority tools python3 scripts\/check_tools.py --json | \ jq -r '.tools | to_entries[] | select(.value.available == false and .value.priority == "high") | .key' ``` **Output:** ``` === Lisp Validation Tools Status === CLOJURE: [✓] clj-kondo (2024.03.13) Primary Clojure validator with JSON output [✗] joker Secondary Clojure validator with complementary checks UNIVERSAL: [✓] tree-sitter-python (installed) Tree-sitter Python library (more reliable than CLI) [✗] tree-sitter Universal parser for incomplete\/partial code (CLI) === Recommendations === CLOJURE: ℹ️ Consider installing joker (complementary checks) UNIVERSAL: ℹ️ Consider tree-sitter Python library (more reliable) ``` ## Dialect-Specific Validation ### Clojure **Primary tool:** clj-kondo (JSON output, comprehensive) **Secondary tool:** joker (complementary checks) ```bash # Using dialect-specific validator python3 scripts\/validate_clojure.py # Skip joker (faster, clj-kondo only) python3 scripts\/validate_clojure.py src\/ --no-joker ``` **What it detects:** - Unbalanced parentheses - Mismatched delimiters (`{` closed with `)`) - Unexpected EOF - Undefined symbols - Arity mismatches - Unused bindings - Style issues **Output structure:** ```json { "target": "src\/core.clj", "dialect": "clojure", "findings": [ { "file": "src\/core.clj", "line": 10, "col": 15, "end_line": 10, "end_col": 20, "severity": "error", "message": "Unexpected EOF.", "type": "unexpected-eof", "tool": "clj-kondo" } ], "summary": { "total_errors": 1, "total_warnings": 0, "tools_used": ["clj-kondo", "joker"] } } ``` **Exit codes:** - 0: No issues - 2: Warnings only - 3: Errors present ### Racket\/Scheme **Tools used:** raco expand, raco review, raco warn (tiered validation) **Note:** raco tools work for both Racket and generic Scheme when Racket is installed ```bash # Using dialect-specific validator python3 scripts\/validate_scheme.py # Force raco tools (default if available) python3 scripts\/validate_scheme.py file.rkt --raco # Fallback to specific Scheme dialect python3 scripts\/validate_scheme.py file.scm --no-raco --dialect guile ``` **Supported Scheme dialects (when raco unavailable):** - guile - chez - chicken - mit **Validation stages:** 1. **Fast check** (raco expand): Safe syntax validation without execution 2. **Surface lint** (raco review): Quick error detection 3. **Deep analysis** (raco warn): Comprehensive warnings with suggestions **What it detects:** - Unbound identifiers - Duplicate bindings - Arity mismatches - Type errors (Typed Racket) - Unused variables - Style violations ### Common Lisp **Primary tool:** SBLint (machine-readable output) **Secondary tool:** SBCL (deep semantic validation) ```bash # Using dialect-specific validator python3 scripts\/validate_common_lisp.py # Skip SBCL (faster, SBLint only) python3 scripts\/validate_common_lisp.py src\/ --no-sbcl ``` **What it detects:** - Undefined variables - Undefined functions - Unused variables - Style warnings - Compilation errors - Read errors (syntax) **Note:** SBCL provides verbose output requiring parsing; SBLint provides machine-readable format. ### Tree-Sitter (Incomplete Code) **Critical for LLM workflows:** Handles partial\/incomplete expressions ```bash # Using tree-sitter validator python3 scripts\/validate_tree_sitter.py # Use Python library (more reliable) python3 scripts\/validate_tree_sitter.py file.lisp # Use CLI only python3 scripts\/validate_tree_sitter.py file.lisp --no-python ``` **When to use:** - Code is incomplete (missing closing parens) - Validating partial expressions during generation - Traditional validators fail on incomplete code - Structural validation without semantic analysis **Supported grammars:** - Clojure (`tree-sitter-clojure`) - Common Lisp (`tree-sitter-commonlisp`) - Emacs Lisp (`tree-sitter-elisp`) **Output:** Marks ERROR and MISSING nodes in parse tree ## Validation Workflows ### Progressive Validation (Recommended) Validate in stages from fast to comprehensive: ```bash # Stage 1: Fast check (< 1s) python3 scripts\/validate_tree_sitter.py file.clj # Stage 2: Comprehensive (if stage 1 passes) python3 scripts\/validate_clojure.py file.clj # Stage 3: Auto-format (only if validation passes) # [Apply formatter like cljfmt, raco fmt, etc.] ``` ### Incomplete Code Validation When validating LLM-generated partial code: ```bash # Force tree-sitter for incomplete code python3 scripts\/validate.py partial_code.clj --tree-sitter ``` **Interpreting results for incomplete code:** - ERROR nodes: Unparseable sections - MISSING nodes: Expected tokens absent - "Unexpected EOF" is expected for incomplete code Serious structural errors beyond incompleteness warrant attention. ### Project-Wide Validation ```bash # Validate entire project (auto-detects files) python3 scripts\/validate.py project\/src\/ # Clojure project python3 scripts\/validate_clojure.py src\/ # Racket package python3 scripts\/validate_scheme.py src\/ --raco # Common Lisp system python3 scripts\/validate_common_lisp.py src\/ ``` ## Using Validation Scripts ### Main Orchestrator `scripts\/validate.py` auto-detects dialect and routes to appropriate validator. **Options:** ```bash --dialect Force specific dialect --tree-sitter Force tree-sitter (incomplete code) --format Output format (json|text|summary) ``` **Examples:** ```bash # Auto-detect python3 scripts\/validate.py src\/ # Force dialect python3 scripts\/validate.py file.scm --dialect scheme # Incomplete code python3 scripts\/validate.py partial.clj --tree-sitter # Human-readable output python3 scripts\/validate.py src\/ --format text ``` ### Dialect-Specific Validators Each validator provides focused validation for its dialect: **Clojure:** ```bash python3 scripts\/validate_clojure.py [--no-joker] ``` **Racket\/Scheme:** ```bash python3 scripts\/validate_scheme.py [--no-raco] [--dialect ] ``` **Common Lisp:** ```bash python3 scripts\/validate_common_lisp.py [--no-sbcl] ``` **Tree-sitter:** ```bash python3 scripts\/validate_tree_sitter.py [--no-python] ``` ### Tool Checker `scripts\/check_tools.py` shows installation status and provides installation guidance. ```bash # Text output (default) python3 scripts\/check_tools.py # JSON output python3 scripts\/check_tools.py --json ``` ## Reference Documentation Detailed information is available in the `references\/` directory: ### references\/tool_comparison.md Load this when determining which validation tools to use. Contains: - Complete tool comparison matrix - Detailed tool profiles (installation, usage, output formats) - Dialect-specific recommendations - Performance comparison - Exit code standards - Optimal tool combinations for LLM workflows **Use when:** - Selecting validation tools for a project - Understanding tool capabilities and limitations - Comparing different validators - Setting up CI\/CD pipelines ### references\/error_patterns.md Load this when parsing validation tool output. Contains: - Regex patterns for each tool's output format - Structured output formats (JSON, parseable text) - Unstructured output parsing strategies (SBCL, Scheme dialects) - Unified error schema for normalization - Common error types by dialect - Edge cases and parsing best practices **Use when:** - Parsing validation output programmatically - Normalizing errors across multiple tools - Implementing custom error handlers - Debugging parsing issues ### references\/integration_strategies.md Load this when integrating validation into LLM workflows. Contains: - Core principles (progressive validation, structured output) - Dialect-specific strategies and pipelines - LLM-specific patterns (edit validation loop, partial expression validation) - CI\/CD integration examples - Performance optimization techniques - Error recovery strategies **Use when:** - Implementing LLM-guided code editing workflows - Setting up automated validation pipelines - Optimizing validation performance - Handling validation errors in LLM context ## Interpreting Validation Results ### Error Severity Levels - **error**: Code will not run (syntax errors, undefined symbols) - **warning**: Code may run but has issues (unused variables, style) - **info**: Informational messages (suggestions, style recommendations) ### Common Error Types **Unbalanced parentheses:** ``` error: Unexpected EOF (missing closing parenthesis) error: Unmatched delimiter: ) ``` **Undefined symbols:** ``` error: Unresolved symbol: foo error: Unbound variable: bar ``` **Arity mismatches:** ``` error: Wrong number of args (3) passed to function (expects 2) ``` ### Acting on Validation Results 1. **Errors first:** Fix syntax and structural errors before warnings 2. **Location precision:** Use file:line:col to locate exact problem 3. **Suggestions:** Some tools (raco warn) provide fix suggestions 4. **Multiple tools:** Different tools may catch different issues 5. **Incomplete code:** Distinguish between "incomplete" and "invalid" ## Installation Guidance ### Recommended Tools by Dialect **Clojure:** ```bash # Primary: clj-kondo brew install borkdude\/brew\/clj-kondo # Or: npm install -g clj-kondo # Secondary: joker brew install candid82\/joker\/joker ``` **Racket\/Scheme:** ```bash # Install Racket (provides raco) brew install racket # macOS # Or download from: https:\/\/racket-lang.org # Install raco packages raco pkg install review syntax-warn ``` **Common Lisp:** ```bash # Install Roswell brew install roswell # macOS # Install SBCL and SBLint ros install sbcl ros use sbcl ros install cxxxr\/sblint ``` **Universal (all dialects):** ```bash # tree-sitter CLI npm install -g tree-sitter-cli@0.19.3 # tree-sitter Python library (more reliable) pip install tree-sitter tree-sitter-commonlisp tree-sitter-clojure tree-sitter-elisp ``` ### Checking Installation Status Always check which tools are available before validating: ```bash python3 scripts\/check_tools.py ``` This provides: - Installation status per tool - Platform-specific installation commands - Dialect-specific recommendations - Warnings for missing high-priority tools ## Best Practices 1. **Check tools first:** Run `check_tools.py` to verify available validators 2. **Use structured output:** JSON format for programmatic parsing 3. **Validate incrementally:** After each code edit in LLM workflows 4. **Handle incomplete code:** Use tree-sitter for partial expressions 5. **Combine tools:** Multiple validators catch different error types 6. **Read references:** Load relevant reference docs for detailed guidance 7. **Interpret exit codes:** 0=success, 2=warnings, 3=errors 8. **Fix errors before warnings:** Prioritize structural issues 9. **Use progressive validation:** Fast check → comprehensive → auto-fix 10. **Cache when possible:** clj-kondo and raco warn support caching ## Exit Codes All validation scripts use consistent exit codes: - **0**: Validation passed (no errors or warnings) - **2**: Warnings only (code should run) - **3**: Errors present (code may not run) Use these for automation: ```bash if python3 scripts\/validate.py src\/; then echo "✓ Validation passed" else exit_code=$? if [ $exit_code -eq 2 ]; then echo "⚠ Warnings present" elif [ $exit_code -eq 3 ]; then echo "✗ Errors found" fi fi ``` ## Troubleshooting ### "Tool not found" errors **Problem:** `clj-kondo not found` even though it's installed ```bash # 1. Check if tool is in PATH which clj-kondo # 2. Verify installation clj-kondo --version # 3. Check PATH variable echo $PATH # 4. If not found, install it brew install borkdude\/brew\/clj-kondo # or npm install -g clj-kondo ``` ### "Cannot parse output" errors **Problem:** Tree-sitter parse errors on valid code This usually means you're using tree-sitter CLI 0.20+. Downgrade to 0.19.3: ```bash # Uninstall current version npm uninstall -g tree-sitter-cli # Install correct version npm install -g tree-sitter-cli@0.19.3 # Verify version tree-sitter --version # Should output: tree-sitter 0.19.3 ``` ### "Unexpected EOF" on complete code **Problem:** Getting EOF errors but code looks complete ```bash # Use tree-sitter to find exact error location python3 scripts\/validate_tree_sitter.py file.clj # Check for hidden characters or mismatched delimiters cat -A file.clj # Shows hidden characters # Count delimiters grep -o '(' file.clj | wc -l # Count opening parens grep -o ')' file.clj | wc -l # Count closing parens ``` ### False positives **Problem:** Joker flags macro-introduced bindings as errors ```bash # Cross-reference with clj-kondo only python3 scripts\/validate_clojure.py file.clj --no-joker # Compare tools side by side python3 scripts\/validate_clojure.py file.clj --format json | \ jq '.findings[] | select(.tool == "joker")' ``` ### Performance issues **Problem:** Validation takes too long on large projects ```bash # Skip secondary tools for faster validation python3 scripts\/validate_clojure.py src\/ --no-joker python3 scripts\/validate_common_lisp.py src\/ --no-sbcl # Validate only changed files (with git) git diff --name-only --cached | \ grep '\.clj$' | \ xargs python3 scripts\/validate.py # Parallel validation for multiple files find src -name '*.clj' | \ xargs -P 4 -I {} python3 scripts\/validate.py {} ``` ### JSON parsing errors **Problem:** Cannot parse validation output as JSON ```bash # Ensure you're getting JSON output python3 scripts\/validate.py file.clj --format json | jq # Check for stderr contamination python3 scripts\/validate.py file.clj --format json 2>\/dev\/null | jq # Validate JSON structure python3 scripts\/validate.py file.clj --format json | python3 -m json.tool ```