@spec add_edge(t(), Clarity.Vertex.t(), Clarity.Vertex.t(), :digraph.label()) ::
  result()

Adds an edge between two vertices.

@spec add_vertex(t(), Clarity.Vertex.t(), Clarity.Vertex.t()) :: result()

Adds a vertex.

@spec available_vertex_types(t()) :: [module()]

Gets all unique vertex types present in the graph.

Returns a list of modules representing the types of vertices in the graph.

@spec breadcrumbs(t(), Clarity.Vertex.t()) :: [Clarity.Vertex.t()] | false

Gets the shortest path between the root and the vertex. Returns false if no path exists.

@spec clear(t()) :: result()

Clears all vertices and edges from the graph.

Resets graphs to empty state with root vertex.

@spec delete(t()) :: result()

Deletes Graph

@spec edge(t(), :digraph.edge()) ::
  {:digraph.edge(), Clarity.Vertex.t() | nil, Clarity.Vertex.t() | nil,
   :digraph.label()}
  | false

Gets edge information for a given edge ID.

@spec edges(t()) :: [:digraph.edge()]

Gets all edges IDs.

@spec filter(t(), Clarity.Graph.Filter.filter() | [Clarity.Graph.Filter.filter()]) ::
  t()

Creates a filtered subgraph using a composable filter. Returns a new Clarity.Graph instance with the filtered vertices and edges.

Examples

# Single filter
subgraph = Graph.filter(graph, Filter.within_steps(vertex, 2, 1))

# Multiple composed filters
filter = Filter.all([
  Filter.within_steps(vertex, 2, 1),
  Filter.reachable_from([root_vertex])
])
subgraph = Graph.filter(graph, filter)

@spec get_short_path(t(), Clarity.Vertex.t(), Clarity.Vertex.t()) ::
  [Clarity.Vertex.t()] | false

Gets the shortest path between two vertices. Returns false if no path exists.

@spec get_update_count(t()) :: pos_integer()

Gets the current update count for the graph.

The count remains stable when no mutations occur and increases monotonically when the graph is modified. Use this for change detection to invalidate cached subgraphs.

Do not rely on specific count values or increment amounts as the internal update mechanism may change.

Example

count1 = Graph.get_update_count(graph)
# ... operations that might modify graph ...
count2 = Graph.get_update_count(graph)

if count2 > count1, do: # graph changed

@spec get_vertex(t(), String.t()) :: Clarity.Vertex.t() | nil

Looks up a vertex struct by its ID.

@spec handover(t(), pid()) :: result(t())

Transfers ownership of all ETS tables to another process.

Used to hand over a loaded graph from the Cache process to the Server process. Returns an updated graph struct with the new owner.

@spec in_degree(t(), Clarity.Vertex.t()) :: non_neg_integer()

Gets the total in-degree for a vertex across all edge types.

@spec in_degree(t(), Clarity.Vertex.t(), :digraph.label()) :: non_neg_integer()

Gets the in-degree for a vertex for a specific edge type.

@spec in_edges(t(), Clarity.Vertex.t()) :: [:digraph.edge()]

Gets incoming edges for a vertex.

@spec in_neighbors(t(), Clarity.Vertex.t()) :: [Clarity.Vertex.t()]

Gets all vertices that are direct sources of incoming edges to a vertex.

@spec load(Path.t()) :: result(t())

Loads a persisted graph from disk.

Returns {:error, posix} on file errors (e.g., :enoent, :eacces).

@spec navigation_children(t(), Clarity.Vertex.t()) :: %{
  required(:digraph.label()) => [Clarity.Vertex.t()]
}

Gets the direct children of a vertex in the tree graph, grouped by edge label.

Returns a map where keys are edge labels and values are lists of child vertices, sorted by vertex name for consistent ordering.

Examples

children = Graph.navigation_children(graph, root_vertex)
# Returns: %{:application => [app1, app2], :module => [mod1]}

@spec new() :: t()

Creates a new graph.

@spec out_degree(t(), Clarity.Vertex.t()) :: non_neg_integer()

Gets the total out-degree for a vertex across all edge types.

@spec out_degree(t(), Clarity.Vertex.t(), :digraph.label()) :: non_neg_integer()

Gets the out-degree for a vertex for a specific edge type.

@spec out_edges(t(), Clarity.Vertex.t()) :: [:digraph.edge()]

Gets outgoing edges for a vertex.

@spec out_neighbors(t(), Clarity.Vertex.t()) :: [Clarity.Vertex.t()]

Gets all vertices that are direct targets of outgoing edges from a vertex.

@spec persist(t(), Path.t()) :: result()

Persists a graph to disk.

The graph must not be a subgraph.

Returns {:error, posix} on file errors (e.g., :enoent, :eacces, :enospc).

@spec purge(t(), Clarity.Vertex.t()) :: result([Clarity.Vertex.t()])

Purges a vertex and all vertices that were caused by it.

@spec vertex_count(t()) :: non_neg_integer()

Gets the total number of vertices.

@spec vertices(t(), query()) :: [Clarity.Vertex.t()]

Gets all vertices matching the query.

Query Syntax

Queries support complex boolean expressions using operations, operators, and fields.

Operations

• {:and, query1, query2} - Both queries must match
• {:or, query1, query2} - Either query must match
• {:not, query} - Query must not match

Operators

• {:==, field, value} - Field equals value
• {:!=, field, value} - Field does not equal value
• {:in, field, values} - Field is in list of values

Fields

• :vertex_type - The module of the vertex (e.g., Application, Module)
• :vertex_id - The unique ID string of the vertex
• {:field, :field_name} - A field within the vertex struct (e.g., {:field, :app}, {:field, :module})

Examples

# All Application vertices
Graph.vertices(graph, {:==, :vertex_type, Application})

# Application OR Root vertices
Graph.vertices(graph, {:or,
  {:==, :vertex_type, Application},
  {:==, :vertex_type, Root}
})

# Same as above, using :in
Graph.vertices(graph, {:in, :vertex_type, [Application, Root]})

# Complex: Root/Application OR (Module with specific ID)
Graph.vertices(graph, {:or,
  {:in, :vertex_type, [Root, Application]},
  {:and, {:==, :vertex_type, Module}, {:==, :vertex_id, "module:Foo"}}
})

# All vertices except Root
Graph.vertices(graph, {:not, {:==, :vertex_type, Root}})

# Query by field value
Graph.vertices(graph, {:and,
  {:==, :vertex_type, Application},
  {:==, {:field, :app}, :my_app}
})

# All vertices (default)
Graph.vertices(graph, true)
Graph.vertices(graph)