feat: warn about semver-like version on vim.pack.add error

When vim.pack.add fails, detect if user has semver-like version
strings (e.g., "1.*", "^1.0.0") and suggest using sem_version
instead. This helps users who may have confused the version field
(expects branch/tag/commit) with sem_version (semver ranges).

Also:
- Add utils.notify with consistent [zpack.nvim] prefix
- Remove redundant [zpack] prefix from deprecation messages
- Fix test framework to cleanup on failure (prevent cascading)

Author: zuqini

lua/zpack/deprecation.lua

@@ -38,7 +38,7 @@ M.notify_removed = function(key)
   local entry = M.removed[key]
   if not entry then return end
   utils.schedule_notify(
-    ("[zpack] REMOVED: %s\n\n%s"):format(entry.message, entry.replacement),
+    ("REMOVED: %s\n\n%s"):format(entry.message, entry.replacement),
     vim.log.levels.WARN
   )
 end
@@ -47,7 +47,7 @@ M.notify_deprecated = function(key)
   local entry = M.deprecated[key]
   if not entry then return end
   utils.schedule_notify(
-    ("[zpack] DEPRECATED: %s\n\n%s"):format(entry.message, entry.replacement),
+    ("DEPRECATED: %s\n\n%s"):format(entry.message, entry.replacement),
     vim.log.levels.WARN
   )
 end

lua/zpack/init.lua

@@ -27,9 +27,7 @@ end
 
 local function check_version()
   if vim.fn.has('nvim-0.12') ~= 1 then
-    vim.schedule(function()
-      vim.notify('zpack.nvim requires Neovim 0.12+', vim.log.levels.ERROR)
-    end)
+    require('zpack.utils').schedule_notify('requires Neovim 0.12+', vim.log.levels.ERROR)
     return false
   end
   return true

lua/zpack/registration.lua

@@ -6,7 +6,7 @@ local M = {}
 
 ---@param ctx zpack.ProcessContext
 M.register_all = function(ctx)
-  vim.pack.add(ctx.vim_packs, {
+  local ok, err = pcall(vim.pack.add, ctx.vim_packs, {
     confirm = ctx.confirm,
     load = function(plugin)
       local pack_spec = plugin.spec
@@ -43,6 +43,24 @@ M.register_all = function(ctx)
     end
   })
 
+  if not ok then
+    local semver_like_specs = {}
+    for _, pack_spec in ipairs(ctx.vim_packs) do
+      if pack_spec.version and utils.is_semver_like(pack_spec.version) then
+        table.insert(semver_like_specs, pack_spec)
+      end
+    end
+    for _, pack_spec in ipairs(semver_like_specs) do
+      utils.schedule_notify(
+        ('Is `version = "%s"` for %s meant to be a semver range?\n'
+          .. 'Consider using `sem_version = "%s"` or `version = vim.version.range("%s")` instead.')
+          :format(pack_spec.version, pack_spec.src, pack_spec.version, pack_spec.version),
+        vim.log.levels.WARN
+      )
+    end
+    error(err)
+  end
+
   table.sort(ctx.registered_startup_packs, utils.compare_priority)
   table.sort(ctx.registered_lazy_packs, utils.compare_priority)
   table.sort(state.registered_plugin_names, function(a, b) return a:lower() < b:lower() end)

lua/zpack/utils.lua

@@ -42,9 +42,13 @@ M.reset_lsdir_cache = function()
   lsdir_cache = {}
 end
 
+M.notify = function(msg, level)
+  vim.notify('[zpack.nvim] ' .. msg, level)
+end
+
 M.schedule_notify = function(msg, level)
   vim.schedule(function()
-    vim.notify(msg, level)
+    M.notify(msg, level)
   end)
 end
 
@@ -168,6 +172,21 @@ M.normalize_name = function(name)
   return norm
 end
 
+---Check if a string looks like a semver range (not a branch/tag/commit)
+---@param str any
+---@return boolean
+M.is_semver_like = function(str)
+  if type(str) ~= 'string' then
+    return false
+  end
+  return str:match('%*') ~= nil
+      or str:match('^%d[%d%.]*%.[xX]$') ~= nil
+      or str:match('^%d[%d%.]*%.%a') ~= nil
+      or str:match('^[>=<^~]') ~= nil
+      or str:match('[>=<]') ~= nil
+      or str:match('^%d+[%d%.]*$') ~= nil
+end
+
 ---Normalize plugin version using priority: version > sem_version > branch > tag > commit
 ---@param spec zpack.Spec
 ---@return string|vim.VersionRange|nil version

tests/helpers.lua

@@ -1,3 +1,4 @@
+---@diagnostic disable: duplicate-set-field
 local M = {}
 
 M.test_results = {}
@@ -74,6 +75,7 @@ function M.test(name, fn)
     table.insert(M.test_results, { name = name, passed = false, error = err })
     print(string.format("✗ %s", name))
     print(string.format("  Error: %s", err))
+    M.cleanup_test_env()
   end
 end
 

tests/module_loader_test.lua

@@ -1,3 +1,4 @@
+---@diagnostic disable: duplicate-set-field
 local helpers = require('helpers')
 
 return function()

tests/utils_test.lua

@@ -118,4 +118,74 @@ return function()
       helpers.cleanup_test_env()
     end)
   end)
