Repository navigation
Expand file tree
/
Copy pathcheck_catalog.py
More file actions
executable file
·509 lines (459 loc) · 19 KB
/
Copy pathcheck_catalog.py
File metadata and controls
executable file
·509 lines (459 loc) · 19 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
#!/usr/bin/env python3
"""Smoke-test the split catalog for shape regressions.
Reads ``definitions/components.index.json`` plus per-id bodies
under ``definitions/components/``.
Loads the catalog via ``ComponentCatalog`` (i.e. through the same
JSON loader the API uses), then asserts that a curated list of
well-known components are present and structured the way the
frontend expects. Catches:
- A popular component disappearing from the catalog
- A field's type changing in a way that would break form rendering
(e.g. ``output.gpio.pin`` flipping from ``pin`` to ``string``)
- ``id`` fields regressing into spurious cross-references
Designed to run in CI right after ``script/sync_components.py``,
before the diff-budget check / PR creation. Exits non-zero on the
first violation with a clear "[component].[field] expected X, got Y"
message so the operator can read the workflow log without spelunking.
Run locally:
python script/check_catalog.py
"""
from __future__ import annotations
import json
import sys
from pathlib import Path
from typing import Any
# Allow running via ``python script/check_catalog.py`` without
# installing the package.
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
from esphome_device_builder.controllers.components import (
ComponentCatalog,
_load_body_from_disk,
)
from script.sync_components import _FIELD_BULLET_PATTERN
# Per-component shape assertions. Each entry is a tuple of
# ``(component_id, [(field_key, type, required, refs)])``. A field
# is a 4-tuple where ``type`` is a ConfigEntryType.value (or a tuple
# of acceptable values, for fields mid-migration), ``required`` is
# bool or None (don't care), and ``refs`` is the expected
# ``references_component`` value or None (don't care).
#
# The list is intentionally short — these are the components the
# frontend uses on every device's "Add component" flow. If they
# break, the whole catalog UX breaks.
_EXPECTATIONS: list[
tuple[str, list[tuple[str, str | tuple[str, ...], bool | None, str | None]]]
] = [
(
"wifi",
[
# ssid is migrating to a secret-eligible secure_string (2026.6);
# accept both while stable still emits a plain string.
("ssid", ("string", "secure_string"), None, None),
("password", "secure_string", None, None),
# ``ap`` is wrapped in a custom validator and would
# regress to ``string`` if the _FIELD_OVERRIDES entry
# were removed (issue #308).
("ap", "nested", None, None),
],
),
(
"uart",
[
# Same custom-validator-wrapper pattern as wifi.ap.
("debug", "nested", None, None),
],
),
(
"ble_nus",
[
# Reuses uart's maybe_empty_debug — share the override.
("debug", "nested", None, None),
],
),
(
"api",
[
("encryption", "nested", None, None),
],
),
(
"esphome",
[
("name", "string", True, None),
("comment", "string", None, None),
("areas", "nested", None, None),
],
),
(
"logger",
[
("level", "string", None, None),
("logs", "map", None, None),
],
),
(
"i2c",
[
("sda", "pin", None, None),
("scl", "pin", None, None),
],
),
(
"esp32",
[
("variant", "string", None, None),
("framework", "nested", None, None),
],
),
(
"ota.esphome",
[
("password", "secure_string", None, None),
],
),
(
"sensor.dht",
[
("pin", "pin", True, None),
("temperature", "nested", None, None),
("humidity", "nested", None, None),
],
),
(
"output.gpio",
[
("pin", "pin", True, None),
# The classic regression: id used to be type=string with
# references_component="gpio". It's the component's OWN id.
("id", "id", True, None),
# power_supply IS a real cross-reference and must stay
# one — guards the inverse regression.
("power_supply", "id", None, "power_supply"),
],
),
(
"light.binary",
[
("output", "id", True, "output"),
],
),
(
"switch.gpio",
[
("pin", "pin", True, None),
],
),
(
"stepper.uln2003",
[
# Suffix-stripping custom validators ("<float> steps/s[^2]")
# that would regress to bare ``float`` if ``_derive_suffix_units``
# stopped classifying them (issue #2056).
("max_speed", "float_with_unit", True, None),
("acceleration", "float_with_unit", None, None),
("deceleration", "float_with_unit", None, None),
],
),
(
"remote_transmitter",
[
# ``cv.percentage_int`` accepts a ``%`` suffix; would regress to
# ``integer`` (rejecting the documented "50%") if the
# ``_NON_INTROSPECTABLE_UNITS`` entry were removed.
("carrier_duty_percent", "float_with_unit", True, None),
],
),
(
"remote_receiver",
[
# ``cv.validate_bytes`` has no ``float_with_unit`` closure to
# introspect; the byte picker exists only through its
# ``_NON_INTROSPECTABLE_UNITS`` entry (mis-keyed as
# ``data_size`` until #2363).
("buffer_size", "float_with_unit", None, None),
],
),
]
def main() -> int: # noqa: C901
catalog = ComponentCatalog()
catalog.load()
if not catalog._components:
print("ERROR: catalog is empty — sync_components.py probably failed.")
return 2
failures: list[str] = []
for component_id, fields in _EXPECTATIONS:
if component_id not in catalog._by_id:
failures.append(f"missing component: {component_id}")
continue
component = _load_body_from_disk(component_id)
if component is None:
failures.append(f"missing component body on disk: {component_id}")
continue
for key, expected_type, expected_required, expected_refs in fields:
entry = next((e for e in component.config_entries if e.key == key), None)
if entry is None:
failures.append(f"{component_id}: missing field {key!r}")
continue
actual_type = str(entry.type)
allowed_types = (expected_type,) if isinstance(expected_type, str) else expected_type
if actual_type not in allowed_types:
failures.append(
f"{component_id}.{key}: type expected {expected_type!r}, got {actual_type!r}"
)
if expected_required is not None and entry.required != expected_required:
failures.append(
f"{component_id}.{key}: required expected {expected_required}, "
f"got {entry.required}"
)
if entry.references_component != expected_refs:
failures.append(
f"{component_id}.{key}: references_component expected "
f"{expected_refs!r}, got {entry.references_component!r}"
)
failures.extend(_check_option_lists(catalog))
failures.extend(_check_component_gating(catalog))
# One shared body pass feeds the full-catalog checks below.
all_bodies = [(cid, _load_body_from_disk(cid)) for cid in catalog._by_id]
failures.extend(_check_gating_floors(all_bodies))
failures.extend(_check_no_field_bullet_descriptions(catalog))
failures.extend(_check_boolean_options_exclusive(all_bodies))
failures.extend(_check_automation_enrichment_floor())
failures.extend(_check_list_shaped_filter_fields())
if failures:
print(f"FAIL: {len(failures)} catalog regression(s):")
for line in failures:
print(f" - {line}")
return 1
field_count = sum(len(fields) for _, fields in _EXPECTATIONS)
print(
f"OK: {len(_EXPECTATIONS)} components, {field_count} fields, "
f"{len(_OPTION_EXPECTATIONS)} option lists, "
f"{len(_GATING_EXPECTATIONS)} gating rules, "
f"{len(_GATING_FLOORS)} gating floors, "
"boolean/options exclusivity verified."
)
return 0
# Per-field minimum option-count assertions. Catches regressions where
# inherited fields like ``device_class`` lose their enum values
# because of a partial-override merge bug, or where
# ``unit_of_measurement``'s curated UNIT_* list isn't being layered on.
# Each tuple is ``(component_id, field_path, min_options)`` where
# ``field_path`` is dot-separated for nested access (e.g.
# ``humidity.state_class`` for ``sensor.dht``'s humidity sub-reading).
_OPTION_EXPECTATIONS: list[tuple[str, str, int]] = [
("sensor.ct_clamp", "device_class", 50),
("sensor.ct_clamp", "unit_of_measurement", 30),
("sensor.ct_clamp", "state_class", 3),
("sensor.ct_clamp", "entity_category", 2),
# Inherited via extends + partial-override merge — the same field
# at a deeper level must keep its options.
("sensor.dht", "humidity.device_class", 50),
("sensor.dht", "humidity.state_class", 3),
]
# Cross-component gating assertions. Catches regressions where
# infrastructure-dependent fields (zigbee_sensor, web_server) lose
# their ``depends_on_component`` tag and start showing up on the
# form even when the named component isn't configured on the device.
# Gates are introspected from the live schema (requires_component /
# OnlyWith), so a component's own fields carry no self-gate; only
# entity-level inheritances belong here. The derivation itself is
# pinned against live manifests in
# ``tests/test_sync_components_component_gates.py``.
_GATING_EXPECTATIONS: list[tuple[str, str, str | None]] = [
# Zigbee + web_server entity options are inherited onto every
# sensor via ``_SENSOR_SCHEMA``; they must be gated.
("sensor.ct_clamp", "zigbee_sensor", "zigbee"),
("sensor.ct_clamp", "web_server", "web_server"),
# MQTT entity options inherited via ``MQTT_COMPONENT_SCHEMA`` /
# ``MQTT_COMMAND_COMPONENT_SCHEMA`` (#2300).
("switch.gpio", "state_topic", "mqtt"),
("switch.gpio", "command_retain", "mqtt"),
# ``None`` pins gate *absence*: mqtt's own page never self-gates,
# and singleton auto-loaded base ids stay ungated advanced pickers
# (#1441; restored in #2305).
("mqtt", "discovery", None),
("captive_portal", "web_server_base_id", None),
]
# Catalog-wide floors on gated-entry counts. The per-field rules above
# can't catch the wholesale failure mode: live-schema introspection
# silently returning nothing (esphome upstream reshapes the
# ``requires_component`` closures or ``OnlyWith`` markers, the walker
# breaks) and a sync shipping a catalog with every gate stripped —
# thousands of MQTT/zigbee/web_server fields un-hidden at once. Floors
# sit well below the live counts so legitimate churn passes and
# wholesale loss fails; the band test in
# ``tests/test_check_catalog_guards.py`` keeps them calibrated against
# the checked-in catalog from both sides.
_GATING_FLOORS: dict[str, int] = {
"mqtt": 6000,
"web_server": 3500,
"zigbee": 4000,
}
# Catalog-wide floor on automation entries carrying live-introspection
# enrichment (unit_options / display_format / range). A component import
# silently failing mid-sweep de-refines its actions; wholesale loss
# lands the count under the floor and reds the sync smoke. Sits well
# below the live count (149 at introduction) so legitimate churn
# passes; the band test keeps it calibrated from both sides.
_AUTOMATION_ENRICHMENT_FLOOR = 100
_AUTOMATIONS_DIR = (
Path(__file__).parent.parent / "esphome_device_builder" / "definitions" / "automations"
)
def _check_automation_enrichment_floor() -> list[str]:
"""Fail when refinement-shaped automation enrichment falls below the floor."""
enriched = count_enriched_automation_entries()
if enriched >= _AUTOMATION_ENRICHMENT_FLOOR:
return []
return [
(
f"automation enrichment count {enriched} fell below floor "
f"{_AUTOMATION_ENRICHMENT_FLOOR} — a component import likely failed "
"mid-sweep, de-refining its actions"
)
]
# Filter fields whose YAML value is a list (or a list-or-mapping union);
# a plain single-value string input would drop the list on save.
_LIST_SHAPED_FILTER_FIELDS: list[tuple[str, str]] = [
("to_ntc_resistance", "calibration"),
("to_ntc_temperature", "calibration"),
]
def _check_list_shaped_filter_fields() -> list[str]:
"""Fail when a list-shaped filter field ships as a single-value input."""
base = _AUTOMATIONS_DIR / "filters"
failures = []
for filter_id, key in _LIST_SHAPED_FILTER_FIELDS:
path = base / f"{filter_id}.json"
if not path.is_file():
failures.append(f"filter {filter_id} body is missing")
continue
body = json.loads(path.read_text(encoding="utf-8"))
entry = next((e for e in body.get("config_entries") or [] if e["key"] == key), None)
if entry is None or not (entry.get("type") == "unknown" or entry.get("multi_value")):
failures.append(f"filter {filter_id}.{key} lost its list shape: {entry!r}")
return failures
def count_enriched_automation_entries() -> int:
"""Count action / condition fields carrying refinement-shaped enrichment."""
base = _AUTOMATIONS_DIR
count = 0
for sub in ("actions", "conditions"):
for body_path in sorted((base / sub).glob("*.json")):
body = json.loads(body_path.read_text(encoding="utf-8"))
for entry in body.get("config_entries") or []:
if entry.get("unit_options") or entry.get("display_format") or entry.get("range"):
count += 1
return count
def _resolve_field(component: Any, path: str) -> Any:
"""Walk ``component.config_entries`` along a dotted ``path``."""
parts = path.split(".")
entries = component.config_entries
entry = None
for part in parts:
entry = next((e for e in entries if e.key == part), None)
if entry is None:
return None
entries = entry.config_entries or []
return entry
def _check_option_lists(catalog: ComponentCatalog) -> list[str]:
"""Return a failure message per field whose option list is too small."""
failures: list[str] = []
for cid, path, minimum in _OPTION_EXPECTATIONS:
if cid not in catalog._by_id:
failures.append(f"options check: missing component {cid}")
continue
component = _load_body_from_disk(cid)
if component is None:
failures.append(f"options check: missing body for {cid}")
continue
entry = _resolve_field(component, path)
if entry is None:
failures.append(f"options check: {cid}.{path} not found")
continue
count = len(entry.options or [])
if count < minimum:
failures.append(
f"{cid}.{path}: options count {count} < expected minimum {minimum} "
"(inherited enum values may have been lost)"
)
return failures
def _check_no_field_bullet_descriptions(catalog: ComponentCatalog) -> list[str]:
"""Fail when any component's description matches the field-bullet pattern.
The pattern is imported from ``script/sync_components.py`` so a widening
on the sync side automatically tightens the check side — they cannot
drift apart. Triggered when the upstream esphome.io schema_doc bug
leaks past ``_repair_field_bullet_descriptions``.
"""
failures: list[str] = []
for component in catalog._by_id.values():
desc = (component.description or "").strip()
if desc and _FIELD_BULLET_PATTERN.match(desc):
failures.append(
f"{component.id}: description is a config-variables bullet "
f"({desc[:80]!r}) — sync workaround missed it"
)
return failures
def _check_component_gating(catalog: ComponentCatalog) -> list[str]:
"""Return a failure message per field missing its ``depends_on_component``."""
failures: list[str] = []
for cid, path, gate in _GATING_EXPECTATIONS:
if cid not in catalog._by_id:
failures.append(f"gating check: missing component {cid}")
continue
component = _load_body_from_disk(cid)
if component is None:
failures.append(f"gating check: missing body for {cid}")
continue
entry = _resolve_field(component, path)
if entry is None:
failures.append(f"gating check: {cid}.{path} not found")
continue
if entry.depends_on_component != gate:
failures.append(
f"{cid}.{path}: depends_on_component expected {gate!r}, "
f"got {entry.depends_on_component!r}"
)
return failures
def _check_gating_floors(bodies: list[tuple[str, Any]]) -> list[str]:
"""Return a failure per gate whose catalog-wide entry count fell below its floor."""
counts: dict[str, int] = {}
for _cid, component in bodies:
if component is None:
continue
stack = list(component.config_entries or [])
while stack:
entry = stack.pop()
if entry.depends_on_component:
counts[entry.depends_on_component] = counts.get(entry.depends_on_component, 0) + 1
stack.extend(entry.config_entries or [])
failures: list[str] = []
for gate, floor in _GATING_FLOORS.items():
if counts.get(gate, 0) < floor:
failures.append(
f"gating floor: {counts.get(gate, 0)} entries gated on {gate!r}, "
f"expected at least {floor} — introspection likely stopped "
"discovering gates"
)
return failures
def _check_boolean_options_exclusive(bodies: list[tuple[str, Any]]) -> list[str]:
"""Fail on any entry typed ``boolean`` that also carries an option list.
The frontend renders any entry with options as a dropdown, so a boolean
type alongside options means a ``cv.Any(cv.boolean, cv.one_of(...))``
union lost its true/false half (``zigbee.wipe_on_boot``) —
``_merge_boolean_union_options`` on the sync side should have folded the
boolean literals into the options instead.
"""
failures: list[str] = []
def walk(cid: str, entries: list[Any], prefix: str) -> None:
for entry in entries:
path = f"{prefix}{entry.key}"
if str(entry.type) == "boolean" and entry.options:
failures.append(f"{cid}.{path}: boolean entry carries an options list")
if entry.config_entries:
walk(cid, entry.config_entries, f"{path}.")
for cid, component in bodies:
if component is None:
failures.append(f"boolean/options check: missing body for {cid}")
elif component.config_entries:
walk(cid, component.config_entries, "")
return failures
if __name__ == "__main__":
sys.exit(main())