Skip to content

TopMark policy guide

Policies control:

  • whether headers may be inserted or updated
  • how empty files are classified
  • whether file-content probing is allowed
  • how runtime-resolution behavior interacts with safety gates
  • how file-type-specific runtime policy overrides interact with global policy

See also:

TopMark policies control how the runtime pipeline detects file types, classifies empty files, evaluates runtime safety gates, and determines whether headers may be inserted or updated.

Policy settings are part of the layered runtime configuration (FrozenConfig) and are merged according to layered discovery, normalization, precedence, and runtime overlay rules. See:

Policy semantics behave consistently across:

  • discovered config files (topmark.toml or [tool.topmark] in pyproject.toml)
  • TOML configuration overlays
  • command-specific CLI options
  • API overlays
  • effective runtime policy evaluation and runtime resolution

Policy values shown here are part of the public configuration surface.

Note

Internal runtime helper types such as PolicyOverrides and ConfigOverrides are not part of the user-facing CLI or Python API contract. Public callers should use plain mapping-based inputs via config=..., policy=..., and policy_by_type=... when using topmark.api.

In topmark.toml, policy is defined under [policy] and [policy_by_type.<file_type>]. In pyproject.toml, the same settings live under [tool.topmark.policy] and [tool.topmark.policy_by_type.<file_type>].

For canonical file-type identifier semantics, see Configuration discovery, precedence, and policy.

During staged configuration-loading validation, TopMark first validates each whole-source TOML fragment (unknown sections, unknown keys, malformed section shapes, etc.). Only validated layered configuration fragments contribute to runtime policy resolution.

Command-line policy options override resolved config for the current run only.

Policy layers

TopMark resolves policy in this order:

  1. defaults
  2. discovered config files
  3. explicit config overlays
  4. CLI or API overrides

These runtime policy layers are constructed after staged TOML-layer validation. Source-local TOML sections (e.g. [config]) do not participate in runtime policy layering.

Per-file-type policy in policy_by_type is evaluated on top of the global policy section.

CLI, configuration, and API value spelling

Policy configuration keys use the same names across the CLI, API, and TOML configuration. Some policy 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, policy values shown throughout this page use the canonical TOML/API/machine-readable underscore form.

Global policy keys

header_mutation_mode

Controls mutation behavior for topmark check.

Allowed TOML/API values:

  • all: insert missing headers and update existing headers
  • add_only: insert missing headers only; existing headers are not updated
  • update_only: update existing headers only; missing headers are not inserted

This policy affects dry-run reporting, --apply behavior, API result views, and semantic runtime outcome bucketing. It applies only to check; strip and probe reject generated-header mutation controls.

Runtime safety gates still take precedence. Malformed headers, unreadable files, unsupported files, blocked filesystem states, and other non-mutable runtime conditions are not made mutable by header_mutation_mode.

Example:

[policy]
header_mutation_mode = "add_only"

allow_header_in_empty_files

Controls whether TopMark may insert headers into files considered empty under the effective empty_insert_mode.

[policy]
allow_header_in_empty_files = true

empty_insert_mode

Controls which empty or empty-like files are classified as empty for insertion.

This policy affects dry-run reporting, --apply behavior, API result views, and semantic runtime outcome bucketing.

This setting is evaluated together with allow_header_in_empty_files:

  • If allow_header_in_empty_files = false (default), files classified as empty for insertion are treated as unchanged and compliant by default.
  • If allow_header_in_empty_files = true, files classified as empty for insertion may receive generated headers, subject to normal runtime safety gates.

Allowed values:

  • bytes_empty: only true 0-byte files
  • logical_empty: true 0-byte files plus logically empty placeholders (optional BOM, optional horizontal whitespace, and at most one trailing newline)
  • whitespace_empty: true 0-byte files plus any decoded content containing only whitespace or newlines
[policy]
empty_insert_mode = "whitespace_empty"

render_empty_header_when_no_fields is separate. It controls whether TopMark may render an otherwise empty header when no header fields are configured.

