@gwigz/slua-tstl-plugin 0.2.0 → 0.3.0

package/README.md

@@ -5,6 +5,8 @@
 ## What it does
 
 - Translates TypeScript patterns to native Luau/LSL equivalents (see below)
+- Automatically adjusts `ll.*` index arguments and return values from 0-based to 1-based
+- Optimizes self-reassignment array concat/spread to in-place `table.extend`
 - Handles adjusting `Vector`, `Quaternion`, and `UUID` casing
 - Validates `luaTarget` is set to `Luau`
 
@@ -46,6 +48,7 @@ String methods are translated to LSL `ll.*` functions or Luau `string.*` stdlib
 | `str.repeat(n)`        | `string.rep(str, n)`                      |
 | `str.substring(start)` | `string.sub(str, start + 1)`              |
 | `str.substring(s, e)`  | `string.sub(str, s + 1, e)`               |
+| `str.replaceAll(a, b)` | `ll.ReplaceSubString(str, a, b, 0)`       |
 
 > [!NOTE]
 > `str.indexOf(x, fromIndex)` and `str.startsWith(x, position)` with a second argument fall through to TSTL's default handling. Similarly, `str.split()` with no separator is not transformed.
@@ -87,6 +90,37 @@ Comparisons of a bitwise AND against zero are automatically optimized to `bit32.
 
 This works with `!=`, `==`, and with the zero on either side (`0 !== (a & b)`).
 
+### `ll.*` index adjustment
+
+SLua's `ll.*` functions use 1-based indexing (Lua convention), but TypeScript uses 0-based. The plugin automatically adjusts index arguments and return values based on `@indexArg` and `@indexReturn` JSDoc tags in the type definitions:
+
+| TypeScript                       | Lua output                                                   |
+| -------------------------------- | ------------------------------------------------------------ |
+| `ll.GetSubString("hello", 0, 2)` | `ll.GetSubString("hello", 1, 3)`                             |
+| `ll.GetSubString("hello", i, j)` | `ll.GetSubString("hello", i + 1, j + 1)`                     |
+| `ll.ListFindList(a, b)`          | `____tmp = ll.ListFindList(a, b); ____tmp and (____tmp - 1)` |
+
+- **`@indexArg`** parameters get `+ 1` (constant-folded for literals)
+- **`@indexReturn`** wraps the result in a nil-safe `____tmp and (____tmp - 1)` expression
+- Functions without these tags (e.g. `ll.Say`) are left unchanged
+
+### Array concat self-assignment
+
+When an array is reassigned to itself with additional elements appended, the plugin emits `table.extend` (SLua's in-place append) instead of TSTL's `__TS__ArrayConcat` which allocates a new table:
+
+| TypeScript                   | Lua output                              |
+| ---------------------------- | --------------------------------------- |
+| `arr = arr.concat(b)`        | `table.extend(arr, b)`                  |
+| `arr = arr.concat(b, c)`     | `table.extend(table.extend(arr, b), c)` |
+| `arr = [...arr, ...b]`       | `table.extend(arr, b)`                  |
+| `arr = [...arr, ...b, ...c]` | `table.extend(table.extend(arr, b), c)` |
+
+This optimization only applies when:
+
+- The expression is a statement (not `const result = arr.concat(b)`)
+- The LHS is a simple identifier matching the receiver/first spread
+- All concat arguments / spread expressions are array-typed
+
 ### Floor division
 
 `Math.floor(a / b)` is translated to the native Luau floor division operator `//`:

package/dist/index.js

@@ -113,6 +113,17 @@ function isArrayType(expr, checker) {
     const type = checker.getTypeAtLocation(expr);
     return checker.isArrayLikeType(type);
 }
+function isDetectedEventType(expr, checker) {
+    const type = checker.getTypeAtLocation(expr);
+    return type.symbol?.name === "DetectedEvent";
+}
+/**
+ * Returns true when `node` is `detectedEvent.index` — a property access
+ * on a `DetectedEvent` reading the `.index` field.
+ */
+function isDetectedEventIndex(node, checker) {
+    return node.name.text === "index" && isDetectedEventType(node.expression, checker);
+}
 /**
  * Checks whether `node` is `obj.method(args)` where `obj` matches the
  * given type predicate and the method name matches.
@@ -149,6 +160,175 @@ function isGlobalCall(node, name) {
 function createNamespacedCall(ns, fn, args, node) {
     return tstl.createCallExpression(tstl.createTableIndexExpression(tstl.createIdentifier(ns), tstl.createStringLiteral(fn)), args, node);
 }
+// ---------------------------------------------------------------------------
+// Self-reassignment array concat -> table.extend optimization
+// ---------------------------------------------------------------------------
+/**
+ * Detects `arr = arr.concat(b, c, ...)` where LHS is a simple identifier,
+ * the receiver matches LHS, and all concat arguments are array-typed.
+ */
+function extractConcatSelfAssignment(expr, checker) {
+    if (expr.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
+        return null;
+    if (!ts.isIdentifier(expr.left))
+        return null;
+    if (!ts.isCallExpression(expr.right))
+        return null;
+    if (!ts.isPropertyAccessExpression(expr.right.expression))
+        return null;
+    if (expr.right.expression.name.text !== "concat")
+        return null;
+    if (!ts.isIdentifier(expr.right.expression.expression))
+        return null;
+    if (expr.right.expression.expression.text !== expr.left.text)
+        return null;
+    if (expr.right.arguments.length === 0)
+        return null;
+    for (const arg of expr.right.arguments) {
+        if (!isArrayType(arg, checker))
+            return null;
+    }
+    return { name: expr.left, args: expr.right.arguments };
+}
+/**
+ * Detects `arr = [...arr, ...b, ...c]` where LHS is a simple identifier,
+ * all elements are spreads, the first spread matches LHS, and all tail
+ * spread expressions are array-typed.
+ */
+function extractSpreadSelfAssignment(expr, checker) {
+    if (expr.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
+        return null;
+    if (!ts.isIdentifier(expr.left))
+        return null;
+    if (!ts.isArrayLiteralExpression(expr.right))
+        return null;
+    const elements = expr.right.elements;
+    if (elements.length < 2)
+        return null;
+    for (const el of elements) {
+        if (!ts.isSpreadElement(el))
+            return null;
+    }
+    const first = elements[0];
+    if (!ts.isIdentifier(first.expression))
+        return null;
+    if (first.expression.text !== expr.left.text)
+        return null;
+    const tailArgs = [];
+    for (let i = 1; i < elements.length; i++) {
+        const spread = elements[i];
+        if (!isArrayType(spread.expression, checker))
+            return null;
+        tailArgs.push(spread.expression);
+    }
+    return { name: expr.left, args: tailArgs };
+}
+/**
+ * Builds nested `table.extend` calls:
+ * - Single arg: `table.extend(arr, b)`
+ * - Multiple: `table.extend(table.extend(arr, b), c)`
+ */
+function emitChainedExtend(target, args, node) {
+    let result = createNamespacedCall("table", "extend", [target, args[0]], node);
+    for (let i = 1; i < args.length; i++) {
+        result = createNamespacedCall("table", "extend", [result, args[i]], node);
+    }
+    return result;
+}
+/**
+ * For an `ll.Foo(...)` call, inspect the resolved signature's JSDoc tags
+ * to determine which arguments have `@indexArg` semantics and whether
+ * the return value has `@indexReturn` semantics.
+ */
+function getLLIndexSemantics(node, checker) {
+    // Must be ll.Something(...)
+    if (!ts.isPropertyAccessExpression(node.expression))
+        return null;
+    if (!ts.isIdentifier(node.expression.expression))
+        return null;
+    if (node.expression.expression.text !== "ll")
+        return null;
+    const sig = checker.getResolvedSignature(node);
+    const decl = sig?.declaration;
+    if (!decl || !ts.isFunctionDeclaration(decl))
+        return null;
+    const tags = ts.getJSDocTags(decl);
+    const indexArgs = new Set();
+    let indexReturn = false;
+    for (const tag of tags) {
+        const tagName = tag.tagName.text;
+        if (tagName === "indexArg") {
+            const text = typeof tag.comment === "string"
+                ? tag.comment
+                : Array.isArray(tag.comment)
+                    ? tag.comment.map((c) => c.text).join("")
+                    : undefined;
+            if (text) {
+                indexArgs.add(text.trim());
+            }
+        }
+        else if (tagName === "indexReturn") {
+            indexReturn = true;
+        }
+    }
+    if (indexArgs.size === 0 && !indexReturn)
+        return null;
+    return { indexArgs, indexReturn };
+}
+/**
+ * Adjusts a 0-based index argument to 1-based for Lua.
+ * Constant-folds numeric literals; otherwise emits `expr + 1`.
+ */
+function adjustIndexArg(arg, context) {
+    if (ts.isNumericLiteral(arg)) {
+        return tstl.createNumericLiteral(Number(arg.text) + 1);
+    }
+    // DetectedEvent.index is already 1-based at runtime. The PropertyAccess
+    // visitor emits `- 1` to make it 0-based for TS, and @indexArg adds `+ 1`.
+    // These cancel out, so emit the raw property access directly.
+    if (ts.isPropertyAccessExpression(arg) && isDetectedEventIndex(arg, context.checker)) {
+        const obj = context.transformExpression(arg.expression);
+        return tstl.createTableIndexExpression(obj, tstl.createStringLiteral("index"));
+    }
+    return tstl.createBinaryExpression(context.transformExpression(arg), tstl.createNumericLiteral(1), tstl.SyntaxKind.AdditionOperator, arg);
+}
+/**
+ * Emit an `ll.Foo(...)` call with automatic index adjustments:
+ * - `@indexArg` parameters get `+1`
+ * - `@indexReturn` wraps the result in a nil-safe `__tmp and (__tmp - 1)`
+ */
+function emitLLIndexCall(node, context, semantics) {
+    const expr = node.expression;
+    const fnName = expr.name.text;
+    // Resolve parameter names from the declaration
+    const sig = context.checker.getResolvedSignature(node);
+    const params = sig?.declaration && ts.isFunctionDeclaration(sig.declaration)
+        ? sig.declaration.parameters
+        : undefined;
+    const args = node.arguments.map((arg, i) => {
+        const paramName = params?.[i]?.name;
+        const name = paramName && ts.isIdentifier(paramName) ? paramName.text : undefined;
+        if (name && semantics.indexArgs.has(name)) {
+            return adjustIndexArg(arg, context);
+        }
+        return context.transformExpression(arg);
+    });
+    const call = createNamespacedCall("ll", fnName, args, node);
+    if (!semantics.indexReturn) {
+        return call;
+    }
+    // Check if return type is number-like (skip for list/string returns like llFindNotecardTextSync)
+    const retType = context.checker.getTypeAtLocation(node);
+    const isNumberReturn = !!(retType.flags & ts.TypeFlags.NumberLike) ||
+        (retType.isUnion() && retType.types.some((t) => !!(t.flags & ts.TypeFlags.NumberLike)));
+    if (!isNumberReturn) {
+        return call;
+    }
+    // Nil-safe return adjustment: `local __tmp = ll.Fn(...); __tmp and (__tmp - 1)`
+    const tempId = tstl.createIdentifier("____tmp");
+    context.addPrecedingStatements(tstl.createVariableDeclarationStatement(tempId, call, node));
+    return tstl.createBinaryExpression(tstl.cloneIdentifier(tempId), tstl.createParenthesizedExpression(tstl.createBinaryExpression(tstl.cloneIdentifier(tempId), tstl.createNumericLiteral(1), tstl.SyntaxKind.SubtractionOperator)), tstl.SyntaxKind.AndOperator, node);
+}
 const CALL_TRANSFORMS = [
     // JSON.stringify(val) -> lljson.encode(val)
     {
@@ -351,6 +531,12 @@ const plugin = {
                     result.table.text = replacement;
                 }
             }
+            // DetectedEvent.index is 1-based at runtime in SLua; emit `obj.index - 1`
+            // so TypeScript sees a 0-based value. This composes correctly with
+            // @indexArg functions (which add +1, cancelling out the -1).
+            if (isDetectedEventIndex(node, context.checker)) {
+                return tstl.createBinaryExpression(result, tstl.createNumericLiteral(1), tstl.SyntaxKind.SubtractionOperator, node);
+            }
             return result;
         },
         [ts.SyntaxKind.BinaryExpression]: (node, context) => {
@@ -400,6 +586,15 @@ const plugin = {
                     const call = createBit32Call(compoundFn, [left, right], node);
                     return [tstl.createAssignmentStatement(left, call, node)];
                 }
+                // Self-reassignment concat/spread -> table.extend (in-place, no assignment needed)
+                const concatMatch = extractConcatSelfAssignment(node.expression, context.checker) ??
+                    extractSpreadSelfAssignment(node.expression, context.checker);
+                if (concatMatch) {
+                    const target = context.transformExpression(concatMatch.name);
+                    const args = concatMatch.args.map((a) => context.transformExpression(a));
+                    const call = emitChainedExtend(target, args, node);
+                    return [tstl.createExpressionStatement(call, node)];
+                }
             }
             return context.superTransformStatements(node);
         },
@@ -410,6 +605,11 @@ const plugin = {
                     return transform.emit(node, context);
                 }
             }
