refactor(docs): code analysis engine

changes:
  - file: formats.py
    area: cli
    modified: [_export_simple_formats, _export_evolution]
  - file: prompt.py
    area: cli
    modified: [_build_prompt_footer, _analyze_generated_files, _build_dynamic_focus_areas, _build_subprojects_section, _build_dynamic_tasks]
  - file: cli_parser.py
    area: analyzer
    modified: [create_parser]
  - file: evolution_exporter.py
    area: core
    added: [export_to_yaml]
    modified: [EvolutionExporter]
  - file: map_exporter.py
    area: core
    added: [export_to_yaml]
    modified: [MapExporter]
  - file: readme_exporter.py
    area: docs
    modified: [_get_existing_files, _build_core_files_section, _extract_insights, _generate_readme_content, READMEExporter]

stats:
  lines: "+1328/-416 (net +912)"
  files: 24
  complexity: "Large structural change (normalized)"

Author: tom-sapletta-com

CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [Unreleased]
 
+## [0.5.68] - 2026-03-25
+
+### Docs
+- Update project/README.md
+- Update project/context.md
+
+### Other
+- Update code2llm/cli_exports/formats.py
+- Update code2llm/cli_exports/prompt.py
+- Update code2llm/cli_parser.py
+- Update code2llm/exporters/__init__.py
+- Update code2llm/exporters/evolution_exporter.py
+- Update code2llm/exporters/flow_exporter.py
+- Update code2llm/exporters/map_exporter.py
+- Update code2llm/exporters/readme_exporter.py
+- Update code2llm/exporters/toon/metrics.py
+- Update code2llm/exporters/toon/module_detail.py
+- ... and 12 more files
+
 ## [0.5.67] - 2026-03-25
 
 ### Other

VERSION

@@ -1 +1 @@
-0.5.67
+0.5.68

code2llm/__init__.py

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

code2llm/cli_exports/formats.py

@@ -5,7 +5,7 @@
 from pathlib import Path
 from typing import Optional
 
