xray16 1.6.2 → 1.6.4

package/plugins/inline_constants/transformation/transformers.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFoldedExpression = createFoldedExpression;
+exports.transformAccessExpression = transformAccessExpression;
+exports.transformIdentifierExpression = transformIdentifierExpression;
+exports.transformImportDeclaration = transformImportDeclaration;
+const ts = require("typescript");
+const lua = require("typescript-to-lua");
+const ast_1 = require("./ast");
+const evaluation_1 = require("./evaluation");
+const virtual_1 = require("./virtual");
+const NUMERIC_KEY_PATTERN = /^(0|[1-9][0-9]*)$/;
+const TREE_LUA_OPERATORS = {
+    "+": lua.SyntaxKind.AdditionOperator,
+    "-": lua.SyntaxKind.SubtractionOperator,
+    "*": lua.SyntaxKind.MultiplicationOperator,
+    "/": lua.SyntaxKind.DivisionOperator,
+    "**": lua.SyntaxKind.PowerOperator,
+};
+const fileBindingUsageCache = new WeakMap();
+/**
+ * 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 - Folded value to create expression for.
+ * @param node - Original TypeScript node.
+ * @returns Lua expression.
+ */
+function createFoldedExpression(value, node) {
+    if (typeof value === "string") {
+        return lua.createStringLiteral(value, node);
+    }
+    if (typeof value === "boolean") {
+        return lua.createBooleanLiteral(value, node);
+    }
+    if (typeof value === "number") {
+        return value < 0
+            ? lua.createUnaryExpression(lua.createNumericLiteral(Math.abs(value), node), lua.SyntaxKind.NegationOperator, node)
+            : lua.createNumericLiteral(value, node);
+    }
+    switch (value.kind) {
+        case "engine-ref": {
+            let expression = lua.createIdentifier(value.path[0]);
+            for (const member of value.path.slice(1)) {
+                expression = lua.createTableIndexExpression(expression, lua.createStringLiteral(member), node);
+            }
+            return expression;
+        }
+        case "binary":
+            return lua.createBinaryExpression(createFoldedExpression(value.left, node), createFoldedExpression(value.right, node), TREE_LUA_OPERATORS[value.operator], node);
+        case "negate":
+            return lua.createUnaryExpression(createFoldedExpression(value.operand, node), lua.SyntaxKind.NegationOperator, node);
+    }
+}
+/**
+ * Create a Lua table literal that replaces an object spread of a `@virtual` object.
+ * Returns null when the referenced symbol is not a virtual object or an entry cannot be computed.
+ *
+ * @param checker - Program type checker.
+ * @param symbol - Referenced symbol of the spread expression.
+ * @param node - Original TypeScript node.
+ * @returns Lua table literal or null.
+ */
+function tryCreateVirtualSpreadTable(checker, symbol, node) {
+    if ((0, virtual_1.getVirtualDeclaration)(checker, symbol) === null) {
+        return null;
+    }
+    const entries = (0, virtual_1.getVirtualObjectEntries)(checker, symbol);
+    if (entries === null) {
+        return null;
+    }
+    const fields = entries.map(([name, value]) => {
+        const key = NUMERIC_KEY_PATTERN.test(name)
+            ? lua.createNumericLiteral(Number(name))
+            : lua.createStringLiteral(name);
+        return lua.createTableFieldExpression(createFoldedExpression(value, node), key);
+    });
+    return lua.createTableExpression(fields, node);
+}
+/**
+ * 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 the access resolves to a tagged constant, default transformation otherwise.
+ */
+function transformAccessExpression(node, context) {
+    const symbol = (0, evaluation_1.resolveMemberSymbol)(context.checker, node);
+    if (symbol === null) {
+        return context.superTransformExpression(node);
+    }
+    const value = (0, evaluation_1.tryGetInlineValue)(context.checker, symbol);
+    if (value !== null) {
+        return createFoldedExpression(value, node);
+    }
+    if (node.parent !== undefined && ts.isSpreadAssignment(node.parent)) {
+        const table = tryCreateVirtualSpreadTable(context.checker, symbol, node);
+        if (table !== null) {
+            return table;
+        }
+    }
+    return context.superTransformExpression(node);
+}
+/**
+ * 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 the identifier resolves to a tagged constant, default transformation otherwise.
+ */
+function transformIdentifierExpression(node, context) {
+    if (node.parent !== undefined && ts.isSpreadAssignment(node.parent)) {
+        const symbol = context.checker.getSymbolAtLocation(node);
+        const table = symbol === undefined ? null : tryCreateVirtualSpreadTable(context.checker, symbol, node);
+        if (table !== null) {
+            return table;
+        }
+        return context.superTransformExpression(node);
+    }
+    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 createFoldedExpression(value, node);
+            }
+        }
+    }
+    return context.superTransformExpression(node);
+}
+/**
+ * Get a map of import binding symbols to whether each binding has usages that block removal in the file.
+ * Bindings with only erasable references (inlined accesses, expanded spreads, type positions) can be stripped.
+ *
+ * @param checker - Program type checker.
+ * @param sourceFile - Source file to analyze.
+ * @returns Map of import alias symbols to whether each alias has a blocking usage.
+ */
+function getFileBindingUsage(checker, sourceFile) {
+    const cached = fileBindingUsageCache.get(sourceFile);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const usage = new Map();
+    visitNode(sourceFile);
+    fileBindingUsageCache.set(sourceFile, usage);
+    return usage;
+    function markImportBindingUsage(symbol, isBlocking) {
+        const declaration = symbol?.declarations?.[0];
+        if (symbol === undefined || declaration === undefined || !ts.isImportSpecifier(declaration)) {
+            return;
+        }
+        if (isBlocking) {
+            usage.set(symbol, true);
+        }
+        else if (!usage.has(symbol)) {
+            usage.set(symbol, false);
+        }
+    }
+    function visitNode(node) {
+        // References inside erased virtual statements never survive to emitted output:
+        if ((ts.isVariableStatement(node) || ts.isEnumDeclaration(node)) && (0, ast_1.hasVirtualTag)(node)) {
+            return;
+        }
+        if (ts.isIdentifier(node) && node.parent !== undefined && !ts.isImportSpecifier(node.parent)) {
+            // Re-exports and shorthand properties emit direct references to import bindings:
+            if (ts.isExportSpecifier(node.parent)) {
+                markImportBindingUsage(checker.getExportSpecifierLocalTargetSymbol(node.parent), true);
+            }
+            else if (ts.isShorthandPropertyAssignment(node.parent)) {
+                markImportBindingUsage(checker.getShorthandAssignmentValueSymbol(node.parent), true);
+            }
+            else {
+                const symbol = checker.getSymbolAtLocation(node);
+                if (symbol !== undefined) {
+                    const isVirtual = (0, virtual_1.getVirtualDeclaration)(checker, symbol) !== null;
+                    markImportBindingUsage(symbol, !(0, virtual_1.isErasableReference)(checker, node, symbol, isVirtual));
+                }
+            }
+        }
+        node.forEachChild(visitNode);
+    }
+}
+/**
+ * Check whether an import specifier resolves to a declaration tagged with `@inline` or `@virtual`.
+ *
+ * @param checker - Program type checker.
+ * @param symbol - Import alias symbol to check.
+ * @returns Whether the specifier target is tagged.
+ */
+function isTaggedImportTarget(checker, symbol) {
+    const declaration = (0, virtual_1.resolveAliasedSymbol)(checker, symbol).valueDeclaration;
+    if (declaration === undefined) {
+        return false;
+    }
+    if (ts.isEnumDeclaration(declaration)) {
+        return (0, ast_1.hasInlineTag)(declaration);
+    }
+    if (ts.isVariableDeclaration(declaration)) {
+        const statement = (0, ast_1.getContainingVariableStatement)(declaration);
+        return statement !== null && (0, ast_1.hasInlineTag)(statement);
+    }
+    return false;
+}
+/**
+ * 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.
+ */
+function transformImportDeclaration(statement, context) {
+    const clause = statement.importClause;
+    if (clause === undefined ||
+        clause.isTypeOnly ||
+        clause.name !== undefined ||
+        clause.namedBindings === undefined ||
+        !ts.isNamedImports(clause.namedBindings)) {
+        return context.superTransformStatements(statement);
+    }
+    const checker = context.checker;
+    const usage = getFileBindingUsage(checker, context.sourceFile);
+    const kept = [];
+    let hasRuntimeBindings = false;
+    for (const specifier of clause.namedBindings.elements) {
+        if (specifier.isTypeOnly) {
+            kept.push(specifier);
+            continue;
+        }
+        const symbol = checker.getSymbolAtLocation(specifier.name);
+        if (symbol === undefined) {
+            kept.push(specifier);
+            hasRuntimeBindings = true;
+            continue;
+        }
+        // Pure type imports produce no runtime bindings:
+        if (((0, virtual_1.resolveAliasedSymbol)(checker, symbol).flags & ts.SymbolFlags.Value) === 0) {
+            kept.push(specifier);
+            continue;
+        }
+        // Tagged targets with only erased usages and bindings with no surviving usages at all are droppable:
+        const isDroppable = (isTaggedImportTarget(checker, symbol) || !usage.has(symbol)) && usage.get(symbol) !== true;
+        if (isDroppable) {
+            continue;
+        }
+        kept.push(specifier);
+        hasRuntimeBindings = true;
+    }
+    if (kept.length === clause.namedBindings.elements.length) {
+        return context.superTransformStatements(statement);
+    }
+    if (!hasRuntimeBindings) {
+        const target = (0, virtual_1.resolveModuleSourceFile)(checker, statement.moduleSpecifier);
+        if (target !== null && (0, virtual_1.isPureConstantsModule)(checker, target)) {
+            return [];
+        }
+        // Side effects are possible, keep the module require without bindings:
+        return context.superTransformStatements(ts.factory.updateImportDeclaration(statement, statement.modifiers, undefined, statement.moduleSpecifier, undefined));
+    }
+    return context.superTransformStatements(ts.factory.updateImportDeclaration(statement, statement.modifiers, ts.factory.updateImportClause(clause, clause.isTypeOnly, clause.name, ts.factory.updateNamedImports(clause.namedBindings, kept)), statement.moduleSpecifier, undefined));
+}

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

