topmark.api

topmark.api

Public TopMark API (stable surface).

This package provides a small, typed façade for running TopMark programmatically.

Design goals: - Provide a stable entry point for integrations without requiring the CLI (Click). - Keep inputs JSON/TOML-friendly (plain mappings) while maintaining strict internal typing. - Return machine-friendly results (dataclasses / TypedDicts) without ANSI formatting.

Stability policy: - Symbols exported by topmark.api via __all__ are the supported surface, including stable re-exports such as Outcome. - Adding optional parameters with defaults is allowed in minor releases. - Removing/renaming symbols or changing return shapes is a breaking change. - Low-level runtime helpers may expose ApiPipelineRun when callers need resolved config, selected files, processing contexts, and a fatal pipeline-level exit code before conversion into public result DTOs.

High-level concepts: - Recognized file types exist in the file type registry. - Supported file types are recognized and have a processor bound. - Diagnostics returned by the API are JSON-friendly and use string severities: "info", "warning", "error". - Pipeline outcome values are shared core primitives re-exported here as Outcome for public API convenience. - High-level commands return stable result DTOs such as RunResult and ProbeRunResult. Lower-level runtime orchestration returns ApiPipelineRun for integrations that intentionally work with processing contexts.

Configuration contract: - Public pipeline functions (probe(), check(), strip()) accept an optional plain mapping (mirroring the TOML/pyproject structure) or an immutable FrozenConfig. - Passing config=None triggers layered discovery (defaults → user → project) using the same rules as the CLI. - The internal MutableConfig builder is not part of the public API; it exists to perform discovery/merging and is frozen immediately into an immutable FrozenConfig before execution.

Example

from topmark import api

config = {
    "fields": {
        "project": "TopMark",
        "license": "MIT",
    },
    "header": {
        "fields": [
            "file",
            "project",
            "license",
        ]
    },
    "formatting": {
        "align_fields": True,
    },
    "files": {
        "include_file_types": ["python"],
        "exclude_patterns": [".venv"],
    },
    "policy_by_type": {
        "python": {
            "allow_header_in_empty_files": True,
        },
    },
}

run: api.RunResult = api.check(
    ["src"],
    config=config,
    diff=True,
    report="actionable",
)

assert run.summary.get("unchanged", 0) >= 0

ApiPipelineRun dataclass

ApiPipelineRun(
    *, effective_cfg, file_list, results, exit_code
)

Resolved runtime state and pipeline results for one API execution.

This value object is the low-level orchestration result returned by the internal API runtime helpers. It exposes the fully resolved runtime config, the selected file list, the produced processing contexts, and any fatal pipeline-level exit code.

Attributes:

Name	Type	Description
effective_cfg	FrozenConfig	Final runtime config after layered discovery, runtime overlays, and execution-scoped adjustments.
file_list	list[Path]	Files selected for pipeline execution after discovery and filtering.
results	list[ProcessingContext]	Processing contexts produced by pipeline execution. For probe runs, this may also include synthetic contexts representing missing or filtered explicit inputs.
exit_code	ExitCode | None	Fatal pipeline-level exit code, if one was encountered.

Notes

This object intentionally exposes internal processing contexts rather than stable public DTOs. Higher-level public API helpers are expected to normalize these contexts into stable machine-facing result objects such as RunResult and ProbeRunResult.

DiagnosticEntry

Bases: TypedDict

JSON-friendly diagnostic entry for API consumers.

Notes

• Uses string literal levels for stability and easy serialization.
• Mirrors internal pipeline diagnostics but does not expose internal enums/classes.

FileResult dataclass

FileResult(
    *,
    path,
    outcome,
    diff,
    bucket_key=None,
    bucket_label=None,
)

Result for a single file after pipeline execution and view filtering.

This object is a pure data carrier intended for machine consumption (JSON, NDJSON, API callers). It deliberately contains no pre-rendered human-facing messages or ANSI formatting.

Attributes:

Name	Type	Description
path	Path	Absolute or workspace-relative path to the file.
outcome	Outcome	Stable, high-level outcome bucket describing the file's final state (e.g. UNCHANGED, WOULD_UPDATE, ERROR).
diff	str | None	Unified diff as a string when available. None if diffs were not requested or are not applicable.
bucket_key	str | None	Public bucket identifier corresponding to the outcome classification (typically outcome.value). This key is stable and suitable for aggregation and machine processing.
bucket_label	str | None	Human-oriented explanation for the bucket, derived from the first-seen classification reason. Intended for display purposes only.

Notes

• outcome is the authoritative semantic signal and is stable across versions.
• bucket_key mirrors the public outcome value and exists to support uniform bucketing and summaries.
• bucket_label is best-effort, may change between versions, and should not be relied upon for programmatic decisions.
• Any human-readable or colorized summaries must be generated by presentation helpers (e.g. in topmark.presentation), not by the API.

FileTypeInfo

Bases: TypedDict

Stable metadata about a registered file type.

This is the JSON-friendly public view returned by registry-facing API helpers. It describes discovery metadata, binding state, and the effective placement policy for the file type.

Attributes:

Name	Type	Description
local_key	str	File type local key (compatibility identifier).
namespace	str	Namespace that owns the file type.
qualified_key	str	Canonical file type key.
description	str	Human description.
bound	bool	Whether the file type currently has an effective processor binding.
extensions	Sequence[str]	Known filename extensions (without dots).
filenames	Sequence[str]	Exact filenames matched (for example, "Makefile").
patterns	Sequence[str]	Full-match regular-expression patterns.
skip_processing	bool	Whether the type is discoverable but not processed.
has_content_matcher	bool	Whether a content matcher exists.
has_insert_checker	bool	Whether a header insert checker exists.
policy	FileTypePolicyInfo	Policy/strategy for header placement.

ProbeCandidateInfo dataclass

ProbeCandidateInfo(
    *,
    file_type,
    qualified_key,
    score,
    selected,
    rank,
    matched_by,
)

Stable public view of one file-type resolution candidate.

Attributes:

Name	Type	Description
file_type	str	Public file type identifier for the candidate.
qualified_key	str	Canonical namespaced file type key.
score	int	Resolver score used only for explanatory ordering within this probe result. The exact scoring algorithm is internal and may evolve.
selected	bool	Whether this candidate was selected as the effective file type.
rank	int	One-based rank after resolver tie-breaking.
matched_by	tuple[str, ...]	Stable string tokens describing which resolver signals matched, such as extension, filename, pattern, content, or content_error.

Notes

This object deliberately omits internal registry objects, matcher instances, and raw scoring details. Consumers should treat selected, rank, and matched_by as the stable decision signals; score is explanatory only.

ProbeFileResult dataclass

ProbeFileResult(
    *,
    path,
    status,
    reason,
    selected_file_type,
    selected_processor,
    candidates,
)

Probe result for a single path.

Attributes:

Name	Type	Description
path	Path	Path that was probed, reported as missing, or reported as filtered during explicit-input discovery.
status	str	Stable string status for the probe result, derived from the internal resolver status without exposing internal enum classes.
reason	str	Stable string reason describing why the path reached that status.
selected_file_type	str | None	Public local identifier of the selected file type, if one resolved successfully.
selected_processor	str | None	Public local identifier of the selected processor, if one is bound for the selected file type.
candidates	Sequence[ProbeCandidateInfo]	Ordered, normalized candidate list considered during file-type resolution. Empty for missing or discovery-filtered paths.

Notes

status and reason are plain strings to keep the public API JSON-friendly and independent from internal resolver enum classes. Candidate internals are reduced to ProbeCandidateInfo records.

ProbeRunResult dataclass

ProbeRunResult(
    *,
    files,
    summary,
    had_errors,
    diagnostics=None,
    diagnostic_totals=None,
)

Aggregate result of a TopMark probe run.

Attributes:

Name	Type	Description
files	Sequence[ProbeFileResult]	Ordered sequence of per-path probe results.
summary	Mapping[str, int]	Mapping from public probe status strings to counts for files.
had_errors	bool	True when any unfiltered result represents a hard error.
diagnostics	dict[str, list[DiagnosticEntry]] | None	Optional mapping from file path to public diagnostic entries for the probe result set.
diagnostic_totals	DiagnosticTotals | None	Aggregate diagnostic counts across the probe result set.

Notes

This is the public API shape for topmark.api.probe(). It intentionally exposes resolution as stable primitive values and DTOs instead of returning ProcessingContext, ResolutionProbeResult, or other internal structures.

ProcessorInfo

Bases: TypedDict

Stable metadata about a registered header processor.

