ruff-sync 0.1.5.dev4__tar.gz → 0.1.5.dev5__tar.gz

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev5}/.agents/skills/ruff-sync-usage/references/ci-integration.md

@@ -12,7 +12,10 @@ Add this step to any existing workflow (e.g., `.github/workflows/ci.yaml`):
 ```
 
 `--semantic` ignores cosmetic differences (comments, whitespace) — only real value or rule changes cause failure.
-`--output-format github` creates inline PR annotations for errors and warnings.
+`--output-format github` creates inline PR annotations and a structured Job Summary report.
+
+> [!TIP]
+> `ruff-sync` automatically groups multiple drifts in the same file into a single annotation to reduce PR noise.
 
 ### Full Workflow Example
 
@@ -73,7 +76,13 @@ For repositories with GitHub Advanced Security enabled, upload SARIF results to
 The `|| true` ensures the upload step always runs even when `ruff-sync` exits 1 (drift detected). Without it, GitHub Actions would skip the upload step on failure.
 
 > **Why SARIF over `--output-format github`?**
-> The `github` format creates ephemeral workflow annotations that disappear once the check re-runs. SARIF findings are persisted in the Security tab, tracked as "introduced" and "resolved" across branches, and each drifted TOML key (`lint.select`, `target-version`, etc.) is a separate finding with a stable fingerprint — making it easy to trend configuration health over time.
+>
+> | Feature | `github` | `sarif` |
+> |---------|----------|---------|
+> | **PR Feedback** | Inline annotations (grouped) | Inline annotations (per-key) |
+> | **Job Summary** | ✅ Markdown table | ❌ (requires separate parsing) |
+> | **Persistence** | Ephemeral (until re-run) | Persistent (Security tab) |
+> | **Tracking** | Manual | Automated "introduced/resolved" |
 
 ---
 

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.1.5.dev4
+Version: 0.1.5.dev5
 Summary: Synchronize Ruff linter configuration across projects
 Project-URL: Homepage, https://github.com/Kilo59/ruff-sync
 Project-URL: Documentation, https://kilo59.github.io/ruff-sync/

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev5}/docs/ci-integration.md

@@ -31,8 +31,17 @@ jobs:
 
 By using `--output-format github`, `ruff-sync` will emit special workflow commands that GitHub translates into inline annotations directly on your Pull Request's file diff.
 
+> [!NOTE]
+> If multiple configuration drifts are detected in the same file, `ruff-sync` automatically groups them into a single, combined annotation to reduce visual noise and preserve your GitHub Actions annotation limits.
+
 ![GitHub PR Annotation](assets/github-pr-annotation.png)
 
+#### Job Summary
+
+In addition to inline annotations, `ruff-sync` writes a structured Markdown report to the GitHub Actions **Job Summary** page. This provides a high-level overview of all drifts detected across the entire run, making it easy to see exactly what needs to be synchronized without scrolling through log files.
+
+![GitHub Job Summary](assets/github-job-summary.png)
+
 ### SARIF Upload (GitHub Advanced Security)
 
 For repositories with [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) enabled, upload SARIF results to track drift findings in the **Security tab** and get per-key inline PR annotations:
@@ -50,7 +59,7 @@ For repositories with [GitHub Advanced Security](https://docs.github.com/en/get-
 
 The `|| true` ensures the upload step always runs even when drift is detected (exit code 1).
 
-> **Why SARIF over `--output-format github`?** The `github` format creates ephemeral PR annotations that disappear after the check re-runs. SARIF findings are persisted in the Security tab, tracked as "introduced" and "resolved" across branches, and each drifted TOML key (`lint.select`, `target-version`, etc.) appears as a separate, deduplicated finding.
+> **Why SARIF over `--output-format github`?** The `github` format is excellent for lightweight, immediate feedback with a summarized job report. However, SARIF findings are persisted in the Security tab, tracked as "introduced" and "resolved" across branches, and each drifted TOML key (`lint.select`, `target-version`, etc.) appears as a separate, deduplicated finding in the GitHub Security dashboard.
 
 ### Automated Sync PRs
 

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev5}/docs/usage.md

@@ -165,10 +165,12 @@ ruff-sync [UPSTREAM_URL...] [--to PATH] [--exclude KEY...] [--init] [--pre-commi
 * **`--exclude KEY...`**: Dotted paths of keys to keep local and never overwrite (e.g., `lint.isort`).
 * **`--init`**: Create a new `pyproject.toml` with the upstream configuration if it doesn't already exist. This automatically saves the upstream source and any other CLI flags into the `[tool.ruff-sync]` section.
 * **`--save` / `--no-save`**: Force serialization (or prevent serialization) of the provided CLI arguments (like `upstream`, `exclude`, etc.) directly into the `[tool.ruff-sync]` section of the target `pyproject.toml` for future use. Note: any credentials present in the upstream URL will cause this operation to safely abort.
-* **`--output-format [text|json|github]`**: Specify the output format for synchronization results.
+* **`--output-format [text|json|github|gitlab|sarif]`**: Specify the output format for synchronization results.
     - `text` (default): Human-readable terminal output.
     - `json`: Machine-readable JSON output for tool integration.
-    - `github`: GitHub Actions workflow commands (`::error`, `::warning`) for inline PR annotations.
+    - `github`: GitHub Actions workflow commands and Job Summary report.
+    - `gitlab`: GitLab Code Quality report (JSON format).
+    - `sarif`: Static Analysis Results Interchange Format (SARIF) for GitHub Security or GitLab SAST.
 * **`--pre-commit`**: Sync the `astral-sh/ruff-pre-commit` hook version inside `.pre-commit-config.yaml` with the project's Ruff version.
 
 ### `check`
@@ -186,7 +188,7 @@ ruff-sync check [UPSTREAM_URL...] [--semantic] [--diff] [--pre-commit]
 * **`UPSTREAM_URL...`**: The source URL(s). Optional if defined locally.
 * **`--semantic`**: Ignore "non-functional" differences like whitespace, comments, or key order. Only errors if the actual Python-level data differs.
 * **`--diff` / `--no-diff`**: Control the display of the unified diff in the terminal.
-* **`--output-format [text|json|github]`**: Specify the output format for check results. Defaults to `text`.
+* **`--output-format [text|json|github|gitlab|sarif]`**: Specify the output format for check results (defaults to `text`).
 * **`--pre-commit`**: Verify that the `astral-sh/ruff-pre-commit` hook version matches the project's Ruff version in addition to checking configuration drift. If you have `pre-commit-version-sync = true` configured in your `pyproject.toml`, the `check` command will automatically respect this setting and you do not need to pass this flag.
 
 ---

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ruff-sync"
-version = "0.1.5.dev4"
+version = "0.1.5.dev5"
 description = "Synchronize Ruff linter configuration across projects"
 keywords = ["ruff", "linter", "config", "synchronize", "python", "linting", "automation", "tomlkit", "pre-commit"]
 authors = [

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev5}/src/ruff_sync/formatters.py

@@ -5,9 +5,11 @@ from __future__ import annotations
 import hashlib
 import json
 import logging
+import os
 import pathlib
 from typing import Any, Final, Literal, Protocol, TypedDict
 
+from ruff_sync.config_io import RuffConfigFileName
 from ruff_sync.constants import OutputFormat
 
 LOGGER: Final[logging.Logger] = logging.getLogger(__name__)
@@ -150,13 +152,29 @@ class TextFormatter:
         """No-op for streaming formatters."""
 
 
+class GithubIssue(TypedDict):
+    """GitHub Action output issue."""
+
+    level: Literal["error", "warning"]
+    message: str
+    file_path: pathlib.Path | None
+    drift_key: str | None
+
+
 class GithubFormatter:
     """GitHub Actions output formatter.
 
     Emits ``::error::`` and ``::warning::`` workflow commands for inline
-    annotations.
+    annotations, and writes a Markdown report to ``GITHUB_STEP_SUMMARY``.
     """
 
+    _DEFAULT_PATH: Final[pathlib.Path] = pathlib.Path(RuffConfigFileName.PYPROJECT_TOML)
+
+    def __init__(self) -> None:
+        """Initialise an empty issue list."""
+        self._errors: list[GithubIssue] = []
+        self._warnings: list[GithubIssue] = []
+
     @staticmethod
     def _escape(value: str, is_property: bool = False) -> str:
         r"""Escapes characters for GitHub Actions workflow commands.
@@ -170,6 +188,11 @@ class GithubFormatter:
             return escaped.replace(":", "%3A").replace(",", "%2C")
         return escaped
 
+    @staticmethod
+    def _strip_status_prefix(message: str) -> str:
+        """Return the message without leading status emoji (e.g. ❌, ⚠️)."""
+        return message.removeprefix("❌ ").removeprefix("⚠️ ")
+
     def note(self, message: str) -> None:
         """Print a status note (standard stdout)."""
         print(message)
@@ -190,17 +213,17 @@ class GithubFormatter:
         check_name: str = _DEFAULT_CHECK_NAME,
         drift_key: str | None = None,
     ) -> None:
-        """Print an error message as a GitHub Action error annotation."""
+        """Accumulate an error-level finding."""
         # Delegate standard log output to the logger to preserve context
         (logger or LOGGER).error(message)
-
-        file_val = self._escape(str(file_path), is_property=True) if file_path else ""
-        file_arg = f"file={file_val},line=1," if file_path else ""
-        title_val = self._escape("Ruff Sync Error", is_property=True)
-
-        clean_msg = message.removeprefix("❌ ").removeprefix("⚠️ ")
-        escaped_msg = self._escape(clean_msg)
-        print(f"::error {file_arg}title={title_val}::{escaped_msg}")
+        self._errors.append(
+            {
+                "level": "error",
+                "message": message,
+                "file_path": file_path,
+                "drift_key": drift_key,
+            }
+        )
 
     def warning(
         self,
@@ -210,16 +233,16 @@ class GithubFormatter:
         check_name: str = _DEFAULT_CHECK_NAME,
         drift_key: str | None = None,
     ) -> None:
-        """Print a warning message as a GitHub Action warning annotation."""
+        """Accumulate a warning-level finding."""
         (logger or LOGGER).warning(message)
-
-        file_val = self._escape(str(file_path), is_property=True) if file_path else ""
-        file_arg = f"file={file_val},line=1," if file_path else ""
-        title_val = self._escape("Ruff Sync Warning", is_property=True)
-
-        clean_msg = message.removeprefix("❌ ").removeprefix("⚠️ ")
-        escaped_msg = self._escape(clean_msg)
-        print(f"::warning {file_arg}title={title_val}::{escaped_msg}")
+        self._warnings.append(
+            {
+                "level": "warning",
+                "message": message,
+                "file_path": file_path,
+                "drift_key": drift_key,
+            }
+        )
 
     def debug(self, message: str, logger: logging.Logger | None = None) -> None:
         """Print a debug message as a GitHub Action debug annotation."""
@@ -232,7 +255,75 @@ class GithubFormatter:
         print(diff_text, end="")
 
     def finalize(self) -> None:
-        """No-op for streaming formatters."""
+        """Finalize and emit all accumulated issues as GitHub workflow commands.
+
+        If multiple issues exist for a single file/level, they are combined into
+        a single multi-line annotation to reduce visual noise.
+
+        A Markdown summary is also written to ``GITHUB_STEP_SUMMARY`` if the
+        environment variable is set.
+        """
+        all_issues = self._errors + self._warnings
+
+        # 1. Emit Inline Annotations
+        self._emit_annotations()
+
+        # 2. Write Step Summary
+        self._write_summary(all_issues)
+
+    def _emit_annotations(self) -> None:
+        """Group and emit issues as GitHub Action workflow commands."""
+        for level, issues in [("error", self._errors), ("warning", self._warnings)]:
+            # Group by file path object
+            by_file: dict[pathlib.Path, list[GithubIssue]] = {}
+            for issue in issues:
+                file_key = issue["file_path"] or self._DEFAULT_PATH
+                by_file.setdefault(file_key, []).append(issue)
+
+            for file_path, file_issues in by_file.items():
+                if not file_issues:
+                    continue
+
+                title_prefix = "Error" if level == "error" else "Warning"
+                title_val = self._escape(f"Ruff Sync {title_prefix}", is_property=True)
+                file_val = self._escape(str(file_path), is_property=True)
+                file_arg = f"file={file_val},line=1,"
+
+                if len(file_issues) == 1:
+                    issue = file_issues[0]
+                    clean_msg = self._strip_status_prefix(issue["message"])
+                    escaped_msg = self._escape(clean_msg)
+                else:
+                    # Combine into a single bulleted annotation
+                    combined_msg = f"Multiple ruff-sync {level}s in {file_path}:"
+                    for issue in file_issues:
+                        clean_line = self._strip_status_prefix(issue["message"])
+                        combined_msg += f"\n- {clean_line}"
+                    escaped_msg = self._escape(combined_msg)
+
+                print(f"::{level} {file_arg}title={title_val}::{escaped_msg}")
+
+    def _write_summary(self, all_issues: list[GithubIssue]) -> None:
+        """Write a Markdown report to the GitHub Step Summary file."""
+        summary_file = os.environ.get("GITHUB_STEP_SUMMARY")
+        if not summary_file or not all_issues:
+            return
+
+        summary_path = pathlib.Path(summary_file)
+        try:
+            with summary_path.open("a", encoding="utf-8") as f:
+                f.write("### 🔄 Ruff-Sync Drift Report\n\n")
+                f.write("| Severity | Key | Message | File |\n")
+                f.write("| :--- | :--- | :--- | :--- |\n")
+                for issue in all_issues:
+                    severity = "❌ Error" if issue["level"] == "error" else "⚠️ Warning"
+                    key = issue["drift_key"] or "-"
+                    clean_msg = self._strip_status_prefix(issue["message"])
+                    file_path = issue["file_path"] or self._DEFAULT_PATH
+                    f.write(f"| {severity} | `{key}` | {clean_msg} | `{file_path.name}` |\n")
+                f.write("\n")
+        except OSError:
+            LOGGER.exception(f"Failed to write to GITHUB_STEP_SUMMARY: {summary_file}")
 
 
 class JsonFormatter:

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev5}/tests/test_formatters.py

@@ -26,9 +26,11 @@ if TYPE_CHECKING:
 # ---------------------------------------------------------------------------
 
 
-@pytest.fixture(params=[TextFormatter, GithubFormatter, JsonFormatter])
+@pytest.fixture(
+    params=[TextFormatter, GithubFormatter, JsonFormatter, GitlabFormatter, SarifFormatter]
+)
 def formatter(request: pytest.FixtureRequest) -> ResultFormatter:
-    """Fixture providing instances of all streaming formatters."""
+    """Fixture providing instances of ALL available formatters."""
     formatter_cls: type[ResultFormatter] = request.param
     return formatter_cls()
 
@@ -53,26 +55,39 @@ class TestFormatterBasics:
     ) -> None:
         """Verify methods that primarily output to stdout."""
         getattr(formatter, method)(message)
+        formatter.finalize()
         captured = capsys.readouterr().out
 
-        if isinstance(formatter, JsonFormatter):
-            # diff strip()s input in implementation
-            expected_msg = message.strip() if method == "diff" else message
-            assert json.loads(captured) == {"level": method, "message": expected_msg}
-        else:
-            # Text and Github both print raw for these
-            assert message in captured
-
-    def test_finalize_is_noop_for_streaming_formatters(
+        match formatter:
+            case JsonFormatter():
+                # diff strip()s input in implementation
+                expected_msg = message.strip() if method == "diff" else message
+                assert json.loads(captured) == {"level": method, "message": expected_msg}
+            case GitlabFormatter() | SarifFormatter():
+                # These only output on finalize, and don't output notes/success/diffs
+                # (except Gitlab potentially logging them via logger)
+                pass
+            case _:
+                # Text and Github print raw for these (Github prints notes/success immediately)
+                assert message in captured
+
+    def test_finalize_is_safe_and_reproducible(
         self,
         formatter: ResultFormatter,
         capsys: pytest.CaptureFixture[str],
     ) -> None:
-        """finalize() must not emit any output for streaming formatters."""
+        """finalize() must be safe to call and only produce output for accumulating types."""
         formatter.finalize()
         captured = capsys.readouterr()
-        assert captured.out == ""
-        assert captured.err == ""
+
+        match formatter:
+            case GithubFormatter() | GitlabFormatter() | SarifFormatter():
+                # Accumulating formatters might output empty lists or valid JSON/Markdown
+                pass
+            case _:
+                # Strictly streaming formatters should have no output on empty finalize()
+                assert captured.out == ""
+                assert captured.err == ""
 
     @pytest.mark.parametrize(
         "method, level",
@@ -97,45 +112,139 @@ class TestFormatterBasics:
         with caplog.at_level(level, logger="ruff_sync.formatters"):
             getattr(formatter, method)(message)
 
+        formatter.finalize()
         captured = capsys.readouterr().out
 
-        if isinstance(formatter, TextFormatter):
-            # TextFormatter only logs, never prints diagnostics
-            assert captured == ""
-            assert message in caplog.text
-        elif isinstance(formatter, GithubFormatter):
-            # GithubFormatter logs AND prints workflow commands
-            assert message in caplog.text
-            if method != "info":  # info only logs in GithubFormatter presently
-                assert f"::{method}" in captured
-        elif isinstance(formatter, JsonFormatter):
-            # JsonFormatter only prints JSON
-            data = json.loads(captured)
-            assert data["level"] == method
-            assert data["message"] == message
+        match formatter:
+            case TextFormatter():
+                # TextFormatter only logs, never prints diagnostics
+                assert captured == ""
+                assert message in caplog.text
+            case GithubFormatter():
+                # GithubFormatter logs AND prints workflow commands
+                assert message in caplog.text
+                if method != "info":
+                    assert f"::{method}" in captured
+            case JsonFormatter():
+                # JsonFormatter only prints JSON object per diagnostic
+                assert message in captured
+            case GitlabFormatter():
+                # Gitlab only accumulates error/warning
+                if method in ("error", "warning"):
+                    data = json.loads(captured)
+                    assert any(issue["description"] == message for issue in data)
+            case SarifFormatter():
+                # Sarif only accumulates error/warning
+                if method in ("error", "warning"):
+                    data = json.loads(captured)
+                    assert any(r["message"]["text"] == message for r in data["runs"][0]["results"])
 
 
 class TestGithubFormatterSpecifics:
+    """Tests for GithubFormatter (GitHub Actions workflow commands)."""
+
     def test_escape(self) -> None:
         """Verify GitHub-specific character escaping."""
         assert GithubFormatter._escape("a%b\rc\nd") == "a%25b%0Dc%0Ad"
         assert GithubFormatter._escape("a:b,c", is_property=True) == "a%3Ab%2Cc"
 
+    def test_note_and_success_are_streaming(self, capsys: pytest.CaptureFixture[str]) -> None:
+        """note() and success() should emit output immediately."""
+        fmt = GithubFormatter()
+        fmt.note("note msg")
+        fmt.success("success msg")
+        captured = capsys.readouterr().out
+        assert "note msg" in captured
+        assert "success msg" in captured
+
+    def test_debug_is_streaming(self, capsys: pytest.CaptureFixture[str]) -> None:
+        """debug() should emit ::debug:: immediately."""
+        fmt = GithubFormatter()
+        fmt.debug("debug msg")
+        captured = capsys.readouterr().out
+        assert "::debug::debug msg" in captured
+
+    def test_error_and_warning_are_accumulated(self, capsys: pytest.CaptureFixture[str]) -> None:
+        """error() and warning() must not emit output until finalize() is called."""
+        fmt = GithubFormatter()
+        fmt.error("error msg")
+        fmt.warning("warning msg")
+
+        captured = capsys.readouterr().out
+        assert "::error" not in captured
+        assert "::warning" not in captured
+
+        fmt.finalize()
+        captured = capsys.readouterr().out
+        assert "::error" in captured
+        assert "::warning" in captured
+
     def test_emoji_stripping(self, capsys: pytest.CaptureFixture[str]) -> None:
         """Ensure leading status icons are stripped from GitHub-specific output."""
         fmt = GithubFormatter()
         fmt.error("❌ error msg")
         fmt.warning("⚠️ warning msg")
+        fmt.finalize()
 
         captured = capsys.readouterr().out
         assert "title=Ruff Sync Error::error msg" in captured
         assert "title=Ruff Sync Warning::warning msg" in captured
 
-    def test_file_path_metadata(self, capsys: pytest.CaptureFixture[str]) -> None:
-        """Ensure file path is propagated in GitHub annotations."""
+    def test_single_issue_has_precision(self, capsys: pytest.CaptureFixture[str]) -> None:
+        """A single issue should still include line=1 and the raw message."""
         fmt = GithubFormatter()
         fmt.error("msg", file_path=pathlib.Path("src/foo.py"))
-        assert "file=src/foo.py" in capsys.readouterr().out
+        fmt.finalize()
+        captured = capsys.readouterr().out
+        assert "file=src/foo.py,line=1," in captured
+        assert "::error" in captured
+        assert "::msg" in captured
+
+    def test_multiple_issues_are_combined(self, capsys: pytest.CaptureFixture[str]) -> None:
+        """Multiple issues in the same file should be combined into one annotation."""
+        fmt = GithubFormatter()
+        path = pathlib.Path("pyproject.toml")
+        fmt.error("msg 1", file_path=path)
+        fmt.error("msg 2", file_path=path)
+        fmt.finalize()
+
+        captured = capsys.readouterr().out
+        # Should only have ONE ::error line
+        assert captured.count("::error") == 1
+        assert "Multiple ruff-sync errors in pyproject.toml" in captured
+        assert "msg 1" in captured
+        assert "msg 2" in captured
+
+    def test_step_summary_logic(
+        self,
+        tmp_path: pathlib.Path,
+        capsys: pytest.CaptureFixture[str],
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Verify the Markdown summary is written to GITHUB_STEP_SUMMARY."""
+        summary_file = tmp_path / "summary.md"
+        monkeypatch.setenv("GITHUB_STEP_SUMMARY", str(summary_file))
+
+        fmt = GithubFormatter()
+        fmt.error("error msg", drift_key="lint.select")
+        fmt.warning("warn msg", drift_key="target-version")
+        fmt.finalize()
+
+        content = summary_file.read_text()
+        assert "### 🔄 Ruff-Sync Drift Report" in content
+        assert "❌ Error" in content
+        assert "⚠️ Warning" in content
+        assert "| `lint.select` | error msg |" in content
+        assert "| `target-version` | warn msg |" in content
+
+    def test_step_summary_no_env(
+        self, tmp_path: pathlib.Path, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        """Finalize should work fine and output nothing to summary if env var is missing."""
+        fmt = GithubFormatter()
+        fmt.error("error")
+        fmt.finalize()
+        # No crash occurs
 
 
 class TestJsonFormatterSpecifics:

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev5}/uv.lock

@@ -1594,7 +1594,7 @@ wheels = [
 
 [[package]]
 name = "ruff-sync"
-version = "0.1.5.dev4"
+version = "0.1.5.dev5"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },