ruff-sync 0.1.5.dev2__py3-none-any.whl → 0.1.5.dev3__py3-none-any.whl

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/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())

ruff_sync/dependencies.py

@@ -2,10 +2,19 @@
 
 from __future__ import annotations
 
+import importlib
 import importlib.util
-from typing import Final
+from typing import TYPE_CHECKING, Final
 
-__all__: Final[list[str]] = ["is_installed", "require_dependency"]
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from typing import Any
+
+__all__: Final[list[str]] = ["DependencyError", "is_installed", "require_dependency"]
+
+
+class DependencyError(Exception):
+    """Raised when a required optional dependency is missing or broken."""
 
 
 def is_installed(package_name: str) -> bool:
@@ -20,19 +29,36 @@ def is_installed(package_name: str) -> bool:
     return importlib.util.find_spec(package_name) is not None
 
 
-def require_dependency(package_name: str, extra_name: str) -> None:
-    """Ensure a dependency is installed, or raise a helpful ImportError.
+def require_dependency(
+    package_name: str,
+    extra_name: str,
+    *,
+    _is_installed: Callable[[str], bool] = is_installed,
+    _import_module: Callable[[str], Any] = importlib.import_module,
+) -> None:
+    """Ensure a dependency is installed and importable, or raise DependencyError.
 
     Args:
         package_name: The name of the required package.
         extra_name: The name of the ruff-sync extra that provides this package.
+        _is_installed: Internal use only for testing. Function to check if a package is installed.
+        _import_module: Internal use only for testing. Function to import a module.
 
     Raises:
-        ImportError: If the package is not installed.
+        DependencyError: If the package is not installed or raises an error during import.
     """
-    if not is_installed(package_name):
-        msg = (
-            f"The '{package_name}' package is required for this feature. "
-            f"Install it with: pip install 'ruff-sync[{extra_name}]'"
-        )
-        raise ImportError(msg)
+    msg = (
+        f"The '{package_name}' package is required for this feature. "
+        f"Install it with: pip install 'ruff-sync[{extra_name}]'"
+    )
+
+    # 1. Fast check (dry) to see if it exists at all
+    if not _is_installed(package_name):
+        raise DependencyError(msg)
+
+    # 2. Wet check (real import) to ensure it's functional
+    try:
+        _import_module(package_name)
+    except (ImportError, ModuleNotFoundError) as e:
+        # If it failed here, it's installed but BROKEN (e.g. missing sub-dependencies)
+        raise DependencyError(msg) from e

ruff_sync/system.py

@@ -3,8 +3,12 @@
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
-from typing import Final
+from typing import TYPE_CHECKING, Any, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
 
 LOGGER = logging.getLogger(__name__)
 
@@ -20,6 +24,132 @@ async def get_ruff_rule_markdown(rule_code: str) -> str | None:
         or the rule is not found.
     """
     cmd: Final[list[str]] = ["ruff", "rule", rule_code]
+    return await _run_ruff_command(cmd, f"ruff rule {rule_code}")
+
+
+async def get_ruff_config_markdown(setting_path: str) -> str | None:
+    """Execute `ruff config <SETTING>` and return the Markdown documentation.
+
+    Args:
+        setting_path: The Ruff configuration setting path (e.g., 'lint.select').
+
+    Returns:
+        The Markdown documentation for the setting, or None if the execution fails.
+    """
+    # Strip 'tool.ruff.' prefix if present as 'ruff config' expects relative paths
+    clean_path = setting_path.removeprefix("tool.ruff.")
+    if not clean_path or clean_path == "tool.ruff":
+        return None
+    cmd: Final[list[str]] = ["ruff", "config", clean_path]
+    return await _run_ruff_command(cmd, f"ruff config {clean_path}")
+
+
+async def get_all_ruff_rules() -> list[dict[str, Any]]:
+    """Execute `ruff rule --all --output-format json` and return the parsed rules.
+
+    Returns:
+        A list of dictionaries representing all supported Ruff rules.
+    """
+    cmd: Final[list[str]] = ["ruff", "rule", "--all", "--output-format", "json"]
+    output = await _run_ruff_command(cmd, "ruff rule --all")
+    if not output:
+        return []
+    try:
+        data = json.loads(output)
+    except json.JSONDecodeError:
+        LOGGER.exception("Failed to parse Ruff rules JSON.")
+        return []
+
+    if isinstance(data, list):
+        return data
+    return []
+
+
+async def get_ruff_linters() -> list[dict[str, Any]]:
+    """Execute `ruff linter --output-format json` and return the parsed linters.
+
+    Returns:
+        A list of dictionaries representing Ruff linter categories.
+    """
+    cmd: Final[list[str]] = ["ruff", "linter", "--output-format", "json"]
+    output = await _run_ruff_command(cmd, "ruff linter")
+    if not output:
+        return []
+    try:
+        data = json.loads(output)
+    except json.JSONDecodeError:
+        LOGGER.exception("Failed to parse Ruff linters JSON.")
+        return []
+
+    if isinstance(data, list):
+        return data
+    return []
+
+
+def compute_effective_rules(
+    all_rules: list[dict[str, Any]], toml_config: Mapping[str, Any]
+) -> list[dict[str, Any]]:
+    """Determine the status (Enabled, Ignored, Disabled) for each rule.
+
+    Args:
+        all_rules: The list of all supported rules.
+        toml_config: The local configuration dictionary.
+
+    Returns:
+        The list of rules enriched with a 'status' key.
+    """
+    # The config may be "wrapped" (top-level 'tool' key) or
+    # "unwrapped" (direct Ruff config as returned by load_local_ruff_config).
+    lint = toml_config.get("lint")
+    if lint is None:
+        lint = toml_config.get("tool", {}).get("ruff", {}).get("lint", {})
+
+    select = set(lint.get("select", [])) | set(lint.get("extend-select", []))
+    ignore = set(lint.get("ignore", [])) | set(lint.get("extend-ignore", []))
+
+    # If no select/extend-select is provided, Ruff defaults to E and F
+    if not lint.get("select") and not lint.get("extend-select"):
+        select.update(["E", "F"])
+
+    enriched: list[dict[str, Any]] = []
+    for rule in all_rules:
+        code = rule["code"]
+
+        # Find longest matching select prefix
+        best_select_len = -1
+        for s in select:
+            if code.startswith(s):
+                best_select_len = max(best_select_len, len(s))
+
+        # Find longest matching ignore prefix
+        best_ignore_len = -1
+        for i in ignore:
+            if code.startswith(i):
+                best_ignore_len = max(best_ignore_len, len(i))
+
+        status = "Disabled"
+        if best_select_len > best_ignore_len:
+            status = "Enabled"
+        elif best_ignore_len >= best_select_len and best_ignore_len != -1:
+            status = "Ignored"
+
+        rule_with_status = dict(rule)
+        rule_with_status["status"] = status
+        enriched.append(rule_with_status)
+
+    return enriched
+
+
+async def _run_ruff_command(cmd: list[str], description: str) -> str | None:
+    """Execute a ruff command and return the decoded output.
+
+    Args:
+        cmd: The command to execute.
+        description: A human-readable description for logging.
+
+    Returns:
+        The decoded stdout, or None if the command fails.
+    """
     LOGGER.debug(f"Executing system command: {' '.join(cmd)}")
 
     try:
