refactor(config): nest integration toggles under integrations namespace

Problem: integration keys (`fugitive`, `neogit`, `gitsigns`, `committia`,
`telescope`) live at the top level of `vim.g.diffs`, cluttering the
config alongside unrelated options like `highlights` and `conflict`.

Solution: move them under `vim.g.diffs.integrations.*`. Old top-level
keys are migrated automatically with a `vim.deprecate` warning targeting
v0.3.2. `compute_filetypes` and `plugin/diffs.lua` fall back to legacy
keys for pre-`init()` callers.

lua/diffs/init.lua

@@ -61,16 +61,24 @@
 ---@field priority integer
 ---@field keymaps diffs.ConflictKeymaps
 
----@class diffs.Config
----@field debug boolean|string
----@field hide_prefix boolean
----@field extra_filetypes string[]
----@field highlights diffs.Highlights
+---@class diffs.IntegrationsConfig
 ---@field fugitive diffs.FugitiveConfig|false
 ---@field neogit diffs.NeogitConfig|false
 ---@field gitsigns diffs.GitsignsConfig|false
 ---@field committia diffs.CommittiaConfig|false
 ---@field telescope diffs.TelescopeConfig|false
+
+---@class diffs.Config
+---@field debug boolean|string
+---@field hide_prefix boolean
+---@field extra_filetypes string[]
+---@field highlights diffs.Highlights
+---@field integrations diffs.IntegrationsConfig
+---@field fugitive diffs.FugitiveConfig|false deprecated: use integrations.fugitive
+---@field neogit diffs.NeogitConfig|false deprecated: use integrations.neogit
+---@field gitsigns diffs.GitsignsConfig|false deprecated: use integrations.gitsigns
+---@field committia diffs.CommittiaConfig|false deprecated: use integrations.committia
+---@field telescope diffs.TelescopeConfig|false deprecated: use integrations.telescope
 ---@field conflict diffs.ConflictConfig
 
 ---@class diffs
@@ -148,11 +156,13 @@ local default_config = {
       char_bg = 201,
     },
   },
+  integrations = {
     fugitive = false,
     neogit = false,
     gitsigns = false,
     committia = false,
     telescope = false,
+  },
   conflict = {
     enabled = true,
     disable_diagnostics = true,
@@ -209,11 +219,18 @@ end
 ---@return string[]
 function M.compute_filetypes(opts)
   local fts = { 'git', 'gitcommit' }
-  local fug = opts.fugitive
+  local intg = opts.integrations or {}
+  local fug = intg.fugitive
+  if fug == nil then
+    fug = opts.fugitive
+  end
   if fug == true or type(fug) == 'table' then
     table.insert(fts, 'fugitive')
   end
-  local neo = opts.neogit
+  local neo = intg.neogit
+  if neo == nil then
+    neo = opts.neogit
+  end
   if neo == true or type(neo) == 'table' then
     table.insert(fts, 'NeogitStatus')
     table.insert(fts, 'NeogitCommitView')
@@ -584,6 +601,26 @@ local function compute_highlight_groups()
   end
 end
 
+local integration_keys = { 'fugitive', 'neogit', 'gitsigns', 'committia', 'telescope' }
+
+local function migrate_integrations(opts)
+  opts.integrations = opts.integrations or {}
+  for _, key in ipairs(integration_keys) do
+    if opts[key] ~= nil then
+      vim.deprecate(
+        'vim.g.diffs.' .. key,
+        'vim.g.diffs.integrations.' .. key,
+        '0.3.2',
+        'diffs.nvim'
+      )
+      if opts.integrations[key] == nil then
+        opts.integrations[key] = opts[key]
+      end
+      opts[key] = nil
+    end
+  end
+end
+
 local function init()
   if initialized then
     return
@@ -592,48 +629,45 @@ local function init()
 
   local opts = vim.g.diffs or {}
 
+  migrate_integrations(opts)
+
+  local intg = opts.integrations or {}
   local fugitive_defaults = { horizontal = 'du', vertical = 'dU' }
-  if opts.fugitive == true then
-    opts.fugitive = vim.deepcopy(fugitive_defaults)
-  elseif type(opts.fugitive) == 'table' then
-    opts.fugitive = vim.tbl_extend('keep', opts.fugitive, fugitive_defaults)
+  if intg.fugitive == true then
+    intg.fugitive = vim.deepcopy(fugitive_defaults)
+  elseif type(intg.fugitive) == 'table' then
+    intg.fugitive = vim.tbl_extend('keep', intg.fugitive, fugitive_defaults)
   end
 
-  if opts.neogit == true then
-    opts.neogit = {}
+  if intg.neogit == true then
+    intg.neogit = {}
   end
 
-  if opts.gitsigns == true then
-    opts.gitsigns = {}
+  if intg.gitsigns == true then
+    intg.gitsigns = {}
   end
 
-  if opts.committia == true then
-    opts.committia = {}
+  if intg.committia == true then
+    intg.committia = {}
   end
 
-  if opts.telescope == true then
-    opts.telescope = {}
+  if intg.telescope == true then
+    intg.telescope = {}
   end
 
+  opts.integrations = intg
+
   vim.validate('debug', opts.debug, function(v)
     return v == nil or type(v) == 'boolean' or type(v) == 'string'
   end, 'boolean or string (file path)')
   vim.validate('hide_prefix', opts.hide_prefix, 'boolean', true)
-  vim.validate('fugitive', opts.fugitive, function(v)
+  vim.validate('integrations', opts.integrations, 'table', true)
+  local integration_validator = function(v)
     return v == nil or v == false or type(v) == 'table'
-  end, 'table or false')
-  vim.validate('neogit', opts.neogit, function(v)
-    return v == nil or v == false or type(v) == 'table'
-  end, 'table or false')
-  vim.validate('gitsigns', opts.gitsigns, function(v)
-    return v == nil or v == false or type(v) == 'table'
-  end, 'table or false')
-  vim.validate('committia', opts.committia, function(v)
-    return v == nil or v == false or type(v) == 'table'
-  end, 'table or false')
-  vim.validate('telescope', opts.telescope, function(v)
-    return v == nil or v == false or type(v) == 'table'
-  end, 'table or false')
+  end
+  for _, key in ipairs(integration_keys) do
+    vim.validate('integrations.' .. key, intg[key], integration_validator, 'table or false')
+  end
   vim.validate('extra_filetypes', opts.extra_filetypes, 'table', true)
   vim.validate('highlights', opts.highlights, 'table', true)
 
@@ -704,13 +738,13 @@ local function init()
     end
   end
 
-  if type(opts.fugitive) == 'table' then
+  if type(intg.fugitive) == 'table' then
     ---@type diffs.FugitiveConfig
-    local fug = opts.fugitive
-    vim.validate('fugitive.horizontal', fug.horizontal, function(v)
+    local fug = intg.fugitive
+    vim.validate('integrations.fugitive.horizontal', fug.horizontal, function(v)
       return v == nil or v == false or type(v) == 'string'
     end, 'string or false')
-    vim.validate('fugitive.vertical', fug.vertical, function(v)
+    vim.validate('integrations.fugitive.vertical', fug.vertical, function(v)
       return v == nil or v == false or type(v) == 'string'
     end, 'string or false')
   end
@@ -934,7 +968,7 @@ function M.attach(bufnr)
   attached_buffers[bufnr] = true
 
   local neogit_augroup = nil
-  if config.neogit and vim.bo[bufnr].filetype:match('^Neogit') then
+  if config.integrations.neogit and vim.bo[bufnr].filetype:match('^Neogit') then
     vim.b[bufnr].neogit_disable_hunk_highlight = true
     neogit_augroup = vim.api.nvim_create_augroup('diffs_neogit_' .. bufnr, { clear = true })
     vim.api.nvim_create_autocmd('User', {
@@ -1014,19 +1048,19 @@ end
 ---@return diffs.FugitiveConfig|false
 function M.get_fugitive_config()
   init()
-  return config.fugitive
+  return config.integrations.fugitive
 end
 
 ---@return diffs.CommittiaConfig|false
 function M.get_committia_config()
   init()
-  return config.committia
+  return config.integrations.committia
 end
 
 ---@return diffs.TelescopeConfig|false
 function M.get_telescope_config()
   init()
-  return config.telescope
+  return config.integrations.telescope
 end
 
 ---@return diffs.ConflictConfig

plugin/diffs.lua

@@ -5,7 +5,17 @@ vim.g.loaded_diffs = 1
 
 require('diffs.commands').setup()
 
-local gs_cfg = (vim.g.diffs or {}).gitsigns
+local function get_raw_integration(key)
+  local user = vim.g.diffs or {}
+  local intg = user.integrations or {}
+  local v = intg[key]
+  if v ~= nil then
+    return v
+  end
+  return user[key]
+end
+
+local gs_cfg = get_raw_integration('gitsigns')
 if gs_cfg == true or type(gs_cfg) == 'table' then
   if not require('diffs.gitsigns').setup() then
     vim.api.nvim_create_autocmd('User', {
@@ -18,7 +28,7 @@ if gs_cfg == true or type(gs_cfg) == 'table' then
   end
 end
 
-local tel_cfg = (vim.g.diffs or {}).telescope
+local tel_cfg = get_raw_integration('telescope')
 if tel_cfg == true or type(tel_cfg) == 'table' then
   vim.api.nvim_create_autocmd('User', {
     pattern = 'TelescopePreviewerLoaded',

spec/init_spec.lua

@@ -336,45 +336,45 @@ describe('diffs', function()
       assert.are.same({ 'git', 'gitcommit' }, fts)
     end)
 
-    it('includes fugitive when fugitive = true', function()
-      local fts = compute({ fugitive = true })
+    it('includes fugitive when integrations.fugitive = true', function()
+      local fts = compute({ integrations = { fugitive = true } })
       assert.is_true(vim.tbl_contains(fts, 'fugitive'))
     end)
 
-    it('includes fugitive when fugitive is a table', function()
-      local fts = compute({ fugitive = { horizontal = 'dd' } })
+    it('includes fugitive when integrations.fugitive is a table', function()
+      local fts = compute({ integrations = { fugitive = { horizontal = 'dd' } } })
       assert.is_true(vim.tbl_contains(fts, 'fugitive'))
     end)
 
-    it('excludes fugitive when fugitive = false', function()
-      local fts = compute({ fugitive = false })
+    it('excludes fugitive when integrations.fugitive = false', function()
+      local fts = compute({ integrations = { fugitive = false } })
       assert.is_false(vim.tbl_contains(fts, 'fugitive'))
     end)
 
-    it('excludes fugitive when fugitive is nil', function()
-      local fts = compute({})
+    it('excludes fugitive when integrations.fugitive is nil', function()
+      local fts = compute({ integrations = {} })
       assert.is_false(vim.tbl_contains(fts, 'fugitive'))
     end)
 
-    it('includes neogit filetypes when neogit = true', function()
-      local fts = compute({ neogit = true })
+    it('includes neogit filetypes when integrations.neogit = true', function()
+      local fts = compute({ integrations = { neogit = true } })
       assert.is_true(vim.tbl_contains(fts, 'NeogitStatus'))
       assert.is_true(vim.tbl_contains(fts, 'NeogitCommitView'))
       assert.is_true(vim.tbl_contains(fts, 'NeogitDiffView'))
     end)
 
-    it('includes neogit filetypes when neogit is a table', function()
-      local fts = compute({ neogit = {} })
+    it('includes neogit filetypes when integrations.neogit is a table', function()
+      local fts = compute({ integrations = { neogit = {} } })
       assert.is_true(vim.tbl_contains(fts, 'NeogitStatus'))
     end)
 
-    it('excludes neogit when neogit = false', function()
-      local fts = compute({ neogit = false })
+    it('excludes neogit when integrations.neogit = false', function()
+      local fts = compute({ integrations = { neogit = false } })
       assert.is_false(vim.tbl_contains(fts, 'NeogitStatus'))
     end)
 
-    it('excludes neogit when neogit is nil', function()
-      local fts = compute({})
+    it('excludes neogit when integrations.neogit is nil', function()
+      local fts = compute({ integrations = {} })
       assert.is_false(vim.tbl_contains(fts, 'NeogitStatus'))
     end)
 
@@ -383,13 +383,31 @@ describe('diffs', function()
       assert.is_true(vim.tbl_contains(fts, 'diff'))
     end)
 
-    it('combines fugitive, neogit, and extra_filetypes', function()
-      local fts = compute({ fugitive = true, neogit = true, extra_filetypes = { 'diff' } })
+    it('combines integrations and extra_filetypes', function()
+      local fts = compute({
+        integrations = { fugitive = true, neogit = true },
+        extra_filetypes = { 'diff' },
+      })
       assert.is_true(vim.tbl_contains(fts, 'git'))
       assert.is_true(vim.tbl_contains(fts, 'fugitive'))
       assert.is_true(vim.tbl_contains(fts, 'NeogitStatus'))
       assert.is_true(vim.tbl_contains(fts, 'diff'))
     end)
+
+    it('falls back to legacy top-level fugitive key', function()
+      local fts = compute({ fugitive = true })
+      assert.is_true(vim.tbl_contains(fts, 'fugitive'))
+    end)
+
+    it('falls back to legacy top-level neogit key', function()
+      local fts = compute({ neogit = true })
+      assert.is_true(vim.tbl_contains(fts, 'NeogitStatus'))
+    end)
+
+    it('prefers integrations key over legacy top-level key', function()
+      local fts = compute({ integrations = { fugitive = false }, fugitive = true })
+      assert.is_false(vim.tbl_contains(fts, 'fugitive'))
+    end)
   end)
 
   describe('diff mode', function()

spec/neogit_integration_spec.lua

@@ -1,6 +1,6 @@
 require('spec.helpers')
 
-vim.g.diffs = { neogit = true }
+vim.g.diffs = { integrations = { neogit = true } }
 
 local diffs = require('diffs')
 local parser = require('diffs.parser')