ruff-sync 0.1.7.dev2__py3-none-any.whl → 0.1.9.dev0__py3-none-any.whl

ruff_sync/.agents/skills/ruff-sync/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: ruff-sync
+description: >-
+  Configure and operate ruff-sync to synchronize Ruff linter settings across Python projects.
+  Use when the user wants to set up ruff-sync, sync Ruff config from an upstream source,
+  check for configuration drift, integrate ruff-sync into CI, troubleshoot sync issues,
+  or keep Ruff rules consistent across multiple repositories.
+---
+
+# ruff-sync Usage
+
+`ruff-sync` pulls a canonical Ruff configuration from an upstream URL and merges it into your local project, preserving comments, whitespace, and per-project overrides.
+
+## Quick Start
+
+```bash
+# 1. Install
+uv tool install ruff-sync
+
+# 2. Sync from an upstream repo (extracts [tool.ruff] / ruff.toml automatically)
+ruff-sync https://github.com/my-org/standards
+
+# 3. Review the changes before committing
+git diff pyproject.toml
+```
+
+## Persist Configuration
+
+Add to `pyproject.toml` so you don't need to pass CLI args every time:
+
+```toml
+[tool.ruff-sync]
+upstream = "https://github.com/my-org/standards"
+exclude = [
+    "target-version",            # each project uses its own Python version
+    "lint.per-file-ignores",     # project-specific suppressions
+    "lint.ignore",
+    "lint.isort.known-first-party",
+]
+```
+
+Then just run `ruff-sync` (no arguments needed).
+
+See [references/configuration.md](references/configuration.md) for all config keys and defaults.
+
+## Common Workflows
+
+### Initial Project Setup
+
+```
+Setup Progress:
+- [ ] 1. Install ruff-sync (uv tool install ruff-sync)
+- [ ] 2. Check for `.pre-commit-config.yaml` — if present, ensure the `ruff` hook is used
+- [ ] 3. Add `[tool.ruff-sync]` to `pyproject.toml` with upstream URL and exclusions
+- [ ] 4. If `.pre-commit-config.yaml` exists, set `pre-commit-version-sync = true` in `[tool.ruff-sync]`
+- [ ] 5. Run `ruff-sync` to pull the upstream config
+- [ ] 6. Review `git diff`
+- [ ] 7. Fix any new lint errors: `uv run ruff check . --fix`
+- [ ] 8. Commit
+```
+
+### Upstream Layers (multi-source)
+
+Stack multiple upstream sources — later entries win on conflict:
+
+```toml
+[tool.ruff-sync]
+upstream = [
+    "https://github.com/my-org/python-standards",   # base company rules
+    "https://github.com/my-org/ml-team-tweaks",     # team-specific overrides
+]
+```
+
+### CI Drift Check
+
+```
+CI Setup Progress:
+- [ ] 1. Add ruff-sync check step to CI workflow (see references/ci-integration.md)
+- [ ] 2. Decide: --semantic for value-only checks, or full string comparison
+- [ ] 3. Set output format: --output-format github for PR annotations
+- [ ] 4. Set exit-code expectations (0 = in sync, 1 = config drift, 2 = pre-commit only)
+- [ ] 5. Verify locally: `ruff-sync check --semantic`
+```
+
+Keep the `ruff-pre-commit` hook version in `.pre-commit-config.yaml` aligned with the project's Ruff version.
+
+**Recommendation:** Always prefer the persistent TOML configuration over the ephemeral `--pre-commit` CLI flag.
+
+```toml
+[tool.ruff-sync]
+pre-commit-version-sync = true
+```
+
+Then run `ruff-sync` — it updates the hook rev automatically. Exit code 2 means only the hook version is out of sync (Ruff config itself is fine).
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | In sync — no action needed |
+| `1` | Ruff config is out of sync with upstream |
+| `2` | Config is in sync, but pre-commit hook version is stale (only when `--pre-commit` is active) |
+
+## URL Formats Supported
+
+All of these work as the `upstream` value:
+
+```bash
+ruff-sync https://github.com/my-org/standards              # repo root
+ruff-sync https://github.com/my-org/standards/tree/main/cfg  # subdirectory
+ruff-sync https://github.com/my-org/standards/blob/main/ruff.toml  # specific file
+ruff-sync https://raw.githubusercontent.com/my-org/standards/main/pyproject.toml
+ruff-sync git@github.com:my-org/standards.git             # SSH (shallow clone)
+```
+
+## CLI Reference (Short)
+
+| Flag | Meaning |
+|------|---------|
+| `--validate`      | Validate merged config with Ruff before writing; aborts if Ruff rejects it |
+| `--strict`        | Like `--validate` but also treats warnings (version mismatch, deprecated rules) as failures. Implies `--validate` |
+| `--output-format` | `text` (default), `json`, `github`, `gitlab`, `sarif` (auto-detected in CI) |
+| `--semantic`      | Ignore whitespace/comments in `check` |
+| `--pre-commit`    | Sync `.pre-commit-config.yaml` hook version |
+| `--save`          | Persist CLI args to `pyproject.toml` |
+
+## Gotchas
+
+- **`exclude` uses dotted paths, not TOML paths.** `lint.per-file-ignores` refers to the `per-file-ignores` key inside `[tool.ruff.lint]`. Do NOT write `tool.ruff.lint.per-file-ignores`.
+- **`--validate` is opt-in.** Validation is off by default. Pass `--validate` (or `--strict`) to run the merged config through Ruff before writing. The sync is aborted if Ruff rejects the config, leaving the local file untouched. This includes a **Python version consistency check** that compares upstream `target-version` against local `requires-python`.
+- **Excluding `target-version` skips consistency validation.** If `target-version` (or `tool.ruff.target-version`) is in the `exclude` list, `ruff-sync` will skip the version consistency check and log a warning. This is useful for projects that intentionally deviate from upstream Python versions.
+- **`--strict` implies `--validate`.** If you want warnings (like version mismatches or deprecated rules) treated as failures, only `--strict` is needed — don't pass both.
+- **Validation soft-fails if `ruff` is not on PATH.** If the `ruff` binary can't be found, a warning is logged and the sync continues normally.
+- **Use `--init` only for new projects.** `ruff-sync` requires an existing `pyproject.toml` or `ruff.toml`. Pass `--init` to scaffold one if the directory is empty. This will automatically generate a `[tool.ruff-sync]` configuration block for future syncs.
+- **Use `--save` to persist CLI arguments.** If you want to update an existing `pyproject.toml` with a new upstream URL or exclusion, pass `--save` to write the new configuration to the file.
+- **`--semantic` ignores comments and whitespace.** Use it in CI to avoid false positives from cosmetic local edits. Omit it for strict byte-for-byte checks.
+- **SSH URLs trigger a shallow clone.** `git@github.com:...` URLs use `git clone --filter=blob:none --depth=1` — no `git` credential issues as long as SSH auth is configured.
+- **Later upstreams win in `upstream` lists.** In a multi-source list, keys set by entry 2 overwrite keys from entry 1.
+- **Config discovery order matters.** When targeting a directory, `ruff-sync` looks for `ruff.toml` -> `.ruff.toml` -> `pyproject.toml` in that order.
+- **Pre-commit exit code 2 is intentional.** A `2` exit from `ruff-sync check` means the Ruff _config_ is fine, only the pre-commit hook tag is stale. You may want to treat this differently from a full config drift (exit 1) in CI.
+- **Prefer TOML for pre-commit sync.** While `--pre-commit` works on the CLI, setting `pre-commit-version-sync = true` in `pyproject.toml` is the recommended way to ensure hook versioning stays consistent for all contributors.
+
+## References
+
+- **[Configuration reference](references/configuration.md)** — All `[tool.ruff-sync]` keys, types, and defaults
+- **[Troubleshooting](references/troubleshooting.md)** — Common errors and how to resolve them
+- **[CI integration recipes](references/ci-integration.md)** — GitHub Actions, GitLab CI, pre-commit hook

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

@@ -0,0 +1,233 @@
+# 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 and a structured Job Summary report.
+
+### With Strict Validation
+
+To also catch deprecated rules and Python version mismatches in CI:
+
+```yaml
+- name: Check Ruff config (with validation)
+  run: ruff-sync check --semantic --strict --output-format github
+```
+
+`--strict` implies `--validate`. Deprecated rules and version mismatches are upgraded to failures.
+
+> [!TIP]
+> `ruff-sync` automatically groups multiple drifts in the same file into a single annotation to reduce PR noise.
+
+### 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`?**
+>
+> | 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" |
+
+---
+
+## 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.6   # 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 (`check`), validation failure (`pull --validate`), or sync error |
+| **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/.agents/skills/ruff-sync/references/configuration.md

@@ -0,0 +1,164 @@
+# ruff-sync Configuration Reference
+
+All keys live under `[tool.ruff-sync]` in `pyproject.toml`.
+
+## Keys
+
+### `upstream` *(required unless passed on CLI)*
+
+The URL(s) of your canonical Ruff configuration. Accepts a single string or a list. When a list is given, sources are merged in order — later entries win on conflict.
+
+```toml
+# Single source
+upstream = "https://github.com/my-org/standards"
+
+# Multiple sources (base + team overlay)
+upstream = [
+    "https://github.com/my-org/python-standards",
+    "https://github.com/my-org/ml-team-tweaks",
+]
+```
+
+**Supported URL formats (with automatic browser link resolution):**
+- GitHub/GitLab repo root: `https://github.com/<org>/<repo>`
+- Subdirectory (tree): `https://github.com/<org>/<repo>/tree/main/configs/ruff`
+- Specific file (blob): `https://github.com/<org>/<repo>/blob/main/pyproject.toml`
+- Raw URL: `https://raw.githubusercontent.com/<org>/<repo>/main/pyproject.toml`
+- SSH (triggers shallow clone): `git@github.com:<org>/<repo>.git`
+
+---
+
+### `exclude` *(default: `["lint.per-file-ignores"]`)*
+
+List of config keys to protect from being overwritten by upstream. Use dotted paths to reference nested keys.
+
+```toml
+exclude = [
+    "target-version",                       # keep per-project Python version
+    "lint.per-file-ignores",               # keep per-file suppressions
+    "lint.ignore",                          # keep repo-specific rule suppressions
+    "lint.isort.known-first-party",         # keep first-party package list
+    "lint.flake8-tidy-imports.banned-api",  # keep banned API list
+    "lint.pydocstyle.convention",           # keep docstring style choice
+]
+```
+
+**Key format:**
+- Top-level keys: `"target-version"`, `"line-length"`
+- Nested keys (dotted): `"lint.select"`, `"lint.per-file-ignores"`, `"format.quote-style"`
+- These are ruff config key names, NOT TOML paths — do NOT include `tool.ruff.` prefix.
+
+---
+
+### `branch` *(default: `"main"`)*
+
+The branch, tag, or commit hash to use when fetching from a Git repo URL.
+
+```toml
+branch = "develop"
+```
+
+---
+
+### `path` *(default: `""`)*
+
+Path inside the repository where the config lives, when it's not at the repo root.
+
+```toml
+path = "configs/ruff"
+```
+
+Useful when combined with a repo-root `upstream` URL:
+
+```toml
+upstream = "git@github.com:my-org/standards.git"
+path = "configs/strict"
+```
+
+---
+
+### `to` *(default: `"."`)*
+
+Local target directory or file path to sync into.
+
+```toml
+to = "services/api"   # sync into a subdirectory of the monorepo
+```
+
+---
+
+### `pre-commit-version-sync` *(default: `false`)*
+
+When `true`, `ruff-sync` also updates the `ruff-pre-commit` hook rev in `.pre-commit-config.yaml` to match the Ruff version installed in the project.
+
+> [!TIP]
+> This is the preferred way to enable pre-commit hook synchronization as it persists the setting in your project configuration.
+
+```toml
+pre-commit-version-sync = true
+```
+
+Requires a `- repo: https://github.com/astral-sh/ruff-pre-commit` entry in `.pre-commit-config.yaml`.
+
+---
+
+### `validate` *(default: `false`)*
+
+When `true`, `ruff-sync` validates the merged configuration by running it through Ruff before writing to disk. If Ruff rejects the config (e.g., due to an unknown key), the sync is aborted and the local file is left unchanged.
+
+```toml
+validate = true
+```
+
+> [!NOTE]
+> Validation requires `ruff` to be available on PATH. If `ruff` is not found, validation is skipped with a warning.
+
+---
+
+### `strict` *(default: `false`)*
+
+When `true`, all validation warnings (Python version mismatches, deprecated rules) are treated as hard failures. Implies `validate = true`.
+
+```toml
+strict = true
+```
+
+---
+
+## Full Example
+
+```toml
+[tool.ruff-sync]
+upstream = [
+    "https://github.com/my-org/python-standards",
+    "https://github.com/my-org/backend-team-rules",
+]
+exclude = [
+    "target-version",
+    "lint.per-file-ignores",
+    "lint.ignore",
+    "lint.isort.known-first-party",
+]
+branch = "main"
+path = "ruff"
+to = "."
+pre-commit-version-sync = true
+validate = true
+```
+
+## CLI Overrides
+
+All config keys have CLI equivalents. CLI values always win over `pyproject.toml`:
+
+```bash
+ruff-sync https://github.com/my-org/standards --exclude lint.ignore --branch develop --output-format github
+```
+
+## Config Discovery for `ruff.toml` Projects
+
+If the local target is a directory, ruff-sync looks for config in this order:
+1. `ruff.toml`
+2. `.ruff.toml`
+3. `pyproject.toml`
+
+If the upstream is a `ruff.toml`, it syncs the root config object (no `[tool.ruff]` section extraction needed).

ruff_sync/.agents/skills/ruff-sync/references/troubleshooting.md

@@ -0,0 +1,157 @@
+# Troubleshooting ruff-sync
+
+## Config Not Changing After Sync
+
+**Symptom:** `ruff-sync` runs without error, but `git diff` shows no changes.
+
+**Likely causes:**
+1. The key is in `exclude`. Check `[tool.ruff-sync] exclude` in your `pyproject.toml`.
+2. The local value already matches upstream — you're already in sync.
+3. The upstream URL resolved to the wrong file. Verify with `ruff-sync check --semantic` and look at the diff output.
+
+---
+
+## `UpstreamError` / HTTP Failure
+
+**Symptom:**
+```
+UpstreamError: Failed to fetch https://...
+```
+
+**Steps:**
+1. Check the URL works in a browser or with `curl -I <url>`.
+2. For GitHub URLs, make sure you're pointing at a _raw_ or _tree/blob_ URL, not an HTML page.
+3. If using a private repo, the raw URL requires authentication. Use an SSH URL instead:
+   ```bash
+   ruff-sync git@github.com:my-org/private-standards.git
+   ```
+4. Check network/proxy settings if in a corporate environment.
+
+---
+
+## HTTP 404 on GitHub URL
+
+**Symptom:** 404 when fetching a GitHub tree or blob URL.
+
+**Cause:** The branch or path doesn't exist, or the repo is private.
+
+**Fix:**
+```toml
+[tool.ruff-sync]
+upstream = "https://github.com/my-org/standards"
+branch = "main"   # make sure this branch exists
+path = "configs"  # make sure this path exists on that branch
+```
+
+Validate: `curl https://github.com/my-org/standards/tree/main/configs` should return 200.
+
+---
+
+## `FileNotFoundError` — No Local Config
+
+**Symptom:**
+```
+FileNotFoundError: No pyproject.toml or ruff.toml found in .
+```
+
+**Fix:** Use `--init` to scaffold a new config file before syncing:
+```bash
+ruff-sync https://github.com/my-org/standards --init
+```
+
+---
+
+## Pre-commit Version Mismatch (Exit Code 2)
+
+**Symptom:** `ruff-sync check` exits with code 2 and a warning like:
+```
+⚠️  Pre-commit ruff hook version is out of sync: .pre-commit-config.yaml uses v0.9.3, project has ruff==0.10.0
+```
+
+**This is not a config drift.** The Ruff configuration is in sync. Only the pre-commit hook tag is stale.
+
+**Fix:**
+```bash
+ruff-sync          # pulls config AND updates the hook rev (if pre-commit-version-sync = true)
+# or manually: update the 'rev:' line in .pre-commit-config.yaml
+```
+
+To suppress this check entirely, omit `--pre-commit` from `ruff-sync check` or set `pre-commit-version-sync = false`.
+---
+
+## Python Version Mismatch Warning
+
+**Symptom:** Sync succeeds but logs a warning like:
+```
+⚠️  Version mismatch: upstream [tool.ruff] target-version='py39' targets Python 3.9, but local [project] requires-python='>=3.10' requires Python >= 3.10.
+```
+
+**Cause:** The upstream configuration is targeting an older Python version than your project requires. This can lead to Ruff not using newer rules or features available to your project.
+
+**Fix:**
+1. **Update Upstream:** The ideal fix is to update the `target-version` in the upstream repository to a newer version (e.g., `py311`).
+2. **Exclude the key:** If you need to stay on a specific version locally, add `target-version` to your `exclude` list:
+   ```toml
+   [tool.ruff-sync]
+   exclude = ["target-version"]
+   ```
+
+In **`--strict`** mode, this warning is upgraded to a hard failure and will abort the sync.
+
+---
+
+## Merge Produces Unexpected `tomlkit` Structure
+
+**Symptom:** Synced `pyproject.toml` has repeated sections or oddly formatted keys.
+
+**Cause:** Mixing dotted-key style (`lint.select = [...]`) with explicit table header style (`[tool.ruff.lint]`) in the same file.
+
+**Fix:** Pick one style consistently. `ruff-sync` uses `tomlkit` which preserves formatting, but mixing styles can produce unexpected output.
+
+---
+
+## SSH Clone Fails
+
+**Symptom:** Hangs or fails when using `git@github.com:...` URL.
+
+**Cause:** SSH key not configured or not added to the agent.
+
+**Fix:** Verify SSH auth first:
+```bash
+ssh -T git@github.com
+```
+
+Alternatively, switch to HTTPS:
+```toml
+upstream = "https://github.com/my-org/standards"
+```
+
+---
+
+## `ruff-sync` Not Found After Install
+
+**Symptom:** `ruff-sync: command not found`
+
+**Fix:**
+```bash
+# If installed with uv tool:
+uv tool list   # confirm it appears
+# Ensure uv tools bin dir is on PATH:
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+
+# If using pipx:
+pipx ensurepath
+```
+
+---
+
+## Getting More Debug Info
+
+```bash
+# Show what config would be merged without applying it
+ruff-sync check https://github.com/my-org/standards
+
+# Show a diff of what changed
+ruff-sync check --semantic   # value-only diff
+ruff-sync check              # full string diff (catches comment/whitespace changes too)
+```

