roschema 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -3,6 +3,26 @@
 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roschema
-Version: 0.3.0
+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
@@ -148,6 +148,9 @@ 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
@@ -155,7 +158,7 @@ roschema ls
 ```
 roschema check [TARGET] --against BASELINE [--level LEVEL] [--format text|json|github]
                [--deep | --no-deep] [--exit-zero] [--warnings-as-errors] [--allow-empty]
-               [--config PATH] [--exclude GLOB]
+               [--verbose] [--summary FILE] [--config PATH] [--exclude GLOB]
 ```
 
 `TARGET` selects what to check; omit it to check every interface package below
@@ -179,7 +182,10 @@ 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 only in the target`. A baseline with no interfaces at all is
+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
@@ -248,7 +254,7 @@ same. Comparison ignores it.
 ```
 roschema bag-check BAG.mcap [TARGETS...] [--level LEVEL] [--config PATH]
                    [--format text|json|github] [--exit-zero] [--warnings-as-errors]
-                   [--exclude GLOB]
+                   [--verbose] [--summary FILE] [--exclude GLOB]
 ```
 
 Needs the `bag` extra (`uv tool install 'roschema[bag]'`).
@@ -341,16 +347,27 @@ allow every rule for that target.
 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.
 
+**`--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`):
 
 ```json
@@ -368,7 +385,8 @@ workflow commands, which GitHub 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": {
@@ -389,7 +407,12 @@ workflow commands, which GitHub shows as annotations on the PR diff.
 
 `old`/`new` are `null` when there is no corresponding side (a removed interface
 has no `new`). `coverage` counts interfaces present on both sides (`compared`)
-and on one side only. `lint` output has no `advisories` or `coverage`.
+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
 
@@ -406,7 +429,8 @@ turns `1` into `0` for `check`, `bag-check` and `lint`; tool errors still exit
 ## 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
@@ -421,7 +445,7 @@ jobs:
       - uses: justagist/roschema/action@main
         with:
           against: origin/${{ github.base_ref }}
-          # version: "roschema==0.3.0"   # 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"
@@ -448,8 +472,10 @@ because it is part of the checkout.
 ## Troubleshooting
 
 **"no breaking changes found", but you expected some.** The line under the
-header says how many interfaces were compared. Run `roschema ls` with the same
-target to see which packages and interfaces are discovered, then check that:
+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;
 - a package-name target did not fall back to the installed copy (the warning
@@ -466,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.3.0 → roschema-0.4.0}/README.md

@@ -113,6 +113,9 @@ 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
@@ -120,7 +123,7 @@ roschema ls
 ```
 roschema check [TARGET] --against BASELINE [--level LEVEL] [--format text|json|github]
                [--deep | --no-deep] [--exit-zero] [--warnings-as-errors] [--allow-empty]
-               [--config PATH] [--exclude GLOB]
+               [--verbose] [--summary FILE] [--config PATH] [--exclude GLOB]
 ```
 
 `TARGET` selects what to check; omit it to check every interface package below
@@ -144,7 +147,10 @@ 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 only in the target`. A baseline with no interfaces at all is
+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
@@ -213,7 +219,7 @@ same. Comparison ignores it.
 ```
 roschema bag-check BAG.mcap [TARGETS...] [--level LEVEL] [--config PATH]
                    [--format text|json|github] [--exit-zero] [--warnings-as-errors]
-                   [--exclude GLOB]
+                   [--verbose] [--summary FILE] [--exclude GLOB]
 ```
 
 Needs the `bag` extra (`uv tool install 'roschema[bag]'`).
@@ -306,16 +312,27 @@ allow every rule for that target.
 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.
 
+**`--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`):
 
 ```json
@@ -333,7 +350,8 @@ workflow commands, which GitHub 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": {
@@ -354,7 +372,12 @@ workflow commands, which GitHub shows as annotations on the PR diff.
 
 `old`/`new` are `null` when there is no corresponding side (a removed interface
 has no `new`). `coverage` counts interfaces present on both sides (`compared`)
-and on one side only. `lint` output has no `advisories` or `coverage`.
+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
 
@@ -371,7 +394,8 @@ turns `1` into `0` for `check`, `bag-check` and `lint`; tool errors still exit
 ## 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
