build(lint): consolidate linters under pre-commit

Migrate all linting tools to pre-commit for unified local and CI execution.

- Add .pre-commit-config.yaml with hooks for file checks, Python version
  consistency, EditorConfig, markdownlint-cli2, Ruff, mypy, and Mergify
- Add conditional_hook.py wrapper for a graceful skip (with a warning) when requirements for
  linters (like Node.js for markdownlint-cli2) are not installed locally
- Update Hatch lint environment with pre-commit integration
- Rename .markdownlint-config.yaml to .markdownlint.yaml for markdownlint-cli2
  compatibility
- Update AGENTS.md and docs/develop.md with pre-commit documentation

Author: MichaelYochpaz

.github/workflows/check.yaml

@@ -20,53 +20,16 @@ jobs:
         with:
           python-version: "3.11"  # minimum supported lang version
 
-      - name: Install 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
+      - name: Set up Node.js (for markdownlint)
+        uses: actions/setup-node@v4
         with:
-          fetch-depth: 0
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: "3.11"  # minimum supported lang version
+          node-version: "20"
 
       - 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.11"  # 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
+      - name: Run pre-commit hooks
+        run: hatch run lint:install-hooks && hatch run lint:precommit
 
   pkglint:
     name: pkglint
@@ -89,22 +52,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/[email protected]
-        with:
-          config: .markdownlint-config.yaml
-        #   files: 'docs/**/*.md'
-        #   ignore: node_modules
-        #   version: 0.28.1
-
   docs:
     name: readthedocs
     runs-on: ubuntu-latest
@@ -125,23 +72,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/[email protected] # 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

.markdownlint-config.yaml .markdownlint.yaml.markdownlint-config.yaml renamed to .markdownlint.yaml

@@ -1,4 +1,11 @@
+# Pre-commit configuration
+# Run locally: pre-commit run --all-files
+# CI runs via: hatch run lint:precommit
+
 repos:
+  # ---------------------------------------------------------------------------
+  # 1. Standard file checks (fastest, run first)
+  # ---------------------------------------------------------------------------
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0
     hooks:
@@ -9,18 +16,76 @@ repos:
       - id: check-merge-conflict     # Prevents merge conflict markers
       - id: check-toml               # Validates TOML syntax
 
+  # ---------------------------------------------------------------------------
+  # 2. Python version consistency check
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/mgedmin/check-python-versions
+    rev: "0.24.0"
+    hooks:
+      - id: check-python-versions
+        args: ["--only", "pyproject.toml,.github/workflows/test.yaml"]
+
+  # ---------------------------------------------------------------------------
+  # 3. EditorConfig validation (polyglot formatting)
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/editorconfig-checker/editorconfig-checker.python
+    rev: 3.2.1
+    hooks:
+      - id: editorconfig-checker
+        alias: ec
+        # Exclude files that are auto-generated or strictly formatted elsewhere
+        exclude: |
+          (?x)^(
+              LICENSE|
+              .*\.lock|
+              dist/.*
+          )$
+
+  # ---------------------------------------------------------------------------
+  # 4. Markdown linting
+  # ---------------------------------------------------------------------------
   - repo: local
     hooks:
-      - id: hatch-lint
-        name: hatch lint check
-        entry: hatch run lint:check
+      - id: markdownlint
+        name: markdownlint
+        entry: python scripts/conditional_hook.py markdownlint-cli2
+        args: ["--fix"]
         language: system
-        types: [python]
-        pass_filenames: false
+        types: [markdown]
+        require_serial: true
+        verbose: true
 
+  # ---------------------------------------------------------------------------
+  # 5. Python linting & formatting (Ruff - official hooks)
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.11
+    hooks:
+      # Linter: Runs BEFORE formatter
+      # Rationale: Fixes (like removing imports) change line lengths
+      - id: ruff-check
+        args: [--fix]
+        types_or: [python, pyi]
+
+      # Formatter: Runs AFTER linter to clean up any changes
+      - id: ruff-format
+        types_or: [python, pyi]
+
+  # ---------------------------------------------------------------------------
+  # 6. Local hooks (tools without official pre-commit hooks)
+  # ---------------------------------------------------------------------------
+  - 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

.pre-commit-config.yaml

