third_party.md

Third-party integrations

• Lualine
• Heirline
• Neotest
• DAP
• Session managers
  • resession.nvim
  • Other session managers

Lualine

There is a drop-in lualine component available. Use like:

require("lualine").setup({
  sections = {
    lualine_x = { "overseer" },
  },
})

Or with options:

require("lualine").setup({
  sections = {
    lualine_x = {
      {
        "overseer",
        label = "", -- Prefix for task counts
        colored = true, -- Color the task icons and counts
        symbols = {
          [overseer.STATUS.FAILURE] = "F:",
          [overseer.STATUS.CANCELED] = "C:",
          [overseer.STATUS.SUCCESS] = "S:",
          [overseer.STATUS.RUNNING] = "R:",
        },
        unique = false, -- Unique-ify non-running task count by name
        status = nil, -- List of task statuses to display
        filter = nil, -- Function to filter out tasks you don't wish to display
      },
    },
  },
})

Heirline

Here is a recipe for using Overseer with heirline

local Spacer = { provider = " " }
local function rpad(child)
  return {
    condition = child.condition,
    child,
    Spacer,
  }
end
local function OverseerTasksForStatus(status)
  return {
    condition = function(self)
      return self.tasks[status]
    end,
    provider = function(self)
      return string.format("%s%d", self.symbols[status], #self.tasks[status])
    end,
    hl = function(self)
      return {
        fg = utils.get_highlight(string.format("Overseer%s", status)).fg,
      }
    end,
  }
end

local Overseer = {
  condition = function()
    return package.loaded.overseer
  end,
  init = function(self)
    local tasks = require("overseer.task_list").list_tasks({ unique = true, include_ephemeral = true })
    local tasks_by_status = require("overseer.util").tbl_group_by(tasks, "status")
    self.tasks = tasks_by_status
  end,
  static = {
    symbols = {
      ["CANCELED"] = " ",
      ["FAILURE"] = "󰅚 ",
      ["SUCCESS"] = "󰄴 ",
      ["RUNNING"] = "󰑮 ",
    },
  },

  rpad(OverseerTasksForStatus("CANCELED")),
  rpad(OverseerTasksForStatus("RUNNING")),
  rpad(OverseerTasksForStatus("SUCCESS")),
  rpad(OverseerTasksForStatus("FAILURE")),
}

Neotest

To run all neotest processes using overseer, add it as a custom consumer:

require("neotest").setup({
  consumers = {
    overseer = require("neotest.consumers.overseer"),
  },
})

This will automatically hook neotest.run and force it to use overseer to run tests wherever possible. If you would instead like to only use the overseer consumer explicitly, you can disable the monkey patching:

require("neotest").setup({
  consumers = {
    overseer = require("neotest.consumers.overseer"),
  },
  overseer = {
    enabled = true,
    -- When this is true (the default), it will replace all neotest.run.* commands
    force_default = false,
  },
})

-- Now neotest.run is unchanged; to run tests with overseer use:
neotest.overseer.run({})

You can customize the default components of neotest tasks by setting the default_neotest component alias (when unset it maps to default).

require("overseer").setup({
  component_aliases = {
    default_neotest = {
      "on_exit_set_status",
      "on_complete_notify",
      "on_complete_dispose",
    },
  },
})

You can also customize the components by passing them in to the strategy spec for neotest. This can be a normal list of components, or a function that returns a list of components like so:

require("neotest").setup({
  strategies = {
    overseer = {
      components = function(run_spec)
        return {
          { "dependencies", tasks = {
            { cmd = "sleep 4" },
          } },
          "default_neotest",
        }
      end,
    },
  },
})

DAP

If you have both overseer and nvim-dap installed, overseer will automatically run the preLaunchTask and postDebugTask when present in a debug configuration. No special configuration or action is needed.

For lazy-loading, you may wish to avoid loading nvim-dap when overseer is loaded. If so, you can disable DAP support initially:

require("overseer").setup({
  dap = false,
})

And enable the integration manually later, such as when nvim-dap is loaded:

require("overseer").enable_dap()

Session managers

resession.nvim

Overseer has built-in support for resession.nvim.

require("resession").setup({
  extensions = {
    overseer = {
      -- customize here
    },
  },
})

The configuration options will be passed to list_tasks, and determine which tasks will be saved when saving a session.

Other session managers

For other session managers, the API allows you to list and serialize tasks. As long as your session manager has some way to store auxiliary data, you can use this to save and restore tasks.

For example, to integrate with auto-session

require("auto-session").setup({
  pre_save_cmds = {
    function()
      local tasks = require("overseer.task_list").list_tasks()
      local cmds = {}
      for _, task in ipairs(tasks) do
        local json = vim.json.encode(task:serialize())
        -- For some reason, vim.json.encode encodes / as \/.
        json = string.gsub(json, "\\/", "/")
        -- Escape single quotes so we can put this inside single quotes
        json = string.gsub(json, "'", "\\'")
        table.insert(cmds, string.format("lua require('overseer').new_task(vim.json.decode('%s')):start()", json))
      end
      return cmds
    end,
  },
  -- Optionally get rid of all previous tasks when restoring a session
  pre_restore_cmds = {
    function()
      for _, task in ipairs(require("overseer").list_tasks({})) do
        task:dispose(true)
      end
    end,
  },
})