@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/furnace/operations.js

@@ -0,0 +1,283 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The edits that change which components a project has: create, override,
+ * rename and remove. Each edits `components/`, `furnace.json`, the typing
+ * files and the component's tests in one transaction. None touches a
+ * workspace: the next deployment adds what a component gained and takes
+ * away what it lost, since the deployment record knows what was deployed.
+ */
+import { join, posix } from 'node:path';
+import { resolveRevision } from '../git/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { listDir, pathInfo, readBytes } from '../kernel/fs.js';
+import { isRecord } from '../kernel/json.js';
+import { componentDir, editFurnaceConfig, findComponent, ftlDir, ftlResourceDir, loadFurnaceConfig, section, tagProblem, WIDGETS_DIR, } from './config.js';
+import { overrideDeploys, upstreamDirectory, upstreamFiles, } from './deploy.js';
+import { editProject } from './edit.js';
+import { componentSources, removeTestScaffold, renameTag, TEST_STYLES, testScaffold, writeTestScaffold, } from './scaffold.js';
+import { writeTypingFiles } from './typing.js';
+function refuse(message, hint) {
+    return new FireForgeError('furnace-invalid-name', message, {
+        exitCode: ExitCode.INVALID_ARGUMENT,
+        ...(hint === undefined ? {} : { hint }),
+    });
+}
+function scaffoldProject(project) {
+    return {
+        moduleDir: `browser/modules/${project.config.binaryName}`,
+        license: project.config.license,
+    };
+}
+/** Refuses a name that is taken in `furnace.json` or in `components/`. */
+async function assertFree(project, config, name) {
+    if (name in config.custom || name in config.overrides) {
+        throw refuse(`furnace.json already has a component "${name}".`);
+    }
+    for (const kind of ['custom', 'override']) {
+        if ((await pathInfo(componentDir(project, kind, name))) !== undefined) {
+            throw refuse(`${componentDir(project, kind, name)} already exists.`, 'Move it away or pick another name.');
+        }
+    }
+}
+function assertCustomName(config, name) {
+    const problem = tagProblem(name);
+    if (problem !== undefined)
+        throw refuse(problem);
+    if (!name.startsWith(config.componentPrefix)) {
+        throw refuse(`"${name}" does not start with the component prefix "${config.componentPrefix}".`, 'Pick a name with the prefix, or change componentPrefix in furnace.json.');
+    }
+}
+/**
+ * Creates a custom component: its module and stylesheet (and `.ftl` when it
+ * is localized on its own) in `components/custom/<name>/`, its `furnace.json`
+ * entry, an optional test with its manifest entry, and the typing files.
+ *
+ * @param project - The project
+ * @param tracked - The project's tracked engine files, for the test
+ * @param name - The element's tag
+ * @param options - See {@link CreateOptions}
+ * @throws `furnace-invalid-name` (exit code 8) for a name that is not a tag, lacks the prefix, or is taken
+ */
+export async function createComponent(project, tracked, name, options = {}) {
+    return editProject(project, `creating component ${name}`, options, async (tx) => {
+        const config = await loadFurnaceConfig(project);
+        assertCustomName(config, name);
+        await assertFree(project, config, name);
+        const localized = options.localized === true || options.sharedFtl !== undefined;
+        const resource = ftlResourceDir(config);
+        const ftl = !localized
+            ? undefined
+            : (options.sharedFtl ?? (resource === undefined ? `${name}.ftl` : `${resource}/${name}.ftl`));
+        const dir = componentDir(project, 'custom', name);
+        const sources = componentSources({
+            name,
+            description: options.description ?? '',
+            license: project.config.license,
+            ftl,
+            ownFtl: localized && options.sharedFtl === undefined,
+        });
+        for (const [file, content] of sources)
+            await tx.write(join(dir, file), content);
+        const next = await editFurnaceConfig(project, tx, (document) => {
+            section(document, 'custom')[name] = {
+                description: options.description ?? '',
+                targetPath: `${WIDGETS_DIR}/${name}`,
+                register: options.register ?? true,
+                localized,
+                ...(options.sharedFtl === undefined ? {} : { sharedFtl: options.sharedFtl }),
+                ...(options.composes === undefined || options.composes.length === 0
+                    ? {}
+                    : { composes: options.composes }),
+            };
+        });
+        const notes = options.tests === undefined
+            ? []
+            : await writeTestScaffold(tracked, tx, testScaffold(name, project.config.binaryName, options.tests, project.config.license), scaffoldProject(project));
+        await writeTypingFiles(project, next, tracked, tx);
+        return notes;
+    });
+}
+/**
+ * Starts overriding a stock component: copies its upstream files (from the
+ * engine's `HEAD`) into `components/overrides/<name>/` and records the
+ * override, with the Firefox version and commit it was taken from.
+ *
+ * @param project - The project
+ * @param tracked - The project's tracked engine files, for the typing files
+ * @param workspace - The engine to read the stock component from
+ * @param name - The stock component
+ * @param options - See {@link OverrideOptions}
+ * @throws `furnace-invalid-name` (exit code 8) when the name is taken or upstream has no such component
+ */
+export async function overrideComponent(project, tracked, workspace, name, options = {}) {
+    return editProject(project, `overriding component ${name}`, options, async (tx) => {
+        const config = await loadFurnaceConfig(project);
+        await assertFree(project, config, name);
+        const type = options.cssOnly === true ? 'css-only' : 'full';
+        const basePath = options.from ?? `${WIDGETS_DIR}/${name}`;
+        const paths = (await upstreamDirectory(workspace, basePath))
+            .filter((file) => file !== 'override.json' && overrideDeploys(type, file) && !file.endsWith('.ftl'))
+            .map((file) => `${basePath}/${file}`);
+        if (paths.length === 0) {
+            throw refuse(`The engine has no stock component files in ${basePath}.`, 'Name its directory with --from.');
+        }
+        if (type === 'full')
+            paths.push(`${ftlDir(config)}/${name}.ftl`);
+        const dir = componentDir(project, 'override', name);
+        for (const [path, content] of await upstreamFiles(workspace, paths)) {
+            await tx.write(join(dir, posix.basename(path)), content);
+        }
+        const commit = await resolveRevision(workspace.engineDir, 'HEAD');
+        const next = await editFurnaceConfig(project, tx, (document) => {
+            section(document, 'overrides')[name] = {
+                type,
+                description: options.description ?? '',
+                basePath,
+                baseVersion: project.config.firefox.version,
+                ...(commit === undefined ? {} : { baseCommit: commit }),
+            };
+            const stock = document['stock'];
+            if (Array.isArray(stock))
+                document['stock'] = stock.filter((entry) => entry !== name);
+        });
+        await writeTypingFiles(project, next, tracked, tx);
+        return [];
+    });
+}
+/** The component's files, refusing anything but plain files. */
+async function plainFiles(dir, name) {
+    const entries = await listDir(dir);
+    const odd = entries.find((entry) => entry.kind !== 'file');
+    if (odd !== undefined) {
+        throw refuse(`components of "${name}" include ${odd.name}, which is not a plain file.`, 'Move it out of the component directory first.');
+    }
+    return entries.map((entry) => entry.name);
+}
+function renamedFile(file, from, to) {
+    return file.startsWith(`${from}.`) || file.startsWith(`${from}-`)
+        ? to + file.slice(from.length)
+        : file;
+}
+function renameConfigEntry(document, kind, from, to) {
+    const key = kind === 'custom' ? 'custom' : 'overrides';
+    const entries = section(document, key);
+    const entry = entries[from];
+    if (!isRecord(entry))
+        return;
+    const moved = { ...entry };
+    if (typeof moved['description'] === 'string')
+        moved['description'] = renameTag(moved['description'], from, to);
+    if (kind === 'custom' && typeof moved['targetPath'] === 'string') {
+        moved['targetPath'] = moved['targetPath'].replace(new RegExp(`(^|/)${from}$`), `$1${to}`);
+    }
+    entries[from] = undefined;
+    entries[to] = moved;
+    for (const other of Object.values(section(document, 'custom'))) {
+        if (isRecord(other) && Array.isArray(other['composes'])) {
+            other['composes'] = other['composes'].map((ref) => (ref === from ? to : ref));
+        }
+    }
+    const exceptions = document['validationExceptions'];
+    if (Array.isArray(exceptions)) {
+        for (const exception of exceptions) {
+            if (isRecord(exception) && exception['component'] === from)
+                exception['component'] = to;
+        }
+    }
+}
+/**
+ * Renames a component: moves its directory, renames its `<name>.*` and
+ * `<name>-*` files, rewrites its tag and class name inside its sources,
+ * re-keys its `furnace.json` entry and every reference to it, and moves its
+ * tests. The next deployment takes the old name out of the engine.
+ *
+ * @param project - The project
+ * @param tracked - The project's tracked engine files
+ * @param from - The current name
+ * @param to - The new name
+ * @param options - See {@link EditOptions}
+ */
+export async function renameComponent(project, tracked, from, to, options = {}) {
+    return editProject(project, `renaming component ${from} to ${to}`, options, async (tx) => {
+        const config = await loadFurnaceConfig(project);
+        const { kind } = findComponent(config, from);
+        if (kind === 'custom')
+            assertCustomName(config, to);
+        await assertFree(project, config, to);
+        const source = componentDir(project, kind, from);
+        const target = componentDir(project, kind, to);
+        const others = [...Object.keys(config.custom), ...Object.keys(config.overrides)];
+        for (const file of await plainFiles(source, from)) {
+            const bytes = await readBytes(join(source, file));
+            const content = /\.(?:mjs|css|ftl)$/.test(file)
+                ? renameTag(bytes.toString('utf8'), from, to, others)
+                : bytes;
+            await tx.write(join(target, renamedFile(file, from, to)), content);
+        }
+        await tx.remove(source);
+        const next = await editFurnaceConfig(project, tx, (document) => {
+            renameConfigEntry(document, kind, from, to);
+        });
+        const notes = [];
+        for (const style of TEST_STYLES) {
+            const old = testScaffold(from, project.config.binaryName, style, project.config.license);
+            const test = await tracked.read(old.test.path);
+            if (test === undefined)
+                continue;
+            await removeTestScaffold(tracked, tx, old);
+            const moved = testScaffold(to, project.config.binaryName, style, project.config.license);
+            notes.push(...(await writeTestScaffold(tracked, tx, { ...moved, test: { path: moved.test.path, content: renameTag(test, from, to, others) } }, scaffoldProject(project))));
+        }
+        await writeTypingFiles(project, next, tracked, tx);
+        return notes;
+    });
+}
+/**
+ * Removes a component: its directory, its `furnace.json` entry and the
+ * validation exceptions recorded for it, its tests, and its typing entries.
+ * The next deployment takes it out of the engine.
+ *
+ * @param project - The project
+ * @param tracked - The project's tracked engine files
+ * @param name - The component
+ * @param options - See {@link EditOptions}
+ * @throws `furnace-invalid-name` (exit code 8) when another component composes it
+ */
+export async function removeComponent(project, tracked, name, options = {}) {
+    return editProject(project, `removing component ${name}`, options, async (tx) => {
+        const config = await loadFurnaceConfig(project);
+        const { kind } = findComponent(config, name);
+        const users = Object.entries(config.custom)
+            .filter(([, entry]) => entry.composes?.includes(name) === true)
+            .map(([user]) => user);
+        if (users.length > 0) {
+            throw refuse(`${users.join(', ')} compose${users.length === 1 ? 's' : ''} "${name}".`, 'Remove it from their composes first.');
+        }
+        await tx.remove(componentDir(project, kind, name));
+        const next = await editFurnaceConfig(project, tx, (document) => {
+            section(document, kind === 'custom' ? 'custom' : 'overrides')[name] = undefined;
+            const exceptions = document['validationExceptions'];
+            if (Array.isArray(exceptions)) {
+                document['validationExceptions'] = exceptions.filter((entry) => !isRecord(entry) || entry['component'] !== name);
+            }
+        });
+        for (const style of TEST_STYLES) {
+            await removeTestScaffold(tracked, tx, testScaffold(name, project.config.binaryName, style, project.config.license));
+        }
+        await writeTypingFiles(project, next, tracked, tx);
+        return [];
+    });
+}
+/**
+ * Brings the generated typing files up to date.
+ *
+ * @param project - The project
+ * @param tracked - The project's tracked engine files
+ * @param options - See {@link EditOptions}
+ */
+export async function updateTypingFiles(project, tracked, options = {}) {
+    return editProject(project, 'updating the component typing files', options, async (tx) => {
+        await writeTypingFiles(project, await loadFurnaceConfig(project), tracked, tx);
+        return [];
+    });
+}

