Skip to content

About

A Neovim plugin that shows Hex dependency status inline in your Elixir mix.exs. Each dependency's latest version and status appears as virtual text as you type, with one-key upgrades and a versions browser.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

hex-outdated.nvim

CI License: MIT Neovim

Live "are my Hex deps up to date?" feedback for Elixir mix.exs, in the spirit of crates.nvim. As you edit mix.exs, the plugin checks each dependency's declared version requirement against hex.pm: inline virtual text shows the latest version and status, and non-existent versions/packages show up as diagnostics.

hex-outdated.nvim showing inline version status in a mix.exs buffer

Features

  • Live inline virtual text as you edit mix.exs, no :command needed
  • Status at a glance: up to date, upgradable, outdated pin, retired, or non-existent
  • Non-existent versions/packages and retired-only matches also show up as real vim.diagnostic entries
  • One-key actions: upgrade the requirement under the cursor, browse published versions, or open the package on hex.pm
  • Treesitter parsing, with a Lua line-scanner fallback when the elixir parser is missing or the buffer doesn't parse mid-edit
  • Status comes from mix.exs alone; no shelling out to mix
  • Async, cached hex.pm requests; configurable text, highlights, and keymaps

Requirements

  • Neovim 0.10+
  • curl on PATH
  • (Recommended) the elixir Treesitter parser (:TSInstall elixir); without it, the plugin falls back to Lua patterns.

Install

With lazy.nvim:

{
  "jpease/hex-outdated.nvim",
  ft = "elixir",
  opts = {},
}

With packer.nvim:

use({
  "jpease/hex-outdated.nvim",
  config = function()
    require("hex-outdated").setup({})
  end,
})

With mini.deps:

MiniDeps.add({ source = "jpease/hex-outdated.nvim" })
require("hex-outdated").setup({})

With vim-plug:

Plug 'jpease/hex-outdated.nvim'
" after plug#end():
lua require("hex-outdated").setup({})

As a native package (no plugin manager):

git clone https://github.com/jpease/hex-outdated.nvim \
  ~/.config/nvim/pack/plugins/start/hex-outdated.nvim
-- in your init.lua
require("hex-outdated").setup({})

Every manager other than lazy.nvim's opts = {} needs an explicit require("hex-outdated").setup({}) call, because the plugin activates entirely through setup().

Usage

When you open a mix.exs, status appears automatically and updates as you type.

:HexOutdated {refresh|toggle|upgrade|versions|open|info|lock} (bare :HexOutdated = refresh; the subcommands act on mix.exs buffers only)

Subcommand Action
refresh Re-fetch, bypassing the cache.
toggle Enable/disable the inline display for the current buffer.
upgrade Rewrite the requirement under the cursor to target the latest release, keeping its operator, precision, and spacing.
versions Floating window of active published versions; <CR> inserts the selected one, q/<Esc> closes.
open Open the package's page on hex.pm in a browser.
info Floating detail view (requirement / locked / latest) for the dependency under the cursor.
lock Toggle the per-buffer lock lens: a locked X · latest Y line under each dependency.

The same actions are also plain functions, so you can bind your own keys:

local hex = require("hex-outdated")
-- hex.refresh() / hex.toggle() / hex.upgrade() / hex.versions() / hex.open()
-- hex.info()    / hex.lock()

upgrade and selecting a release from versions both preserve the current requirement style: comparison requirements stay comparisons, bare exact versions stay bare, and ~> keeps its existing precision (with full prerelease versions preserved). Both re-analyze the buffer right away. Retired Hex releases never count as the latest release and are not offered in the popup.

Status meanings

Status Meaning
up_to_date The requirement allows the latest stable release.
upgradable The requirement resolves, but excludes the latest release (~> 1.6.0 once 1.7.0 is out).
outdated An exact pin (==) that is below the latest release.
retired Only retired releases match the requirement (also a warning diagnostic).
invalid No published release matches the requirement (also an error diagnostic).

The plugin annotates public Hex packages only. It leaves git:/github:, path:, and in_umbrella: deps alone, and also private organization:/repo: packages, which the public API cannot see, whether or not they carry a requirement. Requirements it can't analyze (combined and/or clauses) get no inline status; the detail float still shows their latest release. When a fetch fails, the detail float says why (timeout, rate limit, ...).

Lock context (optional)

By default hex-outdated reads only mix.exs. When a mix.lock is present it can also show what's actually locked, kept secondary so the inline requirement status stays primary:

  • Detail float. :HexOutdated info (or press K on a dependency line) shows requirement / locked / latest for the dependency under the cursor.
  • Lens. :HexOutdated lock toggles a locked X · latest Y line under each dependency (off by default).
  • Stale-lock diagnostic. A warning when mix.lock holds a version that no longer satisfies your requirement (e.g. after you tighten it), prompting a mix deps.get.

The lock context is re-read when the buffer is analyzed and when mix.lock may have changed outside it: on regaining focus, on entering the buffer, and after a :! command.

All of this no-ops when there is no mix.lock. Disable it entirely with lock = { enabled = false }. The K binding only acts on dependency lines and otherwise falls through to LSP hover / keywordprg; set popup.hover_key = false to leave K alone.

