[core] Harden the shared library converter (#18685)

esphome/platformio/extra_script.py

@@ -0,0 +1,365 @@
+"""Run a PlatformIO library ``extraScript`` against a fake SCons env.
+
+The shim execs the script with a stand-in ``env``, captures ``env.Append``
+calls (everything else is a logged no-op), and folds the result into the
+library's build flags. No sandboxing: the script runs with full process
+access, so it carries the same trust as the library's own source.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+import logging
+import os
+from pathlib import Path
+import shlex
+from typing import TYPE_CHECKING, Any, NamedTuple
+
+from esphome.core import EsphomeError
+from esphome.platformio.library import ESPHOME_DATA_KEY, ESPHOME_DATA_LINK_FLAGS_KEY
+
+if TYPE_CHECKING:
+    from esphome.platformio.library import ConvertedLibrary
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def apply_extra_script(
+    component: ConvertedLibrary,
+    board_mcu: Callable[[], str],
+    pio_platform: str,
+) -> None:
+    """Run a library's ``extraScript`` and fold its captured env vars into
+    ``build.flags``; ``board_mcu`` is a callable so it resolves lazily."""
+    extra_script = component.data.get("build", {}).get("extraScript")
+    if extra_script is None or extra_script == "":
+        return
+    if not isinstance(extra_script, str):
+        # A list/dict value would raise an opaque TypeError on the join below
+        raise EsphomeError(
+            f"extraScript of library {component.name} must be a string, "
+            f"got {type(extra_script).__name__}"
+        )
+    # Resolve and confine to the library's source dir so a malicious
+    # library.json can't escape (e.g. ``"extraScript": "../../etc/passwd"``).
+    source_path = component.source_dir
+    library_root = source_path.resolve()
+    script_path = (source_path / extra_script).resolve()
+    if not script_path.is_relative_to(library_root):
+        # More hostile than a missing script; must not be quieter than it
+        raise EsphomeError(
+            f"extraScript {extra_script} of library {component.name} escapes "
+            "the library directory"
+        )
+    if not script_path.is_file():
+        # A declared-but-absent script is a broken or half-downloaded
+        # package, not an unsupported script; PlatformIO fails on it too
+        raise EsphomeError(
+            f"extraScript {extra_script} of library {component.name} not found"
+        )
+    result = run_extra_script(
+        script_path,
+        library_dir=source_path,
+        board_mcu=board_mcu(),
+        pio_platform=pio_platform,
+    )
+    if link_flags := _str_entries(result.linkflags, "LINKFLAGS"):
+        # Kept apart from build.flags: the CMake emitters route those to
+        # target_compile_options, where a link flag is silently ineffective
+        esphome_data = component.data.setdefault(ESPHOME_DATA_KEY, {})
+        esphome_data.setdefault(ESPHOME_DATA_LINK_FLAGS_KEY, []).extend(link_flags)
+    extra_flags = captured_as_build_flags(result, library_dir=source_path)
+    if not extra_flags:
+        return
+    flags = component.data.setdefault("build", {}).setdefault("flags", [])
+    if isinstance(flags, str):
+        flags = [flags]
+    elif not isinstance(flags, list):
+        # A null/dict value coerced through a list wrapper would inject a
+        # non-string into the compiler command line; fail naming the library
+        raise EsphomeError(
+            f"Library {component.name} has a malformed build.flags "
+            f"({type(flags).__name__}); expected a string or list"
+        )
+    component.data["build"]["flags"] = [*flags, *extra_flags]
+
+
+# Keys we know how to translate back into ESPHome's build-flag pipeline.
+# Other env.Append kwargs are recorded but ignored downstream.
+_CAPTURED_KEYS = frozenset(
+    {"CPPPATH", "LIBPATH", "LIBS", "CPPDEFINES", "LINKFLAGS", "CPPFLAGS"}
+)
+
+
+@dataclass
+class ExtraScriptResult:
+    """Build-var deltas captured from a PIO extra-script ``env.Append`` call."""
+
+    cpppath: list[str] = field(default_factory=list)
+    libpath: list[str] = field(default_factory=list)
+    libs: list[str] = field(default_factory=list)
+    cppdefines: list[CppDefine] = field(default_factory=list)
+    linkflags: list[str] = field(default_factory=list)
+    cppflags: list[str] = field(default_factory=list)
+
+
+class CppDefine(NamedTuple):
+    """One normalized CPPDEFINES entry; a ``value`` of None is a bare -DNAME."""
+
+    name: str
+    value: str | None = None
+
+
+def _cppdefine(entry: Any) -> CppDefine | None:
+    """Normalize one CPPDEFINES element, or warn and drop an unsupported
+    shape; formatting those blind would hand the compiler garbage like
+    ``-D{'FOO': '1'}``."""
+    if isinstance(entry, str):
+        return CppDefine(entry)
+    if (
+        isinstance(entry, (tuple, list))
+        and len(entry) == 2
+        and isinstance(entry[0], (str, int))
+        and isinstance(entry[1], (str, int, type(None)))
+    ):
+        value = entry[1]
+        return CppDefine(str(entry[0]), None if value is None else str(value))
+    _LOGGER.warning("Ignoring unsupported CPPDEFINES entry %r", entry)
+    return None
+
+
+def _cppdefines_items(value: Any) -> list[CppDefine]:
+    """Normalize SCons ``processDefines`` spellings into ``CppDefine``s: a
+    bare 2-tuple is one ``name=value`` pair, a dict maps names to values, a
+    list is element-wise."""
+    if isinstance(value, tuple) and len(value) == 2:
+        elements: list[Any] = [value]
+    elif isinstance(value, dict):
+        elements = list(value.items())
+    else:
+        elements = list(value) if isinstance(value, (list, tuple)) else [value]
+    return [d for e in elements if (d := _cppdefine(e)) is not None]
+
+
+class _FakeSConsEnv:
+    """Minimal SCons ``Environment`` stand-in: ``get`` and ``Append`` work;
+    every other method is a swallowed no-op so scripts don't abort."""
+
+    def __init__(self, *, board_mcu: str, pio_env: str, pio_platform: str) -> None:
+        self._vars: dict[str, str] = {
+            "BOARD_MCU": board_mcu,
+            "PIOPLATFORM": pio_platform,
+            "PIOENV": pio_env,
+        }
+        self.result = ExtraScriptResult()
+        self._warned_methods: set[str] = set()
+        self._warned_keys: set[str] = set()
+        self._warned_gets: set[str] = set()
+
+    # ----- SCons env API the common scripts use -----
+
+    def get(self, key: str, default: str | None = None) -> str | None:
+        if key not in self._vars and key not in self._warned_gets:
+            # A script branching on an unmodelled var silently takes the
+            # default branch; make that diagnosable from a normal build log
+            self._warned_gets.add(key)
+            _LOGGER.warning(
+                "PIO extra-script env.get(%r) is not modelled; returning the default",
+                key,
+            )
+        return self._vars.get(key, default)
+
+    def __contains__(self, key: object) -> bool:
+        # Without this, "KEY" in env falls back to the legacy sequence
+        # protocol: __getitem__(0), (1), ... never raises, so it loops
+        # forever flooding the log
+        return key in self._vars
+
+    def __iter__(self):
+        return iter(self._vars)
+
+    def __getitem__(self, key: str) -> str:
+        # Scripts also read env["BOARD_MCU"]; an unmodelled subscript
+        # degrades one branch instead of discarding the whole capture
+        if key not in self._vars and key not in self._warned_gets:
+            self._warned_gets.add(key)
+            _LOGGER.warning(
+                "PIO extra-script env[%r] is not modelled; returning ''", key
+            )
+        return self._vars.get(key, "")
+
+    def Append(self, **kwargs) -> None:  # noqa: N802 (SCons API name)
+        self._add(kwargs, prepend=False)
+
+    def Prepend(self, **kwargs) -> None:  # noqa: N802 (SCons API name)
+        self._add(kwargs, prepend=True)
+
+    def _add(self, kwargs: dict[str, Any], *, prepend: bool) -> None:
+        for key, value in kwargs.items():
+            if key not in _CAPTURED_KEYS:
+                # Warn once per key so a loop of Appends cannot spam
+                if key not in self._warned_keys:
+                    self._warned_keys.add(key)
+                    _LOGGER.warning(
+                        "PIO extra-script env.Append(%s=...) is not captured; ignoring",
+                        key,
+                    )
+                continue
+            if key == "CPPDEFINES":
+                items = _cppdefines_items(value)
+            else:
+                items = list(value) if isinstance(value, (list, tuple)) else [value]
+            bucket = getattr(self.result, key.lower())
+            if prepend:
+                # SCons order: new values ahead of what is already there
+                # (scripts prepend LIBS for static-link symbol resolution)
+                bucket[:0] = items
+            else:
+                bucket.extend(items)
+
+    # Dedup is not modelled; a repeated flag is harmless on the command line
+    AppendUnique = Append
+    PrependUnique = Prepend
+
+    # ----- Everything else is a no-op so unsupported scripts don't crash -----
+
+    def __getattr__(self, name: str):
+        if name.startswith("__") and name.endswith("__"):
+            # Protocol probes (copy, pickle, iteration) are not script calls
+            raise AttributeError(name)
+        if name not in self._warned_methods:
+            # Warn on access, not call: hasattr()/truthiness branches would
+            # otherwise silently take the wrong path; a script whose whole
+            # effect is env.Replace() stays diagnosable either way
+            self._warned_methods.add(name)
+            _LOGGER.warning("PIO extra-script env.%s is not supported; ignoring", name)
+
+        def _noop(*args, **kwargs):
+            return None
+
+        return _noop
+
+
+def run_extra_script(
+    script_path: Path,
+    *,
+    library_dir: Path,
+    board_mcu: str,
+    pio_platform: str,
+) -> ExtraScriptResult:
+    """Execute ``script_path`` with a fake SCons env, ``library_dir`` as CWD.
+
+    A crashed script warns and returns an empty result, never a partial
+    capture."""
+    env = _FakeSConsEnv(
+        board_mcu=board_mcu,
+        pio_env=f"esphome_{board_mcu}",
+        pio_platform=pio_platform,
+    )
+    try:
+        source = script_path.read_text(encoding="utf-8")
+    except OSError as err:
+        # An unreadable declared script is a broken package, exactly like a
+        # missing one; must not be quieter than that case
+        raise EsphomeError(f"extraScript {script_path} is unreadable: {err}") from err
+    except UnicodeDecodeError as e:
+        # A content problem, best-effort like a SyntaxError below
+        _LOGGER.warning(
+            "PIO extra-script %s (in %s) is not UTF-8 (%r); ignoring its output",
+            script_path,
+            library_dir.name,
+            e,
+        )
+        return ExtraScriptResult()
+    old_cwd = Path.cwd()
+    try:
+        # Inside the try: a SyntaxError in a vendored script is just as
+        # best-effort as a runtime failure
+        code = compile(source, str(script_path), "exec")
+        os.chdir(library_dir)
+        exec(  # noqa: S102 pylint: disable=exec-used
+            code,
+            {
+                "Import": lambda *_args: None,  # SCons-side import; harmless here
+                "env": env,
+                "__file__": str(script_path),
+                "__name__": "__pio_extra_script__",
+            },
+        )
+    except SystemExit as e:
+        if not e.code:
+            # sys.exit() / sys.exit(0) is a normal PlatformIO script ending;
+            # the capture is complete
+            return env.result
+        _LOGGER.warning(
+            "PIO extra-script %s (in %s) exited with status %r; ignoring its output",
+            script_path,
+            library_dir.name,
+            e.code,
+        )
+        return ExtraScriptResult()
+    except Exception as e:  # noqa: BLE001  # pylint: disable=broad-exception-caught
+        # Discard any partial capture: half-applied flags could build wrong
+        # firmware that links cleanly.
+        _LOGGER.warning(
+            "PIO extra-script %s (in %s) raised %r; ignoring its output",
+            script_path,
+            library_dir.name,
+            e,
+        )
+        return ExtraScriptResult()
+    finally:
+        os.chdir(old_cwd)
+    return env.result
+
+
+def _str_entries(bucket: list, kind: str) -> list[str]:
+    # Third-party scripts legally append SCons nodes, ints, or dicts;
+    # stringifying those into flags would hand the compiler garbage
+    good = [entry for entry in bucket if isinstance(entry, str)]
+    for entry in bucket:
+        if not isinstance(entry, str):
+            _LOGGER.warning("Ignoring unsupported %s entry %r", kind, entry)
+    return good
+
+
+def captured_as_build_flags(
+    result: ExtraScriptResult, *, library_dir: Path
+) -> list[str]:
+    """Translate captured env vars into -L/-l/-D/raw build flags; path
+    entries anchor to ``library_dir`` so the build files stay portable."""
+    flags: list[str] = []
+    library_root = library_dir.resolve()
+
+    def _anchored(path: str) -> str:
+        # Anchor relative paths to library_dir; the script's CWD has been
+        # restored by now
+        resolved = (library_dir / path).resolve()
+        try:
+            return str(resolved.relative_to(library_root))
+        except ValueError:
+            return str(resolved)
+
+    # shlex.quote so a spaced path survives lex_build_flags as one token
+    flags.extend(
+        f"-I{shlex.quote(_anchored(path))}"
+        for path in _str_entries(result.cpppath, "CPPPATH")
+    )
+    flags.extend(
+        f"-L{shlex.quote(_anchored(path))}"
+        for path in _str_entries(result.libpath, "LIBPATH")
+    )
+    flags.extend(f"-l{shlex.quote(lib)}" for lib in _str_entries(result.libs, "LIBS"))
+    for define in result.cppdefines:
+        if define.value is None:
+            # {"FOO": None} / ("FOO", None) is a bare -DFOO in SCons
+            flags.append(shlex.quote(f"-D{define.name}"))
+        else:
+            flags.append(shlex.quote(f"-D{define.name}={define.value}"))
+    # Each captured entry is one argv token in SCons; quote so the
+    # lex_build_flags round-trip cannot split a spaced value into two.
+    # LINKFLAGS are deliberately absent: they travel via
+    # ESPHOME_DATA_LINK_FLAGS_KEY straight to the link line.
+    flags.extend(shlex.quote(f) for f in _str_entries(result.cppflags, "CPPFLAGS"))
+    return flags

esphome/platformio/library.py

@@ -13,7 +13,7 @@ regardless of which toolchain consumes the result.
 """
 
 from collections import deque
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 from dataclasses import dataclass, field
 import glob
 import hashlib
@@ -47,25 +47,34 @@ DEFAULT_BUILD_SRC_FILTER = (
 DEFAULT_BUILD_SRC_DIRS = "src"
 DEFAULT_BUILD_INCLUDE_DIR = "include"
 DEFAULT_BUILD_FLAGS = []
-SRC_FILE_EXTENSIONS = [
-    ".c",
-    ".cpp",
-    ".cc",
-    ".cxx",
-    ".c++",
-    ".S",
-    ".spp",
-    ".SPP",
-    ".sx",
-    ".s",
-    ".asm",
-    ".ASM",
-]
+# Suffix -> compiler kind (PlatformIO's CSUFFIXES/CXXSUFFIXES/ASSUFFIXES);
+# "asm" merges SCons's AS and ASPP sets. Per CXXSUFFIXES .C/.C++ are C++
+# here, even where SCons demotes .C on case-insensitive filesystems.
+SOURCE_KIND_FOR_SUFFIX: dict[str, str] = {
+    ".c": "c",
+    ".cpp": "cxx",
+    ".cc": "cxx",
+    ".cxx": "cxx",
+    ".c++": "cxx",
+    ".C": "cxx",
+    ".C++": "cxx",
+    ".S": "asm",
+    ".spp": "asm",
+    ".SPP": "asm",
+    ".sx": "asm",
+    ".s": "asm",
+    ".asm": "asm",
+    ".ASM": "asm",
+}
+SRC_FILE_EXTENSIONS = list(SOURCE_KIND_FOR_SUFFIX)
 
 DOMAIN = "pio_components"
 
 ESPHOME_DATA_KEY = "ESPHOME"
 ESPHOME_DATA_EXTRA_CMAKE_KEY = "EXTRA_CMAKE"
+# Captured extra-script LINKFLAGS; kept apart from build.flags so they reach
+# the link line (target_link_options), not target_compile_options
+ESPHOME_DATA_LINK_FLAGS_KEY = "LINK_FLAGS"
 
 
 class Source:
@@ -203,6 +212,11 @@ class InvalidLibrary(Exception):
     pass
 
 
+class IncompatiblePlatform(InvalidLibrary):
+    """The routine cross-platform skip, typed so callers need not match
+    message text."""
+
+
 class ConvertedLibrary:
     """A resolved PlatformIO library plus its parsed manifest and on-disk path.
 
@@ -427,17 +441,22 @@ def check_library_data(data: dict, platform: str | None, framework: str):
     if isinstance(platforms, str):
         platforms = [a.strip() for a in platforms.split(",")]
     platforms = ensure_list(platforms)
+    if not all(isinstance(pf, str) for pf in platforms):
+        # A real (non-platform) manifest problem; callers warn, not skip
+        raise InvalidLibrary(f"Malformed platforms value: {platforms!r}")
 
     # Check if library supports the target platform
     valid_platforms = platform is None or "*" in platforms or platform in platforms
 
     if not valid_platforms:
-        raise InvalidLibrary(f"Unsupported library platforms: {platforms}")
+        raise IncompatiblePlatform(f"Unsupported library platforms: {platforms}")
 
     frameworks = data.get("frameworks", "*")
     if isinstance(frameworks, str):
         frameworks = [a.strip() for a in frameworks.split(",")]
     frameworks = ensure_list(frameworks)
+    if not all(isinstance(fw, str) for fw in frameworks):
+        raise InvalidLibrary(f"Malformed frameworks value: {frameworks!r}")
 
     # Check if library declares the active framework. PIO library manifests
     # often list only "arduino" even when the library actually compiles fine
@@ -455,7 +474,7 @@ def check_library_data(data: dict, platform: str | None, framework: str):
         )
 
 