This is the JSON-friendly public view returned by registry-facing API helpers. It describes the processor's identity, binding state, and comment delimiter metadata.

Attributes:

Name	Type	Description
local_key	str	Processor local key (compatibility identifier).
namespace	str	Namespace that owns the processor.
qualified_key	str	Canonical processor key.
description	str	Human description.
bound	bool	Whether the processor currently participates in at least one effective file-type binding.
line_indent	str	Line comment indent (if applicable).
line_prefix	str	Line comment prefix (if applicable).
line_suffix	str	Line comment suffix (if applicable).
block_prefix	str	Block comment prefix (if applicable).
block_suffix	str	Block comment suffix (if applicable).

RunResult dataclass

RunResult(
    *,
    files,
    summary,
    had_errors,
    skipped=0,
    written=0,
    failed=0,
    bucket_summary=None,
    diagnostics=None,
    diagnostic_totals=None,
    diagnostic_totals_all=None,
)

Aggregate result of a TopMark run after view-level filtering.

This structure summarizes per-file results, outcome counts, and diagnostics in a JSON-friendly form suitable for API consumers and machine-readable output formats.

Attributes:

Name	Type	Description
files	Sequence[FileResult]	Ordered sequence of per-file results after report-scope filtering.
summary	Mapping[str, int]	Mapping from public outcome values (Outcome.value) to counts for the returned files.
had_errors	bool	True if any file encountered an error during processing, computed from the unfiltered result set so that real errors are not hidden by report filtering.
skipped	int	Number of results excluded by report-scope filtering.
written	int	Number of files successfully written (only meaningful when apply=True; otherwise 0).
failed	int	Number of files that failed to write (only meaningful when apply=True; otherwise 0).
bucket_summary	Mapping[str, int] | None	Optional summary aggregated by bucket key rather than by outcome alone. When present, this is primarily intended to support CLI-style reporting.
diagnostics	dict[str, list[DiagnosticEntry]] | None	Optional mapping from file path to public diagnostic entries for the returned view.
diagnostic_totals	DiagnosticTotals | None	Aggregate diagnostic counts across the returned (filtered) view.
diagnostic_totals_all	DiagnosticTotals | None	Aggregate diagnostic counts across the entire run (pre report filtering).

Notes

• summary is strictly derived from files and reflects only the filtered view.
• bucket_summary is optional and more presentation-oriented than summary; consumers should not assume it is always present.
• No fields in this object contain formatted or colorized output. Presentation is the responsibility of higher layers (CLI or UI).

Outcome

Bases: str, Enum

Stable per-file outcome bucket used by the public API.

Values mirror the high-level outcome categories exposed by the CLI and API. Consumers should prefer Outcome (and Outcome.value) for programmatic decisions rather than relying on human-facing labels.

VersionInfo dataclass

VersionInfo(*, version_text, version_format, err)

Prepared payload for topmark version (and the API equivalent).

VersionInfo is part of the stable API surface.

Attributes:

Name	Type	Description
version_text	str	TopMark version text in the requested output format.
version_format	VersionFormatLiteral	The format of version_text ("pep440" or "semver").
err	Exception | None	Conversion error when semver=True and conversion fails. In that case version_text remains the original PEP 440 string and version_format is "pep440".

check

check(
    paths,
    *,
    apply=False,
    diff=False,
    config=None,
    policy=None,
    policy_by_type=None,
    include_file_types=None,
    exclude_file_types=None,
    report="all",
    prune_views=False,
)

Validate or apply TopMark headers for the given paths.

This is the programmatic equivalent of the CLI topmark check. It preserves the same discovery behavior when config is None and accepts optional policy overlays that are applied after discovery, before the pipeline runs.

Parameters:

Name	Type	Description	Default
paths	Iterable[Path | str]	Files and/or directories to process. Globs are allowed by the caller; TopMark will recurse and filter internally.	required
apply	bool	If True, write changes in-place; otherwise perform a dry run.	False
diff	bool	If True, include unified diffs for changes where applicable.	False
config	Mapping[str, object] | None	Optional plain mapping or immutable FrozenConfig to seed configuration. When None, project discovery and layered merge are performed.	None
policy	PublicPolicy | None	Optional global policy overrides in the public API shape. These are merged after discovery using standard policy resolution.	None
policy_by_type	Mapping[str, PublicPolicy] | None	Optional per-type policy overrides in the public API shape, merged after discovery.	None
include_file_types	Sequence[str] | None	Optional whitelist of file type identifiers to restrict discovery.	None
exclude_file_types	Sequence[str] | None	Optional blacklist of file type identifiers to exclude from discovery.	None
report	PublicReportScopeLiteral	Reporting scope for the returned API view (actionable, noncompliant, or all).	'all'
prune_views	bool	If True, trim heavy views after the run (keeps summaries).	False

