refactor(docs): code analysis engine

changes:
  - file: settings_builders.py
    area: cli
    modified: [build_batch_settings]

stats:
  lines: "+620/-1179 (net -559)"
  files: 9
  complexity: "Stable complexity"

Author: tom-sapletta-com

CHANGELOG.md

@@ -124,6 +124,20 @@ 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.49] - 2026-03-23
+
+### Docs
+- Update project/context.md
+
+### Other
+- Update project/analysis.toon
+- Update project/analysis.yaml
+- Update project/dashboard.html
+- Update project/flow.toon
+- Update project/map.toon
+- Update project/project.toon
+- Update project/project.yaml
+
 ## [0.1.48] - 2026-03-23
 
 ### Other

VERSION

@@ -1 +1 @@
-0.1.48
+0.1.49

project/analysis.toon

@@ -5,7 +5,7 @@
 - **Project**: vallm
 - **Language**: python
 - **Files**: 30
-- **Lines**: 7527
+- **Lines**: 7523
 - **Functions**: 175
 - **Classes**: 31
 - **Avg CC**: 3.5

project/analysis.yaml

@@ -67,7 +67,7 @@ <h1>
   <div class="card"><div class="value">175</div><div class="label">Functions</div></div>
   <div class="card"><div class="value">31</div><div class="label">Classes</div></div>
   <div class="card"><div class="value">30</div><div class="label">Files</div></div>
-  <div class="card"><div class="value">7,527</div><div class="label">Lines</div></div>
+  <div class="card"><div class="value">7,523</div><div class="label">Lines</div></div>
   <div class="card"><div class="value">2</div><div class="label">Languages</div></div>
   <div class="card"><div class="value">3.5</div><div class="label">Avg CC</div></div>
   <div class="card"><div class="value">8</div><div class="label">Critical (CC≥10)</div></div>
@@ -96,7 +96,7 @@ <h2 style="border:none;margin:0 0 .5rem;">Evolution (2026-03-23)</h2>
     <div class="evo-cards">
       <div class="card"><div class="value">3.5</div><div class="label">CC̄ ↓</div></div>
       <div class="card"><div class="value">8</div><div class="label">Critical →</div></div>
-      <div class="card"><div class="value">7527</div><div class="label">Lines</div></div>
+      <div class="card"><div class="value">7523</div><div class="label">Lines</div></div>
     </div>
     <p class="trend" style="margin-top:.5rem;">Run analysis multiple times to build a trend chart (≥3 data points needed).</p>
   </div>
@@ -482,7 +482,7 @@ <h2>Refactoring Priorities (3)</h2>
 </div>
 </div>
 
-<footer>Generated by code2llm on 2026-03-23 21:04</footer>
+<footer>Generated by code2llm on 2026-03-23 21:11</footer>
 
 <script>
 // Evolution chart disabled — fewer than 3 data points

project/context.md

@@ -8,20 +8,20 @@ PIPELINES[12] (Analysis:2, Core:3, Export:2, IO:1, NLP:1, Unknown:3):
               → from_path(cls, path:str | Path) → Optional[Language] CC=1    pure ■
               PURITY: 2/4 pure  BOTTLENECK: _check_lizard(CC=12)
 
-  Src [Unknown]: Proposal → Optional[int]
-              → validate(proposal:Proposal, context:dict) → ValidationResult CC=3    cache ▶
-              → _parse_response(response_text:str) → ValidationResult CC=4    IO
-              → _parse_issues(data:dict) → list         CC=3    mutation
-              → _parse_line_number(line) → Optional[int] CC=4    pure ■
-              PURITY: 1/4 pure  BOTTLENECK: _parse_response(CC=4)
-
   Src [Core]: Proposal → ?
               → validate(proposal:Proposal, context:dict) → ValidationResult CC=2    pure ▶
               → _validate_treesitter(code:str, language:str) → tuple[float, list[Issue]] CC=3    mutation
               → tree_sitter_error_count(code:str, language:str) → int CC=1    mutation
               → parse_code(code:str, language:str)      CC=1    pure ■
               PURITY: 2/4 pure  BOTTLENECK: _validate_treesitter(CC=3)
 
