feat: speak filenames, paths and semantic versions

[StuBehan]

Two things in normalize_for_speech - filenames and paths, then semantic versions.

filenames

Turns out espeak already spells extensions correctly on its own. .md is "em dee", .tf is "tee eff", .json is "jason", .txt is "tee ex tee". So we leave the extension alone, respelling it would just regress the cases it gets right.

What it gets wrong is everything around the extension. The dot is silent, so README.md comes out "readmee-emdee" glued together. Hyphens get swallowed too, so speech-normalization is one long word. A leading dot is silent as well, so .github is just "github", and ~/ glues into "tilde-slash".

So now,

• README.md -> "README dot md",
• docs/speech-normalization.md -> "docs slash speech normalization dot md",
• .github/workflows/ci.yml -> "dot github slash workflows slash ci dot yaml",
• src/cli.py:42 -> "line 42 of cli dot py in src" - line number still leads because thats the signal, path trails as a prepositional phrase like you'd actually say it,

.yml is the one extension espeak really mangles (it reads as "immle"), so that aliases across to yaml.

The bare-filename matcher is gated on an extension allowlist rather than any old word.word, because prose is full of lookalikes espeak already reads fine - os.path.join, e.g., U.S., example.com. An allowlist drops all of those for free. Single-letter extensions are deliberately not in it (.c, .h) since they'd turn J.R.R into "J dot R dot R", didn't feel worth the prose regression. Node.js and friends are carved out by name.

Nice side effect - spacing the dot fixed the dev-terms collision for nothing. cli.py used to come out C L I.py because . is a word boundary for \b. Now the stem is a standalone word, so the dict still corrects "kligh" to "see ell eye" and doesn't glue it on. No change to the dictionary at all.

versions

versions_to_words already handled the dotted digits, this does the rest of the semver string,

• 1.2.3-rc.1 glued into "three-arsee-one", now "1.2.3, rc 1",
• ^, > and < are silent, so ^1.2.3 sounded identical to an exact pin! now "compatible with 1.2.3",
• 1.x was "one ex", now "1 dot x",

And >= was broken by us, not by espeak - the = unit rule was splitting it into > equals, and a bare > voices as literally nothing, so >=1.2.3 was coming out as "equals 1 point 2 point 3". Which is the opposite of what it means. espeak reads an intact >= perfectly well, so speak_versions has to run before expand_units. Theres an ordering note on it so we don't undo that later.

Operators go semantic rather than literal - "at least", "at most", "above", "below", "exactly". ~ was already mapping to "about" via the units rule which is accidentally the right sense for a tilde range, so thats untouched.

Two guards in there worth keeping. Every operator needs a following digit so the rules stay in version context, and the boundary character gets re-emitted with a space so pip's glued requests>=2.0 doesn't fuse into "requestsat least". And a caret only counts at the start of a token, otherwise x^2 became "x compatible with 2" 🤦

Left 3.11 alone. A two-part version is indistinguishable from a real decimal, where digit-by-digit is the correct reading (770.72 -> "770 point 7 2"), so it needs a context heuristic rather than a rule change. There's a test pinning both together so the reasoning survives.

flags

Both get their own switch. filenames is new, versions ride on the existing expand_numbers, and theres a --no-filenames on the cli. Deliberately not on dev_terms - file refs used to be gated on that, which meant --no-dev-terms silently killed them too.

checking

Worth saying I checked the readings by phonemizing rather than guessing, ie confirmed README.md gives ɹiːdmiː.ɛmdiː before deciding what to change. That's how the "extensions are already fine" thing turned up - my first assumption was that we needed to spell them out, and that would have been wasted work.

236 tests, docs updated in docs/speech-normalization.md.

Does the "compatible with" wording for ^ seem right, or would you rather it just said "caret"?