Returns:

Type	Description
RunResult	Filtered per-file outcomes, counts, diagnostics, and write stats.

Notes

Reporting/view filtering is handled by the public view layer. It does not change which files are eligible to be written when apply=True.

Source code in src/topmark/api/commands/pipeline.py

def check(
    paths: Iterable[Path | str],
    *,
    apply: bool = False,
    diff: bool = False,
    config: Mapping[str, object] | None = None,
    policy: PublicPolicy | None = None,
    policy_by_type: Mapping[str, PublicPolicy] | None = None,
    include_file_types: Sequence[str] | None = None,
    exclude_file_types: Sequence[str] | None = None,
    report: PublicReportScopeLiteral = "all",
    prune_views: bool = False,
) -> RunResult:
    """Validate or apply TopMark headers for the given paths.

    This is the programmatic equivalent of the CLI `topmark check`. It preserves
    the same discovery behavior when `config` is `None` and accepts optional
    policy overlays that are applied after discovery, before the pipeline runs.

    Args:
        paths: Files and/or directories to process. Globs are allowed by the caller;
            TopMark will recurse and filter internally.
        apply: If `True`, write changes in-place; otherwise perform a dry run.
        diff: If `True`, include unified diffs for changes where applicable.
        config: Optional plain mapping or immutable
            [`FrozenConfig`][topmark.config.model.FrozenConfig] to seed configuration.
            When `None`, project discovery and layered merge are performed.
        policy: Optional global policy overrides in the public API shape. These
            are merged after discovery using standard policy resolution.
        policy_by_type: Optional per-type policy overrides in the public API shape,
            merged after discovery.
        include_file_types: Optional whitelist of file type identifiers to restrict discovery.
        exclude_file_types: Optional blacklist of file type identifiers to exclude from discovery.
        report: Reporting scope for the returned API view (`actionable`,
            `noncompliant`, or `all`).
        prune_views: If `True`, trim heavy views after the run (keeps summaries).

    Returns:
        Filtered per-file outcomes, counts, diagnostics, and write stats.

    Notes:
        Reporting/view filtering is handled by the public view layer. It does not
        change which files are eligible to be written when `apply=True`.
    """
    # Choose the concrete content-processing pipeline variant.
    pipeline: Sequence[Step[ProcessingContext]] = select_pipeline(
        "check",
        apply=apply,
        diff=diff,
    )

    # Run the pipeline; runtime helpers handle config discovery, policy overlays,
    # file-list resolution, per-path config, and pipeline execution.

    run_options: RunOptions = RunOptions(
        apply_changes=apply,
        prune_views=prune_views,
        keep_diff_view=diff,
    )

    api_run: ApiPipelineRun = run_pipeline(
        pipeline=pipeline,
        paths=paths,
        run_options=run_options,
        base_config=config,  # None preserves discovery; mapping/FrozenConfig is honored.
        include_file_types=include_file_types,
        exclude_file_types=exclude_file_types,
        policy=policy,
        policy_by_type=policy_by_type,
    )

    # Use common content-processing result assembly with check write statuses.
    update_statuses: set[PlanStatus] = {
        PlanStatus.INSERTED,
        PlanStatus.REPLACED,
        PlanStatus.REMOVED,
    }

    report_scope: ReportScope = _resolve_public_report_scope(report)

    return finalize_run_result(
        results=api_run.results,
        file_list=api_run.file_list,
        apply=apply,
        report_scope=report_scope,
        would_change=effective_would_add_or_update,
        update_statuses=update_statuses,
        encountered_exit_code=api_run.exit_code,
    )

probe

probe(
    paths,
    *,
    config=None,
    policy=None,
    policy_by_type=None,
    include_file_types=None,
    exclude_file_types=None,
    prune_views=False,
)

Explain how paths resolve to TopMark file types and processors.

This is the programmatic equivalent of the CLI topmark probe. It runs the read-only probe pipeline and returns a stable public view of file-type resolution, selected processors, and normalized candidate information.

