wormajs 0.0.1

package/dist/helper/config/GeneratorHelper.js

@@ -0,0 +1,343 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatorHelper = exports.GeneratorHelper = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const zod_validation_error_1 = require("zod-validation-error");
+const constant_1 = require("../../constant");
+const parser_1 = require("../../core/parser");
+const helper_1 = require("../../core/parser/openApiParser/helper");
+const getAutoTemplateType_1 = __importDefault(require("../../functions/getAutoTemplateType"));
+const wormaJson_1 = require("../../functions/wormaJson");
+const helper_2 = require("../../helper");
+const progress_1 = require("../../helper/progress");
+const zType_1 = require("./zType");
+class GeneratorHelper {
+    constructor() {
+        /**
+         * Default configuration values
+         */
+        this.defaultConfig = Object.freeze({
+            input: '',
+            output: '',
+            responseMediaType: 'application/json',
+            bodyMediaType: 'application/json',
+            type: constant_1.ConfigTypeEnum.AUTO,
+            defaultRequire: false,
+        });
+    }
+    static getInstance() {
+        if (!GeneratorHelper.instance) {
+            GeneratorHelper.instance = new GeneratorHelper();
+        }
+        return GeneratorHelper.instance;
+    }
+    static load(config) {
+        const ins = new GeneratorHelper();
+        return ins.load(config);
+    }
+    getConfig() {
+        return this.readConfig;
+    }
+    getDefaultConfig() {
+        return this.defaultConfig;
+    }
+    /**
+     * Load and validate configuration
+     * @param config - Partial generator configuration
+     * @returns GeneratorHelper instance
+     */
+    async load(config) {
+        // Merge with default config
+        const mergedConfig = { ...this.defaultConfig, ...config };
+        // Validate configuration
+        const validatedConfig = await GeneratorHelper.validateConfig(mergedConfig);
+        // Update config
+        this.config = validatedConfig;
+        this.readConfig = Object.freeze(this.config);
+        this.pluginDriver = new helper_2.PluginDriver(this.config.plugins);
+        return this;
+    }
+    /**
+     * Get template type based on config
+     * @param projectPath - Project path
+     * @returns Template type
+     */
+    async getTemplateType(projectPath) {
+        return GeneratorHelper.getTemplateType(this.config, projectPath);
+    }
+    getPluginDriver() {
+        return this.pluginDriver;
+    }
+    async openApiData(projectPath) {
+        return GeneratorHelper.openApiData(this.config, projectPath);
+    }
+    /**
+     * Validate configuration using zod schema
+     * @param config - Configuration to validate
+     * @returns Validated configuration
+     */
+    static async validateConfig(config) {
+        let result = config;
+        try {
+            result = zType_1.zGeneratorConfig.parse(config);
+        }
+        catch (error) {
+            const zError = (0, zod_validation_error_1.fromError)(error);
+            throw helper_2.logger.throwError(zError.message, zError.details);
+        }
+        return result;
+    }
+    /**
+     * Determine template type based on config type value
+     * @param config - Generator configuration
+     * @param projectPath - Project path for auto detection
+     * @returns Template type
+     */
+    static async getTemplateType(config, projectPath) {
+        let type;
+        const configType = config.type ?? constant_1.ConfigTypeEnum.AUTO;
+        switch (configType) {
+            case constant_1.ConfigTypeEnum.TS:
+            case constant_1.ConfigTypeEnum.TYPESCRIPT:
+                type = constant_1.TemplateTypeEnum.TYPESCRIPT;
+                break;
+            case constant_1.ConfigTypeEnum.MODULE:
+                type = constant_1.TemplateTypeEnum.MODULE;
+                break;
+            case constant_1.ConfigTypeEnum.AUTO:
+                type = await (0, getAutoTemplateType_1.default)(projectPath);
+                break;
+            default:
+                type = constant_1.TemplateTypeEnum.COMMONJS;
+                break;
+        }
+        return type;
+    }
+    /**
+     * Parse OpenAPI document from config input
+     * @param config - Generator configuration
+     * @param projectPath - Project path
+     * @returns OpenAPI document
+     */
+    static openApiData(config, projectPath) {
+        return parser_1.openApiParser.parse(config.input, {
+            projectPath,
+            fetchOptions: config.fetchOptions,
+        });
+    }
+    static async openApiDataWithUrl(config, projectPath) {
+        return (0, helper_1.getOpenApiDataWithUrl)(config.input, {
+            projectPath,
+            fetchOptions: config.fetchOptions,
+        });
+    }
+    static async generate(config, { projectPath, force, tracker }) {
+        const reporter = (plugin) => tracker?.reporterFor(plugin.name ?? 'plugin') ?? progress_1.noopReportProgress;
+        const pluginDriver = new helper_2.PluginDriver(config.plugins, { reporter });
+        const reportCore = (progress, message) => {
+            tracker?.update(progress_1.CORE_PROGRESS_SOURCE, progress, message);
+        };
+        const pluginCount = (config.plugins || []).length;
+        const pluginNames = (config.plugins || []).map(p => p.name).filter(Boolean);
+        helper_2.logger.debug('Starting generation process', {
+            projectPath,
+            force,
+            input: config.input,
+            output: config.output,
+            plugins: pluginCount,
+            pluginNames: pluginNames.length ? pluginNames : 'none',
+        });
+        reportCore(5, 'starting');
+        const frozenConfig = Object.freeze(config);
+        // Plugin: handle before parse openapi
+        reportCore(10, 'beforeOpenapiParse');
+        helper_2.logger.debug('Running beforeOpenapiParse hook');
+        await pluginDriver.hookParallelEach('beforeOpenapiParse', () => ({
+            config: frozenConfig,
+            projectPath,
+        }));
+        reportCore(20, 'parsing openapi document');
+        helper_2.logger.debug('Fetching OpenAPI document', { input: config.input });
+        const openApiResult = await this.openApiDataWithUrl(config, projectPath);
+        let document = openApiResult.data;
+        const resolvedInput = openApiResult.resolvedUrl;
+        if (!document) {
+            helper_2.logger.debug('No OpenAPI document found, skipping generation', { resolvedInput });
+            reportCore(100, 'skipped: no openapi document');
+            return { success: false, resolvedInput };
+        }
+        helper_2.logger.debug('OpenAPI document parsed successfully', {
+            resolvedUrl: resolvedInput,
+            version: document?.info?.version,
+            paths: Object.keys(document?.paths || {}).length,
+        });
+        reportCore(35, 'openapi parsed');
+        // Plugin: handle after parse openapi (openapiParsed)
+        helper_2.logger.debug('Running openapiParsed hook', { pluginCount });
+        const openapiParsed = await pluginDriver.hookSeqEach('openapiParsed', (_p, prevResult, _ctx) => {
+            if (prevResult) {
+                document = prevResult;
+            }
+            return {
+                config: frozenConfig,
+                document,
+                projectPath,
+            };
+        });
+        if (openapiParsed) {
+            document = openapiParsed;
+            helper_2.logger.debug('openapiParsed hook modified document');
+        }
+        reportCore(45, 'openapiParsed');
+        const output = node_path_1.default.resolve(projectPath, config.output);
+        const templateType = await GeneratorHelper.getTemplateType(config, projectPath);
+        helper_2.logger.debug('Resolved output and template type', { output, templateType });
+        // Get template path from plugins (last non-nil wins)
+        helper_2.logger.debug('Running getTemplate hook');
+        const templateResult = await pluginDriver.hookSeqEach('getTemplate', (_p, _prevResult, _ctx) => ({
+            config: frozenConfig,
+            projectPath,
+        }));
+        if (!templateResult?.path) {
+            throw helper_2.logger.throwError('No template configured. Please add a template preset plugin (e.g. alovaGlobals, alova, axios, fetch, ky) to `config.generator.plugins`.');
+        }
+        helper_2.logger.debug('Template configuration loaded', {
+            path: templateResult.path,
+            type: templateType,
+        });
+        reportCore(55, 'template configuration loaded');
+        // Collect onHandlebarsCreated callbacks from plugins (deferred until hbs is created)
+        const onHbsCreatedCallbacks = [];
+        const plugins = (config.plugins || []);
+        for (const plugin of plugins) {
+            if (typeof plugin.onHandlebarsCreated === 'function') {
+                const fn = plugin.onHandlebarsCreated;
+                onHbsCreatedCallbacks.push((hbs) => fn.call(plugin, {
+                    hbs,
+                    config: frozenConfig,
+                    projectPath,
+                    reportProgress: reporter(plugin),
+                }));
+            }
+        }
+        const templateHelper = helper_2.TemplateHelper.load({
+            type: templateType,
+            templatePath: templateResult.path,
+            // We'll collect and inject onHandlebarsCreated later
+        });
+        // Parse document and create template data
+        const tempalteParser = new parser_1.TemplateParser();
+        const templateData = await tempalteParser.parse(document, {
+            projectPath,
+            generatorConfig: config,
+        });
+        helper_2.logger.debug('Template data parsed', {
+            apisCount: templateData.allApis?.length ?? 0,
+            tagsCount: templateData.tagedApis?.length ?? 0,
+        });
+        reportCore(65, 'template data parsed');
+        // M3-B2: hash-based comparison instead of lodash.isEqual O(n·s) deep compare
+        // P2: Pass tagedApis to avoid re-grouping; apiHashCache avoids re-hashing same Api objects
+        const newApis = templateData.allApis || [];
+        const newHashInfo = (0, wormaJson_1.computePerTagHashes)(newApis, templateData.tagedApis);
+        let changedTags;
+        if (!force) {
+            const oldEntry = await (0, wormaJson_1.getCacheEntry)(projectPath, config.output);
+            if (oldEntry) {
+                if (oldEntry.hash === newHashInfo.hash) {
+                    helper_2.logger.debug('Template data unchanged (hash match), skipping generation');
+                    reportCore(100, 'skipped: template data unchanged');
+                    return { success: false, resolvedInput };
+                }
+                // Compute which tags changed for incremental rendering
+                changedTags = (0, wormaJson_1.diffChangedTags)(oldEntry.tags, newHashInfo.tags);
+                helper_2.logger.debug('Incremental update detected', {
+                    totalTags: Object.keys(newHashInfo.tags).length,
+                    changedTags: changedTags.size,
+                });
+            }
+        }
+        reportCore(70, 'beforeCodeGenerate');
+        helper_2.logger.debug('Running beforeCodeGenerate hook');
+        await pluginDriver.hookParallelEach('beforeCodeGenerate', () => ({
+            config: frozenConfig,
+            data: templateData,
+            projectPath,
+        }));
+        let codeGenError;
+        let filePaths = [];
+        try {
+            // Reload templateHelper with onHandlebarsCreated callbacks
+            templateHelper.load({
+                type: templateType,
+                templatePath: templateResult.path,
+                onHandlebarsCreated: onHbsCreatedCallbacks,
+            });
+            helper_2.logger.debug('Resolving template files', { templatePath: templateResult.path });
+            // Save template data and cache data (hash info included for later write)
+            await helper_2.TemplateHelper.setData(templateData, projectPath, config.output, config);
+            helper_2.logger.debug('Processing templates');
+            reportCore(80, 'processing templates');
+            // 9.2.1: Unified streaming pipeline — render + beforeFileWrite hooks + write
+            const perf = config.performance;
+            const writeConcurrency = perf?.writeConcurrency ?? 32;
+            const formatFile = perf?.formatFile ?? true;
+            helper_2.logger.debug('Starting template generation', {
+                writeConcurrency,
+                formatFile,
+                changedTagsCount: changedTags?.size ?? 'all',
+            });
+            const result = await templateHelper.generateFromTemplateDir(templateResult.path, output, templateData, {
+                changedTags,
+                writeConcurrency,
+                formatFile,
+                beforeFileWrite: async ({ filePath: relPath, content: fileContent, meta }) => {
+                    return pluginDriver.hookPipe('beforeFileWrite', fileContent, (_p, currentContent, _ctx) => ({
+                        config: frozenConfig,
+                        data: templateData,
+                        filePath: relPath,
+                        content: currentContent,
+                        projectPath,
+                        meta,
+                    }));
+                },
+            });
+            filePaths = result.filePaths;
+            helper_2.logger.debug('Template generation completed', {
+                filesWritten: filePaths.length,
+            });
+            reportCore(95, 'files written');
+        }
+        catch (error) {
+            codeGenError = error;
+            helper_2.logger.debug('Template generation failed', {
+                error: codeGenError.message,
+                stack: codeGenError.stack,
+            });
+        }
+        // 9.1.4 & 9.1.1: codeGenerated is called AFTER all files are written, only receives file paths
+        helper_2.logger.debug('Running codeGenerated hook', { fileCount: filePaths.length });
+        await pluginDriver.hookParallelEach('codeGenerated', () => ({
+            config: frozenConfig,
+            data: templateData,
+            filePaths,
+            outputDir: output,
+            projectPath,
+            error: codeGenError,
+            renderTemplate: (params) => helper_2.TemplateHelper.renderToDir(params),
+        }));
+        if (!codeGenError) {
+            reportCore(100, 'completed');
+        }
+        else {
+            reportCore(100, `failed: ${codeGenError.message}`);
+            throw codeGenError;
+        }
+        return { success: true, resolvedInput };
+    }
+}
+exports.GeneratorHelper = GeneratorHelper;
+exports.generatorHelper = GeneratorHelper.getInstance();

