ruff-sync 0.1.5.dev4__tar.gz → 0.1.5.dev6__tar.gz

ruff_sync-0.1.5.dev6/.agents/doc-fix.md

@@ -0,0 +1,160 @@
+# Fix Versioned Documentation CI (`mike` + MkDocs)
+
+## Summary
+
+After researching the official `mike` README, Material for MkDocs docs, and comparing against real-world projects, the current setup has **one fatal flaw** and several secondary problems that have caused versioning to never work correctly.
+
+---
+
+## Root Cause: Two Workflows Fighting Each Other
+
+The most critical issue is that **two separate workflows both deploy docs to `gh-pages` on every push to `main`**, and they use incompatible methods:
+
+| Workflow | Trigger | Command | Effect |
+|---|---|---|---|
+| `ci.yaml` → `publish-docs` | push to `main` | `mike deploy --push dev` | Appends a `dev/` directory and `versions.json` to `gh-pages` |
+| `docs.yaml` → `deploy` | push to `main` | `mkdocs gh-deploy --force` | **Completely overwrites the entire `gh-pages` branch** |
+
+`mkdocs gh-deploy --force` does not know about `mike`. It builds a flat site and force-pushes it as the **sole content** of `gh-pages`. This destroys everything `mike` deployed, including `versions.json`, the `dev/` subdirectory, and the root redirect.
+
+**This is why versioning has never worked: `docs.yaml` immediately destroys `mike`'s work.**
+
+---
+
+## Secondary Issues
+
+### 1. Wrong `alias_type` in `mkdocs.yml`
+- `alias_type: copy` is set, but for GitHub Pages `redirect` is the most reliable option. `copy` creates full file copies for every alias, meaning the `stable` alias contains a complete separate copy of docs that becomes stale when the `stable` alias moves. `symlink` is the default and works on most servers, but GitHub Pages does not follow actual symlinks. `redirect` creates a thin HTML redirect per page at the alias path — the correct approach for GitHub Pages.
+
+### 2. Invalid `mike alias --push stable stable` bootstrap
+- The CI attempts `mike alias --push stable stable` to "ensure `stable` exists." This is nonsensical — it tries to create an alias called `stable` pointing to `stable` (which doesn't exist yet). Mike will error, and the `|| true` suppresses it. It achieves nothing.
+
+### 3. `mike deploy --update-aliases dev` on stable releases
+- When releasing `0.1.4 stable`, the CI also runs `mike deploy --push --update-aliases dev`. This re-deploys the current commit as *both* the stable `0.1.4` and the `dev` version, which makes `dev` identical to `stable`. `dev` should only be updated on commits to `main` when the version is a dev pre-release.
+
+### 4. The `validate-docs-build` job is fine but could use `--no-directory-urls`
+- `mkdocs build --strict` is a good validation step on PRs. No change needed.
+
+---
+
+## Proposed Changes
+
+### [`DELETE`] `.github/workflows/docs.yaml`
+
+This file is the root cause. It must be deleted. All documentation deployment must happen exclusively through `mike` in `ci.yaml`.
+
+---
+
+### [`MODIFY`] `.github/workflows/ci.yaml` — `publish-docs` job
+
+**Fix the deploy logic:**
+
+```yaml
+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: Fetch gh-pages branch
+      # mike needs the gh-pages branch history to make incremental commits.
+      # Without this, mike may fail or corrupt the branch.
+      run: git fetch origin gh-pages --depth=1 || true
+
+    - 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: Configure git
+      run: |
+        git config user.name "github-actions[bot]"
+        git config user.email "github-actions[bot]@users.noreply.github.com"
+
+    - name: Extract version
+      id: version
+      run: |
+        VERSION=$(uv run python -c "
+        import pathlib, tomlkit
+        data = tomlkit.parse(pathlib.Path('pyproject.toml').read_text(encoding='utf-8'))
+        version = data.get('project', {}).get('version') or data.get('version')
+        if not version: raise SystemExit('Version not found')
+        print(version)
+        ")
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        echo "Current Version: $VERSION"
+
+    - name: Deploy dev documentation
+      if: contains(steps.version.outputs.version, '.dev')
+      run: uv run mike deploy --push --update-aliases dev
+
+    - name: Deploy stable documentation
+      if: "!contains(steps.version.outputs.version, '.dev')"
+      run: |
+        VERSION="${{ steps.version.outputs.version }}"
+        uv run mike deploy --push --update-aliases "$VERSION" stable
+        uv run mike set-default --push stable
+```
+
+**Key changes from current:**
+1. Added `git fetch origin gh-pages --depth=1 || true` — required by mike to make incremental commits (per the mike README CI section).
+2. Split the version extraction into its own step with `id: version` so it can be used in `if` conditions.
+3. `dev` is **only** deployed when the version string contains `.dev`. The stable deploy no longer also writes a `dev` alias.
+4. Removed the bogus `mike alias --push stable stable || true` bootstrap.
+
+---
+
+### [`MODIFY`] `mkdocs.yml` — Fix `alias_type`
+
+Change `alias_type` from `copy` to `redirect`:
+
+```yaml
+plugins:
+  - mike:
+      alias_type: redirect   # was: copy
+      canonical_version: stable
+```
+
+`redirect` is the correct choice for GitHub Pages: it creates a lightweight `.html` redirect file at the alias path for every page (e.g., `stable/index.html` redirects to `0.1.4/index.html`). Unlike `symlink`, it works reliably on GitHub Pages. Unlike `copy`, it doesn't create diverging stale copies.
+
+---
+
+### [`MODIFY`] `.agents/skills/mike/SKILL.md`
+
+- Remove the failed repair history section (no longer relevant once fixed)
+- Update the CI workflow documentation to reflect the corrected single-workflow approach
+- Document the critical `git fetch origin gh-pages --depth=1` requirement
+- Document why `docs.yaml` must not exist alongside `mike deploy`
+- Update `alias_type` guidance from `copy` to `redirect`
+
+---
+
+## Verification Plan
+
+### After merging:
+1. Check that `docs.yaml` is deleted and only `ci.yaml` deploys docs.
+2. Watch the next CI run on `main` — the `publish-docs` job should run `mike deploy --push --update-aliases dev`.
+3. Check the `gh-pages` branch: it should contain a `dev/` directory, a `versions.json`, and a root `index.html` redirect.
+4. Visit `https://kilo59.github.io/ruff-sync/` — it should redirect to `dev/` (since no stable version has been deployed yet).
+5. The version selector in the Material theme should appear showing `dev`.
+
+### For stable releases:
+When version is bumped to a non-dev release and merged:
+- `0.x.y/` directory appears on `gh-pages`
+- `stable` alias points to `0.x.y/` via redirects
+- Root redirects to `stable/`
+- Version selector shows both `0.x.y [stable]` and `dev`
+
+> [!IMPORTANT]
+> After deploying, you may need to manually run a one-time `mike deploy --push dev` locally (or trigger the CI) to bootstrap the `gh-pages` branch if it currently contains a flat `mkdocs gh-deploy` dump. You may first want to run `mike delete --all --push` to wipe the broken state.

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev6}/.agents/skills/mike/SKILL.md

