Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneeszack

Relationships

#4612 Lazy loading: route completion callbacks to the target command instead of the full tree

Opened by zack · 11/10/2026· Shipped 11/11/2026

Problem

With the route table from #4592, completions is marked needsFullTree, so every invocation that starts with completions loads all top-level commands through import(). #4592 accepts that full-tree paths are slower until the bundled build ships, because modules loaded through import() miss Deno's code cache.

That cost is paid whenever a shell asks swamp for dynamic values, like behavior, workflow or vault names. The generated bash, zsh and fish scripts call back with swamp completions complete <action> <command words...> (for example completions complete model_name behavior get).

Measured on compiled binaries (10-run averages, Linux, offline):

invocation before #4592 with #4592
completions complete model_name behavior get ~435 ms ~525 ms
behavior get hello --json (a routed command, for comparison) ~465 ms ~385 ms

Proposal

Route the completion callback the way help <path> is routed. For completions complete <action> <word> ..., load the completions route plus the route that <word> names, not the full tree. Keep needsFullTree for completions bash|zsh|fish|powershell, which generate scripts from the whole tree.

Why a partial tree is enough: Cliffy's CompleteCommand walks down from the main command through the given command names with getCommand(name, false), then calls getCompletion(action). That checks the command's own completions, then getGlobalCompletion, which walks only up the parent chain. Everything it reads is the root, the target route's subtree and its ancestors, all of which a two-route tree contains.

Expected result: dynamic completion runs at routed-command speed, faster than before #4592 rather than ~90 ms slower, and it doesn't depend on the bundled build.

Details to settle

  • selectRoute returns one route today; this needs a selection of two (completions plus the target).
  • No command words (completions complete <action>) completes on the root, so loading only completions is enough.
  • An unknown or hidden first word should keep falling back to the full tree, so UnknownCompletionCommandError reads the same as today. The walk uses getCommand(name, false), which excludes hidden commands.
  • Aliases (behaviour, summarize) resolve through the route table as they do for help.
  • Check whether the custom PowerShell completer (src/cli/commands/completion_powershell.ts, which walks from getMainCommand()) calls back through completions complete or its own path, and route it too if so.
  • Extend the per-path schema parity fitness test, or add a sibling test, so that for every command path the two-route tree gives the same completion output as the full tree.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 29 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/11/2026, 12:53:20 AM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/10/2026, 9:50:26 PM

Sign in to post a ripple.