draft

Author: tom-sapletta-com

docs/README.md

@@ -3,40 +3,40 @@ flowchart LR
         code2docs__analyzers__project_scanner__ProjectScanner__analyze["analyze"]
     end
     subgraph code2docs__cli
-        code2docs__cli__check["check"]
+        code2docs__cli___run_diff["_run_diff"]
+        code2docs__cli___run_sync["_run_sync"]
+        code2docs__cli__diff["diff"]
         code2docs__cli___load_config["_load_config"]
-        code2docs__cli___run_watch["_run_watch"]
-        code2docs__cli__watch["watch"]
         code2docs__cli___run_check["_run_check"]
-        code2docs__cli__diff["diff"]
-        code2docs__cli___run_diff["_run_diff"]
+        code2docs__cli___run_watch["_run_watch"]
         code2docs__cli__sync["sync"]
-        code2docs__cli___run_sync["_run_sync"]
+        code2docs__cli__check["check"]
+        code2docs__cli__watch["watch"]
     end
     subgraph code2docs__config
         code2docs__config__Code2DocsConfig__from_yaml["from_yaml"]
     end
     subgraph code2docs__formatters
         code2docs__formatters__badges__generate_badges["generate_badges"]
-        code2docs__formatters__toc__extract_headings["extract_headings"]
+        code2docs__formatters__badges___make_badge["_make_badge"]
         code2docs__formatters__toc__generate_toc["generate_toc"]
+        code2docs__formatters__toc__extract_headings["extract_headings"]
         code2docs__formatters__toc___slugify["_slugify"]
-        code2docs__formatters__badges___make_badge["_make_badge"]
     end
     subgraph code2docs__generators
-        code2docs__generators__contributing_gen__ContributingGenerator___get_jsts_style_lines["_get_jsts_style_lines"]
-        code2docs__generators__code2llm_gen___process_line["_process_line"]
-        code2docs__generators__contributing_gen__ContributingGenerator___render_code_style["_render_code_style"]
         code2docs__generators__code2llm_gen___is_valid_pattern["_is_valid_pattern"]
-        code2docs__generators__readme_gen__generate_readme["generate_readme"]
-        code2docs__generators__code2llm_gen___clean_pattern["_clean_pattern"]
-        code2docs__generators__contributing_gen__ContributingGenerator___get_python_style_lines["_get_python_style_lines"]
-        code2docs__generators__code2llm_gen__parse_gitignore["parse_gitignore"]
         code2docs__generators__code2llm_gen__Code2LlmGenerator___add_exclude_patterns["_add_exclude_patterns"]
-        code2docs__generators__code2llm_gen___extract_patterns["_extract_patterns"]
+        code2docs__generators__contributing_gen__ContributingGenerator___get_python_style_lines["_get_python_style_lines"]
+        code2docs__generators__code2llm_gen___clean_pattern["_clean_pattern"]
+        code2docs__generators__readme_gen__generate_readme["generate_readme"]
         code2docs__generators__contributing_gen__ContributingGenerator___get_style_lines["_get_style_lines"]
+        code2docs__generators__contributing_gen__ContributingGenerator___render_code_style["_render_code_style"]
+        code2docs__generators__code2llm_gen__parse_gitignore["parse_gitignore"]
         code2docs__generators__code2llm_gen___should_skip_line["_should_skip_line"]
+        code2docs__generators__code2llm_gen___extract_patterns["_extract_patterns"]
+        code2docs__generators__code2llm_gen___process_line["_process_line"]
         code2docs__generators__readme_gen__ReadmeGenerator___build_context["_build_context"]
+        code2docs__generators__contributing_gen__ContributingGenerator___get_jsts_style_lines["_get_jsts_style_lines"]
     end
     subgraph code2docs__llm_helper
         code2docs__llm_helper__LLMHelper__complete["complete"]
@@ -49,11 +49,11 @@ flowchart LR
         examples__02_configuration__load_config_from_yaml["load_config_from_yaml"]
     end
     subgraph examples__03_programmatic_api
