build(lint): consolidate linters under pre-commit

.git-blame-ignore-revs

@@ -0,0 +1,8 @@
+# This file lists commits that should be ignored by `git blame`.
+# To read more, see: https://docs.github.com/en/repositories/working-with-files/using-files/viewing-and-understanding-files#ignore-commits-in-the-blame-view
+
+# MDFormat Markdown formatting alignment
+0be84aaf1f350aae7a40e1dc7d6fc07711d87277
+
+# Ruff formatting alignment
+f81e85ca9f02941cc012e82c189db417d4fed9ca

.github/workflows/check.yaml

@@ -20,54 +20,12 @@ jobs:
         with:
           python-version: "3.12"  # minimum supported lang version
 
-      - name: Install dependencies
+      - name: Install Python dependencies
         run: python -m pip install hatch 'click!=8.3.0'
 
       - name: Run pre-commit hooks
         run: hatch run lint:install-hooks && hatch run lint:precommit
 
-  linter:
-    name: linter
-    runs-on: ubuntu-latest
-    if: ${{ !startsWith(github.ref, 'refs/tags') }}
-
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: "3.12"  # minimum supported lang version
-
-      - name: Install dependencies
-        run: python -m pip install hatch 'click!=8.3.0'
-
-      - name: Run
-        run: hatch run lint:check
-
-  mypy:
-    name: mypy
-    runs-on: ubuntu-latest
-    if: ${{ !startsWith(github.ref, 'refs/tags') }}
-
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: "3.12"  # minimum supported lang version
-
-      - name: Install dependencies
-        run: python -m pip install hatch 'click!=8.3.0'
-
-      - name: Check MyPy
-        run: hatch run mypy:check
-
   pkglint:
     name: pkglint
     runs-on: ubuntu-latest
@@ -89,22 +47,6 @@ jobs:
       - name: Run
         run: hatch run lint:pkglint
 