The returned objects intentionally do not expose internal resolution enums, pipeline contexts, or registry implementation details. Use string fields and ProbeCandidateInfo values for programmatic decisions.

Parameters:

Name	Type	Description	Default
paths	Iterable[Path | str]	Files and/or directories to probe. Globs are allowed by the caller; TopMark will recurse and filter internally.	required
config	Mapping[str, object] | None	Optional plain mapping or immutable FrozenConfig to seed configuration. When None, project discovery and layered merge are performed.	None
policy	PublicPolicy | None	Optional global policy overrides. For probe, this is primarily useful for resolver-affecting options such as allow_content_probe.	None
policy_by_type	Mapping[str, PublicPolicy] | None	Optional per-type policy overrides merged after discovery.	None
include_file_types	Sequence[str] | None	Optional whitelist of file type identifiers to restrict discovery.	None
exclude_file_types	Sequence[str] | None	Optional blacklist of file type identifiers to exclude from discovery.	None
prune_views	bool	If True, trim heavy internal views after the run where applicable. Probe results are built from resolution data, not presentation views.	False

Returns:

Type	Description
ProbeRunResult	Resolved runtime config, selected file list, probe results, and any
ProbeRunResult	fatal pipeline-level exit code.

Notes

probe() is always read-only. It has no apply or diff mode because it explains resolution rather than planning or applying header mutations.

Source code in src/topmark/api/commands/pipeline.py

def probe(
    paths: Iterable[Path | str],
    *,
    config: Mapping[str, object] | None = None,
    policy: PublicPolicy | None = None,
    policy_by_type: Mapping[str, PublicPolicy] | None = None,
    include_file_types: Sequence[str] | None = None,
    exclude_file_types: Sequence[str] | None = None,
    prune_views: bool = False,
) -> ProbeRunResult:
    """Explain how paths resolve to TopMark file types and processors.

    This is the programmatic equivalent of the CLI `topmark probe`. It runs the
    read-only probe pipeline and returns a stable public view of file-type
    resolution, selected processors, and normalized candidate information.

    The returned objects intentionally do not expose internal resolution enums,
    pipeline contexts, or registry implementation details. Use string fields and
    `ProbeCandidateInfo` values for programmatic decisions.

    Args:
        paths: Files and/or directories to probe. Globs are allowed by the caller;
            TopMark will recurse and filter internally.
        config: Optional plain mapping or immutable
            [`FrozenConfig`][topmark.config.model.FrozenConfig] to seed configuration.
            When `None`, project discovery and layered merge are performed.
        policy: Optional global policy overrides. For probe, this is primarily
            useful for resolver-affecting options such as `allow_content_probe`.
        policy_by_type: Optional per-type policy overrides merged after discovery.
        include_file_types: Optional whitelist of file type identifiers to restrict discovery.
        exclude_file_types: Optional blacklist of file type identifiers to exclude from discovery.
        prune_views: If `True`, trim heavy internal views after the run where applicable.
            Probe results are built from resolution data, not presentation views.

    Returns:
        Resolved runtime config, selected file list, probe results, and any
        fatal pipeline-level exit code.

    Notes:
        `probe()` is always read-only. It has no `apply` or `diff` mode because it
        explains resolution rather than planning or applying header mutations.
    """
    # Probe has a single read-only diagnostic pipeline.
    pipeline: Sequence[Step[ProcessingContext]] = select_pipeline(
        "probe",
        apply=False,
        diff=False,
    )
    # Run the probe pipeline; runtime helpers also attach synthetic contexts for
    # missing literals and explicit inputs filtered before probing.

    run_options: RunOptions = RunOptions(
        apply_changes=False,
        prune_views=prune_views,
    )

    api_run: ApiPipelineRun = run_probe_pipeline(
        pipeline=pipeline,
        paths=paths,
        run_options=run_options,
        base_config=config,
        include_file_types=include_file_types,
        exclude_file_types=exclude_file_types,
        policy=policy,
        policy_by_type=policy_by_type,
    )

    # Probe has a dedicated public result shape; do not route it through the
    # check/strip finalizer.
    return finalize_probe_result(
        results=api_run.results,
        file_list=api_run.file_list,
        encountered_exit_code=api_run.exit_code,
    )

strip

