Skip to content

Add discriminated unions structure linter #230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MatteoFari wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add discriminated unions structure linter #230

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/linters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
| [DefaultOrRequired](#defaultorrequired) | Ensures fields marked as required do not have default values | True | Native, CRD |
| [Defaults](#defaults) | Checks that fields with default markers are configured correctly | True | Native, CRD |
| [DependentTags](#dependenttags) | Enforces dependencies between markers | False | Native, CRD |
| [DiscriminatedUnions](#discriminatedunions) | Validates discriminated union marker structure | False | Native, CRD |
| [DuplicateMarkers](#duplicatemarkers) | Checks for exact duplicates of markers | True | Native, CRD |
| [ForbiddenMarkers](#forbiddenmarkers) | Checks that no forbidden markers are present on types/fields. | False | Native, CRD |
| [Integers](#integers) | Validates usage of supported integer types | True | Native, CRD |
Expand Down Expand Up @@ -138,6 +139,38 @@ This linter only checks for the presence or absence of markers; it does not insp
- **Fixes:** This linter does not provide automatic fixes. It only reports violations.
- **Same/Different Values:** Whether you want the same or different values between dependent markers is outside the scope of this linter. You would need other validation mechanisms (e.g., CEL validation) to enforce value-based dependencies.

## DiscriminatedUnions

The `discriminatedunions` linter validates discriminated union definitions across legacy markers (`+union`, `+unionDiscriminator`, `+unionMember`) and declarative markers (`+k8s:unionDiscriminator`, `+k8s:unionMember`).
Union detection is triggered when a struct has either:
- A type-level `+union` marker.
- One or more union field markers (`+unionDiscriminator`/`+unionMember` or `+k8s:unionDiscriminator`/`+k8s:unionMember`).

The linter enforces:

- Exactly one discriminator field.
- A required discriminator field.
- Member fields marked optional.
- Optional forbidding of non-member fields.

The legacy `+unionMember,optional` marker is union membership metadata. It does not replace field optionality markers such as `+optional` or `+k8s:optional`.
Diagnostics for missing optional markers recommend the configured `preferredOptionalMarker`.
Declarative union markers do not have a type-level `+k8s:union` marker; declarative unions are detected from `+k8s:unionDiscriminator` and `+k8s:unionMember` field markers.

### Configuration

```yaml
lintersConfig:
discriminatedunions:
nonMemberFields: Forbid | Allow # Defaults to `Forbid`.
preferredOptionalMarker: optional # optional | kubebuilder:validation:Optional | k8s:optional
```

### Behavior

- **Default:** Disabled by default; enable explicitly.
- **Scope:** Structure-only validation in this linter implementation.

## CommentStart

The `commentstart` linter checks that all comments in the API types start with the serialized form of the type they are commenting on.
Expand Down
Loading
Loading