refactor: move pack_spec creation from import to merge phase

- Remove pack_spec creation from import.lua (just registers specs now)
- Create pack_specs in merge.resolve_all() with correct merged data
- Return sorted vim_packs array from resolve_all()
- Fix KeySpec type annotation in utils.lua

Author: zuqini

README.md

@@ -10,18 +10,16 @@ A thin layer on top of Neovim's native `vim.pack`, adding support for lazy-loadi
 ```lua
 -- ./lua/plugins/fundo.lua
 return {
-  {
-    'kevinhwang91/nvim-fundo',
-    dependencies = { "kevinhwang91/promise-async" },
-    cond = not vim.g.vscode,
-    version = 'main',
-    build = function() require('fundo').install() end,
-    opts = {},
-    config = function(_, opts)
-      vim.o.undofile = true
-      require('fundo').setup(opts)
-    end,
-  },
+  'kevinhwang91/nvim-fundo',
+  dependencies = { "kevinhwang91/promise-async" },
+  cond = not vim.g.vscode,
+  version = 'main',
+  build = function() require('fundo').install() end,
+  opts = {},
+  config = function(_, opts)
+    vim.o.undofile = true
+    require('fundo').setup(opts)
+  end,
 }
 ```
 
@@ -46,25 +44,8 @@ vim.pack.add({ 'https://github.com/zuqini/zpack.nvim' })
 vim.g.mapleader = " "
 vim.g.maplocalleader = "\\"
 
--- automatically import specs from `/lua/plugins/`
+-- automatically import specs from `./lua/plugins/`
 require('zpack').setup()
-
--- or import from a custom directory e.g. `/lua/a/b/plugins/`
-require('zpack').setup({ { import = 'a.b.plugins' } })
-
--- or add your specs inline in setup
-require('zpack').setup({
-  { 'neovim/nvim-lspconfig', config = function() ... end },
-  { import = 'plugins.mini' }, -- additionally import from `/lua/plugins/mini/`
-})
-
--- or via the spec field
-require('zpack').setup({
-  spec = {
-    { 'neovim/nvim-lspconfig', config = function() ... end },
-    { import = 'plugins.mini' }, -- additionally import from `/lua/plugins/mini/`
-  },
-})
 ```
 
 ### Commands
@@ -122,20 +103,45 @@ require('zpack').setup({
 
 Plugin-level settings always take precedence over `defaults`.
 
+### Importing Specs
+
+```lua
+-- automatically import specs from `./lua/plugins/`
+require('zpack').setup()
+
+-- or import from a custom directory e.g. `./lua/a/b/plugins/`
+require('zpack').setup({ { import = 'a.b.plugins' } })
+
+-- or add your specs inline in setup
+require('zpack').setup({
+  { 'neovim/nvim-lspconfig', config = function() ... end },
+  ...
+  { import = 'plugins.mini' }, -- or additionally import from `./lua/plugins/mini/`
+})
+
+-- or via the spec field
+require('zpack').setup({
+  spec = {
+    { 'neovim/nvim-lspconfig', config = function() ... end },
+    ...
+  },
+})
+```
+
 ## Why zpack?
 
 Neovim 0.12+ includes a built-in package manager (`vim.pack`) that handles plugin installation, updates, and version management. zpack is a thin layer that adds lazy-loading capabilities and support for a lazy.nvim-like declarative spec while completely leveraging the native infrastructure.
 
 #### Features
-- z***pack*** is completely native
-    - Install and manage your plugins _(including zpack)_ all within `vim.pack`.
-- ⚡pack is "batteries included":
-    - Add plugins using the same lazy.nvim spec provided by plugin authors you know and love, with minimal configuration
-- 💤pack powers up `vim.pack` without the bells and whistles
+- [z***pack***] is completely native
+    - Install and manage your plugins _(including zpack)_ all within `vim.pack`
+- [🔋pack] is "batteries included"
+    - Add plugins using the same lazy.nvim spec provided by plugin authors you know and love
+    - Minimal configurations necessary
+- [💤pack] powers up `vim.pack` without the frills
+    - Powerful lazy-loading triggers
     - Build triggers for installation/updates
     - Basic plugin management commands
-    - Powerful lazy-loading triggers
-
 
 zpack might be for you if:
 - you're a lazy.nvim user, love its declarative spec, and its wide adoption by plugin authors, but you don't need most of its advanced features
@@ -150,6 +156,8 @@ As a thin layer, zpack does not provide:
 - UI dashboard for your plugins
 - Advanced profiling, dev mode, change-detection, etc.
 
+If you're a lazy.nvim user, see [Migrating from lazy.nvim](#migrating-from-lazynvim)
+
 ## Examples
 For more examples, refer to my personal config:
 - [zpack installation and setup](https://github.com/zuqini/nvim/blob/main/init.lua)
@@ -347,6 +355,7 @@ return {
   { 'nvim-lua/plenary.nvim' },
   { 'nvim-tree/nvim-web-devicons' },
   { 'nvim-lualine/lualine.nvim', opts = { theme = 'auto' } },
+  { import = 'plugins.mini' },
 }
 ```
 

