Rules
mlinter ships 56 rules, 54 of them enabled by default. Every rule is static: it reads the file’s syntax tree and never imports or runs the model code.
Rules whose scope names a date only apply to models contributed to Transformers on or after it — existing models are grandfathered so a new convention does not retroactively fail the whole library. Individual models can also be exempted; each rule page lists its own exemptions.
| Code | What it checks | Default | Scope |
|---|---|---|---|
| TRF001 | Class-level config_class on <Model>PreTrainedModel should match <Model>Config naming. | Enabled | All models |
| TRF002 | base_model_prefix should be a non-empty canonical string when defined on PreTrainedModel classes. | Enabled | All models |
| TRF003 | forward() should use capture_output/can_return_tuple decorators instead of manual return_dict branching. | Disabled | All models |
| TRF004 | Models must never override tie_weights. Use _tied_weights_keys instead. | Enabled | All models |
| TRF005 | _no_split_modules, when defined, should be a list/tuple of non-empty strings. | Enabled | All models |
| TRF006 | forward with cache arguments should reference cache control/state variables consistently. | Enabled | All models |
| TRF007 | self.post_init() in __init__ should remain at the end of initialization for PreTrainedModel classes. | Enabled | All models |
| TRF008 | Doc decorators on PreTrainedModel classes should avoid empty add_start_docstrings usage. | Enabled | All models |
| TRF009 | modeling_<name>.py should avoid importing implementation code from another model package. | Enabled | All models |
| TRF010 | Direct config definitions must use @strict(accept_kwargs=True). | Enabled | All models |
| TRF011 | forward() must not access non-nn.Module attributes on submodules (breaks pipeline parallelism with Identity replacement). | Enabled | All models |
| TRF012 | _init_weights must use init primitives, not in-place operations on module weights. | Enabled | All models |
| TRF013 | PreTrainedModel __init__ must call self.post_init(). | Enabled | All models |
| TRF014 | trust_remote_code should never be used in native model integrations. |
Enabled | All models |
| TRF015 | Models with non-empty _tied_weights_keys must have tie_word_embeddings in their Config. | Enabled | All models |
| TRF016 | do_* flags declared on a processor class must be referenced by overridden preprocess/_preprocess. | Enabled | All models |
| TRF017 | @auto_docstring must be placed above @dataclass on output classes. | Enabled | All models |
| TRF018 | _init_weights overrides should call super()._init_weights(module), except modular-file sentinels. | Enabled | All models |
| TRF019 | A processor TypedDict class must not define _defaults, instead push them upstream to the hub (processor_config.json). |
Enabled | 2026-06-20 |
| TRF020 | MLA models must isolate the KV LoRA expansion (kv_b_proj) in a dedicated method that forward() calls. | Enabled | All models |
| TRF021 | Scalar tensors must be filled on-device with torch.full((), …) instead of torch.tensor(…, device=…). | Enabled | All models |
| TRF022 | _no_split_modules entries must name module classes that exist in the model. | Enabled | All models |
| TRF023 | Config fields must use canonical dimension names (hidden_size, intermediate_size, num_attention_heads, …). | Enabled | 2026-06-20 |
| TRF024 | Layer dimensions must come from the config, not from an integer literal in the modeling file. | Enabled | 2026-06-20 |
| TRF025 | Attention masks must be built once in the model, not rebuilt inside a layer or attention module. | Enabled | 2026-06-20 |
| TRF026 | A module whose forward only delegates to its single submodule adds nothing; inline it. | Enabled | 2026-06-20 |
| TRF027 | Model files must raise explicit errors instead of using bare assert. |
Enabled | 2026-06-20 |
| TRF028 | Model files must carry a complete license header. | Enabled | 2026-06-20 |
| TRF029 | A module taking config must not also take arguments that live on the config. |
Enabled | 2026-06-20 |
| TRF030 | Reaching more than two levels into the config means the module was handed the wrong config. | Enabled | 2026-06-20 |
| TRF031 | Dataclasses in modeling files must inherit ModelOutput. | Enabled | 2026-06-20 |
| TRF032 | Masked positions must be filled with torch.finfo(dtype).min, not a magic negative number. | Enabled | 2026-06-20 |
| TRF033 | Hyperparameters must be set on the config, not mutated through a set_* method. | Enabled | 2026-06-20 |
| TRF034 | Layer classes held in an nn.ModuleList must subclass GradientCheckpointingLayer. | Enabled | 2026-06-20 |
| TRF035 | Model files must not silence the linter with # noqa. |
Enabled | 2026-06-20 |
| TRF036 | nn.Sequential hides the forward flow; declare the submodules explicitly. | Enabled | 2026-06-20 |
| TRF037 | torch.einsum is hard to read; prefer explicit matmul/transpose operations. | Disabled | 2026-06-20 |
| TRF038 | Every modeling-family source file needs a matching test file under tests/models/. | Enabled | All models |
| TRF039 | Imports guarded by is_*_available() must be removed once nothing in the file uses them. | Enabled | All models |
| TRF040 | @can_return_tuple must not be combined with @capture_outputs. | Enabled | All models |
| TRF041 | A config-gated branch must carry a # CODEPATH: note saying which checkpoints diverge. |
Enabled | 2026-06-20 |
| TRF042 | A tokenizer test must exercise the shared TokenizerTesterMixin suite. | Enabled | 2026-06-20 |
| TRF043 | Attention classes must not declare position_ids in their forward signature; it flows via **kwargs. | Enabled | All models |
| TRF044 | cache_position must not appear as a parameter in modeling code; it is removed framework surface. | Enabled | All models |
| TRF045 | forward must not declare output_attentions/output_hidden_states/return_dict; decorators own them. | Enabled | 2026-06-20 |
| TRF046 | forward must not write module attributes; modules are stateless in forward. | Enabled | All models |
| TRF047 | Image/video processors are stateless: preprocess/_preprocess/post_process_* must not write self attributes. | Enabled | All models |
| TRF048 | _tied_weights_keys must be a dict mapping target to source, not the pre-v5 list form. | Enabled | All models |
| TRF049 | Weight initialization belongs in _init_weights, never in __init__ (meta-device init discards it). | Enabled | All models |
| TRF050 | One rotary module per model: attention classes must not instantiate their own rotary embedding. | Enabled | All models |
| TRF051 | Modeling code must not branch on _attn_implementation; the attention interface owns dispatch. | Enabled | All models |
| TRF052 | No *_ATTENTION_CLASSES dispatch dicts; attention backends route through the attention interface. | Enabled | All models |
| TRF053 | No manual label shifting in modeling code; self.loss_function owns it. | Enabled | All models |
| TRF055 | config on a PreTrainedModel subclass must be an annotation (config: SomeConfig), not an assignment (config = SomeConfig). |
Enabled | All models |
| TRF056 | forward() must not materialize tensors with .item() or .tolist(). | Enabled | 2026-06-20 |
| TRF057 | Public model, config, output and processor classes and their public methods must be decorated with @auto_docstring. | Enabled | 2026-06-20 |
Removed rules
1 rule has been retired. It no longer runs, it is not included in the count above, and its number is never reused. A leftover # trf-ignore comment naming one is harmless.
| Code | Why it was removed |
|---|---|
| TRF054 | Removed in 0.1.4: flagged self.<media>_token_id assignments in processor __init__, too noisy on legitimate processor code. |