lua-language-server type rules, a strict mode, flow narrowing and FiveM data updates

crates/qbx_fivem_data/src/lib.rs

@@ -42,6 +42,9 @@ pub struct Native {
     returns: &'static str,
     params: &'static str,
     pub alias_of: Option<&'static str>,
+    /// The hash, returned values and parameters of the server native of the same name, when they
+    /// differ from those of the client one: `GetAllVehicles` returns a table on the server.
+    server: Option<(&'static str, &'static str, &'static str)>,
 }
 
 impl Native {
@@ -58,20 +61,52 @@ impl Native {
         let returns = cols.next()?;
         let params = cols.next()?;
         let alias_of = cols.next().filter(|a| !a.is_empty());
-        Some(Self { name, side, namespace, hash, returns, params, alias_of })
+        let server = match (cols.next(), cols.next(), cols.next()) {
+            (Some(hash), Some(returns), Some(params)) => Some((hash, returns, params)),
+            _ => None,
+        };
+        Some(Self { name, side, namespace, hash, returns, params, alias_of, server })
+    }
+
+    /// The native that code on `side` calls: on the server, the server native of the same name
+    /// when its signature differs from the client one.
+    pub fn on(self, side: Option<Side>) -> Self {
+        match (side, self.server) {
+            (Some(Side::Server), Some((hash, returns, params))) => {
+                Self { side: Side::Server, namespace: "CFX", hash, returns, params, server: None, ..self }
+            }
+            _ => self,
+        }
     }
 
+    /// The types of the values it returns. A `table` has the LuaCATS type of `RETURN_TYPES` where
+    /// that table gives one.
     pub fn returns(&self) -> impl Iterator<Item = &'static str> {
-        self.returns.split(',').filter(|r| !r.is_empty())
+        let native = self.name;
+        self.returns.split(',').filter(|r| !r.is_empty()).map(move |ty| match ty {
+            "table" => RETURN_TYPES.iter().find(|(owner, _)| *owner == native).map_or(ty, |(_, ty)| ty),
+            _ => ty,
+        })
     }
 
-    /// `(name, type)` pairs.
-    pub fn params(&self) -> impl Iterator<Item = (&'static str, &'static str)> {
-        self.params.split(',').filter_map(|p| p.split_once(':'))
+    /// `(name, type, optional)` triples. The table writes an optional parameter `name?`: the
+    /// pointer that the Lua wrapper takes as an initial value, which nil leaves 0. A function
+    /// parameter has the LuaCATS type of `CALLBACK_TYPES` where that table gives one.
+    pub fn params(&self) -> impl Iterator<Item = (&'static str, &'static str, bool)> {
+        let native = self.name;
+        self.params.split(',').filter_map(|p| p.split_once(':')).map(move |(name, ty)| {
+            let (name, optional) = match name.strip_suffix('?') {
+                Some(name) => (name, true),
+                None => (name, false),
+            };
+            let callback = CALLBACK_TYPES.iter().find(|(owner, param, _)| *owner == native && *param == name);
+            (name, callback.map_or(ty, |(_, _, ty)| ty), optional)
+        })
     }
 
     pub fn signature(&self) -> String {
-        let params: Vec<String> = self.params().map(|(n, t)| format!("{n}: {t}")).collect();
+        let params: Vec<String> =
+            self.params().map(|(n, t, optional)| format!("{n}{}: {t}", if optional { "?" } else { "" })).collect();
         let returns: Vec<&str> = self.returns().collect();
         let mut out = format!("function {}({})", self.name, params.join(", "));
         if !returns.is_empty() {
@@ -82,6 +117,51 @@ impl Native {
     }
 }
 
+/// The LuaCATS types of the function parameters of natives, which the native data only calls
+/// `function`, as their documentation describes the functions: `(native, parameter, type)`. The
+/// classes they name are declared in the stubs. `RegisterRawNuiCallback` is left out, as nothing
+/// documents what its callback receives.
+pub static CALLBACK_TYPES: &[(&str, &str, &str)] = &[
+    ("RegisterCommand", "handler", "fun(source: integer, args: string[], rawCommand: string)"),
+    (
+        "AddStateBagChangeHandler",
+        "handler",
+        "fun(bagName: string, key: string, value: any, reserved: number, replicated: boolean)",
+    ),
+    ("AddConvarChangeListener", "handler", "fun(conVarName: string, reserved: any)"),
+    ("RegisterConsoleListener", "listener", "fun(channel: string, message: string)"),
+    ("SetHttpHandler", "handler", "fun(request: HttpHandlerRequest, response: HttpHandlerResponse)"),
+    ("RegisterNuiCallback", "callback", "fun(data: unknown, cb: fun(response: any))"),
+    ("RegisterRawKeymap", "onKeyDown", "fun()|nil"),
+    ("RegisterRawKeymap", "onKeyUp", "fun()|nil"),
+    ("ScanResourceRoot", "callback", "fun(results: table)"),
+    ("RegisterResourceBuildTaskFactory", "factoryFn", "fun(): ResourceBuildTask"),
+    ("RegisterArchetypes", "factory", "fun(): table[]"),
+];
+
+/// The LuaCATS types of the tables that natives return, which the native data only calls `table`:
+/// `(native, type)`. Each is what the native serializes in the source of the runtime: a list of
+/// handles, hashes or names, of `[a, b]` pairs, or of command objects. `GetStateBagValue` gives the
+/// stored value itself, which may be of any type.
+pub static RETURN_TYPES: &[(&str, &str)] = &[
+    ("DoorSystemGetActive", "[Hash, Object][]"),
+    ("GetActivePlayers", "Player[]"),
+    ("GetAllObjects", "Object[]"),
+    ("GetAllPeds", "Ped[]"),
+    ("GetAllRopes", "integer[]"),
+    ("GetAllTrackJunctions", "integer[]"),
+    ("GetAllVehicleModels", "string[]"),
+    ("GetAllVehicles", "Vehicle[]"),
+    ("GetClosestTrackNodes", "[integer, integer][]"),
+    ("GetEntitiesInRadius", "Entity[]"),
+    ("GetGamePool", "Entity[]"),
+    ("GetPedDecorations", "[Hash, Hash][]"),
+    ("GetRegisteredCommands", "{ name: string, resource: string, arity: integer }[]"),
+    ("GetResourceCommands", "{ name: string, resource: string, arity: integer }[]"),
+    ("GetStateBagKeys", "string[]"),
+    ("GetStateBagValue", "any"),
+];
+
 struct LineTable {
     text: &'static str,
     starts: Vec<u32>,
@@ -171,17 +251,63 @@ pub fn native_docs(name: &str) -> Option<String> {
 pub struct Stub {
     pub name: &'static str,
     pub side: Side,
+    /// Whether it declares Lua standard libraries rather than CfxLua additions.
+    pub library: bool,
     pub source: &'static str,
 }
 
+const fn stub(name: &'static str, side: Side, library: bool, source: &'static str) -> Stub {
+    Stub { name, side, library, source }
+}
+
+/// The runtime definitions. FiveM only opens the `io` and `os` libraries on the server
+/// (`IS_FXSERVER` in citizen-scripting-lua's `LuaScriptRuntime.cpp`), so `lua54_server.lua` holds
+/// them; stubs extending a table come after the one declaring it.
 pub static STUBS: &[Stub] = &[
-    Stub { name: "lua54.lua", side: Side::Shared, source: include_str!("../stubs/lua54.lua") },
-    Stub { name: "cfx.lua", side: Side::Shared, source: include_str!("../stubs/cfx.lua") },
-    Stub { name: "glm.lua", side: Side::Shared, source: include_str!("../stubs/glm.lua") },
-    Stub { name: "cfx_client.lua", side: Side::Client, source: include_str!("../stubs/cfx_client.lua") },
-    Stub { name: "cfx_server.lua", side: Side::Server, source: include_str!("../stubs/cfx_server.lua") },
+    stub("lua54.lua", Side::Shared, true, include_str!("../stubs/lua54.lua")),
+    stub("lua54_server.lua", Side::Server, true, include_str!("../stubs/lua54_server.lua")),
+    stub("cfx.lua", Side::Shared, false, include_str!("../stubs/cfx.lua")),
+    stub("glm.lua", Side::Shared, false, include_str!("../stubs/glm.lua")),
+    stub("cfx_client.lua", Side::Client, false, include_str!("../stubs/cfx_client.lua")),
+    stub("cfx_server.lua", Side::Server, false, include_str!("../stubs/cfx_server.lua")),
+    stub("cfx_events.lua", Side::Shared, false, EVENTS_STUB),
 ];
 
+static EVENTS_STUB: &str = include_str!("../stubs/cfx_events.lua");
+
+/// An event that FiveM itself triggers, such as `onResourceStop` or `playerDropped`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct BuiltinEvent {
+    pub name: &'static str,
+    /// The only side that triggers it, or `Shared` when both do.
+    pub side: Side,
+}
+
+/// The events that FiveM itself triggers, as the `---@field` lines of the `CfxEvents` class in
+/// `cfx_events.lua` declare them: a `(client)` or `(server)` before the name scopes one to that side.
+pub fn builtin_events() -> &'static [BuiltinEvent] {
+    static EVENTS: OnceLock<Vec<BuiltinEvent>> = OnceLock::new();
+    EVENTS.get_or_init(|| {
+        let class = EVENTS_STUB.lines().skip_while(|line| *line != "---@class CfxEvents").skip(1);
+        class
+            .map_while(|line| line.strip_prefix("---@field "))
+            .filter_map(|field| {
+                let (side, field) = match field.split_once(") ") {
+                    Some(("(client", rest)) => (Side::Client, rest),
+                    Some(("(server", rest)) => (Side::Server, rest),
+                    _ => (Side::Shared, field),
+                };
+                Some(BuiltinEvent { name: field.split(' ').next()?, side })
+            })
+            .collect()
+    })
+}
+
+/// The event `name` when FiveM itself triggers it.
+pub fn builtin_event(name: &str) -> Option<BuiltinEvent> {
+    builtin_events().iter().find(|event| event.name == name).copied()
+}
+
 pub struct KnownImport {
     pub path: &'static str,
     pub globals: &'static [&'static str],
@@ -226,12 +352,76 @@ mod tests {
     fn looks_up_natives() {
         let native = native("GetEntityCoords").unwrap();
         assert_eq!(native.returns().collect::<Vec<_>>(), ["vector3"]);
-        assert_eq!(native.params().next(), Some(("entity", "Entity")));
+        assert_eq!(native.params().next(), Some(("entity", "Entity", false)));
         assert_eq!(super::native("GetPlayerIdentifier").unwrap().side, Side::Server);
         assert!(super::native("NotARealNative").is_none());
         assert!(native_count() > 6000);
     }
 
+    #[test]
+    fn server_natives_keep_their_own_signature() {
+        let vehicles = native("GetAllVehicles").unwrap();
+        assert_eq!(vehicles.on(Some(Side::Client)).returns().collect::<Vec<_>>(), ["integer", "integer"]);
+        assert_eq!(vehicles.on(None).returns().collect::<Vec<_>>(), ["integer", "integer"]);
+        let server = vehicles.on(Some(Side::Server));
+        assert_eq!(server.returns().collect::<Vec<_>>(), ["Vehicle[]"]);
+        assert_eq!((server.side, server.namespace, server.hash), (Side::Server, "CFX", "0x332169F5"));
+        let weapon = native("GetCurrentPedWeapon").unwrap().on(Some(Side::Server));
+        assert_eq!(weapon.signature(), "function GetCurrentPedWeapon(ped: Ped): Hash");
+        // A native without a server signature of its own is the same everywhere.
+        let health = native("GetEntityHealth").unwrap();
+        assert_eq!(health.on(Some(Side::Server)).hash, health.hash);
+    }
+
+    #[test]
+    fn pointers_follow_the_lua_wrappers() {
+        let shape = |name: &str| {
+            let native = native(name).unwrap();
+            (native.params().collect::<Vec<_>>(), native.returns().collect::<Vec<_>>())
+        };
+        // Two pointers: both are returned, neither is an argument.
+        assert_eq!(shape("GetGroupSize"), (vec![("groupID", "integer", false)], vec!["integer", "integer"]));
+        // The one pointer, last: an optional initial value, and returned.
+        assert_eq!(
+            shape("GetEntityPlayerIsFreeAimingAt"),
+            (vec![("player", "Player", false), ("entity", "Entity", true)], vec!["boolean", "Entity"])
+        );
+        // A native that releases the handle it is given needs one.
+        assert_eq!(shape("DeleteEntity"), (vec![("entity", "Entity", false)], vec!["Entity"]));
+        let server = native("DeleteEntity").unwrap().on(Some(Side::Server));
+        assert_eq!(server.returns().count(), 0, "the server native takes the handle itself");
+        // The wrapper reads an Any* as an integer, and passes none it does not take.
+        assert_eq!(shape("DataarrayGetInt"), (vec![("arrayIndex", "integer", false)], vec!["integer", "integer"]));
+        assert_eq!(
+            native("GetEntityPlayerIsFreeAimingAt").unwrap().signature(),
+            "function GetEntityPlayerIsFreeAimingAt(player: Player, entity?: Entity): boolean, Entity"
+        );
+    }
+
+    #[test]
+    fn callback_types_name_function_parameters() {
+        for (name, param, ty) in CALLBACK_TYPES {
+            let native = native(name).unwrap_or_else(|| panic!("{name} is no native"));
+            let declared = native.params.split(',').filter_map(|p| p.split_once(':')).find(|(n, _)| n == param);
+            assert_eq!(declared.map(|(_, ty)| ty), Some("function"), "{name}({param})");
+            assert!(native.params().any(|(n, t, _)| n == *param && t == *ty));
+        }
+    }
+
+    #[test]
+    fn return_types_name_tables_that_natives_return() {
+        for (name, ty) in RETURN_TYPES {
+            let native = native(name).unwrap_or_else(|| panic!("{name} is no native"));
+            let returns = native.server.map_or(native.returns, |(_, server, _)| server);
+            assert!(
+                native.returns.split(',').chain(returns.split(',')).any(|r| r == "table"),
+                "{name} returns no table"
+            );
+            let side = native.server.map(|_| Side::Server);
+            assert!(native.on(side).returns().any(|r| r == *ty), "{name}");
+        }
+    }
+
     #[test]
     fn natives_are_sorted_for_binary_search() {
         let names: Vec<&str> = natives().map(|n| n.name).collect();
@@ -246,6 +436,21 @@ mod tests {
         assert!(!is_hash_native_name("Foo"));
     }
 
+    #[test]
+    fn builtin_events_keep_their_side() {
+        let side = |name| builtin_event(name).map(|event| event.side);
+        assert_eq!(side("onResourceStop"), Some(Side::Shared));
+        assert_eq!(side("onClientResourceStart"), Some(Side::Client));
+        assert_eq!(side("playerDropped"), Some(Side::Server));
+        assert_eq!(side("rconCommand"), Some(Side::Server));
+        for name in ["explosionEvent", "fireEvent", "serverEntityCreated", "onPedDeath", "stopNetworkSyncedSceneEvent"]
+        {
+            assert_eq!(side(name), Some(Side::Server), "{name}");
+        }
+        assert_eq!(side("setModel"), None, "the fields of other classes are no events");
+        assert_eq!(builtin_events().len(), 46);
+    }
+
     #[cfg(feature = "docs")]
     #[test]
     fn docs_are_unescaped() {