Skip to content

topmark.toml.validation

topmark / toml / validation

Structured TOML schema-validation issues and diagnostic adapters.

This module defines TOML-specific validation issue types used by the static schema layer in topmark.toml.schema. The goal is to keep schema validation structured and machine-friendly while still allowing the existing diagnostic log to receive ordinary Diagnostic entries.

The issue model is intentionally narrow for phase 1 of the TOML schema refactor: - it captures unknown sections and keys, - it distinguishes invalid table shapes, - it preserves section/key/path metadata for later machine-readable output.

TomlDiagnosticCode

Bases: str, Enum

Stable codes for TOML schema-validation diagnostics.

These codes identify the structural kind of TOML validation issue without depending on a human-facing message string.

TomlValidationIssue dataclass 

TomlValidationIssue(
    *,
    code,
    level,
    message,
    path,
    section=None,
    key=None,
    allowed_keys=(),
    suggestion=None,
)

Structured TOML schema-validation issue.

The validator emits these issues first so callers can later map them to the internal diagnostic log, machine-readable output, or test assertions.

Attributes:

Name Type Description
code TomlDiagnosticCode

Stable TOML validation code.
level DiagnosticLevel

Diagnostic severity.
message str

Human-readable diagnostic message.
path tuple[str, ...]

Full TOML path to the offending element.
section str | None

Section name, or None for top-level unknown sections.
key str | None

Offending key name when applicable.
allowed_keys tuple[str, ...]

Candidate keys valid in the relevant context.
suggestion str | None

Suggested replacement key when a close match exists.

add_toml_issues 

add_toml_issues(log, issues)

Record TOML validation issues through the diagnostic log.

This preserves the existing level-specific logging behavior by routing each issue through the corresponding MutableDiagnosticLog helper.

Parameters:

Name Type Description Default
log MutableDiagnosticLog

Mutable diagnostic log receiving the TOML validation issues.

 required
issues Iterable[TomlValidationIssue]

Structured TOML validation issues to record.

 required

Raises:

Type Description
RuntimeError

If an invalid diagnostic level was provided.
Source code in src/topmark/toml/validation.py 
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def add_toml_issues(
    log: MutableDiagnosticLog,
    issues: Iterable[TomlValidationIssue],
) -> None:
    """Record TOML validation issues through the diagnostic log.

    This preserves the existing level-specific logging behavior by routing each
    issue through the corresponding
    [`MutableDiagnosticLog`][topmark.diagnostic.model.MutableDiagnosticLog] helper.

    Args:
        log: Mutable diagnostic log receiving the TOML validation issues.
        issues: Structured TOML validation issues to record.

    Raises:
        RuntimeError: If an invalid diagnostic level was provided.
    """
    for issue in issues:
        msg: str = issue.message
        lvl: DiagnosticLevel = issue.level
        if lvl == DiagnosticLevel.INFO:
            log.add_info(msg)
        elif lvl == DiagnosticLevel.WARNING:
            log.add_warning(msg)
        elif lvl == DiagnosticLevel.ERROR:
            log.add_error(msg)
        else:
            # Defensive guard
            raise RuntimeError(f"Invalid diagnostic level {lvl}")