topmark.cli.commands.config_defaults

topmark / cli / commands / config_defaults

TopMark config defaults command.

Prints TopMark's built-in default TOML configuration document.

This command is intended as a copy/paste reference for users. It differs from topmark config init, which emits the annotated packaged template (when available) intended to be written as an initial config file.

config_defaults_command

config_defaults_command(
    *,
    verbosity,
    color_mode,
    no_color,
    for_pyproject,
    config_root,
    output_format,
)

Print the built-in default configuration document.

Outputs a clean TOML representation of TopMark's default configuration. This serves as a reference when no configuration files are present.

Notes

• In JSON/NDJSON modes, this command emits only a Config snapshot (no diagnostics).

Parameters:

Name	Type	Description	Default
verbosity	int	Increase TEXT output detail.	required
color_mode	ColorMode | None	Color mode for text format (default: auto).	required
no_color	bool	If set, disable color mode.	required
for_pyproject	bool	If True, render as subtable under [tool.topmark] (default: False: plain topmark.toml TOML config format).	required
config_root	bool	If True, set config as root (stops further config resolution).	required
output_format	OutputFormat | None	Output format to use (text, markdown, json, or ndjson). Verbosity applies only to TEXT output; this command does not support --quiet.	required

Raises:

Type	Description
NotImplementedError	When providing an unsupported OutputType.

Source code in src/topmark/cli/commands/config_defaults.py

@click.command(
    name=CliCmd.CONFIG_DEFAULTS,
    context_settings=GROUP_CONTEXT_SETTINGS,
    help=(
        "Print TopMark's built-in default configuration. "
        "This command is file-agnostic: positional PATHS "
        "and file-processing STDIN modes are rejected. "
        f"Use {CliOpt.OUTPUT_FORMAT}={OutputFormat.JSON.value}/{OutputFormat.NDJSON.value} "
        "for machine-readable output."
    ),
    epilog=(
        "\b\n"
        "Examples:\n"
        "  # Print built-in default configuration\n"
        f"  topmark {CliCmd.CONFIG} {CliCmd.CONFIG_DEFAULTS}\n"
        "  # Print the built-in default configuration reference for pyproject.toml\n"
        f"  topmark {CliCmd.CONFIG} {CliCmd.CONFIG_DEFAULTS} {CliOpt.CONFIG_FOR_PYPROJECT}\n"
        "  # Emit machine-readable configuration\n"
        f"  topmark {CliCmd.CONFIG} {CliCmd.CONFIG_DEFAULTS} "
        f"{CliOpt.OUTPUT_FORMAT}={OutputFormat.JSON.value}\n"
        "\n"
        "\b\n"
        "Notes:\n"
        "  • Human formats render a clean TOML view of defaults (no comments).\n"
        "  • Machine-readable formats emit a minimal Config snapshot without diagnostics.\n"
    ),
)
@common_color_options
@common_text_output_verbosity_options
@config_pyproject_options
@config_root_options
@common_output_format_options
def config_defaults_command(
    *,
    # common_ui_options (verbosity, color):
    verbosity: int,
    color_mode: ColorMode | None,
    no_color: bool,
    # config_pyproject_options:
    for_pyproject: bool,
    # config_root_options:
    config_root: bool,
    # common_output_format_options:
    output_format: OutputFormat | None,
) -> None:
    """Print the built-in default configuration document.

    Outputs a clean TOML representation of TopMark's default configuration.
    This serves as a reference when no configuration files are present.

    Notes:
        - In JSON/NDJSON modes, this command emits only a Config snapshot
          (no diagnostics).

    Args:
        verbosity: Increase TEXT output detail.
        color_mode: Color mode for text format (default: auto).
        no_color: If set, disable color mode.
        for_pyproject: If True, render as subtable under `[tool.topmark]`
            (default: False: plain topmark.toml TOML config format).
        config_root: If True, set config as root (stops further config resolution).
        output_format: Output format to use (``text``, ``markdown``, ``json``, or ``ndjson``).
            Verbosity applies only to TEXT output; this command does not support
            ``--quiet``.

    Raises:
        NotImplementedError: When providing an unsupported OutputType.
    """
    ctx: click.Context = click.get_current_context()
    state: TopmarkCliState = bootstrap_cli_state(ctx)
    # Effective output format (stored early so shared initialization sees it).
    state.output_format = output_format or OutputFormat.TEXT

    # Initialize the common state (verbosity, color mode) and initialize console
    init_common_state(
        ctx,
        verbosity=verbosity,
        quiet=False,  # Pure informational command; no ``--quiet`` option is registered.
        color_mode=color_mode,
        no_color=no_color,
    )

    # Retrieve effective human facing program-output verbosity for gating extra details
    verbosity_level: int = state.verbosity

    # Select the console
    console: ConsoleProtocol = state.console

    # Machine metadata
    meta: MetaPayload = build_meta_payload()

    # Output format
    fmt: OutputFormat = state.output_format

    apply_color_policy_for_output_format(ctx, fmt=fmt)
    enable_color: bool = state.color_enabled

    # `config defaults` is file-agnostic: ignore positional PATHS
    apply_ignore_positional_paths_policy(
        ctx,
        warn_stdin_dash=True,
    )

    validate_human_only_config_flags_for_machine_format(
        ctx,
        fmt=fmt,
        config_root=config_root,
        for_pyproject=for_pyproject,
    )

    if fmt in (OutputFormat.JSON, OutputFormat.NDJSON):
        resolved_config: ResolvedConfigDraft = resolve_default_table_and_build_mutable_config()
        # Machine-readable formats: emit JSON/NDJSON without human banners
        emit_config_machine(
            console=console,
            meta=meta,
            config=resolved_config.draft.freeze(),
            resolved_toml=resolved_config.resolved,
            fmt=fmt,
        )
        return

    report: ConfigDefaultsHumanReport = build_config_defaults_human_report(
        for_pyproject=for_pyproject,
        root=config_root,
        verbosity_level=verbosity_level,
        styled=enable_color,
    )
    if fmt == OutputFormat.MARKDOWN:
        console.print(
            render_config_defaults_markdown(report),
            nl=False,
        )
        return

    if fmt == OutputFormat.TEXT:
        console.print(render_config_defaults_text(report))
        return

    # Defensive guard in case OutputFormat gains new members
    raise NotImplementedError(f"Unsupported output format: {fmt!r}")