@@ -18,10 +18,27 @@ 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.
+1.  **`dev`**: Represents the current `main` branch. Deployed on every push to `main` when the version string contains `.dev`.
+2.  **Stable Releases**: Versioned documentation (e.g., `0.1.4`) created upon release — when the version string does NOT contain `.dev`.
 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).
+
+## mkdocs.yml Configuration
+
+```yaml
+extra:
+  version:
+    provider: mike
+
+plugins:
+  - mike:
+      alias_type: redirect   # NOT 'copy' or 'symlink' — redirect is correct for GitHub Pages
+      canonical_version: stable
+```
+
+### Why `alias_type: redirect`?
+- **`symlink`** (default): Creates actual filesystem symlinks. GitHub Pages does not follow symlinks — the alias directory appears empty.
+- **`copy`**: Duplicates all files at the alias path. Creates stale copies when the alias moves to a new version.
+- **`redirect`**: Creates a thin HTML redirect file for each page at the alias path. Works correctly on GitHub Pages and stays current because it redirects to the canonical versioned path.
 
 ## Theme Overrides
 
@@ -35,13 +52,7 @@ theme:
 
 ### Version switcher
 
-The version switcher is enabled via `extra.version.provider: mike`:
-
-```yaml
-extra:
-  version:
-    provider: mike
-```
+The version switcher is enabled via `extra.version.provider: mike` (shown above).
 
 ## Versioning Banner
 
