gdscript_base/

lib.rs

//! `gdscript-base` — foundational POD types shared across the gdscript-analyzer.
//!
//! The lowest layer of the crate stack (`plans/01-ARCHITECTURE.md` §1). It holds the
//! engine-/protocol-neutral, `serde`-serializable result structs every client maps to
//! its own protocol, plus byte-offset position types and a [`LineIndex`] for the
//! byte↔(line, column) and byte↔UTF-16 conversions LSP clients need.
//!
//! All offsets are **byte** offsets into a file's UTF-8 source. No logic beyond the
//! conversions lives here. The crate is `wasm32`-safe (no `std::fs`, clocks, threads).
//!
//! These POD result structs are the analyzer's **public wire contract** (consumed via
//! [`gdscript_ide`](https://docs.rs/gdscript-ide)), so every public item is documented and
//! `#![deny(missing_docs)]` keeps it that way.
#![cfg_attr(docsrs, feature(doc_cfg))]
#![deny(missing_docs)]

use serde::{Deserialize, Serialize};

/// An opaque file handle. The host owns the `FileId` → text mapping; the library never
/// reads paths.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct FileId(pub u32);

/// A half-open byte range `[start, end)` into a file's UTF-8 source.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct TextRange {
    /// Inclusive start byte offset.
    pub start: u32,
    /// Exclusive end byte offset.
    pub end: u32,
}

impl TextRange {
    /// A new range from `start` to `end` (bytes).
    #[must_use]
    pub const fn new(start: u32, end: u32) -> Self {
        Self { start, end }
    }
}

/// A `(file, byte offset)` cursor position.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct FilePosition {
    /// The file.
    pub file: FileId,
    /// The byte offset within the file.
    pub offset: u32,
}

/// Diagnostic severity.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Severity {
    /// A hard error.
    Error,
    /// A warning.
    Warning,
    /// Informational.
    Info,
    /// A hint.
    Hint,
}

/// What analysis layer produced a diagnostic — lets clients group/filter parse vs. type
/// diagnostics without parsing the `code`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum DiagnosticSource {
    /// A lexer / parser / indentation diagnostic (Phase 1).
    #[default]
    Syntax,
    /// A type / semantic diagnostic from inference (Phase 2).
    Type,
}

/// An LSP-aligned diagnostic tag — a rendering hint editors apply on top of the severity.
/// Serialized as the LSP `DiagnosticTag` NUMBER (`1` / `2`) so protocol clients forward it
/// without a mapping table.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DiagnosticTag {
    /// Unused or unreachable code — editors render it faded/dimmed (LSP value `1`).
    Unnecessary,
    /// Deprecated code — editors render it struck through (LSP value `2`).
    Deprecated,
}

impl Serialize for DiagnosticTag {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        match self {
            Self::Unnecessary => 1u8,
            Self::Deprecated => 2u8,
        }
        .serialize(s)
    }
}

impl<'de> Deserialize<'de> for DiagnosticTag {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match u8::deserialize(d)? {
            1 => Ok(Self::Unnecessary),
            2 => Ok(Self::Deprecated),
            other => Err(serde::de::Error::custom(format!(
                "unknown DiagnosticTag value {other} (expected 1 or 2)"
            ))),
        }
    }
}

/// A diagnostic with a byte range, a stable machine code, a severity, and a message.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Diagnostic {
    /// The byte range the diagnostic applies to.
    pub range: TextRange,
    /// Severity.
    pub severity: Severity,
    /// A stable code, e.g. `GDSCRIPT_SYNTAX` or `INTEGER_DIVISION`.
    pub code: String,
    /// Human-readable message.
    pub message: String,
    /// Which analysis layer produced it. Defaults to [`DiagnosticSource::Syntax`] so older
    /// serialized diagnostics and Phase-1 call sites round-trip unchanged.
    #[serde(default)]
    pub source: DiagnosticSource,
    /// Quick-fixes offered for this diagnostic (e.g. "add type annotation"). Empty when none.
    #[serde(default)]
    pub fixes: Vec<CodeAction>,
    /// LSP-aligned rendering tags ([`DiagnosticTag`]) — `Unnecessary` on the unused/unreachable
    /// family so editors dim it. Omitted from JSON when empty, so pre-tag serialized
    /// diagnostics and consumers round-trip unchanged.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<DiagnosticTag>,
}