-        examples__03_programmatic_api__generate_full_documentation["generate_full_documentation"]
-        examples__03_programmatic_api__generate_docs_if_needed["generate_docs_if_needed"]
-        examples__03_programmatic_api__custom_documentation_pipeline["custom_documentation_pipeline"]
         examples__03_programmatic_api__inspect_project_structure["inspect_project_structure"]
+        examples__03_programmatic_api__custom_documentation_pipeline["custom_documentation_pipeline"]
+        examples__03_programmatic_api__generate_docs_if_needed["generate_docs_if_needed"]
         examples__03_programmatic_api__generate_readme_simple["generate_readme_simple"]
+        examples__03_programmatic_api__generate_full_documentation["generate_full_documentation"]
     end
     subgraph examples__04_sync_and_watch
         examples__04_sync_and_watch__watch_and_auto_regenerate["watch_and_auto_regenerate"]
@@ -62,15 +62,15 @@ flowchart LR
         examples__05_custom_generators__generate_custom_report["generate_custom_report"]
     end
     subgraph examples__06_formatters
+        examples__06_formatters__build_custom_readme["build_custom_readme"]
         examples__06_formatters__toc_examples["toc_examples"]
         examples__06_formatters__badge_examples["badge_examples"]
-        examples__06_formatters__build_custom_readme["build_custom_readme"]
     end
     subgraph examples__07_web_frameworks
-        examples__07_web_frameworks__generate_api_docs_from_endpoints["generate_api_docs_from_endpoin"]
-        examples__07_web_frameworks__document_web_project["document_web_project"]
-        examples__07_web_frameworks__detect_fastapi_endpoints["detect_fastapi_endpoints"]
         examples__07_web_frameworks__detect_flask_endpoints["detect_flask_endpoints"]
+        examples__07_web_frameworks__detect_fastapi_endpoints["detect_fastapi_endpoints"]
+        examples__07_web_frameworks__document_web_project["document_web_project"]
+        examples__07_web_frameworks__generate_api_docs_from_endpoints["generate_api_docs_from_endpoin"]
     end
     code2docs__formatters__badges__generate_badges --> code2docs__formatters__badges___make_badge
     code2docs__formatters__toc__generate_toc --> code2docs__formatters__toc__extract_headings

project/calls.mmd

@@ -43,15 +43,15 @@
 - **Classes**: 1
 - **File**: `org_readme_gen.py`
 
-### code2docs.cli
+### code2docs.generators.getting_started_gen
 - **Functions**: 14
 - **Classes**: 1
-- **File**: `cli.py`
+- **File**: `getting_started_gen.py`
 
-### code2docs.generators.getting_started_gen
+### code2docs.cli
 - **Functions**: 14
 - **Classes**: 1
-- **File**: `getting_started_gen.py`
+- **File**: `cli.py`
 
 ### code2docs.formatters.markdown
 - **Functions**: 13
@@ -78,16 +78,16 @@
 - **Classes**: 1
 - **File**: `architecture_gen.py`
 
-### code2docs.analyzers.dependency_scanner
-- **Functions**: 10
-- **Classes**: 3
-- **File**: `dependency_scanner.py`
-
 ### code2docs.analyzers.docstring_extractor
 - **Functions**: 10
 - **Classes**: 2
 - **File**: `docstring_extractor.py`
 
+### code2docs.analyzers.dependency_scanner
+- **Functions**: 10
+- **Classes**: 3
+- **File**: `dependency_scanner.py`
+
 ### code2docs.generators.depgraph_gen
 - **Functions**: 9
 - **Classes**: 1
@@ -117,14 +117,14 @@
 
 Main execution flows into the system:
 
-### code2docs.generators.examples_gen.ExamplesGenerator._generate_quickstart
-> Generate quickstart.py — minimal working example.
-- **Calls**: self._find_convenience_functions, self._find_api_classes, set, lines.extend, lines.append, self._find_class_by_name, lines.append, lines.append
-
 ### code2docs.config.Code2DocsConfig.from_yaml
 > Load configuration from code2docs.yaml.
 - **Calls**: Path, cls, data.get, project.get, project.get, project.get, project.get, project.get
 
