topmark.cli.emitters.machine¶

CLI helpers for emitting machine-readable output.

This module is Click/console-aware and is responsible only for writing already rendered machine-readable output strings (JSON or NDJSON) to the active ConsoleLike.

All shaping and serialization lives in topmark.core.machine.

emit_machine ¶

emit_machine(serialized, *, console, nl=True)

Emit the serialized machine-readable format to the ConsoleLike.

Parameters:

Name	Type	Description	Default
`serialized`	`str \| Iterable[str]`	The serialized machine data to emit.	required
`console`	`ConsoleProtocol`	Console used to emit the already-serialized machine-readable output.	required
`nl`	`bool`	If True (default), emit a newline at the end of each line.	`True`

Source code in src/topmark/cli/emitters/machine.py

def emit_machine(
    serialized: str | Iterable[str],
    *,
    console: ConsoleProtocol,
    nl: bool = True,
) -> None:
    """Emit the serialized machine-readable format to the ConsoleLike.

    Args:
        serialized: The serialized machine data to emit.
        console: Console used to emit the already-serialized machine-readable output.
        nl: If True (default), emit a newline at the end of each line.
    """
    if not serialized:
        # Nothing to print
        return

    if isinstance(serialized, str):
        console.print(serialized, nl=nl)
    else:
        for line in serialized:
            console.print(line, nl=nl)

emit_probe_results_machine ¶

emit_probe_results_machine(
    *, console, meta, config, resolved_toml, results, fmt
)

Emit topmark probe machine-readable output.

Parameters:

Name	Type	Description	Default
`console`	`ConsoleProtocol`	Console used to emit the already-serialized machine-readable output.	required
`meta`	`MetaPayload`	The machine metadata payload.	required
`config`	`FrozenConfig`	The immutable `FrozenConfig` instance.	required
`resolved_toml`	`ResolvedTopmarkTomlSources`	ResolvedTopmarkTomlSources,	required
`results`	`list[ProcessingContext]`	Ordered list of per-file probe results.	required
`fmt`	`OutputFormat`	Output format (`OutputFormat.JSON` or `OutputFormat.NDJSON`).	required

Raises:

Type	Description
`ValueError`	if `fmt` is not a machine-readable format.

Source code in src/topmark/cli/emitters/machine.py

def emit_probe_results_machine(
    *,
    console: ConsoleProtocol,
    meta: MetaPayload,
    config: FrozenConfig,
    resolved_toml: ResolvedTopmarkTomlSources,
    results: list[ProcessingContext],
    fmt: OutputFormat,
) -> None:
    """Emit topmark probe machine-readable output.

    Args:
        console: Console used to emit the already-serialized machine-readable output.
        meta: The machine metadata payload.
        config: The immutable [`FrozenConfig`][topmark.config.model.FrozenConfig] instance.
        resolved_toml: ResolvedTopmarkTomlSources,
        results: Ordered list of per-file probe results.
        fmt: Output format (`OutputFormat.JSON` or `OutputFormat.NDJSON`).

    Raises:
        ValueError: if `fmt` is not a machine-readable format.
    """
    if not is_machine_format(fmt):
        raise ValueError(f"Unsupported machine-readable output format: {fmt!r}")

    serialized: str | Iterator[str] = serialize_probe_results(
        meta=meta,
        config=config,
        resolved_toml=resolved_toml,
        results=results,
        fmt=fmt,
    )

    nl: bool = fmt != OutputFormat.JSON
    emit_machine(serialized, console=console, nl=nl)

emit_processing_results_machine ¶

emit_processing_results_machine(
    *,
    console,
    meta,
    config,
    resolved_toml,
    results,
    fmt,
    summary_mode,
)

Emit already-rendered machine strings to console.

Parameters:

Name	Type	Description	Default
`console`	`ConsoleProtocol`	Console used to emit the already-serialized machine-readable output.	required
`meta`	`MetaPayload`	The machine metadata payload.	required
`config`	`FrozenConfig`	The immutable `FrozenConfig` instance.	required
`resolved_toml`	`ResolvedTopmarkTomlSources`	ResolvedTopmarkTomlSources,	required
`results`	`list[ProcessingContext]`	Ordered list of per-file processing results.	required
`fmt`	`OutputFormat`	Output format (`OutputFormat.JSON` or `OutputFormat.NDJSON`).	required
`summary_mode`	`bool`	If True, emit aggregated counts instead of per-file entries.	required

Raises:

Type	Description
`ValueError`	if `fmt` is not a machine-readable format.

Source code in src/topmark/cli/emitters/machine.py

