Documentation
¶
Overview ¶
Package declaredbreak — АДЪЮДИКАЦИЯ ломающих изменений контракта, а не голый `buf breaking`.
───────────────────────────────────────────────────────────────────────────── ЗАЧЕМ АДЪЮДИКАЦИЯ, А НЕ ПРОСТО ПРОВЕРКА
Голый `buf breaking` верен ровно до того дня, когда ломающее изменение становится ОСОЗНАННЫМ — снят метод, отвечающий отказом при любом входе; снято поле, которое служба принимает и не читает. Тогда шаг красен ПО ПОСТРОЕНИЮ, и у читателя остаются два плохих хода: снять шаг — потерять защиту от СЛУЧАЙНЫХ разрывов на всём дереве ради одного объявленного; либо внести файл в `breaking.ignore` — послабление без предмета и без срока, ослепляющее проверку на целом файле НАВСЕГДА.
Поэтому разрыв проходит только через перечень объявленных, и запись живёт ровно пока у неё есть предмет: НАХОДКА ВНЕ ПЕРЕЧНЯ — КРАСНОЕ, ЗАПИСЬ БЕЗ НАХОДКИ — ТОЖЕ КРАСНОЕ. Вторая половина и есть самоистечение: без неё перечень пережил бы свой предмет и остался бы слепой зоной, выданной вперёд.
───────────────────────────────────────────────────────────────────────────── ПОЧЕМУ СВОЯ РЕАЛИЗАЦИЯ, А НЕ КОПИЯ ПЛАТФОРМЕННОЙ
У платформы адъюдикатор того же класса есть. Взять его файлом нельзя: копия файла чужого репозитория запрещена, и запрет не смягчается совпадением содержимого — он им ДОКАЗЫВАЕТСЯ, потому что расхождение наступит молча. Взять пином тоже нельзя: ребро `kaname → kacho` снято, и заводить его обратно ради проверки значило бы замкнуть граф.
Поэтому здесь ПОВТОРЕН ПРЕДМЕТ, а не текст: те же три исхода, то же самоистечение, тот же разбор вывода. Расхождение реализаций расхождением СВОЙСТВА не является — свойство у каждого дерева своё, и доказывается оно своей инъекцией на СВОЁМ выводе buf.
───────────────────────────────────────────────────────────────────────────── ИСХОДОВ ТРИ, И ТРЕТИЙ НЕСУЩИЙ
0 — находок нет и перечень пуст либо каждая находка объявлена; 1 — НАХОДКА: разрыв вне перечня либо запись, которой нечего прощать; 2 — гейт НЕ СДЕЛАЛ СВОЕЙ РАБОТЫ: вывод не разобран, перечень не прочитан.
Код возврата самого `buf` разбирает вызывающий: 100 — «есть находки» (штатный вход сюда), 0 — «разрывов нет», ЛЮБОЙ ДРУГОЙ — третий исход. Схлопни их, и сетевой отказ читался бы как «разрывов нет».
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Declaration ¶
type Declaration struct {
Rule string `yaml:"rule"`
Path string `yaml:"path"`
Symbol string `yaml:"symbol"`
Reason string `yaml:"reason"`
Issue string `yaml:"issue"`
}
Declaration — объявленный разрыв. Полей пять, и все обязательны.
func LoadDeclarations ¶
func LoadDeclarations(path string) ([]Declaration, error)
LoadDeclarations — перечень объявленных разрывов.
ОТСУТСТВИЕ ФАЙЛА — ОТКАЗ, А НЕ ПУСТОЙ ПЕРЕЧЕНЬ: «перечня нет» и «перечень пуст» ведут читателя в разные места, и схлопывание их сделало бы удаление файла способом снять проверку.
func (Declaration) Validate ¶
func (d Declaration) Validate() []string
Validate — негодная запись есть находка, а не молчание: объявление, которое нельзя сопоставить, прощает не то, что называет.
type Finding ¶
type Finding struct {
Path string `json:"path"`
Type string `json:"type"`
Message string `json:"message"`
Line int `json:"start_line"`
}
Finding — одна находка `buf breaking`, как её печатает `--error-format=json`.
func ParseFindings ¶
ParseFindings — разбор вывода `buf breaking --error-format=json`.
СТРОКА, НЕ ЯВЛЯЮЩАЯСЯ ОБЪЕКТОМ JSON, — ОТКАЗ, а не пропуск: buf печатает в поток вывода только находки, и всё прочее означает, что шаг не сделал своей работы. Молчание здесь читалось бы как «разрывов нет».
func (Finding) Coordinate ¶
Coordinate — координата находки для сопоставления и для текста.
func (Finding) Symbol ¶
Symbol — символ находки: то, по чему запись перечня называет РОВНО ЭТОТ разрыв. buf называет предмет В КАВЫЧКАХ, и это предпосылка, а не догадка: она снята с настоящего вывода buf 1.72.0 и проверяется пробой на нём — TestSymbolNamesTheSubjectInsideItsContainer.
ГДЕ СООБЩЕНИЕ НАЗЫВАЕТ ОБЪЕМЛЮЩИЙ СИМВОЛ, символ — `<контейнер>.<предмет>`:
Previously present field "1" with name "id" on message "Role" was deleted. → Role.1 Previously present enum value "4" on enum "CredentialKind" was deleted. → CredentialKind.4 Previously present RPC "Get" on service "RoleService" was deleted. → RoleService.Get Message "M" had required field "2" deleted. … → M.2
Предмет — ПЕРВОЕ кавычечное вхождение до контейнера: у поля и значения перечисления это НОМЕР, у RPC, oneof и зарезервированного имени — имя, у зарезервированного диапазона — его запись. Номер, а не имя поля, потому что номер buf печатает у поля ВСЕГДА, а имя — не всегда: у переименования поля описание идёт без имени, и одно поле получило бы два написания.
Контейнер обязателен, и это не украшение (kaname#474). Имени значения перечисления buf не печатает вовсе, и прежний выбор «первое вхождение вида имени» делал символом САМО ПЕРЕЧИСЛЕНИЕ; у поля символом было имя без сообщения. Запись о снятии одного значения прощала снятие любого соседнего, запись о поле одного сообщения — одноимённое поле соседнего. Обе стороны оставались синтаксически верными, и сопоставление не отличало одно от другого.
ГДЕ КОНТЕЙНЕРА В СООБЩЕНИИ НЕТ, символ — первое кавычечное вхождение вида имени (снятое сообщение, перечисление, служба; параметр сообщения). Номер именем не является и отсеивается `nameRe`. Различить два таких разрыва одного файла нечем, и держит их не символ, а расходование записи (Adjudicate): одна запись прощает ровно один разрыв.
У снятия ФАЙЛА символ совпадает с путём: предмет такой находки — сам файл, и другого имени у неё нет.
Контейнер назван, а предмета до него нет — пустой символ: ParseFindings отказывает, а не делает символом контейнер.
type Result ¶
type Result struct {
// Undeclared — разрывы, которых нет в перечне.
Undeclared []Finding
// Expired — записи, которым нечего прощать. Самоистечение перечня.
Expired []Declaration
// Matched — объявленные разрывы, нашедшие свой предмет.
Matched int
// Invalid — негодные записи перечня.
Invalid []string
// Findings — сколько находок разобрано, Declarations — сколько записей прочитано.
Findings int
Declarations int
// contains filtered or unexported fields
}
Result — исход адъюдикации.
func Adjudicate ¶
func Adjudicate(findings []Finding, decls []Declaration) Result
Adjudicate — сопоставление находок с объявлениями.
ЗАПИСЬ ПРОЩАЕТ РОВНО ОДИН РАЗРЫВ: простившая запись расходуется, и следующая находка с тем же символом ищет СВОЮ запись. Без этого одна запись прощала бы сколько угодно находок, которые её символ не различает (kaname#474): у параметра сообщения buf имени сообщения не печатает, у одноимённых вложенных сообщений одного файла контейнер назван одним и тем же простым именем. Два неразличимых разрыва объявляются двумя записями — тогда число записей и есть утверждение объявившего, сколько таких разрывов он допускает.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
adjudicate-declared-breaks
command
adjudicate-declared-breaks — читает вывод `buf breaking --error-format=json` со стандартного входа и сопоставляет его с перечнем объявленных разрывов.
|
adjudicate-declared-breaks — читает вывод `buf breaking --error-format=json` со стандартного входа и сопоставляет его с перечнем объявленных разрывов. |