Lexical.Plugin.V1.Diagnostic behaviour (lexical_plugin v0.5.0)

A use-able diagnostic plugin module

A diagnostic result examines a diagnosable data structure and emits a list of Lexical.Plugin.V1.Diagnostic.Result structs.

Diagnostic plugins are called in two places. When a file is saved, they're called with the Lexical.Project struct and are expected to perform diagnostics across the whole project.

On receipt of a change to a Lexical.Document, they're called with the changed document and are expected to analyze that document and emit any diagnostics they find.

Both calls to diagnose operate on tight deadlines, though when diagnose is called with a Lexical.Project, the deadline is much longer than it is when diagnose is called with a Lexical.Document. This is because analyzing a project should take a lot longer than analyzing a single document. Currently, Lexical sets a deadline of around a second on project-level diagnostics and a tens-of-milliseconds deadline on document plugins.

errors-and-timeouts

Errors and Timeouts

Plugins are very sensitive to errors and are disabled by lexical if they cause too many. At present, a disabled plugin can only be re-enabled by restarting lexical, so ensure that your plugin doesn't crash, and if you don't have diagnostics, return {:ok, []} rather than some error response.

plugin-lifecycle

Plugin lifecycle

When a plugin is started, Lexical calls the init/0 function, which can perform setup actions, like starting the application associated with the plugin. Implementing this function is optional. From then on, the plugin will be resident and run in tasks whenever files are changed or saved.

a-simple-do-nothing-plugin

A simple do-nothing plugin

defmodule DoesNothing do
  use Lexical.Plugin.V1.Diagnostic

  def diagnose(%Lexical.Document{} = doc) do
   {:ok, []}
  end

  def diagnose(%Lexical.Project{}) do
    {:ok, []}
  end
end

Check out the README for a plugin that does something more.

Link to this section Summary

Link to this section Types

Link to this type

diagnosable()

@type diagnosable() :: Lexical.Project.t() | Lexical.Document.t()
Link to this type

diagnostics_reply()

@type diagnostics_reply() :: {:ok, results()} | {:error, any()}
@type results() :: [Lexical.Plugin.V1.Diagnostic.Result.t()]
@type state() :: any()

Link to this section Callbacks

Link to this callback

diagnose(diagnosable)

@callback diagnose(diagnosable()) :: diagnostics_reply()