@@ -386,7 +410,7 @@ jobs:
       - uses: justagist/roschema/action@main
         with:
           against: origin/${{ github.base_ref }}
-          # version: "roschema==0.3.0"   # 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"
@@ -413,8 +437,10 @@ because it is part of the checkout.
 ## Troubleshooting
 
 **"no breaking changes found", but you expected some.** The line under the
-header says how many interfaces were compared. Run `roschema ls` with the same
-target to see which packages and interfaces are discovered, then check that:
+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;
 - a package-name target did not fall back to the installed copy (the warning
@@ -431,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.3.0 → roschema-0.4.0}/action/action.yml

@@ -38,7 +38,7 @@ 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.3.0") for
+      on every run, even with a uv cache); pin it (e.g. "roschema==0.4.0") for
       reproducible results.
     default: roschema
 
@@ -78,6 +78,9 @@ runs:
         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.3.0 → roschema-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "roschema"
-version = "0.3.0"
+version = "0.4.0"
 description = "Breaking-change detection, linting and formatting for ROS 2 interface definitions"
 readme = "README.md"
 license = "Apache-2.0"

{roschema-0.3.0 → roschema-0.4.0}/src/roschema/cli.py

@@ -2,16 +2,18 @@
 
 from __future__ import annotations
 
+import difflib
 import json
 import os
 import posixpath
 from collections.abc import Callable
-from dataclasses import replace
+from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Annotated
 
 import typer
 from rich.console import Console
