fix(precommit): derive API check catalog from engine SSOT — adds 5 missing checks (#9873)

[mrveiss]

Closes #9873.

Thinking Path

Surfaced during the dedup sweep: api/analytics_precommit.py had forked from the analyzer engine code_intelligence/precommit_analyzer.py — not just a stale catalog (missing 5 checks) but a conflicting one (QUA002 = "Magic Number" in the API vs "Bare Except" in the engine), a divergent SEC004, a fast-mode skip list tuned to the old catalog, and a duplicate regex runner that couldn't execute the engine's multiline checks. A first attempt that only synced the catalog was reviewed and found to ship silent regressions. Per maintainer decision, the fix is full delegation: make the API a thin layer over the engine (single source of truth).

What Changed

• Catalog BUILTIN_CHECKS is derived from the engine's BUILTIN_CHECKS (engine dataclass → API Pydantic schema via _engine_check_to_schema).
• Execution is delegated to PrecommitAnalyzer.analyze_content(); the duplicate run_check/matches_file_pattern/_filter_enabled_checks and the stale _EXPENSIVE_CHECKS are removed. Engine CheckResult → API schema CheckResult via _engine_result_to_schema.
• _active_engine_checks() applies the API's enable/disable config (per-check .enabled toggle + HookConfig allow/deny lists) and, in fast mode, the engine's own expensive_checks — so catalog, skip list and runner can never disagree again.

Behavior changes (intended — engine is now SSOT):

• API exposes all 19 engine checks (adds SEC005, SEC006, DOC002, QUA004, STY003).
• QUA002 is "Bare Except" (the API's old "Magic Number" check is dropped — it does not exist in the engine).
• SEC004 now flags loopback/0.0.0.0/localhost (the engine's pattern has no exclusion).
• The multiline checks (DOC001/DOC002/STY003) now actually fire via the API (the old per-line runner could not match them).

Verification

• Catalog: 19 checks; the 5 previously-missing present.
• Bare-except sample fires QUA002; class-without-docstring fires the multiline DOC002 (previously impossible via the API).
• _engine_result_to_schema maps every field (file_path→file, drops column); result schema validates.
• fast_mode excludes the engine's expensive set {DOC001,DOC002,QUA003,STY003}; disabling a check via the toggle removes it from the active set.
• flake8 clean; thread_safety_test.py (precommit/analytics) 5 passed. (Engine unit test can't run green in a deps-light env — missing deps stub to MagicMock — so verification is by direct functional assertion against the engine + API helpers.)

Model Used

Claude Opus 4.8 (1M context)

🤖 Generated with Claude Code

[github-actions]

✅ SSOT Configuration Compliance: Passing

🎉 No hardcoded values detected that have SSOT config equivalents!

[mrveiss]

CodeReviewer Assessment

Code review: ✅ Ready to merge

• Clean refactoring: derives API check catalog from engine SSOT (code_intelligence/precommit_analyzer)
• Removes 147 lines of duplicated check definitions
• Adds 5 missing checks (SEC005, SEC006, DOC002, QUA004, STY003) that existed in engine but not API
• Converter function _engine_check_to_schema() is simple and correct
• Proper enum value mapping (engine CheckCategory/CheckSeverity → API enums)
• No behavior change for existing 14 shared checks (all fields match exactly)

CI status: ⏳ Pending

• submit-pypi: IN_PROGRESS (running ~3 minutes)

Will auto-merge when CI goes green.

---

Automated review by CodeReviewer agent

[mrveiss]

⚠️ Holding this PR — review found the drift is deeper than a stale dict

An objective review surfaced that api/analytics_precommit.py and the engine code_intelligence/precommit_analyzer.py haven't just drifted in count — they've forked in meaning, so the "derive catalog from engine" approach in this PR introduces silent regressions:

1. QUA002 is a conflicting definition. API = "Magic Number" (INFO); engine = "Bare Except" (WARN, except\s*:). Deriving from the engine silently replaces the API's Magic Number check and the API loses Magic Number entirely.
2. SEC004 — the API's pattern excluded loopback/0.0.0.0/localhost; the engine's doesn't → the API would start flagging localhost IPs.
3. _EXPENSIVE_CHECKS ({"QUA002","DOC001"}) was tuned to the old catalog; the engine's own expensive set is {"DOC001","DOC002","QUA003","STY003"}. Fast mode (default on GET /check) now skips the wrong checks.
4. The API has its own duplicate runner (re.MULTILINE, line-by-line) that cannot execute the engine's multiline=True checks (DOC002, STY003) — they'd be advertised in the catalog but never fire.

Root cause: analytics_precommit.py re-implements the engine (catalog + runner + expensive-set). Syncing only the catalog is incomplete. The engine's analyze_content() runs correctly and could back the API directly.

Awaiting a direction decision before proceeding (see issue #9873).