@@ -32,14 +162,15 @@ async def get_ruff_rule_markdown(rule_code: str) -> str | None:
 
         if process.returncode != 0:
             msg = stderr.decode().strip()
-            LOGGER.warning(f"Ruff command failed with exit code {process.returncode}: {msg}")
+            LOGGER.warning(f"Command '{description}' failed with code {process.returncode}: {msg}")
             return None
 
-        return stdout.decode().strip()
-
+        output = stdout.decode().strip()
     except FileNotFoundError:
         LOGGER.exception("Ruff executable not found in PATH.")
         return None
     except Exception:
-        LOGGER.exception(f"Unexpected error executing ruff rule {rule_code}")
+        LOGGER.exception(f"Unexpected error executing '{description}'")
         return None
+    else:
+        return output or None

ruff_sync/tui/__init__.py

@@ -0,0 +1,26 @@
+"""TUI package for ruff-sync."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ruff_sync.tui.app import RuffSyncApp
+
+
+def get_tui_app() -> type[RuffSyncApp]:
+    """Lazy-load the TUI and return the RuffSyncApp class.
+
+    Returns:
+        The RuffSyncApp class.
+
+    Raises:
+        DependencyError: If 'textual' is not installed or the TUI cannot be loaded.
+    """
+    from ruff_sync.dependencies import require_dependency  # noqa: PLC0415
+
+    require_dependency("textual", extra_name="tui")
+
+    from ruff_sync.tui.app import RuffSyncApp  # noqa: PLC0415
+
+    return RuffSyncApp

ruff_sync/tui/app.py

@@ -0,0 +1,304 @@
+"""Main application logic for the Ruff-Sync Terminal User Interface."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, ClassVar, Final
+
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal, Vertical
+from textual.widgets import DataTable, Footer, Header, Tree
+from typing_extensions import override
+
+from ruff_sync.config_io import load_local_ruff_config
+from ruff_sync.system import compute_effective_rules, get_all_ruff_rules, get_ruff_linters
+from ruff_sync.tui.constants import RULE_PATTERN
+from ruff_sync.tui.screens import LegendScreen, OmniboxScreen
+from ruff_sync.tui.themes import AMBER_EMBER
+from ruff_sync.tui.widgets import CategoryTable, ConfigTree, RuleInspector
+
+if TYPE_CHECKING:
+    from ruff_sync.cli import Arguments
+
+
+LOGGER = logging.getLogger(__name__)
+
+MIN_RULE_COLUMNS: Final = 4
+
+
+class RuffSyncApp(App[None]):
+    """Ruff-Sync Terminal User Interface."""
+
+    CSS = """
+    Screen {
+        background: $surface;
+    }
+
+    #config-tree {
+        width: 1fr;
+        max-width: 42;
+        height: 100%;
+        border-right: solid $primary-darken-2;
+    }
+
+    #content-pane {
+        width: 1fr;
+        height: 100%;
+    }
+
+    #category-table {
+        height: 40%;
+        border-bottom: solid $primary-darken-2;
+    }
+
+    #inspector {
+        height: 60%;
+        padding: 1;
+        background: $surface-darken-1;
+        overflow-y: auto;
+    }
+    """
+
+    BINDINGS: ClassVar[list[Any]] = [
+        ("q", "quit", "Quit"),
+        ("/", "search", "Search Rules"),
+        ("?", "show_legend", "Show Legend"),
+        ("l", "show_legend", "Show Legend"),
+        ("c", "copy_content", "Copy Content"),
+    ]
+
+    def __init__(self, args: Arguments, **kwargs: Any) -> None:
+        """Initialize the application.
+
+        Args:
+            args: The CLI arguments.
+            **kwargs: Additional keyword arguments.
+        """
+        super().__init__(**kwargs)
+        self.args = args
+        self.config: dict[str, Any] = {}
+        self.all_rules: list[dict[str, Any]] = []
+        self.effective_rules: list[dict[str, Any]] = []
+        self.linters: list[dict[str, Any]] = []
+
+    @override
+    def compose(self) -> ComposeResult:
+        """Compose the user interface elements."""
+        yield Header()
+        with Horizontal():
+            yield ConfigTree("Local Configuration", id="config-tree")
+            with Vertical(id="content-pane"):
+                yield CategoryTable(id="category-table")
+                yield RuleInspector(id="inspector")
+        yield Footer()
+
+    async def on_mount(self) -> None:
+        """Load the configuration and populate the tree."""
+        try:
+            self.config = load_local_ruff_config(self.args.to)
+        except Exception:
+            LOGGER.exception("Failed to load Ruff configuration.")
+            self.notify("Failed to load Ruff configuration.", severity="error")
+            self.config = {}
+
+        tree = self.query_one(ConfigTree)
+        tree.populate(self.config, has_rules=True)
+        tree.focus()
+
+        # Register and set the default theme
+        self.register_theme(AMBER_EMBER)
+        self.theme = "amber-ember"
+
+        # Prime the caches in the background
+        self._prime_caches()
+
+    @work
+    async def _prime_caches(self) -> None:
+        """Fetch rules and compute effectiveness in the background."""
+        self.all_rules = await get_all_ruff_rules()
+        self.linters = await get_ruff_linters()
+        if self.config:
+            self.effective_rules = compute_effective_rules(self.all_rules, self.config)
+
+        # Refresh the tree once metadata is loaded to show linter groups
+        # We pass effective_rules so the tree can filter out entire groups that are disabled
+        tree = self.query_one(ConfigTree)
+        tree.populate(
+            self.config,
+            has_rules=True,
+            linters=self.linters,
+            effective_rules=self.effective_rules,
+        )
+
+    @work
+    async def _display_effective_rules(self) -> None:
+        """Populate the table with the effective rules list."""
+        if not self.all_rules:
+            self.all_rules = await get_all_ruff_rules()
+            self.effective_rules = compute_effective_rules(self.all_rules, self.config)
+
+        # Filter for only Enabled or Ignored rules as per the "Effective Rules" proposal
+        effective_only = [r for r in self.effective_rules if r["status"] != "Disabled"]
+
+        table = self.query_one(CategoryTable)
+        table.update_rules(effective_only)
+
+        inspector = self.query_one(RuleInspector)
+        inspector.update(
+            "## Effective Rule Status\n\nThis table shows rules that are actively being used "
+            "or have been explicitly ignored in your configuration."
+        )
+
+    @on(Tree.NodeSelected)
+    def handle_node_selected(self, event: Tree.NodeSelected[Any]) -> None:
+        """Handle tree node selection.
+
+        Args:
+            event: The tree node selected event.
+        """
+        data = event.node.data
+        label = event.node.label
+        label_text = str(label.plain) if hasattr(label, "plain") else str(label)
+
+        table = self.query_one(CategoryTable)
+        inspector = self.query_one(RuleInspector)
+
+        if data == "__rules__":
+            self._display_effective_rules()
+            return
+
+        if isinstance(data, dict) and data.get("type") == "linter":
+            prefix = data.get("prefix", "")
+            name = data.get("name", "Unknown Linter")
+
+            # Filter effective rules by prefix
+            # We show all rules in the group (even Disabled) as per the Discovery proposal
+            filtered_rules = [r for r in self.effective_rules if r["code"].startswith(prefix)]
+
+            table.update_rules(filtered_rules)
+            msg = f"## {name} ({prefix or 'No Prefix'})\n\nShowing rules for the {name} category."
+            inspector.update(msg)
+            return
+
+        # Build full path for context
+        full_path = self._get_node_path(event.node)
+
+        # Check if the node label or path matches a ruff rule
+        if isinstance(label_text, str) and RULE_PATTERN.match(label_text):
+            self._inspect_rule(label_text)
+        elif isinstance(data, (dict, list)):
+            table.update_content(data)
+            # Fetch config documentation for the section if possible (skip root)
+            if full_path != "tool.ruff":
+                inspector.fetch_and_display(full_path, is_rule=False)
+            else:
+                inspector.show_placeholder()
+        else:
+            table.update_content(data)
+            inspector.fetch_and_display(full_path, is_rule=False)
+
+    @on(DataTable.RowSelected)
+    def handle_row_selected(self, event: DataTable.RowSelected) -> None:
+        """Handle data table row selection.
+
+        Args:
+            event: The data table row selected event.
+        """
+        table = self.query_one(CategoryTable)
+        row = table.get_row_at(event.cursor_row)
+
+        # Handle multi-column rules view vs key-value view
+        if len(row) >= MIN_RULE_COLUMNS:
+            # Use row_key for stable rule code extraction (avoids markup)
+            rule_code = str(event.row_key.value)
+            self._inspect_rule(rule_code)
+            return
+
+        key, value = row
+        # Check if the value or key looks like a rule code
+        rule_code_from_kv = None
+        if RULE_PATTERN.match(str(key)):
+            rule_code_from_kv = str(key)
+        elif RULE_PATTERN.match(str(value)):
+            rule_code_from_kv = str(value)
+
+        if rule_code_from_kv:
+            self._inspect_rule(rule_code_from_kv)
+        else:
+            # It's a configuration key, show its documentation
+            inspector = self.query_one(RuleInspector)
+            full_path = f"{self._get_node_path(self.query_one(ConfigTree).cursor_node)}.{key}"
+            inspector.fetch_and_display(full_path, is_rule=False)
+
+    def _inspect_rule(self, rule_code: str) -> None:
+        """Centralized helper for rule inspection with metadata enrichment.
+
+        Args:
+            rule_code: The Ruff rule code to inspect.
+        """
+        # Fetch metadata for enrichment
+        rule_data = next((r for r in self.effective_rules if r["code"] == rule_code), None)
+        name = rule_data.get("name") if rule_data else None
+        status = rule_data.get("status") if rule_data else "Disabled"
+        explanation = rule_data.get("explanation") if rule_data else None
+
+        inspector = self.query_one(RuleInspector)
+        inspector.fetch_and_display(
+            rule_code,
+            is_rule=True,
+            cached_content=explanation,
+            rule_name=name,
+            rule_status=status,
+        )
+
+    def _get_node_path(self, node: Any) -> str:
+        """Construct the full configuration path to a tree node.
+
+        Args:
+            node: The tree node.
+
+        Returns:
+            The dot-separated configuration path.
+        """
+        path: list[str] = []
+        current = node
+        tree = self.query_one(ConfigTree)
+        while current and current != tree.root:
+            label = current.label
+            label_text = str(label.plain) if hasattr(label, "plain") else str(label)
+            path.append(label_text)
+            current = current.parent
+
+        if not path:
+            return "tool.ruff"
+        return "tool.ruff." + ".".join(reversed(path))
+
+    def action_search(self) -> None:
+        """Launch the global fuzzy search Omnibox."""
+        if not self.all_rules:
+            self.notify("Still fetching rule metadata...", severity="warning")
+            # Even if empty, we push; the screen handles empty list
+        self.push_screen(OmniboxScreen(self.all_rules), self.handle_omnibox_result)
+
+    def handle_omnibox_result(self, rule_code: str | None) -> None:
+        """Handle the result from the Omnibox search.
+
+        Args:
+            rule_code: The selected rule code, or None if cancelled.
+        """
+        if rule_code:
+            self._inspect_rule(rule_code)
+
+    def action_show_legend(self) -> None:
+        """Display the TUI legend modal."""
+        self.push_screen(LegendScreen())
+
+    def action_copy_content(self) -> None:
+        """Copy the current inspector content to the clipboard."""
+        inspector = self.query_one(RuleInspector)
+        if inspector.source:
+            self.copy_to_clipboard(str(inspector.source))
+            self.notify("Copied content to clipboard", title="Clipboard")
+        else:
+            self.notify("No content to copy", severity="warning")

