Skip to content

Header placement rules

TopMark is comment-aware and places header blocks according to resolved file type identities and header-processor semantics.

Different file types use different comment syntaxes and placement rules. TopMark preserves those conventions while keeping insertion and update behavior deterministic.

Configuration-loading strictness (for example through --strict or strict) does not affect header-placement semantics. It controls only whether a run proceeds when staged configuration-loading validation warnings are present.

Header placement rules apply only after a file has passed filesystem-identity evaluation, runtime applicability evaluation, and runtime processor resolution. File-type-specific runtime policy overrides configured through policy_by_type may influence runtime mutation eligibility and insertion behavior, but the selected header processor controls the concrete comment syntax and placement behavior.

Configuration discovery is evaluated before these runtime header-placement stages. Project-chain configuration sources are discovered from the resolved discovery anchor before filesystem-identity evaluation, processor resolution, policy evaluation, or header placement begins.

Note

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

Note

Path representation

TopMark serializes machine-readable filesystem path fields with POSIX / separators on all platforms.

Path serialization is a presentation contract and is distinct from filesystem identity.

TopMark first determines the selected processing path for the filesystem target being processed and then serializes that processing path according to the machine-output contract.

This contract applies to:

  • header metadata path fields;
  • processing machine-output payloads;
  • probe machine-output payloads;
  • configuration machine-output payloads; and
  • TOML/config provenance payloads.

Examples:

real/file.py
./real/file.py
link-to-file.py

may refer to the same filesystem identity and therefore produce the same serialized processing path.

TopMark's machine-readable path fields remain path-based and are derived from the selected processing path for each processing target.

Filesystem identity policy is a separate concern from path serialization. TopMark may apply additional filesystem-identity rules when determining whether a processing target is eligible for processing. For example, selected hard-linked files are detected using device/inode identity and are reported as unsupported processing targets. Such checks do not alter the serialized path values emitted in machine-readable output.

Human-facing output follows display-path policy instead:

  • CLI and Markdown reports may use the host platform's native path representation;
  • STDIN-backed processing displays the logical --stdin-filename when available; and
  • unified diff file labels are human-facing display labels, not machine-readable path fields.

Synthetic configuration-source identifiers (for example built-in defaults) are serialized as stable labels rather than filesystem paths.

Note

File type identities are bound to header processors, and each processor defines how headers are detected, inserted, updated, and stripped for the file types bound to it. The generated registry pages list the file types, processors, and bindings supported by TopMark 1.0.2.dev45+g93e96e60f:

Runtime placement model

Runtime placement starts only after configuration discovery has produced the effective layered configuration for the command invocation.

TopMark intentionally separates:

  1. runtime file discovery
  2. filesystem-identity evaluation and processing-path selection
  3. runtime applicability evaluation
  4. runtime file-type probing
  5. runtime processor resolution
  6. runtime policy evaluation
  7. runtime mutation planning
  8. concrete header rendering and placement

Header placement semantics are determined by the selected header processor after runtime probing, policy evaluation, and processor resolution have completed.

The generated header metadata describes the selected processing target rather than the original invocation spelling used to reach that target.

Filesystem-identity normalization resolves equivalent path spellings, such as symlink spellings, to that selected processing target before header metadata is generated. Processing-target eligibility checks, such as hard-link policy, run before placement as well; hard-linked selected processing paths are blocked and do not receive inserted, updated, or stripped headers.

This layered runtime model keeps placement behavior deterministic while preserving stable processor-specific comment syntax and insertion semantics.

Pound-style files

The topmark:pound processor is used for pound-prefixed line-comment formats such as Python, Python stub files, shell scripts, Ruby, Perl, R, Julia, Makefile, Dockerfile, TOML, YAML, INI-style configuration files, environment files, Git metadata files, and Python requirements/constraints files.

Rules:

  • If a shebang is present (e.g., #!/usr/bin/env python3), place the header after the shebang and ensure exactly one blank line between them.
  • If a coding/encoding line follows the shebang (PEP 263 style), place the header after both the shebang and encoding line.
  • Otherwise, place the header at the top of the file.
  • Ensure one trailing blank line after the header block when the next line is not already blank.

Example (Python / shell-style line comments):

#!/bin/bash

# topmark:header:start
#
#   project      : ACME Project
#   file         : script.sh
#   file_relpath : tools/script.sh
#   license      : BSD
#   copyright    : (C) 2025 John Doe
#
# topmark:header:end

echo "Hello, World!"

Slash-style files

The topmark:slash processor is used for C-style line-comment formats such as C, C++, C#, Go, Java, JavaScript, TypeScript, Kotlin, Rust, Swift, JSONC, and VS Code JSONC.

Rules:

  • Place the header at the top of the file.
  • Use // as the line prefix.
  • Ensure one trailing blank line after the header block when the next line is not already blank.

Example (JavaScript / slash-style line comments):

// topmark:header:start
//
//   project      : ACME Project
//   file         : app.js
//   file_relpath : frontend/app.js
//   license      : GPLv3
//   copyright    : (C) 2025 John Doe
//
// topmark:header:end

console.log("Hello, World!");

C-style block-comment files

The topmark:cblock processor is used for C-like block-comment formats such as CSS, SCSS, Less, Stylus, Solidity, and SQL.

Rules:

  • Place the header at the top of the file.
  • Wrap the header in /* ... */.
  • Prefix header content lines with *.
  • Ensure one trailing blank line after the header block when the next line is not already blank.

Example (CSS):

/*
 * topmark:header:start
 *
 *   project      : ACME Project
 *   file         : styles.css
 *   file_relpath : styles/admin/styles.css
 *   license      : MIT
 *   copyright    : (C) 2025 John Doe
 *
 * topmark:header:end
 */

body {
  margin: 0;
}

XML-style files

The topmark:xml processor is used for XML/HTML-style block-comment formats such as XML, XHTML, HTML, SVG, XSL, XSLT, Vue, and Svelte.

Rules:

  • If present, place the header after the XML declaration and DOCTYPE, with one blank line before the header block.
  • Otherwise, place the header at the top of the file.
  • The header uses the file's native comment syntax; for XML/HTML this is an XML-style block comment wrapper.

Example (XML):

<?xml version="1.0" encoding="UTF-8"?>
<!--
topmark:header:start

  project      : ACME Project
  file         : config.xml
  file_relpath : settings/web/config.xml
  license      : BSD
  copyright    : (C) 2025 John Doe

topmark:header:end
-->

<configuration>
  <!-- XML content here -->
</configuration>

Markdown files

The topmark:markdown processor is used for Markdown files. It uses HTML comments like the topmark:xml processor, but handles Markdown as a line-oriented documentation format.

Rules:

  • Place the header at the top of the file.
  • Use an HTML comment block wrapper.
  • Ensure one trailing blank line after the header block when the next line is not already blank.

Example (Markdown):

<!--
topmark:header:start

  project      : ACME Project
  file         : README.md
  file_relpath : README.md
  license      : MIT
  copyright    : (C) 2025 John Doe

topmark:header:end
-->

# Project notes

Placement guarantees

  • Configuration discovery: project-chain configuration files are discovered from the resolved discovery anchor before runtime placement begins.
  • Path serialization: generated header path fields (file_relpath, file_abspath, relpath, and abspath) describe the selected processing target and use POSIX / separators on all platforms.
  • Filesystem-identity safety: files blocked by processing-target eligibility checks, such as hard-linked processing targets, do not reach header rendering or placement.
  • Newline preservation: the inserted header uses the same newline style as the file (LF/CRLF/CR).
  • BOM preservation: if a UTF-8 BOM is present, it is preserved.
  • Idempotency: re-running TopMark on a file with a compliant header produces no runtime changes.
  • Unheaderable file types: some recognized file type identities intentionally have no effective processor binding and are skipped rather than headered, such as JSON files without comments, license text files, and single-token marker files.

See also