roschema 0.2.1__tar.gz → 0.4.0__tar.gz

{roschema-0.2.1 → roschema-0.4.0}/.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v10.3.3
         with:
           python-version: "3.12"
           enable-cache: true
@@ -36,10 +36,10 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v10.3.3
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: true

{roschema-0.2.1 → roschema-0.4.0}/.github/workflows/release.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v10.3.3
         with:
           python-version: "3.12"
           enable-cache: true

{roschema-0.2.1 → roschema-0.4.0}/CHANGELOG.md

@@ -3,6 +3,49 @@
 The format follows [Keep a Changelog](https://keepachangelog.com/), and the
 project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] - 2026-11-03
+
+### Added
+
+- JSON findings link to their rule's documentation (`help_uri`).
+- `roschema explain RULE` prints a rule's reference section.
+- `check --verbose` and `bag-check --verbose` list the changes that are not
+  reported (added, outside the level, rule off or suppressed) with the reason;
+  JSON adds a `changes` array.
+- `--summary FILE` appends a Markdown report; the Action writes it to the job
+  summary, so every finding and the semver advice are visible even when GitHub
+  truncates the annotations.
+
+### Changed
+
+- The semver advice suggests MINOR for a package that adds an interface or a
+  constant, and is printed even when there are no findings.
+- The coverage line names the first few new interfaces and says "new" and
+  "removed" instead of "only in the target" and "only in the baseline".
+
+## [0.3.0] - 2026-11-03
+
+### Added
+
+- Reports say how many interfaces were compared, and on which side the rest
+  exist only (JSON: `coverage`).
+- `--warnings-as-errors` for `check`, `bag-check` and `lint`, and the Action's
+  `warnings-as-errors` input.
+
+### Changed
+
+- Python 3.14 is supported and tested.
+- An empty baseline is an error (exit `2`) instead of a silent pass; pass
+  `--allow-empty` (Action: `allow-empty`) when that is expected.
+
+### Fixed
+
+- `--format github` attaches findings with no new-side location, such as a
+  removed field or a reorder, to the interface's file instead of leaving GitHub
+  to show them against the workflow file.
+- The Action uses `astral-sh/setup-uv@v10.3.3` (Node 24) with its cache off,
+  removing the Node 20 deprecation and missing `uv.lock` warnings.
+
 ## [0.2.1] - 2026-11-03
 
 ### Added

