topmark.presentation.markdown.pipeline

topmark / presentation / markdown / pipeline

Markdown pipeline renderers for the TopMark CLI.

This module renders human-facing Markdown output for pipeline-oriented commands such as topmark check and topmark strip.

Markdown output is document-oriented: it intentionally ignores TEXT-only verbosity, quiet, and styling controls. Pipeline content is controlled by semantic command options such as --summary, --report, and --diff.

Notes

• TEXT pipeline output is implemented in topmark.presentation.text.pipeline.
• Machine-readable output is handled via domain machine serializers.

render_pipeline_output_markdown

render_pipeline_output_markdown(report)

Render human-facing Markdown output for a pipeline command.

Parameters:

Name	Type	Description	Default
report	PipelineCommandHumanReport	Prepared human report for the pipeline command.	required

Returns:

Type	Description
str	Rendered Markdown output.

Raises:

Type	Description
RuntimeError	If an invalid pipeline kind was selected.

Source code in src/topmark/presentation/markdown/pipeline.py

def render_pipeline_output_markdown(
    report: PipelineCommandHumanReport,
) -> str:
    """Render human-facing Markdown output for a pipeline command.

    Args:
        report: Prepared human report for the pipeline command.

    Returns:
        Rendered Markdown output.

    Raises:
        RuntimeError: If an invalid pipeline kind was selected.
    """
    make_message: Callable[[ProcessingContext, bool], str | None] | None = None
    if report.pipeline_kind == CliCmd.CHECK:
        make_message = _render_check_guidance_message_markdown
    elif report.pipeline_kind == CliCmd.STRIP:
        make_message = _render_strip_guidance_message_markdown
    else:
        # Defensive guard.
        raise RuntimeError(f"Invalid pipeline kind selected: {report.pipeline_kind}")

    parts: list[str] = []

    # Markdown always starts with a document banner.
    parts.append(
        _render_pipeline_banner_markdown(
            cmd=report.cmd,
            n_files=report.file_list_total,
        )
    )
    parts.append("")

    # Summary mode (grouped by `(outcome, reason)`).
    if report.summary_mode:
        if report.show_diffs:
            parts.append(
                _render_pipeline_diffs_markdown(
                    results=report.view_results,
                )
            )
        parts.append(
            _render_summary_counts_markdown(
                view_results=report.view_results,
                total=report.file_list_total,
            )
        )
    else:
        # Per-file guidance
        parts.append(
            _render_per_file_guidance_markdown(
                view_results=report.view_results,
                make_message=make_message,
                apply_changes=report.apply_changes,
                show_diffs=report.show_diffs,
            ),
        )

    # In actionable mode, unsupported files are hidden from the per-file listing but summarized
    # for visibility.
    if (
        (not report.summary_mode)
        and (report.report_scope == ReportScope.ACTIONABLE)
        and (report.unsupported_count > 0)
    ):
        parts.append(
            f"\n> ⚠️ Unsupported: {report.unsupported_count} file(s) "
            f"(use {CliOpt.REPORT}={ReportScope.NONCOMPLIANT.value} to list)\n"
        )

    return "\n".join(parts)

render_pipeline_apply_summary_markdown

render_pipeline_apply_summary_markdown(
    *, command_path, written, failed
)

Render the apply-summary footer for Markdown output.

Parameters:

Name	Type	Description	Default
command_path	str	Command path, such as topmark check.	required
written	int	Number of files written.	required
failed	int	Number of files that failed to write.	required

Returns:

Type	Description
str	Rendered Markdown footer.

Source code in src/topmark/presentation/markdown/pipeline.py

def render_pipeline_apply_summary_markdown(
    *,
    command_path: str,
    written: int,
    failed: int,
) -> str:
    """Render the apply-summary footer for Markdown output.

    Args:
        command_path: Command path, such as `topmark check`.
        written: Number of files written.
        failed: Number of files that failed to write.

    Returns:
        Rendered Markdown footer.
    """
    parts: list[str] = []
    cmd_md: str = markdown_code_span(command_path)
    if written:
        parts.append(f"\n✅ {cmd_md}: applied changes to **{written}** file(s).\n")
    else:
        parts.append(f"\n✅ {cmd_md}: no changes to apply.\n")
    if failed:
        parts.append(
            f"\n> ⚠️ {cmd_md}: failed to write **{failed}** file(s). See log for details.\n"
        )

    return "\n".join(parts)