REFACTORING_PLAN.md

Plan Refaktoryzacji code2llm (v0.4.0)

Podsumowanie Zmian

Refaktoryzacja monolitycznego flow.py (1145 linii) w modularną paczkę Python, wprowadzenie taksonomii 4 formatów (v0.3.0), a następnie:

• Rename: code2flow → code2llm (v0.4.0)
• Cleanup: usunięcie martwego kodu (optimization/, visualizers/)
• Reorganizacja: generatory przeniesione do generators/ subpakietu
• Testy: nazwy sprint-based → feature-based

Aktualna Struktura (v0.6.0)

code2llm/
├── code2llm/                  # Główna paczka
│   ├── __init__.py            # Eksportuje publiczne API
│   ├── __main__.py            # Entry point: python -m code2llm
│   ├── cli.py                 # CLI: code2llm (map,toon,flow,context,all)
│   ├── core/                  # Klasy bazowe i konfiguracja
│   │   ├── __init__.py
│   │   ├── config.py          # Config, ANALYSIS_MODES, NODE_COLORS
│   │   ├── models.py          # FlowNode, FlowEdge, DataFlow, AnalysisResult
│   │   ├── analyzer.py        # ProjectAnalyzer - główny orchestrator
│   │   ├── streaming_analyzer.py  # StreamingAnalyzer z priorytetyzacją
│   │   ├── core/              # Subpackage: file analysis internals (v0.6.0)
│   │   │   ├── __init__.py    # Re-exports: FileCache, FastFileFilter, FileAnalyzer, RefactoringAnalyzer
│   │   │   ├── cache.py       # FileCache
│   │   │   ├── file_filter.py # FastFileFilter
│   │   │   ├── file_analyzer.py # FileAnalyzer (AST parsing)
│   │   │   └── refactoring.py # RefactoringAnalyzer
│   │   └── streaming/         # Subpackage: streaming internals (v0.6.0)
│   │       ├── __init__.py    # Re-exports: StreamingScanner, SmartPrioritizer, etc.
│   │       ├── scanner.py     # StreamingScanner
│   │       ├── prioritizer.py # SmartPrioritizer
│   │       └── incremental.py # IncrementalAnalyzer
│   ├── analysis/              # Moduły analizy
│   │   ├── call_graph.py      # CallGraphExtractor
│   │   ├── cfg.py             # CFGExtractor - Control Flow Graph
│   │   ├── coupling.py        # CouplingAnalyzer
│   │   ├── data_analysis.py   # DataAnalyzer
│   │   ├── dfg.py             # DFGExtractor - Data Flow Graph
│   │   ├── pipeline_detector.py # PipelineDetector (networkx, method→method edges)
│   │   ├── side_effects.py    # SideEffectDetector
│   │   ├── type_inference.py  # TypeInference (AST-based, dispatch dict)
│   │   └── smells.py          # SmellDetector
│   ├── exporters/             # Eksport do formatów (9 eksporterów)
│   │   ├── __init__.py
│   │   ├── base.py            # Exporter ABC
│   │   ├── toon/              # Package: ToonExporter (v0.6.0, was toon.py)
│   │   │   ├── __init__.py    # ToonExporter facade
│   │   │   ├── renderer.py    # ToonRenderer (CC-split sub-methods)
│   │   │   ├── metrics.py     # MetricsComputer
│   │   │   ├── helpers.py     # Helper functions
│   │   │   └── module_detail.py # ModuleDetailRenderer
│   │   ├── toon.py            # backward-compat shim → toon/ package
│   │   ├── map_exporter.py    # MapExporter → map.toon (struktura)
│   │   ├── flow_exporter.py   # FlowExporter → flow.toon (data-flow)
│   │   ├── context_exporter.py # ContextExporter → context.md (LLM)
│   │   ├── llm_exporter.py    # backward-compat shim → ContextExporter
│   │   ├── yaml_exporter.py   # YAMLExporter → analysis.yaml
│   │   ├── json_exporter.py   # JSONExporter → analysis.json
│   │   ├── mermaid_exporter.py # MermaidExporter → *.mmd (subpackage grouping)
│   │   ├── evolution_exporter.py # EvolutionExporter → evolution.toon
│   │   └── readme_exporter.py # READMEExporter → README.md
│   ├── generators/            # Generatory
│   │   ├── __init__.py
│   │   ├── llm_flow.py        # LLM flow summary generator
│   │   ├── llm_task.py        # LLM task breakdown generator
│   │   └── mermaid.py         # Mermaid PNG generator
│   ├── nlp/                   # NLP pipeline
│   ├── patterns/              # Detekcja wzorców
│   ├── refactor/              # Silnik refaktoryzacji
│   └── templates/             # Jinja2 templates for refactoring prompts
├── tests/                     # 159 tests, all passing
├── benchmarks/
├── examples/
├── pyproject.toml
├── Makefile
└── README.md

Usunięte

