# protocol

URL: /patitas/api/linting/protocol/
Section: linting
Description: LintRule protocol — the single contract a rule author implements.

A rule is a stateless, pure object: it receives one immutable
`LintContext` and yields
`Diagnostic` objects. 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.

---

> For a complete page index, fetch /patitas/llms.txt.

Open LLM text
(/patitas/api/linting/protocol/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Flinting%2Fprotocol%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Flinting%2Fprotocol%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Flinting%2Fprotocol%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Flinting%2Fprotocol%2Findex.txt)

Module

#
`linting.protocol`

LintRule protocol — the single contract a rule author implements.

A rule is a stateless, pure object: it receives one immutable
`LintContext`and yields
`Diagnostic`objects. 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` (/patitas/api/linting/context/#LintContext) (the parsed Document plus
the raw source and a precomputed document-order node sequence) and
yields `Diagnostic` (/patitas/api/linting/diagnostic/#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` (/patitas/api/linting/context/#LintContext) / `ctx.headings()`/
`ctx.nodes_of_type(...)`; line-oriented rules read `ctx.lines` (/patitas/api/linting/context/#LintContext).
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 inside`check`or 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 (/patitas/api/linting/diagnostic/#Severity)]`

Severity stamped onto Diagnostics this rule emits.

#### Methods

`check`

1

`Iterable[Diagnostic (/patitas/api/linting/diagnostic/#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` (/patitas/api/linting/context/#LintContext),
`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` (/patitas/api/linting/context/#LintContext) (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 (/patitas/api/linting/diagnostic/#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.