feat(docs): code analysis engine

changes:
  - file: formats.py
    area: cli
    added: [_export_calls_toon]
  - file: yaml_exporter.py
    area: core
    added: [_render_edges, _render_hubs, export_calls_toon, _render_calls_header, _render_modules]
    modified: [YAMLExporter]

stats:
  lines: "+4066/-66 (net +4000)"
  files: 8
  complexity: "Large structural change (normalized)"

Author: tom-sapletta-com

CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.5.111] - 2026-04-18
+
+### Docs
+- Update project/README.md
+- Update project/context.md
+
+### Other
+- Update code2llm/cli_exports/formats.py
+- Update code2llm/exporters/yaml_exporter.py
+- Update project/analysis.toon.yaml
+- Update project/calls.yaml
+- Update project/index.html
+
 ## [0.5.110] - 2026-04-18
 
 ### Other

README.md

@@ -3,7 +3,7 @@
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.5.110-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.5.111-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 ![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-53.7h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
 - 🤖 **LLM usage:** $7.5000 (154 commits)

VERSION

@@ -1 +1 @@
-0.5.110
+0.5.111

code2llm/__init__.py

@@ -8,7 +8,7 @@
 and entity resolution with multilingual support.
 """
 
-__version__ = "0.5.110"
+__version__ = "0.5.111"
 __author__ = "STTS Project"
 
 # Core analysis components (lightweight, always needed)

code2llm/cli_exports/formats.py

@@ -225,6 +225,17 @@ def _export_calls(args, result, output_dir: Path):
         print(f"  - CALLS (call graph YAML): {output_dir / 'calls.yaml'}")
 
 
+def _export_calls_toon(args, result, output_dir: Path):
+    """Export calls.toon.yaml (call graph in human-readable toon format).
+    
+    Generates calls.toon.yaml with hubs, modules, and edges sections.
+    """
+    yaml_exporter = YAMLExporter()
+    yaml_exporter.export_calls_toon(result, str(output_dir / 'calls.toon.yaml'))
+    if args.verbose:
+        print(f"  - CALLS (toon format): {output_dir / 'calls.toon.yaml'}")
+
+
 def _export_mermaid(args, result, output_dir: Path):
     """Export Mermaid diagrams + optional PNG generation.
     

code2llm/exporters/yaml_exporter.py

@@ -252,3 +252,75 @@ def _get_cc(fi: FunctionInfo) -> int:
         if isinstance(fi.complexity, dict):
             return fi.complexity.get('cyclomatic_complexity', 0)
         return fi.complexity or 0
+
+    def export_calls_toon(self, result: AnalysisResult, output_path: str, max_calls_per_func: int = 10, max_edges: int = 500) -> None:
+        """Export call graph as toon.yaml format (human-readable).
+
+        Generates a human-readable toon format with:
+        - Header with project stats
+        - HUBS: high-degree functions (many calls in/out)
+        - CHAINS: call chains/paths
+        - MODULES: functions grouped by module with call relationships
+        """
+        connected, edges = self._collect_edges(result, max_calls_per_func, max_edges)
+        nodes = self._build_nodes(result, connected)
+        modules = self._group_by_module(result, connected)
+
+        # Build toon format sections
+        lines = []
+        lines.extend(self._render_calls_header(result, nodes, edges, modules))
+        lines.append("")
+        lines.extend(self._render_hubs(nodes))
+        lines.append("")
+        lines.extend(self._render_modules(modules, nodes, edges))
+        lines.append("")
+        lines.extend(self._render_edges(edges))
+
+        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, 'w', encoding='utf-8') as f:
+            f.write('\n'.join(lines) + '\n')
+
+    def _render_calls_header(self, result: AnalysisResult, nodes: Dict, edges: List, modules: Dict) -> List[str]:
+        """Render header section for calls.toon.yaml."""
+        nfuncs = len(result.functions)
+        all_cc = [self._get_cc(fi) for fi in result.functions.values()]
+        avg_cc = round(sum(all_cc) / len(all_cc), 1) if all_cc else 0.0
+
+        return [
+            f"# code2llm call graph | {result.project_path}",
+            f"# nodes: {len(nodes)} | edges: {len(edges)} | modules: {len(modules)}",
+            f"# CC̄={avg_cc}",
+        ]
+
+    def _render_hubs(self, nodes: Dict) -> List[str]:
+        """Render high-degree hub functions (sorted by total calls)."""
+        hubs = sorted(
+            [(name, data) for name, data in nodes.items()],
+            key=lambda x: x[1]['calls_in'] + x[1]['calls_out'],
+            reverse=True
+        )[:20]
+
+        lines = ['HUBS[20]:']
+        for name, data in hubs:
+            total_calls = data['calls_in'] + data['calls_out']
+            lines.append(f"  {name}")
+            lines.append(f"    CC={data['cyclomatic_complexity']}  in:{data['calls_in']}  out:{data['calls_out']}  total:{total_calls}")
+        return lines
+
+    def _render_modules(self, modules: Dict, nodes: Dict, edges: List) -> List[str]:
+        """Render modules section with functions and call relationships."""
+        lines = ['MODULES:']
+        for module, funcs in sorted(modules.items()):
+            lines.append(f"  {module}  [{len(funcs)} funcs]")
+            for func in funcs[:10]:  # Show up to 10 funcs per module
+                if func in nodes:
+                    data = nodes[func]
+                    lines.append(f"    {data['name']}  CC={data['cyclomatic_complexity']}  out:{data['calls_out']}")
+        return lines
+
+    def _render_edges(self, edges: List) -> List[str]:
+        """Render call edges section."""
+        lines = ['EDGES:']
+        for edge in edges[:50]:  # Show up to 50 edges
+            lines.append(f"  {edge['caller']} → {edge['callee']}")
+        return lines

