zuqini · zuqini · May 19, 2026 · May 19, 2026
diff --git a/.busted b/.busted
@@ -0,0 +1,9 @@
+return {
+  default = {
+    ROOT = { 'tests' },
+    -- Each tests/*_test.lua is a native busted spec. Match only those: the
+    -- pattern is anchored so shared modules like pack_update_test_helpers.lua
+    -- (which carries the substring `_test`) are not discovered as specs.
+    pattern = '_test%.lua$',
+  },
+}
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -0,0 +1,57 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  luacheck:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up Lua
+        uses: leafo/gh-actions-lua@v13
+        with:
+          luaVersion: "luajit-2.1"
+
+      - name: Set up LuaRocks
+        uses: leafo/gh-actions-luarocks@v6
+
+      - name: Install luacheck
+        run: luarocks install luacheck
+
+      - name: Run luacheck
+        run: luacheck lua/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Install Neovim
+        uses: rhysd/action-setup-vim@v1
+        with:
+          neovim: true
+          version: v0.12.0
+
+      - name: Install lua-language-server
+        run: |
+          mkdir -p "$HOME/lua-ls"
+          curl -sL "https://github.com/LuaLS/lua-language-server/releases/download/${LUALS_VERSION}/lua-language-server-${LUALS_VERSION}-linux-x64.tar.gz" \
+            | tar -xz -C "$HOME/lua-ls"
+          echo "$HOME/lua-ls/bin" >> "$GITHUB_PATH"
+        env:
+          LUALS_VERSION: "3.17.1"
+
+      - name: Resolve VIMRUNTIME
+        run: echo "VIMRUNTIME=$(nvim --clean --headless --cmd 'lua io.write(vim.env.VIMRUNTIME)' --cmd 'quit')" >> "$GITHUB_ENV"
+
+      - name: Type-check lua/
+        run: lua-language-server --check "$PWD/lua" --checklevel=Warning --configpath="$PWD/.luarc.json"
diff --git a/.github/workflows/pr-tests.yml b/.github/workflows/pr-tests.yml
@@ -13,17 +13,24 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Install Neovim
         uses: rhysd/action-setup-vim@v1
         with:
           neovim: true
           version: ${{ matrix.neovim-version }}
 
-      - name: Run tests
-        run: nvim --version && nvim -u NONE --headless -S run_tests.lua
+      - name: Set up LuaJIT
+        uses: leafo/gh-actions-lua@v13
+        with:
+          luaVersion: "luajit-2.1"
+
+      - name: Set up LuaRocks
+        uses: leafo/gh-actions-luarocks@v6
 
-      - name: Check test results
-        if: failure()
-        run: echo "Tests failed - check logs above"
+      - name: Install busted
+        run: luarocks install --tree .luarocks busted 2.3.0
+
+      - name: Run tests
+        run: nvim --version && nvim -u NONE -l tests/busted.lua
diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
@@ -0,0 +1,18 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -13,17 +13,24 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Install Neovim
         uses: rhysd/action-setup-vim@v1
         with:
           neovim: true
           version: ${{ matrix.neovim-version }}
 
-      - name: Run tests
-        run: nvim --version && nvim -u NONE --headless -S run_tests.lua
+      - name: Set up LuaJIT
+        uses: leafo/gh-actions-lua@v13
+        with:
+          luaVersion: "luajit-2.1"
+
+      - name: Set up LuaRocks
+        uses: leafo/gh-actions-luarocks@v6
 
-      - name: Check test results
-        if: failure()
-        run: echo "Tests failed - check logs above"
+      - name: Install busted
+        run: luarocks install --tree .luarocks busted 2.3.0
+
+      - name: Run tests
+        run: nvim --version && nvim -u NONE -l tests/busted.lua
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,5 @@
 .DS_Store
 .claude/
+
+# Project-local LuaRocks tree (busted and its dependencies for tests)
+.luarocks/
diff --git a/.luacheckrc b/.luacheckrc
@@ -0,0 +1,25 @@
+-- Lint configuration for zpack.nvim.
+-- Warning reference: https://luacheck.readthedocs.io/en/stable/warnings.html
+
+std = "luajit"
+codes = true
+
+-- zpack runs inside Neovim; `vim` is an injected global.
+read_globals = { "vim" }
+
+-- The project has no line-length convention (no stylua/editorconfig). luacheck
+-- here guards correctness — unused/shadowed vars, undefined globals — not
+-- formatting, so the line-length check is left off.
+max_line_length = false
+
+-- The suite runs under busted (describe/it/assert globals). The harness also
+-- stubs vim.* (vim.notify, vim.pack.add, ...) and threads shared state
+-- through the _G.test_state table, so under tests/ `vim` is written to and
+-- `_G` is used directly. Test files also carry documentary callback args and
+-- assertion-scaffolding locals; their unused-variable hygiene (2xx/23x) is
+-- intentionally not linted.
+files["tests"] = {
+  std = "luajit+busted",
+  globals = { "vim", "_G" },
+  ignore = { "21", "23" },
+}
diff --git a/.luarc.json b/.luarc.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
+  "runtime": {
+    "version": "LuaJIT",
+    "path": ["lua/?.lua", "lua/?/init.lua", "tests/?.lua", "?.lua"]
+  },
+  "workspace": {
+    "library": ["$VIMRUNTIME/lua"],
+    "checkThirdParty": false
+  },
+  "diagnostics": {
+    "globals": ["vim"]
+  }
+}
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -0,0 +1,3 @@
+{
+  ".": "1.2.1"
+}
diff --git a/README.md b/README.md
@@ -93,6 +93,14 @@ On Neovim 0.13+, several subcommands map to native `vim.pack` commands you can u
 `clean`, `build`, and `load` have no native equivalent. The `:ZPack` subcommands are concise, consistent shortcuts — reach for the native commands when you want their extra flags (e.g. `:packupdate ++offline`).
 
 
+#### Health Check
+
+Run `:checkhealth zpack` to diagnose a broken or unexpected setup. It verifies
+the Neovim version and `vim.pack` availability, whether `setup()` was called,
+validates your configuration (flagging deprecated options), and prints a
+status summary of every registered plugin.
+
+
 #### Configurations
 
 ```lua

diff --git a/doc/zpack.txt b/doc/zpack.txt
@@ -241,6 +241,29 @@ performance     (table, optional)
                 Performance-related settings.
                   - `vim_loader`: Enable vim.loader caching. Default: `true`
 
+------------------------------------------------------------------------------
+4.6 HEALTH CHECK                                              *zpack-health*
+
+zpack ships a healthcheck. Run it to diagnose a broken or unexpected setup: >
+
+    :checkhealth zpack
+<
+The report has these sections:
+
+Environment     Confirms Neovim is 0.12.0+ and that `vim.pack` is available.
+
+Setup           Whether |zpack.setup()| has been called. zpack is inactive
+                until it has.
+
+Configuration   Validates the resolved |zpack-setup-options| and lists any
+                deprecated or removed options still in use, with their
+                replacements.
+
+Plugins         A status summary of every registered plugin: how many are
+                loaded, lazy, pending, installing, or disabled by `cond`.
+
+Reporting a bug A minimal-config template and the steps for filing an issue.
+
 ==============================================================================
 5. WHY ZPACK?                                                *zpack-why-zpack*
 

diff --git a/lua/zpack/deprecation.lua b/lua/zpack/deprecation.lua
@@ -1,7 +1,24 @@
+-- Deprecation and removal notices for zpack.
+--
+-- This custom layer is kept deliberately rather than migrated to
+-- vim.deprecate(); the evaluation:
+--   * Legacy :<prefix><Suffix> commands notify on EVERY invocation (see
+--     notify_legacy_command) so a notice that scrolled past is not lost.
+--     vim.deprecate() routes through vim.notify_once and would dedup it,
+--     conflicting with that intent.
+--   * `add`/`auto_import` are already removed, not pending removal, so
+--     vim.deprecate()'s "will be removed in version X" framing is wrong.
+--   * The option notices below carry copy-paste replacement snippets that
+--     vim.deprecate()'s single-line `alternative` argument cannot express.
+-- Deprecated options actually in use are also surfaced by :checkhealth zpack.
+
 local utils = require('zpack.utils')
 
 local M = {}
 
+-- Every M.removed/M.deprecated entry must carry both `message` and
+-- `replacement` strings: notify_removed/notify_deprecated format them
+-- unguarded, and :checkhealth zpack splits `replacement` into advice lines.
 M.removed = {
   add = {
     message = "zpack.add() has been removed. Pass specs directly to setup():",
@@ -34,6 +51,16 @@ M.deprecated = {
   },
 }
 
+-- setup() option keys that are deprecated or removed, for :checkhealth zpack
+-- to report when one is still passed. Kept here as the single authoritative
+-- list rather than derived from M.removed/M.deprecated: M.removed also holds
+-- `add` (a removed function, not an option key) and `cmd_prefix` has only
+-- computed notices with no static entry — so the key set is neither table's
+-- keys. Update this list whenever M.removed/M.deprecated gains an option.
+M.deprecated_option_keys = {
+  'cmd_prefix', 'confirm', 'disable_vim_loader', 'plugins_dir', 'auto_import',
+}
+
 M.notify_removed = function(key)
   local entry = M.removed[key]
   if not entry then return end