@@ -51,48 +62,40 @@ A custom banner is displayed when users are viewing the `dev` documentation. Thi
 -   `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 documentation for the <strong>development</strong> version.
-      The latest stable release can be found at <a href="https://kilo59.github.io/ruff-sync/">kilo59.github.io/ruff-sync</a>.
-    </p>
-  </div>
-</div>
-<script>
-  (function() {
-    const version_warning = document.getElementById("version-warning");
-    if (!version_warning) return;
-
-    // mike provides a 'mike' object with some metadata if available
-    // Otherwise fall back to checking the pathname
-    const isDev = window.location.pathname.includes("/dev/") ||
-                 (window.mike && typeof window.mike.version === 'string' && window.mike.version === "dev");
-
-    if (isDev) {
-      version_warning.style.display = "block";
-    }
-  })();
-</script>
-```
+## CI/CD Integration
 
-### 1. Deploying Development Docs
-Run this from the `main` branch to update the `dev` version:
-```bash
-mike deploy dev --push --update-aliases
-```
+> [!CAUTION]
+> **Golden Rule**: Only ONE workflow may ever write to `gh-pages`. If two workflows both deploy to `gh-pages`, the second one will overwrite the first, destroying `versions.json` and all versioned directories.
+>
+> **Never** use `mkdocs gh-deploy` alongside `mike deploy` — they are mutually exclusive deployment strategies. This project uses `mike deploy` exclusively. There is no `docs.yaml` workflow; all deployment happens in `ci.yaml`.
 
-### 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
+The deployment logic is automated in [.github/workflows/ci.yaml](.github/workflows/ci.yaml). The `publish-docs` job:
 
-# Set 'stable' as the default version for the site root
-mike set-default --push stable
+1. **Fetches the `gh-pages` branch** before deploying — this is required by mike to make incremental commits. Without it, mike may reset the entire branch.
+2. **Detects the version** from `pyproject.toml` using `tomlkit`.
+3. **Deploys `dev`** if the version string contains `.dev`.
+4. **Deploys a versioned release + `stable` alias** and sets `stable` as the default if not a dev version.
+
+### Key CI snippet
+
+```yaml
+- name: Fetch gh-pages branch
+  # Required: mike needs the gh-pages branch history for incremental commits.
+  run: git fetch origin gh-pages --depth=1 || true
+
+- name: Deploy documentation
+  run: |
+    git config user.name "github-actions[bot]"
+    git config user.email "github-actions[bot]@users.noreply.github.com"
+
+    VERSION=$(uv run python -c "...")
+
+    if [[ "$VERSION" == *".dev"* ]]; then
+      uv run mike deploy --push --update-aliases dev
+    else
+      uv run mike deploy --push --update-aliases "$VERSION" stable
+      uv run mike set-default --push stable
+    fi
 ```
 
 ## Reference Commands
@@ -104,13 +107,23 @@ mike set-default --push stable
 | **Set Default** | `mike set-default <version>` |
 | **Alias** | `mike alias <version> <alias>` |
 | **Delete** | `mike delete <identifier>` |
+| **Delete all** | `mike delete --all` |
 
-## CI/CD Integration
+### Deploying Development Docs
+Run this from the `main` branch to update the `dev` version:
+```bash
+mike deploy dev --push --update-aliases
+```
 
-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.
+### 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
+```
 
 > [!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.
@@ -130,21 +143,12 @@ The deployment logic is automated in [.github/workflows/ci.yaml](.github/workflo
 ### 404 for `versions.json`
 - If you see a 404 for `/versions.json` but `https://<user>.github.io/<repo>/versions.json` exists, the switcher is looking at the domain root instead of the project root. Verify `site_url` includes the repository name and has a trailing slash.
 
