Linting & Formatting Toolchain

Relevant source files

The following files were used as context for generating this wiki page:

• tasks.py
• README.md
• AGENTS.md
• pyproject.toml
• dev/guidelines/python.md
• dev/guidelines/documentation.md
• dev/guidelines/git-workflow.md

The linting and formatting toolchain ensures code quality, consistency, and adherence to project standards across Python, YAML, and Markdown files. It serves as a mandatory quality gate for contributors, requiring all checks to pass before code is merged into the protected stable branch. The toolchain integrates multiple specialized linters and formatters, including Ruff for Python, Rumdl for Markdown, and Ty for type checking.

Contributors use invoke tasks to execute these tools locally, which mirrors the automated checks performed in the GitHub Actions CI pipeline. This system prevents technical debt and maintains a professional codebase by enforcing rules on code complexity, style, and documentation structure.

Sources: AGENTS.md:58-65, dev/guidelines/git-workflow.md:15-28, dev/guidelines/python.md:9-15

Toolchain Architecture and Components

The toolchain is organized into two primary categories: formatting (which modifies files to match style rules) and linting (which checks for errors or violations without modifying code).

Core Components Table

Category	Tool	Scope	Description
Formatting	Ruff	Python	Handles auto-formatting and import sorting (isort).
Formatting	Rumdl	Markdown	Formats .md and .mdx files.
Linting	Ruff	Python	Performs fast linting for style and logical errors.
Linting	Pylint	Python	Conducts deep static analysis of Python code.
Linting	Ty	Python	Checks static type annotations using ty.
Linting	Yamllint	YAML	Validates YAML syntax and style.
Linting	Rumdl	Markdown	Validates Markdown structure and formatting.
Linting	Vale	Prose	Checks prose style and spelling in documentation.

Sources: tasks.py:16-72, pyproject.toml:50-65, dev/guidelines/python.md:16-24, dev/guidelines/documentation.md:68-83

Execution Flow

The following diagram illustrates how the invoke tasks orchestrate different tools during a full quality check.

This flow ensures that formatting occurs before final linting to avoid style-related lint failures.

Sources: tasks.py:19-72, dev/guidelines/git-workflow.md:17-21

Python Toolchain Configuration

Python quality is managed primarily through Ruff, Pylint, and Ty. Configuration for these tools resides in pyproject.toml.

Ruff and Pylint

Ruff is configured with a line length of 120 characters and uses double quotes. It enables multiple rule families, including Flake8-bugbear, Flake8-async, and Pylint-specific rules. Pylint is used for more intensive checks but has certain rules disabled to avoid conflicts with Ruff or to accommodate Pydantic v2 models.

Sources: pyproject.toml:98-170, dev/guidelines/python.md:20-25

Type Checking (Ty)

The project uses ty for static type checking. Public functions and parameters must carry type hints. Some rules are relaxed in pyproject.toml to handle dynamic types within the Infrahub SDK, such as unresolved-import and possibly-missing-attribute.

Sources: pyproject.toml:88-92, dev/guidelines/python.md:32-37

Documentation and Markdown Linting

Documentation quality involves structural checks and prose analysis.

Rumdl and Vale

Rumdl replaces markdownlint for checking Markdown files. It is configured to ignore specific rules like MD013 (line length) for tables and MD033 (inline HTML) for Docusaurus/MDX compatibility. Vale is used specifically for prose style, applying Infrahub style rules defined in .vale/styles/.

@task(name="lint_markdown")
def lint_markdown(context: Context):
    """Run rumdl to check all Markdown files."""
    print(" - Check Markdown with rumdl")
    exec_cmd = "rumdl check ."
    with context.cd(MAIN_DIRECTORY_PATH):
        context.run(exec_cmd)

Sources: tasks.py:59-65, pyproject.toml:172-205, dev/guidelines/documentation.md:68-83

Integration with Development Workflow

The toolchain is integrated into the daily development cycle through local tasks and CI gates.

1. Local Execution: Developers run invoke format then invoke lint before committing code.
2. Pre-commit Hooks: A .pre-commit-config.yaml file (referenced in documentation) wires fast checks like Ruff and Rumdl into the Git workflow.
3. CI Pipeline: The GitHub Actions CI workflow (.github/workflows/ci.yml) runs the identical linting suite on every Pull Request.
4. Enforcement: Constitution guidelines prohibit weakening or disabling lint/type gates to pass CI. Any suppression must be narrow (e.g., # noqa) and justified.

Sources: AGENTS.md:58-65, dev/guidelines/git-workflow.md:24-28, 62-72

Summary

The nornir-infrahub toolchain provides a multi-layered defense against code quality degradation. By combining formatting tools like Ruff and Rumdl with rigorous linters like Pylint and Ty, the project maintains high standards for both code logic and documentation. The orchestration of these tools via invoke tasks ensures that local development environments match the enforcement levels of the central CI pipeline.