@@ -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`.
+**Conditional hooks:** The markdownlint hook skips with a warning when Node.js is unavailable locally. In CI, missing Node.js fails the build.
 
 ## Safety and Permissions
 

AGENTS.md

@@ -1,5 +1,45 @@
 # 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**: markdownlint (style and consistency)
+- **Config validation**: EditorConfig, Mergify, Python version consistency
+
+### Optional: Markdown linting
+
+The markdownlint hook requires Node.js. If Node.js isn't installed on your system:
+
+- **Locally**: The hook skips with a warning—your commit proceeds normally
+- **In CI**: The hook runs strictly and will fail if markdownlint fails to run
+
+To enable markdown linting locally, install Node.js and then:
+
+```bash
+npm install -g markdownlint-cli2
+```
+
 ## Unit tests and linter
 
 The unit tests and linter now use [Hatch](https://hatch.pypa.io/) and a

docs/develop.md

@@ -1,6 +1,5 @@
 import logging
 import pathlib
-import typing
 
 from packaging.requirements import Requirement
 from packaging.version import Version
@@ -25,10 +24,15 @@ def build_wheel(
     # 'pip wheel'.
     #
     # https://flit.pypa.io/en/stable/bootstrap.html
-    logger.info('using override to build flit_core wheel in %s', sdist_root_dir)
+    logger.info("using override to build flit_core wheel in %s", sdist_root_dir)
     external_commands.run(
-        [str(build_env.python), '-m', 'flit_core.wheel',
-         '--outdir', str(ctx.wheels_build)],
+        [
+            str(build_env.python),
+            "-m",
+            "flit_core.wheel",
+            "--outdir",
+            str(ctx.wheels_build),
+        ],
         cwd=str(sdist_root_dir),
         extra_environ=extra_environ,
     )

e2e/flit_core_override/src/package_plugins/flit_core.py

@@ -47,9 +47,7 @@ def after_prebuilt_wheel(
     dist_version: str,
     wheel_filename: pathlib.Path,
 ) -> None:
-    logger.info(
-        f"running post build hook in {__name__} for {wheel_filename}"
-    )
+    logger.info(f"running post build hook in {__name__} for {wheel_filename}")
     test_file = ctx.work_dir / "test-prebuilt.txt"
     logger.info(f"prebuilt-wheel hook writing to {test_file}")
     test_file.write_text(f"{dist_name}=={dist_version}")

e2e/fromager_hooks/src/package_plugins/hooks.py

@@ -41,15 +41,19 @@
 e2e_dir = pathlib.Path("e2e")
 # Look for CI suite scripts instead of individual test scripts
 ci_suite_jobs = set(
-    script.name[:-len(".sh")] for script in e2e_dir.glob("ci_*_suite.sh")
+    script.name[: -len(".sh")] for script in e2e_dir.glob("ci_*_suite.sh")
 )
 print("found CI suite scripts:\n  ", "\n  ".join(sorted(ci_suite_jobs)), sep="")
 
 # Also find all individual e2e test scripts to ensure they're all covered
 individual_e2e_scripts = set(
     script.name[len("test_") : -len(".sh")] for script in e2e_dir.glob("test_*.sh")
 )
-print("found individual e2e scripts:\n  ", "\n  ".join(sorted(individual_e2e_scripts)), sep="")
+print(
+    "found individual e2e scripts:\n  ",
+    "\n  ".join(sorted(individual_e2e_scripts)),
+    sep="",
+)
 
 # Remember if we should fail so we can apply all of the rules and then
 # exit with an error.
@@ -66,23 +70,27 @@
 for ci_suite_file in e2e_dir.glob("ci_*_suite.sh"):
     content = ci_suite_file.read_text(encoding="utf8")
     # Look for run_test "script_name" calls (excluding commented lines)
-    for line in content.split('\n'):
+    for line in content.split("\n"):
         # Skip lines that start with # (comments)
         stripped = line.strip()
-        if stripped.startswith('#'):
+        if stripped.startswith("#"):
             continue
         for match in re.finditer(r'run_test\s+"([^"]+)"', line):
             referenced_scripts.add(match.group(1))
 
-print("scripts referenced in CI suites:\n  ", "\n  ".join(sorted(referenced_scripts)), sep="")
+print(
+    "scripts referenced in CI suites:\n  ",
+    "\n  ".join(sorted(referenced_scripts)),
+    sep="",
+)
 
 # Find any individual e2e scripts that aren't referenced in any CI suite
 unreferenced_scripts = individual_e2e_scripts.difference(referenced_scripts)
 if unreferenced_scripts:
-    print(f"\nERROR: The following e2e scripts are not referenced in any CI suite:")
+    print("\nERROR: The following e2e scripts are not referenced in any CI suite:")
     for script in sorted(unreferenced_scripts):
         print(f"  - {script}")
-    print(f"Please add these scripts to the appropriate CI suite script.")
+    print("Please add these scripts to the appropriate CI suite script.")
     RC = 1
 else:
     print("✓ All individual e2e scripts are covered by CI suites!")
@@ -99,15 +107,17 @@
     )
 )
 # for macOS, only expect latest Python version and latest Rust version
-expected_jobs.update(set(
-    str(combo).replace("'", "")
-    for combo in itertools.product(
-        python_versions[-1:],
-        rust_versions[-1:],
-        test_scripts,
-        ["macos-latest"],
+expected_jobs.update(
+    set(
+        str(combo).replace("'", "")
+        for combo in itertools.product(
+            python_versions[-1:],
+            rust_versions[-1:],
+            test_scripts,
+            ["macos-latest"],
+        )
     )
-))
+)
 if not expected_jobs.difference(existing_jobs):
     print("found rules for all expected jobs!")
 for job_name in sorted(expected_jobs.difference(existing_jobs)):