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

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

@@ -3,7 +3,7 @@
 
 version: 2
 updates:
-  - package-ecosystem: "pip" # Documentation: For package managers such as pipenv and poetry, you need to use the pip YAML value.
+  - package-ecosystem: "uv"
     directory: "/" # Location of package manifests
     schedule:
       interval: daily

{ruff_sync-0.0.1.dev3 → ruff_sync-0.0.2.dev0}/.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.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.0.1.dev3
+Version: 0.0.2.dev0
 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
@@ -52,6 +52,7 @@ Description-Content-Type: text/markdown
   - [Install](#install)
   - [Usage](#usage)
 - [Key Features](#key-features)
+- [CI Integration](#ci-integration)
 - [Configuration](#configuration)
 - [Contributing](#contributing)
 - [License](#license)
@@ -142,34 +143,100 @@ 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 below), 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
+
+# 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
 ```
 
 ### CLI Reference
 
+#### `ruff-sync`
+
+```
+usage: ruff-sync [-h] [--source SOURCE] [--exclude EXCLUDE [EXCLUDE ...]] [-v] [upstream]
+
+positional arguments:
+  upstream              The URL to download the pyproject.toml file from.
+                        Optional if defined in [tool.ruff-sync]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --source SOURCE       The directory or file to sync. Default: .
+  --exclude EXCLUDE [EXCLUDE ...]
+                        Exclude certain ruff config keys. Default: lint.per-file-ignores
+  -v, --verbose         Increase verbosity. -v for INFO, -vv for DEBUG.
+```
+
+#### `ruff-sync check`
+
 ```
-usage: ruff-sync [-h] [--source SOURCE] [--exclude EXCLUDE [EXCLUDE ...]] upstream
+usage: ruff-sync check [-h] [--source SOURCE] [--exclude EXCLUDE [EXCLUDE ...]] [--semantic] [--no-diff] [-v] [upstream]
 
 positional arguments:
   upstream              The URL to download the pyproject.toml file from.
+                        Optional if defined in [tool.ruff-sync]
 
 optional arguments:
   -h, --help            show this help message and exit
-  --source SOURCE       The directory to sync the pyproject.toml file to. Default: .
+  --source SOURCE       The directory or file to check. Default: .
   --exclude EXCLUDE [EXCLUDE ...]
-                        Exclude certain ruff configs. Default: lint.per-file-ignores
+                        Exclude certain ruff config keys.
+  --semantic            Ignore cosmetic differences (whitespace, comments);
+                        only fail on actual value changes.
+  --no-diff             Suppress the diff output.
+  -v, --verbose         Increase verbosity. -v for INFO, -vv for DEBUG.
 ```
 
+Exits **0** if in sync, **1** if out of sync.
+
 ## 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.
 - **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.
+- **Semantic mode** — Use `--semantic` to ignore cosmetic differences (comments, whitespace) and only fail on real value changes.
+
+## 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",
+     ...
+   ]
+```
 
 ## Configuration
 
@@ -177,6 +244,9 @@ 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]
@@ -225,9 +295,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.dev0}/README.md

@@ -22,6 +22,7 @@
   - [Install](#install)
   - [Usage](#usage)
 - [Key Features](#key-features)
+- [CI Integration](#ci-integration)
 - [Configuration](#configuration)
 - [Contributing](#contributing)
 - [License](#license)
@@ -112,34 +113,100 @@ 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 below), 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
+
+# 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
 ```
 
 ### CLI Reference
 
+#### `ruff-sync`
+
+```
+usage: ruff-sync [-h] [--source SOURCE] [--exclude EXCLUDE [EXCLUDE ...]] [-v] [upstream]
+
+positional arguments:
+  upstream              The URL to download the pyproject.toml file from.
+                        Optional if defined in [tool.ruff-sync]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --source SOURCE       The directory or file to sync. Default: .
+  --exclude EXCLUDE [EXCLUDE ...]
+                        Exclude certain ruff config keys. Default: lint.per-file-ignores
+  -v, --verbose         Increase verbosity. -v for INFO, -vv for DEBUG.
+```
+
+#### `ruff-sync check`
+
 ```
-usage: ruff-sync [-h] [--source SOURCE] [--exclude EXCLUDE [EXCLUDE ...]] upstream
+usage: ruff-sync check [-h] [--source SOURCE] [--exclude EXCLUDE [EXCLUDE ...]] [--semantic] [--no-diff] [-v] [upstream]
 
 positional arguments:
   upstream              The URL to download the pyproject.toml file from.
+                        Optional if defined in [tool.ruff-sync]
 
 optional arguments:
   -h, --help            show this help message and exit
-  --source SOURCE       The directory to sync the pyproject.toml file to. Default: .
+  --source SOURCE       The directory or file to check. Default: .
   --exclude EXCLUDE [EXCLUDE ...]
-                        Exclude certain ruff configs. Default: lint.per-file-ignores
+                        Exclude certain ruff config keys.
+  --semantic            Ignore cosmetic differences (whitespace, comments);
+                        only fail on actual value changes.
+  --no-diff             Suppress the diff output.
+  -v, --verbose         Increase verbosity. -v for INFO, -vv for DEBUG.
 ```
 
+Exits **0** if in sync, **1** if out of sync.
+
 ## 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.
 - **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.
+- **Semantic mode** — Use `--semantic` to ignore cosmetic differences (comments, whitespace) and only fail on real value changes.
+
+## 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",
+     ...
+   ]
+```
 
 ## Configuration
 
@@ -147,6 +214,9 @@ 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]
@@ -195,9 +265,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.dev0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ruff-sync"
-version = "0.0.1.dev3"
+version = "0.0.2.dev0"
 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",