Skip to content

User configuration

TopMark runtime configuration may be provided through:

  • topmark.toml
  • pyproject.toml ([tool.topmark])
  • CLI overrides
  • API overlays

Configuration is resolved through layered discovery, normalization, and precedence rules. Higher-precedence layers override lower-precedence layers.

Project-chain discovery starts from a discovery anchor: the first input path, or the current working directory when no input path is provided. That anchor is resolved before TopMark walks upward looking for project configuration files, so symlinked working directories or input anchors follow their filesystem targets for discovery.

For file-backed configuration sources, TopMark determines configuration-source identity using the resolved configuration-file target. Symlink spellings are not preserved for precedence, scope, or applicability evaluation.

Configuration-source identity is distinct from processing-target identity. The hard-link processing policy used by runtime file-processing commands such as check, strip, and probe does not affect configuration discovery, configuration precedence, scope evaluation, or applicability evaluation.

Note

The canonical vocabulary used throughout the documentation is defined in Terminology and Canonical Vocabulary.

Configuration-source identity

TopMark evaluates file-backed configuration sources using configuration-source identity rather than invocation spelling.

Examples such as:

real/topmark.toml
link-to-topmark.toml

may refer to the same configuration source.

Configuration precedence, scope evaluation, layered configuration export, and machine-readable configuration provenance operate on the resolved configuration-file target. If multiple discovered or explicit entries resolve to the same configuration-source identity, TopMark keeps the highest-precedence occurrence and reports that source once in layered provenance. This prevents one physical configuration file from contributing multiple layers through different path spellings or discovery paths.

Note

This behavior mirrors the processing-path contract used for runtime file processing, but the two identity systems are evaluated independently. Configuration-source identity governs configuration loading and precedence, while processing-target identity governs runtime file-processing behavior such as path selection and hard-link policy enforcement.

CLI, configuration, and API value spelling

Configuration keys use consistent naming across the CLI, API, and TOML configuration surfaces. Some options accept predefined multi-word values such as add_only or whitespace_empty.

TopMark uses different spelling conventions depending on the interface: CLI examples prefer hyphenated forms for readability, while TOML configuration, Python API values, and machine-readable output use canonical underscore forms.

Note

CLI spelling vs configuration/API spelling

TopMark uses hyphenated spelling for CLI option names:

topmark check --header-mutation-mode=add-only

For multi-word option values, the CLI accepts both hyphenated and canonical underscore forms:

topmark check --header-mutation-mode=add-only
topmark check --header-mutation-mode=add_only

TOML configuration, Python API values, and machine-readable output use the canonical underscore form:

[policy]
header_mutation_mode = "add_only"

CLI option names themselves do not accept underscores. Use --header-mutation-mode, not --header_mutation_mode.

Unless otherwise noted, configuration and policy values shown throughout this page use the canonical TOML/API/machine-readable underscore form.

File type identifiers

TopMark accepts file type identifiers in local form, such as python, or qualified form, such as topmark:python.

Local identifiers are accepted only when unambiguous. Internally, TopMark normalizes identifiers to canonical qualified file type identities before filtering, runtime resolution, policy evaluation, diagnostics, and registry lookup.

See file-type filtering for the full identifier contract.

File type identifiers participate in stable runtime behavior such as:

  • include_file_types
  • exclude_file_types
  • policy_by_type
  • CLI file-type filters
  • API file-type filters and policy overlays

File-type filters

File-type filters allow restricting runtime processing to a selected subset of file types.

Example using local identifiers:

[files]
include_file_types = ["python", "markdown"]

Equivalent configuration using canonical qualified keys:

[files]
include_file_types = ["topmark:python", "topmark:markdown"]

Exclude filters work the same way:

[files]
exclude_file_types = ["topmark:yaml"]

[NOTE] Internally, TopMark normalizes configured file type identifiers to canonical qualified identities before filtering, runtime resolution, policy evaluation, diagnostics, and registry lookup.

Per-file-type policy

policy_by_type allows file-type-specific policy overrides for selected file types.

Example using a local identifier:

[policy_by_type.python]
header_mutation_mode = "update_only"

Equivalent configuration using canonical qualified keys:

[policy_by_type."topmark:python"]
header_mutation_mode = "update_only"

Both forms are accepted when the local identifier resolves unambiguously.

Internally, TopMark stores and resolves per-file-type policies using canonical qualified file type identities.

Example: Different policy per file type

[policy]
header_mutation_mode = "add_only"

[policy_by_type."topmark:python"]
header_mutation_mode = "update_only"

[policy_by_type.markdown]
allow_content_probe = false

In this example:

  • the global default policy uses add_only
  • Python files override this with update_only
  • Markdown files disable runtime content probing

Ambiguous identifiers

When more than one registered file type shares the same local identifier, TopMark requires the canonical qualified form.

For example, if both:

  • topmark:python
  • acme:python

are registered, then:

include_file_types = ["python"]

is ambiguous.

Use:

include_file_types = ["topmark:python"]

instead.

Ambiguous identifiers are ignored diagnostically during configuration normalization and staged configuration-loading validation.

Unknown and malformed identifiers

Unknown identifiers are ignored diagnostically during configuration normalization and staged configuration-loading validation.

Malformed qualified identifiers are also ignored diagnostically during configuration normalization and staged configuration-loading validation.

Examples of malformed identifiers:

:python
topmark:
topmark:python:extra

CLI and API parity

CLI options, TOML configuration, API overlays, and runtime policy evaluation all share the same file type identity semantics.

Examples:

topmark check --include-file-types python .

topmark check --include-file-types topmark:python .

api.check(
    paths=[repo],
    include_file_types=["topmark:python"],
)

Runtime configuration model

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.

Runtime evaluation consumes the effective configuration produced after workspace-root discovery, precedence, normalization, and configuration-source identity resolution have completed.

For configuration files loaded through symlinks, the effective configuration is associated with the resolved configuration target rather than the symlink spelling used to reach it.

Hard-link processing policy is not represented in the runtime configuration model because it is a processing-target eligibility rule evaluated by runtime file-processing commands rather than a configuration-layering concern.

See also