refactor(docs): code analysis engine

changes:
  - file: command_handlers.py
    area: cli
    modified: [batch_command]
  - file: output_formatters.py
    area: cli
    modified: [output_batch_yaml, output_batch_json, output_batch_rich, output_json, output_batch_toon]
  - file: settings_builders.py
    area: cli
    modified: [build_batch_settings]

dependencies:
  flow: "command_handlers→validation"
  - command_handlers.py -> validation.py

stats:
  lines: "+2594/-1272 (net +1322)"
  files: 23
  complexity: "Stable complexity"

Author: tom-sapletta-com

.gitignore

@@ -1,3 +1,6 @@
+# Git
+.git/
+
 releases
 vendor/
 publish-env

CHANGELOG.md

@@ -124,6 +124,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Tree-sitter for all** — syntax validation for 165+ languages
 - **Example 07** — comprehensive multi-language demo with 8 languages
 
+## [0.1.17] - 2026-03-23
+
+### Docs
+- Update README.md
+- Update docs/README.md
+- Update project/README.md
+- Update project/context.md
+
+### Other
+- Update .gitignore
+- Update project.sh
+- Update project/analysis.toon
+- Update project/calls.mmd
+- Update project/calls.png
+- Update project/compact_flow.mmd
+- Update project/compact_flow.png
+- Update project/dashboard.html
+- Update project/duplication.toon
+- Update project/evolution.toon
+- ... and 8 more files
+
 ## [0.1.16] - 2026-03-23
 
 ### Docs

README.md

@@ -136,26 +136,63 @@ vallm check src/main.go
 vallm info
 ```
 
+### Fast Validation Options
+
+When validating large projects (100+ files), use these options to speed up validation:
+
+```bash
+# Fastest - syntax only (skip imports and complexity)
+vallm batch . --recursive --no-imports --no-complexity
+
+# Fast - skip import validation (often the slowest)
+vallm batch . --recursive --no-imports
+
+# Parallel processing for multi-core speedup
+vallm batch . --recursive --parallel
+
+# Combine for maximum speed
+vallm batch . --recursive --parallel --no-imports --no-complexity
+
+# Quick syntax check only (single files)
+vallm check src/proxym/config.py
+```
+
+| Option | Speed Impact | Description |
+|--------|--------------|-------------|
+| `--no-imports` | **High** | Skip import resolution (slowest validator) |
+| `--no-complexity` | **Medium** | Skip complexity analysis (radon/lizard) |
+| `--parallel` | **High** | Process files in parallel (multi-core) |
+| `--security` | **Low** | Add security checks (fast pattern matching) |
+
+**Recommendation for CI/CD:**
+```bash
+# Fast validation for quick feedback
+vallm batch src/ --recursive --no-imports --parallel
+
+# Full validation before merge (slower but thorough)
+vallm batch src/ --recursive --parallel
+```
+
 ### Generate Validation Summary File
 
 ```bash
 # JSON summary for entire project (with per-file details and issues)
-vallm batch . --recursive --format json > validation-summary.json
+vallm batch . --recursive --output json > validation-summary.json
 
 # YAML summary for src/ directory (with per-file details and issues)
-vallm batch src/ --recursive --format yaml > validation-summary.yaml
+vallm batch src/ --recursive --output yaml > validation-summary.yaml
 
 # TOON format (compact, human-readable) with per-file details
-vallm batch . --recursive --format toon > validation-summary.toon
+vallm batch . --recursive --output toon > validation-summary.toon
 
 # Text format with security checks
-vallm batch . --recursive --format text --security > validation-report.txt
+vallm batch . --recursive --output text --security > validation-report.txt
 
 # Full validation with semantic review - save to file
-vallm batch . --recursive --semantic --model qwen2.5-coder:7b --format json > full-validation.json
+vallm batch . --recursive --semantic --model qwen2.5-coder:7b --output json > full-validation.json
 
 # Tee output to both console and file