{roschema-0.2.1 → roschema-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roschema
-Version: 0.2.1
+Version: 0.4.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
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
@@ -147,13 +148,17 @@ roschema bag-check recording.mcap
 
 # what would be checked? (discovered packages and interfaces)
 roschema ls
+
+# what does a rule report, and why?
+roschema explain RS004
 ```
 
 ## Checking
 
 ```
 roschema check [TARGET] --against BASELINE [--level LEVEL] [--format text|json|github]
-               [--deep | --no-deep] [--exit-zero] [--config PATH] [--exclude GLOB]
+               [--deep | --no-deep] [--exit-zero] [--warnings-as-errors] [--allow-empty]
+               [--verbose] [--summary FILE] [--config PATH] [--exclude GLOB]
 ```
 
 `TARGET` selects what to check; omit it to check every interface package below
@@ -176,6 +181,16 @@ MCAP bag (`.mcap`) or a lockfile (`roschema.lock`); the type is detected
 automatically. Initialised git submodules are compared at the commit the
 baseline records for them.
 
+Every report says how much was compared, for example `compared 12 interface(s)
+in 3 package(s); 1 new (my_msgs/msg/Status)`. New interfaces are not findings,
+since adding one breaks nothing; the line names the first few so that an
+unexpected one (say, from an unrelated checkout below the target) is easy to
+spot. A baseline with no interfaces at all is
+an error (exit `2`): every current interface would look newly added, so the
+check would pass without comparing anything. That usually means the wrong
+baseline or target; on the pull request that adds the first interfaces, pass
+`--allow-empty`.
+
 Limitations:
 
 - When a git ref and a directory share a name, the git ref wins; prefix the
@@ -199,7 +214,7 @@ followed.
 
 ```
 roschema lint [TARGET] [--format text|json|github] [--rules RULE=SEV] [--exit-zero]
-              [--config PATH] [--exclude GLOB]
+              [--warnings-as-errors] [--config PATH] [--exclude GLOB]
 roschema fmt  [TARGET] [--check] [--exclude GLOB]
 ```
 
@@ -238,7 +253,8 @@ same. Comparison ignores it.
 
 ```
 roschema bag-check BAG.mcap [TARGETS...] [--level LEVEL] [--config PATH]
-                   [--format text|json|github] [--exit-zero] [--exclude GLOB]
+                   [--format text|json|github] [--exit-zero] [--warnings-as-errors]
+                   [--verbose] [--summary FILE] [--exclude GLOB]
 ```
 
 Needs the `bag` extra (`uv tool install 'roschema[bag]'`).
@@ -327,19 +343,30 @@ allow every rule for that target.
 
 ## Output
 
-**Text** (the default) groups findings by package and ends with a summary and a
-semver advice per package:
+**Text** (the default) starts with what was compared, groups findings by
+package and ends with a summary and a semver advice per package:
 
 - **MAJOR** when the package has a wire- or source-level error;
-- **MINOR** when its only notable change is an added field (RS002) whose
-  severity you lowered to `warn`;
+- **MINOR** when it adds an interface or a constant (neither is a finding,
+  since neither breaks anything), or an added field (RS002) whose severity you
+  lowered to `warn`;
 - **PATCH** otherwise.
 
-The advice only covers reported findings. Additions such as a new interface or
-constant are not findings, so they never raise the advice to MINOR on their own.
+**`--verbose`** also lists, under "not reported", every change that produced no
+reported finding, and why: a new interface or constant (no rule reports either,
+at any level; an added field is RS002), a rule whose level is outside the one
+being checked, a rule that is off, or a suppression, with the allowlist reason.
+Comment-only edits are not changes, so they never appear.
+
+**`--format github`** prints what was compared, then emits `::error`/`::warning`
+workflow commands, which GitHub shows as annotations on the PR diff.
 
-**`--format github`** emits `::error`/`::warning` workflow commands, which GitHub
-shows as annotations on the PR diff.
+**`--summary FILE`** appends a Markdown report to `FILE` as well, whatever the
+`--format`: what was compared, a table of findings linked to the rule
+reference, the semver advice, and the unreported changes in a collapsed
+section. Pointed at `$GITHUB_STEP_SUMMARY`, it becomes the job summary, which
+matters because GitHub shows only the first 10 error and 10 warning annotations
+of a step.
 
 **`--format json`** emits a stable document (`version: 1`):
 
@@ -358,7 +385,8 @@ shows as annotations on the PR diff.
       "message": "type changed float32 -> float64",
       "old": { "file": "my_msgs/msg/Pose.msg", "line": 1 },
       "new": { "file": "my_msgs/msg/Pose.msg", "line": 1 },
-      "suppressed": false
+      "suppressed": false,
+      "help_uri": "https://github.com/justagist/roschema/blob/v0.4.0/docs/rules.md#rs003----field-type-changed"
     }
   ],
   "summary": {
@@ -367,12 +395,24 @@ shows as annotations on the PR diff.
     "warnings": 0,
     "suppressed": 0,
     "advisories": { "my_msgs": "MAJOR" }
+  },
+  "coverage": {
+    "packages": 1,
+    "compared": 1,
+    "target_only": 0,
+    "baseline_only": 0
   }
 }
 ```
 
 `old`/`new` are `null` when there is no corresponding side (a removed interface
-has no `new`). `lint` output has no `advisories`.
+has no `new`). `coverage` counts interfaces present on both sides (`compared`)
+and on one side only. `help_uri` links to the rule's section of the
+[rule reference](docs/rules.md) for the installed release. With `--verbose`, a
+`changes` array lists the unreported changes (each with `rule`, `package`,
+`interface`, `section`, `target`, `message` and `reason`), including suppressed
+findings with the reason they are suppressed. `lint` output has no
+`advisories`, `coverage` or `changes`.
 
 ## Exit codes
 
