chore: adopt toml-sort layout and ignore TC001-TC003

[Jamie-BitFlight]

Provenance — read this first

Commit 1 (58fdfab) is pre-existing uncommitted work recovered from the working tree on main. It was not authored in this task. It was sitting unstaged and orphaned; it is committed here verbatim, unmodified, so it is recoverable and reviewable. It has not been reformatted, corrected, or extended.

Commit 2 (bae1c1f) is the only work authored here.

Commit 1 — 58fdfab recovered work

• pyproject.toml (+373 lines changed): wholesale toml-sort reformat — tables alphabetised, comment alignment collapsed; new [tool.tomlsort] plus ~10 [tool.tomlsort.overrides.*] tables; [dependency-groups] repositioned; toml-sort and uv-sort added as dev dependencies.
• It also adds lint.isort.required-imports = ["from __future__ import annotations"], which is absent from origin/main.
• uv.lock (+205 lines): matches the new dev dependencies. Does not move ruff — still 0.14.8, same as origin/main.
• CLAUDE.md: full prose rewrite.

Commit 2 — bae1c1f TC001-TC003 ignores

TC (flake8-type-checking) is in extend-select (pyproject.toml:104). Convention here is that required-imports = ["from __future__ import annotations"] and the TC rules must never both be active: TC moves annotation-only imports into TYPE_CHECKING, which raises NameError at runtime on Python 3.10-3.13 for anything resolving annotations at runtime. Commit 1 introduces required-imports, so it introduces the hazard; these three ignores neutralise it.

Spelling is codes, not names. uv.lock resolves ruff 0.14.8 and .pre-commit-config.yaml:56 pins ruff-pre-commit at v0.14.4 — both predate rule-codes-in-selectors/RUF201. Confirmed against the modified lock: uvx ruff@0.14.8 rule RUF201 returns error: invalid value 'RUF201', while uvx ruff@0.14.8 rule TC001 resolves.

No suppressions beyond these three entries.

Gate result

The blocking jobs in .github/workflows/test.yml are format, lint, typecheck, test-linux, test-macos, test-windows. There is no pytest job, despite [tool.pytest.ini_options] existing (pyproject.toml:41) — and its testpaths = ["tests"] (pyproject.toml:50) names a directory that does not exist; the repo has test/.

Job	Command	Baseline origin/main	This branch
format (test.yml:42)	uv run ruff format --check packages/	exit 0	exit 0
lint (test.yml:65)	uv run ruff check --output-format=github packages/	exit 0	exit 0 (see below)
typecheck (test.yml:89)	uv run mypy packages/ --show-error-codes	exit 0	exit 0
test-* (test.yml:116)	uv run ensure-uv	exit 0	exit 0
test-* (test.yml:119)	uv run python -c "from ensure_uv import main; ..."	exit 0	exit 0

Baseline was measured in a throwaway git worktree on origin/main (3301c47) and was fully green — nothing is already failing upstream. The worktree has been removed.

Behavioural change the recovered work causes — not fixed here

[tool.ruff] fix = true (pyproject.toml:53), with unsafe-fixes = true (:56). Because commit 1 adds required-imports, the lint job now finds an I002 violation in packages/ensure_uv/__init__.py (it lacks from __future__ import annotations; main.py and version.py have it) and silently rewrites that file in place, then exits 0. So the gate passes, but CI's checkout is mutated and the committed source is not required-imports-clean.

Per instruction this was left exactly as the work was found. The one-line fix, if wanted, is adding from __future__ import annotations to packages/ensure_uv/__init__.py.

TYPE_CHECKING audit

Exactly one hit repo-wide: test/setup_test_project.py:17-20, from collections.abc import Sequence under if TYPE_CHECKING:, used only in annotations (Sequence[str]) — a TC003 shape. Runtime-safe as written, since that file has from __future__ import annotations at line 8. It is outside the gate's scope: every CI command targets packages/ only. Nothing in packages/ has a TYPE_CHECKING block.

Note on local verification

Local uv sync (full dev group) cannot complete on the author's machine: basedpyright pulls nodejs-wheel-binaries, which has no wheel for this platform and fails its CMake source build. The disk is also at 100%. Both are environment problems, unrelated to this branch, and they affected baseline and branch identically. Gate tools were therefore run via uvx pinned to the lockfile versions (ruff@0.14.8, mypy@1.19.0) with uv sync --no-dev for the entry-point jobs. The local prek hooks could not install for the same reason, so both commits used --no-verify; CI is the authoritative check.

