(** Resolve an odoc reference against every package installed in the switch, and
    locate the item it names — the substrate shared by {!Show} and {!Complete}.

    This is the reference-resolution half of [odoc link], run standalone over
    the whole switch (with [Stdlib] open and the package roots in scope), with
    no "current unit" — so relative ([./…]) and current-package ([//…]) path
    references don't apply, but absolute ([/pkg/…]) ones do. *)

module Id = Odoc_model.Paths.Identifier
module Lang = Odoc_model.Lang
module Url = Odoc_document.Url

type scan = {
  odoc : Fpath.t;  (** the switch's [odoc/] root *)
  directories : Fpath.t list;  (** every dir holding a [.odoc] (the [-I] set) *)
  odocl : (string, Fpath.t) Hashtbl.t;  (** capitalised unit name -> [.odocl] *)
  page_roots : (string * Fpath.t) list;
      (** package name -> [odoc/<pkg>] ([-P]) *)
  lib_roots : (string * Fpath.t) list;
      (** library name -> [odoc/<pkg>/<lib>] ([-L]) *)
}

val scan : Switch.t -> scan
(** Scan the switch's [odoc/] tree: the include directories, the package/library
    roots, and the linked-unit index. *)

val default_open : string list
(** Modules resolution treats as open (currently [Stdlib]), mirroring the
    compiler's default environment. *)

val resolve_to_id : scan -> string -> (Id.t, [> `Msg of string ]) result
(** Parse and resolve a (complete) reference to its canonical identifier, using
    the same machinery as [odoc link]. Resolver ambiguity chatter on stderr is
    suppressed; genuine failures are returned as [`Msg]. *)

type located =
  | Lmodule of Odoc_model.Comment.docs * Lang.Signature.t option
      (** module / module type / unit: doc comment, and the expansion's
          signature when present *)
  | Lclass of Odoc_model.Comment.docs * Lang.ClassSignature.t option
  | Ltype of Odoc_model.Comment.docs * Lang.TypeDecl.t
  | Lleaf of Odoc_model.Comment.docs
      (** value, exception, constructor, field, method, … — no children *)

val find : Id.t -> Lang.Compilation_unit.t -> located option
(** Locate the item named by [id] within a loaded compilation unit, descending
    through module/class expansions and includes. *)

val root_candidates : scan -> Id.t -> Fpath.t list
(** The linked [.odocl] files whose name matches the root of [id]. More than one
    means the reference is ambiguous across packages/libraries (the resolver
    would otherwise silently pick the first). *)

val owning_content :
  scan ->
  ref_str:string ->
  Id.t ->
  (Odoc_odoc.Odoc_file.content, [> `Msg of string ]) result
(** Load the linked [.odocl] file that defines [id], disambiguating same-named
    files by matching the identifier key. [ref_str] is used only for error
    messages. *)