Greptile, przegląd kodu z kontekstem repozytorium

Greptile, przegląd kodu, który zna resztę repozytorium

Większość narzędzi do automatycznego przeglądu kodu patrzy na sam diff. Widzi, co się zmieniło, i komentuje to w oderwaniu od reszty, przez co wyłapuje literówki i pomija rzeczy istotne: zmianę, która psuje wywołanie w innym pliku, albo poprawkę cofającą wcześniejszy fix.

Greptile podchodzi do tego inaczej. Przed przeglądem indeksuje całe repozytorium do grafu opisującego funkcje, klasy, zmienne i powiązania między nimi, a potem prześledza zależności zmienionego kodu przez kolejne pliki. Efekt jest taki, że uwagi dotyczą skutków zmiany, a nie jej wyglądu.

Na czym polega różnica

Przegląd oparty wyłącznie na diffie odpowiada na pytanie „czy ten fragment wygląda poprawnie". Przegląd oparty na grafie odpowiada na pytanie „czy ta zmiana psuje coś w innym miejscu".

To rozróżnienie widać na konkretnych przypadkach. Zmiana sygnatury funkcji wywołanej w siedmiu miejscach jest w diffie jedną linią, a jej skutki leżą w siedmiu plikach, których w diffie nie ma. Usunięcie sprawdzenia wartości pustej wygląda niewinnie, dopóki nie zobaczy się, że jedyne wywołanie tej funkcji przychodzi z miejsca, gdzie wartość pusta jest normalna.

Narzędzie potrafi też sięgnąć do historii zmian, więc rozpoznaje sytuację, w której nowa poprawka cofa coś, co wcześniej naprawiono świadomie. To jedna z tych rzeczy, których człowiek w przeglądzie zwykle nie zauważy, bo nie pamięta zmiany sprzed pół roku.

Konsekwencją tego podejścia jest indeksowanie. Repozytorium trzeba przeanalizować raz przy podłączeniu i aktualizować przy zmianach, co przy dużym projekcie zajmuje chwilę i wymaga dostępu do kodu.

Jak to działa w praktyce

Podłączenie polega na instalacji aplikacji w organizacji na platformie hostingu kodu i wskazaniu repozytoriów. Od tego momentu każda nowa propozycja zmian dostaje komentarze.

Ważniejsza od samego podłączenia jest konfiguracja tego, o czym narzędzie ma mówić. Domyślnie komentuje wszystko, co uzna za warte uwagi, a to przy pierwszym uruchomieniu na starszym repozytorium potrafi dać kilkadziesiąt uwag do jednej zmiany.

Ustawienia leżą w pliku greptile.json w katalogu głównym repozytorium i mają pierwszeństwo przed ustawieniami organizacji z panelu. Czytane są z gałęzi źródłowej propozycji zmian, więc zmianę konfiguracji da się przetestować w tej samej propozycji, w której ją wprowadzasz.

Obok tego pliku istnieje nowszy format, katalog .greptile/ z plikiem config.json. Przyjmuje te same pola, a dokłada ustawienia dziedziczone per katalog, co w monorepo pozwala zaostrzyć przegląd tylko w jednym pakiecie. Jeśli w tym samym katalogu leżą oba, katalog wygrywa i greptile.json jest pomijany. Sam greptile.json nadal działa, więc poniższe przykłady zachowują ważność.

{
  "instructions": "Nie zglaszaj uwag o formatowaniu, mamy automatyczny formater. Zawsze sprawdzaj, czy nowe zapytanie do bazy ma indeks.",
  "commentTypes": ["logic", "syntax"],
  "ignorePatterns": "legacy/**\n*.generated.ts",
  "strictness": 2,
  "triggerOnDrafts": false
}

Pole instructions przyjmuje zwykły język i działa lepiej niż sama lista wyłączonych kategorii, bo pozwala opisać, co w Twoim projekcie jest ważne. Zespół, który ma automatyczny formater, nie potrzebuje uwag o odstępach, a zespół po incydencie z brakującym indeksem chce je widzieć przy każdej zmianie.

