Module

linting.protocol

LintRule protocol — the single contract a rule author implements.

A rule is a stateless, pure object: it receives one immutable LintContextand yields Diagnosticobjects. Mirrors the RoleHandler/DirectiveHandler protocol style (@runtime_checkable, ClassVar metadata with per-attribute docstrings, ...method body, and Args/Returns/Thread Safety docstring sections).

Thread Safety:

Rules MUST be stateless. The same rule instance may be invoked concurrently
from multiple threads against different documents.
1Class

Classes

LintRule 3 ▼
Protocol for a single, stateless Markdown lint rule. Implement this protocol to add a custom rule.…
Bases: Protocol

Protocol for a single, stateless Markdown lint rule.

Implement this protocol to add a custom rule. A rule is pure: it receives an immutable LintContext (the parsed Document plus the raw source and a precomputed document-order node sequence) and yields Diagnostic objects. Rules never mutate the AST, the context, or any shared state, and they never see the runner.

AST-oriented rules read ctx.document / ctx.headings()/ ctx.nodes_of_type(...); line-oriented rules read ctx.lines. One method serves both: the rule reads whatever it needs.

Thread Safety: Rules MUST be stateless. All per-run state must live in local variables insidecheckor in the immutable LintContext. The same rule instance may be invoked concurrently from multiple threads against different documents.

Attributes

Name Type Description
rule_id ClassVar[str]

Unique, kebab-case rule identifier (e.g. "heading-increment"). Used as the registry key and stamped onto every Diagnostic this rule emits.
default_severity ClassVar[Severity]

Severity stamped onto Diagnostics this rule emits.

Methods

check 1 Iterable[Diagnostic] ▼
Inspect the document/source and yield diagnostics. Called exactly once per lin…
def check(self, ctx: LintContext) -> Iterable[Diagnostic]

Inspect the document/source and yield diagnostics.

Called exactly once per lint run. AST rules read ctx.document, ctx.headings() or ctx.nodes_of_type(...)(a precomputed, document-order node sequence — rules never subclass BaseVisitor and never depend on traversal-hook timing). Line-oriented rules read ctx.lines (source split on '\n').

Thread Safety: Must not modify any shared state. May be called concurrently.

Parameters
Name Type Description
ctx —

Immutable lint context carrying the parsed Document (ctx.document), the raw source (ctx.source / ctx.lines), ctx.source_file, and precomputed node accessors.
Returns
Iterable[Diagnostic] An iterable of Diagnostic (may be a generator). The runner stamps ``rule_id`` and ``severity`` from this rule, so a rule need not get those exactly right, but should set ``message`` and ``location``. AST rules should reuse a node's ``location``; line rules synthesize their own.