xray16 1.6.1 → 1.6.3

package/README.md

@@ -62,6 +62,7 @@ Plugins can be included in [tstl tsconfig](https://typescripttolua.github.io/doc
       { "name": "xray16/plugins/inject_filename" },
       { "name": "xray16/plugins/from_cast_utils" },
       { "name": "xray16/plugins/optimize_return_ternary" },
+      { "name": "xray16/plugins/inline_constants/plugin" },
       { "name": "xray16/plugins/inject_tracy_zones" }
     ]
   }
@@ -112,6 +113,43 @@ All the calls are completely gets stripped and removed from runtime.
 Plugin rewrites returned ternary expressions into direct `if` / `else` branch returns when it is safe.\
 This avoids temporary result locals for patterns like `return condition ? first : second` while preserving general ternary semantics.
 
+### inline_constants
+
+Plugin inlining compile-time constant values of `@inline` JSDoc tagged declarations.\
+Supported targets are enums, module-level `as const` object literals and module-level scalar constants.\
+Member accesses are replaced with literal values in place, while original tables are still emitted,
+so iteration / reverse mapping / whole-object usages keep working.\
+Tagged declarations act as an explicit whitelist and produce build errors when they cannot be inlined.
+
+Values may be literals or expressions foldable on build time - arithmetic, string concatenation,
+template literals and references to other constant declarations (enum members, module-level const scalars,
+`as const` object properties, whitelisted namespace constants like `math.pi`).\
+Runtime-dependent expressions (function calls, mutable object properties, values producing NaN / Infinity)
+are rejected with build errors.
+
+```typescript
+/**
+ * @inline
+ */
+export const medkits = {
+  medkit: "medkit",
+  medkit_army: "medkit_army",
+} as const;
+
+/**
+ * @inline
+ */
+export const TIMEOUT: number = 60 * 1000;
+
+/**
+ * @inline
+ */
+export const PI_DEGREE: number = math.pi / 180;
+
+// Build time: `medkits.medkit_army` access is emitted as plain "medkit_army" string literal.
+// Build time: `TIMEOUT` reference is emitted as 60000, `PI_DEGREE` as 0.017453292519943295.
+```
+
 ### inject_tracy_zones
 
 Plugin designed to work specifically with [tracy profiler](https://github.com/wolfpld/tracy).\

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xray16",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "author": "Neloreck",
   "repository": "https://github.com/xray-forge/xray-16-types",
   "homepage": "https://xray-forge.github.io/xray-16-types/index.html",
@@ -11,10 +11,11 @@
     "prepublish": "npm run build",
     "prepack": "npm run build",
     "build": "npm run build:plugins && npm run build:types",
-    "build:plugins": "tsc -p ./src/tsconfig.json",
+    "build:plugins": "tsc -p ./src/tsconfig.build.json",
     "build:types": "rollup -c rollup.dts.config.mjs",
     "build:docs": "typedoc",
-    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p ./src/tsconfig.json",
     "typedoc": "typedoc",
     "format": "prettier --write \"**/*.(js|ts|tsx|md)\" && eslint . --fix",
     "lint": "eslint ."
@@ -24,6 +25,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
+    "@types/jest": "^29.5.14",
     "@types/node": "22.10.2",
     "@typescript-eslint/eslint-plugin": "^8.62.0",
     "@typescript-eslint/parser": "^8.62.0",
@@ -34,9 +36,11 @@
     "eslint-plugin-jest": "^29.15.2",
     "eslint-plugin-jsdoc": "^63.0.7",
     "globals": "^17.7.0",
+    "jest": "^29.7.0",
     "prettier": "^3.4.2",
     "rollup": "^4.62.2",
     "rollup-plugin-dts": "^6.4.1",
+    "ts-jest": "^29.4.11",
     "typedoc": "^0.27.5",
     "typescript": "5.7.2",
     "typescript-eslint": "^8.62.0",

package/plugins/inline_constants/plugin.d.ts

@@ -0,0 +1,14 @@
+import { type Plugin } from "typescript-to-lua";
+/**
+ * Plugin that inlines compile-time constant values of `@inline` JSDoc tagged declarations.
+ *
+ * Supported targets are enums, module-level `as const` object literals and module-level scalar constants.
+ * Values may be literals or expressions foldable on build time - arithmetic, string concatenation,
+ * template literals and references to other constant declarations (enum members, const scalars,
+ * `as const` object properties, whitelisted constants like 'math.pi').
+ * Tagged declarations act as an explicit whitelist - member accesses are replaced with literal values in place,
+ * while original tables are still emitted, so iteration / reverse mapping / whole-object usages keep working.
+ * Tagged declarations that cannot be inlined produce build errors instead of silently emitting property lookups.
+ */
+declare const plugin: Plugin;
+export default plugin;

package/plugins/inline_constants/plugin.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ts = require("typescript");
+const transformation_1 = require("./transformation");
+/**
+ * Plugin that inlines compile-time constant values of `@inline` JSDoc tagged declarations.
+ *
+ * Supported targets are enums, module-level `as const` object literals and module-level scalar constants.
+ * Values may be literals or expressions foldable on build time - arithmetic, string concatenation,
+ * template literals and references to other constant declarations (enum members, const scalars,
+ * `as const` object properties, whitelisted constants like 'math.pi').
+ * Tagged declarations act as an explicit whitelist - member accesses are replaced with literal values in place,
+ * while original tables are still emitted, so iteration / reverse mapping / whole-object usages keep working.
+ * Tagged declarations that cannot be inlined produce build errors instead of silently emitting property lookups.
+ */
+const plugin = {
+    beforeTransform(program) {
+        // Force binder to assign node parents before any 'getJSDocTags' call,
+        // otherwise empty results are computed for parent-less nodes and cached on them forever.
+        program.getTypeChecker();
+        const diagnostics = (0, transformation_1.validateTopLevelTags)(program);
+        if (diagnostics.length > 0) {
+            return diagnostics;
+        }
+    },
+    visitors: {
+        [ts.SyntaxKind.PropertyAccessExpression]: transformation_1.transformAccessExpression,
+        [ts.SyntaxKind.ElementAccessExpression]: transformation_1.transformAccessExpression,
+        [ts.SyntaxKind.Identifier]: transformation_1.transformIdentifierExpression,
+        [ts.SyntaxKind.VariableStatement]: (statement, context) => {
+            if ((0, transformation_1.hasInlineTag)(statement)) {
+                (0, transformation_1.validateVariableStatement)(statement, context);
+            }
+            return context.superTransformStatements(statement);
+        },
+        [ts.SyntaxKind.EnumDeclaration]: (declaration, context) => {
+            if ((0, transformation_1.hasInlineTag)(declaration)) {
+                (0, transformation_1.validateEnumDeclaration)(declaration, context);
+            }
+            return context.superTransformStatements(declaration);
+        },
+    },
+};
+exports.default = plugin;

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

@@ -0,0 +1,60 @@
+import * as ts from "typescript";
+/**
+ * Check whether node is annotated with `@inline` JSDoc tag.
+ *
+ * @param node - Node to check tags for.
+ * @returns Whether the node has `@inline` JSDoc tag.
+ */
+export declare function hasInlineTag(node: ts.Node): boolean;
+/**
+ * Find variable statement containing provided declaration node, if any.
+ *
+ * @param node - Declaration node to walk up from.
+ * @returns Containing variable statement or null.
+ */
+export declare function getContainingVariableStatement(node: ts.Node): ts.VariableStatement | null;
+/**
+ * Unwrap initializer expression from as/satisfies/parenthesized wrappers.
+ *
+ * @param expression - Initializer expression to unwrap.
+ * @returns Unwrapped expression or null.
+ */
+export declare function unwrapInitializer(expression?: ts.Expression): ts.Expression | null;
+/**
+ * Check whether variable statement is a module-level `const` declaration.
+ *
+ * @param statement - Variable statement to check.
+ * @returns Whether statement is module-level const.
+ */
+export declare function isModuleLevelConst(statement: ts.VariableStatement): boolean;
+/**
+ * Check whether expression is wrapped with `as const` assertion, possibly through parens/satisfies wrappers.
+ *
+ * @param expression - Expression to check.
+ * @returns Whether expression has `as const` assertion.
+ */
+export declare function hasAsConstAssertion(expression?: ts.Expression): boolean;
+/**
+ * Check whether property is declared inside an `as const` object literal assigned to a module-level const.
+ * Such properties are readonly and cannot be legally reassigned, so their values are stable at runtime.
+ *
+ * @param declaration - Property declaration to check.
+ * @returns Whether property value is safe to fold.
+ */
+export declare function isReadonlyModuleConstProperty(declaration: ts.PropertyAssignment | ts.ShorthandPropertyAssignment): boolean;
+/**
+ * Check whether identifier node is used in a value position where it can be replaced with a literal.
+ *
+ * @param node - Identifier node to check.
+ * @returns Whether identifier is a replace-able value usage.
+ */
+export declare function isValueUsagePosition(node: ts.Identifier): boolean;
+/**
+ * Resolve member symbol for property/element access expression.
+ * Element access with literal key is resolved through object type when direct symbol resolution fails.
+ *
+ * @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;

package/plugins/inline_constants/transformation/ast.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasInlineTag = hasInlineTag;
+exports.getContainingVariableStatement = getContainingVariableStatement;
+exports.unwrapInitializer = unwrapInitializer;
+exports.isModuleLevelConst = isModuleLevelConst;
+exports.hasAsConstAssertion = hasAsConstAssertion;
+exports.isReadonlyModuleConstProperty = isReadonlyModuleConstProperty;
+exports.isValueUsagePosition = isValueUsagePosition;
+exports.resolveMemberSymbol = resolveMemberSymbol;
+const ts = require("typescript");
+const constants_1 = require("./constants");
+/**
+ * Check whether node is annotated with `@inline` JSDoc tag.
+ *
+ * @param node - Node to check tags for.
+ * @returns Whether the node has `@inline` JSDoc tag.
+ */
+function hasInlineTag(node) {
+    return ts.getJSDocTags(node).some((it) => it.tagName.text === constants_1.INLINE_TAG);
+}
+/**
+ * Find variable statement containing provided declaration node, if any.
+ *
+ * @param node - Declaration node to walk up from.
+ * @returns Containing variable statement or null.
+ */
+function getContainingVariableStatement(node) {
+    let current = node;
+    while (current !== undefined && !ts.isSourceFile(current)) {
+        if (ts.isVariableStatement(current)) {
+            return current;
+        }
+        current = current.parent;
+    }
+    return null;
+}
+/**
+ * Unwrap initializer expression from as/satisfies/parenthesized wrappers.
+ *
+ * @param expression - Initializer expression to unwrap.
+ * @returns Unwrapped expression or null.
+ */
+function unwrapInitializer(expression) {
+    let current = expression ?? null;
+    while (current !== null &&
+        (ts.isAsExpression(current) ||
+            ts.isSatisfiesExpression(current) ||
+            ts.isParenthesizedExpression(current) ||
+            ts.isTypeAssertionExpression(current))) {
+        current = current.expression;
+    }
+    return current;
+}
+/**
+ * Check whether variable statement is a module-level `const` declaration.
+ *
+ * @param statement - Variable statement to check.
+ * @returns Whether statement is module-level const.
+ */
+function isModuleLevelConst(statement) {
+    return ts.isSourceFile(statement.parent) && (statement.declarationList.flags & ts.NodeFlags.Const) !== 0;
+}
+/**
+ * Check whether expression is wrapped with `as const` assertion, possibly through parens/satisfies wrappers.
+ *
+ * @param expression - Expression to check.
+ * @returns Whether expression has `as const` assertion.
+ */
+function hasAsConstAssertion(expression) {
+    let current = expression;
+    while (current !== undefined) {
+        if (ts.isAsExpression(current) &&
+            ts.isTypeReferenceNode(current.type) &&
+            current.type.typeName.getText() === "const") {
+            return true;
+        }
+        if (ts.isAsExpression(current) || ts.isParenthesizedExpression(current) || ts.isSatisfiesExpression(current)) {
+            current = current.expression;
+        }
+        else {
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * Check whether property is declared inside an `as const` object literal assigned to a module-level const.
+ * Such properties are readonly and cannot be legally reassigned, so their values are stable at runtime.
+ *
+ * @param declaration - Property declaration to check.
+ * @returns Whether property value is safe to fold.
+ */
+function isReadonlyModuleConstProperty(declaration) {
+    let sawAsConst = false;
+    let current = declaration.parent;
+    while (current !== undefined && !ts.isVariableDeclaration(current)) {
+        if (ts.isAsExpression(current) &&
+            ts.isTypeReferenceNode(current.type) &&
+            current.type.typeName.getText() === "const") {
+            sawAsConst = true;
+        }
+        if (!ts.isObjectLiteralExpression(current) &&
+            !ts.isPropertyAssignment(current) &&
+            !ts.isAsExpression(current) &&
+            !ts.isParenthesizedExpression(current) &&
+            !ts.isSatisfiesExpression(current)) {
+            return false;
+        }
+        current = current.parent;
+    }
+    if (current === undefined || !sawAsConst) {
+        return false;
+    }
+    const statement = getContainingVariableStatement(current);
+    return statement !== null && isModuleLevelConst(statement);
+}
+/**
+ * Check whether identifier node is used in a value position where it can be replaced with a literal.
+ *
+ * @param node - Identifier node to check.
+ * @returns Whether identifier is a replace-able value usage.
+ */
+function isValueUsagePosition(node) {
+    const parent = node.parent;
+    if (parent === undefined || ts.isPartOfTypeNode(node)) {
+        return false;
+    }
+    if (ts.isPropertyAccessExpression(parent)) {
+        return parent.expression === node;
+    }
+    if (ts.isPropertyAssignment(parent) ||
+        ts.isBindingElement(parent) ||
+        ts.isParameter(parent) ||
+        ts.isEnumMember(parent) ||
+        ts.isPropertyDeclaration(parent) ||
+        ts.isVariableDeclaration(parent)) {
+        return parent.initializer === node;
+    }
+    if (ts.isShorthandPropertyAssignment(parent) ||
+        ts.isImportSpecifier(parent) ||
+        ts.isImportClause(parent) ||
+        ts.isNamespaceImport(parent) ||
+        ts.isExportSpecifier(parent) ||
+        ts.isNamespaceExport(parent) ||
+        ts.isImportEqualsDeclaration(parent) ||
+        ts.isQualifiedName(parent) ||
+        ts.isLabeledStatement(parent) ||
+        ts.isBreakOrContinueStatement(parent)) {
+        return false;
+    }
+    if (ts.isFunctionDeclaration(parent) ||
+        ts.isFunctionExpression(parent) ||
+        ts.isClassDeclaration(parent) ||
+        ts.isClassExpression(parent) ||
+        ts.isMethodDeclaration(parent) ||
+        ts.isGetAccessorDeclaration(parent) ||
+        ts.isSetAccessorDeclaration(parent) ||
+        ts.isModuleDeclaration(parent) ||
+        ts.isEnumDeclaration(parent) ||
+        ts.isInterfaceDeclaration(parent) ||
+        ts.isTypeAliasDeclaration(parent)) {
+        return parent.name !== node;
+    }
+    return true;
+}
+/**
+ * Resolve member symbol for property/element access expression.
+ * Element access with literal key is resolved through object type when direct symbol resolution fails.
+ *
+ * @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) &&
+        (ts.isStringLiteralLike(node.argumentExpression) || ts.isNumericLiteral(node.argumentExpression))) {
+        return checker.getTypeAtLocation(node.expression).getProperty(node.argumentExpression.text) ?? null;
+    }
+    return null;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * JSDoc tag marking declarations as whitelisted for compile-time inlining.
+ */
+export declare const INLINE_TAG: string;
+/**
+ * Value types that can be inlined as lua literals.
+ */
+export type TInlineValue = string | number | boolean;
+/**
+ * Numeric namespace constants that are identical IEEE 754 doubles in build environment and LuaJIT runtime.
+ * Covers both TS 'Math' and lua 'math' namespaces, function calls are intentionally not supported
+ * since libm implementations may differ between build machine and game runtime.
+ */
+export declare const FOLDABLE_NAMESPACE_CONSTANTS: Record<string, Record<string, number>>;

package/plugins/inline_constants/transformation/constants.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOLDABLE_NAMESPACE_CONSTANTS = exports.INLINE_TAG = void 0;
+/**
+ * JSDoc tag marking declarations as whitelisted for compile-time inlining.
+ */
+exports.INLINE_TAG = "inline";
+/**
+ * Numeric namespace constants that are identical IEEE 754 doubles in build environment and LuaJIT runtime.
+ * Covers both TS 'Math' and lua 'math' namespaces, function calls are intentionally not supported
+ * since libm implementations may differ between build machine and game runtime.
+ */
+exports.FOLDABLE_NAMESPACE_CONSTANTS = {
+    Math: {
+        E: Math.E,
+        LN10: Math.LN10,
+        LN2: Math.LN2,
+        LOG10E: Math.LOG10E,
+        LOG2E: Math.LOG2E,
+        PI: Math.PI,
+        SQRT1_2: Math.SQRT1_2,
+        SQRT2: Math.SQRT2,
+    },
+    math: {
+        pi: Math.PI,
+    },
+};

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

@@ -0,0 +1,24 @@
+export declare const createUnsupportedDeclarationError: ((node: import("typescript").Node, ...args: any[]) => import("typescript").Diagnostic) & {
+    code: number;
+};
+export declare const createNotModuleLevelError: ((node: import("typescript").Node, ...args: any[]) => import("typescript").Diagnostic) & {
+    code: number;
+};
+export declare const createNotConstError: ((node: import("typescript").Node, ...args: any[]) => import("typescript").Diagnostic) & {
+    code: number;
+};
+export declare const createNotAsConstObjectError: ((node: import("typescript").Node, name: string) => import("typescript").Diagnostic) & {
+    code: number;
+};
+export declare const createNotLiteralConstantError: ((node: import("typescript").Node, name: string) => import("typescript").Diagnostic) & {
+    code: number;
+};
+export declare const createNotLiteralPropertyError: ((node: import("typescript").Node, object: string, property: string) => import("typescript").Diagnostic) & {
+    code: number;
+};
+export declare const createForeignPropertyError: ((node: import("typescript").Node, object: string, property: string) => import("typescript").Diagnostic) & {
+    code: number;
+};
+export declare const createNotConstantEnumMemberError: ((node: import("typescript").Node, name: string) => import("typescript").Diagnostic) & {
+    code: number;
+};

package/plugins/inline_constants/transformation/errors.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNotConstantEnumMemberError = exports.createForeignPropertyError = exports.createNotLiteralPropertyError = exports.createNotLiteralConstantError = exports.createNotAsConstObjectError = exports.createNotConstError = exports.createNotModuleLevelError = exports.createUnsupportedDeclarationError = void 0;
+const diagnostics_1 = require("../../utils/diagnostics");
+const constants_1 = require("./constants");
+exports.createUnsupportedDeclarationError = (0, diagnostics_1.createErrorDiagnosticFactory)(`'@${constants_1.INLINE_TAG}' is supported only for enums and module-level 'const' declarations.`);
+exports.createNotModuleLevelError = (0, diagnostics_1.createErrorDiagnosticFactory)(`'@${constants_1.INLINE_TAG}' declarations must be module-level statements.`);
+exports.createNotConstError = (0, diagnostics_1.createErrorDiagnosticFactory)(`'@${constants_1.INLINE_TAG}' declarations must use 'const' keyword.`);
+exports.createNotAsConstObjectError = (0, diagnostics_1.createErrorDiagnosticFactory)((name) => `'@${constants_1.INLINE_TAG}' object '${name}' must use 'as const' assertion.`);
+exports.createNotLiteralConstantError = (0, diagnostics_1.createErrorDiagnosticFactory)((name) => `'@${constants_1.INLINE_TAG}' constant '${name}' must have a compile-time constant value, ` +
+    "use a literal or an expression computable on build time.");
+exports.createNotLiteralPropertyError = (0, diagnostics_1.createErrorDiagnosticFactory)((object, property) => `'@${constants_1.INLINE_TAG}' object '${object}' property '${property}' must have a compile-time constant value, ` +
+    "use a literal or an expression computable on build time.");
+exports.createForeignPropertyError = (0, diagnostics_1.createErrorDiagnosticFactory)((object, property) => `'@${constants_1.INLINE_TAG}' object '${object}' property '${property}' is declared outside of '@${constants_1.INLINE_TAG}' statements, ` +
+    `mark the source declaration with '@${constants_1.INLINE_TAG}' too.`);
+exports.createNotConstantEnumMemberError = (0, diagnostics_1.createErrorDiagnosticFactory)((name) => `'@${constants_1.INLINE_TAG}' enum member '${name}' must have a compile-time constant value.`);

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

@@ -0,0 +1,79 @@
+import * as ts from "typescript";
+import { type TInlineValue } from "./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.
+ */
+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
+ * (17 significant digits vs '%.14g'), so folding would change runtime-visible output.
+ *
+ * @param value - Folded value to convert.
+ * @returns String representation or null.
+ */
+export declare function toFoldedString(value: TInlineValue | null): string | 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.
+ */
+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).
+ *
+ * @param operator - Binary operator kind.
+ * @param left - Folded left operand.
+ * @param right - Folded right operand.
+ * @returns Folded value or null.
+ */
+export declare function foldBinaryExpression(operator: ts.SyntaxKind, left: TInlineValue, right: TInlineValue): TInlineValue | 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.
+ */
+export declare function evaluateConstantExpression(checker: ts.TypeChecker, expression: ts.Expression, seen: Set<ts.Declaration>): TInlineValue | 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.
+ */
+export declare function resolveConstantSymbol(checker: ts.TypeChecker, symbol: ts.Symbol, seen: Set<ts.Declaration>): TInlineValue | 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.
+ */
+export declare function getComputedDeclarationValue(checker: ts.TypeChecker, symbol: ts.Symbol, seen: Set<ts.Declaration>): TInlineValue | 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.
+ *
+ * @param checker - Program type checker.
+ * @param symbol - Symbol to resolve inline value for.
+ * @returns Literal value or null.
+ */
+export declare function tryGetInlineValue(checker: ts.TypeChecker, symbol: ts.Symbol): TInlineValue | null;