Research: where does the specs table’s breadth come from — Fig’s spec corpus, carapace’s man-generated YAML, fish’s completion files, or the tab’s own history?

Date: 2026-11-07 Question: The completions menu knows five commands in-code plus an audited fourteen-command seed the user copies in. For any command outside them (rustc --em, node --ver, kubectl get) every provider is silent and the menu refuses to open. Which completion-knowledge source should feed the table at scale — hundreds of commands with subcommands, long flags, and descriptions — inside the standing rulings: no shell integration, nothing executes at the terminal’s behest beyond the reviewed git generators, nothing reads man pages or --help at runtime, dynamic sources only as fixed reviewed argv in source, nothing leaves the machine?

TL;DR

Scale the table from the withfig/autocomplete spec corpus — a one-time, maintainer-run static conversion exactly like the fourteen already shipped, grown from 14 commands toward the 440 purely static specs of its 715 — and reimplement the spec-walking parser in Rust from microsoft/inshellisense, the one actively-maintained MIT engine that consumes the same format. The corpus is MIT-licensed with a uniform notice (one license line to carry, not 755 per-command audits), 61.5% of its specs are purely static at the pinned commit (440/715 carry no generators: key, no script:, no loadSpec, no generateSpec), descriptions are a first-class field on every subcommand and option, and it is the same source the shipped seed already proved the conversion for — the same source VS Code pins in its cgmanifest, Warp credits in its open-source README, and inshellisense (600+ tools, pushed 2026-10-19) runs as a terminal-native PTY wrapper. The upstream dormancy (frozen at v2.692.3, 2025-05-05, 105 unmerged community PRs) is priced and acceptable because DropTerm owns the converted snapshot, never the live repo. Carapace’s newly-checked-in man/cmd/ YAML corpus (755 commands, serde-trivial, same-day-active upstream) is the runner-up and the better format, but every line of it is verbatim man-page text whose license varies per command — an unauditable per-content licensing tail, and man-derived machine truth against the project’s curation frame. fish’s 1,097 completion files have the best description coverage (94% of 33,603 lines) and a uniform line grammar, but are GPL-2 (cannot ship inside GPL-3.0-only), carry fish code in 51% of lines (-n conditions — where the subcommand structure lives) and 74% of -a values, and would hang breadth on whether the user installed fish. History-learned flags are the floor, not the answer. zsh compsys and bash-completion are shell programs, not data — closed with pinned evidence. No terminal emulator in the field ships its own knowledge source: Warp and VS Code both stand on the Fig specs; Windows Terminal’s Suggestions UI is shell-integration-powered history; Tabby bundles Clink; Wave, Ghostty, kitty, WezTerm ship nothing.

This record extends autosuggest-warp-parity (consumes its Phase B ruling: the loadable data file plus a one-time audited conversion), extends completions-seed-audit (the conversion rules are its rules, at scale), and extends suggest-menu-layering (breadth feeds the menu surface it examined). Nothing here supersedes a ruling; the 2026-11-02 record’s own rejection ledger (carapace as a runtime binary, Warp code, runtime TS parsing) all still stands — the winner is the data path that record already named, now measured.

What DropTerm has today

Grounded in the working tree at HEAD be7ae913f0f6 (2026-11-06), GPL-3.0-only (Cargo.toml:6, LICENSE):

Findings

1. withfig/autocomplete, measured at the pinned commit — the breadth is there and 61.5% of it is purely static

Cloned --depth 1 into a fresh /tmp directory on 2026-11-06 and pinned: aef52acff84c45edde61ae610cc2c964802b9a38 (v2.692.3, commit dated 2025-05-05 — the same commit the seed audit pinned; the repo has not moved since, see finding 3). All numbers below are commands run against that checkout.

2. The format is typed, documented, and its static subset maps onto DropTerm’s schema with no seat changes needed for breadth

The spec type definition ships as @withfig/autocomplete-types — registry tarball autocomplete-types-1.31.0.tgz fetched and extracted 2026-11-06 (no scripts run; npm pack equivalent via direct registry curl; 1.31.0 is the latest published version and matches the repo’s devDependency ^1.31.0, withfig/package.json devDependencies). Key shapes in package/index.d.ts (1,300 lines):

What the static subset keeps and loses. Keeps: subcommand names and descriptions, long-flag names and descriptions (short flags exist but DropTerm’s rulings exclude them — docs/autosuggestions.md:53), the multi-name alias convention (the seed’s rule 2 already collapses it to the primary/first-long name), requiresSubcommand (mappable to the subcommand seat), isPersistent (mappable to the flag seat’s current “flags from any argument seat” approximation — DropTerm already treats git’s flags as position-independent for exactly this reason, src/terminal/suggest.rs:952-958). Loses: generators/templates (the dynamic values — for git, DropTerm’s own reviewed generators already ship under a stricter contract than Fig’s), loadSpec sub-files (the cloud spec trees inshellisense also refuses), nested subcommands and per-subcommand options (a walker feature, not a data feature — the top-level tables alone already answer kubectl get, rustc --em, node --ver), and args templates (argument seats stay the path provider’s and git generators’ territory). Crucially, going from 14 to hundreds of commands needs zero changes to specs_context, specs_candidates, or the menu: the seats, the match policy, and the description column are all per-command table lookups that already work; only the table grows.

