@hadss/turbo-trans-json-plugin 1.0.0-rc.0

package/src/core/Types.ts

@@ -0,0 +1,356 @@
+/*
+ * Copyright (c) 2025 Huawei Device Co., Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { ClassDeclaration, InterfaceDeclaration, TypeNode } from 'ts-morph';
+
+// ============= 基础枚举类型 =============
+
+export enum PropertyKind {
+  // ===== 基础类型（对应PrimitiveKind） =====
+  STRING = 'string',        // StringSerializer.INSTANCE
+  NUMBER = 'number',        // NumberSerializer.INSTANCE
+  BOOLEAN = 'boolean',      // BooleanSerializer.INSTANCE
+  BIGINT = 'bigint',        // BigintSerializer.INSTANCE
+
+  // ===== 特殊原始类型 =====
+  NULL = 'null',            // NullSerializer.INSTANCE
+  UNDEFINED = 'undefined',  // UndefinedSerializer.INSTANCE
+
+  // ===== 集合类型（泛型构造器） =====
+  ARRAY = 'array',          // new ArraySerializer<T>(elementSerializer)
+  MAP = 'map',              // new MapSerializer<K,V>(keySerializer, valueSerializer)
+  SET = 'set',              // new SetSerializer<T>(elementSerializer)
+  RECORD = 'record',        // new RecordSerializer<K,V>(keySerializer, valueSerializer)
+  COLLECTIONS_ARRAY = 'collections.Array',    // new CollectionsArraySerializer<T>(elementSerializer)
+  COLLECTIONS_SET = 'collections.Set',        // new CollectionsSetSerializer<T>(elementSerializer)
+  COLLECTIONS_MAP = 'collections.Map',        // new CollectionsMapSerializer<K,V>(keySerializer, valueSerializer)
+
+  // ===== 复杂对象类型 =====
+  OBJECT = 'object',        // ObjectSerializer.INSTANCE
+  GENERIC = 'generic',      // Serializer<T>
+
+  // ===== 高级类型 =====
+  UNION = 'union',          // new UnionTypeSerializer<string | number>([string, number])
+  OPTIONAL = 'optional',    // new OptionalSerializer<T>(serializer) - for T | undefined
+  NULLABLE = 'nullable',    // new NullableSerializer<T>(serializer) - for T | null
+  OPTIONAL_NULLABLE = 'optionalNullable', // new OptionalNullableSerializer<T>(serializer) - for T | null | undefined
+  ENUM = 'enum',            // new EnumSerializer<number>('Habit', [['HAVE_FUN', 0], ['READING', 1], ['SPORT', 2]])
+  TUPLE = 'tuple',          // new TupleSerializer<[string, number]>([string, number])
+  ARRAY_LIST = 'arrayList',       // new ArrayListSerializer<T>(elementSerializer)
+  HASH_MAP = 'hashMap',           // new HashMapSerializer<K,V>(keySerializer, valueSerializer)
+  HASH_SET = 'hashSet',           // new HashSetSerializer<T>(elementSerializer)
+  LIST = 'list',                 // new ListSerializer<T>(elementSerializer)
+  Date = 'date',                  // new DateSerializer()
+  Decimal = 'decimal', // new DecimalSerializer()
+  INTERFACE = 'interface', // new AnySerializer<T>(interfaceDeclaration)
+
+  // ===== 未知类型（需要 @Transient） =====
+  UNKNOWN = 'unknown', // 暂不支持的类型（如 Date, Function, Symbol 等），必须标记 @Transient
+}
+
+export enum DeserializationMode {
+  PERFORMANCE = 'performance', // 性能模式
+  STRICT = 'strict' // 严格模式
+}
+
+// ============= 第一层：类分析结果 =============
+
+/**
+ * 类分析结果（顶层入口）
+ * 阅读路径：ClassAnalysis → 基础信息 → 泛型 → 继承 → 装饰器 → 属性分组
+ */
+export interface ClassAnalysis {
+  // 基础信息
+  className: string;              // 类名
+  sourceFilePath: string;         // 类在源码中的绝对路径
+  originalClass?: ClassDeclaration; // 原始AST引用（可选，用于高级处理和回溯）
+
+  // 核心特性
+  generics: GenericInfo;          // 泛型信息
+  inheritance: InheritanceInfo;   // 继承信息
+  decorators: ClassDecorators;    // 类装饰器
+
+  // 属性分组（基于继承信息的智能分组）
+  ownProperties: PropertyAnalysis[];        // 当前类自己定义的属性
+  inheritedProperties: PropertyAnalysis[];  // 从父类继承且未重写的属性
+  overriddenProperties: PropertyAnalysis[]; // 重写了父类的属性
+  properties: PropertyAnalysis[];           // 所有属性的合并视图(重写后的属性会覆盖父类属性，只保留一个)
+
+  // 构造函数信息
+  constructorParams: ConstructorParam[];    // 构造函数参数
+
+  // Sendable合并性
+  canMerge?: boolean;
+}
+
+export interface InterfaceAnalysis {
+  className: string;
+  sourceFilePath: string;
+  originalInterface: InterfaceDeclaration;
+  generics: GenericInfo;
+  inheritance: InheritanceInfo;
+  decorators?: ClassDecorators;
+
+  ownProperties: PropertyAnalysis[];        // 当前接口自己定义的属性
+  inheritedProperties: PropertyAnalysis[];  // 从父类继承且未重写的属性
+  overriddenProperties: PropertyAnalysis[]; // 重写了父类的属性
+  properties: PropertyAnalysis[];           // 所有属性的合并视图(重写后的属性会覆盖父类属性，只保留一个)
+}
+
+// ============= 第二层：类的核心特性 =============
+
+/**
+ * 泛型信息
+ * 专门处理类和方法的泛型参数、约束、变型信息
+ */
+export interface GenericInfo {
+  isGeneric: boolean;             // 是否为泛型类/方法
+  parameters: string[];           // 泛型参数名列表 ['T', 'U']
+}
+
+/**
+ * 继承信息（简化版，专注核心）
+ * 描述类的继承关系
+ */
+export interface InheritanceInfo {
+  isInherited: boolean;               // 是否继承其他类
+  baseClassAnalysis?: ClassAnalysis | InterfaceAnalysis;  // 直接父类的详细信息
+  genericTypeArguments?: TypeNode[];    // 继承时传入的泛型参数
+}
+
+/**
+ * 类装饰器信息
+ * 类级别的装饰器配置
+ */
+export interface ClassDecorators {
+  serializable?: SerializableOptions; // @Serializable 序列化配置
+  serialName?: string;
+}
+
+/**
+ * @Serializable 装饰器选项
+ * 配置序列化行为的选项
+ */
+export interface SerializableOptions {
+  generateSendable?: boolean;    // 是否生成Sendable变体类
+  with?: string;                 // 自定义序列化器工厂（完整表达式内容）
+  deserializationMode?: DeserializationMode; // 反序列化模式（粗糙/精确）
+}
+
+/**
+ * 构造函数参数信息
+ * 描述类构造函数的参数结构
+ */
+export interface ConstructorParam {
+  name: string;                   // 参数名称
+  type: string;                   // 参数类型字符串
+  isOptional: boolean;           // 是否可选
+  defaultValue?: string;          // 默认值（可选）
+}
+
+// ============= 第三层：属性分析结果 =============
+
+/**
+ * 属性分析结果（从ClassAnalysis.properties跳转到这里）
+ * 阅读路径：PropertyAnalysis → 基础信息 → 类型分析 → 装饰器
+ */
+export interface PropertyAnalysis {
+  name: string;                   // 属性名称
+  defaultValue?: string;          // 默认值表达式字符串
+  decorators?: PropertyDecorators; // 装饰器信息
+  isMust: boolean;                // 精确模式下反序列化时的必要性
+  type: TypeStructure;       // 完整的类型分析结果（详细类型信息）
+}
+
+/**
+ * 属性装饰器信息
+ * 分离装饰器解析结果，避免与分析结果混合
+ */
+export interface PropertyDecorators {
+  serialName?: string;            // @SerialName 自定义序列化名称
+  isRequired: boolean;            // @Required 是否必需字段
+  isTransient: boolean;           // @Transient 是否跳过序列化
+  with?: string;                  // @Serializable 自定义序列化器
+}
+
+// ============= 第五层：类型结构详情 =============
+
+/**
+ * 类型结构（从TypeAnalysisResult.structure跳转到这里）
+ * 阅读路径：TypeStructure → 基础信息 → 子结构 → 特殊类型信息
+ */
+export interface TypeStructure {
+  kind: PropertyKind;             // 类型种类（STRING, ARRAY, MAP等）
+  depth: number;                  // 嵌套深度（用于复杂度控制）
+  sourceText: string;             // 原始类型文本（如 "Array<Map<string, User>>"）
+  args: TypeStructure[]           // 泛型参数的类型
+  // 类型依赖和特殊信息
+  dependencies: TypeDependency[]; // 依赖信息列表（包含完整导入信息）
+  enumDetails?: EnumDetails;      // 枚举类型详细信息（仅当kind=ENUM时）
+  classDetails?: ClassDetails;    // 枚举类型详细信息（仅当kind=OBJECT时）
+  interfaceDetails?: InterfaceDetails; //（仅当kind=INTERFACE时）
+  unionDetails?: TypeStructure[]; // Union types 的成员类型
+  isOptional?: boolean;           // 是否可选
+}
+
+// ============= 第六层：类型依赖信息 =============
+
+export enum TypeKind {
+  CLASS = 'class',
+  INTERFACE = 'interface',
+  ENUM = 'enum',
+  TYPE = 'type',
+}
+
+/**
+ * 类型依赖信息（从TypeStructure.dependencies跳转到这里）
+ * 阅读路径：TypeDependency → 基础信息 → 来源信息 → 详细信息
+ */
+export interface TypeDependency {
+  typeName: string;               // 类型名称（如 "User"）
+  typeKind: TypeKind;             // 类型种类
+  importPath: string;             // 导入路径（如 "sampleentry/ets/model/User"）
+
+  source: DependencySource;       // 统一的来源信息
+  details?: TypeDetails;          // 扩展的类型详细信息（按需包含）
+}
+
+/**
+ * 依赖来源信息（从TypeDependency.source跳转到这里）
+ */
+export interface DependencySource {
+  type: 'local' | 'imported' | 'builtin'; // 本地定义/外部导入/内置类型
+  sourceFilePath?: string;        // 源文件绝对路径（仅当 type='local'|'imported' 时）
+  originalImport?: string;        // 原始导入语句（仅当 type='imported' 时）
+  packageName?: string;           // 包名（如果是包导入）
+}
+
+// ============= 第七层：类型详细信息 =============
+
+/**
+ * 类型详细信息（从TypeDependency.details跳转到这里）
+ * 联合类型，按typeKind区分，统一管理所有类型的详细信息
+ */
+export type TypeDetails =
+  | EnumDetails
+  | ClassDetails
+  | InterfaceDetails
+  | TypeAliasDetails;
+
+/**
+ * 枚举详细信息
+ */
+export interface EnumDetails {
+  kind: TypeKind.ENUM;
+  members: EnumMemberInfo[];      // 枚举成员列表
+  valueType: 'string' | 'number'; // 枚举值类型
+}
+
+/**
+ * 枚举成员信息（从EnumDetails.members跳转到这里）
+ */
+export interface EnumMemberInfo {
+  name: string;                   // 枚举成员名称（如 'HAVE_FUN'）
+  value: string | number;         // 枚举成员值（如 0 或 'football'）
+  literalValue: string;           // 字面量形式（用于代码生成，如 '0' 或 "'football'"）
+}
+
+/**
+ * 类详细信息
+ */
+export interface ClassDetails {
+  kind: TypeKind.CLASS;
+  classDecl: ClassDeclaration;
+  isGeneric: boolean;             // 是否为泛型类
+}
+
+/**
+ * 接口详细信息
+ */
+export interface InterfaceDetails {
+  kind: TypeKind.INTERFACE;
+  interfaceDecl: InterfaceDeclaration;
+  isGeneric: boolean;             // 是否为泛型接口
+}
+
+/**
+ * 类型别名详细信息
+ */
+export interface TypeAliasDetails {
+  kind: TypeKind.TYPE;
+  aliasedType: string;               // 别名指向的类型字符串（如 "User | Admin"）
+  resolvedType: TypeStructure;      // 解析后的实际类型（递归分析结果）
+}
+
+// ============= 代码生成阶段 =============
+
+/**
+ * 生成上下文（代码生成的顶层入口）
+ * 阅读路径：GenerationContext → 类分析 → 属性生成信息 → 模板和配置
+ */
+export interface GenerationContext {
+  class: ClassAnalysis | InterfaceAnalysis;           // 类分析结果
+  properties: PropertyGenerationInfo[]; // 属性生成信息列表
+  serialNameConstant: string;
+}
+
+/**
+ * 属性生成信息（从GenerationContext.properties跳转到这里）
+ * 阅读路径：PropertyGenerationInfo → 分析结果 → 序列化器元数据 → 模板数据
+ */
+export interface PropertyGenerationInfo {
+  analysis: PropertyAnalysis;     // 引用分析结果（不重复存储）
+  serializer: SerializerMetadata; // 序列化器生成元数据
+}
+
+/**
+ * 序列化器元数据（从PropertyGenerationInfo.serializer跳转到这里）
+ */
+export interface SerializerMetadata {
+  name: string;                   // 序列化器名称（如 "ArraySerializer"）
+  typeDeclaration: string;        // 类型声明（如 "ArraySerializer<User>"）
+  instantiationTemplate: string;  // 实例化模板（如 "new ArraySerializer<User>(UserSerializer.INSTANCE)"）
+  encodeMethod: string;           // 编码方法名（如 "encodeSerializableElement"）
+  decodeMethod: string;           // 解码方法名（如 "decodeSerializableElement"）
+  decoderType: string;            // 解码器类型（如 "string | undefined"）
+  needsTypeAssertion?: boolean;   // 是否需要类型断言（字符串枚举等情况）
+}
+
+// ============= 配置和选项 =============
+export interface ImportRewriteOptions {
+  scanPaths: string[]; // 导入重写扫描路径列表
+  preserveOriginalImports?: boolean; // 是否保留原始导入，默认值为false
+}
+
+export interface TurboTransJsonPluginOptions {
+  ignoreModuleNames: string[];
+  scanDir: string[];
+  deserializationMode: DeserializationMode;
+  importRewrite?: ImportRewriteOptions;
+}
+
+export interface IGenerationResult {
+  generatedFiles: IGeneratedFile[];
+  skippedFiles: string[];
+}
+
+export interface IGeneratedFile {
+  sourcePath: string;
+  outputPath: string;
+  contentLength: number;
+  serializerCount: number;
+  generatedAt: number;
+  contentHash?: string;
+}