+  Src [Unknown]: Proposal → Optional[int]
+              → validate(proposal:Proposal, context:dict) → ValidationResult CC=3    cache ▶
+              → _parse_response(response_text:str) → ValidationResult CC=4    IO
+              → _parse_issues(data:dict) → list         CC=3    mutation
+              → _parse_line_number(line) → Optional[int] CC=4    pure ■
+              PURITY: 1/4 pure  BOTTLENECK: _parse_response(CC=4)
+
   Src [Core]: Path | str → str
               → matches(path:Path | str) → bool         CC=4    pure ▶
               → _match_pattern(rel_path:str, name:str, pattern:str) → bool CC=8    pure
@@ -43,20 +43,20 @@ PIPELINES[12] (Analysis:2, Core:3, Export:2, IO:1, NLP:1, Unknown:3):
               → output_rich(result:ValidationResult, verbose:bool) → None CC=6    IO ■
               PURITY: 2/4 pure  BOTTLENECK: _process_files(CC=26)
 
-  Examples [Unknown]: ? → ?
-              → main()                                  CC=4    IO ▶
-              → run_autonomous_workflow(code_path:Path, max_iterations:int) CC=9    IO
-              → run_runtime_tests(code_path:Path, test_file:Optional[Path]) → Dict CC=8    IO
-              → create_basic_tests(code_path:Path, test_file:Path) CC=7    IO ■
-              PURITY: 0/4 pure  BOTTLENECK: run_autonomous_workflow(CC=9)
-
   Src [Core]: ? → ?
               → main()                                  CC=9    IO ▶
               → diff_python_code(before_code:str, after_code:str) → GraphDiffResult CC=1    pure
               → diff_graphs(before:CodeGraph, after:CodeGraph) → GraphDiffResult CC=5    pure
               → _diff_list(before, after, added:bool)   CC=9    pure ■
               PURITY: 3/4 pure  BOTTLENECK: main(CC=9)
 
+  Examples [Unknown]: ? → ?
+              → main()                                  CC=4    IO ▶
+              → run_autonomous_workflow(code_path:Path, max_iterations:int) CC=9    IO
+              → run_runtime_tests(code_path:Path, test_file:Optional[Path]) → Dict CC=8    IO
+              → create_basic_tests(code_path:Path, test_file:Path) CC=7    IO ■
+              PURITY: 0/4 pure  BOTTLENECK: run_autonomous_workflow(CC=9)
+
   Examples [Unknown]: ? → ?
               → main()                                  CC=5    IO ▶
               → run_simple_workflow(code_path:Path, max_iterations:int) CC=9    IO
@@ -125,27 +125,6 @@ CONTRACTS:
       IN:  cls, path:str | Path
       OUT: Optional[Language]
 
-  Pipeline: Src
-    validate(proposal:Proposal, context:dict) → ValidationResult
-      IN:  proposal:Proposal, context:dict
-      OUT: ValidationResult
-      SIDE-EFFECT: cache(self.cache.get, self.cache.set)
-      INVARIANT: raises on invalid input
-
-    _parse_response(response_text:str) → ValidationResult
-      IN:  response_text:str
-      OUT: ValidationResult
-      SIDE-EFFECT: IO(loads)
-
-    _parse_issues(data:dict) → list
-      IN:  data:dict
-      OUT: list
-      SIDE-EFFECT: pure
-
-    _parse_line_number(line) → Optional[int]
-      IN:  line
-      OUT: Optional[int]
-
   Pipeline: Src
     validate(proposal:Proposal, context:dict) → ValidationResult
       IN:  proposal:Proposal, context:dict
@@ -167,6 +146,27 @@ CONTRACTS:
       IN:  code:str, language:str
       OUT: None
 
