ruff-sync 0.1.6.dev1__tar.gz → 0.1.6.dev3__tar.gz

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev3}/.agents/plans/issue-116-config-validation.md

@@ -24,12 +24,12 @@ passing both.
 > Use this to pick your agent tier. Simple phases can be handled by a weak/cheap model;
 > Complex phases need a capable reasoning model.
 
-| Priority | Label | Complexity | Feature | Scope |
-|---|---|---|---|---|
-| 1 (Must Have) | 🔴 | 🟡 Moderate | TOML syntax + Ruff CLI validation | New `validation.py` module; gated by `--validate` in `pull()` |
-| 2 (Should Have) | 🟠 | 🟢 Simple | Python version consistency check | `validation.py` + warn when `--validate` is active |
-| 3 (Could Have) | 🟡 | 🔴 Complex | Rule deprecation warnings | `validation.py` + subprocess + JSON + DI; gated by `--validate` |
-| 4 (Nice to Have) | 🟢 | 🟢 Simple | `--strict` flag | Upgrades warnings to failures; implies `--validate` |
+| Priority | Label | Complexity | Feature | Scope | Status |
+|---|---|---|---|---|---|
+| 1 (Must Have) | 🔴 | 🟡 Moderate | TOML syntax + Ruff CLI validation | New `validation.py` module; gated by `--validate` in `pull()` | ✅ Completed |
+| 2 (Should Have) | 🟠 | 🟢 Simple | Python version consistency check | `validation.py` + warn when `--validate` is active | ✅ Completed |
+| 3 (Could Have) | 🟡 | 🔴 Complex | Rule deprecation warnings | `validation.py` + subprocess + JSON + DI; gated by `--validate` | ✅ Completed |
+| 4 (Nice to Have) | 🟢 | 🟢 Simple | `--strict` flag | Upgrades warnings to failures; implies `--validate` | ✅ Completed |
 
 ---
 

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev3}/.agents/skills/ruff-sync-usage/SKILL.md

@@ -127,8 +127,9 @@ ruff-sync git@github.com:my-org/standards.git             # SSH (shallow clone)
 ## Gotchas
 
 - **`exclude` uses dotted paths, not TOML paths.** `lint.per-file-ignores` refers to the `per-file-ignores` key inside `[tool.ruff.lint]`. Do NOT write `tool.ruff.lint.per-file-ignores`.
-- **`--validate` is opt-in.** Validation is off by default. Pass `--validate` (or `--strict`) to run the merged config through Ruff before writing. The sync is aborted if Ruff rejects the config, leaving the local file untouched.
-- **`--strict` implies `--validate`.** If you want warnings treated as failures, only `--strict` is needed — don't pass both.
+- **`--validate` is opt-in.** Validation is off by default. Pass `--validate` (or `--strict`) to run the merged config through Ruff before writing. The sync is aborted if Ruff rejects the config, leaving the local file untouched. This includes a **Python version consistency check** that compares upstream `target-version` against local `requires-python`.
+- **Excluding `target-version` skips consistency validation.** If `target-version` (or `tool.ruff.target-version`) is in the `exclude` list, `ruff-sync` will skip the version consistency check and log a warning. This is useful for projects that intentionally deviate from upstream Python versions.
+- **`--strict` implies `--validate`.** If you want warnings (like version mismatches or deprecated rules) treated as failures, only `--strict` is needed — don't pass both.
 - **Validation soft-fails if `ruff` is not on PATH.** If the `ruff` binary can't be found, a warning is logged and the sync continues normally.
 - **Use `--init` only for new projects.** `ruff-sync` requires an existing `pyproject.toml` or `ruff.toml`. Pass `--init` to scaffold one if the directory is empty. This will automatically generate a `[tool.ruff-sync]` configuration block for future syncs.
 - **Use `--save` to persist CLI arguments.** If you want to update an existing `pyproject.toml` with a new upstream URL or exclusion, pass `--save` to write the new configuration to the file.

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev3}/.agents/skills/ruff-sync-usage/references/troubleshooting.md

@@ -77,6 +77,26 @@ ruff-sync          # pulls config AND updates the hook rev (if pre-commit-versio
 ```
 
 To suppress this check entirely, omit `--pre-commit` from `ruff-sync check` or set `pre-commit-version-sync = false`.
+---
+
+## Python Version Mismatch Warning
+
+**Symptom:** Sync succeeds but logs a warning like:
+```
+⚠️  Version mismatch: upstream [tool.ruff] target-version='py39' targets Python 3.9, but local [project] requires-python='>=3.10' requires Python >= 3.10.
+```
+
+**Cause:** The upstream configuration is targeting an older Python version than your project requires. This can lead to Ruff not using newer rules or features available to your project.
+
+**Fix:**
+1. **Update Upstream:** The ideal fix is to update the `target-version` in the upstream repository to a newer version (e.g., `py311`).
+2. **Exclude the key:** If you need to stay on a specific version locally, add `target-version` to your `exclude` list:
+   ```toml
+   [tool.ruff-sync]
+   exclude = ["target-version"]
+   ```
+
+In **`--strict`** mode, this warning is upgraded to a hard failure and will abort the sync.
 
 ---
 

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev3}/AGENTS.md

@@ -20,6 +20,7 @@ Specific workflows, libraries, and tools are documented in `.agents/skills/`. Be
 
 - **Python** ≥ 3.10 (target version `py310`)
 - **Package Manager**: [uv](https://docs.astral.sh/uv/) — Use `uv run <command>` for all executions to ensure the correct environment.
+    - **Note on PATH**: On macOS, `uv` is often installed in `~/.local/bin`. If `uv` is not found, add this to your `PATH`: `export PATH="$PATH:$HOME/.local/bin"`.
 - **Linter / Formatter**: [Ruff](https://docs.astral.sh/ruff/) (`>=0.15.0`)
 - **Type Checker**: [mypy](https://mypy-lang.org/) (strict mode)
 - **Test Framework**: [pytest](https://docs.pytest.org/) with `pytest-asyncio`, `respx`, `pyfakefs` (See [Testing Standards](.agents/TESTING.md))

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.1.6.dev1
+Version: 0.1.6.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.6.dev1 → ruff_sync-0.1.6.dev3}/docs/configuration.md

@@ -62,6 +62,9 @@ If your projects are on different Python versions but share linting rules:
 exclude = ["target-version"]
 ```
 
+> [!NOTE]
+> Excluding `target-version` also automatically skips the Python version consistency check otherwise performed during `--validate` or `--strict` runs.
+
 #### Sequential merging of multiple sources
 
 You can specify multiple upstream sources as a list. They will be merged in order—from top to bottom—with later sources overriding or extending earlier ones.

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev3}/docs/usage.md

@@ -122,12 +122,15 @@ ruff-sync --validate
 
 If Ruff rejects the merged config (e.g., because the upstream introduced an unknown key), the sync is aborted and your local file is left untouched.
 
-For stricter enforcement, use `--strict`. This upgrades any validation *warnings* — such as a Python version mismatch between `[tool.ruff] target-version` and `[project] requires-python` — into hard failures:
+For stricter enforcement, use `--strict`. This upgrades any validation *warnings* into hard failures. This includes a **Python version consistency check** that compares the upstream `[tool.ruff] target-version` against your local `[project] requires-python`:
 
 ```bash
 ruff-sync --strict
 ```
 
+> [!TIP]
+> If you intentionally manage your Python version locally and it differs from the upstream, you can add `target-version` to your `exclude` list. `ruff-sync` will then skip the consistency check and log a warning explaining why.
+
 > [!NOTE]
 > `--strict` implies `--validate`. You do not need to pass both flags.
 >

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ruff-sync"
-version = "0.1.6.dev1"
+version = "0.1.6.dev3"
 description = "Synchronize Ruff linter configuration across projects"
 keywords = ["ruff", "linter", "config", "synchronize", "python", "linting", "automation", "tomlkit", "pre-commit"]
 authors = [

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev3}/src/ruff_sync/core.py