• optimization/ — 1590L martwego kodu (v0.4.0)
• visualizers/ — 150L martwego kodu (v0.4.0)
• core/analyzer_old.py — 765L (v0.6.0)
• core/streaming_analyzer_old.py — 666L (v0.6.0)
• TODO/ — stare pliki migracji (v0.6.0)

Kluczowe Decyzje Architektoniczne

1. Separacja Odpowiedzialności

• core/: Modele danych i główny analyzer
• analysis/: Logika parsowania AST (CFG, DFG, Call Graph, pipelines, side effects)
• exporters/: Formaty wyjściowe (TOON, YAML, JSON, Mermaid, Context)
• generators/: Generatory LLM flow, task, Mermaid PNG
• patterns/: Detekcja wzorców behawioralnych

2. API Publiczne

from code2llm import ProjectAnalyzer, Config
from code2llm.core.models import AnalysisResult

3. CLI

code2llm /path/to/project -m hybrid -o ./output -f toon,map,flow,context,all

4. Konfiguracja

• Config dataclass z opcjami analizy
• ANALYSIS_MODES - dostępne tryby
• NODE_COLORS - kolory dla wizualizacji

Porównanie z Narzędziami Referencyjnymi

Cecha	code2llm	PyCG	Pyan	Angr	Code2Logic
CFG	✓	✓	✗	✓	✓
DFG	✓	✗	✗	✓	✓
Call Graph	✓	✓	✓	✓	✓
Wzorce	✓	✗	✗	✗	✓
LLM Output	✓	✗	✗	✗	✓
Modularność	✓	✓	✓	✗	?

Przyszłe Rozszerzenia

Priorytet Wysoki

1. CI/CD pipeline (GitHub Actions)
2. Type hints (mypy compliant)
3. Obsługa dynamicznej analizy (sys.settrace)

Priorytet Średni

4. Więcej formatów wyjściowych (Graphviz DOT, PlantUML)
5. Interaktywna wizualizacja (D3.js/Plotly)
6. Plugin system dla custom extractors
7. Cache analizy (pickle/JSON)

Priorytet Niski

8. Wsparcie dla Cython
9. Analiza bytecode (dis)
10. Integracja z IDE (VS Code extension)
11. Web UI (Flask/FastAPI)

Komendy Makefile

make install       # pip install -e .
make dev-install   # pip install -e ".[dev]"
make test          # pytest tests/
make lint          # flake8 + black --check
make format        # black code2llm/
make typecheck     # mypy code2llm/
make run           # code2llm ../python/stts_core
make build         # python setup.py sdist bdist_wheel
make clean         # rm -rf build/ dist/
make check         # lint + typecheck + test

Instalacja

pip install -e .
code2llm /path/to/project -v

Użycie Programowe

from code2llm import ProjectAnalyzer, Config
from code2llm.exporters import YAMLExporter

config = Config(mode='hybrid', max_depth_enumeration=10)
analyzer = ProjectAnalyzer(config)
result = analyzer.analyze_project('/path/to/project')

exporter = YAMLExporter()
exporter.export(result, 'output.yaml')  # Default: skip empty values
exporter.export(result, 'output_full.yaml', include_defaults=True)  # Full output

Eksport Danych (Compact by Default)

Wszystkie eksporty YAML/JSON domyślnie ukrywają puste wartości:

• column: null - pomijane
• conditions: [] - pomijane
• data_flow: [] - pomijane
• metadata: {} - pomijane
• returns: null - pomijane

Aby pokazać wszystkie pola (np. dla debugowania):

code2llm /path/to/project --full

Programowo:

result.to_dict()  # Default: False - skip empty values
result.to_dict(include_defaults=True)  # Include all fields

Znane Problemy

1. Dynamic analysis: Wymaga implementacji DynamicTracer w pełni
2. Cross-file resolution: Może nie rozwiązać wszystkich importów
3. Complex control flow: Np. async/await, generators - uproszczona obsługa
4. Performance: Duże projekty (>10k LOC) mogą być wolne

Konwencje Kodu

• PEP 8 z line-length=100
• Type hints dla wszystkich funkcji publicznych
• Docstrings Google style
• Black do formatowania
• isort do importów (opcjonalnie)

Status: ✅ Ukończone (v0.6.0)

• Rename code2flow → code2llm
• Struktura katalogów (reorganizacja generators/)
• Moduły core/ + core/core/ + core/streaming/ subpackages
• Moduły analysis/ (+ pipeline_detector method→method, type_inference dispatch)
• Moduły exporters/ (9 eksporterów + toon/ package, wszystkie podłączone do CLI)
• Moduły generators/ (przeniesione z root-level)
• Usunięcie martwego kodu (optimization/, visualizers/, *_old.py, TODO/)
• CLI (streaming, strategy, refactor, examples)
• setup.py / pyproject.toml
• Makefile
• Testy (159/159 passing)
• Metryki: CC̄=4.7, max-CC=19, 12 pipelines, 0 god modules
• Dokumentacja API (do zrobienia)