xray16 1.6.3 → 1.6.4

package/plugins/inline_constants/transformation/evaluation.d.ts

@@ -1,79 +1,109 @@
 import * as ts from "typescript";
-import { type TInlineValue } from "./constants";
+import { type TFoldedValue, type TInlineValue } from "./constants";
+/**
+ * Resolve the member symbol for a property or element access expression.
+ * When direct symbol resolution fails, element access is resolved through the object type. This supports
+ * literal keys and keys that fold to constants at build time, such as 'table[misc.device_pda]'.
+ *
+ * @param checker - Program type checker.
+ * @param node - Access expression to resolve symbol for.
+ * @returns Resolved member symbol or null.
+ */
+export declare function resolveMemberSymbol(checker: ts.TypeChecker, node: ts.PropertyAccessExpression | ts.ElementAccessExpression): ts.Symbol | null;
 /**
  * Get literal value of symbol declared type, if it is a unit type.
  * Uses declared type instead of flow-narrowed type so mutable narrowed values are never inlined.
  *
  * @param checker - Program type checker.
  * @param symbol - Symbol to get declared literal value for.
- * @returns Literal value or null.
+ * @returns Literal value, or null when the declared type is not a unit type.
  */
 export declare function getDeclaredLiteralValue(checker: ts.TypeChecker, symbol: ts.Symbol): TInlineValue | null;
 /**
- * Convert folded value to string for concatenation contexts.
- * Non-integer numbers are rejected - JS 'String()' and LuaJIT 'tostring' format them differently
+ * Convert a folded value to a string for concatenation contexts.
+ * Non-integer numbers are rejected because JS 'String()' and LuaJIT 'tostring' format them differently
  * (17 significant digits vs '%.14g'), so folding would change runtime-visible output.
+ * Expression trees are rejected because Lua '..' coercion differs from JS string conversion.
  *
  * @param value - Folded value to convert.
  * @returns String representation or null.
  */
-export declare function toFoldedString(value: TInlineValue | null): string | null;
+export declare function toFoldedString(value: TFoldedValue | null): string | null;
 /**
- * Guard folded numeric results against NaN / Infinity that cannot be emitted as lua literals.
+ * Guard folded numeric results against NaN and Infinity, which cannot be emitted as Lua literals.
  *
  * @param value - Folded numeric value.
- * @returns Finite number or null.
+ * @returns Finite number, or null when the value cannot be emitted as a Lua literal.
  */
 export declare function toFiniteNumber(value: number): number | null;
 /**
- * Fold binary expression of constant operands with JS semantics.
- * JS semantics are the correct target since tstl preserves them at runtime (e.g. '%' on negative operands).
+ * Fold a binary expression with constant operands using JavaScript semantics.
+ * JavaScript semantics are the correct target because TSTL preserves them at runtime,
+ * including '%' behavior for negative operands.
+ *
+ * When an operand is an expression tree with engine references, the result is a tree as well.
+ * Trees only allow numeric operands and operators where emitted Lua matches TSTL lowering exactly:
+ * '%', bitwise operators and string concatenation with trees are rejected.
  *
  * @param operator - Binary operator kind.
  * @param left - Folded left operand.
  * @param right - Folded right operand.
- * @returns Folded value or null.
+ * @returns Folded value, or null when the operation is not safe to fold.
  */
-export declare function foldBinaryExpression(operator: ts.SyntaxKind, left: TInlineValue, right: TInlineValue): TInlineValue | null;
+export declare function foldBinaryExpression(operator: ts.SyntaxKind, left: TFoldedValue, right: TFoldedValue): TFoldedValue | null;
 /**
- * Evaluate expression to a compile-time constant value when possible.
+ * Evaluate an expression to a compile-time constant value when possible.
  * Supports literals, unary/binary arithmetic, string concatenation, template literals,
- * references to enum members / module-level const scalars / `as const` object properties
- * and whitelisted namespace constants like 'math.pi'.
+ * references to enum members / module-level const scalars / `as const` object properties,
+ * whitelisted namespace constants like 'math.pi' and runtime-constant engine references
+ * like 'stalker_ids.action_dying' (emitted as expressions instead of baked literals).
  *
  * @param checker - Program type checker.
  * @param expression - Expression to evaluate.
  * @param seen - Set of declarations on current resolution path, guards from circular references.
- * @returns Folded constant value or null.
+ * @returns Folded constant value, or null when the expression is not safe to fold.
+ */
+export declare function evaluateConstantExpression(checker: ts.TypeChecker, expression: ts.Expression, seen: Set<ts.Declaration>): TFoldedValue | null;
+/**
+ * Check whether an enum member is computable at build time - either constant for TypeScript
+ * or initialized with an expression that folds to a literal or an engine reference tree.
+ *
+ * @param checker - Program type checker.
+ * @param member - Enum member to check.
+ * @returns Whether the member is computable at build time.
  */
