comment out global functions that don't act right in a definitions file

Author: tapple

generated/secondlife.d.luau

@@ -230,27 +230,27 @@ export type PrimParamsSetterType = typeof(
 )
 
 
-declare function assert<T>(value: T?, message: string?): T -- magic type
+-- declare function assert<T>(value: T?, message: string?): T -- magic type
 declare function dangerouslyexecuterequiredmodule(f: (...any) -> ...any): ...any
 declare function error(obj: any, level: number?): never
 declare function gcinfo(): number
 declare getfenv: nil
-declare function getmetatable(obj: any): {[any]: any}?
+-- declare function getmetatable(obj: any): {[any]: any}? -- builtin
 declare function ipairs<V>(t: {V}): (({V}, number) -> (number?, V), {V}, number)
 declare loadstring: nil
 declare function newproxy(mt: boolean?): any
-declare function next<K, V>(t: {[K]: V}, i: K?): (K, V)?
-declare function pairs<K, V>(t: {[K]: V}): (({[K], V}, K) -> (K?, V), {[K], V}, K)
+-- declare function next<K, V>(t: {[K]: V}, i: K?): (K, V)? -- builtin
+-- declare function pairs<K, V>(t: {[K]: V}): (({[K], V}, K) -> (K?, V), {[K], V}, K) -- builtin
 declare function pcall<A..., R...>(f: (A...) -> R..., A...): (boolean, R...)
 declare function print(...any): ()
 declare function rawequal(a: any, b: any): boolean
 declare function rawget<K, V>(t: {[K]: V}, k: K): V?
 declare function rawlen<K, V>(t: {[K]: V} | string): number
 declare function rawset<K, V>(t: {[K]: V}, k: K, v: V): {[K]: V}
-declare function require(target: string): any -- magic type
-declare function select(i: string | number, ...any): any -- magic type
+-- declare function require(target: string): any -- magic type
+-- declare function select(i: string | number, ...any): any -- magic type
 declare setfenv: nil
-declare function setmetatable(t: { [any]: any }, mt: { [any]: any }?): () -- magic type
+-- declare function setmetatable(t: { [any]: any }, mt: { [any]: any }?): () -- builtin, magic type
 declare function tonumber(s: string, base: number?): number?
 declare function toquaternion(val: string? | quaternion): quaternion?
 declare function torotation(val: string? | quaternion): quaternion?
@@ -472,23 +472,23 @@ declare quaternion: ((x: number, y: number, z: number, s: number) -> quaternion)
 ---------------------------
 
 declare string: {
-  byte: (s: string, i: number?, j: number?) -> ...number,
-  char: (...number) -> string,
-  find: (s: string, pattern: string, init: number?, plain: boolean?) -> (number?, number?, ...string), -- magic type
-  format: (formatstring: string, ...any) -> string, -- magic type
-  gmatch: (s: string, pattern: string) -> () -> ...string, -- magic type
-  gsub: (s: string, pattern: string, repl: string | { [string]: string } | (...string) -> string, maxn: number?) -> (string, number),
-  len: (s: string) -> number,
-  lower: (s: string) -> string,
-  match: (s: string, pattern: string, init: number?) -> ...string, -- magic type
-  pack: (fmt: string, ...any) -> string,
-  packsize: (fmt: string) -> number,
-  rep: (s: string, n: number) -> string,
-  reverse: (s: string) -> string,
-  split: (s: string, separator: string?) -> {string},
-  sub: (s: string, i: number, j: number?) -> string,
-  unpack: (fmt: string, s: string, init: number?) -> ...any,
-  upper: (s: string) -> string,
+  byte: (s: string, i: number?, j: number?) -> ...number, -- builtin
+  char: (...number) -> string, -- builtin
+  find: (s: string, pattern: string, init: number?, plain: boolean?) -> (number?, number?, ...string), -- builtin, magic type
+  format: (formatstring: string, ...any) -> string, -- builtin, magic type
+  gmatch: (s: string, pattern: string) -> () -> ...string, -- builtin, magic type
+  gsub: (s: string, pattern: string, repl: string | { [string]: string } | (...string) -> string, maxn: number?) -> (string, number), -- builtin
+  len: (s: string) -> number, -- builtin
+  lower: (s: string) -> string, -- builtin
+  match: (s: string, pattern: string, init: number?) -> ...string, -- builtin, magic type
+  pack: (fmt: string, ...any) -> string, -- builtin
+  packsize: (fmt: string) -> number, -- builtin
+  rep: (s: string, n: number) -> string, -- builtin
+  reverse: (s: string) -> string, -- builtin
+  split: (s: string, separator: string?) -> {string}, -- builtin
+  sub: (s: string, i: number, j: number?) -> string, -- builtin
+  unpack: (fmt: string, s: string, init: number?) -> ...any, -- builtin
+  upper: (s: string) -> string, -- builtin
 }
 
 

lsl_definitions/generators/slua.py

