Skip to content

Commit 437a4f4

Browse files
authored
Merge pull request #236 from ExpressLRS/add-targets-validator
Add validator for hardware/targets.json and run it before builds
2 parents 1f25dcd + 6bbbbfb commit 437a4f4

2 files changed

Lines changed: 196 additions & 0 deletions

File tree

‎.github/targets_validator.py‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
import sys
2+
import json
3+
import glob
4+
import argparse
5+
import configparser
6+
import re
7+
from dataclasses import dataclass
8+
9+
DEVICE_TYPES = ['txbp', 'vrx', 'timer', 'aat']
10+
PLATFORMS = ['esp8285', 'esp32', 'esp32-c3', 'esp32-s3']
11+
UPLOAD_METHODS = ['uart', 'etx', 'passthru', 'wifi']
12+
DEVICE_KEYS = ['product_name', 'firmware', 'platform', 'upload_methods', 'validation_ignores']
13+
14+
# PlatformIO board -> targets.json "platform" value
15+
BOARD_PLATFORMS = {
16+
'esp8285': 'esp8285',
17+
'esp12e': 'esp8285',
18+
'esp32dev': 'esp32',
19+
'esp32-c3-devkitm-1': 'esp32-c3',
20+
'esp32-s3-devkitc-1': 'esp32-s3',
21+
}
22+
23+
24+
@dataclass
25+
class Finding:
26+
severity: str # 'error' or 'warning'
27+
target: str # 'vendor.type.device', or the offending vendor/environment
28+
code: str | None # ignorable via the device's "validation_ignores" when set
29+
message: str
30+
31+
32+
def load_environments():
33+
"""Parse targets/*.ini and return {env_name: platform} for every [env:...] section,
34+
resolving each env's platform through its 'extends' chain down to an
35+
env_common_* section with a 'board'."""
36+
ini = configparser.RawConfigParser(strict=False)
37+
for inifile in sorted(glob.glob('targets/*.ini')):
38+
ini.read(inifile)
39+
40+
def resolve_platform(section, seen=()):
41+
if section in seen or not ini.has_section(section):
42+
return None
43+
if ini.has_option(section, 'board'):
44+
return BOARD_PLATFORMS.get(ini.get(section, 'board'))
45+
if ini.has_option(section, 'extends'):
46+
for parent in re.split(r'[,\s]+', ini.get(section, 'extends')):
47+
platform = resolve_platform(parent, seen + (section,))
48+
if platform is not None:
49+
return platform
50+
return None
51+
52+
environments = {}
53+
for section in ini.sections():
54+
if section.startswith('env:'):
55+
environments[section[4:]] = resolve_platform(section)
56+
return environments
57+
58+
59+
class TargetsValidator:
60+
def __init__(self, targets, environments):
61+
self.targets = targets
62+
self.environments = environments
63+
self.findings = []
64+
self.ignores = {} # target -> that device's "validation_ignores" set
65+
66+
def error(self, target, message, code=None):
67+
self.findings.append(Finding('error', target, code, message))
68+
69+
def warn(self, target, message, code=None):
70+
self.findings.append(Finding('warning', target, code, message))
71+
72+
def validate(self):
73+
for vendor in self.targets:
74+
self.validate_vendor(vendor, self.targets[vendor])
75+
self.validate_unreferenced_environments()
76+
return self.findings
77+
78+
def validate_vendor(self, vendor, types):
79+
if not re.match(r'^[a-z0-9_-]+$', vendor):
80+
self.error(vendor, f'vendor tag "{vendor}" can only include lowercase a-z, 0-9, and underscores and dashes')
81+
82+
if 'name' not in types or not isinstance(types['name'], str) or not types['name']:
83+
self.error(vendor, f'vendor "{vendor}" must have a non-empty "name" child element')
84+
85+
if not any(type in DEVICE_TYPES for type in types):
86+
self.error(vendor, f'vendor "{vendor}" must have at least one device type, one of {DEVICE_TYPES}')
87+
88+
for type in types:
89+
if type not in DEVICE_TYPES + ['name']:
90+
self.error(vendor, f'invalid tag "{type}" in "{vendor}"')
91+
if type in DEVICE_TYPES:
92+
for device in types[type]:
93+
self.validate_device(vendor, type, device, types[type][device])
94+
95+
def validate_device(self, vendor, type, devname, device):
96+
target = f'{vendor}.{type}.{devname}'
97+
self.ignores[target] = set(device.get('validation_ignores', []))
98+
99+
if not re.match(r'^[A-Za-z0-9_-]+$', devname):
100+
self.error(target, f'device tag "{devname}" can only include a-z, A-Z, 0-9, and underscores and dashes', 'invalid_device_tag')
101+
102+
for key in device:
103+
if key not in DEVICE_KEYS:
104+
self.error(target, f'device "{target}" has an unknown child element "{key}"', 'unknown_device_key')
105+
106+
if 'product_name' not in device or not isinstance(device['product_name'], str) or not device['product_name']:
107+
self.error(target, f'device "{target}" must have a non-empty "product_name" child element', 'missing_product_name')
108+
109+
if 'upload_methods' not in device or not isinstance(device['upload_methods'], list) or not device['upload_methods']:
110+
self.error(target, f'device "{target}" must have a non-empty "upload_methods" list', 'missing_upload_methods')
111+
else:
112+
methods = device['upload_methods']
113+
for method in methods:
114+
if method not in UPLOAD_METHODS:
115+
self.error(target, f'invalid upload method "{method}" for target "{target}", must be one of {UPLOAD_METHODS}', 'invalid_upload_method')
116+
if len(set(methods)) != len(methods):
117+
self.error(target, f'duplicate upload methods for target "{target}"', 'duplicate_upload_method')
118+
119+
platform = device.get('platform')
120+
if platform not in PLATFORMS:
121+
self.error(target, f'device "{target}" must have a "platform" child element, one of {PLATFORMS}', 'invalid_platform')
122+
platform = None
123+
124+
if 'firmware' not in device or not isinstance(device['firmware'], str):
125+
self.error(target, f'device "{target}" must have a "firmware" child element', 'missing_firmware')
126+
else:
127+
firmware = device['firmware']
128+
env_platform = self.environments.get(firmware + '_via_UART')
129+
if firmware + '_via_UART' not in self.environments:
130+
self.error(target, f'device "{target}" firmware "{firmware}" has no [env:{firmware}_via_UART] in targets/*.ini', 'invalid_firmware_file')
131+
elif env_platform is None:
132+
self.error(target, f'could not determine the platform of [env:{firmware}_via_UART] from targets/*.ini', 'unknown_env_platform')
133+
elif platform is not None and env_platform != platform:
134+
self.error(target, f'device "{target}" "firmware" and "platform" MUST match: firmware "{firmware}" is {env_platform}, not {platform}', 'firmware_platform_mismatch')
135+
136+
def validate_unreferenced_environments(self):
137+
firmwares = set()
138+
for vendor in self.targets:
139+
for type in self.targets[vendor]:
140+
if type in DEVICE_TYPES:
141+
for device in self.targets[vendor][type].values():
142+
if isinstance(device.get('firmware'), str):
143+
firmwares.add(device['firmware'])
144+
for env in sorted(self.environments):
145+
if not env.endswith('_via_UART'):
146+
continue
147+
firmware = env[:-len('_via_UART')]
148+
if firmware.startswith('DEBUG_'):
149+
continue
150+
if firmware not in firmwares:
151+
self.warn(env, f'[env:{env}] in targets/*.ini is not referenced by any target in hardware/targets.json')
152+
153+
def report(self, warn_as_error=False):
154+
had_error = False
155+
for finding in self.findings:
156+
if finding.code is not None and finding.code in self.ignores.get(finding.target, ()):
157+
continue
158+
print(f'{finding.severity.upper()}: {finding.message}')
159+
if finding.severity == 'error' or warn_as_error:
160+
had_error = True
161+
return 1 if had_error else 0
162+
163+
164+
def main():
165+
parser = argparse.ArgumentParser(description="Validate hardware/targets.json")
166+
parser.add_argument("--warn", "-w", action='store_true', default=False, help="Treat warnings as errors")
167+
args = parser.parse_args()
168+
169+
with open('hardware/targets.json') as f:
170+
try:
171+
targets = json.load(f)
172+
except json.JSONDecodeError as e:
173+
print(f'ERROR: hardware/targets.json is not valid JSON: {e}')
174+
return 1
175+
176+
environments = load_environments()
177+
if not environments:
178+
print('ERROR: no [env:...] sections found in targets/*.ini, run from the repository root')
179+
return 1
180+
181+
validator = TargetsValidator(targets, environments)
182+
validator.validate()
183+
return validator.report(warn_as_error=args.warn)
184+
185+
186+
if __name__ == '__main__':
187+
sys.exit(main())

‎.github/workflows/build.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,16 @@
11
name: Build ExpressLRS Backpack
22
on: [push, pull_request]
33
jobs:
4+
validate:
5+
runs-on: ubuntu-latest
6+
steps:
7+
- name: Checkout
8+
uses: actions/checkout@v7
9+
- name: Validate targets.json
10+
run: python3 .github/targets_validator.py
11+
412
targets:
13+
needs: validate
514
runs-on: ubuntu-latest
615
outputs:
716
targets: ${{ steps.set-targets.outputs.targets }}

0 commit comments

Comments
 (0)