refactor(registry): match board families by token table, not substring ladder

for_device_by_model() had grown to 21 sequential `if key is None` branches
and 102 comment lines against 59 lines of code -- 33 of the repo's 243
commits have touched this file. Most of that bulk came from one wrong
primitive: substring matching on a delimited string.

Samsung spells the same board family with either delimiter, so '_RAC_' and
'-RAC-' each needed their own rule, and 'ARTIK051_DONGLE_REF' (issues #77,
#83) matched no '_TOKEN_' spelling at all because REF lands at the end of
the pipe-prefix with no trailing underscore -- which is what
_model_num_segments() existed to work around. Which field a rule searched
(modelNum, or modelNum + description) was historical accident. Collisions
like WAC vs WA were resolved by one `if` physically preceding another,
invisible in the code and explained at length in prose.

Tokenize on any non-alphanumeric run, upper-case, and look the tokens up in
a flat table. Every delimiter spelling collapses to one entry, both fields
go through the same matcher in a documented order (modelNum, then
description, then the fuzzy consumer prefix), and specificity is a property
of the table rather than of line ordering.

Two behaviours are preserved deliberately:

- modelNum is matched before description, which is what keeps the legacy
  gas cooktop correct: it reports 'ARTIK051_GB_CT_001' (CT) alongside
  'ARTIK051_GLOBAL_COOKTOP' (COOKTOP, which otherwise means induction).
  It is the only known device whose two fields disagree.
- _consumer_model_key still splits on '_' only. Widening it to '-' would
  read the dishwasher's 'ADW-WW-RTL-24-AILITE' board segment as a bare 'WW'
  washer.

Verified identical: all 49 device fixtures resolve to the same registry
before and after, and every existing for_device_by_model test case passes
unchanged. The table also picks up two families that previously depended on
oneUiVersion alone (TP1X_DA-AC-AIR air purifiers, ADW dishwashers), so they
now survive firmware that omits it.

TestBoardTokenAmbiguity guards the one property the flat lookup needs --
that no real model string contains two tokens naming different device types
-- across the whole fixture corpus, so a newly added dump exercises it
automatically.

The skill gains a section on routing: what each detection stage is for, the
rules for adding a token (name the specific type, never the board family;
never add a delimiter spelling; two-letter tokens are a last resort), when
to reach for the consumer prefix or a resource signature instead, and the
measured stake -- an unrouted device loses roughly half its entities.
This commit is contained in:
Marc Billow committed 2026-07-29 01:57:10 +00:00
1 parent 288ba02cc5
commit a863df1e59
4 files changed
+342 -185

No files matched your search

+15
View File
@@ -41,3 +41,18 @@ def fridge_resources() -> dict[str, dict]:
@pytest.fixture
def washer_resources() -> dict[str, dict]:
return _load_device('washer')
@pytest.fixture
def all_device_fixtures() -> dict[str, dict[str, dict]]:
"""Every scrubbed device dump, keyed by fixture name.
For invariants that must hold across the whole corpus rather than for one
device -- so a newly added dump exercises them automatically.
"""
return {
path.name[:-len('_device.json')]: _resources_from_dump(
json.loads(path.read_text())
)
for path in sorted(FIXTURES.glob('*_device.json'))
}
+111 -10
View File
@@ -114,23 +114,60 @@ class TestWasherRegistry:
assert href in registry.capabilities, f"{href} missing from washer registry"
class TestModelNumSegments:
def test_splits_pipe_prefix_on_underscore(self):
from custom_components.localthings.registry.by_type import _model_num_segments
assert _model_num_segments('ARTIK051_DONGLE_REF|00127641|000800200014') == [
class TestBoardTokens:
def test_splits_pipe_prefix_into_whole_tokens(self):
from custom_components.localthings.registry.by_type import _board_tokens
assert _board_tokens('ARTIK051_DONGLE_REF|00127641|000800200014', '|') == [
'ARTIK051', 'DONGLE', 'REF',
]
def test_ignores_everything_after_first_pipe(self):
from custom_components.localthings.registry.by_type import _model_num_segments
assert _model_num_segments('TP2X_RAC_20K|abc|REF_should_not_appear') == [
def test_ignores_everything_after_the_cut(self):
from custom_components.localthings.registry.by_type import _board_tokens
assert _board_tokens('TP2X_RAC_20K|abc|REF_should_not_appear', '|') == [
'TP2X', 'RAC', '20K',
]
def test_both_delimiters_produce_the_same_tokens(self):
"""The whole point of tokenizing: Samsung spells one board family
with either delimiter, and both must reduce to the same tokens."""
from custom_components.localthings.registry.by_type import _board_tokens
assert (_board_tokens('TP1X_DA-AC-RAC-01001_0000', '|')
== _board_tokens('TP1X_DA_AC_RAC_01001_0000', '|')
== ['TP1X', 'DA', 'AC', 'RAC', '01001', '0000'])
def test_upper_cases_and_drops_empty_runs(self):
from custom_components.localthings.registry.by_type import _board_tokens
assert _board_tokens('a--b__c', '|') == ['A', 'B', 'C']
def test_empty_for_none_or_empty_input(self):
from custom_components.localthings.registry.by_type import _model_num_segments
assert _model_num_segments('') == ['']
assert _model_num_segments(None) == ['']
from custom_components.localthings.registry.by_type import _board_tokens
assert _board_tokens('', '|') == []
assert _board_tokens(None, '|') == []
class TestBoardTokenTable:
def test_no_board_family_token_shadows_a_specific_type(self):
"""'DA-AC-' prefixes RAC/WAC/DHM/AIR alike -- a bare 'AC' entry would
type the dehumidifier and the air purifier as air conditioners."""
from custom_components.localthings.registry.by_type import _BOARD_TOKEN_TO_KEY
for family_token in ('AC', 'DA', 'KS', 'WM', 'TP1X', 'TP2X', 'ARTIK051'):
assert family_token not in _BOARD_TOKEN_TO_KEY
def test_every_token_resolves_to_a_real_registry(self):
from custom_components.localthings.registry.by_type import (
_BOARD_TOKEN_TO_KEY, _CONSUMER_PREFIX_TO_KEY, _REGISTRY_BY_KEY,
)
for token, key in _BOARD_TOKEN_TO_KEY.items():
assert key in _REGISTRY_BY_KEY, f"{token!r} -> unknown registry {key!r}"
for prefix, key in _CONSUMER_PREFIX_TO_KEY.items():
assert key in _REGISTRY_BY_KEY, f"{prefix!r} -> unknown registry {key!r}"
def test_tokens_are_upper_case(self):
"""`_board_tokens` upper-cases before lookup, so a lower-case entry
would be dead."""
from custom_components.localthings.registry.by_type import _BOARD_TOKEN_TO_KEY
for token in _BOARD_TOKEN_TO_KEY:
assert token == token.upper()
class TestConsumerModelKey:
@@ -452,6 +489,70 @@ class TestForDeviceByModel:
from custom_components.localthings.registry.by_type import for_device_by_model
assert for_device_by_model('', '') is None
@pytest.mark.parametrize('model_num', [
'TP1X_DA-AC-RAC-01001_0000', # hyphenated (issue #91)
'TP1X_DA_AC_RAC_01001_0000', # underscored
'TP2X_RAC_20K', # bare, no board-family prefix (issue #37)
'TP2X-RAC-20K',
])
def test_delimiter_spelling_does_not_change_the_answer(self, model_num):
"""One board family, four spellings, one table entry."""
from custom_components.localthings.registry.by_type import for_device_by_model
reg = for_device_by_model(model_num, '')
assert reg is not None
assert reg.name == 'airconditioner'
def test_model_num_wins_when_the_two_fields_disagree(self):
"""The legacy gas cooktop is the one known device whose fields
conflict: modelNum says CT (gas), description says COOKTOP (which
otherwise means induction). The board is right, so modelNum is
consulted first."""
from custom_components.localthings.registry.by_type import for_device_by_model
reg = for_device_by_model('ARTIK051_GB_CT_001', 'ARTIK051_GLOBAL_COOKTOP')
assert reg is not None
assert reg.name == 'gas_cooktop'
def test_board_token_in_description_used_when_model_num_has_none(self):
"""Some units report a placeholder modelNum and carry the board token
only in `description`."""
from custom_components.localthings.registry.by_type import for_device_by_model
reg = for_device_by_model('TEST-MODEL', 'TP1X_REF_21K')
assert reg is not None
assert reg.name == 'refrigerator'
def test_board_token_beats_consumer_prefix(self):
"""'WAC' (window AC, issue #87) starts with 'WA' (top-load washer,
issue #106). The board table runs first, so the AC wins."""
from custom_components.localthings.registry.by_type import for_device_by_model
reg = for_device_by_model('TP1X_DA_AC_WAC_01001_0000', 'TP1X_DA_AC_WAC_01001_0000')
assert reg is not None
assert reg.name == 'airconditioner'
class TestBoardTokenAmbiguity:
"""`_board_family_key` returns the first matching token, which is only
safe while no real model string contains two tokens naming different
device types. Guard that against every dump we have."""
def test_no_fixture_model_string_yields_two_conflicting_keys(self, all_device_fixtures):
from custom_components.localthings.registry.by_type import (
_BOARD_TOKEN_TO_KEY, _board_tokens,
)
for name, resources in all_device_fixtures.items():
info = resources.get('/information/vs/0', {})
for field, cut in (
(info.get('x.com.samsung.da.modelNum', ''), '|'),
(info.get('x.com.samsung.da.description', ''), '/'),
):
keys = {
_BOARD_TOKEN_TO_KEY[t]
for t in _board_tokens(field, cut)
if t in _BOARD_TOKEN_TO_KEY
}
assert len(keys) <= 1, (
f"{name}: {field!r} matches conflicting board tokens {keys}"
)
class TestForDeviceByResources:
def test_na9300k_without_one_ui_or_information_is_cooktop(self):