ruff-sync 0.1.4.dev0__tar.gz → 0.1.4.dev1__tar.gz

ruff_sync-0.1.4.dev1/.agents/skills/ruff-sync-usage/references/ci-integration.md

@@ -0,0 +1,213 @@
+# CI Integration Recipes
+
+## GitHub Actions
+
+### Basic Drift Check
+
+Add this step to any existing workflow (e.g., `.github/workflows/ci.yaml`):
+
+```yaml
+- name: Check Ruff config is in sync
+  run: ruff-sync check --semantic --output-format github
+```
+
+`--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.
+
+### Full Workflow Example
+
+Uses [`astral-sh/setup-uv`](https://github.com/astral-sh/setup-uv) — the official action that installs uv, adds it to PATH, and handles caching. No separate `setup-python` step needed.
+
+```yaml
+name: Ruff sync check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ruff-sync-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.10.x"   # pin to a minor range; Dependabot can keep this current
+
+      - name: Install ruff-sync
+        run: uv tool install ruff-sync
+
+      - name: Check Ruff config is in sync with upstream
+        run: ruff-sync check --semantic --output-format github
+```
+
+### With Pre-commit Sync Check
+
+To also verify the pre-commit hook version, add the `--pre-commit` flag:
+
+```yaml
+- name: Check Ruff config and pre-commit hook
+  run: ruff-sync check --semantic --pre-commit --output-format github
+```
+
+(Note: For better consistency, you can instead set `pre-commit-version-sync = true` in your `pyproject.toml` — then `ruff-sync check --semantic` will automatically include this check.)
+
+### SARIF Upload (GitHub Advanced Security)
+
+For repositories with GitHub Advanced Security enabled, upload SARIF results to track drift findings in the **Security tab** and get per-key inline PR annotations that persist across runs:
+
+```yaml
+- name: Check Ruff config (SARIF)
+  run: ruff-sync check --output-format sarif > ruff-sync.sarif || true
+
+- name: Upload SARIF results
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: ruff-sync.sarif
+    category: ruff-sync
+```
+
+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.
+
+---
+
+## GitLab CI
+
+Use the official [`ghcr.io/astral-sh/uv`](https://docs.astral.sh/uv/guides/integration/gitlab/) image — uv is already on the `PATH`, no install step needed.
+
+```yaml
+variables:
+  UV_VERSION: "0.10"
+  PYTHON_VERSION: "3.12"
+  BASE_LAYER: alpine
+  UV_LINK_MODE: copy   # required: GitLab mounts build dir separately
+
+ruff-sync-check:
+  stage: lint
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+  script:
+    - uvx ruff-sync check --semantic --output-format gitlab > gl-code-quality-report.json
+  artifacts:
+    when: always
+    reports:
+      codequality: gl-code-quality-report.json
+    paths:
+      - gl-code-quality-report.json
+    expire_in: 1 week
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+```
+
+### GitLab SAST Report / SARIF (Ultimate tier)
+
+Use `--output-format sarif` to feed the GitLab [Security & Compliance dashboard](https://docs.gitlab.com/user/application_security/) via the `sast` artifact report type:
+
+```yaml
+variables:
+  UV_VERSION: "0.10"
+  PYTHON_VERSION: "3.12"
+  BASE_LAYER: alpine
+  UV_LINK_MODE: copy   # required: GitLab mounts build dir separately
+
+ruff-sync-sarif:
+  stage: lint
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+  script:
+    - uvx ruff-sync check --output-format sarif > ruff-sync.sarif
+  artifacts:
+    when: always          # Upload even when ruff-sync exits 1 (drift detected)
+    reports:
+      sast: ruff-sync.sarif
+    paths:
+      - ruff-sync.sarif
+    expire_in: 1 week
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+```
+
+> **Why SARIF over `--output-format gitlab` (codequality)?**
+>
+> | Concern | `codequality` | `sarif` |
+> |---------|--------------|--------|
+> | GitLab tier | Free (MR widget), Ultimate (inline diff) | Ultimate (Security dashboard) |
+> | GitHub support | ❌ | ✅ via `upload-sarif` |
+> | Per-key findings | ❌ one issue per file | ✅ one finding per drifted TOML key |
+> | Finding persistence | MR widget only | Security tab, tracked across branches |
+> | Portability | GitLab only | GitHub, GitLab, SonarQube, IDE extensions |
+>
+> **Rule of thumb**: use `codequality` for lightweight GitLab-native linting feedback; use `sarif` when you need cross-platform compatibility or want findings tracked in a security/code-scanning dashboard.
+
+---
+
+## Pre-commit Hook
+
+Run `ruff-sync check` as a pre-commit hook to catch drift before every commit:
+
+```yaml
+# .pre-commit-config.yaml
+- repo: https://github.com/Kilo59/ruff-sync
+  rev: v0.1.3   # pin to a release tag
+  hooks:
+    - id: ruff-sync-check
+```
+
+The hook runs `ruff-sync check --semantic` automatically. Update `rev` to the latest ruff-sync version.
+
+---
+
+## Makefile
+
+```makefile
+.PHONY: sync-check sync
+
+sync-check:
+	ruff-sync check --semantic
+
+sync:
+	ruff-sync
+	git diff pyproject.toml
+```
+
+---
+
+## Deciding: `--semantic` vs. Full String Check
+
+| Mode | Fails on | Use when |
+|------|---------|---------|
+| `ruff-sync check --semantic` | Value/rule differences only | CI — avoids false positives from local comment edits |
+| `ruff-sync check` | Any string difference (comments, whitespace, values) | Enforcing exact config file consistency |
+
+Recommendation: **use `--semantic` in CI** and save the full-string check for auditing purposes.
+
+---
+
+## Dogfooding (Self-Check)
+
+If `ruff-sync` is configured in the project's own `pyproject.toml` (the standard case), just run:
+
+```bash
+ruff-sync check
+```
+
+No URL argument needed — it reads `upstream` from `[tool.ruff-sync]`.
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|----------|
+| **0** | In sync — no drift detected |
+| **1** | Config drift — `[tool.ruff]` values differ from upstream |
+| **2** | CLI usage error — invalid arguments (reserved by argparse) |
+| **3** | Pre-commit hook drift — use `--pre-commit` flag to enable this check |
+| **4** | Upstream unreachable — HTTP error or network failure |
+
+All non-zero codes cause a CI step to fail, which is the desired behaviour. To diagnose which failure occurred, check the exit code with `echo $?` after the `ruff-sync check` call.

{ruff_sync-0.1.4.dev0 → ruff_sync-0.1.4.dev1}/.pre-commit-config.yaml

@@ -28,7 +28,7 @@ repos:
         types_or: [yaml, json]
         exclude: .agents/skills/mkdocs-generation/templates/mkdocs.yml
   - repo: https://github.com/rhysd/actionlint
-    rev: v1.7.11
+    rev: v1.7.12
     hooks:
       - id: actionlint
         exclude: .github/workflows/complexity.yaml

{ruff_sync-0.1.4.dev0 → ruff_sync-0.1.4.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.1.4.dev0
+Version: 0.1.4.dev1
 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.4.dev1/docs/ci-integration.md

@@ -0,0 +1,170 @@
+# CI Integration
+
+`ruff-sync` is designed to be run in CI pipelines to ensure that all repositories in an organization stay in sync with the central standards.
+
+## Usage in CI
+
+The best way to use `ruff-sync` in CI is with the `check` command. If the configuration has drifted, `ruff-sync check` will exit with a non-zero code, failing the build.
+
+### GitHub Actions
+
+We recommend using `uv` to run `ruff-sync` in GitHub Actions.
+
+#### Basic Check
+
+```yaml
+name: "Standards Check"
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  ruff-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Check Ruff Config
+        run: uvx ruff-sync check --semantic --output-format github
+```
+
+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.
+
+![GitHub PR Annotation](assets/github-pr-annotation.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:
+
+```yaml
+- name: Check Ruff config (SARIF)
+  run: ruff-sync check --output-format sarif > ruff-sync.sarif || true
+
+- name: Upload SARIF results
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: ruff-sync.sarif
+    category: ruff-sync
+```
+
+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.
+
+### Automated Sync PRs
+
+Instead of just checking, you can have a bot automatically open a PR when the upstream configuration changes.
+
+```yaml
+name: "Upstream Sync"
+
+on:
+  schedule:
+    - cron: '0 0 * * 1' # Every Monday at midnight
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Pull upstream
+        run: uvx ruff-sync
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: "chore: sync ruff configuration from upstream"
+          title: "chore: sync ruff configuration"
+          body: "This PR synchronizes the Ruff configuration with the upstream source."
+          branch: "ruff-sync-update"
+```
+
+### GitLab CI
+
+#### Code Quality Report (Free tier)
+
+Use `--output-format gitlab` to produce a [GitLab Code Quality](https://docs.gitlab.com/ci/testing/code_quality/) report. This appears in the MR widget on the Free tier and as inline diff annotations on Ultimate.
+
+```yaml
+ruff-sync-check:
+  stage: lint
+  image: ghcr.io/astral-sh/uv:latest
+  script:
+    - uvx ruff-sync check --semantic --output-format gitlab > gl-code-quality-report.json
+  artifacts:
+    when: always          # Upload even when ruff-sync exits 1 (drift detected)
+    reports:
+      codequality: gl-code-quality-report.json
+    paths:
+      - gl-code-quality-report.json   # Also expose for download/browsing
+    expire_in: 1 week
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+```
+
+#### SAST Report / SARIF (Ultimate tier)
+
+Use `--output-format sarif` to feed the GitLab [Security & Compliance dashboard](https://docs.gitlab.com/user/application_security/) via the `sast` artifact report type:
+
+```yaml
+ruff-sync-sarif:
+  stage: lint
+  image: ghcr.io/astral-sh/uv:latest
+  script:
+    - uvx ruff-sync check --output-format sarif > ruff-sync.sarif
+  artifacts:
+    when: always
+    reports:
+      sast: ruff-sync.sarif
+    paths:
+      - ruff-sync.sarif
+    expire_in: 1 week
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+```
+
+> **Why SARIF over `codequality`?** SARIF is a portable, vendor-neutral format — the same file works for GitHub Advanced Security, GitLab SAST, SonarQube, and IDE extensions. It also carries per-key granularity: each drifted TOML key is a separate finding with a stable fingerprint that is tracked as "introduced" or "resolved" across pipeline runs. Use `codequality` for lightweight GitLab-native linting feedback; use `sarif` when you need cross-platform compatibility or want findings tracked in a security dashboard.
+
+---
+
+You can use `ruff-sync` with `pre-commit` to ensure your configuration is always in sync before pushing.
+
+See the [Pre-commit Guide](pre-commit.md) for details on using the official hooks.
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|----------|
+| **0** | In sync — no drift detected |
+| **1** | Config drift — `[tool.ruff]` values differ from upstream |
+| **2** | CLI usage error — invalid arguments (reserved by argparse) |
+| **3** | Pre-commit hook drift — use `--pre-commit` flag to enable this check |
+| **4** | Upstream unreachable — HTTP error or network failure |
+
+All non-zero codes cause a CI step to fail. Use `artifacts: when: always` (GitLab) or `if: always()` (GitHub Actions) to ensure report artifacts are uploaded even when the job fails.
+
+---
+
+## 💡 Best Practices
+
+> [!TIP]
+> Read the complete [Best Practices](best-practices.md) guide for a broader look at organizing `ruff-sync` deployments, including when semantic checks should be blocking vs. informational.
+
+### Use `--semantic`
+
+In CI, you usually only care about the functional configuration. Using `--semantic` ensures that minor formatting changes don't break your builds, while still guaranteeing that the actual rules are identical.
+
+### Handle Exclusions Properly
+
+If your project intentionally diverges from the upstream (e.g., using different `per-file-ignores` or ignoring a specific rule), ensure those overrides are listed in the `[tool.ruff-sync]` `exclude` list in your `pyproject.toml`.
+
+The `check` command respects your local `exclude` list. If you exclude a setting, `ruff-sync check` will completely ignore it when comparing against the upstream, ensuring that intended deviations never cause CI to fail!
+
+### Use a Dedicated Workflow
+
+Running `ruff-sync` as a separate job in your linting workflow makes it easy to identify when a failure is due to configuration drift rather than a code quality issue.

{ruff_sync-0.1.4.dev0 → ruff_sync-0.1.4.dev1}/pyproject.toml

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

{ruff_sync-0.1.4.dev0 → ruff_sync-0.1.4.dev1}/src/ruff_sync/cli.py

@@ -506,7 +506,7 @@ def main() -> int:
     except UpstreamError as e:
         for url, err in e.errors:
             LOGGER.error(f"❌ Failed to fetch {url}: {err}")  # noqa: TRY400
-        return 1
+        return 4
 
 
 if __name__ == "__main__":

{ruff_sync-0.1.4.dev0 → ruff_sync-0.1.4.dev1}/src/ruff_sync/constants.py

@@ -53,6 +53,7 @@ class OutputFormat(str, enum.Enum):
     JSON = "json"
     GITHUB = "github"
     GITLAB = "gitlab"
+    SARIF = "sarif"
 
     @override
     def __str__(self) -> str:

{ruff_sync-0.1.4.dev0 → ruff_sync-0.1.4.dev1}/src/ruff_sync/core.py

@@ -875,9 +875,11 @@ def _print_diff(
 
 
 def _check_pre_commit_sync(args: Arguments, fmt: ResultFormatter) -> int | None:
-    """Return exit code 2 if pre-commit hook version is out of sync, otherwise None.
+    """Return exit code 3 if pre-commit hook version is out of sync, otherwise None.
 
     Shared helper to avoid duplicating the pre-commit synchronization logic.
+    Exit code 3 is reserved for pre-commit hook drift to avoid collision with
+    argparse (2) and config drift (1).
     """
     if getattr(args, "pre_commit", False) and not sync_pre_commit(pathlib.Path.cwd(), dry_run=True):
         repo_root = pathlib.Path.cwd()
@@ -888,10 +890,112 @@ def _check_pre_commit_sync(args: Arguments, fmt: ResultFormatter) -> int | None:
             logger=LOGGER,
             file_path=file_path,
         )
-        return 2
+        return 3
     return None
 
 
+def _find_changed_keys(
+    source: Any,
+    merged: Any,
+    prefix: str = "",
+) -> list[str]:
+    """Return a list of dotted TOML keys that differ between *source* and *merged*.
+
+    Recursively walks both tables and returns keys whose leaf values have
+    changed or that are present only in *merged* (added by upstream).  Keys
+    that exist only in *source* (local-only additions) are intentionally
+    excluded — ruff-sync never removes local keys.
+
+    Args:
+        source: The original (local) TOML table or value.
+        merged: The merged (upstream-applied) TOML table or value.
+        prefix: Dotted key prefix built up during recursion.
+
+    Returns:
+        A list of dotted key paths, e.g. ``["lint.select", "target-version"]``.
+    """
+    changed: list[str] = []
+
+    source_is_mapping = isinstance(source, Mapping)
+    merged_is_mapping = isinstance(merged, Mapping)
+
+    if source_is_mapping and merged_is_mapping:
+        for key, merged_val in merged.items():
+            full_key = f"{prefix}.{key}" if prefix else key
+            source_val = source.get(key)
+            if source_val is None and key not in source:
+                # Key is new (only in merged)
+                changed.append(full_key)
+            else:
+                # Unwrap tomlkit proxy objects before comparing.
+                # Note: source_val is always set here because the key exists in source
+                # (the is None + key not in guard above handles the absent case).
+                src_unwrapped = (
+                    source_val.unwrap()
+                    if source_val is not None and hasattr(source_val, "unwrap")
+                    else source_val
+                )
+                mrg_unwrapped = merged_val.unwrap() if hasattr(merged_val, "unwrap") else merged_val
+                nested = _find_changed_keys(src_unwrapped, mrg_unwrapped, prefix=full_key)
+                if nested:
+                    changed.extend(nested)
+                elif src_unwrapped != mrg_unwrapped:
+                    changed.append(full_key)
+    elif source_is_mapping != merged_is_mapping:
+        # Structural type mismatch (table vs scalar or vice-versa): treat the
+        # whole node as changed rather than attempting a meaningless value
+        # comparison between incompatible TOML node types.
+        changed.append(prefix or ".")
+    else:
+        # Both are leaf values — compare directly.
+        src_unwrapped = source.unwrap() if hasattr(source, "unwrap") else source
+        mrg_unwrapped = merged.unwrap() if hasattr(merged, "unwrap") else merged
+        if src_unwrapped != mrg_unwrapped:
+            changed.append(prefix or ".")
+
+    return changed
+
+
+def _report_drift(
+    fmt: ResultFormatter,
+    rel_path: pathlib.Path,
+    source_doc: TOMLDocument,
+    merged_doc: TOMLDocument,
+    is_ruff_toml: bool,
+) -> None:
+    """Report configuration drift by emitting one error per changed key.
+
+    Emits one ``fmt.error()`` call per differing dotted key so that structured
+    formatters (SARIF, GitLab, JSON) can build per-key fingerprints.  If no
+    granular keys are found (whitespace-only diff), falls back to a single
+    generic error.
+    """
+    if is_ruff_toml:
+        source_section: Any = source_doc
+        merged_section: Any = merged_doc
+    else:
+        source_section = source_doc.get("tool", {}).get("ruff") or {}
+        merged_section = merged_doc.get("tool", {}).get("ruff") or {}
+    changed_keys = sorted(set(_find_changed_keys(source_section, merged_section)))
+
+    if changed_keys:
+        for drift_key in changed_keys:
+            fmt.error(
+                f"\u274c Key '{drift_key}' in {rel_path} is out of sync! "
+                "Run `ruff-sync` to update.",
+                file_path=rel_path,
+                logger=LOGGER,
+                drift_key=drift_key,
+            )
+    else:
+        # Structural change only (e.g. whitespace) — single generic error.
+        fmt.error(
+            f"\u274c Ruff configuration at {rel_path} is out of sync! Run `ruff-sync` to update.",
+            file_path=rel_path,
+            logger=LOGGER,
+        )
+
+
 async def check(
     args: Arguments,
 ) -> int:
@@ -974,10 +1078,13 @@ async def check(
             rel_path = _source_toml_path.relative_to(pathlib.Path.cwd())
         except ValueError:
             rel_path = _source_toml_path
-        fmt.error(
-            f"❌ Ruff configuration at {rel_path} is out of sync! Run `ruff-sync` to update.",
-            file_path=rel_path,
-            logger=LOGGER,
+
+        _report_drift(
+            fmt=fmt,
+            rel_path=rel_path,
+            source_doc=source_doc,
+            merged_doc=merged_doc,
+            is_ruff_toml=is_ruff_toml_file(_source_toml_path.name),
         )
 
         if args.diff: