gdscript_ide/

lib.rs

//! `gdscript-ide` — the public, engine-/protocol-neutral analysis API.
//!
//! Modeled on rust-analyzer's `ide::AnalysisHost` / `ide::Analysis`
//! (`plans/01-ARCHITECTURE.md` §2). [`AnalysisHost`] is the single mutable owner of the
//! input world; [`Analysis`] is a cheap, cloneable, `Send` snapshot whose queries take
//! byte offsets and return plain `serde` result structs from `gdscript-base` — never
//! `lsp-types`. Each client (LSP server, the guitkx adapter, the CLI, the WASM
//! playground) maps these POD results to its own protocol.
//!
//! Phase 3 (M0) swaps the engine behind these types from a plain VFS map to a **salsa**
//! query graph in [`gdscript_db`]: the input world is now `FileText` salsa inputs, mutated
//! through `apply_change`; [`Analysis`] is a cloned database handle (salsa handles are
//! `Clone + Send`, replacing the old `Arc<map>` snapshot). Cancellation is now *real* —
//! a concurrent `apply_change` cancels in-flight reads on outstanding handles, which unwind
//! into `Err(Cancelled)` at the query boundary (see [`catch`]). The public API shape is
//! unchanged. The crate stays `wasm32`-safe (CI guards this).
#![cfg_attr(docsrs, feature(doc_cfg))]

use std::sync::Arc;

use gdscript_base::{
    Cancellable, CodeAction, CompletionItem, Diagnostic, DocumentSymbol, FileId, FilePosition,
    FoldRange, HoverResult, InlayHint, SignatureHelp,
};
use gdscript_db::{Db, RootDatabase};
use salsa::Durability;

mod features;
mod navigation;
mod semantic;
mod semantic_tokens;

/// Run a read query, turning a salsa cancellation (a concurrent `apply_change` invalidated the
/// snapshot) into `Err(Cancelled)`. The closure is `AssertUnwindSafe` because the database
/// handle it borrows is shared, immutable for the duration of the read, and salsa's unwind is
/// panic-safe by design.
fn catch<T>(f: impl FnOnce() -> T) -> Cancellable<T> {
    salsa::Cancelled::catch(std::panic::AssertUnwindSafe(f)).map_err(|_| gdscript_base::Cancelled)
}

/// The single mutable owner of analysis state — one per project/workspace.
///
/// The input world is a virtual file system (`FileId` → UTF-8 text) held as salsa inputs; the
/// host never reads paths. Clients push text via [`AnalysisHost::apply_change`].
#[derive(Debug, Clone, Default)]
pub struct AnalysisHost {
    db: RootDatabase,
}

/// A batch of input changes. `None` text removes the file.
#[derive(Debug, Default)]
pub struct Change {
    /// Files to add/replace (`Some`) or remove (`None`).
    pub files: Vec<(FileId, Option<Arc<str>>)>,
    /// Each file's `res://` path (loader-supplied; M3 `preload`/`extends "res://…"` resolution).
    /// Supply it when a file is **added**; it is stable across edits, so a keystroke change must
    /// omit it (salsa bumps an input field's revision on *every* set, even an identical value, so
    /// re-sending a path each edit would needlessly invalidate the `res_path_registry`).
    pub paths: Vec<(FileId, String)>,
    /// The project's `project.godot` text (loader-supplied; M4 `[autoload]` resolution). Set once
    /// on project open / when it changes; omit on `.gd` keystrokes.
    pub project_config: Option<Arc<str>>,
}

impl Change {
    /// An empty change set.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Queue a file add/replace.
    pub fn change_file(&mut self, file: FileId, text: impl Into<Arc<str>>) {
        self.files.push((file, Some(text.into())));
    }

    /// Queue a file removal.
    pub fn remove_file(&mut self, file: FileId) {
        self.files.push((file, None));
    }

    /// Record a file's `res://` path (the project-relative resource path the loader assigns). Set
    /// it once, when the file is first added; omit it on subsequent edits.
    pub fn set_file_path(&mut self, file: FileId, path: impl Into<String>) {
        self.paths.push((file, path.into()));
    }

