ruff-sync 0.1.5.dev2__py3-none-any.whl → 0.1.5.dev4__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/core.py

@@ -11,11 +11,10 @@ import re
 import subprocess
 import sys
 import tempfile
-from collections.abc import Iterable, Mapping
+from collections.abc import Iterable, Mapping, MutableMapping
 from io import StringIO
 from typing import (
     TYPE_CHECKING,
-    Any,
     Final,
     Literal,
     NamedTuple,
@@ -27,7 +26,7 @@ import httpx
 import tomlkit
 from httpx import URL
 from tomlkit import TOMLDocument, table
-from tomlkit.items import Table
+from tomlkit.items import Item, Table
 from tomlkit.toml_file import TOMLFile
 
 from ruff_sync.config_io import RuffConfigFileName, is_ruff_toml_file, resolve_target_path
@@ -41,6 +40,8 @@ from ruff_sync.formatters import ResultFormatter, get_formatter
 from ruff_sync.pre_commit import sync_pre_commit
 
 if TYPE_CHECKING:
+    from tomlkit.container import Container
+
     from ruff_sync.cli import Arguments
 
 __all__: Final[list[str]] = [
@@ -103,8 +104,8 @@ class DiffContext(NamedTuple):
     source_toml_path: pathlib.Path
     source_doc: TOMLDocument
     merged_doc: TOMLDocument
-    source_val: Any
-    merged_val: Any
+    source_val: object
+    merged_val: object
 
 
 class Config(TypedDict, total=False):
@@ -552,16 +553,19 @@ def _apply_exclusions(tbl: Table | TOMLDocument, exclude: Iterable[str]) -> None
     """
     for key_path in exclude:
         parts = key_path.split(".")
-        target: Any = tbl
+        target: Table | TOMLDocument | Item | Container | None = tbl
         for part in parts[:-1]:
-            target = target.get(part) if hasattr(target, "get") else None
-            if target is None:
+            if isinstance(target, Mapping):
+                target = target.get(part)
+            else:
+                target = None
                 break
-        if target is not None and hasattr(target, "pop"):
+        if isinstance(target, Mapping):
             leaf = parts[-1]
             if leaf in target:
                 LOGGER.info(f"Excluding `{key_path}` from upstream ruff config.")
-                target.pop(leaf)
+                if hasattr(target, "pop"):
+                    target.pop(leaf)
 
 
 def toml_ruff_parse(toml_s: str, exclude: Iterable[str]) -> TOMLDocument:
@@ -573,9 +577,11 @@ def toml_ruff_parse(toml_s: str, exclude: Iterable[str]) -> TOMLDocument:
     return ruff_toml
 
 
-def _recursive_update(source_table: Any, upstream: Any) -> None:
+def _recursive_update(
+    source_table: MutableMapping[str, object], upstream: Mapping[str, object]
+) -> None:
     """Recursively update a TOML table, preserving formatting of existing keys."""
-    if hasattr(upstream, "items") or isinstance(upstream, Mapping):
+    if isinstance(upstream, Mapping) or hasattr(upstream, "items"):
         items = upstream.items()
     else:
         return
@@ -588,26 +594,32 @@ def _recursive_update(source_table: Any, upstream: Any) -> None:
                 # Structural fix: if the target is a proxy (dotted key),
                 # and we are adding NEW keys to it, we must convert it to a real
                 # table to ensure children get correct headers.
-                source_sub_keys = set(source_table[key].keys())
-                upstream_sub_keys = set(value.keys())
+                source_key_val = source_table[key]
+                source_sub_keys = (
+                    set(source_key_val.keys()) if isinstance(source_key_val, Mapping) else set()
+                )
+                upstream_sub_keys = set(value.keys()) if isinstance(value, Mapping) else set()
                 if not upstream_sub_keys.issubset(source_sub_keys):
-                    current_val = source_table[key].unwrap()
+                    current_val = getattr(
+                        source_table[key], "unwrap", lambda k=key: source_table[k]
+                    )()
                     # DELETE PROXY FIRST to avoid structural doubling
                     del source_table[key]
                     # ADD AS REAL TABLE
-                    source_table.add(key, current_val)
-
-                _recursive_update(source_table[key], value)
+                    if hasattr(source_table, "add"):
+                        source_table.add(key, current_val)
+                    else:
+                        source_table[key] = current_val
+
+                child_source = source_table[key]
+                if isinstance(child_source, MutableMapping) and isinstance(value, Mapping):
+                    _recursive_update(child_source, value)
             else:
                 # Overwrite existing leaf value only if it's semantically different.
                 # Compare unwrapped values, but assign the raw tomlkit Item to
                 # preserve inline comments attached to the upstream value.
-                current_val = (
-                    source_table[key].unwrap()
-                    if hasattr(source_table[key], "unwrap")
-                    else source_table[key]
-                )
-                new_val_unwrapped = value.unwrap() if hasattr(value, "unwrap") else value
+                current_val = getattr(source_table[key], "unwrap", lambda k=key: source_table[k])()
+                new_val_unwrapped = getattr(value, "unwrap", lambda v=value: v)()
                 if current_val != new_val_unwrapped:
                     source_table[key] = value
         else:
@@ -813,8 +825,8 @@ def _check_pre_commit_sync(args: Arguments, fmt: ResultFormatter) -> int | None:
 
 
 def _find_changed_keys(
-    source: Any,
-    merged: Any,
+    source: object,
+    merged: object,
     prefix: str = "",
 ) -> list[str]:
     """Return a list of dotted TOML keys that differ between *source* and *merged*.
@@ -834,12 +846,9 @@ def _find_changed_keys(
     """
     changed: list[str] = []
 
-    source_is_mapping = isinstance(source, Mapping)
-    merged_is_mapping = isinstance(merged, Mapping)
-
-    if source_is_mapping and merged_is_mapping:
+    if isinstance(source, Mapping) and isinstance(merged, Mapping):
         for key, merged_val in merged.items():
-            full_key = f"{prefix}.{key}" if prefix else key
+            full_key = f"{prefix}.{key}" if prefix else str(key)
             source_val = source.get(key)
             if source_val is None and key not in source:
                 # Key is new (only in merged)
@@ -859,7 +868,7 @@ def _find_changed_keys(
                     changed.extend(nested)
                 elif src_unwrapped != mrg_unwrapped:
                     changed.append(full_key)
-    elif source_is_mapping != merged_is_mapping:
+    elif isinstance(source, Mapping) != isinstance(merged, Mapping):
         # Structural type mismatch (table vs scalar or vice-versa): treat the
         # whole node as changed rather than attempting a meaningless value
         # comparison between incompatible TOML node types.
@@ -889,8 +898,8 @@ def _report_drift(
     generic error.
     """
     if is_ruff_toml:
-        source_section: Any = source_doc
-        merged_section: Any = merged_doc
+        source_section: object = source_doc
+        merged_section: object = merged_doc
     else:
         source_section = source_doc.get("tool", {}).get("ruff") or {}
         merged_section = merged_doc.get("tool", {}).get("ruff") or {}
@@ -966,8 +975,8 @@ async def check(
             )
 
         is_source_ruff_toml = is_ruff_toml_file(_source_toml_path.name)
-        source_val: Any = None
-        merged_val: Any = None
+        source_val: object = None
+        merged_val: object = None
         if args.semantic:
             if is_source_ruff_toml:
                 source_ruff = source_doc

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,14 @@
 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
+
+    from ruff_sync.types_ import RuffLinter, RuffRule
 
 LOGGER = logging.getLogger(__name__)
 
@@ -20,6 +26,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[RuffRule]:
+    """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[RuffLinter]:
+    """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[RuffRule], toml_config: Mapping[str, Any]
+) -> list[RuffRule]:
+    """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[RuffRule] = []
+    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)  # type: ignore[arg-type]
+
+    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 +164,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