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

{ruff_sync-0.1.4.dev0 → ruff_sync-0.1.5.dev1}/.agents/TESTING.md

@@ -8,7 +8,7 @@ This document defines the mandatory testing standards and patterns for the `ruff
 - **No Side Effects**: Tests must be isolated and not touch the actual filesystem or make real network calls.
 - **Semantic + Structural Assertions**: When testing TOML merges, always verify **both**:
   1. **Structural/Whitespace**: The file "looks" correct (comments and spacing are preserved).
-  2. **Semantic**: The actual data in the merged result matches the expected values.
+  2. **Semantic**: The actual data in the merged result matches the expected values. Use the [dirty-equals](skills/dirty-equals/SKILL.md) Agent Skill for declarative, concise assertions.
 - **DRY with Fixtures and Parameterization**: Avoid code duplication. Use fixtures for common setups and `@pytest.mark.parametrize` for matrix testing.
 
 ## 2. Tooling and Environment
@@ -130,6 +130,6 @@ def test_my_edge_case():
 
 ## 6. Code Coverage
 
-We target **high coverage** for `ruff_sync.py`.
+We target **high coverage** for `src/ruff_sync/`.
 - 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.1.5.dev1/.agents/skills/dirty-equals/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: dirty-equals
+description: Use this skill when you need to write declarative, readable, and maintainable assertions in Python tests. It is particularly effective for matching complex data structures, validating merged TOML configurations, and performing fuzzy matching on URLs, file paths, or object types. Use this when the user asks to "assert," "check," "verify," or "match" data in a test, even if they don't explicitly mention "dirty-equals."
+---
+
+# `dirty-equals` Skill
+
+This skill provides patterns and best practices for writing declarative assertions in the `ruff-sync` project using the `dirty-equals` library.
+
+## Overview
+
+Instead of asserting on every field manually, compare against a "dirty" object that matches the expected structure and types.
+
+```python
+from dirty_equals import IsInt, IsPartialDict, IsStr
+
+def test_config_logic():
+    result = {"status": "active", "version": 1, "extra": "data"}
+    # Declarative assertion
+    assert result == IsPartialDict({
+        "status": IsStr(regex="act.*"),
+        "version": IsInt(gt=0),
+    })
+```
+
+## Detailed reference
+
+Check these references for project-specific usage and common matchers:
+
+- **[Common Matchers](references/common-matchers.md)**: Standard `dirty-equals` matchers like `IsPartialDict`, `IsInstance`, and more.
+- **[Specialized Matching](references/toml-matching.md)**: Handling `tomlkit.unwrap()` and `Arguments._asdict()`.
+
+## Best Practices
+
+- **Import Style**: Always use the `from dirty_equals import ...` style at the **module level** of your test files.
+- **Semantic Matching**: Use `dirty-equals` for the semantic part of your test assertions, while using string comparisons or `respx` for structural/whitespace checks where appropriate.
+- **Type Safety**: Prefer `IsInstance(httpx.URL)` or `IsInstance(pathlib.Path)` over custom regex for well-known types in the project.

ruff_sync-0.1.5.dev1/.agents/skills/dirty-equals/references/common-matchers.md

@@ -0,0 +1,51 @@
+# Common `dirty-equals` Matchers
+
+This guide covers the most frequently used `dirty-equals` matchers in the `ruff-sync` project. Standard practice is to import these using the `from` syntax at the module level in test files.
+
+## Structural Matching
+
+- **`IsPartialDict`**: Matches a subset of a dictionary. Essential for verifying specific fields in a larger configuration.
+- **`IsDict`**: Matches an entire dictionary exactly (while still allowing fuzzy values).
+- **`IsList`**: Matches a list, allowing fuzzy matching for elements.
+
+## Type and Instance Matching
+
+- **`IsInstance(type)`**: Matches an object of a specific class. Used for objects like `httpx.URL` or `pathlib.Path`.
+- **`IsStr()`**: Matches any string. Can also specify regex or prefix/suffix.
+- **`IsInt()`**: Matches any integer.
+
+## Examples
+
+### Using `IsPartialDict` and `IsInstance`
+
+```python
+from dirty_equals import IsInstance, IsPartialDict
+import httpx
+import pathlib
+
+# Match a partial dict with mixed types
+assert response_data == IsPartialDict({
+    "url": IsInstance(httpx.URL),
+    "status": "success",
+    "retries": 0,
+})
+```
+
+### String and Path Matching
+
+```python
+from dirty_equals import IsInstance, IsStr
+import pathlib
+
+# Match a path instance
+assert result_path == IsInstance(pathlib.Path)
+
+# Match a string with a specific prefix
+assert error_message == IsStr(regex="^ERROR:.*")
+```
+
+## Logic Matchers
+
+- **`~` (Negation)**: Match values that are *not* the given value (e.g., `assert x == ~IsNone`).
+- **`&` (AND)**: Combine matchers (e.g., `IsInt & IsPositive`).
+- **`|` (OR)**: Combine alternatives.

ruff_sync-0.1.5.dev1/.agents/skills/dirty-equals/references/toml-matching.md

@@ -0,0 +1,54 @@
+# Specialized Matching for `ruff-sync`
+
+This reference covers project-specific data structures where `dirty-equals` matchers require particular preparation for reliable results.
+
+## TOML Matching (`tomlkit`)
+
+`tomlkit` returns proxy objects (containers and items). To reliably match these with `dirty-equals`, always use `.unwrap()` on the parsed document or table to convert it to plain Python types.
+
+### Correct Pattern
+
+```python
+from dirty_equals import IsPartialDict
+import tomlkit
+
+# Parse some TOML
+doc = tomlkit.parse('[tool.ruff]\nline-length = 80')
+
+# Match the tool.ruff section
+ruff_config = doc["tool"]["ruff"]
+
+# Must use .unwrap()
+assert ruff_config.unwrap() == IsPartialDict({"line-length": 80})
+```
+
+### Potential Gotcha
+Direct matching of `tomlkit` proxy objects without `.unwrap()` can fail because `dirty-equals` may see the proxy's internal attributes rather than its data.
+
+## CLI `Arguments` matching
+
+Our CLI arguments are defined as a `NamedTuple`. To match specific fields without validating the entire object, convert it to a dictionary using `._asdict()`.
+
+### Correct Pattern
+
+```python
+from dirty_equals import IsInstance, IsPartialDict
+import httpx
+import pathlib
+import ruff_sync_cli
+
+# Sample Arguments instance
+args = ruff_sync_cli.Arguments(
+    command="pull",
+    upstream=(httpx.URL("https://example.com"),),
+    to=pathlib.Path("."),
+    # ... other defaults ...
+)
+
+# Convert to dict and match specific fields
+assert args._asdict() == IsPartialDict({
+    "command": "pull",
+    "upstream": (IsInstance(httpx.URL),),
+    "to": IsInstance(pathlib.Path),
+})
+```

ruff_sync-0.1.5.dev1/.agents/skills/dirty-equals/trigger_eval.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "I need to check if the tool.ruff section was merged correctly",
+    "should_trigger": true
+  },
+  {
+    "query": "add a unit test that verifies the output",
+    "should_trigger": true
+  },
+  {
+    "query": "where should I use dirty-equals",
+    "should_trigger": true
+  },
+  {
+    "query": "verify that this URL is from github.com",
+    "should_trigger": true
+  },
+  {
+    "query": "assert that the dictionary matches this schema",
+    "should_trigger": true
+  },
+  {
+    "query": "fix this syntax error in the CLI",
+    "should_trigger": false
+  },
+  {
+    "query": "run the tests with coverage",
+    "should_trigger": false
+  }
+]

ruff_sync-0.1.5.dev1/.agents/skills/mike/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: mike
+description: Use this skill to manage multiple versions of documentation for MkDocs-powered sites. Deploy new versions, update aliases (like 'latest' or 'stable'), set the default version for the site root, and manage versioned subdirectories in the deployment branch. Use this whenever the user wants to publish, version, or alias documentation, even if they don't explicitly mention "mike". Also use this when the user wants to troubleshoot or debug versioned documentation.
+---
+
+# mike: MkDocs Versioning
+
+`mike` is used in this project to manage a versioned documentation site, allowing side-by-side availability of `dev` (main branch) and stable release docs (e.g., `0.1.4`).
+
+## Prerequisites
+
+`mike` is included in the `docs` dependency group.
+```bash
+# Sync documentation dependencies
+uv sync --group docs
+```
+
+## Project Strategy
+
+This project follows a specific versioning strategy:
+1.  **`dev`**: Represents the current `main` branch.
+2.  **Stable Releases**: Versioned documentation (e.g., `0.1.4`) created upon release.
+3.  **`stable`**: An alias always pointing to the most recent non-dev release.
+
+## Core Workflows
+
+### 1. Deploying Development Docs
+Run this from the `main` branch to update the `dev` version:
+```bash
+mike deploy dev --push --update-aliases
+```
+
+### 2. Deploying a Stable Release
+When a new version is released (e.g., `0.1.4`), deploy it and update the `stable` alias:
+```bash
+# Deploy the specific version and update 'stable'
+mike deploy 0.1.4 stable --push --update-aliases
+
+# Set 'stable' as the default version for the site root
+mike set-default --push stable
+```
+
+## Reference Commands
+
+| Action | Command |
+| :--- | :--- |
+| **Deploy** | `mike deploy <version> [alias]` |
+| **List** | `mike list` |
+| **Set Default** | `mike set-default <version>` |
+| **Alias** | `mike alias <version> <alias>` |
+| **Delete** | `mike delete <identifier>` |
+
+## CI/CD Integration
+
+The deployment logic is automated in [.github/workflows/ci.yaml](.github/workflows/ci.yaml). It automatically:
+- Extracts the version from `pyproject.toml`.
+- Deploys to `dev` if the version contains `.dev`.
+- Deploys to `<version>` and updates `stable` for official releases.
+
+> [!IMPORTANT]
+> **Do NOT** use `mike install-gh-pages`. It is deprecated and removed in the version used by this project. `mike deploy` handles branch initialization automatically.
+
+> [!TIP]
+> Use `mike serve` locally to preview the version switcher before pushing changes.

ruff_sync-0.1.5.dev1/.agents/skills/mike/references/commands.md

@@ -0,0 +1,78 @@
+# Reference: mike CLI commands
+
+Detailed parameter and core command reference for `mike`.
+
+## `deploy`
+
+```bash
+mike deploy [options] <version> [alias]...
+```
+
+Build the documentation for the specified version and commit it to the deployment branch.
+
+- `<version>`: The version name to deploy (e.g., `1.0`, `v1.2.3`).
+- `[alias]`: Optional aliases to point to this version (e.g., `latest`, `stable`).
+
+**Common options:**
+- `-p, --push`: Push the branch to the remote repository.
+- `-b, --branch NAME`: Deployment branch (default: `gh-pages`).
+- `-m, --message MESSAGE`: Custom commit message.
+- `-u, --update-aliases`: Update existing aliases if they already point to a different version.
+- `--alias-type {symlink,redirect,copy}`: Method for creating aliases.
+
+---
+
+## `alias`
+
+```bash
+mike alias [options] <version> <alias>...
+```
+
+Create or update aliases for a version without rebuilding the documentation.
+
+---
+
+## `set-default`
+
+```bash
+mike set-default [options] <version>
+```
+
+Set the default version for the documentation site's root redirect.
+
+---
+
+## `list`
+
+```bash
+mike list [options]
+```
+
+List all versions and aliases deployed to the deployment branch.
+
+---
+
+## `delete`
+
+```bash
+mike delete [options] <identifier>...
+```
+
+Delete one or more versions or aliases.
+
+- `<identifier>`: Version or alias name.
+
+**Options:**
+- `--all`: Delete all versions/aliases.
+
+---
+
+## `serve`
+
+```bash
+mike serve [options]
+```
+
+Locally serve the documentation from the deployment branch. This is for testing the built versioned site.
+
+- `-a, --addr ADDR`: Address to bind to (default: `localhost:8000`).

{ruff_sync-0.1.4.dev0 → ruff_sync-0.1.5.dev1}/.agents/skills/ruff-sync-usage/SKILL.md

@@ -117,7 +117,7 @@ ruff-sync git@github.com:my-org/standards.git             # SSH (shallow clone)
 
 | Flag | Meaning |
 |------|---------|
-| `--output-format` | `text` (default), `json`, `github` (PR annotations) |
+| `--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` |

ruff_sync-0.1.5.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.5.dev1}/.github/workflows/ci.yaml

@@ -134,6 +134,67 @@ jobs:
           echo "Verifying that --semantic check fails for kitchen-sink config (expected failure)..."
           ! ruff-sync check --semantic https://github.com/Kilo59/ruff-sync --path configs/kitchen-sink
 
+  publish-docs:
+    name: Publish Documentation
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [pre-publish]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.10
+
+      - name: Install dependencies
+        run: uv sync --group docs --frozen
+
+      - name: Deploy documentation
+        run: |
+          # Configure git
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # mike deploy handles gh-pages initialization automatically
+
+          # Extract version from pyproject.toml in a TOML-aware way using already installed dependencies
+          VERSION=$(uv run python - << 'PY'
+          import pathlib
+          import tomlkit
+
+          pyproject = pathlib.Path("pyproject.toml")
+          data = tomlkit.parse(pyproject.read_text(encoding="utf-8"))
+
+          # Support both top-level `version` and `[project]` table `version`
+          version = (
+              data.get("project", {}).get("version")
+              or data.get("version")
+          )
+          if not version:
+              raise SystemExit("Version not found in pyproject.toml")
+          print(version)
+          PY
+          )
+          echo "Current Version: $VERSION"
+
+          if [[ "$VERSION" == *".dev"* ]]; then
+            echo "Deploying DEV documentation only..."
+            uv run mike deploy --push --update-aliases dev
+          else
+            echo "Deploying STABLE documentation..."
+            uv run mike deploy --push --update-aliases $VERSION stable
+            uv run mike set-default --push stable
+            # Also update dev to match stable on a full release
+            uv run mike deploy --push --update-aliases dev
+          fi
+
   publish:
     name: Build and publish to PyPI
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'

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

@@ -16,7 +16,7 @@ repos:
       - id: no-commit-to-branch
         args: [--branch, develop, --branch, main]
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.8"
+    rev: "v0.15.9"
     hooks:
       - id: ruff-check
         args: ["--fix"]
@@ -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