def emit_processing_results_machine(
    *,
    console: ConsoleProtocol,
    meta: MetaPayload,
    config: FrozenConfig,
    resolved_toml: ResolvedTopmarkTomlSources,
    results: list[ProcessingContext],
    fmt: OutputFormat,
    summary_mode: bool,
) -> None:
    """Emit already-rendered machine strings to console.

    Args:
        console: Console used to emit the already-serialized machine-readable output.
        meta: The machine metadata payload.
        config: The immutable [`FrozenConfig`][topmark.config.model.FrozenConfig] instance.
        resolved_toml: ResolvedTopmarkTomlSources,
        results: Ordered list of per-file processing results.
        fmt: Output format (`OutputFormat.JSON` or `OutputFormat.NDJSON`).
        summary_mode: If True, emit aggregated counts instead of per-file entries.

    Raises:
        ValueError: if `fmt` is not a machine-readable format.
    """
    if not is_machine_format(fmt):
        raise ValueError(f"Unsupported machine-readable output format: {fmt!r}")

    serialized: str | Iterator[str] = serialize_processing_results(
        meta=meta,
        config=config,
        resolved_toml=resolved_toml,
        results=results,
        fmt=fmt,
        summary_mode=summary_mode,
    )

    # Do not emit trailing newline for JSON
    nl: bool = fmt != OutputFormat.JSON
    emit_machine(serialized, console=console, nl=nl)

emit_config_machine ¶

emit_config_machine(
    *,
    console,
    meta,
    config,
    resolved_toml,
    fmt,
    show_config_layers=False,
)

Emit the effective Config snapshot in a machine-readable format.

When show_config_layers is enabled, machine-readable output also includes a config_provenance payload that preserves ordered config layers and the corresponding source-local TOML fragments.

Shapes

JSON, default:
JSON, with provenance:
NDJSON, default:
NDJSON, with provenance: {"kind": "config_provenance", "meta": ..., "config_provenance": ...}

Parameters:

Name	Type	Description	Default
`console`	`ConsoleProtocol`	Console used to emit the already-serialized machine-readable output.	required
`meta`	`MetaPayload`	The machine metadata payload.	required
`config`	`FrozenConfig`	Immutable runtime configuration to serialize.	required
`resolved_toml`	`ResolvedTopmarkTomlSources`	Resolved TOML sources used to build optional machine-readable config provenance.	required
`fmt`	`OutputFormat`	Target machine-readable format (JSON or NDJSON).	required
`show_config_layers`	`bool`	If `True`, include layered config provenance in the machine-readable output.	`False`

Raises:

Type	Description
`ValueError`	If `fmt` is not a supported machine-readable format, or if show_config_layers is `True` but resolved_toml is `None`.

Source code in src/topmark/cli/emitters/machine.py

def emit_config_machine(
    *,
    console: ConsoleProtocol,
    meta: MetaPayload,
    config: FrozenConfig,
    resolved_toml: ResolvedTopmarkTomlSources,
    fmt: OutputFormat,
    show_config_layers: bool = False,
) -> None:
    """Emit the effective Config snapshot in a machine-readable format.

    When `show_config_layers` is enabled, machine-readable output also includes a
    `config_provenance` payload that preserves ordered config layers and the
    corresponding source-local TOML fragments.

    Shapes:
        - JSON, default:
            {"meta": ..., "config": ...}
        - JSON, with provenance:
            {"meta": ..., "config_provenance": ..., "config": ...}
        - NDJSON, default:
            {"kind": "config", "meta": ..., "config": ...}
        - NDJSON, with provenance:
            {"kind": "config_provenance", "meta": ..., "config_provenance": ...}
            {"kind": "config", "meta": ..., "config": ...}

    Args:
        console: Console used to emit the already-serialized machine-readable output.
        meta: The machine metadata payload.
        config: Immutable runtime configuration to serialize.
        resolved_toml: Resolved TOML sources used to build optional machine-readable
            config provenance.
        fmt: Target machine-readable format (JSON or NDJSON).
        show_config_layers: If `True`, include layered config provenance in the
            machine-readable output.

    Raises:
        ValueError: If `fmt` is not a supported machine-readable format, or
            if show_config_layers is `True` but resolved_toml is `None`.


    """
    if not is_machine_format(fmt):
        raise ValueError(f"Unsupported machine-readable output format: {fmt!r}")

    serialized: str | Iterator[str] = serialize_config(
        meta=meta,
        config=config,
        fmt=fmt,
        resolved_toml=resolved_toml,
        show_config_layers=show_config_layers,
    )

    # Do not emit trailing newline for JSON
    nl: bool = fmt != OutputFormat.JSON
    emit_machine(serialized, console=console, nl=nl)

emit_config_diagnostics_machine ¶