Warto poświęcić pierwszy tydzień na dopracowanie reguł. Narzędzie zgłaszające dziesięć uwag, z których siedem jest nietrafionych, zostanie zignorowane przez zespół w ciągu miesiąca i to jest najczęstszy powód nieudanych wdrożeń.

Czego szukać w wynikach

Automatyczny przegląd ma trzy poziomy przydatności i warto je rozróżniać, bo wpływają na to, jak zespół traktuje uwagi.

Poziom pierwszy to rzeczy, które wyłapie każdy sprawdzacz składni: nieużywana zmienna, brakujący typ, niespójne nazewnictwo. Wartość jest niewielka, bo te rzeczy powinien łapać potok budowania, i to zanim ktokolwiek otworzy propozycję zmian.

Ten poziom da się po prostu wyłączyć. Pole commentTypes przyjmuje cztery wartości, logic, syntax, style i info, i domyślnie włączone są wszystkie. Podanie listy zastępuje ten domyślny zestaw, więc zostawienie samego logic sprawia, że narzędzie milczy o składni, stylu i uwagach kontekstowych, a odzywa się wyłącznie przy logice.

{
  "commentTypes": ["logic"],
  "strictness": 3
}

Pole strictness przyjmuje wartości od jednego do trzech, gdzie jeden oznacza zgłaszanie wszystkiego, a trzy tylko rzeczy krytycznych. Domyślna dwójka jest dobrym startem, a trójka ratuje wdrożenie tam, gdzie zespół już przestał czytać komentarze.

Poziom drugi to błędy logiczne widoczne w kontekście: nieobsłużony przypadek brzegowy, zapytanie bez indeksu, wywołanie mogące zwrócić wartość pustą bez sprawdzenia. Tu leży główna wartość narzędzia i to na tym poziomie warto mierzyć jego skuteczność.

Poziom trzeci to uwagi o architekturze i zamyśle. Narzędzie może zauważyć, że nowa funkcja duplikuje istniejącą, ale nie wie, dlaczego zespół zdecydował się na duplikację. Tych uwag nie traktuj jako wiążących, tylko jako pytanie do rozważenia.

Praktyczny wniosek: nie ustawiaj narzędzia jako blokującego scalenie. Automatyczny przegląd jest sitem wstępnym, a decyzja należy do człowieka, który zna kontekst biznesowy.

Wdrożenie w zespole

Narzędzie włączone bez przygotowania zwykle kończy się tym, że po miesiącu nikt nie czyta jego uwag. Kilka kroków zmienia ten wynik.

Pierwszy to podłączenie jednego repozytorium, nie wszystkich naraz. Wybierz projekt aktywny, ale nie krytyczny, i przez dwa tygodnie obserwuj, co narzędzie zgłasza.

Drugi to prowadzenie prostej listy: przy każdej uwadze notujesz, czy była trafna, nietrafna czy nieistotna. Po dwudziestu propozycjach zmian masz liczbę, na której da się oprzeć decyzję o rozszerzeniu na resztę repozytoriów.

Trzeci to dopisywanie reguł na bieżąco. Każda uwaga nietrafiona to kandydat na regułę mówiącą, żeby o tym nie pisać. Każdy błąd przepuszczony to kandydat na regułę mówiącą, żeby na to zwracać uwagę.

Reguły da się przy tym zawęzić do katalogu albo do typu pliku, zamiast nakładać je na całe repozytorium. To istotne w projekcie, gdzie część kodu ma inne wymagania niż reszta.

{
  "customContext": {
    "rules": [
      { "scope": ["src/api/**/*.ts"], "rule": "Kazda trasa musi walidowac wejscie schematem" },
      { "scope": ["src/db/**"], "rule": "Zapytanie bez indeksu zglaszaj zawsze" },
      { "scope": ["**/*.test.ts"], "rule": "Nie komentuj powtorzen w testach" }
    ]
  }
}