@@ -54,6 +54,8 @@ def gen_luau_lsp_defs(definitions: LSLDefinitions, slua_definitions: SLuaDefinit
     for func in slua_definitions.functions:
         if func.private or func.local_only:
             continue
+        if not func.typechecker_flags.fully_defined:
+            defs.write("-- ")
         defs.write("declare ")
         func.write_luau_global_def(defs)
     for module in sorted(slua_definitions.modules, key=lambda x: x.name):

lsl_definitions/slua.py

@@ -71,6 +71,30 @@ def to_luau_def(self) -> str:
             return f"{self.name}: {self.type}"
 
 
+@dataclasses.dataclass
+class SLuaTypecheckerFlags:
+    """Flags specific to the internals of luau-analyze and luau-lsp."""
+
+    builtin: bool = False
+    """This function is defined in BuiltinDefinitions.cpp, rather than EmbeddedBuiltinDefinitions.cpp."""
+    magic: bool = False
+    """The typechecker has custom logic for this function."""
+
+    @property
+    def fully_defined(self) -> bool:
+        """True if this function is fully defined and won't cause issues for the typechecker."""
+        return not self.builtin and not self.magic
+
+    @property
+    def comment_string(self) -> str:
+        comments = []
+        if self.builtin:
+            comments.append("builtin")
+        if self.magic:
+            comments.append("magic type")
+        return " -- " + ", ".join(comments) if comments else ""
+
+
 @dataclasses.dataclass
 class SLuaFunctionBase(abc.ABC):
     name: str = ""
@@ -111,8 +135,10 @@ class SLuaFunction(SLuaFunctionBase):
     must_use: bool = False
     """Emit a warning if the return value is not used.
     See https://kampfkarren.github.io/selene/usage/std.html#must_use."""
-    magic_type: bool = False
-    """The typechecker has custom logic for this function."""
+    typechecker_flags: SLuaTypecheckerFlags = dataclasses.field(
+        default_factory=SLuaTypecheckerFlags
+    )
+    """Flags specific to the internals of luau-analyze and luau-lsp."""
     overloads: List[SLuaFunctionOverload] = dataclasses.field(default_factory=list)
 
     @property
@@ -163,8 +189,7 @@ def write_luau_global_def(self, f: TextIO, indent: int = 0) -> None:
             f.write(self.type_parameters_string)
             f.write(self.parameters_string)
             f.write(f": {self.return_type}")
-            if self.magic_type:
-                f.write(" -- magic type")
+            f.write(self.typechecker_flags.comment_string)
             f.write("\n")
 
     def write_luau_table_def(self, f: TextIO, indent: int = 0, suffix=",") -> None:
@@ -181,8 +206,7 @@ def write_luau_table_def(self, f: TextIO, indent: int = 0, suffix=",") -> None:
                 f.write(overload.type_def_string)
             f.write(")")
         f.write(suffix)
-        if self.magic_type:
-            f.write(" -- magic type")
+        f.write(self.typechecker_flags.comment_string)
         f.write("\n")
 
 
@@ -769,7 +793,7 @@ def _validate_function(
                 local_only=data.get("local-only", False),
                 slua_removed=data.get("slua-removed", False),
                 must_use=data.get("must-use", False),
-                magic_type=data.get("magic-type", False),
+                typechecker_flags=SLuaTypecheckerFlags(**data.get("typechecker", {})),
             )
             self._validate_identifier(func.name)
             self._validate_scope(func.name, scope)

slua_definitions.yaml

@@ -408,7 +408,7 @@ functions:
     comment: The object to get the metatable for.
     type: any
   return-type: "{[any]: any}?"
-  typechecker: {builtin: true}
+  typechecker: {builtin: true}  # builtin due to FFlag::LuauSolverV2
   fastcall: true
 - name: graphheap
   comment: Writes the contents of heap to the given file in JSON format.
@@ -460,7 +460,7 @@ functions:
     comment: Optional key to start traversal after.
     type: K?
   return-type: (K, V)?
-  typechecker: {builtin: true}
+  typechecker: {builtin: true}  # builtin due to FFlag::LuauStorePolarityInline
 - name: pairs
   comment: Returns an iterator for all key-value pairs in the table.
   type-parameters: [K, V]
@@ -469,7 +469,7 @@ functions:
     comment: The table to iterate over.
     type: "{[K]: V}"
   return-type: "(({[K], V}, K) -> (K?, V), {[K], V}, K)"
-  typechecker: {builtin: true}
+  typechecker: {builtin: true}  # builtin due to FFlag::LuauStorePolarityInline
 - name: pcall
   comment: Calls function f with parameters args, returning success and function results or an error.
   type-parameters: [A..., R...]
@@ -575,7 +575,7 @@ functions:
     type: "{ [any]: any }?"
   return-type: ()
   fastcall: true
-  typechecker: {builtin: true, magic: true}
+  typechecker: {builtin: true, magic: true}  # builtin due to FFlag::LuauSolverV2
 - name: tonumber
   comment: Converts the input string to a number in the specified base.
   parameters: