Format a hygiene report for Markdown review

By Batu · English technical notes

Also published in our Blogger archive.

Direct answer

A Markdown hygiene report should not hide all meaning in one score. Each row here carries a stable identifier, a status, and a short detail, while a separate Limits heading states the scope. Constructing a list of lines avoids accidental spacing changes and gives reviewers a predictable order.

The edge case is a formatter that omits its limits section during a visual cleanup. The final assertion checks the exact ending, so the filename-only boundary cannot disappear while the check rows still look healthy. The output remains readable in a pull request without asking a reader to infer the scanner’s assumptions.

This example formats trusted synthetic fields only. It does not escape arbitrary Markdown, wrap long error messages, or decide how warnings affect a release. Escape values before rendering if filenames or details can contain Markdown control characters. The formatting contract is intentionally narrower than a full reporting system.

Complete example

from dataclasses import dataclass


@dataclass(frozen=True)
class Check:
    identifier: str
    status: str
    detail: str


checks = [
    Check("root-readme", "pass", "README.md found"),
    Check("env-files", "warn", "names only"),
]
lines = ["# Hygiene report", ""]
lines.extend(
    f"- `{check.identifier}`: **{check.status}** — {check.detail}"
    for check in checks
)
lines.extend(["", "## Limits", "- Filenames only"])
report = "\n".join(lines) + "\n"
assert "`root-readme`: **pass**" in report
assert report.endswith("- Filenames only\n")
print(report, end="")

Expected stdout:

# Hygiene report

- `root-readme`: **pass** — README.md found
- `env-files`: **warn** — names only

## Limits
- Filenames only

Sources

- Official API documentation

Prepared with AI assistance. The example uses synthetic data; its stated limits apply.