topmark.config.resolution.bridge

topmark / config / resolution / bridge

Bridge helpers between TOML source resolution and config draft construction.

This module defines the small public bridge between TOML-side source resolution (topmark.toml.resolution) and config-side draft construction. It performs no per-path applicability checks and no runtime override application.

Its diagnostics role is to replay source-level TOML validation issues into the merged config draft's TOML-source validation stage so later staged config/preflight validation sees the full config-loading diagnostic picture.

ResolvedConfigDraft dataclass

ResolvedConfigDraft(*, resolved, draft)

Resolved TOML-side state and the mutable config draft built from it.

Attributes:

Name	Type	Description
resolved	ResolvedTopmarkTomlSources	Resolved TOML-side state, including source provenance, writer options, and TOML-side strictness.
draft	MutableConfig	Mutable config draft produced by merging the resolved config layers.

build_mutable_config_from_resolved_toml_sources

build_mutable_config_from_resolved_toml_sources(resolved)

Merge resolved TOML sources into one mutable config draft.

This helper consumes already-resolved TOML-side state and performs the config-layer construction and merge step without re-running TOML discovery.

In addition to merging the layered config fragments, it replays whole-source TOML schema validation issues collected during TOML loading into the merged draft's TOML-source validation stage. This ensures that the effective strictness derived from strict sees schema issues outside the layered-config subset, such as invalid top-level keys under [tool.topmark], unknown keys in [writer], or TOML-layer missing-section INFO diagnostics.

Source-local config-loading options such as strict are resolved on the TOML side. This helper only performs config-layer construction, merging, and diagnostic aggregation; it does not re-run TOML schema validation.

Parameters:

Name	Type	Description	Default
resolved	ResolvedTopmarkTomlSources	Resolved TOML-side state for the current run.	required

Returns:

Type	Description
MutableConfig	Merged mutable config draft built from the defaults layer plus all
MutableConfig	resolved layered TOML sources, with source-level TOML schema issues
MutableConfig	replayed into its TOML-source validation stage for later staged
MutableConfig	config/preflight validation.

Source code in src/topmark/config/resolution/bridge.py

def build_mutable_config_from_resolved_toml_sources(
    resolved: ResolvedTopmarkTomlSources,
) -> MutableConfig:
    """Merge resolved TOML sources into one mutable config draft.

    This helper consumes already-resolved TOML-side state and performs the
    config-layer construction and merge step without re-running TOML discovery.

    In addition to merging the layered config fragments, it replays whole-source
    TOML schema validation issues collected during TOML loading into the merged
    draft's TOML-source validation stage. This ensures that the effective
    strictness derived from `strict` sees schema issues outside
    the layered-config subset, such as invalid top-level keys under
    `[tool.topmark]`, unknown keys in `[writer]`, or TOML-layer missing-section
    INFO diagnostics.

    Source-local config-loading options such as `strict` are
    resolved on the TOML side. This helper only performs config-layer
    construction, merging, and diagnostic aggregation; it does not re-run TOML
    schema validation.

    Args:
        resolved: Resolved TOML-side state for the current run.

    Returns:
        Merged mutable config draft built from the defaults layer plus all
        resolved layered TOML sources, with source-level TOML schema issues
        replayed into its TOML-source validation stage for later staged
        config/preflight validation.
    """
    layers: list[ConfigLayer] = build_config_layers_from_resolved_toml_sources(resolved.sources)
    draft: MutableConfig = merge_layers_globally(layers)

    for source in resolved.sources:
        add_toml_issues(
            draft.validation_logs.toml_source,
            source.validation_issues,
        )
        for diagnostic in source.load_diagnostics:
            draft.validation_logs.toml_source.add(diagnostic)

    return draft

resolve_toml_sources_and_build_mutable_config

resolve_toml_sources_and_build_mutable_config(
    *,
    input_paths=None,
    extra_config_files=None,
    strict=None,
    no_config=False,
)

Resolve TOML sources once and build the merged config draft from them.

This helper is the preferred bridge between TOML-side source resolution and config-layer merge for callers that need both the resolved TOML-side state and the merged mutable config draft.

Parameters:

Name	Type	Description	Default
input_paths	Iterable[Path] | None	Optional discovery anchors. The first path is used to pick the project-discovery starting directory. If it points to a file, its parent directory is used. If omitted, discovery falls back to the current working directory.	None
extra_config_files	Iterable[Path] | None	Explicit config files to merge after discovered layers. Later files override earlier ones.	None
strict	bool | None	Optional explicit override for the TOML-side strictness preference that later governs staged staged config-loading validation.	None
no_config	bool	If True, skip all discovered config layers (user + project) and only use built-in defaults plus any explicit extra config files.	False