ruff_sync/tui/constants.py

@@ -0,0 +1,9 @@
+"""Constants for the Ruff-Sync Terminal User Interface."""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+# Regex pattern for matching Ruff rule codes (e.g., E501, RUF012)
+RULE_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[A-Z]+[0-9]+$")

ruff_sync/tui/screens.py

@@ -0,0 +1,185 @@
+"""Screens for the Ruff-Sync Terminal User Interface."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, Final
+
+from textual import on
+from textual.containers import Vertical
+from textual.screen import ModalScreen
+from textual.widgets import Input, OptionList, Static
+from textual.widgets.option_list import Option
+from typing_extensions import override
+
+if TYPE_CHECKING:
+    from textual.app import ComposeResult
+
+MAX_SEARCH_RESULTS: Final = 15
+
+
+class OmniboxScreen(ModalScreen[str]):
+    """A modal search screen for quickly finding Ruff rules."""
+
+    CSS = """
+    OmniboxScreen {
+        align: center middle;
+    }
+
+    #omnibox-container {
+        width: 60;
+        height: auto;
+        max-height: 20;
+        background: $boost;
+        border: thick $primary;
+        padding: 1;
+    }
+
+    #omnibox-input {
+        margin-bottom: 1;
+    }
+
+    #omnibox-results {
+        height: auto;
+        max-height: 12;
+        border: none;
+        background: $surface;
+    }
+    """
+
+    def __init__(self, all_rules: list[dict[str, Any]], **kwargs: Any) -> None:
+        """Initialize the search screen.
+
+        Args:
+            all_rules: The list of all rules to search through.
+            **kwargs: Additional keyword arguments.
+        """
+        super().__init__(**kwargs)
+        self.all_rules = all_rules
+
+    @override
+    def compose(self) -> ComposeResult:
+        """Compose the search interface."""
+        with Vertical(id="omnibox-container"):
+            yield Static("[b]Search Ruff Rules[/b] (e.g. F401, unused)", id="omnibox-title")
+            yield Input(placeholder="Start typing...", id="omnibox-input")
+            yield OptionList(id="omnibox-results")
+
+    def on_mount(self) -> None:
+        """Focus the input on mount."""
+        self.query_one(Input).focus()
+
+    @on(Input.Changed)
+    def handle_input_changed(self, event: Input.Changed) -> None:
+        """Filter rules based on search input.
+
+        Args:
+            event: The input changed event.
+        """
+        search_query = event.value.strip().lower()
+        results_list = self.query_one(OptionList)
+        results_list.clear_options()
+
+        if not search_query:
+            return
+
+        matches = []
+        for rule in self.all_rules:
+            code = rule["code"].lower()
+            name = rule["name"].lower()
+            if search_query in code or search_query in name:
+                matches.append(rule)
+                if len(matches) >= MAX_SEARCH_RESULTS:  # Limit results
+                    break
+
+        for match in matches:
+            results_list.add_option(
+                Option(f"[b]{match['code']}[/b] - {match['name']}", id=match["code"])
+            )
+
+    @on(Input.Submitted)
+    def handle_input_submitted(self) -> None:
+        """Handle enter key in the input."""
+        results_list = self.query_one(OptionList)
+        if results_list.option_count > 0:
+            # If there's a selected option, use it. Otherwise use the first matching one.
+            index = results_list.highlighted if results_list.highlighted is not None else 0
+            option = results_list.get_option_at_index(index)
+            if option.id:
+                self.dismiss(str(option.id))
+
+    @on(OptionList.OptionSelected)
+    def handle_option_selected(self, event: OptionList.OptionSelected) -> None:
+        """Handle selection from the results list."""
+        if event.option.id:
+            self.dismiss(str(event.option.id))
+
+    def action_cancel(self) -> None:
+        """Close the screen without selection."""
+        self.dismiss()
+
+
+class LegendScreen(ModalScreen[None]):
+    """A toggleable legend explaining TUI status colors and icons."""
+
+    BINDINGS: ClassVar[list[Any]] = [
+        ("escape,l,?", "dismiss", "Close Legend"),
+    ]
+
+    CSS = """
+    LegendScreen {
+        align: center middle;
+        background: black 50%;
+    }
+
+    #legend-container {
+        width: 50;
+        height: auto;
+        background: $boost;
+        border: heavy $accent;
+        padding: 1 2;
+    }
+
+    .legend-title {
+        text-align: center;
+        text-style: bold;
+        margin-bottom: 1;
+        color: $accent;
+    }
+
+    .legend-section {
+        text-style: underline;
+        margin-top: 1;
+        margin-bottom: 1;
+    }
+
+    .legend-row {
+        margin-left: 2;
+    }
+
+    #legend-footer {
+        text-align: center;
+        margin-top: 1;
+        color: $text-disabled;
+    }
+    """
+
+    @override
+    def compose(self) -> ComposeResult:
+        """Compose the legend content."""
+        with Vertical(id="legend-container"):
+            yield Static("Ruff-Sync TUI Legend", id="legend-title", classes="legend-title")
+
+            yield Static("Rule Status", classes="legend-section")
+            yield Static(
+                "🟢 [green]Enabled[/green]   - Active in configuration", classes="legend-row"
+            )
+            yield Static("🟡 [yellow]Ignored[/yellow]   - Explicitly ignored", classes="legend-row")
+            yield Static("⚪ [dim]Disabled[/dim]  - Category not selected", classes="legend-row")
+
+            yield Static("Fix Availability", classes="legend-section")
+            yield Static("[cyan]Always[/cyan]      - Automatic fix available", classes="legend-row")
+            yield Static(
+                "[yellow]Sometimes[/yellow]   - Conditional/enforced fix", classes="legend-row"
+            )
+
+            yield Static("Press [b]? [/b] or [b]Esc[/b] to close", id="legend-footer")

ruff_sync/tui/themes.py

@@ -0,0 +1,21 @@
+"""Custom themes for the ruff-sync TUI."""
+
+from __future__ import annotations
+
+from textual.theme import Theme
+
+# AMBER_EMBER
+# High-contrast, warm dark theme with vibrant gold primary colors.
+AMBER_EMBER = Theme(
+    name="amber-ember",
+    primary="#FFB300",  # Darker, punchy Amber
+    secondary="#FFD54F",  # Lighter Amber
+    accent="#D81B60",  # Material Magenta
+    warning="#FFB300",  # Amber 600
+    error="#E91E63",  # Pink 500
+    success="#81C784",  # Light Green 300
+    background="#121212",  # Material Dark
+    surface="#1E1E1E",
+    panel="#2C2C2C",
+    boost="#2C2C2C",
+)

ruff_sync/tui/widgets.py

@@ -0,0 +1,293 @@
+"""Widgets for the Ruff-Sync Terminal User Interface."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from textual import work
+from textual.widgets import DataTable, Markdown, Tree
+from typing_extensions import override
+
+from ruff_sync.system import get_ruff_config_markdown, get_ruff_rule_markdown
+
+if TYPE_CHECKING:
+    from textual.widgets.tree import TreeNode
+
+
+class ConfigTree(Tree[Any]):
+    """A tree widget for navigating Ruff configuration."""
+
+    def populate(
+        self,
+        config: dict[str, Any],
+        has_rules: bool = False,
+        linters: list[dict[str, Any]] | None = None,
+        effective_rules: list[dict[str, Any]] | None = None,
+    ) -> None:
+        """Populate the tree with configuration sections.
+
+        Args:
+            config: The unwrapped dictionary of Ruff configuration.
+            has_rules: Whether to inject the 'Effective Rule Status' node.
+            linters: Optional linter metadata for expanding the rules node.
+            effective_rules: List of rules with status for filtering.
+        """
+        self.clear()
+        self.root.expand()
+        if has_rules:
+            rules_node = self.root.add("Effective Rule Status", data="__rules__")
+            if linters and effective_rules:
+                self._populate_linter_nodes(rules_node, linters, effective_rules)
+        self._populate_node(self.root, config)
+
+        # Auto-expand up to 2 levels if it fits in the current view
+        self._expand_if_fits()
+
+    def _is_linter_active(
+        self, linter: dict[str, Any], effective_rules: list[dict[str, Any]]
+    ) -> bool:
+        """Check if a linter (or any of its categories) has active/ignored rules."""
+        prefix = linter.get("prefix")
+        if prefix and any(
+            r["code"].startswith(prefix) and r["status"] != "Disabled" for r in effective_rules
+        ):
+            return True
+
+        if "categories" in linter:
+            return any(self._is_linter_active(c, effective_rules) for c in linter["categories"])
+
+        return False
+
+    def _populate_linter_nodes(
+        self,
+        parent: TreeNode[Any],
+        linters: list[dict[str, Any]],
+        effective_rules: list[dict[str, Any]],
+    ) -> None:
+        """Recursively add linter category nodes to the tree."""
+        # Sort linters by name for better navigation
+        for linter in sorted(linters, key=lambda x: x["name"]):
+            # Filter: only show if this linter or any category has active rules
+            if not self._is_linter_active(linter, effective_rules):
+                continue
+
+            name = linter["name"]
+            prefix = linter.get("prefix")
+            label = f"{name} ({prefix})" if prefix else name
+
+            # Use 'linter' structure in data for easy detection
+            node_data = {"type": "linter", "prefix": prefix, "name": name}
+            node = parent.add(label, data=node_data)
+
+            # Recursive call for sub-categories (e.g. Pylint, pycodestyle)
+            if "categories" in linter:
+                self._populate_linter_nodes(node, linter["categories"], effective_rules)
+
+    def _populate_node(self, parent: TreeNode[Any], data: Any) -> None:
+        """Recursively add nodes to the tree.
+
+        Args:
+            parent: The parent tree node.
+            data: The data to add to the tree.
+        """
+        if isinstance(data, dict):
+            for key, value in sorted(data.items()):
+                node = parent.add(key, data=value)
+                if isinstance(value, (dict, list)):
+                    self._populate_node(node, value)
+        elif isinstance(data, list):
+            for i, item in enumerate(data):
+                label = str(item) if not isinstance(item, (dict, list)) else f"[{i}]"
+                node = parent.add(label, data=item)
+                if isinstance(item, (dict, list)):
+                    self._populate_node(node, item)
+
+    def _expand_if_fits(self) -> None:
+        """Expand the first few levels of the tree if they fit in the vertical space."""
+        # We target depth 2 expansion (Root -> Categories -> Items)
+        target_depth = 2
+
+        # Use widget height if available, otherwise fallback to a common terminal height
+        # Subtract some margin for header/footer
+        limit = (self.size.height or 24) - 2
+
+        # Count visible nodes if we were to expand
+        to_expand: list[TreeNode[Any]] = []
+        visible_count = 1  # Start with the root
+
+        def collect_nodes(node: TreeNode[Any], depth: int) -> int:
+            nonlocal visible_count
+            if depth >= target_depth:
+                return visible_count
+
+            children = list(node.children)
+            if not children:
+                return visible_count
+
+            # If adding these children exceeds the limit, stop
+            if visible_count + len(children) > limit:
+                return visible_count
+
+            # Mark for expansion and continue
+            to_expand.append(node)
+            visible_count += len(children)
+
+            for child in children:
+                collect_nodes(child, depth + 1)
+            return visible_count
+
+        collect_nodes(self.root, 0)
+
+        # Apply the expansions
+        for node in to_expand:
+            node.expand()
+
+
+class CategoryTable(DataTable[Any]):
+    """A table widget for displaying configuration keys and values."""
+
+    @override
+    def on_mount(self) -> None:
+        """Initialize the table columns."""
+        self.cursor_type = "row"
+        self.add_columns("Key", "Value")
+
+    def update_content(self, data: Any) -> None:
+        """Update the table rows based on the selected data.
+
+        Args:
+            data: The data to display in the table.
+        """
+        self.clear(columns=True)
+        self.add_columns("Key", "Value")
+        if isinstance(data, dict):
+            for key, value in sorted(data.items()):
+                self.add_row(key, str(value))
+        elif isinstance(data, list):
+            for i, item in enumerate(data):
+                self.add_row(str(i), str(item))
+        else:
+            self.add_row("Value", str(data))
+
+    def update_rules(self, rules: list[dict[str, Any]]) -> None:
+        """Update the table with a list of rules using row-level highlighting.
+
+        Args:
+            rules: The enriched rules list to display.
+        """
+        self.clear(columns=True)
+        # Status is now indicated by row highlighting (colors), so column is removed
+        self.add_columns("Code", "Name", "Linter", "Fix")
+        for rule in rules:
+            status = rule.get("status", "Unknown")
+
+            # Determine row color based on status
+            color = ""
+            if status == "Enabled":
+                color = "success"
+            elif status == "Ignored":
+                color = "warning"
+            elif status == "Disabled":
+                color = (
+                    "dim"  # Keep dim as it's a standard Rich style that works across backgrounds
+                )
+
+            # Rich uses [/] to close the nearest open tag
+            code_markup = f"[{color}]{rule['code']}[/]" if color else rule["code"]
+            name_markup = f"[{color}]{rule['name']}[/]" if color else rule["name"]
+
+            fix = rule.get("fix_availability", "None")
+            fix_markup = fix
+            if fix == "Always":
+                fix_markup = f"[accent]{fix}[/]"
+            elif fix in ("Sometimes", "Enforced"):
+                fix_markup = f"[warning]{fix}[/]"
+
+            # Note: We still keep linter as-is for clarity
+            self.add_row(code_markup, name_markup, rule["linter"], fix_markup, key=rule["code"])
+
+
+class RuleInspector(Markdown):
+    """A markdown widget for inspecting Ruff rules and settings."""
+
+    _current_meta: ClassVar[dict[str, str]] = {}
+
+    def on_mount(self) -> None:
+        """Set initial placeholder content."""
+        self.show_placeholder()
+
+    @work(exclusive=True, group="inspector_update")
+    async def show_placeholder(self) -> None:
+        """Display a placeholder message."""
+        self.update(
+            "## Selection Details\n\nSelect a configuration key in the tree or a rule "
+            "code in the table to view documentation or additional context."
+        )
+
+    def show_context(self, path: str, value: Any) -> None:
+        """Display general context for a configuration setting.
+
+        Args:
+            path: The full configuration path (e.g., 'tool.ruff.lint.select').
+            value: The value of the setting.
+        """
+        # Show a summary for complex types, or the raw value for simple ones
+        if isinstance(value, dict):
+            summary = f"Table with {len(value)} keys"
+        elif isinstance(value, list):
+            summary = f"List with {len(value)} items"
+        else:
+            summary = f"`{value}`"
+
+        self.update(f"### Configuration Context\n\n**Path**: `{path}`\n\n**Value**: {summary}")
+
+    @work(exclusive=True, group="inspector_update")
+    async def fetch_and_display(
+        self,
+        target: str,
+        is_rule: bool = True,
+        cached_content: str | None = None,
+        rule_name: str | None = None,
+        rule_status: str | None = None,
+    ) -> None:
+        """Fetch and display the documentation for a rule or setting.
+
+        Args:
+            target: The Ruff rule code or configuration path.
+            is_rule: True if fetching a rule, False if fetching a config setting.
+            cached_content: Optional pre-fetched documentation.
+            rule_name: Optional rule name for display.
+            rule_status: Optional rule status (Enabled, Ignored, Disabled).
+        """
+        if target == "tool.ruff":
+            self.show_placeholder()
+            return
+
+        content: str | None = None
+        if cached_content:
+            content = cached_content
+        else:
+            # Set a loading message
+            desc = "rule" if is_rule else "config"
+            self.update(
+                f"## Inspecting {target}...\n\nFetching documentation from `ruff {desc}`..."
+            )
+
+            if is_rule:
+                content = await get_ruff_rule_markdown(target)
+            else:
+                content = await get_ruff_config_markdown(target)
+
+        if content:
+            # Prepend header if it's a rule
+            header = ""
+            if is_rule:
+                status_icons = {"Enabled": "🟢", "Ignored": "🟡", "Disabled": "⚪"}
+                icon = status_icons.get(rule_status or "Disabled", "⚪")
+                name = rule_name or "Unknown Rule"
+                header = f"# {icon} {target}: {name}\n\n---\n\n"
+
+            self.update(header + content.strip())
+        else:
+            desc = "rule" if is_rule else "config"
+            self.update(f"## Error\n\nCould not fetch documentation for {desc} `{target}`.")

