topmark.config.machine.schemas

topmark / config / machine / schemas

Schema objects for config-related machine-readable output.

This module defines small dataclasses used as the typed payload layer for config-related JSON/NDJSON output. Instances are designed to be trivially JSON-serializable via to_dict().

Shape construction and serialization are handled by

• topmark.config.machine.payloads (payload builders)
• topmark.config.machine.envelopes (envelope/record builders)
• topmark.config.machine.serializers (JSON/NDJSON string rendering)

ConfigKey

Bases: str, Enum

Stable config-domain keys for machine-readable payloads.

These keys belong to the config machine-readable output domain and should be used for config-specific JSON payload members and NDJSON container keys. Shared envelope keys remain in topmark.core.machine.schemas, while shared diagnostic keys live in topmark.diagnostic.machine.schemas.

Attributes:

Name	Type	Description
CONFIG		Container key for the effective config payload.
CONFIG_PROVENANCE		Container key for layered config provenance output.
CONFIG_LAYERS		Container key for ordered TOML/config provenance layers.
CONFIG_DIAGNOSTICS		Container key for config diagnostic summary payloads.
CONFIG_FILES		Key for the resolved list of config files.
CONFIG_CHECK		Container key for topmark config check summary payloads.
OK		Boolean success field for config-check summaries.
STRICT		Whether warnings are treated as failures.

ConfigKind

Bases: str, Enum

Stable NDJSON kinds emitted by the config machine-readable output domain.

Attributes:

Name	Type	Description
CONFIG		Effective config record.
CONFIG_PROVENANCE		Config provenance record.
CONFIG_LAYER		Single provenance-layer record.
CONFIG_DIAGNOSTICS		Config diagnostic-summary record.
CONFIG_CHECK		Config-check summary record.

ConfigPayload dataclass

ConfigPayload(
    *,
    fields,
    header,
    formatting,
    files,
    policy,
    policy_by_type,
    writer,
)

JSON-friendly representation of the effective TopMark configuration.

The shape loosely mirrors config_to_topmark_toml_table(include_files=False) but guarantees JSON-serializable values (paths/enums normalized to strings).

Diagnostics are emitted separately via ConfigDiagnosticsPayload.

Attributes:

Name	Type	Description
fields	dict[str, str]	Available header fields and related settings (e.g. relative_to).
header	dict[str, list[str]]	Contains the ordered list of headers fields to render in TopMark headers.
formatting	dict[str, object]	Contains header formatting settings.
files	dict[str, object]	List of files to process.
policy	dict[str, object]	Global, resolved, immutable runtime policy (plain booleans), applied after discovery.
policy_by_type	dict[str, object]	Per-file-type resolved policy overrides (plain booleans), applied after discovery.
writer	dict[str, object]	Runtime writer options resolved from TOML, when configured.

to_dict

to_dict()

Return a JSON-friendly dict of the ConfigPayload instance.

Source code in src/topmark/config/machine/schemas.py

def to_dict(self) -> dict[str, object]:
    """Return a JSON-friendly dict of the `ConfigPayload` instance."""
    return {
        Toml.SECTION_FIELDS: self.fields,
        Toml.SECTION_HEADER: self.header,
        Toml.SECTION_FORMATTING: self.formatting,
        Toml.SECTION_FILES: self.files,
        Toml.SECTION_POLICY: self.policy,
        Toml.SECTION_POLICY_BY_TYPE: self.policy_by_type,
        # Runtime settings
        Toml.SECTION_WRITER: self.writer,
    }

ConfigDiagnosticsPayload dataclass

ConfigDiagnosticsPayload(*, diagnostics, diagnostic_counts)

Machine-readable diagnostics collected while building the FrozenConfig.

This represents the diagnostics for the FrozenConfig as the diagnostics (list) and stats (counts per severity level).

Attributes:

Name	Type	Description
diagnostics	list[MachineDiagnosticEntry]	list of {level, message} entries.
diagnostic_counts	MachineDiagnosticCounts	aggregate per-level counts.

to_dict

to_dict()

Return a JSON-friendly mapping of diagnostics and diagnostic counts.

Returns:

Type	Description
Mapping[str, object]	Mapping with keys "diagnostics" and "diagnostic_counts",
Mapping[str, object]	representing config diagnostics (list[MachineDiagnosticEntry]) and the
Mapping[str, object]	config diagnostic counts per severity level (MachineDiagnosticCounts).

Source code in src/topmark/config/machine/schemas.py

def to_dict(self) -> Mapping[str, object]:
    """Return a JSON-friendly mapping of diagnostics and diagnostic counts.

    Returns:
        Mapping with keys `"diagnostics"` and `"diagnostic_counts"`,
        representing config diagnostics (`list[MachineDiagnosticEntry]`) and the
        config diagnostic counts per severity level (`MachineDiagnosticCounts`).
    """
    return {
        DiagnosticKey.DIAGNOSTICS.value: [d.to_dict() for d in self.diagnostics],
        DiagnosticKey.DIAGNOSTIC_COUNTS.value: self.diagnostic_counts.to_dict(),
    }

ConfigCheckSummary dataclass

ConfigCheckSummary(
    *,
    command,
    subcommand,
    ok,
    strict,
    diagnostic_counts,
    config_files,
)

Summary payload for topmark config check machine-readable output.

Captures the pass/fail outcome of validating the effective configuration under the selected strictness, plus diagnostic counts and the resolved list of config files contributing to the final config.

Emitted as: - JSON: top-level config_check payload in the JSON envelope. - NDJSON: kind="config_check" record (payload container config_check).

Attributes:

Name	Type	Description
command	str	Top-level command name (typically "config").
subcommand	str	Subcommand name (typically "check").
ok	bool	True when validation succeeded under the selected strictness.
strict	bool	True when warnings are treated as failures.
diagnostic_counts	MachineDiagnosticCounts	Counts per diagnostic level.
config_files	list[str]	Resolved list of loaded config file paths.

to_dict

to_dict()

Return a JSON-friendly dict of the ConfigCheckSummary instance.

Returns:

Type	Description
dict[str, object]	JSON-friendly dict representing the ConfigCheckSummary instance.

Source code in src/topmark/config/machine/schemas.py

def to_dict(self) -> dict[str, object]:
    """Return a JSON-friendly dict of the `ConfigCheckSummary` instance.

    Returns:
        JSON-friendly dict representing the `ConfigCheckSummary` instance.
    """
    return {
        MachineKey.COMMAND.value: self.command,
        MachineKey.SUBCOMMAND.value: self.subcommand,
        ConfigKey.OK.value: self.ok,
        ConfigKey.STRICT.value: self.strict,
        DiagnosticKey.DIAGNOSTIC_COUNTS.value: self.diagnostic_counts.to_dict(),
        ConfigKey.CONFIG_FILES.value: self.config_files,
    }