# Quality-Scale Audit: `fritz` (FRITZ!Box Tools)

> Audit snapshot per rubric; re-verify against `dev` before execution.
> Scope is the `fritz` domain (router/mesh: device tracker, sensors, switches, update,
> button, binary sensor, image) — **not** `fritzbox` (smart home) or `fritzbox_callmonitor`.

## 1. Integration profile

| Attribute | Value |
|---|---|
| Domain | `fritz` |
| IoT class | `local_polling` |
| Primary libraries | `fritzconnection` (TR-064/AHA, **synchronous**, executor-wrapped), `xmltodict` |
| Declared `quality_scale` | none declared |
| Install base | Top-30 in Europe-heavy deployments; FRITZ!Box is the dominant router brand in DACH |
| Issue volume | High — device-tracker ghosts/stale devices, mesh topology errors, slow setup (TR-064 latency), call-deflection switch failures, profile switches, memory growth reports |
| CODEOWNERS | Yes — multiple active code owners, historically welcoming to structured contributions |

**Why selected:** very high issue volume relative to peers, mature codebase that already has
many Silver/Gold features (reauth, diagnostics) but lacks the scoring, coverage and
stale-device hygiene to claim them — i.e., high leverage per line changed.

## 2. Rule-by-rule audit

### Bronze

| Rule | Status | Evidence / Gap |
|---|---|---|
| `config-flow` | ✅ | UI flow with SSDP discovery; options flow for consider-home and feature toggles. |
| `test-before-configure` | ✅ | Connects + authenticates before entry creation. |
| `unique-config-entry` | ✅ | UDN-based. |
| `config-flow-test-coverage` | 🟡 | Broad, but SSDP-update and error-recovery branches need coverage verification. |
| `entity-unique-id` | ✅ | Stable IDs (MAC/UDN-derived). |
| `has-entity-name` | 🟡 | Most platforms migrated; verify device-tracker and legacy sensor descriptions; some sensors may still embed device name. |
| `runtime-data` | 🟡 | `AvmWrapper`/`FritzBoxTools` historically in `hass.data`; verify `entry.runtime_data` migration completed across all platform modules. |
| `appropriate-polling` | 🟡 | 30 s default scan; TR-064 calls are heavy. Rule satisfied if intervals are justified and host-load documented; document, and verify per-call batching in the coordinator. |
| `entity-event-setup` | ➖ | N/A. |
| `action-setup` | 🟡 | Custom services (`set_guest_wifi_password`, cleanup) — verify registration in `async_setup` and `ServiceValidationError` on bad entry IDs per current rules. |
| `common-modules` | ✅ | `coordinator.py`, `entity.py` present. |
| `dependency-transparency` | ✅ | PyPI, public source. |
| `docs-*` (Bronze set) | ✅/🟡 | Docs page extensive; verify removal instructions section exists. |
| `brands` | ✅ | Present. |

### Silver

| Rule | Status | Evidence / Gap |
|---|---|---|
| `config-entry-unloading` | ✅ | Implemented. |
| `reauthentication-flow` | ✅ | Exists and triggers on `FritzConnectionException`-auth errors; verify flow tests cover both success and wrong-password retry. |
| `action-exceptions` | 🟡 | Several wrapper calls swallow TR-064 errors into logs; service calls should raise translated `HomeAssistantError`. |
| `entity-unavailable` | 🟡 | Coordinator-driven, mostly correct; mesh-only entities can stay stale when a repeater drops out of the mesh — tie availability to per-device presence in mesh topology. |
| `log-when-unavailable` | 🟡 | Verify log-once pattern at coordinator level. |
| `parallel-updates` | ❌ | Not declared; declare `0` for coordinator platforms, `1` for action platforms (button/switch) pending measurement of TR-064 concurrency tolerance (FRITZ!OS serializes poorly under concurrent SOAP calls — likely root cause of some timeout reports). |
| `integration-owner` | ✅ | Present. |
| `test-coverage` | 🟡 | Coordinator and flow well covered; switch (deflection/profile/port-forward) branches and image platform under-covered. |
| `docs-configuration-parameters` | ✅/🟡 | Options documented; verify completeness. |

### Gold (selected)

| Rule | Status | Notes |
|---|---|---|
| `diagnostics` | ✅ | `diagnostics.py` exists; verify redaction list still covers serials/external IP and add mesh-topology summary if cheap. |
| `discovery` / `discovery-update-info` | ✅/🟡 | SSDP discovery present; verify host updates on rediscovery. |
| `stale-devices` | 🟡 | **Key gap, top issue theme.** Tracked devices that left the network linger; there is a cleanup service/button, but the rule expects automatic removal or `async_remove_config_entry_device` support. Implement `async_remove_config_entry_device` (allow deletion when device absent from current host list) — small, high user value. **Pulled into scope** (FZ-4). |
| `dynamic-devices` | ✅ | New tracked devices appear at runtime. |
| `repair-issues` | ❌ | Out of scope. |
| `strict-typing` | 🟡 | Largely typed; not in `.strict-typing`. Out of scope (Platinum) — but keep new code strict-clean. |

## 3. Gap summary and proposed work items

| ID | Work item | Rule(s) | Size | Risk |
|---|---|---|---|---|
| FZ-1 | Declare `PARALLEL_UPDATES` (incl. measuring TR-064 concurrency behavior), finish `runtime_data` migration, log-once unavailability | `parallel-updates`, `runtime-data`, `log-when-unavailable` | S–M | Low |
| FZ-2 | Translated exceptions for service/switch failures; service registration audit (`async_setup`, entry validation) | `action-exceptions`, `action-setup` | S | Low |
| FZ-3 | Mesh-aware availability for repeater-scoped entities + tests | `entity-unavailable` | M | Medium — needs fixtures for mesh topology JSON |
| FZ-4 | Implement `async_remove_config_entry_device` for stale tracked devices; document in docs PR | `stale-devices` | S | Low — high user-visible value |
| FZ-5 | Coverage: switch/button/image platforms to ≥95 %; config-flow branch coverage | `test-coverage`, `config-flow-test-coverage` | M (tests only) | Low |
| FZ-6 | Naming sweep (`has_entity_name` stragglers), diagnostics redaction review | `has-entity-name`, `diagnostics` | S | Low |
| FZ-7 | Add `quality_scale.yaml`; declare Bronze, then Silver after FZ-1…FZ-3, FZ-5 | meta | XS | Low |

**Target outcome:** unscored → **Silver**, plus the Gold `stale-devices` rule which directly
addresses the largest recurring complaint class.

## 4. Maintainer-coordination notes

- Owners actively triage; reference their existing labels/issue threads on stale trackers
  when proposing FZ-4 — there is prior discussion to align with rather than relitigate.
- TR-064 fixtures are verbose; reuse the existing fixture infrastructure in
  `tests/components/fritz/` rather than introducing a new mock style.