emit_config_diagnostics_machine(
    *, console, meta, config, fmt
)

Emit Config diagnostics in a machine-readable format to ConsoleLike.

Shapes

JSON: a single object matching ConfigDiagnosticsPayload, wrapped as {"meta": ..., "config_diagnostics": ...}.
NDJSON: a single line of the form {"kind": "config_diagnostics", "meta": ..., "config_diagnostics": }.

Parameters:

Name	Type	Description	Default
`console`	`ConsoleProtocol`	Console used to emit the already-serialized machine-readable output.	required
`meta`	`MetaPayload`	The machine metadata payload.	required
`config`	`FrozenConfig`	Immutable runtime configuration providing diagnostics.	required
`fmt`	`OutputFormat`	Target machine-readable format (JSON or NDJSON).	required

Raises:

Type	Description
`ValueError`	if `fmt` is not a supported machine-readable format.

Source code in src/topmark/cli/emitters/machine.py

def emit_config_diagnostics_machine(
    *,
    console: ConsoleProtocol,
    meta: MetaPayload,
    config: FrozenConfig,
    fmt: OutputFormat,
) -> None:
    """Emit Config diagnostics in a machine-readable format to ConsoleLike.

    Shapes:
        - JSON: a single object matching ConfigDiagnosticsPayload, wrapped as
          {"meta": ..., "config_diagnostics": ...}.
        - NDJSON: a single line of the form
          {"kind": "config_diagnostics", "meta": ..., \
            "config_diagnostics": <ConfigDiagnosticsPayload>}.

    Args:
        console: Console used to emit the already-serialized machine-readable output.
        meta: The machine metadata payload.
        config: Immutable runtime configuration providing diagnostics.
        fmt: Target machine-readable format (JSON or NDJSON).

    Raises:
        ValueError: if `fmt` is not a supported machine-readable format.
    """
    if not is_machine_format(fmt):
        raise ValueError(f"Unsupported machine-readable output format: {fmt!r}")

    serialized: str | Iterator[str] = serialize_config_diagnostics(
        meta=meta,
        config=config,
        fmt=fmt,
    )

    # Do not emit trailing newline for JSON
    nl: bool = fmt != OutputFormat.JSON
    emit_machine(serialized, console=console, nl=nl)

emit_config_check_machine ¶

emit_config_check_machine(
    *, console, meta, config, resolved_toml, strict, ok, fmt
)

Emit topmark config check results in a machine-readable format.

JSON

One envelope containing meta, config, config_diagnostics, and config_check.

NDJSON

1) config 2) config_diagnostics (counts-only) 3) config_check (command=config, subcommand=check) 4+) diagnostic (domain=config) one per diagnostic

Parameters:

Name	Type	Description	Default
`console`	`ConsoleProtocol`	Console used to emit the already-serialized machine-readable output.	required
`meta`	`MetaPayload`	The machine metadata payload.	required
`config`	`FrozenConfig`	Immutable runtime configuration providing diagnostics.	required
`resolved_toml`	`ResolvedTopmarkTomlSources`	Resolved TOML sources used to include TOML-authored writer options in the config payload.	required
`strict`	`bool`	Enforce strict config checking (fail on warning) if True, fail on error otherwise.	required
`ok`	`bool`	True if config checking passed, False otherwise.	required
`fmt`	`OutputFormat`	Target machine-readable format (JSON or NDJSON).	required

Raises:

Type	Description
`ValueError`	if `fmt` is not a supported machine-readable format.

Source code in src/topmark/cli/emitters/machine.py

def emit_config_check_machine(
    *,
    console: ConsoleProtocol,
    meta: MetaPayload,
    config: FrozenConfig,
    resolved_toml: ResolvedTopmarkTomlSources,
    strict: bool,
    ok: bool,
    fmt: OutputFormat,
) -> None:
    """Emit `topmark config check` results in a machine-readable format.

    JSON:
      - One envelope containing `meta`, `config`, `config_diagnostics`, and
        `config_check`.

    NDJSON:
      1) `config`
      2) `config_diagnostics` (counts-only)
      3) `config_check` (command=`config`, subcommand=`check`)
      4+) `diagnostic` (domain=`config`) one per diagnostic

    Args:
        console: Console used to emit the already-serialized machine-readable output.
        meta: The machine metadata payload.
        config: Immutable runtime configuration providing diagnostics.
        resolved_toml: Resolved TOML sources used to include TOML-authored
            writer options in the config payload.
        strict: Enforce strict config checking (fail on warning) if True,
            fail on error otherwise.
        ok: True if config checking passed, False otherwise.
        fmt: Target machine-readable format (JSON or NDJSON).

    Raises:
        ValueError: if `fmt` is not a supported machine-readable format.
    """
    if not is_machine_format(fmt):
        raise ValueError(f"Unsupported machine-readable output format: {fmt!r}")

    serialized: str | Iterator[str] = serialize_config_check(
        meta=meta,
        config=config,
        resolved_toml=resolved_toml,
        strict=strict,
        ok=ok,
        fmt=fmt,
    )

    # Do not emit trailing newline for JSON
    nl: bool = fmt != OutputFormat.JSON
    emit_machine(serialized, console=console, nl=nl)

