baglint 0.1.0__tar.gz

baglint-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.pytest_cache/

baglint-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Puja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

baglint-0.1.0/Makefile

@@ -0,0 +1,18 @@
+# ROS installs put /opt/ros/*/site-packages on PYTHONPATH, which leaks into the
+# venv and drags ROS's pytest plugins into our test run. baglint is deliberately
+# ROS-free, so every target runs with PYTHONPATH cleared.
+PY := .venv/bin/python
+RUN := env -u PYTHONPATH
+
+.PHONY: install test lint clean
+
+install:
+	python3 -m venv .venv
+	$(RUN) $(PY) -m pip install -q --upgrade pip
+	$(RUN) $(PY) -m pip install -q -e ".[dev]"
+
+test:
+	$(RUN) $(PY) -m pytest -q
+
+clean:
+	rm -rf .venv .pytest_cache **/__pycache__ *.egg-info

baglint-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: baglint
+Version: 0.1.0
+Summary: Validates the contents of MCAP recordings against a declarative specification
+Project-URL: Homepage, https://github.com/catplotlib/baglint
+Project-URL: Issues, https://github.com/catplotlib/baglint/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: linter,mcap,robotics,ros2,rosbag,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: mcap-ros2-support>=0.5
+Requires-Dist: mcap>=1.2
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# baglint
+
+Validates the contents of MCAP recordings against a declarative specification.
+Checks for missing topics, recording gaps and rate violations, and returns a
+non-zero exit status when a recording does not satisfy the specification.
+
+Validation of the MCAP container itself, such as chunk CRCs and index
+integrity, is out of scope. Use `mcap doctor` for that.
+
+## Requirements
+
+* Python 3.10 or later
+
+## Installation
+
+```console
+$ python3 -m venv .venv
+$ .venv/bin/pip install -e .
+```
+
+When ROS 2 is sourced, `/opt/ros/$ROS_DISTRO/lib/python3.*/site-packages` is on
+`PYTHONPATH` and is inherited by the virtual environment, which causes ROS
+pytest plugins to load during test runs. Clear it when invoking the tool:
+
+```console
+$ env -u PYTHONPATH .venv/bin/baglint --help
+```
+
+## Usage
+
+```console
+$ baglint BAG [-s SPEC] [-f {text,json}] [--strict]
+$ baglint BAG --init [--margin FRACTION]
+```
+
+| Option | Description |
+| --- | --- |
+| `-s`, `--spec` | Specification file to validate against |
+| `-f`, `--format` | Output format, `text` (default) or `json` |
+| `--strict` | Exit non-zero on `WARN` findings as well as `FAIL` |
+| `--init` | Print a specification generated from the recording instead of validating it |
+| `--margin` | With `--init`, the fraction below the observed rate at which to set `min_rate`. Default `0.1` |
+| `--version` | Print version and exit |
+
+Without `-s`, no checks run and nothing is validated.
+
+## Generating a specification
+
+`--init` writes a specification describing a recording, which is the practical
+way to produce a first one:
+
+```console
+$ baglint good_run.mcap --init > spec.yaml
+$ baglint experiment_042.mcap --spec spec.yaml
+```
+
+`min_rate` is set below each topic's observed mean rate by `--margin`, and
+`max_gap_ms` to twice the worst interval observed. Topics with fewer than ten
+messages are generated as presence-only, since a mean rate over so few samples
+describes the recording length rather than the publisher.
+
+The bounds describe the recording they came from, defects included. Generate
+from a run that is known to be good, and treat the result as a starting point.
+
+## Specification
+
+Topic keys accept glob patterns. The first matching entry applies, so list
+specific topics before wildcards.
+
+```yaml
+topics:
+  /joint_states:
+    min_rate: 490
+    max_gap_ms: 10
+
+  /camera/*:
+    min_rate: 25
+
+  /diagnostics:
+    required: false
+```
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `min_rate` | float | Minimum mean publication rate in Hz, measured over the topic's own span |
+| `max_gap_ms` | float | Maximum permitted interval between consecutive messages |
+| `required` | bool | Whether a topic named literally must be present. Default `true` |
+| `check_stamps` | bool | Validate `header.stamp` ordering. Default `false`, as it deserializes payloads |
+
+A `transforms.required` list of `[parent, child]` frame pairs is parsed and
+validated, but no check consumes it yet.
+
+## Output
+
+```console
+$ baglint experiment_042.mcap --spec examples/demo_spec.yaml
+experiment_042.mcap
+  3 topics · 680,884 messages · 18m32s
+
+FAIL /camera/image
+  rate 12.4 Hz below minimum 25 Hz  [log_time]
+
+FAIL /joint_states
+  3 missing interval(s) >10 ms (worst 122.0 ms at 904.00 s)  [log_time]
+
+FAIL /tf
+  required by spec but no messages in bag
+
+3 findings: 3 FAIL
+```
+
+To regenerate the recording used above:
+
+```console
+$ python examples/make_demo_bag.py experiment_042.mcap
+```
+
+`--format json` emits the same findings for machine consumption. Each carries a
+stable `code`, intended for filtering and baselining in CI:
+
+| Code | Level | Meaning |
+| --- | --- | --- |
+| `gap` | FAIL | Consecutive messages exceeded `max_gap_ms` |
+| `rate_below_min` | FAIL | Mean rate fell below `min_rate` |
+| `rate_unmeasurable` | FAIL | Fewer than two messages, so no rate can be computed |
+| `missing_topic` | FAIL | A required topic carried no messages |
+| `stamp_backwards` | FAIL | A `header.stamp` preceded the stamp before it |
+| `stamp_duplicate` | WARN | A message repeated the previous `header.stamp` |
+| `stamp_unset` | WARN | A message carried a zero `header.stamp` |
+| `stamp_unavailable` | WARN | `check_stamps` was set on a message type without a header |
+
+## Message timestamps
+
+Each message carries two timestamps, and findings state which one was used:
+
+| Timestamp | Set by | A defect indicates |
+| --- | --- | --- |
+| `log_time` | the recorder, on write | the recorder stalled: disk I/O, CPU starvation, a terminated node |
+| `header.stamp` | the publisher, at sample time | the sensor or its driver misbehaved |
+
+Gap and rate checks read `log_time`. Stamp checks read `header.stamp` and are
+enabled per topic with `check_stamps`, which is off by default because it
+requires deserializing every message on that topic:
+
+```yaml
+topics:
+  /imu:
+    check_stamps: true
+```
+
+A stamp that moves backwards is reported as a failure. Downstream consumers
+such as tf2, `message_filters` and the SLAM backends assume a non-decreasing
+stamp sequence per topic, and do not report the violation themselves. Duplicate and zero stamps
+are reported as warnings.
+
+A zero stamp is treated as never populated rather than as a timestamp, so it
+does not become the baseline for the messages that follow it.
+
+## Exit codes
+
+| Code | Condition |
+| --- | --- |
+| 0 | No `FAIL` findings. With `--strict`, no `WARN` findings either |
+| 1 | At least one finding at or above the failing level |
+| 2 | Invalid arguments, unreadable recording, or malformed specification |
+
+## Development
+
+```console
+$ make install
+$ make test
+```
+
+Tests construct MCAP recordings with injected defects at known offsets. See
+`tests/fixtures.py`.

