topmark.presentation.shared.config

topmark / presentation / shared / config

Shared data preparation for config CLI emitters.

This module contains Click-free helpers that prepare domain data for human-facing emitters (TEXT / MARKDOWN).

It intentionally sits between:

• configuration I/O helpers in topmark.config.io, and
• renderers in topmark.presentation.text.config (ANSI) and topmark.presentation.markdown.config (Markdown).

Notes

These helpers may perform light serialization work and may load bundled template resources. They do not print to stdout/stderr; user-facing warnings should be handled by the caller or the emitters. Where human-facing config diagnostics are prepared, this module flattens staged config-validation logs at the presentation boundary. TEXT renderers may use verbosity_level and styled; Markdown renderers treat Markdown as document-oriented output and ignore TEXT-only verbosity and quiet controls.

ConfigInitHumanReport dataclass

ConfigInitHumanReport(
    *, toml_text, error, verbosity_level, styled
)

Prepared payload for topmark config init (human formats).

Attributes:

Name	Type	Description
toml_text	str	Starter configuration TOML text (annotated template).
error	Exception | None	Optional exception raised while reading the bundled template. When set, callers may render a warning and still proceed with the returned TOML text (which may be a synthesized fallback).
verbosity_level	int	Effective TEXT verbosity; Markdown renderers ignore it.
styled	bool	Whether TEXT renderers should apply styling; Markdown renderers ignore it.

ConfigDefaultsHumanReport dataclass

ConfigDefaultsHumanReport(
    *, toml_text, verbosity_level, styled
)

Prepared TOML payload for topmark config defaults.

This is the cleaned default configuration (copy/paste friendly).

Attributes:

Name	Type	Description
toml_text	str	Cleaned TOML text. When prepared with for_pyproject=True, the TOML is nested under [tool.topmark].
verbosity_level	int	Effective TEXT verbosity; Markdown renderers ignore it.
styled	bool	Whether TEXT renderers should apply styling; Markdown renderers ignore it.

ConfigCheckHumanReport dataclass

ConfigCheckHumanReport(
    *,
    config_files,
    ok,
    strict,
    merged_toml,
    counts,
    diagnostics,
    verbosity_level,
    styled,
)

Prepared human-facing data for topmark config check.

Attributes:

Name	Type	Description
config_files	list[str]	Config files contributing to the effective config (stringified paths).
ok	bool	Whether the configuration passed validation.
strict	bool	Whether strict checking was enabled.
merged_toml	str | None	Effective merged configuration as TOML, or None when not requested (typically only included at verbosity >= 2).
counts	HumanDiagnosticCounts	Human diagnostic counts.
diagnostics	list[HumanDiagnosticLine]	Human diagnostic lines (ordered).
verbosity_level	int	Effective TEXT verbosity; Markdown renderers ignore it.
styled	bool	Whether TEXT renderers should apply styling; Markdown renderers ignore it.

ConfigDumpHumanReport dataclass

ConfigDumpHumanReport(
    *,
    config_files,
    merged_toml,
    provenance_toml,
    show_config_layers,
    verbosity_level,
    styled,
)

Prepared human-facing data for topmark config dump.

Attributes:

Name	Type	Description
config_files	list[str]	Config files contributing to the effective config, rendered as stringified paths.
merged_toml	str	Final flattened effective configuration rendered as TOML.
provenance_toml	str | None	Optional layered TOML provenance export rendered as TOML. When present, this is an inspection-oriented document whose [[layers]] entries preserve provenance metadata and expose each source-local TOML fragment under [layers.toml.*].
show_config_layers	bool	Whether layered provenance output was requested.
verbosity_level	int	Effective TEXT verbosity; Markdown renderers ignore it.
styled	bool	Whether TEXT renderers should apply styling; Markdown renderers ignore it.

build_config_init_human_report

build_config_init_human_report(
    *, for_pyproject, root, verbosity_level, styled
)

Prepare human-facing data for topmark config init.

The annotated template is authored in plain topmark.toml shape. Template edits therefore happen in that plain shape first:

1. load the annotated template (or generated fallback)
2. optionally set [config].root = true in the plain template text
3. if for_pyproject=True, nest the whole document under [tool.topmark]
4. validate the final output shape as a defensive backstop

Parameters:

Name	Type	Description	Default
for_pyproject	bool	If True, nest the final document under [tool.topmark].	required
root	bool	If True, set [config].root = true before any optional nesting.	required
verbosity_level	int	Effective TEXT verbosity; Markdown renderers ignore it.	required
styled	bool	Whether TEXT renderers should apply styling; Markdown renderers ignore it.	required

Returns:

Type	Description
ConfigInitHumanReport	Prepared TOML text plus optional template read error.

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

def build_config_init_human_report(
    *,
    for_pyproject: bool,
    root: bool,
    verbosity_level: int,
    styled: bool,
) -> ConfigInitHumanReport:
    """Prepare human-facing data for `topmark config init`.

    The annotated template is authored in plain `topmark.toml` shape. Template
    edits therefore happen in that plain shape first:

    1. load the annotated template (or generated fallback)
    2. optionally set `[config].root = true` in the plain template text
    3. if `for_pyproject=True`, nest the whole document under `[tool.topmark]`
    4. validate the final output shape as a defensive backstop

    Args:
        for_pyproject: If `True`, nest the final document under `[tool.topmark]`.
        root: If `True`, set `[config].root = true` before any optional nesting.
        verbosity_level: Effective TEXT verbosity; Markdown renderers ignore it.
        styled: Whether TEXT renderers should apply styling; Markdown renderers ignore it.

    Returns:
        Prepared TOML text plus optional template read error.
    """
    template_text: DefaultTomlTemplateText = load_default_topmark_template_toml_text()
    toml_text: str = template_text.toml_text
    template_error: Exception | None = template_text.error
    changed = False

    if root:
        res: TemplateEditResult = set_root_flag_in_template_text(
            toml_text,
            for_pyproject=False,
            root=True,
        )
        toml_text, changed = res.text, (changed or res.changed)

    if for_pyproject:
        nested_text: str = nest_toml_under_section(
            toml_text,
            "tool.topmark",
        )  # Raises ValueError, TomlParseError, TomlSurgeryError.

        changed: bool = changed or (nested_text != toml_text)
        toml_text = nested_text

    # TOML correctness backstop. Raises TemplateValidationError.
    validate_toml_for_config_init(
        toml_text,
        for_pyproject=for_pyproject,
        root_expected=root,
    )  # Raises TemplateValidationError.

    return ConfigInitHumanReport(
        toml_text=toml_text,
        error=template_error,
        verbosity_level=verbosity_level,
        styled=styled,
    )

build_config_defaults_human_report

build_config_defaults_human_report(
    *, for_pyproject, root, verbosity_level, styled
)

Prepare human-facing data for topmark config defaults.

Renders the centralized default TopMark TOML document, optionally nests it under [tool.topmark], then cleans it for copy/paste.

Parameters:

Name	Type	Description	Default
for_pyproject	bool	If True, nest the TOML under [tool.topmark].	required
root	bool	If True, set root = true (top-level or tool.topmark.root).	required
verbosity_level	int	Effective TEXT verbosity; Markdown renderers ignore it.	required
styled	bool	Whether TEXT renderers should apply styling; Markdown renderers ignore it.	required

Returns:

Type	Description
ConfigDefaultsHumanReport	Prepared cleaned TOML text.

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

