repomatic.broken_links module

Broken links detection and reporting.

Combines Lychee and Sphinx linkcheck results into a single “Broken links” GitHub issue. Sphinx linkcheck parsing detects broken auto-generated links (intersphinx, autodoc, type annotations) that Lychee cannot see because they only exist in the rendered HTML output.

Issue lifecycle management is delegated to issue.

repomatic.broken_links.ISSUE_TITLE = 'Broken links'

Issue title used for the combined broken links report.

repomatic.broken_links.LYCHEE_BROKEN_LINKS_EXIT = 2

The one lychee exit code that reports on the links rather than on the run.

Lychee exits 0 on success, 1 on an unexpected failure, 2 when it found broken links, and 3 on a config error. Only 2 is a verdict about the links; 1 and 3 say the run itself did not complete, so neither “broken links found” nor “no broken links” can be claimed from them.

repomatic.broken_links.LYCHEE_DEFAULT_BODY = PosixPath('lychee/out.md')

Default output path used by the lychee-action GitHub Action.

repomatic.broken_links.SPHINX_DEFAULT_OUTPUT = PosixPath('docs/_linkcheck/output.json')

Default Sphinx linkcheck output path produced by the docs.yaml workflow.

class repomatic.broken_links.LinkcheckResult(filename, lineno, status, code, uri, info)

Bases: object

A single result entry from Sphinx linkcheck output.json.

Each line in the JSON-lines file corresponds to one checked URI.

filename: str

lineno: int

status: str

code: int

uri: str

info: str

repomatic.broken_links.parse_output_json(output_json)

Parse the Sphinx linkcheck output.json file.

The file uses JSON-lines format: one JSON object per line. Blank lines are skipped.

Parameters:

output_json (Path) – Path to the output.json file.

Return type:

list[LinkcheckResult]

Returns:

List of parsed linkcheck results.

repomatic.broken_links.filter_broken(results)

Filter results to only broken and timed-out links.

Parameters:

results (Iterable[LinkcheckResult]) – Iterable of linkcheck results.

Return type:

list[LinkcheckResult]

Returns:

List of results with status of "broken" or "timeout".

repomatic.broken_links.generate_markdown_report(broken, source_url=None)

Generate a Markdown report of broken links grouped by source file.

The report starts with H2 file headings, suitable for embedding as a section in the combined broken links issue body.

Parameters:

• broken (list[LinkcheckResult]) – List of broken linkcheck results.

• source_url (str | None) – Base URL for linking filenames and line numbers. When provided, file headers become clickable links and line numbers deep-link to the specific line.

Return type:

str

Returns:

Markdown-formatted report string.

repomatic.broken_links.get_label(repo_name)

Return the appropriate label based on repository name.

Parameters:

repo_name (str) – The repository name.

Return type:

str

Returns:

"🩹 fix link" for awesome-* repos, else "📚 documentation".

repomatic.broken_links.manage_combined_broken_links_issue(repo_name=None, lychee_exit_code=None, lychee_body_file=None, sphinx_output_json=None, sphinx_source_url=None)

Manage the combined broken links issue lifecycle.

Combines results from Lychee and Sphinx linkcheck into a single “Broken links” issue. Each tool’s results appear under its own heading. Tools that were not run are omitted from the report. Tools that found no broken links show a “No broken links found.” message.

When running in GitHub Actions, most parameters are auto-detected from Metadata and well-known file paths:

• repo_name defaults to Metadata.repo_name.

• lychee_body_file defaults to ./lychee/out.md when lychee_exit_code is provided and the file exists.

• sphinx_output_json defaults to ./docs/_linkcheck/output.json when the file exists.

• sphinx_source_url is composed from Metadata.repo_url and Metadata.sha.

Parameters:

• repo_name (str | None) – Repository name (for label selection). Defaults to Metadata.repo_name.

• lychee_exit_code (int | None) – Exit code from lychee (0=no broken links, 2=broken links found). None if lychee was not run.

• lychee_body_file (Path | None) – Path to the lychee output file. Defaults to ./lychee/out.md when lychee_exit_code is provided and the file exists.

• sphinx_output_json (Path | None) – Path to Sphinx linkcheck output.json. Defaults to ./docs/_linkcheck/output.json when the file exists.

• sphinx_source_url (str | None) – Base URL for linking filenames and line numbers in the Sphinx report. Auto-composed from Metadata.repo_url and Metadata.sha.

Raises:

ValueError – If repo_name cannot be determined.

Return type:

None