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
  • Project-chain discovery starts from the discovery anchor and walks upward using the resolved anchor path, so symlinked working directories or input anchors are followed to their filesystem targets before project configs are discovered.
  • 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).
  • Configuration-source identity is based on the resolved configuration-file target. Symlink spellings are not preserved for precedence, scope, applicability, or layered provenance.
  • Configuration-source identity is distinct from processing-target identity. Runtime filesystem-processing commands evaluate selected processing paths separately, including filesystem-identity normalization and eligibility checks such as hard-link policy.
  • 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.

When strict validation fails, TopMark exits with CONFIG_ERROR. The diagnostics that triggered the failure remain visible in human-readable and machine-readable output formats.

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.

For file-backed configuration sources, layered provenance reports the resolved configuration target used for configuration-source identity. If a configuration file is loaded through a symlink, precedence, scope evaluation, and provenance operate on the resolved target rather than the symlink spelling.

Hard-link processing policy does not affect configuration discovery, layered provenance, configuration precedence, scope evaluation, or applicability evaluation. It is enforced later for runtime filesystem-processing targets selected by commands such as check, strip, and probe.

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. configuration-source identity normalization
  3. workspace-root and configuration-discovery anchoring
  4. staged configuration-loading validation
  5. layered configuration deserialization and merging
  6. runtime configuration resolution
  7. runtime overlay application
  8. runtime policy evaluation
  9. filesystem-identity evaluation
  10. processing-path selection
  11. runtime pipeline gatekeeping and execution

Configuration-source identity and filesystem identity are intentionally distinct.

File-backed configuration sources are normalized to resolved configuration targets before precedence, scope applicability, and layered provenance evaluation. Runtime file processing similarly operates on selected processing paths derived from filesystem-identity evaluation. Workspace-root discovery and configuration-discovery anchoring are evaluated independently and may traverse resolved filesystem locations when determining configuration search roots.

If multiple discovered or explicit configuration entries resolve to the same configuration-source identity, TopMark retains only the highest-precedence occurrence for configuration layering and provenance evaluation.

Filesystem-identity evaluation includes:

  • filesystem-identity normalization (for example symlink-path normalization and processing-path selection); and
  • filesystem-identity eligibility checks (for example hard-link policy enforcement).

These normalization stages occur before runtime policy evaluation and pipeline execution.

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

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

Configuration discovery, workspace-root anchoring, precedence evaluation, configuration-source identity normalization, and scope applicability are completed before the effective runtime configuration is frozen.

Workspace-root anchoring handles symlinked discovery anchors before project-chain discovery. Configuration-source identity normalization then handles configuration path spellings, such as symlinked configuration files. Both are separate from runtime processing-target eligibility checks, such as hard-link policy enforcement for selected processing paths.

Configuration flow at a glance

flowchart LR
    A["Resolve TOML sources<br/>(defaults, user, project from resolved anchor, --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

For file-backed configuration sources, configuration-source identity is established before layered configuration merging. Different path spellings that resolve to the same configuration-file target therefore contribute to the same effective configuration source.

This configuration-source identity behavior mirrors only the path-spelling normalization part of runtime processing-target identity. Runtime processing-target eligibility checks are not part of configuration merging and are not represented in the effective configuration snapshot.

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