fix(deps): pin tree-sitter-language-pack to the range where get_parser().parse(bytes) works (#253)

[cdeust]

Closes #253. Also closes #249 and #251 — three filings of the same defect, and
this change meets all three acceptance-criteria lists (reconciliation below).

The defect, and what was under it

The pyright gate is zero-diagnostic, but its input was not pinned. CI
installs the hash-pinned export of uv.lock; the documented developer install
resolved pyproject.toml's tree-sitter-language-pack>=0.24.0,<1.14. The two
landed seven minor versions apart, so the same commit reported 1 error to a
contributor and 0 to CI.

Probing every published wheel to find where the type surface actually changes
turned up a live runtime defect the old floor admitted:

version	SupportedLanguage	get_parser →	parse(b"...")	pyright
≤1.6.2	179-name Literal, no csharp	SupportedLanguage param	ok	1 error
1.6.3	macOS wheel ships no package	—	—	—
1.7.x	never published (PyPI goes 1.6.3 → 1.8.0)	—	—	—
1.8.0	symbol absent entirely	str param	—	1 error
1.9.0–1.12.2	306-name Literal	builtins.Parser	TypeError: 'bytes' object is not an instance of 'str'	1 error
≥1.12.5	306-name Literal	tree_sitter.Parser	ok	0 errors

_get_extractor_and_tree calls get_parser(language).parse(content) with
content: bytes and catches only ImportError, so on any 1.9.0–1.12.2
resolution codebase_analyze / seed_project die with an uncaught TypeError
on the first file. The pin's own comment described that window ("1.7.0+ …
AttributeError on instances of builtins.Parser") while the pin it annotated
said <1.14 and admitted it.

What changed

1. pyproject.toml — floor >=0.24.0 → >=1.12.5, with the measured
   per-release table above as a # source: comment. (>=0.24.0 never matched
   a 0.x release anyway: the pack goes 0.13.0 → 1.0.0.) uv lock re-run with
   the CI-pinned uv 0.11.3; resolution unchanged at 1.13.5, so no requirements
   file moved.
2. mcp_server/core/ast_parser.py — _EXTRACTORS is keyed by the pack's
   SupportedLanguage literal (so the checker validates every grammar name
   against the pack the environment resolved), AST_SUPPORTED is derived
   from that table instead of restated beside it, and _is_ast_language is a
   TypeGuard that narrows before get_parser. Deriving the set deleted an
   unreachable arm: AST_SUPPORTED == set(_EXTRACTORS) held exactly, so
   if not extractor: return None could never fire (§9), and
   _EXTRACTORS[language] is now total after the guard.
3. CONTRIBUTING.md / CLAUDE.md — both documented installs resolve from
   uv.lock (uv sync), not from the ranges, plus a new
   Reproducing the pyright gate locally section with the exact environment CI
   builds.
4. .github/workflows/ci.yml — the Type Check job prints the three package
   versions its verdict depends on, one grep per package so a missing one
   fails the step instead of degrading to Unknown inside pyright.

Completion Ledger (§13.2)

Paths introduced by the diff

Path in git diff origin/main...HEAD	Evidence
_is_ast_language returns True (name in AST_SUPPORTED)	test_is_ast_language_accepts_every_declared_name
_is_ast_language returns False	test_is_ast_language_rejects_names_outside_the_set ("", cobol, Python, text)
_get_extractor_and_tree early return on unsupported language	test_unsupported_language_falls_back_before_touching_the_pack
_get_extractor_and_tree except ImportError → None	test_missing_pack_falls_back_instead_of_raising (sys.modules[...] = None)
_get_extractor_and_tree success → (_EXTRACTORS[language], tree)	test_supported_language_with_an_extractor_parses
_EXTRACTORS[language] cannot KeyError	test_supported_set_is_exactly_the_extractor_table (equality, not inclusion)
AST_SUPPORTED names are real for the installed pack	test_every_supported_name_is_typed_by_the_installed_pack (get_args) + test_every_supported_name_parses_bytes
is_available() True / False arms (touched file, previously unasserted)	test_is_available_is_true_when_the_pack_imports / test_is_available_is_false_when_the_pack_is_absent
build_extra_extractors return-type change	test_every_supported_name_parses_bytes exercises all 7 of its keys; pyright validates them against the literal
CONTRIBUTING's uv sync extras == ci-typecheck.txt set	test_extras_match_the_ci_typecheck_constraint_set
… groups == typecheck-tool.txt set	test_groups_match_the_typecheck_tool_constraint_set
… --no-default-groups on both sides	test_default_groups_are_excluded_like_the_export
… runs pyright from that venv	test_pyright_is_run_from_that_environment
… names the failure mode in both docs	test_range_resolution_is_documented_as_forbidden
ci.yml installs the hash-pinned files	test_job_installs_the_hash_pinned_files
ci.yml installs the project --no-deps	test_job_installs_the_project_without_resolving_its_ranges
ci.yml never range-installs an extra	test_job_does_not_pip_install_an_extra_range
ci.yml records the resolved type surface	test_job_records_the_resolved_type_surface

