feat(search): use Home Assistant's reference graph for entity dependency discovery (#2277)

* test: scope the supply-chain Dockerfile scan to repository content

- rglob picked up Dockerfiles inside gitignored worktree checkouts
- Renovate only sees tracked content, so the assertion should too
- unblocked committing for anyone following the worktree workflow

* feat(search): add Home Assistant reference-graph lookups

- query-shape gate, search/related frame, response parsing and merge
- distinguishes an unreadable answer from 'no references found'
- suppresses repeat frames only after a second unknown_command rejection

* refactor(search): drop the phantom bulk config tier and use the reference graph

- the keyless bulk GET matched no HA route and 404'd on every version
- per-id fetch now orders by what the graph already confirmed
- renamed scenes resolve through the registry storage key

* test(search): update suites for per-id fetching and renamed-scene resolution

- drop mocks and assertions that simulated the removed bulk endpoint
- delete two tests whose hand-built input the real path cannot produce
- rename the bulk-fetch e2e file to what it actually covers

* docs: record unit-test invocation and e2e component routing

- AGENTS.md documented only the E2E command; add the parallel unit one
- note that ha_search routes to the component on every e2e lane

* fix(search): address review findings on the reference-graph merge

- disclose unmodelled consumers as a count, never ids: enforce mode refuses
  any response carrying a hidden entity_id, which failed the whole search
- treat a populated but unreadable bucket as not consulted
- bound the optional graph lookup with its own 5s timeout
- emit match_in_references on dashboard records too
- fix the documented unit-test command to run from tests/

* fix(search): let scene incompleteness reach the scope-sentence gate

- a scene-only search whose configs failed lost the scope sentence entirely
- tighten a scene assertion that could pass on unrelated wording
- drop a docstring reference to state that was consolidated away

* fix(search): correct the budget-exhausted guidance

- raising config_time_budget does complete the scan when Home Assistant's
  serialized reads finish inside the higher limit
- state the latency tradeoff and the throughput ceiling instead of claiming
  the limit is irrelevant, which steered users to the component needlessly

* refactor(internal): isolate the reference-graph clock behind a seam

- _graph.time is the stdlib module object, so patching monotonic through it
  faked the clock for every module in the process
- mirrors the existing component_api._monotonic pattern

* test: address review findings on e2e conventions and the Dockerfile scan

- use call_tool_success inside MCPAssertions, and safe_call_tool for cleanup
  so a cleanup failure cannot mask the real assertion
- enumerate Dockerfiles via git ls-files: the .claude name filter also
  excluded the tracked .claude/skills tree
- refresh a fixture comment that still described the removed bulk tier

* fix(test): let the Dockerfile scan read the index inside CI's container

- the unit-test job runs in a container with the workspace bind-mounted, so
  the checkout is owned by another uid and git refused with exit 128
- scope safe.directory to the one invocation; no git config is written
- carry git's stderr into the assertion so the next failure explains itself

---------

Co-authored-by: Sergey <sergey@example.com>

Author: sergeykad

AGENTS.md

@@ -417,6 +417,16 @@ uv run hamcp-test-env --no-interactive   # For automation
 
 Test token centralized in `tests/test_constants.py`.
 
+**Unit tests** (`tests/src/unit/`, no Docker) — run them in parallel, as CI does
+(`pr.yml`); serial takes 25+ minutes for ~11k tests:
+
+```bash
+cd tests && uv run pytest src/unit/ -n auto --tb=short
+```
+
+`tests/pytest.ini` sets `--maxfail=3`, so a run reporting "3 failed" has stopped
+early rather than finished — pass `--maxfail=0` when you need the full picture.
+
 ### Code Quality
 
 C901 (mccabe complexity ≤10) is enforced repo-wide with zero per-file exemptions (issue #925 cleared the grandfathered list) — never reintroduce a `["C901"]` per-file-ignore; extract helpers instead.
@@ -896,7 +906,10 @@ empty, so the English a `tools` entry translates is read from the tool
 definition in `src/ha_mcp/tools/` — the `title=` kwarg and the summary
 paragraph of the docstring, or the `FEATURE_GATED_TOOLS` stub where a gated
 tool shows one instead. Editing that summary moves the English out from under
-six catalogs; the pipeline retranslates them. One deliberate exception: a
+six catalogs; the pipeline retranslates them. A parameter's
+`Field(description=...)` is NOT in the baseline — only the title and the
+docstring summary are — so editing one owes no translation work. One
+deliberate exception: a
 change to a feature-gated tool's PARSED docstring (its stub unchanged) is
 stub-review work, not translation work — the pipeline holds that baseline key
 stale, and the locale-sync run stays red until a human confirms the stub

src/ha_mcp/tools/smart_search/__init__.py

@@ -20,9 +20,8 @@
 # keep resolving.
 from ._config import (
     AUTOMATION_CONFIG_TIME_BUDGET,
-    BULK_REST_TIMEOUT,
-    BULK_WEBSOCKET_TIMEOUT,
     DEFAULT_CONCURRENCY_LIMIT,
+    ENTITY_REGISTRY_TIMEOUT,
     INDIVIDUAL_CONFIG_TIMEOUT,
     INDIVIDUAL_FETCH_BATCH_SIZE,
     SCENE_CONFIG_TIME_BUDGET,

src/ha_mcp/tools/smart_search/_config.py

@@ -10,13 +10,13 @@
 # Default concurrency limit for parallel operations
 DEFAULT_CONCURRENCY_LIMIT = 20
 
-# Bulk fetch timeouts (in seconds)
-BULK_REST_TIMEOUT = 5.0  # Timeout for bulk REST endpoint calls
-BULK_WEBSOCKET_TIMEOUT = 3.0  # Timeout for bulk WebSocket calls
+# Timeout for the entity-registry WebSocket list used by the scene walk.
+ENTITY_REGISTRY_TIMEOUT = 3.0
 
 
-# Attempt-C (per-id fallback; the letter predates the removal of the phantom
-# WS bulk tier in #1889 and is kept as a proper name) tuning knobs. Sourced from the resolved
+# Per-id config-fetch tuning knobs. The code calls this pass "Attempt C":
+# a proper name left from when two earlier bulk tiers were tried first,
+# both since removed as phantoms (#1889, #2258). It is now the only pass. Sourced from the resolved
 # Settings (issues #1538 / #1784) so the env var, the web Settings UI
 # override file, and the field defaults all flow through one precedence path
 # — and so add-on users (who cannot set raw env vars) can tune them from the
@@ -25,7 +25,7 @@
 # carry a restart-required notice in the UI).
 _settings = get_global_settings()
 
-# Time budgets for fallback individual fetching (in seconds).
+# Wall-clock budgets for the per-id config fetch (in seconds).
 AUTOMATION_CONFIG_TIME_BUDGET = _settings.automation_config_time_budget
 SCRIPT_CONFIG_TIME_BUDGET = _settings.script_config_time_budget
 SCENE_CONFIG_TIME_BUDGET = _settings.scene_config_time_budget