def build_config_defaults_human_report(
    *,
    for_pyproject: bool,
    root: bool,
    verbosity_level: int,
    styled: bool,
) -> ConfigDefaultsHumanReport:
    """Prepare human-facing data for `topmark config defaults`.

    Renders the centralized default TopMark TOML document, optionally nests it under
    `[tool.topmark]`, then cleans it for copy/paste.

    Args:
        for_pyproject: If True, nest the TOML under `[tool.topmark]`.
        root: If True, set `root = true` (top-level or tool.topmark.root).
        verbosity_level: Effective TEXT verbosity; Markdown renderers ignore it.
        styled: Whether TEXT renderers should apply styling; Markdown renderers ignore it.

    Returns:
        Prepared cleaned TOML text.
    """
    toml_text: str = render_default_topmark_toml_text(for_pyproject=for_pyproject)

    if root:
        toml_text = set_root_flag(toml_text, for_pyproject=for_pyproject, root=True)
        # Raises TomlParseError, TomlSurgeryError.

    cleaned: str = clean_toml_text(toml_text)
    return ConfigDefaultsHumanReport(
        toml_text=cleaned,
        verbosity_level=verbosity_level,
        styled=styled,
    )

render_effective_config_toml

render_effective_config_toml(
    *, config, writer_options, include_files=False
)

Render the effective configuration plus runtime writer options as TOML.

FrozenConfig intentionally models the layered TopMark configuration, while writer options are resolved from TOML into runtime-facing state outside the immutable FrozenConfig model. Human-facing config reports still need to show the full effective TOML surface authored by users, including the [writer] section.

Parameters:

Name	Type	Description	Default
config	FrozenConfig	Effective runtime configuration to serialize.	required
writer_options	WriterOptions | None	Resolved runtime writer options to merge into the exported TOML document, or None when no writer options were configured.	required
include_files	bool	Whether to include file-listing fields from config in the rendered TOML document.	False

Returns:

Type	Description
str	Rendered TOML text containing the effective config-originating entries
str	and, when present, the resolved [writer] section.

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

def render_effective_config_toml(
    *,
    config: FrozenConfig,
    writer_options: WriterOptions | None,
    include_files: bool = False,
) -> str:
    """Render the effective configuration plus runtime writer options as TOML.

    [`FrozenConfig`][topmark.config.model.FrozenConfig] intentionally models the
    layered TopMark configuration, while writer options are resolved from TOML
    into runtime-facing state outside the immutable
    [`FrozenConfig`][topmark.config.model.FrozenConfig] model.
    Human-facing config reports still need to show the full effective TOML surface
    authored by users, including the `[writer]` section.

    Args:
        config: Effective runtime configuration to serialize.
        writer_options: Resolved runtime writer options to merge into the
            exported TOML document, or `None` when no writer options were
            configured.
        include_files: Whether to include file-listing fields from `config` in
            the rendered TOML document.

    Returns:
        Rendered TOML text containing the effective config-originating entries
        and, when present, the resolved `[writer]` section.
    """
    merged_toml_table: TomlTable = config_to_topmark_toml_table(
        config,
        include_files=include_files,
    )
    merged_toml_table.update(
        writer_options_to_toml_table(writer_options),
    )
    return render_toml_table(merged_toml_table)

build_config_check_human_report

build_config_check_human_report(
    *,
    config,
    resolved_sources,
    ok,
    strict,
    verbosity_level,
    styled,
)

Prepare human-facing data for topmark config check.

This helper is Click-free and may perform light computation (counts, string normalization). It does not print.

Parameters:

Name	Type	Description	Default
config	FrozenConfig	Effective runtime configuration.	required
resolved_sources	ResolvedTopmarkTomlSources	Resolved sources (includes runtime options such as write options).	required
ok	bool	Whether the configuration passed validation.	required
strict	bool	Whether strict checking was enabled.	required
verbosity_level	int	Effective verbosity (used for gating heavy/verbose sections).	required
styled	bool	Whether to style text output (OutputFormat.TEXT)	required

Returns:

Type	Description
ConfigCheckHumanReport	Prepared config file list, optional merged TOML (verbosity > 1), plus
ConfigCheckHumanReport	human diagnostic counts and lines derived from the flattened
ConfigCheckHumanReport	compatibility view of staged config-validation logs.

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

