qa: bumped mlinter and allow local override (#45585)

* qa: bumped mlinter and allow local override

* bump version

* Update utils/check_modeling_rules_doc.py

Co-authored-by: Anton Vlasjuk <73884904+vasqu@users.noreply.github.com>

* license header

* license header

---------

Co-authored-by: Anton Vlasjuk <73884904+vasqu@users.noreply.github.com>

Author: tarekziade

docs/source/en/modeling_rules.md

@@ -13,22 +13,22 @@ specific language governing permissions and limitations under the License.
 
 # Model structure rules
 
-Transformers enforces a set of static rules on every `modeling_*.py`, `modular_*.py`, and `configuration_*.py` file. The [mlinter](https://github.com/huggingface/transformers-mlinter) tool checks them as part of `make typing` and errors out if violations are found.
+Transformers enforces a set of static rules on every `modeling_*.py`, `modular_*.py`, and `configuration_*.py` file. The [mlinter](https://github.com/huggingface/transformers-mlinter) package provides the checker engine, and the repository keeps its active rule set in `utils/rules.toml`. That local TOML lets us enable, disable, or tweak rules quickly without waiting for a new `transformers-mlinter` release.
 
 These are the expected model conventions for adding or changing modeling code. They keep the codebase consistent and ensure compatibility with features like pipeline parallelism, device maps, and weight tying.
 
 ## Running the checker
 
-`make typing` runs `mlinter` alongside the `ty` type checker. Run `mlinter` on its own with the following commands.
+`make typing` runs `mlinter` alongside the `ty` type checker through the repo wrapper, so it picks up `utils/rules.toml`. Run the same wrapper directly with the following commands.
 
 ```bash
-mlinter                  # check all modeling files
-mlinter --changed-only   # check only files changed vs origin/main
-mlinter --list-rules     # list all rules and their enabled status
-mlinter --rule TRF001    # show built-in docs for a specific rule
+python utils/check_modeling_structure.py                 # check all modeling files
+python utils/check_modeling_structure.py --changed-only  # check only files changed vs origin/main
+python utils/check_modeling_structure.py --list-rules    # list all rules and their enabled status
+python utils/check_modeling_structure.py --rule TRF001   # show built-in docs for a specific rule
 ```
 
-The `--changed-only` flag is the fastest option during development. It only checks the files you've modified relative to the main branch.
+The `--changed-only` flag is the fastest option during development. It only checks the files you've modified relative to the main branch. If you invoke `mlinter` directly instead of the wrapper, pass `--rules-toml utils/rules.toml` so local overrides are applied.
 
 ## Fixing a violation
 
@@ -52,7 +52,7 @@ Use the rule ID to look up the fix in the [rules reference](#rules-reference). T
 
 ## Rules reference
 
-Each rule below lists what it enforces and a diff showing the fix. Run `mlinter --rule TRF001` to see the built-in docs for any rule.
+Each rule below lists what it enforces and a diff showing the fix. Run `python utils/check_modeling_structure.py --rule TRF001` to see the built-in docs for any rule with the repo's current rule set.
 
 <!-- BEGIN RULES REFERENCE -->
 

setup.py

@@ -124,7 +124,9 @@
     "rjieba",
     "rouge-score!=0.0.7,!=0.0.8,!=0.1,!=0.1.1",
     "ruff==0.14.10",
-    "transformers-mlinter==0.1.0",
+    # When bumping `transformers-mlinter`, sync repo-local rule overrides from
+    # `utils/rules.toml` back into the released package.
+    "transformers-mlinter==0.1.1",
     "ty==0.0.20",
     # `sacrebleu` not used in `transformers`. However, it is needed in several tests, when a test calls
     # `evaluate.load("sacrebleu")`. This metric is used in the examples that we use to test the `Trainer` with, in the

src/transformers/dependency_versions_table.py

@@ -56,7 +56,7 @@
     "rjieba": "rjieba",
     "rouge-score": "rouge-score!=0.0.7,!=0.0.8,!=0.1,!=0.1.1",
     "ruff": "ruff==0.14.10",
-    "transformers-mlinter": "transformers-mlinter==0.1.0",
+    "transformers-mlinter": "transformers-mlinter==0.1.1",
     "ty": "ty==0.0.20",
     "sacrebleu": "sacrebleu>=1.4.12,<2.0.0",
     "sacremoses": "sacremoses",

utils/check_modeling_rules_doc.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 """
 Keep `## Rules reference` section of docs/source/en/modeling_rules.md in sync
-with the rules defined in the mlinter package.
+with the rules defined in utils/rules.toml via the installed mlinter package.
 
 Usage (from the root of the repo):
 
@@ -31,21 +31,22 @@
 """
 
 import argparse
-import os
+from pathlib import Path
 
 
 CHECKER_CONFIG = {
     "name": "modeling_rules_doc",
     "label": "Modeling rules documentation",
-    # Depends on the installed `mlinter` package output, which cannot be expressed
-    # as repo file globs for the checker cache.
+    # Depends on utils/rules.toml plus the installed `mlinter` package output,
+    # which cannot be fully expressed as repo file globs for the checker cache.
     "file_globs": None,
-    "check_args": [],
-    "fix_args": ["--fix_and_overwrite"],
+    "check_args": ["--rules-toml", "utils/rules.toml"],
+    "fix_args": ["--rules-toml", "utils/rules.toml", "--fix_and_overwrite"],
 }
 
-ROOT = os.path.dirname(os.path.dirname(__file__))
-DOC_PATH = os.path.join(ROOT, "docs", "source", "en", "modeling_rules.md")
+ROOT = Path(__file__).resolve().parent.parent
+DOC_PATH = ROOT / "docs" / "source" / "en" / "modeling_rules.md"
+RULES_TOML_PATH = ROOT / "utils" / "rules.toml"
 
 BEGIN_MARKER = "<!-- BEGIN RULES REFERENCE -->"
 END_MARKER = "<!-- END RULES REFERENCE -->"
@@ -54,21 +55,29 @@
 def _require_mlinter():
     try:
         import mlinter
+        from mlinter import mlinter as mlinter_impl
     except ModuleNotFoundError as error:
         raise ModuleNotFoundError(
             "This script requires the standalone `transformers-mlinter` package. "
             'Install the repo quality dependencies with `pip install -e ".[quality]"` and retry.'
         ) from error
 
-    return mlinter
+    return mlinter, mlinter_impl
 
 
-def generate_rules_reference() -> str:
-    return _require_mlinter().render_rules_reference()
+def _resolve_path(path: Path) -> Path:
+    return path if path.is_absolute() else ROOT / path
 
 
-def check_modeling_rules_doc(overwrite: bool = False):
-    with open(DOC_PATH, encoding="utf-8") as f:
+def generate_rules_reference(rule_specs_path: Path = RULES_TOML_PATH) -> str:
+    mlinter, mlinter_impl = _require_mlinter()
+    # Reuse mlinter's registry-switching helper so docs rendering reflects the repo-local rule file.
+    with mlinter_impl._using_rule_specs(_resolve_path(rule_specs_path)):
+        return mlinter.render_rules_reference()
+
+
+def check_modeling_rules_doc(overwrite: bool = False, rule_specs_path: Path = RULES_TOML_PATH):
+    with DOC_PATH.open(encoding="utf-8") as f:
         content = f.read()
 
     begin_idx = content.find(BEGIN_MARKER)
@@ -80,30 +89,36 @@ def check_modeling_rules_doc(overwrite: bool = False):
         )
 
     after_begin = begin_idx + len(BEGIN_MARKER)
-    expected = "\n\n" + generate_rules_reference() + "\n"
+    expected = "\n\n" + generate_rules_reference(rule_specs_path) + "\n"
     current = content[after_begin:end_idx]
 
     if current == expected:
         return
 
     if overwrite:
         new_content = content[:after_begin] + expected + content[end_idx:]
-        with open(DOC_PATH, "w", encoding="utf-8") as f:
+        with DOC_PATH.open("w", encoding="utf-8") as f:
             f.write(new_content)
         print(f"Updated rules reference in {DOC_PATH}")
     else:
         raise ValueError(
             "The rules reference section in docs/source/en/modeling_rules.md is out of sync "
-            "with the mlinter package's rules. Run `make fix-repo` to regenerate it."
+            "with utils/rules.toml. Run `make fix-repo` to regenerate it."
         )
 
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--rules-toml",
+        type=Path,
+        default=RULES_TOML_PATH,
+        help="Path to a rules TOML file. Defaults to utils/rules.toml.",
+    )
     parser.add_argument("--fix_and_overwrite", action="store_true", help="Whether to fix inconsistencies.")
     args = parser.parse_args()
 
     try:
-        check_modeling_rules_doc(args.fix_and_overwrite)
+        check_modeling_rules_doc(args.fix_and_overwrite, args.rules_toml)
     except ModuleNotFoundError as error:
         raise SystemExit(str(error)) from error

utils/check_modeling_structure.py

@@ -1,6 +1,23 @@
 #!/usr/bin/env python
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 """Thin local entrypoint for the external mlinter package."""
 
+import sys
+from pathlib import Path
+
+
 CHECKER_CONFIG = {
     "name": "modeling_structure",
     "label": "Modeling file structure",
@@ -9,10 +26,12 @@
         "src/transformers/models/**/modular_*.py",
         "src/transformers/models/**/configuration_*.py",
     ],
-    "check_args": [],
+    "check_args": ["--rules-toml", "utils/rules.toml"],
     "fix_args": None,
 }
 
+RULES_TOML_PATH = Path(__file__).resolve().with_name("rules.toml")
+
 
 def _require_mlinter():
     try:
@@ -26,8 +45,16 @@ def _require_mlinter():
     return mlinter
 
 
+def _add_default_rules_toml(argv: list[str]) -> list[str]:
+    if any(arg == "--rules-toml" or arg.startswith("--rules-toml=") for arg in argv[1:]):
+        return argv
+
+    return [argv[0], "--rules-toml", str(RULES_TOML_PATH), *argv[1:]]
+
+
 if __name__ == "__main__":
     try:
+        sys.argv = _add_default_rules_toml(sys.argv)
         raise SystemExit(_require_mlinter().main())
     except ModuleNotFoundError as error:
         raise SystemExit(str(error)) from error