code2llm 0.5.4__tar.gz → 0.5.6__tar.gz

code2llm-0.5.6/PKG-INFO

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: code2llm
+Version: 0.5.6
+Summary: High-performance Python code flow analysis with optimized TOON format - CFG, DFG, call graphs, and intelligent code queries
+Home-page: https://github.com/wronai/stts
+Author: STTS Project
+Author-email: Tom Sapletta <tom@sapletta.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/wronai/stts
+Project-URL: Repository, https://github.com/wronai/stts
+Project-URL: Issues, https://github.com/wronai/stts/issues
+Keywords: static-analysis,control-flow,data-flow,call-graph,reverse-engineering,toon-format,code-analysis,ast,optimization,complexity-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx>=2.6
+Requires-Dist: matplotlib>=3.4
+Requires-Dist: pyyaml>=5.4
+Requires-Dist: numpy>=1.20
+Requires-Dist: jinja2>=3.0
+Requires-Dist: radon>=5.1
+Requires-Dist: astroid>=3.0
+Requires-Dist: vulture>=2.10
+Requires-Dist: tiktoken>=0.5
+Requires-Dist: tree-sitter>=0.21
+Requires-Dist: tree-sitter-python>=0.21
+Provides-Extra: dev
+Requires-Dist: pytest>=6.2; extra == "dev"
+Requires-Dist: pytest-cov>=2.12; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.9; extra == "dev"
+Requires-Dist: mypy>=0.910; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# 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 |
+
+### 🤖 LLM-Ready Documentation
+
+| File | Format | Purpose | Use Case |
+|------|--------|---------|----------|
+| `context.md` | **Markdown** | **📖 LLM narrative** - Architecture summary | Paste into ChatGPT/Claude for code analysis |
+| `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
+
+### 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
+
+# Memory-limited analysis
+code2llm ./ -f all --max-memory 500
+
+# Skip PNG generation (faster)
+code2llm ./ -f all --no-png
+```
+
+### Refactoring Focus
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```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
+
+# Focus on specific issues
+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)
+- **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
+```bash
+#!/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
+```bash
+#!/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
+```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`** - 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
+
+# Performance-optimized
+code2llm ./ -m static -f toon --strategy quick
+
+# Refactoring-focused
+code2llm ./ -f toon,evolution --refactor
+```
+
+### Output Customization
+```bash
+# 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

code2llm-0.5.6/README.md

@@ -0,0 +1,308 @@
+# 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 |
+
+### 🤖 LLM-Ready Documentation
+
+| File | Format | Purpose | Use Case |
+|------|--------|---------|----------|
+| `context.md` | **Markdown** | **📖 LLM narrative** - Architecture summary | Paste into ChatGPT/Claude for code analysis |
+| `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
+
+### 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
+
+# Memory-limited analysis
+code2llm ./ -f all --max-memory 500
+
+# Skip PNG generation (faster)
+code2llm ./ -f all --no-png
+```
+
+### Refactoring Focus
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```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
+
+# Focus on specific issues
+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)
+- **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
+```bash
+#!/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
+```bash
+#!/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
+```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`** - 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
+
+# Performance-optimized
+code2llm ./ -m static -f toon --strategy quick
+
+# Refactoring-focused
+code2llm ./ -f toon,evolution --refactor
+```
+
+### Output Customization
+```bash
+# 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