+  Pipeline: Src
+    validate(proposal:Proposal, context:dict) → ValidationResult
+      IN:  proposal:Proposal, context:dict
+      OUT: ValidationResult
+      SIDE-EFFECT: cache(self.cache.get, self.cache.set)
+      INVARIANT: raises on invalid input
+
+    _parse_response(response_text:str) → ValidationResult
+      IN:  response_text:str
+      OUT: ValidationResult
+      SIDE-EFFECT: IO(loads)
+
+    _parse_issues(data:dict) → list
+      IN:  data:dict
+      OUT: list
+      SIDE-EFFECT: pure
+
+    _parse_line_number(line) → Optional[int]
+      IN:  line
+      OUT: Optional[int]
+
   Pipeline: Src
     matches(path:Path | str) → bool
       IN:  path:Path | str
@@ -225,6 +225,24 @@ CONTRACTS:
       OUT: None
       SIDE-EFFECT: IO(print, print, print)
 
+  Pipeline: Src
+    main()
+      IN:  ()
+      OUT: None
+      SIDE-EFFECT: IO(print, print, print)
+
+    diff_python_code(before_code:str, after_code:str) → GraphDiffResult
+      IN:  before_code:str, after_code:str
+      OUT: GraphDiffResult
+
+    diff_graphs(before:CodeGraph, after:CodeGraph) → GraphDiffResult
+      IN:  before:CodeGraph, after:CodeGraph
+      OUT: GraphDiffResult
+
+    _diff_list(before, after, added:bool)
+      IN:  before, after, added:bool
+      OUT: None
+
   Pipeline: Examples
     main()
       IN:  ()
@@ -246,24 +264,6 @@ CONTRACTS:
       OUT: None
       SIDE-EFFECT: IO(read_text, write_text, print)
 
-  Pipeline: Src
-    main()
-      IN:  ()
-      OUT: None
-      SIDE-EFFECT: IO(print, print, print)
-
-    diff_python_code(before_code:str, after_code:str) → GraphDiffResult
-      IN:  before_code:str, after_code:str
-      OUT: GraphDiffResult
-
-    diff_graphs(before:CodeGraph, after:CodeGraph) → GraphDiffResult
-      IN:  before:CodeGraph, after:CodeGraph
-      OUT: GraphDiffResult
-
-    _diff_list(before, after, added:bool)
-      IN:  before, after, added:bool
-      OUT: None
-
   Pipeline: Examples
     main()
       IN:  ()
@@ -355,17 +355,17 @@ DATA_TYPES (by cross-function usage) [242 annotated, 0 inferred / 316 functions]
   ValidationResult     consumed:5   produced:18 
   Proposal             consumed:16  produced:1    !! HUB-TYPE → split interface
   str, Any             consumed:6   produced:10 
-  Dict                 consumed:7   produced:6  
   VallmSettings        consumed:11  produced:2    !! HUB-TYPE → split interface
+  Dict                 consumed:7   produced:6  
   list[Path]           consumed:6   produced:2  
   float                consumed:4   produced:4  
   Issue                consumed:1   produced:4  
   Language             consumed:0   produced:4    narrow scope
+  str | Path           consumed:3   produced:0    narrow scope
+  list[Issue]          consumed:0   produced:3    narrow scope
   ExecutionResult      consumed:0   produced:3    narrow scope
   GitignoreParser      consumed:1   produced:2    narrow scope
-  str | Path           consumed:3   produced:0    narrow scope
   list[str]            consumed:2   produced:1    narrow scope
-  list[Issue]          consumed:0   produced:3    narrow scope
 
   HUB TYPES (consumed ≥10):
     str → 186 consumers → split into:
@@ -386,21 +386,21 @@ DATA_TYPES (by cross-function usage) [242 annotated, 0 inferred / 316 functions]
       - (analyze consumers to suggest sub-interfaces)
 
 SIDE_EFFECTS:
