spark

<!--
SPDX-FileCopyrightText: 2020 Zach Daniel
SPDX-FileCopyrightText: 2022 spark contributors <https://github.com/ash-project/spark/graphs.contributors>

SPDX-License-Identifier: MIT
-->

# Using Source Annotations

Spark automatically tracks source location information for all DSL elements
using Erlang's `:erl_anno` module. This provides comprehensive location tracking
for sections, options, and entities, enabling better error messages, IDE
integration, and debugging capabilities.

Source annotations are only enabled when the Elixir compile option `debug_info`
is enabled (`Code.get_compiler_option(:debug_info)` returns true). By default,
debug info is disabled in production and in `.exs` script files, which means
source annotations won't be available in those contexts.

> #### ExUnit Test Cases {: .warning}
>
> If you're defining modules inside ExUnit test cases (which use `.exs` files),
> source annotations won't be available unless you explicitly enable
> `debug_info` in your tests.
>
> ```elixir
> setup do
>   debug_info? = Code.get_compiler_option(:debug_info)
>   Code.put_compiler_option(:debug_info, true)
>   on_exit(fn -> Code.put_compiler_option(:debug_info, debug_info?) end)
>   :ok
> end
> ```

## What are Source Annotations?

Source annotations capture metadata about where DSL elements are defined in your
source code, including:

- **File path**: The source file where the DSL element is declared
- **Line number**: The exact line where the element starts
- **End location**: The line where DSL blocks end (available on OTP 28+,
  requires Elixir Parser Configuration)

```elixir
defmodule Acme.MixProject do
  use Mix.Project

  def project do
    [
      app: :acme,
      elixirc_options: [
        parser_options: [
          token_metadata: true,
          parser_columns: true
        ]
      ],
      # ...
    ]
  end
end
```

Spark tracks annotations for:
- **Sections**: Location where section blocks are defined (`section do ... end`)
- **Options**: Location where individual options are set (`option_name "value"`)
- **Entities**: Location where entities are declared (`entity :name do ... end`)

## Annotation Introspection

### Universal Access via Introspection Functions

Spark provides introspection functions that work regardless of whether entities
define an `anno_field`. These functions access annotation data stored in the DSL
state:

```elixir
# Get DSL state
dsl_state = MyModule.spark_dsl_config()

# Section annotations
section_anno = Spark.Dsl.Extension.get_section_anno(dsl_state, [:my_section])
if section_anno do
  # Extract line number (Spark currently provides line numbers only)
  line = case :erl_anno.location(section_anno) do
    {line_num, _col} -> line_num
    line_num -> line_num
  end
  file = :erl_anno.file(section_anno) |> to_string()
  IO.puts("Section defined at #{file}:#{line}")
end

# Option annotations
option_anno = Spark.Dsl.Extension.get_opt_anno(dsl_state, [:my_section], :option_name)
if option_anno do
  line = :erl_anno.location(option_anno)
  file = :erl_anno.file(option_anno) |> to_string()
  IO.puts("Option defined at #{file}:#{line}")
end

# Entity annotations
entities = Spark.Dsl.Extension.get_entities(dsl_state, [:my_section])
Enum.each(entities, fn entity ->
  case Spark.Dsl.Entity.anno(entity) do
    nil -> :ok
    anno ->
      line = :erl_anno.location(anno)
      file = :erl_anno.file(anno) |> to_string()
      IO.puts("Entity defined at #{file}:#{line}")
  end
end)
```

### Entity Annotations

For direct access to annotations, entities should include the
`__spark_metadata__` field in their struct definition:

```elixir
defmodule MyEntity do
  defstruct [
    :name,
    :__spark_metadata__ # Required for annotation access
  ]
end

@my_entity %Spark.Dsl.Entity{
  name: :my_entity,
  target: MyEntity,
  schema: [
    name: [type: :atom, required: true]
  ]
}

# Access annotations
entities = Spark.Dsl.Extension.get_entities(dsl_state, [:my_section])
Enum.each(entities, fn entity ->
  if entity_anno = Spark.Dsl.Entity.anno(entity) do
    line = :erl_anno.location(entity_anno)
    file = :erl_anno.file(entity_anno) |> to_string()
    IO.puts("Entity defined at #{file}:#{line}")
  end

  if name_anno = Spark.Dsl.Entity.property_anno(entity, :name) do
    line = :erl_anno.location(name_anno)
    file = :erl_anno.file(name_anno) |> to_string()
    IO.puts("Entity name property defined at #{file}:#{line}")
  end
end)
```

## Working with Annotations

Annotations use Erlang's `:erl_anno` module, which provides several utilities:

```elixir
# Check if something is an annotation
:erl_anno.is_anno(anno)

# Get the location (line number or {line, column})
# Note: Spark currently only provides line numbers, not column information
location = :erl_anno.location(anno)

# Helper function to extract line number from location
get_line = fn location ->
  case location do
    {line_num, _column} -> line_num  # Future column support
    line_num when is_integer(line_num) -> line_num  # Current Spark behavior
  end
end

line = get_line.(location)

# Get the file (returns :undefined or a charlist)
file = :erl_anno.file(anno)

# Convert charlist to string safely
file_string = case file do
  :undefined -> "unknown"
  charlist -> to_string(charlist)
end

# Get the end location (OTP 28+, returns :undefined if not available)
if function_exported?(:erl_anno, :end_location, 1) do
  end_location = :erl_anno.end_location(anno)
end
```

## Use Cases

### Enhanced Error Messages in Verifiers

Create precise error messages that point to the exact source location:

```elixir
defmodule MyLibrary.Verifiers.UniqueNames do
  use Spark.Dsl.Verifier

  def verify(dsl_state) do
    entities = Spark.Dsl.Extension.get_entities(dsl_state, [:my_section])

    case find_duplicate(entities) do
      nil -> :ok
      {duplicate_name, duplicate_entity} ->
        location = Spark.Dsl.Entity.anno(duplicate_entity)

        {:error,
         Spark.Error.DslError.exception(
           message: "Duplicate entity name: #{duplicate_name}",
           path: [:my_section, duplicate_name],
           module: Spark.Dsl.Verifier.get_persisted(dsl_state, :module),
           location: location
         )}
    end
  end
end
```

### Enhanced Error Messages in Transformers

```elixir
defmodule MyLibrary.Transformers.ValidateEntity do
  use Spark.Dsl.Transformer

  def transform(dsl_state) do
    entities = Spark.Dsl.Extension.get_entities(dsl_state, [:my_section])

    entities
    |> Enum.each(fn entity ->
      if invalid?(entity) do
        location = Spark.Dsl.Entity.anno(entity)

        raise Spark.Error.DslError,
          message: "Invalid configuration for #{entity.name}",
          path: [:my_section, entity.name],
          location: location
      end
    end)

    {:ok, dsl_state}
  end
end
```

### IDE Integration and Language Servers

Language servers can provide enhanced features using annotation data:

```elixir
defmodule MyLanguageServer do
  def find_definition(file, line, column) do
    # Find modules that might contain DSL at this location
    modules = find_modules_in_file(file)

    Enum.find_value(modules, fn module ->
      dsl_state = module.spark_dsl_config()

      # Check section annotations
      Enum.find_value(dsl_state, fn {path, config} ->
        if match_location?(config.section_anno, line) do
          {:section, path, config.section_anno}
        end
      end) ||

      # Check entity annotations
      find_entity_at_location(dsl_state, line)
    end)
  end
end
```

### Debugging and Development Tools

Create debugging utilities that show DSL source locations:

```elixir
defmodule MyLibrary.Debug do
  def inspect_dsl_sources(module) do
    dsl_state = module.spark_dsl_config()

    # Show all DSL elements with their locations
    Enum.each(dsl_state, fn {path, config} ->
      IO.puts("Section #{inspect(path)}:")

      if config.section_anno do
        print_location("  Section", config.section_anno)
      end

      # Show options
      Enum.each(config.opts_anno, fn {opt_name, anno} ->
        print_location("  Option #{opt_name}", anno)
      end)

      # Show entities
      Enum.each(config.entities, fn entity ->
        anno = Spark.Dsl.Entity.anno(entity)
        print_location("  Entity #{entity.name}", anno)
      end)
    end)
  end

  defp print_location(label, anno)
  defp print_location(label, nil), do: nil
  defp print_location(label, anno) do
    line = :erl_anno.location(anno)
    file = :erl_anno.file(anno) |> to_string() |> Path.relative_to_cwd()
    IO.puts("    #{label}: #{file}:#{line}")
  end
end
```

## Best Practices

### 1. Always Include Location in DslErrors

When creating DslErrors, include location information whenever available:

```elixir
# Get the appropriate annotation for your error context
location = case error_type do
  :section_error ->
    Spark.Dsl.Transformer.get_section_anno(dsl_state, path)
  :option_error ->
    Spark.Dsl.Transformer.get_opt_anno(dsl_state, path, option_name)
  :entity_error ->
    entity = Enum.at(entities, entity_index)
    Spark.Dsl.Entity.anno(entity)
end

{:error,
 Spark.Error.DslError.exception(
   message: "Clear error description",
   path: path,
   module: module,
   location: location
 )}
```

### 2. Handle Missing Annotations Gracefully

Not all annotations may be available (e.g., programmatically generated DSL
elements):

```elixir
location_info = if anno do
  line = :erl_anno.location(anno)
  file = :erl_anno.file(anno) |> to_string()
  " at #{file}:#{line}"
else
  ""
end

IO.puts("Error in entity#{location_info}")
```

### 3. Use Both Introspection and Anno Fields

- **Use introspection functions** for universal access in verifiers and
  transformers
- **Use anno fields** in entity structs for convenient access in application
  code

### 4. Check OTP Version for End Location

End location tracking requires OTP 28+:

```elixir
if function_exported?(:erl_anno, :end_location, 1) do
  end_location = :erl_anno.end_location(anno)
  # Use end location for precise span information
end
```

## Current Limitations

- Column information is not currently tracked (only line numbers)
- End Location is only tracked for OTP28+
- End Location is not available for multiline options