-  markdownlint:
-    # https://github.com/marketplace/actions/markdown-lint
-    name: markdownlint
-    runs-on: ubuntu-latest
-    if: ${{ !startsWith(github.ref, 'refs/tags') }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-      - uses: articulate/actions-markdownlint@v1.1.0
-        with:
-          config: .markdownlint-config.yaml
-        #   files: 'docs/**/*.md'
-        #   ignore: node_modules
-        #   version: 0.28.1
-
   docs:
     name: readthedocs
     runs-on: ubuntu-latest
@@ -125,23 +67,3 @@ jobs:
 
       - name: Run
         run: hatch run docs:build
-
-  super-linter:
-    name: super-linter
-    runs-on: ubuntu-latest
-    if: ${{ !startsWith(github.ref, 'refs/tags') }}
-
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-      - name: Super-Linter
-        uses: super-linter/super-linter@v8.5.0 # x-release-please-version
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # To reuse the same Super-linter configuration that you use in the
-          # lint job without duplicating it, see
-          # https://github.com/super-linter/super-linter/blob/main/docs/run-linter-locally.md#share-environment-variables-between-environments
-          VALIDATE_ALL_CODEBASE: false
-          VALIDATE_MARKDOWN: true
-          VALIDATE_EDITORCONFIG: true

.mdformat.toml

@@ -0,0 +1,9 @@
+# Use consecutive numbering for ordered lists (1, 2, 3 instead of 1, 1, 1)
+number = true
+
+# Preserve original line wrapping
+wrap = "keep"
+
+[plugin.tables]
+# Strip extra spaces from GFM tables (don't pad columns for alignment)
+compact_tables = true

.mergify.yml

@@ -7,7 +7,7 @@ pull_request_rules:
           - "title~=^e2e:"
           - files~=pyproject.toml
           - files~=.github/
-          - files~=.markdownlint-config.yaml
+          - files~=.mdformat.toml
           - files~=tests/
           - files~=e2e/
     actions:

.pre-commit-config.yaml

@@ -1,32 +1,63 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v6.0.0
     hooks:
-      - id: end-of-file-fixer        # Ensures single trailing newline
-      - id: trailing-whitespace      # Removes trailing spaces
-        args: [--markdown-linebreak-ext=md]  # Preserve markdown line breaks
-      - id: check-yaml               # Validates YAML syntax
-      - id: check-merge-conflict     # Prevents merge conflict markers
-      - id: check-toml               # Validates TOML syntax
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: check-yaml
+      - id: check-merge-conflict
+      - id: check-toml
 
-  - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.39.0
+  - repo: https://github.com/mgedmin/check-python-versions
+    rev: "0.24.0"
     hooks:
-      - id: markdownlint
-        args: [--config, .markdownlint-config.yaml]
+      - id: check-python-versions
+        args: ["--only", "pyproject.toml,.github/workflows/test.yaml"]
 
-  - repo: local
+  - repo: https://github.com/editorconfig-checker/editorconfig-checker.python
+    rev: 3.2.1
     hooks:
-      - id: hatch-lint
-        name: hatch lint check
-        entry: hatch run lint:check
-        language: system
-        types: [python]
-        pass_filenames: false
+      - id: editorconfig-checker
+        alias: ec
+        # Exclude files that are auto-generated or strictly formatted elsewhere
+        exclude: |
+          (?x)^(
+              LICENSE|
+              .*\.lock|
+              dist/.*
+          )$
 
+  - repo: https://github.com/hukkin/mdformat
+    rev: 1.0.0
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-gfm  # GitHub Flavored Markdown support (tables, autolinks, etc.)
+          - mdformat-simple-breaks  # Use --- for thematic breaks instead of 70 underscores
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.11
+    hooks:
+      # Linter runs before formatter so fixes (like removing imports) get formatted
+      - id: ruff-check
+        args: [--fix]
+        types_or: [python, pyi]
+      - id: ruff-format
+        types_or: [python, pyi]
+
+  - repo: local
+    hooks:
       - id: hatch-mypy
         name: hatch mypy check
         entry: hatch run mypy:check
         language: system
         types: [python]
         pass_filenames: false
+
+      - id: mergify-lint
+        name: mergify lint
+        entry: hatch run lint:mergify
+        language: system
+        files: ^\.mergify\.yml$
+        pass_filenames: false

AGENTS.md

@@ -74,15 +74,15 @@ hatch run lint:precommit # All linters and other pre-commit hooks
 
 ### Pre-commit Hooks
 
-The project uses pre-commit hooks to automatically check file formatting:
+Run all linters and formatters via pre-commit:
 
-- **File endings**: Ensures all files end with a single newline
-- **Whitespace**: Removes trailing whitespace
-- **Syntax**: Validates YAML/TOML files
-- **Conflicts**: Prevents committing merge conflict markers
-- **Linters**: Runs the `mypy` and `ruff` linters
+```bash
+hatch run lint:precommit    # Run all hooks manually
+```
+
+Pre-commit runs automatically on commit after installation with `hatch run lint:install-hooks`.
 
-These run automatically on commit if installed with `hatch run lint:install-hooks`.
+**Markdown formatting:** The mdformat hook formats Markdown files using a pure Python formatter with GitHub Flavored Markdown support.
 
 ## Safety and Permissions
 

CONTRIBUTING.md

@@ -23,6 +23,7 @@ Fromager thrives on practical, well-tested contributions. This guide summarizes
 ### Prerequisites
 
 - Python 3.12 or newer
+
 - `hatch` for environment and task management
 
   ```bash
@@ -358,7 +359,7 @@ EnvKey = typing.Annotated[str, BeforeValidator(_validate_envkey)]
 ### Commands
 
 | Task | Command |
-| ------ | --------- |
+| -- | -- |
 | Run tests | `hatch run test:test` |
 | Check code quality | `hatch run lint:check` |
 | Fix formatting | `hatch run lint:fix` |
@@ -367,7 +368,7 @@ EnvKey = typing.Annotated[str, BeforeValidator(_validate_envkey)]
 ### Standards
 
 | Standard | Requirement |
-| ---------- | ------------- |
+| -- | -- |
 | Type annotations | Required for every function |
 | Docstrings | Required on public APIs |
 | Tests | Required for new behavior |

README.md

@@ -7,13 +7,13 @@ wheels from source.
 
 Fromager is designed to guarantee that:
 
-* Every binary package you install was built from source in a reproducible environment compatible with your own.
+- Every binary package you install was built from source in a reproducible environment compatible with your own.
 
-* All dependencies are also built from source, no prebuilt binaries.
+- All dependencies are also built from source, no prebuilt binaries.
 
-* The build tools themselves are built from source, ensuring a fully transparent toolchain.
+- The build tools themselves are built from source, ensuring a fully transparent toolchain.
 
-* Builds can be customized for your needs: applying patches, adjusting compiler options, or producing build variants.
+- Builds can be customized for your needs: applying patches, adjusting compiler options, or producing build variants.
 
 ## Design Principles
 
@@ -23,9 +23,9 @@ Fromager automates the build process with sensible defaults that work for most P
 
 Fromager can also build wheels in collections, rather than individually. Managing dependencies as a unified group ensures that:
 
-* Packages built against one another remain ABI-compatible.
+- Packages built against one another remain ABI-compatible.
 
-* All versions are resolved consistently, so the resulting wheels can be installed together without conflicts.
+- All versions are resolved consistently, so the resulting wheels can be installed together without conflicts.
 
 This approach makes Fromager especially useful in Python-heavy domains like AI, where reproducibility and compatibility across complex dependency trees are essential.
 
@@ -61,9 +61,9 @@ GITHUB_TOKEN=<access_token>
 
 ## Additional docs
 
-* [Using fromager](docs/using.md)
-* [Package build customization instructions](docs/customization.md)
-* [Developer instructions](docs/develop.md)
+- [Using fromager](docs/using.md)
+- [Package build customization instructions](docs/customization.md)
+- [Developer instructions](docs/develop.md)
 
 ## What's with the name?
 

docs/develop.md

@@ -1,5 +1,32 @@
 # Developing these tools
 
+## Pre-commit hooks
+
+The project uses [pre-commit](https://pre-commit.com/) to run linters and formatters automatically on each commit. This ensures consistent code quality across all contributions.
+
+### Setup
+
+Install the hooks once after cloning:
+
+```bash
+hatch run lint:install-hooks
+```
+
+### Running hooks
+
+Hooks run automatically when you commit. To run all hooks manually:
+
+```bash
+hatch run lint:precommit
+```
+
+### What the hooks check
+
+- **File formatting**: Trailing whitespace, final newlines, YAML/TOML syntax
+- **Python**: Ruff (linting + formatting), mypy (type checking)
+- **Markdown**: mdformat (formatting with GitHub Flavored Markdown support)
+- **Config validation**: EditorConfig, Mergify, Python version consistency
+
 ## Unit tests and linter
 
 The unit tests and linter now use [Hatch](https://hatch.pypa.io/) and a

docs/http-retry.md

@@ -7,16 +7,21 @@ Fromager includes enhanced HTTP retry functionality to handle network failures,
 The retry system provides:
 
 - **Exponential backoff with jitter** to avoid thundering herd problems
+
 - **Configurable retry attempts** (default: 8 retries)
+
 - **Smart error handling** for common network issues:
+
   - HTTP 5xx server errors (500, 502, 503, 504)
   - HTTP 429 rate limiting
   - Connection timeouts and broken connections
   - Incomplete reads during large downloads
   - DNS resolution failures
 
 - **GitHub API rate limit handling** with proper reset time detection
+
 - **GitHub authentication** automatically applied for GitHub API requests via `GITHUB_TOKEN` environment variable
+
 - **Temporary file handling** to prevent partial downloads
 
 ## Configuration