baglint-0.1.0/README.md

@@ -0,0 +1,175 @@
+# baglint
+
+Validates the contents of MCAP recordings against a declarative specification.
+Checks for missing topics, recording gaps and rate violations, and returns a
+non-zero exit status when a recording does not satisfy the specification.
+
+Validation of the MCAP container itself, such as chunk CRCs and index
+integrity, is out of scope. Use `mcap doctor` for that.
+
+## Requirements
+
+* Python 3.10 or later
+
+## Installation
+
+```console
+$ python3 -m venv .venv
+$ .venv/bin/pip install -e .
+```
+
+When ROS 2 is sourced, `/opt/ros/$ROS_DISTRO/lib/python3.*/site-packages` is on
+`PYTHONPATH` and is inherited by the virtual environment, which causes ROS
+pytest plugins to load during test runs. Clear it when invoking the tool:
+
+```console
+$ env -u PYTHONPATH .venv/bin/baglint --help
+```
+
+## Usage
+
+```console
+$ baglint BAG [-s SPEC] [-f {text,json}] [--strict]
+$ baglint BAG --init [--margin FRACTION]
+```
+
+| Option | Description |
+| --- | --- |
+| `-s`, `--spec` | Specification file to validate against |
+| `-f`, `--format` | Output format, `text` (default) or `json` |
+| `--strict` | Exit non-zero on `WARN` findings as well as `FAIL` |
+| `--init` | Print a specification generated from the recording instead of validating it |
+| `--margin` | With `--init`, the fraction below the observed rate at which to set `min_rate`. Default `0.1` |
+| `--version` | Print version and exit |
+
+Without `-s`, no checks run and nothing is validated.
+
+## Generating a specification
+
+`--init` writes a specification describing a recording, which is the practical
+way to produce a first one:
+
+```console
+$ baglint good_run.mcap --init > spec.yaml
+$ baglint experiment_042.mcap --spec spec.yaml
+```
+
+`min_rate` is set below each topic's observed mean rate by `--margin`, and
+`max_gap_ms` to twice the worst interval observed. Topics with fewer than ten
+messages are generated as presence-only, since a mean rate over so few samples
+describes the recording length rather than the publisher.
+
+The bounds describe the recording they came from, defects included. Generate
+from a run that is known to be good, and treat the result as a starting point.
+
+## Specification
+
+Topic keys accept glob patterns. The first matching entry applies, so list
+specific topics before wildcards.
+
+```yaml
+topics:
+  /joint_states:
+    min_rate: 490
+    max_gap_ms: 10
+
+  /camera/*:
+    min_rate: 25
+
+  /diagnostics:
+    required: false
+```
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `min_rate` | float | Minimum mean publication rate in Hz, measured over the topic's own span |
+| `max_gap_ms` | float | Maximum permitted interval between consecutive messages |
+| `required` | bool | Whether a topic named literally must be present. Default `true` |
+| `check_stamps` | bool | Validate `header.stamp` ordering. Default `false`, as it deserializes payloads |
+
+A `transforms.required` list of `[parent, child]` frame pairs is parsed and
+validated, but no check consumes it yet.
+
+## Output
+
+```console
+$ baglint experiment_042.mcap --spec examples/demo_spec.yaml
+experiment_042.mcap
+  3 topics · 680,884 messages · 18m32s
+
+FAIL /camera/image
+  rate 12.4 Hz below minimum 25 Hz  [log_time]
+
+FAIL /joint_states
+  3 missing interval(s) >10 ms (worst 122.0 ms at 904.00 s)  [log_time]
+
+FAIL /tf
+  required by spec but no messages in bag
+
+3 findings: 3 FAIL
+```
+
+To regenerate the recording used above:
+
+```console
+$ python examples/make_demo_bag.py experiment_042.mcap
+```
+
+`--format json` emits the same findings for machine consumption. Each carries a
+stable `code`, intended for filtering and baselining in CI:
+
+| Code | Level | Meaning |
+| --- | --- | --- |
+| `gap` | FAIL | Consecutive messages exceeded `max_gap_ms` |
+| `rate_below_min` | FAIL | Mean rate fell below `min_rate` |
+| `rate_unmeasurable` | FAIL | Fewer than two messages, so no rate can be computed |
+| `missing_topic` | FAIL | A required topic carried no messages |
+| `stamp_backwards` | FAIL | A `header.stamp` preceded the stamp before it |
+| `stamp_duplicate` | WARN | A message repeated the previous `header.stamp` |
+| `stamp_unset` | WARN | A message carried a zero `header.stamp` |
+| `stamp_unavailable` | WARN | `check_stamps` was set on a message type without a header |
+
+## Message timestamps
+
+Each message carries two timestamps, and findings state which one was used:
+
+| Timestamp | Set by | A defect indicates |
+| --- | --- | --- |
+| `log_time` | the recorder, on write | the recorder stalled: disk I/O, CPU starvation, a terminated node |
+| `header.stamp` | the publisher, at sample time | the sensor or its driver misbehaved |
+
+Gap and rate checks read `log_time`. Stamp checks read `header.stamp` and are
+enabled per topic with `check_stamps`, which is off by default because it
+requires deserializing every message on that topic:
+
+```yaml
+topics:
+  /imu:
+    check_stamps: true
+```
+
+A stamp that moves backwards is reported as a failure. Downstream consumers
+such as tf2, `message_filters` and the SLAM backends assume a non-decreasing
+stamp sequence per topic, and do not report the violation themselves. Duplicate and zero stamps
+are reported as warnings.
+
+A zero stamp is treated as never populated rather than as a timestamp, so it
+does not become the baseline for the messages that follow it.
+
+## Exit codes
+
+| Code | Condition |
+| --- | --- |
+| 0 | No `FAIL` findings. With `--strict`, no `WARN` findings either |
+| 1 | At least one finding at or above the failing level |
+| 2 | Invalid arguments, unreadable recording, or malformed specification |
+
+## Development
+
+```console
+$ make install
+$ make test
+```
+
+Tests construct MCAP recordings with injected defects at known offsets. See
+`tests/fixtures.py`.