+            // ll.* index-semantics: automatic 0->1 index adjustment
+            const indexSemantics = getLLIndexSemantics(node, context.checker);
+            if (indexSemantics) {
+                return emitLLIndexCall(node, context, indexSemantics);
+            }
             // `Math.floor(a / b)` -> `a // b` (native Luau floor division operator)
             if (isMathFloor(node)) {
                 const arg = node.arguments[0];
@@ -445,6 +645,14 @@ const plugin = {
         return diagnostics;
     },
     beforeEmit(program, _options, _emitHost, result) {
+        // Strip internal @indexArg / @indexReturn JSDoc tags from Lua comments.
+        // These are only consumed by the plugin at transpile time; they should
+        // not leak into the output as Lua comments.
+        for (const file of result) {
+            file.code = file.code
+                .replace(/^--\s*@index(?:Arg|Return)\b.*\n/gm, "")
+                .replace(/^(---.*)\n(?:-- *\n)+(?=local |ll\.)/gm, "$1\n");
+        }
         // Strip empty module boilerplate from files without explicit exports.
         // `moduleDetection: "force"` causes TSTL to wrap every file as a module;
         // standalone SLua scripts don't need the ____exports wrapper.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gwigz/slua-tstl-plugin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScriptToLua plugin for targeting Second Life's SLua runtime",
   "license": "MIT",
   "repository": {
@@ -28,6 +28,6 @@
     "typescript-to-lua": "^1.33.0"
   },
   "peerDependencies": {
-    "typescript": "~5.7.0"
+    "typescript": "~5.9.3"
   }
 }