code2llm/nlp/__init__.py

@@ -4,7 +4,7 @@
 with multilingual support and fuzzy matching.
 """
 
-__version__ = "0.5.110"
+__version__ = "0.5.111"
 
 from .pipeline import NLPPipeline
 from .normalization import QueryNormalizer

project/README.md

@@ -332,7 +332,7 @@ code2llm ./ -f yaml --separate-orphans
 
 **Generated by**: `code2llm ./ -f all --readme`  
 **Analysis Date**: 2026-04-18  
-**Total Functions**: 1014  
+**Total Functions**: 1035  
 **Total Classes**: 111  
 **Modules**: 131  
 

project/analysis.toon.yaml

@@ -1,15 +1,11 @@
-# code2llm | 122f 22773L | python:117,shell:4,java:1 | 2026-04-18
-# CC̄=4.4 | critical:3/1014 | dups:0 | cycles:0
+# code2llm | 122f 22887L | python:117,shell:4,java:1 | 2026-04-18
+# CC̄=4.3 | critical:0/1035 | dups:0 | cycles:0
 
-HEALTH[3]:
-  🟡 CC    export_calls CC=18 (limit:15)
-  🟡 CC    main CC=17 (limit:15)
-  🟡 CC    validate_chunked_output CC=15 (limit:15)
+HEALTH[0]: ok
 
-REFACTOR[1]:
-  1. split 3 high-CC methods  (CC>15)
+REFACTOR[0]: none needed
 
-PIPELINES[673]:
+PIPELINES[683]:
   [1] Src [read_readme]: read_readme
       PURITY: 100% pure
   [2] Src [main]: main → run_analysis
@@ -44,22 +40,22 @@ LAYERS:
   │ analyzer                   355L  1C    9m  CC=14     ←0
   │ entity_resolution          326L  3C   16m  CC=13     ←1
   │ cli_analysis               323L  0C   11m  CC=14     ←1
+  │ formats                    301L  0C   14m  CC=13     ←3
   │ intent_matching            297L  3C   15m  CC=7      ←0
+  │ cli_parser                 295L  0C    2m  CC=2      ←1
   │ side_effects               294L  2C   15m  CC=14     ←0
   │ cfg                        293L  1C   17m  CC=5      ←0
   │ type_inference             290L  1C   17m  CC=9      ←0
-  │ formats                    289L  0C   13m  CC=13     ←3
   │ data_analysis              286L  1C   18m  CC=14     ←0
   │ llm_task                   284L  0C   15m  CC=14     ←0
-  │ cli_parser                 277L  0C    1m  CC=1      ←1
   │ toon_size_manager          265L  0C    8m  CC=10     ←1
   │ mermaid_flow_helpers       262L  0C   12m  CC=10     ←1
+  │ yaml_exporter              254L  1C   19m  CC=8      ←0
+  │ cli_commands               250L  0C   12m  CC=7      ←1
   │ context_exporter           248L  1C   15m  CC=10     ←0
   │ dfg                        224L  1C   12m  CC=7      ←0
-  │ !! cli_commands               220L  0C    6m  CC=15     ←1
   │ call_graph                 211L  1C   13m  CC=9      ←0
   │ config                     210L  6C    0m  CC=0.0    ←0
-  │ !! yaml_exporter              203L  1C   10m  CC=18     ←0
   │ scanner                    201L  1C    6m  CC=14     ←0
   │ refactoring                196L  1C   11m  CC=9      ←0
   │ __init__                   196L  1C   11m  CC=9      ←0
@@ -75,10 +71,10 @@ LAYERS:
   │ module_detail              162L  1C    9m  CC=7      ←0
   │ ts_parser                  158L  1C    9m  CC=7      ←2
   │ toon_view                  157L  1C    9m  CC=6      ←0
+  │ orchestrator               156L  0C    5m  CC=11     ←1
   │ export_pipeline            153L  2C    5m  CC=4      ←0
   │ incremental                150L  1C   10m  CC=4      ←0
   │ prompt_engine              150L  1C    7m  CC=12     ←0
-  │ orchestrator               149L  0C    5m  CC=11     ←1
   │ toon_parser                147L  0C   10m  CC=8      ←1
   │ ruby                       143L  0C    3m  CC=14     ←1
   │ context_view               140L  1C    8m  CC=11     ←0
@@ -125,16 +121,16 @@ LAYERS:
   │ __init__                     0L  0C    0m  CC=0.0    ←0
   │ __init__                     0L  0C    0m  CC=0.0    ←0
   │
-  ./                              CC̄=4.2    ←in:0  →out:0
-  │ !! validate_toon              394L  0C   15m  CC=17     ←0
-  │ setup                       67L  0C    1m  CC=2      ←0
-  │ orchestrator.sh             58L  0C    0m  CC=0.0    ←0
-  │ project.sh                  49L  0C    0m  CC=0.0    ←0
-  │
   scripts/                        CC̄=3.9    ←in:0  →out:0
   │ benchmark_badges           392L  0C    9m  CC=13     ←0
   │ bump_version                96L  0C    7m  CC=4      ←0
   │
+  ./                              CC̄=3.6    ←in:0  →out:0
+  │ validate_toon              390L  0C   19m  CC=7      ←0
+  │ setup                       67L  0C    1m  CC=2      ←0
+  │ orchestrator.sh             58L  0C    0m  CC=0.0    ←0
+  │ project.sh                  49L  0C    0m  CC=0.0    ←0
+  │
   benchmarks/                     CC̄=3.0    ←in:0  →out:1
   │ benchmark_performance      306L  0C    7m  CC=6      ←0
   │ project_generator          233L  0C    6m  CC=1      ←1
@@ -149,11 +145,11 @@ LAYERS:
   │ server                     110L  0C    3m  CC=4      ←0
   │
   demo_langs/                     CC̄=1.5    ←in:0  →out:0
-  │ sample.rs                   47L  1C    5m  CC=2      ←0
-  │ sample.java                 47L  2C    7m  CC=3      ←1
+  │ sample.java                 47L  2C    7m  CC=3      ←2
+  │ sample.rs                   47L  1C    4m  CC=2      ←0
   │ sample.go                   46L  0C    4m  CC=3      ←0
   │ sample.php                  44L  1C    1m  CC=1      ←0
-  │ sample                      40L  1C    4m  CC=3      ←0
+  │ sample                      40L  1C    5m  CC=3      ←0
   │ sample.ts                   26L  1C    1m  CC=1      ←0
   │
   ── zero ──