wormajs 0.4.0 → 1.0.0-beta.0

package/dist/functions/wormaJson.js

@@ -3,21 +3,32 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCacheRoot = getCacheRoot;
+exports.cacheDirPath = cacheDirPath;
 exports.toCacheRelativePath = toCacheRelativePath;
+exports.stableStringify = stableStringify;
+exports.parseSpecText = parseSpecText;
+exports.normalizeSpecText = normalizeSpecText;
+exports.computeSpecHash = computeSpecHash;
 exports.computeApiHash = computeApiHash;
 exports.computePerTagHashes = computePerTagHashes;
 exports.readCacheIndex = readCacheIndex;
 exports.writeApiCacheEntry = writeApiCacheEntry;
 exports.writeCacheIndex = writeCacheIndex;
 exports.writeCacheEntry = writeCacheEntry;
+exports.updateSourceBaselines = updateSourceBaselines;
+exports.updateSourceBaseline = updateSourceBaseline;
 exports.readCacheApis = readCacheApis;
 exports.readAllCacheApis = readAllCacheApis;
 exports.getCacheEntry = getCacheEntry;
+exports.hasGenerationBaseline = hasGenerationBaseline;
+exports.readChangeSeq = readChangeSeq;
 exports.diffChangedTags = diffChangedTags;
 exports.toCacheData = toCacheData;
 const node_crypto_1 = require("node:crypto");
 const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
 const config_1 = require("../config");
 // ---- Directory-based cache format ----
 const CACHE_SCHEMA_VERSION = 1;
@@ -46,6 +57,58 @@ function toCacheRelativePath(projectPath, outputPath) {
         : node_path_1.default.resolve(projectPath, outputPath);
     return (node_path_1.default.relative(cacheRoot, absoluteOutput) || '.').replace(/\\/g, '/');
 }
+// ---- Spec text normalization + hashing (requirement A) ----
+/**
+ * Deterministic JSON serialization: object keys are sorted so that two
+ * semantically equal documents always produce the same string.
+ */
+function stableStringify(value) {
+    if (value === undefined)
+        return 'undefined';
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map(k => `${JSON.stringify(k)}:${stableStringify(record[k])}`).join(',')}}`;
+}
+/**
+ * Parse a raw spec text (JSON or YAML) into a plain structure.
+ * Throws when the text cannot be parsed at all.
+ */
+function parseSpecText(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        const loaded = js_yaml_1.default.load(text);
+        if (loaded !== undefined)
+            return loaded;
+        throw new Error('Unable to parse spec text as JSON or YAML');
+    }
+}
+/**
+ * Normalize a raw spec text into a canonical form so that cosmetic differences
+ * (key order, indentation, JSON vs YAML, trailing whitespace) collapse into the
+ * same value. Falls back to the raw (trimmed) text when it is not a structured
+ * document.
+ */
+function normalizeSpecText(text) {
+    try {
+        const parsed = parseSpecText(text);
+        if (parsed && typeof parsed === 'object')
+            return stableStringify(parsed);
+    }
+    catch { /* not a structured document — fall through */ }
+    return text.trim();
+}
+/**
+ * Compute a stable hash of a raw spec text (JSON or YAML).
+ * Stable across key reordering, whitespace and JSON/YAML equivalence.
+ */
+function computeSpecHash(text) {
+    return (0, node_crypto_1.createHash)('sha256').update(normalizeSpecText(text)).digest('hex').slice(0, 16);
+}
 // ---- M3-B2: API hash computation ----
 /**
  * P2: WeakMap cache for per-Api hashes. Same Api object reused across
@@ -101,77 +164,248 @@ function computePerTagHashes(allApis, tagedApis) {
 }
 // ---- M3-B3: New format read/write ----
 async function readCacheIndex(projectRoot) {
+    const indexFile = node_path_1.default.join(cacheDirPath(projectRoot), 'index.json');
+    // Retry on parse failures: `index.json` is replaced (not appended to) by its
+    // writers, so a concurrent writer can leave a truncated file behind. Reading
+    // it as `null` would make the next writer start from an empty index and drop
+    // `changeSeq` / `tags` / `source` baselines accumulated so far.
+    for (let attempt = 0; attempt < 3; attempt++) {
+        let content;
+        try {
+            content = await promises_1.default.readFile(indexFile, 'utf-8');
+        }
+        catch {
+            return null; // no cache yet
+        }
+        try {
+            const index = JSON.parse(content);
+            if (index.schemaVersion !== CACHE_SCHEMA_VERSION)
+                return null;
+            if (!Array.isArray(index.entries))
+                return null;
+            return index;
+        }
+        catch {
+            // Partially written file — back off briefly and re-read.
+            if (attempt < 2)
+                await new Promise(resolve => setTimeout(resolve, 10 * (attempt + 1)));
+        }
+    }
+    return null;
+}
+/** Whether `<cacheRoot>/.worma-cache/index.json` exists on disk (readable or not). */
+async function cacheIndexExists(projectRoot) {
     try {
-        const indexFile = node_path_1.default.join(cacheDirPath(projectRoot), 'index.json');
-        const content = await promises_1.default.readFile(indexFile, 'utf-8');
-        const index = JSON.parse(content);
-        if (index.schemaVersion !== CACHE_SCHEMA_VERSION)
-            return null;
-        if (!Array.isArray(index.entries))
-            return null;
-        return index;
+        await promises_1.default.access(node_path_1.default.join(cacheDirPath(projectRoot), 'index.json'));
+        return true;
     }
     catch {
-        return null;
+        return false;
     }
 }
-/** Write a single entry's API data file to disk (without updating index). */
-async function writeApiCacheEntry(projectRoot, outputPath, serverName, apis) {
-    const dataDir = node_path_1.default.join(cacheDirPath(projectRoot), 'data');
-    const slug = slugify(outputPath);
-    const entryFile = node_path_1.default.join(dataDir, `${slug}.json`);
-    await promises_1.default.mkdir(node_path_1.default.dirname(entryFile), { recursive: true });
-    await promises_1.default.writeFile(entryFile, JSON.stringify({ serverName, apis }));
+/** Directory holding one cache entry's per-tag data files: `data/<slug>/<tag>.json` */
+function dataEntryDir(projectRoot, relativePath) {
+    return node_path_1.default.join(cacheDirPath(projectRoot), 'data', slugify(relativePath));
 }
-/** Write/update the cache index.json from pre-computed entries. */
-async function writeCacheIndex(projectRoot, newEntries) {
-    const dir = cacheDirPath(projectRoot);
-    let index;
-    try {
-        const indexFile = node_path_1.default.join(dir, 'index.json');
-        index = JSON.parse(await promises_1.default.readFile(indexFile, 'utf-8'));
-        if (index.schemaVersion !== CACHE_SCHEMA_VERSION)
-            index = { schemaVersion: CACHE_SCHEMA_VERSION, entries: [] };
+/** Legacy single-file location kept for backward-compatible reads: `data/<slug>.json` */
+function legacyDataEntryFile(projectRoot, relativePath) {
+    return node_path_1.default.join(cacheDirPath(projectRoot), 'data', `${slugify(relativePath)}.json`);
+}
+function tagFileName(tag) {
+    return `${slugify(tag) || '_default'}.json`;
+}
+/**
+ * Write a single entry's API data files to disk (without updating index).
+ *
+ * Data is stored **per tag** (`data/<slug>/<tag>.json`) so that a large spec
+ * only rewrites the files of the tags that actually changed. Tag files that no
+ * longer exist in `apis` are removed.
+ */
+async function writeApiCacheEntry(projectRoot, outputPath, serverName, apis) {
+    const relativePath = toCacheRelativePath(projectRoot, outputPath);
+    const dir = dataEntryDir(projectRoot, relativePath);
+    await promises_1.default.mkdir(dir, { recursive: true });
+    const byTag = new Map();
+    for (const api of apis) {
+        const tag = api.tag ?? '';
+        const list = byTag.get(tag) || [];
+        list.push(api);
+        byTag.set(tag, list);
     }
-    catch {
-        index = { schemaVersion: CACHE_SCHEMA_VERSION, entries: [] };
+    const kept = new Set();
+    for (const [tag, tagApis] of byTag) {
+        const fileName = tagFileName(tag);
+        kept.add(fileName);
+        await promises_1.default.writeFile(node_path_1.default.join(dir, fileName), JSON.stringify({ serverName, tag, apis: tagApis }));
     }
-    for (const newEntry of newEntries) {
-        const existingIdx = index.entries.findIndex(e => e.path === newEntry.path);
-        if (existingIdx >= 0)
-            index.entries[existingIdx] = newEntry;
-        else
-            index.entries.push(newEntry);
+    // Drop tag files of tags that disappeared from the spec
+    let existing = [];
+    try {
+        existing = await promises_1.default.readdir(dir);
     }
-    index.entries.sort((a, b) => a.path.localeCompare(b.path));
-    await promises_1.default.mkdir(dir, { recursive: true });
-    await promises_1.default.writeFile(node_path_1.default.join(dir, 'index.json'), JSON.stringify(index));
+    catch { /* directory may not exist yet */ }
+    await Promise.all(existing
+        .filter(name => name.endsWith('.json') && !kept.has(name))
+        .map(name => promises_1.default.unlink(node_path_1.default.join(dir, name)).catch(() => { })));
+}
+/**
+ * Serializes every write to `index.json`.
+ *
+ * Writing the index is a read → modify → write-whole-file operation shared by
+ * three call sites that all run concurrently (`flushAllData` after a
+ * generation, `checkUpdates()` baselines and `captureChange()`'s sequence
+ * counter). Chaining them makes the operation atomic with respect to itself, so
+ * no writer can drop another's `entries`, `source` baseline or `changeSeq`.
+ */
+let indexWriteChain = Promise.resolve();
+function enqueueIndexWrite(task) {
+    // `.then(task, task)` keeps the chain alive even if a previous write rejected.
+    const run = indexWriteChain.then(task, task);
+    indexWriteChain = run.catch(() => { });
+    return run;
 }
-async function writeCacheEntry(projectRoot, outputPath, serverName, apis, hashInfo) {
+/** Write/update the cache index.json from pre-computed entries. */
+function writeCacheIndex(projectRoot, newEntries, options) {
+    return enqueueIndexWrite(async () => {
+        const dir = cacheDirPath(projectRoot);
+        // `readCacheIndex` retries transient read failures; falling back to an
+        // empty index here would silently drop `changeSeq` and every `source` /
+        // `tags` baseline accumulated so far.
+        const index = (await readCacheIndex(projectRoot)) ?? { schemaVersion: CACHE_SCHEMA_VERSION, entries: [] };
+        if (!Array.isArray(index.entries))
+            index.entries = [];
+        for (const newEntry of newEntries) {
+            const existingIdx = index.entries.findIndex(e => e.path === newEntry.path);
+            if (existingIdx >= 0) {
+                // Preserve the detection baseline (`source`) written by checkUpdates()
+                index.entries[existingIdx] = {
+                    ...newEntry,
+                    source: newEntry.source ?? index.entries[existingIdx].source,
+                };
+            }
+            else {
+                index.entries.push(newEntry);
+            }
+        }
+        index.entries.sort((a, b) => a.path.localeCompare(b.path));
+        if (options?.changeSeq !== undefined)
+            index.changeSeq = options.changeSeq;
+        await promises_1.default.mkdir(dir, { recursive: true });
+        await promises_1.default.writeFile(node_path_1.default.join(dir, 'index.json'), JSON.stringify(index));
+    });
+}
+async function writeCacheEntry(projectRoot, outputPath, serverName, apis, hashInfo, source) {
     // Resolve to cache-root-relative path: in monorepo this produces e.g. "packages/a/src/api"
     const relativePath = toCacheRelativePath(projectRoot, outputPath);
     await writeApiCacheEntry(projectRoot, relativePath, serverName, apis);
-    await writeCacheIndex(projectRoot, [{ path: relativePath, serverName, hash: hashInfo.hash, tags: hashInfo.tags }]);
+    await writeCacheIndex(projectRoot, [{
+            path: relativePath,
+            serverName,
+            hash: hashInfo.hash,
+            tags: hashInfo.tags,
+            source,
+        }]);
 }
-/** Read APIs from cache directory */
-async function readCacheApis(projectRoot, outputPath) {
-    const relativePath = toCacheRelativePath(projectRoot, outputPath);
-    const index = await readCacheIndex(projectRoot);
-    if (index) {
-        const entry = index.entries.find(e => e.path === relativePath);
-        if (entry) {
-            const slug = slugify(relativePath);
-            const entryFile = node_path_1.default.join(cacheDirPath(projectRoot), 'data', `${slug}.json`);
-            try {
-                const content = JSON.parse(await promises_1.default.readFile(entryFile, 'utf-8'));
-                return { path: relativePath, serverName: content.serverName, apis: content.apis };
+/**
+ * Update **only** the `source` sub-field of cache index entries, leaving the
+ * generation-side `hash` / `tags` untouched. Used by update detection
+ * (requirement A) so that checking for updates never invalidates the
+ * incremental-render baseline.
+ *
+ * All records are merged in a **single** read → write pass (no lost updates),
+ * and concurrent callers are serialized through {@link enqueueIndexWrite}.
+ */
+function updateSourceBaselines(projectRoot, records) {
+    if (records.length === 0)
+        return Promise.resolve();
+    return enqueueIndexWrite(async () => {
+        const dir = cacheDirPath(projectRoot);
+        const existing = await readCacheIndex(projectRoot);
+        if (!existing && await cacheIndexExists(projectRoot)) {
+            // `index.json` exists but could not be read (another writer is mid-write,
+            // or the file is corrupt). Writing a fresh index here would wipe the
+            // generation baseline (`hash` / `tags`) and `changeSeq`, so skip this
+            // baseline refresh instead — detection is best-effort, generation is not.
+            return;
+        }
+        const index = existing ?? { schemaVersion: CACHE_SCHEMA_VERSION, entries: [] };
+        for (const { outputPath, serverName, source } of records) {
+            const relativePath = toCacheRelativePath(projectRoot, outputPath);
+            const idx = index.entries.findIndex(e => e.path === relativePath);
+            if (idx >= 0) {
+                index.entries[idx] = {
+                    ...index.entries[idx],
+                    source: { ...index.entries[idx].source, ...source },
+                };
             }
-            catch {
-                return null;
+            else {
+                index.entries.push({
+                    path: relativePath,
+                    serverName: serverName ?? '',
+                    hash: '',
+                    tags: {},
+                    source,
+                });
             }
         }
+        await promises_1.default.mkdir(dir, { recursive: true });
+        await promises_1.default.writeFile(node_path_1.default.join(dir, 'index.json'), JSON.stringify(index));
+    });
+}
+/**
+ * Update a single entry's `source` baseline. Thin wrapper over
+ * {@link updateSourceBaselines} so existing call sites stay concurrency-safe.
+ */
+function updateSourceBaseline(projectRoot, outputPath, source, serverName = '') {
+    return updateSourceBaselines(projectRoot, [{ outputPath, serverName, source }]);
+}
+/** Read one entry's APIs, aggregating every `data/<slug>/<tag>.json` file. */
+async function readEntryApis(projectRoot, relativePath, fallbackServerName = '') {
+    const dir = dataEntryDir(projectRoot, relativePath);
+    let files = [];
+    try {
+        files = await promises_1.default.readdir(dir);
     }
-    return null;
+    catch {
+        // Legacy single-file layout (pre per-tag split)
+        try {
+            const content = JSON.parse(await promises_1.default.readFile(legacyDataEntryFile(projectRoot, relativePath), 'utf-8'));
+            return {
+                path: relativePath,
+                serverName: content.serverName || fallbackServerName,
+                apis: content.apis || [],
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    const apis = [];
+    let serverName = fallbackServerName;
+    for (const name of files) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const content = JSON.parse(await promises_1.default.readFile(node_path_1.default.join(dir, name), 'utf-8'));
+            if (content?.serverName)
+                serverName = content.serverName;
+            if (Array.isArray(content?.apis))
+                apis.push(...content.apis);
+        }
+        catch { /* skip corrupted data file */ }
+    }
+    return { path: relativePath, serverName, apis };
+}
+/** Read APIs from cache directory */
+async function readCacheApis(projectRoot, outputPath) {
+    const relativePath = toCacheRelativePath(projectRoot, outputPath);
+    const index = await readCacheIndex(projectRoot);
+    if (!index)
+        return null;
+    const entry = index.entries.find(e => e.path === relativePath);
+    if (!entry)
+        return null;
+    return readEntryApis(projectRoot, relativePath, entry.serverName || '');
 }
 /**
  * Read ALL cached API entries from the unified cache directory.
@@ -183,23 +417,14 @@ async function readAllCacheApis(projectRoot) {
     if (!index)
         return [];
     const results = [];
-    const dataDir = node_path_1.default.join(cacheDirPath(projectRoot), 'data');
     for (const entry of index.entries) {
-        const slug = slugify(entry.path);
-        const entryFile = node_path_1.default.join(dataDir, `${slug}.json`);
-        try {
-            const content = JSON.parse(await promises_1.default.readFile(entryFile, 'utf-8'));
-            results.push({
-                path: entry.path,
-                serverName: content.serverName || entry.serverName || '',
-                apis: content.apis || [],
-            });
-        }
-        catch { /* skip corrupted data file */ }
+        const data = await readEntryApis(projectRoot, entry.path, entry.serverName || '');
+        if (data)
+            results.push(data);
     }
     return results;
 }
-/** Get cache entry metadata (hash + tags) without loading APIs */
+/** Get cache entry metadata (hash + tags + source baseline) without loading APIs */
 async function getCacheEntry(projectRoot, outputPath) {
     const relativePath = toCacheRelativePath(projectRoot, outputPath);
     const index = await readCacheIndex(projectRoot);
@@ -207,6 +432,21 @@ async function getCacheEntry(projectRoot, outputPath) {
         return null;
     return index.entries.find(e => e.path === relativePath) ?? null;
 }
+/**
+ * Whether an entry carries a usable incremental-render baseline.
+ *
+ * Entries created by update detection (`updateSourceBaseline`) only hold a
+ * `source` baseline and have no `tags`, so they must NOT be treated as
+ * "everything already rendered".
+ */
+function hasGenerationBaseline(entry) {
+    return !!entry?.tags && Object.keys(entry.tags).length > 0;
+}
+/** Read the change-record sequence counter from index.json (requirement B). */
+async function readChangeSeq(projectRoot) {
+    const index = await readCacheIndex(projectRoot);
+    return index?.changeSeq ?? 0;
+}
 /** Find set of tags whose hash differs between old and new */
 function diffChangedTags(oldTags, newTags) {
     const changed = new Set();

package/dist/generate.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const poolManager_1 = require("./core/workerPool/poolManager");
+const changeReport_1 = require("./functions/changeReport");
 const helper_1 = require("./helper");
 const GeneratorHelper_1 = require("./helper/config/GeneratorHelper");
 const progress_1 = require("./helper/progress");
@@ -11,7 +12,7 @@ const progress_1 = require("./helper/progress");
  * its lifecycle via {@link GeneratorProgressEvent} discriminated union events.
  *
  * @param config generating config
- * @param options config rules that contains `force`, `projectPath`, `onProgress`
+ * @param options config rules that contains `projectPath`, `onProgress`
  * @returns An array that contains the result of `generator` items in configuration whether generation is successful.
  */
 async function generate(config, options) {
@@ -24,6 +25,9 @@ async function generate(config, options) {
     const helper = new helper_1.ConfigHelper();
     await helper.load(config, projectPath);
     const generators = helper.getConfig().generator;
+    // Requirement B: one change record per `generate()` run, aggregating every
+    // generator that actually changed something.
+    const changeItems = [];
     // Run all generators in parallel, each with its own ProgressTracker
     const results = await Promise.all(generators.map(async (gen, i) => {
         const generatorName = gen.input || `generator-${i}`;
@@ -45,10 +49,11 @@ async function generate(config, options) {
         tracker.start();
         try {
             const result = await GeneratorHelper_1.GeneratorHelper.generate(gen, {
-                force: options?.force,
                 projectPath,
                 tracker,
             });
+            if (result.change)
+                changeItems.push(result.change);
             emit?.({
                 index: i,
                 phase: result.success ? 'done' : 'skipped',
@@ -74,6 +79,23 @@ async function generate(config, options) {
             tracker.stop();
         }
     }));
+    // Requirement B: one record per run, written only when at least one generator
+    // observed a source-document change (keeps the history meaningful).
+    if (changeItems.length > 0) {
+        try {
+            const id = await (0, changeReport_1.captureChange)(projectPath, {
+                schemaVersion: 1,
+                createdAt: Date.now(),
+                projectPath,
+                generators: changeItems,
+            });
+            options?.onChangeRecorded?.({ id, ...(0, changeReport_1.countChanges)(changeItems) });
+        }
+        catch (error) {
+            // A failure to record history must never fail the generation itself.
+            helper_1.logger.debug('Failed to capture change record', { error: error?.message });
+        }
+    }
     helper_1.logger.debug('Flushing template data cache', { projectPath });
     await helper_1.TemplateHelper.flushAllData(projectPath);
     poolManager_1.PoolManager.getInstance().releaseAll();

package/dist/helper/config/ConfigHelper.js

@@ -45,9 +45,8 @@ class ConfigHelper {
             .generator.map(item => GeneratorHelper_1.GeneratorHelper.openApiData(item, this.projectPath)));
     }
     async generate(options) {
-        const { tracker, force } = options;
+        const { tracker } = options;
         const results = await Promise.all(this.configManager.getConfig().generator.map(item => GeneratorHelper_1.GeneratorHelper.generate(item, {
-            force,
             projectPath: this.projectPath,
             tracker,
         })));

package/dist/helper/config/ConfigManager.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConfigManager = void 0;
 const zod_validation_error_1 = require("zod-validation-error");
+const config_1 = require("../../config");
 const prepareConfig_1 = __importDefault(require("../../functions/prepareConfig"));
 const GeneratorHelper_1 = require("../../helper/config/GeneratorHelper");
 const logger_1 = require("../../helper/logger");
@@ -30,6 +31,9 @@ class ConfigManager {
         // update config
         this.config = validatedConfig;
         this.readConfig = Object.freeze(this.config);
+        // 同步格式化配置到全局，供 utils/format 读取。
+        // 每次加载都覆盖（含 undefined），避免跨次生成或测试之间互相污染。
+        (0, config_1.setGlobalConfig)({ format: validatedConfig.format });
         logger_1.logger.debug('Configuration loaded successfully', this.config);
     }
     /**
@@ -74,6 +78,9 @@ class ConfigManager {
             result.generator = userConfig.generator.map(config => ({
                 ...this.defaultGeneratorConfig,
                 ...config,
+                // Shallow-spreading would drop the per-field defaults when the user only
+                // sets part of `performance`, so merge that object one level deep.
+                performance: { ...this.defaultGeneratorConfig.performance, ...config.performance },
             }));
         }
         return result;