doc/zpack.txt

@@ -14,18 +14,16 @@ lazy-loading and the widely adopted lazy.nvim-like declarative spec.
 >lua
     -- ./lua/plugins/fundo.lua
     return {
-      {
-        'kevinhwang91/nvim-fundo',
-        dependencies = { "kevinhwang91/promise-async" },
-        cond = not vim.g.vscode,
-        version = 'main',
-        build = function() require('fundo').install() end,
-        opts = {},
-        config = function(_, opts)
-          vim.o.undofile = true
-          require('fundo').setup(opts)
-        end,
-      },
+      'kevinhwang91/nvim-fundo',
+      dependencies = { "kevinhwang91/promise-async" },
+      cond = not vim.g.vscode,
+      version = 'main',
+      build = function() require('fundo').install() end,
+      opts = {},
+      config = function(_, opts)
+        vim.o.undofile = true
+        require('fundo').setup(opts)
+      end,
     }
 <
 
@@ -51,25 +49,8 @@ Install zpack.nvim via vim.pack.add():
     vim.g.mapleader = " "
     vim.g.maplocalleader = "\\"
 
-    -- automatically import specs from `/lua/plugins/`
+    -- automatically import specs from `./lua/plugins/`
     require('zpack').setup()
-
-    -- or import from a custom directory e.g. `/lua/a/b/plugins/`
-    require('zpack').setup({ { import = 'a.b.plugins' } })
-
-    -- or add your specs inline in setup
-    require('zpack').setup({
-      { 'neovim/nvim-lspconfig', config = function() ... end },
-      { import = 'plugins.mini' }, -- additionally import from `/lua/plugins/mini/`
-    })
-
-    -- or via the spec field
-    require('zpack').setup({
-      spec = {
-        { 'neovim/nvim-lspconfig', config = function() ... end },
-        { import = 'plugins.mini' }, -- additionally import from `/lua/plugins/mini/`
-      },
-    })
 <
 
 ------------------------------------------------------------------------------
@@ -162,7 +143,33 @@ Each file returns a spec or list of specs (see |zpack-examples| or
 Plugin-level settings always take precedence over `defaults`.
 
 ------------------------------------------------------------------------------
-4.4 SETUP OPTIONS                                      *zpack-setup-options*
+4.4 IMPORTING SPECS                                    *zpack-importing-specs*
+
+>lua
+    -- automatically import specs from `./lua/plugins/`
+    require('zpack').setup()
+
+    -- or import from a custom directory e.g. `./lua/a/b/plugins/`
+    require('zpack').setup({ { import = 'a.b.plugins' } })
+
+    -- or add your specs inline in setup
+    require('zpack').setup({
+      { 'neovim/nvim-lspconfig', config = function() ... end },
+      ...
+      { import = 'plugins.mini' }, -- or additionally import from `./lua/plugins/mini/`
+    })
+
+    -- or via the spec field
+    require('zpack').setup({
+      spec = {
+        { 'neovim/nvim-lspconfig', config = function() ... end },
+        ...
+      },
+    })
+<
+
+------------------------------------------------------------------------------
+4.5 SETUP OPTIONS                                      *zpack-setup-options*
 
 The `setup()` function accepts the following options:
 
@@ -216,7 +223,19 @@ performance     (table, optional)
 Neovim 0.12+ includes a built-in package manager (`vim.pack`) that handles
 plugin installation, updates, and version management. zpack is a thin layer
 that adds lazy-loading capabilities and support for a lazy.nvim-like
-declarative spec while leveraging the native infrastructure.
+declarative spec while completely leveraging the native infrastructure.
+
+Features:
+- completely native
+    - Install and manage your plugins (including zpack) all within `vim.pack`
+- batteries included
+    - Add plugins using the same lazy.nvim spec provided by plugin authors
+      you know and love
+    - Minimal configurations necessary
+- powers up `vim.pack` without the frills
+    - Powerful lazy-loading triggers
+    - Build triggers for installation/updates
+    - Basic plugin management commands
 
 zpack might be for you if:
 - you're a lazy.nvim user, love its declarative spec, and its wide adoption
@@ -235,6 +254,8 @@ As a thin layer, zpack does not provide:
 - UI dashboard for your plugins
 - Advanced profiling, dev mode, change-detection, etc.
 
+If you're a lazy.nvim user, see |zpack-migrating-lazy|.
+
 Although you can achieve most of these through other means. See
 |zpack-migrating-lazy|. If something you need isn't achievable natively or
 through zpack, please submit an issue or PR!
@@ -449,6 +470,7 @@ Define multiple plugins in a single file:
       { 'nvim-lua/plenary.nvim' },
       { 'nvim-tree/nvim-web-devicons' },
       { 'nvim-lualine/lualine.nvim', opts = { theme = 'auto' } },
+      { import = 'plugins.mini' },
     }
 <
 

