swagger2api-v3 1.1.9 → 1.1.11

package/dist/utils/logger.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * 轻量级终端日志工具（零依赖，基于 ANSI 转义码）
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+/** 终端是否支持颜色输出 */
+const supportsColor = process.stdout.isTTY &&
+    process.env.NODE_ENV !== 'test' &&
+    process.env.NO_COLOR === undefined;
+/** 日志左侧缩进 */
+const INDENT = '  ';
+/** 列表标签默认宽度 */
+const LIST_LABEL_WIDTH = 22;
+/** 日志图标 */
+const icon = {
+    success: '✅',
+    info: 'ℹ',
+    warn: '⚠',
+    error: '❌',
+    debug: '·',
+    path: '📂',
+    bullet: '•'
+};
+/**
+ * 包裹 ANSI 颜色码
+ * @param code ANSI 转义码
+ * @param text 文本内容
+ * @returns 带颜色的字符串（不支持颜色时返回原文）
+ */
+function wrap(code, text) {
+    return supportsColor ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+/** 颜色与样式快捷方法 */
+const style = {
+    /**
+     * 加粗文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    bold(text) {
+        return wrap('1', text);
+    },
+    /**
+     * 弱化文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    dim(text) {
+        return wrap('2', text);
+    },
+    /**
+     * 绿色文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    green(text) {
+        return wrap('32', text);
+    },
+    /**
+     * 黄色文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    yellow(text) {
+        return wrap('33', text);
+    },
+    /**
+     * 紫色文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    magenta(text) {
+        return wrap('35', text);
+    },
+    /**
+     * 青色文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    cyan(text) {
+        return wrap('36', text);
+    },
+    /**
+     * 灰色文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    gray(text) {
+        return wrap('90', text);
+    }
+};
+/**
+ * 日志工具类
+ *
+ * 提供统一的、带颜色的终端输出格式。
+ * error 方法不使用颜色码，确保 console.error 的参数为纯文本，
+ * 兼容测试中对 console.error 的 spy 断言。
+ */
+class Logger {
+    constructor() {
+        this.step = 0;
+        this.totalSteps = 0;
+    }
+    /**
+     * 写入标准输出
+     * @param message 输出内容
+     */
+    log(message = '') {
+        console.log(message);
+    }
+    /**
+     * 写入错误输出
+     * @param message 输出内容
+     */
+    fail(message) {
+        console.error(message);
+    }
+    /**
+     * 格式化未知错误
+     * @param error 错误对象
+     * @returns 错误文案
+     */
+    formatError(error) {
+        if (error instanceof Error) {
+            return error.message ? `${error.name}: ${error.message}` : error.name;
+        }
+        return String(error);
+    }
+    /**
+     * 输出带图标的状态行
+     * @param symbol 状态图标
+     * @param message 消息内容
+     */
+    status(symbol, message) {
+        this.log(`${INDENT}${symbol}  ${message}`);
+    }
+    /**
+     * 设置总步骤数
+     * @param n 步骤总数
+     */
+    setTotalSteps(n) {
+        this.totalSteps = n;
+        this.step = 0;
+    }
+    /**
+     * 输出步骤标题
+     * @param emoji 步骤图标
+     * @param title 步骤标题
+     */
+    stepTitle(emoji, title) {
+        this.step++;
+        const progress = this.totalSteps > 0
+            ? style.dim(`[${this.step}/${this.totalSteps}] `)
+            : '';
+        this.log();
+        this.log(`${INDENT}${progress}${emoji}  ${style.bold(title)}`);
+    }
+    /**
+     * 输出成功信息
+     * @param message 消息内容
+     */
+    success(message) {
+        this.status(style.green(icon.success), message);
+    }
+    /**
+     * 输出信息
+     * @param message 消息内容
+     */
+    info(message) {
+        this.status(style.cyan(icon.info), message);
+    }
+    /**
+     * 输出文件/路径信息
+     * @param label 标签
+     * @param path 路径
+     */
+    path(label, path) {
+        this.status(icon.path, `${style.dim(label)}: ${style.bold(path)}`);
+    }
+    /**
+     * 输出警告信息
+     * @param message 消息内容
+     */
+    warn(message) {
+        this.status(style.yellow(icon.warn), message);
+    }
+    /**
+     * 输出错误信息（不使用颜色码，兼容测试断言）
+     * @param message 消息内容
+     * @param error 错误对象
+     */
+    error(message, error) {
+        const detail = error === undefined ? message : `${message}: ${this.formatError(error)}`;
+        this.fail(`${icon.error} ${detail}`);
+    }
+    /**
+     * 输出错误列表
+     * @param title 错误标题
+     * @param items 错误项列表
+     */
+    errorList(title, items) {
+        this.fail(`${icon.error} ${title}`);
+        items.forEach((item) => this.fail(`${INDENT} - ${item}`));
+    }
+    /**
+     * 输出调试信息（灰色暗淡）
+     * @param message 消息内容
+     */
+    debug(message) {
+        this.status(style.gray(icon.debug), style.gray(message));
+    }
+    /**
+     * 输出调试键值对
+     * @param key 键名
+     * @param value 键值
+     */
+    debugKV(key, value) {
+        this.status(style.gray(icon.debug), `${style.gray(key)}: ${style.gray(String(value))}`);
+    }
+    /**
+     * 输出列表项
+     * @param label 列表项标签
+     * @param detail 列表项详情
+     */
+    listItem(label, detail) {
+        const paddedLabel = label.padEnd(LIST_LABEL_WIDTH, ' ');
+        this.log(`${INDENT}   ${style.dim(icon.bullet)} ${style.cyan(paddedLabel)} ${style.dim(detail)}`);
+    }
+    /**
+     * 输出分隔线
+     */
+    divider() {
+        const line = '─'.repeat(48);
+        this.log(`${INDENT}${style.dim(line)}`);
+    }
+    /**
+     * 输出横幅标题
+     * @param title 标题
+     * @param subtitle 副标题（可选）
+     */
+    banner(title, subtitle) {
+        this.log();
+        this.log(`${INDENT}${style.bold(style.magenta(title))}`);
+        if (subtitle) {
+            this.log(`${INDENT}${style.dim(subtitle)}`);
+        }
+        this.log();
+    }
+    /**
+     * 输出完成横幅
+     * @param message 完成消息
+     */
+    done(message) {
+        this.log();
+        this.log(`${INDENT}${style.green(icon.success)}  ${style.bold(message)}`);
+        this.log();
+    }
+}
+/** 日志单例 */
+exports.logger = new Logger();

package/dist/utils/naming.js

@@ -118,7 +118,8 @@ function sanitizeFilename(filename) {
  */
 function sanitizeTypeName(name) {
     if (!name)
-        return name;
+        return 'AnonymousType';
     const replaced = name.replace(/[^a-zA-Z0-9_]/g, '_');
-    return toPascalCase(replaced);
+    const typeName = toPascalCase(replaced) || 'AnonymousType';
+    return /^\d/.test(typeName) ? `_${typeName}` : typeName;
 }

package/dist/utils/schema.d.ts

@@ -0,0 +1,79 @@
+import { SwaggerSchema } from '../types';
+/** Schema 的使用场景 */
+export type SchemaUsage = 'neutral' | 'request' | 'response';
+/** 对象属性类型覆盖 */
+export type SchemaPropertyOverrides = Record<string, string>;
+/**
+ * 判断字符串是否为合法 TypeScript 标识符
+ * @param name 属性名
+ * @returns 是否为合法标识符
+ */
+export declare function isValidIdentifier(name: string): boolean;
+/**
+ * 格式化 TypeScript 属性名
+ * @param name 属性名
+ * @returns 可用于类型声明的属性名
+ */
+export declare function formatTsPropertyName(name: string): string;
+/**
+ * 转义 JSDoc 文本
+ * @param text 原始文本
+ * @returns 可安全写入单行 JSDoc 的文本
+ */
+export declare function escapeJSDocText(text: string): string;
+/**
+ * 移除联合类型中的顶层 null 类型
+ * @param typeStr 类型字符串
+ * @returns 移除 null 后的类型字符串
+ */
+export declare function stripNullFromUnion(typeStr: string): string;
+/**
+ * 判断 Schema 是否应按对象处理
+ * @param schema OpenAPI Schema
+ * @returns 是否为对象 Schema
+ */
+export declare function isObjectSchema(schema: SwaggerSchema): boolean;
+/**
+ * 判断 Schema 是否为项目约定的泛型响应容器
+ * @param schema OpenAPI Schema
+ * @returns 是否为泛型响应容器
+ */
+export declare function isGenericResponseSchema(schema: SwaggerSchema): boolean;
+/**
+ * 获取当前使用场景可见的对象属性
+ * @param schema OpenAPI Schema
+ * @param usage Schema 使用场景
+ * @returns 可见属性数组
+ */
+export declare function getVisibleSchemaProperties(schema: SwaggerSchema, usage?: SchemaUsage): Array<[string, SwaggerSchema]>;
+/**
+ * 判断 Schema 在指定场景下是否需要独立类型
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @returns 是否需要独立类型
+ */
+export declare function schemaNeedsUsageVariant(schema: SwaggerSchema, schemas: Record<string, SwaggerSchema>, usage: Exclude<SchemaUsage, 'neutral'>): boolean;
+/**
+ * 渲染对象类型成员
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @param overrides 属性类型覆盖
+ * @returns 对象成员代码
+ */
+export declare function renderObjectMembers(schema: SwaggerSchema, schemas?: Record<string, SwaggerSchema>, usage?: SchemaUsage, overrides?: SchemaPropertyOverrides): string;
+/**
+ * 将 OpenAPI Schema 转换为 TypeScript 类型
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @returns TypeScript 类型字符串
+ */
+export declare function swaggerTypeToTsType(schema: SwaggerSchema | undefined | null, schemas?: Record<string, SwaggerSchema>, usage?: SchemaUsage): string;
+/**
+ * 从 $ref 字符串中提取并解码引用名称
+ * @param ref OpenAPI $ref 字符串
+ * @returns 引用名称
+ */
+export declare function getRefName(ref: string): string;