hand-edited-catalogue-invariants
Guard hand-edited data catalogues (seeded exercise/item lists, preset programs, skill/tech trees, title tables) with structural invariant tests — cross-reference existence, name uniqueness, enum-store
SKILL.mdskills/managed/hand-edited-catalogue-invariants/SKILL.md
GitHubHand-edited catalogue invariants
Catalogues edited by hand (seed lists, preset programs, skill trees, title tables) fail silently: no crash, no error, just wrong content shipped. Behaviour tests pass on a broken catalogue because the rules are fine — it is the data that is inconsistent. Assert the structure over the real data.
The four invariants that actually catch bugs
- Cross-reference existence. Every name one catalogue quotes from another must exist there. Critical when the reader auto-creates unknown names (a lenient import/resolve path): a typo then mints a near-duplicate row instead of failing, so nothing ever complains.
val missing = Programs.ALL.flatMap { p -> p.entries.filter { it.name !in catalogue } }
assertEquals(emptyList(), missing) // list the offenders, don't just count
Name uniqueness — case-insensitively when lookups are. Two rows differing only by case both match; the loser is unreachable, and
forName(x).fieldsilently returns the wrong row's value.Enum-stored-as-String validity. A
Stringcolumn holding an enum name compiles with any typo and throws atvalueOfon read — the persisted-enum launch crash. Assert every value is inEnum.entries.map { it.name }.Prerequisite acyclicity for any progression tree. A loop locks every member forever: each waits on another, and no play can open them. Invisible in-app; only a walk finds it. Dangling-reference and unlock-gating tests both pass on a cyclic graph — that is why this needs its own test.
// single nullable parent -> ancestor walk; ordered set so the message shows the path
val parentOf = ALL.associate { it.name to it.requires }
ALL.forEach { skill ->
val seen = linkedSetOf(skill.name)
var cursor = skill.requires
while (cursor != null) {
assertTrue("prerequisite loop: ${seen.joinToString(" -> ")} -> $cursor", cursor !in seen)
seen += cursor; cursor = parentOf[cursor]
}
}
Multiple parents -> DFS colouring instead. Acyclicity + the existence check together imply every chain terminates at a real root, i.e. full reachability.
Also cheap and worth it: non-empty child lists, numeric fields > 0, scheduling
keys unique (two programs on one weekday makes "today" depend on list order),
and domain coherence — e.g. a load may only sit on an item that can carry one
(weight > 0 ⇒ inherentlyWeighted || modifier says so), otherwise the UI renders
an unexplained value.
Mutation-prove every invariant
An invariant asserted over a constant list can trivially be vacuous. Break the real data once per invariant and confirm the matching assertion fires:
- misspell one cross-reference → existence test names it
- duplicate one name → uniqueness test (expect collateral failures: one duplicate commonly breaks 3–4 tests, including value lookups)
- typo one enum string → enum test
- point a parent at its own child → loop test prints the path
Commit first, then revert each mutation with git checkout -- <file> in the same command (a .bak
copy can be deleted mid-run) and re-run the gate after; mutation mechanics are in
gradle-mutation-proof-regression-test.
Traps
- Read the accessors first. The composed public list is often built from a
privatebase list plus extras; test the public one or the test misses rows. - Confirm the test path is new (
git log --oneline -1 -- <path>) beforewrite— overwriting an existing test file deletes cases with no compile error. - Capture gradle's real exit code (
cmd > log; EXIT=$?), not a pipeline's — piping throughsedmakes&&gate onsed's status, so a red build can still commit.