topmark.core.exit_codes¶

Exit codes for the TopMark runtime and CLI.

This module centralizes the exit codes used by the CLI, engine helpers, and tests. TopMark aligns with the BSD sysexits convention where practical so that other tooling can interpret failures consistently. TopMark deliberately avoids assigning semantic runtime meaning to exit code 2 because Click uses it for parser-level usage errors before TopMark command logic can normalize the failure. Dry-run change detection therefore uses WOULD_CHANGE = 3 so scripts can distinguish valid change signals from parser failures by exit code alone.

ExitCode ¶

Bases: IntEnum

Standardized exit codes for the TopMark runtime and CLI.

TopMark follows the BSD sysexits convention where practical so other tooling can interpret failures consistently.

Exit code 2 is reserved for Click-owned parser usage errors, such as unknown options or invalid option values raised before TopMark command logic runs.

TopMark dry-run change detection therefore uses WOULD_CHANGE = 3 so automation can distinguish valid change signals from parser failures by exit code alone.

Attributes:

Name	Type	Description
`SUCCESS`		Successful execution with no errors.
`FAILURE`		Generic failure (non-specific error). Prefer a more specific code if available.
`WOULD_CHANGE`		Dry-run: changes would be made if `--apply` were set.
`USAGE_ERROR`		Command-line invocation error (invalid flags/args). Mirrors BSD `EX_USAGE (64)`.
`ENCODING_ERROR`		Text decoding/encoding error (e.g., UnicodeDecodeError). Mirrors BSD `EX_DATAERR (65)`.
`FILE_NOT_FOUND`		Input path does not exist. Mirrors BSD `EX_NOINPUT (66)`.
`UNSUPPORTED_FILE_TYPE`		Known/unsupported file type encountered (skipped as per policy). Mirrors BSD `EX_UNAVAILABLE (69)`.
`PIPELINE_ERROR`		Internal pipeline failure (processor/step contract violation). Mirrors BSD `EX_SOFTWARE (70)`.
`IO_ERROR`		I/O error reading/writing a file. Mirrors BSD `EX_IOERR (74)`.
`PERMISSION_DENIED`		Insufficient permissions (read/write). Mirrors BSD `EX_NOPERM (77)`.
`CONFIG_ERROR`		Configuration error (missing/invalid/malformed config). Mirrors BSD `EX_CONFIG (78)`.
`VERSION_CONVERSION_ERROR`		Version conversion error (missing/invalid/malformed PEP version identifier, version cannot be converted to SemVer). Mirrors BSD `EX_CONFIG (78)`.
`UNEXPECTED_ERROR`		Unhandled/unknown error (last-resort). Mirrors BSD `EX_SOFTWARE (70)` but kept distinct for clarity.

Notes

Exit code 2 is intentionally not represented here because it is owned by Click parser usage errors, not by TopMark semantic outcomes.