refactor(docs): code analysis engine

stats:
  lines: "+658/-376 (net +282)"
  files: 20
  complexity: "Stable complexity"

Author: tom-sapletta-com

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+      - name: Run tests with coverage
+        if: matrix.python-version == '3.12'
+        run: pytest tests/ --cov=code2docs --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false

.gitignore

@@ -208,6 +208,9 @@ marimo/_static/
 marimo/_lsp/
 __marimo__/
 
-# code2docs
+# code2docs generated outputs
 .code2docs.state
 .code2docs.api_snapshot.json
+docs/
+examples/
+mkdocs.yml

CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-03-07
+
+### Docs
+- Update project/README.md
+- Update project/context.md
+
+### Other
+- Update .gitignore
+- Update VERSION
+- 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/evolution.toon
+- Update project/flow.mmd
+- ... and 6 more files
+
 ## [0.1.7] - 2026-03-07
 
 ### Test

README.md

@@ -1,6 +1,6 @@
 # code2docs
 
-![version](https://img.shields.io/badge/version-0.1.7-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
+![version](https://img.shields.io/badge/version-0.2.1-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
 
 > Auto-generate and sync project documentation from source code analysis.
 
@@ -140,7 +140,7 @@ code2docs can update only specific sections of an existing README using markers:
 ```markdown
 <!-- code2docs:start --># code2docs
 
-![version](https://img.shields.io/badge/version-0.1.7-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-153-green)
+![version](https://img.shields.io/badge/version-0.2.1-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-153-green)
 > **153** functions | **30** classes | **28** files | CC̄ = 0.0
 
 ## Installation

VERSION

@@ -1 +1 @@
-0.1.7
+0.2.1

code2docs/__init__.py

@@ -5,7 +5,7 @@
 README.md, API references, module docs, examples, and architecture diagrams.
 """
 
-__version__ = "0.1.7"
+__version__ = "0.2.1"
 __author__ = "Tom Sapletta"
 
 from .config import Code2DocsConfig

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 | 12 critical functions, 0 god modules |
+| `analysis.toon` | **TOON** | **🔥 Health diagnostics** - Complexity, god modules, coupling | 16 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 |
@@ -338,8 +338,8 @@ code2llm ./ -f yaml --separate-orphans
 
 **Generated by**: `code2llm ./ -f all --readme`  
 **Analysis Date**: 2026-03-07  
-**Total Functions**: 127  
-**Total Classes**: 25  
-**Modules**: 24  
+**Total Functions**: 154  
+**Total Classes**: 30  
+**Modules**: 31  
 
 For more information about code2llm, visit: https://github.com/tom-sapletta/code2llm

project/analysis.toon

@@ -1,11 +1,13 @@
-# code2llm | 24f 2544L | py:24 | 2026-03-07
-# CC̄=4.2 | critical:12/127 | dups:0 | cycles:1
+# code2llm | 28f 3095L | py:28 | 2026-03-07
+# CC̄=4.4 | critical:16/154 | dups:0 | cycles:1
 
-HEALTH[1]:
+HEALTH[3]:
+  🟡 CC    _render_per_module CC=18 (limit:15)
+  🟡 CC    _run_generate CC=17 (limit:15)
   🟡 CC    _parse_sections CC=15 (limit:15)
 
 REFACTOR[2]:
-  1. split 1 high-CC methods  (CC>15)
+  1. split 3 high-CC methods  (CC>15)
   2. break 1 circular dependencies
 
 COUPLING:
@@ -17,25 +19,29 @@ COUPLING:
   CYCLES: 1
 
 LAYERS:
-  code2docs/                      CC̄=4.2    ←in:0  →out:1
+  code2docs/                      CC̄=4.4    ←in:0  →out:1
+  │ !! cli                        269L  1C   10m  CC=17     ←0
   │ readme_gen                 260L  1C   14m  CC=7      ←0
-  │ !  cli                        229L  1C   10m  CC=13     ←0
   │ !  module_docs_gen            220L  1C   17m  CC=12     ←0
   │ !  examples_gen               198L  1C   12m  CC=12     ←0
+  │ !  api_changelog_gen          196L  2C    9m  CC=14     ←0
   │ !  architecture_gen           192L  1C    6m  CC=12     ←0
   │ !  api_reference_gen          162L  1C   11m  CC=13     ←0
   │ dependency_scanner         159L  3C    6m  CC=8      ←0
   │ config                     158L  5C    2m  CC=7      ←1
+  │ depgraph_gen               140L  1C    9m  CC=9      ←0
   │ differ                     125L  2C    7m  CC=6      ←0
   │ changelog_gen              121L  2C    6m  CC=6      ←0
   │ !! docstring_extractor        119L  2C    6m  CC=15     ←0
   │ endpoint_detector          113L  2C    3m  CC=5      ←0
+  │ !! coverage_gen                85L  1C    5m  CC=18     ←0
+  │ mkdocs_gen                  79L  1C    4m  CC=8      ←0
   │ !  updater                     77L  1C    2m  CC=12     ←0
   │ watcher                     75L  0C    1m  CC=5      ←1
   │ markdown                    73L  1C   13m  CC=4      ←0
   │ toc                         63L  0C    3m  CC=6      ←0
+  │ __init__                    53L  0C    1m  CC=5      ←0
   │ !  badges                      52L  0C    2m  CC=11     ←1
-  │ __init__                    42L  0C    1m  CC=5      ←0
   │ project_scanner             42L  1C    4m  CC=2      ←0
   │ __init__                    32L  0C    1m  CC=4      ←0
   │ __init__                    13L  0C    0m  CC=0.0    ←0
@@ -46,10 +52,12 @@ LAYERS:
 
 DUPLICATES[0]: none
 
-FUNCTIONS (CC≥10, 12 of 127):
+FUNCTIONS (CC≥10, 16 of 154):
+   18.0  CoverageGenerator._render_per_module        4n   2exit  loops+ret  !! split
+   17.0  _run_generate                              33n   2exit  cond+ret  !! split
    15.0  DocstringExtractor._parse_sections         15n   1exit  loops+cond  !! split
+   14.0  ApiChangelogGenerator._render              17n   4exit  loops+cond+ret
    13.0  ApiReferenceGenerator._render_api_classes   14n   3exit  loops+cond+ret
-   13.0  _run_generate                              25n   2exit  cond+ret
    12.0  Updater.apply                              14n   1exit  loops+cond
    12.0  ModuleDocsGenerator._render_classes_section   14n   3exit  loops+cond+ret
    12.0  ExamplesGenerator._generate_class_examples   10n   2exit  loops+cond+ret
@@ -59,63 +67,61 @@ FUNCTIONS (CC≥10, 12 of 127):
    11.0  ArchitectureGenerator._generate_class_diagram   12n   2exit  loops+cond+ret
    10.0  ModuleDocsGenerator._render_dependencies_section   12n   3exit  loops+cond+ret
    10.0  ExamplesGenerator._generate_basic_usage     3n   2exit  ret
+   10.0  ApiChangelogGenerator._diff_functions       9n   1exit  loops+cond
+   10.0  ApiChangelogGenerator._diff_classes        15n   1exit  loops+cond
 
   summary:
-    critical(≥10): 12 | high(5-10): 33 | medium(2-5): 54 | low(<2): 28
-    9% CC≥10  35% CC≥5
+    critical(≥10): 16 | high(5-10): 39 | medium(2-5): 65 | low(<2): 34
+    10% CC≥10  36% CC≥5
 
 HOTSPOTS:
-  #1  _run_generate                        fan=24   "calls 24 functions"
+  #1  _run_generate                        fan=34   "calls 34 functions"
   #2  start_watcher                        fan=22   "calls 22 functions"
   #3  Updater.apply                        fan=20   "Updater method, fan-out=20"
   #4  Code2DocsConfig.from_yaml            fan=15   "Code2DocsConfig method, fan-out=15"
-  #5  ApiReferenceGenerator._render_api_classes  fan=11   "ApiReferenceGenerator method, fan-out=11"
-  #6  ArchitectureGenerator.generate       fan=11   "ArchitectureGenerator method, fan-out=11"
-  #7  DocstringExtractor._parse_sections   fan=11   "DocstringExtractor method, fan-out=11"
-  #8  Differ.detect_changes                fan=10   "Differ method, fan-out=10"
-  #9  init                                 fan=10   "calls 10 functions"
-  #10 EndpointDetector._scan_django_urls   fan=10   "EndpointDetector method, fan-out=10"
+  #5  ApiChangelogGenerator._diff_classes  fan=12   "ApiChangelogGenerator method, fan-out=12"
+  #6  generate_docs                        fan=11   "calls 11 functions"
+  #7  ApiReferenceGenerator._render_api_classes  fan=11   "ApiReferenceGenerator method, fan-out=11"
+  #8  ArchitectureGenerator.generate       fan=11   "ArchitectureGenerator method, fan-out=11"
+  #9  DocstringExtractor._parse_sections   fan=11   "DocstringExtractor method, fan-out=11"
+  #10 Differ.detect_changes                fan=10   "Differ method, fan-out=10"
 
 CLASSES:
   ModuleDocsGenerator            ████████████████████████  17m  CC̄=4.6   max=12  
   MarkdownFormatter              ██████████████████        13m  CC̄=1.2   max=4   
   ReadmeGenerator                ██████████████████        13m  CC̄=3.9   max=7   
   ExamplesGenerator              ████████████████          12m  CC̄=6.0   max=12  
   ApiReferenceGenerator          ███████████████           11m  CC̄=4.0   max=13  
+  DepGraphGenerator              ████████████               9m  CC̄=3.9   max=9   
+  ApiChangelogGenerator          ████████████               9m  CC̄=5.4   max=14  
   Differ                         ████████                   6m  CC̄=4.0   max=6   
   ChangelogGenerator             ████████                   6m  CC̄=3.5   max=6   
   ArchitectureGenerator          ████████                   6m  CC̄=7.8   max=12  
-  DocstringExtractor             ████████                   6m  CC̄=6.2   max=15    !!
   DependencyScanner              ████████                   6m  CC̄=4.5   max=8   
+  DocstringExtractor             ████████                   6m  CC̄=6.2   max=15    !!
+  CoverageGenerator              ███████                    5m  CC̄=6.4   max=18    !!
+  MkDocsGenerator                █████                      4m  CC̄=3.0   max=8   
   ProjectScanner                 ████                       3m  CC̄=1.3   max=2   
   EndpointDetector               ████                       3m  CC̄=4.0   max=5   
   Updater                        ██                         2m  CC̄=7.0   max=12  
   Code2DocsConfig                ██                         2m  CC̄=4.0   max=7   
   ChangeInfo                     █                          1m  CC̄=1.0   max=1   
   DefaultGroup                   █                          1m  CC̄=4.0   max=4   
   ChangelogEntry                                            0m  CC̄=0.0   max=0.0 
+  ApiChange                                                 0m  CC̄=0.0   max=0.0 
   ReadmeConfig                                              0m  CC̄=0.0   max=0.0 
   DocsConfig                                                0m  CC̄=0.0   max=0.0 
   ExamplesConfig                                            0m  CC̄=0.0   max=0.0 
   SyncConfig                                                0m  CC̄=0.0   max=0.0 
-  DocstringInfo                                             0m  CC̄=0.0   max=0.0 
   DependencyInfo                                            0m  CC̄=0.0   max=0.0 
   ProjectDependencies                                       0m  CC̄=0.0   max=0.0 
+  DocstringInfo                                             0m  CC̄=0.0   max=0.0 
   Endpoint                                                  0m  CC̄=0.0   max=0.0 
 
 D:
-  code2docs/analyzers/docstring_extractor.py:
-    e: DocstringInfo,DocstringExtractor
-    DocstringInfo  # Parsed docstring with sections....
-    DocstringExtractor  # Extract and parse docstrings from AnalysisResult....
-      extract_all(1)  CC=5.0
-        → parse(1)  CC=2.0
-        → _extract_summary(0)  CC=2.0
-        → _parse_sections(2)  CC=15.0  !
-        → _classify_section(0)  CC=5.0
-  code2docs/generators/api_reference_gen.py:
-    e: ApiReferenceGenerator
-    ApiReferenceGenerator  # Generate docs/api/ — per-module API reference from signature...
+  code2docs/generators/coverage_gen.py:
+    e: CoverageGenerator
+    CoverageGenerator  # Generate docs/coverage.md — docstring coverage report....
       __init__(2)  CC=1.0
   code2docs/cli.py:
     e: DefaultGroup,main,generate,sync,watch,init,_load_config,_run_generate,_run_sync,_run_watch
@@ -131,6 +137,24 @@ D:
     _run_generate(project_path,config,readme_only,dry_run)
     _run_sync(project_path,config,dry_run)
     _run_watch(project_path,config)
+  code2docs/analyzers/docstring_extractor.py:
+    e: DocstringInfo,DocstringExtractor
+    DocstringInfo  # Parsed docstring with sections....
+    DocstringExtractor  # Extract and parse docstrings from AnalysisResult....
+      extract_all(1)  CC=5.0
+        → parse(1)  CC=2.0
+        → _extract_summary(0)  CC=2.0
+        → _parse_sections(2)  CC=15.0  !
+        → _classify_section(0)  CC=5.0
+  code2docs/generators/api_changelog_gen.py:
+    e: ApiChange,ApiChangelogGenerator
+    ApiChange  # A single API change between two analysis snapshots....
+    ApiChangelogGenerator  # Generate API changelog by diffing current analysis with a sa...
+      __init__(2)  CC=1.0
+  code2docs/generators/api_reference_gen.py:
+    e: ApiReferenceGenerator
+    ApiReferenceGenerator  # Generate docs/api/ — per-module API reference from signature...
+      __init__(2)  CC=1.0
   code2docs/sync/updater.py:
     e: Updater
     Updater  # Apply selective documentation updates based on detected chan...
@@ -151,6 +175,14 @@ D:
     e: generate_badges,_make_badge
     generate_badges(project_name,badge_types,stats,deps)
     _make_badge(badge_type,project_name,stats,deps)
+  code2docs/generators/depgraph_gen.py:
+    e: DepGraphGenerator
+    DepGraphGenerator  # Generate docs/dependency-graph.md with Mermaid diagrams....
+      __init__(2)  CC=1.0
+  code2docs/generators/mkdocs_gen.py:
+    e: MkDocsGenerator
+    MkDocsGenerator  # Generate mkdocs.yml from the docs/ directory structure....
+      __init__(2)  CC=1.0
   code2docs/analyzers/dependency_scanner.py:
     e: DependencyInfo,ProjectDependencies,DependencyScanner
     DependencyInfo  # Information about a project dependency....
@@ -217,7 +249,10 @@ D:
       __init__(1)  CC=2.0
         → _build_llm_config(0)  CC=1.0
     analyze_and_document(project_path,config)
+  examples/entry_points.py:
+  examples/class_examples.py:
   code2docs/__main__.py:
+  examples/basic_usage.py:
   code2docs/sync/__init__.py:
   code2docs/formatters/__init__.py:
   code2docs/analyzers/__init__.py:

project/calls.mmd

@@ -1,22 +1,22 @@
 flowchart LR
     subgraph code2docs_cli
-        code2docs__cli___run_sync["_run_sync"]
         code2docs__cli__watch["watch"]
-        code2docs__cli___run_generate["_run_generate"]
-        code2docs__cli__sync["sync"]
-        code2docs__cli___load_config["_load_config"]
+        code2docs__cli___run_sync["_run_sync"]
         code2docs__cli__generate["generate"]
+        code2docs__cli___load_config["_load_config"]
         code2docs__cli___run_watch["_run_watch"]
+        code2docs__cli__sync["sync"]
+        code2docs__cli___run_generate["_run_generate"]
     end
     subgraph code2docs_config
         code2docs__config__Code2DocsConfig__from_yaml["from_yaml"]
     end
     subgraph code2docs_formatters
+        code2docs__formatters__toc__extract_headings["extract_headings"]
         code2docs__formatters__badges___make_badge["_make_badge"]
+        code2docs__formatters__badges__generate_badges["generate_badges"]
         code2docs__formatters__toc__generate_toc["generate_toc"]
         code2docs__formatters__toc___slugify["_slugify"]
-        code2docs__formatters__badges__generate_badges["generate_badges"]
-        code2docs__formatters__toc__extract_headings["extract_headings"]
     end
     subgraph code2docs_generators
         code2docs___build_context["_build_context"]