wormajs 0.3.1 → 1.0.0-beta.0

package/dist/bin/actions.js

@@ -38,6 +38,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.actionInit = actionInit;
 exports.actionGen = actionGen;
+exports.actionDiff = actionDiff;
+exports.printRecordedChanges = printRecordedChanges;
 const node_path_1 = __importDefault(require("node:path"));
 const readline = __importStar(require("node:readline/promises"));
 const config_1 = require("../config");
@@ -51,6 +53,8 @@ const renderer_1 = require("./renderer");
 const theme_1 = require("./theme");
 // eslint-disable-next-line ts/no-require-imports, perfectionist/sort-imports
 const pkg = require('../../package.json');
+// eslint-disable-next-line ts/no-require-imports, perfectionist/sort-imports
+const Table = require('cli-table3');
 async function actionInit({ type, template, project }) {
     const renderer = new renderer_1.InitRenderer(pkg.version);
     // Resolve project path
@@ -131,7 +135,7 @@ async function promptTemplate() {
     // Default to first choice (alova) on invalid input
     return renderer_1.INIT_TEMPLATE_CHOICES[0].value;
 }
-async function actionGen({ project, force, debug, }) {
+async function actionGen({ project, debug, }) {
     if (debug) {
         helper_1.logger.configure({ level: 'debug' });
     }
@@ -169,7 +173,7 @@ async function actionGen({ project, force, debug, }) {
     if (projects.length === 1) {
         // Single project: existing MultiGeneratorRenderer path — 100% unchanged behaviour
         const proj = projects[0];
-        await generateForProject(proj, force);
+        await generateForProject(proj);
     }
     else {
         // Multi-project: new MultiProjectRenderer + sequential execution
@@ -182,15 +186,18 @@ async function actionGen({ project, force, debug, }) {
         }));
         const renderer = new renderer_1.MultiProjectRenderer(projectInfos, pkg.version);
         const allResults = [];
+        const recorded = [];
         for (let pi = 0; pi < projects.length; pi++) {
             const proj = projects[pi];
             try {
                 const results = await (0, generate_1.default)(proj.config, {
-                    force,
                     projectPath: proj.dir,
                     onProgress(event) {
                         renderer.onProjectEvent(pi, event);
                     },
+                    onChangeRecorded(change) {
+                        recorded.push(change);
+                    },
                 });
                 allResults.push(results);
             }
@@ -205,9 +212,155 @@ async function actionGen({ project, force, debug, }) {
             }
         }
         renderer.finalize(allResults);
+        printRecordedChanges(recorded);
     }
 }
-async function generateForProject(entry, force) {
+// ──────────────────────────────────────────────────────────────
+// `worma diff` — browse recorded API changes (requirement B)
+// ──────────────────────────────────────────────────────────────
+/**
+ * Format a timestamp in the **local** time zone (`YYYY-MM-DD HH:mm:ss`).
+ *
+ * `toISOString()` renders UTC, which made every record look ~8h off for anyone
+ * outside UTC and is the reason a record created at noon showed up as 04:xx.
+ */
+function formatTime(ts) {
+    const date = new Date(ts);
+    if (Number.isNaN(date.getTime()))
+        return '-';
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+/**
+ * Build a bordered `cli-table3` instance with our theme colours applied to the
+ * header (the library's own head/border colours are disabled so our `theme`
+ * palette wins). ANSI escape codes are measured as zero-width by cli-table3's
+ * internal `string-width` layout, so coloured cells stay aligned.
+ */
+function createTable(head) {
+    return new Table({
+        head,
+        style: { head: [], border: [] },
+    });
+}
+/** `worma diff` / `worma diff <id>` / `worma diff latest` */
+async function actionDiff(id, { list, project }) {
+    const projectPath = project
+        ? (node_path_1.default.isAbsolute(project) ? project : node_path_1.default.resolve(process.cwd(), project))
+        : process.cwd();
+    // Mirror `actionGen`: always resolve the cache from CWD so monorepo
+    // sub-packages share one unified cache root.
+    (0, config_1.setGlobalConfig)({ cacheRoot: process.cwd() });
+    const { countChanges, getChange, listChanges } = await Promise.resolve().then(() => __importStar(require('../functions/changeReport')));
+    if (!id || list) {
+        const summaries = await listChanges(projectPath);
+        if (summaries.length === 0) {
+            console.log(`\n  ${theme_1.theme.dim('No change records found.')}`);
+            console.log(`  ${theme_1.theme.dim('Run `worma gen` after changing your spec to create one.')}\n`);
+            return;
+        }
+        const table = createTable([
+            theme_1.theme.label('ID'),
+            theme_1.theme.label('CREATED'),
+            theme_1.theme.label('OUTPUTS'),
+            theme_1.theme.label('CHANGES'),
+        ]);
+        summaries.forEach(s => table.push([
+            s.id,
+            formatTime(s.createdAt),
+            s.outputs.join(', ') || '-',
+            `+${s.summary.added} / -${s.summary.removed} / ~${s.summary.modified}`,
+        ]));
+        console.log('');
+        console.log(table.toString());
+        console.log('');
+        return;
+    }
+    const change = await getChange(projectPath, id);
+    if (!change) {
+        console.log(`\n  ${theme_1.theme.warning('?')} No change record found for "${id}".\n`);
+        return;
+    }
+    console.log('');
+    console.log(`  ${theme_1.theme.label(`Change ${change.id}`)}  ${theme_1.theme.dim(formatTime(change.createdAt))}`);
+    console.log('');
+    const totals = countChanges(change.generators);
+    for (const gen of change.generators) {
+        console.log(`  ${theme_1.theme.header(gen.serverName ? `${gen.output}  (${gen.serverName})` : gen.output)}`);
+        if (gen.changes.length === 0) {
+            console.log(`    ${theme_1.theme.dim('no changes')}`);
+            console.log('');
+            continue;
+        }
+        // Every change is one row: component changes carry their affected
+        // operations in `affects`, listed under the change itself (one per line).
+        const table = createTable([
+            '',
+            theme_1.theme.label('TYPE'),
+            theme_1.theme.label('TARGET'),
+            theme_1.theme.label('ITEM'),
+            theme_1.theme.label('CHANGE'),
+            theme_1.theme.label('LEVEL'),
+        ]);
+        for (const row of gen.changes) {
+            table.push([
+                opText(row.op),
+                theme_1.theme.dim(row.kind),
+                row.target,
+                row.item ?? '',
+                changeCell(row),
+                levelText(row.level),
+            ]);
+        }
+        console.log(table.toString());
+        console.log('');
+    }
+    console.log(`  ${theme_1.theme.label('Total:')} ${theme_1.theme.success(`+${totals.added} added`)}, ${theme_1.theme.error(`-${totals.removed} removed`)}, ${theme_1.theme.warning(`~${totals.modified} modified`)}`);
+    console.log('');
+}
+/**
+ * `CHANGE` cell of one row: the change itself plus, for a component change, the
+ * operations it affects — one per line, so nothing is folded away.
+ */
+function changeCell(row) {
+    return [row.detail, ...(row.affects ?? [])].filter(Boolean).join('\n');
+}
+/** `+` / `-` / `~` cell with the matching palette colour. */
+function opText(op) {
+    if (op === '+')
+        return theme_1.theme.success(op);
+    if (op === '-')
+        return theme_1.theme.error(op);
+    return theme_1.theme.warning(op);
+}
+/** Severity cell with the matching palette colour. */
+function levelText(level) {
+    if (level === 'breaking')
+        return theme_1.theme.error(level);
+    if (level === 'additive')
+        return theme_1.theme.success(level);
+    return theme_1.theme.dim(level);
+}
+/**
+ * Close a `worma gen` run with the change-record pointer: the id(s) written by
+ * this run plus the command showing their details.
+ *
+ * A run that recorded nothing (the source document did not change) prints no
+ * closing line at all.
+ */
+function printRecordedChanges(recorded) {
+    if (recorded.length === 0)
+        return;
+    const totals = recorded.reduce((acc, change) => ({
+        added: acc.added + change.added,
+        removed: acc.removed + change.removed,
+        modified: acc.modified + change.modified,
+    }), { added: 0, removed: 0, modified: 0 });
+    const ids = recorded.map(change => change.id).join(', ');
+    console.log(`\n  ${theme_1.theme.success('✔')} Changes recorded: ${theme_1.theme.label(ids)} ${theme_1.theme.dim(`(+${totals.added}/-${totals.removed}/~${totals.modified})`)}`);
+    console.log(`  ${theme_1.theme.dim('Run `worma diff latest` to view the details.')}\n`);
+}
+async function generateForProject(entry) {
     const { dir, configPath, config, generators } = entry;
     // Initialize renderer — prints pre-flight (Phase 1), starts live-update (Phase 2)
     const renderer = new renderer_1.MultiGeneratorRenderer(generators, pkg.version, configPath);
@@ -216,8 +369,8 @@ async function generateForProject(entry, force) {
         renderer.setActive(i);
     }
     // Unified entry — generate() creates per-gen trackers internally
+    const recorded = [];
     const results = await (0, generate_1.default)(config, {
-        force,
         projectPath: dir,
         onProgress(event) {
             switch (event.phase) {
@@ -238,8 +391,12 @@ async function generateForProject(entry, force) {
                     break;
             }
         },
+        onChangeRecorded(change) {
+            recorded.push(change);
+        },
     });
     // Finalize — Phase 3: stop live-update, show concise ✔/✖ summary
     const failedCount = results.filter(r => !r).length;
     renderer.finalize(failedCount);
+    printRecordedChanges(recorded);
 }

package/dist/bin/cli.js

@@ -19,9 +19,15 @@ program
 program
     .command('gen')
     .description('generate API from OpenAPI specs')
-    .option('-f, --force', 'force generate api')
     .option('-d, --debug', 'enable debug logging')
     .option('-p, --project <path>', 'project directory (single project mode)')
     .action(actions_1.actionGen);
+program
+    .command('diff')
+    .description('browse recorded API changes')
+    .argument('[id]', 'change id (e.g. 0007) or `latest`; omit to list all')
+    .option('-l, --list', 'list all recorded changes')
+    .option('-p, --project <path>', 'project directory')
+    .action(actions_1.actionDiff);
 program.parse(process.argv);
 /* c8 ignore stop */

package/dist/bin/renderer.js

@@ -161,9 +161,6 @@ class MultiGeneratorRenderer {
             else if (st.status === 'failed') {
                 row += `\n      ${theme_1.theme.error(`✖ ${st.error || 'failed'}`)}`;
             }
-            else if (st.status === 'skipped') {
-                row += `  ${theme_1.theme.dim('up-to-date')}`;
-            }
             // Add blank line between rows for readability
             lines.push(row);
             lines.push('');
@@ -201,7 +198,7 @@ class MultiGeneratorRenderer {
             console.log(theme_1.theme.success('\n✔ Generated successfully!\n'));
         }
         else {
-            console.log(theme_1.theme.dim('\n  Try `worma gen -f` to force regenerate.\n'));
+            console.log(theme_1.theme.dim('\n  Generation finished with failures. See the log above for details.\n'));
         }
     }
 }
@@ -400,9 +397,6 @@ class MultiProjectRenderer {
                     else if (st.status === 'failed') {
                         row += `\n      ${theme_1.theme.error(`✖ ${st.error || 'failed'}`)}`;
                     }
-                    else if (st.status === 'skipped') {
-                        row += `  ${theme_1.theme.dim('up-to-date')}`;
-                    }
                     lines.push(row);
                     lines.push('');
                 }
@@ -471,7 +465,7 @@ class MultiProjectRenderer {
             console.log(theme_1.theme.success('\n✔ Generated successfully!\n'));
         }
         else {
-            console.log(theme_1.theme.dim('\n  Try `worma gen -f` to force regenerate.\n'));
+            console.log(theme_1.theme.dim('\n  Generation finished with failures. See the log above for details.\n'));
         }
     }
 }

package/dist/checkUpdates.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkUpdates = checkUpdates;
+const helper_1 = require("./core/parser/openApiParser/helper");
+const prepareConfig_1 = require("./functions/prepareConfig");
+const wormaJson_1 = require("./functions/wormaJson");
+/**
+ * Detect whether the configured OpenAPI sources changed since the last
+ * recorded baseline.
+ *
+ * This is a **source-level, side-effect free** check:
+ *
+ * - it only hashes the raw spec text — no parsing, no plugin hooks;
+ * - it only reads/writes the `source` sub-field of `index.json` entries, never
+ *   the generation-side `hash` / `tags`;
+ * - when no baseline exists yet (`new`) it writes the baseline silently and
+ *   does *not* report a change (first run must not nag the user).
+ *
+ * Nothing on the user's disk is rewritten — callers decide what to do with the
+ * result (the VS Code extension asks for confirmation before generating).
+ */
+async function checkUpdates(config, options) {
+    const projectPath = options?.projectPath ?? process.cwd();
+    const generators = config?.generator ?? [];
+    const cacheIndex = await (0, wormaJson_1.readCacheIndex)(projectPath);
+    const hasGenerationBaseline = !!cacheIndex?.entries?.some(entry => !!entry.tags && Object.keys(entry.tags).length > 0);
+    // Collect `new` baselines and persist them in a single pass after the
+    // concurrent checks finish. Writing inside the `Promise.all` below would let
+    // the generators race on the same `index.json` (read → modify → write), so
+    // only the last writer's baseline would survive.
+    const baselineWrites = [];
+    const updates = await Promise.all(generators.map(async (gen, index) => {
+        // Run plugin `config` hooks (the same step the generator pipeline performs
+        // via ConfigManager/prepareConfig) so that `gen.input` is populated. Without
+        // this, configs that supply the OpenAPI source through a platform plugin
+        // (e.g. `swagger('petstore.json')`) leave `gen.input` empty, and the source
+        // fetch resolves to the project directory itself → "Cannot find module
+        // '<projectPath>'".
+        const prepared = await (0, prepareConfig_1.prepareConfig)(gen, projectPath);
+        const output = prepared.output ?? '';
+        const info = { index, output, serverName: prepared.serverName, status: 'unchanged' };
+        let text;
+        let resolvedInput;
+        try {
+            const urls = Array.isArray(prepared.input) ? prepared.input : [prepared.input ?? ''];
+            const raw = await (0, helper_1.getRawSpecText)(urls, {
+                projectPath,
+                fetchOptions: gen.fetchOptions,
+            });
+            text = raw.text;
+            resolvedInput = raw.url;
+        }
+        catch (error) {
+            info.status = 'error';
+            info.error = error?.message ?? String(error);
+            return info;
+        }
+        const hash = (0, wormaJson_1.computeSpecHash)(text);
+        info.resolvedInput = resolvedInput;
+        info.hash = hash;
+        let previous;
+        try {
+            previous = (await (0, wormaJson_1.getCacheEntry)(projectPath, output))?.source?.rawHash;
+        }
+        catch {
+            previous = undefined;
+        }
+        if (previous === undefined) {
+            // First sight of this source — record the baseline, stay silent.
+            info.status = 'new';
+            baselineWrites.push({
+                outputPath: output,
+                serverName: prepared.serverName ?? '',
+                source: {
+                    resolvedInput,
+                    rawHash: hash,
+                    updatedAt: Date.now(),
+                },
+            });
+        }
+        else if (previous !== hash) {
+            info.status = 'changed';
+        }
+        else {
+            info.status = 'unchanged';
+        }
+        return info;
+    }));
+    if (baselineWrites.length > 0)
+        await (0, wormaJson_1.updateSourceBaselines)(projectPath, baselineWrites);
+    return {
+        projectPath,
+        updates,
+        hasChanges: updates.some(u => u.status === 'changed'),
+        hasGenerationBaseline,
+    };
+}
+exports.default = checkUpdates;

package/dist/config.js

@@ -6,6 +6,13 @@ const DEFAULT_CONFIG = {
     cacheDir: '.worma-cache',
     /** Overrides cacheDir's parent directory for monorepo unified cache. */
     cacheRoot: undefined,
+    /**
+     * Maximum number of `changes/<NNNN>.json` records to keep.
+     * `0` (or any non-positive value) keeps every record.
+     */
+    changeHistoryLimit: 100,
+    /** 用户自定义的产物格式化配置，未设置时使用内置默认值 */
+    format: undefined,
     Error,
     templateData: new Map(),
 };

package/dist/constant.js

@@ -26,7 +26,6 @@ var PlatformTypeEnum;
 (function (PlatformTypeEnum) {
     PlatformTypeEnum["SWAGGER"] = "swagger";
     PlatformTypeEnum["KNIFE4J"] = "knife4j";
-    PlatformTypeEnum["FASTAPI"] = "fastapi";
     PlatformTypeEnum["YAPI"] = "yapi";
 })(PlatformTypeEnum || (exports.PlatformTypeEnum = PlatformTypeEnum = {}));
 /** Module system type */
@@ -96,9 +95,9 @@ var PluginName;
     PluginName["IMPORT_TYPE"] = "importType";
     PluginName["AI_DOC"] = "aiDoc";
     PluginName["APIFOX"] = "apifox";
+    PluginName["POSTMAN"] = "postman";
     PluginName["SWAGGER"] = "swagger";
     PluginName["KNIFE4J"] = "knife4j";
-    PluginName["FASTAPI"] = "fastapi";
     PluginName["YAPI"] = "yapi";
     PluginName["TEMPLATE_ALOVA"] = "templateAlova";
     PluginName["TEMPLATE_ALOVA_GLOBALS"] = "templateAlovaGlobals";

package/dist/core/WorkerPool.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkerPool = void 0;
 exports.pickPoolSize = pickPoolSize;
+exports.resolvePoolSize = resolvePoolSize;
 /**
  * 9.3.1: Generic WorkerPool — pure thread pool for task/result patterns.
  * Handles lifecycle, task distribution, and result collection.
@@ -21,6 +22,19 @@ function pickPoolSize(apiCount) {
         return Math.min(Math.ceil(cpu * 0.75), cpu);
     return Math.max(2, cpu - 1);
 }
+/**
+ * Resolve the worker pool size from the user-facing `performance.workerPool` strategy:
+ * - `false` disables workers entirely (conversion stays on the main thread)
+ * - a number pins the pool size (clamped to >= 0)
+ * - `'auto'` / omitted uses the adaptive {@link pickPoolSize} heuristic
+ */
+function resolvePoolSize(apiCount, strategy) {
+    if (strategy === false)
+        return 0;
+    if (typeof strategy === 'number')
+        return Math.max(0, Math.floor(strategy));
+    return pickPoolSize(apiCount);
+}
 class WorkerPool {
     options;
     workers = [];

package/dist/core/loader/callingCodeLoader/helper.js

@@ -177,7 +177,6 @@ exports.generateDefaultValues = generateDefaultValues;
  * @returns Object containing type and interface default values
  */
 function generateDefaultValuesFormat(sourceCode) {
-    return (0, utils_1.format)((0, exports.generateDefaultValues)(sourceCode), {
-        parser: 'json',
-    });
+    // 产物是对象字面量，用 .json 让 oxfmt 按 JSON 解析（oxfmt 无 prettier 的 parser 选项，按扩展名推断）
+    return (0, utils_1.format)('default-values.json', (0, exports.generateDefaultValues)(sourceCode));
 }

package/dist/core/loader/callingCodeLoader/index.js

@@ -22,7 +22,7 @@ class CallingCodeLoader {
         if (api.requestBodyComment) {
             configStrArr.push(`data: ${await this.transform(api.requestBodyComment.replace(/\*/g, ''))}`);
         }
-        return (0, utils_1.format)(`${api.name}({${configStrArr.join(',\n')}})`, {
+        return (0, utils_1.format)('calling-code.ts', `${api.name}({${configStrArr.join(',\n')}})`, {
             printWidth: 40, // Shorten print width to force line breaks
             tabWidth: 2,
             semi: false, // Remove the trailing semicolon

package/dist/core/parser/openApiParser/helper.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRawSpecText = getRawSpecText;
 exports.getOpenApiDataWithUrl = getOpenApiDataWithUrl;
 exports.getOpenApiData = getOpenApiData;
 const node_fs_1 = require("node:fs");
@@ -81,8 +82,11 @@ const isRemoteUrl = (u) => /^https?:\/\//.test(u);
 /**
  * Fetch the raw spec text (JSON/YAML) from the first URL that succeeds.
  * Returns the raw text together with the resolved URL; throws if all URLs fail.
+ *
+ * Exported as `getRawSpecText` so that update detection (requirement A) can
+ * hash the source without parsing it or running any plugin hook.
  */
-async function fetchRawText(urls, options) {
+async function getRawSpecText(urls, options) {
     if (urls.length === 0) {
         throw helper_1.logger.throwError('No URLs provided to fetch OpenAPI document');
     }
@@ -97,22 +101,13 @@ async function fetchRawText(urls, options) {
             const text = isRemoteUrl(u)
                 ? await fetchRawRemoteFile(u, fetchOptions)
                 : await fetchRawLocalFile(u, projectPath);
-            // Quick parse + validity check (full parse + Swagger2→OpenAPI3 conversion
-            // happens later in parseSpec, after beforeSpecParse may rewrite the text).
-            let probe;
-            try {
-                probe = JSON.parse(text);
-            }
-            catch (jsonError) {
-                try {
-                    probe = js_yaml_1.default.load(text);
-                }
-                catch (yamlError) {
-                    throw new Error(`${u}: ${(jsonError instanceof Error ? jsonError.message : String(jsonError))} (YAML: ${yamlError instanceof Error ? yamlError.message : String(yamlError)})`);
-                }
-            }
-            if (!isValidOpenApiData(probe)) {
-                throw new Error(`${u} did not yield a valid OpenAPI/Swagger document`);
+            // Nothing is parsed here on purpose: the OpenAPI validity check runs in
+            // parseSpec, i.e. after `beforeSpecParse` may rewrite the text. Only
+            // payloads that can never be a spec (HTML error pages, e.g. a Swagger UI
+            // page hit instead of its spec document) are rejected so that Promise.any
+            // falls through to the next URL.
+            if (!couldBeSpecText(text)) {
+                throw new Error(`${u} did not yield a usable OpenAPI/Swagger payload`);
             }
             return { text, url: u };
         })();
@@ -127,6 +122,24 @@ async function fetchRawText(urls, options) {
         throw helper_1.logger.throwError(`Unable to retrieve valid OpenAPI document from any URL:\n${errors.join('\n')}`);
     }
 }
+/**
+ * Keywords every OpenAPI/Swagger document carries, either as a JSON key
+ * (`"openapi": "3.0.3"`) or as a YAML key (`openapi: 3.0.3`). Escaped forms are
+ * matched as well, so an envelope such as `{ "output": "{\"openapi\":...}" }`
+ * still passes and can be unwrapped by `beforeSpecParse`. The optional leading
+ * `\\` accounts for the backslash JSON adds when the spec is embedded as a
+ * string (e.g. the Postman transformation response).
+ */
+const SPEC_KEYWORD_RE = /\\?["']?(?:openapi|swagger|paths)\\?["']?\s*:/;
+/**
+ * Cheap, parse-free guard for a fetched candidate: the text must mention a spec
+ * keyword, so HTML pages and unrelated JSON payloads are rejected early and
+ * Promise.any falls through to the next URL. The authoritative validity check
+ * still happens in `parseSpec`, i.e. after `beforeSpecParse` may rewrite the text.
+ */
+function couldBeSpecText(text) {
+    return SPEC_KEYWORD_RE.test(text);
+}
 // Validate OpenAPI data
 function isValidOpenApiData(data) {
     if (!data || typeof data !== 'object') {
@@ -184,7 +197,7 @@ async function getOpenApiDataWithUrl(url, options) {
     const { projectPath, fetchOptions, beforeSpecParse } = options ?? {};
     // Normalize to array — single string or array both handled uniformly
     const urls = Array.isArray(url) ? url : [url];
-    const { text, url: resolvedUrl } = await fetchRawText(urls, { projectPath, fetchOptions });
+    const { text, url: resolvedUrl } = await getRawSpecText(urls, { projectPath, fetchOptions });
     // Allow the caller (e.g. a `beforeSpecParse` plugin hook) to transform the
     // raw spec text before it is parsed into an OpenAPIDocument.
     const finalText = (beforeSpecParse ? await beforeSpecParse(text) : text) ?? text;
@@ -196,7 +209,7 @@ async function getOpenApiDataWithUrl(url, options) {
             fetchOptions,
         });
     }
-    return { data: result, resolvedUrl };
+    return { data: result, resolvedUrl, rawText: text };
 }
 /**
  * Parse OpenAPI document from config input.

package/dist/core/parser/templateParser/index.js

@@ -60,8 +60,14 @@ async function pMap(items, fn, concurrency) {
     await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
     return results;
 }
-/** Automatically compute a reasonable concurrency limit based on CPU core count */
-function autoConcurrency() {
+/**
+ * Resolve the transform-phase concurrency limit.
+ * An explicit positive `performance.transformConcurrency` wins; otherwise it is
+ * computed from the CPU core count.
+ */
+function autoConcurrency(configured) {
+    if (typeof configured === 'number' && configured > 0)
+        return Math.max(1, Math.floor(configured));
     const cpuCount = Math.max(1, (0, node_os_1.cpus)().length);
     return Math.min(64, Math.max(8, cpuCount * 4));
 }
@@ -129,7 +135,8 @@ class TemplateParser {
         return result;
     }
     async parseApiMethods(apiMethods, templateData) {
-        const concurrency = autoConcurrency();
+        const perf = this.options.generatorConfig.performance;
+        const concurrency = autoConcurrency(perf?.transformConcurrency);
         const apiMethodArray = (await pMap(apiMethods, apiMethod => this.transformApiMethods(apiMethod), concurrency)).filter(apiMethod => !!apiMethod);
         const refsMap = Object.fromEntries(this.refNameMap);
         const usedRefs = this.openApiHelper
@@ -137,7 +144,7 @@ class TemplateParser {
             .filterUsedReferences(Object.keys(refsMap));
         this.refNameMap = new Map(Object.entries((0, openapi_1.optimizeRefsMap)(refsMap, usedRefs)));
         // M4-C1: Pre-process schemas via worker pool for parallel schema→TS conversion
-        const poolSize = (0, WorkerPool_1.pickPoolSize)(apiMethodArray.length);
+        const poolSize = (0, WorkerPool_1.resolvePoolSize)(apiMethodArray.length, perf?.workerPool);
         if (poolSize > 0) {
             const tasks = this.collectSchemaTasks(apiMethodArray);
             if (tasks.length > 0) {
@@ -147,10 +154,11 @@ class TemplateParser {
                 const { existsSync: fex } = await Promise.resolve().then(() => __importStar(require('node:fs')));
                 const workerScript = fex(jsWp) ? jsWp : tsWp;
                 // Reuse workers only within the same generator output. The workerData document is immutable after spawn,
-                // so generators in the same project must not share a pool.
+                // so generators in the same project must not share a pool. The pool size is part of the key so a
+                // reconfiguration never silently reuses a pool with a different size.
                 const outputDir = node_path_1.default.resolve(this.options.projectPath, this.options.generatorConfig.output);
                 const pool = poolManager_1.PoolManager.getInstance().get({
-                    key: `schemaWorker_${outputDir}`,
+                    key: `schemaWorker_${outputDir}_${poolSize}`,
                     workerScript,
                     sharedContext: {
                         document: this.document,
@@ -173,12 +181,17 @@ class TemplateParser {
             .forEach((api) => {
             this.parseApi(api, templateData);
         });
-        templateData.components = [...new Set(this.schemasMap.values())];
-        templateData.componentNames = [...this.schemasMap.keys()];
-        // sort by name lexicographically to ensure deterministic output order (avoid Map insertion-order drift under concurrency)
-        const sorted = [...this.schemasMap.entries()].sort(([a], [b]) => a.localeCompare(b));
-        templateData.componentNames = sorted.map(([k]) => k);
-        templateData.components = sorted.map(([, v]) => v);
+        if (perf?.deterministicSort === false) {
+            // Opt-out: keep the collection order, which may drift with worker scheduling.
+            templateData.components = [...new Set(this.schemasMap.values())];
+            templateData.componentNames = [...this.schemasMap.keys()];
+        }
+        else {
+            // sort by name lexicographically to ensure deterministic output order (avoid Map insertion-order drift under concurrency)
+            const sorted = [...this.schemasMap.entries()].sort(([a], [b]) => a.localeCompare(b));
+            templateData.componentNames = sorted.map(([k]) => k);
+            templateData.components = sorted.map(([, v]) => v);
+        }
     }
     /**
      * M4-C1: Collect all unique schema objects from API methods for batch processing.

package/dist/core/workerPool/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WorkerPool = exports.pickPoolSize = void 0;
+exports.WorkerPool = exports.resolvePoolSize = exports.pickPoolSize = void 0;
 var WorkerPool_1 = require("../WorkerPool");
 Object.defineProperty(exports, "pickPoolSize", { enumerable: true, get: function () { return WorkerPool_1.pickPoolSize; } });
+Object.defineProperty(exports, "resolvePoolSize", { enumerable: true, get: function () { return WorkerPool_1.resolvePoolSize; } });
 Object.defineProperty(exports, "WorkerPool", { enumerable: true, get: function () { return WorkerPool_1.WorkerPool; } });