package/dist/src/furnace/registration.js

@@ -0,0 +1,220 @@
+import MagicString from 'magic-string';
+import { compareBytes, insertJarEntry, parseJar, updateJarEntries } from '../mozbuild/index.js';
+import { isStringLiteral, lineIndent, lineStart, parseJs, walkJs, } from '../syntax/index.js';
+import { CUSTOM_ELEMENTS_JS, ELEMENTS_URL, furnaceError } from './config.js';
+/** Element lines sort by the file's stem, so a component's files stay together. */
+const tagKey = (target) => target.split('/').pop()?.split('.')[0] ?? target;
+/**
+ * The jar manifest with exactly the wanted component lines: lines whose
+ * source lies in an owned directory and that are not wanted are removed,
+ * wanted lines that are missing are added. Everything else is untouched.
+ *
+ * @param text - jar.mn text
+ * @param wanted - The lines the deployed components need
+ * @param ownedDirs - Source directories (relative to the manifest) Furnace deploys into
+ * @throws `manifest-invalid` when a wanted target is registered with another source
+ */
+export function planJar(text, wanted, ownedDirs) {
+    const wantedSources = new Map(wanted.map((file) => [file.target, file.source]));
+    const owned = (source) => source !== undefined && ownedDirs.some((dir) => source.startsWith(`${dir}/`));
+    let next = updateJarEntries(text, (entry) => owned(entry.source) && wantedSources.get(entry.target) !== entry.source ? null : undefined).text;
+    for (const file of [...wanted].sort((a, b) => compareBytes(a.target, b.target))) {
+        next = insertJarEntry(next, file, { sortKey: tagKey }).text;
+    }
+    return next;
+}
+/**
+ * The jar lines of `wanted` that the manifest lacks.
+ *
+ * @param text - jar.mn text
+ * @param wanted - Lines to look for
+ */
+export function missingJarFiles(text, wanted) {
+    const present = new Set(parseJar(text).entries.map((entry) => `${entry.target}\0${entry.source}`));
+    return wanted.filter((file) => !present.has(`${file.target}\0${file.source}`));
+}
+function unreadable(cause) {
+    return furnaceError('furnace-custom-elements-unreadable', `${CUSTOM_ELEMENTS_JS} does not parse as JavaScript, so its registrations cannot be edited.`, { hint: 'Restore the file from upstream and apply again.', cause });
+}
+function isDomContentLoadedListener(node) {
+    if (node.type !== 'CallExpression')
+        return false;
+    const { callee, arguments: args } = node;
+    const first = args[0];
+    return (callee.type === 'MemberExpression' &&
+        callee.property.type === 'Identifier' &&
+        callee.property.name === 'addEventListener' &&
+        isStringLiteral(first) &&
+        first.value === 'DOMContentLoaded');
+}
+/** Every registration list: the array of each `for (… of <array or name>)` loop. */
+function registrationLists(program) {
+    const declared = new Map();
+    walkJs(program, (node) => {
+        if (node.type === 'VariableDeclarator' &&
+            node.id.type === 'Identifier' &&
+            node.init?.type === 'ArrayExpression') {
+            declared.set(node.id.name, node.init);
+        }
+    });
+    const lists = [];
+    walkJs(program, (node, ancestors) => {
+        if (node.type !== 'ForOfStatement')
+            return;
+        const array = node.right.type === 'ArrayExpression'
+            ? node.right
+            : node.right.type === 'Identifier'
+                ? declared.get(node.right.name)
+                : undefined;
+        if (array !== undefined) {
+            lists.push({ array, module: ancestors.some(isDomContentLoadedListener) });
+        }
+    });
+    return lists;
+}
+function parseElements(text) {
+    let program;
+    try {
+        program = parseJs(text, 'script').program;
+    }
+    catch (error) {
+        throw unreadable(error);
+    }
+    const lists = registrationLists(program);
+    const entries = [];
+    for (const list of lists) {
+        for (const element of list.array.elements) {
+            const first = element?.type === 'ArrayExpression' ? element.elements[0] : undefined;
+            if (!isStringLiteral(first))
+                continue;
+            const { start, end } = element;
+            entries.push({ tag: first.value, module: list.module, start, end });
+        }
+    }
+    const callbacks = new Set();
+    walkJs(program, (node) => {
+        if (node.type === 'CallExpression' &&
+            node.callee.type === 'MemberExpression' &&
+            node.callee.property.type === 'Identifier' &&
+            node.callee.property.name === 'setElementCreationCallback' &&
+            isStringLiteral(node.arguments[0])) {
+            callbacks.add(node.arguments[0].value);
+        }
+    });
+    return { lists, entries, callbacks };
+}
+/**
+ * The entries of every registration list.
+ *
+ * @param text - customElements.js text
+ * @throws `furnace-custom-elements-unreadable` when the file does not parse
+ */
+export function elementEntries(text) {
+    return parseElements(text).entries;
+}
+/**
+ * Widens an entry's range to its whole line or lines: the trailing comma,
+ * a trailing line comment (the marker) and the line break, and the
+ * indentation before it, so removal leaves no hole.
+ */
+function removalRange(text, start, end) {
+    let to = end;
+    const skipBlanks = () => {
+        while (text[to] === ' ' || text[to] === '\t')
+            to++;
+    };
+    skipBlanks();
+    if (text[to] === ',')
+        to++;
+    skipBlanks();
+    if (text.startsWith('//', to)) {
+        while (to < text.length && text[to] !== '\n')
+            to++;
+    }
+    if (text[to] === '\n')
+        to++;
+    let from = start;
+    while (from > 0 && (text[from - 1] === ' ' || text[from - 1] === '\t'))
+        from--;
+    return [from, to];
+}
+/**
+ * customElements.js without the list entries of `tag`. A tag that is not
+ * listed changes nothing.
+ *
+ * @param text - customElements.js text
+ * @param tag - The element
+ */
+export function unregisterElement(text, tag) {
+    const doomed = parseElements(text).entries.filter((entry) => entry.tag === tag);
+    if (doomed.length === 0)
+        return text;
+    const edit = new MagicString(text);
+    for (const entry of doomed) {
+        const [from, to] = removalRange(text, entry.start, entry.end);
+        edit.remove(from, to);
+    }
+    return edit.toString();
+}
+function entryText(text, reference, tag, marker) {
+    const script = `${ELEMENTS_URL}${tag}.mjs`;
+    const suffix = `  // ${marker}:`;
+    if (reference === undefined)
+        return `      [${JSON.stringify(tag)}, ${JSON.stringify(script)}],${suffix}`;
+    const indent = lineIndent(text, reference.start);
+    if (!text.slice(reference.start, reference.end).includes('\n')) {
+        return `${indent}[${JSON.stringify(tag)}, ${JSON.stringify(script)}],${suffix}`;
+    }
+    const inner = `${indent}  `;
+    return [
+        `${indent}[${suffix}`,
+        `${inner}${JSON.stringify(tag)},${suffix}`,
+        `${inner}${JSON.stringify(script)},${suffix}`,
+        `${indent}],${suffix}`,
+    ].join('\n');
+}
+/**
+ * customElements.js with `tag` listed as an ES module element
+ * (`chrome://global/content/elements/<tag>.mjs`), in tag order, each line
+ * ending with the project marker. A tag already in the module list, or with
+ * a creation callback of its own, changes nothing; one in a subscript list
+ * is moved.
+ *
+ * @param text - customElements.js text
+ * @param tag - The element
+ * @param marker - The project marker, such as `MYBROWSER`
+ * @throws `furnace-custom-elements-unreadable` when the file does not parse
+ *   or has no list inside a `DOMContentLoaded` listener
+ */
+export function registerElement(text, tag, marker) {
+    const parsed = parseElements(text);
+    if (parsed.callbacks.has(tag))
+        return text;
+    if (parsed.entries.some((entry) => entry.tag === tag && entry.module))
+        return text;
+    if (parsed.entries.some((entry) => entry.tag === tag)) {
+        return registerElement(unregisterElement(text, tag), tag, marker);
+    }
+    const list = parsed.lists.find((candidate) => candidate.module);
+    if (list === undefined) {
+        throw furnaceError('furnace-custom-elements-unreadable', `${CUSTOM_ELEMENTS_JS} has no element list iterated inside its DOMContentLoaded listener.`, { hint: 'Restore the file from upstream and apply again.' });
+    }
+    const siblings = parsed.entries.filter((entry) => entry.module && entry.start >= list.array.start && entry.end <= list.array.end);
+    const next = siblings.find((entry) => compareBytes(entry.tag, tag) > 0);
+    const previous = [...siblings].reverse().find((entry) => compareBytes(entry.tag, tag) < 0);
+    const line = entryText(text, previous ?? next, tag, marker);
+    const edit = new MagicString(text);
+    if (next !== undefined) {
+        edit.appendLeft(lineStart(text, next.start), `${line}\n`);
+    }
+    else if (previous === undefined) {
+        edit.appendLeft(text.indexOf('\n', list.array.start) + 1, `${line}\n`);
+    }
+    else {
+        // The last entry may lack a trailing comma; the new one follows it.
+        if (!/^[ \t]*,/.test(text.slice(previous.end)))
+            edit.appendLeft(previous.end, ',');
+        edit.appendLeft(removalRange(text, previous.start, previous.end)[1], `${line}\n`);
+    }
+    return edit.toString();
+}