// ZSH-MORE-COMPLETIONS — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

zsh-more-completions is the largest curated zsh completion corpus in existence. 47,393 _* compsys completion files are partitioned across 12 source directories — src/ (8,360), more_src/ (13,128), more_src2/ (4,497), more_src3/ (3,788), more_src4/ (5,244), more_src5/ (3,717), more_src6/ (3,973), more_src7/ (100), more_src8/ (100), man_src/ (3,398), architecture_src/ (1,067), override_src/ (21) — and a single 18-LOC zsh-more-completions.plugin.zsh entrypoint splices all 12 onto $fpath at source time (override prepended, the other 11 appended). Files are auto-generated by 6 Python harvest pipelines (scripts/harvest-{apt,brew,crates,gh-releases,nix,web}-completions.py) that pull from Debian Contents indexes, Homebrew bottles, nixpkgs install-shell-completion macros, crates.io's clap_complete reverse-deps, GitHub release tarballs, and GitHub tree/code-search trees — each capture verified against the upstream argument parser (clap derive, argparse, Getopt::Long, cobra, urfave/cli, Click, Kong, Cmd modules, cmdliner), validated with zsh -nf, header-stamped with a provenance URL, and pinned by an existence test under tests/t-*-existence*.zsh. Doc claims are reconciled against scripts/print-repo-stats.zsh output — never hand-edited; the figures on this page are the script's output at the current HEAD. The 46,937-entry blacklist.txt is the corpus's negative space: every name a harvester ever rejected, so re-runs converge instead of thrashing.

~SCALE & POSITION

Quantitative comparison against every other public zsh / fish / bash completion collection that ships as a package. The competing sets are all curated; the difference is corpus size, harvest automation, and verification depth.

Order-of-magnitude position: against the round figures above, zsh-more-completions ships ~60x the upstream zsh-completions corpus, ~28x the fish in-tree set, ~170x the bash-completion baseline. The differential isn't one collection winning a hand-curation race — it's that the harvest pipelines turn distro package indexes, language ecosystems, and GitHub trees into completion files automatically, with each capture verified before commit. The competing-set sizes are approximate; the 47,316 figure is exact print-repo-stats.zsh output at HEAD.

#SOURCE DIRECTORIES

12 fpath-prefixed source directories. override_src/ is prepended to $fpath so its 21 files win against anything else (system zsh-completions, user-installed plugins, the other 11 dirs in this repo). The remaining 11 dirs are appended in load order — first match wins for any given _NAME.

