Створення інтерактивної карти коду за допомогою Codex

Створення інтерактивної карти коду за допомогою Codex

Попросіть Codex створити інтерактивну карту вашого репозиторію, а потім відзначайте, які модулі змінилися з моменту її генерації.

Натиснувши на будь-який модуль, можна побачити його викликаючі компоненти, залежності, основні потоки виконання, пов'язані тести та підтверджуючі дані з вихідного коду.

Codex створює:

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

Повний промпт

Аналізуйте поточну кодову базу. Не змінюйте код продукту. Створюйте або оновлюйте файли лише в docs/codemap/.

Ігноруйте каталоги vendor, build, dist, cache та інші згенеровані каталоги.

Якщо docs/codemap/ вже існує, спочатку порівняйте існуючий codemap.lock з поточним репозиторієм і перелікуйте модулі, які змінилися. Потім згенеруйте ці три файли разом:

1. docs/codemap/codemap.html
   Створіть повністю самодостатню інтерактивну карту коду, яка відкривається безпосередньо в браузері. Включіть:

   • основні модулі, сервіси, бази даних, черги та зовнішні залежності
   • не більше 20 основних вузлів; групуйте низькорівневі файли під їх батьківським модулем
   • виклики та потоки даних між модулями
   • 3-5 найважливіших кінцевих потоків
   • чітку темну тему за замовчуванням
   • межі системи та найважливіші потоки даних, видимі на першому екрані
   • кольорове кодування типів модулів з простою легендою
   • автоматичну компоновку, яка мінімізує перетворення країв
   • натискання на будь-який модуль підсвічує його викликаючі компоненти, залежності, пов'язані тести та потоки, до яких він належить
   • вибір потоку підсвічує його повний шлях
   • пошук, фільтрацію, масштабування та управління перетягуванням

   На верху покажіть назву репозиторію, час генерації та коміт, з якого він був згенерований.

2. docs/codemap/codemap.json
   Використовуйте цю структуру:

   JSON

   Скопіювати

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

   Кожен вузол повинен включати:

   • id
   • path
   • role
   • entrypoints
   • tests
   • constraints
   • evidence

   Кожен край повинен включати:

   • from
   • to
   • type
   • evidence

   type може бути лише:

   • imports
   • calls
   • reads
   • writes
   • publishes
   • subscribes

   Кожен потік повинен включати:

   • trigger
   • steps
   • outcome

   Кожен крок повинен посилатися на існуючий id вузла. Прикріпіть відповідний шлях джерела та символ до кожного вузла та краю. Позначте будь-які зв'язки без джерельних доказів як невідомі. Не здогадуйтесь.

3. docs/codemap/codemap.lock
   Використовуйте парсований JSON для запису:

   • поточного коміту
   • чи має робоче дерево незбережені зміни
   • час генерації
   • сканований обсяг
   • виключені каталоги
   • алгоритм відбитка
   • детермінований відбиток для кожного верхнього модуля, розрахований з його відстежуваних шляхів файлів та поточного вмісту файлів

   Якщо жоден існуючий codemap.lock не знайдено, вважайте кожен модуль новим і згенеруйте повну карту.

   Коли закінчите, перевірте:

   • codemap.json успішно парситься
   • кожен шлях вузла існує, і кожен символ доказу можна знайти в джерелі
   • кожен край і крок потоку посилається на існуючий вузол
   • codemap.html та codemap.json використовують ті ж вузли, краї та потоки
   • codemap.lock відповідає поточному коміту, стану робочого дерева та відбиткам модулів
   • кожна зв'язок без джерельного доказу позначена як невідома

   Ці три файли завжди повинні генеруватися разом з поточного репозиторію. Ніколи не редагуйте лише один з них вручну.

Нарешті, покажіть:

• створені або змінені файли
• застарілі модулі
• залишкові невідомі
• результати валідації
• повний диф

Додаткове правило

Додайте правило в AGENTS.md, щоб карта коду завжди залишалася синхронізованою з репозиторієм:

На початку кожного завдання, що змінює код, порівняйте поточний репозиторій з docs/codemap/codemap.lock.

Перед зміною модуля використовуйте docs/codemap/codemap.json, щоб відповісти на три питання:

1. Що його викликає?
2. На що це впливає?
3. Які тести його покривають?

Якщо карта застаріла або не може відповісти на ці питання, згенеруйте codemap.html, codemap.json та codemap.lock перед зміною коду.

Коли змінюються межі модулів, залежності, маршрути, бази даних, черги або основні потоки даних, оновлюйте карту коду в тому ж коміті, що й код.