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

ruff_sync-0.1.5.dev2/.agents/DEPENDENCIES.md

@@ -0,0 +1,47 @@
+# Optional Dependencies & Lazy Loading
+
+To keep the `ruff-sync` CLI fast and lightweight, while still allowing for extensible features (like a TUI or specialized formatters), we use a standardized pattern for **Optional Dependencies**.
+
+## Requirements
+
+1. **Defensive Coding**: The application must never crash at startup if an optional dependency is missing. Instead, it should fail gracefully ONLY when the specific feature requiring that dependency is invoked.
+2. **Delayed Import Cycles**: We must avoid expensive imports of optional dependencies during the initial CLI application boot.
+3. **User-Friendly Errors**: If a dependency is missing, we must provide clear instructions on how the user can install it using `ruff-sync` extras.
+
+## Standard Pattern
+
+All code that relies on an optional dependency MUST follow this pattern:
+
+### 1. Define the Extra in `pyproject.toml`
+
+Add the dependency to the `[project.optional-dependencies]` section.
+
+```toml
+[project.optional-dependencies]
+tui = ["textual>=8.2.2"]
+```
+
+### 2. Check and Lazy-Import (Locally)
+
+Never import optional dependencies at the top level of a module. All imports must happen inside the function or method that requires them, AFTER a defensive check.
+
+```python
+def run_tui_feature():
+    # 1. First, check availability (fast, lightweight)
+    from ruff_sync.dependencies import require_dependency
+    require_dependency("textual", extra_name="tui")
+
+    # 2. Then, perform local import (delayed expensive cycle)
+    from textual.app import App
+    ...
+```
+
+## The Dependency Helper (`ruff_sync.dependencies`)
+
+Use the utilities in `src/ruff_sync/dependencies.py` to handle these checks.
+
+- `is_installed(package_name: str) -> bool`: A fast check using `importlib.util.find_spec` that doesn't trigger the package initialization.
+- `require_dependency(package_name: str, extra_name: str) -> None`: Checks if a package is installed and raises a helpful `ImportError` if it is not.
+
+### Example ImportError
+> "The 'textual' package is required for this feature. Install it with: pip install 'ruff-sync[tui]'"

{ruff_sync-0.1.4.dev1 → ruff_sync-0.1.5.dev2}/.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.dev2/.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.dev2/.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.dev2/.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.dev2/.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.dev2/.agents/skills/mike/SKILL.md

@@ -0,0 +1,106 @@
+---
+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.
+4.  **`latest`**: An alias pointing to the most recent release (including dev, if applicable).
+
+## Theme Overrides
+
+To support the version switcher and custom banners, the project uses a `custom_dir` override in `mkdocs.yml`:
+
+```yaml
+theme:
+  name: material
+  custom_dir: docs/overrides
+```
+
+### Version switcher
+
+The version switcher is enabled via `extra.version.provider: mike`:
+
+```yaml
+extra:
+  version:
+    provider: mike
+```
+
+## Versioning Banner
+
+A custom banner is displayed when users are viewing the `dev` documentation. This is handled via `docs/overrides/main.html` and `docs/overrides/partials/version_warning.html`.
+
+### How it works:
+-   `main.html`: Extends the base template and includes the `version_warning.html` partial at the start of the `content` block.
+-   `version_warning.html`: Contains an HTML snippet that is hidden by default and shown via JavaScript if the URL path contains `/dev/`.
+
+Example in `version_warning.html`:
+```html
+<div id="version-warning" style="display: none;">
+  <div class="admonition warning">
+    <p class="admonition-title">Warning</p>
+    <p>You are viewing the development version of the documentation.</p>
+  </div>
+</div>
+<script>
+  if (window.location.pathname.includes("/dev/")) {
+    document.getElementById("version-warning").style.display = "block";
+  }
+</script>
+```
+
+### 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.dev2/.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.dev1 → ruff_sync-0.1.5.dev2}/.agents/skills/mkdocs-generation/templates/mkdocs.yml

@@ -10,10 +10,13 @@ repo_name: [GITHUB_USER]/[REPO_NAME]
 extra:
   version:
     provider: mike
-    default: latest
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/[GITHUB_USER]/[REPO_NAME]
 
 theme:
   name: material
+  custom_dir: docs/overrides
   features:
     - navigation.sections
     - navigation.top

