explico

# Explico

Explico runs Vale against `@moduledoc`, `@doc`, and `@typedoc` content and
reports findings as Credo issues at their original source lines. It lets Elixir
projects enforce their own prose policies through existing Credo workflows.

## Requirements

To run documentation checks, install
[Vale](https://docs.vale.sh/topics/installation) and make `vale` available on
`PATH`. Explico is tested with Vale 3.15.1.

If the `vale` executable is not found, Explico skips its check without affecting
other configured Credo checks. Vale configuration errors or execution failures
are reported as Credo issues.

Each consuming application owns its `.vale.ini`, Vale styles, terminology, and
writing policy. Explico does not provide a default policy for consumers.

## Installation

Add Explico beside Credo as a development dependency:

```elixir
{:credo, "~> 1.7", only: [:dev, :test], runtime: false},
{:explico, "~> 0.1.1", only: [:dev, :test], runtime: false}
```

## Credo configuration

Explico provides `Explico.Check.Vale`, which extracts all selected Elixir
documentation and runs Vale once. Add it to your project's `.credo.exs`:

```elixir
%{
  configs: [
    %{
      name: "explico",
      checks: %{
        extra: [
          {Explico.Check.Vale, []}
        ]
      }
    }
  ]
}
```

Expose project aliases that forward files and flags to Credo:

```elixir
explico: "credo suggest --config-name explico --only Explico.Check.Vale",
"explico.diff": "credo diff --config-name explico --only Explico.Check.Vale"
```

## Usage

Use Explico for documentation embedded in Elixir source files:

```sh
mix explico lib/my_app/accounts.ex
mix explico --strict lib/my_app/accounts.ex
mix explico.diff origin/main
```

Check standalone Markdown files directly with Vale:

```sh
vale README.md
vale docs/
```

## Example output

Given a consumer Vale rule that flags vague language:

```elixir
@doc """
Handles user authentication.
"""
def authenticate(credentials), do: Auth.authenticate(credentials)
```

Explico reports the finding through Credo:

```text
Warnings - please take a look
┃
┃ [R] → [Docs.VagueBehavior] Describe the specific behavior instead of using 'Handles'.
┃       lib/my_app/accounts.ex:12 #(module)
```

Explico maps each finding back to its original documentation attribute.

## How it works

`Explico.Check.Vale` receives selected source files from Credo. The check
extracts `@moduledoc`, `@doc`, and `@typedoc` into temporary Markdown files. One
Vale process checks the batch. Explico converts the results into `Credo.Issue`
structs at the original Elixir lines.

Consumer Vale configuration defines the prose policy. Credo provides file
selection and issue reporting; Explico connects them while preserving source
locations.

## License

Explico is available under the [Apache License 2.0](LICENSE).