@@ -1164,7 +1164,7 @@ async def pull(
 
             is_ruff_toml = is_ruff_toml_file(_source_toml_path.name)
             if not validate_merged_config(
-                source_doc, is_ruff_toml=is_ruff_toml, strict=args.strict
+                source_doc, is_ruff_toml=is_ruff_toml, strict=args.strict, exclude=args.exclude
             ):
                 fmt.error(
                     "❌ Merged config failed validation. Local file left unchanged.",

ruff_sync-0.1.6.dev3/src/ruff_sync/validation.py

@@ -0,0 +1,323 @@
+"""Validation logic for ruff-sync merged configurations."""
+
+from __future__ import annotations
+
+import functools
+import json
+import logging
+import pathlib
+import re
+import subprocess
+import tempfile
+from typing import TYPE_CHECKING
+
+import tomlkit
+from tomlkit import TOMLDocument
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+__all__ = [
+    "validate_merged_config",
+    "validate_ruff_accepts_config",
+    "validate_toml_syntax",
+]
+
+LOGGER = logging.getLogger(__name__)
+
+_RUFF_TARGET_VERSION_PATTERN = re.compile(r"^py(\d)(\d+)$")
+
+
+def _ruff_target_to_tuple(target_version: str) -> tuple[int, int] | None:
+    """Parse a Ruff target-version string (e.g. 'py311') into a (major, minor) tuple."""
+    m = _RUFF_TARGET_VERSION_PATTERN.match(target_version)
+    if not m:
+        return None
+    return int(m.group(1)), int(m.group(2))
+
+
+def _requires_python_min_version(requires_python: str) -> tuple[int, int] | None:
+    """Extract the minimum Python version from a PEP 440 requires-python string.
+
+    Examples:
+        '>=3.10' -> (3, 10)
+        '^3.11'  -> (3, 11)
+        '~=3.9'  -> (3, 9)
+    """
+    # TODO: Consider using packaging.specifiers.SpecifierSet optionally if available
+    # Match all version specifiers of the form X.Y
+    matches = re.findall(r"(\d+)\.(\d+)", requires_python)
+    if matches:
+        # Convert to list of (int, int) and return the minimum semantic version
+        versions = [(int(major), int(minor)) for major, minor in matches]
+        return min(versions)
+    return None
+
+
+def check_python_version_consistency(
+    doc: TOMLDocument, strict: bool = False, exclude: Iterable[str] = ()
+) -> bool:
+    """Warn if the merged ruff target-version conflicts with requires-python.
+
+    Args:
+        doc: The merged TOML document (pyproject.toml format).
+        strict: If True, treat version mismatch as a failure.
+        exclude: List of keys excluded from the ruff configuration.
+
+    Returns:
+        True if versions are consistent or if check is skipped.
+        False if strict=True and versions are inconsistent.
+    """
+    if "target-version" in exclude or "tool.ruff.target-version" in exclude:
+        LOGGER.warning(
+            "Skipping Python version consistency check: 'target-version' is "
+            "excluded in [tool.ruff-sync]."
+        )
+        return True
+    try:
+        ruff_section = doc.get("tool", {}).get("ruff", {})
+        target_version = ruff_section.get("target-version")
+        requires_python = doc.get("project", {}).get("requires-python")
+    except (AttributeError, TypeError):
+        return True  # Don't crash on unexpected doc shapes
+
+    if not target_version or not requires_python:
+        missing = []
+        if not target_version:
+            missing.append("[tool.ruff] target-version")
+        if not requires_python:
+            missing.append("[project] requires-python")
+        LOGGER.warning(f"Skipping Python version consistency check: missing {', '.join(missing)}.")
+        return True  # Nothing to compare
+
+    ruff_min = _ruff_target_to_tuple(str(target_version))
+    proj_min = _requires_python_min_version(str(requires_python))
+
+    if ruff_min is None or proj_min is None:
+        return True  # Couldn't parse one of the versions
+
+    if ruff_min < proj_min:
+        msg = (
+            f"Version mismatch: upstream [tool.ruff] target-version='{target_version}' "
+            f"targets Python {ruff_min[0]}.{ruff_min[1]}, but local [project] requires-python="
+            f"'{requires_python}' requires Python >= {proj_min[0]}.{proj_min[1]}. "
+            "Consider updating target-version in the upstream config."
+        )
+        if strict:
+            LOGGER.error(f"❌ {msg}")
+            return False
+        LOGGER.warning(f"⚠️  {msg}")
+
+    return True
+
+
+_RULE_LIST_KEYS: frozenset[str] = frozenset({"select", "extend-select", "ignore", "extend-ignore"})
+
+
+@functools.lru_cache(maxsize=1)
+def _get_deprecated_rule_codes() -> frozenset[str]:
+    """Return the set of deprecated rule codes reported by the installed Ruff version.
+
+    Returns an empty frozenset if ruff is not found or output cannot be parsed.
+    """
+    try:
+        result = subprocess.run(
+            ["ruff", "rule", "--all", "--output-format", "json"],  # noqa: S607
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
+        )
+        if result.returncode != 0:
+            return frozenset()
+        rules = json.loads(result.stdout)
+        return frozenset(r["code"] for r in rules if r.get("deprecated") is True)
+    except (
+        FileNotFoundError,
+        subprocess.TimeoutExpired,
+        json.JSONDecodeError,
+        KeyError,
+        TypeError,
+    ):
+        return frozenset()
+
+
+def check_deprecated_rules(
+    doc: TOMLDocument,
+    is_ruff_toml: bool = False,
+    strict: bool = False,
+    _deprecated_codes: frozenset[str] | None = None,
+    exclude: Iterable[str] = (),
+) -> bool:
+    """Warn if the merged config references any deprecated Ruff rules.
+
+    Args:
+        doc: The merged TOML document.
+        is_ruff_toml: True if the document is a standalone ruff.toml.
+        strict: If True, treat deprecated rules as a failure.
+        _deprecated_codes: Optional set of deprecated codes to use (for testing).
+        exclude: List of keys excluded from the ruff configuration.
+
+    Returns:
+        True if no deprecated rules are found, or if strict=False.
+        False if strict=True and deprecated rules are found.
+    """
+    deprecated_codes = (
+        _deprecated_codes if _deprecated_codes is not None else _get_deprecated_rule_codes()
+    )
+    if not deprecated_codes:
+        return True  # Nothing to check (ruff not found or returned no deprecated rules)
+
+    if is_ruff_toml:
+        lint_section = doc.get("lint", {})
+    else:
+        lint_section = doc.get("tool", {}).get("ruff", {}).get("lint", {})
+
+    if not isinstance(lint_section, dict):
+        return True
+
+    found_deprecated = False
+    for key in _RULE_LIST_KEYS:
+        full_key = f"lint.{key}" if is_ruff_toml else f"tool.ruff.lint.{key}"
+        if key in exclude or full_key in exclude:
+            continue
+
+        rule_list = lint_section.get(key, [])
+        if not isinstance(rule_list, list):
+            continue
+        for rule_code in rule_list:
+            rule_str = str(rule_code).strip().upper()
+            if rule_str in deprecated_codes:
+                found_deprecated = True
+                msg = (
+                    f"Upstream config uses deprecated rule '{rule_str}' "
+                    f"(found in [{'lint' if is_ruff_toml else 'tool.ruff.lint'}].{key}). "
+                    "This rule may be removed in a future Ruff version."
+                )
+                if strict:
+                    LOGGER.error(f"❌ {msg}")
+                else:
+                    LOGGER.warning(f"⚠️  {msg}")
+
+    return not (strict and found_deprecated)
+
+
+def validate_toml_syntax(doc: TOMLDocument) -> bool:
+    """Return True if the document serializes to valid TOML.
+
+    tomlkit always produces valid TOML, so this catches any edge cases
+    where serialization itself raises an unexpected exception.
+    """
+    try:
+        tomlkit.parse(doc.as_string())
+        return True  # noqa: TRY300
+    except tomlkit.exceptions.TOMLKitError:
+        LOGGER.exception("❌ Merged config failed TOML syntax check")
+        return False
+
+
+def validate_ruff_accepts_config(
+    doc: TOMLDocument, is_ruff_toml: bool = False, strict: bool = False
+) -> bool:
+    """Return True if Ruff accepts the merged configuration.
+
+    Writes the merged config to a temporary file and runs:
+        ruff check --isolated --config <tmp> <dummy-py-file>
+
+    Args:
+        doc: The merged TOML document to validate.
+        is_ruff_toml: True if the document is a ruff.toml (not pyproject.toml).
+        strict: If True, treat configuration warnings (deprecated rules, etc.) as failures.
+
+    Returns:
+        True if Ruff accepts the config without errors, False otherwise.
+    """
+    # The filename matters: ruff.toml uses flat format, pyproject.toml uses [tool.ruff]
+    config_filename = "ruff.toml" if is_ruff_toml else "pyproject.toml"
+
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        tmp_path = pathlib.Path(tmp_dir) / config_filename
+        tmp_path.write_text(doc.as_string(), encoding="utf-8")
+
+        # Create a minimal dummy Python file for ruff to lint
+        dummy_py = pathlib.Path(tmp_dir) / "dummy.py"
+        dummy_py.write_text("# ruff-sync config validation\n", encoding="utf-8")
+
+        config_flag = f"--config={tmp_path}"
+        # Using --config should be enough to isolate from project config
+        cmd = ["ruff", "check", config_flag, str(dummy_py)]
+        LOGGER.debug(f"Running ruff config validation: {' '.join(cmd)}")
+
+        try:
+            result = subprocess.run(  # noqa: S603
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=30,
+                check=False,
+            )
+        except FileNotFoundError:
+            LOGGER.warning("⚠️  `ruff` not found on PATH — skipping Ruff config validation.")
+            return True  # Soft fail: don't block if ruff isn't installed
+        except subprocess.TimeoutExpired:
+            LOGGER.warning("⚠️  Ruff config validation timed out — skipping.")
+            return True  # Soft fail on timeout
+
+        # Exit 0 = no issues found, exit 1 = issues found — both mean ruff
+        # parsed the config successfully. Exit 2 = config/usage error.
+        if result.returncode not in (0, 1):
+            LOGGER.error(
+                f"❌ Ruff rejected the merged config (exit {result.returncode}):\n"
+                f"{result.stderr.strip()}"
+            )
+            return False
+
+        # If strict mode is enabled, check stderr for configuration warnings
+        if strict and result.stderr:
+            # Ruff emits "warning: ..." or "deprecated ..." to stderr for config issues
+            # that aren't fatal enough to cause exit code 2.
+            lower_stderr = result.stderr.lower()
+            if "warning:" in lower_stderr or "deprecated" in lower_stderr:
+                LOGGER.error(
+                    "❌ Ruff validation warning(s) detected in strict mode:\n"
+                    f"{result.stderr.strip()}"
+                )
+                return False
+
+        return True
+
+
+def validate_merged_config(
+    doc: TOMLDocument,
+    is_ruff_toml: bool = False,
+    strict: bool = False,
+    exclude: Iterable[str] = (),
+) -> bool:
+    """Run all validation checks on the merged TOML document.
+
+    Returns True only if all checks pass. Returns False and logs errors
+    if any check fails.
+
+    Args:
+        doc: The merged TOML document to validate.
+        is_ruff_toml: True if the document is a standalone ruff.toml.
+        strict: If True, treat configuration warnings as hard failures.
+        exclude: List of keys excluded from the ruff configuration.
+
+    Returns:
+        True if all validation checks pass, False otherwise.
+    """
+    if not validate_toml_syntax(doc):
+        return False
+    if not validate_ruff_accepts_config(doc, is_ruff_toml=is_ruff_toml, strict=strict):
+        return False
+
+    version_ok = True
+    if not is_ruff_toml:
+        version_ok = check_python_version_consistency(doc, strict=strict, exclude=exclude)
+
+    deprecated_ok = check_deprecated_rules(
+        doc, is_ruff_toml=is_ruff_toml, strict=strict, exclude=exclude
+    )
+
+    return version_ok and deprecated_ok