colgen

name	colgen
description	Colgen — генератор коллекций для Go-структур. Используй при работе с collection.go и конвертерами между слоями.

Colgen

Upstream: https://github.com/vmkteam/colgen Docs: https://vmkteam.dev/colgen/

Генерирует коллекции (XxxList []Xxx) с утилитарными методами из директив в collection.go. Также: inline-сниппеты, LLM-режимы.

Директивы

• //go:generate colgen — запуск генератора в файле
• //colgen:News,Tag — базовая генерация типов + IDs() + Index() (если есть поле ID)
• //colgen:News:<Method>[,<Method>...] — дополнительные методы
• Код должен компилироваться перед запуском — парсинг через AST

Методы

Директива	Эффект
NewsID	NewsIDs() []int (если поле ID нестандартное)
Index(Field)	IndexByField() map[T]News
UniqueField	уникальные значения (поддерживает *T c nil-check)
Count(Field)	CountByField(v) int
Group(Field)	GroupByField() map[T]NewsList; для []T — fan-out
Fill(Target,Junction)	заполняет связи; режим определяется типом junction
Cast(Interface)	Interfaces() []Interface через pointer receiver
Map(pkg) / MapP(pkg)	конструктор NewNewsList(in []pkg.News) NewsList
map/mapp	то же в lowercase (приватный конструктор)

Поведение <Field> по типу

• Скаляр StatusID int → StatusIDs() []int
• Слайс TagIDs []int → flatten в []int (не [][]int)
• Указатель Author *Author → []Author с nil-check и разыменованием

Fill — определение режима

Fill(Tags,TagIDs) где TagIDs []int → many-to-many через related.Index() + append Fill(Author,AuthorID) где AuthorID *int → one-to-one с nil-check Все FillXxx возвращают ll для чейнинга: news.FillTags(tags).FillAuthor(authors)

Map / MapP — конвертеры между слоями

//go:generate colgen -imports=newsportal/pkg/db
//colgen:News,Tag
//colgen:News:UniqueTagIDs,Map(db)

Требования:

• Проект должен содержать дженерики Map[T,M] / MapP[T,M] (pointer-версия)
• MapP(db) — если NewNews принимает *db.News
• map/mapp (lowercase) — приватные конструкторы
• Разное имя в db-слое: Map(db.News) (полный путь)
• Структура не в базовой директиве → конструктор вернёт []News вместо NewsList
• Другой пакет для Map/MapP: -funcpkg=<pkg> + имя пакета в -imports через запятую

Порядок первой генерации (gotcha)

1. Базовые директивы + методы (без Map/MapP)
2. Inline-сниппеты конструкторов (//colgen@NewNews(db))
3. Добавить дженерики Map/MapP в проект
4. Только теперь добавить Map(db) в colgen

Если добавить Map(db) сразу — не скомпилируется (нет NewNews), AST-парсинг упадёт.

Восстановление

Если всё сломалось — удалить *_colgen.go и перегенерировать. Но: если сгенерированные функции уже используются в коде — удаление даст нерабочий код, и генератор не запустится. Временно удалить использования, перегенерировать, вернуть.

Рекомендация: один colgen на пакет, директивы в collection.go.

Inline-сниппеты

//colgen@<Name>(<pkg>) заменяется прямо в файле на тип + конструктор.

//colgen@NewNews(db)                       // embed-стиль (домен-слой)
//colgen@newNewsSummary(db.News,full,json) // full + json-теги (API-слой)

Embed-вариант:

type News struct { db.News }
func NewNews(in *db.News) *News { ... }

Full-вариант — явные поля с тегами json:"..." (поле ID получает тег json:"<entityName>Id").

На сложных объектах сниппет может быть невалиден — редактировать вручную.

LLM-режимы

Нужен API-ключ. Отправляется содержимое файла (+ тест) + промт.

• //colgen@ai:review → .md с ревью
• //colgen@ai:readme → README.md по файлу
• //colgen@ai:tests → _test.go

Суффикс (deepseek) или (claude). DeepSeek по умолчанию.

Маркеры

• Generated: *_colgen.go с // Code generated by colgen; DO NOT EDIT.
• Редактируемые: collection.go (директивы), файлы inline-сниппетов после первой генерации