@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/kernel/json-edit.js

@@ -0,0 +1,198 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Format-preserving edits of a JSON document. Re-serialising a whole document
+ * expands every one-line object and array a project keeps compact, so a
+ * one-key change becomes a diff across unrelated sections. {@link editJsonText}
+ * compares the text on disk with the wanted document and rewrites only the
+ * values that differ, keeping every other byte: indentation, one-line
+ * containers, key order, line endings and the trailing newline.
+ *
+ * An inserted value follows the container it lands in: one line inside a
+ * one-line container, the container's own indentation otherwise.
+ */
+import { applyEdits, findNodeAtLocation, modify, parseTree } from 'jsonc-parser';
+import { isRecord, parseJson } from './json.js';
+/** Keys whose value survives serialisation: an `undefined` value is an absent key. */
+function definedKeys(object) {
+    return Object.keys(object).filter((key) => object[key] !== undefined);
+}
+function asObject(value) {
+    return isRecord(value) ? value : undefined;
+}
+function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((value, index) => jsonEqual(value, b[index]));
+    }
+    const left = asObject(a);
+    const right = asObject(b);
+    if (left === undefined || right === undefined)
+        return false;
+    const keys = definedKeys(left);
+    return (keys.length === definedKeys(right).length &&
+        keys.every((key) => jsonEqual(left[key], right[key])));
+}
+function collectChanges(path, before, after, changes) {
+    if (jsonEqual(before, after))
+        return;
+    const beforeObject = asObject(before);
+    const afterObject = asObject(after);
+    if (beforeObject !== undefined && afterObject !== undefined) {
+        for (const key of definedKeys(beforeObject)) {
+            if (afterObject[key] === undefined)
+                changes.push({ kind: 'remove', path: [...path, key] });
+        }
+        for (const key of definedKeys(afterObject)) {
+            const next = afterObject[key];
+            const previous = beforeObject[key];
+            if (previous === undefined)
+                changes.push({ kind: 'set', path: [...path, key], value: next });
+            else
+                collectChanges([...path, key], previous, next, changes);
+        }
+        return;
+    }
+    if (Array.isArray(before) && Array.isArray(after)) {
+        const isAppend = after.length > before.length &&
+            before.every((value, index) => jsonEqual(value, after[index]));
+        if (isAppend) {
+            for (const value of after.slice(before.length))
+                changes.push({ kind: 'append', path, value });
+            return;
+        }
+        if (after.length === before.length) {
+            before.forEach((value, index) => {
+                collectChanges([...path, index], value, after[index], changes);
+            });
+            return;
+        }
+    }
+    changes.push({ kind: 'set', path, value: after });
+}
+function detectStyle(text) {
+    const indent = /^([ \t]+)\S/m.exec(text)?.[1];
+    return {
+        eol: text.includes('\r\n') ? '\r\n' : '\n',
+        indentUnit: indent === undefined ? '  ' : indent.startsWith('\t') ? '\t' : indent,
+    };
+}
+function isMultiline(text, node) {
+    return node !== undefined && text.slice(node.offset, node.offset + node.length).includes('\n');
+}
+/** The object or array holding `node`, skipping the property node of an object member. */
+function containerOf(node) {
+    const parent = node.parent;
+    return parent?.type === 'property' ? parent.parent : parent;
+}
+/** Leading whitespace of the line `offset` sits on. */
+function lineIndent(text, offset) {
+    const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
+    return /^[ \t]*/.exec(text.slice(lineStart))?.[0] ?? '';
+}
+function renderCompact(value) {
+    if (Array.isArray(value))
+        return `[${value.map(renderCompact).join(', ')}]`;
+    const object = asObject(value);
+    if (object === undefined)
+        return JSON.stringify(value);
+    const entries = definedKeys(object).map((key) => `${JSON.stringify(key)}: ${renderCompact(object[key])}`);
+    return entries.length === 0 ? '{}' : `{ ${entries.join(', ')} }`;
+}
+function renderValue(value, multiline, indent, style) {
+    if (!multiline)
+        return renderCompact(value);
+    return JSON.stringify(value, null, style.indentUnit)
+        .split('\n')
+        .join(style.eol + indent);
+}
+function replaceRange(text, offset, length, content) {
+    return text.slice(0, offset) + content + text.slice(offset + length);
+}
+/** Replaces an existing value, keeping a container's one-line or multi-line shape. */
+function replaceNode(text, node, value, style) {
+    const isContainer = node.type === 'object' || node.type === 'array';
+    const multiline = isContainer ? isMultiline(text, node) : isMultiline(text, containerOf(node));
+    const rendered = renderValue(value, multiline, lineIndent(text, node.offset), style);
+    return replaceRange(text, node.offset, node.length, rendered);
+}
+/** Appends an entry (a property or an array element) after the container's last child. */
+function appendEntry(text, container, renderEntry, style) {
+    const last = container.children?.at(-1);
+    const containerIndent = lineIndent(text, container.offset);
+    if (last === undefined) {
+        // An empty container opens up the way its parent is laid out.
+        const multiline = isMultiline(text, containerOf(container));
+        const [open, close] = container.type === 'array' ? ['[', ']'] : ['{', '}'];
+        const childIndent = containerIndent + style.indentUnit;
+        const body = multiline
+            ? `${open}${style.eol}${childIndent}${renderEntry(true, childIndent)}${style.eol}${containerIndent}${close}`
+            : container.type === 'array'
+                ? `${open}${renderEntry(false, childIndent)}${close}`
+                : `${open} ${renderEntry(false, childIndent)} ${close}`;
+        return replaceRange(text, container.offset, container.length, body);
+    }
+    const multiline = isMultiline(text, container);
+    const indent = multiline ? lineIndent(text, last.offset) : containerIndent;
+    const separator = multiline ? `,${style.eol}${indent}` : ', ';
+    return replaceRange(text, last.offset + last.length, 0, separator + renderEntry(multiline, indent));
+}
+function applyChange(text, change, style) {
+    const root = parseTree(text);
+    if (root === undefined)
+        throw new Error('document is not valid JSON');
+    if (change.kind === 'remove')
+        return applyEdits(text, modify(text, change.path, undefined, {}));
+    const target = findNodeAtLocation(root, change.path);
+    if (change.kind === 'append') {
+        if (target?.type !== 'array')
+            throw new Error('append target is not an array');
+        const render = (multiline, indent) => renderValue(change.value, multiline, indent, style);
+        return appendEntry(text, target, render, style);
+    }
+    if (target !== undefined)
+        return replaceNode(text, target, change.value, style);
+    const parent = findNodeAtLocation(root, change.path.slice(0, -1));
+    const key = change.path.at(-1);
+    if (parent?.type !== 'object' || typeof key !== 'string') {
+        throw new Error('insertion parent is not an object');
+    }
+    const render = (multiline, indent) => `${JSON.stringify(key)}: ${renderValue(change.value, multiline, indent, style)}`;
+    return appendEntry(text, parent, render, style);
+}
+/**
+ * Rewrites JSON text so it parses to `next`, editing only the values that
+ * differ. Returns undefined when the text is not a JSON object or the edit
+ * cannot be proven to produce `next`, so the caller can write the document
+ * in full instead.
+ *
+ * @param text - The document as it is on disk
+ * @param next - The document wanted
+ */
+export function editJsonText(text, next) {
+    let current;
+    try {
+        current = parseJson(text);
+    }
+    catch {
+        return undefined;
+    }
+    const currentObject = asObject(current);
+    if (currentObject === undefined)
+        return undefined;
+    const changes = [];
+    collectChanges([], currentObject, next, changes);
+    const style = detectStyle(text);
+    try {
+        let edited = text;
+        for (const change of changes)
+            edited = applyChange(edited, change, style);
+        // The edits are structural; prove the result before trusting it.
+        return jsonEqual(parseJson(edited), next) ? edited : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/kernel/json.js

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * JSON values and JSON documents on disk. A document read from a file always
+ * passes through a schema, so nothing downstream handles an unchecked shape.
+ */
+import { FireForgeError, toError } from './errors.js';
+import { readTextIfExists, writeFile } from './fs.js';
+/**
+ * Narrows an unknown value to a plain object (not an array, not null).
+ *
+ * @param value - The value
+ */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * A copy of an object without the named keys.
+ *
+ * @param object - The object
+ * @param keys - The keys to leave out
+ */
+export function omitKeys(object, ...keys) {
+    return Object.fromEntries(Object.entries(object).filter(([key]) => !keys.includes(key)));
+}
+/**
+ * Parses JSON text, reporting a syntax error as a {@link FireForgeError} that
+ * names the source.
+ *
+ * @param text - The JSON text
+ * @param details - `source` names what is being parsed; the rest shape the error
+ */
+export function parseJson(text, details = {}) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        const { source, ...rest } = details;
+        throw new FireForgeError('json-invalid', `${source ?? 'The document'} is not valid JSON: ${toError(error).message}`, { cause: error, ...rest });
+    }
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (!isRecord(value))
+        return value;
+    const sorted = {};
+    for (const key of Object.keys(value).sort())
+        sorted[key] = sortKeys(value[key]);
+    return sorted;
+}
+/**
+ * Serialises a value as JSON text ending in a newline.
+ *
+ * @param value - The value
+ * @param options - See {@link StringifyOptions}
+ */
+export function stringifyJson(value, options = {}) {
+    const subject = options.sortKeys === true ? sortKeys(value) : value;
+    return `${JSON.stringify(subject, null, options.indent ?? 2)}\n`;
+}
+/**
+ * Reads and validates a JSON document, or returns undefined when the file
+ * does not exist. A file that exists but does not parse or does not match the
+ * schema is an error naming the file and the key path, never an empty default.
+ *
+ * @param path - The document
+ * @param schema - What it must look like
+ * @param options - See {@link ReadJsonOptions}
+ */
+export async function readJsonIfExists(path, schema, options = {}) {
+    const text = await readTextIfExists(path);
+    if (text === undefined)
+        return undefined;
+    const details = { source: path, ...options };
+    return schema.parse(parseJson(text, details), details);
+}
+/**
+ * Reads and validates a JSON document that must exist.
+ *
+ * @param path - The document
+ * @param schema - What it must look like
+ * @param options - See {@link ReadJsonOptions}
+ */
+export async function readJson(path, schema, options = {}) {
+    const value = await readJsonIfExists(path, schema, options);
+    if (value === undefined) {
+        const { code, ...details } = options;
+        throw new FireForgeError(code ?? 'document-missing', `${path} does not exist`, details);
+    }
+    return value;
+}
+/**
+ * Writes a JSON document atomically.
+ *
+ * @param path - The document
+ * @param value - Its content
+ * @param options - See {@link StringifyOptions}
+ */
+export async function writeJson(path, value, options = {}) {
+    await writeFile(path, stringifyJson(value, options));
+}