@spec add_data(engine(), json_encodable()) ::
  {:ok, engine()} | {:error, Regolix.Error.t()}

Adds data to the engine's data document.

Can be called multiple times to merge data.

Examples

{:ok, engine} = Regolix.add_data(engine, %{"users" => %{"alice" => %{"role" => "admin"}}})

@spec add_data!(engine(), json_encodable()) :: engine()

Adds data to the engine. Raises on error.

@spec add_policy(engine(), String.t(), String.t()) ::
  {:ok, engine()} | {:error, Regolix.Error.t()}

Adds a Rego policy to the engine.

Examples

{:ok, engine} = Regolix.add_policy(engine, "authz.rego", "package authz")

@spec add_policy!(engine(), String.t(), String.t()) :: engine()

Adds a Rego policy to the engine. Raises on error.

@spec clear_coverage!(engine()) :: engine()

Clears accumulated coverage data without disabling coverage.

Use this to reset coverage between test runs while keeping coverage enabled.

Examples

engine = Regolix.clear_coverage!(engine)

@spec clear_data(engine()) :: {:ok, engine()} | {:error, Regolix.Error.t()}

Clears all data from the engine, keeping policies intact.

Examples

{:ok, engine} = Regolix.clear_data(engine)

@spec clear_data!(engine()) :: engine()

Clears all data from the engine. Raises on error.

@spec disable_coverage!(engine()) :: engine()

Disables coverage tracking on the engine.

Coverage data is retained until explicitly cleared with clear_coverage!/1.

Examples

engine = Regolix.disable_coverage!(engine)

@spec enable_coverage!(engine()) :: engine()

Enables coverage tracking on the engine.

After enabling, all query evaluations will track which policy lines are executed. Use get_coverage_report/1 to retrieve the accumulated coverage data.

Examples

engine = Regolix.enable_coverage!(engine)

@spec eval_query(engine(), String.t()) ::
  {:ok, eval_result()} | {:error, Regolix.Error.t()}

Evaluates a Rego query against the engine.

Returns the result as Elixir terms, or :undefined if the query has no result.

Examples

{:ok, true} = Regolix.eval_query(engine, "data.authz.allow")
{:ok, :undefined} = Regolix.eval_query(engine, "data.authz.nonexistent")

@spec eval_query!(engine(), String.t()) :: eval_result()

Evaluates a Rego query. Raises on error.

@spec get_coverage_report(engine()) ::
  {:ok, coverage_report()} | {:error, Regolix.Error.t()}

Returns the accumulated coverage report.

Returns coverage data for all policy files, showing which lines were executed (covered) and which were not (not_covered).

Examples

{:ok, coverage} = Regolix.get_coverage_report(engine)
# => %{"authz.rego" => %{covered: [1, 2, 5], not_covered: [9, 10]}}

@spec get_coverage_report!(engine()) :: coverage_report()

Returns the accumulated coverage report. Raises on error.

@spec get_packages(engine()) :: [String.t()]

Returns the list of package names loaded in the engine.

Examples

packages = Regolix.get_packages(engine)
# => ["data.authz", "data.rbac"]

@spec get_rules(engine()) ::
  {:ok, %{required(String.t()) => [rule_info()]}} | {:error, Regolix.Error.t()}

Returns metadata about rules defined in loaded policies.

Parses the policy sources to extract rule names, descriptions (from comments), and line ranges. Useful for mapping coverage line numbers to human-readable rule names.

Examples

rules = Regolix.get_rules(engine)
# => %{
#   "policy.rego" => [
#     %{name: "allow", description: "Allow if not denied", start_line: 10, end_line: 15},
#     %{name: "deny", description: "Deny sanctioned countries", start_line: 20, end_line: 25}
#   ]
# }

@spec get_rules!(engine()) :: %{required(String.t()) => [rule_info()]}

Returns metadata about rules defined in loaded policies. Raises on error.

@spec new() :: {:ok, engine()}

Creates a new Rego policy engine.

Examples

{:ok, engine} = Regolix.new()

@spec new!() :: engine()

Creates a new Rego policy engine. Raises on error.

@spec set_input(engine(), json_encodable()) ::
  {:ok, engine()} | {:error, Regolix.Error.t()}

Sets the input document for policy evaluation.

Accepts Elixir terms (maps, lists, etc.) which are automatically JSON-encoded.

Examples

{:ok, engine} = Regolix.set_input(engine, %{"user" => "alice"})

@spec set_input!(engine(), json_encodable()) :: engine()

Sets the input document. Raises on error.

@spec with_coverage(engine(), (engine() -> result)) :: {result, coverage_report()}
when result: var

Executes a function with coverage tracking enabled, returning both the result and coverage.

This is the recommended API for single-operation coverage. Coverage is automatically enabled before the function runs and disabled/cleared afterward.

Examples

{result, coverage} = Regolix.with_coverage(engine, fn e ->
  Regolix.eval_query!(e, "data.authz.allow")
end)
# result => true
# coverage => %{"authz.rego" => %{covered: [1, 2, 5], not_covered: [9, 10]}}

For multi-query accumulation, use the raw primitives:

• enable_coverage!/1
• disable_coverage!/1
• get_coverage_report!/1
• clear_coverage!/1