@@ -380,15 +420,17 @@ has no `new`). `lint` output has no `advisories`.
 |---|---|---|---|
 | `0` | no unsuppressed errors (warnings allowed) | every file formatted | success |
 | `1` | at least one unsuppressed error | a file would change | n/a |
-| `2` | tool or usage error (bad target, baseline, configuration or file) | tool or usage error | tool or usage error |
+| `2` | tool or usage error (bad target, baseline, configuration or file, or an empty baseline) | tool or usage error | tool or usage error |
 
-`--exit-zero` turns `1` into `0` for `check`, `bag-check` and `lint`; tool
-errors still exit `2`.
+`--warnings-as-errors` makes unsuppressed warnings exit `1` too. `--exit-zero`
+turns `1` into `0` for `check`, `bag-check` and `lint`; tool errors still exit
+`2`.
 
 ## GitHub Action
 
 A composite Action runs `roschema check` on the runner (no setup needed) and
-posts the findings as annotations on the PR diff:
+posts the findings as annotations on the PR diff, with a full report (findings,
+semver advice and unreported changes) as the job summary:
 
 ```yaml
 # .github/workflows/interfaces.yml
@@ -403,9 +445,10 @@ jobs:
       - uses: justagist/roschema/action@main
         with:
           against: origin/${{ github.base_ref }}
-          # version: "roschema==0.2.1"   # pin a release for reproducible results
+          # version: "roschema==0.4.0"   # pin a release for reproducible results
           # level: source
           # deep: "true"
+          # warnings-as-errors: "true"
           # exclude: "vendor_msgs* legacy_msgs/msg/Old"
 ```
 
@@ -416,6 +459,8 @@ jobs:
 | `level` | (empty) | reporting level; empty uses the configured level, else `source` |
 | `format` | `github` | `text`, `json` or `github` |
 | `deep` | `"false"` | `"true"` adds `--deep` |
+| `allow-empty` | `"false"` | `"true"` adds `--allow-empty` |
+| `warnings-as-errors` | `"false"` | `"true"` adds `--warnings-as-errors` |
 | `exclude` | (empty) | whitespace-separated globs passed as `--exclude` |
 | `version` | `roschema` | the roschema requirement installed with `uvx` |
 
@@ -426,8 +471,10 @@ because it is part of the checkout.
 
 ## Troubleshooting
 
-**"no breaking changes found", but you expected some.** Run `roschema ls` with
-the same target to see which packages and interfaces are discovered, then check
+**"no breaking changes found", but you expected some.** The line under the
+header says how many interfaces were compared, and `--verbose` lists the changes
+that were seen but not reported, with the reason. Run `roschema ls` with the
+same target to see which packages and interfaces are discovered, then check
 that:
 
 - the packages are not below a `COLCON_IGNORE` or `AMENT_IGNORE` marker;
