--
--  Copyright (C) 2014-2024, AdaCore
--  SPDX-License-Identifier: Apache-2.0
--
--  This package provides various helpers to format the semantic diagnostics
--  produced during name resolution.

with Ada.Containers.Vectors;

with Langkit_Support.Text; use Langkit_Support.Text;

with Libadalang.Analysis; use Libadalang.Analysis;

with GNATCOLL.Traces;

package Libadalang.Semantic_Diagnostics is
   Diags_Trace : GNATCOLL.Traces.Trace_Handle := GNATCOLL.Traces.Create
     ("LIBADALANG.SEM_DIAGS", Default => GNATCOLL.Traces.From_Config);

   type Located_Message is record
      Location : Ada_Node;
      Message  : Unbounded_Text_Type;
   end record;
   --  A message associated to a specific location

   function To_Pretty_String (Msg : Located_Message) return String;
   --  Return a formatted string showing the error message at its location

   package Located_Message_Vectors is new Ada.Containers.Vectors
     (Positive, Located_Message);

   subtype Located_Message_Vector is Located_Message_Vectors.Vector;

   type Contextual_Diagnostic is record
      Error    : Located_Message;
      Contexts : Located_Message_Vector;
   end record;
   --  A diagnostic which gather the error itself, as well as a set of
   --  informative diagnostics.

   type Node_Renderer is access function
     (Node : Ada_Node) return Text_Type;
   --  A node renderer is used during the formatting of diagnostics, to pretty
   --  print holes which actuals are nodes. Diagnostic formatters typically
   --  take a node renderer as parameter so that users can customize how nodes
   --  are renderered depending on the application.

   type Diagnostic_Aggregator is access function
     (Sem_Diags   : Solver_Diagnostic_Array;
      Render_Node : Node_Renderer) return Contextual_Diagnostic;
   --  A diagnostic aggregator takes as input the array of raw name resolution
   --  diagnostics that were produced on a single xref entry point which
   --  resolution failed, and processes/formats them to turn them into concise
   --  and human-readable errors which are ready to be emitted. Aggregators
   --  may typically choose to drop information when the raw diagnostics carry
   --  too much information which may be too difficult to render nicely or
   --  too difficult to be processed by humans.

   function Build_Contextual_Diagnostics
     (Node        : Ada_Node;
      Sem_Diags   : Solver_Diagnostic_Array;
      Aggregate   : Diagnostic_Aggregator;
      Render_Node : Node_Renderer) return Contextual_Diagnostic;
   --  Simply runs the aggregator on the given list of raw diagnostics, using
   --  the given node renderer. If the array of diagnostics is empty, this
   --  returns a generic "resolution failed" diagnostic spanning the entire
   --  node.

   function Basic_Aggregator
     (Sem_Diags   : Solver_Diagnostic_Array;
      Render_Node : Node_Renderer) return Contextual_Diagnostic;
   --  This is a basic implementation of a ``Diagnostic_Aggregator``, which
   --  tries to have a simple output:
   --   * if there is a single raw diagnostic, return it after formatting it.
   --   * if there are multiple raw diagnostics, find those which correspond
   --     to multiple overload attempts and build a nice user diagnostic which
   --     shows why each candidate was rejected, for up to 3 of them.
   --   * if there are multiple such cases or multiple unrelated errors in
   --     general, return the last one of them.

   function Basic_Node_Renderer (Node : Ada_Node) return Text_Type;
   --  Pretty print the given node to basic text without any stylization. this
   --  also renders node in generic contexts, and handles special cases such
   --  as universal types, anonymous access types, etc.

end Libadalang.Semantic_Diagnostics;