code2llm - Generated Analysis Files

This directory contains the complete analysis of your Python 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:

🎯 Core Analysis Files

File	Format	Purpose	Key Insights
analysis.toon	TOON	🔥 Health diagnostics - Complexity, god modules, coupling	45 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
project.toon	TOON	🧠 Project logic - Code2Logic compact module view	Generated via code2logic integration

🤖 LLM-Ready Documentation

File	Format	Purpose	Use Case
context.md	Markdown	📖 LLM narrative - Architecture summary	Paste into ChatGPT/Claude for code analysis
prompt.txt	Text	📝 Ready-to-send prompt - Lists all generated files with instructions	Attach to LLM conversation as context guide
analysis.yaml	YAML	📊 Structured data - Machine-readable	For scripts and automated processing
analysis.json	JSON	🔧 API format - Programmatic access	For integration with other tools

📊 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
*.png	PNG	🖼️ Visual diagrams	Rendered versions of Mermaid files

🚀 Quick Start Commands

Complete LLM Analysis (with Code2Logic)

# Generate complete analysis with code2logic integration
# Creates: analysis.toon, evolution.toon, project.toon, prompt.txt, README.md

# Using specific formats (recommended)
code2llm ./ -f toon,evolution,code2logic -o ./project

# Using 'all' format (includes code2logic)
code2llm ./ -f all -o ./project

The code2logic format automatically:

1. Runs code2logic tool to generate project.toon (compact module view)
2. Creates prompt.txt - ready-to-send prompt listing all generated files

Basic Analysis

# 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

Przykład z projektu toonic, z użyciem modelu Kimi K2.5 w VScode Windsurf:

code2llm ./ -f toon,evolution -o ./project

Performance Options

# Fast analysis for large projects
code2llm ./ -f toon --strategy quick

# Memory-limited analysis
code2llm ./ -f all --max-memory 500

# Skip PNG generation (faster)
code2llm ./ -f all --no-png

Refactoring Focus

# Get refactoring recommendations
code2llm ./ -f evolution

# Focus on specific code smells
code2llm ./ -f toon --refactor --smell god_function

# Data flow analysis
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:

# View health issues
cat analysis.toon | head -30

# Check refactoring priorities
grep "REFACTOR" analysis.toon

evolution.toon - Refactoring Queue

Purpose: Step-by-step refactoring plan Key sections:

• NEXT: Immediate actions to take
• RISKS: Potential breaking changes
• METRICS-TARGET: Success criteria

Example usage:

# Get refactoring plan
cat evolution.toon

# Track progress
grep "NEXT" evolution.toon

flow.toon - Data Flow Analysis

Purpose: Understand data movement through the system Key sections:

• PIPELINES: Data processing chains
• CONTRACTS: Function input/output contracts
• SIDE_EFFECTS: Functions with external impacts

Example usage:

# Find data pipelines
grep "PIPELINES" flow.toon

# Identify side effects
grep "SIDE_EFFECTS" flow.toon

map.toon - Structural Map

Purpose: High-level architecture overview Key sections:

• MODULES: All modules with basic stats
• IMPORTS: Dependency relationships
• SIGNATURES: Public API functions

Example usage:

# See project structure
cat map.toon | head -50

# Find public APIs
grep "SIGNATURES" map.toon

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:

# Copy to clipboard for LLM
cat context.md | pbcopy  # macOS
cat context.md | xclip -sel clip  # Linux

# Use with Claude/ChatGPT for code analysis

project.toon - Project Logic (Code2Logic)

Purpose: Compact module view generated by code2logic integration Key sections:

• Modules list: All project modules with file sizes
• Imports: Dependency information
• Classes/Functions: Summary counts

When to use: When you need a lightweight project overview combined with code2llm analysis

Generation:

# Generated automatically when using -f code2logic
code2llm ./ -f toon,evolution,code2logic -o ./project

prompt.txt - Ready-to-Send LLM Prompt

Purpose: Pre-formatted prompt listing all generated files for LLM conversation Contents:

• Files section: Lists all existing generated files (analysis.toon, context.md, etc.)
• Missing section: Shows which files weren't generated (if any)
• Task section: Instructions for LLM analysis
• Constraints section: Guidelines for suggested changes

Example usage:

# View the prompt
cat project/prompt.txt

# Copy to clipboard and paste into ChatGPT/Claude
cat project/prompt.txt | pbcopy  # macOS
cat project/prompt.txt | xclip -sel clip  # Linux

Generated when: Using -f code2logic or -f all

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:

# 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

# Quick health check
code2llm ./ -f toon
cat analysis.toon | grep -E "(HEALTH|REFACTOR)"

2. Refactoring Planning

# Get refactoring queue
code2llm ./ -f evolution
cat evolution.toon

# Focus on specific issues
code2llm ./ -f toon --refactor --smell god_function

3. LLM Assistance

# 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

# 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)
• FAN-IN: High incoming dependencies
• CYCLES: Circular dependencies

Data Flow Indicators

• PIPELINE: Sequential data processing
• CONTRACT: Clear input/output specification
• SIDE_EFFECT: External state modification

🛠️ Integration Examples

CI/CD Pipeline

#!/bin/bash
# Analyze code quality in CI
code2llm ./ -f toon -o ./analysis
if grep -q "🔴 GOD" ./analysis/analysis.toon; then
    echo "❌ God modules detected"
    exit 1
fi

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit
code2llm ./ -f toon -o ./temp_analysis
if grep -q "🔴" ./temp_analysis/analysis.toon; then
    echo "⚠️  Critical issues found. Review before committing."
fi
rm -rf ./temp_analysis

Documentation Generation

# 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 - 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

# Deep analysis with all insights
code2llm ./ -m hybrid -f all --max-depth 15 -v

# Performance-optimized
code2llm ./ -m static -f toon --strategy quick

# Refactoring-focused
code2llm ./ -f toon,evolution --refactor

Output Customization

# Separate output directories
code2llm ./ -f all -o ./analysis-$(date +%Y%m%d)

# Split YAML into multiple files
code2llm ./ -f yaml --split-output

# Separate orphaned functions
code2llm ./ -f yaml --separate-orphans

---

Generated by: code2llm ./ -f all --readme
Analysis Date: 2026-03-01
Total Functions: 645
Total Classes: 94
Modules: 76

For more information about code2llm, visit: https://github.com/tom-sapletta/code2llm

License

Apache License 2.0 - see LICENSE for details.

Author

Created by Tom Sapletta - tom@sapletta.com