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.
Files changed (57) hide show
  1. roschema/__init__.py +3 -0
  2. roschema/cli.py +457 -0
  3. roschema/config.py +263 -0
  4. roschema/deep.py +114 -0
  5. roschema/differ.py +296 -0
  6. roschema/discovery/__init__.py +28 -0
  7. roschema/discovery/discover.py +74 -0
  8. roschema/discovery/model.py +55 -0
  9. roschema/discovery/resolve.py +209 -0
  10. roschema/formatter.py +48 -0
  11. roschema/freeze.py +109 -0
  12. roschema/ir.py +180 -0
  13. roschema/loader.py +32 -0
  14. roschema/mcap_fs.py +246 -0
  15. roschema/parser/__init__.py +36 -0
  16. roschema/parser/core.py +361 -0
  17. roschema/parser/errors.py +41 -0
  18. roschema/report/__init__.py +17 -0
  19. roschema/report/github.py +30 -0
  20. roschema/report/json_report.py +46 -0
  21. roschema/report/summary.py +64 -0
  22. roschema/report/text.py +106 -0
  23. roschema/rules/__init__.py +30 -0
  24. roschema/rules/breaking/__init__.py +44 -0
  25. roschema/rules/breaking/rs001_field_removed.py +27 -0
  26. roschema/rules/breaking/rs002_field_added.py +27 -0
  27. roschema/rules/breaking/rs003_field_type_changed.py +32 -0
  28. roschema/rules/breaking/rs004_fields_reordered.py +28 -0
  29. roschema/rules/breaking/rs005_field_renamed.py +28 -0
  30. roschema/rules/breaking/rs006_array_kind_changed.py +32 -0
  31. roschema/rules/breaking/rs007_bound_tightened.py +32 -0
  32. roschema/rules/breaking/rs008_bound_loosened.py +32 -0
  33. roschema/rules/breaking/rs020_constant_removed.py +24 -0
  34. roschema/rules/breaking/rs021_constant_value_changed.py +32 -0
  35. roschema/rules/breaking/rs022_constant_type_changed.py +29 -0
  36. roschema/rules/breaking/rs030_default_changed.py +38 -0
  37. roschema/rules/breaking/rs040_interface_removed.py +24 -0
  38. roschema/rules/breaking/rs060_message_version.py +39 -0
  39. roschema/rules/breaking/rs110_transitive.py +36 -0
  40. roschema/rules/gendocs.py +98 -0
  41. roschema/rules/lint/__init__.py +22 -0
  42. roschema/rules/lint/_common.py +34 -0
  43. roschema/rules/lint/rsl001_field_snake_case.py +36 -0
  44. roschema/rules/lint/rsl002_constant_upper_snake.py +33 -0
  45. roschema/rules/lint/rsl003_name_pascal_case.py +30 -0
  46. roschema/rules/lint/rsl004_missing_doc.py +35 -0
  47. roschema/rules/lint/rsl005_discouraged_types.py +42 -0
  48. roschema/rules/lint/rsl006_unbounded.py +43 -0
  49. roschema/rules/lint/rsl010_srv_shadow.py +43 -0
  50. roschema/rules/model.py +161 -0
  51. roschema/rules/registry.py +98 -0
  52. roschema/vfs.py +187 -0
  53. roschema-0.1.0.dist-info/METADATA +270 -0
  54. roschema-0.1.0.dist-info/RECORD +57 -0
  55. roschema-0.1.0.dist-info/WHEEL +4 -0
  56. roschema-0.1.0.dist-info/entry_points.txt +2 -0
  57. 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
+ ]