ruff-sync 0.0.2.dev0__tar.gz → 0.0.3__tar.gz

{ruff_sync-0.0.2.dev0 → ruff_sync-0.0.3}/.agents/TESTING.md

@@ -13,7 +13,7 @@ This document defines the mandatory testing standards and patterns for the `ruff
 
 ## 2. Tooling and Environment
 
-- **Execution**: Always run tests using `poetry run pytest -vv`.
+- **Execution**: Always run tests using `uv run pytest -vv`.
 - **Async Tests**: We use `pytest-asyncio` in **strict mode**.
   - Always decorate async tests with `@pytest.mark.asyncio`.
 - **HTTP Mocking**: Use [respx](https://github.com/lundberg/respx) for all network interactions.
@@ -79,7 +79,7 @@ Each test case consists of three files in `tests/lifecycle_tomls/`:
 ### Scaffolding New Cases
 Use the provided Invoke task to create a new case from a template:
 ```bash
-poetry run invoke new-case --name <case_name> --description "Description of the edge case"
+uv run invoke new-case --name <case_name> --description "Description of the edge case"
 ```
 
 ## 5. Standard Assertions for Merges
@@ -109,5 +109,5 @@ def test_my_edge_case():
 ## 6. Code Coverage
 
 We target **high coverage** for `ruff_sync.py`.
-- Run coverage locally: `poetry run coverage run -m pytest -vv && poetry run coverage report`
+- Run coverage locally: `uv run coverage run -m pytest -vv && uv run coverage report`
 - New features MUST include unit tests in `tests/test_basic.py` or specialized files like `tests/test_whitespace.py` if they involve formatting logic.

{ruff_sync-0.0.2.dev0 → ruff_sync-0.0.3}/.agents/workflows/add-test-case.md

@@ -12,7 +12,7 @@ Follow these steps to add a new end-to-end (E2E) test case for `ruff-sync` to te
 // turbo
 1. Run the `new-case` task to generate the file triple:
    ```bash
-   poetry run invoke new-case --name <case_name> --description "Description of the test case"
+   uv run invoke new-case --name <case_name> --description "Description of the test case"
    ```
    *Replace `<case_name>` with a simple name (e.g., `dotted_keys`). This creates files in `tests/lifecycle_tomls/`.*
 
@@ -25,7 +25,7 @@ Follow these steps to add a new end-to-end (E2E) test case for `ruff-sync` to te
 // turbo
 1. Execute the tests to ensure the new case is picked up:
    ```bash
-   poetry run pytest -vv tests/test_e2e.py
+   uv run pytest -vv tests/test_e2e.py
    ```
    *The E2E suite automatically discovers all file triples in the `lifecycle_tomls/` directory.*
 
@@ -33,6 +33,6 @@ Follow these steps to add a new end-to-end (E2E) test case for `ruff-sync` to te
 // turbo
 1. Ensure the new TOML files don't break any project rules:
    ```bash
-   poetry run invoke lint --check
-   poetry run invoke types
+   uv run invoke lint --check
+   uv run invoke types
    ```

ruff_sync-0.0.3/.git-blame-ignore-revs

@@ -0,0 +1,20 @@
+# .git-blame-ignore-revs
+#
+# This file contains a list of Git commit hashes that should be ignored by
+# `git blame`. It is primarily used for large-scale refactorings, purely
+# stylistic changes, or mass-formatting that would otherwise "pollute" the
+# blame history without changing the actual logic.
+#
+# Use this file VERY SELECTIVELY. Only include commits that are truly
+# non-functional and where seeing the original author in the blame history
+# provides no useful context for the code's behavior.
+#
+# Entries should follow this pattern:
+#
+# # <Brief description of the change>
+# # PR: https://github.com/Kilo59/ruff-sync/pull/<PR_NUMBER>
+# <COMMIT_HASH>
+
+# Changing linelength to 100, other changes are tests and readme only
+# PR: https://github.com/Kilo59/ruff-sync/pull/76
+75f9e34ced8537a32cdc62f85ae0f8e464756cee

{ruff_sync-0.0.2.dev0 → ruff_sync-0.0.3}/.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: "uv"
-    directory: "/" # Location of package manifests
+    directory: "/"
     schedule:
-      interval: daily
+      interval: "weekly"
+    cooldown:
+      default-days: 7

{ruff_sync-0.0.2.dev0 → ruff_sync-0.0.3}/.github/workflows/ci.yaml

@@ -64,10 +64,35 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           slug: Kilo59/ruff-sync
 
+  pre-publish:
+    name: Test package installation
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [static-analysis, tests]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.10
+
+      - name: Build package
+        run: uv build
+
+      - name: Install and test packaged program
+        run: |
+          uv tool install $(ls dist/*.whl)
+          ruff-sync --version
+          ruff-sync https://github.com/Kilo59/ruff-sync
+          ruff-sync check https://github.com/Kilo59/ruff-sync
+
   publish:
     name: Build and publish to PyPI
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    needs: [static-analysis, tests]
+    needs: [pre-publish]
     runs-on: ubuntu-latest
     permissions:
       # This permission is required for trusted publishing

{ruff_sync-0.0.2.dev0 → ruff_sync-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.0.2.dev0
+Version: 0.0.3
 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, or any raw URL) and merges it into your local project, preserving your comments, formatting, and project-specific overrides.
 
 ---
 
@@ -49,16 +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)
-- [CI Integration](#ci-integration)
 - [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.
@@ -75,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
 
 ```
 ┌─────────────────────────────┐