The more_src split (more_src through more_src8) is a filesystem-performance decision, not a semantic one — some filesystems / tools degrade past 10k entries per directory (find walks, zsh completion compile times, git's index when renaming). Splitting across sibling dirs keeps each comfortably under the ceiling while preserving the "everything is one append on fpath" model. more_src7/ and more_src8/ are the freshest siblings — harvest batches land there first and migrate as they fill.

$PLUGIN ENTRYPOINT

18 LOC of zsh. Inline anonymous fn ((){...} ${0:h}) takes the plugin's own dir as $1, then for each subdir checks if it's already on $fpath via ${fpath[(r)$dir]} reverse-index lookup — only appends if missing. Override goes first via prepend; the rest go last via append.

  (){
      local __zsh_more_comp_dirs_first=("$1/override_src")
      local __zsh_more_comp_dirs_last=("$1/src" "$1/more_src"
                                      "$1/more_src2" "$1/more_src3"
                                      "$1/more_src4" "$1/more_src5" "$1/more_src6"
                                      "$1/more_src7" "$1/more_src8"
                                      "$1/man_src" "$1/architecture_src")
      local __zsh_more_comp_dir

      for __zsh_more_comp_dir in $__zsh_more_comp_dirs_first[@]; do
          if [[ -z ${fpath[(r)$__zsh_more_comp_dir]} ]]; then
              fpath=($__zsh_more_comp_dir $fpath)            # prepend
          fi
      done
      for __zsh_more_comp_dir in $__zsh_more_comp_dirs_last[@]; do
          if [[ -z ${fpath[(r)$__zsh_more_comp_dir]} ]]; then
              fpath=($fpath $__zsh_more_comp_dir)            # append
          fi
      done
  } ${0:h}

@HARVEST PIPELINE

6 Python harvest scripts in scripts/ totalling 3,361 LOC. Each script targets a different upstream registry and produces validated, header-stamped completions that land in more_src/ (or one of its 2..8 splits). Common shape across all 6: (1) enumerate candidates from the registry, (2) dedupe against existing corpus + blacklist.txt, (3) probe / fetch / extract, (4) validate the capture with zsh -nf, (5) strip runtime-dispatch stubs (cobra compdef calls, clap_complete compinit wrappers), (6) write headers + body + record in blacklist, (7) merge into the corresponding existence test file.

// VALIDATION CONTRACT

Every capture across all 6 pipelines passes through the same gate before landing in the tree:

&COMPLETION ECOSYSTEMS

The 47,393 files cover commands from every major distro package set plus a long tail of language-specific ecosystems. The "ecosystems harvested" list is the explicit upstream coverage matrix — if a distro packages a CLI with a --help flag, the harvest pipeline reaches it.

// PACKAGE INDEXES

// LANGUAGE REGISTRIES

// LONG-TAIL ECOSYSTEMS

!README RECONCILE CADENCE

The README and docs/index.html claim a "current" completion count in their front-matter. That number is allowed to drift between reconcile points; periodic reconcile commits snap doc claims back to print-repo-stats.zsh output. The harvest history in git log — add N ... (round <N>) milestone commits and docs: reconcile ... commits — is the audit trail.

This report's authoritative numbers (47,393 files, 22,634 tests, 6,397 commits) are print-repo-stats.zsh output at the current HEAD. README front-matter and this report are reconciled to the same script; small drift between reconcile points is expected and resolved on the next cadence pass, never by hand-editing a total.

^OVERRIDE_SRC & ARCHITECTURE_SRC

Two specialised source directories that don't fit the generic harvest model.

// override_src — 10 files, prepended to fpath

Completions that must win against the upstream zsh-completions corpus, OMZ-shipped completions, and any system-installed alternative. These are hand-maintained by the author and re-verified on every release.

// architecture_src — 1,067 files, cross-arch toolchains

One completion per (triple, tool, version) tuple for cross-compilers. Covers aarch64-alpine-linux-musl-*, aarch64-apple-darwin{21,22,23}-*, x86_64-w64-mingw32-*, arm-none-eabi-*, riscv64-linux-gnu-*, etc. Generated by mirroring the host's gcc-N/clang-N/g++-N/gfortran-N completion structure across every cross-triple a binutils install creates.

.BLACKLIST

51,623 entries in blacklist.txt — flat newline-separated stems. The negative space of the corpus: every name a harvester ever rejected for any reason (no --help, no parser, runtime-dispatch only, duplicate of a hand-curated src/ entry, name conflict with a built-in zsh completion that wins on its own, etc.).

*TEST COVERAGE

22,634 zunit @test cases across 21 test files. The vast majority are existence pins: one @test per completion file, in the appropriate tests/t-*-existence*.zsh. CI fails the moment a file is deleted without removing the test line — the corpus can't silently shrink. Beyond existence: header conformance (provenance URL + harvest timestamp), bulk quality gates, content-shape rules, structural / contract / convention / syntax pins.

CI: zunit tests/*.zsh on Ubuntu via .github/workflows/ci.yml. Existence tests must use the exact on-disk basename (case-sensitive on Linux); the macOS host can stat wrong-case names so local-only correctness isn't enough — CI is the gate.

+COMPLETION FILE SHAPE

Every _NAME file follows the same shape: #compdef NAME first line, comment header with provenance URL + harvest timestamp, then the _arguments or _values body. No trailing compdef _NAME NAME call — that would force the file to evaluate at compinit time. The fpath-driven model lazy-loads each file the first time the user types its name.

?KEY DESIGN DECISIONS

Each call-out is a decision the implementation could have gone either way on, with the rationale for the path taken.

!STRATEGIC POSITION

zsh-more-completions is the corpus underlying the most-completed zsh in existence. The 47,393-file count clears every comparable collection by more than an order of magnitude; the harvest automation is what makes that scale maintainable.

^LOAD MODEL

The plugin's source-time cost is 12 $fpath updates plus 12 reverse-index probes. The 47,316 completion files are not loaded at source time — compinit indexes them by stem, and zsh's autoload machinery defers the actual file source until the user first tabs against the corresponding command.

The corpus is large but the load model is lazy — only completion files for commands the user actually types are sourced. A user who tabs against 50 commands in a session pays the autoload cost on 50 files, not 47,393.

.COMPAT & DEPS

Hard runtime deps: zsh 5.x+ with compsys. The plugin runs entirely within zsh's own completion engine; no Python required at runtime. The Python harvest pipelines are maintainer-only — users never run them.

Install via zinit is the recommended path — the nocompletions ice prevents zinit from symlinking everything into a flat dir, preserving override_src precedence. OMZ requires manual fpath wiring documented in the README. Manual install: clone + copy _* files into a directory already on $fpath.

;GIT POSTURE

6,397 commits on main. The repo is the highest-churn submodule in the MenkeTechnologies meta — harvest runs land in batches of 5-25 new completions per commit, plus periodic reconciles, plus blacklist consolidations. Push races against the meta repo's cross-ref bumps are common; the maintainer rebase-cleans on every reject.