feat: add public introspection API for third-party tooling#12
Merged
Conversation
Introduces `require('zpack').get_plugins()` and `get_plugin(name)` as
the supported surface for tools (e.g. zshow.nvim) that need to enumerate
or look up plugins zpack is managing, along with a documented
`zpack.PluginInfo` shape.
Fixes a regression in b1eab47 where external consumers reaching into
zpack's internal `src_to_pack_spec` crashed on disabled plugins. The API
draws a clear internal/external boundary so consumers no longer need to
touch internal state.
To keep the contract simple, `enabled = false` plugins (and any dep-only
plugins orphaned by the cascade) are now pruned from the registry during
setup and do not appear in the API; use `cond` for runtime conditions
that should remain visible with `status = "disabled"`. `:ZClean` will
remove `enabled = false` plugins from disk, matching the hard-disable
semantic.
Install-state queries (checked-out rev, available updates, etc.) are
intentionally not part of this API — they are owned by `vim.pack`, which
is itself public and stable. Consumers should call `vim.pack.get`
directly for those.
`name_to_src` and `is_lazy_resolved` are now populated during
`resolve_all` from the merged spec, so `get_plugin(name)` is symmetric
with `get_plugins()` across the installing → pending → loaded
lifecycle, and the reported `lazy` flag stays stable as an entry
transitions (no flip between raw `merged_spec.lazy` and the plugin-aware
resolution). Entries whose `vim.pack.add` load callback has not yet
fired surface as `status = "installing"` with a nil `path` so UIs can
render "downloading" instead of the plugin vanishing. `get_plugins()` is
side-effect-free — no notifications — so it is safe for statuslines and
dashboards to poll.
`derive_status` checks `load_status` before `cond_result` so a
cond=false plugin that gets force-loaded (via `:ZLoad!` or as a
required dependency of a live parent) correctly reports `loaded`
instead of `disabled`.
`src` is now documented as "the git URL or local path passed to
vim.pack.add" — committing to a real semantic rather than the previous
"opaque, do not parse" disclaimer. A formal deprecation policy is
deliberately deferred until the first time a field actually needs
retiring, rather than promised in advance.
4de0007 to
d8940e9
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduces
require('zpack').get_plugins()andget_plugin(name)as the supported surface for tools (e.g. zshow.nvim) that need to enumerate or look up plugins zpack is managing, along with a documentedzpack.PluginInfoshape and stability promise.Fixes a regression in b1eab47 where external consumers reaching into zpack's internal
src_to_pack_speccrashed on disabled plugins. The API draws a clear internal/external boundary so consumers no longer need to touch internal state.To keep the contract simple,
enabled = falseplugins (and any dep-only plugins orphaned by the cascade) are now pruned from the registry during setup and do not appear in the API; usecondfor runtime conditions that should remain visible withstatus = "disabled". Every plugin returned by the API has therefore been throughvim.pack.add, soPluginInfo.name,path, andlazyare all guaranteed to be populated.