xray16 1.6.1 → 1.6.3

package/plugins/inline_constants/transformation/evaluation.js

@@ -0,0 +1,296 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDeclaredLiteralValue = getDeclaredLiteralValue;
+exports.toFoldedString = toFoldedString;
+exports.toFiniteNumber = toFiniteNumber;
+exports.foldBinaryExpression = foldBinaryExpression;
+exports.evaluateConstantExpression = evaluateConstantExpression;
+exports.resolveConstantSymbol = resolveConstantSymbol;
+exports.getComputedDeclarationValue = getComputedDeclarationValue;
+exports.tryGetInlineValue = tryGetInlineValue;
+const ts = require("typescript");
+const ast_1 = require("./ast");
+const constants_1 = require("./constants");
+/**
+ * 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.
+ */
+function getDeclaredLiteralValue(checker, symbol) {
+    const declaration = symbol.valueDeclaration;
+    if (declaration === undefined) {
+        return null;
+    }
+    const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+    if (type.isStringLiteral()) {
+        return type.value;
+    }
+    if (type.isNumberLiteral()) {
+        return type.value;
+    }
+    if ((type.flags & ts.TypeFlags.BooleanLiteral) !== 0) {
+        return checker.typeToString(type) === "true";
+    }
+    return null;
+}
+/**
+ * Convert folded value to string for concatenation contexts.
+ * Non-integer numbers are rejected - JS 'String()' and LuaJIT 'tostring' format them differently
+ * (17 significant digits vs '%.14g'), so folding would change runtime-visible output.
+ *
+ * @param value - Folded value to convert.
+ * @returns String representation or null.
+ */
+function toFoldedString(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" && Number.isInteger(value) && Math.abs(value) < 1e14) {
+        return String(value);
+    }
+    return null;
+}
+/**
+ * Guard folded numeric results against NaN / Infinity that cannot be emitted as lua literals.
+ *
+ * @param value - Folded numeric value.
+ * @returns Finite number or null.
+ */
+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).
+ *
+ * @param operator - Binary operator kind.
+ * @param left - Folded left operand.
+ * @param right - Folded right operand.
+ * @returns Folded value or null.
+ */
+function foldBinaryExpression(operator, left, right) {
+    if (operator === ts.SyntaxKind.PlusToken) {
+        if (typeof left === "number" && typeof right === "number") {
+            return toFiniteNumber(left + right);
+        }
+        const leftString = toFoldedString(left);
+        const rightString = toFoldedString(right);
+        return leftString !== null && rightString !== null ? leftString + rightString : null;
+    }
+    if (typeof left !== "number" || typeof right !== "number") {
+        return null;
+    }
+    switch (operator) {
+        case ts.SyntaxKind.MinusToken:
+            return toFiniteNumber(left - right);
+        case ts.SyntaxKind.AsteriskToken:
+            return toFiniteNumber(left * right);
+        case ts.SyntaxKind.SlashToken:
+            return toFiniteNumber(left / right);
+        case ts.SyntaxKind.PercentToken:
+            return toFiniteNumber(left % right);
+        case ts.SyntaxKind.AsteriskAsteriskToken:
+            return toFiniteNumber(left ** right);
+        case ts.SyntaxKind.AmpersandToken:
+            return left & right;
+        case ts.SyntaxKind.BarToken:
+            return left | right;
+        case ts.SyntaxKind.CaretToken:
+            return left ^ right;
+        case ts.SyntaxKind.LessThanLessThanToken:
+            return left << right;
+        case ts.SyntaxKind.GreaterThanGreaterThanToken:
+            return left >> right;
+        case ts.SyntaxKind.GreaterThanGreaterThanGreaterThanToken:
+            return left >>> right;
+        default:
+            return null;
+    }
+}
+/**
+ * Evaluate 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'.
+ *
+ * @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.
+ */
+function evaluateConstantExpression(checker, expression, seen) {
+    const node = (0, ast_1.unwrapInitializer)(expression);
+    if (node === null) {
+        return null;
+    }
+    if (ts.isStringLiteralLike(node)) {
+        return node.text;
+    }
+    if (ts.isNumericLiteral(node)) {
+        return Number(node.text);
+    }
+    if (node.kind === ts.SyntaxKind.TrueKeyword) {
+        return true;
+    }
+    if (node.kind === ts.SyntaxKind.FalseKeyword) {
+        return false;
+    }
+    if (ts.isPrefixUnaryExpression(node)) {
+        const operand = evaluateConstantExpression(checker, node.operand, seen);
+        if (operand === null) {
+            return null;
+        }
+        switch (node.operator) {
+            case ts.SyntaxKind.MinusToken:
+                return typeof operand === "number" ? toFiniteNumber(-operand) : null;
+            case ts.SyntaxKind.PlusToken:
+                return typeof operand === "number" ? operand : null;
+            case ts.SyntaxKind.TildeToken:
+                return typeof operand === "number" ? ~operand : null;
+            case ts.SyntaxKind.ExclamationToken:
+                return typeof operand === "boolean" ? !operand : null;
+            default:
+                return null;
+        }
+    }
+    if (ts.isBinaryExpression(node)) {
+        const left = evaluateConstantExpression(checker, node.left, seen);
+        if (left === null) {
+            return null;
+        }
+        const right = evaluateConstantExpression(checker, node.right, seen);
+        if (right === null) {
+            return null;
+        }
+        return foldBinaryExpression(node.operatorToken.kind, left, right);
+    }
+    if (ts.isTemplateExpression(node)) {
+        let result = node.head.text;
+        for (const span of node.templateSpans) {
+            const substitution = toFoldedString(evaluateConstantExpression(checker, span.expression, seen));
+            if (substitution === null) {
+                return null;
+            }
+            result += substitution + span.literal.text;
+        }
+        return result;
+    }
+    if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression)) {
+        const namespaceConstant = constants_1.FOLDABLE_NAMESPACE_CONSTANTS[node.expression.text]?.[node.name.text];
+        if (namespaceConstant !== undefined) {
+            return namespaceConstant;
+        }
+    }
+    if (ts.isIdentifier(node)) {
+        const symbol = checker.getSymbolAtLocation(node);
+        return symbol === undefined ? null : resolveConstantSymbol(checker, symbol, seen);
+    }
+    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+        const symbol = (0, ast_1.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.
+ *
+ * @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.
+ */
+function resolveConstantSymbol(checker, symbol, seen) {
+    const resolved = (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
+    const declaration = resolved.valueDeclaration;
+    if (declaration === undefined) {
+        return null;
+    }
+    if (ts.isEnumMember(declaration)) {
+        const value = checker.getConstantValue(declaration);
+        return typeof value === "string" || typeof value === "number" ? value : null;
+    }
+    if (ts.isVariableDeclaration(declaration)) {
+        const statement = (0, ast_1.getContainingVariableStatement)(declaration);
+        if (statement === null || !(0, ast_1.isModuleLevelConst)(statement)) {
+            return null;
+        }
+        return getComputedDeclarationValue(checker, resolved, seen);
+    }
+    if (ts.isPropertyAssignment(declaration) || ts.isShorthandPropertyAssignment(declaration)) {
+        return (0, ast_1.isReadonlyModuleConstProperty)(declaration) ? getComputedDeclarationValue(checker, resolved, seen) : null;
+    }
+    return null;
+}
+/**
+ * Get constant value of a declaration - declared unit type first, initializer folding as fallback.
+ * 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.
+ */
+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;
+    }
+    seen.add(declaration);
+    try {
+        if ((ts.isVariableDeclaration(declaration) || ts.isPropertyAssignment(declaration)) &&
+            declaration.initializer !== undefined) {
+            return evaluateConstantExpression(checker, declaration.initializer, seen);
+        }
+        if (ts.isShorthandPropertyAssignment(declaration)) {
+            const valueSymbol = checker.getShorthandAssignmentValueSymbol(declaration);
+            return valueSymbol === undefined ? null : resolveConstantSymbol(checker, valueSymbol, seen);
+        }
+        return null;
+    }
+    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.
+ *
+ * @param checker - Program type checker.
+ * @param symbol - Symbol to resolve inline value for.
+ * @returns Literal value or null.
+ */
+function tryGetInlineValue(checker, symbol) {
+    const declaration = symbol.valueDeclaration;
+    if (declaration === undefined) {
+        return null;
+    }
+    if (ts.isEnumMember(declaration)) {
+        if (!(0, ast_1.hasInlineTag)(declaration.parent)) {
+            return null;
+        }
+        const value = checker.getConstantValue(declaration);
+        return typeof value === "string" || typeof value === "number" ? value : null;
+    }
+    if (ts.isPropertyAssignment(declaration) ||
+        ts.isShorthandPropertyAssignment(declaration) ||
+        ts.isVariableDeclaration(declaration)) {
+        const statement = (0, ast_1.getContainingVariableStatement)(declaration);
+        if (statement === null || !(0, ast_1.hasInlineTag)(statement)) {
+            return null;
+        }
+        return getComputedDeclarationValue(checker, symbol, new Set());
+    }
+    return null;
+}

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

@@ -0,0 +1,6 @@
+export * from "./ast";
+export * from "./constants";
+export * from "./errors";
+export * from "./evaluation";
+export * from "./transformers";
+export * from "./validation";

package/plugins/inline_constants/transformation/index.js

@@ -0,0 +1,22 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ast"), exports);
+__exportStar(require("./constants"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./evaluation"), exports);
+__exportStar(require("./transformers"), exports);
+__exportStar(require("./validation"), exports);

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

@@ -0,0 +1,27 @@
+import * as ts from "typescript";
+import * as lua from "typescript-to-lua";
+import { type TInlineValue } from "./constants";
+/**
+ * Create lua literal expression for provided constant value.
+ *
+ * @param value - Constant value to create literal for.
+ * @param node - Original typescript node.
+ * @returns Lua literal expression.
+ */
+export declare function createLiteralExpression(value: TInlineValue, node: ts.Node): lua.Expression;
+/**
+ * Transform property/element access expressions, inline literal values of `@inline` tagged declarations.
+ *
+ * @param node - Access expression node to transform.
+ * @param context - Transformation context.
+ * @returns Lua literal when 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.
+ *
+ * @param node - Identifier node to transform.
+ * @param context - Transformation context.
+ * @returns Lua literal when identifier resolves to a tagged constant, default transformation otherwise.
+ */
+export declare function transformIdentifierExpression(node: ts.Identifier, context: lua.TransformationContext): lua.Expression;

package/plugins/inline_constants/transformation/transformers.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLiteralExpression = createLiteralExpression;
+exports.transformAccessExpression = transformAccessExpression;
+exports.transformIdentifierExpression = transformIdentifierExpression;
+const ts = require("typescript");
+const lua = require("typescript-to-lua");
+const ast_1 = require("./ast");
+const evaluation_1 = require("./evaluation");
+/**
+ * Create lua literal expression for provided constant value.
+ *
+ * @param value - Constant value to create literal for.
+ * @param node - Original typescript node.
+ * @returns Lua literal expression.
+ */
+function createLiteralExpression(value, node) {
+    if (typeof value === "string") {
+        return lua.createStringLiteral(value, node);
+    }
+    if (typeof value === "boolean") {
+        return lua.createBooleanLiteral(value, node);
+    }
+    return value < 0
+        ? lua.createUnaryExpression(lua.createNumericLiteral(Math.abs(value), node), lua.SyntaxKind.NegationOperator, node)
+        : lua.createNumericLiteral(value, node);
+}
+/**
+ * Transform property/element access expressions, inline literal values of `@inline` tagged declarations.
+ *
+ * @param node - Access expression node to transform.
+ * @param context - Transformation context.
+ * @returns Lua literal when access resolves to a tagged constant, default transformation otherwise.
+ */
+function transformAccessExpression(node, context) {
+    const symbol = (0, ast_1.resolveMemberSymbol)(context.checker, node);
+    const value = symbol === null ? null : (0, evaluation_1.tryGetInlineValue)(context.checker, symbol);
+    return value === null ? context.superTransformExpression(node) : createLiteralExpression(value, node);
+}
+/**
+ * Transform identifier expressions, inline literal values of `@inline` tagged scalar constants.
+ *
+ * @param node - Identifier node to transform.
+ * @param context - Transformation context.
+ * @returns Lua literal when identifier resolves to a tagged constant, default transformation otherwise.
+ */
+function transformIdentifierExpression(node, context) {
+    if ((0, ast_1.isValueUsagePosition)(node)) {
+        let symbol = context.checker.getSymbolAtLocation(node);
+        if (symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0) {
+            symbol = context.checker.getAliasedSymbol(symbol);
+        }
+        if (symbol?.valueDeclaration !== undefined && ts.isVariableDeclaration(symbol.valueDeclaration)) {
+            const value = (0, evaluation_1.tryGetInlineValue)(context.checker, symbol);
+            if (value !== null) {
+                return createLiteralExpression(value, node);
+            }
+        }
+    }
+    return context.superTransformExpression(node);
+}

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

@@ -0,0 +1,25 @@
+import * as ts from "typescript";
+import type * as lua from "typescript-to-lua";
+/**
+ * Validate `@inline` tagged variable statement and push diagnostics for not supported shapes.
+ * Tagged statements must be module-level `const` declarations with compile-time computable scalars
+ * or flat `as const` object literals.
+ *
+ * @param statement - Tagged variable statement to validate.
+ * @param context - Transformation context.
+ */
+export declare function validateVariableStatement(statement: ts.VariableStatement, context: lua.TransformationContext): void;
+/**
+ * Validate `@inline` tagged enum declaration and push diagnostics for members without constant values.
+ *
+ * @param declaration - Tagged enum declaration to validate.
+ * @param context - Transformation context.
+ */
+export declare function validateEnumDeclaration(declaration: ts.EnumDeclaration, context: lua.TransformationContext): void;
+/**
+ * Scan program source files for `@inline` tags on unsupported declaration kinds.
+ *
+ * @param program - Program to scan.
+ * @returns List of produced diagnostics.
+ */
+export declare function validateTopLevelTags(program: ts.Program): Array<ts.Diagnostic>;

package/plugins/inline_constants/transformation/validation.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateVariableStatement = validateVariableStatement;
+exports.validateEnumDeclaration = validateEnumDeclaration;
+exports.validateTopLevelTags = validateTopLevelTags;
+const ts = require("typescript");
+const ast_1 = require("./ast");
+const errors_1 = require("./errors");
+const evaluation_1 = require("./evaluation");
+/**
+ * Validate `@inline` tagged variable statement and push diagnostics for not supported shapes.
+ * Tagged statements must be module-level `const` declarations with compile-time computable scalars
+ * or flat `as const` object literals.
+ *
+ * @param statement - Tagged variable statement to validate.
+ * @param context - Transformation context.
+ */
+function validateVariableStatement(statement, context) {
+    if (!ts.isSourceFile(statement.parent)) {
+        context.diagnostics.push((0, errors_1.createNotModuleLevelError)(statement));
+    }
+    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) {
+        context.diagnostics.push((0, errors_1.createNotConstError)(statement));
+        return;
+    }
+    for (const declaration of statement.declarationList.declarations) {
+        const name = declaration.name.getText();
+        const initializer = (0, ast_1.unwrapInitializer)(declaration.initializer);
+        if (initializer !== null && ts.isObjectLiteralExpression(initializer)) {
+            if (!(0, ast_1.hasAsConstAssertion)(declaration.initializer)) {
+                context.diagnostics.push((0, errors_1.createNotAsConstObjectError)(declaration, name));
+                continue;
+            }
+            const type = context.checker.getTypeAtLocation(declaration);
+            for (const property of type.getProperties()) {
+                const propertyDeclaration = property.valueDeclaration;
+                const sourceStatement = propertyDeclaration === undefined ? null : (0, ast_1.getContainingVariableStatement)(propertyDeclaration);
+                if (sourceStatement !== statement && (sourceStatement === null || !(0, ast_1.hasInlineTag)(sourceStatement))) {
+                    context.diagnostics.push((0, errors_1.createForeignPropertyError)(propertyDeclaration ?? declaration, name, property.name));
+                }
+                else if ((0, evaluation_1.getComputedDeclarationValue)(context.checker, property, new Set()) === null) {
+                    context.diagnostics.push((0, errors_1.createNotLiteralPropertyError)(propertyDeclaration ?? declaration, name, property.name));
+                }
+            }
+        }
+        else {
+            const symbol = context.checker.getSymbolAtLocation(declaration.name);
+            if (symbol === undefined || (0, evaluation_1.getComputedDeclarationValue)(context.checker, symbol, new Set()) === null) {
+                context.diagnostics.push((0, errors_1.createNotLiteralConstantError)(declaration, name));
+            }
+        }
+    }
+}
+/**
+ * Validate `@inline` tagged enum declaration and push diagnostics for members without constant values.
+ *
+ * @param declaration - Tagged enum declaration to validate.
+ * @param context - Transformation context.
+ */
+function validateEnumDeclaration(declaration, context) {
+    for (const member of declaration.members) {
+        if (context.checker.getConstantValue(member) === undefined) {
+            context.diagnostics.push((0, errors_1.createNotConstantEnumMemberError)(member, member.name.getText()));
+        }
+    }
+}
+/**
+ * Scan program source files for `@inline` tags on unsupported declaration kinds.
+ *
+ * @param program - Program to scan.
+ * @returns List of produced diagnostics.
+ */
+function validateTopLevelTags(program) {
+    const diagnostics = [];
+    for (const sourceFile of program.getSourceFiles()) {
+        if (sourceFile.isDeclarationFile) {
+            continue;
+        }
+        for (const statement of sourceFile.statements) {
+            if ((0, ast_1.hasInlineTag)(statement) && !ts.isVariableStatement(statement) && !ts.isEnumDeclaration(statement)) {
+                diagnostics.push((0, errors_1.createUnsupportedDeclarationError)(statement));
+            }
+        }
+    }
+    return diagnostics;
+}