strip(
    paths,
    *,
    apply=False,
    diff=False,
    config=None,
    policy=None,
    policy_by_type=None,
    include_file_types=None,
    exclude_file_types=None,
    report="all",
    prune_views=False,
)

Remove TopMark headers from files (dry-run or apply).

This is the programmatic equivalent of the CLI topmark strip. When config is None, the function performs the same project discovery as the CLI and then applies optional policy overlays before running the pipeline.

Parameters:

Name	Type	Description	Default
paths	Iterable[Path | str]	Files and/or directories to process. Globs are allowed.	required
apply	bool	If True, write changes in-place; otherwise perform a dry run.	False
diff	bool	If True, include unified diffs for changes where applicable.	False
config	Mapping[str, object] | None	Optional plain mapping or immutable FrozenConfig to seed configuration. When None, project discovery and layered merge are performed.	None
policy	PublicPolicy | None	Optional global policy overrides in the public API shape. Strip flows are currently policy-agnostic, but this is accepted for forward compatibility.	None
policy_by_type	Mapping[str, PublicPolicy] | None	Optional per-type policy overrides in the public API shape.	None
include_file_types	Sequence[str] | None	Optional whitelist of file type identifiers to restrict discovery.	None
exclude_file_types	Sequence[str] | None	Optional blacklist of file type identifiers to exclude from discovery.	None
report	PublicReportScopeLiteral	Reporting scope for the returned API view (actionable, noncompliant, or all).	'all'
prune_views	bool	If True, trim heavy internal views after the run (keeps summaries).	False

Returns:

Type	Description
RunResult	Resolved runtime config, selected file list, filtered results, and any
RunResult	fatal pipeline-level exit code.

Notes

Reporting/view filtering is handled by the public view layer and does not modify pipeline write decisions.

Source code in src/topmark/api/commands/pipeline.py

def strip(
    paths: Iterable[Path | str],
    *,
    apply: bool = False,
    diff: bool = False,
    config: Mapping[str, object] | None = None,
    policy: PublicPolicy | None = None,
    policy_by_type: Mapping[str, PublicPolicy] | None = None,
    include_file_types: Sequence[str] | None = None,
    exclude_file_types: Sequence[str] | None = None,
    report: PublicReportScopeLiteral = "all",
    prune_views: bool = False,
) -> RunResult:
    """Remove TopMark headers from files (dry-run or apply).

    This is the programmatic equivalent of the CLI `topmark strip`. When `config`
    is `None`, the function performs the same project discovery as the CLI and
    then applies optional policy overlays before running the pipeline.

    Args:
        paths: Files and/or directories to process. Globs are allowed.
        apply: If `True`, write changes in-place; otherwise perform a dry run.
        diff: If `True`, include unified diffs for changes where applicable.
        config: Optional plain mapping or immutable
            [`FrozenConfig`][topmark.config.model.FrozenConfig] to seed configuration.
            When `None`, project discovery and layered merge are performed.
        policy: Optional global policy overrides in the public API shape. Strip
            flows are currently policy-agnostic, but this is accepted for forward
            compatibility.
        policy_by_type: Optional per-type policy overrides in the public API shape.
        include_file_types: Optional whitelist of file type identifiers to restrict discovery.
        exclude_file_types: Optional blacklist of file type identifiers to exclude from discovery.
        report: Reporting scope for the returned API view (`actionable`,
            `noncompliant`, or `all`).
        prune_views: If `True`, trim heavy internal views after the run (keeps summaries).

    Returns:
        Resolved runtime config, selected file list, filtered results, and any
        fatal pipeline-level exit code.

    Notes:
        Reporting/view filtering is handled by the public view layer and does not
        modify pipeline write decisions.
    """
    # Choose the concrete content-processing pipeline variant.
    pipeline: Sequence[Step[ProcessingContext]] = select_pipeline(
        "strip",
        apply=apply,
        diff=diff,
    )

    # Run the pipeline; runtime helpers handle config discovery, policy overlays,
    # file-list resolution, per-path config, and pipeline execution.

    run_options: RunOptions = RunOptions(
        apply_changes=apply,
        prune_views=prune_views,
        keep_diff_view=diff,
    )

    api_run: ApiPipelineRun = run_pipeline(
        pipeline=pipeline,
        paths=paths,
        run_options=run_options,
        base_config=config,  # None preserves discovery; mapping/Config is honored.
        include_file_types=include_file_types,
        exclude_file_types=exclude_file_types,
        policy=policy,
        policy_by_type=policy_by_type,
    )

    # Use common content-processing result assembly with strip write statuses.
    update_statuses: set[PlanStatus] = {
        PlanStatus.REMOVED,
    }

    report_scope: ReportScope = _resolve_public_report_scope(report)

    return finalize_run_result(
        results=api_run.results,
        file_list=api_run.file_list,
        apply=apply,
        report_scope=report_scope,
        would_change=effective_would_strip,
        update_statuses=update_statuses,
        encountered_exit_code=api_run.exit_code,
    )

