docs: правила о контексте и о токене записаны, две находки — в журнал
- в go-linters.md заведён раздел «Отмена и внешний собеседник», перечень механизированного пополнен девятью правилами и двумя шагами гейта, названы остатки: contextcheck не видит сигнатуру без контекста вовсе, шаг migrations судит только шаги, бывшие в базе диффа, rowserrcheck и sqlclosecheck профилактические — предмета в коде нет - в logging.md и security.md чистка отказа Telegram описана по факту: точка одна и лежит на границе клиента, закрыты все пять путей вместе с логгером самой библиотеки. Прежнее «*Расхождение:* вычистки нет... она не логируется» было неверным дважды - в журнал дефектов записаны две находки: отказ скачивания уносил токен бота (проскочил, жил с самого начала) и остановка сервиса хоронила конвертируемую запись в failed (поймано ревью до коммита) - вопрос темы operations про отмену переформулирован: спрашивать надо не «доходит ли контекст», а «что шаг делает с задачей, деньгами и ответом отправителю»; вопрос про таймаут оставлен с оговоркой, что проброс контекста на него не отвечает - в памятке: словарь кодов новых шагов, требование компилятора C у детектора гонок и оговорка, что «CGO не нужен» относится к сборке, а не к гейту
This commit is contained in:
@@ -40,7 +40,11 @@ Go-проект как есть. Своё здесь — перечень пра
|
||||
версий Go поведение нормировано отдельно, спекой
|
||||
[toolchain](../../openspec/specs/toolchain/spec.md): это единственная проверка
|
||||
проекта, у которой есть своя capability, и потому единственная, чьи сценарии
|
||||
проверяются построчно (`scripts/check_go_version_test.go`).
|
||||
проверяются построчно (`scripts/check_go_version_test.go`). Второй самодельный
|
||||
шаг — `migrations` — нормы не имеет: он проверен мутацией на трёх исходах
|
||||
(переписанный шаг, пустой каталог, чистое дерево), но регрессионных проверок у
|
||||
него нет, и дрейф его собственного шаблона имени никто не поймает. Это
|
||||
объявленный долг, а не умолчание.
|
||||
|
||||
## Лестница механизации
|
||||
|
||||
@@ -104,6 +108,9 @@ Go-проект как есть. Своё здесь — перечень пра
|
||||
| Сравнение ошибок через `errors.Is` и `errors.As`, не `==` и не приведением типа | `.golangci.yml` → `errorlint` |
|
||||
| Ошибка не узнаётся сравнением текста сообщения (`strings.Contains(err.Error(), …)`, `err.Error() == …`) | `internal/archrules` → `TestОшибкаНеУзнаётсяПоТексту` |
|
||||
| Непроверенное возвращаемое значение ошибки | `.golangci.yml` → `errcheck`, включая присваивание в `_` (`check-blank`). Отказ, который решено не проверять, объявляют в `exclude-functions` поимённо — там сегодня `defer Close`, `os.Remove` и `send` |
|
||||
| Непроверенное приведение типа (`v := x.(T)`) | `.golangci.yml` → `errcheck` с `check-type-assertions`. Отдельная настройка, потому что такое приведение паникует, а не возвращает ошибку, и `check-blank` его не видит |
|
||||
| Проверенный отказ не оборачивается в `return nil` | `.golangci.yml` → `nilerr`. Механизирует половину инварианта «принятая запись не теряется молча»: молчаливый успех после отказа |
|
||||
| Отказ выборки из хранилища не теряется (`rows.Err()`), а сама выборка закрывается | `.golangci.yml` → `rowserrcheck`, `sqlclosecheck`. **Профилактические: предмета в коде сегодня нет** — выборки идут через `dbx` хранилища, а из `database/sql` употребляются только `sql.NullString` и `sql.ErrNoRows`. Правила заведены на будущий сырой запрос; мутацией проверены на пробе, а не на своём коде |
|
||||
| Ошибки — только stdlib, без сторонних пакетов | `.golangci.yml` → `depguard` |
|
||||
|
||||
### Структура и границы
|
||||
@@ -115,6 +122,14 @@ Go-проект как есть. Своё здесь — перечень пра
|
||||
| Адаптер не знает ни ядра, ни транспортов | `internal/archrules` → `TestАдаптерыНеЗнаютНиЯдра_НиТранспортов` |
|
||||
| Колонки очереди согласованы: перечень захвата ↔ структура захвата ↔ шаг схемы ↔ запись коллекции ↔ перенос поля в задачу | `internal/archrules` → четыре правила о захвате. Закрывает инвариант «колонки правятся в четырёх местах» (CLAUDE.md, major), которого компилятор не держит. Литерал колонки ищется в телах нужных функций: по файлу целиком условие выполнялось бы тегами `db:"…"` самой структуры, и правило было бы зелёным всегда |
|
||||
|
||||
### Отмена и внешний собеседник
|
||||
|
||||
| Правило | Где механизировано |
|
||||
| --- | --- |
|
||||
| Запрос и внешний процесс заводятся с контекстом (`exec.CommandContext`, `http.NewRequestWithContext`, `QueryContext`) | `.golangci.yml` → `noctx`. Единая точка не нужна: контекст приезжает доводом, а контракты `internal/contract` несут его первым |
|
||||
| Контекст приезжает сверху, а не заводится по месту (`context.Background()` в середине цепочки) | `.golangci.yml` → `contextcheck` |
|
||||
| Тело ответа HTTP закрывается | `.golangci.yml` → `bodyclose`. Отдельно от `errcheck`: там `(io.ReadCloser).Close` объявлен исключением, и незакрытое тело от невыясненного `Close` неотличимо |
|
||||
|
||||
### Время, вывод, конфигурация
|
||||
|
||||
| Правило | Где механизировано |
|
||||
@@ -130,6 +145,9 @@ Go-проект как есть. Своё здесь — перечень пра
|
||||
| --- | --- |
|
||||
| Проверка судит ответ по готовому ответу (`Result()`), а не по живой карте заголовков обработчика | `.golangci.yml` → `forbidigo` с `analyze-types`, находки только в `*_test.go`. Судит по типу приёмника (`httptest.ResponseRecorder`), поэтому ловит любую форму: цепочкой, через переменную, по индексу карты, обходом, полем `HeaderMap`. Остаётся ревью проверка, идущая мимо recorder — через свой `http.ResponseWriter` |
|
||||
| Каждый сценарий нормы шага сверки версий проверен мутацией, а не памятью | `scripts/check_go_version_test.go` — 20 сценариев спеки `toolchain` плюс два свойства самого шага: исход не зависит от установленного `go`, и шаг не зовёт ни `go`, ни `docker`, ни сеть |
|
||||
| Форма утверждения в проверках: «ожидалось» и «получено» не перепутаны местами, отказ судится `NoError`, а не `Nil`, `require` не зовут из горутины | `.golangci.yml` → `testifylint` |
|
||||
| Одновременный доступ проверен детектором, а не чтением кода | `Taskfile.yml` → шаг `tests` (`go test -race ./...`). Общее у воркеров — счётчики метрик, логгер и клиент бота; захват задачи в гонку не входит, он по построению её не даёт (одно состояние на воркер) — см. «Типовые ложноположительные» в [../review.md](../review.md). Без компилятора C шаг гоняет тесты без детектора и краснеет кодом 3: гонки — не повод отнимать у гейта сами тесты |
|
||||
| Строчное подавление называет линтер и причину, а протухшее краснеет | `.golangci.yml` → `nolintlint` (`require-explanation`, `require-specific`, `allow-unused: false`) |
|
||||
|
||||
### Форма кода и файлов вне Go
|
||||
|
||||
@@ -146,6 +164,7 @@ Go-проект как есть. Своё здесь — перечень пра
|
||||
|
||||
| Правило | Где механизировано |
|
||||
| --- | --- |
|
||||
| Применённый шаг схемы не переписывается: у файла шага допустим один статус — `A` | `Taskfile.yml` → шаг `migrations`. Закрывает инвариант CLAUDE.md (critical), которого не держит ни компилятор, ни хранилище: применённое считается по имени файла. Баз диффа две — `BASE` и `HEAD`: первая отвечает на «шаг уже уехал» ровно настолько, насколько свежа `origin/master`, вторая ловит правку закоммиченного шага независимо от неё. Каталог берётся из ключа `migrations` в `docs/.docs.json`, чтобы у факта не было второго дома; пустой каталог роняет шаг — правило, потерявшее предмет, молчать не должно. `migrations.go` под правило не подпадает: строка `Register` нового шага прибавляется именно там |
|
||||
| Раскладка документов, битые ссылки, изменённый шаг схемы без правки `database.md` | `docs.py check`; каталог шагов задаёт ключ `migrations` в `docs/.docs.json` |
|
||||
| Согласованность каталога задач, форма `openspec/config.yaml` | `tasks.py check`, `openspec.py check` |
|
||||
| Секреты в коммите | `lefthook.yml` → `gitleaks git --staged` |
|
||||
@@ -166,6 +185,7 @@ Go-проект как есть. Своё здесь — перечень пра
|
||||
| Правило о заголовках вне `*_test.go` | `.golangci.yml`, `exclusions` | В рабочем коде `Header()` и есть способ отдать заголовок |
|
||||
| `time.Now` внутри `internal/clock` | там же | Единой точке чтения времени нечем читать время иначе |
|
||||
| Чтение времени и окружения в `*_test.go` | там же | Проверка строит вход прогона — фикстуру времени, `PATH`, окружение дочернего процесса, — а не метку домена и не настройки приложения. Исключение объявлено по тексту сообщения: правило называет четыре имени, и исключение обязано покрывать те же четыре |
|
||||
| `noctx` на `httptest.NewRequest` в `*_test.go` | `.golangci.yml`, `exclusions` | Фикстура запроса к обработчику в том же процессе: внешнего собеседника за ней нет, отменять нечего. Изъятие названо по имени этой функции, а не выключением `noctx` на проверках: настоящий внешний вызов из проверки — `http.Get`, `exec.Command` — правилу по-прежнему подсуден, и это проверено мутацией |
|
||||
| `SC1007` в `scripts/check-go-version.sh` | директива в скрипте | Ложное срабатывание на идиому `CDPATH= cd`, которая защищает `cd` от чужого `CDPATH` |
|
||||
| `DL3007` (`alpine:latest`) | `Taskfile.yml`, шаг `dockerfile` | Открытая задача `pin-runtime-image-base`; до её решения шаг краснел бы на известном |
|
||||
| `DL3018` (закрепить версии `apk`) | там же | Alpine не держит старые версии пакетов в репозитории: закрепление ломает сборку через недели |
|
||||
@@ -185,6 +205,15 @@ Go-проект как есть. Своё здесь — перечень пра
|
||||
- вывод в stdout через `fmt.Fprintln(os.Stdout, …)` и `os.Stdout.WriteString`:
|
||||
`forbidigo` судит по имени вызванной функции, а не по её первому аргументу;
|
||||
- проверка, судящая ответ мимо recorder — через свой `http.ResponseWriter`;
|
||||
- **отсутствие** контекста у сигнатуры: `contextcheck` ловит обрыв цепочки —
|
||||
`context.Background()` там, где контекст был доводом, — но метод, у которого
|
||||
довода нет вовсе, правилу не виден. Первый проброс контекста в новый адаптер
|
||||
остаётся человеку;
|
||||
- шаг `migrations` судит только те шаги схемы, которые **есть в базе диффа**: у
|
||||
добавленного после неё файла статус `A`, и правка такого файла законна — он
|
||||
ещё никуда не уехал. Отсюда следствие: при отставшей `origin/master` правило
|
||||
молчит на всём каталоге, и на подозрении база задаётся руками
|
||||
(`task migrations BASE=<rev>`);
|
||||
- направление «транспорт не знает адаптера»: сегодня оно нарушено осознанно —
|
||||
`controller/http` импортирует адаптер хранилища, потому что HTTP-поверхность и
|
||||
есть роутер этого хранилища. Изъятие названо в
|
||||
@@ -223,5 +252,11 @@ Go-проект как есть. Своё здесь — перечень пра
|
||||
принятое молчанием инструмента, — это не правило: прецеденты есть, и записаны
|
||||
они в [../review.md](../review.md) (журнал 2026-08-11 про недостижимую норму,
|
||||
2026-08-13 про обходимый текстовый запрет).
|
||||
|
||||
**Мутация ставится по одному нарушению на строку.** `golangci-lint` печатает
|
||||
с одной строки исходника **одну** находку (умолчание `uniq-by-line`), и
|
||||
мутация, задевшая сразу два правила, покажет только первое: так молчали
|
||||
`sqlclosecheck` и `rowserrcheck` на пробе, где та же строка уже краснела от
|
||||
`noctx`. Проверять правило пробой, где оно единственное нарушенное.
|
||||
5. **Записать строкой здесь** и удалить прозу из конвенции, если правило её
|
||||
заменило.
|
||||
|
||||
Reference in New Issue
Block a user