Do not merge without review.

---

Second pass — basedpyright removal, prek autoupdate, mypy → ty

Four further commits on this branch, each self-contained.

Commit	Change
245283c	chore(deps): remove basedpyright dependency + hook
36ea52f	chore(config): replace the [tool.basedpyright] config with typeCheckingMode = "off"
a0082ec	chore(prek): prek autoupdate
091cb0c	refactor(typing): replace mypy with Astral ty

245283c — basedpyright removed

Removed via uv remove --group dev basedpyright (never hand-edited; uv.lock regenerated), plus the basedpyright-prek-mirror hook block from .pre-commit-config.yaml.

This fixes local uv sync. The note at the bottom of the original body was correct: basedpyright pulls nodejs-wheel-binaries, which has no wheel for macOS 12 and whose CMake source build fails. Measured this session:

• Before: uv sync fails — *** CMake build failed, with uv's own hint: `nodejs-wheel-binaries` (v24.11.1) was included because `ensure-uv:dev` (v0.1.0) depends on `basedpyright` (v1.35.0) which depends on `nodejs-wheel-binaries`
• After: uv sync → Resolved 32 packages, Checked 25 packages, exit 0.

Consequently the gate in this pass was run natively via uv run …, not via pinned uvx invocations as in the first pass.

The uv.lock diff (+20/−50) contains no unrelated version bumps — only the removal of basedpyright and nodejs-wheel-binaries, plus marker simplification that falls out of dropping them.

36ea52f — basedpyright disabled rather than configured

Correction to a premise carried into this task: a [tool.basedpyright] stanza did already exist (pyproject.toml:187, typeCheckingMode = "basic", ten keys). It was replaced wholesale, not added.

091cb0c — mypy → ty

• uv remove mypy, uv add --group dev ty → ty>=0.0.75 (0.0.75 confirmed as latest on PyPI this session).
• [tool.ty.src] include = ["packages"]. packages/ is the only source directory in this repo and the sole target of the CI typecheck job. No [tool.ty.environment] — that table exists in the reference repo purely for a scripts/ sibling-import layout this repo does not have, so it would be dead config here.
• [tool.mypy] reduced to exclude = [".*"], keeping editor-launched mypy quiet without a second checker second-guessing ty.
• .pre-commit-config.yaml: the local mypy hook replaced by a local ty hook (entry: uv run -q ty check, language: system, pass_filenames: true).
• CI typecheck job (test.yml:89): uv run mypy packages/ --show-error-codes → uv run ty check packages/.

Error count: ty reports 0, mypy reported 0. No suppressions were added — no # type: ignore, no # ty: ignore, no cast(), no loosened config.

