.. Copyright (C) 2025-2026 Free Software Foundation, Inc.
   Originally contributed by David Malcolm <dmalcolm@redhat.com>

   This is free software: you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see
   <https://www.gnu.org/licenses/>.

.. default-domain:: c

Graphs
======

.. type:: diagnostic_graph

SARIF has support for capturing directed graphs (such as callgraphs
and control flow graphs), both at the level of the run as a whole,
and at the level of individual results.

libgdiagnostics supports this with the following entrypoints, allowing
directed graphs to be

* created (with :func:`diagnostic_manager_new_graph`)

* reported "globally" (with :func:`diagnostic_manager_take_global_graph`)

* reported as part of a :type:`diagnostic` (with :func:`diagnostic_take_graph`), or

* discarded (with :func:`diagnostic_graph_release`).

.. function:: diagnostic_graph * diagnostic_manager_new_graph (diagnostic_manager *manager)

   Create a new directed graph.

   The resulting graph is owned by the caller and must have one of
   :func:`diagnostic_manager_take_global_graph`,
   :func:`diagnostic_take_graph`,
   or :func:`diagnostic_graph_release` called on it to avoid leaks.

   The parameter ``manager`` must be non-null.

   This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`.

.. function:: void diagnostic_manager_take_global_graph (diagnostic_manager *manager, \
				      diagnostic_graph *graph)

   Report this graph "globally", taking ownership of it.
   This won't appear in text sinks, but in SARIF sinks the graph will be
   added to theRun.graphs (SARIF v2.1.0 3.14.20).

   Parameters ``manager`` and ``graph`` must both be non-null.

   This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`.

.. function:: void diagnostic_take_graph (diagnostic *diag, \
		      diagnostic_graph *graph)

   Add this graph to ``diag``, transferring ownership of it to ``diag``.
   This won't appear in text sinks, but in SARIF sinks the graph will be
   added to theResult.graphs (SARIF v2.1.0 3.27.19).

   Parameters ``diag`` and ``graph`` must both be non-null.

   This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`.

.. function:: void diagnostic_graph_release (diagnostic_graph *graph)

   Release ``graph`` which must still be owned by the caller
   i.e. it must *not* have had
   :func:`diagnostic_manager_take_global_graph` or
   :func:`diagnostic_take_graph` called on it.

   Parameters ``graph`` can be null.

   This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`.


.. function:: void diagnostic_graph_set_description (diagnostic_graph *graph, \
				 const char *description)

   Set the description of ``graph`` for use in the value of the
   SARIF ``description`` property (SARIF v2.1.0 section 3.39.2).

   The parameter ``graph`` must be non-null.
   The parameter ``description`` can be null, for clearing any existing
   description.

   This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`.

.. function:: diagnostic_node * diagnostic_graph_add_node (diagnostic_graph *graph, \
			   const char *node_id, \
			   diagnostic_node *parent_node)

   Create and add a new node within ``graph`` with the given `id``.
   The id must be unique within nodes in ``graph``.

   The parameters ``graph`` and ``id`` must be non-null.

   ``parent_node`` can be NULL (for a top-level node in the graph),
   or non-null for a child node, allowing for arbitrary nesting of
   nodes.

   The new node is owned by ``graph``.

   This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`.

.. function:: diagnostic_edge * diagnostic_graph_add_edge (diagnostic_graph *graph, \
			   const char *edge_id, \
			   diagnostic_node *src_node, \
			   diagnostic_node *dst_node, \
			   const char *label)

   Create and add a new edge within ``graph``.

   The parameters ``graph``, ``src_node`` and ``dest_node``
   must be non-null.

   If non-null, then ``edge_id`` must be unique within ``graph``;
   if ``edge_id`` is null then a unique id of the form "edge0", "edge1",
   etc will be used automatically.

   If non-null, then ``label`` will be used for the value of the
   SARIF ``label`` property (SARIF v2.1.0 section 3.41.3).

   The new edge is owned by ``graph``.

   This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`.

.. function:: diagnostic_node *diagnostic_graph_get_node_by_id (diagnostic_graph *graph, \
				 const char *node_id)

   Get the node in ``graph`` with the given id, or null.

   The parameters ``graph`` and ``node_id`` must be non-null.

   This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`.

.. function:: diagnostic_edge *diagnostic_graph_get_edge_by_id (diagnostic_graph *graph, \
				 const char *edge_id)

   Get the edge in ``graph`` with the given id, or null.

   The parameters ``graph`` and ``edge_id`` must be non-null.

   This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`.


.. type:: diagnostic_node

.. function:: void diagnostic_node_set_label (diagnostic_node *node, \
			   const char *label)

   Set the label of ``node`` for use in the value of the
   SARIF ``label`` property (SARIF v2.1.0 section 3.40.3).

   The parameter ``node`` must be non-null.
   The parameter ``label`` can be null, for clearing any existing
   label.

   This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`.

.. function:: void diagnostic_node_set_location (diagnostic_node *node, \
			      const diagnostic_physical_location *loc)

   Set the physical location of ``node``, if any.

   The parameter ``node`` must be non-null.
   The parameter ``loc`` can be null, for clearing any existing
   location.

   If set, the value will be used by SARIF sinks within the
   ``location`` property  (SARIF v2.1.0 section 3.40.4).

   This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`.

.. function:: void diagnostic_node_set_logical_location (diagnostic_node *node, \
				      const diagnostic_logical_location *logical_loc)

   Set the logical location of ``node``, if any.

   The parameter ``node`` must be non-null.
   The parameter ``logical_loc`` _can be null, for clearing any existing
   location.

   If set, the value will be used by SARIF sinks within the
   ``location`` property  (SARIF v2.1.0 section 3.40.4).

   This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`.