    /// Record the project's `project.godot` text (M4 `[autoload]` resolution). Set on project open
    /// / when it changes; omit on `.gd` keystrokes.
    pub fn set_project_config(&mut self, text: impl Into<Arc<str>>) {
        self.project_config = Some(text.into());
    }
}

impl AnalysisHost {
    /// A new, empty host.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Apply a batch of input changes. The **only** mutation entry point — each `set`/`remove`
    /// bumps the salsa revision (and cancels any in-flight reads on outstanding [`Analysis`]
    /// handles). Edited files are `LOW` durability (they change every keystroke).
    pub fn apply_change(&mut self, change: Change) {
        let mut structure_changed = false;
        for (id, text) in change.files {
            if let Some(t) = text {
                // A file the project hasn't seen before changes the file *set*.
                structure_changed |= self.db.file_text(id).is_none();
                self.db.set_file_text(id, &t, Durability::LOW);
            } else {
                structure_changed |= self.db.file_text(id).is_some();
                self.db.remove_file(id);
            }
        }
        // Apply `res://` paths (loader-supplied, on add). `set_file_path` no-ops when the path is
        // unchanged, so this never invalidates the `res_path_registry` on a redundant set; the
        // FileText must already exist, so it runs after the text loop above.
        for (id, path) in change.paths {
            self.db.set_file_path(id, &path);
        }
        // The `project.godot` config (M4 autoloads) — its own MEDIUM input, guarded against no-op
        // re-sets, so re-opening a project doesn't invalidate the autoload registry.
        if let Some(text) = change.project_config {
            self.db.set_project_config(&text);
        }
        // Rebuild the project file-set input ONLY on add/remove — never on a body edit — so the
        // MEDIUM-durability registry stays firewalled against keystrokes.
        if structure_changed {
            self.db.sync_source_root();
        }
    }

    /// Install a runtime-fetched engine model — the **wasm path** (an `extension_api` blob the host
    /// `fetch`ed and brotli-decoded, decoded here via `EngineApi::from_bytes`). Native builds use the
    /// bundled model and normally never call this. Returns `false` (rather than panicking) if the
    /// bytes fail to decode, leaving the model unset. First install wins (load-once); installing it
    /// **after** queries have already run correctly recomputes them — the wasm engine-generation
    /// input invalidates the affected reads, so loading the blob async (after opening a document) is
    /// safe, not just loading it first.
    pub fn set_engine_api(&mut self, bytes: &[u8]) -> bool {
        match gdscript_api::EngineApi::from_bytes(bytes) {
            Ok(api) => {
                self.db.set_engine_api(api);
                true
            }
            Err(_) => false,
        }
    }

    /// A cheap, cloneable, `Send` snapshot for read queries (a cloned salsa database handle).
    #[must_use]
    pub fn analysis(&self) -> Analysis {
        Analysis {
            db: self.db.clone(),
        }
    }
}

/// An immutable snapshot of the world — a cloned salsa handle. Every query is [`Cancellable`]:
/// a concurrent `apply_change` cancels in-flight reads, which the client re-issues against the
/// fresh snapshot.
#[derive(Debug, Clone)]
pub struct Analysis {
    db: RootDatabase,
}

impl Analysis {
    // ---- Tier-0 features: real data ----

    /// A pretty-printed dump of the syntax tree (debugging / playground).
    ///
    /// # Errors
    /// `Err(Cancelled)` if a concurrent `apply_change` invalidated this snapshot.
    pub fn syntax_tree(&self, file: FileId) -> Cancellable<Option<String>> {
        catch(|| {
            self.db
                .file_text(file)
                .map(|ft| gdscript_db::parse(&self.db, ft).debug_tree())
        })
    }

    /// Parse-error diagnostics ∪ the Phase-2 §5 type diagnostics.
    ///
    /// # Errors
    /// See [`Analysis::syntax_tree`].
    pub fn diagnostics(&self, file: FileId) -> Cancellable<Vec<Diagnostic>> {
        catch(|| {
            self.db
                .file_text(file)
                .map(|ft| {
                    let mut diags = features::diagnostics(&self.db, ft);
                    diags.extend(semantic::type_diagnostics(&self.db, ft));
                    diags
                })
                .unwrap_or_default()
        })
    }

    /// The document outline (classes, funcs, vars, consts, enums, signals, members).
    ///
    /// # Errors
    /// See [`Analysis::syntax_tree`].
    pub fn document_symbols(&self, file: FileId) -> Cancellable<Vec<DocumentSymbol>> {
        catch(|| {
            self.db
                .file_text(file)
                .map(|ft| features::document_symbols(&self.db, ft))
                .unwrap_or_default()
        })
    }

    /// Semantic-highlighting tokens: each meaningful token classified by its contextual role
    /// (declarations, types, parameters, members, calls, literals, comments) — richer than a
    /// grammar. In source order.
    ///
    /// # Errors
    /// See [`Analysis::syntax_tree`].
    pub fn semantic_tokens(&self, file: FileId) -> Cancellable<Vec<gdscript_base::SemanticToken>> {
        catch(|| {
            self.db
                .file_text(file)
                .map(|ft| semantic_tokens::semantic_tokens(&self.db, ft))
                .unwrap_or_default()
        })
    }

    /// Foldable ranges (blocks, `#region` pairs, multi-line brackets).
    ///
    /// # Errors
    /// See [`Analysis::syntax_tree`].
    pub fn folding_ranges(&self, file: FileId) -> Cancellable<Vec<FoldRange>> {
        catch(|| {
            self.db
                .file_text(file)
                .map(|ft| features::folding_ranges(&self.db, ft))
                .unwrap_or_default()
        })
    }

    /// Completions. After `receiver.` it offers the inferred member set; otherwise (or when
    /// the receiver is `Variant`/`Unknown`) it falls back to the Tier-0 by-name completion
    /// (keywords, annotations after `@`, document-local symbols) so it never regresses.
    ///
    /// # Errors
    /// See [`Analysis::syntax_tree`].
    pub fn completions(&self, pos: FilePosition) -> Cancellable<Vec<CompletionItem>> {
        catch(|| {
            self.db
                .file_text(pos.file)
                .map(|ft| {
                    semantic::node_path_completions(&self.db, ft, pos.offset)
                        .or_else(|| semantic::member_completions(&self.db, ft, pos.offset))
                        .unwrap_or_else(|| features::completions(&self.db, ft, pos.offset))
                })
                .unwrap_or_default()
        })
    }

    /// Hover: the inferred type of the expression / binding under the cursor (`Unknown`
    /// elided). `None` when there is nothing typed there.
    ///
    /// # Errors
    /// See [`Analysis::syntax_tree`].
    pub fn hover(&self, pos: FilePosition) -> Cancellable<Option<HoverResult>> {
        catch(|| {
            self.db
                .file_text(pos.file)
                .and_then(|ft| semantic::hover(&self.db, ft, pos.offset))
        })
    }

    /// Inlay `: T` hints on `:=` declarations + unannotated params / `for`-vars (suppressed
    /// when the type is `Variant`/`Unknown`).
    ///
    /// # Errors
    /// See [`Analysis::syntax_tree`].
    pub fn inlay_hints(&self, file: FileId) -> Cancellable<Vec<InlayHint>> {
        catch(|| {
            self.db
                .file_text(file)
                .map(|ft| semantic::inlay_hints(&self.db, ft))
                .unwrap_or_default()
        })
    }

    /// Signature help at a call site (active parameter by top-level comma count).
    ///
    /// # Errors
    /// See [`Analysis::syntax_tree`].
    pub fn signature_help(&self, pos: FilePosition) -> Cancellable<Option<SignatureHelp>> {
        catch(|| {
            self.db
                .file_text(pos.file)
                .and_then(|ft| semantic::signature_help(&self.db, ft, pos.offset))
        })
    }

    /// Code actions at a position (currently "add type annotation").
    ///
    /// # Errors
    /// See [`Analysis::syntax_tree`].
    pub fn code_actions(&self, pos: FilePosition) -> Cancellable<Vec<CodeAction>> {
        catch(|| {
            self.db
                .file_text(pos.file)
                .map(|ft| semantic::code_actions(&self.db, ft, pos.offset))
                .unwrap_or_default()
        })
    }

