AareDAQ/CLAUDE.md

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.