Tworzenie interaktywnej mapy kodu z Codex

Tworzenie interaktywnej mapy kodu z Codex

Poproś Codex o utworzenie interaktywnej mapy repozytorium, a następnie oznacz, które moduły uległy zmianie od momentu jej wygenerowania.

Klikając na dowolny moduł, możesz zobaczyć jego komponenty wywołujące, zależności, główne przepływy wykonania, powiązane testy oraz dane wspierające pochodzące z kodu źródłowego.

Codex generuje następujące pliki:

• docs/codemap/codemap.html
• docs/codemap/codemap.json
• docs/codemap/codemap.lock

Pełny prompt

Przeanalizuj bieżącą bazę kodu. Nie modyfikuj kodu produktowego. Twórz lub aktualizuj wyłącznie pliki w katalogu docs/codemap/.

Ignoruj katalogi vendor, build, dist, cache oraz inne katalogi generowane automatycznie.

Jeśli katalog docs/codemap/ już istnieje, najpierw porównaj istniejący plik codemap.lock z aktualnym stanem repozytorium i wypisz moduły, które uległy zmianie. Następnie wygeneruj ponownie te trzy pliki jednocześnie:

1. docs/codemap/codemap.html
   Zbuduj w pełni samodzielną, interaktywną mapę kodu, którą można otworzyć bezpośrednio w przeglądarce. Mapa powinna zawierać:

   • główne moduły, usługi, bazy danych, kolejki i zależności zewnętrzne,
   • nie więcej niż 20 węzłów głównych; pliki niskopoziomowe grupuj pod macierzystym modułem,
   • połączenia i przepływy danych między modułami,
   • 3–5 najważniejszych przepływów end-to-end,
   • domyślnie wyraźny ciemny motyw,
   • granice systemu i najważniejsze przepływy danych widoczne na pierwszym ekranie,
   • kolorowe oznaczenia typów modułów wraz z prostą legendą,
   • automatyczny układ minimalizujący przecięcia krawędzi,
   • po kliknięciu modułu podświetlenie jego wywołań upstream, zależności downstream, powiązanych testów oraz przepływów, w których uczestniczy,
   • po wyborze przepływu podświetlenie jego pełnej ścieżki,
   • kontrolki wyszukiwania, filtrowania, zoomu i przeciągania.

   Na górze strony wyświetl nazwę repozytorium, czas generowania oraz commit, z którego mapa została wygenerowana.

2. docs/codemap/codemap.json
   Użyj następującej struktury:

   JSON

   Скопіювати

   {
     "generated_at": "",
     "generated_from_commit": "",
     "scope": [],
     "nodes": [],
     "edges": [],
     "flows": []
   }
   

   Każdy węzeł musi zawierać:

   • id,
   • path (ścieżka),
   • role (rola),
   • entrypoints (punkty wejścia),
   • tests (testy),
   • constraints (ograniczenia),
   • evidence (dowody).

   Każda krawędź musi zawierać:

   • from (źródło),
   • to (cel),
   • type (typ),
   • evidence (dowody).

   Pole type może przyjmować wyłącznie wartości:

   • imports (importy),
   • calls (wywołania),
   • reads (odczyty),
   • writes (zapisy),
   • publishes (publikacje),
   • subscribes (subskrypcje).

   Każdy przepływ musi zawierać:

   • trigger (wyzwalacz),
   • steps (kroki),
   • outcome (wynik).

   Każdy krok musi odnosić się do istniejącego id węzła. Do każdego węzła i krawędzi dołącz pasującą ścieżkę źródłową oraz symbol. Oznacz każdą relację bez dowodu źródłowego jako „unknown” (nieznana). Nie zgaduj.

3. docs/codemap/codemap.lock
   Użyj parsowalnego JSON-a do zapisania:

   • aktualnego commita,
   • informacji o tym, czy drzewo robocze ma niezatwierdzone zmiany,
   • czasu generowania,
   • skanu zakresu,
   • wykluczonych katalogów,
   • algorytmu fingerprintingu,
   • deterministycznego fingerprintu dla każdego modułu najwyższego poziomu, obliczonego na podstawie ścieżek śledzonych plików i ich aktualnej zawartości.

   Jeśli nie znaleziono istniejącego pliku codemap.lock, traktuj każdy moduł jako nowy i wygeneruj pełną mapę.

   Po zakończeniu zweryfikuj, że:

   • codemap.json poprawnie się parsuje,
   • każda ścieżka węzła istnieje, a każdy symbol dowodowy można znaleźć w źródle,
   • każda krawędź i krok przepływu odnoszą się do istniejącego węzła,
   • codemap.html i codemap.json używają tych samych węzłów, krawędzi i przepływów,
   • codemap.lock odpowiada aktualnemu commitowi, stanowi drzewa roboczego i fingerprintom modułów,
   • każda relacja bez dowodu źródłowego jest oznaczona jako „unknown”.

   Te trzy pliki muszą być zawsze generowane razem na podstawie aktualnego stanu repozytorium. Nigdy nie edytuj ręcznie tylko jednego z nich.

   Na koniec wyświetl:

   • utworzone lub zmodyfikowane pliki,
   • przestarzałe moduły,
   • pozostałe elementy oznaczone jako „unknown”,
   • wyniki walidacji,
   • pełny diff.

Dodatkowa zasada

Dodaj regułę w pliku AGENTS.md, aby utrzymać mapę kodu zawsze zsynchronizowaną z repozytorium:

Na początku każdego zadania zmieniającego kod, porównaj aktualny stan repozytorium z plikiem docs/codemap/codemap.lock.

Przed modyfikacją modułu użyj pliku docs/codemap/codemap.json, aby odpowiedzieć na trzy pytania:

1. Co go wywołuje?
2. Na co on wpływa?
3. Jakie testy go pokrywają?

Jeśli mapa jest przestarzała lub nie pozwala odpowiedzieć na te pytania, wygeneruj ponownie codemap.html, codemap.json i codemap.lock przed wprowadzeniem zmian w kodzie.

Zawsze, gdy zmienią się granice modułów, zależności, trasy, bazy danych, kolejki lub główne przepływy danych, aktualizuj mapę kodu w tym samym commicie co kod.

Dlaczego to ważne: To podejście pomaga zachować aktualność dokumentacji kodu, co jest kluczowe dla pracy zespołowej i redukuje ryzyko błędów przy wprowadzaniu zmian. Interaktywna mapa kodu upraszcza zrozumienie struktury projektu.