rbxts-transform-luau 1.0.0

package/README.md

@@ -0,0 +1,154 @@
+# rbxts-transform-luau
+
+A [roblox-ts](https://roblox-ts.com) / [rotor](https://github.com/roblox-ts/rotor) TypeScript transformer that makes compiled Luau output idiomatic — cleaning up noise, organizing the preamble, injecting Luau directives, annotating types, and converting JSDoc comments.
+
+## What it does
+
+### Luau directives
+
+Injects `--!strict` and/or `--!optimize N` at the top of every file.
+
+```luau
+--!native
+--!optimize 2
+--!strict
+```
+
+### Preamble organization
+
+Sorts the top of every file into labeled sections: directives → services → runtime → imports. Makes the compiled output readable at a glance.
+
+```luau
+--!optimize 2
+--!strict
+
+-- Compiled with roblox-ts v3.0.0
+
+-- Services
+const _ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+-- Runtime
+const TS = require(_ReplicatedStorage:WaitForChild("include"):WaitForChild("RuntimeLib"))
+
+-- Imports
+const fns; if false then fns = require(...) else fns = TS.import(...) :: any end
+```
+
+### `const` promotion
+
+Locals and imports that are never reassigned anywhere in the file are promoted to `const`, allowing the Luau native compiler to make stronger assumptions.
+
+```luau
+-- Before
+local N = 100000
+local function compute()
+    local scale = 0.5
+    local result = scale * N
+local base; if false then base = require(...) else base = TS.import(...) :: any end
+
+-- After
+const N = 100000
+local function compute()
+    const scale = 0.5
+    const result = scale * N
+local base; if false then base = require(...) else base = TS.import(...) :: any end
+```
+
+Only variables initialized inline (`local name = value`) are eligible. Imports use a deferred-assignment workaround (`local name; ... name = ...`) that requires `local` in Luau, so they are left alone. Variables that are mutated anywhere in the file (`i += 1`, reassignment, etc.) are also correctly left as `local`.
+
+### Luau type annotations
+
+Uses the TypeScript type checker to inject Luau type annotations into every function signature — covering inferred types that have no explicit annotation in source.
+
+```typescript
+// Input — types inferred by TypeScript, not explicitly written
+export function dot(a: Vector3, b: Vector3) {
+    return a.X * b.X + a.Y * b.Y + a.Z * b.Z
+}
+export function lerp(a: number, b: number, t: number) {
+    return a + (b - a) * t
+}
+```
+
+```luau
+-- Output — type checker resolved them; luau-lsp now sees them too
+local function dot(a: Vector3, b: Vector3): number
+local function lerp(a: number, b: number, t: number): number
+```
+
+Supports: primitives (`number`, `string`, `boolean`), Roblox value types (`Vector3`, `CFrame`, `UDim2`, etc.), arrays (`{T}`), and `LuaTuple<[T, U]>` → multi-return `(T, U)`.
+
+Set `annotate: false` to disable.
+
+### TS.import type hints
+
+Wraps `TS.import` calls with a dead-code `require` branch so luau-lsp can infer the module's return type — zero runtime cost.
+
+```luau
+-- luau-lsp gets full autocomplete and types through the require branch
+const fns; if false then fns = require(_ReplicatedStorage.shared.fns) else fns = TS.import(script, _ReplicatedStorage, "shared", "fns") :: any end
+```
+
+### JSDoc → Luau doc comments
+
+TypeScript JSDoc (`@param`, `@returns`, `@deprecated`) is converted to luau-lsp doc comment format with inferred Luau types. Works with both roblox-ts and rotor.
+
+```typescript
+/**
+ * Computes the dot product of two vectors.
+ * @param a First vector.
+ * @param b Second vector.
+ * @returns Scalar result.
+ */
+export function dot(a: Vector3, b: Vector3): number { ... }
+
+/** @deprecated Use dot() instead. */
+export function oldDot(a: Vector3, b: Vector3): number { ... }
+```
+
+```luau
+--- Computes the dot product of two vectors.
+--- @param a Vector3 First vector.
+--- @param b Vector3 Second vector.
+--- @return number Scalar result.
+local function dot(a: Vector3, b: Vector3): number
+
+--- @deprecated Use dot() instead.
+local function oldDot(a: Vector3, b: Vector3): number
+```
+
+### Comment cleanup
+
+Strips useless block comments (`--[[ ]]`) that compilers emit for non-function declarations where no useful information can be extracted.
+
+## Installation
+
+```bash
+npm install --save-dev rbxts-transform-luau
+```
+
+## Setup
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "transform": "rbxts-transform-luau",
+        "strict": true,
+        "optimize": 2,
+        "annotate": true
+      }
+    ]
+  }
+}
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `strict` | `boolean` | `true` | Inject `--!strict` at the top of every file |
+| `optimize` | `false \| 0 \| 1 \| 2` | `false` | Inject `--!optimize N` (`false` disables, `0`/`1`/`2` set the level) |
+| `annotate` | `boolean` | `true` | Inject Luau type annotations using the TypeScript type checker |
+| `verbose` | `boolean` | `false` | Log per-file processing info to the console |