/// The kind of a document symbol (a subset of LSP `SymbolKind`, named for GDScript).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SymbolKind {
    /// A `class_name` / inner `class`.
    Class,
    /// A `func`.
    Function,
    /// A `func` that is a class member (currently same as `Function`).
    Method,
    /// A `var`.
    Variable,
    /// A `const`.
    Constant,
    /// An `enum`.
    Enum,
    /// An enum variant.
    EnumMember,
    /// A `signal`.
    Signal,
}

/// A (possibly nested) symbol in a document's outline.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DocumentSymbol {
    /// The symbol name.
    pub name: String,
    /// Optional detail (e.g. a signature).
    pub detail: Option<String>,
    /// The symbol kind.
    pub kind: SymbolKind,
    /// The full range of the symbol (its whole declaration).
    pub range: TextRange,
    /// The range of the name/selection within `range`.
    pub selection_range: TextRange,
    /// Nested symbols (members of a class, variants of an enum).
    pub children: Vec<DocumentSymbol>,
}

/// What a fold range corresponds to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum FoldKind {
    /// An indented block body.
    Block,
    /// A `#region`…`#endregion` pair.
    Region,
    /// A multi-line bracketed span.
    Brackets,
}

/// A foldable range.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct FoldRange {
    /// The foldable byte range.
    pub range: TextRange,
    /// What kind of fold it is.
    pub kind: FoldKind,
}

/// The kind of a completion item.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CompletionKind {
    /// A language keyword.
    Keyword,
    /// An annotation (`@export`, …).
    Annotation,
    /// A function/method name.
    Function,
    /// A variable / parameter / local.
    Variable,
    /// A constant.
    Constant,
    /// A class / type name.
    Class,
    /// An enum.
    Enum,
    /// A signal.
    Signal,
}

/// A by-name completion suggestion.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CompletionItem {
    /// The label shown / inserted.
    pub label: String,
    /// The kind of suggestion.
    pub kind: CompletionKind,
    /// Optional text to insert (defaults to `label`).
    pub insert_text: Option<String>,
    /// Optional secondary text shown after the label — a type or signature, e.g. `: int`
    /// or `(node: Node) -> void`. Phase 2 fills this for typed members; `None` keeps the
    /// Phase-1 by-name items unchanged.
    #[serde(default)]
    pub detail: Option<String>,
}

// ---------------------------------------------------------------------------
// Phase 2 PODs — hover, signature help, inlay hints, code actions, navigation.
// Each is an engine-/protocol-neutral result struct (byte offsets, serde). A feature
// returning one of these maps it to its own protocol at the client edge. See
// `plans/PHASE-2-IMPLEMENTATION-PLAYBOOK.md` §1.1.
// ---------------------------------------------------------------------------

/// Documentation rendered as Markdown (engine `BBCode` already converted at codegen time).
pub type Markdown = String;

/// The result of a hover query: an inferred type / signature label plus engine docs.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct HoverResult {
    /// The inferred type / signature rendered for display, e.g. `Node` or
    /// `add_child(node: Node) -> void`. `None` when the type is `Unknown` (elided — the
    /// Phase-3 cross-file seam) so we never show a placeholder type.
    pub ty_label: Option<String>,
    /// Engine documentation as Markdown. Empty when no doc XML is available.
    pub doc: Markdown,
    /// The source range the hover applies to (the hovered token / expression).
    pub range: TextRange,
}

