roschema 0.1.2__tar.gz → 0.2.0__tar.gz

{roschema-0.1.2 → roschema-0.2.0}/.github/workflows/ci.yml

@@ -22,7 +22,9 @@ jobs:
       - name: Install
         run: uv sync --extra dev --extra bag
       - name: Ruff
-        run: uv run ruff check .
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
       - name: Mypy
         run: uv run mypy --strict src
       - name: Rule docs in sync

{roschema-0.1.2 → roschema-0.2.0}/.github/workflows/release.yml

@@ -20,6 +20,7 @@ jobs:
         run: |
           uv run pytest -q
           uv run ruff check .
+          uv run ruff format --check .
           uv run mypy --strict src
           uv run python -m roschema.rules.gendocs --check
       - name: Tag matches package version

roschema-0.2.0/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/), and the
+project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-11-03
+
+### Added
+
+- `bag-check --level` and `--config`.
+- Git baselines read initialised submodules at their recorded commit, and warn
+  when that commit is not available locally.
+
+### Changed
+
+- `bag-check` reports at the `wire` level by default, since constant and other
+  source-level changes do not stop current code decoding a recording.
+- Package-name targets resolve to the workspace source package before the
+  installed copy, with a warning when the installed copy is used.
+- Adding or removing a sequence bound (`T[]` <-> `T[<=N]`) is reported as a
+  bound change (RS007/RS008) rather than an array-kind change (RS006).
+- RS110 takes the severity of the change it traces back to and ignores
+  suppressed, allowlisted or disabled changes.
+- Configuring a rule's severity no longer reports it outside the selected
+  level; only rules that are off by default (such as RS060) bypass the level.
+- The GitHub Action passes `--level` only when set, so configured levels apply.
+- RS002 is tagged `wire` only, and RSL005 explains why `char` and scalar `byte`
+  are ambiguous instead of calling them deprecated.
+
+### Fixed
+
+- `bag-check` skips schemas recorded without a definition and compares service
+  event schemas (`SRV:` blocks) instead of failing.
+- A same-package type written with its package (`pkg/Type` inside `pkg`) is no
+  longer reported as a type change.
+- Duplicate field or constant names are parse errors, as in rosidl.
+- Unknown configuration keys are configuration errors, with a suggestion.
+- `lint --format json` no longer includes semver advisories.
+- Text output no longer wraps long lines when not writing to a terminal.
+- Files are read and written as UTF-8 regardless of locale.
+- GitHub annotation text is escaped.
+- `wchar` in MCAP IDL schemas is rejected instead of narrowed to `char`.
+- The README's GitHub Action example references an existing ref (`@main`).
+
+## [0.1.3] - 2026-11-03
+
+### Added
+
+- `--version` / `-v` to display the installed package version.
+
+### Fixed
+
+- Pass GitHub Action inputs as literal arguments to prevent shell injection.
+- Report tightened bounds even when another bound on the same field increases.
+- Include deleted packages when checking glob targets against Git or directory
+  baselines, including globs with parent traversal; reject path globs for lockfile
+  and MCAP baselines.
+- Reject unsupported, conflicting or unusable MCAP schemas instead of silently
+  checking incomplete definitions, while preserving supported IDL string constants.
+- Accept equivalent NaN constants and defaults when comparing repeated MCAP schemas.
+- Replace each installed package's full interface set with its source target in
+  `bag-check`, so deleted source interfaces are reported as removed.
+- Honour workspace and package deep-check settings, with `--deep` / `--no-deep`
+  taking precedence.
+- Inherit enclosing workspace configuration when targeting a package directly,
+  and apply package lint overrides from `roschema.toml` or `pyproject.toml`.
+- Preserve root package settings in `bag-check` and after deleting its last interface.
+- Reject unknown or misplaced rule identifiers and invalid configuration values.
+- Detect unbounded string elements inside arrays and sequences with RSL006.
+
+## [0.1.2] - 2026-11-03
+
+### Fixed
+
+- Respect `COLCON_IGNORE` and `AMENT_IGNORE` during package discovery to avoid
+  reading generated build and install trees, including dangling package symlinks.
+
+## [0.1.1] - 2026-07-25
+
+Packaging and documentation release; no behavioural changes to the CLI.
+
+### Added
+
+- `py.typed` marker (PEP 561) so downstream type-checkers use roschema's types.
+- `Typing :: Typed` and Python 3.10-3.13 classifiers; `Repository` and `Issues`
+  project URLs.
+- README: installation section, common-usage recipes, a demo screenshot, and a
+  link to the [roschema-demo](https://github.com/justagist/roschema-demo) repo.
+
+### Changed
+
+- Dropped the redundant Apache license classifier in favour of the SPDX
+  `license` expression.
+
+### Fixed
+
+- Removed a broken demo image reference from the README.
+
+## [0.1.0] - 2026-07-24
+
+First release.
+
+### Added
+
+- `check`: breaking-change detection against a git ref, directory, MCAP bag or
+  lockfile baseline. Rules RS001-RS110 across the wire / source / introspection
+  / behaviour compatibility levels, with cumulative `--level` presets and
+  per-package semver bump advice.
+- `lint`: rosidl-aligned naming and style rules (RSL001-RSL010), with `--rules`
+  overrides.
+- `fmt`: canonical, idempotent formatting that never changes what `check`
+  reports; inline `# roschema: ignore=` suppressions survive formatting.
+- `bag-check`: check a recorded MCAP bag against the current environment
+  (ament index), with optional source targets overlaid.
+- `freeze`: lockfile baselines for non-git distribution; `--deep` reports
+  transitive breakage (RS110).
+- `ls`: discovery diagnostics.
+- Configuration via `roschema.toml` / `pyproject.toml`, inline suppression and
+  reasoned allowlists; text / JSON / GitHub output formats; a composite GitHub
+  Action.

{roschema-0.1.2 → roschema-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roschema
-Version: 0.1.2
+Version: 0.2.0
 Summary: Breaking-change detection, linting and formatting for ROS 2 interface definitions
 Project-URL: Homepage, https://github.com/justagist/roschema
 Project-URL: Documentation, https://github.com/justagist/roschema#readme
@@ -124,7 +124,9 @@ roschema check [TARGET] --against REF [--level LEVEL] [--format text|json|github
 `TARGET` is a path, a package name, or a glob (`'src/**'`) that expands to every
 package underneath; omit it for the current workspace. Discovery skips trees
 marked with `COLCON_IGNORE` or `AMENT_IGNORE`, including standard colcon build
-and install directories.
+and install directories. Glob targets include matching packages deleted from a Git
+or directory baseline. Lockfile and MCAP baselines have synthetic paths; use a
+workspace target with those baselines instead of a path glob.
 
 `--against` accepts a git ref (validated with `git rev-parse`), a directory, an
 MCAP bag (`.mcap`) or a lockfile (`roschema.lock`); the type is auto-detected. A
@@ -171,7 +173,7 @@ roschema fmt  [TARGET] [--check]
 
 `lint` checks a single tree (no baseline). Naming rules follow rosidl: field
 names snake_case (RSL001), constants UPPER_SNAKE (RSL002), interface names
-PascalCase (RSL003); it also flags deprecated `char`/scalar-`byte` (RSL005) and
+PascalCase (RSL003); it also flags ambiguous `char`/scalar-`byte` (RSL005) and
 request/response field shadowing in services (RSL010). RSL004 (missing doc) and
 RSL006 (unbounded) are off by default; enable via `[lint.rules]` or per run with
 `--rules` (e.g. `--rules RSL004=warn --rules RSL001=off`; a bare `--rules RSL004`
@@ -200,10 +202,19 @@ definitions rather than reported as missing.
 
 Optional `TARGETS` (paths or package names) are overlaid on top of the
 environment, so a package you are editing can be checked from source instead of
-its installed copy. A bag type found in neither the environment nor any target
+its installed copy. Each source package replaces its entire installed interface
+set, so deleted source interfaces are reported as removed even when an installed
+copy remains. If targets overlap, the last target wins for that package. A bag
+type found in neither the environment nor any target
 is reported as removed (RS040). `ros2msg` schemas (including concatenated
 dependent definitions) are fully supported; `ros2idl` is a best-effort
-conversion of the msg-equivalent subset.
+conversion of the msg-equivalent subset. Unsupported encodings or IDL constructs,
+conflicting definitions of the same type (including embedded dependencies), and
+bags without usable ROS schemas produce a tool error (exit `2`). Equivalent
+definitions that differ only in formatting or comments are accepted, including
+repeated NaN constants and defaults. IDL struct inheritance and constants outside
+structs (including generated `T_Constants` modules) are rejected because their
+conversion is incomplete.
 
 ## Compatibility levels
 
@@ -221,11 +232,17 @@ conversion of the msg-equivalent subset.
 
 `roschema.toml` at the workspace root, a per-package `roschema.toml`, or
 `[tool.roschema]` in `pyproject.toml`. Precedence: CLI > package > workspace >
-defaults.
+defaults. Workspace discovery searches upwards to the Git repository root, or
+the filesystem root outside Git. Package configurations override inherited
+workspace values even when checking the package directly by path. At each
+directory, `roschema.toml` takes precedence over `[tool.roschema]`. Unknown rule
+IDs, rule IDs in the wrong section, and invalid settings produce configuration
+errors (exit `2`).
 
 ```toml
 [check]
 level = "source"
+deep = false          # --deep / --no-deep overrides this
 
 [check.rules]
 RS008 = "off"          # off | warn | error
@@ -290,9 +307,10 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0            # needed for the git-ref baseline
-      - uses: justagist/roschema/action@v1
+      - uses: justagist/roschema/action@main
         with:
           against: origin/${{ github.base_ref }}
+          # version: "roschema==0.2.0"   # pin a release for reproducible results
           # level: source
           # deep: "true"
           # exclude: "vendor_msgs* legacy_msgs/msg/Old"
@@ -302,6 +320,10 @@ jobs:
 `roschema.lock`). A lockfile or directory baseline needs no `fetch-depth: 0`
 because it is a plain file in the checkout.
 
+By default the Action installs the latest roschema release, so new rules can
+change results without any change on your side. Uncomment `version` to pin a
+release instead.
+
 ## Rule reference
 
 Every rule, its levels, default severity and rationale is documented in

{roschema-0.1.2 → roschema-0.2.0}/README.md

@@ -90,7 +90,9 @@ roschema check [TARGET] --against REF [--level LEVEL] [--format text|json|github
 `TARGET` is a path, a package name, or a glob (`'src/**'`) that expands to every
 package underneath; omit it for the current workspace. Discovery skips trees
 marked with `COLCON_IGNORE` or `AMENT_IGNORE`, including standard colcon build
-and install directories.
+and install directories. Glob targets include matching packages deleted from a Git
+or directory baseline. Lockfile and MCAP baselines have synthetic paths; use a
+workspace target with those baselines instead of a path glob.
 
 `--against` accepts a git ref (validated with `git rev-parse`), a directory, an
 MCAP bag (`.mcap`) or a lockfile (`roschema.lock`); the type is auto-detected. A
@@ -137,7 +139,7 @@ roschema fmt  [TARGET] [--check]
 
 `lint` checks a single tree (no baseline). Naming rules follow rosidl: field
 names snake_case (RSL001), constants UPPER_SNAKE (RSL002), interface names
-PascalCase (RSL003); it also flags deprecated `char`/scalar-`byte` (RSL005) and
+PascalCase (RSL003); it also flags ambiguous `char`/scalar-`byte` (RSL005) and
 request/response field shadowing in services (RSL010). RSL004 (missing doc) and
 RSL006 (unbounded) are off by default; enable via `[lint.rules]` or per run with
 `--rules` (e.g. `--rules RSL004=warn --rules RSL001=off`; a bare `--rules RSL004`
@@ -166,10 +168,19 @@ definitions rather than reported as missing.
 
 Optional `TARGETS` (paths or package names) are overlaid on top of the
 environment, so a package you are editing can be checked from source instead of
-its installed copy. A bag type found in neither the environment nor any target
+its installed copy. Each source package replaces its entire installed interface
+set, so deleted source interfaces are reported as removed even when an installed
+copy remains. If targets overlap, the last target wins for that package. A bag
+type found in neither the environment nor any target
 is reported as removed (RS040). `ros2msg` schemas (including concatenated
 dependent definitions) are fully supported; `ros2idl` is a best-effort
-conversion of the msg-equivalent subset.
+conversion of the msg-equivalent subset. Unsupported encodings or IDL constructs,
+conflicting definitions of the same type (including embedded dependencies), and
+bags without usable ROS schemas produce a tool error (exit `2`). Equivalent
+definitions that differ only in formatting or comments are accepted, including
+repeated NaN constants and defaults. IDL struct inheritance and constants outside
+structs (including generated `T_Constants` modules) are rejected because their
+conversion is incomplete.
 
 ## Compatibility levels
 
@@ -187,11 +198,17 @@ conversion of the msg-equivalent subset.
 
 `roschema.toml` at the workspace root, a per-package `roschema.toml`, or
 `[tool.roschema]` in `pyproject.toml`. Precedence: CLI > package > workspace >
-defaults.
+defaults. Workspace discovery searches upwards to the Git repository root, or
+the filesystem root outside Git. Package configurations override inherited
+workspace values even when checking the package directly by path. At each
+directory, `roschema.toml` takes precedence over `[tool.roschema]`. Unknown rule
+IDs, rule IDs in the wrong section, and invalid settings produce configuration
+errors (exit `2`).
 
 ```toml
 [check]
 level = "source"
+deep = false          # --deep / --no-deep overrides this
 
 [check.rules]
 RS008 = "off"          # off | warn | error
@@ -256,9 +273,10 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0            # needed for the git-ref baseline
-      - uses: justagist/roschema/action@v1
+      - uses: justagist/roschema/action@main
         with:
           against: origin/${{ github.base_ref }}
+          # version: "roschema==0.2.0"   # pin a release for reproducible results
           # level: source
           # deep: "true"
           # exclude: "vendor_msgs* legacy_msgs/msg/Old"
@@ -268,6 +286,10 @@ jobs:
 `roschema.lock`). A lockfile or directory baseline needs no `fetch-depth: 0`
 because it is a plain file in the checkout.
 
+By default the Action installs the latest roschema release, so new rules can
+change results without any change on your side. Uncomment `version` to pin a
+release instead.
+
 ## Rule reference
 
 Every rule, its levels, default severity and rationale is documented in

roschema-0.2.0/action/action.yml

@@ -0,0 +1,65 @@
+name: roschema
+description: Catch breaking ROS 2 interface changes in the pull request.
+branding:
+  icon: git-pull-request
+  color: purple
+
+inputs:
+  target:
+    description: Path or package to check.
+    default: "."
+  against:
+    description: Baseline -- a git ref, directory, .mcap bag or roschema.lock.
+    default: origin/main
+  level:
+    description: >-
+      Reporting level (wire, source, introspection, behavior). Empty uses the
+      level configured in roschema.toml, else source.
+    default: ""
+  format:
+    description: Output format (text, json, github).
+    default: github
+  deep:
+    description: Resolve nested types and report transitive breakage (RS110).
+    default: "false"
+  exclude:
+    description: >-
+      Whitespace-separated globs of packages/interfaces to skip. Split on
+      whitespace only so patterns reach roschema literally.
+    default: ""
+  version:
+    description: >-
+      roschema requirement for uvx. Unpinned runs the latest release (refreshed
+      on every run, even with a uv cache); pin it (e.g. "roschema==0.2.0") for
+      reproducible results.
+    default: roschema
+
+runs:
+  using: composite
+  steps:
+    - uses: astral-sh/setup-uv@v5
+    - shell: bash
+      env:
+        ROSCHEMA_TARGET: ${{ inputs.target }}
+        ROSCHEMA_AGAINST: ${{ inputs.against }}
+        ROSCHEMA_LEVEL: ${{ inputs.level }}
+        ROSCHEMA_FORMAT: ${{ inputs.format }}
+        ROSCHEMA_DEEP: ${{ inputs.deep }}
+        ROSCHEMA_EXCLUDE: ${{ inputs.exclude }}
+        ROSCHEMA_VERSION: ${{ inputs.version }}
+      run: |
+        set -euo pipefail
+        args=(check "$ROSCHEMA_TARGET"
+              --against "$ROSCHEMA_AGAINST"
+              --format "$ROSCHEMA_FORMAT")
+        if [ -n "$ROSCHEMA_LEVEL" ]; then
+          args+=(--level "$ROSCHEMA_LEVEL")
+        fi
+        if [ "$ROSCHEMA_DEEP" = "true" ]; then
+          args+=(--deep)
+        fi
+        read -r -a excludes <<< "${ROSCHEMA_EXCLUDE//$'\n'/ }"
+        for glob in "${excludes[@]}"; do
+          args+=(--exclude "$glob")
+        done
+        uvx --refresh-package roschema --from "$ROSCHEMA_VERSION" roschema "${args[@]}"

{roschema-0.1.2 → roschema-0.2.0}/docs/rules.md

@@ -26,7 +26,7 @@ int32 a
 
 A field was added to an interface section.
 
-- Levels: wire, source
+- Levels: wire
 - Default severity: error
 
 *Rationale:* Appending a field is source-compatible but still changes the CDR wire layout, so a new publisher and an old subscriber cannot interoperate.
@@ -91,12 +91,12 @@ float32 yaw
 
 ### RS006 -- Array kind changed
 
-A field changed between fixed, bounded and unbounded array forms.
+A field changed between scalar, fixed-size array and sequence forms.
 
 - Levels: wire, source
 - Default severity: error
 
-*Rationale:* Fixed, bounded and unbounded arrays use different CDR encodings and generate different container types.
+*Rationale:* A sequence carries a length prefix that a fixed-size array and a scalar do not, so the CDR layout and the generated container type both change. Adding or removing a sequence bound is reported as RS007 or RS008 instead.
 
 ```
 # before
@@ -107,7 +107,7 @@ int32[8] data
 
 ### RS007 -- Bound tightened
 
-A bounded array or string had its capacity reduced.
+A sequence or string gained a bound or had its bound reduced.
 
 - Levels: wire
 - Default severity: error
@@ -123,7 +123,7 @@ string<=16 name
 
 ### RS008 -- Bound loosened
 
-A bounded array or string had its capacity increased.
+A sequence or string lost its bound or had its bound increased.
 
 - Levels: wire
 - Default severity: warn
@@ -239,7 +239,7 @@ int32 b
 
 ### RS110 -- Transitively broken by an embedded type
 
-An interface embeds (directly or through nested types) another interface whose wire layout changed, so it is broken even though its own definition did not change. Reported only with --deep.
+An interface embeds (directly or through nested types) another interface whose wire layout changed, so it is broken even though its own definition did not change. Reported only with --deep, with the severity of the reported change it traces back to; suppressed changes are not followed.
 
 - Levels: wire
 - Default severity: error
@@ -290,15 +290,15 @@ A field has no trailing documentation comment.
 
 ### RSL005 -- Discouraged type
 
-Uses `char`, or a scalar `byte`, both deprecated aliases in ROS 2.
+Uses `char`, or a scalar `byte`, whose generated types are ambiguous.
 
 - Default severity: warn
 
-*Rationale:* ROS 2 deprecated `char` and `byte` as scalar types in favour of `uint8`/`int8`; `byte[]` remains idiomatic for opaque binary data.
+*Rationale:* rosidl generates `char` as `uint8` although the ROS 2 type table lists it as a DDS `char`, and a scalar `byte` becomes a Python `bytes` object rather than an integer; `uint8` states the intent. `byte[]` remains idiomatic for opaque binary data.
 
 ### RSL006 -- Unbounded string or array
 
-A field is an unbounded array or unbounded string.
+A field is an unbounded array or contains unbounded strings.
 
 - Default severity: off
 

{roschema-0.1.2 → roschema-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "roschema"
-dynamic = ["version"]
+version = "0.2.0"
 description = "Breaking-change detection, linting and formatting for ROS 2 interface definitions"
 readme = "README.md"
 license = "Apache-2.0"
@@ -46,9 +46,6 @@ Documentation = "https://github.com/justagist/roschema#readme"
 Repository = "https://github.com/justagist/roschema"
 Issues = "https://github.com/justagist/roschema/issues"
 
-[tool.hatch.version]
-path = "src/roschema/__init__.py"
-
 [tool.hatch.build.targets.wheel]
 packages = ["src/roschema"]
 
@@ -67,4 +64,6 @@ files = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "-q"
+# A sourced ROS environment auto-loads its launch testing plugins, which fail to
+# import in a virtualenv without ROS's Python dependencies (e.g. PyYAML).
+addopts = "-q -p no:launch_testing -p no:launch_ros -p no:launch_pytest"

roschema-0.2.0/src/roschema/__init__.py

@@ -0,0 +1,8 @@
+"""roschema: breaking-change detection, linting and formatting for ROS 2 interfaces."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("roschema")
+except PackageNotFoundError:  # Uninstalled source checkout.
+    __version__ = "0.0.0.dev"