+from rich.markdown import Markdown
 
 from . import __version__
 from .config import (
@@ -38,8 +40,18 @@ from .ir import InterfaceFile
 from .loader import load_interfaces
 from .mcap_fs import McapTypeFS
 from .parser import ParseError
-from .report import Coverage, build_github, build_json, coverage, render_lint, render_text
-from .rules import Finding, all_lint_rules, evaluate, lint_interfaces
+from .report import (
+    Coverage,
+    build_github,
+    build_json,
+    build_markdown,
+    coverage,
+    render_lint,
+    render_text,
+)
+from .report.changes import Change, additions, by_location, suppressed_changes
+from .rules import Finding, all_lint_rules, all_rules, evaluate, lint_interfaces
+from .rules.gendocs import docs_url, find_rule, render_rule
 from .vfs import GitTreeFS, RealFS, VfsError, git_toplevel
 
 app = typer.Typer(
@@ -52,6 +64,31 @@ app = typer.Typer(
 console = Console(soft_wrap=True)
 err_console = Console(stderr=True, soft_wrap=True)
 
+
+@dataclass(frozen=True)
+class _Result:
+    """What a check or bag check found, for reporting.
+
+    Args:
+        findings: Finalized findings, including suppressed ones.
+        new_source: Description of the target side.
+        old_source: Description of the baseline side.
+        coverage: Interface counts across both sides.
+        changes: Changes that are not findings: additions, and findings dropped
+            for their level or because their rule is off.
+        interface_files: Each current interface's source file, by interface key.
+        display_prefix: Repo-root-relative prefix for annotation paths.
+    """
+
+    findings: list[Finding]
+    new_source: str
+    old_source: str
+    coverage: Coverage
+    changes: list[Change]
+    interface_files: dict[str, str]
+    display_prefix: str = ""
+
+
 # A bag check asks whether current code can still decode the recording, which is
 # a wire question; constant and other source-level changes do not affect it.
 BAG_DEFAULT_LEVEL = "wire"
@@ -117,6 +154,21 @@ def check(
         bool,
         typer.Option("--warnings-as-errors", help="Exit 1 on warnings as well as errors."),
     ] = False,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            help="Also list changes that are not reported (added, below the level, rule off "
+            "or suppressed) and why.",
+        ),
+    ] = False,
+    summary_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--summary",
+            help="Also append a Markdown report to this file, e.g. $GITHUB_STEP_SUMMARY.",
+        ),
+    ] = None,
     allow_empty: Annotated[
         bool,
         typer.Option(
@@ -138,24 +190,28 @@ def check(
         raise typer.Exit(code=2)
 
     try:
-        findings, new_source, old_source, prefix, files, cov = _compute(
+        result = _compute(
             target, lambda root: resolve_baseline(against, root), level, config_path, exclude, deep
         )
     except (VfsError, ParseError, ConfigError) as exc:
         err_console.print(f"[red]error:[/red] {exc}")
         raise typer.Exit(code=2) from exc
 
-    if old_source.startswith("git:") and Path(against).is_dir():
+    if result.old_source.startswith("git:") and Path(against).is_dir():
         err_console.print(
             f"[dim]note: {against!r} matched a git ref; "
             f"use './{against}' to compare against the directory instead.[/dim]"
         )
     if not allow_empty:
         _require_baseline(
-            cov, f"the baseline ({old_source})", "pass --allow-empty if that is expected"
+            result.coverage,
+            f"the baseline ({result.old_source})",
+            "pass --allow-empty if that is expected",
         )
-    _emit(findings, fmt, new_source, old_source, cov, prefix, files)
-    _exit_for(findings, exit_zero, warnings_as_errors)
+    _emit(result, fmt, verbose)
+    if summary_path is not None:
+        _write_summary(result, summary_path)
+    _exit_for(result.findings, exit_zero, warnings_as_errors)
 
 
 @app.command(name="bag-check")
@@ -189,6 +245,21 @@ def bag_check(
         bool,
         typer.Option("--warnings-as-errors", help="Exit 1 on warnings as well as errors."),
     ] = False,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            help="Also list changes that are not reported (added, below the level, rule off "
+            "or suppressed) and why.",
+        ),
+    ] = False,
+    summary_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--summary",
+            help="Also append a Markdown report to this file, e.g. $GITHUB_STEP_SUMMARY.",
+        ),
+    ] = None,
     exclude: Annotated[
         list[str] | None,
         typer.Option("--exclude", help="Glob of packages/interfaces to skip."),
@@ -224,14 +295,21 @@ def bag_check(
         err_console.print(f"[red]error:[/red] {exc}")
         raise typer.Exit(code=2) from exc
 
-    findings = finalize_findings(
-        evaluate(diff_interfaces(old_ifaces, new_ifaces)), config, level, BAG_DEFAULT_LEVEL
+    events = diff_interfaces(old_ifaces, new_ifaces)
+    dropped: list[tuple[Finding, str]] = []
+    result = _Result(
+        findings=finalize_findings(evaluate(events), config, level, BAG_DEFAULT_LEVEL, dropped),
+        new_source=new_source,
+        old_source=old_res.source,
+        coverage=coverage(old_ifaces, new_ifaces),
+        changes=additions(events) + [Change.from_finding(f, why) for f, why in dropped],
+        interface_files={key: iface.source_file for key, iface in new_ifaces.items()},
     )
-    cov = coverage(old_ifaces, new_ifaces)
-    _require_baseline(cov, "the bag", "check the --exclude patterns")
-    files = {key: iface.source_file for key, iface in new_ifaces.items()}
-    _emit(findings, fmt, new_source, old_res.source, cov, interface_files=files)
-    _exit_for(findings, exit_zero, warnings_as_errors)
+    _require_baseline(result.coverage, "the bag", "check the --exclude patterns")
+    _emit(result, fmt, verbose)
+    if summary_path is not None:
+        _write_summary(result, summary_path)
+    _exit_for(result.findings, exit_zero, warnings_as_errors)
 
 
 def _resolve_current(
@@ -285,12 +363,8 @@ def _compute(
     config_path: Path | None,
     exclude: list[str] | None,
     deep: bool | None = None,
-) -> tuple[list[Finding], str, str, str, dict[str, str], Coverage]:
-    """Resolve both sides, diff and finalize; the shared check pipeline.
-
-    Also returns each current interface's source file, keyed by interface, and
-    how many interfaces were compared.
-    """
+) -> _Result:
+    """Resolve both sides, diff and finalize; the shared check pipeline."""
     new_res = _resolve_target(target, allow_empty_glob=True)
     if not isinstance(new_res.vfs, RealFS):
         raise VfsError("target must be a directory or workspace")
@@ -324,16 +398,24 @@ def _compute(
             raise VfsError(f"target glob {target!r} matched no interface packages on either side")
         old_packages = tuple(p for p in old_packages if p.name in scope)
     old_ifaces = load_interfaces(old_res.vfs, apply_exclude(old_packages, excludes))
-    findings = finalize_findings(evaluate(diff_interfaces(old_ifaces, new_ifaces)), config, level)
+    events = diff_interfaces(old_ifaces, new_ifaces)
+    dropped: list[tuple[Finding, str]] = []
+    findings = finalize_findings(evaluate(events), config, level, dropped=dropped)
     deep_packages = {p.name for p in new_res.packages if config.effective_deep(p.name, deep)}
     if deep_packages:
         transitive = transitive_findings(new_ifaces, findings)
         findings += finalize_findings(
-            [f for f in transitive if f.package in deep_packages], config, level
+            [f for f in transitive if f.package in deep_packages], config, level, dropped=dropped
         )
-    files = {key: iface.source_file for key, iface in new_ifaces.items()}
-    cov = coverage(old_ifaces, new_ifaces)
-    return findings, new_res.source, old_res.source, prefix, files, cov
+    return _Result(
+        findings=findings,
+        new_source=new_res.source,
+        old_source=old_res.source,
+        coverage=coverage(old_ifaces, new_ifaces),
+        changes=additions(events) + [Change.from_finding(f, why) for f, why in dropped],
+        interface_files={key: iface.source_file for key, iface in new_ifaces.items()},
+        display_prefix=prefix,
+    )
 
 
 def _note_skipped_schemas(res: Resolution) -> None:
@@ -376,23 +458,37 @@ def _exit_for(findings: list[Finding], exit_zero: bool, warnings_as_errors: bool
     raise typer.Exit(code=1 if has_failure else 0)
 
 
-def _emit(
-    findings: list[Finding],
-    fmt: str,
-    new_source: str,
-    old_source: str,
-    cov: Coverage,
-    display_prefix: str = "",
-    interface_files: dict[str, str] | None = None,
-) -> None:
+def _write_summary(result: _Result, path: Path) -> None:
+    """Append the Markdown report to ``path``; GitHub collects step summaries this way."""
+    report = build_markdown(
+        result.findings, result.new_source, result.old_source, result.coverage, result.changes
+    )
+    try:
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(report)
+    except OSError as exc:
+        err_console.print(f"[red]error:[/red] cannot write the summary to {str(path)!r}: {exc}")
+        raise typer.Exit(code=2) from exc
+
+
+def _emit(result: _Result, fmt: str, verbose: bool) -> None:
+    findings, cov, changes = result.findings, result.coverage, result.changes
     if fmt == "json":
-        typer.echo(json.dumps(build_json(findings, coverage=cov), indent=2))
+        doc = build_json(findings, coverage=cov, changes=changes, verbose=verbose)
+        typer.echo(json.dumps(doc, indent=2))
     elif fmt == "github":
         typer.echo(cov.describe())
-        for line in build_github(findings, display_prefix, interface_files):
+        if verbose:
+            for change in by_location([*changes, *suppressed_changes(findings)]):
+                rule = f"{change.rule} " if change.rule else ""
+                line = f"{rule}{change.qualified_target}: {change.message} ({change.reason})"
+                # A line break (e.g. in an allowlist reason) could start a
+                # workflow command; commands are only read at line starts.
+                typer.echo("not reported: " + " ".join(line.splitlines()))
+        for line in build_github(findings, result.display_prefix, result.interface_files):
             typer.echo(line)
     else:
-        render_text(findings, console, new_source, old_source, cov)
+        render_text(findings, console, result.new_source, result.old_source, cov, changes, verbose)
 
 
 @app.command()
@@ -543,6 +639,22 @@ def freeze(
     console.print(f"wrote {len(interfaces)} interface(s) to {output}")
 
 
+@app.command()
+def explain(
+    rule_id: Annotated[str, typer.Argument(metavar="RULE", help="Rule ID, e.g. RS003.")],
+) -> None:
+    """Describe a rule: what it reports, its levels, rationale and an example."""
+    rule = find_rule(rule_id)
+    if rule is None:
+        ids = [r.id for r in all_rules()] + [r.id for r in all_lint_rules()]
+        close = difflib.get_close_matches(rule_id.upper(), ids, n=1)
+        hint = f"; did you mean {close[0]}?" if close else ""
+        err_console.print(f"[red]error:[/red] unknown rule {rule_id!r}{hint}")
+        raise typer.Exit(code=2)
+    console.print(Markdown(render_rule(rule)))
+    console.print(f"\n{docs_url(rule.id)}")
+
+
 @app.command()
 def ls(
     target: Annotated[