Reports

The format-agnostic report model, the renderer contract and implementations, and the writer that emits rendered reports. See Report Format Reference for the user-facing shape of each format.

Base

Renderer contract for turning a Report into a string.

class markdown_checker.reports.base.ReportRenderer

Bases: ABC

Renders a Report into a string. Pure: no file or network I/O.

format_name: Literal['markdown', 'json', 'github-annotations', 'console']

Registry key and CLI value, e.g. “markdown”, “json

file_extension: str

Default file extension for this report format, including the dot, e.g. “.md”, “.json”.

abstractmethod render(report)

Return the complete report body as a string.

Parameters:

report (Report)

Return type:

str

Model

Format-agnostic report model.

Report (and the ReportIssue / FileReport / ReportContext types it is made of) is the single pivot between the check-running tool and report rendering: build_report() is the only place that converts tool-specific CheckResult data into this structure, and every renderer consumes only Report from here on.

class markdown_checker.reports.model.ReportIssue(link, line_number, file_path, message, level)

Bases: object

A single finding, decoupled from the runtime MarkdownLinkBase object.

Parameters:

• link (str)

• line_number (int)

• file_path (Path)

• message (str)

• level (Literal['error', 'warning'])

link: str

line_number: int

file_path: Path

message: str

level: Literal['error', 'warning']

class markdown_checker.reports.model.FileReport(file_path, errors=(), warnings=())

Bases: object

All findings for one file, pre-split by level.

Parameters:

• file_path (Path)

• errors (tuple[ReportIssue, ...])

• warnings (tuple[ReportIssue, ...])

file_path: Path

errors: tuple[ReportIssue, ...]

warnings: tuple[ReportIssue, ...]

class markdown_checker.reports.model.ReportContext(check_name, output_mode='local', repo_url=None, guide_url=None, tool_name='markdown-checker', tool_version='')

Bases: object

Run-level metadata that any renderer may use.

Parameters:

• check_name (str)

• output_mode (Literal['ci', 'local'])

• repo_url (str | None)

• guide_url (str | None)

• tool_name (str)

• tool_version (str)

check_name: str

output_mode: Literal['ci', 'local']

repo_url: str | None

guide_url: str | None

tool_name: str

tool_version: str

class markdown_checker.reports.model.Report(context, files=(), links_checked=0, files_checked=0)

Bases: object

A complete, format-agnostic report for a single check run.

Parameters:

• context (ReportContext)

• files (tuple[FileReport, ...])

• links_checked (int)

• files_checked (int)

context: ReportContext

files: tuple[FileReport, ...]

links_checked: int

files_checked: int

property error_count: int

Total number of error-level issues across all files.

property warning_count: int

Total number of warning-level issues across all files.

property has_errors: bool

True if any file has at least one error-level issue.

property has_warnings: bool

True if any file has at least one warning-level issue.

markdown_checker.reports.model.build_report(check_result, *, context, files_checked)

Convert checker output (CheckResult of MarkdownLinkBase issues) into the format-agnostic Report.

Parameters:

• check_result (CheckResult) – The result returned by run_check_on_files.

• context (ReportContext) – Run-level metadata to attach to the report.

• files_checked (int) – Total number of files that were checked.

Returns:

A Report with issues split into errors/warnings per file.

Return type:

Report

Registry

Registry mapping report format names to ReportRenderer implementations.

markdown_checker.reports.registry.RENDERERS: dict[Literal['markdown', 'json', 'github-annotations', 'console'], type[ReportRenderer]]

Maps the CLI --report-format argument value to the corresponding renderer class.

markdown_checker.reports.registry.get_renderer(format_name, **options)

Instantiate a renderer by name.

Parameters:

• format_name (Literal['markdown', 'json', 'github-annotations', 'console']) – One of the keys in RENDERERS.

• **options (object) – Constructor keyword arguments forwarded to the renderer class.

Raises:

ValueError – If format_name is not a registered renderer.

Return type:

ReportRenderer

Writer

Writes rendered report strings to a file or stdout.

markdown_checker.reports.writer.write_report(rendered, *, output_path)

Write a rendered report to output_path, or to stdout when output_path is None.

Parameters:

• rendered (str) – The rendered report body, as returned by a ReportRenderer.

• output_path (Path | None) – File path to write to, or None to write to stdout.

Return type:

None

Markdown Renderer

Renders a Report as a Markdown document with an HTML issues table.

This mirrors the original MarkdownGenerator output exactly: a per-check header template, an optional contributing-guide line, then a table of error-level issues only (warnings are not included in the Markdown report).

class markdown_checker.reports.renderers.markdown.MarkdownRenderer

Bases: ReportRenderer

Renders a Report as Markdown, matching the historical comment.md output.

format_name: Literal['markdown', 'json', 'github-annotations', 'console']

Registry key and CLI value, e.g. “markdown”, “json

file_extension: str

Default file extension for this report format, including the dot, e.g. “.md”, “.json”.

render(report)

Render the report’s error-level issues as a Markdown document.

Parameters:

report (Report)

Return type:

str

JSON Renderer

Renders a Report as machine-readable JSON.

class markdown_checker.reports.renderers.json.JsonRenderer(indent=2)

Bases: ReportRenderer

Renders a Report as a JSON document, including both errors and warnings.

Parameters:

indent (int)

format_name: Literal['markdown', 'json', 'github-annotations', 'console']

Registry key and CLI value, e.g. “markdown”, “json

file_extension: str

Default file extension for this report format, including the dot, e.g. “.md”, “.json”.

render(report)

Render the report (errors and warnings) as a JSON string.

Parameters:

report (Report)

Return type:

str

GitHub Annotations Renderer

Renders a Report as GitHub Actions workflow annotations (::error file=...,line=...::...).

class markdown_checker.reports.renderers.annotations.GitHubAnnotationsRenderer

Bases: ReportRenderer

Renders a Report as one GitHub Actions annotation per issue.

format_name: Literal['markdown', 'json', 'github-annotations', 'console']

Registry key and CLI value, e.g. “markdown”, “json

file_extension: str

Default file extension for this report format, including the dot, e.g. “.md”, “.json”.

render_lines(report)

Return (annotation_line, level) pairs, in file/issue order.

Parameters:

report (Report)

Return type:

list[tuple[str, Literal[‘error’, ‘warning’]]]

render(report)

Render every issue as a GitHub Actions annotation line.

Parameters:

report (Report)

Return type:

str

Console Renderer

Renders a Report as plain, human-readable console text (local/non-CI mode).

class markdown_checker.reports.renderers.console.ConsoleRenderer

Bases: ReportRenderer

Renders a Report as plain console text, one block per issue.

format_name: Literal['markdown', 'json', 'github-annotations', 'console']

Registry key and CLI value, e.g. “markdown”, “json

file_extension: str

Default file extension for this report format, including the dot, e.g. “.md”, “.json”.

render_lines(report)

Return (console_block, level) pairs, in file/issue order.

Parameters:

report (Report)

Return type:

list[tuple[str, Literal[‘error’, ‘warning’]]]

render(report)

Render every issue as a plain console text block.

Parameters:

report (Report)

Return type:

str