agent/complete files

argv/src/complete.rs

@@ -120,6 +120,52 @@ pub struct Candidate<'a> {
     pub description: Option<&'a str>,
 }
 
+/// Paths a shell should offer, on top of whatever this crate knows about.
+///
+/// Listing them is the shell's job, not ours. It already does it better than a CLI can — the
+/// user's own completion styles, colours, escaping, directory-aware widgets — and doing it here
+/// would put a directory read in a binary whose whole claim is that it does not touch the
+/// filesystem to parse a command line. So the answer says *that* paths belong here, and the
+/// generated script hands the position to `_files`, `__fish_complete_path` or `compgen -f`.
+///
+/// This is a deliberate divergence from usage-lib, which reads the directory itself and returns
+/// the names. The conformance comparison holds the two equivalent rather than equal: where the
+/// reference answers with a listing, this answers with the marker.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Files {
+    /// Anything: files, directories, whatever the shell shows for a path.
+    Any,
+    /// Directories only.
+    Dirs,
+}
+
+/// Everything a shell needs to answer one Tab.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Completions<'a> {
+    /// What this CLI knows the word could be.
+    pub candidates: Vec<Candidate<'a>>,
+    /// Paths the shell should add, if the position admits them.
+    pub files: Option<Files>,
+}
+
+/// The paths an argument or value name asks for, by the name itself.
+///
+/// The reference resolves a completer by the *lowercased name* and falls back to treating that
+/// name as the type, so an argument called `<FILE>` completes files and `<DIR>` directories
+/// without a spec saying so. Reimplemented rather than modelled as new vocabulary, because it
+/// is the same rule read off the same names.
+fn files_for(name: &str) -> Option<Files> {
+    // Compared without allocating a lowercased copy: a name is short, and this is a parser.
+    let matches = |want: &str| name.eq_ignore_ascii_case(want);
+    if matches("file") || matches("path") || matches("config_file") {
+        Some(Files::Any)
+    } else if matches("dir") || matches("directory") {
+        Some(Files::Dirs)
+    } else {
+        None
+    }
+}
+
 /// What could be typed at the cursor, given a spec and a split line.
 ///
 /// The rules are usage-lib's, because a CLI's completions should not change with the
@@ -131,6 +177,44 @@ pub struct Candidate<'a> {
 ///
 /// Hidden things are never offered, in any branch. What is *not* here yet: the file fallback
 /// for a word nothing is known about, and the `run=` completions a spec can declare.
+pub fn complete<'a>(spec: &'a Spec<'a>, split: &Split) -> Completions<'a> {
+    let position = walk(spec.root.cmd, split.argv());
+    let token = split.prefix.as_str();
+    let candidates = candidates(spec, split);
+
+    // A dash-prefixed word is a flag or nothing: no path starts with one, and the reference
+    // suppresses its own listing there for the same reason.
+    let flag_like = position.flags_possible && token.starts_with('-');
+
+    // The name a value here would have, which is what says whether paths belong.
+    let named = if let Some(flag) = position.awaiting_value {
+        flag_meta(spec.root, flag)
+            .and_then(|m| m.value_name)
+            .or(Some(flag.name))
+    } else {
+        position.next_arg.map(|arg| arg.name)
+    };
+    let asked_for = named.and_then(files_for);
+
+    // Closed: the position knows its whole set, so an unmatched prefix means no matches rather
+    // than "ask somebody else". Offering the working directory for a mistyped choice is worse
+    // than offering nothing.
+    let closed = !candidates.is_empty() || position.help_topic;
+
+    let files = if flag_like {
+        None
+    } else if asked_for.is_some() {
+        asked_for
+    } else if closed {
+        None
+    } else {
+        Some(Files::Any)
+    };
+
+    Completions { candidates, files }
+}
+
+/// Just the candidates this CLI knows about, without the question of paths.
 pub fn candidates<'a>(spec: &'a Spec<'a>, split: &Split) -> Vec<Candidate<'a>> {
     let position = walk(spec.root.cmd, split.argv());
     let meta = crate::help::find(spec, position.cmd).map(|(_, meta)| meta);
@@ -682,6 +766,23 @@ mod tests {
         args: &[&FIRST, &SECOND],
         ..Command::EMPTY
     };
+    static FILE: Arg = Arg {
+        key: 9,
+        name: "FILE",
+        ..Arg::REQUIRED
+    };
+    static EDIT: Command = Command {
+        name: "edit",
+        flags: &[&INTO],
+        args: &[&FILE],
+        ..Command::EMPTY
+    };
+    static INTO: Flag = Flag {
+        key: 10,
+        name: "into",
+        longs: &["into"],
+        ..Flag::VALUE
+    };
     static AFTER: Arg = Arg {
         key: 7,
         name: "AFTER",
@@ -744,6 +845,25 @@ mod tests {
         }],
         ..CommandMeta::EMPTY
     };
