Process improvement plan: fixes, robustness, tests/CI, behavior, perf, docs (v1.18.1 → v1.22.1)

[karolperkowski]

Implements all 29 findings from the v1.18.0 code review & improvement plan, as six milestone commits (each with its own version bump, so the release workflow publishes v1.22.1 on merge).

Commits / milestones

v1.18.1 — pure fixes & hygiene (#1, #5, #16–18, #21)

• Service docs said Port Number; the code routes by Order. services.yaml + strings.json/en.json now describe destination/source as Order numbers with corrected examples — following the old docs routed the wrong source on any profile where Order ≠ Port (438 sources on the tested profile).
• Diagnostics downloads redact the router host (safe to attach to public issues).
• Dead code in helpers.device_info(), stale comments (ParseResult keying, button.py, CLAUDE.md keepalive), unused imports/variables, stale hacs.json filename key.

v1.19.0 — robustness (#2, #3, #6, #11, #13, #14)

• Config entries get a {host}:{port} unique_id — adding the same router twice now aborts with already_configured.
• Hidden CSV rows are kept in the name/port maps (MAGNUM still uses their Orders in .UV/.SV) but excluded from source dropdowns; flow wording aligned with actual behavior.
• .E storm guard: the reader task runs concurrently with the connect-time sweep; mnemonic sweeps abort after 5 consecutive .E, and expected .E replies are counted in new interrogate_rejected/mnemonic_rejected stats instead of flooding recent_errors.
• Destination selects cache their options list with a label → Order reverse map; duplicate Global Names get an (Order N) suffix so every label resolves unambiguously (also removes the per-state-write rebuild and per-take O(n) scan).

v1.20.0 — tests, CI, validation (#19, #24–26, #29)

• 70 pytest cases via pytest-homeassistant-custom-component: csv_parser (all 5 formats, hidden rows, Order≠Port, malformed rows), client dispatch (.UV/.A/.BA/.RAD/.RAT/.E/.X), optimistic routing, sweep abort, an end-to-end fake-router test for CR-only framing, permission matrix, blocked-route event payloads, config/options flows, select labels.
• ci.yml (ruff + mypy + pytest + strings.json ↔ en.json equality assert) and validate.yml (HACS + hassfest).
• Flow annotations migrated to ConfigFlowResult; DeviceInfo imported under TYPE_CHECKING.

v1.21.0 — behavior (#4, #7, #8, #12)

• Optimistic route state rolls back when the router answers a take with .E within 5 s (a .UV echo disarms the rollback).
• Entity listeners unregister via async_on_remove — no more leaked callbacks on partial platform reloads.
• Reconfigure flow: change host/port/name without deleting the entry; profile data, CSV names, and options are preserved.
• Exponential reconnect backoff (configured delay → ×2 per failed cycle → 120 s cap, reset on success).

v1.22.0 — performance & refactors (#10, #15, #20, #22, #23)

• Connect-time sweeps batched (8 commands per drain, 50 ms between batches) — a 512-destination matrix syncs in ~8 s instead of ~74 s; estimated_sync_seconds() matches.
• Over-provision detection driven by sync_callback instead of sleep(10) per connect; grace/detection tasks tracked and cancelled on disconnect/unload.
• Detect Destinations awaits the interrogation drain (with stall detection) instead of sleeping 2 s.
• stop() awaits the cancelled run loop; .P re-query tasks tracked.
• One helpers.detection_status() replaces three copies of the configured/detected/suggested logic.
• Public QuartzClient.connected property replaces all _connected peeks.

v1.22.1 — docs (#27, #28)

• README caught up (~5 releases): locks, sensors, detect/cleanup buttons, read-only destinations + allowed users, an Events section documenting the evertz_quartz_route_blocked contract with an example automation, startup sync notification, connection behavior, lock protocol commands.
• CLAUDE.md drift fixed (file map, entity table, new architecture sections, testing).

Verification

• 70 tests pass (3 consecutive runs), ruff and mypy clean, strings.json/en.json byte-identical.
• Client exercised end-to-end against a fake TCP router: concurrent sync, .E attribution, sweep abort, optimistic routing + rollback all observed working.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NTy9wAPHGwy2FM5yyjxqPR

---

Generated by Claude Code