    /// Go-to-definition: the declaration target(s) of the symbol under the cursor (cross-file).
    ///
    /// # Errors
    /// See [`Analysis::syntax_tree`].
    pub fn goto_definition(&self, pos: FilePosition) -> Cancellable<Vec<gdscript_base::NavTarget>> {
        catch(|| navigation::goto_definition(&self.db, pos))
    }

    /// Find every reference to the symbol under the cursor, project-wide (incl. its declaration).
    ///
    /// # Errors
    /// See [`Analysis::syntax_tree`].
    pub fn find_references(&self, pos: FilePosition) -> Cancellable<Vec<gdscript_base::Reference>> {
        catch(|| navigation::find_references(&self.db, pos))
    }

    /// Rename the symbol under the cursor to `new_name` — a cross-file edit, or a refusal
    /// ([`RenameError`](gdscript_base::RenameError)); never a partial edit.
    ///
    /// # Errors
    /// `Err(Cancelled)` if a concurrent `apply_change` invalidated this snapshot. The rename's own
    /// refusal is the `Result` *inside* the `Cancellable`.
    pub fn rename(
        &self,
        pos: FilePosition,
        new_name: &str,
    ) -> Cancellable<Result<gdscript_base::SourceChange, gdscript_base::RenameError>> {
        catch(|| navigation::rename(&self.db, pos, new_name))
    }