-  IO:        main, LogicalErrorValidator._check_pyflakes, SecurityValidator._try_bandit, SemanticCache.__init__, SemanticCache.get, SemanticCache.set, SemanticCache.clear, SemanticValidator._call_http, SemanticValidator._parse_response, LintValidator._check_ruff
+  IO:        main, LogicalErrorValidator._check_pyflakes, SemanticCache.__init__, SemanticCache.get, SemanticCache.set, SemanticCache.clear, SecurityValidator._try_bandit, SemanticValidator._call_http, SemanticValidator._parse_response, LintValidator._check_ruff
   Cache:     SemanticCache.get_cache_stats, get_semantic_cache, clear_semantic_cache, SemanticValidator.__init__, SemanticValidator.validate
-  Mutation:  _initialize_validators, _run_validation_pipeline, _get_default_validators, ComplexityValidator.__init__, ComplexityValidator.validate, ComplexityValidator._check_python_complexity, ComplexityValidator._check_lizard, LogicalErrorValidator.__init__, SecurityValidator.validate, SecurityValidator._check_patterns
+  Mutation:  _initialize_validators, _run_validation_pipeline, _get_default_validators, LogicalErrorValidator.__init__, ComplexityValidator.__init__, ComplexityValidator.validate, ComplexityValidator._check_python_complexity, ComplexityValidator._check_lizard, SecurityValidator.validate, SecurityValidator._check_patterns
   Pure:      bump_version, VallmSpec.validate_proposal, VallmSpec.get_validator_name, VallmSpec.get_validator_tier, Issue.__str__, compute_verdict, validate, _initialize_settings, _initialize_context, BaseValidator.validate
 
   PIPELINE PURITY:
     Src             ██░░ 50% pure
-    Src             █░░░ 25% pure
     Src             ██░░ 50% pure
+    Src             █░░░ 25% pure
     Src             ███░ 75% pure
     Src             ███░ 75% pure
     Src             ██░░ 50% pure
-    Examples        ░░░░ 0% pure
     Src             ███░ 75% pure
     Examples        ░░░░ 0% pure
+    Examples        ░░░░ 0% pure
     Examples        ██░░ 50% pure
     Examples        ░░░░ 0% pure
     Examples        ██░░ 50% pure

project/dashboard.html

@@ -230,13 +230,6 @@ D:
   examples/12_ollama_simple_demo/utils/process_user_input.py:
     e: process_user_input
     process_user_input(user_input)
-  examples/08_code2llm_integration/main.py:
-    e: create_sample_project,analyze_with_code2llm,validate_with_vallm,generate_report,main
-    create_sample_project(base_path)
-    analyze_with_code2llm(project_path)
-    validate_with_vallm(project_path)
-    generate_report(code2llm_result;vallm_result;output_path)
-    main()
   examples/12_ollama_simple_demo/legacy_code/simple_buggy.py:
     e: BadClass,process_user_input,load_config,save_data,calculate_total,duplicate_function,duplicate_function,unused_function,main
     BadClass: __init__(0),process_data(1),another_method(0)  # Class with multiple issues...
@@ -248,6 +241,13 @@ D:
     duplicate_function()
     unused_function()
     main()
+  examples/08_code2llm_integration/main.py:
+    e: create_sample_project,analyze_with_code2llm,validate_with_vallm,generate_report,main
+    create_sample_project(base_path)
+    analyze_with_code2llm(project_path)
+    validate_with_vallm(project_path)
+    generate_report(code2llm_result;vallm_result;output_path)
+    main()
   src/vallm/validators/imports/python_imports.py:
     e: PythonImportValidator
     PythonImportValidator(BaseImportValidator): validate(2),extract_imports(1),module_exists(1),get_language(0),_get_error_message(1),_get_rule_name(0)  # Python-specific import validator...
@@ -315,12 +315,12 @@ D:
   examples/03_security_check/main.py:
     e: main
     main()
