From 3f76981e2d1837ea7d38fc058ed7cf454ed80625 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Mon, 24 Aug 2026 13:36:07 -0500
Subject: [PATCH] Serialize the cache-stamp command unambiguously, annotate the
 test helpers

---
 esphome/build_gen/arduino8266.py               |  5 ++++-
 tests/unit_tests/build_gen/test_arduino8266.py | 12 +++++++-----
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/esphome/build_gen/arduino8266.py b/esphome/build_gen/arduino8266.py
index fb884bf17b..7d842308f6 100644
--- a/esphome/build_gen/arduino8266.py
+++ b/esphome/build_gen/arduino8266.py
@@ -20,6 +20,7 @@ import logging
 import os
 from pathlib import Path
 import re
+import shlex
 import subprocess
 from typing import TYPE_CHECKING, NamedTuple
 
@@ -627,7 +628,9 @@ def generate_ld_scripts(
     # and the surgery fingerprint (a build_surgery edit invalidates old
     # build dirs)
     stamp_content = (
-        " ".join(cmd)
+        # shlex.join: a spaced path stays one quoted element, so two
+        # different cmd lists can never collide to the same stamp string
+        shlex.join(cmd)
         + f" testing={CORE.testing_mode}"
         + f" header={_stat_sig(header)}"
         + f" gcc={_stat_sig(gcc)}"
diff --git a/tests/unit_tests/build_gen/test_arduino8266.py b/tests/unit_tests/build_gen/test_arduino8266.py
index 9b5d0fc47d..21a81804ab 100644
--- a/tests/unit_tests/build_gen/test_arduino8266.py
+++ b/tests/unit_tests/build_gen/test_arduino8266.py
@@ -59,30 +59,32 @@ def _set_flags(*flags: str) -> None:
     CORE.build_flags = set(flags)
 
 
-def _resolve(*flags: str):
+def _resolve(*flags: str) -> arduino8266._BuildConfig:
     """Set the build flags and resolve the knob config in one step."""
     _set_flags(*flags)
     return _resolve_current()
 
 
-def _defines():
+def _defines() -> dict[str, str]:
     """The -D map for the current build flags."""
     return _flag_defines(set(), arduino8266._lexed_build_flags())
 
 
-def _resolve_current():
+def _resolve_current() -> arduino8266._BuildConfig:
     """Resolve whatever flags are already set (must not clear them)."""
     return _resolve_build_config(_defines())
 
 
-def _split_flags():
+def _split_flags() -> tuple[list[str], list[str], list[Path], list[str]]:
     """Classify the current build flags the way write_project does."""
     return arduino8266._project_flags(
         arduino8266._unflag_tokens(), arduino8266._lexed_build_flags()
     )
 
 
-def _ok_result(stdout=None, stderr=""):
+def _ok_result(
+    stdout: str | bytes | None = None, stderr: str | bytes = ""
+) -> MagicMock:
     """A successful preprocessor spawn (defaults to the common ld output).
 
     Streams are bytes, as the un-decoded subprocess.run delivers them.