refactoring

Author: tom-sapletta-com

docs/README.md

@@ -1,3 +1,7 @@
+# code2llm - Generated Analysis Files
+
+This directory contains the complete analysis of your project generated by `code2llm`. Each file serves a specific purpose for understanding, refactoring, and documenting your codebase.
+
 ## 📁 Generated Files Overview
 
 When you run `code2llm ./ -f all`, the following files are created:
@@ -16,10 +20,30 @@ When you run `code2llm ./ -f all`, the following files are created:
 | `prompt.txt` | **Text** | **📝 Ready-to-send prompt** - Lists all files with instructions | Attach to LLM conversation as context guide |
 | `context.md` | **Markdown** | **📖 LLM narrative** - Architecture summary | Paste into ChatGPT/Claude for code analysis |
 
+### 📊 Visualizations
+
+| File | Format | Purpose | Description |
+|------|--------|---------|-------------|
+| `flow.mmd` | **Mermaid** | **🔄 Control flow diagram** | Function call paths with complexity styling |
+| `calls.mmd` | **Mermaid** | **📞 Call graph** | Function dependencies (edges only) |
+| `compact_flow.mmd` | **Mermaid** | **📦 Module overview** | Aggregated module-level view |
+
+## 🚀 Quick Start Commands
+
+### Basic Analysis
+```bash
+# Quick health check (TOON format only)
+code2llm ./ -f toon
+
+# Generate all formats (what created these files)
+code2llm ./ -f all
+
 # LLM-ready context only
 code2llm ./ -f context
 ```
 
+### Performance Options
+```bash
 # Fast analysis for large projects
 code2llm ./ -f toon --strategy quick
 
@@ -30,6 +54,8 @@ code2llm ./ -f all --max-memory 500
 code2llm ./ -f all --no-png
 ```
 
+### Refactoring Focus
+```bash
 # Get refactoring recommendations
 code2llm ./ -f evolution
 
@@ -40,6 +66,20 @@ code2llm ./ -f toon --refactor --smell god_function
 code2llm ./ -f flow --data-flow
 ```
 
+## 📖 Understanding Each File
+
+### `analysis.toon` - Health Diagnostics
+**Purpose**: Quick overview of code health issues
+**Key sections**:
+- **HEALTH**: Critical issues (🔴) and warnings (🟡)
+- **REFACTOR**: Prioritized refactoring actions
+- **COUPLING**: Module dependencies and potential cycles
+- **LAYERS**: Package complexity metrics
+- **FUNCTIONS**: High-complexity functions (CC ≥ 10)
+- **CLASSES**: Complex classes needing attention
+
+**Example usage**:
+```bash
 # View health issues
 cat analysis.toon | head -30
 
@@ -122,24 +162,60 @@ grep -E "^  .*[0-9]{3,}$" project.toon.yaml | sort -t',' -k2 -n -r | head -10
 
 **Example usage**:
 ```bash
+# View the prompt
+cat prompt.txt
+
 # Copy to clipboard and paste into ChatGPT/Claude
 cat prompt.txt | pbcopy  # macOS
 cat prompt.txt | xclip -sel clip  # Linux
 ```
 
+### `context.md` - LLM Narrative
+**Purpose**: Ready-to-paste context for AI assistants
+**Key sections**:
+- **Overview**: Project statistics
+- **Architecture**: Module breakdown
+- **Entry Points**: Public interfaces
+- **Patterns**: Design patterns detected
+
+**Example usage**:
+```bash
 # Copy to clipboard for LLM
 cat context.md | pbcopy  # macOS
 cat context.md | xclip -sel clip  # Linux
 
+# Use with Claude/ChatGPT for code analysis
+```
+
+### Visualization Files (`*.mmd`, `*.png`)
+**Purpose**: Visual understanding of code structure
+**Files**:
+- `flow.mmd` - Detailed control flow with complexity colors
+- `calls.mmd` - Simple call graph
+- `compact_flow.mmd` - High-level module view
+- `*.png` - Pre-rendered images
+
+**Example usage**:
+```bash
 # View diagrams
 open flow.png  # macOS
 xdg-open flow.png  # Linux
 