package/dist/helper/config/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ConfigHelper"), exports);
+__exportStar(require("./ConfigManager"), exports);
+__exportStar(require("./GeneratorHelper"), exports);

package/dist/helper/config/type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/helper/config/zType.js

@@ -0,0 +1,170 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zConfig = exports.zGeneratorConfig = exports._zGeneratorConfig = exports.zApiPlugin = exports.zFetchOptions = exports.zHandleApi = exports.zApiDescriptor = exports.zTemplateResult = exports.zTemplateType = exports.zConfigType = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const v3_1 = require("zod/v3"); // v4版本不稳定，暂时使用v3
+/**
+ * Find the corresponding input attribute value
+ */
+exports.zConfigType = v3_1.z.enum(['auto', 'ts', 'typescript', 'module', 'commonjs']);
+/**
+ * template type
+ */
+exports.zTemplateType = v3_1.z.enum(['typescript', 'module', 'commonjs']);
+exports.zTemplateResult = v3_1.z.object({
+    path: v3_1.z.string(),
+});
+exports.zApiDescriptor = v3_1.z.any();
+exports.zHandleApi = v3_1.z
+    .function()
+    .args(exports.zApiDescriptor)
+    .returns(v3_1.z.union([exports.zApiDescriptor, v3_1.z.undefined(), v3_1.z.null(), v3_1.z.void()]));
+exports.zFetchOptions = v3_1.z.record(v3_1.z.string(), v3_1.z.any());
+exports.zApiPlugin = v3_1.z.object({
+    name: v3_1.z.string().optional(),
+    config: v3_1.z.function().optional(),
+    beforeOpenapiParse: v3_1.z.function().optional(),
+    openapiParsed: v3_1.z.function().optional(),
+    beforeCodeGenerate: v3_1.z.function().optional(),
+    beforeFileWrite: v3_1.z.function().optional(),
+    codeGenerated: v3_1.z.function().optional(),
+    getTemplate: v3_1.z.function().optional(),
+    onHandlebarsCreated: v3_1.z.function().optional(),
+});
+exports._zGeneratorConfig = v3_1.z.object({
+    /**
+     * Openapi file path, it supports json and yaml file, and network url.
+     * Can be a single URL string or an array of URLs. When set to an array,
+     * each URL will be tried in order and the first successful response is returned.
+     * @requires true
+     *
+     * @example
+     * input: 'http://localhost:3000/openapi.json'
+     * input: 'openapi/api.json' -> Take the current project as the local address of the relative directory
+     * input: ['https://primary.com/openapi.json', 'https://fallback.com/openapi.json'] -> Try each URL in order
+     */
+    input: v3_1.z.union([v3_1.z.string(), v3_1.z.array(v3_1.z.string())]).refine(val => (typeof val === 'string' && val.length > 0) || (Array.isArray(val) && val.length > 0), 'Field input is required in `config.generator`'),
+    // Fetch options used by remote OpenAPI retrieval (headers, timeout, insecure). See FetchOptions in '@/utils/base'.
+    fetchOptions: exports.zFetchOptions.optional(),
+    /**
+     * A list of type identifiers to exclude from generation.
+     * Matches against type names parsed from the OpenAPI schema; matched types
+     * are skipped and referenced directly by their identifier in generated code
+     * to avoid duplicate or conflicting declarations.
+     * Use this when you already have hand-written types or types provided by
+     * frameworks/libraries that should not be generated.
+     *
+     * @example
+     * externalTypes: ['File', 'Blob', 'FormData', 'Pagination']
+     */
+    externalTypes: v3_1.z.array(v3_1.z.string()).optional(),
+    /**
+     * The output path of the interface file and type file, multiple generators cannot have repeated addresses, otherwise the generated codes will cover each other, which is meaningless.
+     * @requires true
+     */
+    output: v3_1.z
+        .string({
+        required_error: 'Field output is required in `config.generator`',
+    })
+        .nonempty('Field output is required in `config.generator`'),
+    /**
+     * Whether to generate documentation comments, default is true.
+     * Set to false to improve generation performance.
+     */
+    docComment: v3_1.z.boolean().optional(),
+    /**
+     * Specify the media type of the generated response data. After specifying, use this data type to generate the response ts format of the 2xx status code.
+     * Can be a string or an array of strings for fallback media types.
+     */
+    responseMediaType: v3_1.z.union([v3_1.z.string(), v3_1.z.array(v3_1.z.string())]).optional(),
+    /**
+     * Specify the media type of the generated request body data. After specifying, use this data type to generate the ts format of the request body.
+     * Can be a string or an array of strings for fallback media types.
+     */
+    bodyMediaType: v3_1.z.union([v3_1.z.string(), v3_1.z.array(v3_1.z.string())]).optional(),
+    /**
+     * Custom server name for displaying in the sidebar when multiple API docs are configured.
+     */
+    serverName: v3_1.z.string().optional(),
+    /**
+     * The type of generated code. The optional value is `auto/ts/typescript/module/commonjs`.
+     * default is `auto`, it means the type of current project will be determined through certain rules.
+     *
+     * @param type
+     * 1. ts/typescript: The same meaning means generating ts type files
+     * 2. module: generate esModule specification file
+     * 3. commonjs: means generating commonjs specification file
+     *
+     * @default 'auto'
+     */
+    type: exports.zConfigType.optional(),
+    /**
+     * When there is no require, it defaults to require, and only nullable takes effect.
+     */
+    defaultRequire: v3_1.z.boolean().optional(),
+    /**
+     * plugin will be executed before `handleApi`
+     */
+    plugins: v3_1.z.array(exports.zApiPlugin).optional(),
+    /**
+     * Filter or convert the generated api function and return a new `apiDescriptor` to generate the api.
+     * When this function is not specified, `apiDescriptor` object is not converted.
+     * The type of `apiDescriptor` is the same as the api item of openapi file.
+     *
+     * @see https://spec.openapis.org/oas/v3.1.0.html#operation-object
+     *
+     * @example
+     * ```js
+     * // Do not generate the apis that starts with `/user`
+     * handleApi(apiDescriptor) {
+     *   if (apiDescriptor.path.startsWith('/user')) {
+     *     return;
+     *   }
+     *   return apiDescriptor;
+     * }
+     * ```
+     *
+     * ```js
+     * // modify the api's parameters
+     * handleApi(apiDescriptor) {
+     *   apiDescriptor.parameters = (apiDescriptor.parameters || []).filter(
+     *     param => param.in === 'header' && param.name === 'token'
+     *   );
+     *   delete apiDescriptor.requestBody.id;
+     *   apiDescriptor.url = apiDescriptor.url.replace('/user', '');
+     *   return apiDescriptor;
+     * }
+     * ```
+     */
+    handleApi: exports.zHandleApi.optional(),
+});
+exports.zGeneratorConfig = exports._zGeneratorConfig;
+exports.zConfig = v3_1.z.object({
+    /**
+     * API generation settings are arrays. Each item represents an automatically generated rule, including the generated input and output directories, specification file addresses, etc.
+     * Currently, only OpenAPI specifications are supported, including OpenAPI 2.0 and 3.0 specifications.
+     */
+    generator: v3_1.z
+        .array(exports.zGeneratorConfig)
+        .min(1, 'No items found in the `config.generator`')
+        .superRefine((data, ctx) => {
+        if (data.length < 2) {
+            return;
+        }
+        const outputSet = new Set();
+        data.forEach((item) => {
+            if (outputSet.has(node_path_1.default.join(item.output ?? ''))) {
+                ctx.addIssue({
+                    code: v3_1.z.ZodIssueCode.custom,
+                    path: ['generator', 'output'],
+                    message: `output \`${item.output}\` is repeated`,
+                });
+                return;
+            }
+            outputSet.add(node_path_1.default.join(item.output ?? ''));
+        });
+    }),
+});