ruff_sync/config_io.py

@@ -17,7 +17,7 @@ if TYPE_CHECKING:
 
 
 @enum.unique
-class RuffConfigFileName(str, enum.Enum):
+class RuffConfigFileName(enum.StrEnum):
     """Enumeration of Ruff configuration filenames."""
 
     PYPROJECT_TOML = "pyproject.toml"

ruff_sync/constants.py

@@ -47,7 +47,7 @@ MISSING: Final[MissingType] = MissingType.SENTINEL
 
 
 @enum.unique
-class OutputFormat(str, enum.Enum):
+class OutputFormat(enum.StrEnum):
     """Output formats for the CLI."""
 
     TEXT = "text"
@@ -63,7 +63,7 @@ class OutputFormat(str, enum.Enum):
 
 
 @enum.unique
-class ConfKey(str, enum.Enum):
+class ConfKey(enum.StrEnum):
     """Centralized configuration keys for [tool.ruff-sync].
 
     These are the canonical names used in the pyproject.toml configuration file.
@@ -129,7 +129,7 @@ class ConfKey(str, enum.Enum):
 
 def resolve_defaults(
     branch: str | MissingType,
-    path: str | None | MissingType,
+    path: str | MissingType | None,
     exclude: Iterable[str] | MissingType,
 ) -> tuple[str, str | None, Iterable[str]]:
     """Resolve MISSING sentinel values to their effective defaults.

