wormajs 0.3.1 → 1.0.0-beta.0

package/dist/functions/changeReport.js

@@ -0,0 +1,230 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LATEST_CHANGE_ID = void 0;
+exports.countChanges = countChanges;
+exports.changesDirPath = changesDirPath;
+exports.captureChange = captureChange;
+exports.listChanges = listChanges;
+exports.getChange = getChange;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const config_1 = require("../config");
+const wormaJson_1 = require("../functions/wormaJson");
+/** Alias accepted by {@link getChange} — resolves to the newest record. */
+exports.LATEST_CHANGE_ID = 'latest';
+/** Aggregate the change rows of every generator into flat counts. */
+function countChanges(generators) {
+    let added = 0;
+    let removed = 0;
+    let modified = 0;
+    for (const generator of generators) {
+        for (const change of generator.changes) {
+            if (change.op === '+')
+                added++;
+            else if (change.op === '-')
+                removed++;
+            else
+                modified++;
+        }
+    }
+    return { added, removed, modified };
+}
+/**
+ * Read one generator entry, upgrading legacy api-level entries on the fly.
+ *
+ * Legacy records stored `added` / `removed` / `modified` api lists with
+ * `changedFields` and carried no `schemaVersion`; normalising both shapes into
+ * flat rows means every consumer only ever handles the source-document model.
+ */
+function normalizeItem(raw) {
+    const output = String(raw?.output ?? '');
+    const serverName = raw?.serverName || undefined;
+    if (Array.isArray(raw?.changes))
+        return { output, serverName, resolvedInput: raw?.resolvedInput || undefined, changes: raw.changes };
+    const targetOf = (entry) => `${String(entry?.method ?? '').toUpperCase()} ${entry?.path ?? ''}`.trim();
+    const changes = [];
+    for (const entry of raw?.added ?? [])
+        changes.push({ op: '+', kind: 'api', target: targetOf(entry), detail: entry?.name || undefined, level: 'additive' });
+    for (const entry of raw?.removed ?? [])
+        changes.push({ op: '-', kind: 'api', target: targetOf(entry), detail: entry?.name || undefined, level: 'breaking' });
+    for (const entry of raw?.modified ?? []) {
+        changes.push({
+            op: '~',
+            kind: 'api',
+            target: targetOf(entry),
+            detail: (entry?.changedFields ?? []).join(', ') || undefined,
+            level: 'breaking',
+        });
+    }
+    return { output, serverName, changes };
+}
+/** `<cacheRoot>/changes/` — change records live next to the cache index. */
+function changesDirPath(projectRoot) {
+    return node_path_1.default.join((0, wormaJson_1.cacheDirPath)(projectRoot), 'changes');
+}
+function recordFile(projectRoot, id) {
+    return node_path_1.default.join(changesDirPath(projectRoot), `${id}.json`);
+}
+function padId(seq) {
+    return String(seq).padStart(4, '0');
+}
+function toSummary(change) {
+    return {
+        id: change.id,
+        createdAt: change.createdAt,
+        summary: {
+            generators: change.generators.length,
+            ...countChanges(change.generators),
+        },
+        outputs: change.generators.map(g => g.output),
+    };
+}
+/**
+ * Highest id already present in `<cacheRoot>/changes/`.
+ *
+ * The record files — not `index.json#changeSeq` — are the authoritative source:
+ * the counter lives in a file that is rewritten by several concurrent writers
+ * and can be reset (corrupt / unreadable / hand-edited `index.json`). Allocating
+ * from `max(counter, existing ids) + 1` keeps ids monotonic and, more
+ * importantly, never reuses an id — a reused id would silently overwrite an
+ * older record.
+ */
+async function maxChangeSeq(projectRoot) {
+    let files = [];
+    try {
+        files = await promises_1.default.readdir(changesDirPath(projectRoot));
+    }
+    catch {
+        return 0;
+    }
+    let max = 0;
+    for (const name of files) {
+        const seq = Number.parseInt(name.replace(/\.json$/, ''), 10);
+        if (Number.isFinite(seq) && seq > max)
+            max = seq;
+    }
+    return max;
+}
+async function readRecord(projectRoot, id) {
+    try {
+        const content = JSON.parse(await promises_1.default.readFile(recordFile(projectRoot, id), 'utf-8'));
+        if (!content || typeof content !== 'object')
+            return null;
+        const record = content;
+        return { ...record, generators: (record.generators ?? []).map(normalizeItem) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist one change record.
+ *
+ * Called by `generate()` **only when something actually changed**. Allocates the
+ * next `changes/<NNNN>.json` id from `index.json#changeSeq` and prunes records
+ * that fall outside `changeHistoryLimit`.
+ *
+ * @returns the allocated id (e.g. `"0007"`)
+ */
+async function captureChange(projectPath, change) {
+    // Never trust the counter alone: if it was reset (see {@link maxChangeSeq})
+    // `counter + 1` would collide with an existing record and overwrite it.
+    const [counter, existingMax] = await Promise.all([
+        (0, wormaJson_1.readChangeSeq)(projectPath),
+        maxChangeSeq(projectPath),
+    ]);
+    const seq = Math.max(counter, existingMax) + 1;
+    const id = padId(seq);
+    const record = {
+        ...change,
+        id,
+        createdAt: change.createdAt ?? Date.now(),
+    };
+    const dir = changesDirPath(projectPath);
+    await promises_1.default.mkdir(dir, { recursive: true });
+    await promises_1.default.writeFile(recordFile(projectPath, id), JSON.stringify(record));
+    // Persist the bumped counter; `writeCacheIndex` preserves existing entries.
+    await (0, wormaJson_1.writeCacheIndex)(projectPath, [], { changeSeq: seq });
+    await pruneChanges(projectPath);
+    return id;
+}
+/**
+ * Remove records outside the configured history window, keeping the newest
+ * `changeHistoryLimit` records. `changeHistoryLimit <= 0` means "keep everything".
+ *
+ * Ordering is by `createdAt` (not by id): ids can be out of chronological order
+ * when `index.json#changeSeq` was reset at some point, and pruning by id
+ * arithmetic would then delete the newest records instead of the oldest ones.
+ */
+async function pruneChanges(projectPath) {
+    const limit = (0, config_1.getGlobalConfig)().changeHistoryLimit;
+    if (typeof limit !== 'number' || limit <= 0)
+        return;
+    // `listChanges` returns the records newest first.
+    const summaries = await listChanges(projectPath);
+    const stale = summaries.slice(limit);
+    await Promise.all(stale.map(s => promises_1.default.unlink(recordFile(projectPath, s.id)).catch(() => { })));
+}
+/**
+ * List recorded changes, newest first.
+ *
+ * Sorted by `createdAt` (id as tie-breaker) rather than by file name: an id is
+ * only chronological as long as `index.json#changeSeq` never resets, and a
+ * reset would otherwise make a brand-new record show up last.
+ */
+async function listChanges(projectPath) {
+    const dir = changesDirPath(projectPath);
+    let files = [];
+    try {
+        files = await promises_1.default.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const ids = files
+        .filter(name => name.endsWith('.json'))
+        .map(name => name.replace(/\.json$/, ''));
+    const summaries = [];
+    for (const id of ids) {
+        const record = await readRecord(projectPath, id);
+        if (record)
+            summaries.push(toSummary(record));
+    }
+    summaries.sort((a, b) => (b.createdAt - a.createdAt) || b.id.localeCompare(a.id));
+    return summaries;
+}
+/**
+ * Read a single change record.
+ *
+ * @param projectPath absolute path of the project root
+ * @param id `"0007"` or the alias `"latest"` (newest record)
+ */
+async function getChange(projectPath, id) {
+    let resolvedId = id;
+    if (!id || id === exports.LATEST_CHANGE_ID) {
+        // Resolve the newest record by scanning the changes directory rather than
+        // trusting `index.json#changeSeq`: the counter can be stale or missing
+        // (pruned records, manual edits, or a generation that rewrote index.json
+        // without carrying the counter) while the record files themselves remain
+        // the authoritative source.
+        const latestId = await resolveLatestId(projectPath);
+        if (!latestId)
+            return undefined;
+        resolvedId = latestId;
+    }
+    const record = await readRecord(projectPath, resolvedId);
+    return record ?? undefined;
+}
+/**
+ * Return the newest change-record id.
+ *
+ * Resolved by `createdAt` (see {@link listChanges}) so `latest` keeps pointing
+ * at the most recent generation even when ids are not chronological.
+ */
+async function resolveLatestId(projectRoot) {
+    const [newest] = await listChanges(projectRoot);
+    return newest?.id;
+}

package/dist/functions/diffApis.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiDiffKey = apiDiffKey;
+exports.diffApis = diffApis;
+exports.hasApiChanges = hasApiChanges;
+const wormaJson_1 = require("../functions/wormaJson");
+/**
+ * Fields compared when two APIs share the same `method` + `path` key.
+ * `name` / `tag` are included so that renames and tag moves are reported
+ * instead of being silently ignored.
+ */
+const COMPARED_FIELDS = [
+    'name',
+    'tag',
+    'response',
+    'requestBody',
+    'queryParameters',
+    'pathParameters',
+];
+/**
+ * Stable matching key for an API.
+ *
+ * `method` + `path` is used instead of `name` because it survives function
+ * renames: a renamed API is reported as *modified* rather than
+ * removed + added.
+ */
+function apiDiffKey(api) {
+    return `${String(api.method ?? '').toLowerCase()} ${api.path ?? ''}`;
+}
+function toChange(api) {
+    return {
+        method: api.method,
+        path: api.path,
+        name: api.name,
+        tag: api.tag,
+    };
+}
+/**
+ * Diff two API lists at API level.
+ *
+ * @param oldApis API list as of the previous generation (from cache)
+ * @param newApis API list parsed from the current spec
+ */
+function diffApis(oldApis = [], newApis = []) {
+    const oldMap = new Map();
+    for (const api of oldApis) {
+        oldMap.set(apiDiffKey(api), api);
+    }
+    const newMap = new Map();
+    for (const api of newApis) {
+        newMap.set(apiDiffKey(api), api);
+    }
+    const added = [];
+    const removed = [];
+    const modified = [];
+    for (const [key, api] of newMap) {
+        if (!oldMap.has(key))
+            added.push(toChange(api));
+    }
+    for (const [key, api] of oldMap) {
+        if (!newMap.has(key))
+            removed.push(toChange(api));
+    }
+    for (const [key, api] of newMap) {
+        const previous = oldMap.get(key);
+        if (!previous)
+            continue;
+        const changedFields = COMPARED_FIELDS.filter(field => (0, wormaJson_1.stableStringify)(previous[field]) !== (0, wormaJson_1.stableStringify)(api[field]));
+        if (changedFields.length > 0) {
+            modified.push({ ...toChange(api), changedFields: [...changedFields] });
+        }
+    }
+    const byKey = (a, b) => apiDiffKey(a).localeCompare(apiDiffKey(b));
+    added.sort(byKey);
+    removed.sort(byKey);
+    modified.sort(byKey);
+    return { added, removed, modified };
+}
+/** Whether a diff result contains any change at all. */
+function hasApiChanges(diff) {
+    return diff.added.length > 0 || diff.removed.length > 0 || diff.modified.length > 0;
+}