From c5ddc54fefdb5b2fd0e1344fc3a1209af8af93b4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ricardo=20Cas=C3=ADa?=
 <31012661+rcasia@users.noreply.github.com>
Date: Wed, 23 Sep 2026 16:46:10 +0200
Subject: [PATCH 1/2] feat(lux): migrate project to lux package manager

---
 .github/workflows/ci-pipeline.yml     |   2 +
 .github/workflows/e2e-test.yml        |   3 +
 .github/workflows/luarocks.yml        |  47 ++++++----
 .github/workflows/lux.yml             |  39 ++++++++
 .github/workflows/static-analysis.yml |   6 ++
 .github/workflows/test.yml            |   3 +
 .gitignore                            |   4 +
 .luarc.json                           |  42 +++++----
 CONTRIBUTING.md                       |  29 ++++++
 Makefile                              |  17 +++-
 README.md                             |  12 +++
 lux.lock                              | 126 ++++++++++++++++++++++++++
 lux.toml                              |  27 ++++++
 13 files changed, 320 insertions(+), 37 deletions(-)
 create mode 100644 .github/workflows/lux.yml
 create mode 100644 lux.lock
 create mode 100644 lux.toml

diff --git a/.github/workflows/ci-pipeline.yml b/.github/workflows/ci-pipeline.yml
index 1406ee84..1c7b071a 100644
--- a/.github/workflows/ci-pipeline.yml
+++ b/.github/workflows/ci-pipeline.yml
@@ -9,6 +9,8 @@ on:
       - "scripts/**"
       - "*.lua"
       - "Makefile"
+      - "lux.toml"
+      - "lux.lock"
       - ".github/workflows/**"
 
 jobs:
diff --git a/.github/workflows/e2e-test.yml b/.github/workflows/e2e-test.yml
index 2c11265f..72bbd1c2 100644
--- a/.github/workflows/e2e-test.yml
+++ b/.github/workflows/e2e-test.yml
@@ -11,7 +11,10 @@ on:
       - "scripts/**"
       - "*.lua"
       - "Makefile"
+      - "lux.toml"
+      - "lux.lock"
       - ".github/workflows/e2e-test.yml"
+      - ".github/workflows/lux.yml"
   workflow_call:
 
 jobs:
diff --git a/.github/workflows/luarocks.yml b/.github/workflows/luarocks.yml
index 7ae1731e..94b82bae 100644
--- a/.github/workflows/luarocks.yml
+++ b/.github/workflows/luarocks.yml
@@ -40,25 +40,32 @@ jobs:
       - uses: actions/checkout@v7
         with: { fetch-depth: 0 }
 
-      - name: Set Version
-        run: echo "LUAROCKS_VERSION=${{ needs.check_tag.outputs.tag }}" >> $GITHUB_ENV
+      - name: Install Lux
+        uses: lumen-oss/gh-actions-lux@v1
+        with:
+          version: 0.46.0
+
+      - name: Validate project
+        run: |
+          lx --lua-version 5.1 build
+          lx --lua-version 5.1 generate-rockspec
 
-      - name: LuaRocks Upload
-        uses: nvim-neorocks/luarocks-tag-release@v7
+      # NOTE: lux.toml is the single source of truth for the
+      # luarocks package (dependencies, build spec, metadata).
+      # `lx upload` generates the rockspec from lux.toml, so the
+      # dependencies below are informational only — keep them in
+      # sync with the [dependencies] table in lux.toml.
+      # NOTE: tree-sitter-java is intentionally NOT a dependency.
+      # The Java parser is provided by nvim-treesitter (`:TSInstall java`,
+      # see README prerequisites and `:checkhealth neotest-java`).
+      # Listing it here broke the release workflow because the
+      # tree-sitter-java rock needs the `treesitter-parser` build backend
+      # (luarocks-build-treesitter-parser), which luarocks 3.13 in the
+      # action's nix environment cannot find in the isolated test tree
+      # (see Release run 35866794049).
+      # Current lux.toml dependencies:
+      #   neotest, nvim-nio, nvim-dap, nvim-dap-ui
+      - name: Lux Upload
+        run: lx upload --sign-protocol none
         env:
-          LUAROCKS_API_KEY: ${{ secrets.LUAROCKS_API_KEY }}
-        with:
-          version: ${{ env.LUAROCKS_VERSION }}
-          # NOTE: tree-sitter-java is intentionally NOT a luarocks dependency.
-          # The Java parser is provided by nvim-treesitter (`:TSInstall java`,
-          # see README prerequisites and `:checkhealth neotest-java`).
-          # Listing it here broke the release workflow because the
-          # tree-sitter-java rock needs the `treesitter-parser` build backend
-          # (luarocks-build-treesitter-parser), which luarocks 3.13 in the
-          # action's nix environment cannot find in the isolated test tree
-          # (see Release run 35866794049).
-          dependencies: |
-            neotest
-            nvim-nio
-            nvim-dap
-            nvim-dap-ui
+          LUX_API_KEY: ${{ secrets.LUAROCKS_API_KEY }}
diff --git a/.github/workflows/lux.yml b/.github/workflows/lux.yml
new file mode 100644
index 00000000..fbd99653
--- /dev/null
+++ b/.github/workflows/lux.yml
@@ -0,0 +1,39 @@
+---
+name: Lux
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "lux.toml"
+      - "lux.lock"
+      - ".github/workflows/lux.yml"
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "lux.toml"
+      - "lux.lock"
+      - ".github/workflows/lux.yml"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install Lux
+        uses: lumen-oss/gh-actions-lux@v1
+        with:
+          version: 0.46.0
+
+      - name: Build dependencies
+        run: lx --lua-version 5.1 build --only-deps
+
+      - name: Generate rockspec
+        run: |
+          lx --lua-version 5.1 generate-rockspec
+          ls neotest-java-*.rockspec
+
+      - name: Lint with lux
+        run: lx --lua-version 5.1 lint
diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml
index f9fe1134..ebf124e3 100644
--- a/.github/workflows/static-analysis.yml
+++ b/.github/workflows/static-analysis.yml
@@ -8,7 +8,10 @@ on:
       - "*.lua"
       - ".stylua.toml"
       - ".luacheckrc"
+      - "lux.toml"
+      - "lux.lock"
       - ".github/workflows/static-analysis.yml"
+      - ".github/workflows/lux.yml"
   pull_request:
     branches: ["main"]
     paths:
@@ -16,7 +19,10 @@ on:
       - "*.lua"
       - ".stylua.toml"
       - ".luacheckrc"
+      - "lux.toml"
+      - "lux.lock"
       - ".github/workflows/static-analysis.yml"
+      - ".github/workflows/lux.yml"
 
 jobs:
   luacheck:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 75b3b66a..1ec5e973 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -11,7 +11,10 @@ on:
       - "scripts/**"
       - "*.lua"
       - "Makefile"
+      - "lux.toml"
+      - "lux.lock"
       - ".github/workflows/test.yml"
+      - ".github/workflows/lux.yml"
   workflow_call:
 
 jobs:
diff --git a/.gitignore b/.gitignore
index c20ac530..b38bb54f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,5 +29,9 @@ tests/fixtures/*/*.iml
 .dependencies/
 pack/
 
+# Lux (https://github.com/lumen-oss/lux)
+.lux/
+*.rockspec
+
 # OpenSpec: archived changes are historical record, not active work
 openspec/changes/archive/
diff --git a/.luarc.json b/.luarc.json
index 18d45dbf..9d8ad781 100644
--- a/.luarc.json
+++ b/.luarc.json
@@ -1,18 +1,28 @@
 {
-    "diagnostics.globals": [
-        "vim",
-        "describe",
-        "it",
-        "assert",
-        "before_each",
-        "after_each",
-        "jit",
-        "_G",
-        "_NEOTEST_IS_CHILD",
-        "unpack"
-    ],
-    "diagnostics.neededFileStatus": {
-        "undefined-field": "none",
-        "deprecated": "none"
-    }
+  "diagnostics.globals": [
+    "vim",
+    "describe",
+    "it",
+    "assert",
+    "before_each",
+    "after_each",
+    "jit",
+    "_G",
+    "_NEOTEST_IS_CHILD",
+    "unpack"
+  ],
+  "diagnostics.neededFileStatus": {
+    "undefined-field": "none",
+    "deprecated": "none"
+  },
+  "workspace": {
+    "library": [
+      ".lux/5.1/1cac0fb981f4b22dc93e889c354aaf639ed7ac9fe3fb98b349bfaea47f83efb7-nvim-dap@0.10.0-1/src",
+      ".lux/5.1/8e323ff492bc769418af667a70f9172011b68f8290d7b2bf2f3acb147a04f00f-nvim-dap@0.10.0-1/src",
+      ".lux/5.1/c2cca5b988043795056f705fdd6cce841d1476b9bb45aff389a5499aa6b79479-nvim-dap-ui@4.0.0-1/src",
+      ".lux/5.1/de206edd51dbfc1bbe56869d6729cf4a6e6e70e7b2e107093c0f6520c142d79b-nvim-nio@1.10.1-1/src",
+      ".lux/5.1/f93005c41bfd7f344700c1e7c2e423478991138d0f9f7ed512b263fe384313cc-nvim-nio@1.10.1-1/src",
+      ".lux/5.1/fd3cf668616289b2b2d747e78a3786b371e3912050962a1378803e4de441842a-neotest@5.20.0-1/src"
+    ]
+  }
 }
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 748be561..15af9acf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -26,6 +26,9 @@ You will need:
   - `luacheck`
   - `make`
   - `git`
+  - `lx` (<https://lux.lumen-labs.org/>) — for package
+    management (`lux.toml` is the single source of truth
+    for the luarocks package)
 
 #### First build
 
@@ -89,3 +92,29 @@ If you change Java source files, rebuild before running tests:
 ```bash
 make clean && make
 ```
+
+#### Packaging with Lux
+
+This project uses [Lux](https://github.com/lumen-oss/lux)
+for Lua package management. `lux.toml` is the single
+source of truth — `lx upload` generates the rockspec
+from it when publishing to
+[luarocks.org](https://luarocks.org/modules/rcasia/neotest-java).
+
+```bash
+# Install/sync dependencies into .lux/
+make lux-sync
+
+# Build the project
+make lux-build
+
+# Lint via lux (luacheck)
+make lux-lint
+
+# Run the test suite via lux (delegates to `make test`)
+make lux-test
+```
+
+`lux.lock` is committed for reproducible installs.
+`.lux/` (local build tree) and generated `*.rockspec`
+files are gitignored — never commit them.
diff --git a/Makefile b/Makefile
index b5a51926..b8c6e361 100755
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: clean test test-fail-fast test-e2e
+.PHONY: clean test test-fail-fast test-e2e lux-sync lux-build lux-lint lux-test
 
 all: hooks test
 
@@ -57,3 +57,18 @@ validate:
 
 format:
 	stylua .
+
+# Lux targets (https://github.com/lumen-oss/lux).
+# lux.toml is the single source of truth for the luarocks package.
+# These require `lx` on PATH (see https://lux.lumen-labs.org).
+lux-sync:
+	lx --lua-version 5.1 sync
+
+lux-build:
+	lx --lua-version 5.1 build
+
+lux-lint:
+	lx --lua-version 5.1 lint
+
+lux-test:
+	lx --lua-version 5.1 test
diff --git a/README.md b/README.md
index 41cbae3e..3afa38a6 100644
--- a/README.md
+++ b/README.md
@@ -129,6 +129,18 @@ with SHA-256 checksum verification.
 > The plugin will detect if you have an older JUnit version
 > installed and prompt you to upgrade.
 
+### Packaging with Lux
+
+This project uses [Lux](https://github.com/lumen-oss/lux)
+for Lua package management. `lux.toml` is the single
+source of truth — releases are published to
+[luarocks.org](https://luarocks.org/modules/rcasia/neotest-java)
+via `lx upload`, which generates the rockspec from it.
+
+```bash
+lx install neotest-java
+```
+
 ## ⚙️ Configuration
 
 All configuration options are optional.
diff --git a/lux.lock b/lux.lock
new file mode 100644
index 00000000..69a698b6
--- /dev/null
+++ b/lux.lock
@@ -0,0 +1,126 @@
+{
+  "version": "1.0.0",
+  "dependencies": {
+    "rocks": {
+      "1cac0fb981f4b22dc93e889c354aaf639ed7ac9fe3fb98b349bfaea47f83efb7": {
+        "name": "nvim-dap",
+        "version": "0.10.0-1",
+        "pinned": false,
+        "opt": false,
+        "dependencies": [],
+        "constraint": ">=0.5.0",
+        "binaries": [],
+        "source": "luarocks_rockspec+https://luarocks.org/",
+        "source_url": {
+          "type": "url",
+          "url": "https://github.com/mfussenegger/nvim-dap/archive/0.10.0.zip"
+        },
+        "hashes": {
+          "rockspec": "sha256-1I+b1kcgY/5G4EogluprGiVJ27xG8tHDykJSH4IDDj4=",
+          "source": "sha256-S3Q810Zph3f3a/qIRe9j0L0DWHZWi4oxPLD5ZsWo1XE="
+        }
+      },
+      "8e323ff492bc769418af667a70f9172011b68f8290d7b2bf2f3acb147a04f00f": {
+        "name": "nvim-dap",
+        "version": "0.10.0-1",
+        "pinned": false,
+        "opt": false,
+        "dependencies": [],
+        "constraint": null,
+        "binaries": [],
+        "source": "luarocks_rockspec+https://luarocks.org/",
+        "source_url": {
+          "type": "url",
+          "url": "https://github.com/mfussenegger/nvim-dap/archive/0.10.0.zip"
+        },
+        "hashes": {
+          "rockspec": "sha256-1I+b1kcgY/5G4EogluprGiVJ27xG8tHDykJSH4IDDj4=",
+          "source": "sha256-S3Q810Zph3f3a/qIRe9j0L0DWHZWi4oxPLD5ZsWo1XE="
+        }
+      },
+      "c2cca5b988043795056f705fdd6cce841d1476b9bb45aff389a5499aa6b79479": {
+        "name": "nvim-dap-ui",
+        "version": "4.0.0-1",
+        "pinned": false,
+        "opt": false,
+        "dependencies": [
+          "8e323ff492bc769418af667a70f9172011b68f8290d7b2bf2f3acb147a04f00f",
+          "de206edd51dbfc1bbe56869d6729cf4a6e6e70e7b2e107093c0f6520c142d79b"
+        ],
+        "constraint": ">=3.9.0",
+        "binaries": [],
+        "source": "luarocks_rockspec+https://luarocks.org/",
+        "source_url": {
+          "type": "url",
+          "url": "https://github.com/rcarriga/nvim-dap-ui/archive/v4.0.0.zip"
+        },
+        "hashes": {
+          "rockspec": "sha256-VDCV1BjukKW0Zm6Qg/4xT21J1WPYYugnLOlniF9scho=",
+          "source": "sha256-0yaL0FuxwNsLj6FcWDnnorNZEyn1yEN8+k2/eMhkXpc="
+        }
+      },
+      "de206edd51dbfc1bbe56869d6729cf4a6e6e70e7b2e107093c0f6520c142d79b": {
+        "name": "nvim-nio",
+        "version": "1.10.1-1",
+        "pinned": false,
+        "opt": false,
+        "dependencies": [],
+        "constraint": null,
+        "binaries": [],
+        "source": "luarocks_rockspec+https://luarocks.org/",
+        "source_url": {
+          "type": "url",
+          "url": "https://github.com/nvim-neotest/nvim-nio/archive/21f5324bfac14e22ba26553caf69ec76ae8a7662.zip"
+        },
+        "hashes": {
+          "rockspec": "sha256-QL5OCZFBGixecdEoriGck4iG83tjM09ewYbWVSbcfa4=",
+          "source": "sha256-5x+iHduNdyVjS6+OrqfDh17g9o2tP2YFFqKEsK6Z5zw="
+        }
+      },
+      "f93005c41bfd7f344700c1e7c2e423478991138d0f9f7ed512b263fe384313cc": {
+        "name": "nvim-nio",
+        "version": "1.10.1-1",
+        "pinned": false,
+        "opt": false,
+        "dependencies": [],
+        "constraint": ">=1.7.0",
+        "binaries": [],
+        "source": "luarocks_rockspec+https://luarocks.org/",
+        "source_url": {
+          "type": "url",
+          "url": "https://github.com/nvim-neotest/nvim-nio/archive/21f5324bfac14e22ba26553caf69ec76ae8a7662.zip"
+        },
+        "hashes": {
+          "rockspec": "sha256-QL5OCZFBGixecdEoriGck4iG83tjM09ewYbWVSbcfa4=",
+          "source": "sha256-5x+iHduNdyVjS6+OrqfDh17g9o2tP2YFFqKEsK6Z5zw="
+        }
+      },
+      "fd3cf668616289b2b2d747e78a3786b371e3912050962a1378803e4de441842a": {
+        "name": "neotest",
+        "version": "5.20.0-1",
+        "pinned": false,
+        "opt": false,
+        "dependencies": [
+          "de206edd51dbfc1bbe56869d6729cf4a6e6e70e7b2e107093c0f6520c142d79b"
+        ],
+        "constraint": ">=5.0.0",
+        "binaries": [],
+        "source": "luarocks_rockspec+https://luarocks.org/",
+        "source_url": {
+          "type": "url",
+          "url": "https://github.com/nvim-neotest/neotest/archive/1c529a1ef9c82e8131e872368415cecc2bb86ea2.zip"
+        },
+        "hashes": {
+          "rockspec": "sha256-N8+UxMyOyOKb4+8n3nAQ2Kd3zfGZaFrpeyJmgKvdZc4=",
+          "source": "sha256-PXzEYKTCVfr/YMdqEc6o2pQG7iAMsVxWDGCUxJAMkjM="
+        }
+      }
+    },
+    "entrypoints": [
+      "1cac0fb981f4b22dc93e889c354aaf639ed7ac9fe3fb98b349bfaea47f83efb7",
+      "c2cca5b988043795056f705fdd6cce841d1476b9bb45aff389a5499aa6b79479",
+      "f93005c41bfd7f344700c1e7c2e423478991138d0f9f7ed512b263fe384313cc",
+      "fd3cf668616289b2b2d747e78a3786b371e3912050962a1378803e4de441842a"
+    ]
+  }
+}
diff --git a/lux.toml b/lux.toml
new file mode 100644
index 00000000..087d201e
--- /dev/null
+++ b/lux.toml
@@ -0,0 +1,27 @@
+package = "neotest-java"
+lua = "==5.1"
+
+[source]
+url = "https://github.com/rcasia/$(PACKAGE)/archive/refs/tags/v$(VERSION).zip"
+dev = "git+https://github.com/rcasia/$(PACKAGE).git"
+
+[description]
+summary = "Neotest adapter for Java."
+homepage = "https://github.com/rcasia/neotest-java"
+license = "MIT"
+labels = ["java", "junit", "lua", "neotest", "neovim"]
+
+[dependencies]
+neotest = ">=5.0.0"
+nvim-nio = ">=1.7.0"
+nvim-dap = ">=0.5.0"
+nvim-dap-ui = ">=3.9.0"
+
+[build]
+type = "builtin"
+copy_directories = ["plugin"]
+
+[test]
+type = "command"
+command = "make"
+flags = ["test"]

From c368bccc81c69d27fe5f4b7e4f8228278f8c27ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ricardo=20Cas=C3=ADa?=
 <31012661+rcasia@users.noreply.github.com>
Date: Wed, 23 Sep 2026 16:48:27 +0200
Subject: [PATCH 2/2] fix(ci): drop lx lint from lux workflow (lfs ABI failure
 on ubuntu runners)

---
 .github/workflows/lux.yml | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/lux.yml b/.github/workflows/lux.yml
index fbd99653..d1962f1f 100644
--- a/.github/workflows/lux.yml
+++ b/.github/workflows/lux.yml
@@ -35,5 +35,9 @@ jobs:
           lx --lua-version 5.1 generate-rockspec
           ls neotest-java-*.rockspec
 
-      - name: Lint with lux
-        run: lx --lua-version 5.1 lint
+      # NOTE: `lx lint` (luacheck via lux) is intentionally not run
+      # here. It fails on GitHub-hosted ubuntu runners with
+      # `lfs.so: undefined symbol: lua_gettop` (lux's luacheck builds
+      # luafilesystem against incompatible Lua headers in that
+      # environment), while the dedicated `luacheck` job in
+      # static-analysis.yml covers the same check and passes.