package/out/config.d.ts

@@ -0,0 +1,6 @@
+export interface PluginConfig {
+    strict?: boolean;
+    optimize?: false | 0 | 1 | 2;
+    annotate?: boolean;
+    verbose?: boolean;
+}

package/out/config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/index.d.ts

@@ -0,0 +1,4 @@
+import ts from "typescript";
+import type { PluginConfig } from "./config";
+export type { PluginConfig };
+export default function (program: ts.Program, config?: PluginConfig): ts.TransformerFactory<ts.SourceFile>;

package/out/index.js

@@ -0,0 +1,257 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+const typescript_1 = __importDefault(require("typescript"));
+const path = __importStar(require("path"));
+const format_1 = require("./passes/format");
+const LUAU_TYPE = {
+    number: "number",
+    string: "string",
+    boolean: "boolean",
+    void: "()",
+    Vector3: "Vector3",
+    Vector2: "Vector2",
+    Vector2int16: "Vector2int16",
+    Vector3int16: "Vector3int16",
+    CFrame: "CFrame",
+    UDim: "UDim",
+    UDim2: "UDim2",
+    Color3: "Color3",
+    BrickColor: "BrickColor",
+    TweenInfo: "TweenInfo",
+    NumberRange: "NumberRange",
+    NumberSequence: "NumberSequence",
+    ColorSequence: "ColorSequence",
+    Rect: "Rect",
+    Region3: "Region3",
+    Ray: "Ray",
+    buffer: "buffer",
+    Instance: "Instance",
+    BasePart: "BasePart",
+    Part: "Part",
+    Model: "Model",
+    Player: "Player",
+    Camera: "Camera",
+    Workspace: "Workspace",
+    RunService: "RunService",
+    Players: "Players",
+};
+function mapTypeNode(typeNode) {
+    if (typescript_1.default.isTypeReferenceNode(typeNode)) {
+        const name = typescript_1.default.isIdentifier(typeNode.typeName) ? typeNode.typeName.text : null;
+        if (!name)
+            return null;
+        if (LUAU_TYPE[name])
+            return LUAU_TYPE[name];
+        if ((name === "Array" || name === "ReadonlyArray") && typeNode.typeArguments?.length === 1) {
+            const inner = mapTypeNode(typeNode.typeArguments[0]);
+            return inner ? `{${inner}}` : "{any}";
+        }
+        if (name === "LuaTuple" && typeNode.typeArguments?.length === 1) {
+            const arg = typeNode.typeArguments[0];
+            if (typescript_1.default.isTupleTypeNode(arg)) {
+                const elements = arg.elements
+                    .map(e => {
+                    const el = "type" in e ? e.type : e;
+                    return mapTypeNode(el);
+                })
+                    .filter((t) => t !== null);
+                if (elements.length > 0)
+                    return `(${elements.join(", ")})`;
+            }
+        }
+        return null;
+    }
+    if (typescript_1.default.isArrayTypeNode(typeNode)) {
+        const inner = mapTypeNode(typeNode.elementType);
+        return inner ? `{${inner}}` : "{any}";
+    }
+    const kw = {
+        [typescript_1.default.SyntaxKind.NumberKeyword]: "number",
+        [typescript_1.default.SyntaxKind.StringKeyword]: "string",
+        [typescript_1.default.SyntaxKind.BooleanKeyword]: "boolean",
+        [typescript_1.default.SyntaxKind.VoidKeyword]: "()",
+    };
+    if (typeNode.kind in kw)
+        return kw[typeNode.kind];
+    return null;
+}
+function luauTypeForParam(checker, node) {
+    if (node.type) {
+        const mapped = mapTypeNode(node.type);
+        if (mapped)
+            return mapped;
+    }
+    const name = checker.typeToString(checker.getTypeAtLocation(node));
+    return LUAU_TYPE[name] ?? null;
+}
+function luauTypeForReturn(checker, node) {
+    if (node.type) {
+        const mapped = mapTypeNode(node.type);
+        if (mapped)
+            return mapped;
+    }
+    const sig = checker.getSignatureFromDeclaration(node);
+    if (!sig)
+        return null;
+    const ret = checker.getReturnTypeOfSignature(sig);
+    const name = checker.typeToString(ret);
+    return LUAU_TYPE[name] ?? null;
+}
+function collectTypes(checker, sourceFile) {
+    const types = new Map();
+    function visit(node) {
+        if (typescript_1.default.isFunctionDeclaration(node) && node.name) {
+            const params = node.parameters.map(p => luauTypeForParam(checker, p));
+            const ret = luauTypeForReturn(checker, node);
+            if (params.some(p => p !== null) || ret !== null) {
+                types.set(node.name.text, { params, ret });
+            }
+        }
+        typescript_1.default.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return types;
+}
+function outPathForSource(sourceFile, program) {
+    const options = program.getCompilerOptions();
+    const outDir = options.outDir;
+    if (!outDir)
+        return null;
+    const rootDir = options.rootDir ?? commonRoot(program.getRootFileNames());
+    if (!rootDir)
+        return null;
+    const rel = path.relative(rootDir, sourceFile.fileName);
+    if (rel.startsWith(".."))
+        return null;
+    const dir = path.dirname(rel);
+    const base = path.basename(rel).replace(/\.tsx?$/, "");
+    const renamedBase = base.replace(/^index(?=$|\.)/, "init");
+    return path.join(outDir, dir, `${renamedBase}.luau`);
+}
+function commonRoot(files) {
+    if (files.length === 0)
+        return undefined;
+    const parts = files[0].split(path.sep);
+    let root = parts.slice(0, parts.length - 1);
+    for (const f of files.slice(1)) {
+        const fp = f.split(path.sep);
+        let i = 0;
+        while (i < root.length && i < fp.length - 1 && root[i] === fp[i])
+            i++;
+        root = root.slice(0, i);
+    }
+    return root.join(path.sep) || undefined;
+}
+const pending = new Map();
+let finalizeRegistered = false;
+function flushPending() {
+    for (const [, meta] of pending) {
+        try {
+            (0, format_1.formatFile)(meta.outPath, meta.strict, meta.optimizeLevel, meta.sidecar, meta.annotate ? meta.types : new Map());
+        }
+        catch {
+            // silently skip files that fail — they stay as-is
+        }
+    }
+    pending.clear();
+}
+function registerFinalizer() {
+    if (finalizeRegistered)
+        return;
+    finalizeRegistered = true;
+    process.on("exit", flushPending);
+}
+function jsDocText(comment) {
+    if (!comment)
+        return "";
+    if (typeof comment === "string")
+        return comment.trim().replace(/^—\s*/, "");
+    const raw = comment
+        .map(c => ("text" in c ? c.text : ""))
+        .join("");
+    return raw.trim().replace(/^—\s*/, "");
+}
+function collectJsDoc(ts, sourceFile) {
+    const sidecar = new Map();
+    function visit(node) {
+        if (ts.isFunctionDeclaration(node) && node.name) {
+            const jsDocs = node.jsDoc;
+            if (jsDocs && jsDocs.length > 0) {
+                const doc = jsDocs[jsDocs.length - 1];
+                const rawDesc = jsDocText(doc.comment);
+                const desc = rawDesc.split("\n").map(l => l.trim()).filter(Boolean);
+                const params = new Map();
+                let returns = "";
+                let deprecated;
+                for (const tag of doc.tags ?? []) {
+                    if (ts.isJSDocParameterTag(tag)) {
+                        const name = ts.isIdentifier(tag.name) ? tag.name.text : "";
+                        if (name)
+                            params.set(name, jsDocText(tag.comment).trim());
+                    }
+                    else if (ts.isJSDocReturnTag(tag)) {
+                        returns = jsDocText(tag.comment).trim();
+                    }
+                    else if (ts.isJSDocDeprecatedTag(tag)) {
+                        deprecated = jsDocText(tag.comment).trim();
+                    }
+                }
+                if (desc.length > 0 || params.size > 0 || returns || deprecated !== undefined) {
+                    sidecar.set(node.name.text, { desc, params, returns, deprecated });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return sidecar;
+}
+function default_1(program, config = {}) {
+    const { strict = true, optimize = false, annotate = true, verbose = false } = config;
+    const optimizeLevel = optimize === false ? false : [0, 1, 2].includes(optimize) ? optimize : 2;
+    // Watch mode: flush the previous run's pending files before starting this one.
+    flushPending();
+    registerFinalizer();
+    const outDir = program.getCompilerOptions().outDir;
+    const checker = annotate ? program.getTypeChecker() : null;
+    return (_ctx) => (sourceFile) => {
+        const outPath = outPathForSource(sourceFile, program);
+        if (outPath) {
+            const sidecar = collectJsDoc(typescript_1.default, sourceFile);
+            const types = checker ? collectTypes(checker, sourceFile) : new Map();
+            pending.set(outPath, { outPath, strict, optimizeLevel, annotate, verbose, sidecar, types });
+            if (verbose) {
+                const rel = outDir ? path.relative(outDir, outPath) : outPath;
+                console.log(`luau: ${rel}`);
+            }
+        }
+        return sourceFile;
+    };
+}

package/out/passes/format.d.ts

@@ -0,0 +1,23 @@
+export type FnTypes = {
+    params: Array<string | null>;
+    ret: string | null;
+};
+export declare function injectTypeAnnotations(src: string, types: Map<string, FnTypes>): string;
+export declare function stripUselessBlockComments(src: string): string;
+export declare function fixBlockCommentOpeners(src: string): string;
+export declare function organizePreamble(src: string): string;
+export declare function hoistGetService(src: string): string;
+export declare function promoteConstIfUnmutated(src: string, name: string): string;
+export declare function promoteConsts(src: string): string;
+export declare function addSpacing(src: string): string;
+export declare function castTsImports(src: string): string;
+export type FnDoc = {
+    desc: string[];
+    params: Map<string, string>;
+    returns: string;
+    deprecated?: string;
+};
+export declare function injectJsDocFromSidecar(src: string, sidecar: Map<string, FnDoc>): string;
+export declare function convertJsDocComments(src: string): string;
+export declare function applyDirectives(src: string, strict: boolean, optimizeLevel: false | 0 | 1 | 2): string;
+export declare function formatFile(luauPath: string, strict: boolean, optimizeLevel: false | 0 | 1 | 2, sidecar?: Map<string, FnDoc>, types?: Map<string, FnTypes>): void;

package/out/passes/format.js

@@ -0,0 +1,571 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.injectTypeAnnotations = injectTypeAnnotations;
+exports.stripUselessBlockComments = stripUselessBlockComments;
+exports.fixBlockCommentOpeners = fixBlockCommentOpeners;
+exports.organizePreamble = organizePreamble;
+exports.hoistGetService = hoistGetService;
+exports.promoteConstIfUnmutated = promoteConstIfUnmutated;
+exports.promoteConsts = promoteConsts;
+exports.addSpacing = addSpacing;
+exports.castTsImports = castTsImports;
+exports.injectJsDocFromSidecar = injectJsDocFromSidecar;
+exports.convertJsDocComments = convertJsDocComments;
+exports.applyDirectives = applyDirectives;
+exports.formatFile = formatFile;
+const fs = __importStar(require("fs"));
+function byLengthDesc(a, b) {
+    return b.length - a.length;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function injectTypeAnnotations(src, types) {
+    if (types.size === 0)
+        return src;
+    for (const [fnName, ann] of types) {
+        if (ann.params.every(p => p === null) && ann.ret === null)
+            continue;
+        const re = new RegExp(`(local function ${escapeRegex(fnName)}\\()([^)]*)(\\.\\.\\.)?(\\))(?:\\s*:\\s*[^\\r\\n]+)?`);
+        src = src.replace(re, (_m, open, rawParams, vararg, close) => {
+            const names = rawParams.split(",").map((s) => s.trim()).filter(Boolean);
+            const annotated = names.map((name, i) => {
+                const bare = name.split(":")[0].trim();
+                const typ = ann.params[i];
+                return typ ? `${bare}: ${typ}` : bare;
+            });
+            if (vararg)
+                annotated.push("...");
+            return `${open}${annotated.join(", ")}${close}${ann.ret ? `: ${ann.ret}` : ""}`;
+        });
+    }
+    return src;
+}
+function stripUselessBlockComments(src) {
+    const NOISE_TAGS = new Set([
+        "@param", "@returns", "@return", "@throws", "@deprecated",
+        "@private", "@protected", "@public", "@hidden", "@ignore", "@internal",
+    ]);
+    function isNoiseLine(raw) {
+        const t = raw.trim().replace(/^\*+\s*/, "");
+        if (t === "")
+            return true;
+        const tag = t.split(/\s/)[0].toLowerCase();
+        return NOISE_TAGS.has(tag);
+    }
+    const lines = src.split("\n");
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const trimmed = lines[i].trim();
+        if (trimmed === "--[[") {
+            const openerIdx = i;
+            const body = [];
+            i++;
+            while (i < lines.length && lines[i].trim() !== "]]") {
+                body.push(lines[i]);
+                i++;
+            }
+            const closerIdx = i;
+            const isAllNoise = body.every(isNoiseLine);
+            if (isAllNoise) {
+                i++;
+                if (lines[i]?.trim() === "")
+                    i++;
+                continue;
+            }
+            out.push(lines[openerIdx]);
+            for (const bl of body)
+                out.push(bl);
+            if (closerIdx < lines.length)
+                out.push(lines[closerIdx]);
+            i = closerIdx + 1;
+            continue;
+        }
+        out.push(lines[i]);
+        i++;
+    }
+    return out.join("\n");
+}
+function fixBlockCommentOpeners(src) {
+    const lines = src.split("\n");
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const trimmed = lines[i].trim();
+        if (trimmed === "--[[") {
+            out.push(lines[i]);
+            i++;
+            while (i < lines.length) {
+                const t = lines[i].trim();
+                if (t === "" && lines[i + 1]?.trim() === "]]") {
+                    i++;
+                    continue;
+                }
+                out.push(lines[i]);
+                if (t === "]]") {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        if (trimmed.startsWith("*")) {
+            let j = i;
+            while (j < lines.length && lines[j].trim().startsWith("*"))
+                j++;
+            const hasTrailingBlank = j < lines.length && lines[j].trim() === "" && lines[j + 1]?.trim() === "]]";
+            if (hasTrailingBlank)
+                j++;
+            const hasCloser = lines[j]?.trim() === "]]";
+            if (hasCloser) {
+                out.push("--[[");
+                const bodyStart = lines[i]?.trim() === "*" ? i + 1 : i;
+                const bodyEnd = hasTrailingBlank ? j - 1 : j;
+                for (let k = bodyStart; k < bodyEnd; k++)
+                    out.push(lines[k]);
+                out.push(lines[j]);
+                i = j + 1;
+                continue;
+            }
+        }
+        out.push(lines[i]);
+        i++;
+    }
+    return out.join("\n");
+}
+function organizePreamble(src) {
+    const lines = src.split("\n");
+    let i = 0;
+    const shebang = [];
+    const compiledLines = [];
+    const services = [];
+    const runtime = [];
+    const imports = [];
+    const bindings = [];
+    while (i < lines.length) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed === "") {
+            i++;
+            continue;
+        }
+        if (/^--\[\[/.test(trimmed)) {
+            break;
+        }
+        else if (/^--!/.test(line)) {
+            shebang.push(line);
+            i++;
+        }
+        else if (/^-- Compiled/.test(line)) {
+            compiledLines.push(line);
+            i++;
+        }
+        else if (/^--/.test(line)) {
+            i++;
+        }
+        else if (/^(?:local|const) \w+ = game:GetService\(/.test(line)) {
+            const svcVar = line.match(/^(?:local|const) (\w+) = game:GetService\(/)[1];
+            const duplicate = services.some(s => s.match(/^(?:local|const) (\w+) = game:GetService\(/)[1] === svcVar);
+            if (!duplicate)
+                services.push(line);
+            i++;
+        }
+        else if (/^(?:local|const) \w+ = require\(/.test(line)) {
+            runtime.push(line);
+            i++;
+        }
+        else if (/^(?:local|const) \w+ = TS\.import\(/.test(line)) {
+            imports.push(line);
+            i++;
+        }
+        else if (/^TS\.import\(/.test(line)) {
+            imports.push(line);
+            i++;
+        }
+        else if (/^(?:local|const) \w+ = \w+[\.\[]/.test(line) && !/^(?:local|const) function/.test(line)) {
+            bindings.push(line);
+            i++;
+        }
+        else {
+            break;
+        }
+    }
+    shebang.sort(byLengthDesc);
+    services.sort(byLengthDesc);
+    imports.sort(byLengthDesc);
+    bindings.sort(byLengthDesc);
+    const out = [...shebang];
+    if (compiledLines.length > 0)
+        out.push("", ...compiledLines);
+    if (services.length > 0)
+        out.push("", "-- Services", ...services);
+    if (runtime.length > 0)
+        out.push("", "-- Runtime", ...runtime);
+    if (imports.length > 0)
+        out.push("", "-- Imports", ...imports);
+    if (bindings.length > 0)
+        out.push("", "-- Bindings", ...bindings);
+    if (i < lines.length)
+        out.push("", ...lines.slice(i));
+    return out.join("\n");
+}
+function hoistGetService(src) {
+    const re = /game:GetService\("([^"]+)"\)/g;
+    const counts = new Map();
+    for (const m of src.matchAll(re)) {
+        counts.set(m[1], (counts.get(m[1]) ?? 0) + 1);
+    }
+    const toHoist = [...counts.entries()]
+        .filter(([, n]) => n >= 2)
+        .map(([svc]) => svc)
+        .filter(svc => !new RegExp(`(?:^|\\n)(?:local|const) _${svc} = game:GetService\\(`).test(src));
+    if (toHoist.length === 0)
+        return src;
+    const decls = toHoist.map(svc => `local _${svc} = game:GetService("${svc}")`).join("\n");
+    for (const svc of toHoist) {
+        src = src.split(`game:GetService("${svc}")`).join(`_${svc}`);
+    }
+    const insertAt = src.search(/^(?!--[!\s]|--\s*Compiled)/m);
+    if (insertAt === -1)
+        return decls + "\n" + src;
+    return src.slice(0, insertAt) + decls + "\n" + src.slice(insertAt);
+}
+function promoteConstIfUnmutated(src, name) {
+    const lines = src.split("\n");
+    const escaped = escapeRegex(name);
+    const declRe = new RegExp(`^(\\t*)local (${escaped}) =`);
+    const reassignRe = new RegExp(`^\\t*${escaped}\\s*(?:\\+|-|\\*|/{1,2}|%|\\^|\\.\\.)?=(?!=)`);
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(declRe);
+        if (!m)
+            continue;
+        const declIndent = m[1].length;
+        let mutated = false;
+        for (let j = i + 1; j < lines.length; j++) {
+            const line = lines[j];
+            const trimmed = line.replace(/^\t*/, "");
+            if (trimmed === "")
+                continue;
+            const indent = line.length - trimmed.length;
+            if (indent < declIndent)
+                break;
+            if (reassignRe.test(line)) {
+                mutated = true;
+                break;
+            }
+        }
+        if (!mutated)
+            lines[i] = lines[i].replace(declRe, `$1const $2 =`);
+    }
+    return lines.join("\n");
+}
+function promoteConsts(src) {
+    const lines = src.split("\n");
+    // Only `local name =` (value assigned at declaration) — never `local name;`
+    const declRe = /^(\t*)local ([A-Za-z_][A-Za-z0-9_]*) =/;
+    const toPromote = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(declRe);
+        if (!m)
+            continue;
+        const name = m[2];
+        // Any reassignment to this name on lines AFTER the declaration line
+        const mutRe = new RegExp(`(?:^|\\t)${escapeRegex(name)}\\s*(?:[+\\-*/%^]|\\.\\.|/{1,2})?=(?!=)`);
+        let mutated = false;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (mutRe.test(lines[j])) {
+                mutated = true;
+                break;
+            }
+        }
+        if (!mutated)
+            toPromote.push(i);
+    }
+    if (toPromote.length === 0)
+        return src;
+    for (const i of toPromote) {
+        lines[i] = lines[i].replace(/^(\t*)local /, "$1const ");
+    }
+    return lines.join("\n");
+}
+function addSpacing(src) {
+    const lines = src.split("\n");
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        const prevTrimmed = (out.length > 0 ? out[out.length - 1] : "").trim();
+        const alreadyBlank = prevTrimmed === "";
+        if (!alreadyBlank) {
+            if (/^local function /.test(trimmed) && prevTrimmed !== "]]" && !/^---/.test(prevTrimmed)) {
+                out.push("");
+            }
+            else if (/^return\b/.test(trimmed) &&
+                !/\b(then|do|repeat)$/.test(prevTrimmed) &&
+                !/function\s*\([^)]*\)$/.test(prevTrimmed) &&
+                !/^local function /.test(prevTrimmed)) {
+                out.push("");
+            }
+            else if (/^(do\b|while |for |if |repeat\b)/.test(trimmed) &&
+                /^(local |const )/.test(prevTrimmed)) {
+                out.push("");
+            }
+            else if (/^local /.test(trimmed) && /^const /.test(prevTrimmed)) {
+                out.push("");
+            }
+        }
+        out.push(line);
+        if (trimmed === "end") {
+            const next = lines[i + 1]?.trim() ?? "";
+            if (next !== "" && !/^(end\b|else\b|elseif\b|until\b)/.test(next)) {
+                out.push("");
+            }
+        }
+    }
+    return out.join("\n");
+}
+function castTsImports(src) {
+    // Replace TS.import calls with an if/else where the dead branch does a direct
+    // require() so luau-lsp can infer the module type without typeof(require(...))
+    // (which is broken per luau-lang#1844 and luau-lsp#1057).
+    //
+    // Generated pattern:
+    //   local opt
+    //   if false then
+    //       opt = require(game:GetService("ReplicatedStorage").shared.fns)
+    //   else
+    //       opt = TS.import(script, _ReplicatedStorage, "shared", "fns") :: any
+    //   end
+    //
+    // Type checker unifies both branches; runtime always takes the else path.
+    // Match full declaration lines: [const|local] name = TS.import(...)
+    const re = /^([ \t]*)(?:(local|const) (\w+) = )?(TS\.import\(script,[ \t]*([^,")\s][^,)]*?)((?:,[ \t]*"[^"]*")*)\))$/gm;
+    return src.replace(re, (_, indent, kw, varName, call, base, childrenRaw) => {
+        const children = [];
+        for (const m of childrenRaw.matchAll(/"([^"]*)"/g))
+            children.push(m[1]);
+        const path = base.trim() + children.map(c => /^[A-Za-z_][A-Za-z0-9_]*$/.test(c) ? `.${c}` : `["${c}"]`).join("");
+        if (!varName) {
+            // Bare TS.import call (side-effect only) — leave as-is
+            return _;
+        }
+        return `${indent}local ${varName}; if false then ${varName} = require(${path}) else ${varName} = ${call} :: any end`;
+    });
+}
+function injectJsDocFromSidecar(src, sidecar) {
+    if (sidecar.size === 0)
+        return src;
+    const lines = src.split("\n");
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const funcMatch = lines[i].match(/^(\t*)local function (\w+)\(([^)]*)\)(?::\s*(.+))?$/);
+        if (funcMatch) {
+            const name = funcMatch[2];
+            const doc = sidecar.get(name);
+            const prevTrimmed = out.length > 0 ? out[out.length - 1].trim() : "";
+            const alreadyHasDoc = /^---/.test(prevTrimmed);
+            if (doc && !alreadyHasDoc) {
+                const indent = funcMatch[1];
+                const paramTypes = new Map();
+                if (funcMatch[3].trim()) {
+                    for (const part of funcMatch[3].split(",")) {
+                        const pm = part.trim().match(/^(\w+)(\??):\s*(.+)$/);
+                        if (pm)
+                            paramTypes.set(pm[1], pm[2] ? `${pm[3].trim()}?` : pm[3].trim());
+                    }
+                }
+                const rawRet = funcMatch[4]?.trim() ?? "";
+                const retType = rawRet.startsWith("(") && rawRet.endsWith(")")
+                    ? rawRet.slice(1, -1).split(",")[0]?.trim() ?? ""
+                    : rawRet;
+                if (doc.deprecated !== undefined)
+                    out.push(`${indent}--- @deprecated${doc.deprecated ? ` ${doc.deprecated}` : ""}`);
+                for (const desc of doc.desc)
+                    out.push(`${indent}--- ${desc}`);
+                for (const [paramName, paramDesc] of doc.params) {
+                    const type = paramTypes.get(paramName);
+                    out.push(`${indent}--- @param ${paramName}${type ? ` ${type}` : ""}${paramDesc ? ` ${paramDesc}` : ""}`);
+                }
+                if (doc.returns) {
+                    out.push(`${indent}--- @return${retType ? ` ${retType}` : ""} ${doc.returns}`);
+                }
+            }
+        }
+        out.push(lines[i]);
+    }
+    return out.join("\n");
+}
+function convertJsDocComments(src) {
+    const lines = src.split("\n");
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const trimmed = lines[i].trim();
+        if (trimmed === "--[[") {
+            const blockStart = i;
+            const rawBody = [];
+            i++;
+            while (i < lines.length && lines[i].trim() !== "]]") {
+                rawBody.push(lines[i]);
+                i++;
+            }
+            const closerLine = i < lines.length ? lines[i] : "]]";
+            i++; // skip ]]
+            // Skip blank lines between block and next statement
+            let j = i;
+            while (j < lines.length && lines[j].trim() === "")
+                j++;
+            const nextLine = j < lines.length ? lines[j] : "";
+            const funcMatch = nextLine.match(/^(\t*)local function (\w+)\(([^)]*)\)(?::\s*(.+))?$/);
+            if (!funcMatch) {
+                out.push(lines[blockStart]);
+                for (const bl of rawBody)
+                    out.push(bl);
+                out.push(closerLine);
+                continue;
+            }
+            // Strip * prefixes from JSDoc lines (rotor emits "\t * text" format)
+            const cleanBody = rawBody
+                .map(l => l.trim().replace(/^\*+\s*/, "").trim())
+                .filter(l => l !== "");
+            const descLines = [];
+            const paramTags = [];
+            let returnDesc = "";
+            let deprecatedMsg;
+            for (const line of cleanBody) {
+                const lc = line.toLowerCase();
+                if (lc.startsWith("@param")) {
+                    const m = line.match(/@param\s+(\w+)(?:\s+\{[^}]*\})?\s*(.*)/i);
+                    if (m)
+                        paramTags.push({ name: m[1].trim(), desc: m[2].trim() });
+                }
+                else if (lc.startsWith("@returns") || lc.startsWith("@return")) {
+                    const m = line.match(/@returns?\s*(.*)/i);
+                    if (m)
+                        returnDesc = m[1].trim();
+                }
+                else if (lc.startsWith("@deprecated")) {
+                    const m = line.match(/@deprecated\s*(.*)/i);
+                    deprecatedMsg = m?.[1].trim() ?? "";
+                }
+                else if (!lc.startsWith("@")) {
+                    descLines.push(line);
+                }
+            }
+            if (descLines.length === 0 && paramTags.length === 0 && !returnDesc && deprecatedMsg === undefined) {
+                out.push(lines[blockStart]);
+                for (const bl of rawBody)
+                    out.push(bl);
+                out.push(closerLine);
+                continue;
+            }
+            // Extract param types from Luau function signature
+            const paramTypes = new Map();
+            const rawParams = funcMatch[3];
+            if (rawParams.trim()) {
+                for (const part of rawParams.split(",")) {
+                    const pm = part.trim().match(/^(\w+)(\??):\s*(.+)$/);
+                    if (pm)
+                        paramTypes.set(pm[1], pm[2] ? `${pm[3].trim()}?` : pm[3].trim());
+                }
+            }
+            // Extract return types from Luau function signature
+            const rawRet = funcMatch[4]?.trim() ?? "";
+            let retTypes = [];
+            if (rawRet) {
+                retTypes = rawRet.startsWith("(") && rawRet.endsWith(")")
+                    ? rawRet.slice(1, -1).split(",").map(t => t.trim()).filter(Boolean)
+                    : [rawRet];
+            }
+            const indent = funcMatch[1];
+            if (deprecatedMsg !== undefined)
+                out.push(`${indent}--- @deprecated${deprecatedMsg ? ` ${deprecatedMsg}` : ""}`);
+            for (const desc of descLines) {
+                out.push(`${indent}--- ${desc}`);
+            }
+            for (const { name, desc } of paramTags) {
+                const type = paramTypes.get(name);
+                out.push(`${indent}--- @param ${name}${type ? ` ${type}` : ""}${desc ? ` ${desc}` : ""}`);
+            }
+            if (returnDesc) {
+                const retType = retTypes[0] ?? "";
+                out.push(`${indent}--- @return${retType ? ` ${retType}` : ""} ${returnDesc}`);
+            }
+            i = j; // skip blank lines, let function line emit normally
+            continue;
+        }
+        out.push(lines[i]);
+        i++;
+    }
+    return out.join("\n");
+}
+function applyDirectives(src, strict, optimizeLevel) {
+    if (strict && !src.includes("--!strict")) {
+        src = "--!strict\n" + src;
+    }
+    if (optimizeLevel !== false && !src.includes("--!optimize")) {
+        src = `--!optimize ${optimizeLevel}\n` + src;
+    }
+    return src;
+}
+const writingFiles = new Set();
+function formatFile(luauPath, strict, optimizeLevel, sidecar = new Map(), types = new Map()) {
+    if (writingFiles.has(luauPath))
+        return;
+    if (!fs.existsSync(luauPath))
+        return;
+    let src = fs.readFileSync(luauPath, "utf8");
+    let changed = false;
+    const apply = (fn) => {
+        const next = fn(src);
+        if (next !== src) {
+            src = next;
+            changed = true;
+        }
+    };
+    apply(s => applyDirectives(s, strict, optimizeLevel));
+    apply(hoistGetService);
+    apply(fixBlockCommentOpeners);
+    apply(organizePreamble);
+    apply(s => injectTypeAnnotations(s, types));
+    apply(castTsImports);
+    apply(promoteConsts);
+    apply(convertJsDocComments);
+    apply(s => injectJsDocFromSidecar(s, sidecar));
+    apply(stripUselessBlockComments);
+    apply(addSpacing);
+    if (changed) {
+        writingFiles.add(luauPath);
+        try {
+            fs.writeFileSync(luauPath, src, "utf8");
+        }
+        finally {
+            setTimeout(() => writingFiles.delete(luauPath), 50).unref();
+        }
+    }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "rbxts-transform-luau",
+  "version": "1.0.0",
+  "description": "roblox-ts transformer: idiomatic Luau output — preamble organization, comment cleanup, const promotion, and directive injection",
+  "main": "out/index.js",
+  "types": "out/index.d.ts",
+  "files": [
+    "out",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "roblox-ts",
+    "rbxts",
+    "transformer",
+    "luau",
+    "formatting",
+    "output"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "roblox-ts": "^3.0.0",
+    "typescript": "5.5.3"
+  }
+}