Negative controls run for the parity gate (each edit reverted after):
removing --extra otel from the documented block → test_extras_match_…
fails; replacing ci.yml's --no-deps -e . with pip install -e ".[dev,…]" →
test_job_installs_the_project_without_resolving_its_ranges and
test_job_does_not_pip_install_an_extra_range fail.

§13.1 checklist

• A1/A2 happy + edge paths: table above. Edge cases enumerated for the
  narrowing input — empty string, unknown name, wrong case, non-language text.
• A3 every failure path asserted by its observable effect: both None
  returns and the ImportError degraded mode have tests; there is no signal
  emission on these paths (the fallback to the regex parser is the contract).
• A4 input validated at the boundary: detect_language output is narrowed
  before it reaches the pack; nothing else crosses.
• A5/A6 N/A: pure functions, no partial state, no retry semantics.
• B1–B3 N/A: no concurrency touched.
• C1 the guard is O(1) (frozenset membership) and replaces an O(1) dict
  .get; no new loops. C2 no resources. C3 no hot path measured
  because none moved.
• D1–D3 N/A: no queries, no secrets, no new untrusted input (the language
  name was already derived from a path).
• E1 API change is the dependency floor, documented in CHANGELOG; the
  public AST_SUPPORTED keeps its value and membership semantics.
  E2 consumers: tests_py/core/test_ast_extractors_multilang.py (imports
  AST_SUPPORTED) and parse_file_ast — both pass. E3 N/A: no persisted
  format. E4 the pin covers macOS/Linux/Windows wheels for cp310-abi3.
• F1/F2 N/A: no new failure mode emits a signal; the existing degraded
  mode (regex fallback) is unchanged and asserted.
• G1 ledger above. G2 regression control: the contract test fails on
  a version the old pin admitted — under tree-sitter-language-pack 1.12.2,
  test_every_supported_name_parses_bytes and
  test_supported_language_with_an_extractor_parses fail with the TypeError.
  G3 deterministic: no temp paths, no sleeps, monkeypatch scoped.
  G4 negative assertions present (_is_ast_language False arm,
  test_job_does_not_pip_install_an_extra_range). G5 below.
• H1 SOLID/layering/sizes/DI/local-reasoning hold: ast_parser.py is 267
  lines, every function under 50, core still imports only core+shared, the new
  pack import is TYPE_CHECKING-only. H2 the unreachable arm is gone.
  H4 CHANGELOG entry added. H5 one logic commit.
  H7 boy-scout: below.

Evidence (commands + output)

$ .venv/bin/python -m pyright mcp_server/          # locked 1.13.5
0 errors, 0 warnings, 0 informations

$ .venv/bin/python -m pyright -p <cfg with 1.13.6 on extraPaths> mcp_server/
0 errors, 0 warnings, 0 informations               # newest the pin admits

$ .venv/bin/python -m pyright -p <cfg with 1.12.5 on extraPaths> mcp_server/
0 errors, 0 warnings, 0 informations               # the new floor

Paired control, same tree, versions the new pin excludes:

