av
4615de6e86
- README описывает термины, команды, два режима и вывод проверки; модель не пересказывается — истина остаётся в репозитории набора - CLAUDE.md фиксирует распределение языков, инварианты кода и решения, которые уже приняты и не пересматриваются без просьбы - отдельным разделом перечислены известные остатки, чтобы их не искали заново
148 lines
8.0 KiB
Markdown
148 lines
8.0 KiB
Markdown
# convy
|
||
|
||
CLI для управления конвенциями разработки: ведёт набор конвенций и собирает
|
||
копии в проектах.
|
||
|
||
Модель, которую инструмент реализует, описана не здесь, а в репозитории набора
|
||
(`dev-conventions`): `README.md` — устройство набора и копий, `LANGUAGE.md` —
|
||
форма правила, `GUIDE.md` — правила ведения набора, `TOOL.md` — решения об этом
|
||
инструменте. При расхождении истина там.
|
||
|
||
## Термины
|
||
|
||
| Уровень | Что это |
|
||
|---|---|
|
||
| набор | репозиторий с конвенциями, манифестом `suite.toml` и обвязкой |
|
||
| тема | набор правил об одном фокусе разработки; единица подписки |
|
||
| слой | один файл темы: базовый, языковой или стековый |
|
||
| компонент | адресат сборки в проекте: один язык, один стек, один вид приложения |
|
||
| префикс | четыре заглавные латинские буквы, адрес правила: `GTIM-3` |
|
||
|
||
Тему и ось слоя объявляет шапка файла, а не путь: `topic:`, `lang:`, `stack:`.
|
||
Слой без ключей оси — базовый, он попадает в копию всегда.
|
||
|
||
## Установка
|
||
|
||
Внешняя зависимость одна (`BurntSushi/toml`), сборка обычная:
|
||
|
||
```
|
||
go install git.vakhrushev.me/av/convy@latest
|
||
```
|
||
|
||
или из клона репозитория:
|
||
|
||
```
|
||
go build -o convy .
|
||
```
|
||
|
||
Способ раздачи готовых бинарей пока не выбран — вопрос открыт в `TOOL.md`.
|
||
|
||
## Команды
|
||
|
||
```
|
||
В наборе:
|
||
convy suite init завести набор: директория и манифест
|
||
convy suite add завести конвенцию: файл, тема и префикс
|
||
convy suite rule дописать правило: следующий номер, блоки по порядку
|
||
convy suite retire снять правило, конвенцию или тему — без переиспользования
|
||
convy suite list что в наборе и что возьмёт компонент
|
||
convy suite check целостность набора: префиксы, темы, оси, ссылки, форма
|
||
|
||
В проекте (пока не реализовано):
|
||
convy add <тема> подписаться и собрать
|
||
convy pull пересобрать подписанное
|
||
convy list что подключено и что доступно
|
||
convy check проверить форму того, что здесь
|
||
```
|
||
|
||
Контекст определяется по манифесту рядом: `suite.toml` — набор,
|
||
`.conventions.toml` — проект. Наугад не делается ничего: команда не того уровня
|
||
отказывает и подсказывает нужную.
|
||
|
||
## Два режима
|
||
|
||
Команды, которые что-то меняют, работают в двух режимах, и режим читается по
|
||
командной строке.
|
||
|
||
**Без аргументов — диалог.** Каждое поле спрашивается с подсказкой о том, что
|
||
туда кладут и почему. Это для человека.
|
||
|
||
```
|
||
$ convy suite add
|
||
|
||
The focus the rules are about: time, config, db-schema. A topic is the unit of
|
||
subscription — a consumer takes it whole. The name never changes and is never reused.
|
||
Topic: logging
|
||
|
||
It goes into the manifest and builds the table of conventions in a consumer's README.
|
||
One line about the topic: логирование: уровни, структура записи
|
||
...
|
||
```
|
||
|
||
**С флагами — автоматика.** Всё передаётся сразу, вопросов не задаётся, все
|
||
недостающие поля называются разом. Это для агентов и скриптов.
|
||
|
||
```
|
||
$ convy suite add --topic logging --about "логирование: уровни" \
|
||
--prefix SLOG --title "Логирование"
|
||
```
|
||
|
||
Без терминала пустой вызов отказывает, а не виснет в ожидании ответа, которого
|
||
некому дать.
|
||
|
||
## Проверка набора
|
||
|
||
```
|
||
$ convy suite check
|
||
conventions/lang/go/logging.md
|
||
error:5 extends points at "arch/time.md" with topic "time", while the file
|
||
carries topic "logging": the layers of one topic declare one name [spread]
|
||
|
||
suite: 13 files, 8 topics, language version 1 (ru)
|
||
errors: 1, warnings: 0
|
||
```
|
||
|
||
Строка находки — `уровень:строка что не так [семейство]`. Семейств четыре:
|
||
|
||
- **manifest** — префиксы, темы, объявленные файлы, незарегистрированные файлы;
|
||
- **form** — форма правила: нумерация, блоки, модальные слова, словарь.
|
||
Проверяется в любом файле, который язык употребляет;
|
||
- **spread** — то, что относится к отъезду к потребителю: тема в шапке, ось,
|
||
`extends`, пути канона, самодостаточность нормы. Только в конвенциях;
|
||
- **links** — разрешение ссылок вида `PREFIX-N`.
|
||
|
||
Третья часть списка проверок языка — взаимоисключительность строк таблицы,
|
||
покрытие области действия, отвечает ли обоснование на «что сломается» — разбором
|
||
текста не даётся и остаётся работой читателя.
|
||
|
||
Коды возврата: `0` — чисто, `1` — есть ошибки, `2` — команда набрана неверно или
|
||
не в том контексте.
|
||
|
||
## Ступени и словарь
|
||
|
||
Слова, которыми записаны модальность и метки, — свойство версии языка и
|
||
естественного языка набора, а не самого набора. Инструмент знает их сам, и
|
||
`suite.toml` их не дублирует: достаточно `[language] version` и `lang`.
|
||
|
||
Поэтому ступень называется категорией, а не словом:
|
||
|
||
```
|
||
--modality requirement | prohibition | recommendation | not-recommended | permission
|
||
```
|
||
|
||
`prohibition` в русском наборе превращается в `**НЕ ДОЛЖЕН.**`, в английском —
|
||
в `**MUST NOT.**`. Вызывающему не нужно знать, на каком языке записан набор.
|
||
|
||
По той же причине `convy` умеет написать строку о версии языка, и созданный им
|
||
файл проходит `suite check` без единой правки.
|
||
|
||
## Чего инструмент не делает
|
||
|
||
- не сливает трёхсторонне и не разрешает конфликты: правка выше маркера
|
||
локальной части теряется, и это заявленное поведение;
|
||
- не ведёт лок-файл: копии закоммичены, ответ на «что было в прошлый раз» даёт
|
||
git;
|
||
- не хранит список подписчиков: подписка — свойство проекта;
|
||
- не переносит правки из проекта в набор: операция ручная и редкая;
|
||
- не перенумеровывает правила: номер — идентификатор, а не позиция.
|