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

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev2}/.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` | ⏳ Pending |
+| 4 (Nice to Have) | 🟢 | 🟢 Simple | `--strict` flag | Upgrades warnings to failures; implies `--validate` | 🚧 In Progress |
 
 ---
 

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev2}/.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.dev2}/.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.dev2}/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.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.1.6.dev1
+Version: 0.1.6.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/

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev2}/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.dev2}/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.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ruff-sync"
-version = "0.1.6.dev1"
+version = "0.1.6.dev2"
 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.dev2}/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.dev1 → ruff_sync-0.1.6.dev2}/src/ruff_sync/validation.py

@@ -4,12 +4,17 @@ from __future__ import annotations
 
 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",
@@ -18,6 +23,91 @@ __all__ = [
 
 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
+
 
 def validate_toml_syntax(doc: TOMLDocument) -> bool:
     """Return True if the document serializes to valid TOML.
@@ -61,8 +151,8 @@ def validate_ruff_accepts_config(
         dummy_py.write_text("# ruff-sync config validation\n", encoding="utf-8")
 
         config_flag = f"--config={tmp_path}"
-        # Use --isolated to ensure validation is not influenced by local user/project config
-        cmd = ["ruff", "check", "--isolated", config_flag, str(dummy_py)]
+        # 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:
@@ -105,7 +195,10 @@ def validate_ruff_accepts_config(
 
 
 def validate_merged_config(
-    doc: TOMLDocument, is_ruff_toml: bool = False, strict: bool = False
+    doc: TOMLDocument,
+    is_ruff_toml: bool = False,
+    strict: bool = False,
+    exclude: Iterable[str] = (),
 ) -> bool:
     """Run all validation checks on the merged TOML document.
 
@@ -116,10 +209,15 @@ def validate_merged_config(
         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
-    return validate_ruff_accepts_config(doc, is_ruff_toml=is_ruff_toml, strict=strict)
+    if not validate_ruff_accepts_config(doc, is_ruff_toml=is_ruff_toml, strict=strict):
+        return False
+    if not is_ruff_toml:
+        return check_python_version_consistency(doc, strict=strict, exclude=exclude)
+    return True

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev2}/tests/test_config_validation.py

@@ -21,6 +21,7 @@ import ruff_sync
 from ruff_sync import get_config
 from ruff_sync.cli import LOGGER
 from ruff_sync.validation import (
+    check_python_version_consistency,
     validate_merged_config,
     validate_ruff_accepts_config,
     validate_toml_syntax,
@@ -326,8 +327,8 @@ def test_validate_merged_config_valid(monkeypatch: pytest.MonkeyPatch) -> None:
     cmd = cast("list[str]", called["cmd"])
     # Check that some argument refers to a ruff.toml-specific path.
     assert any("ruff.toml" in str(part) for part in cmd)
-    # Also verify --isolated is present
-    assert "--isolated" in cmd
+    # verify --isolated is NOT present because it conflicts with --config
+    assert "--isolated" not in cmd
 
 
 def test_validate_merged_config_returns_false_on_invalid(
@@ -491,5 +492,166 @@ async def test_pull_succeeds_when_validate_passes(
     assert "line-length = 100" in source_path.read_text()
 
 
+# ===========================================================================
+# Priority 2 — Python Version Consistency Check
+# ===========================================================================
+
+
+@pytest.mark.parametrize(
+    "toml_content, expected_warn, expected_msg",
+    [
+        pytest.param(
+            '[project]\nrequires-python = ">=3.10"\n\n[tool.ruff]\ntarget-version = "py39"\n',
+            True,
+            "Version mismatch",
+            id="mismatch-warn",
+        ),
+        pytest.param(
+            '[project]\nrequires-python = ">=3.10"\n\n[tool.ruff]\ntarget-version = "py310"\n',
+            False,
+            None,
+            id="compatible-exact",
+        ),
+        pytest.param(
+            '[project]\nrequires-python = ">=3.10"\n',
+            False,
+            None,
+            id="missing-target-version",
+        ),
+        pytest.param(
+            '[tool.ruff]\ntarget-version = "py39"\n',
+            False,
+            None,
+            id="missing-requires-python",
+        ),
+        pytest.param(
+            '[project]\nrequires-python = "foo"\n\n[tool.ruff]\ntarget-version = "py310"\n',
+            False,
+            None,
+            id="unparsable-requires-python",
+        ),
+        pytest.param(
+            '[project]\nrequires-python = ">=3.10"\n\n[tool.ruff]\ntarget-version = "3.10"\n',
+            False,
+            None,
+            id="unparsable-target-version",
+        ),
+        pytest.param(
+            '[project]\nrequires-python = "==3.11.*,>=3.8"\n'
+            '\n[tool.ruff]\ntarget-version = "py39"\n',
+            False,
+            None,
+            id="multiple-specifiers-ok",
+        ),
+        pytest.param(
+            '[project]\nrequires-python = ">=3.10, <4"\n\n[tool.ruff]\ntarget-version = "py39"\n',
+            True,
+            "Version mismatch",
+            id="multiple-specifiers-warn",
+        ),
+    ],
+)
+def test_version_consistency_cases(
+    caplog: pytest.LogCaptureFixture,
+    toml_content: str,
+    expected_warn: bool,
+    expected_msg: str | None,
+) -> None:
+    """Parametrized test for Python version consistency validation."""
+    doc = tomlkit.parse(toml_content)
+
+    with caplog.at_level(logging.WARNING, logger="ruff_sync.validation"):
+        result = check_python_version_consistency(doc)
+
+    # All these cases should return True (warnings only)
+    assert result is True
+    if expected_warn:
+        assert expected_msg is not None
+        assert expected_msg in caplog.text
+    else:
+        assert "Version mismatch" not in caplog.text
+
+
+def test_version_consistency_skipped_for_ruff_toml(caplog: pytest.LogCaptureFixture) -> None:
+    """Standalone ruff.toml files lack [project], so the check should be skipped."""
+    doc = tomlkit.parse("target-version = 'py39'\n")
+    # validate_merged_config skips the check if is_ruff_toml=True
+    with caplog.at_level(logging.WARNING, logger="ruff_sync.validation"):
+        result = validate_merged_config(doc, is_ruff_toml=True)
+
+    assert result is True
+    assert "Version mismatch" not in caplog.text
+
+
+@pytest.mark.parametrize(
+    "toml_content, expected_suffix",
+    [
+        pytest.param(
+            "",
+            "missing [tool.ruff] target-version, [project] requires-python.",
+            id="missing-both",
+        ),
+        pytest.param(
+            '[project]\nrequires-python = ">=3.10"\n',
+            "missing [tool.ruff] target-version.",
+            id="missing-target",
+        ),
+        pytest.param(
+            '[tool.ruff]\ntarget-version = "py310"\n',
+            "missing [project] requires-python.",
+            id="missing-requires",
+        ),
+    ],
+)
+def test_version_consistency_logs_skip_decision(
+    caplog: pytest.LogCaptureFixture, toml_content: str, expected_suffix: str
+) -> None:
+    """It should log a warning message when skipping due to missing version keys."""
+    doc = tomlkit.parse(toml_content)
+    with caplog.at_level(logging.WARNING, logger="ruff_sync.validation"):
+        check_python_version_consistency(doc)
+
+    expected_msg = f"Skipping Python version consistency check: {expected_suffix}"
+    assert expected_msg in caplog.text
+
+
+def test_version_consistency_skipped_when_excluded(caplog: pytest.LogCaptureFixture) -> None:
+    """It should log a specific warning when target-version is explicitly excluded."""
+    # mismatch that would normally warn
+    toml_content = '[project]\nrequires-python = ">=3.10"\n\n[tool.ruff]\ntarget-version = "py39"\n'
+    doc = tomlkit.parse(toml_content)
+
+    with caplog.at_level(logging.WARNING, logger="ruff_sync.validation"):
+        # Case 1: excluded via 'target-version'
+        result = check_python_version_consistency(doc, exclude=("target-version",))
+        assert result is True
+        assert (
+            "Skipping Python version consistency check: 'target-version' is "
+            "excluded in [tool.ruff-sync]."
+        ) in caplog.text
+
+        caplog.clear()
+
+        # Case 2: excluded via 'tool.ruff.target-version'
+        result = check_python_version_consistency(doc, exclude=("tool.ruff.target-version",))
+        assert result is True
+        assert (
+            "Skipping Python version consistency check: 'target-version' is "
+            "excluded in [tool.ruff-sync]."
+        ) in caplog.text
+
+
+def test_strict_mode_fails_on_version_mismatch(caplog: pytest.LogCaptureFixture) -> None:
+    """In strict mode, a version mismatch should cause validation to fail."""
+    doc = tomlkit.parse(
+        '[project]\nrequires-python = ">=3.10"\n\n[tool.ruff]\ntarget-version = "py39"\n'
+    )
+    with caplog.at_level(logging.ERROR, logger="ruff_sync.validation"):
+        result = validate_merged_config(doc, strict=True)
+
+    assert result is False
+    assert "Version mismatch" in caplog.text
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-vv"])

{ruff_sync-0.1.6.dev1 → ruff_sync-0.1.6.dev2}/uv.lock

@@ -1610,7 +1610,7 @@ wheels = [
 
 [[package]]
 name = "ruff-sync"
-version = "0.1.6.dev1"
+version = "0.1.6.dev2"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },