lattice_completion/builtins/

generators.rs

//! Built-in candidate generators (DESIGN.md §5.11.3).
//!
//! v1 ships:
//! - [`CommandsGenerator`] -- every `CommandSpec` in the registry.
//!   Caches the full set per registry-version (commands don't
//!   change at runtime in v1, so the cache key is fixed and the
//!   cache effectively never expires).
//! - [`FilesGenerator`] -- filesystem entries for a path-shaped
//!   prefix. Caches per-directory with a 1-second soft TTL.
//! - [`DirectoriesGenerator`] -- like [`FilesGenerator`] but only
//!   emits directory entries. Intended for `:cd` and similar
//!   directory-only commands.
//!
//! Other host-state generators (chords, registers, marks, buffers)
//! live in `lattice-ui-tui` because they need App-level state.
//! Plugins register their own through the same trait.

use std::path::PathBuf;
use std::time::Duration;

use crate::candidate::{CacheKey, CandidateData, CandidateKind, RawCandidate};
use crate::traits::{CandidateGenerator, GenerateContext};

/// `gen:commands`. Walks the `CommandRegistry` and emits one
/// `RawCandidate` per registered `CommandSpec`. Filtering is
/// deferred to the matcher; the generator returns the full set
/// every time the cache misses.
///
/// Delimiter-form commands (`ex:substitute`, `ex:global` --
/// `SurfaceForm::Delimiter`) are excluded: the user types those
/// via `:s/.../.../`, `:g/.../.../`, `:v/.../.../`. Surfacing them
/// as completion candidates is misleading because typing
/// `:ex:global` would error with "use the delimiter form" -- the
/// keyword form is intentionally a hard-error redirect (DESIGN.md
/// §B.2). They remain reachable through `:describe-command` /
/// `:apropos` for introspection.
pub struct CommandsGenerator;

impl CandidateGenerator for CommandsGenerator {
    fn generate(&self, ctx: &GenerateContext<'_>) -> Vec<RawCandidate> {
        let mut out: Vec<RawCandidate> = ctx
            .registry
            .names()
            .filter_map(|name| {
                let id = ctx.registry.id_by_name(name)?;
                let spec = ctx.registry.lookup(id)?;
                // UD.2: include ex-commands AND motions. Both are
                // invocable from the `:` line — `:w`, `:motion:line-down`
                // — and now behave identically to a keystroke (the host
                // dispatch is unified; see typed-motion-dispatch.md).
                //
                // OM.14: and ACTIONS, which the ex-command parser used to
                // refuse. The exclusion here was true when it was written and
                // stopped being true when `parse_naked_action` landed; leaving
                // it would have made every action invocable and none of them
                // discoverable, which is the worse half of the original bug —
                // you can only type a name you already know.
                //
                // Operators and text-objects stay filtered: an operator needs
                // a target, so it is not actionable standalone.
                match spec.kind {
                    lattice_grammar::CommandKind::ExCommand => {
                        // Delimiter-only commands (`:s/.../`, `:g/.../`)
                        // have no useful keyword-form completion target.
                        let ex = ctx.registry.ex_command_spec(id)?;
                        if matches!(
                            ex.surface_form,
                            lattice_grammar::SurfaceForm::Delimiter { .. }
                        ) {
                            return None;
                        }
                    }
                    lattice_grammar::CommandKind::Motion | lattice_grammar::CommandKind::Action => {
                    }
                    _ => return None,
                }
                // User-facing name: strip the `ex:` namespace prefix so
                // ex-commands show `oil` not `ex:oil`. Motions keep their
                // `motion:` prefix — that IS what the user types
                // (`:motion:line-down`).
                let display_name = spec
                    .name
                    .strip_prefix("ex:")
                    .unwrap_or(&spec.name)
                    .to_string();
                Some(RawCandidate {
                    insert_text: None,
                    text: display_name.clone(),
                    display: display_name.clone(),
                    kind: CandidateKind::Command,
                    data: CandidateData::Command {
                        name: spec.name.clone(),
                        doc: spec.doc.clone(),
                        kind_label: spec.kind.label().to_string(),
                        source: spec.source.clone(),
                    },
                    source: None,
                    accept_action: None,
                    annotations: Vec::new(),
                    display_spans: Vec::new(),
                })
            })
            .collect();
        out.sort_by(|a, b| a.text.cmp(&b.text));
        out
    }