3. The precedent chain is now three shipping consumers plus one removal — the data is the standard, the engines churn

4. carapace: the Go completers are still programs — but the new man/cmd/ YAML corpus is real static data with a licensing tail

carapace-sh/carapace-bin @ master 63b7842024e8c5651e8a61fcbb799778235ca4e4 (2026-11-06 — the morning of this survey; MIT, “Copyright (c) 2020 rsteube”; actively maintained). Measured from the full git tree (GitHub API, fetched 2026-11-06):

5. fish completion files: the best descriptions, a uniform grammar — and three structural blockers

Measured from fish-shell/fish-shell @ master d92ccd4f8f6f08cfc8a0d9fa17333153e2922af1 (2026-11-03; sparse-checked share/completions into /tmp, 2026-11-06). This machine has fish barely installed (/usr/share/fish/completions holds 1 file, fd.fish; ~/.local/share/fish/generated_completions is empty) — the runtime-dependency cost is not hypothetical.

6. History-learned flags: honest evaluation — a floor, not a breadth source

Mining --flags per command from the tab’s ring is free (the ring already exists, src/terminal/suggest.rs:251-262), needs no license, no parser, no dependency — and answers none of the question. Coverage is exactly “what this user already typed in this tab”: a command never run completes nothing (the fresh-tab case the breadth ask is about), a flag never typed is invisible, and there are no descriptions, ever (the menu’s dim column stays empty). It also adds little the history provider does not have: git che already ghosts ckout main from the ring’s whole-line prefix match (history_candidates, src/terminal/suggest.rs:1373-1384); per-word mining would only re-slice the same lines into more, smaller rows. Where it genuinely helps is as a menu enrichment — the distinct flags of this command surfaced as one row each even when whole-line history rows bury them — a later module at most, not the breadth source.

7. zsh compsys and bash-completion are programs, not data — the door closed with pinned files

Neither can be parsed by any grammar; both require a shell evaluator, which is the integration DropTerm ruled out by construction (docs/autosuggestions.md:9).

8. The field check: no terminal ships its own knowledge source — the ones that ship anything stand on the Fig specs

So the field’s answer to “where does the knowledge come from” is, where it exists at all: Fig’s corpus. DropTerm joining that path is not an outlier bet on a dormant repo; it is adopting the interchange format with the widest living consumer base (VS Code, Warp, inshellisense) after its original vendor exited.

9. Seat fit and shipping shape — what actually changes in DropTerm

Recommendation

Rank 1 — the withfig/autocomplete static corpus (adopt). One-time maintainer-run conversion at the pinned commit, grown in tranches (top-100 first, then long-tail), shipped embedded as a built-in table under the seed audit’s rules and notice, with inshellisense’s walker as the reverse-engineering model for the seat refinement that follows. Decisive reasons: (1) licensing — one uniform MIT/ISC notice, the audit precedent already proven on this exact source at this exact commit, versus 755 per-command man-page audits (carapace) or a GPL-2 workload (fish); (2) provenance fit — hand-written curated specs, not machine-scraped man text, in a typed format whose static subset maps 1:1 onto DropTerm’s shipped schema with zero seat changes; (3) the field — the format’s living consumers (VS Code, Warp, inshellisense) make this the interchange standard, and the one actively-maintained engine is MIT and source-readable.

Rank 2 — carapace’s man/cmd/ YAML (the named fallback/supplement). If the Fig extraction ever proves too TS-flavored at the margins, or for the specific commands Fig lacks, man/cmd/*.yaml is serde-trivial, description-rich, same-day-active upstream. Blockers: per-command man-page licensing (GPL-2-only man text cannot ship in GPL-3.0-only at all), man-derived staleness, and the curation-frame mismatch. Revisit only as a per-command, per-license supplement.

Rank 3 — fish files at runtime (optional user-side source, if ever asked for). License-clean to read (no distribution occurs) and description-dense, but gated on fish being installed, half-noisy with embedded fish code, and structurally unable to yield the subcommand tree without a condition evaluator. Not the breadth path; a possible later completions_from_fish-style opt-in at most.

Rank 4 — history-learned flags (a menu enrichment, not a source). Mine the ring for the command’s own seen flags as extra menu rows; accept that it has no descriptions and no fresh-tab value. A later module inside the existing history provider, not a data program.

Rejected: zsh compsys and bash-completion as data (finding 7 — they are programs; no grammar exists to parse); carapace the binary as a runtime backend (the standing autosuggest-warp-parity rejection — external Go dependency, zero terminal precedents); Warp engine code (AGPL); any runtime TS/fig-spec parsing (conversion once, offline — the standing ruling); and shipping fish-derived or man-derived data without the per-content audit (licensing, findings 4-5).

Unverified / open questions

Next: REA target

The winner’s implementation to reverse-engineer is microsoft/ inshellisense’s spec runtime — the parser/engine that walks a Fig spec against a typed line, which is what DropTerm would reimplement in Rust — analyzed beside the withfig data it consumes.

Sources

All fetched 2026-11-06 unless noted.

Improve this page on GitHub