// ZSH-MORE-COMPLETIONS — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

zsh-more-completions is the largest curated zsh completion corpus in existence. 37,003 _* compsys completion files are partitioned across 7 source directories — src/ (9,253), more_src/ (8,974), more_src2/ (8,546), more_src3/ (5,735), man_src/ (3,398), architecture_src/ (1,087), override_src/ (10) — and a single 18-LOC zsh-more-completions.plugin.zsh entrypoint splices all 7 onto $fpath at source time (override prepended, the rest 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. The README "R# reconcile cadence" tags (last visible: R1431, R1431 cadence) anchor the periodic README/index.html sync points where doc claims are reconciled against print-repo-stats.zsh output — never hand-edited. The 32,780-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: zsh-more-completions ships ~50x the upstream zsh-completions corpus, ~25x the fish in-tree set, ~150x 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.

#SOURCE DIRECTORIES

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

The more_src three-way split 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 at lexical thirds (0-9 + a-h, i-r, s-z) keeps each dir comfortably under the ceiling while preserving the "everything is one append on fpath" model.

$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/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,287 LOC. Each script targets a different upstream registry and produces validated, header-stamped completions that land in more_src/ (or its 2/3 split). 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 37,003 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 R# cadence commits snap doc claims back to print-repo-stats.zsh output. The R# tag in commit subjects is the audit trail.

Last visible cadence tag in git log: R1431. Last reconcile bumped docs/index from 32,190 to 33,175. This report's authoritative numbers (37,003 files, 24,017 tests, 5,695 commits) are print-repo-stats.zsh output at the current HEAD; the README itself still cites the older 33,175 figure until the next R# cadence commits land. Drift between this report and the README front-matter is by design.

^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,087 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

32,780 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

24,017 zunit @test cases across 22 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 37,003-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 7 $fpath updates plus 7 reverse-index probes. The 37,003 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 37,003.

.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

5,695 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 R# reconciles, plus blacklist consolidations. Push races against the meta repo's cross-ref bumps are common; the maintainer rebase-cleans on every reject.