feat: initial commit

2026-08-29 13:17:59 +02:00
commit 142f5f5759
91 changed files with 6155 additions and 0 deletions
@@ -0,0 +1,39 @@
+# ADR-0002: Deterministycznie tyle, ile się da; model tylko na resztę
+
+- Status: przyjęty
+- Data: 2026-08-28
+
+## Kontekst
+
+Migracja SDK to w większości mechaniczne podmiany. Powierzenie ich modelowi kosztuje tokeny,
+wydłuża przebieg i wprowadza wariancję tam, gdzie wariancja jest czystą stratą -
+nikt nie chce, żeby dwa uruchomienia dawały inny diff dla tej samej zmiany nazwy metody.
+
+## Decyzja
+
+Dzielimy pracę wzdłuż linii "czy da się to zrobić kodem":
+
+1. Wykrycie ekosystemu, plików zależności i komendy testowej - adapter (`adapters/`).
+2. Podbicie deklaracji wersji - adapter.
+3. Migracja objęta regułami - silnik reguł czytający `*.codemod.yaml` z pakietu APM.
+4. Reszta - agent `coder` z LLM.
+5. Ocena wyniku - agent `reviewer` **oraz** niezależna kontrola mechaniczna.
+
+Reguły codemod są częścią pakietu APM (leżą obok notatki migracyjnej), więc podlegają
+temu samemu przeglądowi i wersjonowaniu co wiedza dla modelu.
+
+## Konsekwencje
+
+**Pozytywne**
+
+- Powstaje tryb `--offline`: ta sama topologia bez modelu. Smoke test całego pipeline'u
+  na każdym MR, bez GPU i bez internetu.
+- Punkt odniesienia: widać, ile przypadków model faktycznie dołożył ponad reguły.
+- Mniejszy koszt i krótszy przebieg dla typowych migracji.
+
+**Negatywne**
+
+- Dwie ścieżki do utrzymania (`RuleBrain`, `LlmBrain`) i wspólny kontrakt między nimi.
+- Reguły regexowe mają znane ograniczenia (zmiany strukturalne, wieloliniowe konteksty).
+  Świadomie nie budujemy własnego silnika AST - od tego są narzędzia dziedzinowe
+  (OpenRewrite, jscodeshift), które można podpiąć jako kolejny adapter.