/// One parameter within a [`SignatureInfo`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ParamInfo {
    /// The parameter label, e.g. `node: Node` or `force_readable_name: bool = false`.
    pub label: String,
    /// Optional documentation (Markdown).
    pub doc: Markdown,
}

/// One signature shown in signature help (GDScript has no overloads, so usually one).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SignatureInfo {
    /// The full signature label, e.g.
    /// `add_child(node: Node, force_readable_name: bool = false) -> void`.
    pub label: String,
    /// Optional documentation (Markdown).
    pub doc: Markdown,
    /// The parameters, in order.
    pub params: Vec<ParamInfo>,
}

/// The result of a signature-help query at a call site.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SignatureHelp {
    /// The candidate signatures.
    pub signatures: Vec<SignatureInfo>,
    /// Index into `signatures` of the active one.
    pub active_signature: u32,
    /// Index of the active parameter within the active signature. A vararg call keeps the
    /// last parameter active once the fixed parameters are exhausted.
    pub active_parameter: u32,
}

/// What an [`InlayHint`] represents.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum InlayHintKind {
    /// An inferred type, e.g. `: int` after a `:=` declaration or an unannotated parameter.
    Type,
    /// An inferred parameter name shown at a call site.
    Parameter,
}

/// An inline hint rendered at a byte offset (e.g. the `: int` the engine LSP omits).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct InlayHint {
    /// The byte offset at which to render the hint.
    pub offset: u32,
    /// The hint text, e.g. `: int`.
    pub label: String,
    /// What kind of hint it is.
    pub kind: InlayHintKind,
}

/// The semantic role of a [`SemanticToken`] — a GDScript-named subset of the LSP standard token
/// types. Richer than a TextMate grammar: it distinguishes a type from a variable, a parameter from
/// a local, a member from a global, a declaration from a use.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum SemanticTokenType {
    /// A free function / a function call.
    Function,
    /// A method (a function that is a class member).
    Method,
    /// A local variable / `var`.
    Variable,
    /// A function parameter.
    Parameter,
    /// A member field accessed via `.`.
    Property,
    /// A `class` / `class_name`.
    Class,
    /// An `enum`.
    Enum,
    /// An enum variant.
    EnumMember,
    /// A type name (in a `: T`, `as T`, `is T`, `extends T`, `-> T` position).
    Type,
    /// An annotation, e.g. `@export`.
    Decorator,
    /// A numeric literal.
    Number,
    /// A string literal (incl. `StringName` / `NodePath`).
    String,
    /// A comment.
    Comment,
    /// A `signal`.
    Signal,
    /// A `const`.
    Constant,
}

/// Bit flags for [`SemanticToken::modifiers`] (the LSP standard modifier subset we emit).
pub mod semantic_token_modifier {
    /// The token is the *declaration* of the symbol (vs. a use).
    pub const DECLARATION: u32 = 1 << 0;
    /// A read-only binding (`const`).
    pub const READONLY: u32 = 1 << 1;
    /// A `static` member.
    pub const STATIC: u32 = 1 << 2;
    /// An engine / built-in symbol (not user code).
    pub const DEFAULT_LIBRARY: u32 = 1 << 3;
}

/// A semantic-highlighting token: a source range classified by its contextual/resolved role. Drives
/// `textDocument/semanticTokens` — intelligence a grammar can't produce. Modifiers are a bitset of
/// [`semantic_token_modifier`] flags.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct SemanticToken {
    /// The token's byte range.
    pub range: TextRange,
    /// What the token denotes.
    pub token_type: SemanticTokenType,
    /// A bitset of [`semantic_token_modifier`] flags.
    pub modifiers: u32,
}

/// A single text edit: replace `range` with `new_text`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TextEdit {
    /// The byte range to replace.
    pub range: TextRange,
    /// The replacement text.
    pub new_text: String,
}

/// The edits to apply to one file (non-overlapping; the client sorts and applies them).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FileEdit {
    /// The file the edits apply to.
    pub file: FileId,
    /// The edits within that file.
    pub edits: Vec<TextEdit>,
}

/// A set of edits across one or more files (a cross-file rename, a quick-fix). Phase 3's rename
/// spans files, so this is multi-file; a single-file change is just one [`FileEdit`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SourceChange {
    /// The per-file edits.
    pub edits: Vec<FileEdit>,
}

impl SourceChange {
    /// A change that touches a single file.
    #[must_use]
    pub fn single(file: FileId, edits: Vec<TextEdit>) -> Self {
        Self {
            edits: vec![FileEdit { file, edits }],
        }
    }
}

/// A (file, range) pair — the atom of cross-file navigation results.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct FileRange {
    /// The file the range lives in.
    pub file: FileId,
    /// The byte range.
    pub range: TextRange,
}

/// Why a token is a reference (rust-analyzer's `ReferenceCategory`, trimmed).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ReferenceKind {
    /// The symbol's declaration site.
    Declaration,
    /// A read (the default — any non-write use).
    Read,
    /// A write (the symbol on the left of an assignment).
    Write,
}

/// One reference to a symbol (find-references result), including its declaration.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct Reference {
    /// The file the reference is in.
    pub file: FileId,
    /// The identifier-token range.
    pub range: TextRange,
    /// What kind of reference it is.
    pub kind: ReferenceKind,
}

/// Why a [rename](crate) was refused — the "correct or it refuses" contract. Never a partial edit.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum RenameError {
    /// The new name is not a single valid GDScript identifier (or is a keyword).
    InvalidIdentifier {
        /// The rejected name.
        new_name: String,
    },
    /// The target is an engine/builtin symbol, or could not be resolved — not ours to rename.
    NotRenamable {
        /// Why.
        reason: String,
    },
    /// The new name already exists in an affected scope.
    WouldCollide {
        /// Where the colliding symbol is.
        at: FileRange,
        /// The colliding name.
        with: String,
    },
    /// The symbol is also reachable via a surface this analyzer cannot safely rewrite (a `.tscn`
    /// `[connection]`/string call for a method/signal, the `project.godot` `[autoload]` key). We
    /// refuse rather than leave a stale reference behind.
    CrossesUnsupportedBoundary {
        /// What boundary.
        what: String,
    },
}

/// A code action / quick-fix: a titled, optionally-kinded [`SourceChange`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CodeAction {
    /// Human-readable title, e.g. `Add type annotation`.
    pub title: String,
    /// An LSP-style kind such as `quickfix` or `refactor.rewrite`; `None` if unspecified.
    pub kind: Option<String>,
    /// The edit this action performs.
    pub edit: SourceChange,
}

/// A navigation target (goto-definition / -declaration). Phase 2 only ever points within
/// the same file; cross-file targets arrive in Phase 3.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NavTarget {
    /// The file the target lives in.
    pub file: FileId,
    /// The full range of the target's declaration.
    pub full_range: TextRange,
    /// The name / selection range to focus within `full_range`.
    pub focus_range: TextRange,
    /// The target symbol's name.
    pub name: String,
    /// The target symbol's kind.
    pub kind: SymbolKind,
}

/// A read query was cancelled by a concurrent change. (Phase 1 never actually cancels,
/// but the type is on the API surface so the Phase 3 salsa swap is source-compatible.)
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Cancelled;

/// The result of a cancellable read query.
pub type Cancellable<T> = Result<T, Cancelled>;

