refactor(docs): code analysis engine

changes:
  - file: _registry_adapters.py
    area: docs
    added: [_generate_html, IndexHtmlAdapter]
    modified: [should_run, run]

stats:
  lines: "+38238/-4561 (net +33677)"
  files: 13
  complexity: "Large structural change (normalized)"

Author: tom-sapletta-com

CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.21] - 2026-03-15
+
+### Docs
+- Update project/context.md
+
+### Test
+- Update tests/project/dashboard.html
+- Update tests/project/project.yaml
+
+### Other
+- Update code2docs/generators/_registry_adapters.py
+- Update project.sh
+- Update project/analysis.json
+- Update project/analysis.toon
+- Update project/analysis.yaml
+- Update project/calls.mmd
+- Update project/dashboard.html
+- Update project/flow.mmd
+- Update project/flow.toon
+- Update project/map.toon
+- ... and 2 more files
+
 ## [3.0.20] - 2026-03-09
 
 ### Docs

README.md

@@ -1,6 +1,6 @@
 # code2docs
 
-![version](https://img.shields.io/badge/version-3.0.20-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-3.0.21-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-3.0.20-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-276-green)
+![version](https://img.shields.io/badge/version-3.0.21-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-276-green)
 > **276** functions | **57** classes | **51** files | CC̄ = 3.8
 
 > Auto-generated project documentation from source code analysis.

VERSION

@@ -1 +1 @@
-3.0.20
+3.0.21

code2docs/__init__.py

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

code2docs/generators/_registry_adapters.py

@@ -250,25 +250,178 @@ def should_run(self, *, readme_only: bool = False) -> bool:
 
     def run(self, ctx: GenerateContext) -> Optional[str]:
         from .org_readme_gen import OrgReadmeGenerator
-        
+
         org_name = getattr(self.config, 'org_name', '')
         if not org_name:
             return None
-            
+
         gen = OrgReadmeGenerator(self.config, str(ctx.project), org_name)
         content = gen.generate()
-        
+
         if ctx.dry_run:
             click.echo(f"\n--- {org_name} README ({len(content)} chars) ---")
             preview = content[:500] + "..." if len(content) > 500 else content
             click.echo(preview)
             return None
-        
+
         readme_path = ctx.docs_dir / "README.md"
         gen.write(str(readme_path), content)
         return f"✅ {readme_path.relative_to(ctx.project)}"
 
 
+class IndexHtmlAdapter(BaseGenerator):
+    """Adapter for generating index.html for GitHub Pages browsing."""
+    name = "index_html"
+
+    def should_run(self, *, readme_only: bool = False) -> bool:
+        return not readme_only
+
+    def run(self, ctx: GenerateContext) -> Optional[str]:
+        if ctx.dry_run:
+            return "[dry-run] docs/index.html"
+
+        content = self._generate_html(ctx)
+        (ctx.docs_dir / "index.html").write_text(content, encoding="utf-8")
+        return "✅ docs/index.html"
+
+    def _generate_html(self, ctx: GenerateContext) -> str:
+        project_name = self.config.project_name or ctx.project.name
+        repo_url = self.config.repo_url
+
+        files = []
+        if (ctx.docs_dir / "README.md").exists():
+            files.append(("README.md", "Project Overview", "📖"))
+        if (ctx.docs_dir / "getting-started.md").exists():
+            files.append(("getting-started.md", "Getting Started", "🚀"))
+        if (ctx.docs_dir / "api.md").exists():
+            files.append(("api.md", "API Reference", "📚"))
+        if (ctx.docs_dir / "modules.md").exists():
+            files.append(("modules.md", "Module Documentation", "📦"))
+        if (ctx.docs_dir / "architecture.md").exists():
+            files.append(("architecture.md", "Architecture", "🏗️"))
+        if (ctx.docs_dir / "dependency-graph.md").exists():
+            files.append(("dependency-graph.md", "Dependency Graph", "🔗"))
+        if (ctx.docs_dir / "coverage.md").exists():
+            files.append(("coverage.md", "Code Coverage", "📊"))
+        if (ctx.docs_dir / "api-changelog.md").exists():
+            files.append(("api-changelog.md", "API Changelog", "📝"))
+        if (ctx.docs_dir / "configuration.md").exists():
+            files.append(("configuration.md", "Configuration", "⚙️"))
+        if (ctx.docs_dir / "CONTRIBUTING.md").exists():
+            files.append(("CONTRIBUTING.md", "Contributing Guide", "🤝"))
+        if (ctx.docs_dir / "examples").is_dir():
+            files.append(("examples/", "Examples", "💡"))
+
+        github_link = f'<a href="{repo_url}" class="github-link" target="_blank" rel="noopener">View on GitHub</a>' if repo_url else ""
+
+        files_html = "\n".join(
+            f'<a href="{href}" class="doc-card"><span class="icon">{icon}</span><span class="title">{title}</span></a>'
+            for href, title, icon in files
+        )
+
+        return f'''<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{project_name} - Documentation</title>
+    <style>
+        * {{ margin: 0; padding: 0; box-sizing: border-box; }}
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, sans-serif;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            min-height: 100vh;
+            padding: 40px 20px;
+        }}
+        .container {{
+            max-width: 900px;
+            margin: 0 auto;
+        }}
+        .header {{
+            text-align: center;
+            margin-bottom: 40px;
+            color: white;
+        }}
+        .header h1 {{
+            font-size: 2.5rem;
+            margin-bottom: 10px;
+            text-shadow: 0 2px 4px rgba(0,0,0,0.2);
+        }}
+        .header p {{
+            font-size: 1.1rem;
+            opacity: 0.9;
+        }}
+        .github-link {{
+            display: inline-block;
+            margin-top: 15px;
+            padding: 10px 20px;
+            background: rgba(255,255,255,0.2);
+            color: white;
+            text-decoration: none;
+            border-radius: 25px;
+            transition: background 0.3s;
+        }}
+        .github-link:hover {{ background: rgba(255,255,255,0.3); }}
+        .docs-grid {{
+            display: grid;
+            grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
+            gap: 20px;
+        }}
+        .doc-card {{
+            background: white;
+            border-radius: 12px;
+            padding: 25px;
+            text-decoration: none;
+            color: #333;
+            box-shadow: 0 4px 15px rgba(0,0,0,0.1);
+            transition: transform 0.2s, box-shadow 0.2s;
+            display: flex;
+            align-items: center;
+            gap: 15px;
+        }}
+        .doc-card:hover {{
+            transform: translateY(-3px);
+            box-shadow: 0 8px 25px rgba(0,0,0,0.15);
+        }}
+        .doc-card .icon {{
+            font-size: 2rem;
+            flex-shrink: 0;
+        }}
+        .doc-card .title {{
+            font-size: 1.1rem;
+            font-weight: 600;
+        }}
+        .footer {{
+            text-align: center;
+            margin-top: 40px;
+            color: rgba(255,255,255,0.7);
+            font-size: 0.9rem;
+        }}
+        @media (max-width: 600px) {{
+            .header h1 {{ font-size: 1.8rem; }}
+            .docs-grid {{ grid-template-columns: 1fr; }}
+        }}
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="header">
+            <h1>{project_name}</h1>
+            <p>Generated Documentation</p>
+            {github_link}
+        </div>
+        <div class="docs-grid">
+            {files_html}
+        </div>
+        <div class="footer">
+            Generated with <a href="https://github.com/wronai/code2docs" style="color: rgba(255,255,255,0.9);">code2docs</a>
+        </div>
+    </div>
+</body>
+</html>'''
+
+
+
 ALL_ADAPTERS = [
     ReadmeGeneratorAdapter,
     ApiReferenceAdapter,
@@ -284,4 +437,5 @@ def run(self, ctx: GenerateContext) -> Optional[str]:
     MkDocsAdapter,
     Code2LlmAdapter,
     OrgReadmeAdapter,
+    IndexHtmlAdapter,
 ]

project.sh

@@ -2,18 +2,17 @@
 clear
 pip install glon --upgrade
 pip install goal --upgrade
+pip install code2logic --upgrade
 pip install code2llm --upgrade
-#pip install code2docs --upgrade
-pip install -e .
-code2docs ./code2docs --output ../docs/
 #code2llm ./ -f toon,evolution,code2logic,project-yaml -o ./project --no-chunk
 code2llm ./ -f all -o ./project --no-chunk
 #code2llm report --format all       # → all views
 rm project/analysis.json
 rm project/analysis.yaml
 
+pip install code2docs --upgrade
+code2docs ./ --readme-only
 
-#code2docs ./code2docs --readme-only     # Tylko README
-#code2docs ./code2docs --dry-run         # Podgląd bez zapisu
-#code2docs sync ./code2docs              # Tylko zmienione pliki
-#code2docs check ./code2docs             # Sprawdź kompletność docs
+#code2docs ./ --dry-run         # Podgląd bez zapisu
+#code2docs sync ./              # Tylko zmienione pliki
+#code2docs check ./             # Sprawdź kompletność docs

project/analysis.json

@@ -2,7 +2,6 @@
 # CC̄=4.4 | critical:27/295 | dups:0 | cycles:1
 
 HEALTH[11]:
-  🟡 CC    _extract_project_metadata CC=29 (limit:15)
   🟡 CC    _render_first_usage CC=15 (limit:15)
   🟡 CC    _generate_intro CC=16 (limit:15)
   🟡 CC    parse_gitignore CC=15 (limit:15)
@@ -13,6 +12,7 @@ HEALTH[11]:
   🟡 CC    _render_module_section CC=25 (limit:15)
   🟡 CC    _generate_advanced CC=22 (limit:15)
   🟡 CC    _render_code_style CC=16 (limit:15)
+  🟡 CC    _extract_project_metadata CC=29 (limit:15)
 
 REFACTOR[2]:
   1. split 11 high-CC methods  (CC>15)
@@ -94,13 +94,13 @@ FUNCTIONS (CC≥10, 27 of 255):
    11.0  ApiReferenceGenerator.generate             10n   2exit  loops+cond+ret
    11.0  ExamplesGenerator._example_from_type       18n   7exit  cond+ret
    11.0  ArchitectureGenerator._generate_class_diagram   12n   2exit  loops+cond+ret
-   10.0  ConfigDocsGenerator._render_section        14n   2exit  loops+cond+ret
    10.0  GettingStartedGenerator._render_prerequisites   15n   2exit  cond+ret
+   10.0  ConfigDocsGenerator._render_section        14n   2exit  loops+cond+ret
    10.0  ApiReferenceGenerator._has_content          6n   3exit  cond+ret
-   10.0  _run_check                                 11n   1exit  loops+cond
+   10.0  Code2DocsConfig.from_yaml                  20n   3exit  cond+ret
    10.0  ApiChangelogGenerator._diff_functions       9n   1exit  loops+cond
    10.0  ApiChangelogGenerator._diff_classes        15n   1exit  loops+cond
-   10.0  Code2DocsConfig.from_yaml                  20n   3exit  cond+ret
+   10.0  _run_check                                 11n   1exit  loops+cond
 
   summary:
     critical(≥10): 27 | high(5-10): 58 | medium(2-5): 100 | low(<2): 70
@@ -143,8 +143,8 @@ CLASSES:
   Code2LlmGenerator              █████                      4m  CC̄=6.2   max=17    !!
   Code2DocsConfig                █████                      4m  CC̄=4.0   max=10  
   BaseGenerator                  ████                       3m  CC̄=1.0   max=1   
-  ProjectScanner                 ████                       3m  CC̄=1.3   max=2   
   EndpointDetector               ████                       3m  CC̄=4.0   max=5   
+  ProjectScanner                 ████                       3m  CC̄=1.3   max=2   
   Updater                        ██                         2m  CC̄=3.0   max=4   
   ReadmeGeneratorAdapter         ██                         2m  CC̄=2.5   max=4   
   ApiReferenceAdapter            ██                         2m  CC̄=2.0   max=2   
@@ -161,16 +161,16 @@ CLASSES:
   Code2LlmAdapter                ██                         2m  CC̄=4.0   max=7   
   OrgReadmeAdapter               ██                         2m  CC̄=3.0   max=4   
   ChangeInfo                     █                          1m  CC̄=1.0   max=1   
-  DefaultGroup                   █                          1m  CC̄=4.0   max=4   
   LLMConfig                      █                          1m  CC̄=1.0   max=1   
+  DefaultGroup                   █                          1m  CC̄=4.0   max=4   
   GenerateContext                                           0m  CC̄=0.0   max=0.0 
   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 
   Code2LlmConfig                                            0m  CC̄=0.0   max=0.0 
+  ApiChange                                                 0m  CC̄=0.0   max=0.0 
   DependencyInfo                                            0m  CC̄=0.0   max=0.0 
   ProjectDependencies                                       0m  CC̄=0.0   max=0.0 
   Endpoint                                                  0m  CC̄=0.0   max=0.0 
@@ -236,6 +236,18 @@ Thi...
     e: ConfigDocsGenerator
     ConfigDocsGenerator  # Generate docs/configuration.md from Code2DocsConfig dataclas...
       __init__(2)  CC=1.0
+  code2docs/config.py:
+    e: ReadmeConfig,DocsConfig,ExamplesConfig,SyncConfig,Code2LlmConfig,LLMConfig,Code2DocsConfig
+    ReadmeConfig  # Configuration for README generation....
+    DocsConfig  # Configuration for docs/ generation....
+    ExamplesConfig  # Configuration for examples/ generation....
+    SyncConfig  # Configuration for synchronization....
+    Code2LlmConfig  # Configuration for code2llm analysis generation....
+    LLMConfig  # Configuration for optional LLM-assisted documentation genera...
+      from_env(0)  CC=1.0
+    Code2DocsConfig  # Main configuration for code2docs....
+      __post_init__(0)  CC=2.0
+        → _detect_repo_url(-1)  CC=3.0
   code2docs/cli.py:
     e: DefaultGroup,main,generate,sync,watch,init,check,diff,_load_config,_run_generate,_run_sync,_run_watch,_run_check,_run_diff
     DefaultGroup  # Click Group that routes unknown subcommands to 'generate'....
@@ -254,18 +266,6 @@ Thi...
     _run_watch(project_path,config)
     _run_check(project_path,config,target)
     _run_diff(project_path,config)
-  code2docs/config.py:
-    e: ReadmeConfig,DocsConfig,ExamplesConfig,SyncConfig,Code2LlmConfig,LLMConfig,Code2DocsConfig
-    ReadmeConfig  # Configuration for README generation....
-    DocsConfig  # Configuration for docs/ generation....
-    ExamplesConfig  # Configuration for examples/ generation....
-    SyncConfig  # Configuration for synchronization....
-    Code2LlmConfig  # Configuration for code2llm analysis generation....
-    LLMConfig  # Configuration for optional LLM-assisted documentation genera...
-      from_env(0)  CC=1.0
-    Code2DocsConfig  # Main configuration for code2docs....
-      __post_init__(0)  CC=2.0
-        → _detect_repo_url(-1)  CC=3.0
   examples/07_web_frameworks.py:
     e: detect_flask_endpoints,detect_fastapi_endpoints,generate_api_docs_from_endpoints,create_example_web_apps,document_web_project
     detect_flask_endpoints(project_path)