Pole scope przyjmuje wzorce ścieżek z gwiazdkami i klamrami, więc jedną regułą obejmiesz kilka katalogów naraz. Narzędzie czyta przy okazji pliki z wytycznymi leżące już w repozytorium, na przykład te dla asystentów kodu, więc część kontekstu masz bez przepisywania.

Czwarty to ustalenie, kto odpowiada za uwagi. Bez tego komentarze automatu wiszą nierozpatrzone, bo każdy zakłada, że zajmie się nimi ktoś inny. Najprostsza zasada mówi, że autor zmiany rozstrzyga każdą uwagę: poprawia albo odpowiada, dlaczego nie.

Piąty to przegląd po kwartale. Repozytorium się zmienia, więc reguły napisane na starcie mogą przestać pasować, a część uwag, które kiedyś były szumem, może stać się istotna.

Co to znaczy dla procesu przeglądu

Automatyczny przegląd zmienia rozkład pracy recenzenta, a nie ilość tej pracy. Rzeczy techniczne przechodzą przez sito wcześniej, więc człowiek może zająć się tym, czego automat nie widzi.

Trzy pytania zostają po stronie ludzi niezależnie od narzędzia. Czy ta zmiana rozwiązuje właściwy problem, bo poprawnie napisany kod robiący nie to, co trzeba, przejdzie każdy automatyczny przegląd. Czy pasuje do kierunku, w którym idzie projekt, bo automat nie zna planów zespołu. Czy koszt utrzymania jest akceptowalny, bo to ocena, nie fakt.

Warto też pamiętać, że automatyczny przegląd nie zwalnia z testów. Uwaga o nieobsłużonym przypadku brzegowym jest cenna, ale to test pilnuje, żeby ten przypadek nie wrócił za pół roku. Narzędzia pokroju Vitest i automat do przeglądu pracują na różnych warstwach i nie zastępują się nawzajem.

Przy zespołach używających asystenta kodu, na przykład Cursora, pojawia się jeszcze jeden efekt. Kodu powstaje więcej i szybciej, więc wąskim gardłem staje się przegląd, a nie pisanie. To właśnie ta zmiana proporcji sprawia, że automatyczny przegląd zaczął mieć sens ekonomiczny.

Ceny

Jednostką rozliczenia jest kredyt, a nie propozycja zmian. Jeden ukończony zwykły przegląd to jeden kredyt, jeden przegląd z uruchomieniem kodu w wariancie T-Rex to trzy kredyty. Pominięte przeglądy nie liczą się wcale.

Miejsca liczy się po aktywnych programistach, czyli autorach, którzy w danym okresie rozliczeniowym dostali choć jeden ukończony przegląd. Osoba, która w tym miesiącu nie otworzyła nic wymagającego przeglądu, nie generuje kosztu.

Po wyczerpaniu 50 kredytów przypisanych do konkretnego autora każdy kolejny jego przegląd wchodzi w rozliczenie nadwyżkowe po 1 USD za kredyt. Pula nie jest wspólna dla zespołu: każdy autor zużywa najpierw własne 50 kredytów, więc jedna osoba otwierająca sto propozycji nie zjada limitu pozostałym.

Górny pułap tych nadwyżek ustawia się w ustawieniach organizacji. Po osiągnięciu progu Greptile pomija przeglądy, które wygenerowałyby dodatkowy koszt, aż do końca okresu rozliczeniowego albo do podniesienia limitu, a autorzy mieszczący się jeszcze we własnych 50 kredytach dostają przeglądy dalej. Limit ustawiony na zero wyłącza nadwyżki całkowicie.

