[core] Hide build & framework internals from the visual editor (#17449)

tests/component_tests/esp32/test_esp32.py

@@ -601,6 +601,40 @@ def test_network_wifi_ble_coexistence_reconciles_end_to_end(
     assert "CONFIG_ESP_WIFI_ENABLED" not in sdkconfig
 
 
+def test_esp32_build_internals_are_yaml_only() -> None:
+    """ESP32 raw framework / build inputs are ``YAML_ONLY``.
+
+    The framework block's PlatformIO package pins, raw ESP-IDF
+    sdkconfig options, the low-level ``advanced`` block, extra IDF
+    component sources, plus the partition table and toolchain override
+    on the main schema are build internals — never UI form fields.
+    User-facing choices (framework type/version, board, variant, …)
+    stay on the main form.
+    """
+    from esphome.components.esp32 import CONFIG_SCHEMA, FRAMEWORK_SCHEMA
+
+    fw_markers = {str(k): k for k in FRAMEWORK_SCHEMA.schema}
+    for field in (
+        "release",
+        "source",
+        "platform_version",
+        "sdkconfig_options",
+        "advanced",
+        "components",
+    ):
+        assert fw_markers[field].visibility is cv.Visibility.YAML_ONLY, field
+    # Framework type/version remain user-facing.
+    assert fw_markers["type"].visibility is None
+    assert fw_markers["version"].visibility is None
+
+    main_markers = {str(k): k for k in CONFIG_SCHEMA.validators[0].schema}
+    assert main_markers["partitions"].visibility is cv.Visibility.YAML_ONLY
+    # toolchain is a real but rarely-touched override -> advanced disclosure.
+    assert main_markers["toolchain"].visibility is cv.Visibility.ADVANCED
+    assert main_markers["board"].visibility is None
+    assert main_markers["flash_size"].visibility is None
+
+
 def test_downgrade_protection_passes_with_numeric_version_and_signing() -> None:
     assert _ota_downgrade_protection_errors("1.2.3", signed_ota_enabled=True) == []
 

tests/unit_tests/core/test_config.py

@@ -1307,3 +1307,34 @@ async def test_to_code_adds_libraries(yaml_file: Callable[[str], Path]) -> None:
     mock_cg.add_library.assert_any_call(
         "noise-c", None, "https://github.com/esphome/noise-c.git"
     )
+
+
+def test_esphome_build_internals_are_yaml_only() -> None:
+    """Raw build-system inputs in the ``esphome:`` block are ``YAML_ONLY``.
+
+    These knobs (compiler flags, raw PlatformIO options, C/C++ includes,
+    libraries, build host parallelism, the min-version gate, …) are not
+    meaningful as visual-editor form fields and a wrong value breaks the
+    build, so they must never render in a schema-aware UI.
+    """
+    # CONFIG_SCHEMA is cv.All(cv.Schema({...}), validate_hostname).
+    inner = config.CONFIG_SCHEMA.validators[0].schema
+    markers = {str(k): k for k in inner}
+    yaml_only_fields = {
+        CONF_BUILD_PATH,
+        "platformio_options",
+        "build_flags",
+        "environment_variables",
+        "includes",
+        "includes_c",
+        "libraries",
+        "debug_scheduler",
+    }
+    for field in yaml_only_fields:
+        assert markers[field].visibility is cv.Visibility.YAML_ONLY, field
+    # Packaging / build-host knobs are real but rarely-touched overrides:
+    # surface them under the editor's advanced disclosure, not yaml-only.
+    for field in ("min_version", "compile_process_limit"):
+        assert markers[field].visibility is cv.Visibility.ADVANCED, field
+    # A regular device-config field stays on the main form.
+    assert markers[CONF_NAME_ADD_MAC_SUFFIX].visibility is None