ruff-sync 0.0.1.dev3__tar.gz → 0.0.2__tar.gz

{ruff_sync-0.0.1.dev3 → ruff_sync-0.0.2}/.github/dependabot.yml

@@ -1,9 +1,12 @@
 # Please see the documentation for all configuration options:
 # https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+# https://docs.astral.sh/uv/guides/integration/dependency-bots/#dependabot
 
 version: 2
 updates:
-  - package-ecosystem: "pip" # Documentation: For package managers such as pipenv and poetry, you need to use the pip YAML value.
-    directory: "/" # Location of package manifests
+  - package-ecosystem: "uv"
+    directory: "/"
     schedule:
-      interval: daily
+      interval: "weekly"
+    cooldown:
+      default-days: 7

{ruff_sync-0.0.1.dev3 → ruff_sync-0.0.2}/.github/workflows/ci.yaml

@@ -33,6 +33,7 @@ jobs:
 
   tests:
     strategy:
+      fail-fast: ${{ github.event.pull_request.draft == true }}
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 

{ruff_sync-0.0.1.dev3 → ruff_sync-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.0.1.dev3
+Version: 0.0.2
 Summary: Synchronize Ruff linter configuration across projects
 Project-URL: Homepage, https://github.com/Kilo59/ruff-sync
 Project-URL: Documentation, https://github.com/Kilo59/ruff-sync#readme
@@ -40,7 +40,9 @@ Description-Content-Type: text/markdown
 
 # ruff-sync
 
-**Keep your Ruff config consistent across every repo — automatically.**
+**Keep your Ruff config consistent across multiple projects.**
+
+`ruff-sync` is a CLI tool that pulls a canonical [Ruff](https://docs.astral.sh/ruff/) configuration from an upstream `pyproject.toml` (hosted anywhere — GitHub, GitLab, a raw URL) and merges it into your local project, preserving your comments, formatting, and project-specific overrides.
 
 ---
 
@@ -49,15 +51,15 @@ Description-Content-Type: text/markdown
 - [The Problem](#the-problem)
 - [How It Works](#how-it-works)
 - [Quick Start](#quick-start)
-  - [Install](#install)
-  - [Usage](#usage)
 - [Key Features](#key-features)
 - [Configuration](#configuration)
+- [CI Integration](#ci-integration)
+- [Example Workflow](#example-workflow)
+- [Detailed Check Logic](#detailed-check-logic)
 - [Contributing](#contributing)
+- [Dogfooding](#dogfooding)
 - [License](#license)
 
-`ruff-sync` is a CLI tool that pulls a canonical [Ruff](https://docs.astral.sh/ruff/) configuration from an upstream `pyproject.toml` (hosted anywhere — GitHub, GitLab, a raw URL) and merges it into your local project, preserving your comments, formatting, and project-specific overrides.
-
 ## The Problem
 
 If you maintain more than one Python project, you've probably copy-pasted your `[tool.ruff]` config between repos more than once. When you decide to enable a new rule or bump your target Python version, you get to do it again — in _every_ repo. Configs drift, standards diverge, and your "shared" style guide becomes a polite suggestion.
@@ -74,7 +76,7 @@ Ruff's `extend` is perfect inside a monorepo, but if your projects live in **sep
 
 **That's what `ruff-sync` does.**
 
-## How It Works
+### How It Works
 
 ```
 ┌─────────────────────────────┐
@@ -142,34 +144,32 @@ uv tool install git+https://github.com/Kilo59/ruff-sync
 # Sync from a GitHub URL (blob URLs are auto-converted to raw)
 ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml
 
+# Once configured in pyproject.toml (see Configuration), simply run:
+ruff-sync
+
 # Sync into a specific project directory
-ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml --source ./my-project
+ruff-sync --source ./my-project
 
 # Exclude specific sections from being overwritten using dotted paths
-ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml --exclude lint.per-file-ignores lint.ignore
-```
+ruff-sync --exclude lint.per-file-ignores lint.ignore
 
-### CLI Reference
+# Check if your local config is in sync (useful in CI)
+ruff-sync check https://github.com/my-org/standards/blob/main/pyproject.toml
 
+# Semantic check — ignore cosmetic differences like comments and whitespace
+ruff-sync check --semantic
 ```
-usage: ruff-sync [-h] [--source SOURCE] [--exclude EXCLUDE [EXCLUDE ...]] upstream
 
-positional arguments:
-  upstream              The URL to download the pyproject.toml file from.
-
-optional arguments:
-  -h, --help            show this help message and exit
-  --source SOURCE       The directory to sync the pyproject.toml file to. Default: .
-  --exclude EXCLUDE [EXCLUDE ...]
-                        Exclude certain ruff configs. Default: lint.per-file-ignores
-```
+Run `ruff-sync --help` for full details on all available options.
 
 ## Key Features
 
 - **Format-preserving merges** — Uses [tomlkit](https://github.com/sdispater/tomlkit) under the hood, so your comments, whitespace, and TOML structure are preserved. No reformatting surprises.
 - **GitHub URL support** — Paste a GitHub blob URL and it will automatically convert it to the raw content URL.
-- **Selective exclusions** — Keep project-specific overrides (like `target-version`) from being clobbered by the upstream config.
+- **Selective exclusions** — Keep project-specific overrides (like `per-file-ignores` or `target-version`) from being clobbered by the upstream config.
 - **Works with any host** — GitHub, GitLab, Bitbucket, or any raw URL that serves a `pyproject.toml`.
+- **CI-ready `check` command** — Verify that your local config is in sync without modifying anything. Exits 1 if out of sync, making it perfect for pre-merge gates. ([See detailed logic](#detailed-check-logic))
+- **Semantic mode** — Use `--semantic` to ignore cosmetic differences (comments, whitespace) and only fail on real value changes.
 
 ## Configuration
 
@@ -177,16 +177,51 @@ You can configure `ruff-sync` itself in your `pyproject.toml`:
 
 ```toml
 [tool.ruff-sync]
+# The source of truth for your Ruff configuration
+upstream = "https://github.com/my-org/standards/blob/main/pyproject.toml"
+
 # Use simple names for top-level keys, and dotted paths for nested keys
 exclude = [
-    "target-version",          # A top-level key under [tool.ruff]
-    "lint.per-file-ignores",   # A nested key under [tool.ruff.lint]
-    "lint.ignore"
+    "target-version",                      # Top-level [tool.ruff] key — projects target different Python versions
+    "lint.per-file-ignores",                # Project-specific file overrides
+    "lint.ignore",                         # Project-specific rule suppressions
+    "lint.isort.known-first-party",         # Every project has different first-party packages
+    "lint.flake8-tidy-imports.banned-api",  # Entire plugin section — project-specific banned APIs
+    "lint.pydocstyle.convention",          # Teams may disagree on google vs numpy vs pep257
 ]
 ```
 
-This sets the default exclusions so you don't need to pass `--exclude` on the command line every time.
-*Note: Any explicitly provided CLI arguments will override the list in `pyproject.toml`.*
+This sets the default upstream and exclusions so you don't need to pass them on the command line every time.
+*Note: Any explicitly provided CLI arguments will override the values in `pyproject.toml`.*
+
+## CI Integration
+
+The `check` command is designed for use in CI pipelines. Add it as a step to catch config drift before it merges:
+
+```yaml
+# .github/workflows/ci.yaml
+- name: Check ruff config is in sync
+  run: |
+    ruff-sync check --semantic
+```
+
+With `--semantic`, minor reformatting of your local file won't cause a false positive — only actual rule or value differences will fail the check.
+
+To see exactly what's drifted, omit `--no-diff` (the default) and the output will include a unified diff:
+
+```console
+$ ruff-sync check --semantic
+🔍 Checking Ruff sync status...
+❌ Ruff configuration at pyproject.toml is out of sync!
+--- local (semantic)
++++ upstream (semantic)
+@@ -5,6 +5,7 @@
+   "select": [
++    "PERF",
+     "RUF",
+     ...
+   ]
+```
 
 ## Example Workflow
 
@@ -203,6 +238,44 @@ git diff pyproject.toml  # review the changes
 git commit -am "sync ruff config from upstream"
 ```
 
+## Detailed Check Logic
+
+When you run `ruff-sync check`, it follows this process to determine if your project has drifted from the upstream source:
+
+```mermaid
+flowchart TD
+    Start([Start]) --> Local[Read Local pyproject.toml]
+    Local --> Upstream[Download Upstream pyproject.toml]
+    Upstream --> Extract[Extract tool.ruff section]
+    Extract --> Exclude[Apply Exclusions]
+    Exclude --> Merge[Perform in-memory Merge]
+
+    subgraph Comparison [Comparison Logic]
+        direction TB
+        SemanticNode{--semantic?}
+        SemanticNode -- Yes --> Unwrap[Unwrap TOML objects to Python Dicts]
+        Unwrap --> CompareVal[Compare Key/Value Pairs]
+        SemanticNode -- No --> CompareFull[Compare Full File Strings]
+    end
+
+    Merge --> Comparison
+
+    CompareVal --> ResultNode{Match?}
+    CompareFull --> ResultNode
+
+    ResultNode -- Yes --> Success([Exit 0: In Sync])
+    ResultNode -- No --> Diff[Generate Diff]
+    Diff --> Fail([Exit 1: Out of Sync])
+
+    %% Styling
+    style Start fill:#4a90e2,color:#fff,stroke:#357abd
+    style Success fill:#48c774,color:#fff,stroke:#36975a
+    style Fail fill:#f14668,color:#fff,stroke:#b2334b
+    style ResultNode fill:#ffdd57,color:#4a4a4a,stroke:#d4b106
+    style Comparison fill:none,stroke:#9e9e9e,stroke-dasharray: 5 5,stroke-width:2px
+    style SemanticNode fill:#f4f4f4,color:#363636,stroke:#dbdbdb
+```
+
 ## Contributing
 
 This project uses:
@@ -225,9 +298,15 @@ uv run pytest -vv           # test
 
 ## Dogfooding
 
-To see `ruff-sync` in action on a complex, real-world configuration, you can "dogfood" it by syncing this project's own `pyproject.toml` with a large upstream config like Pydantic's.
+To see `ruff-sync` in action, you can "dogfood" it on this project's own config.
+
+**Check if this project is in sync with its upstream:**
+
+```console
+./scripts/dogfood_check.sh
+```
 
-We've provided a script to make this easy:
+**Or sync from a large upstream like Pydantic's config:**
 
 ```console
 ./scripts/dogfood.sh

{ruff_sync-0.0.1.dev3 → ruff_sync-0.0.2}/README.md

@@ -10,7 +10,9 @@
 
 # ruff-sync
 
-**Keep your Ruff config consistent across every repo — automatically.**
+**Keep your Ruff config consistent across multiple projects.**
+
+`ruff-sync` is a CLI tool that pulls a canonical [Ruff](https://docs.astral.sh/ruff/) configuration from an upstream `pyproject.toml` (hosted anywhere — GitHub, GitLab, a raw URL) and merges it into your local project, preserving your comments, formatting, and project-specific overrides.
 
 ---
 
@@ -19,15 +21,15 @@
 - [The Problem](#the-problem)
 - [How It Works](#how-it-works)
 - [Quick Start](#quick-start)
-  - [Install](#install)
-  - [Usage](#usage)
 - [Key Features](#key-features)
 - [Configuration](#configuration)
+- [CI Integration](#ci-integration)
+- [Example Workflow](#example-workflow)
+- [Detailed Check Logic](#detailed-check-logic)
 - [Contributing](#contributing)
+- [Dogfooding](#dogfooding)
 - [License](#license)
 
-`ruff-sync` is a CLI tool that pulls a canonical [Ruff](https://docs.astral.sh/ruff/) configuration from an upstream `pyproject.toml` (hosted anywhere — GitHub, GitLab, a raw URL) and merges it into your local project, preserving your comments, formatting, and project-specific overrides.
-
 ## The Problem
 
 If you maintain more than one Python project, you've probably copy-pasted your `[tool.ruff]` config between repos more than once. When you decide to enable a new rule or bump your target Python version, you get to do it again — in _every_ repo. Configs drift, standards diverge, and your "shared" style guide becomes a polite suggestion.
@@ -44,7 +46,7 @@ Ruff's `extend` is perfect inside a monorepo, but if your projects live in **sep
 
 **That's what `ruff-sync` does.**
 
-## How It Works
+### How It Works
 
 ```
 ┌─────────────────────────────┐
@@ -112,34 +114,32 @@ uv tool install git+https://github.com/Kilo59/ruff-sync
 # Sync from a GitHub URL (blob URLs are auto-converted to raw)
 ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml
 
+# Once configured in pyproject.toml (see Configuration), simply run:
+ruff-sync
+
 # Sync into a specific project directory
-ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml --source ./my-project
+ruff-sync --source ./my-project
 
 # Exclude specific sections from being overwritten using dotted paths
-ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml --exclude lint.per-file-ignores lint.ignore
-```
+ruff-sync --exclude lint.per-file-ignores lint.ignore
 
-### CLI Reference
+# Check if your local config is in sync (useful in CI)
+ruff-sync check https://github.com/my-org/standards/blob/main/pyproject.toml
 
+# Semantic check — ignore cosmetic differences like comments and whitespace
+ruff-sync check --semantic
 ```
-usage: ruff-sync [-h] [--source SOURCE] [--exclude EXCLUDE [EXCLUDE ...]] upstream
 
-positional arguments:
-  upstream              The URL to download the pyproject.toml file from.
-
-optional arguments:
-  -h, --help            show this help message and exit
-  --source SOURCE       The directory to sync the pyproject.toml file to. Default: .
-  --exclude EXCLUDE [EXCLUDE ...]
-                        Exclude certain ruff configs. Default: lint.per-file-ignores
-```
+Run `ruff-sync --help` for full details on all available options.
 
 ## Key Features
 
 - **Format-preserving merges** — Uses [tomlkit](https://github.com/sdispater/tomlkit) under the hood, so your comments, whitespace, and TOML structure are preserved. No reformatting surprises.
 - **GitHub URL support** — Paste a GitHub blob URL and it will automatically convert it to the raw content URL.
-- **Selective exclusions** — Keep project-specific overrides (like `target-version`) from being clobbered by the upstream config.
+- **Selective exclusions** — Keep project-specific overrides (like `per-file-ignores` or `target-version`) from being clobbered by the upstream config.
 - **Works with any host** — GitHub, GitLab, Bitbucket, or any raw URL that serves a `pyproject.toml`.
+- **CI-ready `check` command** — Verify that your local config is in sync without modifying anything. Exits 1 if out of sync, making it perfect for pre-merge gates. ([See detailed logic](#detailed-check-logic))
+- **Semantic mode** — Use `--semantic` to ignore cosmetic differences (comments, whitespace) and only fail on real value changes.
 
 ## Configuration
 
@@ -147,16 +147,51 @@ You can configure `ruff-sync` itself in your `pyproject.toml`:
 
 ```toml
 [tool.ruff-sync]
+# The source of truth for your Ruff configuration
+upstream = "https://github.com/my-org/standards/blob/main/pyproject.toml"
+
 # Use simple names for top-level keys, and dotted paths for nested keys
 exclude = [
-    "target-version",          # A top-level key under [tool.ruff]
-    "lint.per-file-ignores",   # A nested key under [tool.ruff.lint]
-    "lint.ignore"
+    "target-version",                      # Top-level [tool.ruff] key — projects target different Python versions
+    "lint.per-file-ignores",                # Project-specific file overrides
+    "lint.ignore",                         # Project-specific rule suppressions
+    "lint.isort.known-first-party",         # Every project has different first-party packages
+    "lint.flake8-tidy-imports.banned-api",  # Entire plugin section — project-specific banned APIs
+    "lint.pydocstyle.convention",          # Teams may disagree on google vs numpy vs pep257
 ]
 ```
 
-This sets the default exclusions so you don't need to pass `--exclude` on the command line every time.
-*Note: Any explicitly provided CLI arguments will override the list in `pyproject.toml`.*
+This sets the default upstream and exclusions so you don't need to pass them on the command line every time.
+*Note: Any explicitly provided CLI arguments will override the values in `pyproject.toml`.*
+
+## CI Integration
+
+The `check` command is designed for use in CI pipelines. Add it as a step to catch config drift before it merges:
+
+```yaml
+# .github/workflows/ci.yaml
+- name: Check ruff config is in sync
+  run: |
+    ruff-sync check --semantic
+```
+
+With `--semantic`, minor reformatting of your local file won't cause a false positive — only actual rule or value differences will fail the check.
+
+To see exactly what's drifted, omit `--no-diff` (the default) and the output will include a unified diff:
+
+```console
+$ ruff-sync check --semantic
+🔍 Checking Ruff sync status...
+❌ Ruff configuration at pyproject.toml is out of sync!
+--- local (semantic)
++++ upstream (semantic)
+@@ -5,6 +5,7 @@
+   "select": [
++    "PERF",
+     "RUF",
+     ...
+   ]
+```
 
 ## Example Workflow
 
@@ -173,6 +208,44 @@ git diff pyproject.toml  # review the changes
 git commit -am "sync ruff config from upstream"
 ```
 
+## Detailed Check Logic
+
+When you run `ruff-sync check`, it follows this process to determine if your project has drifted from the upstream source:
+
+```mermaid
+flowchart TD
+    Start([Start]) --> Local[Read Local pyproject.toml]
+    Local --> Upstream[Download Upstream pyproject.toml]
+    Upstream --> Extract[Extract tool.ruff section]
+    Extract --> Exclude[Apply Exclusions]
+    Exclude --> Merge[Perform in-memory Merge]
+
+    subgraph Comparison [Comparison Logic]
+        direction TB
+        SemanticNode{--semantic?}
+        SemanticNode -- Yes --> Unwrap[Unwrap TOML objects to Python Dicts]
+        Unwrap --> CompareVal[Compare Key/Value Pairs]
+        SemanticNode -- No --> CompareFull[Compare Full File Strings]
+    end
+
+    Merge --> Comparison
+
+    CompareVal --> ResultNode{Match?}
+    CompareFull --> ResultNode
+
+    ResultNode -- Yes --> Success([Exit 0: In Sync])
+    ResultNode -- No --> Diff[Generate Diff]
+    Diff --> Fail([Exit 1: Out of Sync])
+
+    %% Styling
+    style Start fill:#4a90e2,color:#fff,stroke:#357abd
+    style Success fill:#48c774,color:#fff,stroke:#36975a
+    style Fail fill:#f14668,color:#fff,stroke:#b2334b
+    style ResultNode fill:#ffdd57,color:#4a4a4a,stroke:#d4b106
+    style Comparison fill:none,stroke:#9e9e9e,stroke-dasharray: 5 5,stroke-width:2px
+    style SemanticNode fill:#f4f4f4,color:#363636,stroke:#dbdbdb
+```
+
 ## Contributing
 
 This project uses:
@@ -195,9 +268,15 @@ uv run pytest -vv           # test
 
 ## Dogfooding
 
-To see `ruff-sync` in action on a complex, real-world configuration, you can "dogfood" it by syncing this project's own `pyproject.toml` with a large upstream config like Pydantic's.
+To see `ruff-sync` in action, you can "dogfood" it on this project's own config.
+
+**Check if this project is in sync with its upstream:**
+
+```console
+./scripts/dogfood_check.sh
+```
 
-We've provided a script to make this easy:
+**Or sync from a large upstream like Pydantic's config:**
 
 ```console
 ./scripts/dogfood.sh

{ruff_sync-0.0.1.dev3 → ruff_sync-0.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ruff-sync"
-version = "0.0.1.dev3"
+version = "0.0.2"
 description = "Synchronize Ruff linter configuration across projects"
 keywords = ["ruff", "linter", "config", "synchronize", "python", "linting", "automation", "tomlkit"]
 authors = [
@@ -43,6 +43,7 @@ dev = [
     "coverage>=7.4.4",
     "invoke>=2.2.0",
     "mypy>=1.10.0",
+    "packaging>=26.0",
     "pre-commit>=3.7.0",
     "pyfakefs>=5.4.1",
     "pytest>=8.0.0",
@@ -80,7 +81,7 @@ exclude = ["target-version", "line-length", "lint.per-file-ignores", "lint.ignor
 
 [tool.ruff]
 target-version = "py310"
-line-length = 90
+line-length = 100
 
 [tool.ruff.lint]
 select = [