-  src/vallm/validators/semantic.py:
-    e: SemanticValidator
-    SemanticValidator(BaseValidator): __init__(1),validate(2),_build_prompt(1),_call_llm(1),_call_ollama(1),_call_litellm(1),_call_http(1),_parse_response(1),_extract_json_from_response(1),_create_parse_error_result(1),_create_json_error_result(1),_parse_scores(1),_parse_issues(1),_parse_severity(1),_parse_line_number(1)  # Tier 3: LLM-as-judge semantic code review...
   src/vallm/validators/syntax.py:
     e: SyntaxValidator
     SyntaxValidator(BaseValidator): validate(2),_validate_python(1),_validate_treesitter(2)  # Tier 1: Fast syntax validation...
+  src/vallm/validators/semantic.py:
+    e: SemanticValidator
+    SemanticValidator(BaseValidator): __init__(1),validate(2),_build_prompt(1),_call_llm(1),_call_ollama(1),_call_litellm(1),_call_http(1),_parse_response(1),_extract_json_from_response(1),_create_parse_error_result(1),_create_json_error_result(1),_parse_scores(1),_parse_issues(1),_parse_severity(1),_parse_line_number(1)  # Tier 3: LLM-as-judge semantic code review...
   src/vallm/core/ast_compare.py:
     e: parse_code,parse_python_ast,normalize_python_ast,python_ast_similarity,tree_sitter_node_count,tree_sitter_error_count,structural_diff_summary
     parse_code(code;language)
@@ -337,15 +337,15 @@ D:
   examples/06_multilang_validation/main.py:
     e: main
     main()
+  src/vallm/config.py:
+    e: VallmSettings
+    VallmSettings(BaseSettings): from_toml(1)  # vallm configuration with layered sources: defaults → TOML → ...
   src/vallm/validators/imports/base.py:
     e: BaseImportValidator
     BaseImportValidator(ABC): validate(2),extract_imports(1),module_exists(1),get_language(0),_get_error_message(1),_get_rule_name(0),create_validation_result(4)  # Base class for all import validators...
   src/vallm/validators/imports/rust_imports.py:
     e: RustImportValidator
     RustImportValidator(BaseImportValidator): get_language(0),_get_error_message(1),_get_rule_name(0),extract_imports(1),module_exists(1)  # Rust import validator...
-  src/vallm/config.py:
-    e: VallmSettings
-    VallmSettings(BaseSettings): from_toml(1)  # vallm configuration with layered sources: defaults → TOML → ...
   examples/utils/extract_code_from_response.py:
     e: extract_code_from_response
     extract_code_from_response(response)
@@ -398,12 +398,12 @@ D:
   examples/12_ollama_simple_demo/utils/load_config.py:
     e: load_config
     load_config()
-  examples/12_ollama_simple_demo/utils/main.py:
-    e: run_demo_main
-    run_demo_main()
   examples/12_ollama_simple_demo/utils/save_data.py:
     e: save_data
     save_data(data;filename)
+  examples/12_ollama_simple_demo/utils/main.py:
+    e: run_demo_main
+    run_demo_main()
   examples/__init__.py:
   src/vallm/cli/__init__.py:
   src/vallm/__init__.py:
@@ -424,15 +424,16 @@ Attributes:
     e: run_example
     run_example()
   examples/11_claude_code_autonomous/docker-entrypoint.sh:
-  examples/12_ollama_simple_demo/run.sh:
-  examples/12_ollama_simple_demo/docker-entrypoint.sh:
   examples/11_claude_code_autonomous/run.sh:
     e: print_section,print_step,print_success,print_warning,print_error
     print_section()
     print_step()
     print_success()
     print_warning()
     print_error()
+  examples/12_ollama_simple_demo/docker-entrypoint.sh:
+  examples/12_ollama_simple_demo/run.sh:
+  examples/10_mcp_ollama_demo/docker-entrypoint.sh:
   examples/10_mcp_ollama_demo/run.sh:
     e: print_section,print_step,print_success,print_warning,print_error,print,print,print,print
     print_section()
@@ -444,4 +445,3 @@ Attributes:
     print()
     print()
     print()
-  examples/10_mcp_ollama_demo/docker-entrypoint.sh: