From 6f3f73f1ee985596d18a48c6326d750db0b373df Mon Sep 17 00:00:00 2001 From: sufiyan kazi Date: Mon, 16 Mar 2026 17:42:40 +0530 Subject: [PATCH 1/2] enhance pre-commit hooks with security and quality checks enhance pre-commit hooks with security and quality checks - Add gitleaks to scan for hardcoded secrets and credentials - Add detect-private-key to block accidental SSH/API key commits - Add check-merge-conflict to catch unresolved merge markers - Add check-added-large-files to prevent files over 1MB - Add check-case-conflict for cross-platform filename safety - Add check-toml for pyproject.toml validation - Add mixed-line-ending to enforce consistent LF line endings - Add conventional-pre-commit to enforce structured commit messages - Extend prettier to cover markdown files in addition to yaml/json - Add inline comments to all hooks for better developer clarity --- .pre-commit-config.yaml | 56 ++++++++++++++++++++++++++++++----------- 1 file changed, 42 insertions(+), 14 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index bc68d7a..92631c6 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -2,40 +2,68 @@ repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v6.0.0 hooks: - - id: check-ast - - id: check-json - - id: check-yaml + - id: check-ast # validates Python syntax before committing + - id: check-json # validates JSON file structure + - id: check-yaml # validates YAML file structure args: ["--unsafe"] exclude: .agents/skills/mkdocs-generation/templates/mkdocs.yml - - id: end-of-file-fixer - - id: trailing-whitespace - - id: no-commit-to-branch + - id: check-toml # validates pyproject.toml and other TOML files + - id: check-merge-conflict # blocks files that still have <<< merge conflict markers + - id: check-added-large-files # prevents files over 1MB from being committed + args: ["--maxkb=1024"] + - id: check-case-conflict # catches filename casing issues across Windows/Mac/Linux + - id: detect-private-key # blocks accidental commit of SSH keys and API secrets + - id: mixed-line-ending # enforces LF line endings for cross-platform consistency + args: ["--fix=lf"] + - id: end-of-file-fixer # ensures every file ends with a newline + - id: trailing-whitespace # removes trailing whitespace from all lines + - id: no-commit-to-branch # prevents direct commits to develop and main branches args: [--branch, develop, --branch, main] + + # Ruff: fast Python linter and formatter (replaces flake8, isort, black) - repo: https://github.com/astral-sh/ruff-pre-commit rev: "v0.15.5" hooks: - - id: ruff-check + - id: ruff-check # lints Python code and auto-fixes where possible args: ["--fix"] - - id: ruff-format + - id: ruff-format # formats Python code consistently + + # Prettier: opinionated formatter for YAML, JSON, and Markdown - repo: https://github.com/pre-commit/mirrors-prettier rev: v4.0.0-alpha.8 hooks: - id: prettier - types_or: [yaml, json] + types_or: [yaml, json, markdown] # formats all three file types exclude: .agents/skills/mkdocs-generation/templates/mkdocs.yml + + # Actionlint: static analysis for GitHub Actions workflow files - repo: https://github.com/rhysd/actionlint rev: v1.7.11 hooks: - id: actionlint exclude: .github/workflows/complexity.yaml + + # Conventional Commits: enforces structured commit messages like feat:, fix:, chore: + - repo: https://github.com/compilerla/conventional-pre-commit + rev: v3.6.0 + hooks: + - id: conventional-pre-commit + stages: [commit-msg] # runs only on the commit message stage + args: [feat, fix, docs, style, refactor, test, chore, ci, build] + + # Gitleaks: scans for hardcoded secrets, tokens, and credentials + - repo: https://github.com/gitleaks/gitleaks + rev: v8.24.0 + hooks: + - id: gitleaks + # 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" + autofix_prs: true # automatically opens a PR with fixes + autoupdate_branch: "main" # targets main branch for dependency updates autoupdate_commit_msg: "[pre-commit.ci] pre-commit autoupdate" - autoupdate_schedule: weekly - submodules: false + autoupdate_schedule: weekly # checks for hook version updates every week + submodules: false # does not run hooks inside git submodules From be29758c8affa08e115a265820f432bafde52372 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 16 Mar 2026 12:14:11 +0000 Subject: [PATCH 2/2] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- .agents/TESTING.md | 14 +++++++ .agents/skills/mkdocs-generation/SKILL.md | 4 ++ .agents/skills/mkdocs-generation/examples.md | 25 ++++++++---- .../skills/release-notes-generation/SKILL.md | 3 ++ .agents/workflows/add-test-case.md | 12 +++++- .pre-commit-config.yaml | 40 +++++++++---------- LICENSE.md | 1 - README.md | 12 +++--- docs/ci-integration.md | 4 +- docs/configuration.md | 18 ++++----- docs/index.md | 14 +++---- docs/pre-commit.md | 4 +- docs/usage.md | 17 ++++---- 13 files changed, 102 insertions(+), 66 deletions(-) diff --git a/.agents/TESTING.md b/.agents/TESTING.md index 67799a2..b063690 100644 --- a/.agents/TESTING.md +++ b/.agents/TESTING.md @@ -22,6 +22,7 @@ This document defines the mandatory testing standards and patterns for the `ruff ## 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 @@ -34,6 +35,7 @@ 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 @@ -49,9 +51,11 @@ def test_merge_scenarios(source, upstream, expected_keys): ``` ### 3.3 No Autouse Fixtures + `autouse=True` fixtures are **never allowed**. They hide setup logic and can cause non-obvious side effects or dependencies between tests. All fixtures used by a test must be explicitly requested in the test function's arguments. ### 3.4 Main Entry Point + Every test file **must** end with a main entry point block. This ensures each file is independently executable as a script (`python tests/test_foo.py`). ```python @@ -60,6 +64,7 @@ if __name__ == "__main__": ``` **Why this matters:** + 1. **Direct Execution**: Developers can run a single test file using standard Python without needing to remember complex `pytest` filter flags. 2. **IDE Workflow Integration**: Many IDEs (like VS Code or PyCharm) allow you to run the "Current File" with a single click or keyboard shortcut. Having a main block ensures this works out of the box with the correct verbosity and scope. 3. **Cleaner Diffs**: By terminating the file with this standard block, it prevents "no newline at end of file" warnings and ensures that new tests added above it produce clean, isolated diff segments. It also ensures that when debugging with `--icdiff` or similar tools, the output is scoped correctly to the specific file. @@ -69,8 +74,11 @@ if __name__ == "__main__": `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 @@ -80,6 +88,7 @@ if __name__ == "__main__": 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 @@ -87,13 +96,17 @@ if __name__ == "__main__": 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. `_initial.toml`: The starting project state. 2. `_upstream.toml`: The remote ruff config to sync from. 3. `_final.toml`: The expected result after merge. ### Scaffolding New Cases + Use the provided Invoke task to create a new case from a template: + ```bash uv run invoke new-case --name --description "Description of the edge case" ``` @@ -125,5 +138,6 @@ def test_my_edge_case(): ## 6. Code Coverage We target **high coverage** for `ruff_sync.py`. + - Run coverage locally: `uv run coverage run -m pytest -vv && uv 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. diff --git a/.agents/skills/mkdocs-generation/SKILL.md b/.agents/skills/mkdocs-generation/SKILL.md index ac48436..254e50b 100644 --- a/.agents/skills/mkdocs-generation/SKILL.md +++ b/.agents/skills/mkdocs-generation/SKILL.md @@ -40,6 +40,7 @@ mike>=2.0 ## Directory Structure **Simple (flat)**: + ``` docs/ ├── index.md # Home/overview @@ -49,6 +50,7 @@ docs/ ``` **Complex (nested)**: + ``` docs/ ├── index.md @@ -69,6 +71,7 @@ docs/ See `templates/mkdocs.yml` for the full configuration template. Key sections: + 1. **Site metadata**: name, description, URLs 2. **Versioning**: mike provider for multi-version docs 3. **Theme**: Material with navigation features @@ -88,6 +91,7 @@ Create minimal markdown files that reference Python modules: ``` mkdocstrings auto-generates documentation from docstrings. Configure in `mkdocs.yml`: + - `docstring_style: google` - Use Google-style docstrings - `show_source: false` - Hide source code - `merge_init_into_class: true` - Combine `__init__` with class docs diff --git a/.agents/skills/mkdocs-generation/examples.md b/.agents/skills/mkdocs-generation/examples.md index 76e6f77..c198c70 100644 --- a/.agents/skills/mkdocs-generation/examples.md +++ b/.agents/skills/mkdocs-generation/examples.md @@ -15,6 +15,7 @@ docs/ ``` **mkdocs.yml nav:** + ```yaml nav: - Home: index.md @@ -24,6 +25,7 @@ nav: ``` **index.md:** + ```markdown # Todoist MCP Server @@ -66,6 +68,7 @@ docs/ ``` **mkdocs.yml nav:** + ```yaml nav: - Home: index.md @@ -116,11 +119,11 @@ import asyncio from pydmp import DMPPanel async def main(): - panel = DMPPanel() - await panel.connect("192.168.1.100", "00001", "YOURKEY") - await panel.update_status() - areas = await panel.get_areas() - await panel.disconnect() +panel = DMPPanel() +await panel.connect("192.168.1.100", "00001", "YOURKEY") +await panel.update_status() +areas = await panel.get_areas() +await panel.disconnect() asyncio.run(main()) \`\`\` @@ -173,20 +176,22 @@ The CLI expects a YAML config file: \`\`\`yaml panel: - host: 192.168.1.100 - account: "00001" - remote_key: "YOURKEY" +host: 192.168.1.100 +account: "00001" +remote_key: "YOURKEY" \`\`\` ## Commands ### Areas & Zones + \`\`\`bash pydmp get-areas [--json|-j] pydmp get-zones [--json|-j] \`\`\` ### Arm/Disarm + \`\`\`bash pydmp arm "1,2,3" [--bypass-faulted|-b] [--force-arm|-f] pydmp disarm [--json|-j] @@ -195,10 +200,13 @@ pydmp disarm [--json|-j] ## Examples \`\`\`bash + # View areas with debug logs + pydmp --debug get-areas # Arm area 1 + pydmp arm "1" --bypass-faulted \`\`\` ``` @@ -216,6 +224,7 @@ docs = [ ``` Install and build: + ```bash pip install -e ".[docs]" mkdocs serve diff --git a/.agents/skills/release-notes-generation/SKILL.md b/.agents/skills/release-notes-generation/SKILL.md index d9ac8f2..03e4cd3 100644 --- a/.agents/skills/release-notes-generation/SKILL.md +++ b/.agents/skills/release-notes-generation/SKILL.md @@ -43,6 +43,7 @@ uv run invoke release --draft --skip-tests > [!NOTE] > `invoke release` will: +> > 1. Check if you are on `main`. > 2. Check for clean git state. > 3. Create a GitHub Release with `--generate-notes`. @@ -52,6 +53,7 @@ uv run invoke release --draft --skip-tests GitHub's automatically generated notes are a good start but often lack professional categorization and narrative. Use the following structure for final refinement: #### Categorization + - **🚀 Features**: New capabilities added to `ruff_sync`. - **🐞 Bug Fixes**: Issues resolved in CLI, merging logic, or HTTP handling. - **✨ Improvements**: Enhancements to existing features, performance, or logging. @@ -59,6 +61,7 @@ GitHub's automatically generated notes are a good start but often lack professio - **🛠️ Maintenance**: Dependency updates, CI changes, or test refactoring. #### Writing Style + - Use clear, action-oriented language (e.g., "Add support...", "Fix issue where...", "Refactor..."). - Link to PRs and contributors using their GitHub handles. - Include a "Breaking Changes" section if applicable (use `[!WARNING]` alerts). diff --git a/.agents/workflows/add-test-case.md b/.agents/workflows/add-test-case.md index 3a37f1a..cabf17f 100644 --- a/.agents/workflows/add-test-case.md +++ b/.agents/workflows/add-test-case.md @@ -5,32 +5,40 @@ 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 uv run invoke new-case --name --description "Description of the test case" ``` - *Replace `` with a simple name (e.g., `dotted_keys`). This creates files in `tests/lifecycle_tomls/`.* + _Replace `` with a simple name (e.g., `dotted_keys`). This creates files in `tests/lifecycle_tomls/`._ ### 3. Edit the Fixtures + 1. Edit `tests/lifecycle_tomls/_initial.toml` with the local starting state. 2. Edit `tests/lifecycle_tomls/_upstream.toml` with the remote config (must contain a `[tool.ruff]` section). 3. Edit `tests/lifecycle_tomls/_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 uv run pytest -vv tests/test_e2e.py ``` - *The E2E suite automatically discovers all file triples in the `lifecycle_tomls/` directory.* + _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 uv run invoke lint --check diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 92631c6..26d197f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -2,38 +2,38 @@ repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v6.0.0 hooks: - - id: check-ast # validates Python syntax before committing - - id: check-json # validates JSON file structure - - id: check-yaml # validates YAML file structure + - id: check-ast # validates Python syntax before committing + - id: check-json # validates JSON file structure + - id: check-yaml # validates YAML file structure args: ["--unsafe"] exclude: .agents/skills/mkdocs-generation/templates/mkdocs.yml - - id: check-toml # validates pyproject.toml and other TOML files - - id: check-merge-conflict # blocks files that still have <<< merge conflict markers - - id: check-added-large-files # prevents files over 1MB from being committed + - id: check-toml # validates pyproject.toml and other TOML files + - id: check-merge-conflict # blocks files that still have <<< merge conflict markers + - id: check-added-large-files # prevents files over 1MB from being committed args: ["--maxkb=1024"] - - id: check-case-conflict # catches filename casing issues across Windows/Mac/Linux - - id: detect-private-key # blocks accidental commit of SSH keys and API secrets - - id: mixed-line-ending # enforces LF line endings for cross-platform consistency + - id: check-case-conflict # catches filename casing issues across Windows/Mac/Linux + - id: detect-private-key # blocks accidental commit of SSH keys and API secrets + - id: mixed-line-ending # enforces LF line endings for cross-platform consistency args: ["--fix=lf"] - - id: end-of-file-fixer # ensures every file ends with a newline - - id: trailing-whitespace # removes trailing whitespace from all lines - - id: no-commit-to-branch # prevents direct commits to develop and main branches + - id: end-of-file-fixer # ensures every file ends with a newline + - id: trailing-whitespace # removes trailing whitespace from all lines + - id: no-commit-to-branch # prevents direct commits to develop and main branches args: [--branch, develop, --branch, main] # Ruff: fast Python linter and formatter (replaces flake8, isort, black) - repo: https://github.com/astral-sh/ruff-pre-commit rev: "v0.15.5" hooks: - - id: ruff-check # lints Python code and auto-fixes where possible + - id: ruff-check # lints Python code and auto-fixes where possible args: ["--fix"] - - id: ruff-format # formats Python code consistently + - id: ruff-format # formats Python code consistently # Prettier: opinionated formatter for YAML, JSON, and Markdown - repo: https://github.com/pre-commit/mirrors-prettier rev: v4.0.0-alpha.8 hooks: - id: prettier - types_or: [yaml, json, markdown] # formats all three file types + types_or: [yaml, json, markdown] # formats all three file types exclude: .agents/skills/mkdocs-generation/templates/mkdocs.yml # Actionlint: static analysis for GitHub Actions workflow files @@ -48,7 +48,7 @@ repos: rev: v3.6.0 hooks: - id: conventional-pre-commit - stages: [commit-msg] # runs only on the commit message stage + stages: [commit-msg] # runs only on the commit message stage args: [feat, fix, docs, style, refactor, test, chore, ci, build] # Gitleaks: scans for hardcoded secrets, tokens, and credentials @@ -62,8 +62,8 @@ 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 # automatically opens a PR with fixes - autoupdate_branch: "main" # targets main branch for dependency updates + autofix_prs: true # automatically opens a PR with fixes + autoupdate_branch: "main" # targets main branch for dependency updates autoupdate_commit_msg: "[pre-commit.ci] pre-commit autoupdate" - autoupdate_schedule: weekly # checks for hook version updates every week - submodules: false # does not run hooks inside git submodules + autoupdate_schedule: weekly # checks for hook version updates every week + submodules: false # does not run hooks inside git submodules diff --git a/LICENSE.md b/LICENSE.md index 1d4baf2..aab36bf 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,4 +1,3 @@ - The MIT License (MIT) Copyright (c) 2023 Gabriel Gore diff --git a/README.md b/README.md index 92da808..8197147 100644 --- a/README.md +++ b/README.md @@ -36,11 +36,11 @@ If you maintain more than one Python project, you've probably copy-pasted your ` ### How Other Ecosystems Solve This -| Ecosystem | Mechanism | Limitation for Ruff users | -|-----------|-----------|---------------------------| -| **ESLint** | [Shareable configs](https://eslint.org/docs/latest/extend/shareable-configs) — publish an npm package, then `extends: ["my-org-config"]` | Requires a package registry (npm). Python doesn't have an equivalent convention. | -| **Prettier** | [Shared configs](https://prettier.io/docs/sharing-configurations) — same npm-package pattern, referenced via `"prettier": "@my-org/prettier-config"` in `package.json` | Same — tightly coupled to npm. | -| **Ruff** | [`extend`](https://docs.astral.sh/ruff/configuration/#config-file-discovery) — extend from a _local_ file path (great for monorepos) | Only supports local paths. No native remote URL support ([requested in astral-sh/ruff#12352](https://github.com/astral-sh/ruff/issues/12352)). | +| Ecosystem | Mechanism | Limitation for Ruff users | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| **ESLint** | [Shareable configs](https://eslint.org/docs/latest/extend/shareable-configs) — publish an npm package, then `extends: ["my-org-config"]` | Requires a package registry (npm). Python doesn't have an equivalent convention. | +| **Prettier** | [Shared configs](https://prettier.io/docs/sharing-configurations) — same npm-package pattern, referenced via `"prettier": "@my-org/prettier-config"` in `package.json` | Same — tightly coupled to npm. | +| **Ruff** | [`extend`](https://docs.astral.sh/ruff/configuration/#config-file-discovery) — extend from a _local_ file path (great for monorepos) | Only supports local paths. No native remote URL support ([requested in astral-sh/ruff#12352](https://github.com/astral-sh/ruff/issues/12352)). | Ruff's `extend` is perfect inside a monorepo, but if your projects live in **separate repositories**, there's no built-in way to inherit config from a central source. @@ -199,7 +199,7 @@ Ensure your configuration is always in sync before every commit. Add this to you ```yaml - repo: https://github.com/Kilo59/ruff-sync - rev: v0.1.0 # Use the latest version + rev: v0.1.0 # Use the latest version hooks: - id: ruff-sync-check ``` diff --git a/docs/ci-integration.md b/docs/ci-integration.md index 07d5c63..35b6713 100644 --- a/docs/ci-integration.md +++ b/docs/ci-integration.md @@ -37,7 +37,7 @@ name: "Upstream Sync" on: schedule: - - cron: '0 0 * * 1' # Every Monday at midnight + - cron: "0 0 * * 1" # Every Monday at midnight workflow_dispatch: jobs: @@ -77,7 +77,7 @@ You can use `ruff-sync` with `pre-commit` to ensure your configuration is always See the [Pre-commit Guide](pre-commit.md) for details on using the official hooks. !!! note - Running `ruff-sync check` in pre-commit is fast because it only performs a network request if the local `pyproject.toml` is older than the upstream or if no cache exists. +Running `ruff-sync check` in pre-commit is fast because it only performs a network request if the local `pyproject.toml` is older than the upstream or if no cache exists. --- diff --git a/docs/configuration.md b/docs/configuration.md index 2b85ea9..58b0cf2 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -4,15 +4,15 @@ ## Reference -| Key | Type | Default | Description | -| :--- | :--- | :--- | :--- | -| `upstream` | `str \| list[str]` | *Required* | The URL(s) of the upstream `pyproject.toml` or `ruff.toml`. | -| `to` | `str` | `"."` | The local directory or file where configuration should be merged. | -| `exclude` | `list[str]` | `["lint.per-file-ignores"]` | A list of configuration keys to preserve locally. | -| `branch` | `str` | `"main"` | The default branch to use when resolving repository URLs. | -| `path` | `str` | `""` | The directory path within the repository where the config is located. | -| `semantic` | `bool` | `false` | Whether `check` should default to semantic matching. | -| `diff` | `bool` | `true` | Whether `check` should show a diff by default. | +| Key | Type | Default | Description | +| :--------- | :----------------- | :-------------------------- | :-------------------------------------------------------------------- | +| `upstream` | `str \| list[str]` | _Required_ | The URL(s) of the upstream `pyproject.toml` or `ruff.toml`. | +| `to` | `str` | `"."` | The local directory or file where configuration should be merged. | +| `exclude` | `list[str]` | `["lint.per-file-ignores"]` | A list of configuration keys to preserve locally. | +| `branch` | `str` | `"main"` | The default branch to use when resolving repository URLs. | +| `path` | `str` | `""` | The directory path within the repository where the config is located. | +| `semantic` | `bool` | `false` | Whether `check` should default to semantic matching. | +| `diff` | `bool` | `true` | Whether `check` should show a diff by default. | ## Exclude Patterns diff --git a/docs/index.md b/docs/index.md index ac0ac40..08b3acd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,12 +12,12 @@ ## 🚀 Key Features -* **⚡ Fast & Lightweight**: Zero-config needed for most projects. -* **✨ Formatting Preserved**: Uses `tomlkit` to keep your comments, indentation, and whitespace exactly as they are. -* **🛡️ Smart Merging**: Safely merges nested tables (like `lint.per-file-ignores`) without overwriting local overrides. -* **📂 Upstream Layers**: Combine and merge configurations from several sources sequentially. -* **🔗 Flexible Sources**: Sync from GitHub, GitLab, raw URLs, or local files. -* **✅ CI Ready**: Built-in `check` command with semantic diffs for automated pipelines. +- **⚡ Fast & Lightweight**: Zero-config needed for most projects. +- **✨ Formatting Preserved**: Uses `tomlkit` to keep your comments, indentation, and whitespace exactly as they are. +- **🛡️ Smart Merging**: Safely merges nested tables (like `lint.per-file-ignores`) without overwriting local overrides. +- **📂 Upstream Layers**: Combine and merge configurations from several sources sequentially. +- **🔗 Flexible Sources**: Sync from GitHub, GitLab, raw URLs, or local files. +- **✅ CI Ready**: Built-in `check` command with semantic diffs for automated pipelines. --- @@ -32,7 +32,7 @@ Internal "base" configurations or shared presets often fall out of sync, or requ `ruff-sync` lets you define a "source of truth" (a URL to a `pyproject.toml` or `ruff.toml`) and pull the `[tool.ruff]` section into your local projects with a single command. !!! tip "Zero Drift" - Use `ruff-sync check` in your CI to guarantee that no repository ever drifts from your organization's standards. +Use `ruff-sync check` in your CI to guarantee that no repository ever drifts from your organization's standards. --- diff --git a/docs/pre-commit.md b/docs/pre-commit.md index 31d9677..d5a8f36 100644 --- a/docs/pre-commit.md +++ b/docs/pre-commit.md @@ -12,7 +12,7 @@ Verifies that your local `pyproject.toml` or `ruff.toml` matches the upstream co ```yaml - repo: https://github.com/Kilo59/ruff-sync - rev: v0.1.0 # Use the latest version + rev: v0.1.0 # Use the latest version hooks: - id: ruff-sync-check ``` @@ -23,7 +23,7 @@ Automatically pulls and applies the upstream configuration if a drift is detecte ```yaml - repo: https://github.com/Kilo59/ruff-sync - rev: v0.1.0 # Use the latest version + rev: v0.1.0 # Use the latest version hooks: - id: ruff-sync-pull ``` diff --git a/docs/usage.md b/docs/usage.md index fd6098b..5999954 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -12,10 +12,10 @@ The `pull` command downloads the upstream configuration and merges it into your ruff-sync pull [UPSTREAM_URL...] [--to PATH] [--exclude KEY...] [--init] ``` -* **`UPSTREAM_URL...`**: One or more URLs to the source `pyproject.toml` or `ruff.toml`. Optional if defined in your local config. -* **`--to`**: Where to save the merged config (defaults to `.`). -* **`--exclude`**: Dotted paths of keys to keep local (e.g., `lint.isort`). -* **`--init`**: Create a new `pyproject.toml` if it doesn't exist. +- **`UPSTREAM_URL...`**: One or more URLs to the source `pyproject.toml` or `ruff.toml`. Optional if defined in your local config. +- **`--to`**: Where to save the merged config (defaults to `.`). +- **`--exclude`**: Dotted paths of keys to keep local (e.g., `lint.isort`). +- **`--init`**: Create a new `pyproject.toml` if it doesn't exist. ### `check` @@ -25,8 +25,8 @@ The `check` command verifies if your local configuration matches the upstream on ruff-sync check [UPSTREAM_URL...] [--semantic] [--diff] ``` -* **`--semantic`**: Ignore "non-functional" differences like whitespace, comments, or key order. -* **`--diff` / `--no-diff`**: Control the display of the unified diff. +- **`--semantic`**: Ignore "non-functional" differences like whitespace, comments, or key order. +- **`--diff` / `--no-diff`**: Control the display of the unified diff. --- @@ -37,9 +37,8 @@ One of the core features of `ruff-sync` is its ability to respect your file's ex Unlike other tools that might rewrite your TOML and strip away comments or change indentation, `ruff-sync` uses `tomlkit` to perform a **lossless merge**. !!! info "What is preserved?" - * **Comments**: All comments in your local file are kept. - * **Whitespace**: Your indentation and line breaks are respected. - * **Key Order**: The order of your existing keys in `[tool.ruff]` is preserved where possible. +_ **Comments**: All comments in your local file are kept. +_ **Whitespace**: Your indentation and line breaks are respected. \* **Key Order**: The order of your existing keys in `[tool.ruff]` is preserved where possible. ---