quality_scale.yaml

# Where this integration stands against Home Assistant's integration quality scale.
#
# The graded tiers only apply to integrations inside Home Assistant core. A custom
# integration is scored "Custom", which is not a tier. This file exists because the
# scale is a useful target and because a core submission needs it filled in.
#
# Every "done" below is something checked in the test suite or measured, not a claim.

rules:
  # Bronze
  action-setup: done
  appropriate-polling:
    status: done
    comment: >-
      Default 300 s per context, floor of 30 s, and a 5 s debounce on target-driven
      re-evaluation. Every evaluation is a paid API call, so a flapping entity must
      not be able to spend money in a loop.
  brands:
    status: done
    comment: >-
      icon, logo and their @2x and dark_ variants ship in custom_components/jev/brand.
      Since Home Assistant 2026.3 a custom integration serves its own brand images and
      home-assistant/brands no longer accepts them, so this is the whole rule now.
  common-modules: done
  config-flow-test-coverage:
    status: done
    comment: 100% of config_flow.py, measured by pytest-cov in CI.
  config-flow: done
  dependency-transparency:
    status: done
    comment: >-
      The integration uses Home Assistant's shared aiohttp session and has no
      external API-client dependency. Transport and response validation are built
      into the custom component.
  docs-actions: done
  docs-conditions:
    status: exempt
    comment: The integration provides no conditions.
  docs-high-level-description: done
  docs-installation-instructions: done
  docs-removal-instructions: done
  docs-triggers:
    status: exempt
    comment: The integration provides no triggers.
  entity-event-setup: done
  entity-unique-id: done
  has-entity-name: done
  runtime-data: done
  test-before-configure:
    status: done
    comment: The config flow asks one short question to prove the key works.
  test-before-setup:
    status: done
    comment: >-
      Setup asks one short question, about 40 input tokens, and raises
      ConfigEntryNotReady or ConfigEntryAuthFailed if it fails. A spent budget is
      handled separately and does not block setup, because the entities that explain
      a spent budget only exist once setup finishes.
  unique-config-entry:
    status: done
    comment: The unique id is a hash of the API key, never the key itself.

  # Silver
  action-exceptions:
    status: done
    comment: >-
      ServiceValidationError for bad input, HomeAssistantError for runtime failure.
      Verified over the websocket API, which is the path the UI and automations use.
  config-entry-unloading: done
  docs-configuration-parameters: done
  docs-installation-parameters: done
  entity-unavailable:
    status: done
    comment: An answer is unavailable until one for that exact question has arrived.
  integration-owner: done
  log-when-unavailable:
    status: done
    comment: >-
      One error when the outage starts, one info when it ends. A 30 s context would
      otherwise write 2,880 identical lines a day.
  parallel-updates: done
  reauthentication-flow: done
  test-coverage:
    status: done
    comment: 96% measured across 153 tests, enforced in CI.

  # Gold
  devices: done
  diagnostics:
    status: done
    comment: The API key is redacted, and a test asserts it never appears.
  discovery:
    status: exempt
    comment: A cloud service reached with an API key. There is nothing on the network to find.
  discovery-update-info:
    status: exempt
    comment: No discovery, so no network information to refresh.
  docs-data-update: done
  docs-examples:
    status: done
    comment: >-
      Fifteen worked examples in examples/, each checked by the test suite. One is
      the conversation agent, which is configured rather than scripted, and one is
      the automation shown in the README screenshots, saved exactly as it ran.
  docs-known-limitations: done
  docs-supported-devices:
    status: exempt
    comment: A service, not a device.
  docs-supported-functions: done
  docs-troubleshooting: done
  docs-use-cases: done
  dynamic-devices:
    status: exempt
    comment: One service device per config entry, which cannot appear later.
  entity-category: done
  entity-device-class: done
  entity-disabled-by-default:
    status: done
    comment: The per-context latency sensor is diagnostic and off by default.
  entity-translations:
    status: done
    comment: >-
      Every entity the integration names itself uses a translation key, including the
      per-context latency sensor, whose context name travels as a placeholder. A
      question sensor is named by the user's own question text, which is theirs to
      write and cannot be translated by anyone else. The conversation agent takes the
      device name, which is what every conversation agent in core does, and the six
      sentences it speaks itself go through the common translation category, so a
      Dutch pipeline answers in Dutch.
  exception-translations:
    status: done
    comment: >-
      Fourteen keys, including the library's own limit errors, which are re-raised
      with the real numbers as placeholders rather than passed through in English.
      A test asserts every key raised in code exists in every language file, and a
      check asserts no raise anywhere carries a bare string.
  icon-translations:
    status: done
    comment: >-
      icons.json covers every translated entity and all four actions, and a test
      asserts that. The conversation entity takes the conversation domain's own icon,
      as core's agents do.
  reconfiguration-flow:
    status: done
    comment: The API key can be replaced without losing entities or their history.
  repair-issues:
    status: done
    comment: The daily budget raises a repair issue naming the budget and what was used.
  stale-devices:
    status: exempt
    comment: One device per entry, removed with the entry.

  # Platinum
  async-dependency:
    status: done
    comment: The built-in SystemOne client uses Home Assistant's shared aiohttp session.
  inject-websession:
    status: done
    comment: >-
      The client takes Home Assistant's shared aiohttp session. This is the rule the
      vendor's own SDK cannot satisfy: it requires an httpx2.AsyncClient, and Home
      Assistant ships aiohttp and httpx, not httpx2.
  strict-typing:
    status: done
    comment: mypy --strict passes on all 12 modules, enforced in CI.