refactor(pieces): the shared surface loses its private marker

[derek73]

Follow-up to #441, which deliberately deferred this so its own diff could stay a verifiable byte-identical move.

Eight names in _pieces.py lose their leading underscore. No behavior change — proved mechanically below.

Why

Inside an already-private module the leading underscore marks module-private. The two established shared modules keep that distinction without exception:

module	bare names imported elsewhere	underscored names imported elsewhere
_vocab	12	0
_state	5	0
_pieces	0	8

_vocab also keeps ten genuinely-internal helpers underscored — _dotted, _is_suffix_strict_n, _classify, _ROMAN — and none is imported anywhere. The signal is clean: bare means someone else calls this, underscore means don't.

_pieces inverted it, and the sharpest illustration was inside the file itself: Peel was bare and used only within the module, while _peel_walk was underscored and imported by both stages — the two most closely related names each wearing the wrong marker.

The cost isn't aesthetic. In _vocab, a reader deciding "may I call this from another stage?" answers it from the name. In _pieces that needed a grep, and _PERIOD_ABBREV (truly internal) looked exactly like _peel_trailing (the principal export). The module also advertises itself as _vocab's sibling — mirrors its docstring title, quotes its contract — so the one place it departed read as oversight rather than decision.

What changed

Renamed (8): is_title_piece, is_leading_title, leading_titles, is_suffix_piece, segment_holds_no_name, peel_walk, trailing_start, peel_trailing — 84 references across five files.

Kept: _PERIOD_ABBREV, which is internal. And Peel, which is a CapWords type name with no underscore to drop — its being internal today is incidental, since assign consumed it until #441 trimmed the import.

Settled in the same pass, being the same confusion pointed the other way: _group imported _vocab's bare PH and D as _PH/_D, adding back at the import site the marker the source module had deliberately dropped. They're imported under their own names now.

_pieces.py now states the convention rather than merely following it, so the next shared module has something to copy.

Verification

Proved a pure rename, mechanically. Applying the same substitution to origin/master's copy of each of the five files yields a result byte-identical to this branch — so the diff contains the rename and nothing else:

OK    nameparser/_pipeline/_pieces.py
OK    nameparser/_pipeline/_group.py
OK    nameparser/_pipeline/_assign.py
OK    tests/v2/cases.py
OK    tests/v2/pipeline/test_assign.py

Gate	Result
uv run pytest	5670 passed, 221 skipped, 10 xfailed
uv run mypy	clean (109 files)
uv run ruff check	clean
differential (default baseline)	80 intentional, 0 unexplained — unchanged

Docs

docs/design/decisions.md is deliberately untouched: its entries are dated snapshots naming symbols as they stood on those dates, which the #441 docs review confirmed needs no amendment. mechanisms.md's Lives in is a live map and moves with the code.

One thing worth recording

The rename script's guard refused to run at first: two test comments already wrote is_leading_title() without the underscore, informally naming the very function being renamed. The first draft flagged any textual occurrence of a new name; checking for bound names instead (def/class/import/assignment) let it through — and the rename makes those two comments literally correct.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.59%. Comparing base (f1ef995) to head (42b9f6a).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #442      +/-   ##
==========================================
- Coverage   98.59%   98.59%   -0.01%     
==========================================
  Files          45       45              
  Lines        3068     3067       -1     
==========================================
- Hits         3025     3024       -1     
  Misses         43       43              

☔ 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.