@tilua-types/roblox 9.0.0 → 10.0.1

package/README.md

@@ -71,6 +71,74 @@ caller's `xpcall`. `coroutine` is not wrapped either: `coroutine.resume`
 returning `false, err` is part of how it behaves. Outside a bundle, nothing is
 wrapped.
 
+## A game through Rojo
+
+In a Rojo project as `rojo init` makes it:
+
+```bash
+npm i -D @tilua/compiler @tilua-types/roblox
+npx tilua init          # src is what you write, out what Rojo reads
+npx tilua --watch       # beside `rojo serve`
+```
+
+```
+src/                     what you write
+  shared/Greet.tilua
+  shared/Hello.luau      Luau written by hand
+out/                     the build's: compiled, copied, and nothing else
+  shared/Greet.luau
+  shared/Hello.luau
+  shared/_tilua.luau     the runtime
+```
+
+`tilua init` writes `{ "types": ["roblox"], "output": "files", "rootDir": "src", "outDir": "out" }`
+— `src` being the folder the project's `$path`s share — points those `$path`s
+at `out`, and adds `/out` to `.gitignore`. Each build makes `out` a mirror of
+`src`: every `.tilua` compiled, every other file (Luau written by hand,
+`.meta.json`, models) copied as it is, every folder there even when empty,
+and nothing else — what is in `out` and no longer in `src` is removed.
+`--watch` does that again on every change under `src`, and `rojo serve`
+syncs it into Studio. A project set up the older way, each `.luau` compiled
+beside its `.tilua`, is moved over by `tilua init` the same way, and the first
+build removes those `.luau` from `src`.
+
+The tree the project builds is typed as you write, read straight off
+`default.project.json` and the files in `src` — nothing else to run:
+`game.Workspace.Baseplate` is the project's part, `script` is the file's own
+instance (`script.Parent` its folder), and `FindFirstChild("")` and
+`WaitForChild("")` offer the children's names.
+
+Where each file goes is read off the Rojo project — `default.project.json`
+beside the config, or the one `"rojo"` names — and the files require each
+other by the paths the game knows them by:
+
+```jsonc
+// default.project.json, as `rojo init` writes it
+{
+  "name": "game",
+  "tree": {
+    "$className": "DataModel",
+    "ReplicatedStorage": { "Shared": { "$path": "src/shared" } },
+    "ServerScriptService": { "Server": { "$path": "src/server" } },
+    "StarterPlayer": { "StarterPlayerScripts": { "Client": { "$path": "src/client" } } }
+  }
+}
+```
+
+| in `src` | in the game | requires |
+|---|---|---|
+| `server/main.server.tilua` | `ServerScriptService.Server.main`, a Script | `./data` beside it; `@game/ReplicatedStorage/Shared/net` across services |
+| `client/hud.client.tilua` | a LocalScript under `StarterPlayerScripts` | waits for `game.Loaded` first: a `require` by path does not wait for what it names to replicate |
+| `shared/net/init.tilua` | `ReplicatedStorage.Shared.net`, the folder as a ModuleScript | `@self/remote` below it, `./util` beside it |
+
+- The runtime every file requires, `_tilua.luau`, goes in the folder the
+  project puts in `ReplicatedStorage`, where the server and the clients both
+  reach it. A project with none there is an error.
+- `.server` and `.client` files are scripts the game runs, not modules:
+  importing one is an error, and what one returns is not typed.
+- `import "./net"` finds `net/init.tilua`, as Rojo reads `net/init.luau`.
+- A file the project puts nowhere is a warning: Rojo would leave it out.
+
 ## Where it comes from
 
 `index.d.tilua` is generated. Don't edit it by hand; change
@@ -90,11 +158,11 @@ luau-lsp is MIT licensed. Its notice is in
 <!-- compatibility:start -->
 ## Compatibility
 
-`@tilua-types/roblox@9.0.0` works with these tilua packages. *Released with* is the
+`@tilua-types/roblox@10.0.1` works with these tilua packages. *Released with* is the
 version it was built and tested against.
 
 | Package | Range | Released with | |
 | --- | --- | --- | --- |
-| `@tilua-types/luau` | `^8.0.0` | 8.0.0 | dependency |
-| `@tilua/parser` | `^8.0.0` | 8.0.0 | peer |
+| `@tilua-types/luau` | `^9.0.1` | 9.0.1 | dependency |
+| `@tilua/parser` | `^9.0.0` | 9.0.1 | peer |
 <!-- compatibility:end -->

package/lowering.mjs

@@ -26,11 +26,17 @@
  *
  * `print`, `error` and the console are the compiler's own: Lua's standard
  * library is built into tilua.