def build_config_check_human_report(
    *,
    config: FrozenConfig,
    resolved_sources: ResolvedTopmarkTomlSources,
    ok: bool,
    strict: bool,
    verbosity_level: int,
    styled: bool,
) -> ConfigCheckHumanReport:
    """Prepare human-facing data for `topmark config check`.

    This helper is Click-free and may perform light computation (counts, string normalization).
    It does not print.

    Args:
        config: Effective runtime configuration.
        resolved_sources: Resolved sources (includes runtime options such as write options).
        ok: Whether the configuration passed validation.
        strict: Whether strict checking was enabled.
        verbosity_level: Effective verbosity (used for gating heavy/verbose sections).
        styled: Whether to style text output (OutputFormat.TEXT)

    Returns:
        Prepared config file list, optional merged TOML (verbosity > 1), plus
        human diagnostic counts and lines derived from the flattened
        compatibility view of staged config-validation logs.
    """
    merged_toml: str | None = None
    if verbosity_level > 1:
        merged_toml = render_effective_config_toml(
            config=config,
            writer_options=resolved_sources.writer_options,
            include_files=False,
        )

    # Flatten staged validation logs here so human-facing reports keep the
    # current compatibility diagnostics view.
    flattened_diagnostics: FrozenDiagnosticLog = config.validation_logs.flattened()
    human_diagnostics: HumanDiagnostics = prepare_human_diagnostics(flattened_diagnostics)

    return ConfigCheckHumanReport(
        config_files=_stringify_config_files(config),
        ok=ok,
        strict=strict,
        merged_toml=merged_toml,
        counts=human_diagnostics.counts,
        diagnostics=human_diagnostics.lines,
        styled=styled,
        verbosity_level=verbosity_level,
    )

build_config_dump_human_report

build_config_dump_human_report(
    *,
    config,
    resolved_toml,
    show_config_layers,
    verbosity_level,
    styled,
)

Prepare human-facing data for topmark config dump.

This helper is Click-free: it performs TOML serialization for the flattened effective config and, when requested, also prepares a layered TOML provenance export.

Parameters:

Name	Type	Description	Default
config	FrozenConfig	Effective runtime configuration.	required
resolved_toml	ResolvedTopmarkTomlSources	Resolved TOML sources used to build the optional layered provenance export.	required
show_config_layers	bool	If True, include a layered TOML provenance export before the flattened config dump.	required
verbosity_level	int	Effective TEXT verbosity; Markdown renderers ignore it.	required
styled	bool	Whether TEXT renderers should apply styling; Markdown renderers ignore it.	required

Returns:

Type	Description
ConfigDumpHumanReport	Prepared config file list, flattened TOML text, and optional layered
ConfigDumpHumanReport	TOML provenance export.

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

def build_config_dump_human_report(
    *,
    config: FrozenConfig,
    resolved_toml: ResolvedTopmarkTomlSources,
    show_config_layers: bool,
    verbosity_level: int,
    styled: bool,
) -> ConfigDumpHumanReport:
    """Prepare human-facing data for `topmark config dump`.

    This helper is Click-free: it performs TOML serialization for the
    flattened effective config and, when requested, also prepares a layered
    TOML provenance export.

    Args:
        config: Effective runtime configuration.
        resolved_toml: Resolved TOML sources used to build the optional layered
            provenance export.
        show_config_layers: If `True`, include a layered TOML provenance export
            before the flattened config dump.
        verbosity_level: Effective TEXT verbosity; Markdown renderers ignore it.
        styled: Whether TEXT renderers should apply styling; Markdown renderers ignore it.

    Returns:
        Prepared config file list, flattened TOML text, and optional layered
        TOML provenance export.
    """
    # Build the optional inspection-oriented provenance document only when the
    # caller explicitly requests layered output.
    provenance_toml: str | None = None
    merged_toml: str = render_effective_config_toml(
        config=config,
        writer_options=resolved_toml.writer_options,
        include_files=False,
    )
    if show_config_layers:
        provenance_toml = _build_config_layers_provenance_toml(resolved_toml)

    return ConfigDumpHumanReport(
        config_files=_stringify_config_files(config),
        merged_toml=merged_toml,
        provenance_toml=provenance_toml,
        show_config_layers=show_config_layers,
        styled=styled,
        verbosity_level=verbosity_level,
    )