topmark.resolution.probe

topmark / resolution / probe

Probe result contracts for file type resolution diagnostics.

This module defines the immutable value objects returned by resolution probing. The actual probing implementation lives in topmark.resolution.filetypes so it can reuse the same private scoring helpers as effective file type resolution without cross-module private imports.

ResolutionProbeStatus

Bases: str, Enum

Machine-friendly status for the overall probe outcome.

Attributes:

Name	Type	Description
FILTERED		The path was excluded during discovery before file-type probing.
RESOLVED		A file type and processor were successfully selected.
UNSUPPORTED		No file type candidates matched the path.
NO_PROCESSOR		A file type was selected, but no processor was bound.

ResolutionProbeReason

Bases: str, Enum

Machine-friendly reason explaining the probe outcome.

Attributes:

Name	Type	Description
EXCLUDED_BY_PATH_FILTER		The path was filtered by path discovery filters.
EXCLUDED_BY_FILE_TYPE_FILTER		The path was filtered by file-type filters.
EXCLUDED_BY_DISCOVERY_FILTER		The path was filtered out before probing, but the exact discovery filter category was not identified.
SELECTED_HIGHEST_SCORE		The selected file type had the highest score.
SELECTED_BY_TIE_BREAK		Multiple candidates shared the top score and were ordered deterministically by tie-break rules.
NO_CANDIDATES		No file type candidates matched the path.
SELECTED_FILE_TYPE_HAS_NO_BOUND_PROCESSOR		The selected file type has no associated processor binding.

ResolutionProbeMatchSignals dataclass

ResolutionProbeMatchSignals(
    *,
    extension,
    filename,
    pattern,
    content_probe_allowed,
    content_match,
    content_error=None,
)

Probe-visible match signals used while evaluating a file type candidate.

Attributes:

Name	Type	Description
extension	bool	Whether an extension rule matched the path basename.
filename	bool	Whether a filename or path-tail rule matched the path.
pattern	bool	Whether a regular-expression pattern matched the path basename.
content_probe_allowed	bool	Whether the file type content matcher was allowed to run.
content_match	bool	Whether the file type content matcher produced a positive match.
content_error	str | None	Optional exception type name when content probing failed.

ResolutionProbeCandidate dataclass

ResolutionProbeCandidate(
    *,
    qualified_key,
    namespace,
    local_key,
    score,
    selected,
    tie_break_rank,
    match,
)

Probe-visible scored candidate considered by file type resolution.

Attributes:

Name	Type	Description
qualified_key	str	Canonical namespace-qualified file type key.
namespace	str	Candidate file type namespace.
local_key	str	Candidate file type local key.
score	int	Candidate precedence score used by the resolver; higher is better.
selected	bool	Whether this candidate is the effective winner.
tie_break_rank	int	One-based deterministic rank after score and tie-break ordering.
match	ResolutionProbeMatchSignals	Probe-visible match signals for this candidate.

ResolutionProbeSelection dataclass

ResolutionProbeSelection(
    *, qualified_key, namespace, local_key, score=None
)

Probe-visible selected file type or processor identity.

Attributes:

Name	Type	Description
qualified_key	str	Canonical namespace-qualified key.
namespace	str	Selected object namespace.
local_key	str	Selected object local key.
score	int | None	Selected file type score, or None for processor selections.

ResolutionProbeResult dataclass

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

Probe result explaining file type and processor resolution for one path.

Attributes:

Name	Type	Description
path	Path	Filesystem path that was probed.
status	ResolutionProbeStatus	Machine-friendly probe status.
reason	ResolutionProbeReason	Machine-friendly reason for the probe outcome.
candidates	tuple[ResolutionProbeCandidate, ...]	Scored file type candidates in deterministic resolution order. Empty when the path was filtered before probing or when no candidates matched.
selected_file_type	ResolutionProbeSelection | None	Selected file type identity, or None when unsupported or filtered.
selected_processor	ResolutionProbeSelection | None	Selected processor identity, or None when unsupported, unbound, or filtered.