Terse fence docstring; warn on and test out-of-folder file= refs

Author: bdraco

script/sync_esphome_devices.py

@@ -440,18 +440,19 @@ def _split_frontmatter(text: str) -> tuple[dict[str, Any] | None, str]:
 
 def _resolve_fenced_yaml(info: str, inline: str, device_dir: Path) -> str | None:
     """
-    YAML text for a ``yaml`` fence, following a ``file=`` info attribute.
+    YAML for a ``yaml`` fence; a ``file=`` ref reads the sibling, traversal-guarded.
 
-    Pages may keep their config in a sibling file (``yaml file=config.yaml``)
-    that the rendered site inlines; read it so those devices aren't dropped.
-    Traversal-guarded like image refs. A ``url=`` ref points off-repo and
-    falls through to the inline body (empty), so url-backed pages still skip.
+    ``url=`` and absent refs return the inline body; a guarded or missing
+    ``file=`` returns ``None``.
     """
     match = _FENCE_FILE_RE.search(info)
     if match is None:
         return inline
     ref = match.group(1).removeprefix("./")
     if "/" in ref or "\\" in ref or ".." in ref:
+        # Same single-folder scope as image refs; warn so the resulting
+        # drop is diagnosable instead of a silent "no config" skip.
+        _LOGGER.warning("ignoring out-of-folder file= config ref %r (%s)", ref, device_dir.name)
         return None
     path = device_dir / ref
     try:

tests/test_sync_esphome_devices_config_fence.py

@@ -59,3 +59,19 @@ def test_rejects_path_traversal(tmp_path: Path) -> None:
     (tmp_path.parent / "secret.yaml").write_text("esphome:\n  name: leak\n")
     body = "```yaml file=../secret.yaml\n```\n"
     assert _first_config_yaml(body, tmp_path) is None
+
+
+def test_rejects_subdirectory_reference(tmp_path: Path) -> None:
+    sub = tmp_path / "configs"
+    sub.mkdir()
+    (sub / "device.yaml").write_text("esphome:\n  name: x\nbk72xx:\n  board: cb2s\n")
+    body = "```yaml file=configs/device.yaml\n```\n"
+    assert _first_config_yaml(body, tmp_path) is None
+
+
+def test_strips_dot_slash_prefix(tmp_path: Path) -> None:
+    (tmp_path / "config.yaml").write_text("esphome:\n  name: x\nbk72xx:\n  board: cb2s\n")
+    body = "```yaml file=./config.yaml\n```\n"
+    parsed = _first_config_yaml(body, tmp_path)
+    assert parsed is not None
+    assert parsed[0]["bk72xx"]["board"] == "cb2s"