-from ..exporters import (
+from code2llm.exporters import (
     YAMLExporter, JSONExporter, MermaidExporter,
     ContextExporter, ToonExporter, MapExporter, FlowExporter,
     EvolutionExporter, READMEExporter, ProjectYAMLExporter,
@@ -16,14 +16,14 @@
 
 
 def _export_evolution(args, result, output_dir: Path):
-    """Export evolution.toon format."""
+    """Export evolution.toon.yaml format."""
     if 'evolution' not in [f.strip() for f in args.format.split(',')] and 'all' not in [f.strip() for f in args.format.split(',')]:
         return
     exporter = EvolutionExporter()
-    filepath = output_dir / 'evolution.toon'
-    exporter.export(result, str(filepath))
+    filepath = output_dir / 'evolution.toon.yaml'
+    exporter.export_to_yaml(result, str(filepath))
     if args.verbose:
-        print(f"  - EVOLUTION (refactoring queue): {filepath}")
+        print(f"  - EVOLUTION-YAML (refactoring queue): {filepath}")
 
 
 def _export_data_structures(args, result, output_dir: Path):
@@ -101,16 +101,16 @@ def _export_simple_formats(args, result, output_dir: Path, formats):
     """Export toon, map, flow, context, yaml, json, project-yaml formats."""
     format_map = {
         'toon': (ToonExporter, 'analysis.toon.yaml', 'TOON-YAML (diagnostics)'),
-        'map': (MapExporter, 'map.toon', 'MAP (structure + header)'),
+        'map': (MapExporter, 'map.toon.yaml', 'MAP-YAML (structure)'),
         'flow': (FlowExporter, 'flow.toon', 'FLOW (data-flow)'),
         'context': (ContextExporter, 'context.md', 'CONTEXT (LLM narrative)'),
     }
 
     for fmt, (exporter_cls, filename, label) in format_map.items():
         if fmt in formats:
             exporter = exporter_cls()
-            # For toon format, export as YAML (analysis.toon.yaml)
-            if fmt == 'toon':
+            # For toon and map formats, export as YAML
+            if fmt in ('toon', 'map'):
                 filepath = output_dir / filename
                 exporter.export_to_yaml(result, str(filepath))
                 if args.verbose:

code2llm/cli_exports/prompt.py

@@ -78,9 +78,9 @@ def _get_prompt_paths(source_path: Optional[Path], output_dir: Path) -> Tuple[st
 
 _MAIN_FILES = [
     ('analysis.toon', 'Health diagnostics - complexity metrics, god modules, coupling issues, refactoring priorities'),
-    ('map.toon', 'Structural map - files, sizes, imports, exports, signatures, project header'),
+    ('map.toon.yaml', 'Structural map - files, sizes, imports, exports, signatures, project header'),
     ('context.md', 'LLM narrative - architecture summary, key entry points, process flows, public API surface'),
-    ('evolution.toon', 'Refactoring queue - ranked actions by impact/effort, risks, metrics targets, history'),
+    ('evolution.toon.yaml', 'Refactoring queue - ranked actions by impact/effort, risks, metrics targets, history'),
     ('README.md', 'Documentation - complete guide to all generated files, usage examples, interpretation'),
 ]
 
@@ -139,7 +139,7 @@ def _build_subprojects_section(subprojects: list, output_dir: Path, output_rel_p
         level_name = {0: 'root', 1: 'L1', 2: 'L2', 3: 'chunk'}.get(sp.level, f'L{sp.level}')
         sp_files = []
         total_size = 0
-        for f in ['analysis.toon', 'context.md', 'evolution.toon']:
+        for f in ['analysis.toon', 'context.md', 'evolution.toon.yaml']:
             f_path = sp_dir / f
             if f_path.exists():
                 size = f_path.stat().st_size
@@ -169,9 +169,9 @@ def _analyze_generated_files(output_dir: Path, subprojects: list = None) -> dict
     """Analyze which files were generated and determine appropriate focus areas."""
     analysis = {
         'has_analysis_toon': (output_dir / 'analysis.toon').exists(),
-        'has_map_toon': (output_dir / 'map.toon').exists(),
+        'has_map_toon': (output_dir / 'map.toon.yaml').exists(),
         'has_context_md': (output_dir / 'context.md').exists(),
-        'has_evolution_toon': (output_dir / 'evolution.toon').exists(),
+        'has_evolution_toon': (output_dir / 'evolution.toon.yaml').exists(),
         'has_readme': (output_dir / 'README.md').exists(),
         'has_yaml': (output_dir / 'analysis.yaml').exists(),
         'has_json': (output_dir / 'analysis.json').exists(),
@@ -196,10 +196,10 @@ def _build_dynamic_focus_areas(file_analysis: dict) -> List[str]:
         focus_areas.append("1. **Code Health Analysis** - Review complexity metrics, god modules, coupling issues from analysis.toon")
 
     if file_analysis['has_map_toon']:
-        focus_areas.append("2. **Structural Map** - Use map.toon to inspect imports, exports, signatures, and the project header")
+        focus_areas.append("2. **Structural Map** - Use map.toon.yaml to inspect imports, exports, signatures, and the project header")
 
     if file_analysis['has_evolution_toon']:
-        focus_areas.append("3. **Refactoring Priorities** - Examine ranked refactoring actions and risk assessment from evolution.toon")
+        focus_areas.append("3. **Refactoring Priorities** - Examine ranked refactoring actions and risk assessment from evolution.toon.yaml")
 
     if file_analysis['has_context_md']:
         focus_areas.append("4. **Architecture Overview** - Understand main flows, entry points, and public API from context.md")
@@ -231,10 +231,10 @@ def _build_dynamic_tasks(file_analysis: dict) -> List[str]:
         tasks.append("- Highlight critical functions (CC ≥ 10) and top problem areas from analysis.toon.")
 
     if file_analysis['has_map_toon']:
-        tasks.append("- Cross-check imports, exports, and signatures against map.toon before proposing splits.")
+        tasks.append("- Cross-check imports, exports, and signatures against map.toon.yaml before proposing splits.")
 
     if file_analysis['has_evolution_toon']:
-        tasks.append("- Prioritize refactoring actions by impact/effort ratio from evolution.toon.")
+        tasks.append("- Prioritize refactoring actions by impact/effort ratio from evolution.toon.yaml.")
 
     if file_analysis['has_context_md']:
         tasks.append("- Validate entry points and public API surface match the architecture described.")
@@ -271,9 +271,9 @@ def _build_prompt_footer(chunked: bool = False, file_analysis: dict = None) -> L
         lines.append("")
         lines.append("Analysis Strategy:")
         if file_analysis['has_analysis_toon'] and file_analysis['has_map_toon']:
-            lines.append("- Start with analysis.toon for health metrics, then map.toon for structure and signatures")
+            lines.append("- Start with analysis.toon for health metrics, then map.toon.yaml for structure and signatures")
             if file_analysis['has_evolution_toon']:
-                lines.append("- Finish with evolution.toon for action priorities and next steps")
+                lines.append("- Finish with evolution.toon.yaml for action priorities and next steps")
         elif file_analysis['has_context_md']:
             lines.append("- Use context.md as the primary reference for architectural understanding")
 

code2llm/cli_parser.py

@@ -34,16 +34,16 @@ def create_parser() -> argparse.ArgumentParser:
 
 Format Options (-f):
   toon         — Health diagnostics (analysis.toon) [default]
-  map          — Structural map (map.toon) — modules, imports, exports, signatures, project header
-  evolution    — Refactoring queue (evolution.toon)
+  map          — Structural map (map.toon.yaml) — modules, imports, exports, signatures, project header
+  evolution    — Refactoring queue (evolution.toon.yaml)
   context      — LLM narrative (context.md) — architecture summary
   yaml         — Standard YAML format
   json         — Machine-readable JSON
   mermaid      — Flowchart diagrams (flow.mmd, calls.mmd, compact_flow.mmd)
   flow         — Data-flow analysis (flow.toon) — legacy, explicit opt-in
   code2logic   — Generate project logic (legacy project.toon) via external code2logic
   project-yaml — Unified project.yaml (single source of truth) + generated views
-  all          — Generate core formats (analysis.toon, map.toon, evolution.toon, context, yaml, json, mermaid)
+  all          — Generate core formats (analysis.toon, map.toon.yaml, evolution.toon.yaml, context, yaml, json, mermaid)
 
 Strategy Options (--strategy):
   quick     — Fast overview, fewer files analyzed

code2llm/exporters/__init__.py

@@ -1,12 +1,12 @@
 """Exporters package for code2llm.
 
 Available exporters:
-  - ToonExporter      → analysis.toon  (health diagnostics)
-  - MapExporter       → map.toon       (structural map + project header)
-  - FlowExporter      → flow.toon      (data-flow: pipelines, contracts, types)
-  - EvolutionExporter  → evolution.toon (ranked refactoring queue)
-  - ContextExporter   → context.md     (LLM narrative)
-  - READMEExporter    → README.md      (documentation of all files)
+  - ToonExporter      → analysis.toon       (health diagnostics)
+  - MapExporter       → map.toon.yaml       (structural map + project header)
+  - FlowExporter      → flow.toon           (data-flow: pipelines, contracts, types)
+  - EvolutionExporter → evolution.toon.yaml (ranked refactoring queue)
+  - ContextExporter   → context.md          (LLM narrative)
+  - READMEExporter    → README.md           (documentation of all files)
   - YAMLExporter      → analysis.yaml
   - JSONExporter      → analysis.json
   - MermaidExporter   → *.mmd

code2llm/exporters/evolution_exporter.py

@@ -1,12 +1,13 @@
 """Evolution Exporter — prioritized refactoring queue for iterative improvement.
 
-Generates evolution.toon with:
+Generates evolution.toon.yaml with:
   NEXT[N]         — ranked refactoring actions (impact × effort)
   RISKS[N]        — breaking changes and compatibility notes
   METRICS-TARGET  — measurable goals vs current baseline
-  HISTORY         — comparison with previous evolution.toon
+  HISTORY         — comparison with previous evolution.toon.yaml
 """
 
+import yaml
 from collections import defaultdict
 from datetime import datetime
 from pathlib import Path
@@ -24,7 +25,7 @@
 
 
 class EvolutionExporter(Exporter):
-    """Export evolution.toon — prioritized refactoring queue."""
+    """Export evolution.toon.yaml — prioritized refactoring queue."""
 
     # Exclude patterns (mirrors ToonExporter)
     EXCLUDE_PATTERNS = {
@@ -65,6 +66,94 @@ def export(self, result: AnalysisResult, output_path: str, **kwargs) -> None:
         with open(output_path, "w", encoding="utf-8") as f:
             f.write("\n".join(sections) + "\n")
 
+    def export_to_yaml(self, result: AnalysisResult, output_path: str, **kwargs) -> None:
+        """Generate evolution.toon.yaml (structured YAML)."""
+        ctx = self._build_context(result)
+
+        # Build refactoring actions
+        actions = []
+        for gm in ctx["god_modules"][:3]:
+            actions.append({
+                "priority": "high",
+                "action": "SPLIT",
+                "target": gm["file"],
+                "reason": f"{gm['lines']}L, {gm['classes']} classes, max CC={gm['max_cc']}",
+                "effort": "~4h",
+            })
+
+        for f in ctx["funcs"][:20]:
+            if f["cc"] >= CC_SPLIT_THRESHOLD:
+                actions.append({
+                    "priority": "critical" if f["cc"] >= 25 else "high",
+                    "action": "SPLIT-FUNC",
+                    "target": f"{f['class_name']}.{f['name']}" if f["class_name"] else f["name"],
+                    "cc": f["cc"],
+                    "fan_out": f["fan_out"],
+                    "reason": f"CC={f['cc']} exceeds {CC_SPLIT_THRESHOLD}",
+                    "effort": "~1h",
+                })
+
+        for ht in ctx["hub_types"][:3]:
+            if ht["consumers"] >= 20:
+                actions.append({
+                    "priority": "medium",
+                    "action": "INTERFACE-SPLIT",
+                    "target": ht["type"],
+                    "consumers": ht["consumers"],
+                    "reason": f"Hub type with {ht['consumers']} consumers",
+                    "effort": "~6h",
+                })
+
+        actions.sort(key=lambda x: x.get("priority", "") == "critical", reverse=True)
+
+        # Build risks
+        risks = []
+        for gm in ctx["god_modules"][:3]:
+            risks.append({
+                "type": "breaking_imports",
+                "target": gm["file"],
+                "impact": f"may break {gm['funcs']} import paths",
+            })
+        for ht in ctx["hub_types"][:2]:
+            if ht["consumers"] >= 20:
+                risks.append({
+                    "type": "api_change",
+                    "target": ht["type"],
+                    "impact": f"changes API for {ht['consumers']} consumers",
+                })
+
+        data = {
+            "format": "evolution-toon-yaml",
+            "timestamp": ctx["timestamp"],
+            "stats": {
+                "total_funcs": ctx["total_funcs"],
+                "total_files": ctx["total_files"],
+                "avg_cc": ctx["avg_cc"],
+                "max_cc": ctx["max_cc"],
+                "high_cc_count": ctx["high_cc_count"],
+                "critical_count": ctx["critical_count"],
+            },
+            "refactoring": {
+                "action_count": len(actions),
+                "actions": actions[:10],
+            },
+            "risks": {
+                "count": len(risks),
+                "items": risks,
+            },
+            "metrics_target": {
+                "avg_cc": {"current": ctx["avg_cc"], "target": round(min(ctx["avg_cc"] * 0.7, 5.0), 1)},
+                "max_cc": {"current": ctx["max_cc"], "target": min(ctx["max_cc"] // 2, 20)},
+                "god_modules": {"current": len(ctx["god_modules"]), "target": 0},
+                "high_cc": {"current": ctx["high_cc_count"], "target": max(ctx["high_cc_count"] // 2, 0)},
+                "hub_types": {"current": len(ctx["hub_types"]), "target": max(len(ctx["hub_types"]) - 2, 0)},
+            },
+        }
+
+        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "w", encoding="utf-8") as f:
+            yaml.dump(data, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
     # ------------------------------------------------------------------
     # context builder
     # ------------------------------------------------------------------

code2llm/exporters/flow_exporter.py

@@ -19,12 +19,12 @@
 from .base import Exporter
 from .flow_constants import CC_HIGH, FAN_OUT_THRESHOLD, EXCLUDE_PATTERNS, HUB_SPLIT_RECOMMENDATIONS, HUB_TYPE_THRESHOLD
 from .flow_renderer import FlowRenderer
-from ..core.models import (
+from code2llm.core.models import (
     AnalysisResult, FunctionInfo, ClassInfo, ModuleInfo, FlowNode
 )
-from ..analysis.type_inference import TypeInferenceEngine
-from ..analysis.side_effects import SideEffectDetector, SideEffectInfo
-from ..analysis.pipeline_detector import PipelineDetector, Pipeline
+from code2llm.analysis.type_inference import TypeInferenceEngine
+from code2llm.analysis.side_effects import SideEffectDetector, SideEffectInfo
+from code2llm.analysis.pipeline_detector import PipelineDetector, Pipeline
 
 # Thresholds - already imported from flow_constants