Graf kodu i testy mutacyjne w projekcie Monolynx

Po co projektowi graf kodu i testy mutacyjne?

Agent, który pisze kod, potrzebuje dwóch informacji, których nie da mu sam plik. Pierwsza: kto korzysta z funkcji, którą właśnie zmienia. Druga: czy zielone testy coś znaczą. Graf kodu odpowiada na pierwsze pytanie, a testy mutacyjne na drugie.

Jak zasilić graf kodu?

Graf powstaje w dwóch krokach. Najpierw narzędzie graphify czyta pliki źródłowe i zapisuje wynik do pliku graphify-out/graph.json. Potem skrypt cicd/sync_graph.py zamienia ten plik na węzły i krawędzie Monolynx i wysyła je na platformę.

flowchart LR
  A["Pliki źródłowe"] --> B["graphify update"]
  B --> C["graphify-out/graph.json"]
  C --> D["cicd/sync_graph.py"]
  D --> E["Graf projektu w Monolynx"]
  E --> F["Moduł Połączenia w panelu"]
  E --> G["Agenci: ticket-create, work"]

Ręcznie: /monolynx:graph-sync

Komenda prowadzi przez cały proces za rękę. Dobra na pierwszy raz i dla projektu bez CI.

1. Sprawdzenie graphify

   Komenda sprawdza, czy narzędzie jest zainstalowane. Gdy go brakuje, podaje polecenie instalacji dla Twojego systemu i czeka na zgodę.

2. Plik wykluczeń

   Komenda sprawdza albo proponuje plik .graphifyignore, który pomija testy, migracje, dokumentację i kod zewnętrzny.

3. Ekstrakcja

   Polecenie graphify update . buduje graf lokalnie z samej składni plików.

4. Przebieg próbny

   Skrypt synchronizacji uruchomiony z flagą --dry-run pokazuje liczby węzłów i krawędzi, ale niczego nie wysyła.

5. Wysyłka po Twojej zgodzie

   Komenda uprzedza, że wysyłka podmienia cały graf projektu, i czeka na potwierdzenie.

$ uv tool install graphifyy
$ graphify --version
$ graphify update .
$ python cicd/sync_graph.py --dry-run
$ python cicd/sync_graph.py

Skrypt cicd/sync_graph.py nie jest częścią Twojego repozytorium, dopóki go nie wygenerujesz. Tworzy go komenda /monolynx:create-graph-ci-script, a gdy pliku brakuje, /monolynx:graph-sync generuje go sam według tej samej specyfikacji.

Automatycznie: /monolynx:create-graph-ci-script

Ta komenda dodaje do CI krok, który odświeża graf po każdym merge do gałęzi głównej. Wykrywa system CI (GitLab, GitHub Actions, Bitbucket albo Jenkins), tworzy plik wykluczeń i skrypt synchronizacji, a potem dopisuje krok.

sync-graph:
  stage: deploy
  allow_failure: true
  script:
    - command -v graphify || { echo "graphify nie zainstalowane na runnerze"; exit 0; }
    - graphify update .
    - python cicd/sync_graph.py
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: on_success

Krok ma trzy cechy, które warto znać przed uruchomieniem.

Jak działają testy mutacyjne?

Narzędzie mutacyjne wprowadza do kodu drobny błąd, na przykład zamienia >= na >, i uruchamia testy. Gdy któryś test pada, mutant został wykryty. Gdy wszystkie testy są zielone, mutant przeżył: w tym miejscu kod można zepsuć, a testy tego nie zauważą.

> /monolynx:mutation-check

Mutacje (diff względem 4f2a9c1): 4 przeżyło / 17 mutantów

| plik:linia            | mutator             | oryginał -> mutant |
| src/rozliczenia.py:88 | ConditionalBoundary | >= -> >            |

Komenda ma dwa tryby. Wybiera je argument.

Skąd komenda zna polecenie?

Komenda niczego nie zgaduje. Polecenie, ścieżkę raportu i jego format czyta z sekcji ## Mutacje strony wiki toolchain. Tę sekcję zapisuje komenda /monolynx:project-toolchain, która wykrywa narzędzie pasujące do języka projektu.

Plugin nie instaluje narzędzia mutacyjnego. Gdy sekcji brakuje albo narzędzie nie jest zainstalowane, komenda mówi to wprost, odsyła do /monolynx:project-toolchain i kończy pracę.

Co się dzieje z mutantem, który przeżył?

Mutant, który przeżył, jest brakującym przypadkiem testowym, a nie wynikiem do poprawienia. Komenda najpierw czyta kod wokół wskazanej linii, nazywa niesprawdzane zachowanie, a potem pyta, co z tym zrobić.

Jak dodać testy mutacyjne do CI?

Komenda /monolynx:create-mutation-ci-script dodaje osobny etap CI, który działa tylko na merge requestach i liczy mutacje na zmianie. Raport narzędzia trafia do artefaktów. Etap kopiuje też do katalogu cicd/ dwa skrypty: jeden sprowadza raport do wspólnego formatu, drugi porównuje wynik z zapisaną wartością bazową.

Porównanie działa jak zapadka: wartość bazowa może tylko rosnąć.

Najczęstsze pytania

Słownik i następny krok

Graf kodu

mapa plików, klas i funkcji projektu oraz powiązań między nimi

Graphify

zewnętrzne narzędzie, które buduje graf z analizy składni plików

Węzeł

element grafu: plik, klasa, metoda, funkcja, stała albo moduł

Krawędź

powiązanie między węzłami, na przykład wywołanie albo import

Mutant

kopia kodu z jedną celowo wprowadzoną zmianą

Mutant, który przeżył

zmiana, której nie wykrył żaden test

Wartość bazowa

zapisany wynik mutacji, z którym porównuje się kolejne przebiegi

Zapadka

zasada, że wartość bazowa może tylko rosnąć

Toolchain

strona wiki z poleceniami lintu, testów i mutacji projektu

Stronę toolchain i resztę konfiguracji opisuje wpis Pierwszy projekt w Monolynx. Miejsce obu komend wśród pozostałych pokazuje Mapa pluginu Monolynx.