Instruction file imported from ibanner56/CallersCompendium (
.github/instructions/imports-dialect.instructions.md). Copyright stays with the author.
Importers, dialect, and the figure taxonomy
These rules load for sessions touching the importers, the dialect decoders, or the taxonomy they validate against.
Fixtures are validated against the taxonomy — but not by dart test
Rendering substitutes rather than validates, so an invalid param renders
literally and every test still passes. A drifted fixture is therefore invisible
to a clean local dart test, and shows up only in CI — where it reads as
flakiness if you have forgotten that the local suite omits the check.
Run the ratchet yourself whenever you change a move's params:
(cd packages/compendium_core && fvm dart run tool/check_fixture_validity.dart)or python3 tools/preflight.py, which runs it along with everything else.
Every Figure(...) in either suite must be valid under contraTaxonomy, routed
through testFigure (which validates at run time, for fixtures built from
variables), or marked // invalid-fixture: <reason>. The marker is checked in
both directions: one that introduces no fixture is a stale claim the next fixture
written under it would silently inherit, so it fails rather than lying quietly.
Background: incidents.md.
"Declines to custom" depends on the decoder
Do not copy the claim that an absent map entry declines a line to custom. It is
true where the map is the sole recognizer (figure_parser.dart's partner-token
map) and false where decoders fall through to the shared recognizer and only add
params — the line still structures. When you touch one of these maps, judge the
comment in its context rather than making the two files agree.
Worked example, including the exact sentences and why a uniform sweep was wrong: incidents.md.
Display versus canonical
A rendering change is cheap. Putting the same value into canonical text changes FTS, dedupe and the derived projection, and therefore means a taxonomy bump, a migration and a derived rebuild. Decide which one an issue is asking for before scoping it.
A structured param is filterable the moment it exists; it is findable by typing its words into search only if it reaches canonical text.
Taxonomy changes falsify comments that never mention the taxonomy
Adding or splitting a move, or changing a ParamKind/choices pairing, can make
comments elsewhere untrue without any of them citing the taxonomy — and tests
that inject a synthetic taxonomy stay green. After such a change, grep for the
property you altered, not just for citations of the file you edited.