baglint-0.1.0/examples/demo_spec.yaml

@@ -0,0 +1,14 @@
+# Spec used for the README's example output, against examples/make_demo_bag.py.
+topics:
+  /joint_states:
+    min_rate: 490      # tolerance below the nominal 500 Hz loop rate
+    max_gap_ms: 10
+
+  /camera/image:
+    min_rate: 25
+
+  /imu:
+    min_rate: 100
+
+  /tf:
+    min_rate: 10

baglint-0.1.0/examples/make_demo_bag.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Generate the demo bag used for the README's example output.
+
+The synthetic-bag helper lives in tests/ rather than in the package: it is a
+test utility, not shipped API, so this script puts it on the path explicitly.
+
+    python examples/make_demo_bag.py /tmp/experiment_042.mcap
+    baglint /tmp/experiment_042.mcap --spec examples/demo_spec.yaml
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "tests"))
+
+from fixtures import SynthBag  # noqa: E402
+
+
+def build(path: Path) -> Path:
+    bag = SynthBag(path, duration=1112.0)
+
+    # A 500 Hz control loop that stalls three times.
+    bag.topic("/joint_states", rate=500).gap(at=180.0, ms=52).gap(at=312.4, ms=38).gap(at=904.0, ms=120)
+
+    # A camera that never reaches its configured frame rate.
+    bag.topic("/camera/image", rate=12.4)
+
+    bag.topic("/imu", rate=100)
+
+    # /tf is absent entirely, which the spec requires.
+    return bag.write()
+
+
+if __name__ == "__main__":
+    out = Path(sys.argv[1] if len(sys.argv) > 1 else "experiment_042.mcap")
+    print(f"wrote {build(out)}")