-## Post-Mortem & Known Issues
+### Corrupted/Stale `gh-pages` Branch
+If the `gh-pages` branch was written by `mkdocs gh-deploy` instead of mike, it will be a flat site with no versioning. To reset:
 
-> [!CAUTION]
-> **Current Status**: Documentation versioning is currently **BROKEN** on the live site (`kilo59.github.io/ruff-sync`).
-
-### Failed Repair History
-The following fixes have been attempted and **FAILED** to resolve the issue:
-1.  **Lowercasing `site_url`**: Normalizing the repository name in the URL (e.g., `ruff-sync` instead of `Ruff-Sync`) did not fix the 404s for `versions.json`.
-2.  **Removing `theme.version`**: Removing the redundant Material 9.x config did not restore the switcher.
-3.  **Adding `canonical_version: stable`**: Adding this to the `mike` plugin in `mkdocs.yml` was intended to fix path resolution but has not fixed the root page 404.
-4.  **CI Restoration Logic**: Adding `mike alias --push stable stable` to the CI to manually repair `versions.json` hasn't restored the picker on the root page.
-
-### Root Cause Suspicions
-- **GitHub Pages Subfolder Pathing**: The site is served from a subfolder (`/ruff-sync/`). `mike`'s JavaScript for the version switcher frequently struggles with calculating relative paths to `versions.json` when served from a subfolder if `site_url` or base paths are not perfectly aligned with the deployment environment.
-- **`versions.json` Drift**: The `versions.json` file on the `gh-pages` branch frequently becomes desynchronized or loses the `stable` entry, which triggers `mkdocs-material` to hide the switcher entirely.
-
-### Guidance for Future Agents
-Before attempting another "fix," you **MUST** verify the current state of `versions.json` on the `gh-pages` branch and check the browser console on the live site for 404 paths. Do not assume standard configurations will work without manual verification of the deployed assets.
+```bash
+# WARNING: This deletes all deployed docs. Run locally, then push.
+uv run mike delete --all --push
+# Then trigger a CI run or deploy manually:
+uv run mike deploy --push --update-aliases dev
+```

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev6}/.agents/skills/ruff-sync-usage/references/ci-integration.md

@@ -12,7 +12,10 @@ Add this step to any existing workflow (e.g., `.github/workflows/ci.yaml`):
 ```
 
 `--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.
+`--output-format github` creates inline PR annotations and a structured Job Summary report.
+
+> [!TIP]
+> `ruff-sync` automatically groups multiple drifts in the same file into a single annotation to reduce PR noise.
 
 ### Full Workflow Example
 
@@ -73,7 +76,13 @@ For repositories with GitHub Advanced Security enabled, upload SARIF results to
 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.
+>
+> | 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" |
 
 ---
 

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev6}/.agents/skills/textual/SKILL.md

@@ -51,3 +51,7 @@ if __name__ == "__main__":
 > - **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.
 - **Theme Tokens in Rich Markup**: Textual theme tokens (e.g., `$success`, `$accent`) **cannot** be used directly in Rich markup strings (like in `DataTable` cells). They must be resolved to hex strings at runtime: `str(self.app.get_theme(self.app.theme).success)`.
+- **Type-Safe Queries (No Cast)**: If `typing.cast` is banned (e.g. by `TID251`), use a variable annotation with a targeted `# type: ignore` to resolve `query_one` results:
+  ```python
+  tree: MyTree = app.query_one("#tree-id")  # type: ignore[assignment]
+  ```

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev6}/.agents/skills/textual/references/testing.md

