(** Package metadata and operations.

    A package represents a single opam package discovered from the opam overlay
    repository. It contains the package name, version, git remote URL, and
    optional configuration overrides. *)

(** {1 Types} *)

type t
(** A package discovered from the opam overlay. *)

(** {1 Constructors} *)

val create :
  name:string ->
  version:string ->
  dev_repo:Uri.t ->
  ?branch:string ->
  ?depends:string list ->
  ?synopsis:string ->
  unit ->
  t
(** [create ~name ~version ~dev_repo ?branch ?depends ?synopsis ()] creates a
    new package.

    @param name The opam package name
    @param version The package version (e.g., "dev")
    @param dev_repo The git remote URL from the opam file's dev-repo field
    @param branch Optional branch override; defaults to repository default
    @param depends List of opam package names this package depends on
    @param synopsis Short description of the package *)

(** {1 Accessors} *)

val name : t -> string
(** [name t] returns the package name. *)

val version : t -> string
(** [version t] returns the package version string. *)

val dev_repo : t -> Uri.t
(** [dev_repo t] returns the git remote URI. *)

val branch : t -> string option
(** [branch t] returns the branch to track, if explicitly set. *)

val depends : t -> string list
(** [depends t] returns the list of opam package names this package depends on.
*)

val synopsis : t -> string option
(** [synopsis t] returns the short description of the package, if any. *)

val repo_name : t -> string
(** [repo_name t] returns the repository name extracted from the dev-repo URL.

    This is the basename of the URL path with any ".git" suffix removed. For
    example, "https://github.com/foo/bar.git" returns "bar". *)

(** {1 Derived Paths} *)

val checkout_dir : checkouts_root:Fpath.t -> t -> Fpath.t
(** [checkout_dir ~checkouts_root t] returns the expected path for this
    package's git checkout, based on the repository name.

    For a package with dev-repo "https://example.com/foo/bar.git" and
    checkouts_root "/home/user/src", this returns "/home/user/src/bar".

    Multiple packages from the same repository will share the same checkout. *)

val subtree_prefix : t -> string
(** [subtree_prefix t] returns the subdirectory name used in the monorepo.

    This is the repository name (same as [repo_name t]), so multiple packages
    from the same repository share the same subtree directory. *)

(** {1 Comparison} *)

val compare : t -> t -> int
(** [compare a b] compares packages by name. *)

val equal : t -> t -> bool
(** [equal a b] returns true if packages have the same name. *)

val same_repo : t -> t -> bool
(** [same_repo a b] returns true if packages share the same dev-repo URL. *)

(** {1 Pretty Printing} *)

val pp : t Fmt.t
(** [pp] is a formatter for packages. *)