@spec detect_post_structure(String.t()) :: :versioned | :legacy | :empty

Detects whether a post directory uses versioned structure (v1/, v2/, etc.) or legacy structure (files directly in post directory).

Returns:

• :versioned if v1/ or any vN/ directory exists
• :legacy if .phk files exist directly in the directory
• :empty if neither exists

@spec get_latest_published_version(String.t(), String.t()) ::
  {:ok, integer()} | {:error, :not_found}

Gets the latest published version number for a post. Checks each version's primary language file for status.

@spec get_latest_version(String.t(), String.t()) ::
  {:ok, integer()} | {:error, :not_found}

Gets the latest (highest) version number for a post.

@spec get_live_version(String.t(), String.t()) ::
  {:ok, integer()} | {:error, :not_found}

Deprecated: Use get_published_version/2 instead.

@spec get_published_version(String.t(), String.t()) ::
  {:ok, integer()} | {:error, :not_found}

Gets the published version number for a post. Only ONE version can have status: "published" at a time in the variant versioning model. Falls back to checking legacy is_live field for unmigrated posts.

@spec get_version_date(String.t(), String.t(), integer(), String.t()) ::
  String.t() | nil

Gets the version_created_at date for a specific version.

@spec get_version_metadata(String.t(), String.t(), integer(), String.t()) ::
  {:ok, map()} | {:error, :not_found}

Gets the metadata for a specific version and language.

@spec get_version_status(String.t(), String.t(), integer(), String.t()) ::
  String.t() | nil

Gets the status of a specific version for a language.

@spec list_versions(String.t(), String.t()) :: [integer()]

Lists all version numbers for a slug-mode post. Returns sorted list of integers (e.g., [1, 2, 3]). For legacy posts without version directories, returns [1].

@spec load_version_dates(String.t(), String.t(), [integer()], String.t() | nil) :: %{
  required(integer()) => String.t() | nil
}

Loads version_created_at dates for all specified versions. Returns a map of version number => ISO 8601 date string.

@spec load_version_languages(String.t(), String.t(), [integer()]) :: %{
  required(integer()) => [String.t()]
}

Loads available languages for each version of a post. Returns a map of version number => list of language codes.

This is useful for showing which translations exist for a specific version, e.g., to display the published version's translations in the listing.

@spec load_version_statuses(String.t(), String.t(), [integer()], String.t() | nil) ::
  %{
    required(integer()) => String.t()
  }

Loads version statuses for all versions of a post. Returns a map of version number => status.

@spec only_version?(String.t()) :: boolean()

Checks if a post has only one version.

@spec parse_version_number(String.t()) :: integer() | nil

Parse version number from directory name (e.g., "v2" -> 2)

@spec resolve_version_dir(
  String.t(),
  :versioned | :legacy | :empty,
  integer() | nil,
  String.t(),
  String.t()
) :: {:ok, integer(), String.t()} | {:error, atom()}

Resolves which version directory to read from.

@spec resolve_version_dir_for_listing(
  String.t(),
  :versioned | :legacy | :empty,
  String.t(),
  String.t()
) :: {:ok, integer(), String.t()} | {:error, atom()}

Resolves the version directory for listing operations. Returns {:ok, version, content_dir} or {:error, reason}.

@spec version_dir?(String.t()) :: boolean()

Check if a directory name matches version pattern (v1, v2, etc.)

@spec version_is_published?(String.t(), String.t(), integer()) :: boolean()

Checks if a version is the published (live) version.

@spec version_path(String.t(), String.t(), integer()) :: String.t()

Returns the version directory path for a post.