+### code2docs.generators.examples_gen.ExamplesGenerator._generate_quickstart
+> Generate quickstart.py — minimal working example.
+- **Calls**: self._find_convenience_functions, self._find_api_classes, set, lines.extend, lines.append, self._find_class_by_name, lines.append, lines.append
+
 ### code2docs.generators.architecture_gen.ArchitectureGenerator.generate
 > Generate architecture documentation.
 - **Calls**: lines.append, self._generate_llm_summary, lines.append, self._detect_layers, lines.append, lines.append, lines.append, lines.append
@@ -241,14 +241,14 @@ Main execution flows into the system:
 
 Key execution flows identified:
 
-### Flow 1: _generate_quickstart
+### Flow 1: from_yaml
 ```
-_generate_quickstart [code2docs.generators.examples_gen.ExamplesGenerator]
+from_yaml [code2docs.config.Code2DocsConfig]
 ```
 
-### Flow 2: from_yaml
+### Flow 2: _generate_quickstart
 ```
-from_yaml [code2docs.config.Code2DocsConfig]
+_generate_quickstart [code2docs.generators.examples_gen.ExamplesGenerator]
 ```
 
 ### Flow 3: generate
@@ -345,16 +345,16 @@ This generator wraps the code2llm CLI to pr
 - **Methods**: 10
 - **Key Methods**: code2docs.generators.architecture_gen.ArchitectureGenerator.__init__, code2docs.generators.architecture_gen.ArchitectureGenerator.generate, code2docs.generators.architecture_gen.ArchitectureGenerator._generate_pipeline_overview, code2docs.generators.architecture_gen.ArchitectureGenerator._generate_layer_diagram, code2docs.generators.architecture_gen.ArchitectureGenerator._get_public_entry_points, code2docs.generators.architecture_gen.ArchitectureGenerator._generate_llm_summary, code2docs.generators.architecture_gen.ArchitectureGenerator._generate_module_graph, code2docs.generators.architecture_gen.ArchitectureGenerator._generate_class_diagram, code2docs.generators.architecture_gen.ArchitectureGenerator._detect_layers, code2docs.generators.architecture_gen.ArchitectureGenerator._generate_metrics_table
 
-### code2docs.analyzers.dependency_scanner.DependencyScanner
-> Scan and parse project dependency files.
-- **Methods**: 10
-- **Key Methods**: code2docs.analyzers.dependency_scanner.DependencyScanner.scan, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_pyproject, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_pyproject_regex, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_setup_py, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_requirements_txt, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_package_json, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_cargo_toml, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_go_mod, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_dep_string, code2docs.analyzers.dependency_scanner.DependencyScanner._detect_version
-
 ### code2docs.analyzers.docstring_extractor.DocstringExtractor
 > Extract and parse docstrings from AnalysisResult.
 - **Methods**: 10
 - **Key Methods**: code2docs.analyzers.docstring_extractor.DocstringExtractor.extract_all, code2docs.analyzers.docstring_extractor.DocstringExtractor.parse, code2docs.analyzers.docstring_extractor.DocstringExtractor._extract_summary, code2docs.analyzers.docstring_extractor.DocstringExtractor._classify_section, code2docs.analyzers.docstring_extractor.DocstringExtractor._parse_sections, code2docs.analyzers.docstring_extractor.DocstringExtractor._parse_param_line, code2docs.analyzers.docstring_extractor.DocstringExtractor._parse_returns_line, code2docs.analyzers.docstring_extractor.DocstringExtractor._parse_raises_line, code2docs.analyzers.docstring_extractor.DocstringExtractor._parse_examples_line, code2docs.analyzers.docstring_extractor.DocstringExtractor.coverage_report
 