The ty hook uses pass_filenames, which bypasses [tool.ty.src], so it also reaches test/setup_test_project.py. Checked explicitly: uv run ty check test/*.py → All checks passed!.

uv run toml-sort --check pyproject.toml exits 0, so the new table placement matches the [tool.tomlsort] ordering already committed in 58fdfab (which already listed tool.ty in sort_first and carried [tool.tomlsort.overrides."tool.ty"]).

a0082ec — prek autoupdate

Repo	Old	New	Language
sync-pre-commit-deps	v0.0.3	v0.0.5	python
ruff-pre-commit	v0.14.4	v0.16.5	python
markdownlint-cli2	v0.19.1	v0.23.2	node
mirrors-prettier	v3.1.0	v4.0.0-alpha.8	node
shellcheck-py	v0.11.0.1	v0.11.0.1-1	python
pre-commit-shfmt, pre-commit-hooks	—	already up to date	—

Three things reviewers should see:

1. Both Node hooks are uninstallable on this machine — but were already, before the bump. prek's bundled Node 26.8.1 cannot run under macOS 12.7.6:

dyld[34900]: Symbol not found: (__ZNSt3__122__libcpp_verbose_abortEPKcz)
  Referenced from: '/Users/…/.cache/prek/tools/node/26.8.1/bin/node'
  Expected in: '/usr/lib/libc++.1.dylib'

prek run markdownlint-cli2 and prek run prettier both fail with Failed to install hook … Command 'npm install' exited with an error … signal: 6 (SIGABRT) and that same dyld error. This was verified at the old revs too by temporarily restoring the pre-autoupdate config: v0.19.1 and v3.1.0 fail identically. So autoupdate did not cause this, and nothing was reverted or hidden behind SKIP=. It is a local-environment limitation only: the separate prek and pre-commit workflow jobs (prek - macos-latest, prek - windows-latest, pre-commit - macos-latest, pre-commit - windows-latest) all pass on this branch's head, so the bumped Node hooks install and run correctly in CI.

2. mirrors-prettier was bumped to a pre-release, v4.0.0-alpha.8. That is what autoupdate selected; flagging it rather than silently pinning it back.

3. The ruff hook and CI now run different ruff versions. The hook is v0.16.5; CI runs uv run ruff, which resolves to the locked 0.14.8. On this source they disagree:

$ uvx ruff@0.16.5 check --no-fix --output-format=concise packages/
packages/ensure_uv/__init__.py:1:1: missing-required-import: [*] Missing required import: `from __future__ import annotations`
packages/ensure_uv/version.py:21:62: noqa-comments: [*] `noqa` comment used instead of `ruff: ignore`
packages/ensure_uv/version.py:22:61: noqa-comments: [*] `noqa` comment used instead of `ruff: ignore`
packages/ensure_uv/version.py:23:53: noqa-comments: [*] `noqa` comment used instead of `ruff: ignore`
packages/ensure_uv/version.py:51:45: noqa-comments: [*] `noqa` comment used instead of `ruff: ignore`
Found 5 errors.

$ uv run ruff check --no-fix --output-format=concise packages/   # 0.14.8, as CI runs it
packages/ensure_uv/__init__.py:1:1: I002 [*] Missing required import: `from __future__ import annotations`
Found 1 error.

All five are auto-fixable, and with fix = true the hook will rewrite them rather than fail. Not fixed here; flagged for a decision on whether to bump the locked ruff to match the hook.

fix = true auto-write finding — still present, unchanged

Re-confirmed after all four commits. Running the lint job command verbatim on a clean tree:

$ uv run ruff check --output-format=github packages/
EXIT=0
$ git status --porcelain
 M packages/ensure_uv/__init__.py

--- i/packages/ensure_uv/__init__.py
+++ w/packages/ensure_uv/__init__.py
@@ -1,4 +1,5 @@
 """Pre-commit hook to ensure uv is installed and available."""
+from __future__ import annotations
 
 from .main import main

[tool.ruff] fix = true plus unsafe-fixes = true, combined with the required-imports added in 58fdfab, means CI's ruff check writes to its checkout and still exits 0. The gate passes while the committed source is not required-imports-clean. Left as found, per instruction.

Additional detail measured this pass: the file ruff's lint step writes is not what ruff format wants. After the lint job's rewrite, uv run ruff format --check packages/ exits 1, asking for a blank line after the docstring. The two jobs run on independent checkouts so they do not collide in CI today, but any workflow that ran lint then format in one checkout would fail.

One-line fix, if wanted: add from __future__ import annotations (followed by a blank line) to packages/ensure_uv/__init__.py.

Gate — baseline vs. this branch

Baseline is origin/main (3301c47), fully green, as established in the first pass. Every command below was run verbatim this session.

Job	Command	Baseline	After this pass
format (test.yml:42)	uv run ruff format --check packages/	exit 0	exit 0 — 3 files already formatted
lint (test.yml:65)	uv run ruff check --output-format=github packages/	exit 0	exit 0 (writes — see above)
typecheck (test.yml:89)	was uv run mypy packages/ --show-error-codes; now uv run ty check packages/	exit 0 (mypy: Success: no issues found in 3 source files)	exit 0 (ty: All checks passed!)
test-linux/macos/windows (test.yml:116)	uv run ensure-uv	exit 0	exit 0
test-linux/macos/windows (test.yml:119)	uv run python -c "from ensure_uv import main; print('Import OK')"	exit 0	exit 0 — Import OK

No new gate errors, and no suppressions were added anywhere in this pass.

Caveats

• All four commits used --no-verify: the local prek hooks still cannot all install (Node, above), so CI remains the authoritative check.
• The disk on the author's machine is at ~93 MB free on a 234 GB volume. No command failed on space during this pass, but it is tight.
• Follow-up, not created: the reference repo keeps its full typing standard in docs/TYPING_POLICY.md; this repo has no equivalent doc.

Do not merge without review.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9fb819e6-0079-4dd9-8774-f0a3072c93b7

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}