ruff-sync 0.1.5.dev2__tar.gz → 0.1.5.dev3__tar.gz

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

@@ -0,0 +1,150 @@
+---
+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 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>
+```
+
+### 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.
+
+## Troubleshooting
+
+### Version Selector Not Appearing
+- **Missing `versions.json`**: Ensure `mike deploy` or `mike update-aliases` has been run. The file must exist at the site root.
+- **Incomplete `versions.json`**: If the current page's version (e.g., `stable`) is not listed in `versions.json`, some themes (like Material) may hide the selector.
+- **`site_url` Case Sensitivity**: On GitHub Pages, ensure `site_url` in `mkdocs.yml` matches the actual deployment URL (usually lowercase). Discrepancies can cause the switcher to fail to find `versions.json` due to 404s.
+- **Redundant Config**: Ensure `theme.version` is NOT set in `mkdocs.yml`. Use `extra.version.provider: mike` instead.
+- **`canonical_version` Missing**: If the switcher is hidden on the root page, adding `canonical_version: stable` (or your main alias) to the `mike` plugin configuration can help the theme associate the root with the switcher metadata.
+
+### 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
+
+> [!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.

{ruff_sync-0.1.5.dev2 → ruff_sync-0.1.5.dev3}/.agents/skills/textual/references/widgets.md

@@ -57,3 +57,29 @@ def on_key(self, event: events.Key) -> None:
 
 > [!TIP]
 > Use `BINDINGS` in your `App` or `Screen` class for most navigation tasks. Textual manages the labels and shortcuts in the `Footer` for you.
+
+### `ModalScreen` & Overlays
+Modals are screens with a transparent or dim background that overlay the main app.
+```python
+from textual.screen import ModalScreen
+from textual.app import App
+
+class OmniboxScreen(ModalScreen[str]):
+    # A modal screen that returns a `str` when dismissed.
+    def compose(self) -> ComposeResult:
+        # yield your input/search widgets here
+        yield Input(placeholder="Search...")
+
+    # Dismiss the screen and return data
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        self.dismiss(event.value)
+
+# In the main App or Screen:
+def on_key(self, event: events.Key) -> None:
+    if event.key == "ctrl+p":
+        self.push_screen(OmniboxScreen(), self.handle_omnibox_result)
+
+def handle_omnibox_result(self, result: str | None) -> None:
+    if result:
+        print(f"Selected: {result}")
+```

{ruff_sync-0.1.5.dev2 → ruff_sync-0.1.5.dev3}/.agents/tui_design.md

@@ -12,7 +12,10 @@ Before we build the TUI feature itself, some of the existing codebase should be
 Currently, `ruff-sync` is primarily concerned with TOML serialization. The TUI introduces a requirement to execute the system `ruff` binary (e.g. `ruff rule <CODE>`).
 **Refactoring Task:**
 - Create a generalized, safe abstraction for interacting with the `ruff` executable.
-- Provide a typed function `async def get_ruff_rule_markdown(rule_code: str) -> str | None` that uses `asyncio.create_subprocess_exec` (or threads with `subprocess`) to fetch and return the rule text. This prevents raw `subprocess` sprawl across TUI widgets.
+- Provide typed async functions:
+    - `async def get_ruff_rule_markdown(rule_code: str) -> str | None`
+    - `async def get_ruff_config_markdown(setting_path: str) -> str | None`
+- These should use `asyncio.create_subprocess_exec` to fetch and return the text. This prevents raw `subprocess` sprawl across TUI widgets.
 
 ### B. Configuration Reader Extraction (`src/ruff_sync/config_io.py` or similar)
 Right now, discovering and extracting the local `pyproject.toml` is slightly coupled to the lifecycle of pulling from upstreams (`pull()` / `check()` in `core.py`).
@@ -59,16 +62,21 @@ Right now, discovering and extracting the local `pyproject.toml` is slightly cou
 ### [NEW] src/ruff_sync/tui/app.py
 - Define `RuffSyncApp` subclassing `textual.app.App`.
 - **CSS**: Define embedded TCSS.
-  - Layout: `Horizontal` split with `Tree` (left) sized `1fr`, and a `Vertical` container (right) sized `2fr`. Left side for Navigation, right side for Content & Inspector.
+  - Layout: `Horizontal` split with `Tree` (left) sized `1fr`, and a `Vertical` container (`#content-pane`) (right) sized `2fr`.
+  - **Dynamic Layout**:
+    - `#category-table` takes **40% height** by default.
+    - `#inspector` (Markdown) takes **60% height** by default.
+    - When the table is hidden, the `#inspector` uses a `.full-height` class (**100% height**) to fill the content pane.
+    - Both widgets utilize `overflow-y: auto` for vertical scrolling only when needed.
 - **Compose Method**:
   ```python
   def compose(self) -> ComposeResult:
       yield Header()
       with Horizontal():
           yield ConfigTree(id="config-tree")
-          with Vertical():
+          with Vertical(id="content-pane"):
               yield CategoryTable(id="category-table")
-              yield RuleInspector(id="inspector", classes="hidden")
+              yield RuleInspector(id="inspector")
       yield Footer()
   ```
 - **Lifecycle (`on_mount`)**:
@@ -87,9 +95,9 @@ Contains all custom Textual widgets required for this view.
 - Automatically clears and updates columns/rows when a tree node is highlighted.
 
 **3. `RuleInspector` (inherits `textual.widgets.Markdown`)**:
-- Displays `ruff rule <CODE>` output.
-- Features an `async def fetch_and_display(self, rule_code: str)` method.
-- **Background Worker**: Uses Textual `@work(thread=True)` to execute our refactored `get_ruff_rule_markdown()` function.
+- Displays documentation for both rules (`ruff rule <CODE>`) and settings (`ruff config <SETTING>`).
+- Features an `async def fetch_and_display(self, target: str, is_rule: bool = True)` method.
+- **Background Worker**: Uses Textual `@work(thread=True)` to execute the appropriate refactored `get_ruff_*_markdown()` function.
 
 ---
 
@@ -98,10 +106,11 @@ Contains all custom Textual widgets required for this view.
 ### [MODIFY] src/ruff_sync/tui/app.py (Reactivity)
 - Tie widgets together using Textual's event routing (`@on`):
   - `@on(Tree.NodeSelected)`:
-      - If the node is a configuration section (e.g. `lint.isort`), hide the Inspector and populate the `CategoryTable` with settings.
-      - If the node represents a list of rules (unwrapped `lint.select`), display the active rule list in the table.
+      - If the node is a configuration section (e.g. `lint.isort`), ensure the `CategoryTable` is visible (remove "hidden" class), remove the `.full-height` class from the inspector, and populate it with settings. It also triggers `inspector.fetch_and_display(section_path, is_rule=False)` to show section-level docs if available.
+      - If the node represents a rule code, add the "hidden" class to `CategoryTable` to maximize vertical space, add the `.full-height` class to the `RuleInspector`, and display the rule via `fetch_and_display(code, is_rule=True)`.
   - `@on(DataTable.RowSelected)`:
-      - If the focused row represents a Ruff Rule Code (e.g., `RUF012`), reveal the `RuleInspector` widget and call `inspector.fetch_and_display("RUF012")`.
+      - If the focused row represents a Ruff Rule Code (e.g., `RUF012`), hide the `CategoryTable`, reveal the `RuleInspector` widget, apply `.full-height`, and call `inspector.fetch_and_display("RUF012", is_rule=True)`.
+      - If the focused row represents a configuration setting, reveal the `RuleInspector` (at default height if table is shown) and call `inspector.fetch_and_display(setting_key, is_rule=False)`.
       - Expose related context natively based on selections.
 
 ---

{ruff_sync-0.1.5.dev2 → ruff_sync-0.1.5.dev3}/.agents/tui_requirements.md

@@ -21,15 +21,19 @@
    - Provide visual grouping for rule categories (e.g., `E` for pycodestyle, `F` for Pyflakes, `TC` for flake8-type-checking).
 3. **Contextual Inspector & Documentation**
    - When a user highlights a specific rule (e.g., `RUF012`), asynchronously execute `ruff rule <CODE>` to fetch and render the official documentation as Markdown.