emit_filetypes_machine ¶

emit_filetypes_machine(*, console, meta, fmt, show_details)

Emit topmark registry filetypes machine-readable output.

Parameters:

Name	Type	Description	Default
`console`	`ConsoleProtocol`	Console used to emit the already-serialized machine-readable output.	required
`meta`	`MetaPayload`	The machine metadata payload.	required
`fmt`	`OutputFormat`	Target machine-readable format (`json` or `ndjson`).	required
`show_details`	`bool`	If True, include expanded identity, matching, binding, and policy fields.	required

Source code in src/topmark/cli/emitters/machine.py

def emit_filetypes_machine(
    *,
    console: ConsoleProtocol,
    meta: MetaPayload,
    fmt: OutputFormat,
    show_details: bool,
) -> None:
    """Emit `topmark registry filetypes` machine-readable output.

    Args:
        console: Console used to emit the already-serialized machine-readable output.
        meta: The machine metadata payload.
        fmt: Target machine-readable format (`json` or `ndjson`).
        show_details: If True, include expanded identity, matching, binding,
            and policy fields.
    """
    serialized: str | Iterator[str] = serialize_filetypes(
        meta=meta,
        fmt=fmt,
        show_details=show_details,
    )

    # Do not emit trailing newline for JSON
    nl: bool = fmt != OutputFormat.JSON
    emit_machine(serialized, console=console, nl=nl)

emit_processors_machine ¶

emit_processors_machine(
    *, console, meta, fmt, show_details
)

Emit topmark registry processors machine-readable output.

Parameters:

Name	Type	Description	Default
`console`	`ConsoleProtocol`	Console used to emit the already-serialized machine-readable output.	required
`meta`	`MetaPayload`	The machine metadata payload.	required
`fmt`	`OutputFormat`	Target machine-readable format (`json` or `ndjson`).	required
`show_details`	`bool`	If True, include expanded identity, binding, and delimiter fields.	required

Source code in src/topmark/cli/emitters/machine.py

def emit_processors_machine(
    *,
    console: ConsoleProtocol,
    meta: MetaPayload,
    fmt: OutputFormat,
    show_details: bool,
) -> None:
    """Emit `topmark registry processors` machine-readable output.

    Args:
        console: Console used to emit the already-serialized machine-readable output.
        meta: The machine metadata payload.
        fmt: Target machine-readable format (`json` or `ndjson`).
        show_details: If True, include expanded identity, binding, and
            delimiter fields.
    """
    serialized: str | Iterator[str] = serialize_processors(
        meta=meta,
        fmt=fmt,
        show_details=show_details,
    )

    # Do not emit trailing newline for JSON
    nl: bool = fmt != OutputFormat.JSON
    emit_machine(serialized, console=console, nl=nl)

emit_bindings_machine ¶

emit_bindings_machine(*, console, meta, fmt, show_details)

Emit topmark registry bindings machine-readable output.

Parameters:

Name	Type	Description	Default
`console`	`ConsoleProtocol`	Console used to emit the already-serialized machine-readable output.	required
`meta`	`MetaPayload`	The machine metadata payload.	required
`fmt`	`OutputFormat`	Target machine-readable format (`json` or `ndjson`).	required
`show_details`	`bool`	If True, include expanded file type and processor identity metadata for each binding plus structured auxiliary lists.	required

Source code in src/topmark/cli/emitters/machine.py

def emit_bindings_machine(
    *,
    console: ConsoleProtocol,
    meta: MetaPayload,
    fmt: OutputFormat,
    show_details: bool,
) -> None:
    """Emit `topmark registry bindings` machine-readable output.

    Args:
        console: Console used to emit the already-serialized machine-readable output.
        meta: The machine metadata payload.
        fmt: Target machine-readable format (`json` or `ndjson`).
        show_details: If True, include expanded file type and processor
            identity metadata for each binding plus structured auxiliary lists.
    """
    serialized: str | Iterator[str] = serialize_bindings(
        meta=meta,
        fmt=fmt,
        show_details=show_details,
    )

    # Do not emit trailing newline for JSON
    nl: bool = fmt != OutputFormat.JSON
    emit_machine(serialized, console=console, nl=nl)