ruff-sync 0.1.4.dev1__py3-none-any.whl → 0.1.5.dev2__py3-none-any.whl

ruff_sync/__init__.py

@@ -11,38 +11,48 @@ from .cli import (
     get_config,
     main,
 )
+from .config_io import (
+    RuffConfigFileName,
+    is_ruff_toml_file,
+    load_local_ruff_config,
+    resolve_target_path,
+)
+from .constants import OutputFormat
 from .core import (
     Config,
     FetchResult,
-    RuffConfigFileName,
     check,
     fetch_upstream_config,
     get_ruff_config,
     get_ruff_tool_table,
-    is_ruff_toml_file,
     merge_ruff_toml,
     pull,
     resolve_raw_url,
     to_git_url,
     toml_ruff_parse,
 )
+from .formatters import get_formatter
 
 __all__ = [
     "Arguments",
     "Config",
     "FetchResult",
+    "OutputFormat",
     "RuffConfigFileName",
     "__version__",
     "check",
     "fetch_upstream_config",
     "get_config",
+    "get_formatter",
     "get_ruff_config",
     "get_ruff_tool_table",
     "is_ruff_toml_file",
+    "load_local_ruff_config",
     "main",
     "merge_ruff_toml",
     "pull",
     "resolve_raw_url",
+    "resolve_target_path",
     "to_git_url",
     "toml_ruff_parse",
 ]

ruff_sync/cli.py

@@ -16,25 +16,23 @@ from functools import lru_cache
 from importlib import metadata
 from typing import (
     TYPE_CHECKING,
-    Any,
     ClassVar,
     Final,
+    Literal,
     NamedTuple,
-    cast,
+    Protocol,
 )
 
 import tomlkit
 from httpx import URL