Runtime safety gates still take precedence. Unreadable files, unsupported files, malformed headers, blocked filesystem states, and other non-mutable runtime conditions are not made mutable by empty_insert_mode.

render_empty_header_when_no_fields

Controls whether TopMark may insert an otherwise empty header when no header fields are configured.

[policy]
render_empty_header_when_no_fields = true

allow_reflow

Controls whether TopMark may reflow content while inserting or updating a header.

This can reduce strict idempotent runtime rendering behavior in some cases.

[policy]
allow_reflow = true

allow_content_probe

Controls whether runtime file-type detection may inspect file contents when needed.

This policy applies to both check and strip.

[policy]
allow_content_probe = false

Line-ending handling (not a policy)

TopMark's line-ending behavior is fixed for 1.x releases and is not configurable through policy.

  • Only LF (\n), CRLF (\r\n), and CR (\r) are recognized as physical line-ending styles.
  • These styles are preserved across rendering, planning, patching, and writing.
  • Files with mixed recognized newline styles are skipped by the mixed-line-ending guard.

Non-standard Unicode separators such as NEL (U+0085), Line Separator (U+2028), and Paragraph Separator (U+2029) are treated as ordinary content characters. They are not considered line endings and do not affect newline detection or mixed-newline diagnostics.

Some file-type-specific checks (notably XML) may conservatively skip mutation when such characters appear near insertion boundaries due to idempotence concerns. This is a localized safety behavior, not an extension of newline support.

Per-file-type policy

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.

Use policy_by_type.<file_type_id> to override policy for one file type while inheriting unspecified values from the global policy section.

In pyproject.toml, this section is written as [tool.topmark.policy_by_type.<file_type>].

Both local identifiers:

[policy_by_type.python]

and canonical qualified identifiers:

[policy_by_type."topmark:python"]

are supported when the local identifier is unambiguous.

Internally, TopMark resolves per-file-type runtime policy using canonical qualified file type identities.

Example:

[policy]
header_mutation_mode = "all"
allow_content_probe = true

[policy_by_type.python]
header_mutation_mode = "update_only"
allow_header_in_empty_files = true

In this example:

  • Python files inherit allow_content_probe = true
  • Python files override header_mutation_mode
  • Python files additionally allow header insertion into empty files

Equivalent canonical form:

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

Ambiguous, unknown, and malformed identifiers

Per-file-type runtime policy identifiers follow the same rules as filtering and runtime resolution.

Ambiguous local identifiers require the canonical qualified form.

Examples:

python                # accepted when unambiguous
topmark:python        # canonical qualified form

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

Examples:

:python
topmark:
topmark:python:extra

Policy options by command

topmark check

check supports both check-only and shared policy options.

Check-only policy options:

  • --header-mutation-mode
  • --allow-header-in-empty-files / --no-allow-header-in-empty-files
  • --empty-insert-mode
  • --render-empty-header-when-no-fields / --no-render-empty-header-when-no-fields
  • --allow-reflow / --no-allow-reflow

Shared policy options:

  • --allow-content-probe / --no-allow-content-probe

topmark strip

strip supports only shared runtime policy options:

  • --allow-content-probe / --no-allow-content-probe

Header insertion/update policies, including header_mutation_mode, do not apply to strip and are rejected when provided.

Reporting vs policy

Reporting controls human-readable CLI rendering. Policy controls what the runtime pipeline is allowed to do.

Reporting examples:

  • --report actionable: show human-readable per-file entries that would change, changed, failed, or otherwise need attention
  • --report noncompliant: include actionable files plus unsupported file types in human-readable per-file output

Policy example:

  • --header-mutation-mode add-only: allow check to insert missing headers but not update existing headers

These settings are independent and may be combined.

Runtime policy model

TopMark intentionally separates:

  1. staged configuration-loading validation
  2. layered runtime configuration resolution
  3. runtime applicability evaluation
  4. runtime probing and processor resolution
  5. runtime policy evaluation
  6. runtime mutation planning and execution

Machine-readable diagnostics and runtime behavior expose a flattened compatibility view derived from these internal runtime stages while preserving deterministic stable 1.x runtime behavior.