noqaexplain

Comply or explain - justify every ignored linting rule.

✨ Features 🚀 Quick start 📚 Documentation 🤝 Contribute 👍 Adopters 📜 Legal

Features

noqaexplain is a linter which enforces justifying every ignored linting rule supporting multiple formats/linters:

• Python -ruff and flake8 # noqa, coveragepy # pragma: no cover, and lintkit line, span, and file suppressions
• JavaScript/TypeScript - eslint
• Rust - clippy
• Dockerfiles - hadolint
• YAML - yamllint and lintkit line, span, and file suppressions
• TOML - lintkit line, span, and file suppressions
• Markdown - PyMarkdown, Vale, and md-dead-link-check
• Shell - shellcheck

[!IMPORTANT] You can expand this list with any language and linter by using extend_mapping_suffix and/or extend_mapping_name! Feel free to open a request to add support for more linters.

Table of contents

• Quick start
  • Installation
  • Usage
• Advanced
  • Configuration
  • Run as a pre-commit hook
  • Rules

Quick start

Installation

[!TIP] You can use your favorite package manager like uv, hatch or pdm instead of pip.

> pip install noqaexplain[all]

To install rich output and MCP server as well:

> pip install noqaexplain[all]

Usage

To check against all files (the ones with defined mappings from file extension to error disable comment format), run:

> noqaxplain check

You can pass additional arguments to noqaexplain check, like files to check:

> noqaexplain check path/to/file.py maybe.rs other.yml formats.js

If a certain file has a line with disabled check without an explanation, the tool will report it:

path/to/file.py:10:5: ENQ0 Missing explanation (enoqa) for disabled linting rule

to fix it, just add an explanation after the disable comment prefixed by enq:, e.g.:

import some_library

# enq: Disabled private access check as there is no other workaround currently.
# noqa: SLF001
some_library._private_function()

The same rule applies to opening span and file-wide lintkit directives:

# enq: Generated settings are checked separately before publication.
# noqa-file: MYLINTER1

# enq: This generated section cannot follow the repository style.
# noqa-start: MYLINTER2
generated = true
# noqa-end: MYLINTER2

Markdown suppressions use an HTML comment for the explanation:

<!-- enq: Generated content cannot satisfy the line length rule. -->
<!-- pyml disable-next-line line-length -->

Markdown matching uses the literal comment prefixes <!-- pyml, <!-- vale, and <!-- md-dead-link-check. Every matching comment needs an explanation.

Advanced

Configuration

You can configure noqaexplain in pyproject.toml (or .noqaexplain.toml in the root of your project, just remove the [tool.noqaexplain] section), for example:

[tool.noqaexplain]
# include rules by their complete, case-sensitive name
names = ["ENQ0"] # default: all rules included
# whether to exit after first error or all errors
end_mode = "first" # default: "all"

# Extends Python noqas mappings
# Now every # my_noqa_header: will be treated as a noqa comment
# and checked for explanations.
extend_mapping_suffix = {".py" = ["# my_noqa_header:"]}
# Target any MySuperFile.md file(s) and look for explanations
extend_mapping_name = {"MySuperFile.md" = ["# my_noqa_header:"]}

[!TIP] Rule-specific configuration can be found in the section below.

Run as a pre-commit hook

noqaexplain can be used as a pre-commit hook, to add as a plugin:

repos:
-   repo: "https://github.com/open-nudge/noqaexplain"
    rev: ...  # select the tag or revision you want, or run `pre-commit autoupdate`
    hooks:
    -   id: "noqaexplain"

Rules

[!TIP] Run noqaexplain rules to see the list of available rules.

noqaexplain provides the following rules:

and the following configurable options (in pyproject.toml or .noqaexplain.toml):

Contribute

We welcome your contributions! Start here:

• Code of Conduct
• Contributing Guide
• Roadmap
• Changelog
• Report security vulnerabilities
• Open an Issue

Legal

• This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
• This project is copyrighted by open-nudge - the appropriate copyright notice is included in each file.