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

package/src/core/services/CodeGenerationService/shared/ImportManager.ts

@@ -0,0 +1,191 @@
+/*
+ * 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 SerializationPathUtil from '../../../utils/SerializationPathUtil';
+import { ITaskContext } from '../../..';
+
+interface ImportInfo {
+  modulePath: string;
+  importedNames: string[];
+  isDefaultImport: boolean;
+  isNamespaceImport: boolean;
+}
+
+export class ImportManager {
+  private imports: Map<string, ImportInfo> = new Map();
+  private defaultImports: Map<string, string> = new Map();
+  // 跟踪类型名称到模块路径的映射，用于去重
+  private typeToModulePath: Map<string, string> = new Map();
+  // 路径映射器
+  private context: ITaskContext | null = null;
+
+  registerCoreImports(interfaceNames: string[]): void {
+    const coreModule = '@hadss/turbo-trans-core';
+
+    for (const interfaceName of interfaceNames) {
+      this.registerCustomImport(coreModule, interfaceName);
+    }
+  }
+
+  registerJsonImports(names: string[]): void {
+    const jsonModule = '@hadss/turbo-trans-json';
+
+    for (const name of names) {
+      this.registerCustomImport(jsonModule, name);
+    }
+  }
+
+  registerArkTSImports(names: string[]) {
+    const arkTSModule = '@kit.ArkTS';
+
+    for (const name of names) {
+      this.registerCustomImport(arkTSModule, name);
+    }
+  }
+
+  registerCustomImport(modulePath: string, importedName: string): void {
+    // 智能去重：检查是否已有同名类型的更好路径
+    if (this.typeToModulePath.has(importedName)) {
+      const existingModulePath = this.typeToModulePath.get(importedName)!;
+      
+      // 如果当前路径是模块化路径，而已存在的是相对路径，则替换
+      if (this.isModularPath(modulePath) && this.isRelativePath(existingModulePath)) {
+        // 移除旧的相对路径导入
+        this.removeImportFromModule(existingModulePath, importedName);
+        // 更新映射
+        this.typeToModulePath.set(importedName, modulePath);
+      } else if (this.isRelativePath(modulePath) && this.isModularPath(existingModulePath)) {
+        // 如果当前是相对路径，已存在的是模块化路径，则忽略当前注册
+        return;
+      }
+    } else {
+      // 首次注册该类型
+      this.typeToModulePath.set(importedName, modulePath);
+    }
+
+    if (this.imports.has(modulePath)) {
+      const existingInfo = this.imports.get(modulePath)!;
+      const names = new Set(existingInfo.importedNames);
+      names.add(importedName);
+
+      this.imports.set(modulePath, {
+        ...existingInfo,
+        importedNames: Array.from(names)
+      });
+    } else {
+      this.imports.set(modulePath, {
+        modulePath,
+        importedNames: [importedName],
+        isDefaultImport: false,
+        isNamespaceImport: false
+      });
+    }
+  }
+
+  registerDefaultImport(modulePath: string, importedName: string): void {
+    if (this.defaultImports.has(modulePath)) {
+      return;
+    }
+
+    this.defaultImports.set(modulePath, importedName);
+  }
+
+  /**
+   * 判断是否为模块化路径（不以 . 或 / 开头，不是 @开头的包名）
+   */
+  private isModularPath(modulePath: string): boolean {
+    return !modulePath.startsWith('.') && 
+           !modulePath.startsWith('/') && 
+           !modulePath.startsWith('@') &&
+           modulePath.includes('/');
+  }
+
+  private isRelativePath(modulePath: string): boolean {
+    return modulePath.startsWith('./') || modulePath.startsWith('../');
+  }
+
+  private removeImportFromModule(modulePath: string, importedName: string): void {
+    if (this.imports.has(modulePath)) {
+      const existingInfo = this.imports.get(modulePath)!;
+      const filteredNames = existingInfo.importedNames.filter(name => name !== importedName);
+      
+      if (filteredNames.length === 0) {
+        // 如果该模块没有其他导入，则删除整个模块
+        this.imports.delete(modulePath);
+      } else {
+        // 否则只更新导入列表
+        this.imports.set(modulePath, {
+          ...existingInfo,
+          importedNames: filteredNames
+        });
+      }
+    }
+  }
+
+  getImportDeclarations() {
+    const imports: Array<{ specifier: string, names: string[] }> = [];
+    for (const [specifier, infos] of this.imports) {
+      imports.push({ specifier: specifier, names: infos.importedNames });
+    }
+    return imports;
+  }
+
+  getDefaultImport(): Array<{ specifier: string, name: string }> {
+    const defaultImports: Array<{ specifier: string, name: string }> = [];
+    for (const [specifier, info] of this.defaultImports) {
+      defaultImports.push({ specifier: specifier, name: info });
+    }
+    return defaultImports;
+  }
+
+  clear(): void {
+    this.imports.clear();
+    this.typeToModulePath.clear();
+  }
+
+  /**
+   * 设置路径映射器
+   *
+   * @param context 任务上下文
+   */
+  setContext(context: ITaskContext): void {
+    this.context = context;
+  }
+
+  /**
+   * 注册自定义类型导入（使用模块化路径）
+   * @param customTypeFilePath 自定义类型文件的绝对路径
+   * @param typeName 类型名称
+   */
+  registerCustomTypeImport(customTypeFilePath: string, typeName: string): void {
+    // 使用路径映射器计算模块化路径
+    const modularImportPath = SerializationPathUtil.calculateModularImportPath(customTypeFilePath, this.context!);
+
+    this.registerCustomImport(modularImportPath, typeName);
+  }
+
+  /**
+   * 注册临时序列化器导入（从 tempSerializer/index.ets）
+   * @param serializerName 序列化器名称（如 "PersonSerializer"）
+   */
+  registerTempSerializerImport(serializerName: string): void {
+    // 计算 tempSerializer 目录的模块化路径
+    const outputRoot = this.context!.getOutputRoot();
+    const tempSerializerPath = SerializationPathUtil.pathResolve(outputRoot, 'tempSerializer');
+    const modularImportPath = SerializationPathUtil.calculateModularImportPath(tempSerializerPath, this.context!);
+
+    this.registerCustomImport(modularImportPath, serializerName);
+  }
+}