-def _parse_library_json(library_json_path: PathType):
+def parse_library_json(library_json_path: PathType):
     """
     Load and parse a JSON file describing a library.
 
@@ -469,7 +488,7 @@ def _parse_library_json(library_json_path: PathType):
         return json.load(fp)
 
 
-def _parse_library_properties(library_properties_path: PathType):
+def parse_library_properties(library_properties_path: PathType):
     """
     Parse a key-value platformio .properties style file into a dictionary.
 
@@ -553,19 +572,131 @@ def _resolve_registry_version(
     return owner, name, best["name"], pkgfile["download_url"]
 
 
-def _normalize_dependencies(dependencies: Any) -> list[dict]:
+def split_flag_entry(entry: Any, owner: str) -> list[str]:
+    """``shlex.split`` with a clean error naming the offending flags entry."""
+    # Late import: shlex is only needed when actually lexing flags
+    import shlex
+
+    try:
+        return shlex.split(entry)
+    except (ValueError, AttributeError, TypeError) as err:
+        # AttributeError/TypeError: a dict or number from a third-party
+        # manifest; name the entry instead of an opaque shlex traceback
+        raise EsphomeError(f"Malformed build flag {entry!r} in {owner}: {err}") from err
+
+
+def lex_build_flags(entries: str | list[str], owner: str) -> list[str]:
+    """Shell-lex ``build.flags`` entries the way PlatformIO's ParseFlags
+    does; bare -I/-L/-l/-D tokens re-glue to their argument."""
+    # Lex per entry as ParseFlags does: a dangling -I must warn, not absorb
+    # the next entry's first token
+    return [
+        token
+        for entry in ensure_list(entries)
+        for token in join_flag_args(split_flag_entry(entry, owner), owner)
+    ]
+
+
+# Flags whose argument may follow as a separate token; ParseFlags glues them
+BARE_ARG_FLAGS = frozenset({"-I", "-L", "-l", "-D"})
+
+
+def join_flag_args(tokens: Iterable[str], owner: str) -> list[str]:
+    """Join a bare ``-I``/``-L``/``-l``/``-D`` with its following token, as
+    PlatformIO's ParseFlags does. A trailing or empty argument is warned and
+    dropped: the bare flag would make gcc eat the next flag."""
+    out: list[str] = []
+    it = iter(tokens)
+    for tok in it:
+        if tok in BARE_ARG_FLAGS:
+            arg = next(it, None)
+            if arg is None:
+                _LOGGER.warning("Ignoring trailing '%s' in %s build flags", tok, owner)
+                break
+            if not arg:
+                _LOGGER.warning(
+                    "Ignoring '%s' with empty argument in %s build flags", tok, owner
+                )
+                continue
+            tok += arg
+        out.append(tok)
+    return out
+
+
+def warn_properties_depends(name: str, data: object) -> None:
+    """Warn for ``depends=``-only manifests; the walk reads only the JSON
+    ``dependencies`` key, so they would otherwise drop silently."""
+    if isinstance(data, dict) and not data.get("dependencies") and data.get("depends"):
+        # INFO: common and unactionable for transitive libraries; a WARNING
+        # on every build would train users to ignore the stream
+        _LOGGER.info(
+            "Library %s declares dependencies via library.properties "
+            "depends=, which are not resolved automatically; add them with "
+            "add_library() if needed",
+            name,
+        )
+
+
+def dependency_is_usable(
+    dep: dict, platform: str | None, framework: str, requester: str
+) -> bool:
+    """Compatibility filter for a manifest dependency: platform mismatches
+    skip at debug, any other ``InvalidLibrary`` warns naming the requester."""
+    try:
+        check_library_data(dep, platform, framework)
+    except IncompatiblePlatform as e:
+        _LOGGER.debug("Skip dependency %s of %s: %s", dep.get("name"), requester, e)
+        return False
+    except InvalidLibrary as e:
+        _LOGGER.warning(
+            "Skipping dependency %s of %s: %s", dep.get("name"), requester, e
+        )
+        return False
+    return True
+
+
+def _valid_dependency_entry(entry: dict, manifest_name: str) -> bool:
+    """Whether a normalized entry carries a usable name (non-empty string),
+    version (string, if present), and owner (string, if present); invalid
+    entries warn naming the manifest."""
+    name = entry.get("name")
+    owner = entry.get("owner")
+    name_ok = isinstance(name, str) and name
+    version_ok = "version" not in entry or isinstance(entry["version"], str)
+    owner_ok = owner is None or isinstance(owner, str)
+    if name_ok and version_ok and owner_ok:
+        return True
+    _LOGGER.warning(
+        "Ignoring unrecognized dependency entry %r of %s", entry, manifest_name
+    )
+    return False
+
+
+def normalize_dependencies(
+    dependencies: Any, manifest_name: str = "manifest"
+) -> list[dict]:
     """Normalize a library manifest's ``dependencies`` to a list of dicts.
 
-    PIO's library.json accepts both the list-of-dicts form and the shorthand
-    dict form (``{"owner/Name": "version_spec"}``); normalize the latter so
-    callers see a uniform list.
+    PIO's library.json accepts the list-of-dicts form, the shorthand dict
+    form (``{"owner/Name": "version_spec"}``), bare name strings inside the
+    list, and a plain (possibly comma-separated) string; normalize them all
+    so callers see a uniform list. ``manifest_name`` names the manifest in the
+    warning for entries that cannot be normalized.
+
+    Bare-name spellings carry no version; the dependency walk later drops
+    version-less entries at DEBUG, since they are usually names of bundled
+    framework libraries (Wire, SPI) that need no registry install.
     """
-    if not dependencies:
+    if dependencies is None:
         return []
+    if isinstance(dependencies, str):
+        # A plain string is one or more comma-separated names; iterating it
+        # as a list would shred it into one-character "libraries"
+        return [{"name": n.strip()} for n in dependencies.split(",") if n.strip()]
     if isinstance(dependencies, dict):
         normalized = []
         for raw_name, spec in dependencies.items():
-            if "/" in raw_name:
+            if isinstance(raw_name, str) and "/" in raw_name:
                 owner, pkgname = raw_name.split("/", 1)
             else:
                 owner, pkgname = None, raw_name
@@ -574,9 +705,31 @@ def _normalize_dependencies(dependencies: Any) -> list[dict]:
                 entry.update(spec)
             else:
                 entry["version"] = spec
-            normalized.append(entry)
+            if _valid_dependency_entry(entry, manifest_name):
+                normalized.append(entry)
         return normalized
-    return [d for d in dependencies if isinstance(d, dict)]
+    if not isinstance(dependencies, (list, tuple)):
+        _LOGGER.warning(
+            "Ignoring unrecognized dependencies %r of %s",
+            dependencies,
+            manifest_name,
+        )
+        return []
+    normalized = []
+    for entry in dependencies:
+        if isinstance(entry, dict):
+            if _valid_dependency_entry(entry, manifest_name):
+                normalized.append(entry)
+        elif isinstance(entry, str) and entry:
+            # PIO also accepts a bare list of names ("dependencies": ["Wire"])
+            normalized.append({"name": entry})
+        else:
+            _LOGGER.warning(
+                "Ignoring unrecognized dependency entry %r of %s",
+                entry,
+                manifest_name,
+            )
+    return normalized
 
 
 @dataclass
@@ -688,6 +841,24 @@ def _node_key(
     return name, "registry", (owner, pkgname)
 
 
+def lib_ignore_set() -> set[str]:
+    """The ``lib_ignore`` names from ``esphome->platformio_options``,
+    normalized to lowercase short names (the part after the ``/``)."""
+    return {
+        name.split("/")[-1].lower()
+        for name in CORE.platformio_options.get("lib_ignore", [])
+    }
+
+
+def is_lib_ignored(name: str | None, lib_ignore: set[str]) -> bool:
+    """Whether ``name`` matches the normalized ``lib_ignore`` set."""
+    return (
+        bool(lib_ignore)
+        and name is not None
+        and (name.split("/")[-1].lower() in lib_ignore)
+    )
+
+
 def convert_libraries(
     libraries: list[Library], backend: LibraryBackend
 ) -> list[ConvertedLibrary]:
@@ -713,10 +884,7 @@ def convert_libraries(
     """
     nodes: dict[str, _LibNode] = {}
 
-    lib_ignore = {
-        name.split("/")[-1].lower()
-        for name in CORE.platformio_options.get("lib_ignore", [])
-    }
+    lib_ignore = lib_ignore_set()
 
     # The generated build files inside the shared cache bake in the dependency
     # wiring, which lib_ignore changes; salt the cache path so configs with
@@ -728,11 +896,6 @@ def convert_libraries(
         else ""
     )
 
-    def is_ignored(name: str | None) -> bool:
-        if not lib_ignore or name is None:
-            return False
-        return name.split("/")[-1].lower() in lib_ignore
-
     def add_spec(name: str | None, version: str | None, repository: str | None) -> str:
         key, kind, locator = _node_key(name, version, repository)
         node = nodes.get(key) or _LibNode(key=key, is_git=kind == "git")
@@ -781,7 +944,7 @@ def convert_libraries(
     top_level = [
         add_spec(library.name, library.version, library.repository)
         for library in libraries
-        if not is_ignored(library.name)
+        if not is_lib_ignored(library.name, lib_ignore)
     ]
 
     # Collect + resolve to a fixpoint: a node is (re)resolved whenever its
@@ -795,10 +958,8 @@ def convert_libraries(
         key = worklist.popleft()
         node = nodes[key]
 
-        # A node is queued once per referring edge; skip the (uncached) registry
-        # lookup + download + dependency walk unless its requirement set grew
-        # since the last resolve. Requirements only ever grow, so this still
-        # converges the fixpoint and terminates dependency cycles.
+        # Re-resolve only when the requirement set grew; requirements
+        # only ever grow, so the fixpoint converges and cycles terminate
         requirements = frozenset(node.requirements)
         if resolved_requirements.get(key) == requirements:
             continue
@@ -823,11 +984,8 @@ def convert_libraries(
         has_json = library_json_path.is_file()
         has_properties = library_properties_path.is_file()
         if not has_json and not has_properties and not node.is_local:
-            # The shared cache can hold a broken copy (e.g. a clone or an
-            # extraction interrupted by a killed process). Force one
-            # re-download so a bad cache entry self-heals instead of failing
-            # every build until the user runs a full clean. A local source is
-            # read in place, so there is nothing to re-download.
+            # An interrupted clone/extraction self-heals with one forced
+            # re-download; a local source has nothing to re-download
             _LOGGER.warning(
                 "Library %s at %s is missing library.json and library.properties; "
                 "re-downloading",
@@ -838,49 +996,85 @@ def convert_libraries(
             has_json = library_json_path.is_file()
             has_properties = library_properties_path.is_file()
         if has_json:
-            component.data = _parse_library_json(library_json_path)
+            component.data = parse_library_json(library_json_path)
         elif has_properties:
-            component.data = _parse_library_properties(library_properties_path)
+            component.data = parse_library_properties(library_properties_path)
         else:
-            # For a local library a missing manifest is user input, so raise
-            # EsphomeError (clean CLI message) like the missing-directory case;
-            # for registry/git a missing manifest means a corrupt cache, which
-            # is not user error, so keep RuntimeError.
+            # Local sources are user input (EsphomeError); a registry/git
+            # miss means a corrupt cache (RuntimeError)
             error_cls = EsphomeError if node.is_local else RuntimeError
             raise error_cls(
                 f"Invalid PIO library {key}: missing library.json and "
                 f"library.properties in {source_dir}"
             )
 
+        # A bare json.load imposes no shape; every backend dereferences
+        # these fields, so validate once here and name the library
+        malformed = not isinstance(component.data, dict)
+        if not malformed:
+            build = component.data.get("build", {})
+            esphome_data = component.data.get(ESPHOME_DATA_KEY, {})
+            malformed = (
+                not isinstance(build, dict)
+                or not isinstance(esphome_data, dict)
+                or not isinstance(
+                    esphome_data.get(ESPHOME_DATA_LINK_FLAGS_KEY, []), list
+                )
+                or not isinstance(build.get("srcDir", ""), str)
+                or not isinstance(build.get("includeDir", ""), str)
+                or not isinstance(build.get("srcFilter", ""), (str, list))
+            )
+        if malformed:
+            # Fail fast only for a library the user asked for; a defect in
+            # an unrequested corner of the graph must not block the build
+            if key in top_level_keys:
+                raise EsphomeError(f"Library {key} has a malformed manifest")
+            _LOGGER.warning("Skipping dependency %s: malformed manifest", key)
+            continue
+        warn_properties_depends(component.name, component.data)
+
         try:
             check_library_data(component.data, backend.platform, backend.framework)
         except InvalidLibrary as e:
-            # Skip an incompatible transitive dependency, but fail fast if a
-            # top-level library the build explicitly requested is incompatible.
+            # An explicitly requested library fails fast; the routine
+            # cross-platform skip stays at debug, other causes warn
             if key in top_level_keys:
-                raise RuntimeError(
-                    f"Requested library {key} is not compatible with "
-                    f"{backend.framework}: {e}"
-                ) from e
-            _LOGGER.debug("Skip incompatible dependency %s: %s", key, str(e))
+                reason = (
+                    f"is not compatible with {backend.framework}"
+                    if isinstance(e, IncompatiblePlatform)
+                    else "has a malformed manifest"
+                )
+                raise RuntimeError(f"Requested library {key} {reason}: {e}") from e
+            if isinstance(e, IncompatiblePlatform):
+                _LOGGER.debug("Skip incompatible dependency %s: %s", key, str(e))
+            else:
+                _LOGGER.warning("Skipping dependency %s: %s", key, str(e))
             continue
         components[key] = component
 
         # Requirements changed (we got past the short-circuit above), so
         # (re)walk this component's dependencies.
         node.edges = set()
-        for dependency in _normalize_dependencies(component.data.get("dependencies")):
-            if "name" not in dependency or "version" not in dependency:
+        for dependency in normalize_dependencies(
+            component.data.get("dependencies"), component.name
+        ):
+            if "version" not in dependency:
+                # Cannot resolve from the registry; common for bundled
+                # names (Wire, SPI) -- unactionable noise above debug
+                _LOGGER.debug(
+                    "Skip version-less dependency %r of %s",
+                    dependency.get("name"),
+                    component.name,
+                )
                 continue
-            try:
-                check_library_data(dependency, backend.platform, backend.framework)
-            except InvalidLibrary as e:
-                _LOGGER.debug("Skip dependency %s: %s", dependency.get("name"), str(e))
+            if not dependency_is_usable(
+                dependency, backend.platform, backend.framework, component.name
+            ):
                 continue
             dep_name = _owner_pkgname_to_name(
                 dependency.get("owner"), dependency.get("name")
             )
-            if is_ignored(dep_name):
+            if is_lib_ignored(dep_name, lib_ignore):
                 _LOGGER.debug("Skip ignored dependency %s", dep_name)
                 continue
             # The version field may actually be a URL (git/archive dependency).

esphome/platformio/toolchain.py

@@ -254,6 +254,9 @@ def _ccache_runs(ccache: str) -> bool:
             stdout=subprocess.DEVNULL,
             stderr=subprocess.DEVNULL,
             timeout=15,
+            # Repo-wide convention (posix_spawn fast path); see the
+            # close_fds=False call sites across esphome/ and script/helpers.py
+            close_fds=False,
         )
     except (OSError, subprocess.SubprocessError):
         _LOGGER.warning(