feat: enforce model conventions in labset-lint-plugin

[viqueen]

Summary

Adds the first custom lint checks to labset-lint-plugin, enforcing the model conventions for ROLE_ENTITY messages annotated with the labset.plugin.v1.message option. Checks live in a new internal/checks package, one check_<name>.go per check, registered through checks.Spec.

Checks

ID	Enforces
MODEL_FILE_STRUCTURE	Model messages live in <provider>/<domain>/<version>/models.proto with a package matching the directory path (v1 / v1alpha / v1beta1-style version segment; provider/domain must be proto identifiers).
MODEL_TOP_LEVEL	The option may only be applied to top-level messages — nested messages carrying it are flagged.
MODEL_ENTITY_FIELD	Field 1 must be labset.data.v1.Entity.

A message counts as a model only when the option sets role == ROLE_ENTITY; a role-unspecified annotation is silently ignored (buf lint plugins have no "warning" severity, so the choice is error-or-silent — silent is intentional here).

All three checks run off checkutil.NewMessageRuleHandler, detecting nesting via Parent(), so they apply uniformly to top-level and nested messages.

Tests

Stock checktest harness — fixtures under internal/checks/golden/<check>/<case>/, labset imports resolved against the real protos dir via DirPaths, table tests keyed by name. The file-structure logic also has a pure-function table test covering every branch (version suffixes, non-identifier segments, package mismatch). A role_unspecified fixture proves a non-entity annotation is not treated as a model. Assertions use testify consistently.

Review

High-effort multi-agent review ran over the diff; all surfaced findings were addressed:

• Version regex accepted v1beta1 but rejected v1alpha/v1beta (missing-digit false positive) — fixed.
• isModel keyed off option presence rather than role == ROLE_ENTITY, mis-firing MODEL_ENTITY_FIELD on non-entity models — now gated on the role.
• MODEL_TOP_LEVEL hand-rolled descriptor recursion — replaced with the stock checkutil.NewMessageRuleHandler + Parent() check, which also extends the entity-field and file-structure checks to nested models.
• Package-mismatch message could show a nonsensical expected name for non-identifier path segments — provider/domain segments are now validated as identifiers, yielding a clearer directory violation.

Supporting changes

• cmd/labset-lint-plugin/main.go: register checks.Spec (was an empty spec).
• .mise.toml: add a fmt task (golangci-lint fmt), since golines is enforced.
• CONTRIBUTING.md: document the internal/checks layout and "adding a lint check".

Notes

• The plugin is not wired into this repo's own buf.yaml — its protos aren't model messages, so the checks are meant to run downstream.

mise run fmt, mise run lint, and mise run test all pass.

🤖 Generated with Claude Code

[github-actions]

The latest Buf updates on your PR. Results from workflow schema / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Aug 11, 2026, 1:37 PM