How to check a module

cuefn check is the static health gate for a module — the go vet to cuefn test's go test. It needs no XR instance and no cluster: it proves the CUE is canonically formatted, evaluates cleanly, and still generates a valid structural XRD. Render behavior belongs to cuefn test; checking one concrete XR against the schema belongs to cuefn validate. The CLI reference has the full three-verb comparison.

Run the checks

From the module directory:

cuefn check
PASS fmt
PASS vet
PASS xrd

3 passed, 0 failed, 0 seeded, 0 updated

Use --dir to run from elsewhere (cuefn check --dir example/module). All three units always run, so one invocation surfaces everything:

• fmt — every .cue file (including cue.mod/module.cue) is in the canonical form cue fmt produces. A failure lists the offending files; run cue fmt to fix them.
• vet — the module evaluates cleanly without requiring concreteness. This is the equivalent of cue vet -c=false ./... — the correct author-side invocation, since bare cue vet fails on any required field without a default, which every useful #Spec declares. A module that does not load at all reports its load error under this unit.
• xrd — the structural XRD still generates from #API/#Spec/#Status. This is the failure surface render tests cannot see: a module can render perfectly for every test case and still declare a schema Kubernetes rejects — most commonly a type-crossing disjunction like string | int.

Pin the XRD with a golden

A passing generation proves the XRD is valid; it does not prove it is the API you shipped. A refactor can silently widen, narrow, or re-shape the generated schema while every render test stays green. Pin the XRD against a reviewed golden file:

cuefn check --xrd xrd.yaml
PASS fmt
PASS vet
SEED xrd
    wrote xrd.yaml; review and commit

The first run seeds the golden and exits non-zero so you review it before committing. Seeded files are machine-owned and begin with a # Generated by cuefn check; DO NOT EDIT. header naming the re-bless command. From then on any schema drift fails with a line diff; after an intentional schema change, re-bless with:

cuefn check --xrd xrd.yaml --update
UPDATE xrd
    rewrote drifted golden xrd.yaml

The comparison ignores line endings and leading comment lines, so a headerless file you previously committed from cuefn generate --output xrd.yaml passes unchanged — point --xrd at it and adopt the lifecycle from there.

Run in CI

In CI mode, seeding and --update are refused, so a missing or drifted golden always fails the build:

cuefn check --xrd xrd.yaml --ci

CI mode also engages automatically whenever the CI environment variable is set (as on GitHub Actions runners). Together with the test suite this is the complete author gate — static health plus behavior:

cuefn check --xrd xrd.yaml --ci && cuefn test --ci

What check does not cover

• cue mod tidy — the tidy implementation is not importable from CUE's Go API, so check cannot run it in-process. If you care about a tidy cue.mod/module.cue, run cue mod tidy --check alongside.
• Render behavior — that is cuefn test.
• A concrete XR against the schema — that is cuefn validate.