-vallm batch . --recursive --format json | tee validation-summary.json
+vallm batch . --recursive --output json | tee validation-summary.json
 ```
 
 **Output Structure (JSON/YAML/TOON formats now include per-file details):**

VERSION

@@ -1 +1 @@
-0.1.16
+0.1.17

docs/README.md

@@ -151,31 +151,31 @@ Content outside the markers is preserved when regenerating. Enable this with `sy
 
 ```
 vallm/
-    ├── bump_version        ├── cli/├── examples/        ├── hookspecs    ├── vallm/        ├── __main__            ├── base            ├── logical            ├── complexity        ├── validators/            ├── security            ├── semantic_cache            ├── syntax            ├── lint            ├── semantic            ├── imports/            ├── graph_diff        ├── core/            ├── ast_compare            ├── proposal            ├── gitignore        ├── scoring            ├── output_formatters            ├── batch_processor            ├── languages        ├── sandbox/                ├── base                ├── javascript_imports                ├── python_imports                ├── go_imports                ├── c_imports                ├── rust_imports                ├── utils                ├── wrapper                ├── factory                ├── java_imports        ├── main_template        ├── main        ├── main        ├── claude_autonomous_demo        ├── main        ├── ollama_simple_demo        ├── iteration_1        ├── best_version        ├── iteration_2        ├── main        ├── main        ├── main        ├── main_template        ├── main        ├── main        ├── refactored_output        ├── mcp_demo            ├── runner    ├── utils/        ├── save_analysis_data        ├── extraction        ├── extract_code_from_response        ├── logging_utils        ├── validation_runner            ├── order_processor        ├── main            ├── simple_buggy            ├── load_config        ├── utils/            ├── process_user_input            ├── calculate_total            ├── main            ├── save_data├── project    ├── run        ├── run        ├── docker-entrypoint        ├── run        ├── docker-entrypoint        ├── run        ├── docker-entrypoint            ├── data_processor        ├── config            ├── command_handlers```
+        ├── hookspecs        ├── cli/    ├── bump_version    ├── vallm/        ├── __main__├── examples/            ├── complexity            ├── logical            ├── security            ├── base        ├── validators/            ├── semantic_cache            ├── syntax            ├── lint            ├── imports/            ├── semantic            ├── graph_diff        ├── core/        ├── scoring            ├── gitignore            ├── languages            ├── output_formatters            ├── ast_compare            ├── batch_processor            ├── proposal        ├── sandbox/                ├── base                ├── javascript_imports                ├── python_imports                ├── go_imports                ├── c_imports                ├── rust_imports                ├── utils                ├── wrapper                ├── factory                ├── java_imports        ├── main_template        ├── main        ├── main        ├── claude_autonomous_demo        ├── main        ├── ollama_simple_demo        ├── iteration_1        ├── best_version        ├── iteration_2        ├── main        ├── main        ├── main        ├── main_template        ├── main        ├── main            ├── runner        ├── refactored_output    ├── utils/        ├── extraction        ├── save_analysis_data        ├── mcp_demo        ├── extract_code_from_response        ├── validation_runner        ├── logging_utils            ├── order_processor        ├── main            ├── process_user_input            ├── load_config        ├── utils/            ├── simple_buggy            ├── calculate_total            ├── main            ├── save_data├── project    ├── run        ├── run        ├── docker-entrypoint        ├── run        ├── docker-entrypoint        ├── run        ├── docker-entrypoint            ├── data_processor            ├── command_handlers        ├── config```
 
 ## API Overview
 
 ### Classes
 
 - **`VallmSpec`** — Hook specifications that validators must implement.
-- **`BaseValidator`** — Base class for all vallm validators.
-- **`LogicalErrorValidator`** — Validator for logical errors using pyflakes.
 - **`ComplexityValidator`** — Tier 2: Cyclomatic complexity, maintainability index, and function metrics.
+- **`LogicalErrorValidator`** — Validator for logical errors using pyflakes.
 - **`SecurityValidator`** — Tier 2: Security analysis using built-in patterns and optionally bandit.
+- **`BaseValidator`** — Base class for all vallm validators.
 - **`SemanticCache`** — Cache for semantic validation results to improve performance.
 - **`SyntaxValidator`** — Tier 1: Fast syntax validation.
 - **`LintValidator`** — Validator for linting issues using ruff.
 - **`SemanticValidator`** — Tier 3: LLM-as-judge semantic code review.
 - **`GraphDiffResult`** — Result of comparing two code graphs.
-- **`Proposal`** — A code proposal to be validated.
-- **`GitignoreParser`** — Parse .gitignore files and match paths against patterns.
 - **`Verdict`** — —
 - **`Severity`** — —
 - **`Issue`** — A single issue found during validation.
 - **`ValidationResult`** — Result from a single validator.
 - **`PipelineResult`** — Aggregated result from all validators.
-- **`BatchProcessor`** — Handles batch validation of multiple files.
+- **`GitignoreParser`** — Parse .gitignore files and match paths against patterns.
 - **`Language`** — Supported programming languages with their tree-sitter identifiers.
+- **`BatchProcessor`** — Handles batch validation of multiple files.
+- **`Proposal`** — A code proposal to be validated.
 - **`BaseImportValidator`** — Base class for all import validators.
 - **`JavaScriptImportValidator`** — JavaScript/TypeScript import validator.
 - **`PythonImportValidator`** — Python-specific import validator.
@@ -187,10 +187,10 @@ vallm/
 - **`JavaImportValidator`** — Java import validator.
 - **`Colors`** — —
 - **`Colors`** — —
-- **`OrderManager`** — Class with single responsibility - adheres to SOLID principles.
-- **`Colors`** — —
 - **`ExecutionResult`** — Result of sandboxed code execution.
 - **`SandboxRunner`** — Unified interface for running code in a sandbox.
+- **`OrderManager`** — Class with single responsibility - adheres to SOLID principles.
+- **`Colors`** — —
 - **`Colors`** — ANSI color codes for terminal output.
 - **`OrderManager`** — Class with mixed responsibilities - SOLID violation.
 - **`BadClass`** — Class with multiple issues.
@@ -208,19 +208,14 @@ vallm/
 - `create_validator(settings)` — Factory function for LintValidator.
 - `diff_graphs(before, after)` — Compare two CodeGraphs and return the diff.
 - `diff_python_code(before_code, after_code)` — Convenience function: build graphs from code strings and diff them.
-- `parse_code(code, language)` — Parse code using tree-sitter and return the tree.
-- `parse_python_ast(code)` — Parse Python code using the built-in ast module. Returns None on failure.
-- `normalize_python_ast(tree)` — Normalize a Python AST by replacing identifiers with canonical names.
-- `python_ast_similarity(code1, code2)` — Compute structural similarity between two Python code snippets.
-- `tree_sitter_node_count(code, language)` — Count the number of nodes in a tree-sitter parse tree.
-- `tree_sitter_error_count(code, language)` — Count syntax errors reported by tree-sitter.
-- `structural_diff_summary(code1, code2, language)` — Return a summary of structural differences between two code snippets.
+- `compute_verdict(results, settings)` — Compute the aggregate verdict from a list of validation results.
+- `validate(proposal, settings, validators, context)` — Run the full validation pipeline on a proposal.
 - `load_gitignore(path)` — Load .gitignore from a directory.
 - `get_default_excludes()` — Get default exclude patterns used when no .gitignore exists.
 - `create_default_gitignore_parser()` — Create a parser with default exclude patterns.
 - `should_exclude(path, gitignore_parser, use_defaults)` — Check if a path should be excluded.
-- `compute_verdict(results, settings)` — Compute the aggregate verdict from a list of validation results.
-- `validate(proposal, settings, validators, context)` — Run the full validation pipeline on a proposal.
+- `detect_language(source)` — Auto-detect language from file path, extension, or name.
+- `get_language_for_validation(source, explicit)` — Get tree-sitter language ID for validation.
 - `output_validate_result(result, output_format, verbose)` — Output validation result in the specified format.
 - `output_batch_results(results_by_language, filtered_files, passed_count, failed_files)` — Output batch validation results in the specified format.
 - `output_batch_empty(output_format)` — Output empty results.
@@ -234,8 +229,13 @@ vallm/
 - `output_batch_toon(results_by_language, filtered_files, passed_count, failed_files)` — Output TOON format batch summary with detailed per-file results.
 - `print_summary_header()` — Print summary header for batch results.
 - `build_results_table(results_by_language)` — Build results table for rich output.
-- `detect_language(source)` — Auto-detect language from file path, extension, or name.
-- `get_language_for_validation(source, explicit)` — Get tree-sitter language ID for validation.
+- `parse_code(code, language)` — Parse code using tree-sitter and return the tree.
+- `parse_python_ast(code)` — Parse Python code using the built-in ast module. Returns None on failure.
+- `normalize_python_ast(tree)` — Normalize a Python AST by replacing identifiers with canonical names.
+- `python_ast_similarity(code1, code2)` — Compute structural similarity between two Python code snippets.
+- `tree_sitter_node_count(code, language)` — Count the number of nodes in a tree-sitter parse tree.
+- `tree_sitter_error_count(code, language)` — Count syntax errors reported by tree-sitter.
+- `structural_diff_summary(code1, code2, language)` — Return a summary of structural differences between two code snippets.
 - `walk(root, project_root, gitignore_matcher, skip_tests)` — Walk directory tree yielding Python files.
 - `validate_import_path(import_path, source_file, project_root, known_modules)` — Validate if an import path is resolvable.
 - `main()` — —
@@ -297,6 +297,13 @@ vallm/
 - `save_data(data, filename)` — Save data safely using json.dump.
 - `process_order(data)` — Process order data with proper error handling and validation.
 - `main()` — —
+- `save_analysis_data(example_name, result_data)` — Save analysis data to .vallm folder.
+- `run_validation_examples(example_name, good_code, bad_code, complex_code)` — Run standard validation examples (good, bad, complex code).
+- `validate_code_example(name, code, settings, all_results)` — Validate a code example and store results.
+- `print_summary(all_results)` — Print summary of all validation results.
+- `extract_code_from_response(response, language)` — Extract code from LLM response.
+- `extract_json_from_response(response)` — Extract JSON object from LLM response.
+- `save_analysis_data(example_name, result_data)` — Save analysis data to JSON file.
 - `log_section(title)` — Print a section header.
 - `log_step(step, description)` — Print a step.
 - `log_code(label, code, max_lines)` — Log code with label.
@@ -306,19 +313,12 @@ vallm/
 - `generate_refactoring_prompt(code, analysis)` — Generate prompt for LLM to refactor code.
 - `run_mcp_workflow(code_path, max_iterations)` — Run the complete MCP workflow.
 - `main()` — Main entry point.
-- `save_analysis_data(example_name, result_data)` — Save analysis data to .vallm folder.
-- `run_validation_examples(example_name, good_code, bad_code, complex_code)` — Run standard validation examples (good, bad, complex code).
-- `validate_code_example(name, code, settings, all_results)` — Validate a code example and store results.
-- `print_summary(all_results)` — Print summary of all validation results.
-- `save_analysis_data(example_name, result_data)` — Save analysis data to JSON file.
-- `extract_code_from_response(response, language)` — Extract code from LLM response.
-- `extract_json_from_response(response)` — Extract JSON object from LLM response.
 - `extract_code_from_response(response)` — Extract Python code from LLM response.
+- `run_validation_examples(example_name, good_code, bad_code, complex_code)` — Run standard validation examples (good, bad, complex code).
 - `log_section(title)` — Print a section header.
 - `log_step(step, description)` — Print a step indicator.
 - `log_code(label, code, max_lines)` — Log code with label and truncation.
 - `log_result(status, message)` — Log a result with appropriate color.
-- `run_validation_examples(example_name, good_code, bad_code, complex_code)` — Run standard validation examples (good, bad, complex code).
 - `process_order(data)` — Process order data - has multiple issues.
 - `load_config()` — Load config - security issue with eval.
 - `save_data(data, filename)` — Save data - uses pickle without validation.
@@ -332,15 +332,15 @@ vallm/
 - `validate_with_vallm(project_path)` — Validate all Python files with vallm.
 - `generate_report(code2llm_result, vallm_result, output_path)` — Generate combined analysis report.
 - `main()` — Main example function.
+- `process_user_input(user_input)` — Process user input with standard logic.
+- `load_config()` — Load configuration with default values.
 - `process_user_input(user_input)` — Process user input with security issues.
 - `load_config()` — Load configuration with eval.
 - `save_data(data, filename)` — Save data without validation.
 - `calculate_total(items)` — Calculate total with no error handling.
 - `duplicate_function()` — Another duplicate function.
 - `unused_function()` — This function is never used.
 - `main()` — Main function with problems.
-- `load_config()` — Load configuration with default values.
-- `process_user_input(user_input)` — Process user input with standard logic.
 - `calculate_total(items)` — Calculate total price from items list.
 - `run_demo_main()` — Run the standard demo main function pattern.
 - `save_data(data, filename)` — Save data to JSON file.

project.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 clear
+.venv/bin/pip install -e .
 .venv/bin/pip install redup --upgrade
 .venv/bin/pip install glon --upgrade
 .venv/bin/pip install goal --upgrade
@@ -15,4 +16,6 @@ rm project/analysis.yaml
 .venv/bin/code2docs ./ --readme-only
 .venv/bin/redup scan . --format toon --output ./project
 #  --parallel --functions-only --incremental --min-lines 5
-#.venv/bin/redup scan . --format toon --output ./project --parallel --incremental --functions-only
+#.venv/bin/redup scan . --format toon --output ./project --parallel --incremental --functions-only
+.venv/bin/vallm batch . --recursive --output toon > ./project/validation.toon
+#.venv/bin/vallm batch . --recursive --no-imports --no-complexity

project/README.md

@@ -10,7 +10,7 @@ When you run `code2llm ./ -f all`, the following files are created:
 
 | File | Format | Purpose | Key Insights |
 |------|--------|---------|--------------|
-| `analysis.toon` | **TOON** | **🔥 Health diagnostics** - Complexity, god modules, coupling | 7 critical functions, 0 god modules |
+| `analysis.toon` | **TOON** | **🔥 Health diagnostics** - Complexity, god modules, coupling | 8 critical functions, 0 god modules |
 | `evolution.toon` | **TOON** | **📋 Refactoring queue** - Prioritized improvements | 0 refactoring actions needed |
 | `flow.toon` | **TOON** | **🔄 Data flow analysis** - Pipelines, contracts, types | Data dependencies and side effects |
 | `map.toon` | **TOON** | **🗺️ Structural map** - Modules, imports, signatures | Project architecture overview |