av
b516bfb02c
- родовое «манифест» заменено именем уровня: файл в наборе описывает сам набор, файл в проекте — подключённые конвенции, и каждый назван по тому, что описывает - по имени рядом лежащего манифеста определяется контекст: suite.toml — набор, .conventions.toml — проект; в TOOL.md решение зафиксировано, из открытых вопросов убрано
178 lines
14 KiB
Markdown
178 lines
14 KiB
Markdown
# Инструмент: convy
|
||
|
||
Стартовая точка для разработки. Здесь — принятые решения об инструменте и
|
||
открытые вопросы к нему; модель, которую он реализует, описана в
|
||
[README.md](README.md), а форма правил — в [LANGUAGE.md](LANGUAGE.md). При
|
||
расхождении истина там, а не здесь.
|
||
|
||
## Что это
|
||
|
||
`convy` — CLI для управления конвенциями: собирает копии в проектах и
|
||
проверяет целостность набора. Пишется на Go, живёт в отдельном репозитории,
|
||
ставится готовым бинарём.
|
||
|
||
Имя выбрано за то, что держит корень предметной области и звучит как маленький
|
||
помощник, а уменьшительное `-y` обещает малость — что правда: инструмент
|
||
копирует файлы, собирает тему из слоёв и проверяет форму, не более. Рядом
|
||
существует английское слово `convey`, отличающееся одной буквой и подходящее
|
||
по смыслу, — опечатку в текстах стоит проверять отдельно.
|
||
|
||
Отдельный репозиторий нужен по двум причинам. Инструмент и данные в одном
|
||
репозитории правятся одним движением, и это мешает: лежащий отдельно бинарь
|
||
физически не даёт починить инструмент «заодно» с правкой конвенции. Вторая —
|
||
независимый бинарь работает против любого набора и любого проекта, а не против
|
||
одного конкретного канона.
|
||
|
||
## Термины
|
||
|
||
| Уровень | Английский | Русский | Что там лежит |
|
||
|---|---|---|---|
|
||
| набор | `suite` | набор | `conventions/`, манифест набора, обвязка |
|
||
| проект | `project` | проект | `docs/conventions/`, манифест подключения, копии |
|
||
|
||
`package`, `bundle`, `library` не берём: они тащат багаж менеджеров
|
||
зависимостей — версии, разрешение, лок, — которого в модели нет. `set` не
|
||
годится в CLI: в позиции подкоманды читается глаголом.
|
||
|
||
«Канон» — имя этого конкретного набора, а не термин уровня; в общих
|
||
формулировках употребляется «набор». «Потребитель» — слово про роль
|
||
репозитория, а не про уровень.
|
||
|
||
Манифесты названы по тому, что описывают, а не по уровню ради симметрии:
|
||
`suite.toml` в наборе — идентичность набора, `.conventions.toml` в проекте —
|
||
подключённые конвенции. Точка в проекте отделяет служебное от содержимого
|
||
проекта; в наборе файл правится при каждой новой теме, и прятать его незачем.
|
||
Отсюда же бесплатное определение контекста: по имени рядом видно, где ты.
|
||
|
||
## Раскладка команд
|
||
|
||
Глубина команды отражает частоту и адресата. Проектные команды выполняются в
|
||
каждом репозитории и часто; ведение набора — в одном репозитории и редко.
|
||
|
||
```
|
||
convy add <тема> подписаться и собрать
|
||
convy pull пересобрать подписанное
|
||
convy list что подключено и что можно взять
|
||
convy check проверить форму того, что здесь
|
||
|
||
convy suite check целостность набора: префиксы, темы, ссылки, форма
|
||
convy suite new новая тема: шапка, префикс, запись в манифест
|
||
```
|
||
|
||
Граница проходит не по «проектное против наборного», а по «частое и
|
||
повсеместное» против «только у автора». Поэтому `check` остаётся наверху:
|
||
форма правила одна и та же, локальные правила проекта на `X`-префиксах
|
||
написаны по ней же, и проверять их у себя нужно без подкоманды. Под `suite`
|
||
уходит то, что в проекте не имеет смысла.
|
||
|
||
Три следствия для реализации:
|
||
|
||
- **контекст определяется и отказ говорится явно.** `.conventions.toml` рядом
|
||
— проект, `suite.toml` — набор. Проектная команда, набранная в наборе, не
|
||
делает ничего наугад: она отказывает и подсказывает наборный аналог;
|
||
- **помощь группируется заголовками** «В проекте» и «В наборе»: в плоском
|
||
списке уровни не видны;
|
||
- **синонимов нет.** `convy project pull` рядом с `convy pull` не заводим: два
|
||
способа сказать одно — то, от чего модель избавлялась в остальных местах.
|
||
|
||
В проектах вызов идёт через обёртку раннера (`inv conventions -- pull`,
|
||
`task conventions -- pull`), которая пробрасывает аргументы. Обёртка уже
|
||
называет предмет, поэтому короткая проектная команда здесь тоже выигрывает.
|
||
|
||
## Две задачи, которые нельзя смешивать
|
||
|
||
Они расходятся по частоте, по адресату и по тому, что считается провалом.
|
||
|
||
**Целостность набора.** Префиксы уникальны и не переиспользованы, шапка
|
||
совпадает с манифестом, тема объявлена и зарегистрирована, у каждого правила
|
||
модальность с нормой и обоснование либо заглушка, нумерация сплошная, ссылки
|
||
разрешаются, путей набора в тексте конвенции нет, строка о версии языка на
|
||
месте. Запускается в наборе при каждой правке; провал — ошибка.
|
||
|
||
**Установка в проект.** Манифест подключения, сборка файла темы из слоёв,
|
||
сохранение локальной части, `READING.md` рядом с копиями. Запускается в
|
||
проекте изредка; провал чаще означает «посмотри глазами», чем «ошибка».
|
||
Отчёта «набор ушёл вперёд» нет: его делает `git diff` после пересборки.
|
||
|
||
## Что делает установка
|
||
|
||
Подробности — в README, раздел «Копия в репозитории». Коротко, что важно для
|
||
реализации:
|
||
|
||
- копия плоская, **один файл на тему**; слои идут секциями в порядке
|
||
`arch` → язык → стек, выбор слоёв — по `lang` и `stack` из манифеста
|
||
подключения;
|
||
- шапка копии — только `origin:` с именем темы; отпечатков и дат нет;
|
||
- всё ниже маркера `<!-- conv:local -->` переживает пересборку, всё выше
|
||
перезаписывается; маркер ставит сборщик;
|
||
- `README.md` в директории принадлежит проекту и не трогается; `READING.md`
|
||
принадлежит набору и перезаписывается целиком;
|
||
- транспорта обратно нет: ни `push`, ни отчёта о расхождении, ни лок-файла.
|
||
|
||
## Что делает проверка
|
||
|
||
Список проверок — в `LANGUAGE.md`, раздел «Что стоит проверять машиной». Он
|
||
уже разделён на три части, и это деление прямо ложится в код:
|
||
|
||
- **форма правила** — разбором текста, в любом файле, который язык
|
||
употребляет: конвенции и `GUIDE.md`;
|
||
- **распространение** — разбором текста, только в файлах конвенций: тема в
|
||
шапке, префикс чужой темы в норме, пути набора, `X` у локальных правил;
|
||
- **чтением** — то, что машине не даётся: взаимоисключительность строк
|
||
таблицы, покрытие области действия, самодостаточность нормы, обоснование
|
||
отвечает на «что сломается», примеры не расширяют норму.
|
||
|
||
Третья часть — не работа `convy`. Её выполняет агент, и по ней стоит завести
|
||
скилл, а не пытаться выразить регуляркой.
|
||
|
||
## Независимость от набора
|
||
|
||
Инструмент не зашивает правила языка в код: версия и документы объявлены в
|
||
манифесте набора, секция `[language]`. Пока версия одна, это выглядит
|
||
избыточным — но именно здесь разница между «инструмент для этого канона» и
|
||
«инструмент для любого набора».
|
||
|
||
Отсюда же: никаких упоминаний конкретных тем, префиксов и путей в коде.
|
||
|
||
## Чего инструмент не делает
|
||
|
||
- не сливает трёхсторонне и не разрешает конфликты: правка выше маркера
|
||
теряется, и это заявленное поведение;
|
||
- не ведёт лок-файл: копии закоммичены, автоматического обновления нет,
|
||
ответ на «что было в прошлый раз» даёт git;
|
||
- не хранит список подписчиков: подписка — свойство проекта;
|
||
- не переносит правки из проекта в набор: это ручная и редкая операция.
|
||
|
||
## Открытые вопросы
|
||
|
||
- **Один бинарь или два.** Пока — один с подкомандой `suite`. Разделение
|
||
дешевле заложить сразу, чем отпиливать потом: если задачи разъедутся, у них
|
||
уже будут разные точки входа.
|
||
- **Установка.** `eget` умеет GitHub-релизы, а git у меня свой
|
||
(`git.vakhrushev.me`) — проверить, тянет ли `eget` релизы Gitea, иначе
|
||
остаётся прямой URL или `go install`.
|
||
- **TOML.** В stdlib парсера нет, значит одна внешняя зависимость
|
||
(`BurntSushi/toml` или `pelletier/go-toml`). Выбрать и больше зависимостей
|
||
не заводить.
|
||
- **Предупреждение о висячих ссылках** на неподписанные темы: это установка,
|
||
а не целостность, но список подписок ему нужен из манифеста подключения.
|
||
- **Проверка на `convey`** в текстах — вместе с остальными проверками формы
|
||
или отдельной мелочью.
|
||
- **Прототипы, на которые стоит посмотреть** до того, как писать: дистрибуция
|
||
пакетов Vale (`.vale.ini` → `vale sync` → `styles/`) как образец манифеста и
|
||
`vendir.yml` — как пример границы между «чего хочу» и «что получил».
|
||
|
||
## Состояние
|
||
|
||
`convy` не начат. В наборе лежит `conv` — питоновский скрипт под прежнюю
|
||
модель копий: зеркальное дерево, именованные регионы, `origin_hash`, команды
|
||
`status`, `diff`, `push`. Он не истина ни в чём: модель описана в README,
|
||
проверки — в `LANGUAGE.md`.
|
||
|
||
Логика проверок целостности написана и много раз прогнана руками, но живёт в
|
||
скретчпадах сессий, а не в репозитории. При старте разработки её стоит
|
||
перенести первой — это готовая спецификация в виде кода.
|
||
|
||
Переименование `conv` → `convy` в обвязке (`README.md`, `CLAUDE.md`) делается
|
||
одним заходом, когда инструмент будет готов.
|