Skip to content

Development Environment

barneyonline edited this page Nov 9, 2026 · 10 revisions
HomePod Sensor Link — Development Environment

Development environment

Validation runs Python 3.14 in the official HA images and requires Docker. devtools/validation.json pins HA 2026.11.0 with aiohomekit 4.0.1, coverage, Ruff, Node, hassfest and mypy 2.3.1.

sh scripts/validate.sh

This runs working-content checks, repository/wiki contracts, host tooling/artifact tests, spelling and workflow syntax checks, the HA suite with exact coverage gates, strict typing, the 54-rule quality evidence audit, pinned hassfest, Ruff and Node tests for GitHub issue/PR automation. Containers run without networking and mount source read-only. Reports go outside the source tree. Public tooling-image/package downloads during image construction require network access; test execution does not. sh scripts/validate_automation.sh runs the spelling/actionlint/metadata subset independently.

Focused commands

python3 scripts/check_repository.py
python3 scripts/run_tests.py --version 2026.11.0 --output /tmp/homepod-link-tests
python3 scripts/check_coverage.py /tmp/homepod-link-tests/coverage.json
python3 scripts/check_public_content.py --history --require-git
python3 scripts/package.py --output /tmp/homepod-sensor-link-local.zip

Strict typing uses the image built by full validation:

docker run --rm --network none -v "$PWD:/project:ro" -w /project --entrypoint mypy homepod-link-quality:2026.11.0 --cache-dir /tmp/homepod-link-mypy custom_components/homepod_sensor_link

The image exposes HA source through MYPYPATH and checks every packaged module with strict options. Dynamic HAP/storage dictionaries are validated at boundaries. Narrow callable casts describe aiohomekit's incompletely annotated public methods. See dependencies.

Exact coverage policy

Every integration Python module must have zero missing statements, zero missing branches and zero excluded lines on the supported HA runtime. The checker compares integer miss counts against the complete module inventory, including new modules. Background task exceptions also fail validation.

Credential entry uses native Home Assistant config-flow forms; there is no custom credential panel or production credential JavaScript. The Python suite covers local-administrator ownership, parsing and size limits, validation errors, cancellation and credential cleanup. The Node suite tests GitHub issue/PR automation in tests/automation/issue_automation.test.cjs; it is separate from credential import.

macOS helper checks

On macOS, run the separate synthetic helper checks:

sh scripts/test_macos_homekit.sh
sh scripts/build_macos_homekit.sh /tmp/homepod-helper-build
/tmp/homepod-helper-build/homekit-export --help
/tmp/homepod-helper-build/homekit-export --describe-query

Use a new build-output directory. These commands compile the bundled helper and test synthetic records without signing it or accessing a keychain. The separate macOS CI job runs the same checks; sh scripts/validate.sh does not run that native macOS job.

Quality and release gates

The quality guide describes all 54 rule targets and the release checklist. Run the stricter quality and release checks with:

docker run --rm --network none -v "$PWD:/project:ro" -w /project --entrypoint python homepod-link-quality:2026.11.0 scripts/validate_quality_scale.py --require-complete
docker run --rm --network none -v "$PWD:/project:ro" -w /project --entrypoint python homepod-link-quality:2026.11.0 scripts/validate_quality_scale.py --require-release-ready

The public-content audit checks working files, staged content and reachable Git history. Use generated identities in tests and keep real credentials, backups and household data out of source and reports.

Documentation and automation

Documentation is maintained directly in this GitHub Wiki. Edit pages through GitHub or clone https://github.com/barneyonline/ha-homepod-sensor-link.wiki.git. Keep page content and navigation in that separate repository; the integration repository retains its README, contributing/security guidance and artwork.

Banner source images remain under docs/images/wiki/ in the integration repository. Copy the selected light/dark pair into the Wiki's images/ directory and preserve each page's theme-aware picture header. Check links and review changes before publishing. CI does not write to the Wiki.

The contribution guide contains repository validation, dependency and quality policies.

Workflows default to contents: read. validate.yml provides local, platinum and release readiness modes. Standalone workflows add spelling/actionlint, hassfest, HACS and quality-evidence checks. The HACS validator reads public repository metadata and requires network access. Dependabot proposes weekly Action updates.

Four issue/PR metadata jobs receive issues: write, with pull-requests: write for PR assignment/review. They run trusted main code; pull_request_target does not execute PR-head code. Label and guidance workflows independently handle form events because token-generated label events do not launch other workflows. Manual dispatch previews changes. Policy tests cover injection, forged markers and API failures.

release-candidate.yml builds a scanned archive, SHA-256 sidecar and provenance tied to a clean source commit. release-assets.yml calls that builder and verifies the artifact’s source identity, checksum, version, entries and licence boundaries. Both workflows run manually and produce artifacts for release preparation.

The workflows do not publish releases or install the integration. main can contain changes beyond the latest release while its manifest still has the previous version. Compare the Unreleased changelog with the published releases when documenting availability.

After validation succeeds on main, a separate Codecov job uploads the runtime’s coverage.xml. CODECOV_TOKEN is scoped to the upload action. Codecov uses 100% project/patch targets. The public badge reports Python integration coverage; the Node automation tests are a separate validation step.

Deterministic performance regressions in test_performance_storage.py and test_performance_publication.py cover seven simulated days of audits, protected journal writes/fsyncs, 64-record defensive-copy isolation, and actual HA entity reports at 1, 16 and 64 devices. They compare operation counts rather than machine-dependent timing thresholds. Pairing checkpoints and fresh report verification remain mandatory.

Clone this wiki locally