define custom pre-commit hooks

[Kilo59]

Summary by Sourcery

Document and expose official pre-commit hooks for ruff-sync and link them from the main docs and README.

New Features:

• Add official pre-commit hooks definitions for ruff-sync-check and ruff-sync-pull via .pre-commit-hooks.yaml.

Documentation:

• Add a dedicated Pre-commit Integration guide describing available hooks, configuration, and usage examples.
• Update README and CI integration docs to reference the official pre-commit hooks and guide.
• Adjust MkDocs navigation to include the new Pre-commit documentation section under Usage.

[sourcery-ai]

Reviewer's Guide

Adds official pre-commit hook definitions for ruff-sync, introduces dedicated pre-commit documentation, updates README and CI docs to reference the new hooks, and wires the new page into the MkDocs navigation.

Sequence diagram for ruff-sync pre-commit hooks execution

sequenceDiagram
    actor Developer
    participant git
    participant pre_commit
    participant ruff_sync_check_hook
    participant ruff_sync_cli
    participant Upstream_config_server

    Developer->>git: git commit
    git->>pre_commit: trigger pre-commit
    pre_commit->>ruff_sync_check_hook: run hook ruff-sync-check
    ruff_sync_check_hook->>ruff_sync_cli: execute ruff-sync check --semantic
    ruff_sync_cli->>ruff_sync_cli: load [tool.ruff-sync] config
    ruff_sync_cli->>ruff_sync_cli: check cache and timestamps
    alt cache_miss_or_stale
        ruff_sync_cli->>Upstream_config_server: fetch upstream ruff config
        Upstream_config_server-->>ruff_sync_cli: upstream configuration
    end
    ruff_sync_cli->>ruff_sync_cli: compare local vs upstream (semantic)
    alt configs_in_sync
        ruff_sync_cli-->>ruff_sync_check_hook: exit 0 (pass)
        ruff_sync_check_hook-->>pre_commit: hook passed
        pre_commit-->>git: allow commit
        git-->>Developer: commit succeeds
    else drift_detected
        ruff_sync_cli-->>ruff_sync_check_hook: exit 1 (fail)
        ruff_sync_check_hook-->>pre_commit: hook failed
        pre_commit-->>Developer: show drift error
    end

    note over Developer,ruff_sync_cli: ruff-sync-pull would follow a similar flow but applies upstream config when drift is detected

Loading

Flow diagram for how pre-commit uses the new ruff-sync hook definitions

graph TD
    A[Developer defines pre-commit config
in .pre-commit-config.yaml
- repo: https://github.com/Kilo59/ruff-sync
- hooks: ruff-sync-check / ruff-sync-pull] --> B[pre-commit framework
reads .pre-commit-config.yaml]
    B --> C[pre-commit clones ruff-sync repo]
    C --> D[pre-commit reads .pre-commit-hooks.yaml
in ruff-sync repo]
    D --> E[Hook id ruff-sync-check
mapped to entry ruff-sync check --semantic]
    D --> F[Hook id ruff-sync-pull
mapped to entry ruff-sync pull]
    E --> G[On git commit, pre-commit
executes ruff-sync check --semantic]
    F --> H[On git commit, pre-commit
executes ruff-sync pull]
    G --> I[Local config validated
against upstream]
    H --> J[Local config updated
from upstream if drift detected]

Loading

File-Level Changes

Change	Details	Files
Introduce official pre-commit hooks configuration for ruff-sync.	Define ruff-sync-pull hook that pulls and applies upstream Ruff configuration using ruff-sync pull. Define ruff-sync-check hook that checks for configuration drift using ruff-sync check --semantic. Scope hooks to pyproject.toml, disable filename passing, and ensure ruff-sync is installed via additional_dependencies.	.pre-commit-hooks.yaml
Add dedicated documentation for using ruff-sync with pre-commit.	Document official ruff-sync-check and ruff-sync-pull hooks with example .pre-commit-config.yaml snippets. Explain configuration behavior via [tool.ruff-sync] in pyproject.toml. Describe performance characteristics and typical usage, including manual execution via pre-commit run.	docs/pre-commit.md
Update existing docs and site navigation to reference the new pre-commit guide and hooks.	Replace inline pre-commit example in CI integration docs with a link to the new pre-commit guide. Add a Pre-commit Integration section to the README with a minimal hook example and link to hosted pre-commit docs. Nest Configuration, Pre-commit, and CI Integration under Usage in the MkDocs navigation, and add the new pre-commit page.	docs/ci-integration.md README.md mkdocs.yml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.60%. Comparing base (e3568f6) to head (cc1136e).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #106   +/-   ##
=======================================
  Coverage   90.60%   90.60%           
=======================================
  Files           3        3           
  Lines         575      575           
=======================================
  Hits          521      521           
  Misses         54       54           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• In .pre-commit-hooks.yaml, using additional_dependencies: ["ruff-sync"] for hooks that live in the ruff-sync repo itself is redundant and can cause version skew when the repo is tagged; you can rely on the package from this repo and drop additional_dependencies unless you truly need extra third-party deps.
• Both hooks in .pre-commit-hooks.yaml are restricted to files: ^pyproject\.toml$, but the docs mention supporting ruff.toml as well; consider broadening the file pattern (or making it configurable) so projects using ruff.toml or non-root configs are also checked.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In `.pre-commit-hooks.yaml`, using `additional_dependencies: ["ruff-sync"]` for hooks that live in the `ruff-sync` repo itself is redundant and can cause version skew when the repo is tagged; you can rely on the package from this repo and drop `additional_dependencies` unless you truly need extra third-party deps.
- Both hooks in `.pre-commit-hooks.yaml` are restricted to `files: ^pyproject\.toml$`, but the docs mention supporting `ruff.toml` as well; consider broadening the file pattern (or making it configurable) so projects using `ruff.toml` or non-root configs are also checked.

## Individual Comments

### Comment 1
<location path="mkdocs.yml" line_range="109-110" />
<code_context>
   - Home: index.md
   - Installation: installation.md
   - Usage: usage.md
-  - Configuration: configuration.md
-  - CI Integration: ci-integration.md
+    - Configuration: configuration.md
+    - Pre-commit: pre-commit.md
</code_context>
<issue_to_address>
**issue (bug_risk):** The nested nav items under `Usage` are likely not structured as MkDocs expects for a section with children.

Because `- Usage: usage.md` defines `Usage` as a single page, the indented items become a sequence value for that page key rather than children in a section. To make `Usage` a section with its own page plus children, structure it like:

```yaml
- Usage:
    - Usage: usage.md
    - Configuration: configuration.md
    - Pre-commit: pre-commit.md
    - CI Integration: ci-integration.md
```

Otherwise the YAML may not parse or the nav may not render as intended.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[github-actions]

Wily: No changes in complexity detected.