    fn cache_key(&self, ctx: &GenerateContext<'_>) -> Option<CacheKey> {
        // Dynamic registration (WASM plugins) mutates the command set at
        // runtime, so a fixed key would serve a stale candidate list forever
        // (the cache lives on the CompletionRegistry, which a command-registry
        // RCU never touches). The registry bumps `generation()` on every
        // register / unregister — including a plugin's RCU'd drain and its
        // unload — so keying on it makes a plugin's freshly-registered commands
        // (and its auto `:<mode>` toggles) appear in `<Tab>` completion
        // immediately, and unloaded ones vanish, with no manual cache flush.
        Some(CacheKey::new(format!(
            "gen:commands:v1:{}",
            ctx.registry.generation()
        )))
    }
}

/// `gen:directories`. Resolves the prefix into a directory + basename
/// pattern, then lists *only directories* of that directory matching
/// the basename prefix. Like [`FilesGenerator`] but omits regular files.
pub struct DirectoriesGenerator;

/// `gen:files`. Resolves the prefix into a directory + basename
/// pattern, then lists entries of that directory matching the
/// basename prefix. Returns directories with a trailing `/` so the
/// user can keep tab-completing into nested paths.
pub struct FilesGenerator;

impl CandidateGenerator for DirectoriesGenerator {
    fn generate(&self, ctx: &GenerateContext<'_>) -> Vec<RawCandidate> {
        fs_entries(ctx, false)
    }

    fn cache_key(&self, ctx: &GenerateContext<'_>) -> Option<CacheKey> {
        let dir_str = match ctx.prefix.rfind('/') {
            Some(i) => &ctx.prefix[..=i],
            None => "",
        };
        let dir = expand_tilde(dir_str);
        Some(CacheKey::new(format!(
            "gen:directories:{}",
            dir.to_string_lossy()
        )))
    }

    fn cache_ttl(&self) -> Duration {
        Duration::from_secs(1)
    }
}

impl CandidateGenerator for FilesGenerator {
    fn generate(&self, ctx: &GenerateContext<'_>) -> Vec<RawCandidate> {
        fs_entries(ctx, true)
    }

    fn cache_key(&self, ctx: &GenerateContext<'_>) -> Option<CacheKey> {
        let dir_str = match ctx.prefix.rfind('/') {
            Some(i) => &ctx.prefix[..=i],
            None => "",
        };
        let dir = expand_tilde(dir_str);
        Some(CacheKey::new(format!(
            "gen:files:{}",
            dir.to_string_lossy()
        )))
    }

    fn cache_ttl(&self) -> Duration {
        Duration::from_secs(1)
    }
}

/// Shared helper: list filesystem entries matching the prefix.
/// When `include_files` is false, only directories are emitted.
fn fs_entries(ctx: &GenerateContext<'_>, include_files: bool) -> Vec<RawCandidate> {
    path_entries(ctx.prefix, ctx.case_sensitive, include_files)
}