{ruff_sync-0.1.5.dev2.dist-info → ruff_sync-0.1.5.dev3.dist-info}/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,21 @@
+ruff_sync/__init__.py,sha256=cuUpweRN6fkH9fmxyyTSFkmS4lbBGIhGs6Y5k5Z-2RE,1129
+ruff_sync/__main__.py,sha256=oMIbv9ywToleBKJrZ-GMo_KhM4lHg02nJe7t6neWzJE,179
+ruff_sync/cli.py,sha256=rc-VFsecKnceuhXznRTHyi28ZE6LhrL6J7CSBVVY5LI,21275
+ruff_sync/config_io.py,sha256=3GlFjFlii_hBLaNnUJRfFI0iozkngTBbfqu4rLrpZKQ,4348
+ruff_sync/constants.py,sha256=yE6ORJaErY8Bz5KTDDk7kRKLOlJ-xgS7Gvz_mFpjDJY,4604
+ruff_sync/core.py,sha256=RtuKFRHjZmvi5W7bD3quD4ueqD8wt_5R2xWbtx3_MbI,42599
+ruff_sync/dependencies.py,sha256=RpJXAsrB-Y-ol_ZH4U92XIuyq8_bWaYwp9sn9KpxraA,2096
+ruff_sync/formatters.py,sha256=sDZgx7SYNM1pjKshZLTgQHuAeT0P_tqAeV0VRZuz5FA,26311
+ruff_sync/pre_commit.py,sha256=0ltXUkmocbrSwwf6cPbNc_K5K9n-gvou98xJy9YUhr0,5303
+ruff_sync/system.py,sha256=BtDCXT_fPY-QsZHJ4CJnDBEPnHEJQ1nw-C4CBQ2xDmI,5662
+ruff_sync/tui/__init__.py,sha256=DcwvE70ETjBcC6pQeHpjrYtkJp8z4StGM8L3EuaVcIo,635
+ruff_sync/tui/app.py,sha256=GWvo1cQj5AHI3dOCyBQ5V74H5cYo6mxAzhLimJgDvYg,10656
+ruff_sync/tui/constants.py,sha256=fEPyp2k817QLluyiVHqDObzDONlHz_L3Ec0SYAUzzMs,267
+ruff_sync/tui/screens.py,sha256=uuP3yGsR6nbzRg7S5wHFBppFfsl6UVBsjOHY-ZcoWR8,5520
+ruff_sync/tui/themes.py,sha256=eHZsXmlYs5WVN_5Z7bnlGnka1B5n6sRxl4p7qurie2k,591
+ruff_sync/tui/widgets.py,sha256=tlaCvCzaN92aboMDJgYdDcU3paaZ0qcvhPBQHM15_l0,10894
+ruff_sync-0.1.5.dev3.dist-info/METADATA,sha256=CowilhV_UA5lc4vqoXrri2e9C1jrleoKzLGXC8iFlNs,21464
+ruff_sync-0.1.5.dev3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ruff_sync-0.1.5.dev3.dist-info/entry_points.txt,sha256=QQ0pjxMIN0vp5EmNFkyb-1Yk8JOIkid8zAPN3IpAExA,78
+ruff_sync-0.1.5.dev3.dist-info/licenses/LICENSE.md,sha256=RcCP8t8xyCx2cvMZSLjBrPqJfctciWC6q85ceQAcEfA,1080
+ruff_sync-0.1.5.dev3.dist-info/RECORD,,