+# Edit in Mermaid Live Editor
+# Copy content of .mmd files to https://mermaid.live
+```
+
+## 🔍 Common Analysis Patterns
+
+### 1. Code Health Assessment
+```bash
 # Quick health check
 code2llm ./ -f toon
 cat analysis.toon | grep -E "(HEALTH|REFACTOR)"
 ```
 
+### 2. Refactoring Planning
+```bash
 # Get refactoring queue
 code2llm ./ -f evolution
 cat evolution.toon.yaml
@@ -148,17 +224,33 @@ cat evolution.toon.yaml
 code2llm ./ -f toon --refactor --smell god_function
 ```
 
+### 3. LLM Assistance
+```bash
 # Generate context for AI
 code2llm ./ -f context
 cat context.md
 
+# Use with Claude: "Based on this context, help me refactor the god modules"
+```
+
+### 4. Team Documentation
+```bash
 # Generate all docs for team
 code2llm ./ -f all -o ./docs/
 
 # Create visual diagrams
 open docs/flow.png
 ```
 
+## 📊 Interpreting Metrics
+
+### Complexity Metrics (CC)
+- **🔴 Critical (≥5.0)**: Immediate refactoring needed
+- **🟠 High (3.0-4.9)**: Consider refactoring
+- **🟡 Medium (1.5-2.9)**: Monitor complexity
+- **🟢 Low (0.1-1.4)**: Acceptable
+- **⚪ Basic (0.0)**: Simple functions
+
 ### Module Health
 - **GOD Module**: Too large (>500 lines, >20 methods)
 - **HUB**: High fan-out (calls many modules)
@@ -170,6 +262,11 @@ open docs/flow.png
 - **CONTRACT**: Clear input/output specification
 - **SIDE_EFFECT**: External state modification
 
+## 🛠️ Integration Examples
+
+### CI/CD Pipeline
+```bash
+#!/bin/bash
 # Analyze code quality in CI
 code2llm ./ -f toon -o ./analysis
 if grep -q "🔴 GOD" ./analysis/analysis.toon; then
@@ -178,6 +275,9 @@ if grep -q "🔴 GOD" ./analysis/analysis.toon; then
 fi
 ```
 
+### Pre-commit Hook
+```bash
+#!/bin/sh
 # .git/hooks/pre-commit
 code2llm ./ -f toon -o ./temp_analysis
 if grep -q "🔴" ./temp_analysis/analysis.toon; then
@@ -186,12 +286,26 @@ fi
 rm -rf ./temp_analysis
 ```
 
+### Documentation Generation
+```bash
 # Generate docs for README
 code2llm ./ -f context -o ./docs/
 echo "## Architecture" >> README.md
 cat docs/context.md >> README.md
 ```
 
+## 📚 Next Steps
+
+1. **Review `analysis.toon`** - Identify critical issues
+2. **Check `evolution.toon.yaml`** - Plan refactoring priorities
+3. **Use `context.md`** - Get LLM assistance for complex changes
+4. **Reference visualizations** - Understand system architecture
+5. **Track progress** - Re-run analysis after changes
+
+## 🔧 Advanced Usage
+
+### Custom Analysis
+```bash
 # Deep analysis with all insights
 code2llm ./ -m hybrid -f all --max-depth 15 -v
 
@@ -202,6 +316,8 @@ code2llm ./ -m static -f toon --strategy quick
 code2llm ./ -f toon,evolution --refactor
 ```
 
+### Output Customization
+```bash
 # Separate output directories
 code2llm ./ -f all -o ./analysis-$(date +%Y%m%d)
 
@@ -215,7 +331,7 @@ code2llm ./ -f yaml --separate-orphans
 ---
 
 **Generated by**: `code2llm ./ -f all --readme`  
-**Analysis Date**: 2026-04-13  
+**Analysis Date**: 2026-04-19  
 **Total Functions**: 351  
 **Total Classes**: 60  
 **Modules**: 54  

project/README.md

@@ -1,4 +1,4 @@
-# code2llm | 39f 5459L | python:38,shell:1 | 2026-04-13
+# code2llm | 39f 5459L | python:38,shell:1 | 2026-04-19
 # CC̄=3.8 | critical:0/351 | dups:0 | cycles:1
 
 HEALTH[0]: ok

project/analysis.toon.yaml

@@ -4,43 +4,43 @@ flowchart LR
     end
     subgraph code2docs__cli
         code2docs__cli___run_sync["_run_sync"]
-        code2docs__cli___run_watch["_run_watch"]
         code2docs__cli___run_check["_run_check"]
