fix(cli): resolve the glossary package-relative and report the outcome (#149)

[mmcky]

Fixes #149.

What was wrong

forward and init resolved their glossary candidates only against process.cwd(). The built-in glossaries ship inside this package and no edition repository carries one — I checked lecture-python.zh-cn, lecture-intro.zh-cn and lecture-python-programming.zh-cn, none has a glossary/ directory. So a resync launched from the target repo, a bench root, or anywhere a globally installed CLI is naturally invoked translated with no glossary at all. It logged nothing either way, and a bare catch {} swallowed parse errors, so a run that dropped terminology enforcement was byte-for-byte indistinguishable in its output from one that applied it. That unobservability is the worst of it — it made the difference unauditable after the fact, which is why #149 could only state the defect by construction rather than from the logs.

forward also had no --glossary escape hatch at all, so there was no way to override it even knowingly.

The fix

Resolution moves into one testable module, src/cli/glossary-loader.ts, shared by forward and init (both had the identical CWD-relative lookup, so both are fixed and the duplicate is gone). Precedence, reported on every run:

Order	Candidate	Behaviour
1	--glossary <path>	The only candidate when given — missing or malformed is a hard error, never a silent fallback to different terminology
2	<cwd>/glossary/<lang>.json, <cwd>/glossary-<lang>.json	Unchanged, so a project carrying its own glossary still overrides the estate defaults
3	<package-root>/glossary/<lang>.json	New — resolved relative to the installed CLI, not to the working directory

Every outcome is logged: ✓ Loaded built-in glossary for zh-cn — 357 terms (…) on success, or a warning that names every path tried when a language has no glossary anywhere. A candidate that exists but does not parse is now an error rather than a fall-through to a different glossary — silently translating against terminology you did not ask for is the same class of invisibility.

Bulk resolves once before the first file and threads the result through, so the load is logged once rather than per-file, and a bad glossary stops the wave rather than surfacing after N files have already been resynced against nothing.

On the suggestion to make a glossary-less run an error

#149's point 4 asks whether a glossary-less run should be an error for a language that has a built-in glossary. With resolution now package-relative, that case is unreachable by construction — zh-cn, fa and fr always resolve. The remaining warning path is exactly the legitimate case: a language with no glossary anywhere. So the warning stays a warning, and the two genuinely-wrong cases (explicit path unusable, existing file malformed) are hard errors. Happy to tighten further if you would rather it refuse outright.

Where import.meta.url lives, and why

The package directory is resolved in src/cli/index.ts and threaded into the commands as an option, matching what src/index.ts already does for the Action. The Jest CJS module registry cannot load import.meta.url, so putting it in forward.ts would have made the whole command untestable — the same trap src/rebase-siblings.ts documents. The entry point resolves it; the resolution logic stays in a unit-testable module.

Verification

Built and run from /tmp, a directory with no glossary, against the harness repos:

$ cd /tmp && translate forward -s …/test-translation-sync -t …/test-translation-sync.zh-cn -f lecture.md --test
  Content changes detected — resyncing (whole-file)…
✓ Loaded built-in glossary for zh-cn — 357 terms (…/action-translation/glossary/zh-cn.json)

Before this change that run silently used no glossary. Also confirmed live: -l ja warns and lists all three paths tried; --glossary /no/such.json prints ❌ Glossary not found at /no/such.json (--glossary) and exits 1.

21 new tests across two files — CWD-independence (the regression itself), precedence including explicit-path exclusivity, all three throw paths, the reporting on both success and miss, and an integration test asserting what the translator actually receives on the resync path from a working directory with no glossary, including that the glossary handed over contains Marginal distribution, the term whose absence surfaced this in QuantEcon/lecture-python.zh-cn#198. Full suite: 54 suites, 1270 passing (6 pre-existing skips); lint and format clean.

Not in scope

• Review mode silently ignores glossary-path — verdicts judged against the wrong terminology #146 (review mode ignores glossary-path) — the other half of the compounding pair described in translate forward loads its glossary CWD-relative and fails silently — resyncs can run with no glossary and nothing says so #149, untouched here.
• The 8 remaining lecture-python.zh-cn lectures carrying 边际分布 still need the content audit; Glossary: use 边缘分布 for "marginal distribution" in inventory_dynamics lecture-python.zh-cn#200 fixed only prob_matrix.md. This PR stops the bleeding, it does not clean up what already landed.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes CLI glossary resolution so translate forward and translate init reliably load the packaged (built-in) glossary regardless of the current working directory, and always report what happened (including loud failures for missing/malformed explicit glossaries), addressing #149.

Changes:

• Added a shared, testable CLI glossary resolver/loader (src/cli/glossary-loader.ts) with ordered precedence and explicit reporting.
• Wired forward and init to use package-relative built-in glossaries and to log success/miss consistently; forward gains a --glossary <path> override.
• Added focused unit + integration-style tests for resolution/precedence/reporting, and updated docs + changelog accordingly.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/cli/types.ts	Extends ForwardOptions to carry --glossary, built-in glossary dir, and an optional pre-resolved glossary for bulk runs.
src/cli/index.ts	Resolves <package-root>/glossary via import.meta.url and threads it into forward/init; adds forward --glossary.
src/cli/glossary-loader.ts	New module implementing ordered glossary resolution, strict parsing/validation, and consistent reporting.
src/cli/commands/init.ts	Switches to shared loader and ensures the load outcome is reported (and failures are loud).
src/cli/commands/forward.ts	Uses shared loader, adds a single-wave (bulk) pre-resolve path, and supports --glossary.
src/cli/tests/glossary-loader.test.ts	New tests for CWD-independence, precedence, loud failure, and reporting behavior.
src/cli/tests/forward-glossary.test.ts	New tests asserting the resync path actually passes the resolved glossary to the translator.
src/cli/tests/cli-smoke.test.ts	Updates smoke expectations to include --glossary on forward.
docs/user/glossary.md	Documents CLI resolution order, exclusivity of --glossary, and reporting behavior.
docs/user/cli-reference.md	Updates CLI reference for forward --glossary and revised init glossary description.
CHANGELOG.md	Records the fix and the new forward --glossary option under Unreleased.