@@ -0,0 +1,26 @@
+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 computable values.
+ * Members may be constant for TypeScript or initialized with foldable engine references.
+ *
+ * @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,87 @@
+"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 computable values.
+ * Members may be constant for TypeScript or initialized with foldable engine references.
+ *
+ * @param declaration - Tagged enum declaration to validate.
+ * @param context - Transformation context.
+ */
+function validateEnumDeclaration(declaration, context) {
+    for (const member of declaration.members) {
+        if (!(0, evaluation_1.isComputableEnumMember)(context.checker, member)) {
+            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;
+}

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

@@ -0,0 +1,74 @@
+import * as ts from "typescript";
+import { type TFoldedValue } from "./constants";
+/**
+ * Resolve a symbol through import aliases.
+ *
+ * @param checker - Program type checker.
+ * @param symbol - Symbol to resolve.
+ * @returns Resolved symbol.
+ */
+export declare function resolveAliasedSymbol(checker: ts.TypeChecker, symbol: ts.Symbol): ts.Symbol;
+/**
+ * Get the `@virtual` declaration behind the provided symbol, if any.
+ *
+ * @param checker - Program type checker.
+ * @param symbol - Symbol to check.
+ * @returns Virtual tagged variable statement, enum declaration, or null.
+ */
+export declare function getVirtualDeclaration(checker: ts.TypeChecker, symbol: ts.Symbol): ts.VariableStatement | ts.EnumDeclaration | null;
+/**
+ * Check whether an identifier reference to a tagged declaration is erasable.
+ * Erasable references are inlined, expanded, or stripped during transformation.
+ *
+ * @param checker - Program type checker.
+ * @param node - Identifier reference to check.
+ * @param symbol - Resolved symbol of the identifier.
+ * @param isVirtualSpreadAllowed - Whether object spread positions count as erasable.
+ * @returns Whether the reference is erasable.
+ */
+export declare function isErasableReference(checker: ts.TypeChecker, node: ts.Identifier, symbol: ts.Symbol, isVirtualSpreadAllowed: boolean): boolean;
+/**
+ * Resolve the source file for a module referenced by an import or export declaration specifier.
+ *
+ * @param checker - Program type checker.
+ * @param moduleSpecifier - Module specifier expression.
+ * @returns Resolved source file or null.
+ */
+export declare function resolveModuleSourceFile(checker: ts.TypeChecker, moduleSpecifier: ts.Expression): ts.SourceFile | null;
+/**
+ * Check whether a module has no side effects on load. This silent analysis decides whether a require can be dropped.
+ * Pure modules contain only type-only imports, tagged constants, constant enums, types and
+ * imports or re-exports of other pure modules, including barrel files.
+ *
+ * @param checker - Program type checker.
+ * @param sourceFile - Module source file to check.
+ * @param seen - Modules on current resolution path, guards from circular imports.
+ * @returns Whether module load has no side effects.
+ */
+export declare function isPureConstantsModule(checker: ts.TypeChecker, sourceFile: ts.SourceFile, seen?: Set<ts.SourceFile>): boolean;
+/**
+ * Validate strict purity for a module containing `@virtual` declarations.
+ * This is stricter than silent analysis: value imports and value re-exports are rejected even from pure modules,
+ * so erasing requires to this module can never silently drop transitive loads.
+ *
+ * @param checker - Program type checker.
+ * @param sourceFile - Module source file to validate.
+ * @returns List of produced diagnostics.
+ */
+export declare function validateVirtualModulePurity(checker: ts.TypeChecker, sourceFile: ts.SourceFile): Array<ts.Diagnostic>;
+/**
+ * Scan the program for references to `@virtual` declarations that cannot be erased, and for impure modules
+ * containing `@virtual` declarations.
+ *
+ * @param program - Program to scan.
+ * @returns List of produced diagnostics.
+ */
+export declare function collectVirtualDiagnostics(program: ts.Program): Array<ts.Diagnostic>;
+/**
+ * Get entries of a virtual object declaration for spread expansion.
+ *
+ * @param checker - Program type checker.
+ * @param symbol - Virtual object symbol.
+ * @returns List of property name/value pairs, or null when an entry is not computable.
+ */
+export declare function getVirtualObjectEntries(checker: ts.TypeChecker, symbol: ts.Symbol): Array<[string, TFoldedValue]> | null;