luaut-parser 1.0.0

package/dist/roblox.d.luaut

@@ -0,0 +1,503 @@
+-- Roblox ambient definitions, written in luaut.
+--
+-- Layered on top of `luau.d.luaut`, which carries the core language (including
+-- the `type` / `typeof` overloads that drive narrowing). This file adds the
+-- Roblox data types, the Instance class hierarchy, and the globals.
+--
+-- Pass both: `analyzeTypes(program, scopes, { libs: defaultLibs })`.
+--
+-- Nothing here is special-cased in the analyzer. Three declaration-driven
+-- mechanisms do all the work, and you extend them the same way:
+--
+--   * `typeof(v) == "Vector3"` narrows because `typeof` has one overload per
+--     result string, returning that string as a *literal* type.
+--   * `inst:IsA("Model")` narrows because `IsA` is one generic `self is
+--     ClassMap[K]` guard over the class map, and `K` infers the string
+--     literal that was passed.
+--   * `Instance.new("Part")` and `game:GetService("ReplicatedStorage")` are
+--     the same trick: a generic signature indexing a map of names to types.
+--     Services are also plain properties, so `game.ReplicatedStorage` works.
+--
+-- Hand-written baseline, not the full API dump — extend it, or generate your
+-- own from the Roblox API dump and parse it the same way.
+
+-- ============================================================
+-- Data types (value types, not Instances)
+-- ============================================================
+
+type Vector3 = {
+    X: number, Y: number, Z: number,
+    Magnitude: number, Unit: Vector3,
+    Cross: (self: Vector3, other: Vector3) -> Vector3,
+    Dot: (self: Vector3, other: Vector3) -> number,
+    Lerp: (self: Vector3, goal: Vector3, alpha: number) -> Vector3,
+}
+type Vector2 = { X: number, Y: number, Magnitude: number, Unit: Vector2 }
+type Color3 = { R: number, G: number, B: number }
+type CFrame = {
+    Position: Vector3, LookVector: Vector3, RightVector: Vector3, UpVector: Vector3,
+    Inverse: (self: CFrame) -> CFrame,
+}
+type UDim = { Scale: number, Offset: number }
+type UDim2 = { X: UDim, Y: UDim }
+type NumberRange = { Min: number, Max: number }
+type Rect = { Min: Vector2, Max: Vector2, Width: number, Height: number }
+type Ray = { Origin: Vector3, Direction: Vector3, Unit: Ray }
+type Region3 = { CFrame: CFrame, Size: Vector3 }
+type BrickColor = { Number: number, Name: string, Color: Color3 }
+type EnumItem = { Name: string, Value: number, EnumType: unknown }
+type TweenInfo = { Time: number, DelayTime: number, RepeatCount: number, Reverses: boolean }
+type Random = {
+    NextNumber: (self: Random, min?: number, max?: number) -> number,
+    NextInteger: (self: Random, min: number, max: number) -> number,
+    Clone: (self: Random) -> Random,
+}
+type DateTime = {
+    UnixTimestamp: number,
+    UnixTimestampMillis: number,
+    ToIsoDate: (self: DateTime) -> string,
+}
+
+type RBXScriptConnection = { Connected: boolean, Disconnect: (self: RBXScriptConnection) -> () }
+type RBXScriptSignal = {
+    Connect: (self: RBXScriptSignal, fn: (...unknown) -> ()) -> RBXScriptConnection,
+    Once: (self: RBXScriptSignal, fn: (...unknown) -> ()) -> RBXScriptConnection,
+    Wait: (self: RBXScriptSignal) -> ...unknown,
+}
+
+-- ============================================================
+-- Instance
+-- ------------------------------------------------------------
+-- luaut's type system is structural, so a subclass is written as the parent
+-- intersected with what it adds: `type Model = PVInstance & { ... }`.
+-- ============================================================
+
+type Instance = {
+    Name: string,
+    ClassName: string,
+    Parent: Instance | nil,
+    Archivable: boolean,
+    ChildAdded: RBXScriptSignal,
+    ChildRemoved: RBXScriptSignal,
+    AncestryChanged: RBXScriptSignal,
+    Destroying: RBXScriptSignal,
+
+    -- One generic guard instead of one overload per class: `K` is inferred as
+    -- the string *literal* that was passed (its constraint is a union of
+    -- literals, so it is not widened to `string`), and `ClassMap[K]` looks the
+    -- class up. Adding a class to `ClassMap` is all it takes.
+    IsA: <K extends keyof ClassMap>(self: Instance, className: K) -> self is ClassMap[K],
+
+    FindFirstChild: (self: Instance, name: string, recursive?: boolean) -> Instance | nil,
+    FindFirstChildOfClass: (self: Instance, className: string) -> Instance | nil,
+    FindFirstChildWhichIsA: (self: Instance, className: string) -> Instance | nil,
+    FindFirstAncestor: (self: Instance, name: string) -> Instance | nil,
+    FindFirstAncestorOfClass: (self: Instance, className: string) -> Instance | nil,
+    WaitForChild: (self: Instance, name: string, timeout?: number) -> Instance,
+    GetChildren: (self: Instance) -> Instance[],
+    GetDescendants: (self: Instance) -> Instance[],
+    GetFullName: (self: Instance) -> string,
+    IsDescendantOf: (self: Instance, ancestor: Instance) -> boolean,
+    IsAncestorOf: (self: Instance, descendant: Instance) -> boolean,
+    Clone: (self: Instance) -> Instance,
+    Destroy: (self: Instance) -> (),
+    ClearAllChildren: (self: Instance) -> (),
+    GetAttribute: (self: Instance, name: string) -> unknown,
+    SetAttribute: (self: Instance, name: string, value: unknown) -> (),
+    GetPropertyChangedSignal: (self: Instance, property: string) -> RBXScriptSignal,
+}
+
+-- ============================================================
+-- The class hierarchy
+-- ============================================================
+
+type PVInstance = Instance & {
+    GetPivot: (self: PVInstance) -> CFrame,
+    PivotTo: (self: PVInstance, target: CFrame) -> (),
+}
+
+type Model = PVInstance & {
+    PrimaryPart: BasePart | nil,
+    WorldPivot: CFrame,
+    GetBoundingBox: (self: Model) -> (CFrame, Vector3),
+    GetExtentsSize: (self: Model) -> Vector3,
+    MoveTo: (self: Model, position: Vector3) -> (),
+}
+
+type BasePart = PVInstance & {
+    Position: Vector3,
+    Size: Vector3,
+    CFrame: CFrame,
+    Anchored: boolean,
+    CanCollide: boolean,
+    CanTouch: boolean,
+    Transparency: number,
+    Color: Color3,
+    BrickColor: BrickColor,
+    Material: EnumItem,
+    Massless: boolean,
+    AssemblyLinearVelocity: Vector3,
+    Touched: RBXScriptSignal,
+    TouchEnded: RBXScriptSignal,
+    ApplyImpulse: (self: BasePart, impulse: Vector3) -> (),
+    GetTouchingParts: (self: BasePart) -> BasePart[],
+}
+
+type Part = BasePart & { Shape: EnumItem }
+type MeshPart = BasePart & { MeshId: string, TextureID: string }
+type UnionOperation = BasePart & { UsePartColor: boolean }
+type SpawnLocation = BasePart & { TeamColor: BrickColor, Neutral: boolean }
+
+type Folder = Instance & {}
+type Configuration = Instance & {}
+type Attachment = Instance & { Position: Vector3, WorldPosition: Vector3, WorldCFrame: CFrame }
+
+type Humanoid = Instance & {
+    Health: number,
+    MaxHealth: number,
+    WalkSpeed: number,
+    JumpPower: number,
+    MoveDirection: Vector3,
+    RootPart: BasePart | nil,
+    Died: RBXScriptSignal,
+    HealthChanged: RBXScriptSignal,
+    TakeDamage: (self: Humanoid, amount: number) -> (),
+    MoveTo: (self: Humanoid, location: Vector3, part?: BasePart) -> (),
+    LoadAnimation: (self: Humanoid, animation: Instance) -> Instance,
+}
+
+type Tool = Model & { Grip: CFrame, RequiresHandle: boolean, Activated: RBXScriptSignal }
+type Accessory = Model & { AttachmentPoint: CFrame }
+
+type Player = Instance & {
+    UserId: number,
+    DisplayName: string,
+    Character: Model | nil,
+    Team: Instance | nil,
+    CharacterAdded: RBXScriptSignal,
+    CharacterRemoving: RBXScriptSignal,
+    Kick: (self: Player, message?: string) -> (),
+    LoadCharacter: (self: Player) -> (),
+}
+
+type LuaSourceContainer = Instance & { Source: string }
+type Script = LuaSourceContainer & { Enabled: boolean, RunContext: EnumItem }
+type LocalScript = LuaSourceContainer & { Enabled: boolean }
+type ModuleScript = LuaSourceContainer & {}
+
+type Sound = Instance & {
+    SoundId: string,
+    Volume: number,
+    Playing: boolean,
+    Looped: boolean,
+    TimePosition: number,
+    Ended: RBXScriptSignal,
+    Play: (self: Sound) -> (),
+    Stop: (self: Sound) -> (),
+}
+
+type Camera = Instance & {
+    CFrame: CFrame,
+    FieldOfView: number,
+    CameraSubject: Instance | nil,
+    ViewportSize: Vector2,
+}
+
+type GuiObject = Instance & {
+    Visible: boolean,
+    Position: UDim2,
+    Size: UDim2,
+    AnchorPoint: Vector2,
+    ZIndex: number,
+    BackgroundColor3: Color3,
+    BackgroundTransparency: number,
+    InputBegan: RBXScriptSignal,
+    InputEnded: RBXScriptSignal,
+}
+type Frame = GuiObject & {}
+type TextLabel = GuiObject & { Text: string, TextColor3: Color3, TextSize: number, Font: EnumItem }
+type TextButton = GuiObject & { Text: string, TextColor3: Color3, Activated: RBXScriptSignal }
+type TextBox = GuiObject & { Text: string, PlaceholderText: string, FocusLost: RBXScriptSignal }
+type ImageLabel = GuiObject & { Image: string, ImageColor3: Color3 }
+type ImageButton = GuiObject & { Image: string, Activated: RBXScriptSignal }
+type ScrollingFrame = GuiObject & { CanvasSize: UDim2, CanvasPosition: Vector2 }
+type ScreenGui = Instance & { Enabled: boolean, ResetOnSpawn: boolean, DisplayOrder: number }
+type BillboardGui = Instance & { Adornee: Instance | nil, Size: UDim2, AlwaysOnTop: boolean }
+
+type RemoteEvent = Instance & {
+    OnServerEvent: RBXScriptSignal,
+    OnClientEvent: RBXScriptSignal,
+    FireServer: (self: RemoteEvent, ...unknown) -> (),
+    FireClient: (self: RemoteEvent, player: Player, ...unknown) -> (),
+    FireAllClients: (self: RemoteEvent, ...unknown) -> (),
+}
+type RemoteFunction = Instance & {
+    InvokeServer: (self: RemoteFunction, ...unknown) -> ...unknown,
+    InvokeClient: (self: RemoteFunction, player: Player, ...unknown) -> ...unknown,
+}
+type BindableEvent = Instance & { Event: RBXScriptSignal, Fire: (self: BindableEvent, ...unknown) -> () }
+
+-- ============================================================
+-- Services
+-- ============================================================
+
+type Workspace = Model & {
+    CurrentCamera: Camera | nil,
+    Gravity: number,
+    Raycast: (self: Workspace, origin: Vector3, direction: Vector3, params?: unknown) -> unknown,
+}
+type Players = Instance & {
+    LocalPlayer: Player | nil,
+    PlayerAdded: RBXScriptSignal,
+    PlayerRemoving: RBXScriptSignal,
+    GetPlayers: (self: Players) -> Player[],
+    GetPlayerFromCharacter: (self: Players, character: Model) -> Player | nil,
+}
+type RunService = Instance & {
+    Heartbeat: RBXScriptSignal,
+    RenderStepped: RBXScriptSignal,
+    Stepped: RBXScriptSignal,
+    IsClient: (self: RunService) -> boolean,
+    IsServer: (self: RunService) -> boolean,
+    IsStudio: (self: RunService) -> boolean,
+}
+type UserInputService = Instance & {
+    InputBegan: RBXScriptSignal,
+    InputEnded: RBXScriptSignal,
+    TouchEnabled: boolean,
+    KeyboardEnabled: boolean,
+    IsKeyDown: (self: UserInputService, key: EnumItem) -> boolean,
+}
+type TweenService = Instance & {
+    Create: (self: TweenService, instance: Instance, info: TweenInfo, goals: { [string]: unknown }) -> Instance,
+}
+type Lighting = Instance & { Ambient: Color3, Brightness: number, ClockTime: number, FogEnd: number }
+type ReplicatedStorage = Instance & {}
+type ReplicatedFirst = Instance & {}
+type TeleportService = Instance & {
+    Teleport: (self: TeleportService, placeId: number, player?: Player) -> (),
+}
+type MarketplaceService = Instance & {
+    PromptPurchase: (self: MarketplaceService, player: Player, assetId: number) -> (),
+    UserOwnsGamePassAsync: (self: MarketplaceService, userId: number, gamePassId: number) -> boolean,
+}
+type PhysicsService = Instance & {
+    RegisterCollisionGroup: (self: PhysicsService, name: string) -> (),
+    CollisionGroupSetCollidable: (self: PhysicsService, a: string, b: string, collidable: boolean) -> (),
+}
+type ContextActionService = Instance & {
+    BindAction: (self: ContextActionService, name: string, fn: (...unknown) -> (), touchButton: boolean, ...unknown) -> (),
+    UnbindAction: (self: ContextActionService, name: string) -> (),
+}
+type ServerStorage = Instance & {}
+type ServerScriptService = Instance & {}
+type StarterGui = Instance & {}
+type StarterPlayer = Instance & {}
+type Teams = Instance & {}
+type SoundService = Instance & {}
+type Debris = Instance & { AddItem: (self: Debris, item: Instance, lifetime?: number) -> () }
+type CollectionService = Instance & {
+    AddTag: (self: CollectionService, instance: Instance, tag: string) -> (),
+    HasTag: (self: CollectionService, instance: Instance, tag: string) -> boolean,
+    GetTagged: (self: CollectionService, tag: string) -> Instance[],
+    GetInstanceAddedSignal: (self: CollectionService, tag: string) -> RBXScriptSignal,
+}
+type HttpService = Instance & {
+    JSONEncode: (self: HttpService, value: unknown) -> string,
+    JSONDecode: (self: HttpService, json: string) -> unknown,
+    GenerateGUID: (self: HttpService, wrapInCurlyBraces?: boolean) -> string,
+}
+type DataStoreService = Instance & {
+    GetDataStore: (self: DataStoreService, name: string, scope?: string) -> Instance,
+}
+
+-- Services are a map of their own, so the same map serves both spellings:
+-- intersecting it into `DataModel` gives `game.ReplicatedStorage`, and
+-- indexing it gives `game:GetService("ReplicatedStorage")`.
+type Services = {
+    Workspace: Workspace,
+    Players: Players,
+    RunService: RunService,
+    UserInputService: UserInputService,
+    TweenService: TweenService,
+    Lighting: Lighting,
+    ReplicatedStorage: ReplicatedStorage,
+    ReplicatedFirst: ReplicatedFirst,
+    ServerStorage: ServerStorage,
+    ServerScriptService: ServerScriptService,
+    StarterGui: StarterGui,
+    StarterPlayer: StarterPlayer,
+    Teams: Teams,
+    SoundService: SoundService,
+    Debris: Debris,
+    CollectionService: CollectionService,
+    HttpService: HttpService,
+    DataStoreService: DataStoreService,
+    TeleportService: TeleportService,
+    MarketplaceService: MarketplaceService,
+    PhysicsService: PhysicsService,
+    ContextActionService: ContextActionService,
+}
+
+type DataModel = Instance & Services & {
+    PlaceId: number,
+    JobId: string,
+    BindToClose: (self: DataModel, callback: () -> ()) -> (),
+
+    -- `K` is constrained to the service names, which is both what makes the
+    -- argument infer as a string *literal* rather than widening to `string`,
+    -- and what catches a typo.
+    GetService: <K extends keyof Services>(self: DataModel, name: K) -> Services[K],
+}
+
+
+
+-- ============================================================
+-- The class map
+-- ------------------------------------------------------------
+-- One place that names every class. `IsA` and `Instance.new` are both a
+-- single generic signature over it, so adding a class is adding one line here
+-- plus its type above.
+-- ============================================================
+
+type ClassMap = {
+    Instance: Instance,
+    PVInstance: PVInstance,
+    Model: Model,
+    BasePart: BasePart,
+    Part: Part,
+    MeshPart: MeshPart,
+    UnionOperation: UnionOperation,
+    SpawnLocation: SpawnLocation,
+    Folder: Folder,
+    Configuration: Configuration,
+    Attachment: Attachment,
+    Humanoid: Humanoid,
+    Tool: Tool,
+    Accessory: Accessory,
+    Player: Player,
+    LuaSourceContainer: LuaSourceContainer,
+    Script: Script,
+    LocalScript: LocalScript,
+    ModuleScript: ModuleScript,
+    Sound: Sound,
+    Camera: Camera,
+    GuiObject: GuiObject,
+    Frame: Frame,
+    TextLabel: TextLabel,
+    TextButton: TextButton,
+    TextBox: TextBox,
+    ImageLabel: ImageLabel,
+    ImageButton: ImageButton,
+    ScrollingFrame: ScrollingFrame,
+    ScreenGui: ScreenGui,
+    BillboardGui: BillboardGui,
+    RemoteEvent: RemoteEvent,
+    RemoteFunction: RemoteFunction,
+    BindableEvent: BindableEvent,
+}
+
+-- The abstract classes cannot be constructed, so `Instance.new` works over
+-- everything else — written with `Omit` rather than a second hand-kept list.
+type CreatableClassMap = Omit<ClassMap,
+    "Instance" | "PVInstance" | "BasePart" | "GuiObject" | "LuaSourceContainer">
+
+-- ============================================================
+-- `typeof()` for the Roblox data types
+-- ------------------------------------------------------------
+-- These extend the base overloads declared in `luau.d.luaut`. `typeof` reports
+-- a Roblox data type by name rather than as `userdata`; every Instance reports
+-- as `"Instance"`.
+-- ============================================================
+
+declare function typeof(value: Vector3): "Vector3"
+declare function typeof(value: Vector2): "Vector2"
+declare function typeof(value: CFrame): "CFrame"
+declare function typeof(value: Color3): "Color3"
+declare function typeof(value: UDim): "UDim"
+declare function typeof(value: UDim2): "UDim2"
+declare function typeof(value: NumberRange): "NumberRange"
+declare function typeof(value: Rect): "Rect"
+declare function typeof(value: Ray): "Ray"
+declare function typeof(value: Region3): "Region3"
+declare function typeof(value: BrickColor): "BrickColor"
+declare function typeof(value: EnumItem): "EnumItem"
+declare function typeof(value: TweenInfo): "TweenInfo"
+declare function typeof(value: Random): "Random"
+declare function typeof(value: DateTime): "DateTime"
+declare function typeof(value: RBXScriptSignal): "RBXScriptSignal"
+declare function typeof(value: RBXScriptConnection): "RBXScriptConnection"
+declare function typeof(value: Instance): "Instance"
+
+-- ============================================================
+-- Globals
+-- ============================================================
+
+declare game: DataModel
+declare workspace: Workspace
+declare script: LuaSourceContainer
+declare shared: { [string]: unknown }
+
+-- `Instance.new(className)` returns the class it names, by the same
+-- one-overload-per-class trick as `IsA`.
+declare Instance: {
+    new: <K extends keyof CreatableClassMap>(className: K, parent?: Instance) -> CreatableClassMap[K],
+}
+
+declare Vector3: {
+    new: (x?: number, y?: number, z?: number) -> Vector3,
+    zero: Vector3,
+    one: Vector3,
+    xAxis: Vector3,
+    yAxis: Vector3,
+    zAxis: Vector3,
+}
+declare Vector2: { new: (x?: number, y?: number) -> Vector2, zero: Vector2, one: Vector2 }
+declare Color3: {
+    new: (r?: number, g?: number, b?: number) -> Color3,
+    fromRGB: (r?: number, g?: number, b?: number) -> Color3,
+    fromHSV: (h: number, s: number, v: number) -> Color3,
+}
+declare CFrame: {
+    new: (x?: number, y?: number, z?: number) -> CFrame,
+    lookAt: (at: Vector3, target: Vector3, up?: Vector3) -> CFrame,
+    identity: CFrame,
+}
+declare UDim: { new: (scale?: number, offset?: number) -> UDim }
+declare UDim2: {
+    new: (xScale?: number, xOffset?: number, yScale?: number, yOffset?: number) -> UDim2,
+    fromScale: (x: number, y: number) -> UDim2,
+    fromOffset: (x: number, y: number) -> UDim2,
+}
+declare NumberRange: { new: (min: number, max?: number) -> NumberRange }
+declare Rect: { new: (min: Vector2, max: Vector2) -> Rect }
+declare Ray: { new: (origin: Vector3, direction: Vector3) -> Ray }
+declare Region3: { new: (min: Vector3, max: Vector3) -> Region3 }
+declare BrickColor: { new: (name: string) -> BrickColor, random: () -> BrickColor }
+declare TweenInfo: {
+    new: (time?: number, easingStyle?: EnumItem, easingDirection?: EnumItem,
+          repeatCount?: number, reverses?: boolean, delayTime?: number) -> TweenInfo,
+}
+declare Random: { new: (seed?: number) -> Random }
+declare DateTime: {
+    now: () -> DateTime,
+    fromUnixTimestamp: (unixTimestamp: number) -> DateTime,
+}
+
+declare Enum: { [string]: { [string]: EnumItem } }
+
+declare task: {
+    wait: (seconds?: number) -> number,
+    spawn: (fn: (...unknown) -> (), ...unknown) -> thread,
+    defer: (fn: (...unknown) -> (), ...unknown) -> thread,
+    delay: (seconds: number, fn: (...unknown) -> (), ...unknown) -> thread,
+    cancel: (thread: thread) -> (),
+    synchronize: () -> (),
+    desynchronize: () -> (),
+}
+
+declare function tick(): number
+declare function time(): number
+declare function wait(seconds?: number): number
+declare function delay(seconds: number, fn: () -> ()): ()
+declare function spawn(fn: () -> ()): ()

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "luaut-parser",
+  "version": "1.0.0",
+  "description": "luau parser for roblox",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Uav3537/luaut-parser.git"
+  },
+  "exports": {
+    ".": {
+      "types": {
+        "require": "./dist/index.d.cts",
+        "import": "./dist/index.d.ts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "test": "tsx scripts/test.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.0",
+    "typescript": "^5.0.4"
+  }
+}