@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/furnace-registration-ast.js

@@ -1,402 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * AST-based custom element registration updates for customElements.js.
- * Removal logic is in furnace-registration-remove.ts.
- */
-import { join } from 'node:path';
-import MagicString from 'magic-string';
-import { FurnaceError } from '../errors/furnace.js';
-import { toError } from '../utils/errors.js';
-import { pathExists, readText, writeText } from '../utils/fs.js';
-import { verbose, warn } from '../utils/logger.js';
-import { escapeRegex } from '../utils/regex.js';
-import { asEstree, detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
-import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
-import { validateRegistrationPlacement, validateTagName } from './furnace-registration-validate.js';
-/**
- * Returns true when `content` already contains a registration for `tagName`.
- *
- * Tolerates trailing line comments (e.g. a project marker like `// MYBROWSER:`)
- * that an operator may have appended to entries written by a previous apply.
- * Without this, a re-apply would insert a duplicate entry, and the second
- * `setElementCreationCallback` at window-load would throw `NotSupportedError`.
- *
- * Matches any of:
- *   1. `setElementCreationCallback("tag"` / `setElementCreationCallback('tag'`
- *   2. Single-line array entry: `["tag", "..."]` (column 0 only, comments allowed after)
- *   3. Multi-line array entry: `"tag",` on its own line, optional trailing `//` comment
- */
-export function isTagAlreadyRegistered(content, tagName) {
-    const escaped = escapeRegex(tagName);
-    if (content.includes(`setElementCreationCallback("${tagName}"`) ||
-        content.includes(`setElementCreationCallback('${tagName}'`)) {
-        return true;
-    }
-    if (new RegExp(`^\\s*\\[\\s*["']${escaped}["']\\s*,`, 'm').test(content)) {
-        return true;
-    }
-    if (new RegExp(`^\\s*["']${escaped}["']\\s*,\\s*(?:\\/\\/.*)?$`, 'm').test(content)) {
-        return true;
-    }
-    return false;
-}
-/** Validates a markerComment value and returns the formatted suffix (with leading spaces). */
-function formatMarkerSuffix(markerComment) {
-    if (!markerComment)
-        return '';
-    return `  // ${markerComment}:`;
-}
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-/**
- * Checks whether a `ForOfStatement` is nested inside a
- * `document.addEventListener("DOMContentLoaded", ...)` call by
- * inspecting the ancestor stack.
- */
-function isInsideDOMContentLoaded(ancestors, content) {
-    for (let i = ancestors.length - 1; i >= 0; i--) {
-        const ancestor = ancestors[i];
-        if (!ancestor || ancestor.type !== 'CallExpression')
-            continue;
-        const call = asEstree(ancestor);
-        if (call.callee.type === 'MemberExpression' &&
-            call.callee.object.type === 'Identifier' &&
-            call.callee.object.name === 'document' &&
-            call.callee.property.type === 'Identifier' &&
-            call.callee.property.name === 'addEventListener') {
-            const firstArg = call.arguments[0];
-            if (firstArg && firstArg.type === 'Literal' && firstArg.value === 'DOMContentLoaded') {
-                return true;
-            }
-            // Check if "DOMContentLoaded" appears in the call's source (handles edge cases)
-            const src = getNodeSource(content, call);
-            if (/["']DOMContentLoaded["']/.test(src)) {
-                return true;
-            }
-        }
-    }
-    return false;
-}
-function collectArrayDeclarations(ast) {
-    const arrays = new Map();
-    walkAST(ast, {
-        enter(node) {
-            if (node.type !== 'VariableDeclarator')
-                return;
-            const declarator = asEstree(node);
-            if (declarator.id.type !== 'Identifier' || declarator.init?.type !== 'ArrayExpression') {
-                return;
-            }
-            arrays.set(declarator.id.name, asEstree(declarator.init));
-        },
-    });
-    return arrays;
-}
-function resolveForOfArray(right, declaredArrays) {
-    if (right.type === 'ArrayExpression') {
-        return asEstree(right);
-    }
-    if (right.type === 'Identifier') {
-        return declaredArrays.get(right.name);
-    }
-    return undefined;
-}
-function selectRegistrationTarget(targets, isESModule, tagName) {
-    const target = isESModule
-        ? targets.find((candidate) => candidate.insideDCL)
-        : targets.find((candidate) => !candidate.insideDCL);
-    if (target) {
-        return target;
-    }
-    if (isESModule) {
-        throw new FurnaceError('Could not find DOMContentLoaded block in customElements.js', tagName);
-    }
-    throw new FurnaceError(`${tagName} would land in the DOMContentLoaded/importESModule block (Pattern B) instead of the loadSubScript block (Pattern A) — no non-DOMContentLoaded registration array found in customElements.js. The file structure may have changed upstream — manual intervention required.`, tagName);
-}
-function buildRegistrationEntry(referenceEntry, tagName, modulePath, markerComment) {
-    const marker = formatMarkerSuffix(markerComment);
-    if (!referenceEntry) {
-        return `    ["${tagName}", "${modulePath}"],${marker}`;
-    }
-    if (referenceEntry.isMultiLine) {
-        const indent = referenceEntry.indent;
-        const inner = referenceEntry.innerIndent ?? indent + '  ';
-        return (`${indent}[${marker}\n` +
-            `${inner}"${tagName}",${marker}\n` +
-            `${inner}"${modulePath}",${marker}\n` +
-            `${indent}],${marker}`);
-    }
-    return `${referenceEntry.indent}["${tagName}", "${modulePath}"],${marker}`;
-}
-/**
- * AST-based implementation: parses customElements.js, walks to find the
- * target ForOfStatement array, and inserts the new entry at the correct
- * alphabetical position using magic-string.
- */
-function addRegistrationAST(content, tagName, modulePath, isESModule, markerComment) {
-    validateTagName(tagName);
-    const ast = parseScript(content);
-    const declaredArrays = collectArrayDeclarations(ast);
-    const ancestors = [];
-    // Collect all ForOfStatement nodes with ArrayExpression rights
-    const forOfs = [];
-    walkAST(ast, {
-        enter(node) {
-            ancestors.push(node);
-            if (node.type === 'ForOfStatement') {
-                const forOf = asEstree(node);
-                const array = resolveForOfArray(forOf.right, declaredArrays);
-                if (array) {
-                    forOfs.push({
-                        array,
-                        insideDCL: isInsideDOMContentLoaded(ancestors, content),
-                    });
-                }
-            }
-        },
-        leave() {
-            ancestors.pop();
-        },
-    });
-    // Select the target array
-    const target = selectRegistrationTarget(forOfs, isESModule, tagName);
-    const array = target.array;
-    // Parse existing entries from the ArrayExpression elements
-    const entries = [];
-    for (const el of array.elements) {
-        if (!el || el.type !== 'ArrayExpression')
-            continue;
-        const entryArr = asEstree(el);
-        const firstEl = entryArr.elements[0];
-        if (!firstEl || firstEl.type !== 'Literal')
-            continue;
-        const tag = String(firstEl.value);
-        // Detect if this entry is multi-line
-        const entrySrc = getNodeSource(content, entryArr);
-        const isMultiLine = entrySrc.includes('\n');
-        const indent = detectIndent(content, entryArr.start);
-        let innerIndent;
-        if (isMultiLine) {
-            const firstElNode = asEstree(firstEl);
-            innerIndent = detectIndent(content, firstElNode.start);
-        }
-        entries.push({ tag, node: entryArr, isMultiLine, indent, innerIndent });
-    }
-    // Find alphabetical insertion position
-    let insertAfterNode = null;
-    let insertBeforeNode = null;
-    let referenceEntry;
-    for (const entry of entries) {
-        if (entry.tag > tagName) {
-            insertBeforeNode = entry.node;
-            if (!referenceEntry)
-                referenceEntry = entry;
-            break;
-        }
-        insertAfterNode = entry.node;
-        referenceEntry = entry;
-    }
-    // Build new entry string matching detected format
-    const newEntry = buildRegistrationEntry(referenceEntry, tagName, modulePath, markerComment);
-    const ms = new MagicString(content);
-    // Helper: find the start-of-line position for a given offset
-    function lineStart(pos) {
-        let i = pos - 1;
-        while (i >= 0 && content[i] !== '\n')
-            i--;
-        return i + 1;
-    }
-    // Helper: find the end-of-line position (the \n itself) for a given offset
-    function lineEnd(pos) {
-        let i = pos;
-        while (i < content.length && content[i] !== '\n')
-            i++;
-        return i;
-    }
-    // Find the insertion position (character offset)
-    if (insertBeforeNode) {
-        const sol = lineStart(insertBeforeNode.start);
-        ms.appendLeft(sol, newEntry + '\n');
-    }
-    else if (insertAfterNode) {
-        const eol = lineEnd(insertAfterNode.end);
-        ms.appendRight(eol, '\n' + newEntry);
-    }
-    else {
-        const eol = lineEnd(array.start);
-        ms.appendRight(eol, '\n' + newEntry);
-    }
-    return ms.toString();
-}
-/**
- * Regex-based fallback for inserting a registration entry when the AST parser
- * fails. Finds the last existing `["tag", "path"],` line in the appropriate
- * block and inserts the new entry after it in alphabetical order.
- *
- * This is intentionally less precise than the AST approach (it does not
- * validate indentation or multi-line format), but it is robust against
- * upstream syntax changes that break the parser.
- */
-function addRegistrationRegexFallback(content, tagName, modulePath, isESModule, markerComment) {
-    // Find all registration entries: ["tag", "path"],
-    const entryPattern = /^(\s*)\["([^"]+)",\s*"[^"]+"\],?\s*$/gm;
-    let lastMatch = null;
-    let insertAfterMatch = null;
-    const allMatches = [];
-    let match;
-    // For ESM modules, only consider entries inside a DOMContentLoaded block.
-    // For non-ESM, consider entries outside DOMContentLoaded.
-    const dclStart = content.search(/document\.addEventListener\s*\(\s*["']DOMContentLoaded["']/);
-    const dclBlockStart = dclStart >= 0 ? content.indexOf('{', dclStart) : -1;
-    while ((match = entryPattern.exec(content)) !== null) {
-        const isInDCL = dclBlockStart >= 0 && match.index > dclBlockStart;
-        if (isESModule ? isInDCL : !isInDCL) {
-            allMatches.push(match);
-        }
-    }
-    // Find alphabetical insertion point
-    for (const m of allMatches) {
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- capture group [2] always present when regex matches
-        const existingTag = m[2];
-        if (existingTag < tagName) {
-            insertAfterMatch = m;
-        }
-        lastMatch = m;
-    }
-    // If we found no entries in the target block, give up
-    if (!lastMatch) {
-        throw new FurnaceError(`Regex fallback could not find any registration entries in the ${isESModule ? 'DOMContentLoaded' : 'non-DOMContentLoaded'} block of ${CUSTOM_ELEMENTS_JS}.`, tagName);
-    }
-    const indent = lastMatch[1] ?? '    ';
-    const marker = formatMarkerSuffix(markerComment);
-    const newEntry = `${indent}["${tagName}", "${modulePath}"],${marker}`;
-    if (insertAfterMatch) {
-        // Insert after the last entry that sorts before tagName
-        const insertPos = insertAfterMatch.index + insertAfterMatch[0].length;
-        return content.slice(0, insertPos) + '\n' + newEntry + content.slice(insertPos);
-    }
-    // Insert before the first entry (tagName sorts before all existing)
-    const firstMatch = allMatches[0];
-    if (!firstMatch) {
-        throw new FurnaceError(`Regex fallback found no entries in the target block of ${CUSTOM_ELEMENTS_JS}.`, tagName);
-    }
-    const insertPos = firstMatch.index;
-    return content.slice(0, insertPos) + newEntry + '\n' + content.slice(insertPos);
-}
-function hasRecognizableRegistrationLoop(content) {
-    return /for\s*\(\s*(?:let|const|var)\s*\[[^)]*\]\s+of\s+(?:\[|[A-Za-z_$][\w$]*)/.test(content);
-}
-/**
- * Adds a custom element registration entry to customElements.js.
- *
- * The entry is inserted into the array literal inside the `for...of` loop
- * that registers all custom elements:
- * ```js
- *   ["tag", "chrome://global/content/elements/tag.mjs"],
- * ```
- *
- * New entries are inserted in alphabetical order relative to existing entries.
- * This operation is idempotent: if the tag is already registered the file is
- * left unchanged.
- *
- * @param engineDir - Path to the Firefox engine source root
- * @param tagName - Custom element tag name
- * @param modulePath - chrome:// URI for the module
- */
-export async function addCustomElementRegistration(engineDir, tagName, modulePath, options = {}) {
-    const filePath = join(engineDir, CUSTOM_ELEMENTS_JS);
-    if (!(await pathExists(filePath))) {
-        throw new FurnaceError('customElements.js not found in engine', tagName);
-    }
-    const content = await readText(filePath);
-    // Idempotency: check column-0 of each array entry rather than a literal
-    // substring match. A previous apply may have written this entry with
-    // trailing marker comments (see `options.markerComment`). Matching on the
-    // full line would then miss it and insert a duplicate on re-apply, which
-    // throws NotSupportedError at every window-load.
-    if (isTagAlreadyRegistered(content, tagName)) {
-        return;
-    }
-    // Validate upfront. Tag name errors must not fall through to the regex fallback.
-    validateTagName(tagName);
-    const isESModule = modulePath.endsWith('.mjs');
-    // Cheap pre-flight: the AST walker assumes the file contains at least one
-    // destructuring `for (... of [...])` loop with an array literal on the
-    // right-hand side, and (for ESM tags) at least one such loop inside a
-    // `document.addEventListener("DOMContentLoaded", ...)` block. If either
-    // assumption is violated the AST path errors with a confusing
-    // "Could not find DOMContentLoaded block" message, so fail fast here with
-    // actionable guidance instead.
-    if (!hasRecognizableRegistrationLoop(content)) {
-        throw new FurnaceError(`${CUSTOM_ELEMENTS_JS} does not contain a recognizable registration loop; refusing to mutate. ` +
-            'Run "fireforge reset --force" to restore the engine, or inspect the file manually.', tagName);
-    }
-    if (isESModule && !/document\.addEventListener\s*\(\s*["']DOMContentLoaded["']/.test(content)) {
-        throw new FurnaceError(`${CUSTOM_ELEMENTS_JS} has no DOMContentLoaded block; cannot register ESM element ${tagName}. ` +
-            'The file may be corrupt — run "fireforge reset --force" to restore.', tagName);
-    }
-    let nextContent;
-    try {
-        nextContent = addRegistrationAST(content, tagName, modulePath, isESModule, options.markerComment);
-    }
-    catch (error) {
-        if (error instanceof FurnaceError) {
-            // AST structural errors (missing DOMContentLoaded block, etc.): try regex fallback
-            warn(`AST-based registration failed for ${tagName}: ${error.message}. ` +
-                'Falling back to regex-based insertion. Please report this so the AST parser can be updated.');
-            try {
-                nextContent = addRegistrationRegexFallback(content, tagName, modulePath, isESModule, options.markerComment);
-                verbose(`Regex fallback succeeded for ${tagName}. The registration may be less precise than the AST approach.`);
-            }
-            catch {
-                // If regex fallback also fails, throw the original AST error
-                throw error;
-            }
-        }
-        else {
-            const parserError = toError(error);
-            warn(`AST parser threw an unexpected error for ${tagName}: ${parserError.message}. ` +
-                'Falling back to regex-based insertion.');
-            try {
-                nextContent = addRegistrationRegexFallback(content, tagName, modulePath, isESModule, options.markerComment);
-                verbose(`Regex fallback succeeded for ${tagName}. The registration may be less precise than the AST approach.`);
-            }
-            catch {
-                throw new FurnaceError(`Failed to update ${CUSTOM_ELEMENTS_JS} using both AST and regex fallback: ${parserError.message}`, tagName, parserError);
-            }
-        }
-    }
-    validateRegistrationPlacement(nextContent, tagName, isESModule);
-    await writeText(filePath, nextContent);
-}
-/**
- * Validates that a custom element registration *would* succeed without
- * writing anything. Used by dry-run to surface registration errors early.
- */
-export async function validateCustomElementRegistration(engineDir, tagName, modulePath) {
-    const filePath = join(engineDir, CUSTOM_ELEMENTS_JS);
-    if (!(await pathExists(filePath))) {
-        throw new FurnaceError('customElements.js not found in engine', tagName);
-    }
-    const content = await readText(filePath);
-    if (isTagAlreadyRegistered(content, tagName)) {
-        return;
-    }
-    const isESModule = modulePath.endsWith('.mjs');
-    if (!hasRecognizableRegistrationLoop(content)) {
-        throw new FurnaceError(`${CUSTOM_ELEMENTS_JS} does not contain a recognizable registration loop; refusing to mutate. ` +
-            'Run "fireforge reset --force" to restore the engine, or inspect the file manually.', tagName);
-    }
-    if (isESModule && !/document\.addEventListener\s*\(\s*["']DOMContentLoaded["']/.test(content)) {
-        throw new FurnaceError(`${CUSTOM_ELEMENTS_JS} has no DOMContentLoaded block; cannot register ESM element ${tagName}. ` +
-            'The file may be corrupt — run "fireforge reset --force" to restore.', tagName);
-    }
-    try {
-        addRegistrationAST(content, tagName, modulePath, isESModule);
-    }
-    catch {
-        // Validation only: if AST fails, try regex to see if the entry could be placed
-        addRegistrationRegexFallback(content, tagName, modulePath, isESModule);
-    }
-}

package/dist/src/core/furnace-registration-jar-inplace.d.ts

@@ -1,12 +0,0 @@
-/**
- * Removes the lines registering `files` for `tagName`, leaving every other
- * line of the block where it is. Returns how many lines were removed.
- */
-export declare function removeJarMnFileEntries(engineDir: string, tagName: string, files: readonly string[]): Promise<number>;
-/**
- * Rewrites `oldTag`'s lines in place as `newTag`'s. A line whose renamed
- * file is in `liveFiles` keeps its position and layout; one whose file is
- * gone is dropped. Returns the renamed files that already had a line; the
- * caller's `addJarMnEntries` pass then inserts only the rest.
- */
-export declare function renameJarMnEntriesInPlace(engineDir: string, oldTag: string, newTag: string, liveFiles: readonly string[], renameFile: (file: string) => string): Promise<string[]>;

package/dist/src/core/furnace-registration-jar-inplace.js

@@ -1,79 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * In-place edits to a widget's `toolkit/content/jar.mn` block.
- *
- * Dropping every line of the widget and re-adding the live ones would
- * re-sort the whole block and leave the owning patch carrying reorder
- * hunks. These helpers touch only the lines that change: a deleted file's line goes, a renamed component's
- * lines are rewritten where they stand, and anything still missing is left
- * for `addJarMnEntries` to insert.
- */
-import { join } from 'node:path';
-import { pathExists, readText, writeText } from '../utils/fs.js';
-import { escapeRegex } from '../utils/regex.js';
-import { JAR_MN } from './furnace-constants.js';
-/**
- * The file a widget jar.mn line registers: the `(widgets/<tag>/<file>)`
- * source mapping, or the `content/global/elements/<tag>.<ext>` target of a
- * line that carries no source mapping. Undefined when the line is
- * not one of this tag's.
- */
-function registeredFile(line, tagName) {
-    const tag = escapeRegex(tagName);
-    const source = new RegExp(`\\(widgets/${tag}/([^)]+)\\)`).exec(line);
-    if (source)
-        return source[1];
-    const legacy = new RegExp(`content/global/elements/(${tag}\\.[^\\s]+)`).exec(line);
-    return legacy?.[1];
-}
-/**
- * Removes the lines registering `files` for `tagName`, leaving every other
- * line of the block where it is. Returns how many lines were removed.
- */
-export async function removeJarMnFileEntries(engineDir, tagName, files) {
-    const filePath = join(engineDir, JAR_MN);
-    if (files.length === 0 || !(await pathExists(filePath)))
-        return 0;
-    const doomed = new Set(files);
-    const lines = (await readText(filePath)).split('\n');
-    const kept = lines.filter((line) => {
-        const file = registeredFile(line, tagName);
-        return file === undefined || !doomed.has(file);
-    });
-    const removed = lines.length - kept.length;
-    if (removed > 0)
-        await writeText(filePath, kept.join('\n'));
-    return removed;
-}
-/**
- * Rewrites `oldTag`'s lines in place as `newTag`'s. A line whose renamed
- * file is in `liveFiles` keeps its position and layout; one whose file is
- * gone is dropped. Returns the renamed files that already had a line; the
- * caller's `addJarMnEntries` pass then inserts only the rest.
- */
-export async function renameJarMnEntriesInPlace(engineDir, oldTag, newTag, liveFiles, renameFile) {
-    const filePath = join(engineDir, JAR_MN);
-    if (!(await pathExists(filePath)))
-        return [];
-    const live = new Set(liveFiles);
-    const covered = [];
-    const out = [];
-    for (const line of (await readText(filePath)).split('\n')) {
-        const file = registeredFile(line, oldTag);
-        if (file === undefined) {
-            out.push(line);
-            continue;
-        }
-        const renamed = renameFile(file);
-        if (!live.has(renamed) || covered.includes(renamed))
-            continue;
-        // Textual substitution keeps the indent, column spacing and any
-        // trailing comment the line carried.
-        out.push(line
-            .replace(`content/global/elements/${file}`, `content/global/elements/${renamed}`)
-            .replace(`(widgets/${oldTag}/${file})`, `(widgets/${newTag}/${renamed})`));
-        covered.push(renamed);
-    }
-    await writeText(filePath, out.join('\n'));
-    return covered;
-}

package/dist/src/core/furnace-registration-remove.d.ts

@@ -1,56 +0,0 @@
-/**
- * Removal of custom element registrations from customElements.js.
- *
- * Uses the same AST parser as the add path (`furnace-registration-ast.ts`) to
- * locate and delete registration entries. A line-by-line scan with a bounded
- * bracket match only works against Firefox's stock formatting and fails
- * silently on a hand-reformatted customElements.js. AST-based bracket
- * matching does not depend on the file's formatting.
- *
- * Contract:
- * - Idempotent: if the tag is not registered, the file is left unchanged.
- * - Non-destructive on parse failure: if customElements.js cannot be parsed,
- *   the file is left untouched rather than falling through to a line-based
- *   heuristic that could delete the wrong range.
- * - Two registration shapes are recognised:
- *     (A) Standalone statement:
- *           customElements.setElementCreationCallback("tag", ...);
- *     (B) Entry inside a `for (... of [ ... ])` registration array, or an
- *         array declared by name and iterated with `for (... of NAME)`:
- *           ["tag", "chrome://..."]
- *   Both are deleted together with any trailing comma and newline so the
- *   resulting file is still valid JavaScript.
- */
-import type * as estree from 'estree';
-import { type AcornESTreeNode } from './ast-utils.js';
-/** A `[start, end)` source range in customElements.js. */
-export interface RemovalRange {
-    start: number;
-    end: number;
-}
-/**
- * Walks the AST and returns the source range of every registration of
- * `tagName`: each `[tag, module]` entry of a registration list, and each
- * statement enclosing a `setElementCreationCallback(tag, ...)` call.
- * Ancestor tracking lets us tell an "entry" array from a random
- * `["moz-foo", ...]` literal (only direct children of a registration list
- * are entries). Shared by removal and the in-place rename.
- *
- * @param ast - Parsed customElements.js
- * @param tagName - Tag whose registrations to find
- * @returns Unexpanded `[start, end)` ranges, in source order
- */
-export declare function findRegistrationRanges(ast: AcornESTreeNode<estree.Program>, tagName: string): RemovalRange[];
-/**
- * Removes a custom element registration from customElements.js.
- *
- * This operation is idempotent: if the tag is not registered or the file
- * does not exist, nothing happens. If the file exists but cannot be parsed,
- * the file is left unchanged rather than fall back to a line-based
- * heuristic. A corrupted customElements.js is a doctor problem, not
- * something `furnace remove` should "helpfully" edit around.
- *
- * @param engineDir - Path to the Firefox engine source root
- * @param tagName - Custom element tag name to remove
- */
-export declare function removeCustomElementRegistration(engineDir: string, tagName: string): Promise<void>;