all2md.linter.runner

Lint runner — orchestrates rules against an all2md AST Document.

The runner owns three responsibilities:

Instantiate the rules allowed by the config and run each one against the document.
Catch any exception a rule raises so a single broken rule cannot kill the whole run. Such failures surface as an INTERNAL-ERROR violation.
Apply the severity threshold and sort the resulting violations into a stable, reportable order.

When --fix is requested, LintRunner.lint_and_fix_document() runs the lint pass, applies attached fixes via all2md.linter.fixes.apply_fixes(), and re-lints the mutated AST so reporters can show “fixed N, M remaining”. lint_and_fix_file() additionally serialises the mutated AST back to disk via the markdown renderer.

Top-level convenience wrappers lint_document and lint_file are exposed via the all2md.linter package.

class all2md.linter.runner.LintResult

Bases: object

Result of linting a single document.

file_path: str | None

violations: list[Violation]

rules_checked: int = 0

property error_count: int: Return the number of ERROR-severity violations.

property warning_count: int: Return the number of WARNING-severity violations.

property info_count: int: Return the number of INFO-severity violations.

property total: int: Return the total number of violations in this result.

__init__(file_path: str | None, violations: list[Violation] = <factory>, rules_checked: int = 0) → None

class all2md.linter.runner.LintFixResult

Bases: object

Result of running lint --fix against a single document.

Carries both the pre-fix and post-fix lint results so reporters can show “applied N fixes, M remaining” without recomputing.

file_path: str | None

initial: LintResult

final: LintResult

applied: list[AppliedFix]

skipped_conflicts: list[AppliedFix]

rewritten: bool = False

property violations: list[Violation]: Post-fix violations — the ones the user still needs to address.

property rules_checked: int: Forward to the post-fix lint result.

property error_count: int: Forward to the post-fix lint result.

property warning_count: int: Forward to the post-fix lint result.

property info_count: int: Forward to the post-fix lint result.

property total: int: Forward to the post-fix lint result.

__init__(file_path: str | None, initial: LintResult, final: LintResult, applied: list[AppliedFix] = <factory>, skipped_conflicts: list[AppliedFix] = <factory>, rewritten: bool = False) → None

class all2md.linter.runner.LintRunner

Bases: object

Run a LintConfig over one or more documents.

Initialise the runner with a config and a registry.

Either argument can be omitted; defaults are a blank LintConfig and the global rule_registry.

__init__(config: LintConfig | None = None, registry: RuleRegistry | None = None) → None

Initialise the runner with a config and a registry.

Either argument can be omitted; defaults are a blank LintConfig and the global rule_registry.

lint_document(doc: Document, file_path: str | None = None) → LintResult: Run all enabled rules against doc and return a LintResult.

lint_file(file_path: str | Path) → LintResult: Parse file_path to an AST and lint it.

lint_files(file_paths: list[str | Path]) → list[LintResult]: Run lint_file() against every path in the list.

lint_and_fix_document(doc: Document, *, file_path: str | None = None, max_safety: FixSafety = FixSafety.SAFE, max_passes: int = 5) → LintFixResult

Lint doc, apply attached fixes (in place) to fixpoint, re-lint.

When two fixes target the same node, apply_fixes() skips the later one — so a single pass may leave correctable violations untouched. The runner re-runs the lint+fix cycle until no fixes apply (or max_passes is reached), which converts the per-call “first-wins” policy into “run to fixpoint” at the user level.

max_passes is a safety cap that surfaces non-idempotent fixes (the loop would otherwise oscillate forever). Five passes is plenty for the v2.0 SAFE fixes — the deepest natural cascade is TYP001 → TYP002 on the same node, which converges in two.

The document is mutated in place. Callers that need to write the result back to disk should serialise via the markdown renderer when LintFixResult.rewritten is true.

lint_and_fix_file(file_path: str | Path, *, max_safety: FixSafety = FixSafety.SAFE, write: bool = True) → LintFixResult

Parse file_path, lint+fix, and (optionally) rewrite the file.

When write=True (the default) and at least one fix was applied, the mutated AST is serialised back to file_path via all2md.renderers.markdown.MarkdownRenderer. A clean file (no fixes applied) is never rewritten, sidestepping spurious renderer-canonicalisation drift.

all2md.linter.runner.lint_document(doc: Document, config: LintConfig | None = None, file_path: str | None = None) → LintResult: Lint an already-parsed Document.

all2md.linter.runner.lint_file(file_path: str | Path, config: LintConfig | None = None) → LintResult: Parse file_path into an AST and lint it with config.

all2md.linter.runner.lint_and_fix_document(doc: Document, config: LintConfig | None = None, *, file_path: str | None = None, max_safety: FixSafety = FixSafety.SAFE) → LintFixResult: Lint and fix doc in place; re-lint and return the combined result.

all2md.linter.runner.lint_and_fix_file(file_path: str | Path, config: LintConfig | None = None, *, max_safety: FixSafety = FixSafety.SAFE, write: bool = True) → LintFixResult: Parse, lint+fix, and rewrite file_path.