@easy-electron/ts-parser 1.0.1-alpha.1

package/dist/index.d.cts

@@ -0,0 +1,607 @@
+import ts from 'typescript';
+
+/**
+ * 通用 TypeScript 文件解析结果
+ */
+interface ParsedSourceFile {
+    /** 文件路径 */
+    filePath: string;
+    /** 导入声明 */
+    imports: ImportDeclarationInfo[];
+    /** 导出声明 */
+    exports: ExportDeclarationInfo[];
+    /** 接口定义 */
+    interfaces: InterfaceInfo[];
+    /** 类型别名定义 */
+    typeAliases: TypeAliasInfo[];
+    /** 枚举定义 */
+    enums: EnumInfo[];
+    /** 类定义 */
+    classes: ClassInfo[];
+    /** 函数声明（包括箭头函数变量） */
+    functions: FunctionInfo[];
+    /** 变量声明 */
+    variables: VariableInfo[];
+    /** 默认导出表达式（如 export default defineIpc(...)） */
+    defaultExport?: DefaultExportInfo;
+}
+/**
+ * 导入声明信息
+ */
+interface ImportDeclarationInfo {
+    /** 模块路径 */
+    moduleSpecifier: string;
+    /** 是否为类型导入 (import type) */
+    isTypeOnly: boolean;
+    /** 默认导入名称 */
+    defaultImport?: string;
+    /** 命名导入列表 */
+    namedImports: NamedImportInfo[];
+    /** 命名空间导入 (import * as xxx) */
+    namespaceImport?: string;
+    /** 原始文本 */
+    text: string;
+}
+/**
+ * 命名导入信息
+ */
+interface NamedImportInfo {
+    /** 导入名称 */
+    name: string;
+    /** 别名 */
+    alias?: string;
+    /** 是否为类型导入 */
+    isTypeOnly: boolean;
+}
+/**
+ * 导出声明信息
+ */
+interface ExportDeclarationInfo {
+    /** 导出名称列表（命名导出） */
+    namedExports: NamedExportInfo[];
+    /** 模块路径（re-export 时） */
+    moduleSpecifier?: string;
+    /** 是否为类型导出 */
+    isTypeOnly: boolean;
+    /** 是否为默认导出 */
+    isDefault: boolean;
+    /** 原始文本 */
+    text: string;
+}
+/**
+ * 命名导出信息
+ */
+interface NamedExportInfo {
+    /** 导出名称 */
+    name: string;
+    /** 别名 */
+    alias?: string;
+    /** 是否为类型导出 */
+    isTypeOnly: boolean;
+}
+/**
+ * 接口信息
+ */
+interface InterfaceInfo {
+    /** 接口名称 */
+    name: string;
+    /** 是否导出 */
+    isExported: boolean;
+    /** 泛型参数 */
+    typeParameters: string[];
+    /** 继承列表 */
+    extends: string[];
+    /** 成员列表 */
+    members: PropertySignatureInfo[];
+    /** JSDoc 注释 */
+    comment?: string;
+    /** 原始文本 */
+    text: string;
+}
+/**
+ * 属性签名信息
+ */
+interface PropertySignatureInfo {
+    /** 属性名 */
+    name: string;
+    /** 类型文本 */
+    type: string;
+    /** 是否可选 */
+    isOptional: boolean;
+    /** JSDoc 注释 */
+    comment?: string;
+}
+/**
+ * 类型别名信息
+ */
+interface TypeAliasInfo {
+    /** 类型名称 */
+    name: string;
+    /** 是否导出 */
+    isExported: boolean;
+    /** 泛型参数 */
+    typeParameters: string[];
+    /** 类型文本 */
+    type: string;
+    /** JSDoc 注释 */
+    comment?: string;
+    /** 原始文本 */
+    text: string;
+}
+/**
+ * 枚举信息
+ */
+interface EnumInfo {
+    /** 枚举名称 */
+    name: string;
+    /** 是否导出 */
+    isExported: boolean;
+    /** 是否为 const enum */
+    isConst: boolean;
+    /** 成员列表 */
+    members: EnumMemberInfo[];
+    /** JSDoc 注释 */
+    comment?: string;
+    /** 原始文本 */
+    text: string;
+}
+/**
+ * 枚举成员信息
+ */
+interface EnumMemberInfo {
+    /** 成员名称 */
+    name: string;
+    /** 初始值 */
+    value?: string;
+    /** JSDoc 注释 */
+    comment?: string;
+}
+/**
+ * 类信息
+ */
+interface ClassInfo {
+    /** 类名 */
+    name: string;
+    /** 是否导出 */
+    isExported: boolean;
+    /** 是否为抽象类 */
+    isAbstract: boolean;
+    /** 泛型参数 */
+    typeParameters: string[];
+    /** 继承的类 */
+    extends?: string;
+    /** 实现的接口 */
+    implements: string[];
+    /** 成员列表 */
+    members: ClassMemberInfo[];
+    /** JSDoc 注释 */
+    comment?: string;
+    /** 原始文本 */
+    text: string;
+}
+/**
+ * 类成员信息
+ */
+interface ClassMemberInfo {
+    /** 成员名称 */
+    name: string;
+    /** 成员类型: property | method | constructor | getter | setter */
+    kind: 'property' | 'method' | 'constructor' | 'getter' | 'setter';
+    /** 访问修饰符 */
+    accessibility?: 'public' | 'private' | 'protected';
+    /** 是否为静态成员 */
+    isStatic: boolean;
+    /** 是否为只读 */
+    isReadonly: boolean;
+    /** 是否为抽象成员 */
+    isAbstract: boolean;
+    /** 是否为可选成员 */
+    isOptional: boolean;
+    /** 类型文本（属性类型或方法返回类型） */
+    type?: string;
+    /** 参数列表（方法/构造函数） */
+    parameters?: ParameterInfo[];
+    /** JSDoc 注释 */
+    comment?: string;
+}
+/**
+ * 函数信息（函数声明 + 箭头函数变量）
+ */
+interface FunctionInfo {
+    /** 函数名 */
+    name: string;
+    /** 是否导出 */
+    isExported: boolean;
+    /** 是否为默认导出 */
+    isDefault: boolean;
+    /** 是否为异步函数 */
+    isAsync: boolean;
+    /** 是否为生成器函数 */
+    isGenerator: boolean;
+    /** 泛型参数 */
+    typeParameters: string[];
+    /** 参数列表 */
+    parameters: ParameterInfo[];
+    /** 返回类型 */
+    returnType?: string;
+    /** JSDoc 注释 */
+    comment?: string;
+    /** 原始文本 */
+    text: string;
+}
+/**
+ * 参数信息
+ */
+interface ParameterInfo {
+    /** 参数名 */
+    name: string;
+    /** 参数类型 */
+    type?: string;
+    /** 是否可选 */
+    isOptional: boolean;
+    /** 是否为剩余参数 */
+    isRest: boolean;
+    /** 默认值文本 */
+    defaultValue?: string;
+}
+/**
+ * 变量声明信息
+ */
+interface VariableInfo {
+    /** 变量名 */
+    name: string;
+    /** 声明类型: const | let | var */
+    declarationKind: 'const' | 'let' | 'var';
+    /** 是否导出 */
+    isExported: boolean;
+    /** 类型注解 */
+    type?: string;
+    /** 初始化表达式（如果是函数调用，解析为 CallExpressionInfo） */
+    initializer?: CallExpressionInfo | string;
+    /** JSDoc 注释 */
+    comment?: string;
+    /** 原始文本 */
+    text: string;
+}
+/**
+ * 函数调用表达式信息
+ */
+interface CallExpressionInfo {
+    /** 调用的函数名 */
+    callee: string;
+    /** 泛型参数 */
+    typeArguments: string[];
+    /** 参数列表 */
+    arguments: ArgumentInfo[];
+    /** 原始文本 */
+    text: string;
+}
+/**
+ * 参数信息（调用表达式的参数）
+ */
+interface ArgumentInfo {
+    /** 参数类型: string | number | boolean | object | array | function | identifier | other */
+    kind: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'function' | 'identifier' | 'other';
+    /** 值（字面量时为实际值） */
+    value?: string | number | boolean;
+    /** 对象字面量属性（kind 为 object 时） */
+    properties?: ObjectPropertyInfo[];
+    /** 数组元素（kind 为 array 时） */
+    elements?: ArgumentInfo[];
+    /** 函数信息（kind 为 function 时） */
+    function?: FunctionExpressionInfo;
+    /** 原始文本 */
+    text: string;
+}
+/**
+ * 对象字面量属性信息
+ */
+interface ObjectPropertyInfo {
+    /** 属性名 */
+    name: string;
+    /** 属性值 */
+    value: ArgumentInfo;
+    /** JSDoc 注释 */
+    comment?: string;
+}
+/**
+ * 函数表达式信息（对象属性中的函数值）
+ */
+interface FunctionExpressionInfo {
+    /** 是否为异步 */
+    isAsync: boolean;
+    /** 参数列表 */
+    parameters: ParameterInfo[];
+    /** 返回类型 */
+    returnType?: string;
+    /** 函数体文本 */
+    bodyText?: string;
+}
+/**
+ * 默认导出信息
+ */
+interface DefaultExportInfo {
+    /** 导出类型 */
+    kind: 'call' | 'identifier' | 'function' | 'class' | 'object' | 'other';
+    /** 函数调用信息（kind 为 call 时） */
+    call?: CallExpressionInfo;
+    /** 标识符名称（kind 为 identifier 时） */
+    identifier?: string;
+    /** 原始文本 */
+    text: string;
+}
+
+/**
+ * 通用 TypeScript 文件解析器
+ *
+ * 基于 TypeScript Compiler API，将 TS 源文件解析为结构化数据模型。
+ * 支持解析的结构包括：
+ * - 导入/导出声明
+ * - 接口、类型别名、枚举
+ * - 类（含成员、修饰符、继承关系）
+ * - 函数声明与箭头函数变量
+ * - 变量声明（含函数调用表达式解析）
+ * - 默认导出表达式
+ * - JSDoc 注释提取
+ *
+ * @example
+ * ```ts
+ * const parser = new TsParser()
+ * const result = parser.parse('./src/example.ts')
+ * console.log(result.interfaces) // 所有接口定义
+ * console.log(result.functions)  // 所有函数声明
+ * ```
+ */
+declare class TsParser {
+    private compilerOptions;
+    /**
+     * 创建解析器实例
+     * @param compilerOptions TypeScript 编译选项，不传则使用默认配置（ES2020 + ESNext + Bundler）
+     */
+    constructor(compilerOptions?: ts.CompilerOptions);
+    /**
+     * 解析 TS 文件，返回结构化的解析结果
+     * @param filePath 文件路径
+     * @param content 文件内容（可选，不传则通过 ts.sys 从文件系统读取）
+     * @returns 解析后的源文件结构
+     * @throws 当文件无法读取时抛出错误
+     */
+    parse(filePath: string, content?: string): ParsedSourceFile;
+    /**
+     * 从源码字符串直接解析，无需文件路径
+     * @param source TypeScript 源码字符串
+     * @param fileName 虚拟文件名，默认 'anonymous.ts'
+     * @returns 解析后的源文件结构
+     */
+    parseSource(source: string, fileName?: string): ParsedSourceFile;
+    /**
+     * 遍历源文件的顶层节点，根据节点类型分发到对应的解析方法
+     * @param node 当前遍历的 AST 节点
+     * @param sourceFile 源文件对象（用于获取文本）
+     * @param result 解析结果容器，各解析方法会将结果写入其中
+     */
+    private visitNode;
+    /**
+     * 解析 import 声明节点
+     *
+     * 支持以下导入形式：
+     * - 默认导入: `import Foo from 'module'`
+     * - 命名导入: `import { Foo, Bar as Baz } from 'module'`
+     * - 命名空间导入: `import * as ns from 'module'`
+     * - 类型导入: `import type { Foo } from 'module'`
+     * - 混合导入: `import Foo, { Bar } from 'module'`
+     *
+     * @param node import 声明 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 导入声明信息
+     */
+    private parseImport;
+    /**
+     * 解析 export 声明节点（不含 export default）
+     *
+     * 支持以下导出形式：
+     * - 命名导出: `export { Foo, Bar as Baz }`
+     * - 重导出: `export { Foo } from 'module'`
+     * - 全量重导出: `export * from 'module'`
+     * - 类型导出: `export type { Foo }`
+     *
+     * @param node export 声明 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 导出声明信息
+     */
+    private parseExport;
+    /**
+     * 解析接口声明节点
+     *
+     * 提取接口的名称、泛型参数、继承关系、成员属性及其类型、可选性、JSDoc 注释等。
+     *
+     * @param node 接口声明 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 接口信息
+     */
+    private parseInterface;
+    /**
+     * 解析类型别名声明节点
+     *
+     * 如: `type Foo<T> = Bar | Baz`
+     *
+     * @param node 类型别名声明 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 类型别名信息
+     */
+    private parseTypeAlias;
+    /**
+     * 解析枚举声明节点
+     *
+     * 支持普通枚举和 const 枚举，提取每个成员的名称、初始值和注释。
+     *
+     * @param node 枚举声明 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 枚举信息
+     */
+    private parseEnum;
+    /**
+     * 解析类声明节点
+     *
+     * 提取类的名称、泛型参数、继承/实现关系、是否抽象类，
+     * 以及所有成员（属性、方法、构造函数、getter/setter）。
+     *
+     * @param node 类声明 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 类信息
+     */
+    private parseClass;
+    /**
+     * 解析单个类成员节点
+     *
+     * 根据成员类型（构造函数、属性、方法、getter、setter）提取对应信息，
+     * 包括访问修饰符（public/private/protected）、static、readonly、abstract 等修饰符。
+     *
+     * @param member 类成员 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 类成员信息，无法识别的成员类型返回 null
+     */
+    private parseClassMember;
+    /**
+     * 解析函数声明节点
+     *
+     * 如: `function foo<T>(a: string): Promise<T> { ... }`
+     * 提取函数名、泛型参数、参数列表、返回类型、async/generator 标记等。
+     *
+     * @param node 函数声明 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 函数信息
+     */
+    private parseFunctionDeclaration;
+    /**
+     * 解析变量声明语句
+     *
+     * 对每个变量声明进行分类处理：
+     * - 如果初始化表达式是箭头函数/函数表达式，归入 functions
+     * - 如果初始化表达式是函数调用，解析为 CallExpressionInfo
+     * - 其他情况作为普通变量处理
+     *
+     * @param node 变量声明语句 AST 节点
+     * @param sourceFile 源文件对象
+     * @param result 解析结果容器
+     */
+    private parseVariableStatement;
+    /**
+     * 判断节点是否为函数类表达式（箭头函数或函数表达式）
+     * @param node AST 节点
+     * @returns 是否为函数类表达式
+     */
+    private isFunctionLike;
+    /**
+     * 将箭头函数/函数表达式变量解析为 FunctionInfo
+     *
+     * 如: `const foo = async (a: string) => { ... }`
+     *
+     * @param name 变量名（即函数名）
+     * @param node 函数表达式 AST 节点
+     * @param isExported 是否导出
+     * @param sourceFile 源文件对象
+     * @param comment JSDoc 注释
+     * @returns 函数信息
+     */
+    private parseFunctionExpression;
+    /**
+     * 解析函数调用表达式
+     *
+     * 如: `defineIpc('test', { ... })` 或 `createApp<Config>(options)`
+     * 提取被调用函数名、泛型参数、实参列表（递归解析每个参数）。
+     *
+     * @param node 函数调用表达式 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 函数调用表达式信息
+     */
+    parseCallExpression(node: ts.CallExpression, sourceFile: ts.SourceFile): CallExpressionInfo;
+    /**
+     * 解析表达式参数，递归处理各种字面量和复合类型
+     *
+     * 支持的参数类型：
+     * - 字符串字面量 → kind: 'string'
+     * - 数字字面量 → kind: 'number'
+     * - 布尔字面量 → kind: 'boolean'
+     * - 对象字面量 → kind: 'object'（递归解析属性）
+     * - 数组字面量 → kind: 'array'（递归解析元素）
+     * - 函数/箭头函数 → kind: 'function'
+     * - 标识符引用 → kind: 'identifier'
+     * - 其他表达式 → kind: 'other'
+     *
+     * @param node 参数 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 参数信息
+     */
+    parseArgument(node: ts.Node, sourceFile: ts.SourceFile): ArgumentInfo;
+    /**
+     * 将箭头函数/函数表达式节点解析为 FunctionExpressionInfo
+     * @param node 箭头函数或函数表达式 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 函数表达式信息（含参数、返回类型、函数体）
+     */
+    private parseFunctionExpressionInfo;
+    /**
+     * 将对象字面量中的方法声明解析为 FunctionExpressionInfo
+     *
+     * 如: `{ getData() { ... } }` 中的 getData 方法
+     *
+     * @param node 方法声明 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 函数表达式信息
+     */
+    private parseMethodAsFunctionExpression;
+    /**
+     * 解析默认导出表达式（export default ...）
+     *
+     * 根据导出表达式的类型分类：
+     * - 函数调用: `export default defineIpc(...)` → kind: 'call'
+     * - 标识符: `export default router` → kind: 'identifier'
+     * - 对象字面量: `export default { ... }` → kind: 'object'
+     * - 其他表达式 → kind: 'other'
+     *
+     * @param node 默认导出赋值 AST 节点
+     * @param sourceFile 源文件对象
+     * @returns 默认导出信息
+     */
+    private parseDefaultExport;
+    /**
+     * 解析函数/方法的参数列表
+     * @param params 参数声明节点数组
+     * @param sourceFile 源文件对象
+     * @returns 参数信息列表（含名称、类型、可选性、剩余参数、默认值）
+     */
+    private parseParameters;
+    /**
+     * 提取泛型参数列表的文本表示
+     * @param typeParams 泛型参数声明节点数组
+     * @returns 泛型参数文本列表，如 ['T', 'K extends string']
+     */
+    private getTypeParameters;
+    /**
+     * 检查节点是否具有 export 修饰符
+     * @param node AST 节点
+     * @returns 是否导出
+     */
+    private hasExportModifier;
+    /**
+     * 获取类成员的访问修饰符
+     * @param node 类成员 AST 节点
+     * @returns 访问修饰符（public/private/protected），无显式修饰符时返回 undefined
+     */
+    private getAccessibility;
+    /**
+     * 提取节点的 JSDoc 注释
+     *
+     * 通过 ts.getLeadingCommentRanges 获取节点前的注释块，
+     * 只返回以 `/**` 开头的 JSDoc 风格注释，忽略普通行注释和块注释。
+     *
+     * @param node AST 节点
+     * @param sourceFile 源文件对象
+     * @returns JSDoc 注释文本（含 `/**` 和 `*​/`），无 JSDoc 时返回 undefined
+     */
+    private getJsDoc;
+}
+
+export { TsParser };
+export type { ArgumentInfo, CallExpressionInfo, ClassInfo, ClassMemberInfo, DefaultExportInfo, EnumInfo, EnumMemberInfo, ExportDeclarationInfo, FunctionExpressionInfo, FunctionInfo, ImportDeclarationInfo, InterfaceInfo, NamedExportInfo, NamedImportInfo, ObjectPropertyInfo, ParameterInfo, ParsedSourceFile, PropertySignatureInfo, TypeAliasInfo, VariableInfo };