# AareDAQ project notes

## CI gates — run locally BEFORE every commit/push

CI enforces more than `ruff check` + green tests. Two extra gates diff
against `origin/main`, so they fail on changed lines that a plain lint or
full-suite pass never inspects (`git fetch origin main` first):

1. `uv run ruff check` and `uv run ruff format --check`
2. Typecheck the diff (part of the lint job; ONE new basedpyright
   violation on a changed line fails CI):
   `uv run diff-quality --violations=basedpyright --fail-under=100 --compare-branch=origin/main`
3. Diff coverage >= 80% (coverage-analysis job):
   `QT_QPA_PLATFORM=offscreen uv run pytest --cov=aare --cov-config=./pyproject.toml --cov-branch --cov-report=xml --no-cov-on-fail ./tests/unit`
   `uv run diff-cover coverage.xml --compare-branch=origin/main --fail-under=80`

A pre-push hook in the shared `.git/hooks` runs all of the above; bypass
only deliberately with `git push --no-verify`.

Gotchas learned the hard way:
- The `diff-quality` basedpyright plugin is an editable install from
  `~/repos/aare_suite/diff_quality_basedpyright` (gitea
  mx/diff_quality_basedpyright). On ModuleNotFoundError reinstall with
  `uv pip install -e ~/repos/aare_suite/diff_quality_basedpyright`.
- basedpyright rejects lazily created instance attributes — initialize in
  `__init__`, no `hasattr` patterns.
- Every new branch needs a test that executes it or diff coverage sinks.
- Run GUI tests with `QT_QPA_PLATFORM=offscreen`; a blocking popup (e.g. a
  real `QMenu.exec()`) otherwise freezes the suite on macOS. PySide method
  lookup ignores class-attribute monkeypatches — patch by swapping in a
  Python subclass instead.