/// PC.9: [`fs_entries`] without the completion engine's context.
///
/// The `prefix` split, the `~` expansion, the case rule, the trailing `/` on a
/// directory and the sort are all one behaviour, and the picker's `dir-pick`
/// source needs exactly it — a *picker* source cannot build a
/// [`GenerateContext`], which is shaped for the completion engine (buffer,
/// command registry, cursor). Extracted rather than copied so the two surfaces
/// cannot drift on what "list this path's children" means: a `dir-pick` that
/// expanded `~` differently from `<Tab>` on the `:` line would be a bug nobody
/// would think to look for.
///
/// An unreadable directory yields an empty list rather than an error. Half a
/// typed path names nothing yet, and that is the state the caller is in for
/// most of the keystrokes.
pub fn path_entries(prefix: &str, case_sensitive: bool, include_files: bool) -> Vec<RawCandidate> {
    let (dir_str, basename) = match prefix.rfind('/') {
        Some(i) => (&prefix[..=i], &prefix[i + 1..]),
        None => ("", prefix),
    };
    let dir_path = expand_tilde(dir_str);

    let read_dir = match std::fs::read_dir(&dir_path) {
        Ok(rd) => rd,
        Err(_) => return Vec::new(),
    };

    let basename_lower = basename.to_ascii_lowercase();
    let mut out: Vec<RawCandidate> = Vec::new();
    for entry in read_dir.flatten() {
        let name_os = entry.file_name();
        let name = name_os.to_string_lossy();
        if !case_sensitive && !name.to_ascii_lowercase().starts_with(&basename_lower) {
            continue;
        }
        if case_sensitive && !name.starts_with(basename) {
            continue;
        }
        // `file_type()` before `metadata()`, and `metadata()` only when the
        // answer is actually needed. `read_dir` already carries the type for
        // most entries (`d_type` on Linux/macOS), so `file_type()` is free
        // where `metadata()` is a `stat` syscall each — 5000 entries cost
        // ~15ms of pure syscall that way, and this runs SYNCHRONOUSLY on the
        // actor thread from `on_query_changed`, i.e. inside a keystroke.
        //
        // A symlink is the one case `file_type()` cannot answer: it reports
        // the LINK, never its target, so a symlinked directory would stop
        // being listed. Those fall back to `metadata()`, which follows — the
        // stat is paid only for the entries that need it, and `~/src -> …`
        // is common enough that losing them would be a real regression.
        let file_type = entry.file_type();
        let is_symlink = file_type.as_ref().map(|t| t.is_symlink()).unwrap_or(true);
        let is_dir = if is_symlink {
            entry.metadata().map(|m| m.is_dir()).unwrap_or(false)
        } else {
            file_type.as_ref().map(|t| t.is_dir()).unwrap_or(false)
        };
        if !include_files && !is_dir {
            continue;
        }
        // Only files carry a size, and only a file listing shows one — so a
        // directory listing never pays for it at all.
        let size = if include_files && !is_dir {
            entry.metadata().ok().map(|m| m.len())
        } else {
            None
        };
        let mut text = String::with_capacity(dir_str.len() + name.len() + 1);
        text.push_str(dir_str);
        text.push_str(&name);
        if is_dir {
            text.push('/');
        }
        let display = if is_dir {
            format!("{name}/")
        } else {
            name.to_string()
        };
        out.push(RawCandidate {
            insert_text: None,
            text,
            display,
            kind: if is_dir {
                CandidateKind::Directory
            } else {
                CandidateKind::File
            },
            data: CandidateData::File {
                path: entry.path(),
                is_dir,
                size,
            },
            source: None,
            accept_action: None,
            annotations: Vec::new(),
            display_spans: Vec::new(),
        });
    }
    out.sort_by(|a, b| a.text.cmp(&b.text));
    out
}

/// `~` expansion, plus this consumer's own empty-means-here rule.
///
/// The tilde half delegates to [`lattice_core::home::expand_tilde`] so a
/// Windows host resolves `%USERPROFILE%`; the empty case stays local because it
/// is a *completion* rule (an empty prefix completes the current directory),
/// not something a path helper should decide for everyone.
fn expand_tilde(p: &str) -> PathBuf {
    if p.is_empty() {
        return PathBuf::from(".");
    }
    PathBuf::from(for_the_filesystem(
        lattice_core::home::expand_tilde(p),
        cfg!(windows),
    ))
}