Poza cennikiem stoją dwa rabaty. Projekty otwartoźródłowe na licencji MIT albo Apache mogą dostać narzędzie za darmo po zgłoszeniu, a startupy przed rundą A z przychodem poniżej dwóch milionów dolarów w ostatnich dwunastu miesiącach mają połowę ceny. Rozliczenie roczne i wieloletnie wyceniane jest indywidualnie, bez podanej z góry stawki.

Przy szacowaniu kosztu policz nie liczbę etatów, tylko liczbę przeglądów miesięcznie. Zespół dziesięcioosobowy otwierający dwieście propozycji generuje inne zużycie niż zespół tej samej wielkości otwierający czterdzieści.

Warto też porównać ten koszt z czasem przeglądu po stronie ludzi. Jeśli narzędzie wyłapuje jeden realny błąd na dwadzieścia propozycji, a naprawa błędu na produkcji kosztuje dzień pracy, rachunek zamyka się szybko. Jeśli wyłapuje wyłącznie literówki, nie zamyka się wcale.

Greptile kontra alternatywy

Ostatni wiersz to nie konkurencja, tylko fundament. Formater, sprawdzacz składni i kontrola typów powinny działać w potoku budowania niezależnie od tego, jakie narzędzie do przeglądu wybierzesz. Bez nich automatyczny przegląd traci czas na rzeczy, które maszyna rozstrzyga bez modelu językowego.

Wybór między pierwszymi wierszami zależy od wielkości repozytorium. Przy małym projekcie różnica między przeglądem opartym na diffie a opartym na grafie jest niewielka, bo cały kod i tak mieści się w kontekście. Przy repozytorium na kilkaset tysięcy linii ta różnica decyduje o tym, czy uwagi są trafne.

Drugim czynnikiem jest stawka. Przy aplikacji wewnętrznej używanej przez dziesięć osób błąd przepuszczony do produkcji kosztuje godzinę. Przy systemie obsługującym płatności ten sam błąd kosztuje znacznie więcej, więc opłaca się narzędzie skuteczniejsze, choćby droższe.

Trzecim jest to, gdzie kod może się znaleźć. Wszystkie powyższe warianty wysyłają zmieniony fragment do dostawcy, więc jeśli firmowa polityka tego zabrania, zostaje wdrożenie u siebie. Qodo daje tu otwarty silnik przeglądu uruchamiany w kontenerze z własnymi kluczami, z zastrzeżeniem, że projekt został wyprowadzony spod skrzydeł firmy i jest utrzymywany przez społeczność jako rozwiązanie zastane, a płatna oferta stoi na innym silniku.

Warto też przetestować dwa narzędzia równolegle przez dwa tygodnie na tym samym repozytorium. Porównanie uwag do tych samych propozycji zmian daje odpowiedź, której nie zastąpi żadne zestawienie, bo skuteczność zależy od języka programowania i stylu projektu.

Bezpieczeństwo i dostęp do kodu

Narzędzie indeksujące repozytorium ma dostęp do całego kodu, więc przed wdrożeniem w firmie warto ustalić kilka rzeczy.

Pierwsza to zakres uprawnień. Aplikacja instalowana w organizacji dostaje dostęp do wskazanych repozytoriów, a nie do wszystkich domyślnie. Warto zacząć od jednego i rozszerzać świadomie, zamiast nadawać dostęp na poziomie całej organizacji od razu.

Druga to miejsce przechowywania indeksu. Graf powstaje po stronie usługi, więc kod fizycznie tam trafia. Przy wymogach zgodności trzeba sprawdzić, gdzie leżą te dane i jak długo są przechowywane, a przy ostrzejszych wymogach rozważyć wariant wdrażany we własnej infrastrukturze.

Trzecia to sekrety w repozytorium. Jeśli w historii zmian leżą klucze wpisane kiedyś przez pomyłkę, indeksowanie obejmie także je. To dobry moment, żeby przejrzeć historię i zrotować to, co trzeba, niezależnie od wyboru narzędzia.

Czwarta to katalogi, które warto wykluczyć. Wygenerowany kod, dane testowe i katalogi zewnętrznych zależności nie wnoszą nic do przeglądu, a powiększają indeks i wydłużają analizę.