+
+  helpers.describe("is_semver_like utility", function()
+    helpers.test("detects wildcard patterns", function()
+      helpers.setup_test_env()
+      local utils = require('zpack.utils')
+
+      helpers.assert_equal(utils.is_semver_like('1.*'), true)
+      helpers.assert_equal(utils.is_semver_like('*'), true)
+      helpers.assert_equal(utils.is_semver_like('1.2.*'), true)
+      helpers.assert_equal(utils.is_semver_like('1.2.x'), true)
+      helpers.assert_equal(utils.is_semver_like('1.x'), true)
+      helpers.assert_equal(utils.is_semver_like('1.X'), true)
+      helpers.assert_equal(utils.is_semver_like('1.2.X'), true)
+      helpers.assert_equal(utils.is_semver_like('1.2.y'), true)
+      helpers.assert_equal(utils.is_semver_like('1.a.b'), true)
+
+      helpers.cleanup_test_env()
+    end)
+
+    helpers.test("detects range operators", function()
+      helpers.setup_test_env()
+      local utils = require('zpack.utils')
+
+      helpers.assert_equal(utils.is_semver_like('>=1.0.0'), true)
+      helpers.assert_equal(utils.is_semver_like('<=2.0.0'), true)
+      helpers.assert_equal(utils.is_semver_like('>1.0'), true)
+      helpers.assert_equal(utils.is_semver_like('<2.0'), true)
+      helpers.assert_equal(utils.is_semver_like('^1.0.0'), true)
+      helpers.assert_equal(utils.is_semver_like('~1.0.0'), true)
+      helpers.assert_equal(utils.is_semver_like('foo=bar'), true)
+
+      helpers.cleanup_test_env()
+    end)
+
+    helpers.test("detects bare semver patterns", function()
+      helpers.setup_test_env()
+      local utils = require('zpack.utils')
+
+      helpers.assert_equal(utils.is_semver_like('1.0.0'), true)
+      helpers.assert_equal(utils.is_semver_like('1.2'), true)
+      helpers.assert_equal(utils.is_semver_like('1.2.3.4'), true)
+
+      helpers.cleanup_test_env()
+    end)
+
+    helpers.test("returns false for branch/tag names", function()
+      helpers.setup_test_env()
+      local utils = require('zpack.utils')
+
+      helpers.assert_equal(utils.is_semver_like('main'), false)
+      helpers.assert_equal(utils.is_semver_like('master'), false)
+      helpers.assert_equal(utils.is_semver_like('v1.0.0'), false)
+      helpers.assert_equal(utils.is_semver_like('v1.x'), false)
+      helpers.assert_equal(utils.is_semver_like('release-1.0'), false)
+      helpers.assert_equal(utils.is_semver_like('feature/foo'), false)
+
+      helpers.cleanup_test_env()
+    end)
+
+    helpers.test("returns false for non-strings", function()
+      helpers.setup_test_env()
+      local utils = require('zpack.utils')
+
+      helpers.assert_equal(utils.is_semver_like(nil), false)
+      helpers.assert_equal(utils.is_semver_like(123), false)
+      helpers.assert_equal(utils.is_semver_like({}), false)
+
+      helpers.cleanup_test_env()
+    end)
+  end)
 end

tests/version_test.lua

@@ -1,3 +1,4 @@
+---@diagnostic disable: duplicate-set-field
 local helpers = require('helpers')
 
 return function()
@@ -213,5 +214,78 @@ return function()
 
       helpers.cleanup_test_env()
     end)
+
+    helpers.test("semver-like version emits warning when vim.pack.add fails", function()
+      helpers.setup_test_env()
+
+      local mock_vim_pack_add = vim.pack.add
+      vim.pack.add = function()
+        error("some error from vim.pack.add")
+      end
+
+      local ok = pcall(function()
+        require('zpack').setup({
+          spec = {
+            {
+              'test/plugin',
+              version = '1.*',
+            },
+          },
+          defaults = { confirm = false },
+        })
+      end)
+
+      helpers.flush_pending()
+      helpers.assert_equal(ok, false, "setup should fail when vim.pack.add throws")
+      helpers.assert_equal(#_G.test_state.notifications >= 1, true, "warning should be emitted")
+
+      local found_warning = false
+      for _, notif in ipairs(_G.test_state.notifications) do
+        if notif.msg:match('%[zpack%.nvim%]') and notif.msg:match('sem_version') and notif.msg:match('1%.%*') then
+          found_warning = true
+          break
+        end
+      end
+      helpers.assert_equal(found_warning, true, "warning should have [zpack.nvim] prefix and mention sem_version")
+
+      vim.pack.add = mock_vim_pack_add
+      helpers.cleanup_test_env()
+    end)
+
+    helpers.test("no warning when vim.pack.add fails but no semver-like versions", function()
+      helpers.setup_test_env()
+
+      local mock_vim_pack_add = vim.pack.add
+      vim.pack.add = function()
+        error("some error from vim.pack.add")
+      end
+
+      local ok = pcall(function()
+        require('zpack').setup({
+          spec = {
+            {
+              'test/plugin',
+              version = 'nonexistent-branch',
+            },
+          },
+          defaults = { confirm = false },
+        })
+      end)
+
+      helpers.flush_pending()
+      helpers.assert_equal(ok, false, "setup should fail when vim.pack.add throws")
+
+      local found_warning = false
+      for _, notif in ipairs(_G.test_state.notifications) do
+        if notif.msg:match('sem_version') then
+          found_warning = true
+          break
+        end
+      end
+      helpers.assert_equal(found_warning, false, "no warning should be emitted for non-semver-like versions")
+
+      vim.pack.add = mock_vim_pack_add
+      helpers.cleanup_test_env()
+    end)
   end)
 end