/// Spell `path` the way the OS will accept it.
///
/// A prefix is split on `/` everywhere in this module, so a listing's
/// directory always arrives ending in one. On Windows that is fine for an
/// ordinary path — `C:\Users\me/` opens — but not for a VERBATIM one,
/// `\\?\C:\Users\me/`, which is what `canonicalize` returns: a verbatim path
/// is handed to the filesystem untouched, `/` is not a separator in it, and
/// the directory does not exist. A picker rooted at a canonical path listed
/// nothing at all.
///
/// So a verbatim path has its `/` turned into `\`. Only that form, and only on
/// Windows: elsewhere a backslash is a legal character in a file name.
fn for_the_filesystem(path: String, windows: bool) -> String {
    if windows && path.starts_with(r"\\?\") {
        path.replace('/', "\\")
    } else {
        path
    }
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::panic)]
    use super::*;
    use lattice_core::{Buffer, Document};
    use lattice_grammar::CommandRegistry;

    fn ctx_for<'a>(
        prefix: &'a str,
        buffer: &'a Buffer,
        registry: &'a CommandRegistry,
    ) -> GenerateContext<'a> {
        GenerateContext {
            prefix,
            buffer,
            registry,
            case_sensitive: false,
        }
    }

    // ---- for_the_filesystem ----

    /// The Windows half, pinned on every platform because the function is
    /// pure: a verbatim path gets real separators, and nothing else is
    /// touched — not an ordinary Windows path, and never a path off Windows,
    /// where `\` may be part of a name.
    #[test]
    fn a_verbatim_windows_path_gets_real_separators_and_nothing_else_does() {
        assert_eq!(
            for_the_filesystem(r"\\?\C:\Users\me/src/".to_string(), true),
            r"\\?\C:\Users\me\src\"
        );
        assert_eq!(
            for_the_filesystem(r"C:\Users\me/src/".to_string(), true),
            r"C:\Users\me/src/"
        );
        assert_eq!(
            for_the_filesystem(r"\\?\odd/name/".to_string(), false),
            r"\\?\odd/name/"
        );
    }

    // ---- CommandsGenerator ----

    #[test]
    fn commands_generator_returns_one_candidate_per_registered_command() {
        let mut registry = CommandRegistry::new();
        let _ = lattice_grammar::builtins::populate(&mut registry);
        let _ = lattice_grammar::ex_commands::populate(&mut registry);
        let document = Document::empty();
        let buffer = document.buffer().clone();
        let g = CommandsGenerator;
        let candidates = g.generate(&ctx_for("", &buffer, &registry));
        assert!(candidates.len() > 10, "expected multiple ex-commands");
        // Spot-check: write should appear (it's an ex-command).
        assert!(candidates.iter().any(|c| c.text == "write"));
        // UD.2: motions ARE invocable via `:` (unified dispatch), so they
        // appear with their `motion:` prefix.
        assert!(
            candidates.iter().any(|c| c.text == "motion:line-down"),
            "motions are actionable via `:` and must be completable",
        );
        // Operators are NOT actionable standalone (they need a target) and
        // stay filtered — the boundary the filter draws.
        assert!(
            !candidates.iter().any(|c| c.text.starts_with("operator:")),
            "operators are not standalone-actionable and must be filtered out",
        );
    }

    #[test]
    fn commands_generator_filters_delimiter_only_commands() {
        // ex:substitute and ex:global have SurfaceForm::Delimiter --
        // they're typed via :s/.../.../  and :g/.../.../  not by
        // name. The completion list must hide them so the user
        // doesn't see (and can't pick) a candidate that would error
        // when accepted.
        let mut registry = CommandRegistry::new();
        let _ = lattice_grammar::builtins::populate(&mut registry);
        let _ = lattice_grammar::ex_commands::populate(&mut registry);
        let document = Document::empty();
        let buffer = document.buffer().clone();
        let candidates = CommandsGenerator.generate(&ctx_for("", &buffer, &registry));
        assert!(
            !candidates.iter().any(|c| c.text == "ex:substitute"),
            "ex:substitute is delimiter-form-only and must not appear",
        );
        assert!(
            !candidates.iter().any(|c| c.text == "ex:global"),
            "ex:global is delimiter-form-only and must not appear",
        );
        // Other ex-commands stay present.
        assert!(candidates.iter().any(|c| c.text == "write"));
    }

    #[test]
    fn commands_generator_emits_doc_and_kind_label_in_data() {
        let mut registry = CommandRegistry::new();
        let _ = lattice_grammar::builtins::populate(&mut registry);
        let _ = lattice_grammar::ex_commands::populate(&mut registry);
        let document = Document::empty();
        let buffer = document.buffer().clone();
        let candidates = CommandsGenerator.generate(&ctx_for("", &buffer, &registry));
        let write = candidates.iter().find(|c| c.text == "write").unwrap();
        match &write.data {
            CandidateData::Command {
                doc, kind_label, ..
            } => {
                assert!(!doc.is_empty(), "ex:write should have a doc");
                assert_eq!(kind_label, "ex-command");
            }
            other => panic!("expected Command data, got {other:?}"),
        }
    }

    #[test]
    fn commands_generator_cache_key_embeds_registry_generation() {
        // The key embeds the registry generation so a runtime command
        // registration / unload (a plugin drain, which RCUs a registry with a
        // bumped `generation()`) invalidates the cached candidate list —
        // plugin commands then appear in `<Tab>` completion without a flush.
        let registry = CommandRegistry::new();
        let document = Document::empty();
        let buffer = document.buffer().clone();
        let g = CommandsGenerator;
        let key = g.cache_key(&ctx_for("anything", &buffer, &registry));
        assert_eq!(
            key,
            Some(CacheKey::new(format!(
                "gen:commands:v1:{}",
                registry.generation()
            )))
        );
    }

    #[test]
    fn commands_generator_cache_key_independent_of_prefix() {
        // Verify cache key is the same regardless of prefix --
        // matcher does the filtering against the cached set, so
        // typing more chars shouldn't invalidate.
        let registry = CommandRegistry::new();
        let document = Document::empty();
        let buffer = document.buffer().clone();
        let g = CommandsGenerator;
        let k1 = g.cache_key(&ctx_for("", &buffer, &registry));
        let k2 = g.cache_key(&ctx_for("ex:wri", &buffer, &registry));
        assert_eq!(k1, k2);
    }

    // ---- FilesGenerator ----

    #[test]
    fn files_generator_lists_current_directory_when_prefix_empty() {
        let registry = CommandRegistry::new();
        let document = Document::empty();
        let buffer = document.buffer().clone();
        let g = FilesGenerator;
        // Run from the workspace root; the test harness's cwd is
        // the crate dir.
        let candidates = g.generate(&ctx_for("", &buffer, &registry));
        // Should at least produce some entries (Cargo.toml, src/, etc.).
        assert!(!candidates.is_empty(), "expected non-empty cwd listing");
    }

    #[test]
    fn files_generator_filters_by_basename_prefix() {
        let registry = CommandRegistry::new();
        let document = Document::empty();
        let buffer = document.buffer().clone();
        let g = FilesGenerator;
        let candidates = g.generate(&ctx_for("Carg", &buffer, &registry));
        assert!(candidates.iter().any(|c| c.text.starts_with("Carg")));
    }

    #[test]
    fn files_generator_marks_directories_with_trailing_slash() {
        let registry = CommandRegistry::new();
        let document = Document::empty();
        let buffer = document.buffer().clone();
        let g = FilesGenerator;
        let candidates = g.generate(&ctx_for("", &buffer, &registry));
        let src_entry = candidates.iter().find(|c| c.display.starts_with("src"));
        if let Some(entry) = src_entry {
            // src is a directory; should have trailing /.
            assert_eq!(entry.kind, CandidateKind::Directory);
            assert!(entry.display.ends_with('/'));
            assert!(entry.text.ends_with('/'));
        }
    }

    #[test]
    fn files_generator_completes_nested_path_with_slash() {
        // Regression guard: FilesGenerator must walk the
        // directory referenced by everything before the LAST `/`
        // in the prefix and filter remaining entries by the
        // basename suffix. Without this, `:e crates/latt<Tab>`
        // would fail to surface any candidates.
        let tmp = std::env::temp_dir().join(format!("lattice-files-nested-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&tmp);
        let sub = tmp.join("sub");
        std::fs::create_dir_all(&sub).unwrap();
        for n in ["alpha", "beta", "zeta"] {
            std::fs::write(sub.join(n), "").unwrap();
        }
        // An absolute prefix, NOT `set_current_dir` + a relative one. The
        // working directory is process-global and tests run in parallel, so
        // changing it — even briefly — made the tests above, which list the
        // current directory, see this temp dir instead of the crate's.
        let prefix = format!("{}/sub/al", tmp.display());
        let expected = format!("{}/sub/alpha", tmp.display());

        let registry = CommandRegistry::new();
        let document = Document::empty();
        let buffer = document.buffer().clone();
        let g = FilesGenerator;
        let candidates = g.generate(&ctx_for(&prefix, &buffer, &registry));

        let _ = std::fs::remove_dir_all(&tmp);

        assert!(
            candidates.iter().any(|c| c.text == expected),
            "expected `{expected}` candidate, got {} candidates: {:?}",
            candidates.len(),
            candidates.iter().map(|c| &c.text).collect::<Vec<_>>(),
        );
    }

    #[test]
    fn files_generator_returns_empty_for_nonexistent_directory() {
        let registry = CommandRegistry::new();
        let document = Document::empty();
        let buffer = document.buffer().clone();
        let g = FilesGenerator;
        let candidates = g.generate(&ctx_for("/this/path/should/not/exist/", &buffer, &registry));
        assert!(candidates.is_empty());
    }

    #[test]
    fn files_generator_cache_key_is_per_directory() {
        let registry = CommandRegistry::new();
        let document = Document::empty();
        let buffer = document.buffer().clone();
        let g = FilesGenerator;
        let k_a = g.cache_key(&ctx_for("/tmp/foo", &buffer, &registry));
        let k_b = g.cache_key(&ctx_for("/tmp/foo/", &buffer, &registry));
        let k_c = g.cache_key(&ctx_for("/var/", &buffer, &registry));
        // /tmp/foo (no slash) keys to "" because no slash before.
        // We deliberately bucket by directory; basename doesn't
        // change the key.
        assert_ne!(k_a, k_b);
        assert_ne!(k_b, k_c);
    }

    #[test]
    fn files_generator_uses_short_ttl() {
        let g = FilesGenerator;
        assert_eq!(g.cache_ttl(), Duration::from_secs(1));
    }
}