package/src/core/template/HandlebarsTemplateEngine.ts

@@ -0,0 +1,282 @@
+/*
+ * 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 * as Handlebars from 'handlebars';
+import {
+  ClassAnalysis, ConstructorParam, DecoratorConstants, DeserializationMode, GenerationContext, InterfaceAnalysis,
+  PropertyAnalysis, PropertyDecorators, PropertyGenerationInfo, PropertyKind
+} from '..';
+import SerializationPathUtil from '../utils/SerializationPathUtil';
+import { CustomError, ErrorCodes } from '../utils/CustomError';
+
+export class HandlebarsTemplateEngine {
+  private serializationTemplate?: HandlebarsTemplateDelegate;
+  private serializationRegisterTemplate?: HandlebarsTemplateDelegate;
+  private readonly registerTemplatePath: string =
+    SerializationPathUtil.pathResolve(__dirname, '../../../template/SerializerRegisterTemplate.hbs');
+
+  private readonly performanceTemplatePath: string =
+    SerializationPathUtil.pathResolve(__dirname, '../../../template/SerializerPerformanceTemplate.hbs');
+  private readonly strictTemplatePath: string =
+    SerializationPathUtil.pathResolve(__dirname, '../../../template/SerializerStrictTemplate.hbs');
+  private readonly commonTemplatePath: string =
+    SerializationPathUtil.pathResolve(__dirname, '../../../template/SerializerTemplate.hbs');
+
+  constructor() {
+    this.registerBuiltinHelpers();
+    this.registerTemplate();
+  }
+
+  render(templateName: string, context: GenerationContext): string {
+    const template = this.serializationTemplate;
+
+    if (!template) {
+      throw new CustomError(`Template '${templateName}' not found.`, ErrorCodes.TEMPLATE_NOT_FOUND);
+    }
+
+    return template({ deserializeTemplate: templateName, ...context });
+  }
+
+  renderRegister(context: GenerationContext): string {
+    const template = this.serializationRegisterTemplate;
+
+    if (!template) {
+      throw new CustomError(`Template not found.`, ErrorCodes.TEMPLATE_NOT_FOUND);
+    }
+
+    return template(context);
+  }
+
+  registerTemplate(): void {
+    try {
+      // 性能模式反序列化模板
+      const performanceTemplateContent = SerializationPathUtil.readFileSync(this.performanceTemplatePath).toString();
+      Handlebars.registerPartial(DeserializationMode.PERFORMANCE, performanceTemplateContent);
+
+      // 严格模式反序列化模板
+      const strictTemplateContent = SerializationPathUtil.readFileSync(this.strictTemplatePath).toString();
+      Handlebars.registerPartial(DeserializationMode.STRICT, strictTemplateContent);
+
+      const commonTemplateContent = SerializationPathUtil.readFileSync(this.commonTemplatePath).toString();
+      this.serializationTemplate = this.loadTemplateFromString(commonTemplateContent);
+
+      const registerTemplateContent = SerializationPathUtil.readFileSync(this.registerTemplatePath).toString();
+      this.serializationRegisterTemplate = this.loadTemplateFromString(registerTemplateContent);
+    } catch (error) {
+      throw new CustomError(`Failed to register template ${error instanceof Error ? error.message : String(error)}`,
+        ErrorCodes.TEMPLATE_REGISTER_FAIL);
+    }
+  }
+
+  registerHelper(name: string, helper: Handlebars.HelperDelegate): void {
+    Handlebars.registerHelper(name, helper);
+  }
+
+  loadTemplateFromString(template: string): HandlebarsTemplateDelegate {
+    return Handlebars.compile(template, { noEscape: true });
+  }
+
+  private registerBuiltinHelpers(): void {
+    this.registerComparisonHelpers();
+    this.registerTypeCheckHelpers();
+    this.registerFormattingHelpers();
+    this.registerPropertyAnalysisHelpers();
+    this.registerConstructorHelpers();
+    this.registerLogicHelpers();
+  }
+
+  private registerComparisonHelpers(): void {
+    this.registerHelper('eq', (arg1: unknown, arg2: unknown) => {
+      return (arg1 === arg2);
+    });
+
+    this.registerHelper('eqPrimitiveType', (kind: string) => {
+      const primitives = ['string', 'number', 'boolean', 'bigint', 'undefined', 'null'];
+      return primitives.includes(kind);
+    });
+
+    this.registerHelper('eqEmptyType', (kind: string) => {
+      return ['null', 'undefined'].includes(kind);
+    });
+  }
+
+  private registerTypeCheckHelpers(): void {
+    this.registerHelper('isNumericPropertyName', (propertyName: string) => {
+      return /^\d+$/.test(propertyName);
+    });
+
+    this.registerHelper('containsUndefined', (typeText: string) => {
+      return typeText.includes('undefined');
+    });
+
+    // 条件：All properties are basic type + No undefined + No union type + No @Transient + No @SerialName
+    this.registerHelper('canReturnDirectly', (classAnalysis: ClassAnalysis) => {
+      // 检查类装饰器是否包含非@Serializable装饰器
+      if (this.hasNonSerializableClassDecorator(classAnalysis)) {
+        return false;
+      }
+
+      // 检查属性装饰器是否包含非@Serializable 装饰器
+      if (this.hasNonSerializablePropertyDecorators(classAnalysis)) {
+        return false;
+      }
+
+      const properties = classAnalysis.properties;
+
+      if (!Array.isArray(properties)) {
+        return false;
+      }
+
+      return properties.every(prop => this.isPropertyValidForDirectReturn(prop));
+    });
+
+    this.registerHelper('isClassType', (cls: ClassAnalysis | InterfaceAnalysis) => {
+      return !!(cls as ClassAnalysis).originalClass;
+    });
+  }
+
+  private hasNonSerializableClassDecorator(classAnalysis: ClassAnalysis): boolean {
+    const classDecorators = classAnalysis.originalClass?.getDecorators() || [];
+    return classDecorators.some(decorator =>
+      decorator.getName() !== 'Serializable'
+    );
+  }
+
+  private hasNonSerializablePropertyDecorators(classAnalysis: ClassAnalysis): boolean {
+    const props = classAnalysis.originalClass?.getProperties();
+    if (!props || !Array.isArray(props)) {
+      return false;
+    }
+
+    for (const prop of props) {
+      const decorators = prop.getDecorators();
+      if (decorators && Array.isArray(decorators)) {
+        const hasNonSerializableDecorator = decorators.some(decorator =>
+          !DecoratorConstants.SERIAL_DECORATORS.includes(decorator.getName())
+        );
+        if (hasNonSerializableDecorator) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  private isPropertyValidForDirectReturn(prop: PropertyAnalysis): boolean {
+    // 条件4: No @Transient annotation - 如果有 @Transient 属性，不能直接返回
+    if (prop.decorators?.isTransient) {
+      return false;
+    }
+
+    // 条件5: No @SerialName property - 如果有 @SerialName，不能直接返回
+    if (prop.decorators?.serialName && prop.decorators.serialName !== prop.name) {
+      return false;
+    }
+
+    // 条件6: No with property - 如果有 with，不能直接返回
+    if (prop.decorators?.with) {
+      return false;
+    }
+
+    // 条件1: All properties are basic type（null, boolean, number, string, bigint）
+    const kind = prop.type?.kind;
+    const primitives = ['null', 'boolean', 'number', 'string', 'bigint'];
+    if (!primitives.includes(kind)) {
+      return false;
+    }
+
+    // 条件2: No `undefined` or  `null` type property
+    if (kind === 'undefined' || kind === 'null') {
+      return false;
+    }
+
+    // 条件3: No union type property - 检查是否为联合类型
+    if (kind === PropertyKind.UNION) {
+      return false;
+    }
+
+    return true;
+  }
+
+  private registerFormattingHelpers(): void {
+    this.registerHelper('formatGenericArgs', (args: string[]) => {
+      return Array.isArray(args) && args.length > 0 ? `<${args.join(', ')}>` : '';
+    });
+
+    this.registerHelper('formatPropertyName', (property: PropertyAnalysis) => {
+      return property.decorators?.serialName || property.name;
+    });
+
+    this.registerHelper('toLowerCase', (str: string) => {
+      return str.toLowerCase();
+    });
+
+    this.registerHelper('genericParametersString', (parameters: string[]) => {
+      return parameters.join(', ');
+    });
+
+    this.registerHelper('genericParametersESObjString', (parameters: string[]) => {
+      return parameters.map(() => 'ESObject').join(', ');
+    });
+  }
+
+  private registerPropertyAnalysisHelpers(): void {
+    this.registerHelper('getPropertyIndex',
+      (property: PropertyGenerationInfo, properties: PropertyGenerationInfo[]) => {
+        return properties.findIndex(p => p.analysis.name === property.analysis.name);
+      });
+
+    this.registerHelper('postConstructorAssignments',
+      (constructorParam?: ConstructorParam[], properties?: PropertyGenerationInfo[]) => {
+        return properties?.filter(prop => {
+          return !constructorParam?.some((cp) => cp.name === prop.analysis.name);
+        });
+      });
+  }
+
+  private registerConstructorHelpers(): void {
+    this.registerHelper('getCtorProperties',
+      (constructorParam?: ConstructorParam[], properties?: PropertyGenerationInfo[]) => {
+        return constructorParam?.map(param => {
+          const prop = properties?.find(p => p.analysis.name === param.name);
+          // ✅ 允许构造函数参数包含@Transient属性
+          // 如果在properties中找不到，说明该属性被@Transient过滤掉了，跳过
+          if (!prop) {
+            return null; // 返回null，稍后模板中会过滤掉
+          }
+          return prop;
+        }).filter(p => p !== null); // 过滤掉null值（@Transient属性）
+      });
+  }
+
+  private registerLogicHelpers(): void {
+    // 逻辑与操作
+    this.registerHelper('and', (...args: unknown[]) => {
+      // args 的最后一个元素是 Handlebars 的 options 对象，需要排除
+      const values = args.slice(0, -1);
+      return values.every(val => !!val);
+    });
+
+    // 逻辑非操作
+    this.registerHelper('not', (value: unknown) => {
+      return !value;
+    });
+
+    // 检查装饰器中是否有 @with
+    this.registerHelper('hasDecoratorWith', (decorators?: PropertyDecorators) => {
+      return !!(decorators?.with);
+    });
+  }
+}

package/src/core/utils/ConfigManager.ts

@@ -0,0 +1,49 @@
+/*
+ * 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 { DeserializationMode, TurboTransJsonPluginOptions, PathConstants, ImportRewriteOptions } from '..';
+
+export class ConfigManager {
+  private static instance: ConfigManager;
+  private config: TurboTransJsonPluginOptions | null = null;
+
+  private constructor() {}
+
+  public static getInstance(): ConfigManager {
+    if (!ConfigManager.instance) {
+      ConfigManager.instance = new ConfigManager();
+    }
+    return ConfigManager.instance;
+  }
+
+  public setConfig(config: TurboTransJsonPluginOptions): void {
+    this.config = config;
+  }
+
+  public getConfig(): TurboTransJsonPluginOptions {
+    return this.config || {
+      ignoreModuleNames: [],
+      scanDir: PathConstants.DEFAULT_SCAN_DIRS,
+      deserializationMode: DeserializationMode.PERFORMANCE,
+    };
+  }
+
+  public getImportRewriteConfig(): ImportRewriteOptions {
+    return this.config?.importRewrite || {
+      scanPaths: ['src/main/ets'],
+      preserveOriginalImports: false
+    };
+  }
+}

package/src/core/utils/CustomError.ts

@@ -0,0 +1,51 @@
+/*
+ * 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.
+ */
+
+export class CustomError extends Error {
+  name: string;
+  code: ErrorCodes;
+
+  constructor(message: string, code: ErrorCodes) {
+    super(message);
+    this.name = 'CustomError';
+    this.code = code;
+  }
+}
+
+export enum ErrorCodes {
+  INTERNAL_ERROR = 3000, // 内部未知错误
+  TEMPLATE_NOT_FOUND = 3011, // 没有找到模板
+  TEMPLATE_REGISTER_FAIL = 3012, // 性能和严格模式模板注册失败
+  ROOT_DIRECTROY_NOT_FOUND = 3021, // 源码根目录查找失败
+  INVALID_OUTPUT_FAIL = 3022, // 模板文件输出路径无效
+  INVALID_FILE_CONTENT = 3023, // 查找文件内容无效，例如为空的时候
+  HANDLER_NOT_FOUND = 3031, // 数据类型对应handler处理器查找失败
+  CLASS_DECLARATION_NOT_FOUND = 3032, // 未查找到类对应ClassDeclaration（ts-morph库的概念，用于获取类的基本信息）
+  IS_NOT_ENUM = 3033, // 枚举解析器解析到非枚举类型
+  ENUM_STRUCTURE_NOT_FOUND = 3034, // 未查找到枚举类型对应structure解析结构
+  TYPE_NOT_SUPPORT = 3041, // 自定义类中属性字段类型不支持
+  LITERAL_NOT_SOPPORT = 3042, // 字面量类型不支持
+  TRANSIENT_ATTR_OPTIONAL = 3043, // @Transient装饰属性必须是可选，或者存在默认值
+  ANNOTATION_CONFLICT = 3044, // 同一个属性存在多个Serialization属性装饰器
+  UNEXPECTED_GENERIC = 3051, // 不支持的泛型定义
+  GENERIC_NOT_MATCH = 3052, // 定义的泛型个数不匹配
+  UNION_STRUCTURE_NOT_FOUND = 3061, // 未查找到联合类型对应structure解析结构
+  UNION_EXPEDTED_TWO = 3062, // 当联合类型一部分undefined或者nul时，泛型长度为2，另一部分可以支持带泛型参数的自定义class
+  UNION_INNER_NOT_FOUND = 3063, // 当联合类型一部分undefined或者nul时，泛型长度为2时，未查找到另一部分非null或者undefined定义
+  UNION_UNSUPPORTED_PATTERN = 3064, // 不支持的联合类型 
+  UNION_EXPEDTED_THREE = 3065, // 当联合类型一部分undefined或者nul时，泛型长度为3，另一部分可以支持带泛型参数的自定义class
+  REWRITE_IMPORT_FAIL = 3071, // 重写源文件import失败
+  NOT_SENDABLE = 3072, // sendable类定义的属性费非sendable类型
+}