Wyłączenia zapisujesz w tym samym pliku konfiguracyjnym, składnią znaną z pliku ignorowanych ścieżek w systemie kontroli wersji.

{
  "ignorePatterns": "**/node_modules/**\n**/*.snap\n**/generated/**\ninfra/secrets/**",
  "excludeAuthors": ["dependabot[bot]"]
}

Drugie pole rozwiązuje osobny problem: propozycje zmian otwierane przez automat aktualizujący zależności nie potrzebują przeglądu, a przy dziesięciu takich tygodniowo generują koszt i szum. To samo dotyczy propozycji roboczych, o ile nie włączysz ich świadomie.

Typowe błędy

Pierwszy to włączenie narzędzia bez reguł. Zespół dostaje wtedy kilkadziesiąt uwag do pierwszej propozycji zmian, uznaje je za szum i przestaje czytać.

Drugi to ustawienie przeglądu jako warunku scalenia. Automat nie zna kontekstu biznesowego, więc blokowanie zmiany na podstawie jego uwagi prowadzi do obchodzenia zabezpieczenia, a nie do lepszego kodu.

Trzeci to rezygnacja ze sprawdzaczy statycznych. Narzędzie oparte o model językowy nie zastąpi formatera ani kontroli typów, a marnowanie go na te zadania jest kosztowne i mniej skuteczne.

Czwarty to brak pomiaru skuteczności. Warto przez miesiąc notować, ile uwag było trafnych, bo bez tej liczby decyzja o przedłużeniu opiera się na wrażeniach.

Piąty to podłączenie repozytoriów zawierających dane wrażliwe bez sprawdzenia warunków. Narzędzie indeksuje kod, więc przy wymogach zgodności trzeba wiedzieć, gdzie ten indeks żyje.

Szósty to traktowanie automatycznego przeglądu jako zamiennika przeglądu ludzkiego. To sito wstępne, które oszczędza czas recenzenta, a nie decydent w sprawach projektowych.

FAQ

Czym Greptile różni się od innych narzędzi do przeglądu kodu?

Przed przeglądem indeksuje całe repozytorium do grafu powiązań, więc analizuje skutki zmiany w innych plikach, a nie tylko sam diff. To przekłada się na wykrywanie błędów logicznych wynikających z zależności, których w zmienionym fragmencie nie widać.

Ile kosztuje Greptile?

Plan Starter jest darmowy dla jednego aktywnego programisty i daje 50 kredytów miesięcznie. Plan Pro kosztuje 30 dolarów za miejsce miesięcznie i również zawiera 50 kredytów na miejsce, a każdy kolejny przegląd tego samego autora kosztuje dolara. Enterprise wyceniany jest indywidualnie.

Czy zastępuje przegląd wykonywany przez człowieka?

Nie. Wyłapuje błędy techniczne i skutki zmian w innych plikach, ale nie zna kontekstu biznesowego ani powodów wcześniejszych decyzji zespołu. Właściwy układ to automat jako sito wstępne i człowiek jako decyzja.

Czy działa z GitLabem?

Tak, obsługuje zarówno GitHub, jak i GitLab, a przegląd pojawia się jako komentarze w propozycji zmian. Konfiguracja polega na instalacji aplikacji w organizacji i wskazaniu repozytoriów do indeksowania.

Jak ograniczyć liczbę nietrafionych uwag?

Przez reguły opisane zwykłym językiem: co ignorować, na co zwracać uwagę i które katalogi pominąć. Pierwszy tydzień warto poświęcić na ich dopracowanie, bo narzędzie zgłaszające dużo szumu przestaje być czytane, a wtedy nie ma znaczenia, jak dobre są pozostałe uwagi.

Dokumentacja stoi na stronie projektu, a porównania z innymi narzędziami znajdziesz w zestawieniu narzędzi do przeglądu kodu.