refactor!: consolidate Lua registry sources and the Package API (#1498)

**This removes the following APIs:**
- `Package:check_new_version()`. Instead use the new `Package:get_latest_version()`.

**This has a breaking change in the following APIs:**
- `Package:get_installed_version()` now no longer takes a callback but instead returns the installed version or `nil` if
  not installed.

<details>
<summary>To handle these breaking changes in plugins, leverage the `mason.version` module, for example:</summary>

```lua
local mason_version = require("mason.version")
local registry = require("mason-registry")
local pkg = registry.get_package("rust-analyzer")

if mason_version.MAJOR_VERSION < 2 then
    -- before
    pkg:check_new_version(function (success, new_version)
        -- …
    end)
    pkg:get_installed_version(function (success, installed_version)
        -- …
    end)
else
    -- after
    local new_version = pkg:get_latest_version()
    local installed_version = pkg:get_installed_version()
fi
```

</details>

---

<details>
<summary>This change also introduces breaking changes for Lua registry sources, by consolidating the package schema with the
registry.</summary>

The following is an example of a package defined in a Lua registry, following the new schema:

```lua
local Pkg = require("mason-core.package")

return Pkg.new {
    schema = "registry+v1",
    name = "ripgrep",
    description = "ripgrep recursively searches directories for a regex pattern while respecting your gitignore.",
    homepage = "https://github.com/BurntSushi/ripgrep",
    licenses = { Pkg.License.MIT },
    languages = {},
    categories = {},
    source = {
        id = "pkg:mason/ripgrep@13.0.0",
        ---@param ctx InstallContext
        ---@param purl Purl
        install = function(ctx, purl)
            -- Arbitrary installation code.
        end,
    },
    bin = {
        rg = "./bin/rg",
    },
}
```

</details>

3 files changed, 64 insertions, 62 deletions

diff --git a/tests/mason-core/installer/installer_spec.lua b/tests/mason-core/installer/installer_spec.lua
index 23eeb69e..04de82ba 100644
--- a/tests/mason-core/installer/installer_spec.lua
+++ b/tests/mason-core/installer/installer_spec.lua
@@ -25,12 +25,14 @@ describe("installer", function()
             spy.on(fs.async, "rename")
 
             local handle = InstallHandleGenerator "dummy"
-            spy.on(handle.package.spec, "install")
+            spy.on(handle.package.spec.source, "install")
             local result = installer.execute(handle, {})
 
             assert.is_nil(result:err_or_nil())
-            assert.spy(handle.package.spec.install).was_called(1)
-            assert.spy(handle.package.spec.install).was_called_with(match.instanceof(InstallContext))
+            assert.spy(handle.package.spec.source.install).was_called(1)
+            assert
+                .spy(handle.package.spec.source.install)
+                .was_called_with(match.instanceof(InstallContext), match.is_table())
             assert.spy(fs.async.mkdirp).was_called_with(path.package_build_prefix "dummy")
             assert.spy(fs.async.rename).was_called_with(path.package_build_prefix "dummy", path.package_prefix "dummy")
         end)
@@ -45,8 +47,7 @@ describe("installer", function()
                 error("something went wrong. don't try again.", 0)
             end)
             local handler = InstallHandleGenerator "dummy"
-            stub(handler.package.spec, "install")
-            handler.package.spec.install.invokes(installer_fn)
+            stub(handler.package.spec.source, "install", installer_fn)
             local result = installer.execute(handler, {})
             assert.spy(installer_fn).was_called(1)
             assert.is_true(result:is_failure())
@@ -60,40 +61,45 @@ describe("installer", function()
         "should write receipt",
         async_test(function()
             spy.on(fs.async, "write_file")
-            local handler = InstallHandleGenerator "dummy"
-            ---@param ctx InstallContext
-            handler.package.spec.install = function(ctx)
-                ctx.receipt:with_primary_source { type = "source", source = {} }
-
+            local handle = InstallHandleGenerator "dummy"
+            stub(handle.package.spec.source, "install", function(ctx)
                 ctx.fs:write_file("target", "")
                 ctx.fs:write_file("file.jar", "")
                 ctx.fs:write_file("opt-cmd", "")
-
-                ctx.links.bin = {
-                    ["executable"] = "target",
-                }
-                ctx.links.share = {
-                    ["package/file.jar"] = "file.jar",
-                }
-                ctx.links.opt = {
-                    ["package/bin/opt-cmd"] = "opt-cmd",
-                }
-            end
-            installer.execute(handler, {})
+            end)
+            handle.package.spec.bin = {
+                ["executable"] = "target",
+            }
+            handle.package.spec.share = {
+                ["package/file.jar"] = "file.jar",
+            }
+            handle.package.spec.opt = {
+                ["package/bin/opt-cmd"] = "opt-cmd",
+            }
+            installer.execute(handle, {})
+            handle.package.spec.bin = {}
+            handle.package.spec.share = {}
+            handle.package.spec.opt = {}
             assert.spy(fs.async.write_file).was_called_with(
-                ("%s/mason-receipt.json"):format(handler.package:get_install_path()),
+                ("%s/mason-receipt.json"):format(handle.package:get_install_path()),
                 match.capture(function(arg)
                     ---@type InstallReceipt
                     local receipt = vim.json.decode(arg)
-                    assert.equals("dummy", receipt.name)
-                    assert.same({ type = "source", source = {} }, receipt.primary_source)
-                    assert.same({}, receipt.secondary_sources)
-                    assert.same("1.1", receipt.schema_version)
-                    assert.same({
-                        bin = { executable = "target" },
-                        share = { ["package/file.jar"] = "file.jar" },
-                        opt = { ["package/bin/opt-cmd"] = "opt-cmd" },
-                    }, receipt.links)
+                    assert.is_true(match.tbl_containing {
+                        name = "dummy",
+                        primary_source = match.same {
+                            type = handle.package.spec.schema,
+                            id = handle.package.spec.source.id,
+                        },
+                        secondary_sources = match.same {},
+                        schema_version = "1.1",
+                        metrics = match.is_table(),
+                        links = match.same {
+                            bin = { executable = "target" },
+                            share = { ["package/file.jar"] = "file.jar" },
+                            opt = { ["package/bin/opt-cmd"] = "opt-cmd" },
+                        },
+                    }(receipt))
                 end)
             )
         end)
@@ -106,7 +112,7 @@ describe("installer", function()
             local capture = spy.new()
             local start = timestamp()
             local handle = InstallHandleGenerator "dummy"
-            handle.package.spec.install = function(ctx)
+            stub(handle.package.spec.source, "install", function(ctx)
                 capture(installer.run_concurrently {
                     function()
                         a.sleep(100)
@@ -121,8 +127,7 @@ describe("installer", function()
                         return "three"
                     end,
                 })
-                ctx.receipt:with_primary_source { type = "dummy" }
-            end
+            end)
             installer.execute(handle, {})
             local stop = timestamp()
             local grace_ms = 25
@@ -136,11 +141,10 @@ describe("installer", function()
         async_test(function()
             spy.on(fs.async, "write_file")
             local handle = InstallHandleGenerator "dummy"
-            stub(handle.package.spec, "install", function(ctx)
+            stub(handle.package.spec.source, "install", function(ctx)
                 ctx.stdio_sink.stdout "Hello stdout!\n"
                 ctx.stdio_sink.stderr "Hello "
                 ctx.stdio_sink.stderr "stderr!"
-                ctx.receipt:with_primary_source { type = "unmanaged" }
             end)
             installer.execute(handle, { debug = true })
             assert
@@ -153,7 +157,7 @@ describe("installer", function()
         "should raise spawn errors in strict mode",
         async_test(function()
             local handle = InstallHandleGenerator "dummy"
-            stub(handle.package.spec, "install", function(ctx)
+            stub(handle.package.spec.source, "install", function(ctx)
                 ctx.spawn.bash { "-c", "exit 42" }
             end)
             local result = installer.execute(handle, { debug = true })
@@ -173,7 +177,7 @@ describe("installer", function()
         async_test(function()
             local handle = InstallHandleGenerator "dummy"
             local callback = spy.new()
-            stub(handle.package.spec, "install", function()
+            stub(handle.package.spec.source, "install", function()
                 a.sleep(3000)
             end)
 
@@ -197,7 +201,7 @@ describe("installer", function()
         async_test(function()
             local handle = InstallHandleGenerator "dummy"
             local install = spy.new()
-            stub(handle.package.spec, "install", install)
+            stub(handle.package.spec.source, "install", install)
 
             fs.sync.write_file(path.package_lock "dummy", "dummypid")
             local result = installer.execute(handle, { debug = true })
diff --git a/tests/mason-core/package/package_spec.lua b/tests/mason-core/package/package_spec.lua
index a667cc58..67d49387 100644
--- a/tests/mason-core/package/package_spec.lua
+++ b/tests/mason-core/package/package_spec.lua
@@ -25,13 +25,19 @@ describe("package", function()
 
     if vim.fn.has "nvim-0.11" == 1 then
         it("should validate spec", function()
+            ---@type RegistryPackageSpec
             local valid_spec = {
+                schema = "registry+v1",
                 name = "Package name",
-                desc = "Package description",
+                description = "Package description",
                 homepage = "https://example.com",
                 categories = { Pkg.Cat.LSP },
                 languages = { Pkg.Lang.Rust },
-                install = function() end,
+                licenses = {},
+                source = {
+                    id = "pkg:mason/package@1",
+                    install = function() end,
+                }
             }
             local function spec(fields)
                 return setmetatable(fields, { __index = valid_spec })
@@ -44,9 +50,9 @@ describe("package", function()
             )
 
             assert.equals(
-                "desc: expected string, got number",
+                "description: expected string, got number",
                 assert.has_error(function()
-                    Pkg.new(spec { desc = 23 })
+                    Pkg.new(spec { description = 23 })
                 end)
             )
 
@@ -70,13 +76,6 @@ describe("package", function()
                     Pkg.new(spec { languages = 23 })
                 end)
             )
-
-            assert.equals(
-                "install: expected function, got number",
-                assert.has_error(function()
-                    Pkg.new(spec { install = 23 })
-                end)
-            )
         end)
     end
 
@@ -139,8 +138,7 @@ describe("package", function()
         "should fail to install package",
         async_test(function()
             local dummy = registry.get_package "dummy"
-            stub(dummy.spec, "install")
-            dummy.spec.install.invokes(function()
+            stub(dummy.spec.source, "install", function()
                 error "I simply refuse to be installed."
             end)
             local package_install_success_handler = spy.new()
diff --git a/tests/mason-core/terminator_spec.lua b/tests/mason-core/terminator_spec.lua
index 66b48ba4..24c1ec25 100644
--- a/tests/mason-core/terminator_spec.lua
+++ b/tests/mason-core/terminator_spec.lua
@@ -15,7 +15,7 @@ describe("terminator", function()
             local dummy = registry.get_package "dummy"
             local dummy2 = registry.get_package "dummy2"
             for _, pkg in ipairs { dummy, dummy2 } do
-                stub(pkg.spec, "install", function()
+                stub(pkg.spec.source, "install", function()
                     a.sleep(10000)
                 end)
             end
@@ -24,8 +24,8 @@ describe("terminator", function()
             local dummy2_handle = dummy2:install()
 
             assert.wait_for(function()
-                assert.spy(dummy.spec.install).was_called()
-                assert.spy(dummy2.spec.install).was_called()
+                assert.spy(dummy.spec.source.install).was_called()
+                assert.spy(dummy2.spec.source.install).was_called()
             end)
 
             terminator.terminate(5000)
@@ -49,7 +49,7 @@ describe("terminator", function()
             local dummy = registry.get_package "dummy"
             local dummy2 = registry.get_package "dummy2"
             for _, pkg in ipairs { dummy, dummy2 } do
-                stub(pkg.spec, "install", function()
+                stub(pkg.spec.source, "install", function()
                     a.sleep(10000)
                 end)
             end
@@ -58,8 +58,8 @@ describe("terminator", function()
             local dummy2_handle = dummy2:install()
 
             assert.wait_for(function()
-                assert.spy(dummy.spec.install).was_called()
-                assert.spy(dummy2.spec.install).was_called()
+                assert.spy(dummy.spec.source.install).was_called()
+                assert.spy(dummy2.spec.source.install).was_called()
             end)
 
             terminator.terminate(5000)
@@ -92,8 +92,8 @@ describe("terminator", function()
         async_test(function()
             spy.on(InstallHandle, "kill")
             local dummy = registry.get_package "dummy"
-            stub(dummy.spec, "install")
-            dummy.spec.install.invokes(function(ctx)
+            stub(dummy.spec.source, "install")
+            dummy.spec.source.install.invokes(function(ctx)
                 -- your signals have no power here
                 ctx.spawn.bash { "-c", "function noop { :; }; trap noop SIGTERM; sleep 999999;" }
             end)
@@ -101,7 +101,7 @@ describe("terminator", function()
             local handle = dummy:install()
 
             assert.wait_for(function()
-                assert.spy(dummy.spec.install).was_called()
+                assert.spy(dummy.spec.source.install).was_called()
             end)
             terminator.terminate(50)