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