fix: suppress purpose-specific condition intents as false positives (#306) (#309)

- Add 'condition' to IGNORED_VALUE_KEYS to suppress 'condition: person.is_not_home'
- Add is_template() guard so Jinja2 templates under condition:/trigger: keys are still scanned
- Bump CURRENT_DB_SCHEMA_VERSION to 9 to force cache reset for updated heuristic
- Update heuristics.md with revised entry and new heuristic 24 for purpose-specific conditions
- Add regression tests covering all four scenarios

Author: dummylabs

custom_components/watchman/const.py

@@ -19,7 +19,7 @@
 DEFAULT_REPORT_FILENAME = f"{DOMAIN}_report.txt"
 DB_FILENAME = f"{DOMAIN}_v2.db"
 LEGACY_DB_FILENAME = f"{DOMAIN}.db"
-CURRENT_DB_SCHEMA_VERSION = 8
+CURRENT_DB_SCHEMA_VERSION = 9
 STORAGE_KEY = f"{DOMAIN}.stats"
 STORAGE_VERSION = 1
 LOCK_FILENAME = f"{DOMAIN}.lock"

custom_components/watchman/utils/parser_const.py

@@ -58,8 +58,11 @@
 ACTION_KEYS = {'service', 'action', 'service_template', 'perform_action'}
 
 # Keys where the parser ignores the immediate string value (to avoid false positives)
-# but continues recursion if the value is a complex structure
-IGNORED_VALUE_KEYS = {'trigger', 'triggers'}
+# but continues recursion if the value is a complex structure.
+# 'condition' (singular) covers HA 2025.12+ Purpose-specific condition intents
+# (e.g. `condition: person.is_not_home`). 'conditions' (plural) is NOT listed here
+# because its value is always a list — recursion handles it without hitting the str branch.
+IGNORED_VALUE_KEYS = {'trigger', 'triggers', 'condition'}
 
 # Domains to parse in core.config_entries
 CONFIG_ENTRY_DOMAINS = {'group', 'template'}

custom_components/watchman/utils/parser_core.py

@@ -475,10 +475,11 @@ def _recursive_search(
         line_no = getattr(data, "line", None)
         key_name = parent_key
 
-        # ignore _values_ of the key from IGNORED_VALUE_KEYS
-        # this does not prevent parser to traverse in if there are nested keys
+        # Ignore direct string values of IGNORED_VALUE_KEYS (e.g. trigger, condition intents)
+        # EXCEPT when the value is a Jinja2 template — those must be scanned for entities (Heuristic 21).
         if key_name and str(key_name).lower() in IGNORED_VALUE_KEYS:
-            return
+            if not is_template(data):
+                return
 
         # Sanitize Jinja comments to avoid false positives inside comments
         # We process a copy so we don't modify the original 'data' object which might have attributes

docs/dev/heuristics.md

@@ -7,7 +7,7 @@
 5. **List vs Single:** The parser handles `entity_id` fields that contain either a single string or a list of strings (common in triggers, conditions, and targets).
 6. **String Concatenation:** Entity IDs that appear to be part of a string concatenation (detected by surrounding `+`, `~`, `%`, or `.format`) are ignored, assuming they are dynamic templates.
 7. **Wildcards:** Any entity ID followed immediately by a wildcard (`*`) is ignored (e.g., in glob patterns).
-8. **Ignored Keys:** The parser explicitly ignores content under specific keys: `url`, `example`, and `description`, to avoid false positives in documentation or metadata fields.
+8. **Ignored Keys:** The parser explicitly ignores content under specific keys: `url`, `example`, and `description`, to avoid false positives in documentation or metadata fields. Additionally, the immediate string value of `trigger:`, `triggers:`, and `condition:` keys is suppressed (see Heuristic 24), while recursion into nested child structures continues normally. This suppression is bypassed when the value is a Jinja2 template (see Heuristic 21).
 9. **ESPHOME Context:** When parsing ESPHome configuration files (detected by path), entities and services are *only* extracted if they are values of `service`, `action`, or `entity_id` keys.
 10. **Automation Context:** The parser analyzes the parent hierarchy of an item to determine if it resides within an "automation" (has `trigger`+`action`) or "script" (has `sequence`).
 11. **Embedded Services:** Service calls embedded within string values are detected using a regex pattern (e.g., matching `service: domain.service` inside a template).
@@ -23,3 +23,4 @@
 21. **Inline Template Detection:** The parser detects template markers (`{{`, `{%`, `{#`, `[[[`) anywhere within a string value, allowing it to correctly identify entities embedded in dynamic strings (e.g., `action: domain.service_{{ id }}`) and avoid misidentifying dynamic service calls as missing items.
 22. **Block Scalar Line Alignment:** When identifying items within YAML block scalars (multi-line strings denoted by `|` or `>`), the parser applies a line offset correction to ensure reported line numbers correspond to the actual content rather than the block definition header.
 23. **Template Prefix Detection:** To prevent extracting partial or incorrect entity IDs from Jinja2 templates or custom frontend components (e.g., `decluttering-card`), the parser ignores matches that are immediately followed by an opening curly brace `{` or an opening square bracket `[`.
+24. **Purpose-Specific Condition Intents:** String values appearing directly under a `condition:` key (e.g. `condition: person.is_not_home`) are treated as HA 2025.12+ Purpose-specific condition intents rather than entity references and are suppressed to prevent false positives. This suppression is bypassed when the value contains a Jinja2 template marker (see Heuristic 21), ensuring that `condition: "{{ is_state('light.x', 'on') }}"` still yields `light.x` as a candidate. Recursion into nested child structures (e.g. `target.entity_id` within the same condition block) is unaffected.

tests/__snapshots__/test_db_integrity.ambr

@@ -1,7 +1,7 @@
 # serializer version: 1
 # name: test_db_schema_integrity
   tuple(
-    8,
+    9,
     '''
       Table: found_items
       CREATE TABLE found_items (

tests/data/yaml_config/purpose_specific_conditions.yaml

@@ -0,0 +1,32 @@
+# Fixture: purpose-specific condition intents (HA 2025.12+)
+# Covers four scenarios tested in test_parser_purpose_specific_conditions.py
+
+automation:
+  - id: "test_purpose_specific_automation"
+    alias: "Purpose-Specific Conditions Test"
+    trigger:
+      - platform: state
+        entity_id: binary_sensor.motion_sensor
+    condition:
+      # Scenario 1: purpose-specific condition intent — must NOT be extracted as entity
+      - condition: person.is_not_home
+        target:
+          # Scenario 2: nested entity_id inside the same block — MUST be extracted
+          entity_id: person.xxxxxxxxxx
+        options:
+          behavior: any
+      # Scenario 3: Jinja2 template under condition: — light.kitchen MUST be extracted
+      - condition: "{{ is_state('light.kitchen', 'on') }}"
+    action:
+      - service: light.turn_on
+        target:
+          entity_id: light.living_room
+
+  # Scenario 4: Jinja2 template under trigger: — sensor.outdoor_temp MUST be extracted
+  - id: "test_trigger_template_automation"
+    alias: "Trigger Template Test"
+    trigger: "{{ states('sensor.outdoor_temp') | float > 30 }}"
+    action:
+      - service: fan.turn_on
+        target:
+          entity_id: fan.bedroom

tests/test_parser_purpose_specific_conditions.py

@@ -0,0 +1,80 @@
+"""Regression tests for HA 2025.12+ Purpose-Specific Condition Intents (#306).
+
+String values directly under a `condition:` key that look like entity IDs
+(e.g. `condition: person.is_not_home`) are Purpose-specific condition intents,
+NOT entity references, and must not be reported as false positives.
+"""
+import asyncio
+from pathlib import Path
+
+import pytest
+
+from custom_components.watchman.utils.parser_core import WatchmanParser
+
+
+@pytest.fixture
+def parser_client(tmp_path):
+    """Create a WatchmanParser instance with a temporary database."""
+    db_path = tmp_path / "watchman.db"
+    return WatchmanParser(str(db_path))
+
+
+def _parse_and_get_entities(parser_client, yaml_dir):
+    """Helper: parse a directory and return list of extracted entity IDs."""
+    asyncio.run(parser_client.async_parse(yaml_dir, []))
+    items = parser_client.get_found_items(item_type="all")
+    return [item[0] for item in items if item[3] == "entity"]
+
+
+def test_purpose_specific_condition_not_extracted(parser_client, new_test_data_dir):
+    """Test 1: condition: person.is_not_home must NOT appear in extracted entities.
+
+    'person.is_not_home' is a Purpose-specific condition intent (HA 2025.12+),
+    not an entity reference.  IGNORED_VALUE_KEYS must suppress it.
+    """
+    yaml_dir = str(Path(new_test_data_dir) / "yaml_config")
+    entities = _parse_and_get_entities(parser_client, yaml_dir)
+    assert "person.is_not_home" not in entities, (
+        "person.is_not_home is a condition intent and must not be reported as an entity"
+    )
+
+
+def test_nested_entity_id_still_extracted(parser_client, new_test_data_dir):
+    """Test 2: entity_id nested inside a condition block must still be extracted.
+
+    IGNORED_VALUE_KEYS suppresses only the immediate string value of 'condition:'.
+    Recursion into child structures must continue so that
+    target.entity_id: person.xxxxxxxxxx is still found.
+    """
+    yaml_dir = str(Path(new_test_data_dir) / "yaml_config")
+    entities = _parse_and_get_entities(parser_client, yaml_dir)
+    assert "person.xxxxxxxxxx" in entities, (
+        "person.xxxxxxxxxx is a real entity under target.entity_id and must be extracted"
+    )
+
+
+def test_jinja2_template_in_condition_extracted(parser_client, new_test_data_dir):
+    """Test 3: Jinja2 template under condition: must still yield entities (Heuristic 21).
+
+    condition: "{{ is_state('light.kitchen', 'on') }}"
+    light.kitchen must be extracted — is_template() guard must bypass suppression.
+    """
+    yaml_dir = str(Path(new_test_data_dir) / "yaml_config")
+    entities = _parse_and_get_entities(parser_client, yaml_dir)
+    assert "light.kitchen" in entities, (
+        "light.kitchen inside a Jinja2 template under condition: must be extracted"
+    )
+
+
+def test_jinja2_template_in_trigger_extracted(parser_client, new_test_data_dir):
+    """Test 4: Jinja2 template under trigger: must still yield entities.
+
+    trigger: "{{ states('sensor.outdoor_temp') | float > 30 }}"
+    sensor.outdoor_temp must be extracted — verifies that the is_template()
+    exception that fixes condition: also works correctly for trigger:.
+    """
+    yaml_dir = str(Path(new_test_data_dir) / "yaml_config")
+    entities = _parse_and_get_entities(parser_client, yaml_dir)
+    assert "sensor.outdoor_temp" in entities, (
+        "sensor.outdoor_temp inside a Jinja2 template under trigger: must be extracted"
+    )