1.6.2  -> 1 error   ("csharp" is not in that release's SupportedLanguage)
1.9.0  -> 1 error   (parse(source: str) rejects bytes)
1.11.0 -> 1 error
1.12.0 -> 1 error
1.12.1 -> 1 error
1.12.2 -> 1 error

Runtime probe of the same window:

$ PYTHONPATH=<tslp 1.12.2> python -c "from tree_sitter_language_pack import get_parser; get_parser('python').parse(b'x')"
  parser type: builtins.Parser
  parse(bytes) FAILED: TypeError 'bytes' object is not an instance of 'str'
$ PYTHONPATH=<tslp 1.12.5> ...
  parser type: tree_sitter.Parser
  parse(bytes): module

Suite, lint, and the repo's own gates (G5):

$ pytest -q                       # sqlite backend, DATABASE_URL unset
6367 passed, 81 skipped, 3 warnings, 117 subtests passed in 123.48s

$ ruff check .                    -> All checks passed!
$ ruff format --check .           -> 1069 files already formatted
$ python3 scripts/generate_pip_constraints.py --check   -> requirements OK (13 checked)
$ python3 scripts/check_doc_claims.py --test-count 6448 -> doc claims OK
$ python3 scripts/generate_repo_badges.py --check --test-count 6448 -> badges OK (5 checked)
$ actionlint .github/workflows/ci.yml                   -> no findings

Mutation testing (§12), scoped to the changed file:

$ scripts/mutation_check.sh tests_py/core/test_ast_parser_language_contract.py \
                            mcp_server/core/ast_parser.py
171/171  🎉 8  🫥 163
>>> survivors (must be empty, or documented equivalents):
  none — 0 surviving mutants 🎉

All 8 mutants of the changed functions (is_available, _is_ast_language,
_get_extractor_and_tree) were killed; the 163 the run reports as "no tests"
belong to parse_file_ast (57), _extract_module_doc (37) and the per-language
extractors, which this scoped selection does not import — untouched by this
diff and covered by other test files (§12.1 scopes the blocking tier to the
changed lines).

Boy-scout (§14) — H7

• Fixed here: four pre-existing shellcheck findings in the touched
  ci.yml (SC2015 ×3 — A && B || C retry loops rewritten as
  if …; then break; fi; SC2034 — unused loop variable). actionlint .github/workflows/ci.yml now reports nothing; it reported 4 before.
• Fixed here: the stale pin comment (claimed <1.7 while pinning <1.14)
  and the >=0.24.0 floor that matches no 0.x release of this package.
• Deferred with an issue number: the suite emits 3
  DeprecationWarnings for the stdlib sqlite datetime adapter at
  mcp_server/infrastructure/sqlite_compat.py:287. Fixing it changes the
  on-disk datetime spelling (§13.1 E3) and needs its own migration decision;
  filed as sqlite_compat.py relies on the deprecated stdlib datetime adapter (3 DeprecationWarnings in the suite) #260, outside this change's blast radius (no import path from
  core/ast_parser.py).

Reconciliation with #249 and #251

Their AC	Where it is met
#249-1 narrow at the guard, no cast	_is_ast_language TypeGuard + frozenset[SupportedLanguage]; no cast, no type: ignore
#249-2 reproducible env from the lock, version quoted in the job log	CI already installs requirements/ci-typecheck.txt (exported from uv.lock, --require-hashes, gated by generate_pip_constraints.py --check); the new Record the resolved type surface step prints it
#249-3 0 errors under both the lock and an unconstrained resolution	1.13.5 (locked) and 1.13.6 (newest admitted) runs above
#249-4 job fails loudly if the env differs from uv.lock	--require-hashes + the --check Lint step; the version probe fails on a missing package
#251-1 uv sync + pyright reports 0	documented command in CONTRIBUTING, asserted equal to CI's set by the parity test
#251-2 lock bumped / CI from lock / narrowed	all three: lock at 1.13.5, CI installs from it, floor narrowed to the measured range
#251-3 note in CONTRIBUTING/CLAUDE.md	added — they are not allowed to differ, and the note says so

CI on the pushed tree (H6)

Run 30477779566 —
all 18 required checks pass (Lint, Type Check, Build Package, Test 3.10/3.11/
3.12/3.13, Test SQLite, Test Windows-SQLite, 3× CodeQL Analyze, 2× Docker
Build, Docker Smoke, 2× Fuzz PR batch). The Type Check job's new step and its
verdict:

Type Check  Record the resolved type surface   pyright==1.1.410
Type Check  Record the resolved type surface   tree-sitter==0.26.0
Type Check  Record the resolved type surface   tree-sitter-language-pack==1.13.5
Type Check  Run pyright (zero-diagnostic gate) 0 errors, 0 warnings, 0 informations

That is the same tree-sitter-language-pack a lock-derived developer install
now resolves — which is the whole point of #253.