add-mlinter-rule

name	add-mlinter-rule
description	Add a new TRF rule to the mlinter. Checks for duplicates, creates the rule module and TOML entry, runs against all models, and handles violations (fix or allowlist).

Add Mlinter Rule

Input

• <description>: Natural-language description of what the rule should detect.
• Optional: specific AST pattern or a before/after diff showing the pattern.

Constraints

• Rules MUST use static analysis only with Python's ast module. NEVER import runtime libraries like torch or tensorflow.
• Rules MUST follow the check(tree, file_path, source_lines) -> list[Violation] interface.
• Use the module-level RULE_ID constant instead of hardcoding the rule ID string.

Workflow

1. Check for duplicate coverage in mlinter/rules.toml.

   • Read the full TOML file and review existing rule descriptions and explanations.
   • If an existing rule already covers the same concern, stop and ask whether to proceed, extend the existing rule, or abort.

2. Determine the next rule number.

   • List all mlinter/trf*.py files and find the highest number.
   • The new rule gets that number + 1, zero-padded to three digits.

3. Add the TOML entry to mlinter/rules.toml.

   • Append a new [rules.TRFXXX] section at the end of the file with:
     • description
     • default_enabled = true
     • allowlist_models = []
     • [rules.TRFXXX.explanation] with what_it_does, why_bad, and diff
   • Follow the exact formatting style of existing entries.

4. Create the rule module at mlinter/trfXXX.py.

   • Start with the Apache 2.0 license header copied from an existing trf*.py file.
   • Add a module docstring: """TRFXXX: <short description>."""
   • Import ast, Path, and any needed helpers from ._helpers.
   • Define RULE_ID = "" # Set by discovery.
   • Implement def check(tree: ast.Module, file_path: Path, source_lines: list[str]) -> list[Violation]:.
   • Refer to existing rules in mlinter/trf*.py for patterns and helpers.

5. Run the rule against all models.

   python -m mlinter --enable-rules TRFXXX
   

   • If the run errors, fix the rule code and re-run.

6. Handle violations.

   • Present the list of violations to the user.
   • Ask whether to fix the models or add them to allowlist_models in mlinter/rules.toml.
   • If fixing, apply the fixes and re-run the rule to confirm zero violations.
   • If allowlisting, extract the model directory names from the violation file paths and add them to allowlist_models.

7. Add tests in tests/test_trfXXX.py.

   • Add at least one positive test and one negative test.
   • Follow the existing pattern: create source strings, call mlinter.analyze_file(), and assert on violations.
   • If the tests use the standard _run(rule, source, file_name=...) helper, inherit from RuleTestCase from tests/rule_test_utils.py.
   • For cross-file rules, use tempfile.TemporaryDirectory to create real file structures.
   • If the rule maps a modeling class to a specific config class, add a regression where another config class in the same file would otherwise cause a false positive or false negative.
   • Run the focused tests:

   pytest tests/test_trfXXX.py -x -v
   

8. Update documentation.

   • No rule page to write: the docs site generates one per rule from rules.toml and docs/rules/ is git-ignored, so never commit one. This makes description/what_it_does/why_bad/diff published prose — write them for someone reading a failed CI job. Preview: make docs-rules.
   • Add an entry under the ## [Unreleased] section of CHANGELOG.md (create that section above the latest released version if it does not yet exist) describing the new rule. Mention any incidental changes shipped with it (e.g. expanding MODELING_PATTERNS to cover new file types), since those affect every rule.
   • If the rule applies to file types not already documented, update the list in both README.md and docs/index.md.

9. Final validation.

   make lint
   make test
   

Model architecture knowledge

The mlinter processes files one at a time via analyze_file(file_path, text, enabled_rules). When a rule needs cross-file information, the rule module must read the other file from disk. Watch for these patterns:

Multi-config directories

Some model directories contain multiple configuration files. Match by suffix first: modeling_foo_text.py -> configuration_foo_text.py. Only fall back to a generic configuration_*.py pick when there is no exact suffix match.

Multi-class configuration files

A single configuration_*.py file can define multiple config classes. If the rule is checking a property that belongs to one specific config class, do not accept the first matching class in the file. Resolve the modeling class's target config class first:

• Prefer config_class from the model class, following local modeling inheritance if a parent *PreTrainedModel declares it.
• If there is no explicit config_class, infer the best match from class names, usually by longest shared prefix.

Then validate only that config class.

Inherited configs

Some config classes inherit from another model config rather than directly from PreTrainedConfig. If the base class is not PreTrainedConfig or PretrainedConfig and still ends with Config, assume the field may be inherited and skip the violation unless the rule specifically needs stricter handling.

Modular imported bases

modular_*.py files commonly define classes that inherit from another model's imported class, and analyze_file only passes the AST for the file currently being linted. If a rule depends on inherited methods or a full base chain, an imported base is unknown, not evidence that the expected behavior is missing. Prefer resolving the generated modeling_*.py when the rule needs the flattened class, or skip/report nothing when _base_chain_has_unresolved_import(...) says the local AST is inconclusive. Always add a regression test with a modular_*.py class inheriting from an imported base.

tie_word_embeddings is not in PreTrainedConfig

The base PreTrainedConfig does not define tie_word_embeddings. When a rule needs it, the model config must declare it explicitly, either as a class attribute or through self.tie_word_embeddings = ... in initialization code.

Reference

• Rule modules: mlinter/trf*.py
• Rule config: mlinter/rules.toml
• Helpers: mlinter/_helpers.py
• Rule tests: tests/test_trfXXX.py
• Shared rule-test helpers: tests/rule_test_utils.py
• General linter tests: tests/test_mlinter.py
• README (repo front door + PyPI description): README.md
• Docs site source: docs/ — hand-written pages only; docs/rules/ is generated and git-ignored
• Rule page generator: scripts/build_docs.py