lua/zpack/import.lua

@@ -169,9 +169,6 @@ M.import_specs = function(spec_item_or_list, ctx)
       table.insert(state.spec_registry[src].specs, spec)
     else
       state.spec_registry[src] = { specs = { spec }, load_status = "pending" }
-      local pack_spec = { src = src, version = utils.normalize_version(spec), name = spec.name }
-      table.insert(ctx.vim_packs, pack_spec)
-      state.src_to_pack_spec[src] = pack_spec
     end
 
     if spec.dependencies then

lua/zpack/init.lua

@@ -16,7 +16,6 @@ local M = {}
 local function create_context(opts)
   opts = opts or {}
   return {
-    vim_packs = {},
     src_with_init = {},
     registered_startup_packs = {},
     registered_lazy_packs = {},
@@ -70,7 +69,7 @@ local process_all = function(ctx)
   local state = require('zpack.state')
 
   vim.api.nvim_clear_autocmds({ group = state.lazy_build_group })
-  require('zpack.merge').resolve_all()
+  ctx.vim_packs = require('zpack.merge').resolve_all()
   hooks.setup_build_tracking()
   require('zpack.registration').register_all(ctx)
 

lua/zpack/merge.lua

@@ -231,22 +231,31 @@ function M.resolve_opts(specs, plugin)
 end
 
 ---Pre-compute merged_spec for all entries in the registry
----Also updates pack_spec.version based on merged specs
+---Creates pack_specs with merged data and returns sorted vim_packs array
+---@return vim.pack.Spec[]
 function M.resolve_all()
   local state = require('zpack.state')
   local utils = require('zpack.utils')
 
+  local vim_packs = {}
+
   for src, entry in pairs(state.spec_registry) do
     if entry.specs and #entry.specs > 0 then
       entry.sorted_specs = M.sort_specs(entry.specs)
       entry.merged_spec = M.merge_spec_array(entry.sorted_specs)
 
-      local pack_spec = state.src_to_pack_spec[src]
-      if pack_spec then
-        pack_spec.version = utils.normalize_version(entry.merged_spec)
-      end
+      local pack_spec = {
+        src = src,
+        version = utils.normalize_version(entry.merged_spec),
+        name = entry.merged_spec.name,
+      }
+      table.insert(vim_packs, pack_spec)
+      state.src_to_pack_spec[src] = pack_spec
     end
   end
+
+  table.sort(vim_packs, utils.compare_priority)
+  return vim_packs
 end
 
 return M

lua/zpack/utils.lua

@@ -95,7 +95,7 @@ M.normalize_keys = function(keys)
   -- Normalize to always be an array
   local key_list = (type(keys) == "string" or (keys[1] and type(keys[1]) == "string"))
       and { keys }
-      or keys --[[@as string[]|KeySpec[] ]]
+      or keys --[[@as string[]|zpack.KeySpec[] ]]
 
   local result = {}
   for _, key in ipairs(key_list) do