roschema 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- roschema/__init__.py +3 -0
- roschema/cli.py +457 -0
- roschema/config.py +263 -0
- roschema/deep.py +114 -0
- roschema/differ.py +296 -0
- roschema/discovery/__init__.py +28 -0
- roschema/discovery/discover.py +74 -0
- roschema/discovery/model.py +55 -0
- roschema/discovery/resolve.py +209 -0
- roschema/formatter.py +48 -0
- roschema/freeze.py +109 -0
- roschema/ir.py +180 -0
- roschema/loader.py +32 -0
- roschema/mcap_fs.py +246 -0
- roschema/parser/__init__.py +36 -0
- roschema/parser/core.py +361 -0
- roschema/parser/errors.py +41 -0
- roschema/report/__init__.py +17 -0
- roschema/report/github.py +30 -0
- roschema/report/json_report.py +46 -0
- roschema/report/summary.py +64 -0
- roschema/report/text.py +106 -0
- roschema/rules/__init__.py +30 -0
- roschema/rules/breaking/__init__.py +44 -0
- roschema/rules/breaking/rs001_field_removed.py +27 -0
- roschema/rules/breaking/rs002_field_added.py +27 -0
- roschema/rules/breaking/rs003_field_type_changed.py +32 -0
- roschema/rules/breaking/rs004_fields_reordered.py +28 -0
- roschema/rules/breaking/rs005_field_renamed.py +28 -0
- roschema/rules/breaking/rs006_array_kind_changed.py +32 -0
- roschema/rules/breaking/rs007_bound_tightened.py +32 -0
- roschema/rules/breaking/rs008_bound_loosened.py +32 -0
- roschema/rules/breaking/rs020_constant_removed.py +24 -0
- roschema/rules/breaking/rs021_constant_value_changed.py +32 -0
- roschema/rules/breaking/rs022_constant_type_changed.py +29 -0
- roschema/rules/breaking/rs030_default_changed.py +38 -0
- roschema/rules/breaking/rs040_interface_removed.py +24 -0
- roschema/rules/breaking/rs060_message_version.py +39 -0
- roschema/rules/breaking/rs110_transitive.py +36 -0
- roschema/rules/gendocs.py +98 -0
- roschema/rules/lint/__init__.py +22 -0
- roschema/rules/lint/_common.py +34 -0
- roschema/rules/lint/rsl001_field_snake_case.py +36 -0
- roschema/rules/lint/rsl002_constant_upper_snake.py +33 -0
- roschema/rules/lint/rsl003_name_pascal_case.py +30 -0
- roschema/rules/lint/rsl004_missing_doc.py +35 -0
- roschema/rules/lint/rsl005_discouraged_types.py +42 -0
- roschema/rules/lint/rsl006_unbounded.py +43 -0
- roschema/rules/lint/rsl010_srv_shadow.py +43 -0
- roschema/rules/model.py +161 -0
- roschema/rules/registry.py +98 -0
- roschema/vfs.py +187 -0
- roschema-0.1.0.dist-info/METADATA +270 -0
- roschema-0.1.0.dist-info/RECORD +57 -0
- roschema-0.1.0.dist-info/WHEEL +4 -0
- roschema-0.1.0.dist-info/entry_points.txt +2 -0
- roschema-0.1.0.dist-info/licenses/LICENSE +201 -0
roschema/config.py
ADDED
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
"""Configuration: discovery, parsing, and application to findings.
|
|
2
|
+
|
|
3
|
+
Precedence is CLI flags > per-package ``roschema.toml`` > workspace config
|
|
4
|
+
(``roschema.toml`` or ``[tool.roschema]`` in ``pyproject.toml``) > defaults.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import sys
|
|
10
|
+
from dataclasses import dataclass, field, replace
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
from typing import cast
|
|
13
|
+
|
|
14
|
+
from .discovery import DiscoveredPackage
|
|
15
|
+
from .rules import Finding
|
|
16
|
+
|
|
17
|
+
if sys.version_info >= (3, 11):
|
|
18
|
+
import tomllib
|
|
19
|
+
else: # pragma: no cover - exercised only on py3.10
|
|
20
|
+
import tomli as tomllib
|
|
21
|
+
|
|
22
|
+
# Cumulative level bundles: selecting a level reports it and everything more
|
|
23
|
+
# wire-significant than it.
|
|
24
|
+
LEVEL_BUNDLES: dict[str, frozenset[str]] = {
|
|
25
|
+
"wire": frozenset({"wire"}),
|
|
26
|
+
"source": frozenset({"wire", "source"}),
|
|
27
|
+
"introspection": frozenset({"wire", "source", "introspection"}),
|
|
28
|
+
"behavior": frozenset({"wire", "source", "introspection", "behavior"}),
|
|
29
|
+
}
|
|
30
|
+
DEFAULT_LEVEL = "source"
|
|
31
|
+
_SEVERITIES = frozenset({"off", "warn", "error"})
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class ConfigError(Exception):
|
|
35
|
+
"""Raised on an invalid configuration (exit code 2)."""
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass(frozen=True)
|
|
39
|
+
class AllowEntry:
|
|
40
|
+
"""An intentional-break allowance for a fully-qualified target."""
|
|
41
|
+
|
|
42
|
+
target: str
|
|
43
|
+
rules: tuple[str, ...]
|
|
44
|
+
reason: str
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
@dataclass(frozen=True)
|
|
48
|
+
class ScopeConfig:
|
|
49
|
+
"""A ``[check]`` scope, at workspace or package level."""
|
|
50
|
+
|
|
51
|
+
level: str | None = None
|
|
52
|
+
deep: bool | None = None
|
|
53
|
+
rules: dict[str, str] = field(default_factory=dict)
|
|
54
|
+
allow: tuple[AllowEntry, ...] = ()
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@dataclass(frozen=True)
|
|
58
|
+
class Config:
|
|
59
|
+
"""Merged configuration for a check run."""
|
|
60
|
+
|
|
61
|
+
workspace: ScopeConfig = field(default_factory=ScopeConfig)
|
|
62
|
+
packages: dict[str, ScopeConfig] = field(default_factory=dict)
|
|
63
|
+
lint_rules: dict[str, str] = field(default_factory=dict)
|
|
64
|
+
|
|
65
|
+
def effective_severity(self, rule_id: str, package: str, default: str) -> str:
|
|
66
|
+
"""Severity for a rule in a package: package > workspace > default."""
|
|
67
|
+
pkg_cfg = self.packages.get(package)
|
|
68
|
+
if pkg_cfg is not None and rule_id in pkg_cfg.rules:
|
|
69
|
+
return pkg_cfg.rules[rule_id]
|
|
70
|
+
if rule_id in self.workspace.rules:
|
|
71
|
+
return self.workspace.rules[rule_id]
|
|
72
|
+
return default
|
|
73
|
+
|
|
74
|
+
def is_explicitly_set(self, rule_id: str, package: str) -> bool:
|
|
75
|
+
"""Whether a rule's severity was set in config (bypasses level presets)."""
|
|
76
|
+
pkg_cfg = self.packages.get(package)
|
|
77
|
+
if pkg_cfg is not None and rule_id in pkg_cfg.rules:
|
|
78
|
+
return True
|
|
79
|
+
return rule_id in self.workspace.rules
|
|
80
|
+
|
|
81
|
+
def effective_level(self, package: str, cli_level: str | None) -> str:
|
|
82
|
+
"""Reporting level: CLI > package > workspace > default."""
|
|
83
|
+
if cli_level:
|
|
84
|
+
return cli_level
|
|
85
|
+
pkg_cfg = self.packages.get(package)
|
|
86
|
+
if pkg_cfg is not None and pkg_cfg.level:
|
|
87
|
+
return pkg_cfg.level
|
|
88
|
+
if self.workspace.level:
|
|
89
|
+
return self.workspace.level
|
|
90
|
+
return DEFAULT_LEVEL
|
|
91
|
+
|
|
92
|
+
def is_allowed(self, finding: Finding) -> bool:
|
|
93
|
+
"""Whether an allowlist entry covers this finding."""
|
|
94
|
+
entries = list(self.workspace.allow)
|
|
95
|
+
pkg_cfg = self.packages.get(finding.package)
|
|
96
|
+
if pkg_cfg is not None:
|
|
97
|
+
entries += list(pkg_cfg.allow)
|
|
98
|
+
for entry in entries:
|
|
99
|
+
if entry.target != finding.qualified_target:
|
|
100
|
+
continue
|
|
101
|
+
if not entry.rules or finding.rule in entry.rules:
|
|
102
|
+
return True
|
|
103
|
+
return False
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def finalize_findings(
|
|
107
|
+
findings: list[Finding], config: Config, cli_level: str | None
|
|
108
|
+
) -> list[Finding]:
|
|
109
|
+
"""Apply config to raw findings.
|
|
110
|
+
|
|
111
|
+
Drops rules turned ``off`` and findings outside the selected level, adjusts
|
|
112
|
+
severities, and flags inline-suppressed / allowlisted findings (kept in the
|
|
113
|
+
list with ``suppressed=True`` so they can still be counted and emitted).
|
|
114
|
+
"""
|
|
115
|
+
out: list[Finding] = []
|
|
116
|
+
for finding in findings:
|
|
117
|
+
pkg = finding.package
|
|
118
|
+
severity = config.effective_severity(finding.rule, pkg, finding.severity)
|
|
119
|
+
if severity == "off":
|
|
120
|
+
continue
|
|
121
|
+
finding = replace(finding, severity=severity)
|
|
122
|
+
# A rule whose severity is set explicitly in config bypasses the level
|
|
123
|
+
# preset (an opt-in rule like RS060 is reported once enabled).
|
|
124
|
+
if not config.is_explicitly_set(finding.rule, pkg):
|
|
125
|
+
bundle = LEVEL_BUNDLES[config.effective_level(pkg, cli_level)]
|
|
126
|
+
if not (set(finding.levels) & bundle):
|
|
127
|
+
continue
|
|
128
|
+
if finding.rule in finding.inline_ignores or config.is_allowed(finding):
|
|
129
|
+
finding = replace(finding, suppressed=True)
|
|
130
|
+
out.append(finding)
|
|
131
|
+
return out
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def finalize_lint(findings: list[Finding], config: Config) -> list[Finding]:
|
|
135
|
+
"""Apply ``[lint.rules]`` severities and inline suppression to lint findings.
|
|
136
|
+
|
|
137
|
+
Lint has no baseline, so there is no level filter or allowlist; only severity
|
|
138
|
+
overrides (including ``off``) and inline ``# roschema: ignore=`` apply.
|
|
139
|
+
"""
|
|
140
|
+
out: list[Finding] = []
|
|
141
|
+
for finding in findings:
|
|
142
|
+
severity = config.lint_rules.get(finding.rule, finding.severity)
|
|
143
|
+
if severity == "off":
|
|
144
|
+
continue
|
|
145
|
+
finding = replace(finding, severity=severity)
|
|
146
|
+
if finding.rule in finding.inline_ignores:
|
|
147
|
+
finding = replace(finding, suppressed=True)
|
|
148
|
+
out.append(finding)
|
|
149
|
+
return out
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def load_config(
|
|
153
|
+
root: Path,
|
|
154
|
+
packages: tuple[DiscoveredPackage, ...],
|
|
155
|
+
config_path: Path | None = None,
|
|
156
|
+
) -> Config:
|
|
157
|
+
"""Discover and parse workspace and per-package configuration.
|
|
158
|
+
|
|
159
|
+
Args:
|
|
160
|
+
root: Workspace/target root directory.
|
|
161
|
+
packages: Discovered packages (to locate per-package configs).
|
|
162
|
+
config_path: Explicit workspace config file overriding discovery.
|
|
163
|
+
|
|
164
|
+
Raises:
|
|
165
|
+
ConfigError: On malformed config or an allow entry missing a reason.
|
|
166
|
+
"""
|
|
167
|
+
workspace_scope, lint_rules = _load_workspace(root, config_path)
|
|
168
|
+
package_configs: dict[str, ScopeConfig] = {}
|
|
169
|
+
for pkg in packages:
|
|
170
|
+
if not pkg.path:
|
|
171
|
+
continue
|
|
172
|
+
pkg_toml = root / pkg.path / "roschema.toml"
|
|
173
|
+
if pkg_toml.is_file():
|
|
174
|
+
package_configs[pkg.name] = _parse_scope(_read_toml(pkg_toml))
|
|
175
|
+
return Config(
|
|
176
|
+
workspace=workspace_scope, packages=package_configs, lint_rules=lint_rules
|
|
177
|
+
)
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def _load_workspace(
|
|
181
|
+
root: Path, config_path: Path | None
|
|
182
|
+
) -> tuple[ScopeConfig, dict[str, str]]:
|
|
183
|
+
if config_path is not None:
|
|
184
|
+
if not config_path.is_file():
|
|
185
|
+
raise ConfigError(f"config file not found: {config_path}")
|
|
186
|
+
data = _read_toml(config_path)
|
|
187
|
+
if config_path.name == "pyproject.toml":
|
|
188
|
+
data = _as_dict(_as_dict(data.get("tool")).get("roschema"))
|
|
189
|
+
return _parse_loaded(data)
|
|
190
|
+
|
|
191
|
+
roschema_toml = root / "roschema.toml"
|
|
192
|
+
if roschema_toml.is_file():
|
|
193
|
+
return _parse_loaded(_read_toml(roschema_toml))
|
|
194
|
+
|
|
195
|
+
pyproject = root / "pyproject.toml"
|
|
196
|
+
if pyproject.is_file():
|
|
197
|
+
data = _as_dict(_as_dict(_read_toml(pyproject).get("tool")).get("roschema"))
|
|
198
|
+
if data:
|
|
199
|
+
return _parse_loaded(data)
|
|
200
|
+
|
|
201
|
+
return ScopeConfig(), {}
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def _read_toml(path: Path) -> dict[str, object]:
|
|
205
|
+
try:
|
|
206
|
+
with path.open("rb") as handle:
|
|
207
|
+
return cast("dict[str, object]", tomllib.load(handle))
|
|
208
|
+
except (OSError, tomllib.TOMLDecodeError) as exc:
|
|
209
|
+
raise ConfigError(f"could not read {path}: {exc}") from exc
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
def _parse_loaded(data: dict[str, object]) -> tuple[ScopeConfig, dict[str, str]]:
|
|
213
|
+
scope = _parse_scope(data)
|
|
214
|
+
lint = _as_dict(data.get("lint"))
|
|
215
|
+
lint_rules = _parse_rules(_as_dict(lint.get("rules")), where="[lint.rules]")
|
|
216
|
+
return scope, lint_rules
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def _parse_scope(data: dict[str, object]) -> ScopeConfig:
|
|
220
|
+
check = _as_dict(data.get("check"))
|
|
221
|
+
level = check.get("level")
|
|
222
|
+
if level is not None and level not in LEVEL_BUNDLES:
|
|
223
|
+
raise ConfigError(
|
|
224
|
+
f"invalid level {level!r}; expected one of {sorted(LEVEL_BUNDLES)}"
|
|
225
|
+
)
|
|
226
|
+
deep = check.get("deep")
|
|
227
|
+
return ScopeConfig(
|
|
228
|
+
level=level if isinstance(level, str) else None,
|
|
229
|
+
deep=deep if isinstance(deep, bool) else None,
|
|
230
|
+
rules=_parse_rules(_as_dict(check.get("rules")), where="[check.rules]"),
|
|
231
|
+
allow=_parse_allow(_as_dict(check.get("allow"))),
|
|
232
|
+
)
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def _parse_rules(raw: dict[str, object], where: str) -> dict[str, str]:
|
|
236
|
+
rules: dict[str, str] = {}
|
|
237
|
+
for rule_id, severity in raw.items():
|
|
238
|
+
if severity not in _SEVERITIES:
|
|
239
|
+
raise ConfigError(
|
|
240
|
+
f"{where}: {rule_id} has invalid severity {severity!r}; "
|
|
241
|
+
f"expected off, warn or error"
|
|
242
|
+
)
|
|
243
|
+
rules[rule_id] = str(severity)
|
|
244
|
+
return rules
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
def _parse_allow(raw: dict[str, object]) -> tuple[AllowEntry, ...]:
|
|
248
|
+
entries: list[AllowEntry] = []
|
|
249
|
+
for target, spec in raw.items():
|
|
250
|
+
spec_dict = _as_dict(spec)
|
|
251
|
+
reason = spec_dict.get("reason")
|
|
252
|
+
if not isinstance(reason, str) or not reason.strip():
|
|
253
|
+
raise ConfigError(
|
|
254
|
+
f"allowlist entry {target!r} must include a non-empty 'reason'"
|
|
255
|
+
)
|
|
256
|
+
raw_rules = spec_dict.get("rules", [])
|
|
257
|
+
rules = tuple(str(r) for r in raw_rules) if isinstance(raw_rules, list) else ()
|
|
258
|
+
entries.append(AllowEntry(target=target, rules=rules, reason=reason))
|
|
259
|
+
return tuple(entries)
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
def _as_dict(value: object) -> dict[str, object]:
|
|
263
|
+
return value if isinstance(value, dict) else {}
|
roschema/deep.py
ADDED
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
"""Deep (transitive) breakage detection for `check --deep` (RS110).
|
|
2
|
+
|
|
3
|
+
Shallow checking compares nested complex types by name only. Deep checking
|
|
4
|
+
resolves the type-dependency graph through the workspace and ament index, then
|
|
5
|
+
flags any interface that embeds -- directly or transitively -- a type whose wire
|
|
6
|
+
layout changed, even when the embedding interface's own text is unchanged.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from collections import deque
|
|
12
|
+
|
|
13
|
+
from .discovery import resolve_ament
|
|
14
|
+
from .ir import InterfaceFile
|
|
15
|
+
from .loader import load_interfaces
|
|
16
|
+
from .rules import Finding
|
|
17
|
+
from .rules.breaking.rs110_transitive import RULE as RS110
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def transitive_findings(
|
|
21
|
+
new_ifaces: dict[str, InterfaceFile], direct: list[Finding]
|
|
22
|
+
) -> list[Finding]:
|
|
23
|
+
"""Return RS110 findings for interfaces broken via a changed embedded type.
|
|
24
|
+
|
|
25
|
+
Args:
|
|
26
|
+
new_ifaces: Current interfaces (the target set).
|
|
27
|
+
direct: Findings from the ordinary diff; interfaces with a wire-level
|
|
28
|
+
finding are the roots of transitive breakage.
|
|
29
|
+
"""
|
|
30
|
+
changed = {f.interface for f in direct if "wire" in f.levels}
|
|
31
|
+
if not changed:
|
|
32
|
+
return []
|
|
33
|
+
|
|
34
|
+
graph = dict(new_ifaces)
|
|
35
|
+
_augment_dependencies(graph)
|
|
36
|
+
edges = {key: _referenced_keys(iface) for key, iface in graph.items()}
|
|
37
|
+
|
|
38
|
+
findings: list[Finding] = []
|
|
39
|
+
for key in sorted(new_ifaces):
|
|
40
|
+
chain = _first_changed_dependency(key, edges, changed)
|
|
41
|
+
if chain is None:
|
|
42
|
+
continue
|
|
43
|
+
iface = new_ifaces[key]
|
|
44
|
+
findings.append(
|
|
45
|
+
Finding(
|
|
46
|
+
rule=RS110.id,
|
|
47
|
+
severity=RS110.default_severity.value,
|
|
48
|
+
level=RS110.primary_level,
|
|
49
|
+
interface=key,
|
|
50
|
+
section=None,
|
|
51
|
+
target="",
|
|
52
|
+
message=f"transitively broken via {' -> '.join(chain)}",
|
|
53
|
+
old_file=None,
|
|
54
|
+
old_line=None,
|
|
55
|
+
new_file=iface.source_file,
|
|
56
|
+
new_line=None,
|
|
57
|
+
levels=RS110.levels,
|
|
58
|
+
)
|
|
59
|
+
)
|
|
60
|
+
return findings
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _referenced_keys(iface: InterfaceFile) -> set[str]:
|
|
64
|
+
"""Interface keys of every complex field type referenced by ``iface``."""
|
|
65
|
+
keys: set[str] = set()
|
|
66
|
+
for field in iface.fields():
|
|
67
|
+
if field.type.is_builtin:
|
|
68
|
+
continue
|
|
69
|
+
pkg = field.type.package or iface.package
|
|
70
|
+
keys.add(f"{pkg}/msg/{field.type.base}")
|
|
71
|
+
return keys
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _augment_dependencies(ifaces: dict[str, InterfaceFile]) -> None:
|
|
75
|
+
"""Resolve referenced-but-absent types from the ament index, transitively."""
|
|
76
|
+
while True:
|
|
77
|
+
needed = {
|
|
78
|
+
key
|
|
79
|
+
for iface in list(ifaces.values())
|
|
80
|
+
for key in _referenced_keys(iface)
|
|
81
|
+
if key not in ifaces
|
|
82
|
+
}
|
|
83
|
+
if not needed:
|
|
84
|
+
return
|
|
85
|
+
added = False
|
|
86
|
+
for package in sorted({key.split("/", 1)[0] for key in needed}):
|
|
87
|
+
res = resolve_ament(package)
|
|
88
|
+
if res is None:
|
|
89
|
+
continue
|
|
90
|
+
for key, iface in load_interfaces(res.vfs, res.packages).items():
|
|
91
|
+
if key not in ifaces:
|
|
92
|
+
ifaces[key] = iface
|
|
93
|
+
added = True
|
|
94
|
+
if not added:
|
|
95
|
+
return # remaining deps are unresolvable; stop
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def _first_changed_dependency(
|
|
99
|
+
start: str, edges: dict[str, set[str]], changed: set[str]
|
|
100
|
+
) -> list[str] | None:
|
|
101
|
+
"""Shortest dependency chain from ``start`` to a changed type, or ``None``."""
|
|
102
|
+
visited = {start}
|
|
103
|
+
queue: deque[list[str]] = deque([start, dep] for dep in edges.get(start, set()))
|
|
104
|
+
while queue:
|
|
105
|
+
path = queue.popleft()
|
|
106
|
+
node = path[-1]
|
|
107
|
+
if node in changed:
|
|
108
|
+
return path
|
|
109
|
+
if node in visited:
|
|
110
|
+
continue
|
|
111
|
+
visited.add(node)
|
|
112
|
+
for dep in edges.get(node, set()):
|
|
113
|
+
queue.append([*path, dep])
|
|
114
|
+
return None
|
roschema/differ.py
ADDED
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
"""Structural diff of parsed interfaces into typed change events.
|
|
2
|
+
|
|
3
|
+
Alignment is positional-aware because CDR serialisation is positional: fields
|
|
4
|
+
match by name within a section, renames are detected as a removed/added pair at
|
|
5
|
+
the same index with an identical type, and a changed relative order of common
|
|
6
|
+
fields is itself a (wire-breaking) event.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import math
|
|
12
|
+
from dataclasses import dataclass, field
|
|
13
|
+
from enum import Enum
|
|
14
|
+
|
|
15
|
+
from .ir import ArrayKind, Constant, Field, InterfaceFile, SectionKind
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class ChangeType(Enum):
|
|
19
|
+
"""The kinds of change the differ can report."""
|
|
20
|
+
|
|
21
|
+
INTERFACE_ADDED = "interface_added"
|
|
22
|
+
INTERFACE_REMOVED = "interface_removed"
|
|
23
|
+
FIELD_ADDED = "field_added"
|
|
24
|
+
FIELD_REMOVED = "field_removed"
|
|
25
|
+
FIELD_RENAMED = "field_renamed"
|
|
26
|
+
FIELD_TYPE_CHANGED = "field_type_changed"
|
|
27
|
+
FIELD_ARRAY_KIND_CHANGED = "field_array_kind_changed"
|
|
28
|
+
FIELD_BOUND_TIGHTENED = "field_bound_tightened"
|
|
29
|
+
FIELD_BOUND_LOOSENED = "field_bound_loosened"
|
|
30
|
+
FIELD_REORDERED = "field_reordered"
|
|
31
|
+
FIELD_DEFAULT_CHANGED = "field_default_changed"
|
|
32
|
+
CONSTANT_ADDED = "constant_added"
|
|
33
|
+
CONSTANT_REMOVED = "constant_removed"
|
|
34
|
+
CONSTANT_VALUE_CHANGED = "constant_value_changed"
|
|
35
|
+
CONSTANT_TYPE_CHANGED = "constant_type_changed"
|
|
36
|
+
MESSAGE_VERSION_NOT_BUMPED = "message_version_not_bumped"
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
# Field-level changes that count as a structural change for the MESSAGE_VERSION
|
|
40
|
+
# convention (RS060). Constant and default-only changes are not structural.
|
|
41
|
+
_STRUCTURAL = frozenset(
|
|
42
|
+
{
|
|
43
|
+
ChangeType.FIELD_ADDED,
|
|
44
|
+
ChangeType.FIELD_REMOVED,
|
|
45
|
+
ChangeType.FIELD_RENAMED,
|
|
46
|
+
ChangeType.FIELD_TYPE_CHANGED,
|
|
47
|
+
ChangeType.FIELD_ARRAY_KIND_CHANGED,
|
|
48
|
+
ChangeType.FIELD_BOUND_TIGHTENED,
|
|
49
|
+
ChangeType.FIELD_BOUND_LOOSENED,
|
|
50
|
+
ChangeType.FIELD_REORDERED,
|
|
51
|
+
}
|
|
52
|
+
)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@dataclass(frozen=True)
|
|
56
|
+
class ChangeEvent:
|
|
57
|
+
"""A single structural change between the old and new interface sets.
|
|
58
|
+
|
|
59
|
+
Args:
|
|
60
|
+
type: What changed.
|
|
61
|
+
interface: Interface key (``package/kind/name``) the change belongs to.
|
|
62
|
+
section: Section the change is in, or ``None`` for interface-level events.
|
|
63
|
+
target: Member name the change is about (``""`` for interface/section-level).
|
|
64
|
+
old: The old IR node (Field/Constant/InterfaceFile), if any.
|
|
65
|
+
new: The new IR node, if any.
|
|
66
|
+
detail: Extra structured context (e.g. reordering orders).
|
|
67
|
+
"""
|
|
68
|
+
|
|
69
|
+
type: ChangeType
|
|
70
|
+
interface: str
|
|
71
|
+
section: SectionKind | None
|
|
72
|
+
target: str
|
|
73
|
+
old: object | None = None
|
|
74
|
+
new: object | None = None
|
|
75
|
+
detail: dict[str, object] = field(default_factory=dict)
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def diff_interfaces(
|
|
79
|
+
old: dict[str, InterfaceFile], new: dict[str, InterfaceFile]
|
|
80
|
+
) -> list[ChangeEvent]:
|
|
81
|
+
"""Diff two interface sets keyed by ``package/kind/name``."""
|
|
82
|
+
events: list[ChangeEvent] = []
|
|
83
|
+
for key in sorted(set(old) | set(new)):
|
|
84
|
+
old_iface = old.get(key)
|
|
85
|
+
new_iface = new.get(key)
|
|
86
|
+
if old_iface is not None and new_iface is None:
|
|
87
|
+
events.append(
|
|
88
|
+
ChangeEvent(ChangeType.INTERFACE_REMOVED, key, None, "", old=old_iface)
|
|
89
|
+
)
|
|
90
|
+
elif new_iface is not None and old_iface is None:
|
|
91
|
+
events.append(
|
|
92
|
+
ChangeEvent(ChangeType.INTERFACE_ADDED, key, None, "", new=new_iface)
|
|
93
|
+
)
|
|
94
|
+
elif old_iface is not None and new_iface is not None:
|
|
95
|
+
_diff_interface(key, old_iface, new_iface, events)
|
|
96
|
+
return events
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def _diff_interface(
|
|
100
|
+
key: str, old: InterfaceFile, new: InterfaceFile, events: list[ChangeEvent]
|
|
101
|
+
) -> None:
|
|
102
|
+
local: list[ChangeEvent] = []
|
|
103
|
+
for sec_old, sec_new in zip(old.sections, new.sections, strict=False):
|
|
104
|
+
_diff_fields(key, sec_old.kind, sec_old.members, sec_new.members, local)
|
|
105
|
+
_diff_constants(key, sec_old.kind, sec_old.members, sec_new.members, local)
|
|
106
|
+
_check_message_version(key, old, new, local)
|
|
107
|
+
events.extend(local)
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def _check_message_version(
|
|
111
|
+
key: str, old: InterfaceFile, new: InterfaceFile, local: list[ChangeEvent]
|
|
112
|
+
) -> None:
|
|
113
|
+
"""Emit RS060's event when structure changed without a MESSAGE_VERSION bump.
|
|
114
|
+
|
|
115
|
+
Only applies when the old interface defines a ``MESSAGE_VERSION`` constant
|
|
116
|
+
(PX4 convention). The value is bumped iff the new one is strictly greater.
|
|
117
|
+
"""
|
|
118
|
+
old_const = _message_version(old)
|
|
119
|
+
if old_const is None:
|
|
120
|
+
return
|
|
121
|
+
if not any(e.type in _STRUCTURAL for e in local):
|
|
122
|
+
return
|
|
123
|
+
new_const = _message_version(new)
|
|
124
|
+
old_val = old_const.value
|
|
125
|
+
new_val = new_const.value if new_const is not None else None
|
|
126
|
+
if isinstance(old_val, int) and isinstance(new_val, int) and new_val > old_val:
|
|
127
|
+
return # bumped
|
|
128
|
+
local.append(
|
|
129
|
+
ChangeEvent(
|
|
130
|
+
ChangeType.MESSAGE_VERSION_NOT_BUMPED,
|
|
131
|
+
key,
|
|
132
|
+
None,
|
|
133
|
+
"MESSAGE_VERSION",
|
|
134
|
+
old=old_const,
|
|
135
|
+
new=new_const,
|
|
136
|
+
detail={"old_version": old_val, "new_version": new_val},
|
|
137
|
+
)
|
|
138
|
+
)
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def _message_version(iface: InterfaceFile) -> Constant | None:
|
|
142
|
+
for const in iface.constants():
|
|
143
|
+
if const.name == "MESSAGE_VERSION":
|
|
144
|
+
return const
|
|
145
|
+
return None
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def _diff_fields(
|
|
149
|
+
key: str,
|
|
150
|
+
section: SectionKind,
|
|
151
|
+
old_members: tuple[object, ...],
|
|
152
|
+
new_members: tuple[object, ...],
|
|
153
|
+
events: list[ChangeEvent],
|
|
154
|
+
) -> None:
|
|
155
|
+
old_fields = [m for m in old_members if isinstance(m, Field)]
|
|
156
|
+
new_fields = [m for m in new_members if isinstance(m, Field)]
|
|
157
|
+
old_by = {f.name: (i, f) for i, f in enumerate(old_fields)}
|
|
158
|
+
new_by = {f.name: (i, f) for i, f in enumerate(new_fields)}
|
|
159
|
+
removed = [n for n in old_by if n not in new_by]
|
|
160
|
+
added = [n for n in new_by if n not in old_by]
|
|
161
|
+
|
|
162
|
+
# Rename detection: removed + added at the same index with identical type.
|
|
163
|
+
for old_name in list(removed):
|
|
164
|
+
old_idx, old_field = old_by[old_name]
|
|
165
|
+
for new_name in list(added):
|
|
166
|
+
new_idx, new_field = new_by[new_name]
|
|
167
|
+
if new_idx == old_idx and old_field.type == new_field.type:
|
|
168
|
+
events.append(
|
|
169
|
+
ChangeEvent(
|
|
170
|
+
ChangeType.FIELD_RENAMED,
|
|
171
|
+
key,
|
|
172
|
+
section,
|
|
173
|
+
new_name,
|
|
174
|
+
old=old_field,
|
|
175
|
+
new=new_field,
|
|
176
|
+
detail={"old_name": old_name},
|
|
177
|
+
)
|
|
178
|
+
)
|
|
179
|
+
removed.remove(old_name)
|
|
180
|
+
added.remove(new_name)
|
|
181
|
+
break
|
|
182
|
+
|
|
183
|
+
for name in removed:
|
|
184
|
+
events.append(
|
|
185
|
+
ChangeEvent(ChangeType.FIELD_REMOVED, key, section, name, old=old_by[name][1])
|
|
186
|
+
)
|
|
187
|
+
for name in added:
|
|
188
|
+
events.append(
|
|
189
|
+
ChangeEvent(ChangeType.FIELD_ADDED, key, section, name, new=new_by[name][1])
|
|
190
|
+
)
|
|
191
|
+
|
|
192
|
+
for name in (n for n in old_by if n in new_by):
|
|
193
|
+
old_field = old_by[name][1]
|
|
194
|
+
new_field = new_by[name][1]
|
|
195
|
+
change = _classify_type_change(old_field, new_field)
|
|
196
|
+
if change is not None:
|
|
197
|
+
events.append(
|
|
198
|
+
ChangeEvent(change, key, section, name, old=old_field, new=new_field)
|
|
199
|
+
)
|
|
200
|
+
elif _default_changed(old_field, new_field):
|
|
201
|
+
events.append(
|
|
202
|
+
ChangeEvent(
|
|
203
|
+
ChangeType.FIELD_DEFAULT_CHANGED,
|
|
204
|
+
key,
|
|
205
|
+
section,
|
|
206
|
+
name,
|
|
207
|
+
old=old_field,
|
|
208
|
+
new=new_field,
|
|
209
|
+
)
|
|
210
|
+
)
|
|
211
|
+
|
|
212
|
+
old_order = [f.name for f in old_fields if f.name in new_by]
|
|
213
|
+
new_order = [f.name for f in new_fields if f.name in old_by]
|
|
214
|
+
if old_order != new_order and sorted(old_order) == sorted(new_order):
|
|
215
|
+
events.append(
|
|
216
|
+
ChangeEvent(
|
|
217
|
+
ChangeType.FIELD_REORDERED,
|
|
218
|
+
key,
|
|
219
|
+
section,
|
|
220
|
+
"",
|
|
221
|
+
detail={"old_order": old_order, "new_order": new_order},
|
|
222
|
+
)
|
|
223
|
+
)
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def _classify_type_change(old: Field, new: Field) -> ChangeType | None:
|
|
227
|
+
"""Return the single most significant type-related change, or ``None``."""
|
|
228
|
+
o, n = old.type, new.type
|
|
229
|
+
if o.base != n.base or o.package != n.package or o.is_builtin != n.is_builtin:
|
|
230
|
+
return ChangeType.FIELD_TYPE_CHANGED
|
|
231
|
+
if o.array_kind != n.array_kind:
|
|
232
|
+
return ChangeType.FIELD_ARRAY_KIND_CHANGED
|
|
233
|
+
# A fixed array's size is part of the wire layout: any change is a type change.
|
|
234
|
+
if o.array_kind is ArrayKind.FIXED and o.array_bound != n.array_bound:
|
|
235
|
+
return ChangeType.FIELD_TYPE_CHANGED
|
|
236
|
+
if o.array_kind is ArrayKind.BOUNDED and o.array_bound != n.array_bound:
|
|
237
|
+
return _bound_direction(o.array_bound, n.array_bound)
|
|
238
|
+
if o.string_bound != n.string_bound:
|
|
239
|
+
return _bound_direction(o.string_bound, n.string_bound)
|
|
240
|
+
return None
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
def _default_changed(old: Field, new: Field) -> bool:
|
|
244
|
+
"""Whether a field's default was added, removed or changed in value.
|
|
245
|
+
|
|
246
|
+
Compares parsed values, not raw text, so reformatting a default (e.g.
|
|
247
|
+
``[1,2]`` -> ``[1, 2]``) is never a finding.
|
|
248
|
+
"""
|
|
249
|
+
if (old.default is None) != (new.default is None):
|
|
250
|
+
return True
|
|
251
|
+
if old.default is None or new.default is None:
|
|
252
|
+
return False
|
|
253
|
+
return old.default.value != new.default.value
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
def _bound_direction(old_bound: int | None, new_bound: int | None) -> ChangeType:
|
|
257
|
+
"""Tightened when the capacity shrinks, loosened when it grows (None = inf)."""
|
|
258
|
+
old_cap = math.inf if old_bound is None else old_bound
|
|
259
|
+
new_cap = math.inf if new_bound is None else new_bound
|
|
260
|
+
if new_cap < old_cap:
|
|
261
|
+
return ChangeType.FIELD_BOUND_TIGHTENED
|
|
262
|
+
return ChangeType.FIELD_BOUND_LOOSENED
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
def _diff_constants(
|
|
266
|
+
key: str,
|
|
267
|
+
section: SectionKind,
|
|
268
|
+
old_members: tuple[object, ...],
|
|
269
|
+
new_members: tuple[object, ...],
|
|
270
|
+
events: list[ChangeEvent],
|
|
271
|
+
) -> None:
|
|
272
|
+
old_by = {c.name: c for c in old_members if isinstance(c, Constant)}
|
|
273
|
+
new_by = {c.name: c for c in new_members if isinstance(c, Constant)}
|
|
274
|
+
for name in (n for n in old_by if n not in new_by):
|
|
275
|
+
events.append(
|
|
276
|
+
ChangeEvent(ChangeType.CONSTANT_REMOVED, key, section, name, old=old_by[name])
|
|
277
|
+
)
|
|
278
|
+
for name in (n for n in new_by if n not in old_by):
|
|
279
|
+
events.append(
|
|
280
|
+
ChangeEvent(ChangeType.CONSTANT_ADDED, key, section, name, new=new_by[name])
|
|
281
|
+
)
|
|
282
|
+
for name in (n for n in old_by if n in new_by):
|
|
283
|
+
old_c = old_by[name]
|
|
284
|
+
new_c = new_by[name]
|
|
285
|
+
if old_c.type != new_c.type:
|
|
286
|
+
events.append(
|
|
287
|
+
ChangeEvent(
|
|
288
|
+
ChangeType.CONSTANT_TYPE_CHANGED, key, section, name, old=old_c, new=new_c
|
|
289
|
+
)
|
|
290
|
+
)
|
|
291
|
+
elif old_c.value != new_c.value:
|
|
292
|
+
events.append(
|
|
293
|
+
ChangeEvent(
|
|
294
|
+
ChangeType.CONSTANT_VALUE_CHANGED, key, section, name, old=old_c, new=new_c
|
|
295
|
+
)
|
|
296
|
+
)
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"""Discovery: resolve targets and enumerate interface packages via a VFS."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from .discover import discover, discover_named
|
|
6
|
+
from .model import DiscoveredPackage, InterfaceRef, Resolution
|
|
7
|
+
from .resolve import (
|
|
8
|
+
apply_exclude,
|
|
9
|
+
resolve_ament,
|
|
10
|
+
resolve_bag,
|
|
11
|
+
resolve_baseline,
|
|
12
|
+
resolve_lock,
|
|
13
|
+
resolve_target,
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
__all__ = [
|
|
17
|
+
"DiscoveredPackage",
|
|
18
|
+
"InterfaceRef",
|
|
19
|
+
"Resolution",
|
|
20
|
+
"apply_exclude",
|
|
21
|
+
"discover",
|
|
22
|
+
"discover_named",
|
|
23
|
+
"resolve_ament",
|
|
24
|
+
"resolve_bag",
|
|
25
|
+
"resolve_baseline",
|
|
26
|
+
"resolve_lock",
|
|
27
|
+
"resolve_target",
|
|
28
|
+
]
|