удалены TOOL.md и conv, инструкции переведены на convy

- TOOL.md был стартовой точкой разработки инструмента и свою задачу
  выполнил: решения о нём теперь живут в его собственном репозитории,
  открытые вопросы перенесены туда же
- питоновский conv собран под прежнюю модель копий (зеркальное дерево,
  именованные регионы, origin_hash) и удалён вместе с ней
- команды в README.md переписаны на convy, включая suite-сторону и sync
This commit is contained in:
av
2026-07-28 10:05:22 +03:00
parent 0d335ff58d
commit 34d53d667d
5 changed files with 39 additions and 754 deletions
+29 -20
View File
@@ -14,7 +14,6 @@
| [GUIDE.md](GUIDE.md) | как ведут конвенции: когда заводить, механизация, отступления |
| [READING.md](READING.md) | как читать конвенцию: то, что едет к потребителю |
| `.conventions-suite.toml` | манифест набора: язык, темы, префиксы правил |
| `conv` | сборка копий |
К потребителю едет содержимое `conventions/` и один файл обвязки —
`READING.md`; остальная обвязка остаётся в каноне. Самодостаточность копии это
@@ -366,18 +365,30 @@ topics = ["client-logging"]
## Команды
Копии собирает `convy` — отдельный инструмент, живущий в своём репозитории и
ставящийся бинарём. Запускают его из корня репозитория-потребителя:
```bash
conv list # какие темы есть в каноне и что подключено
conv add time # добавить тему в манифест и собрать файл
conv add time --for backend # то же, когда компонентов несколько
conv pull # пересобрать всё, что перечислено в манифесте
# (и обновить READING.md рядом с копиями)
conv pull --for web # только один компонент
convy init --source <ссылка на канон> --component backend \
--dir docs/conventions --lang go
convy add time # подписаться на тему и собрать файл
convy add time --for backend # то же, когда компонентов несколько
convy pull # пересобрать всё, что перечислено в манифесте
# (и обновить READING.md рядом с копиями)
convy pull --for web # только один компонент
convy sync # подвести раскладку файлов под манифест
convy list # что подключено и что ещё есть в каноне
convy check # проверить форму того, что лежит здесь
```
При одном компоненте `--for` не нужен. При нескольких команда без него не
угадывает, а отказывает и перечисляет имена.
Манифест подключения правится и руками — это данные, а не текст с
комментариями. Что бы в нём ни поменяли, раскладку под него подводит `convy
sync`: чего не хватает — соберёт, что осиротело — уберёт, а копию с локальной
частью не тронет и назовёт.
Отчёт о том, что изменилось, отдельной командой не выдаётся: после `pull`
его показывает `git diff`, а решение — принять, поправить или откатить —
принимает человек перед коммитом.
@@ -386,11 +397,9 @@ conv pull --for web # только один компонент
репозитории, переносится в канон руками: это редкая операция, и её цена —
не аргумент против того, чтобы направление оставалось односторонним.
Запускать из корня репозитория:
```bash
~/projects/private/dev-conventions/conv pull
```
Сам канон ведут те же командой под `suite`: `convy suite add` заводит
конвенцию, `convy suite rule` дописывает правило, `convy suite retire`
снимает, `convy suite check` проверяет целостность набора.
Обёртка в раннере репозитория (`inv conventions -- pull` для ansible,
`task conventions -- pull` для Go) — тонкий проброс аргументов, чтобы
@@ -410,11 +419,11 @@ conv pull --for web # только один компонент
## Состояние
Модель выше — согласованная, а не реализованная. `conv` пока собран под
прежнюю: зеркальное дерево копий вместо плоского, именованные регионы
`<!-- local:имя -->` вместо одного маркера, `origin_hash` в шапке и команды
`status`, `diff`, `push`; `READING.md` рядом с копиями он тоже пока не
кладёт, компонентов и объявленной оси не знает и выбирает слои по пути. Сами
конвенции уже приведены к новой модели — именованных регионов в каноне нет,
ось объявлена в шапках. Ни один репозиторий-потребитель не подключён, поэтому
переход никого не ломает.
Модель выше реализована в `convy`: сборка копий, отбор слоёв по объявленной
оси, маркер локальной части, `READING.md` рядом с копиями, проверка
целостности набора. Прежний питоновский `conv` — с зеркальным деревом,
именованными регионами и `origin_hash` — удалён вместе со своей моделью.
Ни один репозиторий-потребитель ещё не подключён: копий с шапкой `origin:` в
природе нет. Пока это так, непроверенным остаётся главное — как всё это живёт
в чужом репозитории через полгода после первой сборки.