`topmark registry`¶

TopMark exposes a registry command group to inspect the three core registry domains:

Note

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

Subcommands¶

Command	Purpose
`topmark registry filetypes`	Inspect file type identities, matching rules, and policies.
`topmark registry processors`	Inspect registered header processor identities and capabilities.
`topmark registry bindings`	Inspect effective bindings between file types and processors.

These commands reflect the registry split between identities (file types and processors) and bindings, which together define how TopMark performs runtime resolution and processor dispatch.

Input applicability¶

The registry command family is informational and file-agnostic. These commands inspect TopMark's effective composed registry state and do not process project files or perform configuration discovery.

Across all registry subcommands:

positional PATH arguments are rejected as invalid CLI usage
- is not a content-STDIN sentinel
--stdin-filename does not apply
file-list STDIN modes (for example, --files-from -) do not apply
--quiet is not supported; use output-format options for machine-readable output

Configuration discovery does not apply to registry commands.

Runtime overlays and plugin-discovered entries are still reflected in the effective registry view exposed by these commands.

Identity semantics¶

Registry commands expose canonical qualified identities.

Examples:

topmark:python
topmark:markdown

TopMark may still accept local identifiers such as:

python
markdown

in public CLI filters and configuration when unambiguous.

Registry-oriented machine-readable output and effective runtime views use canonical qualified file type identities for deterministic identity handling.

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.

Registry commands expose the effective runtime registry view after registry composition and configuration normalization.

Shared behavior¶

Exit codes¶

All registry subcommands are informational introspection commands:

They exit with SUCCESS (0) on successful execution.
CLI usage errors (invalid or unsupported options) exit with USAGE_ERROR (64).

Registry subcommands do not process project files and therefore do not use file-processing exit codes such as WOULD_CHANGE (2), FILE_NOT_FOUND (66), or IO_ERROR (74).

Invalid positional paths or file-processing input options are reported as CLI usage errors.

See Exit codes for the complete CLI-wide exit-code contract.

Registry model¶

flowchart LR
    FT["File type<br/>(identity)"]
    PR["Header processor<br/>(identity)"]
    BD["Binding<br/>(relationship)"]
    RES[Resolution]

    FT -->|matched by path| RES
    RES -->|selects| BD
    BD -->|maps to| PR

    FT -. defined independently .- PR

This diagram illustrates how file types and header processors are independent identities, while bindings define the effective relationship used during runtime resolution and processor dispatch.

The effective runtime registry view is composed from built-in registry data plus runtime overlays.

Machine-readable output¶

Registry commands emit canonical qualified identities in machine-readable output.

Examples include:

qualified_key
file_type_key
processor_key

These keys are intended for stable joins, comparisons, and tooling integration.

Troubleshooting¶

Unexpected missing file type: ensure plugin discovery completed and that the file type is registered in the effective composed registry.
Unexpected identifier form: registry commands intentionally emit canonical qualified identifiers such as topmark:python.
Unexpected processor relationship: inspect topmark registry bindings to view the effective binding layer.

topmark registry¶