smelt-stdlib 0.1.0

Shared standard-library shims and diagnostic categories used across the Smelt transpiler.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

//! Recognition of well-known language builtins that Smelt does not model.
//!
//! When a reference fails to resolve, the frontend asks this module whether the
//! name is a language/runtime builtin. A builtin that fails to resolve is a
//! [`MissingStdlib`](crate::DiagnosticCategory::MissingStdlib) gap (Smelt should
//! grow support for it); any other unresolved name is an
//! [`UnresolvedReference`](crate::DiagnosticCategory::UnresolvedReference).
//!
//! The set is intentionally a recognition list, not a support list — names here
//! may or may not be lowered yet. It only answers "is this a builtin?".

/// Returns whether `name` is a well-known JavaScript/TypeScript global builtin
/// (ECMAScript intrinsics plus widely available Web/Node runtime globals).
#[must_use]
pub fn is_javascript_global_builtin(name: &str) -> bool {
    matches!(
        name,
        // Core constructors and namespaces.
        "Array" | "Object" | "Number" | "String" | "Boolean" | "BigInt"
        | "Symbol" | "Function" | "Math" | "JSON" | "Reflect" | "Proxy"
        | "Date" | "RegExp" | "Promise" | "Map" | "Set" | "WeakMap"
        | "WeakSet" | "WeakRef" | "Iterator" | "Generator" | "Intl"
        // Error constructors.
        | "Error" | "TypeError" | "RangeError" | "SyntaxError"
        | "ReferenceError" | "EvalError" | "URIError" | "AggregateError"
        // Binary data / typed arrays.
        | "ArrayBuffer" | "SharedArrayBuffer" | "DataView" | "Int8Array"
        | "Uint8Array" | "Uint8ClampedArray" | "Int16Array" | "Uint16Array"
        | "Int32Array" | "Uint32Array" | "Float32Array" | "Float64Array"
        | "BigInt64Array" | "BigUint64Array"
        // Global functions.
        | "parseInt" | "parseFloat" | "isNaN" | "isFinite" | "structuredClone"
        | "encodeURIComponent" | "decodeURIComponent" | "encodeURI" | "decodeURI"
        | "queueMicrotask" | "setTimeout" | "clearTimeout" | "setInterval"
        | "clearInterval"
        // Ambient globals and environment objects.
        | "globalThis" | "global" | "self" | "window" | "console" | "process"
        // Common Web / Node runtime classes.
        | "TextEncoder" | "TextDecoder" | "URL" | "URLSearchParams" | "Blob"
        | "File" | "FormData" | "Headers" | "Request" | "Response" | "Buffer"
        | "AbortController" | "AbortSignal" | "Event" | "EventTarget"
    )
}

/// Compile-time availability of a global object member in the active target profile.
///
/// The current target is a deterministic non-DOM, Node-compatible environment
/// (the default generated Rust test profile from the global-objects plan). A
/// feature probe such as `"X" in globalThis` may only fold to a literal when the
/// answer is *known* for that profile; an [`Unknown`](GlobalPresence::Unknown)
/// member must keep its runtime check so erased and runtime answers never
/// disagree.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum GlobalPresence {
    /// The member is a recognized builtin that exists in the non-DOM profile, so
    /// `"X" in globalThis` is statically `true`.
    Present,
    /// The member is a recognized builtin that is intentionally absent from the
    /// non-DOM profile (browser/DOM-only surfaces), so `"X" in globalThis` is
    /// statically `false`.
    Absent,
    /// The member is not in any recognition registry, so its presence cannot be
    /// decided at compile time and the probe must stay a runtime check.
    Unknown,
}

/// Global members that the non-DOM Node-compatible profile treats as absent.
///
/// These names are still recognized JavaScript globals (see
/// [`is_javascript_global_builtin`]) but only exist in a browser/DOM host, so the
/// non-DOM profile answers `"X" in globalThis` with `false`. Keeping the absent
/// set explicit means everything else recognized is derived as present, instead
/// of maintaining a parallel hand-written "present" list that could drift from
/// the recognition registry.
const NON_DOM_ABSENT_GLOBALS: &[&str] = &["window", "self", "document"];

/// Classify a candidate global member name for the non-DOM Node-compatible profile.
///
/// The result is derived from the recognition registries that codegen actually
/// lowers — [`is_javascript_global_builtin`] plus the absent-in-non-DOM denylist —
/// rather than a separate literal "present" list, so the compile-time answer to
/// `"X" in globalThis` cannot drift from what Smelt can lower. Per the plan,
/// `structuredClone` and `crypto` are *not* answered `Present` here: they are
/// runtime functions whose probes may only fold once a deterministic runtime
/// implementation exists, so they stay [`Unknown`](GlobalPresence::Unknown).
#[must_use]
pub fn global_member_presence(name: &str) -> GlobalPresence {
    if NON_DOM_ABSENT_GLOBALS.contains(&name) {
        return GlobalPresence::Absent;
    }
    // Runtime-capability functions are gated on real deterministic runtime
    // support landing (plan section 7); until then their probe must not fold.
    if matches!(name, "structuredClone" | "crypto" | "fetch") {
        return GlobalPresence::Unknown;
    }
    if is_javascript_global_builtin(name) {
        GlobalPresence::Present
    } else {
        GlobalPresence::Unknown
    }
}

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

    /// Recognized intrinsics and runtime globals report as builtins.
    #[test]
    fn recognizes_known_globals() {
        for name in ["Array", "Number", "Reflect", "Proxy", "TextEncoder", "globalThis"] {
            assert!(is_javascript_global_builtin(name), "{name} should be a builtin");
        }
    }

    /// Ordinary user identifiers are not builtins.
    #[test]
    fn rejects_user_identifiers() {
        for name in ["Foo", "curried", "myHelper", "Circle"] {
            assert!(!is_javascript_global_builtin(name), "{name} should not be a builtin");
        }
    }

    /// Recognized non-DOM globals are present so `"X" in globalThis` folds true.
    #[test]
    fn recognized_node_globals_are_present() {
        for name in ["Map", "Set", "ArrayBuffer", "Reflect", "Promise", "process"] {
            assert_eq!(global_member_presence(name), GlobalPresence::Present, "{name}");
        }
    }

    /// DOM-only globals are absent so `"X" in globalThis` folds false.
    #[test]
    fn dom_only_globals_are_absent() {
        for name in ["window", "self", "document"] {
            assert_eq!(global_member_presence(name), GlobalPresence::Absent, "{name}");
        }
    }

    /// Unrecognized names and runtime-gated capabilities stay unknown.
    #[test]
    fn unmodeled_members_are_unknown() {
        for name in ["DocumentFragment", "__feature", "structuredClone", "crypto"] {
            assert_eq!(global_member_presence(name), GlobalPresence::Unknown, "{name}");
        }
    }

    /// The present set is derived from the recognition registry, not a copy of it.
    #[test]
    fn presence_tracks_recognition_registry() {
        // Every recognized builtin is either present or explicitly absent; none
        // silently fall through to Unknown except the runtime-gated capabilities.
        for name in ["Array", "JSON", "Math", "Buffer", "URL", "TextEncoder"] {
            assert_ne!(
                global_member_presence(name),
                GlobalPresence::Unknown,
                "recognized builtin {name} should have a decided presence"
            );
        }
    }
}