Configuration

setup merges your options over the defaults. Unknown options and values of the wrong type are reported and ignored:

require("hex-outdated").setup({
  enabled = true,            -- show status when a mix.exs opens (:HexOutdated toggle flips it per buffer)
  auto_update = true,        -- re-analyze on buffer changes
  debounce_ms = 500,         -- delay (milliseconds) before re-analyzing after an edit
  api = {
    base_url = "https://hex.pm/api",
    timeout_ms = 5000,          -- invalid/non-positive values use 5000
    max_concurrent = 8,        -- cap on simultaneous curl processes
  },
  lock = {
    enabled = true,            -- read mix.lock when present
    lens = false,              -- locked-version lens; off by default
    stale_diagnostic = true,   -- warn when the lock no longer satisfies the requirement
  },
  cache = {
    ttl_seconds = 3600,        -- how long a successful fetch is cached
    error_ttl_seconds = 60,    -- how long a failed fetch is cached before retry
  },
  text = {                   -- %s is the latest version; only %s and %% are format specifiers
    up_to_date = "✓ %s",
    upgradable = "↑ %s",
    outdated = "↓ %s",
    invalid = "✗ no such version",
    retired = "⚠ retired release",
    loading = "…",
    error = "fetch error",
    lock_behind = "locked %s · latest %s", -- lens line when the lock is behind
    lock_current = "locked %s · up to date",
  },
  highlight = {              -- highlight group per status
    up_to_date = "HexOutdatedUpToDate",
    upgradable = "HexOutdatedUpgradable",
    outdated = "HexOutdatedOutdated",
    invalid = "HexOutdatedInvalid",
    retired = "HexOutdatedRetired",
    loading = "HexOutdatedLoading",
    error = "HexOutdatedError",
    lock = "HexOutdatedLock",
    lock_behind = "HexOutdatedLockBehind",
  },
  popup = {
    border = "rounded",      -- any nvim_open_win() border: a style name or a character list
    max_height = 20,         -- max lines in the versions/info float
    hover_key = "K",         -- key for the detail float; false leaves K unmapped
  },
  -- buffer-local keymaps, action = lhs; actions are the :HexOutdated
  -- subcommands: refresh, toggle, upgrade, versions, open, info, lock
  keymaps = {}, -- e.g. { upgrade = "<leader>cu", versions = "<leader>cv", info = "<leader>ci" }
})

Highlight groups link to Diagnostic* by default and respect your colorscheme if you define them first: HexOutdatedUpToDate, HexOutdatedUpgradable, HexOutdatedOutdated, HexOutdatedInvalid, HexOutdatedRetired, HexOutdatedLoading, HexOutdatedError, HexOutdatedLock, HexOutdatedLockBehind.

How it works

hex-outdated parses mix.exs with Treesitter to find dependency tuples in the list the project's deps: setting names: an inline list, deps() (deps/0 by default), every clause of a call with arguments such as deps(Mix.env()), or a module attribute such as @deps. It falls back to a Lua line scanner in two cases: Neovim doesn't ship the elixir parser, and while you type the buffer is often syntactically incomplete, where Treesitter's error recovery can swallow neighboring dependency tuples. The scanner only needs to track strings, comments, and do/end blocks, so a half-written tuple doesn't hide the rest of the list. Treesitter stays the primary path because a real parse tree handles well-formed files without the scanner's heuristics. For a composed setting such as deps: deps() ++ extra(), only the leading call or list is read, and a list assembled through local variables is only read where its tuples sit in the returned expression. A Hex package alias such as {:local_app, "~> 2.0", hex: :actual_package} points the API lookup at the real package, while the local application name still keys into mix.lock. For each public Hex dependency the plugin asynchronously queries https://hex.pm/api/packages/:name (cached), sets retired releases aside, then compares your requirement against the active published versions using Hex prerelease semantics. The requirement status comes from mix.exs alone; the plugin reads mix.lock locally, and only for the optional lock context above. There is no shelling out to mix.

Development

just check     # fmt-check, lint, test, test-nvim
just test      # busted suite in spec/ (no Neovim)
just test-nvim # nvim --headless -u NONE -i NONE -l test/run.lua
just format    # stylua
just lint      # luacheck

spec/ holds specs that run without Neovim, stubbing the vim APIs a module touches. test/ holds specs that need a real editor (Treesitter, extmarks, diagnostics, jobs, buffers) and runs with only nvim on PATH.

CI runs stylua and luacheck on Ubuntu, busted (on LuaJIT, like Neovim) on Ubuntu and macOS, and the headless suite on Ubuntu, macOS, and Windows with stable Neovim plus Ubuntu with 0.10, the oldest supported release. The Ubuntu and macOS legs install the elixir Treesitter parser and set HEX_OUTDATED_REQUIRE_TS=1, so the Treesitter specs fail rather than skip if it is missing.

License

MIT © Justin Pease

About

A Neovim plugin that shows Hex dependency status inline in your Elixir mix.exs. Each dependency's latest version and status appears as virtual text as you type, with one-key upgrades and a versions browser.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages