Add tools/name_usage.py: count a word's bearers as given and family name

[derek73]

Adds tools/name_usage.py, a dev-only lookup that answers "how often is this word borne as a given name, and as a family name?" with counts instead of memory.

Why

Vocabulary claims are weighed by decisions.md#vocabulary-collisions: a word the parser claims by position (titles, never-given particles) is safe to claim outright only if it is not borne as a name in the position the claim acts on (C-i; #salutation-titles records the one TITLES-only exception, decided on counts). That check has often been run from memory, which misses what the data shows at once. shehu, a title, is also an Albanian and Nigerian surname: 561 bearers in the 2010 US Census, and 180 people on Wikidata, mostly Nigerian and Albanian citizens.

What it does

uv run python tools/name_usage.py shehu greve marshal
uv run python tools/name_usage.py McDonald     # pass names as written
uv run python tools/name_usage.py --no-wikidata knight   # offline, downloads nothing
uv run python tools/name_usage.py --json justice

One row per source, given and family counts, plus Wikidata's top countries of citizenship per role (which tells you whether a surname collision is in a culture that writes the surname first):

source	license	a count means	how it's fetched
US Census 2010 surnames	public domain	bearers; unlisted shows <100	downloaded once into a cache outside the repo, validated before caching
US SSA given names, 1880 onward	CC0	births summed over years, a floor (+); unlisted shows <5/yr	by hand: ssa.gov returns 403 to scripts, so the tool says where to save the zip
Wikidata P735 / P734	CC0	people with the statement, a lower bound (+); a zero proves nothing	live SPARQL, every spelling in one query

It reports; it does not decide. Every row carries a status (ok, unrepresentable, not downloaded, failed), so "no answer" is never shown as 0. The exit status is 2 when any source failed. The cache lives in $NAMEPARSER_TOOLS_CACHE or ~/.cache/nameparser-tools, so no third-party data enters the tree.

Notes

• Both US lists spell names in ASCII letters only (O'Brien → OBRIEN). The fold transliterates letters NFKD leaves whole (Sørensen → SORENSEN, Strauß → STRAUSS) and drops apostrophes, including modifier letters like the ʻokina. A letter with no ASCII spelling makes the word unrepresentable, never a partial lookup of a different name.
• Wikidata labels match exactly, in four spellings: as written, lower-case, capitalized per word, and title case. No rule rebuilds an internal capital, so mcdonald finds 0 where McDonald finds 1,968. The report lists the spellings tried, and the docstring and AGENTS.md say to pass names as written.
• A country with no English label is named by its Q-id, and an "unknown value" citizenship is named as unknown. Only a person with no citizenship statement at all counts as "no citizenship stated".
• I tried a label-position search ("does the word open people's names?"), which would answer the rule's position question directly. It timed out on the query service, so it's not included.
• AGENTS.md's "Adding a word to a config set" and "Titles permanently shadow first names" paragraphs now point at the tool.

Review

Ran /pr-review-toolkit:review-pr (code, tests, comments, errors, types), fixed what it found in 088d44d, then reviewed that fix commit, which turned up four defects the fix had introduced; those are fixed in bd76515. A simplification pass followed (8cd6781). The findings that mattered were all false zeros:

• The original fold deleted ø/ß/Ł, so Sørensen reported 0 against a Census count of 28,069.
• A wrong SSA zip read as empty, so every word reported 0.
• Summing per-spelling queries double-counted people.
• The first fix's SSA validation sat outside any try, so it crashed the run.

Tests

tests/v2/test_name_usage_tool.py: 33 offline tests behind an autouse guard that fails any network call (with a test proving the guard bites). Negative controls re-taken after the last test commit:

• no transliteration: 6 tests fail
• lossy fold allowed: 1 fails
• SSA year check off: 2 fail
• role check off: 1 fails
• modifier letters not skipped: 1 fails
• SSA load unguarded: 1 fails

Full suite at the first commit: 15,008 passed. Ruff and mypy are clean, and the tool also passes mypy --strict.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.02%. Comparing base (73a6b4a) to head (8cd6781).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #651   +/-   ##
=======================================
  Coverage   99.02%   99.02%           
=======================================
  Files          46       46           
  Lines        4513     4513           
=======================================
  Hits         4469     4469           
  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.