Skip to content

Configuration overview

-TopMark supports layered configuration with explicit precedence:

  • Defaults -> User (e.g. $HOME/.config/topmark.toml) -> Project chain (root -> current) -> --config -> CLI
  • Globs declared in config files are resolved relative to the directory of that config file.
  • Globs declared via CLI are resolved relative to the current working directory (invocation site).
  • Path-to-file settings (e.g., exclude_from, files_from) are resolved relative to the declaring config file (or CWD for CLI-provided values).
  • Merge semantics vary by field: runtime behavioral settings usually use nearest-wins semantics, mapping fields usually overlay keys, and discovery inputs usually accumulate across applicable layers.
  • Config-loading behavior (e.g. strict) is resolved from TOML sources ([config] / [tool.topmark.config]) during TOML loading and applied after layered configuration merging; it is not a regular layered configuration field. Effective strictness applies across staged configuration-loading validation logs (see Config-loading behavior).
  • relative_to affects only header metadata (e.g., file_relpath), not discovery.
  • File type identifiers may be written in local form such as python or qualified form such as topmark:python. TopMark normalizes identifiers to canonical qualified file type identities during configuration normalization. For the user-facing contract, see Configuration discovery, precedence, and policy.

Note

[config].strict is a TOML-source-local strictness preference controlling staged configuration-loading validation for the current TOML source.

Effective strictness is evaluated across:

  • TOML-source diagnostics;
  • merged-config diagnostics;
  • runtime applicability diagnostics.

strict is resolved during TOML loading and does not become a layered configuration field.

TopMark also provides an inspection mode via topmark config dump --show-layers that exposes layered configuration provenance. This shows how the effective runtime configuration is constructed from individual TOML sources and runtime CLI overrides, including their original TOML fragments.

During loading, TopMark first validates each whole-source TOML fragment (unknown sections, unknown keys, malformed section shapes, missing known sections, etc.). Only the validated layered configuration fragment is then passed into layered configuration merging.

At the TOML layer, malformed known sections are handled as warning-and-ignore cases, while missing known sections are emitted as INFO diagnostics. This lets callers distinguish absent sections from malformed-present sections before staged configuration-loading validation semantics are applied.

These TOML-source diagnostics are then evaluated together with merged-config and runtime-applicability diagnostics during staged configuration-loading validation.

For the full discovery, precedence, path-resolution, and staged validation contract, see Configuration discovery, precedence, and policy.

Runtime configuration architecture

TopMark intentionally separates:

  1. TOML-source loading
  2. staged configuration-loading validation
  3. layered configuration deserialization and merging
  4. runtime configuration resolution
  5. runtime overlay application
  6. runtime policy evaluation
  7. runtime pipeline gatekeeping and execution

Reporting, API surfaces, and machine-readable output expose a flattened compatibility view derived from these internal runtime stages.

This layered runtime configuration model keeps behavior deterministic while preserving stable configuration, policy, diagnostics, and machine-readable compatibility contracts.

Configuration flow at a glance

flowchart LR
    A["Resolve TOML sources<br/>(defaults, user, project, --config)"]
    B["Validate each whole-source TOML fragment<br/>unknown sections, unknown keys, malformed shapes"]
    C["Extract layered config fragment<br/>source-local sections like [config] and [writer] stay TOML-local"]
    D["Merge layered configuration by precedence<br/>effective MutableConfig state"]
    E["Validate staged configuration-loading diagnostics<br/>TOML-source, merged-config, runtime-applicability"]
    F["Freeze effective FrozenConfig<br/>final runtime configuration snapshot"]
    G["Apply runtime overlays<br/>CLI or API execution intent"]

    A --> B --> C --> D --> E --> F --> G

This reflects the main distinction in TopMark's layered runtime configuration model:

  • TOML sources are validated first at the whole-source TOML layer.
  • Only the validated layered configuration fragment contributes to layered configuration merging.
  • The merged layered result is then validated across staged configuration-loading diagnostics.
  • The validated layered result becomes one immutable effective runtime configuration snapshot.
  • Runtime overlays are then applied for execution-only concerns such as output mode, apply/dry-run behavior, stdin handling, or runtime execution intent.

Start here

See also