-from typing_extensions import deprecated
+from typing_extensions import deprecated, override
 
 from ruff_sync.constants import (
     DEFAULT_BRANCH,
     DEFAULT_EXCLUDE,
     DEFAULT_PATH,
-    MISSING,
-    MissingType,
+    ConfKey,
     OutputFormat,
-    resolve_defaults,
 )
 from ruff_sync.core import (
     Config,
@@ -51,6 +49,7 @@ if TYPE_CHECKING:
 __all__: Final[list[str]] = [
     "Arguments",
     "ColoredFormatter",
+    "OutputFormat",
     "get_config",
     "main",
 ]
@@ -61,6 +60,9 @@ except metadata.PackageNotFoundError:
     __version__ = "0.0.0-dev"
 
 
+CIProvider = Literal[OutputFormat.GITHUB, OutputFormat.GITLAB]
+
+
 LOGGER = logging.getLogger(__name__)
 
 
@@ -80,7 +82,8 @@ class ColoredFormatter(logging.Formatter):
         """Initialize the formatter with a format string."""
         super().__init__(fmt)
 
-    def format(self, record: logging.LogRecord) -> str:  # type: ignore[explicit-override]
+    @override
+    def format(self, record: logging.LogRecord) -> str:
         """Format the log record with colors if the output is a TTY."""
         if sys.stderr.isatty():
             color = self.COLORS.get(record.levelno, self.RESET)
@@ -94,14 +97,14 @@ class Arguments(NamedTuple):
     command: str
     upstream: tuple[URL, ...]
     to: pathlib.Path
-    exclude: Iterable[str] | MissingType
+    exclude: Iterable[str]
     verbose: int
-    branch: str | MissingType = MISSING
-    path: str | MissingType = MISSING
+    branch: str = DEFAULT_BRANCH
+    path: str | None = None
     semantic: bool = False
     diff: bool = True
     init: bool = False
-    pre_commit: bool | MissingType = MISSING
+    pre_commit: bool = False
     save: bool | None = None
     output_format: OutputFormat = OutputFormat.TEXT
 
@@ -123,9 +126,30 @@ class ResolvedArgs(NamedTuple):
 
     upstream: tuple[URL, ...]
     to: pathlib.Path
-    exclude: Iterable[str] | MissingType
-    branch: str | MissingType
-    path: str | MissingType
+    exclude: Iterable[str]
+    branch: str
+    path: str | None
+    output_format: OutputFormat
+
+
+class CLIArguments(Protocol):
+    """Protocol for parsed CLI arguments from ArgumentParser."""
+
+    command: str | None
+    upstream: list[URL]
+    to: str | None
+    source: str | None
+    exclude: list[str] | None
+    verbose: int
+    branch: str | None
+    path: str | None
+    pre_commit: bool | None
+    output_format: OutputFormat | None
+    # Subcommand specific
+    init: bool
+    save: bool | None
+    semantic: bool
+    diff: bool
 
 
 @lru_cache(maxsize=1)
@@ -142,32 +166,39 @@ def get_config(
     """
     local_toml = source / RuffConfigFileName.PYPROJECT_TOML
     # TODO: use pydantic to validate the toml file
-    cfg_result: dict[str, Any] = {}
+    cfg_result: Config = {}
     if local_toml.exists():
         toml = tomlkit.parse(local_toml.read_text())
         config = toml.get("tool", {}).get("ruff-sync")
         if config:
             allowed_keys = set(Config.__annotations__.keys())
-            for arg, value in config.items():
-                arg_norm = arg.replace("-", "_")
-
-                # Handle aliases for pre-commit
-                if arg_norm in ("pre_commit_sync", "pre_commit"):
-                    arg_norm = "pre_commit_version_sync"
-
-                if arg_norm in allowed_keys:
-                    if arg_norm == "source":
-                        LOGGER.warning(
-                            "DeprecationWarning: [tool.ruff-sync] 'source' is deprecated. "
-                            "Use 'to' instead."
-                        )
-                    cfg_result[arg_norm] = value
+            for raw_key, value in config.items():
+                # Check for legacy 'source' key to emit deprecation warning
+                if raw_key.replace("-", "_") == ConfKey.to_attr(ConfKey.SOURCE):
+                    LOGGER.warning(
+                        f"DeprecationWarning: [tool.ruff-sync] '{raw_key}' "
+                        f"is deprecated. Use '{ConfKey.TO}' instead."
+                    )
+
+                # Map legacy names (source, pre_commit_sync) to canonical
+                # (to, pre-commit-version-sync)
+                canonical_key = ConfKey.get_canonical(raw_key)
+
+                # Normalize TOML key (dashes) to internal Python attribute name (underscores)
+                # e.g. "pre-commit-version-sync" -> "pre_commit_version_sync"
+                arg_attr = ConfKey.to_attr(canonical_key)
+
+                if arg_attr in allowed_keys:
+                    cfg_result[arg_attr] = value  # type: ignore[literal-required]
                 else:
-                    LOGGER.warning(f"Unknown ruff-sync configuration: {arg}")
+                    LOGGER.warning(f"Unknown ruff-sync configuration: {raw_key}")
+
             # Ensure 'to' is populated if 'source' was used
-            if "source" in cfg_result and "to" not in cfg_result:
-                cfg_result["to"] = cfg_result["source"]
-    return cast("Config", cfg_result)
+            to_attr = ConfKey.to_attr(ConfKey.TO)
+            source_attr = ConfKey.to_attr(ConfKey.SOURCE)
+            if source_attr in cfg_result and to_attr not in cfg_result:
+                cfg_result[to_attr] = cfg_result[source_attr]  # type: ignore[literal-required]
+    return cfg_result
 
 
 def _get_cli_parser() -> ArgumentParser:
@@ -255,8 +286,8 @@ def _get_cli_parser() -> ArgumentParser:
         "--output-format",
         type=OutputFormat,
         choices=list(OutputFormat),
-        default=OutputFormat.TEXT,
-        help="Format for output. Default: text.",
+        default=None,
+        help="Format for output. Default: text (auto-detected in CI).",
     )
 
     # Pull subcommand (the default action)
@@ -299,16 +330,23 @@ def _get_cli_parser() -> ArgumentParser:
         help="Do not show a diff.",
     )
 
+    # Inspect subcommand
+    subparsers.add_parser(
+        "inspect",
+        parents=[common_parser],
+        help="Open a Terminal UI to explore and interrogate your local ruff configuration.",
+    )
+
     return parser
 
 
 PARSER: Final[ArgumentParser] = _get_cli_parser()
 
 
-def _resolve_upstream(args: Any, config: Mapping[str, Any]) -> tuple[URL, ...]:
+def _resolve_upstream(args: CLIArguments, config: Config) -> tuple[URL, ...]:
     """Resolve upstream URL(s) from CLI or config."""
     if args.upstream:
-        upstreams = tuple(cast("Iterable[URL]", args.upstream))
+        upstreams = tuple(args.upstream)
         # Log CLI upstreams for consistency with config sourcing
         summary = (
             f"{upstreams[0]}... ({len(upstreams)} total)"
@@ -346,54 +384,80 @@ def _resolve_upstream(args: Any, config: Mapping[str, Any]) -> tuple[URL, ...]:
     )
 
 
-def _resolve_exclude(args: Any, config: Mapping[str, Any]) -> Iterable[str] | MissingType:
+def _resolve_exclude(args: CLIArguments, config: Config) -> Iterable[str]:
     """Resolve exclude patterns from CLI or config.
 
     Returns the CLI value if provided, otherwise the value from
     ``[tool.ruff-sync].exclude`` in the config.  If neither is set,
-    returns ``MISSING`` so that :func:`~ruff_sync.constants.resolve_defaults`
-    can apply the ``DEFAULT_EXCLUDE`` set downstream.
+    returns ``DEFAULT_EXCLUDE``.
     """
     if args.exclude is not None:
-        return cast("Iterable[str]", args.exclude)
+        return args.exclude
     if "exclude" in config:
-        exclude = config["exclude"]
+        exclude: Iterable[str] = config["exclude"]
         LOGGER.info(f"🚫 Using exclude from [tool.ruff-sync]: {list(exclude)}")
-        return cast("Iterable[str]", exclude)
-    return MISSING
+        return exclude
+    return DEFAULT_EXCLUDE
 
 
-def _resolve_branch(args: Any, config: Mapping[str, Any]) -> str | MissingType:
+def _resolve_branch(args: CLIArguments, config: Config) -> str:
     """Resolve branch name from CLI, config, or MISSING.
 
     An empty string (``--branch ""``) is treated as falsy and falls back to
     the config or default, preserving the original behaviour.
     """
-    if getattr(args, "branch", None):
-        return cast("str", args.branch)
+    if args.branch:
+        return args.branch
     if "branch" in config:
-        branch = cast("str", config["branch"])
+        branch: str = config["branch"]
         LOGGER.info(f"🌿 Using branch from [tool.ruff-sync]: {branch}")
         return branch
-    return MISSING
+    return DEFAULT_BRANCH
 
 
-def _resolve_path(args: Any, config: Mapping[str, Any]) -> str | MissingType:
+def _resolve_path(args: CLIArguments, config: Config) -> str:
     """Resolve path prefix from CLI, config, or MISSING.
 
     An empty string (``--path ""``) is treated as falsy and falls back to
     the config or default, preserving the original behaviour.
     """
-    if getattr(args, "path", None):
-        return cast("str", args.path)
+    if args.path:
+        return args.path
     if "path" in config:
-        path = cast("str", config["path"])
+        path: str = config["path"]
         LOGGER.info(f"📄 Using path from [tool.ruff-sync]: {path}")
         return path
-    return MISSING
+    return DEFAULT_PATH
+
+
+def _resolve_output_format(args: CLIArguments, config: Config) -> OutputFormat:
+    """Resolve output format from CLI, config, or environment auto-detection."""
+    if args.output_format:
+        return args.output_format
+
+    if "output_format" in config:
+        fmt_str = config["output_format"]
+        try:
+            fmt = OutputFormat(fmt_str)
+        except ValueError:
+            valid_formats = ", ".join(f.value for f in OutputFormat)
+            LOGGER.warning(
+                f"Unknown output format in config: {fmt_str}. Valid values: {valid_formats}"
+            )
+        else:
+            LOGGER.info(f"📊 Using output format from [tool.ruff-sync]: {fmt}")
+            return fmt
+
+    # Auto-detection
+    provider = _detect_ci_provider()
+    if provider:
+        LOGGER.info(f"🤖 Auto-detected CI environment: {provider}")
+        return provider
+
+    return OutputFormat.TEXT
 
 
-def _resolve_to(args: Any, config: Mapping[str, Any], initial_to: pathlib.Path) -> pathlib.Path:
+def _resolve_to(args: CLIArguments, config: Config, initial_to: pathlib.Path) -> pathlib.Path:
     """Resolve target path from CLI, config, or default."""
     if args.source:
         LOGGER.warning("DeprecationWarning: --source is deprecated. Use --to instead.")
@@ -410,14 +474,62 @@ def _resolve_to(args: Any, config: Mapping[str, Any], initial_to: pathlib.Path)
     return initial_to
 
 
-def _resolve_args(args: Any, config: Mapping[str, Any], initial_to: pathlib.Path) -> ResolvedArgs:
+def _resolve_args(args: CLIArguments, config: Config, initial_to: pathlib.Path) -> ResolvedArgs:
     """Resolve upstream, to, exclude, branch, and path from CLI and config."""
     upstream = _resolve_upstream(args, config)
     to = _resolve_to(args, config, initial_to)
     exclude = _resolve_exclude(args, config)
     branch = _resolve_branch(args, config)
     path = _resolve_path(args, config)
-    return ResolvedArgs(upstream, to, cast("Any", exclude), cast("Any", branch), cast("Any", path))
+    output_format = _resolve_output_format(args, config)
+
+    # Normalize path "" -> None to match core expectation
+    final_path: str | None = path or None
+
+    return ResolvedArgs(
+        upstream,
+        to,
+        exclude,
+        branch,
+        final_path,
+        output_format,
+    )
+
+
+def _resolve_pre_commit(args: CLIArguments, config: Config) -> bool:
+    """Resolve pre-commit sync setting from CLI or config."""
+    if args.pre_commit is not None:
+        return args.pre_commit
+
+    pre_commit_attr = ConfKey.to_attr(ConfKey.PRE_COMMIT_VERSION_SYNC)
+    if pre_commit_attr in config:
+        val = config.get(pre_commit_attr)
+        return bool(val)
+    return False
+
+
+def _detect_ci_provider() -> CIProvider | None:
+    """Return the current CI provider, or None if not in a CI environment."""
+    if os.environ.get("GITHUB_ACTIONS") == "true":
+        return OutputFormat.GITHUB
+    if os.environ.get("GITLAB_CI") == "true":
+        return OutputFormat.GITLAB
+    return None
+
+
+def _validate_ci_output_format(args: Arguments) -> None:
+    """Log a warning if the specified output format does not match the CI environment."""
+    provider = _detect_ci_provider()
+    if provider is OutputFormat.GITHUB and args.output_format == OutputFormat.GITLAB:
+        LOGGER.warning(
+            "⚠️ GitLab output format detected in GitHub Actions environment. "
+            "Did you mean '--output-format github'?"
+        )
+    elif provider is OutputFormat.GITLAB and args.output_format == OutputFormat.GITHUB:
+        LOGGER.warning(
+            "⚠️ GitHub output format detected in GitLab CI environment. "
+            "Did you mean '--output-format gitlab'?"
+        )
 
 
 def main() -> int:
@@ -426,6 +538,7 @@ def main() -> int:
     if len(sys.argv) > 1 and sys.argv[1] not in (
         "pull",
         "check",
+        "inspect",
         "-h",
         "--help",
         "--version",
@@ -460,24 +573,14 @@ def main() -> int:
     initial_to = pathlib.Path(arg_to) if arg_to else pathlib.Path()
     config: Config = get_config(initial_to)
 
-    upstream, to_val, exclude, branch, path = _resolve_args(args, config, initial_to)
-
-    pre_commit_arg = getattr(args, "pre_commit", None)
-    if pre_commit_arg is not None:
-        pre_commit_val: bool | MissingType = pre_commit_arg
-    elif "pre-commit-version-sync" in config:
-        pre_commit_val = cast("Any", config).get("pre-commit-version-sync")
-    elif "pre_commit_version_sync" in config:
-        pre_commit_val = config.get("pre_commit_version_sync", MISSING)
-    else:
-        pre_commit_val = MISSING
-
-    # Build Arguments first so _resolve_defaults can centralize MISSING → default
-    # resolution for branch and path (keeps cli.main and core._merge_multiple_upstreams
-    # in sync with a single source of truth).
+    upstream, to_val, exclude, branch, path, output_format = _resolve_args(args, config, initial_to)
+    pre_commit_val = _resolve_pre_commit(args, config)
+
+    resolved_upstream = tuple(resolve_raw_url(u, branch=branch, path=path) for u in upstream)
+
     exec_args = Arguments(
         command=args.command,
-        upstream=upstream,
+        upstream=resolved_upstream,
         to=to_val,
         exclude=exclude,
         verbose=args.verbose,
@@ -488,18 +591,25 @@ def main() -> int:
         init=getattr(args, "init", False),
         pre_commit=pre_commit_val,
         save=getattr(args, "save", None),
-        output_format=getattr(args, "output_format", OutputFormat.TEXT),
+        output_format=output_format,
     )
 
-    # Use the shared helper from constants so the MISSING→default logic for
-    # branch/path cannot diverge between cli.main and core._merge_multiple_upstreams.
-    res_branch, res_path, _exclude = resolve_defaults(branch, path, exclude)
-    resolved_upstream = tuple(
-        resolve_raw_url(u, branch=res_branch, path=res_path) for u in upstream
-    )
-    exec_args = exec_args._replace(upstream=resolved_upstream)
+    # Warn if the specified output format doesn't match the current CI environment
+    _validate_ci_output_format(exec_args)
 
     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
+
+            LOGGER.error("❌ The Terminal UI (inspect) is not yet implemented.")
+            return 1
+
         if exec_args.command == "check":
             return asyncio.run(check(exec_args))
         return asyncio.run(pull(exec_args))

ruff_sync/config_io.py

@@ -0,0 +1,136 @@
+"""Configuration file discovery and loading logic."""
+
+from __future__ import annotations
+
+import enum
+import pathlib
+from collections.abc import Iterable, Mapping
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
+
+import tomlkit
+from tomlkit.items import Table
+from typing_extensions import override
+
+if TYPE_CHECKING:
+    from httpx import URL
+
+
+@enum.unique
+class RuffConfigFileName(str, enum.Enum):
+    """Enumeration of Ruff configuration filenames."""
+
+    PYPROJECT_TOML = "pyproject.toml"
+    RUFF_TOML = "ruff.toml"
+    DOT_RUFF_TOML = ".ruff.toml"
+
+    @classmethod
+    def tried_order(cls) -> list[RuffConfigFileName]:
+        """Return the order in which configuration files should be tried."""
+        return [cls.RUFF_TOML, cls.DOT_RUFF_TOML, cls.PYPROJECT_TOML]
+
+    @override
+    def __str__(self) -> str:
+        """Return the filename as a string."""
+        return self.value
+
+
+def is_ruff_toml_file(path_or_url: str | URL) -> bool:
+    """Return True if the path or URL indicates a ruff.toml file.
+
+    This handles cases with query strings or fragments by examining only the path component.
+    """
+    parsed = urlparse(str(path_or_url))
+
+    # If it's a URL with a scheme/netloc, use the parsed path component.
+    # Otherwise, fall back to stripping any query/fragment from the raw string.
+    if parsed.scheme or parsed.netloc:
+        path = parsed.path
+    else:
+        path = str(path_or_url).split("?", 1)[0].split("#", 1)[0]
+
+    return pathlib.Path(path).name in (
+        RuffConfigFileName.RUFF_TOML,
+        RuffConfigFileName.DOT_RUFF_TOML,
+    )
+
+
+def resolve_target_path(
+    to: pathlib.Path, upstreams: Iterable[str | URL] | None = None
+) -> pathlib.Path:
+    """Resolve the target path for configuration files.
+
+    If 'to' is a file, it's used directly.
+    Otherwise, it looks for existing ruff/pyproject.toml in the 'to' directory.
+    If none found, it defaults to pyproject.toml unless the first upstream is a ruff.toml.
+    """
+    if to.is_file():
+        return to
+
+    # If it's a directory, look for common config files
+    for filename in RuffConfigFileName.tried_order():
+        candidate = to / filename
+        if candidate.exists():
+            return candidate
+
+    # Use the first upstream URL as a hint for the default file name
+    first_upstream = next(iter(upstreams), None) if upstreams else None
+
+    # If upstream is specified and is a ruff.toml, default to ruff.toml
+    if first_upstream and is_ruff_toml_file(first_upstream):
+        return to / RuffConfigFileName.RUFF_TOML
+
+    return to / RuffConfigFileName.PYPROJECT_TOML
+
+
+def load_local_ruff_config(target: pathlib.Path) -> dict[str, Any]:
+    """Load the local Ruff configuration as a plain dictionary.
+
+    Args:
+        target: The directory or file path to load configuration from.
+
+    Returns:
+        A plain dictionary containing the [tool.ruff] configuration.
+
+    Raises:
+        FileNotFoundError: If no configuration file is found at the target path.
+        TypeError: If the configuration structure is invalid.
+    """
+    config_path = resolve_target_path(target)
+    if not config_path.exists():
+        msg = f"No Ruff configuration file found at: {config_path}"
+        raise FileNotFoundError(msg)
+
+    content = config_path.read_text(encoding="utf-8")
+    doc = tomlkit.parse(content)
+
+    is_ruff_toml = config_path.name in (
+        RuffConfigFileName.RUFF_TOML,
+        RuffConfigFileName.DOT_RUFF_TOML,
+    )
+
+    if is_ruff_toml:
+        # For ruff.toml, the entire document is the configuration
+        unwrapped = doc.unwrap() if hasattr(doc, "unwrap") else doc
+        return unwrapped if isinstance(unwrapped, dict) else {}
+
+    # For pyproject.toml, extract [tool.ruff]
+    try:
+        # We use isinstance checks instead of cast to satisfy mypy
+        tool = doc.get("tool")
+        if not isinstance(tool, Mapping):
+            return {}
+        ruff = tool.get("ruff")
+        if ruff is None:
+            return {}
+        if not isinstance(ruff, (Mapping, Table)):
+            msg = f"Expected table for [tool.ruff], got {type(ruff)}"
+            raise TypeError(msg)
+
+        data = ruff.unwrap() if hasattr(ruff, "unwrap") else ruff
+        if not isinstance(data, dict):
+            return {}
+    except KeyError:
+        return {}
+    else:
+        return data

ruff_sync/constants.py

@@ -15,6 +15,7 @@ __all__: Final[list[str]] = [
     "DEFAULT_EXCLUDE",
     "DEFAULT_PATH",
     "MISSING",
+    "ConfKey",
     "MissingType",
     "OutputFormat",
     "resolve_defaults",
@@ -61,6 +62,69 @@ class OutputFormat(str, enum.Enum):
         return self.value
 
 
+@enum.unique
+class ConfKey(str, enum.Enum):
+    """Centralized configuration keys for [tool.ruff-sync].
+
+    These are the canonical names used in the pyproject.toml configuration file.
+    """
+
+    UPSTREAM = "upstream"
+    TO = "to"
+    EXCLUDE = "exclude"
+    BRANCH = "branch"
+    PATH = "path"
+    PRE_COMMIT_VERSION_SYNC = "pre-commit-version-sync"
+    OUTPUT_FORMAT = "output-format"
+    SEMANTIC = "semantic"
+    DIFF = "diff"
+    INIT = "init"
+    SAVE = "save"
+    VERBOSE = "verbose"
+
+    # Legacy / Alias Keys
+    SOURCE = "source"  # Legacy for 'to'
+    PRE_COMMIT = "pre-commit"  # Legacy for 'pre-commit-version-sync'
+    PRE_COMMIT_SYNC_LEGACY = "pre-commit-sync"  # Legacy for 'pre-commit-version-sync'
+
+    @override
+    def __str__(self) -> str:
+        """Return the string value for TOML keys."""
+        return self.value
+
+    @classmethod
+    def to_attr(cls, key: str | ConfKey) -> str:
+        """Normalize a configuration key to its Python attribute name (underscore)."""
+        return str(key).replace("-", "_")
+
+    @classmethod
+    def get_canonical(cls, key: str) -> str:
+        """Map legacy or aliased configuration keys to their canonical names.
+
+        Args:
+            key: The raw key from the configuration file.
+
+        Returns:
+            The canonical ConfKey name (still as a string for use in logic).
+        """
+        # Normalize the input key to underscores for robust alias matching
+        norm_key = cls.to_attr(key)
+
+        # Handle aliases for 'to'
+        if norm_key == cls.to_attr(cls.SOURCE):
+            return cls.TO.value
+
+        # Handle aliases for 'pre-commit-version-sync'
+        if norm_key in (
+            cls.to_attr(cls.PRE_COMMIT_SYNC_LEGACY),
+            cls.to_attr(cls.PRE_COMMIT),
+        ):
+            return cls.PRE_COMMIT_VERSION_SYNC.value
+
+        # Return the original key (even if unknown, let 'allowed_keys' handle it)
+        return key
+
+
 def resolve_defaults(
     branch: str | MissingType,
     path: str | MissingType,
@@ -69,8 +133,7 @@ def resolve_defaults(
     """Resolve MISSING sentinel values to their effective defaults.
 
     This is the single source of truth for MISSING → default resolution across
-    both ``cli.main`` and ``core._merge_multiple_upstreams``, keeping the two
-    layers in sync without introducing a circular dependency between them.
+    the CLI and internal logic, keeping the layers in sync.
 
     Args:
         branch: The resolved branch value or ``MISSING``.
@@ -80,8 +143,7 @@ def resolve_defaults(
     Returns:
         A ``(branch, path, exclude)`` tuple with defaults applied.
         ``path`` is normalised to ``None`` (not ``""``) so callers can forward
-        it directly to :func:`~ruff_sync.core.resolve_raw_url` and
-        :func:`~ruff_sync.core.fetch_upstreams_concurrently`.
+        it directly to :func:`~ruff_sync.core.resolve_raw_url`.
     """
     eff_branch = branch if branch is not MISSING else DEFAULT_BRANCH
     raw_path = path if path is not MISSING else DEFAULT_PATH

ruff_sync/core.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import asyncio
 import difflib
-import enum
 import json
 import logging
 import pathlib
@@ -23,7 +22,6 @@ from typing import (
     TypedDict,
     overload,
 )
-from urllib.parse import urlparse
 
 import httpx
 import tomlkit
@@ -31,12 +29,13 @@ from httpx import URL
 from tomlkit import TOMLDocument, table
 from tomlkit.items import Table
 from tomlkit.toml_file import TOMLFile
-from typing_extensions import override
 
+from ruff_sync.config_io import RuffConfigFileName, is_ruff_toml_file, resolve_target_path
 from ruff_sync.constants import (
     DEFAULT_BRANCH,
-    MISSING,
-    resolve_defaults,
+    DEFAULT_EXCLUDE,
+    DEFAULT_PATH,
+    ConfKey,
 )
 from ruff_sync.formatters import ResultFormatter, get_formatter
 from ruff_sync.pre_commit import sync_pre_commit
@@ -76,25 +75,6 @@ _HTTP_OK: Final = 200
 _HTTP_NOT_FOUND: Final[int] = 404
 
 
-@enum.unique
-class RuffConfigFileName(str, enum.Enum):
-    """Enumeration of Ruff configuration filenames."""
-
-    PYPROJECT_TOML = "pyproject.toml"
-    RUFF_TOML = "ruff.toml"
-    DOT_RUFF_TOML = ".ruff.toml"
-
-    @classmethod
-    def tried_order(cls) -> list[RuffConfigFileName]:
-        """Return the order in which configuration files should be tried."""
-        return [cls.RUFF_TOML, cls.DOT_RUFF_TOML, cls.PYPROJECT_TOML]
-
-    @override
-    def __str__(self) -> str:
-        """Return the filename as a string."""
-        return self.value
-
-
 class FetchResult(NamedTuple):
     """Result of fetching an upstream configuration."""
 
@@ -141,34 +121,7 @@ class Config(TypedDict, total=False):
     diff: bool
     init: bool
     pre_commit_version_sync: bool
-
-
-def resolve_target_path(
-    to: pathlib.Path, upstreams: Iterable[str | URL] | None = None
-) -> pathlib.Path:
-    """Resolve the target path for configuration files.
-
-    If 'to' is a file, it's used directly.
-    Otherwise, it looks for existing ruff/pyproject.toml in the 'to' directory.
-    If none found, it defaults to pyproject.toml unless the first upstream is a ruff.toml.
-    """
-    if to.is_file():
-        return to
-
-    # If it's a directory, look for common config files
-    for filename in RuffConfigFileName.tried_order():
-        candidate = to / filename
-        if candidate.exists():
-            return candidate
-
-    # Use the first upstream URL as a hint for the default file name
-    first_upstream = next(iter(upstreams), None) if upstreams else None
-
-    # If upstream is specified and is a ruff.toml, default to ruff.toml
-    if first_upstream and is_ruff_toml_file(first_upstream):
-        return to / RuffConfigFileName.RUFF_TOML
-
-    return to / RuffConfigFileName.PYPROJECT_TOML
+    output_format: str
 
 
 def _resolve_upstream_target_path(path: str | None) -> str:
@@ -530,29 +483,6 @@ async def fetch_upstream_config(
         raise httpx.HTTPStatusError(msg, request=err.request, response=err.response) from None
 
 
-def is_ruff_toml_file(path_or_url: str | URL) -> bool:
-    """Return True if the path or URL indicates a ruff.toml file.
-
-    This handles:
-    - Plain paths (e.g. "ruff.toml", ".ruff.toml", "configs/ruff.toml")
-    - URLs with query strings or fragments (e.g. "ruff.toml?ref=main", "ruff.toml#L10")
-    by examining only the path component (or the part before any query/fragment).
-    """
-    parsed = urlparse(str(path_or_url))
-
-    # If it's a URL with a scheme/netloc, use the parsed path component.
-    # Otherwise, fall back to stripping any query/fragment from the raw string.
-    if parsed.scheme or parsed.netloc:
-        path = parsed.path
-    else:
-        path = str(path_or_url).split("?", 1)[0].split("#", 1)[0]
-
-    return pathlib.Path(path).name in (
-        RuffConfigFileName.RUFF_TOML,
-        RuffConfigFileName.DOT_RUFF_TOML,
-    )
-
-
 @overload
 def get_ruff_config(
     toml: str | TOMLDocument,
@@ -798,18 +728,6 @@ async def fetch_upstreams_concurrently(
         return fetch_results
 
 
-def _resolve_defaults(
-    args: Arguments,
-) -> tuple[str, str | None, Iterable[str]]:
-    """Resolve MISSING sentinel values in *args* to their effective defaults.
-
-    Delegates to :func:`~ruff_sync.constants.resolve_defaults` so that the
-    MISSING → default logic is centralised in one place and shared with
-    ``cli.main`` without coupling the two layers together.
-    """
-    return resolve_defaults(args.branch, args.path, args.exclude)
-
-
 async def _merge_multiple_upstreams(
     target_doc: TOMLDocument,
     is_target_ruff_toml: bool,
@@ -821,7 +739,7 @@ async def _merge_multiple_upstreams(
     Downloads are performed concurrently via fetch_upstreams_concurrently,
     while merging remains sequential to preserve layering order.
     """
-    branch, path, exclude = _resolve_defaults(args)
+    branch, path, exclude = args.branch, args.path, args.exclude
 
     fetch_results = await fetch_upstreams_concurrently(
         args.upstream, client, branch=branch, path=path
@@ -1017,7 +935,8 @@ async def check(
         ... )
         >>> # asyncio.run(check(args))
     """
-    fmt = get_formatter(args.output_format)
+    output_format = args.output_format
+    fmt: ResultFormatter = get_formatter(output_format)
     try:
         fmt.note("🔍 Checking Ruff sync status...")
 
@@ -1144,32 +1063,32 @@ def serialize_ruff_sync_config(doc: TOMLDocument, args: Arguments) -> None:
 
     # TODO: Consider only saving upstream if it differs from existing config
     if len(args.upstream) == 1:
-        ruff_sync_table["upstream"] = str(args.upstream[0])
+        ruff_sync_table[ConfKey.UPSTREAM] = str(args.upstream[0])
     else:
         urls_array = tomlkit.array()
         urls_array.multiline(True)
         for url in args.upstream:
             urls_array.append(str(url))
-        ruff_sync_table["upstream"] = urls_array
+        ruff_sync_table[ConfKey.UPSTREAM] = urls_array
 
     # Normalize excludes and de-duplicate while preserving order.
     # Only compute and persist excludes when explicitly provided so that
     # DEFAULT_EXCLUDE remains an implicit default and is not serialized.
-    if args.exclude is not MISSING:
+    if args.exclude != DEFAULT_EXCLUDE:
         normalized_excludes = list(dict.fromkeys(args.exclude))
         exclude_array = tomlkit.array()
         for ex in normalized_excludes:
             exclude_array.append(ex)
-        ruff_sync_table["exclude"] = exclude_array
+        ruff_sync_table[ConfKey.EXCLUDE] = exclude_array
 
-    if args.branch is not MISSING:
-        ruff_sync_table["branch"] = args.branch
+    if args.branch != DEFAULT_BRANCH:
+        ruff_sync_table[ConfKey.BRANCH] = args.branch
 
-    if args.path is not MISSING:
-        ruff_sync_table["path"] = args.path
+    if args.path != DEFAULT_PATH and args.path is not None:
+        ruff_sync_table[ConfKey.PATH] = args.path
 
-    if args.pre_commit is not MISSING:
-        ruff_sync_table["pre-commit-version-sync"] = args.pre_commit
+    if args.pre_commit:
+        ruff_sync_table[ConfKey.PRE_COMMIT_VERSION_SYNC] = args.pre_commit
 
 
 async def pull(
@@ -1194,7 +1113,8 @@ async def pull(
         ... )
         >>> # asyncio.run(pull(args))
     """
-    fmt = get_formatter(args.output_format)
+    output_format = args.output_format
+    fmt = get_formatter(output_format)
     try:
         fmt.note("🔄 Syncing Ruff...")
         _source_toml_path = resolve_target_path(args.to, args.upstream).resolve(strict=False)
@@ -1247,7 +1167,7 @@ async def pull(
             rel_path = _source_toml_path.resolve()
         fmt.success(f"✅ Updated {rel_path}")
 
-        if args.pre_commit is not MISSING and args.pre_commit:
+        if args.pre_commit:
             sync_pre_commit(pathlib.Path.cwd(), dry_run=False)
 
         return 0

ruff_sync/dependencies.py

@@ -0,0 +1,38 @@
+"""Utilities for handling optional dependencies and lazy loading."""
+
+from __future__ import annotations
+
+import importlib.util
+from typing import Final
+
+__all__: Final[list[str]] = ["is_installed", "require_dependency"]
+
+
+def is_installed(package_name: str) -> bool:
+    """Check if a package is installed without importing it.
+
+    Args:
+        package_name: The name of the package to check.
+
+    Returns:
+        True if the package is available, False otherwise.
+    """
+    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.
+
+    Args:
+        package_name: The name of the required package.
+        extra_name: The name of the ruff-sync extra that provides this package.
+
+    Raises:
+        ImportError: If the package is not installed.
+    """
+    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)

ruff_sync/system.py

@@ -0,0 +1,45 @@
+"""System and subprocess utilities for ruff-sync."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Final
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def get_ruff_rule_markdown(rule_code: str) -> str | None:
+    """Execute `ruff rule <CODE>` and return the Markdown documentation.
+
+    Args:
+        rule_code: The Ruff rule code (e.g., 'RUF012').
+
+    Returns:
+        The Markdown documentation for the rule, or None if the execution fails
+        or the rule is not found.
+    """
+    cmd: Final[list[str]] = ["ruff", "rule", rule_code]
+    LOGGER.debug(f"Executing system command: {' '.join(cmd)}")
+
+    try:
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, stderr = await process.communicate()
+
+        if process.returncode != 0:
+            msg = stderr.decode().strip()
+            LOGGER.warning(f"Ruff command failed with exit code {process.returncode}: {msg}")
+            return None
+
+        return 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}")
+        return None

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.1.4.dev1
+Version: 0.1.5.dev2
 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/
@@ -27,6 +27,8 @@ Requires-Python: >=3.10
 Requires-Dist: httpx<1.0.0,>=0.27.0
 Requires-Dist: tomlkit<2.0.0,>=0.12.3
 Requires-Dist: typing-extensions>=4.5.0
+Provides-Extra: tui
+Requires-Dist: textual>=8.2.2; extra == 'tui'
 Description-Content-Type: text/markdown
 
 <p align="center">

ruff_sync-0.1.5.dev2.dist-info/RECORD

@@ -0,0 +1,15 @@
+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,,

ruff_sync-0.1.4.dev1.dist-info/RECORD

@@ -1,12 +0,0 @@
-ruff_sync/__init__.py,sha256=k3I_7nbBGsORKMVpbE57pzkRiV18WvztBmw5UQRmASo,849
-ruff_sync/__main__.py,sha256=oMIbv9ywToleBKJrZ-GMo_KhM4lHg02nJe7t6neWzJE,179
-ruff_sync/cli.py,sha256=MKhLxUMlduR8aPhCzWLDewBm77HDqeZqCcJ7JyND1GI,17724
-ruff_sync/constants.py,sha256=10YBAxowzmd_0wwBHeAKgWRYdyI5WnK-OiPl16prNxc,2817
-ruff_sync/core.py,sha256=0PEvEdSsO8lKsScw9qwi08xK37HG8e3V-BKeR6JotzU,45302
-ruff_sync/formatters.py,sha256=sDZgx7SYNM1pjKshZLTgQHuAeT0P_tqAeV0VRZuz5FA,26311
-ruff_sync/pre_commit.py,sha256=0ltXUkmocbrSwwf6cPbNc_K5K9n-gvou98xJy9YUhr0,5303
-ruff_sync-0.1.4.dev1.dist-info/METADATA,sha256=pyknLtGnrKrR_2fGmPQOn3JYy6mjE9F8YVS1BDDtbjw,21398
-ruff_sync-0.1.4.dev1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-ruff_sync-0.1.4.dev1.dist-info/entry_points.txt,sha256=z8TlIElMWLlqY_YWglHeMBksDohf2voVih6YnCBCWzk,45
-ruff_sync-0.1.4.dev1.dist-info/licenses/LICENSE.md,sha256=RcCP8t8xyCx2cvMZSLjBrPqJfctciWC6q85ceQAcEfA,1080
-ruff_sync-0.1.4.dev1.dist-info/RECORD,,