fix(parse): don't leak the mounting CLI's flags into mounted commands; scan past non-global flags

[jdx]

Fixes the parser-side causes of jdx/mise#11282, plus the two follow-ups that turned up while fixing it. mise side: jdx/mise#11284.

Three related defects, all in how Phase 1's subcommand scan and Phase 2's re-parse interact with mounted commands.

1. The mounting CLI's globals leaked into mounted commands

A mounted command describes another program, but the flags of the commands it is mounted under were inherited into it on descent. For a CLI like mise — where everything after a task name is forwarded to the task — that meant:

• mise run mytask --<TAB> offered --cd --env --jobs --locked --quiet --raw --silent --verbose --yes (and via mise tasks run, --all --extended --global --json …). Using any of them fails: mise run mytask --silent → ERROR unexpected word: --silent.
• A flag the mounted command declares itself was shadowed by a global of the same name, so its choices were replaced by the global's: a task declaring --env with choices "dev" "stage" "prod" completed as file names. Renaming it to --environment worked — the reporter's workaround.

Fix: commands merged in by a mount are marked SpecCommand::mounted (runtime-only, propagated to their subcommands). Crossing into the mounted tree keeps the inherited globals in available_flags — they may legitimately appear before the mounted command — but the mounted command's own flags now take precedence for their own names. Only that crossing is a boundary: inside the mounted tree its commands are ordinary commands relative to each other, so descents there use the normal merge, including #649's rule. A mount can also merge flags from its spec's root onto the command it sits on; SpecCommand::flags_from_mount records that so those flags count as the mounted program's. New ParseOutput::completion_flags() returns what a completion should offer: everything recognized, or, once a mounted command is reached, only the flags declared from the mount boundary down. It needs no extra parse state (ParseOutput::cmds already records the descent chain), so the public API stays additive and cargo semver-checks passes. With no mount in play it returns available_flags unchanged.

2. A non-global flag hid the subcommand behind it

Phase 1 stopped scanning at the first non-global flag, so the subcommand — and any mount on it — was never reached, and its name fell through to Phase 2 as a positional:

$ usage complete-word ... -- mise run --force build --bump ''
Error:   × unexpected word: build

That hit every non-global run flag in mise (-f/--force, -n/--dry-run, -o/--output, -s/--shell, -t/--tool, --timeout, …), and mise's promote_orphan_shorts workaround couldn't help: those flags have no root global to promote onto.

The old rationale was that cmd --local-flag run might read run as the flag's value — but that's what the existing "does this flag take an argument" check handles, and it already governs global flags in the same position. Fix: known non-global flags are consumed like globals and the scan continues; they are just not forwarded to mounts, since they're scoped to the command that declared them. An unknown flag still stops the scan, since its arity is unknown.

3. Re-parsed prefix words could bind to the wrong flag

Phase 1 deliberately leaves the words it skips in input so Phase 2 records them in out.flags/as_env(). But by then the recognized flags have changed — each descent drops non-globals, and (after fix 1) a mounted command can own a name a global used. Fix: Phase 1 records which flag each skipped word was read as, and Phase 2 resolves those words through that binding. This removed the special case I'd first written for it, so a mounted command's flag now always owns its own name:

$ mycli --env prod run task --env <TAB>     # task's choices, and --env prod still parses as the global

Verified against a real mise usage spec

	before	after
mise run mytask --<TAB>	--bump --cd --env --jobs --locked --output-dir --quiet --raw --silent --verbose --yes	--bump --env --output-dir
mise run mytask --env <TAB>	mise-tasks/ mise.toml … (files)	dev stage prod
mise tasks run mytask --<TAB>	above + 10 tasks flags	--bump --env --output-dir
mise mytask --<TAB> (naked)	same leak	--bump --env --output-dir
mise run --force mytask --bump <TAB>	Error: unexpected word: mytask	auto major minor patch
mise run -o interleave mytask --env <TAB>	Error: unexpected word: mytask	dev stage prod
mise --env prod run mytask --env <TAB>	files	dev stage prod
mise -C . run mytask --bump <TAB>	auto major minor patch	unchanged
mise run -r/-S mytask <TAB>	works via mise's promotion	works without it

Tests

• examples/mounted-global-flag-leak.sh — new fixture: root globals -E/--env, --silent; run with a non-global -f/--force and a mount; mounted mytask declaring a colliding --env with choices.
• complete_word_mounted_does_not_offer_mounting_cli_flags — end-to-end through a real mount: the offered flag list, --env/--bump value completion, flags still offered before the mount, a prefix global still parsing, the rejected-by-choices prefix value, and run --force mytask / run -f mytask. Verified failing on main.
• complete_word_non_global_flags_stop_search → ..._do_not_stop_search: now asserts the mounted task is found behind --local, and that an unknown flag still stops the scan.
• Parser unit tests: offered-vs-recognized split, mounted-flag precedence, prefix binding (spaced and = forms, plus the after-the-mount case), non-global flags not hiding a subcommand (boolean, short, value-taking, and unknown-flag control), and a non-mounted control asserting completion_flags() == available_flags.
• Two more from review, both failing without their fix: test_mount_boundary_does_not_apply_inside_the_mounted_tree (three levels, nested command re-declaring the mounted program's own global) and test_mount_flags_merged_into_the_mounting_cmd_are_offered.
• Existing #10069 / orphan-short tests unchanged and passing. mise run lint (incl. cargo semver-checks), mise run render, and the full suite are clean; the only failures locally are two pre-existing node-dependent cases in tests/examples.rs, which also fail on main in my sandbox.

This PR was prepared by an AI coding assistant.

---

Note

Medium Risk
Touches core partial-parse and flag-merge logic used by shell completion and dynamic mounts; behavior changes are intentional but broad, with heavy test coverage rather than isolated call sites.

Overview
Fixes mounted-command completion and partial-parse behavior (jdx/mise#11282 and related).

Mounted commands: Merged mount subcommands are marked mounted (and mount-root flags flags_from_mount). Crossing a mount boundary keeps parent globals recognized for tokens before the task, but mounted flags win on name collisions. New ParseOutput::completion_flags() is what completions should offer—only flags from the mount boundary down—while complete-word switches from available_flags to that API.

Phase 1 subcommand scan: Known non-global flags before a subcommand no longer stop the scan (e.g. run --force mytask), so mounts and task names are still found; only globals are forwarded to mount scripts. Unknown flags still stop the scan.

Prefix re-parse: Phase 1 records prefix_bindings so Phase 2 keeps early tokens bound to the flag they were first read as when a mounted command later owns the same name.

Docs cover global vs non-global flags around mounts; new example script and broad parser/integration tests.

^{Reviewed by Cursor Bugbot for commit 6eaaf53. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Bug Fixes

  • Fixed shell completion inside mounted commands so mounting CLI flags are no longer incorrectly suggested.
  • Mounted command flags now take precedence over inherited global flags with the same name.
  • Improved parsing of flags before and across mounted command boundaries, including aliases and inline values.
  • Preserved completion of global flags before entering a mounted command.

• Documentation

  • Added guidance and examples explaining global flag behavior and completion rules for mounted commands.

[coderabbitai]

📝 Walkthrough

Walkthrough

Mounted command parsing now tracks mount provenance, preserves flag bindings across parsing phases, and computes completion candidates that honor mounted flag ownership over inherited global flags. Tests, fixtures, and reference documentation cover these rules.

Changes

Mounted flag completion

Layer / File(s)	Summary
Track mounted command provenance lib/src/spec/cmd.rs	SpecCommand records mounted status and mounted root flag state, marking mounted subcommands recursively during mount processing.
Preserve mount-aware flag bindings lib/src/parse.rs	Parsing applies distinct mount-boundary merge behavior, records prefix bindings, and reuses those bindings when parsing long and short flags in Phase 2.
Expose mounted-aware completion candidates cli/src/cli/complete_word.rs, cli/tests/complete_word.rs	Flag completion uses completion_flags(), with tests covering mounted flag exclusion, precedence, aliases, and non-global flags before subcommands.
Document and exercise mounted flag rules examples/mounted-global-flag-leak.sh, docs/spec/reference/cmd.md, docs/spec/reference/flag.md	The mounted fixture and reference documentation define global flag scope, mounted flag precedence, and completion behavior.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant ParseOutput
  participant SpecCommand
  participant MountedCommand
  CLI->>ParseOutput: parse partial command line
  ParseOutput->>SpecCommand: descend through mount boundary
  SpecCommand->>MountedCommand: merge mounted command flags
  MountedCommand-->>ParseOutput: provide mounted-owned flag set
  ParseOutput-->>CLI: return completion_flags

Loading

Poem

I’m a rabbit with flags in my den,
Mounting new tasks, then parsing again.
Old globals hop out of sight,
New aliases shine just right.
Tabs now bloom where commands begin!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main changes: mounted-command flag leakage prevention and continued scanning past known non-global flags.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR adjusts mounted-command parsing and completion behavior.

• Tracks mount boundaries and mounted-root flags in the runtime command model.
• Continues Phase 1 subcommand scanning past recognized non-global flags.
• Preserves Phase 1 flag bindings during Phase 2 parsing.
• Adds parser, completion, fixture, and documentation coverage for mounted flags.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failures remain.

Important Files Changed

Filename	Overview
lib/src/parse.rs	Adds mount-aware flag merging, completion filtering, prefix bindings, and focused parser tests.
lib/src/spec/cmd.rs	Adds runtime mount provenance fields and marks dynamically mounted command trees.
cli/src/cli/complete_word.rs	Uses the parser's mount-aware flag set when generating flag-name candidates.
cli/tests/complete_word.rs	Adds end-to-end coverage for mounted flag isolation, collisions, and scanning past local flags.
examples/mounted-global-flag-leak.sh	Adds a mounted-command fixture covering colliding flags and nested mounted commands.

_{Reviews (5): Last reviewed commit: "fix(parse): scope the mount boundary to ..." | Re-trigger Greptile}

[coderabbitai]

🧹 Nitpick comments (1)

lib/src/parse.rs (1)

512-519: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Duplicated mount-boundary descent logic.

The crossing_mount computation + merge_subcommand_flags call is now duplicated between the subcommand-found branch and the default_subcommand branch. This mirrors a pre-existing duplication (both branches already called mount()/merge_subcommand_flags before this PR), but this change grows it further. A shared helper (e.g. fn descend(out: &mut ParseOutput, subcommand: SpecCommand)) encapsulating mount + crossing_mount + merge + push/assign would reduce the risk of the two copies drifting on this subtle mount-boundary rule in the future.

♻️ Sketch of a shared helper

+fn descend_into(out: &mut ParseOutput, mut subcommand: SpecCommand, prefix_words: &[String]) -> Result<(), UsageErr> {
+    subcommand.mount(prefix_words)?;
+    let crossing_mount = subcommand.mounted && !out.cmd.mounted;
+    merge_subcommand_flags(&mut out.available_flags, gather_flags(&subcommand), crossing_mount);
+    out.cmds.push(subcommand.clone());
+    out.cmd = subcommand;
+    Ok(())
+}

Also applies to: 573-578

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/src/parse.rs` around lines 512 - 519, Extract the duplicated descent
logic from both the subcommand-found and default_subcommand branches into a
shared helper, such as descend. The helper should perform mount handling,
compute crossing_mount using the mounted-state boundary rule, merge flags, and
then push or assign the descended command as required. Replace both existing
inline sequences with this helper so the branches cannot drift.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@lib/src/parse.rs`:
- Around line 512-519: Extract the duplicated descent logic from both the
subcommand-found and default_subcommand branches into a shared helper, such as
descend. The helper should perform mount handling, compute crossing_mount using
the mounted-state boundary rule, merge flags, and then push or assign the
descended command as required. Replace both existing inline sequences with this
helper so the branches cannot drift.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: a9f2028f-2ba5-4061-9838-3ce319cad385

📥 Commits

Reviewing files that changed from the base of the PR and between 3f36584 and 6eaaf53.

📒 Files selected for processing (7)

• cli/src/cli/complete_word.rs
• cli/tests/complete_word.rs
• docs/spec/reference/cmd.md
• docs/spec/reference/flag.md
• examples/mounted-global-flag-leak.sh
• lib/src/parse.rs
• lib/src/spec/cmd.rs