docs(overview): enumerate dismissed_repair_count in fields= description + static drift test

[kingpanther13]

What does this PR do?

Two changes:

1. Docstring fix. ha_get_overview emits dismissed_repair_count on its response when the caller leaves include_dismissed_repairs=False (the default) AND some repairs are being hidden — it tells the agent how many were filtered out so they can flip the flag if needed. The key has been emitted since #1309, but when #1225 introduced the comma-separated Available keys: ... enumeration in the fields= parameter description it was missed. Functionally fields=["dismissed_repair_count"] already worked (project_fields passes it through); this is a discoverability fix.

2. Static drift test. New tests/src/unit/test_fields_projection_docstring_completeness.py AST-walks the response builders for each tool with a fields= parameter and asserts the Available keys: enumeration matches the keys the code emits, in both directions:

• emitted but not enumerated — what slipped past for dismissed_repair_count on this PR's bug
• enumerated but not assigned anywhere — sibling drift class; see interaction note below

Covers 6 tools: ha_get_overview, ha_search_entities, ha_get_history, ha_config_list_areas, ha_list_services (AST harvest from named response vars + dict-literal returns + marker-shape detection), plus ha_get_state (manifest pin — its fields= projects HA's native entity-record schema, not keys we synthesize, so the test asserts the enumeration matches a pinned {entity_id, state, attributes, last_changed, last_reported, last_updated, context} set).

Three meta-tests pin the scanner's own invariants:

• test_harvester_finds_dismissed_repair_count_in_ha_get_overview — guards against a refactor moving the assignment somewhere the harvester doesn't scan, where both sides of the diff would shrink in lockstep and the regression would go silent.
• test_tool_specs_covers_every_fields_using_tool — AST-discovers every tool with a fields= parameter and asserts TOOL_SPECS enumerates them all, so deleting a spec entry can't silently shrink coverage.
• test_exclude_internal_keys_actually_appear_in_raw_harvest — surfaces dead exclude_internal entries that no longer mask anything.

Interaction with #1381 (now merged)

#1381 introduced settings_url to ha_get_overview's response, set after project_fields(...) so it bypasses projection — always emitted when the settings-UI sidecar is running. This PR's rebase:

• Adds settings_url to the Available keys: enumeration (discoverability) and keeps a trailing note that it's not subject to projection (semantic clarity).
• Extends ha_get_overview's var_harvest spec to include the projected local (where settings_url is assigned), so the dual-direction static check matches.

#1381's commit a473e164 ("always emit notifications + repairs as lists") fixes the runtime-conditional-emission variant of the same drift class; this PR's static test and #1381's TestHaGetOverviewAlwaysEmittedKeys are complementary — static catches "never assigned anywhere", runtime catches "assigned only under if x:".

Type of change

• 🐛 Bug fix
• 🧪 Tests only

Testing

• I have tested these changes with a LLM agent
• All automated tests pass (uv run pytest)
• Code follows style guidelines (uv run ruff check)

Local verification:

• Before the docstring fix, the new test correctly fails with response keys ['dismissed_repair_count'] are emitted by the implementation but NOT enumerated in the 'fields=' parameter description.
• After the fix, all 9 tests pass (6 parametrized + 3 meta).
• Sanity-checked the dual-direction by injecting a phantom doc-only key — correctly flagged as documented_only.
• ruff check clean, ruff format clean, mypy clean on the new file.

Checklist

• I have updated documentation if needed

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a documentation gap where a valid response key was missing from the fields= parameter description. To prevent similar discrepancies in the future, a new static analysis test suite was implemented to automatically validate the completeness of key enumerations across multiple tools by inspecting the source code's response-building logic.

Highlights

• Documentation Update: Added the missing dismissed_repair_count key to the ha_get_overview docstring enumeration, ensuring it is discoverable for AI agents using the fields= parameter.
• Static Analysis Test: Introduced a new unit test, test_fields_projection_docstring_completeness.py, which uses AST walking to verify that all keys emitted by tool response builders are correctly enumerated in their respective docstrings, preventing future drift.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds the missing "dismissed_repair_count" key to the "ha_get_overview" tool's documentation and introduces a new static regression test, "test_fields_projection_docstring_completeness.py". This test uses AST analysis to ensure that all top-level keys emitted by tools are correctly enumerated in their docstrings. The review feedback suggests optimizing the test execution time by caching AST parsing results with "lru_cache" and enhancing the harvester logic to detect keys assigned via keyword arguments in "update()" calls.

[Patch76]

Static drift test is well-shaped. The three meta-tests pin the scanner's own invariants — test_harvester_finds_dismissed_repair_count_in_ha_get_overview for the bug-catch guarantee, test_tool_specs_covers_every_fields_using_tool against silent shrinkage on spec removal, and test_exclude_internal_keys_actually_appear_in_raw_harvest for dead-mask surfacing. That class of test is what keeps the static check itself from rotting.

The docstring rewrite of the settings_url sentence ("emitted regardless of fields= projection") is more accurate than the original "not subject to this projection" framing.

Decline rationales on the Gemini threads hold up.

[github-actions]

🧪 Your changes are now in the dev channel!

Your PR has been merged to master and is available for testing in the dev channel.

Test your changes before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

Found an issue? Please open a new bug report and mention this PR for context.