+ *
+ * With `"output": "files"`, where each file ends up in the game is read off
+ * the project's Rojo project (`rojo`, `default.project.json` unless set), and
+ * the files require each other by the paths the game knows them by (see
+ * rojo.mjs).
  */
 import { readFileSync } from "node:fs"
 import { dirname, join } from "node:path"
 import { fileURLToPath } from "node:url"
 import { hasMembers, isInstanceOf, luauString, returnsTuple } from "@tilua/parser"
+import { rojoLayout } from "./rojo.mjs"
 
 /** @typedef {import("@tilua/parser").LoweringPlugin} LoweringPlugin */
 
@@ -58,6 +64,9 @@ const SIGNAL_MEMBERS = ["Connect", "Once", "Wait"]
 /** Luau globals answering several values, which the runtime gathers. */
 const GATHERED_GLOBALS = new Set(["string.unpack", "coroutine.close", "utf8.codepoint", "utf8.codes", "utf8.graphemes"])
 
+/** The Rojo project a config that names none has. */
+const DEFAULT_PROJECT = "default.project.json"
+
 /** @type {LoweringPlugin} */
 const plugin = {
     runtime: { roblox },
@@ -83,6 +92,11 @@ const plugin = {
         if (GATHERED_GLOBALS.has(name)) return `${use("roblox")}.globals.${name.replace(".", "_")}`
         return undefined
     },
+
+    files(layout) {
+        const project = typeof layout.options.rojo === "string" ? layout.options.rojo : DEFAULT_PROJECT
+        return rojoLayout(layout, project, project !== DEFAULT_PROJECT)
+    },
 }
 
 export default plugin

package/package.json

@@ -1,24 +1,32 @@
 {
   "name": "@tilua-types/roblox",
-  "version": "9.0.0",
+  "version": "10.0.1",
   "description": "Luau and the whole Roblox API as tilua types: every class, enum, data type, service and global",
   "license": "ISC",
   "files": [
     "index.d.tilua",
     "lowering.mjs",
+    "rojo.mjs",
     "runtime",
     "README.md",
     "THIRD_PARTY_NOTICES.md"
   ],
   "tilua": {
     "types": "index.d.tilua",
-    "lowering": "lowering.mjs"
+    "lowering": "lowering.mjs",
+    "options": {
+      "rojo": {
+        "type": "string",
+        "default": "default.project.json",
+        "description": "With \"output\": \"files\", the Rojo project that says where each file goes in the game, from the config's folder."
+      }
+    }
   },
   "dependencies": {
-    "@tilua-types/luau": "^8.0.0"
+    "@tilua-types/luau": "^9.0.1"
   },
   "peerDependencies": {
-    "@tilua/parser": "^8.0.0"
+    "@tilua/parser": "^9.0.0"
   },
   "keywords": [
     "tilua",

package/rojo.mjs

@@ -0,0 +1,133 @@
+// @ts-check
+/**
+ * Where the files of `"output": "files"` end up in the game, read off a Rojo
+ * project, and how they reach each other there.
+ *
+ * A Rojo project maps folders to places in the game — `dist/shared` to
+ * `ReplicatedStorage.Shared`, `dist/server` to `ServerScriptService` — so a
+ * file's place is its folder's, and its own name below that:
+ *
+ *     dist/shared/util.luau         ReplicatedStorage.Shared.util      a ModuleScript
+ *     dist/server/main.server.luau  ServerScriptService.main           a Script
+ *     dist/client/hud.client.luau   StarterPlayer.StarterPlayerScripts.hud   a LocalScript
+ *     dist/shared/net/init.luau     ReplicatedStorage.Shared.net       the folder, as a ModuleScript
+ *
+ * Within one service a file requires another by the path between them
+ * (`./util`, `../net`); across services, from the top: `@game/ReplicatedStorage/Shared/util`.
+ * The runtime every file requires goes where both the server and the
+ * clients can reach it: the folder the project puts in ReplicatedStorage.
+ *
+ * A script the game runs (`.server`, `.client`) is not a module, so nothing
+ * may import one; a LocalScript waits for the game to load before it
+ * requires anything, since a `require` by path does not wait for what it
+ * names to replicate.
+ */
+import { readFileSync } from "node:fs"
+import { dirname, relative, resolve, sep } from "node:path"
+
+/** `.server.luau` and the rest: a script the game runs, not a module. */
+const SCRIPT = /\.(server|client|plugin|local|legacy)\.luau?$/
+const CLIENT = /\.client\.luau?$/
+
+/** Where the runtime goes, best first: somewhere every client reaches. */
+const SHARED_SERVICES = ["ReplicatedStorage", "ReplicatedFirst"]
+
+/**
+ * @typedef {{ folder: string, place: string[] }} Mapping
+ *   A `$path` of the project — absolute — and the place in the game it fills.
+ */
+
+/**
+ * The layout of the files of `layout` under the Rojo project `projectPath`
+ * (from the config's folder), or `undefined` when there is none to read.
+ * @param {import("@tilua/parser").FilesLayout} layout
+ * @param {string} projectPath
+ * @param {boolean} named whether the config named the project, rather than its default
+ * @returns {import("@tilua/parser").FilesAnswer}
+ */
+export function rojoLayout(layout, projectPath, named) {
+    const file = resolve(layout.directory, projectPath)
+    /** @type {import("@tilua/parser").FilesAnswer["problems"] & object[]} */
+    const problems = []
+    const script = (/** @type {string} */ path) => SCRIPT.test(path)
+    const prelude = (/** @type {string} */ path) => (CLIENT.test(path) ? "if not game:IsLoaded() then game.Loaded:Wait() end" : undefined)
+
+    let project
+    try {
+        project = JSON.parse(readFileSync(file, "utf8"))
+    } catch (error) {
+        // Without a project the files stay where they are written, side by side.
+        if (named) problems.push({ message: `Cannot read the Rojo project '${projectPath}': ${/** @type {Error} */ (error).message}` })
+        return { script, prelude, problems }
+    }
+    const tree = project && typeof project === "object" ? project.tree : undefined
+    if (!tree || typeof tree !== "object") {
+        problems.push({ file, message: "The Rojo project has no 'tree'" })
+        return { script, prelude, problems }
+    }
+
+    /** @type {Mapping[]} */
+    const mappings = []
+    const walk = (/** @type {Record<string, unknown>} */ node, /** @type {string[]} */ place) => {
+        const path = typeof node.$path === "string" ? node.$path
+            : node.$path && typeof node.$path === "object" ? /** @type {{ optional?: unknown }} */ (node.$path).optional : undefined
+        if (typeof path === "string") mappings.push({ folder: resolve(dirname(file), path), place })
+        for (const [name, child] of Object.entries(node)) {
+            if (!name.startsWith("$") && child && typeof child === "object") walk(/** @type {Record<string, unknown>} */ (child), [...place, name])
+        }
+    }
+    walk(tree, [])
+    // The deepest mapping a file is under is the one that places it.
+    mappings.sort((a, b) => b.folder.length - a.folder.length)
+
+    /** @param {string} path */
+    const place = path => {
+        for (const mapping of mappings) {
+            const below = relative(mapping.folder, path)
+            if (below === "") return mapping.place
+            if (below.startsWith("..") || resolve(mapping.folder, below) !== resolve(path)) continue
+            const parts = below.split(sep)
+            const last = parts.pop() ?? ""
+            const name = last.replace(SCRIPT, "").replace(/\.luau?$/, "")
+            // `init.luau` is the folder it is in.
+            return name === "init" ? [...mapping.place, ...parts] : [...mapping.place, ...parts, name]
+        }
+        return undefined
+    }
+
+    for (const path of layout.files) {
+        if (!place(path)) {
+            problems.push({
+                file: path, severity: "warning",
+                message: `Nothing in the Rojo project '${projectPath}' puts this file in the game`,
+            })
+        }
+    }
+
+    // The runtime: in the folder the project puts in a service every client
+    // reaches, so the server's files and the clients' all require one.
+    let runtime
+    for (const service of SHARED_SERVICES) {
+        const mapping = mappings.find(m => m.place[0] === service && isInside(layout.outDir, m.folder) && !/\.luau?$/.test(m.folder))
+        if (mapping) {
+            runtime = resolve(mapping.folder, "_tilua.luau")
+            break
+        }
+    }
+    if (runtime === undefined) {
+        problems.push({
+            message: `Nothing in the Rojo project '${projectPath}' puts a folder of outDir in ReplicatedStorage, `
+                + "where the runtime every file requires has to be for the server and the clients to reach it",
+        })
+    }
+
+    // `@game` names the DataModel; a project that is not one is a single tree.
+    const root = tree.$className === "DataModel" ? "@game" : undefined
+    return { place, root, runtime, script, prelude, problems }
+}
+
+/** Is `path` `folder`, or under it? */
+function isInside(/** @type {string} */ folder, /** @type {string} */ path) {
+    const below = relative(folder, path)
+    return below === "" || (!below.startsWith("..") && resolve(folder, below) === resolve(path))
+}