wormajs 0.3.1 → 1.0.0-beta.0

package/dist/functions/diffDocument.js

@@ -0,0 +1,542 @@
+"use strict";
+/**
+ * Structural diff of the **source** OpenAPI document.
+ *
+ * The baseline is the document parsed from the `beforeSpecParse` output, i.e.
+ * taken *before* the `specParsed` hooks run: it is the source file as authored,
+ * not the plugin-normalised document that generation consumes. Every difference
+ * is reported as a flat {@link SourceChange} row so a caller (the CLI table, the
+ * editor webview, a CI script) can render it without any further shaping.
+ *
+ * Design notes:
+ * - `$ref`s are deliberately **not** inlined: the record is a source view, so a
+ *   component change is reported once under `#/components/...`, with the
+ *   affected operations attached as `affects` (resolved through the reverse
+ *   `$ref` index, including transitive references) so the impact stays visible
+ *   without duplicating the row.
+ * - Description-ish keys are still recorded (they are source changes) but get
+ *   the `doc` level so callers can de-emphasise them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffSourceDocument = diffSourceDocument;
+/** HTTP methods recognised as operations inside a path item. */
+const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+/** Component sections compared by key. */
+const COMPONENT_SECTIONS = [
+    'schemas',
+    'parameters',
+    'requestBodies',
+    'responses',
+    'headers',
+    'securitySchemes',
+    'links',
+    'callbacks',
+    'examples',
+];
+/** Keys whose change is documentation-only. */
+const DOC_KEYS = new Set(['description', 'title', 'summary', 'example', 'examples', 'externalDocs', 'deprecated']);
+/** Recursion guard for deeply nested schemas. */
+const MAX_DEPTH = 8;
+/** Row cap: a pathological spec must not produce an unbounded record. */
+const MAX_ROWS = 1000;
+// ──────────────────────────────────────────────────────────────
+// Change collection
+// ──────────────────────────────────────────────────────────────
+class ChangeCollector {
+    changes = [];
+    truncated = false;
+    push(target, kind, change) {
+        if (this.changes.length >= MAX_ROWS) {
+            this.truncated = true;
+            return;
+        }
+        this.changes.push({ ...change, target, kind });
+    }
+    /** Finalise the row list, appending a marker when the cap was hit. */
+    finish() {
+        if (this.truncated) {
+            this.changes.push({
+                op: '~',
+                kind: 'meta',
+                target: '(truncated)',
+                item: '',
+                detail: `more than ${MAX_ROWS} changes`,
+                level: 'doc',
+            });
+        }
+        return this.changes;
+    }
+}
+// ──────────────────────────────────────────────────────────────
+// Value helpers
+// ──────────────────────────────────────────────────────────────
+function isObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function isRefObject(value) {
+    return isObject(value) && typeof value.$ref === 'string';
+}
+function isPrimitive(value) {
+    return value === null || ['string', 'number', 'boolean'].includes(typeof value);
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asObject(value) {
+    return isObject(value) ? value : {};
+}
+/** Sorted union of two objects' keys — keeps the record deterministic. */
+function unionKeys(before, after) {
+    return [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
+}
+/** Sorted union of two maps' keys. */
+function unionMapKeys(a, b) {
+    return [...new Set([...a.keys(), ...b.keys()])].sort();
+}
+function joinPath(prefix, key) {
+    return prefix ? `${prefix}.${key}` : key;
+}
+/** Shallow copy without the given keys. */
+function omit(source, keys) {
+    const result = {};
+    for (const key of Object.keys(source)) {
+        if (!keys.includes(key))
+            result[key] = source[key];
+    }
+    return result;
+}
+function stableKey(value) {
+    return JSON.stringify(value) ?? 'null';
+}
+/** Short, single-line preview of a value for the `detail` column. */
+function summarize(value) {
+    if (value === undefined)
+        return '-';
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value)) {
+        if (value.length <= 4 && value.every(isPrimitive))
+            return JSON.stringify(value);
+        return `array(${value.length})`;
+    }
+    if (isObject(value)) {
+        const keys = Object.keys(value);
+        return `{${keys.slice(0, 4).join(', ')}${keys.length > 4 ? ', ...' : ''}}`;
+    }
+    return JSON.stringify(value) ?? String(value);
+}
+/**
+ * Severity of a leaf change.
+ *
+ * `required`/`enum` are treated per direction because their set semantics are
+ * asymmetric: a newly required field breaks callers, a relaxed one does not; a
+ * new enum value is compatible, a removed one is not.
+ */
+function levelFor(key, op) {
+    if (DOC_KEYS.has(key) || key.startsWith('x-'))
+        return 'doc';
+    if (key === 'required')
+        return op === '+' ? 'breaking' : 'additive';
+    return op === '+' ? 'additive' : 'breaking';
+}
+// ──────────────────────────────────────────────────────────────
+// Generic recursive differ
+// ──────────────────────────────────────────────────────────────
+/**
+ * Recursively diff two JSON-ish values, emitting one row per changed leaf.
+ *
+ * - objects: key union (covers `properties`, where keys are property names)
+ * - primitive arrays: set semantics (covers `enum`, `required`, `type`)
+ * - object arrays: index semantics (covers `allOf`/`oneOf`/`security`/`servers`)
+ */
+function diffValue(ctx, before, after, pointer, key, depth = 0) {
+    if (ctx.collector.truncated || stableKey(before) === stableKey(after))
+        return;
+    if (depth > MAX_DEPTH) {
+        ctx.collector.push(ctx.target, ctx.kind, {
+            op: '~',
+            item: pointer,
+            detail: `${summarize(before)} -> ${summarize(after)}`,
+            level: levelFor(key, '~'),
+        });
+        return;
+    }
+    if (isObject(before) && isObject(after)) {
+        for (const childKey of unionKeys(before, after)) {
+            const hasBefore = childKey in before;
+            const hasAfter = childKey in after;
+            const childPointer = joinPath(pointer, childKey);
+            if (!hasBefore) {
+                ctx.collector.push(ctx.target, ctx.kind, {
+                    op: '+',
+                    item: childPointer,
+                    detail: summarize(after[childKey]),
+                    level: levelFor(childKey, '+'),
+                });
+            }
+            else if (!hasAfter) {
+                ctx.collector.push(ctx.target, ctx.kind, {
+                    op: '-',
+                    item: childPointer,
+                    detail: summarize(before[childKey]),
+                    level: levelFor(childKey, '-'),
+                });
+            }
+            else {
+                diffValue(ctx, before[childKey], after[childKey], childPointer, childKey, depth + 1);
+            }
+        }
+        return;
+    }
+    if (Array.isArray(before) && Array.isArray(after)) {
+        if (before.every(isPrimitive) && after.every(isPrimitive)) {
+            const beforeSet = new Set(before.map(stableKey));
+            const afterSet = new Set(after.map(stableKey));
+            for (const item of after) {
+                if (!beforeSet.has(stableKey(item))) {
+                    ctx.collector.push(ctx.target, ctx.kind, { op: '+', item: pointer, detail: `+${summarize(item)}`, level: levelFor(key, '+') });
+                }
+            }
+            for (const item of before) {
+                if (!afterSet.has(stableKey(item))) {
+                    ctx.collector.push(ctx.target, ctx.kind, { op: '-', item: pointer, detail: `-${summarize(item)}`, level: levelFor(key, '-') });
+                }
+            }
+            return;
+        }
+        const length = Math.max(before.length, after.length);
+        for (let i = 0; i < length; i++) {
+            const childPointer = `${pointer}[${i}]`;
+            if (i >= before.length) {
+                ctx.collector.push(ctx.target, ctx.kind, { op: '+', item: childPointer, detail: summarize(after[i]), level: levelFor(key, '+') });
+            }
+            else if (i >= after.length) {
+                ctx.collector.push(ctx.target, ctx.kind, { op: '-', item: childPointer, detail: summarize(before[i]), level: levelFor(key, '-') });
+            }
+            else {
+                diffValue(ctx, before[i], after[i], childPointer, key, depth + 1);
+            }
+        }
+        return;
+    }
+    ctx.collector.push(ctx.target, ctx.kind, {
+        op: '~',
+        item: pointer,
+        detail: `${summarize(before)} -> ${summarize(after)}`,
+        level: levelFor(key, '~'),
+    });
+}
+function collectOperations(doc) {
+    const result = new Map();
+    const paths = asObject(doc.paths);
+    for (const path of Object.keys(paths).sort()) {
+        const pathItem = asObject(paths[path]);
+        for (const method of HTTP_METHODS) {
+            const operation = pathItem[method];
+            if (!isObject(operation))
+                continue;
+            const key = `${method.toUpperCase()} ${path}`;
+            result.set(key, { key, operation, pathItem });
+        }
+    }
+    return result;
+}
+function operationName(entry) {
+    return typeof entry.operation.operationId === 'string' ? entry.operation.operationId : undefined;
+}
+function parameterKey(parameter) {
+    if (isRefObject(parameter))
+        return `ref:${String(asObject(parameter).$ref)}`;
+    const object = asObject(parameter);
+    return `${String(object.in ?? '')}:${String(object.name ?? '')}`;
+}
+function parameterLabel(parameter) {
+    if (isRefObject(parameter)) {
+        const ref = String(asObject(parameter).$ref);
+        return ref.replace('#/components/', '');
+    }
+    const object = asObject(parameter);
+    return `${String(object.in ?? '')}.${String(object.name ?? '')}`;
+}
+function parameterSummary(parameter) {
+    const object = asObject(parameter);
+    if (isRefObject(parameter))
+        return String(object.$ref);
+    const schema = asObject(object.schema);
+    const type = schema.type ?? object.type;
+    const text = Array.isArray(type) ? type.join(' | ') : (typeof type === 'string' ? type : undefined);
+    if (!text)
+        return undefined;
+    return object.required ? text : `${text}?`;
+}
+/** Effective parameters of an operation: path-item level first, operation level wins. */
+function parametersByKey(entry) {
+    const map = new Map();
+    for (const parameter of [...asArray(entry.pathItem.parameters), ...asArray(entry.operation.parameters)])
+        map.set(parameterKey(parameter), parameter);
+    return map;
+}
+function diffPaths(collector, before, after) {
+    const beforeOps = collectOperations(before);
+    const afterOps = collectOperations(after);
+    for (const key of unionMapKeys(beforeOps, afterOps)) {
+        const beforeOp = beforeOps.get(key);
+        const afterOp = afterOps.get(key);
+        if (!beforeOp) {
+            collector.push(key, 'api', { op: '+', detail: operationName(afterOp), level: 'additive' });
+            continue;
+        }
+        if (!afterOp) {
+            collector.push(key, 'api', { op: '-', detail: operationName(beforeOp), level: 'breaking' });
+            continue;
+        }
+        diffOperation(collector, beforeOp, afterOp);
+    }
+}
+function diffOperation(collector, before, after) {
+    const target = after.key;
+    const ctx = { collector, target, kind: 'api' };
+    // `parameters` / `requestBody` / `responses` have dedicated walkers below.
+    diffValue(ctx, omit(before.operation, ['parameters', 'requestBody', 'responses']), omit(after.operation, ['parameters', 'requestBody', 'responses']), '', 'operation');
+    const paramCtx = { collector, target, kind: 'param' };
+    const beforeParams = parametersByKey(before);
+    const afterParams = parametersByKey(after);
+    for (const key of unionMapKeys(beforeParams, afterParams)) {
+        const beforeParam = beforeParams.get(key);
+        const afterParam = afterParams.get(key);
+        if (beforeParam === undefined) {
+            collector.push(target, 'param', {
+                op: '+',
+                item: parameterLabel(afterParam),
+                detail: parameterSummary(afterParam),
+                level: asObject(afterParam).required ? 'breaking' : 'additive',
+            });
+            continue;
+        }
+        if (afterParam === undefined) {
+            collector.push(target, 'param', { op: '-', item: parameterLabel(beforeParam), level: 'breaking' });
+            continue;
+        }
+        diffValue(paramCtx, beforeParam, afterParam, parameterLabel(afterParam), 'parameter');
+    }
+    diffRequestBody(collector, target, before.operation.requestBody, after.operation.requestBody);
+    diffResponses(collector, target, before.operation.responses, after.operation.responses);
+}
+function diffRequestBody(collector, target, before, after) {
+    if (before === undefined && after === undefined)
+        return;
+    const ctx = { collector, target, kind: 'body' };
+    if (!isObject(before)) {
+        collector.push(target, 'body', { op: '+', item: 'requestBody', detail: summarize(after), level: 'additive' });
+        return;
+    }
+    if (!isObject(after)) {
+        collector.push(target, 'body', { op: '-', item: 'requestBody', detail: summarize(before), level: 'breaking' });
+        return;
+    }
+    if (isRefObject(before) || isRefObject(after)) {
+        diffValue(ctx, before, after, 'requestBody', 'requestBody');
+        return;
+    }
+    diffValue(ctx, omit(before, ['content']), omit(after, ['content']), 'requestBody', 'requestBody');
+    diffContent(ctx, before.content, after.content, 'requestBody');
+}
+function diffResponses(collector, target, before, after) {
+    const beforeResponses = asObject(before);
+    const afterResponses = asObject(after);
+    const ctx = { collector, target, kind: 'resp' };
+    for (const code of unionKeys(beforeResponses, afterResponses)) {
+        const pointer = `responses.${code}`;
+        const beforeResponse = beforeResponses[code];
+        const afterResponse = afterResponses[code];
+        if (beforeResponse === undefined) {
+            collector.push(target, 'resp', { op: '+', item: pointer, detail: summarize(afterResponse), level: 'additive' });
+            continue;
+        }
+        if (afterResponse === undefined) {
+            collector.push(target, 'resp', { op: '-', item: pointer, detail: summarize(beforeResponse), level: 'breaking' });
+            continue;
+        }
+        if (isRefObject(beforeResponse) || isRefObject(afterResponse)) {
+            diffValue(ctx, beforeResponse, afterResponse, pointer, 'responses');
+            continue;
+        }
+        diffValue(ctx, omit(asObject(beforeResponse), ['content']), omit(asObject(afterResponse), ['content']), pointer, 'response');
+        diffContent(ctx, asObject(beforeResponse).content, asObject(afterResponse).content, pointer);
+    }
+}
+/**
+ * Diff a `content` map media type by media type.
+ *
+ * `schema` is walked without its own path segment so the rows read
+ * `requestBody.application/json.properties.name.type` instead of nesting the
+ * `schema` keyword into every pointer.
+ */
+function diffContent(ctx, before, after, prefix) {
+    const beforeContent = asObject(before);
+    const afterContent = asObject(after);
+    for (const mediaType of unionKeys(beforeContent, afterContent)) {
+        const pointer = `${prefix}.${mediaType}`;
+        const beforeMedia = beforeContent[mediaType];
+        const afterMedia = afterContent[mediaType];
+        if (beforeMedia === undefined) {
+            ctx.collector.push(ctx.target, ctx.kind, { op: '+', item: pointer, detail: summarize(afterMedia), level: 'additive' });
+            continue;
+        }
+        if (afterMedia === undefined) {
+            ctx.collector.push(ctx.target, ctx.kind, { op: '-', item: pointer, detail: summarize(beforeMedia), level: 'breaking' });
+            continue;
+        }
+        diffValue(ctx, omit(asObject(beforeMedia), ['schema']), omit(asObject(afterMedia), ['schema']), pointer, 'content');
+        diffValue(ctx, asObject(beforeMedia).schema, asObject(afterMedia).schema, pointer, 'schema');
+    }
+}
+// ──────────────────────────────────────────────────────────────
+// Components (with reverse-`$ref` impact resolution)
+// ──────────────────────────────────────────────────────────────
+class RefIndex {
+    opsByRef = new Map();
+    parents = new Map();
+    static build(doc) {
+        const index = new RefIndex();
+        const paths = asObject(doc.paths);
+        for (const path of Object.keys(paths)) {
+            const pathItem = asObject(paths[path]);
+            for (const method of HTTP_METHODS) {
+                if (!isObject(pathItem[method]))
+                    continue;
+                const operationKey = `${method.toUpperCase()} ${path}`;
+                for (const ref of collectRefs([pathItem[method], pathItem.parameters]))
+                    index.addTo(index.opsByRef, ref, operationKey);
+            }
+        }
+        const components = asObject(doc.components);
+        for (const section of COMPONENT_SECTIONS) {
+            const group = asObject(components[section]);
+            for (const name of Object.keys(group)) {
+                const ref = `#/components/${section}/${name}`;
+                for (const inner of collectRefs(group[name]))
+                    index.addTo(index.parents, inner, ref);
+            }
+        }
+        return index;
+    }
+    addTo(map, key, value) {
+        const set = map.get(key) ?? new Set();
+        set.add(value);
+        map.set(key, set);
+    }
+    /** Operations affected by a component, following transitive references. */
+    affectedBy(ref) {
+        const operations = new Set();
+        const visited = new Set();
+        const queue = [ref];
+        while (queue.length) {
+            const current = queue.shift();
+            if (visited.has(current))
+                continue;
+            visited.add(current);
+            for (const operation of this.opsByRef.get(current) ?? [])
+                operations.add(operation);
+            for (const parent of this.parents.get(current) ?? [])
+                queue.push(parent);
+        }
+        return [...operations].sort();
+    }
+}
+/** Collect every `$ref` string inside a value. */
+function collectRefs(value, out = []) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectRefs(item, out);
+        return out;
+    }
+    if (isObject(value)) {
+        if (typeof value.$ref === 'string')
+            out.push(value.$ref);
+        for (const key of Object.keys(value))
+            collectRefs(value[key], out);
+    }
+    return out;
+}
+/**
+ * Emit one component change.
+ *
+ * The component ref is the row target, the changed field its `item`, and the
+ * affected operations travel in `affects` so a renderer can list them next to
+ * the change (the CLI prints one per line) instead of duplicating the row.
+ */
+function emitComponentChange(collector, ref, affected, change) {
+    collector.push(ref, 'comp', { ...change, affects: affected.length > 0 ? affected : undefined });
+}
+function diffComponents(collector, before, after) {
+    const beforeComponents = asObject(before.components);
+    const afterComponents = asObject(after.components);
+    const beforeRefs = RefIndex.build(before);
+    const afterRefs = RefIndex.build(after);
+    for (const section of COMPONENT_SECTIONS) {
+        const beforeGroup = asObject(beforeComponents[section]);
+        const afterGroup = asObject(afterComponents[section]);
+        for (const name of unionKeys(beforeGroup, afterGroup)) {
+            const ref = `#/components/${section}/${name}`;
+            const beforeValue = beforeGroup[name];
+            const afterValue = afterGroup[name];
+            if (beforeValue === undefined) {
+                emitComponentChange(collector, ref, afterRefs.affectedBy(ref), { op: '+', detail: summarize(afterValue), level: 'additive' });
+                continue;
+            }
+            if (afterValue === undefined) {
+                emitComponentChange(collector, ref, beforeRefs.affectedBy(ref), { op: '-', detail: summarize(beforeValue), level: 'breaking' });
+                continue;
+            }
+            // Diff the component in place: the pointer starts empty so items read
+            // `properties.status.enum` rather than repeating the component ref.
+            const local = new ChangeCollector();
+            diffValue({ collector: local, target: ref, kind: 'comp' }, beforeValue, afterValue, '', name);
+            const affected = afterRefs.affectedBy(ref);
+            for (const change of local.changes) {
+                const { target: _target, kind: _kind, ...rest } = change;
+                emitComponentChange(collector, ref, affected, rest);
+            }
+            if (local.truncated)
+                collector.truncated = true;
+        }
+    }
+}
+// ──────────────────────────────────────────────────────────────
+// Document-global keys
+// ──────────────────────────────────────────────────────────────
+function diffRoot(collector, before, after) {
+    for (const key of unionKeys(before, after)) {
+        if (key === 'paths' || key === 'components')
+            continue;
+        const target = `#/${key}`;
+        if (!(key in after)) {
+            collector.push(target, 'meta', { op: '-', item: key, detail: summarize(before[key]), level: 'breaking' });
+            continue;
+        }
+        if (!(key in before)) {
+            collector.push(target, 'meta', { op: '+', item: key, detail: summarize(after[key]), level: 'additive' });
+            continue;
+        }
+        diffValue({ collector, target, kind: 'meta' }, before[key], after[key], key, key);
+    }
+}
+// ──────────────────────────────────────────────────────────────
+// Entry point
+// ──────────────────────────────────────────────────────────────
+/**
+ * Diff two source documents and return the flattened change rows.
+ *
+ * Returns an empty array when the documents are structurally identical, so the
+ * caller can decide not to write a change record at all.
+ */
+function diffSourceDocument(before, after) {
+    const collector = new ChangeCollector();
+    const beforeDoc = asObject(before);
+    const afterDoc = asObject(after);
+    diffPaths(collector, beforeDoc, afterDoc);
+    diffComponents(collector, beforeDoc, afterDoc);
+    diffRoot(collector, beforeDoc, afterDoc);
+    return collector.finish();
+}

package/dist/functions/sourceSnapshot.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapshotsDirPath = snapshotsDirPath;
+exports.snapshotFilePath = snapshotFilePath;
+exports.sourceDocumentHash = sourceDocumentHash;
+exports.readSourceSnapshot = readSourceSnapshot;
+exports.writeSourceSnapshot = writeSourceSnapshot;
+exports.collectSourceChanges = collectSourceChanges;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const diffDocument_1 = require("../functions/diffDocument");
+const wormaJson_1 = require("../functions/wormaJson");
+const logger_1 = require("../helper/logger");
+/** Payload version of one snapshot file. */
+const SNAPSHOT_VERSION = 1;
+/** `<cacheRoot>/.worma-cache/snapshots/` — one snapshot per generator output. */
+function snapshotsDirPath(projectRoot) {
+    return node_path_1.default.join((0, wormaJson_1.cacheDirPath)(projectRoot), 'snapshots');
+}
+/**
+ * Snapshot file name for one generator output.
+ *
+ * Keyed by the generator's `output` (resolved relative to the cache root in
+ * monorepo mode, same key as the api cache) with separators turned into `_`.
+ * Sharing a snapshot between generators is deliberately avoided even when they
+ * read the same source: they are not necessarily generated at the same time, so
+ * a shared file would let one generator's run overwrite the other's baseline.
+ */
+function snapshotFilePath(projectRoot, outputPath) {
+    const relative = (0, wormaJson_1.toCacheRelativePath)(projectRoot, outputPath);
+    return node_path_1.default.join(snapshotsDirPath(projectRoot), `${relative.replace(/[/\\]/g, '_')}.json`);
+}
+/** Stable hash of a stable-stringified source document. */
+function sourceDocumentHash(documentText) {
+    return (0, node_crypto_1.createHash)('sha256').update(documentText).digest('hex').slice(0, 16);
+}
+/** Read one generator's last source snapshot. */
+async function readSourceSnapshot(projectRoot, outputPath) {
+    try {
+        const content = JSON.parse(await promises_1.default.readFile(snapshotFilePath(projectRoot, outputPath), 'utf-8'));
+        if (!content || typeof content !== 'object' || typeof content.hash !== 'string')
+            return null;
+        return content;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist one generator's source snapshot. */
+async function writeSourceSnapshot(projectRoot, outputPath, snapshot) {
+    const file = snapshotFilePath(projectRoot, outputPath);
+    await promises_1.default.mkdir(node_path_1.default.dirname(file), { recursive: true });
+    await promises_1.default.writeFile(file, JSON.stringify(snapshot));
+}
+/**
+ * Compare the current source document with the previous snapshot and return the
+ * change rows.
+ *
+ * Runs after a successful generation (a failed run must not pay for the diff nor
+ * advance the baseline). The baseline is advanced on every successful run:
+ *
+ * - no previous snapshot → the first run only establishes the baseline and stays
+ *   silent, otherwise every existing project would report "everything changed";
+ * - identical hash → nothing to do, not even a write;
+ * - otherwise → the structured diff is returned and the snapshot is replaced.
+ *
+ * @returns the change rows, or `undefined` when there is nothing to record.
+ */
+async function collectSourceChanges(options) {
+    const { projectRoot, outputPath, documentText, resolvedInput } = options;
+    const hash = sourceDocumentHash(documentText);
+    const previous = await readSourceSnapshot(projectRoot, outputPath);
+    if (previous && previous.hash === hash)
+        return undefined;
+    let document;
+    try {
+        document = JSON.parse(documentText);
+    }
+    catch (error) {
+        // The document is not JSON-serialisable (plugins may have attached exotic
+        // values). Change history is best-effort: skip it instead of failing.
+        logger_1.logger.debug('Skipping source change detection: document is not serialisable', { error: error?.message });
+        return undefined;
+    }
+    let changes;
+    if (previous) {
+        try {
+            changes = (0, diffDocument_1.diffSourceDocument)(previous.doc, document);
+        }
+        catch (error) {
+            logger_1.logger.debug('Failed to diff source documents', { error: error?.message });
+            changes = undefined;
+        }
+    }
+    await writeSourceSnapshot(projectRoot, outputPath, {
+        version: SNAPSHOT_VERSION,
+        resolvedInput,
+        hash,
+        updatedAt: Date.now(),
+        doc: document,
+    });
+    return changes?.length ? changes : undefined;
+}