ruff_sync/core.py

@@ -697,51 +697,24 @@ async def fetch_upstreams_concurrently(
         UpstreamError: If one or more upstreams fail to fetch.
     """
     upstream_list = list(upstreams)
-    if sys.version_info >= (3, 11):
-        # Use structured concurrency on Python 3.11+
-        tasks: list[asyncio.Task[FetchResult]] = []
-        try:
-            async with asyncio.TaskGroup() as tg:
-                tasks = [
-                    tg.create_task(fetch_upstream_config(url, client, branch, path))
-                    for url in upstream_list
-                ]
-            return [t.result() for t in tasks]
-        except BaseException as eg:
-            if isinstance(eg, (asyncio.CancelledError, KeyboardInterrupt)):
-                raise
-            # TODO: Use `except*` once Python 3.11+ is the minimum supported version.
-            # On Python 3.11+, TaskGroup raises an ExceptionGroup.
-            # Catching it as Exception is safe and compatible with Python 3.10 syntax.
-            errors = [
-                (upstream_list[i], t.exception())
-                for i, t in enumerate(tasks)
-                if t.done() and t.exception() is not None
+    tasks: list[asyncio.Task[FetchResult]] = []
+    try:
+        async with asyncio.TaskGroup() as tg:
+            tasks = [
+                tg.create_task(fetch_upstream_config(url, client, branch, path))
+                for url in upstream_list
             ]
-            if errors:
-                raise UpstreamError(errors) from eg
-            raise
-    else:
-        # Fallback for Python 3.10
-        fetch_tasks = [fetch_upstream_config(url, client, branch, path) for url in upstream_list]
-        results = await asyncio.gather(*fetch_tasks, return_exceptions=True)
-
-        errors_list: list[tuple[URL, BaseException]] = []
-        fetch_results: list[FetchResult] = []
-
-        for i, res in enumerate(results):
-            if isinstance(res, BaseException):
-                errors_list.append((upstream_list[i], res))
-            elif isinstance(res, FetchResult):
-                fetch_results.append(res)
-            else:
-                msg = f"Unexpected result type from fetch: {type(res)}"
-                raise TypeError(msg)
-
-        if errors_list:
-            raise UpstreamError(errors_list)
-
-        return fetch_results
+        return [t.result() for t in tasks]
+    except* Exception as eg:
+        errors: list[tuple[URL, BaseException]] = []
+        for i, t in enumerate(tasks):
+            if t.done() and not t.cancelled():
+                exc = t.exception()
+                if exc is not None:
+                    errors.append((upstream_list[i], exc))
+        if errors:
+            raise UpstreamError(errors) from eg
+        raise
 
 
 async def _merge_multiple_upstreams(

ruff_sync/types_.py

@@ -2,9 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Literal, TypedDict
-
-from typing_extensions import NotRequired
+from typing import Any, Literal, NotRequired, TypedDict
 
 RuleSyncStatus = Literal["Enabled", "Ignored", "Disabled"]
 

{ruff_sync-0.1.7.dev2.dist-info → ruff_sync-0.1.9.dev0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ruff-sync
-Version: 0.1.7.dev2
+Version: 0.1.9.dev0
 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/
@@ -17,14 +17,13 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
-Requires-Python: >=3.10
-Requires-Dist: httpx2>=2.3.0
+Requires-Python: >=3.11
+Requires-Dist: httpx2>=2.9.1
 Requires-Dist: tomlkit<2.0.0,>=0.12.3
 Requires-Dist: typing-extensions>=4.5.0
 Provides-Extra: tui
@@ -38,6 +37,7 @@ Description-Content-Type: text/markdown
   <br>
   <a href="https://kilo59.github.io/ruff-sync/"><img src="https://img.shields.io/badge/docs-MkDocs-blue.svg" alt="Documentation"></a>
   <a href="https://pypi.org/project/ruff-sync/"><img src="https://img.shields.io/pypi/v/ruff-sync" alt="PyPI version"></a>
+  <a href="https://pepy.tech/projects/ruff-sync"><img src="https://static.pepy.tech/personalized-badge/ruff-sync?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads" alt="PyPI Downloads"></a>
   <a href="https://codecov.io/gh/Kilo59/ruff-sync"><img src="https://codecov.io/gh/Kilo59/ruff-sync/graph/badge.svg?token=kMZw0XtoFW" alt="codecov"></a>
   <a href="https://results.pre-commit.ci/latest/github/Kilo59/ruff-sync/main"><img src="https://results.pre-commit.ci/badge/github/Kilo59/ruff-sync/main.svg" alt="pre-commit.ci status"></a>
   <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
@@ -353,7 +353,15 @@ $ ruff-sync check --semantic
 
 ## Agent Skill
 
-`ruff-sync` ships a bundled [Agent Skill](https://agentskills.io/home) at [`.agents/skills/ruff-sync-usage/`](.agents/skills/ruff-sync-usage/). AI coding agents that support the [Agent Skills format](https://agentskills.io/what-are-skills) (GitHub Copilot, Claude Code, Cursor, etc.) will automatically use it to guide you through setup, configuration, CI integration, and troubleshooting — without you needing to explain the tool each time.
+`ruff-sync` supports the [Library Skills](https://library-skills.io/) specification. AI coding agents that support the [Agent Skills format](https://agentskills.io/what-are-skills) (GitHub Copilot, Claude Code, Cursor, etc.) can automatically load this skill to guide you through setup, configuration, CI integration, and troubleshooting.
+
+You can install it automatically using `uvx` (or `npx` in a Node.js project):
+
+```console
+$ uvx library-skills
+```
+
+This will link the `ruff-sync` skill (bundled inside the installed package) into your project's `.agents/skills/ruff-sync` folder.
 
 See the **[Agent Skill guide](https://kilo59.github.io/ruff-sync/stable/agent-skill/)** for details.
 
@@ -477,6 +485,24 @@ flowchart TD
     style SemanticNode fill:#4b5563,color:#fff,stroke:#374151
 ```
 
+## Development
+
+For local development and testing:
+
+```console
+# Run test suite
+uv run pytest -vv
+
+# Run linter and formatter
+uv run ruff check . --fix
+uv run ruff format .
+
+# Run type checker
+uv run mypy .
+```
+
+> **Note on Test Environment**: Test mocking uses `respx` with `httpx2`. To ensure `respx` intercepts `httpx2` network calls during `pytest` runs before plugin entrypoints load, a guarded `src/sitecustomize.py` script is used in development. This script is strictly excluded from production wheel builds (`packages = ["src/ruff_sync"]`) and is never shipped to end users.
+
 ## Dogfooding
 
 To see `ruff-sync` in action, this project automatically "dogfoods" its own configuration. Every pull request runs a `ruff-sync check` against the repository's own `pyproject.toml` using the `--output-format github` flag, providing real-time feedback and inline annotations whenever configuration drift is detected.

{ruff_sync-0.1.7.dev2.dist-info → ruff_sync-0.1.9.dev0.dist-info}/RECORD

@@ -1,15 +1,19 @@
 ruff_sync/__init__.py,sha256=M_1YK0BcPzlLlxlBOEPEBTCkAVm37r-yoQzGGZnfQ7Y,1206
 ruff_sync/__main__.py,sha256=oMIbv9ywToleBKJrZ-GMo_KhM4lHg02nJe7t6neWzJE,179
 ruff_sync/cli.py,sha256=IICm0f60_-fKRjFH3gMLUn3sK9yxB9auNglI7E6P-WU,25346
-ruff_sync/config_io.py,sha256=Hfwo0VC2rbs1ToXPwB0_oQae__opyj-Us8pDsgI3-w0,4349
-ruff_sync/constants.py,sha256=g7ZU8mGdQ2682tKQuKkhRaTRRmg0K2vMVp3Ljs60D70,5822
-ruff_sync/core.py,sha256=69AQ0YraOtl3KQ0fSeBtqpw-LPBMRHV5G2QQr9P_A0k,44309
+ruff_sync/config_io.py,sha256=K8wVXRoJ6KYbS5TYs9ND2hWR7DggMl0UwX9QlZAdEnY,4347
+ruff_sync/constants.py,sha256=FEJQjAABC2kJStmtjBf6FVpoxEmmgCCvof53DldwjXI,5818
+ruff_sync/core.py,sha256=N353z7Die51b_CHhO5p5L05xWhFKWsogVcDwESrngHQ,43119
 ruff_sync/dependencies.py,sha256=RpJXAsrB-Y-ol_ZH4U92XIuyq8_bWaYwp9sn9KpxraA,2096
 ruff_sync/formatters.py,sha256=A4p2XAyc-xnteUmdtRXbp63fIjT9MdyKF6qKvcyNMho,29908
 ruff_sync/pre_commit.py,sha256=0ltXUkmocbrSwwf6cPbNc_K5K9n-gvou98xJy9YUhr0,5303
 ruff_sync/system.py,sha256=vF9Jjb-Z9MuLwo3wiOqcCDxniNtjvo3O-aFt4NJf-2Y,5715
-ruff_sync/types_.py,sha256=BejR6sgctR0qr5fKgRTtgHp2TqnvT8zTRo1NJi2VHLo,824
+ruff_sync/types_.py,sha256=9gSZpsDXl40FfXCd95aBToZTjOm1vnBZmqaDKXL4sJA,794
 ruff_sync/validation.py,sha256=OatdkWUKEyxw7CYTOFNpH6IRsbVfU5EHjt6Lu6nOO9U,11585
+ruff_sync/.agents/skills/ruff-sync/SKILL.md,sha256=06D6Sw-WuWQNezRtce-Y724wJcfHmBUb66eA7sNYmWQ,7419
+ruff_sync/.agents/skills/ruff-sync/references/ci-integration.md,sha256=s3CmTFM8uEJU00_Bt99wLGNt3GIadhidwxMW70XxsaY,7325
+ruff_sync/.agents/skills/ruff-sync/references/configuration.md,sha256=xoF6DDbKz_eAipgm-iuwbo5QxM-_49rju8pxjbbIfBQ,4519
+ruff_sync/.agents/skills/ruff-sync/references/troubleshooting.md,sha256=vQxMLg0DA3Hmd7jJAVcvTZFIis9Gg4mZDItRRMoHnw4,4537
 ruff_sync/tui/__init__.py,sha256=DcwvE70ETjBcC6pQeHpjrYtkJp8z4StGM8L3EuaVcIo,635
 ruff_sync/tui/app.py,sha256=soq0fkFsLeB7ZxJWNZM_H6bNj7H8p6nEYyirVcskN54,9317
 ruff_sync/tui/constants.py,sha256=fEPyp2k817QLluyiVHqDObzDONlHz_L3Ec0SYAUzzMs,267
@@ -17,8 +21,8 @@ ruff_sync/tui/screens.py,sha256=NVIlqNIr64JrFFWeec7usqJCb1x41NEmSfRZGeEcwuo,5557
 ruff_sync/tui/themes.py,sha256=-x9u_8iZPa1XZuo8O_tWVHyCImN9Qs9F7xPhl0VLwZw,654
 ruff_sync/tui/types_.py,sha256=poNUBJotgUso2IkUi3nXUuxz6wv1goFWZimj4VttdJE,8271
 ruff_sync/tui/widgets.py,sha256=2m3gyH4xDBpM0CK-5eQmmUCZXYKJujrbyVkFTxqmHcg,9760
-ruff_sync-0.1.7.dev2.dist-info/METADATA,sha256=iysOAshz9XPsmyasNIGUE_zkL8vK8rQ4gUmxLeOVOn0,23134
-ruff_sync-0.1.7.dev2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-ruff_sync-0.1.7.dev2.dist-info/entry_points.txt,sha256=QQ0pjxMIN0vp5EmNFkyb-1Yk8JOIkid8zAPN3IpAExA,78
-ruff_sync-0.1.7.dev2.dist-info/licenses/LICENSE.md,sha256=RcCP8t8xyCx2cvMZSLjBrPqJfctciWC6q85ceQAcEfA,1080
-ruff_sync-0.1.7.dev2.dist-info/RECORD,,
+ruff_sync-0.1.9.dev0.dist-info/METADATA,sha256=KL05bz9etJdfbrqobWgiibwOWrQR4j235ci1xDFAol0,24046
+ruff_sync-0.1.9.dev0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+ruff_sync-0.1.9.dev0.dist-info/entry_points.txt,sha256=QQ0pjxMIN0vp5EmNFkyb-1Yk8JOIkid8zAPN3IpAExA,78
+ruff_sync-0.1.9.dev0.dist-info/licenses/LICENSE.md,sha256=RcCP8t8xyCx2cvMZSLjBrPqJfctciWC6q85ceQAcEfA,1080
+ruff_sync-0.1.9.dev0.dist-info/RECORD,,

{ruff_sync-0.1.7.dev2.dist-info → ruff_sync-0.1.9.dev0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.32.0
 Root-Is-Purelib: true
 Tag: py3-none-any