+    static META_EDIT: CommandMeta = CommandMeta {
+        cmd: &EDIT,
+        about: Some("Edit a file"),
+        flags: &[FlagMeta {
+            flag: &INTO,
+            help: Some("Where to write it"),
+            value_name: Some("DIR"),
+            ..FlagMeta::EMPTY
+        }],
+        args: &[ArgMeta {
+            arg: &FILE,
+            help: Some("Which file"),
+            // Two well-known ones, so the position has candidates *and* wants paths — which is
+            // what makes the name the deciding rule rather than the emptiness.
+            choices: &["mise.toml", "mise.local.toml"],
+            ..ArgMeta::EMPTY
+        }],
+        ..CommandMeta::EMPTY
+    };
     static META_WRAP: CommandMeta = CommandMeta {
         cmd: &WRAP,
         about: Some("Wrap something"),
@@ -810,13 +930,14 @@ mod tests {
             &META_LIST,
             &META_TASK,
             &META_WRAP,
+            &META_EDIT,
         ],
         ..CommandMeta::EMPTY
     };
     static ROOT_WITH_META: Command = Command {
         name: "mise",
         flags: &[&GLOBAL],
-        subcommands: &[&USE, &EXEC, &PLUGINS, &SECRET, &LIST, &TASK, &WRAP],
+        subcommands: &[&USE, &EXEC, &PLUGINS, &SECRET, &LIST, &TASK, &WRAP, &EDIT],
         ..Command::EMPTY
     };
     static SPEC: Spec = Spec {
@@ -1109,7 +1230,10 @@ mod tests {
             offered("mise "),
             // `node` and `python` are the fallback command's, which the root offers too — see
             // `the_root_offers_what_the_command_it_falls_back_to_accepts`.
-            ["exec", "list", "ls", "node", "plugins", "python", "task", "u", "use", "wrap"],
+            [
+                "edit", "exec", "list", "ls", "node", "plugins", "python", "task", "u", "use",
+                "wrap",
+            ],
             "sorted, and a hidden command is offered under none of its names"
         );
         assert_eq!(offered("mise pl"), ["plugins"]);
@@ -1164,7 +1288,10 @@ mod tests {
         // word is not a flag, not that it is not a word.
         assert_eq!(
             offered("mise -- "),
-            ["exec", "list", "ls", "node", "plugins", "python", "task", "u", "use", "wrap"]
+            [
+                "edit", "exec", "list", "ls", "node", "plugins", "python", "task", "u", "use",
+                "wrap",
+            ]
         );
     }
 
@@ -1186,7 +1313,7 @@ mod tests {
         // read about, not for a word to run.
         assert_eq!(
             offered("mise help "),
-            ["exec", "list", "ls", "plugins", "task", "u", "use", "wrap"]
+            ["edit", "exec", "list", "ls", "plugins", "task", "u", "use", "wrap"]
         );
     }
     #[test]
@@ -1244,4 +1371,57 @@ mod tests {
         let found = offered("mise ");
         assert!(found.contains(&"node".to_string()), "{found:?}");
     }
+    /// The whole answer for a line: what this CLI knows, and whether paths belong.
+    fn answer(line: &str) -> Completions<'static> {
+        complete(&SPEC, &at_end(line))
+    }
+
+    #[test]
+    fn a_word_named_like_a_path_asks_the_shell_for_paths() {
+        // The reference resolves a completer by the lowercased name and treats that name as the
+        // type when nothing else says otherwise, so `<FILE>` completes files without the spec
+        // mentioning it. Same rule, read off the same name.
+        assert_eq!(answer("mise edit ").files, Some(Files::Any));
+        // Even though it has choices of its own, which would otherwise close the position: a
+        // path argument that names two well-known files still takes any other path.
+        assert_eq!(offered("mise edit "), ["mise.local.toml", "mise.toml"]);
+        // And a flag's value is named by its placeholder, not by the flag.
+        assert_eq!(answer("mise edit --into ").files, Some(Files::Dirs));
+    }
+
+    #[test]
+    fn a_position_that_knows_its_answers_does_not_ask_for_paths() {
+        // Offering the working directory beside a known set is how a mistyped choice completes
+        // to whatever happened to be lying around.
+        assert_eq!(answer("mise use ").files, None);
+        assert_eq!(answer("mise plugins ").files, None);
+        // Nor for a flag, which no path starts with — including one that matches nothing, where
+        // there is otherwise no candidate to suppress the fallback.
+        assert_eq!(answer("mise use --").files, None);
+        assert_eq!(answer("mise -").files, None);
+        let a = answer("mise use --zzz");
+        assert!(a.candidates.is_empty());
+        assert_eq!(a.files, None);
+        // Nor for a help topic, which is a command name and nothing else.
+        assert_eq!(answer("mise help ").files, None);
+    }
+
+    #[test]
+    fn a_position_with_nothing_to_say_lets_the_shell_answer() {
+        // `mise edit some-file ⌶` has filled its only argument and has no subcommands, so this
+        // CLI has nothing to say — and a path is the shell's best guess, which is the
+        // reference's fallback too.
+        let a = answer("mise edit some-file ");
+        assert!(a.candidates.is_empty(), "{:?}", a.candidates);
+        assert_eq!(a.files, Some(Files::Any));
+    }
+
+    #[test]
+    fn an_argument_that_needs_a_separator_asks_for_nothing_else() {
+        // The separator is the only useful candidate, and a path is not one: the parser would
+        // reject it until the `--` is typed.
+        let a = answer("mise wrap ");
+        assert_eq!(a.candidates.len(), 1);
+        assert_eq!(a.files, None);
+    }
 }