-export declare function evaluateConstantExpression(checker: ts.TypeChecker, expression: ts.Expression, seen: Set<ts.Declaration>): TInlineValue | null;
+export declare function isComputableEnumMember(checker: ts.TypeChecker, member: ts.EnumMember): boolean;
 /**
- * Resolve referenced symbol to a compile-time constant value when the reference is safe to fold.
- * Safe references are enum members, module-level const scalars and readonly `as const` object properties -
- * values that cannot legally change at runtime. Tags are not required on referenced declarations.
+ * Resolve a referenced symbol to a compile-time constant value when the reference is safe to fold.
+ * Safe references are enum members, module-level const scalars, readonly `as const` object properties
+ * and `static readonly` engine members from ambient 'xray16' typings - values that cannot legally
+ * change at runtime. Tags are not required on referenced declarations.
  *
  * @param checker - Program type checker.
  * @param symbol - Referenced symbol to resolve.
  * @param seen - Set of declarations on current resolution path.
- * @returns Folded constant value or null.
+ * @returns Folded constant value, or null when the symbol is not safe to fold.
  */
-export declare function resolveConstantSymbol(checker: ts.TypeChecker, symbol: ts.Symbol, seen: Set<ts.Declaration>): TInlineValue | null;
+export declare function resolveConstantSymbol(checker: ts.TypeChecker, symbol: ts.Symbol, seen: Set<ts.Declaration>): TFoldedValue | null;
 /**
- * Get constant value of a declaration - declared unit type first, initializer folding as fallback.
+ * Get the constant value of a declaration.
+ * Initializers are folded first so engine references are substituted as expressions - the declared
+ * literal type fast path would silently bake possibly stale values claimed by typings.
+ * Declared unit types are only used for initializer-less declarations like ambient constants.
  * Safety and tagging requirements are checked by callers.
  *
  * @param checker - Program type checker.
  * @param symbol - Symbol to get value for.
  * @param seen - Set of declarations on current resolution path.
- * @returns Constant value or null.
+ * @returns Constant value, or null when the declaration cannot be folded.
  */
-export declare function getComputedDeclarationValue(checker: ts.TypeChecker, symbol: ts.Symbol, seen: Set<ts.Declaration>): TInlineValue | null;
+export declare function getComputedDeclarationValue(checker: ts.TypeChecker, symbol: ts.Symbol, seen: Set<ts.Declaration>): TFoldedValue | null;
 /**
- * Get inline-able literal value for a symbol resolved from an access expression or identifier.
- * Only symbols declared inside `@inline` tagged enums / variable statements produce values.
+ * Get the inlineable value for a symbol resolved from an access expression or identifier.
+ * Only symbols declared inside tagged enums or variable statements produce values.
  *
  * @param checker - Program type checker.
  * @param symbol - Symbol to resolve inline value for.
- * @returns Literal value or null.
+ * @returns Folded value, or null when the symbol is not tagged for inlining.
  */
-export declare function tryGetInlineValue(checker: ts.TypeChecker, symbol: ts.Symbol): TInlineValue | null;
+export declare function tryGetInlineValue(checker: ts.TypeChecker, symbol: ts.Symbol): TFoldedValue | null;

package/plugins/inline_constants/transformation/evaluation.js

@@ -1,23 +1,54 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveMemberSymbol = resolveMemberSymbol;
 exports.getDeclaredLiteralValue = getDeclaredLiteralValue;
 exports.toFoldedString = toFoldedString;
 exports.toFiniteNumber = toFiniteNumber;
 exports.foldBinaryExpression = foldBinaryExpression;
 exports.evaluateConstantExpression = evaluateConstantExpression;
+exports.isComputableEnumMember = isComputableEnumMember;
 exports.resolveConstantSymbol = resolveConstantSymbol;
 exports.getComputedDeclarationValue = getComputedDeclarationValue;
 exports.tryGetInlineValue = tryGetInlineValue;
 const ts = require("typescript");
 const ast_1 = require("./ast");
 const constants_1 = require("./constants");
+const TREE_BINARY_OPERATORS = {
+    [ts.SyntaxKind.PlusToken]: "+",
+    [ts.SyntaxKind.MinusToken]: "-",
+    [ts.SyntaxKind.AsteriskToken]: "*",
+    [ts.SyntaxKind.SlashToken]: "/",
+    [ts.SyntaxKind.AsteriskAsteriskToken]: "**",
+};
+/**
+ * Resolve the member symbol for a property or element access expression.
+ * When direct symbol resolution fails, element access is resolved through the object type. This supports
+ * literal keys and keys that fold to constants at build time, such as 'table[misc.device_pda]'.
+ *
+ * @param checker - Program type checker.
+ * @param node - Access expression to resolve symbol for.
+ * @returns Resolved member symbol or null.
+ */
+function resolveMemberSymbol(checker, node) {
+    const symbol = checker.getSymbolAtLocation(node);
+    if (symbol !== undefined) {
+        return symbol;
+    }
+    if (ts.isElementAccessExpression(node)) {
+        const key = evaluateConstantExpression(checker, node.argumentExpression, new Set());
+        if (typeof key === "string" || typeof key === "number") {
+            return checker.getTypeAtLocation(node.expression).getProperty(String(key)) ?? null;
+        }
+    }
+    return null;
+}
 /**
  * Get literal value of symbol declared type, if it is a unit type.
  * Uses declared type instead of flow-narrowed type so mutable narrowed values are never inlined.
  *
  * @param checker - Program type checker.
  * @param symbol - Symbol to get declared literal value for.
- * @returns Literal value or null.
+ * @returns Literal value, or null when the declared type is not a unit type.
  */
 function getDeclaredLiteralValue(checker, symbol) {
     const declaration = symbol.valueDeclaration;
@@ -37,9 +68,10 @@ function getDeclaredLiteralValue(checker, symbol) {
     return null;
 }
 /**
- * Convert folded value to string for concatenation contexts.
- * Non-integer numbers are rejected - JS 'String()' and LuaJIT 'tostring' format them differently
+ * Convert a folded value to a string for concatenation contexts.
+ * Non-integer numbers are rejected because JS 'String()' and LuaJIT 'tostring' format them differently
  * (17 significant digits vs '%.14g'), so folding would change runtime-visible output.
+ * Expression trees are rejected because Lua '..' coercion differs from JS string conversion.
  *
  * @param value - Folded value to convert.
  * @returns String representation or null.
@@ -54,24 +86,36 @@ function toFoldedString(value) {
     return null;
 }
 /**
- * Guard folded numeric results against NaN / Infinity that cannot be emitted as lua literals.
+ * Guard folded numeric results against NaN and Infinity, which cannot be emitted as Lua literals.
  *
  * @param value - Folded numeric value.
- * @returns Finite number or null.
+ * @returns Finite number, or null when the value cannot be emitted as a Lua literal.
  */
 function toFiniteNumber(value) {
     return Number.isFinite(value) ? value : null;
 }
 /**
- * Fold binary expression of constant operands with JS semantics.
- * JS semantics are the correct target since tstl preserves them at runtime (e.g. '%' on negative operands).
+ * Fold a binary expression with constant operands using JavaScript semantics.
+ * JavaScript semantics are the correct target because TSTL preserves them at runtime,
+ * including '%' behavior for negative operands.
+ *
+ * When an operand is an expression tree with engine references, the result is a tree as well.
+ * Trees only allow numeric operands and operators where emitted Lua matches TSTL lowering exactly:
+ * '%', bitwise operators and string concatenation with trees are rejected.
  *
  * @param operator - Binary operator kind.
  * @param left - Folded left operand.
  * @param right - Folded right operand.
- * @returns Folded value or null.
+ * @returns Folded value, or null when the operation is not safe to fold.
  */
 function foldBinaryExpression(operator, left, right) {
+    if (typeof left === "object" || typeof right === "object") {
+        const treeOperator = TREE_BINARY_OPERATORS[operator];
+        if (treeOperator === undefined || !(0, constants_1.isNumericFoldedValue)(left) || !(0, constants_1.isNumericFoldedValue)(right)) {
+            return null;
+        }
+        return { kind: "binary", operator: treeOperator, left, right };
+    }
     if (operator === ts.SyntaxKind.PlusToken) {
         if (typeof left === "number" && typeof right === "number") {
             return toFiniteNumber(left + right);
@@ -111,15 +155,16 @@ function foldBinaryExpression(operator, left, right) {
     }
 }
 /**
- * Evaluate expression to a compile-time constant value when possible.
+ * Evaluate an expression to a compile-time constant value when possible.
  * Supports literals, unary/binary arithmetic, string concatenation, template literals,
- * references to enum members / module-level const scalars / `as const` object properties
- * and whitelisted namespace constants like 'math.pi'.
+ * references to enum members / module-level const scalars / `as const` object properties,
+ * whitelisted namespace constants like 'math.pi' and runtime-constant engine references
+ * like 'stalker_ids.action_dying' (emitted as expressions instead of baked literals).
  *
  * @param checker - Program type checker.
  * @param expression - Expression to evaluate.
  * @param seen - Set of declarations on current resolution path, guards from circular references.
- * @returns Folded constant value or null.
+ * @returns Folded constant value, or null when the expression is not safe to fold.
  */
 function evaluateConstantExpression(checker, expression, seen) {
     const node = (0, ast_1.unwrapInitializer)(expression);
@@ -145,9 +190,14 @@ function evaluateConstantExpression(checker, expression, seen) {
         }
         switch (node.operator) {
             case ts.SyntaxKind.MinusToken:
-                return typeof operand === "number" ? toFiniteNumber(-operand) : null;
+                if (typeof operand === "number") {
+                    return toFiniteNumber(-operand);
+                }
+                return typeof operand === "object" && (0, constants_1.isNumericFoldedValue)(operand) ? { kind: "negate", operand } : null;
             case ts.SyntaxKind.PlusToken:
-                return typeof operand === "number" ? operand : null;
+                return typeof operand === "number" || (typeof operand === "object" && (0, constants_1.isNumericFoldedValue)(operand))
+                    ? operand
+                    : null;
             case ts.SyntaxKind.TildeToken:
                 return typeof operand === "number" ? ~operand : null;
             case ts.SyntaxKind.ExclamationToken:
@@ -189,20 +239,58 @@ function evaluateConstantExpression(checker, expression, seen) {
         return symbol === undefined ? null : resolveConstantSymbol(checker, symbol, seen);
     }
     if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
-        const symbol = (0, ast_1.resolveMemberSymbol)(checker, node);
+        const symbol = resolveMemberSymbol(checker, node);
         return symbol === null ? null : resolveConstantSymbol(checker, symbol, seen);
     }
     return null;
 }
 /**
- * Resolve referenced symbol to a compile-time constant value when the reference is safe to fold.
- * Safe references are enum members, module-level const scalars and readonly `as const` object properties -
- * values that cannot legally change at runtime. Tags are not required on referenced declarations.
+ * Fold an enum member to a constant value.
+ * TypeScript computes literal values of constant members; members initialized with engine references
+ * fold to expression trees instead.
+ *
+ * @param checker - Program type checker.
+ * @param declaration - Enum member declaration to fold.
+ * @param seen - Set of declarations on current resolution path.
+ * @returns Folded constant value, or null when the member is not computable at build time.
+ */
+function getEnumMemberValue(checker, declaration, seen) {
+    const value = checker.getConstantValue(declaration);
+    if (typeof value === "string" || typeof value === "number") {
+        return value;
+    }
+    if (declaration.initializer === undefined || seen.has(declaration)) {
+        return null;
+    }
+    seen.add(declaration);
+    try {
+        return evaluateConstantExpression(checker, declaration.initializer, seen);
+    }
+    finally {
+        seen.delete(declaration);
+    }
+}
+/**
+ * Check whether an enum member is computable at build time - either constant for TypeScript
+ * or initialized with an expression that folds to a literal or an engine reference tree.
+ *
+ * @param checker - Program type checker.
+ * @param member - Enum member to check.
+ * @returns Whether the member is computable at build time.
+ */
+function isComputableEnumMember(checker, member) {
+    return getEnumMemberValue(checker, member, new Set()) !== null;
+}
+/**
+ * Resolve a referenced symbol to a compile-time constant value when the reference is safe to fold.
+ * Safe references are enum members, module-level const scalars, readonly `as const` object properties
+ * and `static readonly` engine members from ambient 'xray16' typings - values that cannot legally
+ * change at runtime. Tags are not required on referenced declarations.
  *
  * @param checker - Program type checker.
  * @param symbol - Referenced symbol to resolve.
  * @param seen - Set of declarations on current resolution path.
- * @returns Folded constant value or null.
+ * @returns Folded constant value, or null when the symbol is not safe to fold.
  */
 function resolveConstantSymbol(checker, symbol, seen) {
     const resolved = (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
@@ -211,8 +299,19 @@ function resolveConstantSymbol(checker, symbol, seen) {
         return null;
     }
     if (ts.isEnumMember(declaration)) {
-        const value = checker.getConstantValue(declaration);
-        return typeof value === "string" || typeof value === "number" ? value : null;
+        return getEnumMemberValue(checker, declaration, seen);
+    }
+    if (ts.isPropertyDeclaration(declaration)) {
+        const path = (0, ast_1.getEngineConstantPath)(declaration);
+        if (path === null) {
+            return null;
+        }
+        const type = checker.getTypeOfSymbolAtLocation(resolved, declaration);
+        return {
+            kind: "engine-ref",
+            path,
+            isNumeric: type.isNumberLiteral() || (type.flags & ts.TypeFlags.NumberLike) !== 0,
+        };
     }
     if (ts.isVariableDeclaration(declaration)) {
         const statement = (0, ast_1.getContainingVariableStatement)(declaration);
@@ -227,23 +326,22 @@ function resolveConstantSymbol(checker, symbol, seen) {
     return null;
 }
 /**
- * Get constant value of a declaration - declared unit type first, initializer folding as fallback.
+ * Get the constant value of a declaration.
+ * Initializers are folded first so engine references are substituted as expressions - the declared
+ * literal type fast path would silently bake possibly stale values claimed by typings.
+ * Declared unit types are only used for initializer-less declarations like ambient constants.
  * Safety and tagging requirements are checked by callers.
  *
  * @param checker - Program type checker.
  * @param symbol - Symbol to get value for.
  * @param seen - Set of declarations on current resolution path.
- * @returns Constant value or null.
+ * @returns Constant value, or null when the declaration cannot be folded.
  */
 function getComputedDeclarationValue(checker, symbol, seen) {
     const declaration = symbol.valueDeclaration;
     if (declaration === undefined) {
         return null;
     }
-    const declared = getDeclaredLiteralValue(checker, symbol);
-    if (declared !== null) {
-        return declared;
-    }
     if (seen.has(declaration)) {
         return null;
     }
@@ -257,19 +355,19 @@ function getComputedDeclarationValue(checker, symbol, seen) {
             const valueSymbol = checker.getShorthandAssignmentValueSymbol(declaration);
             return valueSymbol === undefined ? null : resolveConstantSymbol(checker, valueSymbol, seen);
         }
-        return null;
+        return getDeclaredLiteralValue(checker, symbol);
     }
     finally {
         seen.delete(declaration);
     }
 }
 /**
- * Get inline-able literal value for a symbol resolved from an access expression or identifier.
- * Only symbols declared inside `@inline` tagged enums / variable statements produce values.
+ * Get the inlineable value for a symbol resolved from an access expression or identifier.
+ * Only symbols declared inside tagged enums or variable statements produce values.
  *
  * @param checker - Program type checker.
  * @param symbol - Symbol to resolve inline value for.
- * @returns Literal value or null.
+ * @returns Folded value, or null when the symbol is not tagged for inlining.
  */
 function tryGetInlineValue(checker, symbol) {
     const declaration = symbol.valueDeclaration;
@@ -280,8 +378,7 @@ function tryGetInlineValue(checker, symbol) {
         if (!(0, ast_1.hasInlineTag)(declaration.parent)) {
             return null;
         }
-        const value = checker.getConstantValue(declaration);
-        return typeof value === "string" || typeof value === "number" ? value : null;
+        return getEnumMemberValue(checker, declaration, new Set());
     }
     if (ts.isPropertyAssignment(declaration) ||
         ts.isShorthandPropertyAssignment(declaration) ||

package/plugins/inline_constants/transformation/index.d.ts

@@ -4,3 +4,4 @@ export * from "./errors";
 export * from "./evaluation";
 export * from "./transformers";
 export * from "./validation";
+export * from "./virtual";

package/plugins/inline_constants/transformation/index.js

@@ -20,3 +20,4 @@ __exportStar(require("./errors"), exports);
 __exportStar(require("./evaluation"), exports);
 __exportStar(require("./transformers"), exports);
 __exportStar(require("./validation"), exports);
+__exportStar(require("./virtual"), exports);

package/plugins/inline_constants/transformation/transformers.d.ts

@@ -1,27 +1,41 @@
 import * as ts from "typescript";
 import * as lua from "typescript-to-lua";
-import { type TInlineValue } from "./constants";
+import { type TFoldedValue } from "./constants";
 /**
- * Create lua literal expression for provided constant value.
+ * Create a Lua expression for the provided folded value.
+ * Literals become Lua literals; expression trees with engine references become global access
+ * expressions and arithmetic over them.
  *
- * @param value - Constant value to create literal for.
- * @param node - Original typescript node.
- * @returns Lua literal expression.
+ * @param value - Folded value to create expression for.
+ * @param node - Original TypeScript node.
+ * @returns Lua expression.
  */
-export declare function createLiteralExpression(value: TInlineValue, node: ts.Node): lua.Expression;
+export declare function createFoldedExpression(value: TFoldedValue, node: ts.Node): lua.Expression;
 /**
- * Transform property/element access expressions, inline literal values of `@inline` tagged declarations.
+ * Transform property and element access expressions by inlining literal values from tagged declarations.
+ * Object spreads of `@virtual` objects accessed through namespaces are expanded to table literals.
  *
  * @param node - Access expression node to transform.
  * @param context - Transformation context.
- * @returns Lua literal when access resolves to a tagged constant, default transformation otherwise.
+ * @returns Lua literal when the access resolves to a tagged constant, default transformation otherwise.
  */
 export declare function transformAccessExpression(node: ts.PropertyAccessExpression | ts.ElementAccessExpression, context: lua.TransformationContext): lua.Expression;
 /**
- * Transform identifier expressions, inline literal values of `@inline` tagged scalar constants.
+ * Transform identifier expressions by inlining literal values from tagged scalar constants
+ * and expand object spreads of `@virtual` objects into table literals.
  *
  * @param node - Identifier node to transform.
  * @param context - Transformation context.
- * @returns Lua literal when identifier resolves to a tagged constant, default transformation otherwise.
+ * @returns Lua literal when the identifier resolves to a tagged constant, default transformation otherwise.
  */
 export declare function transformIdentifierExpression(node: ts.Identifier, context: lua.TransformationContext): lua.Expression;
+/**
+ * Transform import declarations by stripping bindings for tagged declarations with no remaining runtime usages.
+ * When no runtime bindings remain, the require is dropped for provably pure modules
+ * or kept as a side-effect import otherwise.
+ *
+ * @param statement - Import declaration to transform.
+ * @param context - Transformation context.
+ * @returns Transformed statements.
+ */
+export declare function transformImportDeclaration(statement: ts.ImportDeclaration, context: lua.TransformationContext): Array<lua.Statement>;