fix(unload): dispatch cannot reach the unload function of a hyphenated plugin

[ss-o]

Problem

.zi-unload resolves the Zsh Plugin Standard unload hook using the plugin's
literal repository name:

zi/lib/zsh/autoload.zsh

Line 908 in 38c63c2

(( ${+functions[${plugin}_plugin_unload]} )) && ${plugin}_plugin_unload

(( ${+functions[${plugin}_plugin_unload]} )) && ${plugin}_plugin_unload

$plugin comes from .zi-any-to-user-plugin and is used verbatim, so
zi unload z-shell/zsh-eza looks for zsh-eza_plugin_unload.

The organization's own analyzer derives the shell-visible prefix by replacing
hyphens with underscores (zsh-lint v1.2.0,
internal/projectconfig/config.go, ShellPrefix), so plugin/function-namespace
rejects that name:

zsh-eza.plugin.zsh:37:3: [plugin/function-namespace] Function name "zsh-eza_plugin_unload"
  must use public prefix "zsh_eza_" or private prefix "_zsh_eza_"

A plugin whose name contains a hyphen can therefore satisfy ADR-0020 or be
unloadable by Zi, but not both.

Reproduction

$ zsh -fc 'plugin=zsh-eza; zsh_eza_plugin_unload() { :; }
  (( ${+functions[${plugin}_plugin_unload]} )) || print "MISS: ${plugin}_plugin_unload not found"'
MISS: zsh-eza_plugin_unload not found

Impact

Renaming to satisfy the analyzer makes unload a silent no-op: no error, and
under zi light there is no per-plugin tracking to fall back on, so nothing is
undone. This affects every hyphenated plugin and annex in the organization,
including zsh-eza, zsh-fancy-completions, and all z-a-* annexes.

This is distinct from #113, which concerns ownership across repeated loads of
the same plugin, and from #108, which concerned add-zsh-hook array ownership.
Both assume the unload function is reached at all.

Two ways to resolve it

Either side can move, and the choice belongs to the maintainers rather than to
the plugin repositories.

1. zsh-lint exempts the unload name. Accept
   <identifier>_plugin_unload in plugin/function-namespace, since the
   standard derives that one name from the project identifier itself. One rule
   change, no manager churn.

2. Zi accepts both forms at the dispatch. Prefer the literal name for
   compatibility:

   local ___unload
   for ___unload in "${plugin}_plugin_unload" "${plugin//[^A-Za-z0-9]/_}_plugin_unload"; do
     (( ${+functions[$___unload]} )) && { $___unload; break; }
   done

Acceptance criteria

• zi unload reaches the unload function for a plugin whose name contains a
  hyphen, whichever naming form the plugin declares.
• Behavior is unchanged for a plugin that declares only the literal-name form.
• A test covers a hyphenated plugin ID with each naming form.
• The chosen resolution is recorded so plugin repositories can drop the
  suppression comments they carry today.

Current workaround

z-shell/zsh-eza and z-shell/z-a-meta-plugins keep the hyphenated name and
suppress the advisory plugin/function-namespace hint with a reason. The hint
is severity Hint and does not gate CI.

References

• ADR-0020, Adopt Zsh Plugin Standard 2
• https://wiki.zshell.dev/community/zsh_plugin_standard#unload-function

[ss-o]

Additional evidence from building unload coverage in z-shell/zd#119.

A plug-in loaded by absolute path registers in zsh_loaded_plugins as %<absolute path>:

PLUGINS_LIST: %/tmp/.../ul2/ulprobe

so the ${plugin}_plugin_unload dispatch never resolves for it either. Defining ulprobe_plugin_unload in that plug-in and unloading it produced no call, while @zsh-plugin-run-on-unload registered by the same plug-in ran normally:

Running plugin's provided unload code: print -r -- STD-HOOK-RAN
STD-HOOK-RAN
UNLOADED: func=0 alias=0 fpath_restored=1

So the name-derived hook is unreachable for two distinct classes, hyphenated repository names and path-loaded plug-ins, while the Plugin Standard callback works for both. That may be worth weighing when choosing the fix: deriving the prefix by replacing hyphens with underscores addresses the hyphen case but still leaves path-loaded plug-ins without a reachable named hook.

z-shell/zd#119 asserts the four unload contracts that do work today and deliberately does not assert this one, so a case for it can land alongside the fix.

[ss-o]

Fixed by #502, merged to next.

The Standard hook is now resolved from an ordered candidate list: the literal name, the underscore form, then the same pair derived from the directory basename. The first that exists is called.

That covers both classes, the hyphenated repository reported here and the path-loaded plug-in found while building z-shell/zd#119. The change is additive, so no name that resolved before stops resolving.

tests/unload-hook-dispatch.zsh covers both and reports the unload function of a path-loaded plug-in was not called: [] against the previous dispatch.

Closing here rather than on merge, since Closes only fires against the default branch and this landed on next.