Returns:

Type	Description
ResolvedConfigDraft	Resolved TOML-side state and the merged mutable config draft built from it.

Source code in src/topmark/config/resolution/bridge.py

def resolve_toml_sources_and_build_mutable_config(
    *,
    input_paths: Iterable[Path] | None = None,
    extra_config_files: Iterable[Path] | None = None,
    strict: bool | None = None,
    no_config: bool = False,
) -> ResolvedConfigDraft:
    """Resolve TOML sources once and build the merged config draft from them.

    This helper is the preferred bridge between TOML-side source resolution and
    config-layer merge for callers that need both the resolved TOML-side state
    and the merged mutable config draft.

    Args:
        input_paths: Optional discovery anchors. The first path is used to pick
            the project-discovery starting directory. If it points to a file,
            its parent directory is used. If omitted, discovery falls back to
            the current working directory.
        extra_config_files: Explicit config files to merge after discovered
            layers. Later files override earlier ones.
        strict: Optional explicit override for the TOML-side
            strictness preference that later governs staged
            staged config-loading validation.
        no_config: If `True`, skip all discovered config layers (user +
            project) and only use built-in defaults plus any explicit extra
            config files.

    Returns:
        Resolved TOML-side state and the merged mutable config draft built from it.
    """
    resolved: ResolvedTopmarkTomlSources = resolve_topmark_toml_sources(
        input_paths=input_paths,
        extra_config_files=extra_config_files,
        strict=strict,
        no_config=no_config,
    )
    return ResolvedConfigDraft(
        resolved=resolved,
        draft=build_mutable_config_from_resolved_toml_sources(resolved),
    )

resolve_default_template_and_build_mutable_config

resolve_default_template_and_build_mutable_config()

Resolve the bundled init template and build its config draft.

This helper is intended for machine-readable topmark config init output. It consumes the bundled template text, or the generated fallback text when the bundled template cannot be read, and replays that fallback error into the returned config draft diagnostics.

Human output should continue to render the template text directly so comments and formatting are preserved.

Returns:

Type	Description
ResolvedConfigDraft	Resolved TOML-side state and mutable config draft built from the bundled
ResolvedConfigDraft	init template.

Source code in src/topmark/config/resolution/bridge.py

def resolve_default_template_and_build_mutable_config() -> ResolvedConfigDraft:
    """Resolve the bundled init template and build its config draft.

    This helper is intended for machine-readable `topmark config init` output.
    It consumes the bundled template text, or the generated fallback text when
    the bundled template cannot be read, and replays that fallback error into
    the returned config draft diagnostics.

    Human output should continue to render the template text directly so
    comments and formatting are preserved.

    Returns:
        Resolved TOML-side state and mutable config draft built from the bundled
        init template.
    """
    diagnostics: MutableDiagnosticLog = MutableDiagnosticLog()
    template_text: DefaultTomlTemplateText = load_default_topmark_template_toml_text()
    toml_text: str = template_text.toml_text
    template_error: Exception | None = template_text.error

    if template_error is not None:
        diagnostics.add_error(str(template_error))

    doc: tomlkit.TOMLDocument = tomlkit.parse(toml_text)
    table: TomlTable = toml_table_from_mapping(as_object_dict(doc.unwrap()))
    return _resolve_single_builtin_toml_table_and_build_mutable_config(
        table=table,
        source_path=BUNDLED_TEMPLATE_TOML_SOURCE,
        load_diagnostics=diagnostics,
    )

resolve_default_table_and_build_mutable_config

resolve_default_table_and_build_mutable_config()

Resolve the built-in default TOML table and build its config draft.

This helper is intended for machine-readable topmark config defaults output. It uses the code-defined canonical default TOML table rather than the annotated starter template used by topmark config init.

Returns:

Type	Description
ResolvedConfigDraft	Resolved TOML-side state and mutable config draft built from the canonical
ResolvedConfigDraft	default TOML table.

Source code in src/topmark/config/resolution/bridge.py

def resolve_default_table_and_build_mutable_config() -> ResolvedConfigDraft:
    """Resolve the built-in default TOML table and build its config draft.

    This helper is intended for machine-readable `topmark config defaults`
    output. It uses the code-defined canonical default TOML table rather than
    the annotated starter template used by `topmark config init`.

    Returns:
        Resolved TOML-side state and mutable config draft built from the canonical
        default TOML table.
    """
    return _resolve_single_builtin_toml_table_and_build_mutable_config(
        table=build_default_topmark_toml_table(),
        source_path=BUILTIN_DEFAULTS_TOML_SOURCE,
    )