gdscript_hir/
ty.rs

1//! The Phase-2 type model (Playbook §2/§3.5): the gradual [`Ty`] lattice over `Variant`, the
2//! hard/soft [`TypeSource`], the ported `is_assignable` compatibility check, and `TyRef`→`Ty`
3//! resolution against the engine API.
4//!
5//! GDScript is gradually typed over one runtime value type, `Variant`. Three top-ish types are
6//! kept distinct on purpose: [`Ty::Variant`] (the absorbing gradual top), [`Ty::Unknown`] (the
7//! Phase-3 cross-file seam — never warns, never cascades, elided from hover), and [`Ty::Error`]
8//! (already diagnosed — suppresses further cascade).
9
10use gdscript_api::{BuiltinId, ClassId, ElemRef, EngineApi, TyRef};
11use smol_str::SmolStr;
12
13/// An opaque reference to another `.gd` script (by `class_name`/path). Resolved to a concrete
14/// type only in Phase 3; in Phase 2 it never appears (the seam returns [`Ty::Unknown`] instead),
15/// but the variant exists so the upgrade is additive.
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
17pub struct ScriptRefId(pub u32);
18
19/// An interned signal signature id (Phase 3+).
20#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
21pub struct SignalSigId(pub u32);
22
23/// A reference to an enum type, kept as the qualified name it was written with. Phase 2 does not
24/// resolve it to a concrete enum table — `is_assignable` only needs the *kind* (enum values are
25/// assignable to `int`), and hover shows the qualified name.
26#[derive(Debug, Clone, PartialEq, Eq, Hash)]
27pub struct EnumRef {
28    /// The dotted name (`Node.ProcessMode`, `Error`, …).
29    pub qualified: SmolStr,
30    /// Whether the source was a `bitfield::`.
31    pub bitfield: bool,
32}
33
34/// A Phase-2 type. `Clone` not `Copy` (the `Box`es in `Array`/`Dict`).
35#[derive(Debug, Clone, PartialEq, Eq, Hash)]
36pub enum Ty {
37    /// A builtin Variant type (`int`, `float`, `String`, `Vector2`, …).
38    Builtin(BuiltinId),
39    /// An engine class instance, this file's own class, or an inner class.
40    Object(ClassId),
41    /// Another script, opaque in Phase 2 (the seam yields `Unknown` instead).
42    ScriptRef(ScriptRefId),
43    /// `Array[T]`; a bare `Array` is `Array(Box::new(Ty::Variant))`.
44    Array(Box<Ty>),
45    /// `Dictionary[K, V]`; a bare `Dictionary` is `Dict(Variant, Variant)`.
46    Dict(Box<Ty>, Box<Ty>),
47    /// An enum type (an enum value is assignable to `int`).
48    Enum(EnumRef),
49    /// A `Signal` value.
50    Signal(Option<SignalSigId>),
51    /// A `Callable` value.
52    Callable,
53    /// No value (`void`).
54    Void,
55    /// The gradual top / escape hatch (≈ engine `VARIANT` ≈ Pyright `Any`).
56    Variant,
57    /// The Phase-3 cross-file seam marker — distinct from `Variant`. Never warns, never appears
58    /// in hover, never cascades a diagnostic.
59    Unknown,
60    /// An already-reported error; suppresses downstream diagnostics.
61    Error,
62}
63
64impl Ty {
65    /// A bare `Array` (`Array[Variant]`).
66    #[must_use]
67    pub fn array_of_variant() -> Self {
68        Self::Array(Box::new(Self::Variant))
69    }
70
71    /// A bare `Dictionary` (`Dictionary[Variant, Variant]`).
72    #[must_use]
73    pub fn dict_of_variant() -> Self {
74        Self::Dict(Box::new(Self::Variant), Box::new(Self::Variant))
75    }
76
77    /// Whether this is the gradual top `Variant`.
78    #[must_use]
79    pub fn is_variant(&self) -> bool {
80        matches!(self, Self::Variant)
81    }
82
83    /// Whether this is the cross-file seam marker.
84    #[must_use]
85    pub fn is_unknown(&self) -> bool {
86        matches!(self, Self::Unknown)
87    }
88
89    /// Whether this is the already-reported error marker.
90    #[must_use]
91    pub fn is_error(&self) -> bool {
92        matches!(self, Self::Error)
93    }
94
95    /// Whether a diagnostic should be suppressed because this type carries no information
96    /// (`Variant`/`Unknown`/`Error`) — the receivers on which `UNSAFE_*` etc. must never fire.
97    #[must_use]
98    pub fn is_uninformative(&self) -> bool {
99        matches!(self, Self::Variant | Self::Unknown | Self::Error)
100    }
101
102    /// A display label for hover / inlay hints, or `None` when the type is `Unknown` (elided —
103    /// the Phase-3 seam) so we never render a placeholder.
104    #[must_use]
105    pub fn label(&self, api: &EngineApi) -> Option<String> {
106        Some(match self {
107            Self::Builtin(id) => api.builtin(*id).name.clone(),
108            Self::Object(id) => api.class(*id).name.clone(),
109            Self::Array(elem) => match elem.label(api) {
110                Some(e) if e != "Variant" => format!("Array[{e}]"),
111                _ => "Array".to_owned(),
112            },
113            Self::Dict(k, v) => match (k.label(api), v.label(api)) {
114                (Some(k), Some(v)) if k != "Variant" || v != "Variant" => {
115                    format!("Dictionary[{k}, {v}]")
116                }
117                _ => "Dictionary".to_owned(),
118            },
119            Self::Enum(e) => e.qualified.to_string(),
120            Self::Signal(_) => "Signal".to_owned(),
121            Self::Callable => "Callable".to_owned(),
122            Self::Void => "void".to_owned(),
123            Self::Variant => "Variant".to_owned(),
124            // `ScriptRef` (opaque) and the seam/error markers carry no display label.
125            Self::ScriptRef(_) | Self::Unknown | Self::Error => return None,
126        })
127    }
128}
129
130/// How a binding's type was established (Playbook §2). The ordering is load-bearing: a type is
131/// *hard* (statically enforced) iff its source is greater than [`TypeSource::Inferred`].
132#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
133pub enum TypeSource {
134    /// No type known yet.
135    Undetected,
136    /// Inferred from an initializer (`:=` / soft) — best-effort; downgraded to `Variant` on
137    /// conflict rather than erroring.
138    Inferred,
139    /// Inferred-but-annotated as inferred (`var x := e` once accepted).
140    AnnotatedInferred,
141    /// Explicitly annotated (`var x: T`) — a mismatch is an error.
142    AnnotatedExplicit,
143}
144
145impl TypeSource {
146    /// A *hard* type is statically enforced (mismatch = error). A *soft* (`Inferred`) type is
147    /// best-effort and downgraded to `Variant` on conflict.
148    #[must_use]
149    pub fn is_hard(self) -> bool {
150        self > Self::Inferred
151    }
152}
153
154/// A typed binding: its [`Ty`] plus how the type was established.
155#[derive(Debug, Clone, PartialEq, Eq)]
156pub struct TypedBinding {
157    /// The binding's type.
158    pub ty: Ty,
159    /// How it was established.
160    pub source: TypeSource,
161}
162
163/// The outcome of [`is_assignable`] — richer than a bool so the caller can raise the right
164/// diagnostic (Playbook §3.5/§5).
165#[derive(Debug, Clone, Copy, PartialEq, Eq)]
166pub enum Assign {
167    /// Cleanly assignable.
168    Ok,
169    /// Assignable, but the source is `Variant` — a gradual (unchecked) escape.
170    OkUnsafe,
171    /// `float` stored into an `int` slot (`NARROWING_CONVERSION`).
172    Narrowing,
173    /// `int` used where an enum is expected (`INT_AS_ENUM_WITHOUT_CAST`).
174    IntAsEnum,
175    /// Not assignable (`TYPE_MISMATCH`).
176    No,
177}
178
179/// Whether a value of type `from` may be assigned to a slot of type `to` (the engine's
180/// `check_type_compatibility`, ported — Playbook §3.5). **Order matters.**
181#[must_use]
182pub fn is_assignable(api: &EngineApi, from: &Ty, to: &Ty) -> Assign {
183    // 1. Anything assigns to `Variant`.
184    if to.is_variant() {
185        return Assign::Ok;
186    }
187    // 2/3. Never cascade through the seam / error markers; a `Variant` source is the gradual
188    // escape (allowed-but-unsafe). These precede the structural checks deliberately.
189    if matches!(from, Ty::Unknown | Ty::Error) || matches!(to, Ty::Unknown | Ty::Error) {
190        return Assign::Ok;
191    }
192    if from.is_variant() {
193        return Assign::OkUnsafe;
194    }
195
196    match to {
197        Ty::Builtin(to_id) => match from {
198            Ty::Builtin(from_id) if from_id == to_id => Assign::Ok,
199            Ty::Builtin(from_id) => {
200                let from_name = api.builtin(*from_id).name.as_str();
201                let to_name = api.builtin(*to_id).name.as_str();
202                match (from_name, to_name) {
203                    ("float", "int") => Assign::Narrowing, // NARROWING_CONVERSION
204                    // `int`→`float` widening (silent) + Godot's string-ish auto-conversions.
205                    ("int", "float")
206                    | ("String", "StringName" | "NodePath")
207                    | ("StringName" | "NodePath", "String") => Assign::Ok,
208                    _ => Assign::No,
209                }
210            }
211            // An enum value is assignable to `int`.
212            Ty::Enum(_) if api.builtin(*to_id).name == "int" => Assign::Ok,
213            _ => Assign::No,
214        },
215        Ty::Enum(to_enum) => match from {
216            Ty::Enum(from_enum) if from_enum == to_enum => Assign::Ok,
217            // A *different* enum's value is an `int` at runtime: Godot wants a cast
218            // (`INT_AS_ENUM_WITHOUT_CAST`) — never a hard `TYPE_MISMATCH`.
219            Ty::Enum(_) => Assign::IntAsEnum,
220            // `int` → enum without a cast.
221            Ty::Builtin(id) if api.builtin(*id).name == "int" => Assign::IntAsEnum,
222            _ => Assign::No,
223        },
224        Ty::Object(to_class) => match from {
225            Ty::Object(from_class) if api.is_subclass(*from_class, *to_class) => Assign::Ok,
226            // Downcast (a base value into a derived slot): permitted with a runtime check —
227            // unsafe, but not a hard error. Real code relies on `var c: Control = get_child(0)`.
228            Ty::Object(from_class) if api.is_subclass(*to_class, *from_class) => Assign::OkUnsafe,
229            // A script reference is opaque — treat like the seam, never a mismatch.
230            Ty::ScriptRef(_) => Assign::Ok,
231            _ => Assign::No,
232        },
233        // Typed arrays are invariant — but only between two *informative* element types
234        // (`Array[Button]` ↛ `Array[Node]`). A bare `Array`/`Array[Variant]`, or an
235        // `Array[Unknown]` (cross-file element), assigns freely: the engine permits
236        // untyped→typed with a runtime check, and the seam must never hard-error.
237        Ty::Array(to_elem) => match from {
238            Ty::Array(from_elem)
239                if from_elem == to_elem
240                    || from_elem.is_uninformative()
241                    || to_elem.is_uninformative() =>
242            {
243                Assign::Ok
244            }
245            _ => Assign::No,
246        },
247        Ty::Dict(to_k, to_v) => match from {
248            Ty::Dict(from_k, from_v)
249                if (from_k == to_k || from_k.is_uninformative() || to_k.is_uninformative())
250                    && (from_v == to_v || from_v.is_uninformative() || to_v.is_uninformative()) =>
251            {
252                Assign::Ok
253            }
254            _ => Assign::No,
255        },
256        Ty::Signal(_) => {
257            if matches!(from, Ty::Signal(_)) {
258                Assign::Ok
259            } else {
260                Assign::No
261            }
262        }
263        Ty::Callable => {
264            if matches!(from, Ty::Callable) {
265                Assign::Ok
266            } else {
267                Assign::No
268            }
269        }
270        Ty::Void => {
271            if matches!(from, Ty::Void) {
272                Assign::Ok
273            } else {
274                Assign::No
275            }
276        }
277        // An opaque script-ref target, and the `Variant`/`Unknown`/`Error` targets already
278        // handled above, all accept anything.
279        Ty::ScriptRef(_) | Ty::Variant | Ty::Unknown | Ty::Error => Assign::Ok,
280    }
281}
282
283/// Resolve an engine-API [`TyRef`] (the unresolved form stored in the model) to a [`Ty`].
284#[must_use]
285pub fn resolve_tyref(api: &EngineApi, tyref: &TyRef) -> Ty {
286    match tyref {
287        TyRef::Void => Ty::Void,
288        TyRef::Variant => Ty::Variant,
289        // `Array`/`Dictionary`/`Callable`/`Signal` are engine builtins, but we keep dedicated
290        // `Ty` variants for them (a lambda is `Ty::Callable`, `[]` is `Ty::Array`); normalize
291        // the bare builtin form so annotations, constructors, and values all agree.
292        TyRef::Builtin(id) => match api.builtin(*id).name.as_str() {
293            "Callable" => Ty::Callable,
294            "Signal" => Ty::Signal(None),
295            "Array" => Ty::array_of_variant(),
296            "Dictionary" => Ty::dict_of_variant(),
297            _ => Ty::Builtin(*id),
298        },
299        TyRef::Class(id) => Ty::Object(*id),
300        TyRef::TypedArray(elem) => Ty::Array(Box::new(resolve_elemref(api, elem))),
301        TyRef::TypedDict(k, v) => Ty::Dict(
302            Box::new(resolve_elemref(api, k)),
303            Box::new(resolve_elemref(api, v)),
304        ),
305        TyRef::Enum {
306            qualified,
307            bitfield,
308        } => Ty::Enum(EnumRef {
309            qualified: SmolStr::new(qualified),
310            bitfield: *bitfield,
311        }),
312    }
313}
314
315/// Resolve a typed-container element [`ElemRef`] to a [`Ty`].
316#[must_use]
317pub fn resolve_elemref(_api: &EngineApi, elem: &ElemRef) -> Ty {
318    match elem {
319        ElemRef::Variant => Ty::Variant,
320        ElemRef::Builtin(id) => Ty::Builtin(*id),
321        ElemRef::Class(id) => Ty::Object(*id),
322        ElemRef::Enum {
323            qualified,
324            bitfield,
325        } => Ty::Enum(EnumRef {
326            qualified: SmolStr::new(qualified),
327            bitfield: *bitfield,
328        }),
329    }
330}
331
332#[cfg(test)]
333mod tests {
334    use super::*;
335
336    fn ty_of(api: &EngineApi, builtin: &str) -> Ty {
337        Ty::Builtin(api.builtin_by_name(builtin).expect("known builtin"))
338    }
339
340    #[test]
341    fn type_source_hardness() {
342        assert!(!TypeSource::Undetected.is_hard());
343        assert!(!TypeSource::Inferred.is_hard());
344        assert!(TypeSource::AnnotatedInferred.is_hard());
345        assert!(TypeSource::AnnotatedExplicit.is_hard());
346    }
347
348    #[test]
349    fn variant_and_seam_assignability() {
350        let api = gdscript_api::bundled();
351        let int = ty_of(api, "int");
352        // Anything assigns to Variant; Variant into a typed slot is allowed-but-unsafe.
353        assert_eq!(is_assignable(api, &int, &Ty::Variant), Assign::Ok);
354        assert_eq!(is_assignable(api, &Ty::Variant, &int), Assign::OkUnsafe);
355        // The seam and error markers never cascade, in either direction.
356        assert_eq!(is_assignable(api, &Ty::Unknown, &int), Assign::Ok);
357        assert_eq!(is_assignable(api, &int, &Ty::Unknown), Assign::Ok);
358        assert_eq!(is_assignable(api, &Ty::Error, &int), Assign::Ok);
359    }
360
361    #[test]
362    fn numeric_conversions() {
363        let api = gdscript_api::bundled();
364        let int = ty_of(api, "int");
365        let float = ty_of(api, "float");
366        assert_eq!(is_assignable(api, &int, &float), Assign::Ok); // widening, silent
367        assert_eq!(is_assignable(api, &float, &int), Assign::Narrowing);
368        assert_eq!(is_assignable(api, &int, &int), Assign::Ok);
369        let string = ty_of(api, "String");
370        assert_eq!(is_assignable(api, &string, &int), Assign::No);
371    }
372
373    #[test]
374    fn object_subclassing() {
375        let api = gdscript_api::bundled();
376        let node = Ty::Object(api.class_by_name("Node").unwrap());
377        let node2d = Ty::Object(api.class_by_name("Node2D").unwrap());
378        // Node2D is a Node (upcast → Ok); a Node into a Node2D slot is a downcast — permitted
379        // with a runtime check (unsafe), not a hard mismatch.
380        assert_eq!(is_assignable(api, &node2d, &node), Assign::Ok);
381        assert_eq!(is_assignable(api, &node, &node2d), Assign::OkUnsafe);
382        // An unrelated builtin is a real mismatch.
383        let s = ty_of(api, "String");
384        assert_eq!(is_assignable(api, &s, &node), Assign::No);
385    }
386
387    #[test]
388    fn arrays_are_invariant() {
389        let api = gdscript_api::bundled();
390        let int = ty_of(api, "int");
391        let float = ty_of(api, "float");
392        let arr_int = Ty::Array(Box::new(int.clone()));
393        let arr_int2 = Ty::Array(Box::new(int));
394        let arr_float = Ty::Array(Box::new(float));
395        assert_eq!(is_assignable(api, &arr_int, &arr_int2), Assign::Ok);
396        // No covariance: Array[int] is not assignable to Array[float] even though int->float.
397        assert_eq!(is_assignable(api, &arr_int2, &arr_float), Assign::No);
398    }
399
400    #[test]
401    fn enum_int_bridge() {
402        let api = gdscript_api::bundled();
403        let int = ty_of(api, "int");
404        let e = Ty::Enum(EnumRef {
405            qualified: SmolStr::new("Node.ProcessMode"),
406            bitfield: false,
407        });
408        assert_eq!(is_assignable(api, &e, &int), Assign::Ok); // enum -> int
409        assert_eq!(is_assignable(api, &int, &e), Assign::IntAsEnum); // int -> enum (warn)
410    }
411
412    #[test]
413    fn label_elides_unknown() {
414        let api = gdscript_api::bundled();
415        assert_eq!(Ty::Unknown.label(api), None);
416        assert_eq!(ty_of(api, "int").label(api).as_deref(), Some("int"));
417        assert_eq!(
418            Ty::Array(Box::new(ty_of(api, "int"))).label(api).as_deref(),
419            Some("Array[int]")
420        );
421    }
422}
gdscript_hir/ty.rs

gdscript_hir/
ty.rs