    /// Project-wide symbols matching `query` (fuzzy-ranked class names + members).
    ///
    /// # Errors
    /// See [`Analysis::syntax_tree`].
    pub fn workspace_symbols(&self, query: &str) -> Cancellable<Vec<gdscript_base::NavTarget>> {
        catch(|| navigation::workspace_symbols(&self.db, query))
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn host_with(src: &str) -> (AnalysisHost, FileId) {
        let mut host = AnalysisHost::new();
        let file = FileId(0);
        let mut change = Change::new();
        change.change_file(file, src);
        host.apply_change(change);
        (host, file)
    }

    #[test]
    fn snapshot_reads_applied_files() {
        let (host, file) = host_with("func f():\n\tpass\n");
        let analysis = host.analysis();
        let symbols = analysis.document_symbols(file).unwrap();
        assert_eq!(symbols.len(), 1);
        assert_eq!(symbols[0].name, "f");
    }

    #[test]
    fn preload_resolves_cross_file_through_the_public_api() {
        // The real `guitkx.gd` pattern, end-to-end through `apply_change` + `set_file_path`:
        // `const M = preload("res://…")` then `M.new().method()`.
        let mut host = AnalysisHost::new();
        let mut change = Change::new();
        change.change_file(
            FileId(0),
            "class_name Markup\nfunc parse() -> int:\n\treturn 1\n",
        );
        change.set_file_path(FileId(0), "res://markup.gd");
        change.change_file(
            FileId(1),
            "const M = preload(\"res://markup.gd\")\nfunc go():\n\tvar n := M.new().parse()\n",
        );
        change.set_file_path(FileId(1), "res://main.gd");
        host.apply_change(change);
        let analysis = host.analysis();

        // Valid code → no diagnostics.
        assert!(analysis.diagnostics(FileId(1)).unwrap().is_empty());
        // The cross-file preload resolved, so `n` is typed `int`; an inlay hint proves it (an
        // *unresolved* preload would leave `n` on the seam, suppressing the hint).
        let hints = analysis.inlay_hints(FileId(1)).unwrap();
        assert!(
            hints.iter().any(|h| h.label.contains("int")),
            "expected an `: int` inlay on the preload-resolved binding, got {hints:?}",
        );
    }

    #[test]
    fn autoload_resolves_cross_file_through_the_public_api() {
        // End-to-end through `apply_change` + `set_project_config`: a `*`-singleton autoload
        // script (no class_name — resolved by path) used by its bare name.
        let mut host = AnalysisHost::new();
        let mut change = Change::new();
        change.change_file(FileId(0), "func volume() -> int:\n\treturn 50\n");
        change.set_file_path(FileId(0), "res://audio.gd");
        change.change_file(FileId(1), "func go():\n\tvar v := Audio.volume()\n");
        change.set_file_path(FileId(1), "res://main.gd");
        change.set_project_config("[autoload]\nAudio=\"*res://audio.gd\"\n");
        host.apply_change(change);
        let analysis = host.analysis();

        assert!(analysis.diagnostics(FileId(1)).unwrap().is_empty());
        // `Audio.volume()` resolved cross-file via the autoload singleton → `v : int` inlay.
        let hints = analysis.inlay_hints(FileId(1)).unwrap();
        assert!(
            hints.iter().any(|h| h.label.contains("int")),
            "expected an `: int` inlay on the autoload-resolved binding, got {hints:?}",
        );
    }

    #[test]
    fn scene_node_path_typing_through_the_public_api() {
        // The Phase-4 killer feature end-to-end: a `.tscn` injected via `apply_change` + a script it
        // attaches → `$Btn` types as `Button`, surfaced as an `: Button` inlay (zero annotations).
        let mut host = AnalysisHost::new();
        let mut change = Change::new();
        change.change_file(
            FileId(0),
            "[gd_scene format=3]\n\
             [ext_resource type=\"Script\" path=\"res://main.gd\" id=\"1\"]\n\
             [node name=\"Root\" type=\"Control\"]\n\
             script = ExtResource(\"1\")\n\
             [node name=\"Btn\" type=\"Button\" parent=\".\"]\n",
        );
        change.set_file_path(FileId(0), "res://main.tscn");
        change.change_file(
            FileId(1),
            "extends Control\nfunc _ready():\n\tvar b := $Btn\n",
        );
        change.set_file_path(FileId(1), "res://main.gd");
        host.apply_change(change);
        let analysis = host.analysis();

        assert!(analysis.diagnostics(FileId(1)).unwrap().is_empty());
        let hints = analysis.inlay_hints(FileId(1)).unwrap();
        assert!(
            hints.iter().any(|h| h.label.contains("Button")),
            "expected a `: Button` inlay on `var b := $Btn`, got {hints:?}",
        );
    }

    #[test]
    fn node_path_completion_offers_scene_children() {
        // `$Panel/` offers Panel's children (typed by their `type=`); `$` offers the attach node's.
        let mut host = AnalysisHost::new();
        let mut change = Change::new();
        change.change_file(
            FileId(0),
            "[gd_scene format=3]\n\
             [ext_resource type=\"Script\" path=\"res://main.gd\" id=\"1\"]\n\
             [node name=\"Root\" type=\"Control\"]\n\
             script = ExtResource(\"1\")\n\
             [node name=\"Panel\" type=\"Panel\" parent=\".\"]\n\
             [node name=\"Ok\" type=\"Button\" parent=\"Panel\"]\n\
             [node name=\"Cancel\" type=\"Button\" parent=\"Panel\"]\n",
        );
        change.set_file_path(FileId(0), "res://main.tscn");
        let gd = "extends Control\nfunc _ready():\n\tvar b := $Panel/\n";
        change.change_file(FileId(1), gd);
        change.set_file_path(FileId(1), "res://main.gd");
        host.apply_change(change);
        let analysis = host.analysis();

        let offset = u32::try_from(gd.find("$Panel/").unwrap() + "$Panel/".len()).unwrap();
        let items = analysis
            .completions(FilePosition {
                file: FileId(1),
                offset,
            })
            .unwrap();
        let labels: Vec<_> = items.iter().map(|i| i.label.as_str()).collect();
        assert!(
            labels.contains(&"Ok") && labels.contains(&"Cancel"),
            "{labels:?}"
        );
        // node completions are typed by their `type=` and don't leak keywords/locals here.
        assert!(
            items
                .iter()
                .find(|i| i.label == "Ok")
                .is_some_and(|i| i.detail.as_deref() == Some("Button")),
            "{items:?}",
        );
        assert!(
            !labels.contains(&"func"),
            "should be node-path, not keyword, completion"
        );
    }

    #[test]
    fn node_path_completion_does_not_hijack_inside_a_string_literal() {
        // A `$child/` that appears INSIDE a string literal must NOT trigger node-path completion
        // (the byte scan has no lexer awareness; a `String` token at the cursor suppresses it).
        let mut host = AnalysisHost::new();
        let mut change = Change::new();
        change.change_file(
            FileId(0),
            "[gd_scene format=3]\n\
             [ext_resource type=\"Script\" path=\"res://main.gd\" id=\"1\"]\n\
             [node name=\"Root\" type=\"Control\"]\n\
             script = ExtResource(\"1\")\n\
             [node name=\"Panel\" type=\"Panel\" parent=\".\"]\n\
             [node name=\"Ok\" type=\"Button\" parent=\"Panel\"]\n",
        );
        change.set_file_path(FileId(0), "res://main.tscn");
        let gd = "extends Control\nfunc _ready():\n\tvar s := \"$Panel/\"\n";
        change.change_file(FileId(1), gd);
        change.set_file_path(FileId(1), "res://main.gd");
        host.apply_change(change);
        let analysis = host.analysis();

        // cursor right after the `/`, INSIDE the string literal.
        let offset = u32::try_from(gd.find("$Panel/").unwrap() + "$Panel/".len()).unwrap();
        let items = analysis
            .completions(FilePosition {
                file: FileId(1),
                offset,
            })
            .unwrap();
        assert!(
            !items.iter().any(|i| i.label == "Ok"),
            "node names must not leak into a string literal: {items:?}",
        );
    }

    #[test]
    fn goto_definition_on_a_node_path_jumps_into_the_tscn() {
        // Cursor on `$Btn` → a NavTarget pointing at the `[node name="Btn" …]` line in the owning
        // `.tscn` (the inverse of M1 typing; navigation the engine LSP cannot provide).
        let mut host = AnalysisHost::new();
        let mut change = Change::new();
        let scene = "[gd_scene format=3]\n\
             [ext_resource type=\"Script\" path=\"res://main.gd\" id=\"1\"]\n\
             [node name=\"Root\" type=\"Control\"]\n\
             script = ExtResource(\"1\")\n\
             [node name=\"Btn\" type=\"Button\" parent=\".\"]\n";
        let gd = "extends Control\nfunc _ready():\n\tvar b := $Btn\n";
        change.change_file(FileId(0), scene);
        change.set_file_path(FileId(0), "res://main.tscn");
        change.change_file(FileId(1), gd);
        change.set_file_path(FileId(1), "res://main.gd");
        host.apply_change(change);
        let analysis = host.analysis();

        let offset = u32::try_from(gd.find("$Btn").unwrap() + 1).unwrap(); // on the `B`
        let targets = analysis
            .goto_definition(FilePosition {
                file: FileId(1),
                offset,
            })
            .unwrap();
        assert_eq!(targets.len(), 1, "{targets:?}");
        assert_eq!(targets[0].file, FileId(0), "jumps into the .tscn");
        let focus =
            &scene[targets[0].focus_range.start as usize..targets[0].focus_range.end as usize];
        assert!(
            focus.contains("Btn"),
            "focus on the node name, got {focus:?}"
        );
    }

    #[test]
    fn find_refs_and_rename_cross_file_through_the_public_api() {
        let mut host = AnalysisHost::new();
        let mut change = Change::new();
        change.change_file(
            FileId(0),
            "class_name Widget\nfunc make() -> int:\n\treturn 1\n",
        );
        change.set_file_path(FileId(0), "res://widget.gd");
        change.change_file(
            FileId(1),
            "func f():\n\tvar w: Widget\n\tvar x := Widget.new()\n",
        );
        change.set_file_path(FileId(1), "res://main.gd");
        host.apply_change(change);
        let analysis = host.analysis();
        // The `class_name Widget` declaration name starts at offset 11 (`"class_name "` is 11).
        let at_decl = FilePosition {
            file: FileId(0),
            offset: 11,
        };
        // find-refs: declaration (f0) + annotation + `.new()` (f1) = 3.
        let refs = analysis.find_references(at_decl).unwrap();
        assert_eq!(refs.len(), 3, "{refs:?}");
        // rename → a cross-file SourceChange touching both files.
        let edit = analysis
            .rename(at_decl, "Gadget")
            .unwrap()
            .expect("rename ok");
        assert_eq!(edit.edits.len(), 2, "both files edited");
    }

    #[test]
    fn removing_a_file_clears_it() {
        let (mut host, file) = host_with("var x = 1\n");
        let mut change = Change::new();
        change.remove_file(file);
        host.apply_change(change);
        let analysis = host.analysis();
        assert!(analysis.document_symbols(file).unwrap().is_empty());
    }
}