@@ -445,6 +492,7 @@ shown in [Configuration](#configuration); the error suggests the closest one.
 
 Every rule, its levels, default severity, rationale and an example is
 documented in [docs/rules.md](docs/rules.md), generated from the rule metadata.
+`roschema explain RULE` prints the same section in the terminal.
 
 ## Non-goals
 

{roschema-0.2.1 → roschema-0.4.0}/README.md

@@ -113,13 +113,17 @@ roschema bag-check recording.mcap
 
 # what would be checked? (discovered packages and interfaces)
 roschema ls
+
+# what does a rule report, and why?
+roschema explain RS004
 ```
 
 ## Checking
 
 ```
 roschema check [TARGET] --against BASELINE [--level LEVEL] [--format text|json|github]
-               [--deep | --no-deep] [--exit-zero] [--config PATH] [--exclude GLOB]
+               [--deep | --no-deep] [--exit-zero] [--warnings-as-errors] [--allow-empty]
+               [--verbose] [--summary FILE] [--config PATH] [--exclude GLOB]
 ```
 
 `TARGET` selects what to check; omit it to check every interface package below
@@ -142,6 +146,16 @@ MCAP bag (`.mcap`) or a lockfile (`roschema.lock`); the type is detected
 automatically. Initialised git submodules are compared at the commit the
 baseline records for them.
 
+Every report says how much was compared, for example `compared 12 interface(s)
+in 3 package(s); 1 new (my_msgs/msg/Status)`. New interfaces are not findings,
+since adding one breaks nothing; the line names the first few so that an
+unexpected one (say, from an unrelated checkout below the target) is easy to
+spot. A baseline with no interfaces at all is
+an error (exit `2`): every current interface would look newly added, so the
+check would pass without comparing anything. That usually means the wrong
+baseline or target; on the pull request that adds the first interfaces, pass
+`--allow-empty`.
+
 Limitations:
 
 - When a git ref and a directory share a name, the git ref wins; prefix the
@@ -165,7 +179,7 @@ followed.
 
 ```
 roschema lint [TARGET] [--format text|json|github] [--rules RULE=SEV] [--exit-zero]
-              [--config PATH] [--exclude GLOB]
+              [--warnings-as-errors] [--config PATH] [--exclude GLOB]
 roschema fmt  [TARGET] [--check] [--exclude GLOB]
 ```
 
@@ -204,7 +218,8 @@ same. Comparison ignores it.
 
 ```
 roschema bag-check BAG.mcap [TARGETS...] [--level LEVEL] [--config PATH]
-                   [--format text|json|github] [--exit-zero] [--exclude GLOB]
+                   [--format text|json|github] [--exit-zero] [--warnings-as-errors]
+                   [--verbose] [--summary FILE] [--exclude GLOB]
 ```
 
 Needs the `bag` extra (`uv tool install 'roschema[bag]'`).
@@ -293,19 +308,30 @@ allow every rule for that target.
 
 ## Output
 
-**Text** (the default) groups findings by package and ends with a summary and a
-semver advice per package:
+**Text** (the default) starts with what was compared, groups findings by
+package and ends with a summary and a semver advice per package:
 
 - **MAJOR** when the package has a wire- or source-level error;
-- **MINOR** when its only notable change is an added field (RS002) whose
-  severity you lowered to `warn`;
+- **MINOR** when it adds an interface or a constant (neither is a finding,
+  since neither breaks anything), or an added field (RS002) whose severity you
+  lowered to `warn`;
 - **PATCH** otherwise.
 
-The advice only covers reported findings. Additions such as a new interface or
-constant are not findings, so they never raise the advice to MINOR on their own.
+**`--verbose`** also lists, under "not reported", every change that produced no
+reported finding, and why: a new interface or constant (no rule reports either,
+at any level; an added field is RS002), a rule whose level is outside the one
+being checked, a rule that is off, or a suppression, with the allowlist reason.
+Comment-only edits are not changes, so they never appear.
+
+**`--format github`** prints what was compared, then emits `::error`/`::warning`
+workflow commands, which GitHub shows as annotations on the PR diff.
 
-**`--format github`** emits `::error`/`::warning` workflow commands, which GitHub
-shows as annotations on the PR diff.
+**`--summary FILE`** appends a Markdown report to `FILE` as well, whatever the
+`--format`: what was compared, a table of findings linked to the rule
+reference, the semver advice, and the unreported changes in a collapsed
+section. Pointed at `$GITHUB_STEP_SUMMARY`, it becomes the job summary, which
+matters because GitHub shows only the first 10 error and 10 warning annotations
+of a step.
 
 **`--format json`** emits a stable document (`version: 1`):
 
@@ -324,7 +350,8 @@ shows as annotations on the PR diff.
       "message": "type changed float32 -> float64",
       "old": { "file": "my_msgs/msg/Pose.msg", "line": 1 },
       "new": { "file": "my_msgs/msg/Pose.msg", "line": 1 },
-      "suppressed": false
+      "suppressed": false,
+      "help_uri": "https://github.com/justagist/roschema/blob/v0.4.0/docs/rules.md#rs003----field-type-changed"
     }
   ],
   "summary": {
@@ -333,12 +360,24 @@ shows as annotations on the PR diff.
     "warnings": 0,
     "suppressed": 0,
     "advisories": { "my_msgs": "MAJOR" }
+  },
+  "coverage": {
+    "packages": 1,
+    "compared": 1,
+    "target_only": 0,
+    "baseline_only": 0
   }
 }
 ```
 
 `old`/`new` are `null` when there is no corresponding side (a removed interface
-has no `new`). `lint` output has no `advisories`.
+has no `new`). `coverage` counts interfaces present on both sides (`compared`)
+and on one side only. `help_uri` links to the rule's section of the
+[rule reference](docs/rules.md) for the installed release. With `--verbose`, a
+`changes` array lists the unreported changes (each with `rule`, `package`,
+`interface`, `section`, `target`, `message` and `reason`), including suppressed
+findings with the reason they are suppressed. `lint` output has no
+`advisories`, `coverage` or `changes`.
 
 ## Exit codes
 