benches/gate/tests/complete.rs

@@ -117,3 +117,51 @@ fn the_short_flags_offered_are_the_reference_s() {
     assert_same("mise use -g");
     assert_same("mise install -f");
 }
+
+/// Where the reference reads the directory, this says the shell should.
+///
+/// The one deliberate divergence in the completion path, so it is checked as an equivalence
+/// rather than waived: for a line whose answer is paths, the reference's candidates must all be
+/// entries that exist in the working directory, and ours must be the marker saying so. A
+/// difference either way — a listing where we claim to know the answer, or a marker where the
+/// reference had real candidates — fails.
+#[test]
+fn where_the_reference_lists_files_this_asks_the_shell_for_them() {
+    use usage_argv::complete::{complete, Files};
+
+    let spec = mise_spec();
+    let cwd = std::env::current_dir().expect("a working directory");
+    let entries: Vec<String> = std::fs::read_dir(&cwd)
+        .expect("readable")
+        .filter_map(|e| e.ok())
+        .map(|e| e.file_name().to_string_lossy().to_string())
+        .collect();
+    assert!(
+        !entries.is_empty(),
+        "the fixture needs a non-empty directory"
+    );
+
+    // `mise trust ⌶` takes a `[CONFIG_FILE]`, which the reference completes as a path.
+    for line in ["mise trust ", "mise config get --file "] {
+        let s = split(line, line.len(), Shell::Bash);
+        let ours = complete(shadow_mise::Cli::spec(), &s);
+        let theirs = usage_cli::complete_candidates(&spec, &s.words, s.cword, "bash")
+            .expect("the reference should answer");
+
+        assert_eq!(
+            ours.files,
+            Some(Files::Any),
+            "{line:?} should hand paths to the shell, got {ours:?}"
+        );
+        // Every name the reference offered is something in this directory — i.e. it answered
+        // with a listing, which is the thing we are replacing rather than contradicting.
+        for (value, _) in &theirs {
+            let bare = value.trim_end_matches('/');
+            assert!(
+                entries.iter().any(|e| e == bare),
+                "{line:?}: the reference offered {value:?}, which is not a directory entry — so \
+                 it was not doing file completion and the marker is wrong here"
+            );
+        }
+    }
+}