ruff-sync 0.0.1.dev2__tar.gz

ruff_sync-0.0.1.dev2/.agents/TESTING.md

@@ -0,0 +1,113 @@
+# Testing Standards for ruff-sync
+
+This document defines the mandatory testing standards and patterns for the `ruff-sync` project. AI agents MUST follow these guidelines when adding or modifying tests.
+
+## 1. Core Principles
+
+- **Every Fix Needs a Test**: Any bug fix must include a reproduction test that fails without the fix and passes with it.
+- **No Side Effects**: Tests must be isolated and not touch the actual filesystem or make real network calls.
+- **Semantic + Structural Assertions**: When testing TOML merges, always verify **both**:
+  1. **Structural/Whitespace**: The file "looks" correct (comments and spacing are preserved).
+  2. **Semantic**: The actual data in the merged result matches the expected values.
+- **DRY with Fixtures and Parameterization**: Avoid code duplication. Use fixtures for common setups and `@pytest.mark.parametrize` for matrix testing.
+
+## 2. Tooling and Environment
+
+- **Execution**: Always run tests using `poetry run pytest -vv`.
+- **Async Tests**: We use `pytest-asyncio` in **strict mode**.
+  - Always decorate async tests with `@pytest.mark.asyncio`.
+- **HTTP Mocking**: Use [respx](https://github.com/lundberg/respx) for all network interactions.
+- **FS Mocking**: Use [pyfakefs](https://jmcgeheeiv.github.io/pyfakefs/) for file-based tests.
+
+## 3. Best Practices and Patterns
+
+### 3.1 Use Pytest Fixtures
+Avoid re-defining common TOML strings or setup logic in every test function. Use fixtures to provide consistent test data.
+
+```python
+@pytest.fixture
+def sample_ruff_config() -> str:
+    return """[tool.ruff]
+target-version = "py310"
+lint.select = ["F", "E"]
+"""
+```
+
+### 3.2 Parameterization
+Use `@pytest.mark.parametrize` to test the same logic against multiple scenarios. Use `pytest.param(..., id="case_name")` to ensure test reports are readable.
+
+```python
+@pytest.mark.parametrize(
+    "source, upstream, expected_keys",
+    [
+        pytest.param("[tool.ruff]\nselect=[]", "select=['F']", {"select"}, id="simple-add"),
+        pytest.param("[tool.ruff]\nignore=['E']", "ignore=['W']", {"ignore"}, id="simple-merge"),
+    ]
+)
+def test_merge_scenarios(source, upstream, expected_keys):
+    # ... test logic ...
+```
+
+## 4. Handling TOML and `tomlkit`
+
+`tomlkit` is central to this project but its dynamic type system can be tricky for mypy.
+
+### The "Proxy" Problem
+`tomlkit` often returns "proxy" objects (like dotted keys) that don't always behave like standard dicts.
+- **Assertion Pattern**: To satisfy mypy when indexing into a parsed document in tests, use the `cast(Any, ...)` pattern:
+  ```python
+  from typing import Any, cast
+  import tomlkit
+
+  doc = tomlkit.parse(content)
+  # Cast the document or table to Any before deep indexing
+  ruff_cfg = cast(Any, doc)["tool"]["ruff"]
+  assert ruff_cfg["target-version"] == "py310"
+  ```
+- **Comparison**: Use `list()` or `.unwrap()` if you need to compare `tomlkit` arrays/objects to standard Python types.
+
+## 4. Lifecycle TOML Fixtures
+
+For end-to-end (E2E) testing of the sync/merge logic, use the "Lifecycle" pattern.
+
+### Fixture Triples
+Each test case consists of three files in `tests/lifecycle_tomls/`:
+1.  `<case_name>_initial.toml`: The starting project state.
+2.  `<case_name>_upstream.toml`: The remote ruff config to sync from.
+3.  `<case_name>_final.toml`: The expected result after merge.
+
+### Scaffolding New Cases
+Use the provided Invoke task to create a new case from a template:
+```bash
+poetry run invoke new-case --name <case_name> --description "Description of the edge case"
+```
+
+## 5. Standard Assertions for Merges
+
+When testing `merge_ruff_toml`, your test body should look like this:
+
+```python
+def test_my_edge_case():
+    source_s = "..."
+    upstream_s = "..."
+
+    source_doc = tomlkit.parse(source_s)
+    upstream_ruff = cast(Any, tomlkit.parse(upstream_s))["tool"]["ruff"]
+
+    merged_doc = ruff_sync.merge_ruff_toml(source_doc, upstream_ruff)
+    merged_s = merged_doc.as_string()
+
+    # 1. Structural check (e.g., check for comment preservation)
+    assert "# Important comment" in merged_s
+
+    # 2. Semantic check (the "Source of Truth")
+    merged_data = tomlkit.parse(merged_s)
+    ruff = cast(Any, merged_data)["tool"]["ruff"]
+    assert ruff["lint"]["select"] == ["F", "E"]
+```
+
+## 6. Code Coverage
+
+We target **high coverage** for `ruff_sync.py`.
+- Run coverage locally: `poetry run coverage run -m pytest -vv && poetry run coverage report`
+- New features MUST include unit tests in `tests/test_basic.py` or specialized files like `tests/test_whitespace.py` if they involve formatting logic.

ruff_sync-0.0.1.dev2/.agents/workflows/add-test-case.md

@@ -0,0 +1,38 @@
+---
+description: How to add a new lifecycle TOML test case for ruff-sync
+---
+
+Follow these steps to add a new end-to-end (E2E) test case for `ruff-sync` to test a specific sync or merge scenario.
+
+### 1. Identify the Edge Case or Bug
+- Clearly define the "Initial" state (local `pyproject.toml`) and the "Upstream" state (remote `pyproject.toml`).
+- Define the "Final" expected state after the sync.
+
+### 2. Scaffold the Fixture
+// turbo
+1. Run the `new-case` task to generate the file triple:
+   ```bash
+   poetry run invoke new-case --name <case_name> --description "Description of the test case"
+   ```
+   *Replace `<case_name>` with a simple name (e.g., `dotted_keys`). This creates files in `tests/lifecycle_tomls/`.*
+
+### 3. Edit the Fixtures
+1. Edit `tests/lifecycle_tomls/<case_name>_initial.toml` with the local starting state.
+2. Edit `tests/lifecycle_tomls/<case_name>_upstream.toml` with the remote config (must contain a `[tool.ruff]` section).
+3. Edit `tests/lifecycle_tomls/<case_name>_final.toml` with the expected result of the merge.
+
+### 4. Run the E2E Test Suite
+// turbo
+1. Execute the tests to ensure the new case is picked up:
+   ```bash
+   poetry run pytest -vv tests/test_e2e.py
+   ```
+   *The E2E suite automatically discovers all file triples in the `lifecycle_tomls/` directory.*
+
+### 5. Validate Formatting and Types
+// turbo
+1. Ensure the new TOML files don't break any project rules:
+   ```bash
+   poetry run invoke lint --check
+   poetry run invoke types
+   ```

ruff_sync-0.0.1.dev2/.github/dependabot.yml

@@ -0,0 +1,9 @@
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # Documentation: For package managers such as pipenv and poetry, you need to use the pip YAML value.
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: daily

ruff_sync-0.0.1.dev2/.github/workflows/ci.yaml

@@ -0,0 +1,90 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  schedule:
+    - cron: "0 */6 * * *"
+
+jobs:
+  static-analysis:
+    strategy:
+      matrix:
+        task: ["lint", "fmt", "type-check"]
+      fail-fast: false
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.10
+
+      - name: Install dependencies
+        run: uv sync --group dev --frozen
+
+      - run: uv run invoke ${{ matrix.task }} --check
+
+  tests:
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev --frozen
+
+      - name: Run tests
+        run: uv run coverage run -m pytest -vv
+
+      - name: Generate coverage report
+        run: uv run coverage xml
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v4.0.1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: Kilo59/ruff-sync
+
+  publish:
+    name: Build and publish to PyPI
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [static-analysis, tests]
+    runs-on: ubuntu-latest
+    permissions:
+      # This permission is required for trusted publishing
+      id-token: write
+      # This permission is required to read the repository content
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.10
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package
+        run: uv publish

ruff_sync-0.0.1.dev2/.github/workflows/complexity.yaml

@@ -0,0 +1,59 @@
+name: complexity
+
+on:
+  pull_request:
+
+jobs:
+  evaluate-complexity:
+    name: wily check
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.ref }}
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+      - name: Install Wily
+        run: pip install 'wily>=1.25.0'
+      - name: Build cache and diff
+        id: wily
+        run: |
+          wily build ruff_sync.py tasks.py tests/
+          DIFF=$(wily diff ruff_sync.py tasks.py tests/ --no-detail -r origin/${{ github.event.pull_request.base.ref }})
+          echo "$DIFF"
+
+          # Build multine output
+          DIFF="${DIFF//'%'/'%25'}"
+          DIFF="${DIFF//$'\n'/'%0A'}"
+          DIFF="${DIFF//$'\r'/'%0D'}"
+          echo "::set-output name=diff::$DIFF"
+      - name: Find current PR
+        uses: jwalton/gh-find-current-pr@v1
+        id: findPr
+      - name: Add Wily PR Comment
+        uses: marocchino/sticky-pull-request-comment@v2
+        if: steps.findPr.outputs.number && steps.wily.outputs.diff != ''
+        with:
+          recreate: true
+          number: ${{ steps.findPr.outputs.number }}
+          message: |
+            ```
+            ${{ steps.wily.outputs.diff }}
+            ```
+      - name: Add Wily PR Comment
+        uses: marocchino/sticky-pull-request-comment@v2
+        if: steps.findPr.outputs.number && steps.wily.outputs.diff == ''
+        with:
+          recreate: true
+          number: ${{ steps.findPr.outputs.number }}
+          message: |
+            ```
+            Wily: No changes in complexity detected.
+            ```

ruff_sync-0.0.1.dev2/.gitignore

@@ -0,0 +1,182 @@
+# Generated by Cargo
+# will have compiled files and executables
+/target/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# Python
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Agent-generated log files
+logs/
+
+# IDEs
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# VSCode
+.vscode
+.DS_Store

ruff_sync-0.0.1.dev2/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-ast
+      - id: check-json
+      - id: check-yaml
+        args: ["--unsafe"]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: no-commit-to-branch
+        args: [--branch, develop, --branch, main]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.15.5"
+    hooks:
+      - id: ruff-check
+        args: ["--fix"]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        types_or: [yaml, json]
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.11
+    hooks:
+      - id: actionlint
+        exclude: .github/workflows/complexity.yaml
+# https://pre-commit.ci/
+ci:
+  autofix_commit_msg: |
+    [pre-commit.ci] auto fixes from pre-commit.com hooks
+
+    for more information, see https://pre-commit.ci
+  autofix_prs: true
+  autoupdate_branch: "main"
+  autoupdate_commit_msg: "[pre-commit.ci] pre-commit autoupdate"
+  autoupdate_schedule: weekly
+  submodules: false