# 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;
- не хранит список подписчиков: подписка — свойство проекта;
- не переносит правки из проекта в набор: операция ручная и редкая;
- не перенумеровывает правила: номер — идентификатор, а не позиция.