schema-sync-check

name: schema-sync-check description: Validate CUE schema sync after editing schemas, Go structs with JSON tags, value-type Validate() methods, enum/disjunction constraints, config defaults, or schema-owned decode behavior. Runs targeted structural and behavioral sync tests and reports mismatches.

Schema Sync Check

Validate that CUE schema definitions and Go struct JSON tags are in sync.

When to Use

Invoke this skill (/schema-sync-check) after:

• Editing any CUE schema file (*_schema.cue)
• Adding or modifying JSON tags on Go structs in pkg/invowkfile/, pkg/invowkmod/, or internal/config/
• Renaming CUE fields or Go struct fields
• Adding new CUE definitions with corresponding Go types
• Changing validation/default behavior mirrored between CUE and Go, including Validate() methods, enum/disjunction values, runtime defaults, and config defaults

What It Checks

Schema Files → Go Structs

Sync Test Pattern

The structural sync tests verify:

1. Every CUE field name has a matching JSON tag in the Go struct
2. Every Go struct JSON tag has a matching CUE field name
3. CUE optional fields and Go omitempty tags are aligned, reported as warnings where the helper cannot prove intent

Behavioral sync tests then cover parser/schema behavior such as runtime defaults, validation constraints, and config decode compatibility. The structural helper does not prove Go/CUE type compatibility by itself.

Workflow

Step 1: Run Sync Tests

go test -v -run Sync ./pkg/invowkfile/ ./pkg/invowkmod/ ./internal/config/

Then run the targeted packages to cover behavioral/default tests whose names do not include Sync:

go test -v ./pkg/invowkfile/ ./pkg/invowkmod/ ./internal/config/

Step 2: Interpret Results

All tests pass: Schema and Go structs are in sync. No action needed.

Test failures: The output will show which fields are mismatched:

--- FAIL: TestCommandSchemaSync
    sync_test.go:142: CUE field "new_field" has no matching Go JSON tag
    sync_test.go:148: Go JSON tag "old_field" has no matching CUE field

Step 3: Fix Mismatches

For each mismatch, determine the correct action:

Step 4: Re-verify

After fixes, run the sync tests again to confirm:

go test -v -run Sync ./pkg/invowkfile/ ./pkg/invowkmod/ ./internal/config/
go test -v ./pkg/invowkfile/ ./pkg/invowkmod/ ./internal/config/

Step 5: Run Full Test Suite

Sync changes may affect parsing behavior:

make test

Quick Reference

Adding a New Field

1. Add to CUE schema with constraints:

   new_field: string & =~"^[a-z]+$" & strings.MaxRunes(128)
   

2. Add to Go struct with JSON tag:

   NewField string `json:"new_field"`
   

3. Run sync check to verify alignment

Adding a New Type

1. Define CUE definition: #NewType: close({ ... })
2. Create Go struct with JSON tags
3. Add the type to the existing table-driven sync test when possible, or add a targeted test function with the shared helper:

   func TestNewTypeSchemaSync(t *testing.T) {
       schema, _ := getCUESchema(t)
       def := schematest.LookupDefinition(t, schema, "#NewType")
       cueFields := schematest.ExtractCUEFields(t, def)
       goFields := schematest.ExtractGoJSONTags(t, reflect.TypeFor[NewType]())
       schematest.AssertFieldsSync(t, "NewType", cueFields, goFields)
   }
   

Common Issues