-        code2docs__cli__watch["watch"]
-        code2docs__cli___run_diff["_run_diff"]
-        code2docs__cli___load_config["_load_config"]
         code2docs__cli__diff["diff"]
+        code2docs__cli___run_watch["_run_watch"]
+        code2docs__cli___load_config["_load_config"]
+        code2docs__cli___run_diff["_run_diff"]
         code2docs__cli__sync["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___make_badge["_make_badge"]
-        code2docs__formatters__badges__generate_badges["generate_badges"]
+        code2docs__formatters__toc___slugify["_slugify"]
         code2docs__formatters__toc__extract_headings["extract_headings"]
+        code2docs__formatters__badges___make_badge["_make_badge"]
         code2docs__formatters__toc__generate_toc["generate_toc"]
-        code2docs__formatters__toc___slugify["_slugify"]
+        code2docs__formatters__badges__generate_badges["generate_badges"]
     end
     subgraph code2docs__generators
-        code2docs__generators__readme_gen__ReadmeGenerator___build_context["_build_context"]
-        code2docs__generators__code2llm_gen__parse_gitignore["parse_gitignore"]
-        code2docs__generators__contributing_gen__ContributingGenerator___get_style_lines["_get_style_lines"]
-        code2docs__generators__code2llm_gen__Code2LlmGenerator___add_exclude_patterns["_add_exclude_patterns"]
-        code2docs__generators__code2llm_gen___should_skip_line["_should_skip_line"]
-        code2docs__generators__code2llm_gen___clean_pattern["_clean_pattern"]
+        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___is_valid_pattern["_is_valid_pattern"]
         code2docs__generators__contributing_gen__ContributingGenerator___render_code_style["_render_code_style"]
+        code2docs__generators__code2llm_gen__parse_gitignore["parse_gitignore"]
         code2docs__generators__contributing_gen__ContributingGenerator___get_jsts_style_lines["_get_jsts_style_lines"]
-        code2docs__generators__code2llm_gen___extract_patterns["_extract_patterns"]
-        code2docs__generators__code2llm_gen___process_line["_process_line"]
+        code2docs__generators__code2llm_gen___should_skip_line["_should_skip_line"]
+        code2docs__generators__code2llm_gen___is_valid_pattern["_is_valid_pattern"]
+        code2docs__generators__code2llm_gen___clean_pattern["_clean_pattern"]
+        code2docs__generators__readme_gen__ReadmeGenerator___build_context["_build_context"]
+        code2docs__generators__contributing_gen__ContributingGenerator___get_style_lines["_get_style_lines"]
         code2docs__generators__readme_gen__generate_readme["generate_readme"]
+        code2docs__generators__code2llm_gen___process_line["_process_line"]
+        code2docs__generators__code2llm_gen__Code2LlmGenerator___add_exclude_patterns["_add_exclude_patterns"]
     end
     subgraph code2docs__llm_helper
-        code2docs__llm_helper__LLMHelper__complete["complete"]
         code2docs__llm_helper___get_litellm["_get_litellm"]
+        code2docs__llm_helper__LLMHelper__complete["complete"]
     end
     subgraph code2docs__sync
         code2docs__sync__watcher__start_watcher["start_watcher"]
@@ -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_readme_simple["generate_readme_simple"]
         examples__03_programmatic_api__custom_documentation_pipeline["custom_documentation_pipeline"]
         examples__03_programmatic_api__inspect_project_structure["inspect_project_structure"]
-        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__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__badge_examples["badge_examples"]
         examples__06_formatters__toc_examples["toc_examples"]
+        examples__06_formatters__build_custom_readme["build_custom_readme"]
     end
     subgraph examples__07_web_frameworks
         examples__07_web_frameworks__document_web_project["document_web_project"]
         examples__07_web_frameworks__generate_api_docs_from_endpoints["generate_api_docs_from_endpoin"]
-        examples__07_web_frameworks__detect_flask_endpoints["detect_flask_endpoints"]
         examples__07_web_frameworks__detect_fastapi_endpoints["detect_fastapi_endpoints"]
+        examples__07_web_frameworks__detect_flask_endpoints["detect_flask_endpoints"]
     end
     code2docs__formatters__badges__generate_badges --> code2docs__formatters__badges___make_badge
     code2docs__formatters__toc__generate_toc --> code2docs__formatters__toc__extract_headings