[derek73]

Part of #747. #750 (the titles) waits for this, so its words land in a checked order.

What

tools/vocab/build.py gains check 10: every language file except und.toml lists its words in one canonical order, and the build refuses a file out of order, naming the entry to move and where it belongs (en.toml: 'snr' (generation) belongs after 'sr'. …). The entry it names is the first one outside the longest run already in order, and its place is given against that run, so following the messages takes the fewest moves and a word appended at the end of a file is the one named. It checks and never rewrites a file, because a comment above an entry belongs to it and must move with it, which no TOML reader can see. Check 10 runs last, so an exclusion's reason (check 6) or a same_as naming no word (check 7) is reported first.

The order:

1. By kind, in CATEGORY's order. It already listed each category's kinds together and the README's kind table already followed it; an import-time assert now keeps the kinds of a category together, and the README test is now sensitive to the table's order. A word with several readings sorts under its first kind. An entry that only records a refusal (senior, fils) sorts under the kind it refuses; a name reading places an entry only when it has nothing else.
2. Then by its same_as chain, starting from the word at the root, with the head first: jr, jnr, junior, then sr, snr. Because the whole chain is used, el- keeps its own spellings after it inside the al- group in ar.toml, where sorting by the direct target alone would have split them. Only the file's own entries are followed, so another file's chain never decides this file's order.
3. Then by text, in codepoint order of the normalized text. That order is defined for every script and is no one language's collation. The costs are that within a script an accented letter comes after z (aḍ- after az-), and that traditional and simplified spellings with no same_as between them end up apart (課長, 课长).

und.toml is exempt: its vetting comments point along the order of the Python lists it came from ("the bare-κ trap above"). A same_as chain that loops back on itself (e.g. jr → jnr → jr) is refused in every file, und.toml included. The check looks at every same_as written, across files and kinds, because nothing holds a word to a single head.

Data

The first commit sorts the 41 of 71 language files that were out of order on cc030b9. Whole entries move and nothing inside an entry changes. The second commit adds the check, so each commit builds.

Docs

• nameparser/vocab/README.md: a new "Word order" section, and the "Adding a word" steps now point to it.
• decisions/vocabulary-model: a dated bullet recording why the order is checked rather than rewritten, why it uses the chain rather than the direct target, why codepoint order, and why und.toml is exempt.

Verification

• uv run python tools/vocab/build.py --check: _compiled.py is current (byte-identical).

• tools/differential/snapshot.py: matches the snapshot.

• Full suite: 21,909 passed, 123 skipped, 3 xfailed. mypy and ruff are clean.

• New rows in tests/v2/test_vocab.py cover a swapped pair, kinds and categories out of order, a variant before its head, a variant away from its head, refusals placed outside their kind, and loops in a language file and in und.toml. The accepted shapes cover a head before its spellings, a refusal beside a name reading, a comment moving with its entry, the ar.toml chain, two scripts in one file, and und.toml out of order passing.

• Review rounds. /pr-review-toolkit:review-pr ran five reviewers, and dd7b335 fixes what they found:

  • the check ran ahead of check 6;
  • the message named an untouched neighbour;
  • some same_as loops passed;
  • another file's chain decided this file's order;
  • a comment quoted from und.toml pointed the wrong way.

  A second-round review of dd7b335 found that the given place could be beside an entry that was out of place itself (up to 22 moves where 10 would do), plus a hang when check_order is called on its own and a RecursionError on a very long chain. 0a223d8 fixes all three. Each new row fails against the commit before its fix: some raise nothing, the rest name the wrong entry or the wrong loop. test_following_the_order_messages_takes_the_fewest_moves checks the move count over every order of six words.

• Negative controls, measured: with check_order disabled, every order row compiles, so the check is what refuses each one. Under a plain-text key, the two variant rows pass, so only the head-first grouping fails them. Under a direct-same_as key, the ar.toml chain shape fails.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.05%. Comparing base (cc030b9) to head (0a223d8).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #767   +/-   ##
=======================================
  Coverage   99.05%   99.05%           
=======================================
  Files          47       47           
  Lines        4642     4642           
=======================================
  Hits         4598     4598           
  Misses         44       44           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.