Migration/step 08

[surchs]

Title: chore(migration): step 08 root pre-commit hooks
Branch: migration/step-08

Can be squash-merged or merged; it imports no history.

Summary

• Root .pre-commit-config.yaml: merges the configs of api, federation-api, bagel-cli and the docs, keeping every hook's upstream rev and arguments.
  • Each hook is scoped with files: ^tools/<tool>/ or ^docs/ and has an alias <hook>-<folder> for SKIP=.
  • Hooks that read config files get the tool's own file explicitly:
    • black --config=tools/<tool>/pyproject.toml
    • flake8 --config=tools/{api,bagel-cli}/.flake8 (federation-api keeps its inline args)
    • isort --settings-path=tools/<tool>/pyproject.toml
    • codespell --config=tools/api/.codespellrc / --config=docs/.codespellrc
    • mypy --config-file=tools/<tool>/pyproject.toml
    • markdownlint -c docs/.markdownlint.jsonc
    • markdown-link-check --config=docs/md_link_check_config.json
• Frontends: local hooks lint-staged-query-tool and lint-staged-annotation-tool run npx --no-install lint-staged in the tool folder, so the unchanged lint-staged.config.js files run typecheck, eslint and prettier on staged files. They fail with "Run npm ci in tools/ first" if node_modules is missing.
• Post-merge hooks: the husky post-merge hooks become pre-commit post-merge hooks, installed by a plain pre-commit install (default_install_hook_types: [pre-commit, post-merge]). After a merge or pull, they run npm ci in a frontend whose package.json or package-lock.json changed between ORIG_HEAD and HEAD. default_stages: [pre-commit] keeps every other hook off that stage.
• Removed:
  • "prepare": "husky" / "husky install" from both package.json files
  • both .husky/ folders
  • the four per-tool .pre-commit-config.yaml files
• CI:
  • New pre-commit job: all hooks on all files, skipping markdown-link-check-docs and the two lint-staged hooks.
  • New non-blocking markdown-link-check job.
• Docs:
  • Root README: new "Commit hooks" section, Step 8 row, and ci.yml description.
  • Python tool READMEs: uv run pre-commit install.
  • Frontend READMEs: hooks via the root config, with the npm ci prerequisite.
  • Docs README: style-guide section.

Checks run

Check	Result
SKIP=markdown-link-check-docs pre-commit run --all-files; git status --porcelain afterwards	exit 0, 31 hooks passed (plus the two lint-staged hooks with nothing staged); no file rewritten
Same with the CI job's SKIP and --show-diff-on-failure (replay of the CI step)	exit 0
pre-commit run markdown-link-check-docs --all-files (CI's non-blocking job)	exit 0 today (the OSF link that failed in the baseline answers again)
markdownlint uses the docs config	npx markdownlint-cli@0.47.0 -c docs/.markdownlint.jsonc docs/README.md and the hook both pass; with an added 110-character line both still pass, while markdownlint's defaults would report 16 × MD013
Scratch change: unused import os in tools/api/app/main.py	flake8: tools/api/app/main.py:1:1: F401 'os' imported but unused (discarded)
Scratch change: debugger; in tools/query-tool/src/App.tsx, staged	lint-staged hook: typecheck passes, eslint error Unexpected 'debugger' statement no-debugger (discarded)
npm ci in both frontends	exit 0, no husky output
Post-merge hooks, real merges in a scratch clone after pre-commit install	installs pre-commit and post-merge; merging a README-only branch runs no npm ci; merging a branch that changes tools/query-tool/package.json runs npm ci in query-tool only; fast-forwarding two commits where only the first changes tools/annotation-tool/package.json runs npm ci in annotation-tool (upstream's HEAD^ comparison would miss it)
scripts/check-unchanged.sh	OK
api / federation-api / bagel-cli tests; frontend static checks; annotation-tool unit tests	188 / 111 / 215; pass; 240
just lint	passes

Documentation check: in a fresh clone of this branch, run verbatim:

• uv run pre-commit install from tools/api, tools/federation-api and tools/bagel-cli installs the repository hook using the root .pre-commit-config.yaml.
• pip install pre-commit && pre-commit install from the root works.
• The root README's two-line all-files run, npm ci in both frontends and then SKIP=markdown-link-check-docs pre-commit run --all-files, exits 0 with no rewrites.
• Without npm ci, the frontend hooks print "Run npm ci in tools/query-tool first".

Deviations and findings

• isort: the first attempt passed --src=tools/<tool>, which isort resolved relative to the settings file (tools/api/tools/api). It treated app as third-party and rewrote 37 protected test files; those changes were discarded and never committed. Only --settings-path is passed now, matching upstream's grouping exactly.
• docker-compose-check: setting files: replaced the hook's built-in compose-file pattern, so it tried to parse every file in tools/api. Fixed with a compose-file pattern.
• check-github-workflows: now validates the root workflows (federation-api used it on its own workflows).
• Post-merge hooks, improved over upstream: upstream compared HEAD^ with HEAD for package.json only. That misses dependency changes in all but the last commit of a pull, and lockfile-only updates. The new hooks compare ORIG_HEAD with HEAD for both files.
• CI coverage: upstream ran these hooks through pre-commit.ci and the docs' pre-commit.yml. The new pre-commit CI job covers both. The ci: block stays in the config in case pre-commit.ci is installed on the repository.

🤖 Generated with Claude Code