topmark.presentation.shared.pipeline¶

topmark / presentation / shared / pipeline

Shared pipeline presentation models and utilities (Click-free).

This module defines the presentation payload shared by human-facing pipeline renderers for topmark check and topmark strip.

Scope

Provide immutable report models consumed by TEXT and Markdown renderers.
Centralize small display helpers that must remain consistent across human formats.
Avoid Click, console, and I/O dependencies; callers are responsible for building reports, rendering strings, and printing output.

TEXT renderers may use verbosity_level and styled for console-oriented progressive disclosure. Markdown renderers treat Markdown as document-oriented output and ignore TEXT-only verbosity and styling controls.

ProbeCommandHumanReport `dataclass` ¶

ProbeCommandHumanReport(
    *,
    verbosity_level,
    styled,
    cmd,
    file_list_total,
    view_results,
)

Prepared payload for human-facing pipeline probe command renderers.

The report is shared by human-facing renderers for topmark probe. It contains only presentation-ready data and policy flags; it does not perform rendering, Click interaction, or console output.

Attributes:

Name	Type	Description
`verbosity_level`	`int`	Effective TEXT verbosity; Markdown renderers ignore it.
`styled`	`bool`	Whether TEXT renderers should apply styling; Markdown renderers ignore it.
`cmd`	`str`	Command name, usually `probe`.
`file_list_total`	`int`	Total number of candidate files before view filtering.
`view_results`	`list[ProcessingContext]`	Processing contexts selected for the current human-output view.

PipelineCommandHumanReport `dataclass` ¶

PipelineCommandHumanReport(
    *,
    verbosity_level,
    styled,
    cmd,
    pipeline_kind,
    file_list_total,
    view_results,
    report_scope,
    unsupported_count,
    summary_mode,
    show_diffs,
    apply_changes,
)

Prepared payload for human-facing pipeline command renderers.

The report is shared by TEXT and Markdown renderers for topmark check and topmark strip. It contains only presentation-ready data and policy flags; it does not perform rendering, Click interaction, or console output.

Attributes:

Name	Type	Description
`verbosity_level`	`int`	Effective TEXT verbosity; Markdown renderers ignore it.
`styled`	`bool`	Whether TEXT renderers should apply styling; Markdown renderers ignore it.
`cmd`	`str`	Command name, such as `check` or `strip`.
`pipeline_kind`	`PipelineKindLiteral`	Pipeline kind used to select command-specific guidance.
`file_list_total`	`int`	Total number of user-requested results before view filtering, including selected pipeline files and synthetic resolver-level outcomes.
`view_results`	`list[ProcessingContext]`	Processing contexts selected for the current human-output view.
`report_scope`	`ReportScope`	Active report scope for the current view.
`unsupported_count`	`int`	Number of unsupported files omitted from actionable listings.
`summary_mode`	`bool`	Whether to render grouped outcome counts instead of per-file sections.
`show_diffs`	`bool`	Whether to include unified diffs.
`apply_changes`	`bool`	Whether the command runs in apply mode.

get_display_path ¶

get_display_path(r)

Return the user-facing path to display for a processing result.

TopMark may process content-on-STDIN by writing it to a temporary file. In that mode, ProcessingContext.path points at the temporary file on disk, but users expect messages to refer to the logical filename supplied via --stdin-filename.

This helper centralizes that policy so all human-facing renderers (TEXT and Markdown) display the same path labels.

Parameters:

Name	Type	Description	Default
`r`	`ProcessingContext`	Processing context to render.	required

Returns:

Type	Description
`str`	The logical filename in STDIN content mode, otherwise the actual file path.

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

def get_display_path(
    r: ProcessingContext,
) -> str:
    """Return the user-facing path to display for a processing result.

    TopMark may process *content-on-STDIN* by writing it to a temporary file.
    In that mode, `ProcessingContext.path` points at the temporary file on disk,
    but users expect messages to refer to the logical filename supplied via
    `--stdin-filename`.

    This helper centralizes that policy so all human-facing renderers (TEXT and
    Markdown) display the same path labels.

    Args:
        r: Processing context to render.

    Returns:
        The logical filename in STDIN content mode, otherwise the actual file path.
    """
    if r.run_options.stdin_mode and bool(r.run_options.stdin_filename):
        return r.run_options.stdin_filename
    return str(r.path)

get_file_type_label ¶

get_file_type_label(ctx)

Return the human-facing file-type label for a pipeline result.

Resolved files use their local file-type key. Unresolved files usually render as <unknown> so users can see that type resolution did not complete. Synthetic missing-file contexts are the exception: they are created by file resolution before type resolution can run, so they omit the file-type segment entirely.

This keeps missing-file output concise:

fubar: error: not_found

while still preserving useful context if a file was resolved before a later filesystem failure.