# `Clarity.Config`
[🔗](https://github.com/team-alembic/clarity/blob/v0.5.1/lib/clarity/config.ex#L1)

Centralized configuration management for Clarity.

This module provides a single source of truth for all Clarity configuration settings,
handling both global application settings and per-application extension configurations.

## Global Configuration Settings

These settings are configured on the `:clarity` application:

### Application Filtering (`:introspector_applications`)

Controls which applications are introspected to improve performance:

```elixir
# Include only specific applications
config :clarity, :introspector_applications, [:my_app, :phoenix, :ecto]
```

When `:introspector_applications` is:
- A list of atoms - Only these applications will be introspected (include mode)
- `nil` or not set - All applications except OTP/Elixir standard libraries will be introspected

This affects which application vertices are created and which code reload events are processed.

### Editor Configuration (`:editor`)

Controls how files are opened from Clarity. Supports both local editor commands and URL mode:

```elixir
# Local editor with template variables
config :clarity, :editor, "code --goto __FILE__:__LINE__:__COLUMN__"
config :clarity, :editor, "subl __FILE__:__LINE__"

# URL mode for browser-based editing (use atom in config)
config :clarity, :editor, :url
```

```bash
# Environment variables (use string since atoms aren't available)
export CLARITY_EDITOR="code --goto __FILE__:__LINE__:__COLUMN__"
export CLARITY_EDITOR="__URL__"  # URL mode via environment variable
```

**Configuration Priority:** (highest to lowest)
1. `config :clarity, editor: ...`
2. `CLARITY_EDITOR` environment variable
3. `ELIXIR_EDITOR` environment variable
4. `EDITOR` environment variable

**Template Variables:** (case-insensitive)
- `__FILE__` - replaced with the file path
- `__LINE__` - replaced with the line number
- `__COLUMN__` - replaced with the column number

> #### Security Warning {: .warning}
>
> Editor configuration executes system commands based on user configuration.
> Ensure configured commands are safe and trusted. For untrusted environments,
> use URL mode (`:url` or `"__URL__"`).

### Default Perspective Lens (`:default_perspective_lens`)

Sets the initial lens when starting a perspective:

```elixir
config :clarity, :default_perspective_lens, "debug"
```

### Cache Path (`:cache_path`)

Sets the directory where the graph cache is stored:

```elixir
config :clarity, :cache_path, "/custom/cache/path"
```

Defaults to `Application.app_dir(:clarity, "priv/cache")` if not configured.

### Auto Start (`:auto_start?`)

Controls whether Clarity automatically starts introspection on application startup:

```elixir
config :clarity, :auto_start?, false
```

When `true` (default), Clarity loads the cache and starts introspection immediately on startup.

When `false`, Clarity defers initialization until the first call to `Clarity.get/1` or
`Clarity.introspect(:full)`. This is useful for:
- Faster application startup in development
- Avoiding unnecessary introspection in test environment
- Manual control over when introspection begins

**Note:** When auto-start is disabled, incremental rebuild calls (triggered by code
reloading) are silently ignored until initialization is triggered.

## Per-Application Extension Settings

These settings are configured on individual applications:

### Lensmaker Registration (`:clarity_perspective_lensmakers`)

Applications can register lensmakers for the perspective system:

```elixir
config :my_app, :clarity_perspective_lensmakers, [
  MyApp.SecurityLensmaker,
  MyApp.CustomExtension
]
```

### Custom Introspector Registration (`:clarity_introspectors`)

Applications can register custom introspectors:

```elixir
config :my_app, :clarity_introspectors, [
  MyApp.MyCustomIntrospector
]
```

### Content Provider Registration (`:clarity_content_providers`)

Applications can register custom content providers:

```elixir
config :my_app, :clarity_content_providers, [
  MyApp.CustomContent,
  MyApp.InteractiveContent
]
```

# `should_process_app?`

```elixir
@spec should_process_app?(Application.app()) :: boolean()
```

Checks if an application should be processed based on `:introspector_applications` configuration.

# `should_process_module?`

```elixir
@spec should_process_module?(module()) :: boolean()
```

Checks if a module should be processed based on `:introspector_applications` configuration.

Returns `false` if the module doesn't belong to any application.

---

*Consult [api-reference.md](api-reference.md) for complete listing*