+### code2docs.analyzers.dependency_scanner.DependencyScanner
+> Scan and parse project dependency files.
+- **Methods**: 10
+- **Key Methods**: code2docs.analyzers.dependency_scanner.DependencyScanner.scan, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_pyproject, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_pyproject_regex, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_setup_py, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_requirements_txt, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_package_json, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_cargo_toml, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_go_mod, code2docs.analyzers.dependency_scanner.DependencyScanner._parse_dep_string, code2docs.analyzers.dependency_scanner.DependencyScanner._detect_version
+
 ### code2docs.generators.depgraph_gen.DepGraphGenerator
 > Generate docs/dependency-graph.md with Mermaid diagrams.
 - **Methods**: 9
@@ -406,13 +406,13 @@ Key functions that process and transform data:
 > Format coverage stats as a Markdown table.
 - **Output to**: None.join, lines.append
 
-### code2docs.cli.DefaultGroup.parse_args
-- **Output to**: None.parse_args, super
-
 ### code2docs.generators.getting_started_gen.GettingStartedGenerator._format_func_args
 > Format function arguments for example code.
 - **Output to**: None.join, enumerate
 
+### code2docs.cli.DefaultGroup.parse_args
+- **Output to**: None.parse_args, super
+
 ### code2docs.generators.code2llm_gen.parse_gitignore
 > Parse .gitignore file and return list of patterns to exclude.
 
@@ -437,37 +437,9 @@ Filters out:
 > Render formatter usage examples.
 - **Output to**: lines.append, lines.append, lines.append, lines.append, lines.append
 
-### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_pyproject
-> Parse pyproject.toml for dependencies.
-- **Output to**: ProjectDependencies, data.get, project.get, project.get, project.get
-
-### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_pyproject_regex
-> Fallback regex-based pyproject.toml parser.
-- **Output to**: ProjectDependencies, path.read_text, re.search, re.search, re.findall
-
-### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_setup_py
-> Parse setup.py for dependencies (regex-based, no exec).
-- **Output to**: ProjectDependencies, path.read_text, re.search, re.search, re.findall
-
-### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_requirements_txt
-> Parse requirements.txt.
-- **Output to**: ProjectDependencies, None.splitlines, line.strip, deps.dependencies.append, path.read_text
-
-### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_package_json
-> Parse package.json for dependencies.
-- **Output to**: ProjectDependencies, data.get, data.get, data.get, engines.get
-
-### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_cargo_toml
-> Parse Cargo.toml for Rust dependencies.
-- **Output to**: ProjectDependencies, path.read_text, re.search, content.splitlines, ver_match.group
-
-### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_go_mod
-> Parse go.mod for Go dependencies.
-- **Output to**: ProjectDependencies, path.read_text, re.search, re.search, re.finditer
-
-### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_dep_string
-> Parse a dependency string like 'package>=1.0'.
-- **Output to**: re.match, DependencyInfo, dep_str.strip, DependencyInfo, dep_str.strip
+### code2docs.analyzers.endpoint_detector.EndpointDetector._parse_decorator
+> Try to parse a route decorator string.
+- **Output to**: self.FASTAPI_PATTERNS.search, self.FLASK_PATTERNS.search, Endpoint, Endpoint, None.upper
 
 ### examples.05_custom_generators.MetricsReportGenerator._format_stats_table
 > Format statistics as markdown table.
@@ -500,9 +472,37 @@ Filters out:
 > Parse an examples line.
 - **Output to**: info.examples.append
 