@@ -51,8 +51,15 @@ async with app.run_test() as pilot:
     assert app.query_one(Input).value == "hello"
 ```
 
-### Waiting for Animations/I/O
-If your UI has transitions or performs background work, use `pilot.wait_for_scheduled_animations()` or simply `await pilot.pause(0.1)`.
+### ⏳ Brittle Navigation & Expansion
+When navigating complex structures like a `Tree` with many nodes:
+- **Expansion Wait**: Expanding a node (`pilot.press("right")`) is asynchronous. If the number of child nodes is large, you MUST provide a significant `pilot.pause()` (e.g., 1.5s - 2.0s) before attempting to select or search for children.
+- **Search-and-Verify**: Instead of fixed `down` counts, use a verification loop with a small `pilot.pause(0.02)` between steps to wait for cursor updates.
+
+### 📸 Automated Screenshots (SVG)
+When using `app.save_screenshot()` in a test:
+- **Visibility Matters**: Only widgets and rows that are currently "scrolled into view" are captured in the SVG. Large tables or trees will be truncated unless you explicitly scroll.
+- **Size Specification**: Define a repeatable terminal size in `run_test(size=(W, H))` to ensure consistent screenshot layouts across environments.
 
 > [!IMPORTANT]
 > Always use `pytest-asyncio` with the `@pytest.mark.asyncio` decorator for Textual tests. The boilerplate provided in `app.run_test()` handles the event loop lifecycle for you.

ruff_sync-0.1.5.dev6/.agents/workflows/update-screenshots.md

@@ -0,0 +1,52 @@
+---
+description: Regenerate TUI screenshots for documentation
+---
+
+Use this workflow to update the SVG screenshots of the Ruff-Sync TUI when the user interface, theme, or major features change.
+
+### 1. Regenerate Screenshots
+// turbo
+1. Run the automated screenshot generation task:
+   ```bash
+   uv run invoke screenshots
+   ```
+   *This script launches the TUI headlessly using Textual's testing harness and captures key views to `docs/assets/screenshots/`.*
+
+### 2. Verify Output
+1. Check the `docs/assets/screenshots/` directory for updated `.svg` files:
+   - `dashboard.svg`
+   - `rule_details.svg`
+   - `search_omnibox.svg`
+   - `legend_help.svg`
+2. Ensure the screenshots correctly reflect the current state of the application.
+
+### 3. Update Documentation (Optional)
+1. If new views were added or filenames changed, update the relevant markdown files in `docs/` or `mkdocs.yml`.
+
+### 4. Commit Changes
+1. Stage and commit the updated assets:
+   ```bash
+   git add docs/assets/screenshots/*.svg
+   git commit -m "docs: update TUI screenshots"
+   ```
+
+---
+
+### Adding a New Screenshot View
+
+To add a new view to the automated screenshot rotation:
+
+1.  **Modify the Script**: Edit `scripts/generate_tui_screenshots.py`.
+2.  **Add Navigation**: Use `pilot` commands within the `async with app.run_test()` block:
+    ```python
+    # Navigate to the new view
+    await pilot.press("control+f")  # Example: Open a specific dialog
+    await pilot.pause(0.2)          # Give the UI time to animate
+    ```
+3.  **Capture the Screen**:
+    ```python
+    path = SCREENSHOTS_DIR / "my_new_view.svg"
+    app.save_screenshot(str(path))
+    ```
+4.  **Update Documentation**: Add the new SVG to the relevant Markdown file or `mkdocs.yml`.
+5.  **Regenerate**: Run `uv run invoke screenshots` to verify the new capture works as expected.

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev6}/.github/workflows/ci.yaml

@@ -175,14 +175,17 @@ jobs:
       - name: Install dependencies
         run: uv sync --group docs --frozen
 
+      - name: Fetch gh-pages branch
+        # mike needs the gh-pages branch history to make incremental commits.
+        # Without fetching it first, mike may reset the entire branch.
+        run: git fetch origin gh-pages --depth=1 || true
+
       - 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
@@ -205,17 +208,11 @@ jobs:
 
           if [[ "$VERSION" == *".dev"* ]]; then
             echo "Deploying DEV documentation..."
-            # Ensure 'stable' exists in versions.json so the switcher doesn't disappear.
-            # 'mike alias' will create it if missing, pointing to the current stable root.
-            # We use --push to ensure versions.json is updated on gh-pages.
-            uv run mike alias --push stable stable || true
             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 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:

{ruff_sync-0.1.5.dev4 → ruff_sync-0.1.5.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.1.5.dev4
+Version: 0.1.5.dev6
 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/