/// Maps byte offsets to/from `(line, column)` and UTF-16 columns.
///
/// Lines and columns are 0-based. The core emits byte offsets; LSP/JS clients convert
/// to UTF-16 via this (the documented position-encoding footgun —
/// `plans/01-ARCHITECTURE.md` §4).
///
/// ```
/// use gdscript_base::LineIndex;
/// // Line 1 contains a 2-byte `é`, so the byte column and the UTF-16 column diverge
/// // after it — the encoding footgun this type exists to handle.
/// let src = "var x := 1\nvar é := 2\n";
/// let idx = LineIndex::new(src);
/// let colon = u32::try_from(src.rfind(":=").unwrap()).unwrap(); // the `:` on line 1
/// let lc = idx.line_col(colon);
/// assert_eq!((lc.line, lc.col), (1, 7)); // byte column 7 (`é` is 2 bytes)
/// assert_eq!(idx.utf16_col(src, colon), 6); // UTF-16 column 6 (`é` is 1 code unit)
/// ```
#[derive(Debug, Clone)]
pub struct LineIndex {
    /// Byte offset of the start of each line (line 0 starts at 0).
    line_starts: Vec<u32>,
    /// Total source length in bytes.
    len: u32,
}

/// A 0-based `(line, column)` position. `col` is a byte offset within the line.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LineCol {
    /// 0-based line.
    pub line: u32,
    /// 0-based byte column within the line.
    pub col: u32,
}

impl LineIndex {
    /// Build a line index for `text`.
    #[must_use]
    pub fn new(text: &str) -> Self {
        let mut line_starts = vec![0u32];
        for (i, b) in text.bytes().enumerate() {
            if b == b'\n' {
                // `i` fits in u32 for any file we accept (< 4 GiB).
                #[allow(clippy::cast_possible_truncation)]
                line_starts.push(i as u32 + 1);
            }
        }
        #[allow(clippy::cast_possible_truncation)]
        let len = text.len() as u32;
        Self { line_starts, len }
    }

    /// The `(line, byte-column)` of a byte offset (clamped to the end of input).
    #[must_use]
    pub fn line_col(&self, offset: u32) -> LineCol {
        let offset = offset.min(self.len);
        // The line is the last line-start <= offset.
        let line = match self.line_starts.binary_search(&offset) {
            Ok(line) => line,
            Err(next) => next - 1,
        };
        #[allow(clippy::cast_possible_truncation)]
        let line = line as u32;
        LineCol {
            line,
            col: offset - self.line_starts[line as usize],
        }
    }

    /// The UTF-16 column of a byte offset on its line (LSP's default encoding).
    #[must_use]
    pub fn utf16_col(&self, text: &str, offset: u32) -> u32 {
        let lc = self.line_col(offset);
        let line_start = self.line_starts[lc.line as usize] as usize;
        let col_end = (line_start + lc.col as usize).min(text.len());
        let units: usize = text[line_start..col_end].chars().map(char::len_utf16).sum();
        u32::try_from(units).unwrap_or(u32::MAX)
    }

    /// The number of lines.
    #[must_use]
    pub fn line_count(&self) -> u32 {
        #[allow(clippy::cast_possible_truncation)]
        {
            self.line_starts.len() as u32
        }
    }
}

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

    #[test]
    fn line_index_basics() {
        let src = "ab\ncde\n\nx";
        let idx = LineIndex::new(src);
        assert_eq!(idx.line_count(), 4);
        assert_eq!(idx.line_col(0), LineCol { line: 0, col: 0 });
        assert_eq!(idx.line_col(1), LineCol { line: 0, col: 1 });
        assert_eq!(idx.line_col(3), LineCol { line: 1, col: 0 }); // 'c'
        assert_eq!(idx.line_col(7), LineCol { line: 2, col: 0 }); // blank line
        assert_eq!(idx.line_col(8), LineCol { line: 3, col: 0 }); // 'x'
    }

    #[test]
    fn utf16_columns_account_for_astral_chars() {
        // "a😀b": 'a' is 1 UTF-8 byte / 1 UTF-16 unit; '😀' is 4 bytes / 2 units.
        let src = "a😀b";
        let idx = LineIndex::new(src);
        assert_eq!(idx.utf16_col(src, 0), 0); // before 'a'
        assert_eq!(idx.utf16_col(src, 1), 1); // before '😀'
        assert_eq!(idx.utf16_col(src, 5), 3); // before 'b' (1 + 2 units)
    }
}