# runner

URL: /patitas/api/linting/runner/
Section: linting
Description: The lint() entrypoint and the Linter class.

`lint`() is the headline function (symmetric with ``parse``/``render``). It
accepts a ``str`` (parsed internally, capturing the source for line rules) OR a
pre-parsed `Document` (with the raw source supplied via the
keyword-only ``text`` parameter). One `LintContext`
is built and fed to each rule's ``check`` once; the runner STAMPS each
diagnostic's ``rule_id`` and ``severity`` from the emitting rule, then returns a
deterministically sorted list.

Thread Safety:
    No module-level mutable state. The only mutable state is the per-call
    accumulator list and the per-construction ``_NodeCollector`` inside the
    context — both created fresh per call. A single `Linter` (immutable
    registry on ``__slots__``) is safe to share across threads.

---

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

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

Share with AI

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

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

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

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

Module

#
`linting.runner`

The lint() entrypoint and the Linter class.

`lint`() is the headline function (symmetric with `parse`/`render`). It
accepts a`str`(parsed internally, capturing the source for line rules) OR a
pre-parsed`Document`(with the raw source supplied via the
keyword-only`text` parameter). One `LintContext`
is built and fed to each rule's`check`once; the runner STAMPS each
diagnostic's`rule_id` and `severity`from the emitting rule, then returns a
deterministically sorted list.

Thread Safety:

```
No module-level mutable state. The only mutable state is the per-call
accumulator list and the per-construction ``_NodeCollector`` inside the
context — both created fresh per call. A single `Linter` (immutable
registry on ``__slots__``) is safe to share across threads.
```

1Class3Functions

## Classes

`Linter`

2

▼

Reusable linter bound to an immutable rule registry.

Use this to lint many documents with a fixed …

Reusable linter bound to an immutable rule registry.

Use this to lint many documents with a fixed rule set. The registry is held
immutably on`__slots__`; each `lint`() call builds its own context
and accumulator, so one `Linter` (/patitas/api/linting/runner/#Linter) is safe to share across threads.

#### Methods

`lint`

3

`list[Diagnostic (/patitas/api/linting/diagnostic/#Diagnostic)]`

▼

Lint Markdown using this linter's registry.

Same polymorphic signature as the …

`def lint(self, source: str | Document, *, text: str = '', source_file: str | None = None) -> list[Diagnostic]`

Lint Markdown using this linter's registry.

Same polymorphic signature as the top-level`lint`(), minus the
`rules`argument (the registry is fixed at construction).

##### Parameters

Name
Type
Description

`source`
`—`

Markdown source string, or a pre-parsed`Document`.

`text`
`—`

Raw source for a pre-parsed`Document` (see :func:`lint`).

Default:`''`

`source_file`
`—`

Optional source file path.

Default:`None`

##### Returns

`list[Diagnostic (/patitas/api/linting/diagnostic/#Diagnostic)]`

A sorted list of :class:`Diagnostic`.

Internal Methods
1

▼

`__init__`

1

▼

Initialize with a registry (the default starter rules if None).

`def __init__(self, registry: LintRuleRegistry | None = None) -> None`

##### Parameters

Name
Type
Description

`registry`
`—`

An immutable :class:`LintRuleRegistry`. Defaults to :func:`create_default_lint_registry`.

Default:`None`

## Functions

`_resolve_rules`

1

`tuple[LintRule (/patitas/api/linting/protocol/#LintRule), ...]`

▼

Normalize the ``rules`` argument to a tuple of rules in order.

`def _resolve_rules(rules: Sequence[LintRule] | LintRuleRegistry | None) -> tuple[LintRule, ...]`

##### Parameters

Name
Type
Description

`rules`
`Sequence[LintRule (/patitas/api/linting/protocol/#LintRule)] | LintRuleRegistry (/patitas/api/linting/registry/#LintRuleRegistry) | None`

##### Returns

`tuple[LintRule (/patitas/api/linting/protocol/#LintRule), ...]`

`_run`

2

`list[Diagnostic (/patitas/api/linting/diagnostic/#Diagnostic)]`

▼

Run rules over a context, stamping id/severity, sorted for determinism.

`def _run(ctx: LintContext, rules: tuple[LintRule, ...]) -> list[Diagnostic]`

##### Parameters

Name
Type
Description

`ctx`
`LintContext (/patitas/api/linting/context/#LintContext)`

`rules`
`tuple[LintRule (/patitas/api/linting/protocol/#LintRule), ...]`

##### Returns

`list[Diagnostic (/patitas/api/linting/diagnostic/#Diagnostic)]`

`lint`

4

`list[Diagnostic (/patitas/api/linting/diagnostic/#Diagnostic)]`

▼

Lint Markdown and return a list of diagnostics.

Pass a ``str`` for the trivial…

`def lint(source: str | Document, *, text: str = '', source_file: str | None = None, rules: Sequence[LintRule] | LintRuleRegistry | None = None) -> list[Diagnostic]`

Lint Markdown and return a list of diagnostics.

Pass a`str`for the trivial path: it is parsed internally and the same
string is used as the raw source for line-oriented rules, so all rules run
with zero ceremony. Pass a pre-parsed `Document` (/patitas/api/nodes/#Document) for
the power path, supplying the raw source via`text=`so source-driven
rules (e.g. trailing-whitespace) are not silently skipped.

##### Parameters

Name
Type
Description

`source`
`str | Document (/patitas/api/nodes/#Document)`

Markdown source string, or a pre-parsed`Document`.

`text`
`str`

Raw source for a pre-parsed`Document`. Ignored when `source` is a `str`. If omitted for a `Document`, source-driven rules have no input and emit nothing (AST rules still run).

Default:`''`

`source_file`
`str | None`

Optional source file path; flows into the parse and into synthesized diagnostic locations.

Default:`None`

`rules`
`Sequence[LintRule (/patitas/api/linting/protocol/#LintRule)] | LintRuleRegistry (/patitas/api/linting/registry/#LintRuleRegistry) | None`

An explicit`Sequence[LintRule]` (used in order), a :class:`LintRuleRegistry` (uses `registry.rules`), or None (the three built-in starter rules).

Default:`None`

##### Returns

`list[Diagnostic (/patitas/api/linting/diagnostic/#Diagnostic)]`