@@ -346,15 +385,17 @@ has no `new`). `lint` output has no `advisories`.
 |---|---|---|---|
 | `0` | no unsuppressed errors (warnings allowed) | every file formatted | success |
 | `1` | at least one unsuppressed error | a file would change | n/a |
-| `2` | tool or usage error (bad target, baseline, configuration or file) | tool or usage error | tool or usage error |
+| `2` | tool or usage error (bad target, baseline, configuration or file, or an empty baseline) | tool or usage error | tool or usage error |
 
-`--exit-zero` turns `1` into `0` for `check`, `bag-check` and `lint`; tool
-errors still exit `2`.
+`--warnings-as-errors` makes unsuppressed warnings exit `1` too. `--exit-zero`
+turns `1` into `0` for `check`, `bag-check` and `lint`; tool errors still exit
+`2`.
 
 ## GitHub Action
 
 A composite Action runs `roschema check` on the runner (no setup needed) and
-posts the findings as annotations on the PR diff:
+posts the findings as annotations on the PR diff, with a full report (findings,
+semver advice and unreported changes) as the job summary:
 
 ```yaml
 # .github/workflows/interfaces.yml
@@ -369,9 +410,10 @@ jobs:
       - uses: justagist/roschema/action@main
         with:
           against: origin/${{ github.base_ref }}
-          # version: "roschema==0.2.1"   # pin a release for reproducible results
+          # version: "roschema==0.4.0"   # pin a release for reproducible results
           # level: source
           # deep: "true"
+          # warnings-as-errors: "true"
           # exclude: "vendor_msgs* legacy_msgs/msg/Old"
 ```
 
@@ -382,6 +424,8 @@ jobs:
 | `level` | (empty) | reporting level; empty uses the configured level, else `source` |
 | `format` | `github` | `text`, `json` or `github` |
 | `deep` | `"false"` | `"true"` adds `--deep` |
+| `allow-empty` | `"false"` | `"true"` adds `--allow-empty` |
+| `warnings-as-errors` | `"false"` | `"true"` adds `--warnings-as-errors` |
 | `exclude` | (empty) | whitespace-separated globs passed as `--exclude` |
 | `version` | `roschema` | the roschema requirement installed with `uvx` |
 
