shellenv: Add zsh site-functions to fpath

[HeroCC]

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew style with your changes locally?
• Have you successfully run brew typecheck with your changes locally?
• Have you successfully run brew tests with your changes locally?

---

This PR adds the brew zsh site-functions directory to the fpath during brew shellenv, allowing us to enable completions in one line instead of the seven currently suggested on the Shell Completions page.

The shell-completions documentations page states we don't do this by default because managing completions is complex. This is true, however, I still think it's fair to pick the low-hanging-fruit on behalf of the user; many installations already call compinit on their behalf, and by including the homebrew fpath we can give those users completions for free. Remaining users only need to call compinit (assuming they have shellenv already setup).

If this gets accepted, I can make another PR to update the docs, suggesting users eval the shellenv command instead of the manual fpath manipulation instructions.

For the implementation itself, I made a few design choices for backwards compatibility (documented in the commit description), but I'm flexible if someone prefers it another way.

[MikeMcQuaid]

I'm not sure this should be enabled by default. I have seen non-zero numbers of Homebrew packages with issues and people who wish to not have default ZSH behaviours overridden like this.

[HeroCC]

Hmm, maybe we could append to fpath instead of prepend to give priority to other functions? I see fpath as serving a very similar function to PATH / MANPATH -- when you install packages to brew, I'd expect all of it's resources to be available. So I found myself surprised to find this not installed by default, like all of the other *PATHs.

I have seen non-zero numbers of Homebrew packages with issues

Are these issues with completions, or autoloaded functions in general? Any functions / completions installed here would still need to be actively autoloaded before ZSH adopts them, so I don't think this would be a significant behavior change for users that don't already opt-in to completions or autoload their functions.

Skimming through a search of homebrew-core it seems like the vast majority of references to site-functions is for completions anyway.