topmark.presentation.markdown.pipeline ¶

def render_pipeline_diffs_markdown(
    *,
    results: Sequence[ProcessingResult],
    show_line_numbers: bool = False,
) -> str:
    """Render standalone Markdown diff output for a pipeline command.

    This output is separate from the human per-file report. Commands use it for
    `--diff` stdout payloads while routing guidance and summaries through the
    regular human report path.

    Args:
        results: Durable processing results to inspect for retained diffs.
        show_line_numbers: Whether to prepend line numbers.

    Returns:
        Markdown diff output, or an empty string when no diff is available.
    """
    return _render_pipeline_diffs_markdown(
        results=results,
        show_line_numbers=show_line_numbers,
    )

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[[ProcessingResult], str | None] | None = None
    if report.pipeline_kind == "check":
        make_message = _render_check_guidance_message_markdown
    elif report.pipeline_kind == "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(
            pipeline_kind=report.pipeline_kind,
            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(
                results=report.view_results,
                make_message=make_message,
                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)

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)