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

@@ -21,8 +21,50 @@ 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).
 
-## Core Workflows
+## 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:

{ruff_sync-0.1.5.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.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()

ruff_sync-0.1.5.dev2/.agents/skills/textual/references/events.md

@@ -0,0 +1,84 @@
+# Events & Reactivity
+
+Textual uses a powerful event-driven architecture and a reactive state system to keep the UI in sync with your data.
+
+## Event Handlers
+
+Naming follows the convention: `on_<widget_name>_<event_type>`.
+
+```python
+class MySidebar(Vertical):
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle any button press within the sidebar."""
+        self.log(f"Button {event.button.id} was pressed!")
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        """Handle specifically an Input widget change."""
+        self.app.notify(f"Searching for: {event.value}")
+```
+
+## Theming (v8.x.x)
+
+Textual v8.x.x introduced a robust theming system.
+
+- **`App.theme`**: Set the active theme (e.g., `self.theme = "nord"`).
+- **`App.register_theme(theme)`**: Add custom themes to the app.
+- **`App.search_themes()`**: Bring up the theme switcher in the command palette.
+- **`variant`**: Use `Button(variant="primary")` or `Label(variant="warning")` for themed styles.
+
+## Reactive Attributes
+
+Define `reactive` attributes to automatically trigger updates. Use `watch_<attribute_name>` to side-effect when a value changes.
+
+```python
+from textual.reactive import reactive
+
+class Counter(Static):
+    # Reactive state: UI updates whenever 'count' is modified
+    count: reactive[int] = reactive(0)
+
+    def watch_count(self, old_value: int, new_value: int) -> None:
+        """Called automatically when count changes."""
+        self.update(f"Current Count: {new_value}")
+
+    def on_click(self) -> None:
+        self.count += 1
+```
+
+## Message Passing
+
+Widgets can communicate with parents via custom messages:
+
+1. **Define a Message**:
+   ```python
+   from textual.message import Message
+   class DataLoaded(Message):
+       def __init__(self, data: list[str]) -> None:
+           self.data = data
+           super().__init__()
+   ```
+2. **Post it**: `self.post_message(DataLoaded(my_data))`
+3. **Handle it in Parent**:
+   ```python
+   def on_data_loaded(self, event: DataLoaded) -> None:
+       self.query_one(DataTable).add_rows(event.data)
+   ```
+
+## Procedure: Implementing a Search Feature
+
+1. **Reactive Search Query**:
+   ```python
+   search_query: reactive[str] = reactive("")
+   ```
+2. **Watch the Query**:
+   ```python
+   def watch_search_query(self, query: str) -> None:
+       """Perform search whenever the query changes."""
+       results = self.search_database(query)
+       self.results_container.update_results(results)
+   ```
+3. **Bridge from UI**:
+   ```python
+   def on_input_changed(self, event: Input.Changed) -> None:
+       self.search_query = event.value
+   ```

ruff_sync-0.1.5.dev2/.agents/skills/textual/references/styling.md

@@ -0,0 +1,54 @@
+# Styling & Layout (TCSS)
+
+Textual uses **TCSS** (Textual Cascading Style Sheets) for design. It is similar to web CSS but optimized for the terminal grid.
+
+## Core Units
+
+- **`fr`**: Fractional units (e.g., `1fr`, `2fr`). Divides available space proportionally.
+- **`%`**: Percentage of the parent container's dimension.
+- **`vh` / `vw`**: Percentage of the entire terminal window height/width.
+- **Integers**: Represent exact terminal character cells (e.g., `width: 20;`).
+
+- **`Vertical`**: Stack widgets top-to-bottom.
+- **`Horizontal`**: Align widgets left-to-right.
+- **`Grid`**: A flexible 2D grid layout. Define `grid-size`, `grid-columns`, and `grid-rows`.
+
+## New CSS Rules (v8.x.x)
+
+- **`pointer`**: Change the mouse cursor style (e.g., `pointer: pointer;`, `pointer: text;`).
+- **`background-tint`**: Apply a translucent color over the background (e.g., `background-tint: $primary 20%;`).
+- **`text-padding`**: Simplified padding for text content within a widget (e.g., `text-padding: 1 2;`).
+- **`scroll-bar-visibility`**: Control when scrollbars are shown (`auto`, `visible`, `hidden`).
+- **`position`**: Support for `relative` and `absolute` positioning.
+
+## Procedure: Rapid Styling
+
+1. **Assign IDs or Classes**:
+   ```python
+   yield Button("Save", id="save-btn", classes="primary-action")
+   ```
+2. **Define TCSS**:
+   ```css
+   .primary-action {
+       background: $accent;
+       color: $text;
+       text-style: bold;
+       width: 100%;
+   }
+
+   #save-btn {
+       border: heavy $success;
+   }
+   ```
+3. **Reference CSS in App**:
+   ```python
+   class MyApp(App):
+       CSS_PATH = "styles.tcss"  # Relative to the Python file
+   ```
+
+## Built-in Design System
+
+Textual includes a set of semantic variables (`$primary`, `$secondary`, `$accent`, `$error`, `$success`) that automatically adapt to the user's terminal theme.
+
+> [!TIP]
+> Use `textual console` or `textual run --dev` to see live styling updates without restarting the application.

ruff_sync-0.1.5.dev2/.agents/skills/textual/references/testing.md

@@ -0,0 +1,58 @@
+# Testing & Debugging
+
+Textual apps are inherently asynchronous. Testing requires simulating user input and observing the UI state.
+
+## Unit Testing with Pilot
+
+Use the `pilot` object to interact with your app in a headless state.
+
+```python
+import pytest
+from my_app import SimpleApp
+
+@pytest.mark.asyncio
+async def test_button_click():
+    app = SimpleApp()
+    async with app.run_test() as pilot:
+        # Simulate a button click by CSS selector or ID
+        await pilot.click("#say-hello-btn")
+
+        # New in v8.x.x: Rapid clicks (double click)
+        await pilot.click("#say-hello-btn", times=2)
+        # OR use dedicated methods:
+        await pilot.double_click("#say-hello-btn")
+        await pilot.triple_click("#say-hello-btn")
+
+        # Verify state
+        assert app.notification_count >= 1
+```
+
+## Developer Tools
+
+Textual includes powerful tools for live development.
+
+### Textual Devtools
+In one terminal, run:
+```bash
+textual console
+```
+In another, run your app with the `--dev` flag:
+```bash
+textual run --dev my_app.py
+```
+Logs and tracebacks will stream to the console, allowing you to see `self.log()` output and `print()` statements without breaking the UI.
+
+## Procedures
+
+### Simulating Text Entry
+```python
+async with app.run_test() as pilot:
+    await pilot.press("h", "e", "l", "l", "o", "enter")
+    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)`.
+
+> [!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.dev2/.agents/skills/textual/references/widgets.md

@@ -0,0 +1,59 @@
+# Widget Library
+
+Textual includes a rich set of built-in widgets. Always check `textual.widgets` before building your own.
+
+## Content & Navigation
+
+- **`Header`**: Standard title bar with optional clock.
+- **`Footer`**: Keybinding bar (automatically populated from `BINDINGS`).
+- **`Static`**: Pure text or basic content. Use **`content`** (v8.x.x) for raw renderable or `markup=True`.
+- **`Link`**: (v8.x.x) New widget for clickable URLs.
+- **`ProgressBar`**: Real-time progress tracking.
+
+## Interaction
+
+- **`Button`**: Standard clickable button. Variants: `success`, `error`, `primary`, `warning`.
+- **`Input`**: Text entry field. Events: `Changed`, `Submitted`.
+- **`MaskedInput`**: (v8.x.x) New widget for formatted inputs (e.g. phones, CC, etc.).
+- **`Checkbox`** / **`Switch`**: Boolean state inputs.
+- **`Select`**: Dropdown selection. Sentinel: **`Select.NULL`** (v8.x.x).
+
+## Data & Selection
+
+### `DataTable`
+High-performance grid for tabular data.
+
+```python
+table = self.query_one(DataTable)
+table.add_columns("ID", "Name", "Score")
+table.add_row("1", "Alice", "100")
+```
+
+### `ListView` & `ListItem`
+Scrollable lists of items.
+
+```python
+list_view = self.query_one(ListView)
+list_view.append(ListItem(Static("Item One")))
+```
+
+## Procedures
+
+### Adding Data to a Table
+
+1. **Clear existing rows**: `table.clear()`
+2. **Batch add rows**: `table.add_rows(data_generator_or_list)`
+3. **Control selection**: `table.cursor_type = "row"` (default is `"cell"`)
+
+### Handling Keyboard Input
+
+Use the `on_key` handler for low-level input:
+
+```python
+def on_key(self, event: events.Key) -> None:
+    if event.key == "ctrl+s":
+        self.save_data()
+```
+
+> [!TIP]
+> Use `BINDINGS` in your `App` or `Screen` class for most navigation tasks. Textual manages the labels and shortcuts in the `Footer` for you.

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

@@ -0,0 +1,140 @@
+# Implementation Plan: Ruff-Sync Read-Only TUI (`inspect`)
+
+This document provides a thorough, step-by-step technical design for implementing the initial "Read-Only" TUI to interrogate and visualize `ruff` configurations. This follows the requirements established in `.agents/tui_requirements.md`.
+
+---
+
+## 1. Pre-Requisite Refactoring & Architecture Upgrades
+
+Before we build the TUI feature itself, some of the existing codebase should be refactored to better support isolated Data Access and Subprocess management.
+
+### A. Subprocess Wrapper (`src/ruff_sync/system.py` or `ruff_cli.py`)
+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.
+
+### 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`).
+**Refactoring Task:**
+- Extract a clean Data Access Object or helper (e.g., `def load_local_ruff_config(path: Path) -> dict[str, Any]`) that utilizes `resolve_target_path`, parses via `tomlkit`, and automatically calls `.unwrap()` to return a plain, read-only Python dictionary. This insulates the Textual app from navigating bizarre `tomlkit` proxy tables.
+
+---
+
+## 2. Dependency & CLI Integration
+
+### [MODIFY] pyproject.toml
+- Under `[project.optional-dependencies]`, define the `tui` extra explicitly pinning the Textual version framework (v8.x.x):
+  ```toml
+  [project.optional-dependencies]
+  tui = ["textual>=8.2.2"]
+  ```
+
+### [MODIFY] src/ruff_sync/cli.py
+- Add an `inspect` subcommand to `PARSER` inside `_get_cli_parser()`:
+  ```python
+  inspect_parser = subparsers.add_parser(
+      "inspect",
+      parents=[common_parser],
+      help="Open a Terminal UI to explore and interrogate your local ruff configuration."
+  )
+  ```
+- In `main()`, route the `inspect` command to a lazy-loaded wrapper:
+  ```python
+  if exec_args.command == "inspect":
+      from ruff_sync.dependencies import require_dependency
+      require_dependency("textual", extra_name="tui")
+
+      from ruff_sync.tui.app import RuffSyncApp
+      return RuffSyncApp(exec_args).run()
+  ```
+
+---
+
+## 3. TUI Application Structure & Views
+
+### [NEW] src/ruff_sync/tui/__init__.py
+- Mark as a Python package.
+
+### [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.
+- **Compose Method**:
+  ```python
+  def compose(self) -> ComposeResult:
+      yield Header()
+      with Horizontal():
+          yield ConfigTree(id="config-tree")
+          with Vertical():
+              yield CategoryTable(id="category-table")
+              yield RuleInspector(id="inspector", classes="hidden")
+      yield Footer()
+  ```
+- **Lifecycle (`on_mount`)**:
+  - Automatically load `[tool.ruff]` via our refactored reader function.
+  - Populate the `ConfigTree` with top-level keys (`lint`, `format`, etc.).
+
+### [NEW] src/ruff_sync/tui/widgets.py
+Contains all custom Textual widgets required for this view.
+
+**1. `ConfigTree` (inherits `textual.widgets.Tree`)**:
+- Parses the unwrapped dictionary representation of the Ruff config.
+- Builds interactive nodes for structural hierarchies (e.g. `lint.select`, `format`).
+
+**2. `CategoryTable` (inherits `textual.widgets.DataTable`)**:
+- Displays key-value sets dynamically.
+- 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.
+
+---
+
+## 4. Textual Events & Data Flow
+
+### [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.
+  - `@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")`.
+      - Expose related context natively based on selections.
+
+---
+
+## 5. Strict Static Typing & mypy Guidelines
+
+Because `ruff-sync` operates under strict mypy regulations, the TUI module must explicitly conform to static type safety.
+
+**Key Typing Considerations:**
+1. **Textual App Generics:** Subclass `App` with its expected return type. If the app just runs and quits without returning a value, define it as `class RuffSyncApp(App[None]):`.
+2. **Event Handler Signatures:** Utilize specific type hints internally provided by Textual for event payloads. For example:
+   ```python
+   async def on_tree_node_selected(self, event: Tree.NodeSelected[Any]) -> None:
+   ```
+3. **Handling `tomlkit` Types (NO `cast`):** `tomlkit`'s proxy objects often resolve ambiguously. Because `typing.cast` is forbidden in production code, when calling `.unwrap()` inside the `ConfigReader` refactor, you **must use explicit `isinstance` checks`** or `TypeGuard` functions (e.g. `if not isinstance(unwrapped_data, dict): raise TypeError(...)`) to strictly narrow the type initially.
+4. **Structured Data over Dicts:** Instead of passing around plain `dict[str, Any]` between the Data Access Object and the Textual widgets, deeply recommend defining and using `TypedDict` or `NamedTuple` objects for predictable configuration structures. This provides significantly better type safety down the pipeline.
+5. **Subprocess IO:** The new `ruff_cli.py` utility function `get_ruff_rule_markdown()` must explicitly declare its return values (`-> str | None`) and the subprocess decoding pipeline should clearly handle `bytes` versus `str` boundary conversions.
+
+---
+
+## 6. Verification Plan
+
+### Automated Tests
+- Scaffold `tests/test_tui.py`.
+- Mock out `get_ruff_rule_markdown()` to reliably return stub Markdown documents.
+- Use `textual.app.App.run_test()` to:
+  1. Boot the application.
+  2. Synthetically select a configuration section and assert the `DataTable` correctly hydrates.
+  3. Select a documented rule row and assert the `RuleInspector` Markdown widget transitions from hidden to visible and displays the mock documentation.
+  4. Ensure `ImportError` gracefully catches environments that attempt to run the feature without installing `ruff-sync[tui]`.
+
+### Manual Testing Protocol
+1. Install feature branch `pip install -e '.[tui]'`.
+2. Execute `uv run ruff-sync inspect` locally.
+3. Validate visual tree correctly reflects the active target `pyproject.toml`.
+4. Highlight rules to ensure rendering triggers asynchronously without locking the UI process block.