-   - Surface related context depending on the selection: highlighting a rule exposes its documentation AND related configuration settings; highlighting a config setting might expose its structural definition or the specific rules it governs.
-4. **Fuzzy Search**
+   - When a user highlights a configuration setting (e.g., `lint.isort.combine-as-imports`), asynchronously execute `ruff config <SETTING>` to fetch its documentation, default value, and type information.
+   - Surface related context depending on the selection: highlighting a rule exposes its documentation AND related configuration settings; highlighting a config setting (in the Tree or CategoryTable) exposes its definition and usage examples.
+4. **Rich Metadata Rendering**
+   - The Inspector should distinguish between Rule documentation and Setting documentation.
+   - Setting documentation should clearly call out **Default Value** and **Type** in a dedicated header or sidebar within the inspector.
+5. **Fuzzy Search**
    - A search bar to quickly locate a specific configuration key or rule code without manual scrolling.
 
 ### 2.2 UX / UI Layout Concept
 - **Header:** Application title and current local repository path.
 - **Left Sidebar (Navigation):** `Tree` widget for configuration categories (`Global`, `Linting`, `Formatting`, `Rule Index`).
-- **Center Area (Main Content):** `DataTable` or `ListView` showing the keys and values for the selected category.
-- **Right/Bottom Panel (Inspector):** Context-aware inspector. Because `ruff rule <CODE>` output contains proper Markdown, this panel MUST robustly render Markdown (e.g., utilizing Textual's `Markdown` widget) while dynamically adjoining related setting/rule cross-references around it.
+- **Center Area (Main Content):** `DataTable` or `ListView` showing the keys and values for the selected category. This panel is dynamically hidden when inspecting dense documentation to maximize reading space.
+- **Right/Bottom Panel (Inspector):** Context-aware scrollable inspector (`overflow-y: auto`). Because `ruff rule <CODE>` output contains proper Markdown, this panel MUST robustly render Markdown (e.g., utilizing Textual's `Markdown` widget) while dynamically adjoining related setting/rule cross-references around it.
 - **Footer:** Action key bindings (`q` to Quit, `/` to Search, `?` for Help).
 
 ---

ruff_sync-0.1.5.dev3/.agents/tui_rule_browsing.md

@@ -0,0 +1,44 @@
+# Ruff-Sync TUI: Rule Browsing & Discovery Proposals
+
+This document outlines additional convenience features and alternative navigation paradigms for browsing and exploring specific Ruff rules and groups outside the standard TOML hierarchy.
+
+**Related Documents:**
+- [TUI Requirements](tui_requirements.md)
+- [TUI Technical Design](tui_design.md)
+- [Rule Browsing Detailed Design](tui_rule_browsing_design.md)
+
+## Background
+While the TOML hierarchy (as established in the core requirements) provides an exact structural representation (e.g., exposing `tool.ruff.lint.select`), it is not always the most intuitive way to discover or understand the net set of rules actively evaluating the project.
+
+The following proposals are designed to augment the current "Read-Only" TUI mode to support rapid interrogation, global searching, and global discovery of Ruff rules.
+
+---
+
+## 1. The "Effective Rules" Flat Table
+Instead of exclusively browsing via the TOML tree (`tool.ruff.lint.select`), we introduce a top-level **"Effective Rules"** dashboard.
+- **How it works:** A single, sortable `DataTable` that flattens all configuration vectors (`select`, `extend-select`, `ignore`, `per-file-ignores`) into a definitive list.
+- **Columns:** `Code` (e.g., F401), `Name` (e.g., unused-import), `Category` (e.g., Pyflakes), and `Status` (Enabled/Ignored).
+- **Benefit:** Gives the user a complete, "at-a-glance" ledger of exactly what the linter is checking without having to manually perform the mental math of `select` minus `ignore`.
+
+## 2. Category / Linter Prefix Grouping
+Ruff is conceptually built around "Linters" (e.g., `Pyflakes`, `pycodestyle`, `flake8-bugbear`). The TOML configuration often just specifies a prefix like `select = ["E", "F", "B"]`.
+- **How it works:** Add a new root node in the `Tree` called **"Linters & Categories"**.
+- **Interaction:** Navigating to "flake8-bugbear (B)" displays a table of all `B` rules, instantly showing which ones are locally enabled, ignored, or inactive.
+- **Benefit:** Maps directly to how developers usually think about adding new rulesets to their projects.
+
+## 3. Global Fuzzy Command Palette ("Omnibox")
+Navigating a tree or a table can be tedious if the user knows exactly what they are looking for.
+- **How it works:** A global keybind (e.g., `Ctrl+P` or `/`) that opens a fuzzy search overlay modal.
+- **Interaction:** The user types "unused" and the palette immediately surfaces `F401 (unused-import)`, `F841 (unused-variable)`, etc. Hitting Enter drops them directly into the `RuleInspector` for that specific rule, completely bypassing the Tree hierarchy.
+- **Benefit:** The fastest possible way to interrogate a specific rule.
+
+## 4. Quick-Filter State Toggles
+When inside any view displaying rules (like the flattened table or the prefix grouping), give the user hotkeys to rapidly shift perspectives.
+- **How it works:** Add toggles (e.g., `1: All`, `2: Enabled`, `3: Ignored`).
+- **Benefit:** If a user is looking at a massive category like `E` (pycodestyle), they can quickly press `3` to filter the table down to ONLY the rules they explicitly ignored, providing an instant audit trail.
+
+## 5. "Rule Registry" / Discovery Mode
+Currently, the user only sees rules they explicitly mention in their `pyproject.toml` or have inherited. How do they discover new rules to adopt?
+- **How it works:** By executing `ruff rule --all` under the hood, the TUI could populate a "Discovery" tab. This lists every single rule Ruff supports.
+- **Visuals:** Rules that are currently enabled in the local project are highlighted or checked off.
+- **Benefit:** Huge value-add for configuration exploration. Users can browse new rules they might want to adopt directly inside the TUI without referring back to the Ruff website.

ruff_sync-0.1.5.dev3/.agents/tui_rule_browsing_design.md

@@ -0,0 +1,66 @@
+# Detailed Implementation Plan: Effective Rules & Omnibox
+
+This document provides exhaustive technical instructions to implement Features 1 (Effective Rules Flat Table) and 3 (Global Fuzzy Command Palette) from the [Rule Browsing Proposals](tui_rule_browsing.md).
+
+---
+
+## 1. Data Access & Subprocess Upgrades
+To present a flat list of rules or allow fuzzy searching across all rules, the TUI must have structural knowledge of every rule Ruff supports.
+
+### A. `get_all_ruff_rules() -> list[dict]`
+- In `src/ruff_sync/system.py` (or the equivalent subprocess wrapper module), implement an async function that executes `uv run ruff rule --all --output-format json` (or `ruff rule --all --output-format json` depending on the environment context).
+- This returns a JSON array of objects representing all rules (fields include `name`, `code`, `linter`, `summary`, etc.).
+
+### B. `get_ruff_linters() -> list[dict]`
+- Implement an async function that executes `ruff linter --output-format json`. Returns categories/prefixes (fields include `prefix`, `name`, `categories`).
+
+### C. Active Rule Evaluation Logic
+- Create a pure utility function `compute_effective_rules(all_rules: list[dict], toml_config: dict) -> list[dict]`.
+- `toml_config` is the unwrapped TOML dictionary.
+- The function iterates over `all_rules`. For each rule, it checks the rule's `code` (e.g. `F401`) against the `[tool.ruff.lint]` keys `select`, `ignore`, `extend-select`.
+- **Heuristic**: Length-based prefix matching. If `select = ["F"]` and `ignore = ["F401"]`, `F401` matches both. Since `F401` (len 4) is a longer and more specific prefix match than `F` (len 1), `ignore` wins. The rule is marked with `status="Ignored"`. If it was only partially matched in `select` it gets `status="Enabled"`.
+- Return an enriched list of dictionaries mimicking the original rules but adding a `status` key.
+
+---
+
+## 2. The "Effective Rules" Flat Table UI
+
+### A. Tree Hierarchy Updates (`src/ruff_sync/tui/widgets.py`)
+- Modify the `ConfigTree` (which parses the `pyproject.toml` hierarchy) to inject a synthetic root node at the very top: **"Effective Active Rules"**.
+
+### B. Table Integration (`src/ruff_sync/tui/app.py` & `widgets.py`)
+- When the user selects the "Effective Active Rules" tree node, intercept the event in `@on(Tree.NodeSelected)`.
+- Make the `CategoryTable` visible and hide the `RuleInspector` initially.
+- Clear existing columns and add `["Code", "Name", "Linter", "Status"]`.
+- Fetch the enriched rules list from `compute_effective_rules`.
+- Iterate the enriched rules, adding them to the `CategoryTable`. Use Textual Rich markup (e.g., `[green]Enabled[/green]`, `[red]Ignored[/red]`) for the Status column.
+
+### C. Row Selection Linkage
+- Ensure `@on(DataTable.RowSelected)` correctly parses the Row Data to extract the "Rule Code" (e.g. `F401`).
+- Hiding the Table and revealing the `RuleInspector` should fire seamlessly by calling `self.query_one("#inspector").fetch_and_display(rule_code, is_rule=True)`.
+
+---
+
+## 3. The Global Fuzzy "Omnibox" UI
+
+### A. App-Level Keybind (`src/ruff_sync/tui/app.py`)
+- In `RuffSyncApp.BINDINGS`, add `("/", "search", "Search Rules")`.
+- Add `def action_search(self) -> None:` to intercept the hotkey.
+
+### B. `OmniboxScreen` Widget (`src/ruff_sync/tui/screens.py`)
+- Create a module `screens.py` and define `class OmniboxScreen(ModalScreen[str]):`.
+- `compose()` should yield an `Input(placeholder="Search rules (e.g. F401, unused)...")` and optionally an initially-empty `OptionList` or `ListView` beneath it for results.
+- **TCSS**: Center the `OmniboxScreen` contents vertically and horizontally. Give the main container a distinct background color and border to pop out over the main App.
+
+### C. Fuzzy Search Logic (`@on(Input.Changed)`)
+- Read `all_rules` from the background fetching mechanism.
+- For every keystroke (`Input.Changed`), perform a simple substring or fuzzy match against both `rule["code"]` and `rule["name"]`.
+- Populate the `ListView`/`OptionList` with the top 10-15 matches.
+
+### D. Submission (`@on(Input.Submitted)` or `OptionList.OptionSelected`)
+- When the user hits enter on a search result, call `self.dismiss(result_rule_code)`.
+
+### E. App Callback Integration
+- In `action_search`, execute `self.push_screen(OmniboxScreen(), self.handle_omnibox_result)`.
+- `def handle_omnibox_result(self, rule_code: str | None) -> None:`
+- If `rule_code` is provided, act exactly as if a row was selected in the `CategoryTable`: Hide the table, show the inspector via `self.query_one("#inspector").fetch_and_display(rule_code, is_rule=True)`.

{ruff_sync-0.1.5.dev2 → ruff_sync-0.1.5.dev3}/.github/workflows/ci.yaml

@@ -84,6 +84,25 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           slug: Kilo59/ruff-sync
 
+  test-no-optional-deps:
+    name: Test without optional dependencies
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install ruff-sync (no extras)
+        # We install only the base package without 'dev' or 'tui' groups.
+        run: pip install .
+
+      - name: Run optional dependency validation script
+        run: bash tests/test_minimal_imports.sh
+
   pre-publish:
     name: Test package installation
     needs: [static-analysis, tests]
@@ -185,7 +204,11 @@ jobs:
           echo "Current Version: $VERSION"
 
           if [[ "$VERSION" == *".dev"* ]]; then
-            echo "Deploying DEV documentation only..."
+            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..."

{ruff_sync-0.1.5.dev2 → ruff_sync-0.1.5.dev3}/PKG-INFO

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

ruff_sync-0.1.5.dev3/docs/overrides/partials/version_warning.html

@@ -0,0 +1,27 @@
+{% if config.extra.version and config.extra.version.provider == "mike" %}
+<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>
+{% endif %}

{ruff_sync-0.1.5.dev2 → ruff_sync-0.1.5.dev3}/mkdocs.yml

@@ -1,6 +1,6 @@
 site_name: ruff-sync
 site_description: Synchronize Ruff linter configuration across Python projects.
-site_url: https://Kilo59.github.io/ruff-sync/
+site_url: https://kilo59.github.io/ruff-sync/
 
 repo_name: Kilo59/ruff-sync
 repo_url: https://github.com/Kilo59/ruff-sync
@@ -26,8 +26,6 @@ theme:
       toggle:
         icon: material/brightness-4
         name: Switch to light mode
-  version:
-    method: mike
   features:
     - content.code.copy
     - content.tabs.link
@@ -98,6 +96,7 @@ plugins:
   - search
   - mike:
       alias_type: copy
+      canonical_version: stable
   - gen-files:
       scripts:
         - docs/gen_ref_pages.py

{ruff_sync-0.1.5.dev2 → ruff_sync-0.1.5.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ruff-sync"
-version = "0.1.5.dev2"
+version = "0.1.5.dev3"
 description = "Synchronize Ruff linter configuration across projects"
 keywords = ["ruff", "linter", "config", "synchronize", "python", "linting", "automation", "tomlkit", "pre-commit"]
 authors = [
@@ -41,6 +41,7 @@ Changelog = "https://github.com/Kilo59/ruff-sync/releases"
 
 [project.scripts]
 ruff-sync = "ruff_sync:main"
+ruff-inspect = "ruff_sync:inspect"
 
 [dependency-groups]
 dev = [
@@ -57,6 +58,7 @@ dev = [
     "respx>=0.21.1",
     "ruamel-yaml>=0.18.6",
     "ruff>=0.15.0",
+    "textual>=8.2.2",
     "wily>=1.25.0",
 ]
 docs = [

{ruff_sync-0.1.5.dev2 → ruff_sync-0.1.5.dev3}/src/ruff_sync/__init__.py

@@ -9,6 +9,7 @@ from .cli import (
     Arguments,
     __version__,
     get_config,
+    inspect,
     main,
 )
 from .config_io import (
@@ -46,6 +47,7 @@ __all__ = [
     "get_formatter",
     "get_ruff_config",
     "get_ruff_tool_table",
+    "inspect",
     "is_ruff_toml_file",
     "load_local_ruff_config",
     "main",

{ruff_sync-0.1.5.dev2 → ruff_sync-0.1.5.dev3}/src/ruff_sync/cli.py

@@ -42,6 +42,7 @@ from ruff_sync.core import (
     pull,
     resolve_raw_url,
 )
+from ruff_sync.dependencies import DependencyError
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Mapping
@@ -378,6 +379,9 @@ def _resolve_upstream(args: CLIArguments, config: Config) -> tuple[URL, ...]:
             f"got {type(config_upstream).__name__}"
         )
 
+    if args.command == "inspect":
+        return ()
+
     PARSER.error(
         "❌ the following arguments are required: upstream "
         f"(or define it in [tool.ruff-sync] in {RuffConfigFileName.PYPROJECT_TOML}) 💥"
@@ -599,25 +603,37 @@ def main() -> int:
 
     try:
         if exec_args.command == "inspect":
-            from ruff_sync.dependencies import require_dependency  # noqa: PLC0415
-
-            try:
-                require_dependency("textual", extra_name="tui")
-            except ImportError as e:
-                LOGGER.error(f"❌ {e}")  # noqa: TRY400
-                return 1
+            from ruff_sync.tui import get_tui_app  # noqa: PLC0415
 
-            LOGGER.error("❌ The Terminal UI (inspect) is not yet implemented.")
-            return 1
+            app_class = get_tui_app()
+            return app_class(exec_args).run() or 0
 
         if exec_args.command == "check":
             return asyncio.run(check(exec_args))
         return asyncio.run(pull(exec_args))
+    except DependencyError as e:
+        LOGGER.error(f"❌ {e}")  # noqa: TRY400
+        return 1
     except UpstreamError as e:
         for url, err in e.errors:
             LOGGER.error(f"❌ Failed to fetch {url}: {err}")  # noqa: TRY400
         return 4
 
 
+def inspect() -> int:
+    """Entry point for the ruff-inspect console script."""
+    # Handle optional subcommands/args if user passed any to ruff-inspect
+    # but primarily ensure "inspect" is the command.
+    if len(sys.argv) > 1 and sys.argv[1] not in ("-h", "--help", "--version"):
+        # If they passed args but no command, insert 'inspect'
+        if sys.argv[1] not in ("pull", "check", "inspect"):
+            sys.argv.insert(1, "inspect")
+    else:
+        # Default to 'inspect' if no args or just flags
+        sys.argv.insert(1, "inspect")
+
+    return main()
+
+
 if __name__ == "__main__":
     sys.exit(main())