| 1 | # ADR 0062: GitMap — карта git-границ (submodules) отдельно от workspace navigation context |
| 2 | |
| 3 | **Статус:** Proposed — черновик для обсуждения; реализация не зафиксирована. |
| 4 | **Дата:** 2026-04-17 |
| 5 | **Обновлено:** 2026-04-17 — зафиксировано **намеренное разделение** с Semantic Map / WSNC (см. [Почему не WSNC](#adr0062-not-wsnc)). Подробности — [§ История](#adr0062-history). |
| 6 | |
| 7 | ## Связанные ADR |
| 8 | |
| 9 | | ADR / документ | Роль | |
| 10 | |----------------|------| |
| 11 | | [0039](0039-workspace-navigation-affordances.md) | WSNC — навигация по коду (**не** GitMap) | |
| 12 | | [0019](0019-shared-git-core-ide-and-git-mcp.md) | Общий Git core | |
| 13 | | [0055](0055-skia-instrument-composition-pipeline.md) | Общий pipeline отрисовки | |
| 14 | | [0056](0056-semantic-map-pipeline-adoption.md) | Adoption pipeline в карте | |
| 15 | | [0067](0067-graph-backed-surfaces-contract.md) | GitMap как graph-backed surface | |
| 16 | | [`git-and-submodules-v1.md`](../git-and-submodules-v1.md) | Продуктовый контур | |
| 17 | |
| 18 | ## Резюме |
| 19 | |
| 20 | - **GitMap:** submodules и git-границы **отдельно** от WSNC/карты намерений. |
| 21 | - Общий Skia pipeline; собственный контракт/MCP. |
| 22 | |
| 23 | |
| 24 | <a id="adr0062-not-wsnc"></a> |
| 25 | |
| 26 | ## Почему не смешивать с workspace navigation context (WSNC) |
| 27 | |
| 28 | **Решение по смыслу (обсуждение → зафиксировано в черновике):** визуализация submodules **не** является расширением `get_code_navigation_context` / `CodeNavigationContextBuilder` и **не** встраивается в Semantic Map как ещё один `kind` в том же JSON. |
| 29 | |
| 30 | Причины: |
| 31 | |
| 32 | 1. **WSNC про решение и код.** Текущий контракт завязан на дерево **`.sln` / `.slnx`**, файлы проектов и эвристики **архитектуры исходников** (partial, проект, namespace, каталог, control flow — см. [0039](0039-workspace-navigation-affordances.md), [0053](0053-semantic-map-control-flow-pfd.md)). Это слой **«где в коде я и что рядом по смыслу разработки»**. |
| 33 | |
| 34 | 2. **Submodules — про git-топологию, не про дизайн ПО.** Граница репозитория — артефакт **истории и модулей VCS** (gitlink, `.gitmodules`, checkout). К архитектуре приложения относится опосредованно; смешивать с графом «соседей по коду» — смешивать **две оси смысла** (код vs репозиторий). |
| 35 | |
| 36 | 3. **Продуктово:** отдельный режим/инструмент проще объяснить пользователю и агенту, чем пресеты `include_kinds`, в которых половина узлов «про git», половина «про файлы». |
| 37 | |
| 38 | **Именование WSNC:** формулировка «workspace navigation» сегодня пересекается с git-картой в голове читателя; возможное **переименование** контракта/команды MCP в сторону «solution graph» / «code navigation context» — **отдельное** решение (не блокер этого ADR), см. [открытые вопросы](#adr0062-open). |
| 39 | |
| 40 | <a id="adr0062-gitmap"></a> |
| 41 | |
| 42 | ## GitMap — отдельная поверхность, общий пайплайн |
| 43 | |
| 44 | **Рабочее имя:** **GitMap** — мини-карта (и при необходимости список) **git-соседей**: родительский репозиторий, вложенные submodules, рёбра «содержит / вложен». |
| 45 | |
| 46 | **Переиспользование:** тот же **Skia pipeline** композиции, что и у Semantic Map ([0055](0055-skia-instrument-composition-pipeline.md), [0056](0056-semantic-map-pipeline-adoption.md)): Intent → (опционально) Declutter → Layout → Render — с **другим** источником графа (git-метаданные, не `CodeNavigationContextBuilder`) и, при необходимости, **другим** инструментом/слотом в PFD ([0047](0047-cockpit-instrument-descriptor-and-slot-composition.md)), чтобы не смешивать «карту намерений» и «карту репозиториев» в одном виджете. |
| 47 | |
| 48 | Семантическая карта (**Semantic Map**) остаётся про **код и задачу**; **GitMap** — про **где в git-дереве я и что за соседние репозитории**. |
| 49 | |
| 50 | --- |
| 51 | ## Контекст задачи |
| 52 | |
| 53 | В монорепозиториях часть путей ведёт в **отдельные git worktrees** (submodule). Пользователь и агент должны видеть **границу репозитория** без обязательного открытия Git UI — в согласовании с [git-and-submodules-v1.md](../git-and-submodules-v1.md). |
| 54 | |
| 55 | ## Источник данных (открыто) |
| 56 | |
| 57 | | Подход | Плюсы | Минусы | |
| 58 | |--------|--------|--------| |
| 59 | | Парсинг `.gitmodules` + пути от корня worktree | Без обязательного `git` в горячем пути | Согласование с фактическим `.git` в submodule | |
| 60 | | `git submodule status` (GitMcp.Core / [0019](0019-shared-git-core-ide-and-git-mcp.md)) | Commit, грязь, расхождения | Процесс, кэш, потоки | |
| 61 | | Гибрид | Богаче подписи | Два источника | |
| 62 | |
| 63 | Корень для привязки: **git worktree**, в котором открыт workspace (вопрос multi-root — отдельно). |
| 64 | |
| 65 | ## Контракт данных GitMap (черновик, не WSNC) |
| 66 | |
| 67 | Отдельное описание графа (узлы/рёбра/метки), **не** расширение payload `related` / `subgraph` из [0039](0039-workspace-navigation-affordances.md): |
| 68 | |
| 69 | - Узлы: как минимум **корень текущего репо**, **submodule roots** (путь каталога), опционально метки состояния (грязь, отставание) — по мере наличия данных. |
| 70 | - Рёбра: «родитель — submodule», при вложенности — цепочка. |
| 71 | - MCP: отдельная команда уровня **`get_git_map_context`** (имя обсуждаемо) или эквивалент в git-слое IDE — **не** параметры к `get_code_navigation_context`. |
| 72 | |
| 73 | Пресеты уровня **кода** (`[code_navigation]` в `settings.toml`) к GitMap **не применяются**; у GitMap — свои лимиты и настройки (или дефолты в коде до появления TOML). |
| 74 | |
| 75 | ## Открытые вопросы |
| 76 | |
| 77 | <a id="adr0062-open"></a> |
| 78 | |
| 79 | 1. Слот PFD: **вкладка** рядом с Semantic Map, **отдельный instrument_id**, или переключатель режима внутри одного слота — что дешевле по вниманию ([0021](0021-pfd-mfd-cockpit-attention-model.md))? |
| 80 | 2. Вложенные submodules: глубина и капы. |
| 81 | 3. Клик по узлу: reveal в explorer, открыть путь, смена корня сессии — MVP. |
| 82 | 4. Переименование публичного имени **WSNC** / команды MCP для ясности «solution/code graph». |
| 83 | 5. Паритет агента: отдельный tool в контракте vs секция в `get_ide_state`. |
| 84 | |
| 85 | ## Не цели (пока) |
| 86 | |
| 87 | - Подмена **полноценного Git UI** (diff, commit, sync submodule) — GitMap **навигационная** подсказка, не замена панелей git. |
| 88 | - Полный граф **всех** remote и политик обновления. |
| 89 | - Смешение узлов «файл из WSNC» и «submodule» в **одном** JSON-ответе без явного слоя (отклонено; см. [Почему не WSNC](#adr0062-not-wsnc)). |
| 90 | |
| 91 | ## Отклонённые альтернативы |
| 92 | |
| 93 | - **Расширить только Semantic Map** новыми `kind` в том же subgraph — отклонено: разные оси смысла, см. выше. |
| 94 | - **Только список без графа** — допустимо как режим деградации GitMap, не как единственный вид. |
| 95 | |
| 96 | --- |
| 97 | |
| 98 | *После согласования: обновить статус, описать MCP/git-слой и слот инструмента; реализация.* |
| 99 | |
| 100 | --- |
| 101 | |
| 102 | ## История изменений |
| 103 | |
| 104 | <a id="adr0062-history"></a> |
| 105 | |
| 106 | | Дата | Изменение | |
| 107 | |------|-----------| |
| 108 | | 2026-04-17 | зафиксировано **намеренное разделение** с Semantic Map / WSNC (см. [Почему не WSNC](#adr0062-not-wsnc)). | |
| 109 | |