{ruff_sync-0.1.5.dev2.dist-info → ruff_sync-0.1.5.dev3.dist-info}/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
+ruff-inspect = ruff_sync:inspect
 ruff-sync = ruff_sync:main

ruff_sync-0.1.5.dev2.dist-info/RECORD

@@ -1,15 +0,0 @@
-ruff_sync/__init__.py,sha256=BFndMiyH2201W9mvl585ox331iwY_L5T_uX9HUJS81c,1101
-ruff_sync/__main__.py,sha256=oMIbv9ywToleBKJrZ-GMo_KhM4lHg02nJe7t6neWzJE,179
-ruff_sync/cli.py,sha256=hdq5M7GdMQm5BrJrRVEwl9LRJvqtYvbgM-GRrkS6SK0,20726
-ruff_sync/config_io.py,sha256=3GlFjFlii_hBLaNnUJRfFI0iozkngTBbfqu4rLrpZKQ,4348
-ruff_sync/constants.py,sha256=yE6ORJaErY8Bz5KTDDk7kRKLOlJ-xgS7Gvz_mFpjDJY,4604
-ruff_sync/core.py,sha256=RtuKFRHjZmvi5W7bD3quD4ueqD8wt_5R2xWbtx3_MbI,42599
-ruff_sync/dependencies.py,sha256=ND4WMPKmXjRTuanMVsYxZJ60mR6umffCnFJVZEpV8p4,1145
-ruff_sync/formatters.py,sha256=sDZgx7SYNM1pjKshZLTgQHuAeT0P_tqAeV0VRZuz5FA,26311
-ruff_sync/pre_commit.py,sha256=0ltXUkmocbrSwwf6cPbNc_K5K9n-gvou98xJy9YUhr0,5303
-ruff_sync/system.py,sha256=sAqp6U4OQ4tWmfX2QD4b2ztutfz0SrqnAfuwaoygrbM,1350
-ruff_sync-0.1.5.dev2.dist-info/METADATA,sha256=3pAjsPujF8BUALhRBy3DcME-WVa4E2OXeiq81DUO8b8,21464
-ruff_sync-0.1.5.dev2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-ruff_sync-0.1.5.dev2.dist-info/entry_points.txt,sha256=z8TlIElMWLlqY_YWglHeMBksDohf2voVih6YnCBCWzk,45
-ruff_sync-0.1.5.dev2.dist-info/licenses/LICENSE.md,sha256=RcCP8t8xyCx2cvMZSLjBrPqJfctciWC6q85ceQAcEfA,1080
-ruff_sync-0.1.5.dev2.dist-info/RECORD,,