{ruff_sync-0.1.4.dev1 → ruff_sync-0.1.5.dev2}/.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.dev2/.agents/skills/textual/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: textual
+description: Build sophisticated Terminal User Interfaces (TUIs) in Python using an async, CSS-inspired framework.
+---
+
+# Textual TUI Framework (>=8.2.2)
+
+Textual is a Python framework for creating interactive, beautiful Terminal User Interfaces (TUIs). It uses an asynchronous engine and a layout system inspired by modern web development (Flexbox/Grid and CSS).
+
+## Quick Start
+
+```python
+from __future__ import annotations
+from textual.app import App, ComposeResult
+from textual.widgets import Header, Footer, Static
+
+class SimpleApp(App[None]):
+    """A minimal Textual app."""
+    BINDINGS = [("q", "quit", "Quit")]
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("Hello, [bold blue]Textual[/bold blue]!")
+        yield Footer()
+
+if __name__ == "__main__":
+    SimpleApp().run()
+```
+
+## Core Workflow
+
+1. **`compose()`**: Define the UI structure by `yield`-ing widgets.
+2. **Styling**: Use **TCSS** (Textual Cascading Style Sheets) for layout and design.
+3. **Event Handlers**: Handle interaction via specially named methods (e.g., `on_button_pressed`).
+4. **Reactivity**: Use `reactive` attributes to automatically update the UI when data changes.
+
+## Progressive Disclosure (Detailed References)
+
+- [**Styling & Layout**](references/styling.md): TCSS, Flexbox, Grid, and Units.
+- [**Events & Reactivity**](references/events.md): Message passing, watchers, and state management.
+- [**Widget Library**](references/widgets.md): Common components (DataTable, Input, ListView).
+- [**Testing**](references/testing.md): Unit testing apps with `pilot` and `App.run_test`.
+
+## Gotchas & Breaking Changes (>=8.2.2)
+
+> [!WARNING]
+> - **8.2.2 Breaking Changes**:
+>   - `Static.renderable` and `Label.renderable` are now **`Static.content`** and **`Label.content`**.
+>   - `Select.BLANK` is now **`Select.NULL`**.
+> - **Fractional Units**: Use `fr` for fractional units (e.g. `width: 1fr`). A common typo is `rf`, which is invalid.
+> - **Async Handlers**: Event handlers can be `async def` or `def`. Use `async` if you need to `await` I/O or `post_message`.
+> - **Main Thread**: Do not block the main thread with long-running synchronous code. Use `self.run_worker()` for background tasks.

ruff_sync-0.1.5.dev2/.agents/skills/textual/examples/basic_app.py

@@ -0,0 +1,62 @@
+"""A minimal Textual app boilerplate."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from textual.app import App, ComposeResult
+from textual.containers import Vertical
+from textual.widgets import Button, Footer, Header, Static
+
+
+class BasicApp(App[None]):
+    """A minimal Textual app boilerplate."""
+
+    # v8.x.x: Specify a default theme
+    theme: ClassVar[str] = "nord"
+
+    BINDINGS: ClassVar[list[tuple[str, str, str]]] = [
+        ("q", "quit", "Quit application"),
+        ("d", "toggle_dark", "Toggle Dark Mode"),
+    ]
+
+    CSS = """
+    Screen {
+        align: center middle;
+    }
+
+    Vertical {
+        width: 30;
+        height: auto;
+        border: solid $accent;
+        padding: 1;
+    }
+
+    Static {
+        text-align: center;
+        width: 100%;
+        margin-bottom: 1;
+    }
+
+    /* v8.x.x: New pointer rule */
+    Button {
+        pointer: pointer;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        """Compose the UI."""
+        yield Header()
+        with Vertical():
+            yield Static("Basic Textual App")
+            yield Button("Click Me!", id="hello-btn", variant="primary")
+        yield Footer()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle button press events."""
+        if event.button.id == "hello-btn":
+            self.notify("Action Triggered!")
+
+
+if __name__ == "__main__":
+    BasicApp().run()

ruff_sync-0.1.5.dev2/.agents/skills/textual/examples/reactive_example.py

@@ -0,0 +1,51 @@
+"""Demonstrating Textual's reactive system."""
+
+from __future__ import annotations
+
+from textual.app import App, ComposeResult
+from textual.containers import Container
+from textual.reactive import reactive
+from textual.widgets import Footer, Header, Input, Static
+
+
+class ReactiveApp(App[None]):
+    """Demonstrating Textual's reactive system."""
+
+    # Reactive attribute: UI can respond to changes automatically
+    search_query: reactive[str] = reactive("")
+
+    CSS = """
+    #status {
+        background: $primary;
+        color: $text;
+        /* v8.x.x: Simplified padding for text content */
+        text-padding: 1 2;
+        margin-top: 1;
+        width: 100%;
+        text-align: center;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        """Compose the UI."""
+        yield Header()
+        with Container():
+            yield Input(placeholder="Type to search...", id="search-input")
+            yield Static("Waiting for input...", id="status")
+        yield Footer()
+
+    def watch_search_query(self, query: str) -> None:
+        """Called automatically when search_query changes."""
+        status = self.query_one("#status")
+        if query:
+            status.update(f"Searching for: [bold]{query}[/bold]")
+        else:
+            status.update("Waiting for input...")
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        """Update reactive state on input."""
+        self.search_query = event.value
+
+
+if __name__ == "__main__":
+    ReactiveApp().run()