list_filetypes

list_filetypes()

Return metadata about registered file types.

Returns:

Type	Description
list[FileTypeInfo]	A list of FileTypeInfo dicts (stable, serializable metadata).

Notes

For object-level access, prefer FileTypeRegistry from topmark.registry. This function returns metadata rather than the registry objects themselves.

Source code in src/topmark/api/commands/registry.py

def list_filetypes() -> list[FileTypeInfo]:
    """Return metadata about registered file types.

    Returns:
        A list of `FileTypeInfo` dicts (stable, serializable metadata).

    Notes:
        For object-level access, prefer `FileTypeRegistry` from
        [`topmark.registry`][]. This function returns metadata rather than the
        registry objects themselves.
    """
    return [
        FileTypeInfo(
            local_key=ft.local_key,
            namespace=ft.namespace,
            qualified_key=ft.qualified_key,
            description=ft.description,
            bound=Registry.is_filetype_bound(file_type_id=ft.qualified_key),
            extensions=tuple(ft.extensions),
            filenames=tuple(ft.filenames),
            patterns=tuple(ft.patterns),
            skip_processing=ft.skip_processing,
            has_content_matcher=bool(ft.content_matcher),
            has_insert_checker=bool(ft.pre_insert_checker),
            policy=_build_filetype_policy_info(ft.header_policy),
        )
        for ft in Registry.filetypes().values()
    ]

list_processors

list_processors()

Return metadata about registered header processors.

Returns:

Type	Description
list[ProcessorInfo]	A list of ProcessorInfo dicts (stable, serializable metadata).

Notes

For object-level access, prefer HeaderProcessorRegistry from topmark.registry. This function returns metadata rather than the registry objects themselves.

Source code in src/topmark/api/commands/registry.py

def list_processors() -> list[ProcessorInfo]:
    """Return metadata about registered header processors.

    Returns:
        A list of `ProcessorInfo` dicts (stable, serializable metadata).

    Notes:
        For object-level access, prefer `HeaderProcessorRegistry` from
        [`topmark.registry`][]. This function returns metadata rather than the
        registry objects themselves.
    """
    bound_processor_keys: set[str] = {
        binding.processor.qualified_key
        for binding in Registry.bindings()
        if binding.processor is not None
    }
    items: list[ProcessorInfo] = []
    for qualified_key, proc_def in Registry.processors().items():
        proc_obj: HeaderProcessor = proc_def.processor_class()
        info: ProcessorInfo = ProcessorInfo(
            local_key=getattr(proc_def, "local_key", ""),
            namespace=getattr(proc_def, "namespace", ""),
            qualified_key=qualified_key,
            description=getattr(proc_obj, "description", ""),
            bound=qualified_key in bound_processor_keys,
            line_indent=getattr(proc_obj, "line_indent", "") or "",
            line_prefix=getattr(proc_obj, "line_prefix", "") or "",
            line_suffix=getattr(proc_obj, "line_suffix", "") or "",
            block_prefix=getattr(proc_obj, "block_prefix", "") or "",
            block_suffix=getattr(proc_obj, "block_suffix", "") or "",
        )
        items.append(info)
    return items

get_version_info

get_version_info(*, semver=False)

Return the current TopMark version info.

Source code in src/topmark/api/commands/version.py

def get_version_info(*, semver: bool = False) -> VersionInfo:
    """Return the current TopMark version info."""
    return compute_version_info(semver=semver)

get_version_text

get_version_text()

Return the current TopMark version (string).

Source code in src/topmark/api/commands/version.py

def get_version_text() -> str:
    """Return the current TopMark version (string)."""
    # Convenience string form for UI/logging; structured metadata is in `get_version_info()`.
    return get_version_info(semver=False).version_text

options: heading_level: 1 show_root_heading: true members_order: source filters: - "!^_"