-### code2docs.analyzers.endpoint_detector.EndpointDetector._parse_decorator
-> Try to parse a route decorator string.
-- **Output to**: self.FASTAPI_PATTERNS.search, self.FLASK_PATTERNS.search, Endpoint, Endpoint, None.upper
+### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_pyproject
+> Parse pyproject.toml for dependencies.
+- **Output to**: ProjectDependencies, data.get, project.get, project.get, project.get
+
+### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_pyproject_regex
+> Fallback regex-based pyproject.toml parser.
+- **Output to**: ProjectDependencies, path.read_text, re.search, re.search, re.findall
+
+### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_setup_py
+> Parse setup.py for dependencies (regex-based, no exec).
+- **Output to**: ProjectDependencies, path.read_text, re.search, re.search, re.findall
+
+### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_requirements_txt
+> Parse requirements.txt.
+- **Output to**: ProjectDependencies, None.splitlines, line.strip, deps.dependencies.append, path.read_text
+
+### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_package_json
+> Parse package.json for dependencies.
+- **Output to**: ProjectDependencies, data.get, data.get, data.get, engines.get
+
+### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_cargo_toml
+> Parse Cargo.toml for Rust dependencies.
+- **Output to**: ProjectDependencies, path.read_text, re.search, content.splitlines, ver_match.group
+
+### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_go_mod
+> Parse go.mod for Go dependencies.
+- **Output to**: ProjectDependencies, path.read_text, re.search, re.search, re.finditer
+
+### code2docs.analyzers.dependency_scanner.DependencyScanner._parse_dep_string
+> Parse a dependency string like 'package>=1.0'.
+- **Output to**: re.match, DependencyInfo, dep_str.strip, DependencyInfo, dep_str.strip
 
 ## Behavioral Patterns
 
@@ -551,8 +551,8 @@ Functions exposed as public API (no underscore prefix):
 - `examples.07_web_frameworks.document_web_project` - 9 calls
 - `code2docs.formatters.markdown.MarkdownFormatter.table` - 8 calls
 - `code2docs.generators.depgraph_gen.DepGraphGenerator.generate` - 8 calls
-- `code2docs.cli.sync` - 8 calls
 - `code2docs.generators.getting_started_gen.GettingStartedGenerator.generate` - 8 calls
+- `code2docs.cli.sync` - 8 calls
 - `code2docs.generators.code2llm_gen.Code2LlmGenerator.generate_all` - 8 calls
 - `code2docs.generators.org_readme_gen.OrgReadmeGenerator.generate` - 8 calls
 - `examples.03_programmatic_api.custom_documentation_pipeline` - 8 calls
@@ -567,14 +567,14 @@ How components interact:
 
 ```mermaid
 graph TD
+    from_yaml --> Path
+    from_yaml --> cls
+    from_yaml --> get
     _generate_quickstart --> _find_convenience_fu
     _generate_quickstart --> _find_api_classes
     _generate_quickstart --> set
     _generate_quickstart --> extend
     _generate_quickstart --> append
-    from_yaml --> Path
-    from_yaml --> cls
-    from_yaml --> get
     generate --> append
     generate --> _generate_llm_summar
     generate --> _detect_layers

project/calls.png

@@ -6,7 +6,7 @@ SUMMARY:
   dup_groups:    6
   dup_fragments: 19
   saved_lines:   69
-  scan_ms:       3900
+  scan_ms:       4006
 
 DUPLICATES[6] (ranked by impact):
   [88c0cfa6561a3637]   EXAC  __init__  L=3 N=9 saved=24 sim=1.00

project/context.md

@@ -36,4 +36,4 @@ PATTERNS (language parser shared logic):
     - Standardized FunctionInfo/ClassInfo models
 
 HISTORY:
-  prev CC̄=4.2 → now CC̄=3.8
+  prev CC̄=3.8 → now CC̄=3.8

project/duplication.toon.yaml

@@ -2,7 +2,7 @@
 # stats: 311 func | 0 cls | 39 mod | CC̄=3.8 | critical:0 | cycles:0
 # alerts[5]: fan-out _run_check=24; fan-out start_watcher=22; fan-out Code2DocsConfig.from_yaml=19; fan-out ReadmeGenerator._build_context=17; fan-out ArchitectureGenerator.generate=16
 # hotspots[5]: _run_check fan=24; start_watcher fan=22; Code2DocsConfig.from_yaml fan=19; ReadmeGenerator._build_context fan=17; Updater.apply fan=16
-# evolution: CC̄ 4.2→3.8 (improved -0.4)
+# evolution: CC̄ 3.8→3.8 (flat 0.0)
 # Keys: M=modules, D=details, i=imports, e=exports, c=classes, f=functions, m=methods
 M[39]:
   code2docs/__init__.py,24