@@ -392,8 +436,10 @@ because it is part of the checkout.
 
 ## Troubleshooting
 
-**"no breaking changes found", but you expected some.** Run `roschema ls` with
-the same target to see which packages and interfaces are discovered, then check
+**"no breaking changes found", but you expected some.** The line under the
+header says how many interfaces were compared, and `--verbose` lists the changes
+that were seen but not reported, with the reason. Run `roschema ls` with the
+same target to see which packages and interfaces are discovered, then check
 that:
 
 - the packages are not below a `COLCON_IGNORE` or `AMENT_IGNORE` marker;
@@ -411,6 +457,7 @@ shown in [Configuration](#configuration); the error suggests the closest one.
 
 Every rule, its levels, default severity, rationale and an example is
 documented in [docs/rules.md](docs/rules.md), generated from the rule metadata.
+`roschema explain RULE` prints the same section in the terminal.
 
 ## Non-goals
 

{roschema-0.2.1 → roschema-0.4.0}/action/action.yml

@@ -22,6 +22,14 @@ inputs:
   deep:
     description: Resolve nested types and report transitive breakage (RS110).
     default: "false"
+  allow-empty:
+    description: >-
+      Pass when the baseline has no interfaces, e.g. on the pull request that
+      adds the first ones. Otherwise an empty baseline fails the step.
+    default: "false"
+  warnings-as-errors:
+    description: Fail the step on warnings as well as errors.
+    default: "false"
   exclude:
     description: >-
       Whitespace-separated globs of packages/interfaces to skip. Split on
@@ -30,14 +38,18 @@ inputs:
   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.1") for
+      on every run, even with a uv cache); pin it (e.g. "roschema==0.4.0") for
       reproducible results.
     default: roschema
 
 runs:
   using: composite
   steps:
-    - uses: astral-sh/setup-uv@v5
+    - uses: astral-sh/setup-uv@v10.3.3
+      with:
+        # Nothing to key a cache on in the caller's repo, and uvx refreshes
+        # roschema on every run anyway.
+        enable-cache: false
     - shell: bash
       env:
         ROSCHEMA_TARGET: ${{ inputs.target }}
@@ -45,6 +57,8 @@ runs:
         ROSCHEMA_LEVEL: ${{ inputs.level }}
         ROSCHEMA_FORMAT: ${{ inputs.format }}
         ROSCHEMA_DEEP: ${{ inputs.deep }}
+        ROSCHEMA_ALLOW_EMPTY: ${{ inputs.allow-empty }}
+        ROSCHEMA_WARNINGS_AS_ERRORS: ${{ inputs.warnings-as-errors }}
         ROSCHEMA_EXCLUDE: ${{ inputs.exclude }}
         ROSCHEMA_VERSION: ${{ inputs.version }}
       run: |
@@ -58,6 +72,15 @@ runs:
         if [ "$ROSCHEMA_DEEP" = "true" ]; then
           args+=(--deep)
         fi
+        if [ "$ROSCHEMA_ALLOW_EMPTY" = "true" ]; then
+          args+=(--allow-empty)
+        fi
+        if [ "$ROSCHEMA_WARNINGS_AS_ERRORS" = "true" ]; then
+          args+=(--warnings-as-errors)
+        fi
+        if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+          args+=(--summary "$GITHUB_STEP_SUMMARY")
+        fi
         read -r -a excludes <<< "${ROSCHEMA_EXCLUDE//$'\n'/ }"
         for glob in "${excludes[@]}"; do
           args+=(--exclude "$glob")

{roschema-0.2.1 → roschema-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "roschema"
-version = "0.2.1"
+version = "0.4.0"
 description = "Breaking-change detection, linting and formatting for ROS 2 interface definitions"
 readme = "README.md"
 license = "Apache-2.0"
@@ -19,6 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Quality Assurance",
     "Typing :: Typed",
 ]