@@ -140,74 +141,79 @@ uv tool install git+https://github.com/Kilo59/ruff-sync
 ### Usage
 
 ```console
-# Sync from a GitHub URL (blob URLs are auto-converted to raw)
+# Sync from a GitHub/GitLab repository (defaults to main/pyproject.toml)
+ruff-sync https://github.com/my-org/standards
+
+# Or a direct blob/file URL (auto-converts 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
+# Clone from any git repository (using SSH or HTTP, defaults to --depth 1)
+# You can use the --branch flag to specify a branch (default: main)
+ruff-sync git@github.com:my-org/standards.git
+ruff-sync ssh://git@gitlab.com/my-org/standards.git
 
-# Sync into a specific project directory
-ruff-sync --source ./my-project
+# Or if configured in pyproject.toml (see Configuration), simply run:
+ruff-sync
 
 # Exclude specific sections from being overwritten using dotted paths
 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
+ruff-sync check https://github.com/my-org/standards
 
 # Semantic check — ignore cosmetic differences like comments and whitespace
 ruff-sync check --semantic
 ```
 
-### CLI Reference
+Run `ruff-sync --help` for full details on all available options.
 
-#### `ruff-sync`
+## Key Features
 
-```
-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.
-```
+- **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 & GitLab URL support** — Automatically converts GitHub/GitLab repository URLs or blob URLs to raw content URLs.
+- **Git clone support** — If the URL starts with `git@` or uses the `ssh://`, `git://`, or `git+ssh://` schemes, `ruff-sync` will perform an efficient shallow clone (using `--filter=blob:none` and `--no-checkout`) to safely extract the configuration with minimal network traffic.
+- **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, private SSH servers, 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.
 
-#### `ruff-sync check`
+## Configuration
 
-```
-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 or file to check. Default: .
-  --exclude EXCLUDE [EXCLUDE ...]
-                        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.
+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"
+
+# Use simple names for top-level keys, and dotted paths for nested keys
+exclude = [
+    "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
+]
 ```
 
-Exits **0** if in sync, **1** if out of sync.
+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`.*
 
-## Key Features
+### Advanced Configuration
 
-- **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.
+For more complex setups, you can also configure the default branch and parent directory used when resolving repository URLs (e.g. `https://github.com/my-org/standards`):
+
+```toml
+[tool.ruff-sync]
+upstream = "https://github.com/my-org/standards"
+
+# Use a specific branch or tag (default: "main")
+branch = "develop"
+
+# Specify a parent directory if pyproject.toml is not at the repo root
+path = "config/ruff"
+```
 
 ## CI Integration
 
@@ -238,26 +244,6 @@ $ ruff-sync check --semantic
    ]
 ```
 
-## Configuration
-
-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"
-]
-```
-
-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`.*
-
 ## Example Workflow
 
 A typical setup for an organization:
@@ -268,11 +254,49 @@ A typical setup for an organization:
 
 ```console
 # In each project repo:
-ruff-sync https://github.com/my-org/python-standards/blob/main/pyproject.toml
+ruff-sync https://github.com/my-org/python-standards
 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:
@@ -300,13 +324,16 @@ 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
+./scripts/check_dogfood.sh
 ```
 
 **Or sync from a large upstream like Pydantic's config:**
 
 ```console
-./scripts/dogfood.sh
+# Using a HTTP URL
+./scripts/pull_dogfood.sh
+# Using a Git URL
+./scripts/gitclone_dogfood.sh
 ```
 
 This will download Pydantic's Ruff configuration and merge it into the local `pyproject.toml`. You can then use `git diff` to see how it merged the keys while preserving the existing structure and comments.