baglint-0.1.0/examples/spec.yaml

@@ -0,0 +1,19 @@
+# Example baglint spec. Topic keys may be glob patterns; the first entry that
+# matches a topic wins, so list specific topics before wildcards.
+
+topics:
+  /joint_states:
+    min_rate: 500
+    max_gap_ms: 10
+
+  /camera/image:
+    min_rate: 25
+    max_gap_ms: 100
+
+  /imu:
+    min_rate: 100
+
+# Not yet implemented -- parsed and validated, but no check consumes it in v0.1.
+transforms:
+  required:
+    - [camera_link, base_link]

baglint-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "baglint"
+version = "0.1.0"
+description = "Validates the contents of MCAP recordings against a declarative specification"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["mcap", "rosbag", "ros2", "robotics", "validation", "linter"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "mcap>=1.2",
+    "mcap-ros2-support>=0.5",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/catplotlib/baglint"
+Issues = "https://github.com/catplotlib/baglint/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+baglint = "baglint.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/baglint"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

baglint-0.1.0/src/baglint/__init__.py

@@ -0,0 +1,7 @@
+__version__ = "0.1.0"
+
+from baglint.findings import Clock, Finding, Level
+from baglint.runner import run
+from baglint.spec import Spec
+
+__all__ = ["Clock", "Finding", "Level", "Spec", "run", "__version__"]

baglint-0.1.0/src/baglint/checks/__init__.py

@@ -0,0 +1,18 @@
+from baglint.checks.base import Check, RunContext, TopicStat
+from baglint.checks.gap import GapCheck
+from baglint.checks.presence import PresenceCheck
+from baglint.checks.rate import RateCheck
+from baglint.checks.stamp import StampCheck
+
+ALL_CHECKS = [PresenceCheck, GapCheck, RateCheck, StampCheck]
+
+__all__ = [
+    "Check",
+    "RunContext",
+    "TopicStat",
+    "GapCheck",
+    "PresenceCheck",
+    "RateCheck",
+    "StampCheck",
+    "ALL_CHECKS",
+]

baglint-0.1.0/src/baglint/checks/base.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable, Protocol
+
+from baglint.findings import Finding
+from baglint.reader import Message
+from baglint.spec import Spec
+
+
+@dataclass
+class TopicStat:
+    """Per-topic timing, accumulated by the runner for every topic in the bag."""
+
+    topic: str
+    count: int = 0
+    first_ns: int | None = None
+    last_ns: int | None = None
+    max_interval_ns: int = 0
+
+    def observe(self, log_time_ns: int) -> None:
+        if self.first_ns is None:
+            self.first_ns = log_time_ns
+        else:
+            self.max_interval_ns = max(self.max_interval_ns, log_time_ns - self.last_ns)
+        self.last_ns = log_time_ns
+        self.count += 1
+
+    @property
+    def max_interval_ms(self) -> float:
+        return self.max_interval_ns / 1e6
+
+    @property
+    def span_s(self) -> float:
+        if self.first_ns is None or self.last_ns is None:
+            return 0.0
+        return (self.last_ns - self.first_ns) / 1e9
+
+    @property
+    def rate_hz(self) -> float | None:
+        """Mean rate over the topic's own span.
+
+        Uses count-1 intervals rather than count messages: for N evenly spaced
+        messages there are N-1 gaps, and dividing by N biases the rate low on
+        short recordings.
+        """
+        if self.count < 2 or self.span_s <= 0:
+            return None
+        return (self.count - 1) / self.span_s
+
+
+@dataclass
+class RunContext:
+    spec: Spec
+    stats: dict[str, TopicStat] = field(default_factory=dict)
+    start_ns: int = 0
+    end_ns: int = 0
+
+    @property
+    def duration_s(self) -> float:
+        return max(0.0, (self.end_ns - self.start_ns) / 1e9)
+
+    def rel_s(self, ns: int) -> float:
+        """Seconds since the first message in the bag."""
+        return (ns - self.start_ns) / 1e9
+
+
+class Check(Protocol):
+    """A streaming accumulator.
+
+    Checks see every message once, in log_time order, then report at the end.
+    Payload deserialization is opt-in per check, via decode_topics().
+    """
+
+    def decode_topics(self, topics: Iterable[str]) -> set[str]:
+        """Topics whose payloads this check needs deserialized.
+
+        Resolved against the bag's actual channel list so spec globs can be
+        expanded. Return an empty set unless message fields are actually read.
+        """
+        ...
+
+    def on_message(self, msg: Message) -> None: ...
+
+    def finalize(self, ctx: RunContext) -> list[Finding]: ...