@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/module-resolution-preflight.js

@@ -1,171 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Engine-aware resolution preflight for queue-owned system modules.
- *
- * An `.sys.mjs` that a packaged module imports but whose `EXTRA_JS_MODULES`
- * registration never landed kills every xpcshell suite with `xpcshell return
- * code: -11` and no output at all: no import error, no stack, nothing. The
- * queue-level `unregistered-system-module` check catches one shape of this:
- * a module newly created by a patch in the projected queue. The other shape,
- * modules imported from an already-existing module before their moz.build
- * lines land, slips past it entirely.
- *
- * This preflight closes that gap by asking the question against the engine
- * rather than against a projected diff: for every `resource:///modules/…`
- * specifier imported by any queue-owned module, does the module it names
- * exist, and is it registered in a moz.build that covers it?
- *
- * Scope is the queue-owned file set on purpose. A specifier that resolves to
- * no owned file is an upstream Firefox module, which FireForge does not
- * police and cannot cheaply enumerate. Policing only what the fork owns is
- * both the actionable set and the one that produces real incidents.
- *
- * An unscoped `verify` widens that set with the engine worktree: changed
- * files import, and untracked files are targets. A chrome script's lazy
- * getter for a new, not yet exported `.sys.mjs` with no moz.build line
- * SIGSEGVed every start of a shared objdir, and neither file was in the
- * queue yet, so the queue-only scan could not see it.
- */
-import { dirname, join } from 'node:path';
-import { toError } from '../utils/errors.js';
-import { pathExists, readText } from '../utils/fs.js';
-import { verbose } from '../utils/logger.js';
-import { escapeRegex } from '../utils/regex.js';
-import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from './git-status.js';
-import { extractResourceModuleSpecifiers, moduleSourceSuffix, } from './patch-lint-module-registration.js';
-/** Extensions whose contents are scanned for resource-module imports. */
-const IMPORTABLE_EXTENSIONS = ['.mjs', '.sys.mjs', '.js', '.jsm'];
-/**
- * Reads a file, returning undefined (with a verbose note) rather than
- * throwing: a preflight must not fail a command over one unreadable path.
- */
-async function readIfPresent(path) {
-    try {
-        if (!(await pathExists(path)))
-            return undefined;
-        return await readText(path);
-    }
-    catch (error) {
-        verbose(`Module resolution preflight: could not read ${path} — ${toError(error).message}`);
-        return undefined;
-    }
-}
-/**
- * True when some `moz.build` at or above `moduleRelPath`'s directory (up
- * to, and including, the engine root) mentions the module's basename.
- *
- * Walking ancestors, rather than checking only the sibling `moz.build`,
- * matches how Mozilla's build system actually works: a module list may sit
- * in a parent directory's `moz.build` with a path-qualified entry. The
- * check is a quoted-basename match for the same reason the queue-level
- * rule uses one: parsing moz.build's Python is not worth it for a
- * preflight, and a quoted basename has no meaningful false-positive shape.
- */
-async function isRegisteredInAncestorMozBuild(engineDir, moduleRelPath, mozBuildCache) {
-    const leaf = moduleRelPath.slice(moduleRelPath.lastIndexOf('/') + 1);
-    // The entry may be the bare basename (`"Foo.sys.mjs"`, sibling
-    // moz.build) or path-qualified relative to the moz.build that declares
-    // it (`"sub/Foo.sys.mjs"`, ancestor moz.build). Both are the same
-    // registration. Anchor on the closing quote and require a path boundary
-    // so `NotFoo.sys.mjs` cannot satisfy `Foo.sys.mjs`.
-    const quotedLeaf = new RegExp(`["'](?:[^"']*/)?${escapeRegex(leaf)}["']`);
-    let dir = dirname(moduleRelPath);
-    for (;;) {
-        const key = dir === '.' ? '' : dir;
-        if (!mozBuildCache.has(key)) {
-            mozBuildCache.set(key, await readIfPresent(join(engineDir, key, 'moz.build')));
-        }
-        const content = mozBuildCache.get(key);
-        if (content !== undefined && quotedLeaf.test(content))
-            return true;
-        if (dir === '.' || dir === '' || dir === '/')
-            return false;
-        const parent = dirname(dir);
-        if (parent === dir)
-            return false;
-        dir = parent;
-    }
-}
-/** Lists the engine's changed and untracked files for the worktree scan. */
-export async function collectWorktreeModuleFiles(engineDir) {
-    const entries = await expandUntrackedDirectoryEntries(engineDir, await getWorkingTreeStatus(engineDir));
-    const present = entries.filter((entry) => entry.worktreeStatus !== 'D');
-    return {
-        changed: present.map((entry) => entry.file),
-        untracked: present.filter((entry) => entry.status === '??').map((entry) => entry.file),
-    };
-}
-/**
- * Resolves every `resource://` system-module import made by the
- * queue-owned files (and, given `worktree`, by changed engine files) and
- * reports the ones a packaged browser could not load.
- *
- * @param engineDir - Path to the engine checkout
- * @param ownedFiles - Engine-relative paths the patch queue owns
- * @param worktree - Changed and untracked engine files to judge as well
- * @returns Findings sorted by module path. Empty when everything resolves
- */
-export async function findUnresolvedSystemModuleImports(engineDir, ownedFiles, worktree) {
-    const owned = [...new Set([...ownedFiles, ...(worktree?.untracked ?? [])])];
-    const importing = [...new Set([...owned, ...(worktree?.changed ?? [])])];
-    /** specifier → importing files. */
-    const importersBySpecifier = new Map();
-    for (const file of importing) {
-        if (!IMPORTABLE_EXTENSIONS.some((extension) => file.endsWith(extension)))
-            continue;
-        const content = await readIfPresent(join(engineDir, file));
-        if (content === undefined)
-            continue;
-        for (const specifier of extractResourceModuleSpecifiers(content)) {
-            const importers = importersBySpecifier.get(specifier) ?? new Set();
-            importers.add(file);
-            importersBySpecifier.set(specifier, importers);
-        }
-    }
-    const mozBuildCache = new Map();
-    const findings = [];
-    for (const [specifier, importers] of importersBySpecifier) {
-        const suffix = moduleSourceSuffix(specifier);
-        if (suffix === undefined)
-            continue;
-        // Only fork-owned targets are policed. Anything else is upstream.
-        const target = owned.find((file) => file.endsWith(suffix));
-        if (target === undefined)
-            continue;
-        const sortedImporters = [...importers].sort((a, b) => a.localeCompare(b));
-        if (!(await pathExists(join(engineDir, target)))) {
-            findings.push({
-                module: target,
-                specifier,
-                importers: sortedImporters,
-                reason: 'missing-file',
-            });
-            continue;
-        }
-        if (!(await isRegisteredInAncestorMozBuild(engineDir, target, mozBuildCache))) {
-            findings.push({
-                module: target,
-                specifier,
-                importers: sortedImporters,
-                reason: 'unregistered',
-            });
-        }
-    }
-    // Deterministic order regardless of Map iteration or owned-file order.
-    return findings.sort((a, b) => a.module.localeCompare(b.module) || a.specifier.localeCompare(b.specifier));
-}
-/**
- * Renders findings as operator-facing lines, naming the unregistered or
- * unresolvable module, so the failure is a sentence instead of a bare
- * `-11`.
- */
-export function formatUnresolvedSystemModuleImports(findings) {
-    return findings.map((finding) => finding.reason === 'missing-file'
-        ? `${finding.module}: imported as ${finding.specifier} by ${finding.importers.join(', ')}, ` +
-            'but the file does not exist in engine/. A packaged browser cannot load it; xpcshell ' +
-            'dies on SIGSEGV with no output.'
-        : `${finding.module}: imported as ${finding.specifier} by ${finding.importers.join(', ')}, ` +
-            'but no moz.build at or above its directory registers it. Add it to EXTRA_JS_MODULES ' +
-            '(or the appropriate namespaced module list) — until then a packaged browser cannot ' +
-            'load it and xpcshell dies on SIGSEGV with no output.');
-}

package/dist/src/core/moz-manifest-helpers.d.ts

@@ -1,79 +0,0 @@
-import type { MozBuildToken } from './moz-manifest-tokenizers.js';
-/**
- * Ordering comparator matching mozbuild's `StrictOrderingOnAppendList`
- * (`mozbuild.util.UnsortedError`): entries are compared case-insensitively,
- * so `HominisAppearanceController` (`appe`) sorts before
- * `HominisAppMenuIntegration` (`appm`) even though a raw byte comparison
- * places the uppercase `M` (0x4D) before the lowercase `e` (0x65).
- *
- * A naive `a > b` insertion landed the new entry in byte order, which
- * `mach configure` then rejected with `UnsortedError`, aborting the build.
- * Ties on the lower-cased key fall back to byte order so the comparison is
- * total and stable.
- */
-export declare function mozbuildSortCompare(a: string, b: string): number;
-/**
- * Find alphabetical position within tokenized moz.build list items.
- */
-export declare function findAlphabeticalMozBuildPosition(tokens: MozBuildToken[], newKey: string): {
-    insertIndex: number;
-    previousEntry: string | undefined;
-};
-/**
- * Inserts one entry into a tokenized jar.mn / jar.inc.mn, honouring an
- * explicit `--after` anchor and falling back to alphabetical placement when
- * the anchor is not found.
- *
- * Shared by the two jar.mn registrars (browser content, shared CSS), which
- * differ only in the sort pattern, the sort key and the "could not find the
- * section" message, so the anchor-fallback semantics are defined once:
- * silently fall back rather than refuse, and report `afterFallback` so the
- * caller can say so.
- *
- * This helper is jar.mn-specific: the moz.build list form has no `after` anchor
- * and no section concept, so a single generic helper over both families
- * would carry parameters that are meaningless on one side. See
- * {@link insertMozBuildListEntry} for its twin.
- *
- * @param content - Full manifest text
- * @param entry - The already-formatted line to insert
- * @param options - Sort pattern/key, refusal message, and optional anchor
- * @returns The rewritten text plus where it landed and how
- */
-export declare function insertJarMnEntry(content: string, entry: string, options: {
-    sortPattern: RegExp;
-    sortKey: string;
-    missingSectionMessage: string;
-    after?: string | undefined;
-}): {
-    result: string;
-    insertIndex: number;
-    previousEntry: string | undefined;
-    afterFallback: boolean;
-};
-/**
- * Inserts one entry alphabetically into a moz.build Python list block.
- *
- * Shared by the two moz.build registrars (module list, browser test
- * manifests), which differ only in the list pattern, the sort key and the
- * refusal message.
- *
- * `tokenizeMozBuildList` mutates `lines` in place when it normalizes the
- * single-line `FOO += []` form into the multi-line shape, and that rewrite is
- * what makes the caller's `splice` land inside the list body. The splice
- * below therefore has to run against the same array the tokenizer was
- * handed. A wrapper that tokenized a copy would silently break it.
- *
- * @param content - Full moz.build text
- * @param entry - The already-formatted line to insert
- * @param options - List pattern, sort key, and refusal message
- * @returns The rewritten text and the entry it landed after
- */
-export declare function insertMozBuildListEntry(content: string, entry: string, options: {
-    listPattern: RegExp;
-    sortKey: string;
-    missingListMessage: string;
-}): {
-    result: string;
-    previousEntry: string | undefined;
-};

package/dist/src/core/moz-manifest-helpers.js

@@ -1,163 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { GeneralError } from '../errors/base.js';
-import { escapeRegex } from '../utils/regex.js';
-import { tokenizeJarMn, tokenizeMozBuildList } from './moz-manifest-tokenizers.js';
-/**
- * Ordering comparator matching mozbuild's `StrictOrderingOnAppendList`
- * (`mozbuild.util.UnsortedError`): entries are compared case-insensitively,
- * so `HominisAppearanceController` (`appe`) sorts before
- * `HominisAppMenuIntegration` (`appm`) even though a raw byte comparison
- * places the uppercase `M` (0x4D) before the lowercase `e` (0x65).
- *
- * A naive `a > b` insertion landed the new entry in byte order, which
- * `mach configure` then rejected with `UnsortedError`, aborting the build.
- * Ties on the lower-cased key fall back to byte order so the comparison is
- * total and stable.
- */
-export function mozbuildSortCompare(a, b) {
-    const la = a.toLowerCase();
-    const lb = b.toLowerCase();
-    if (la < lb)
-        return -1;
-    if (la > lb)
-        return 1;
-    if (a < b)
-        return -1;
-    if (a > b)
-        return 1;
-    return 0;
-}
-/**
- * Find alphabetical position within a tokenized jar.mn section. Private:
- * {@link insertJarMnEntry} is the only caller and the only entry point
- * the jar.mn registrars should use.
- */
-function findAlphabeticalTokenPosition(tokens, sectionTargetPattern, newKey) {
-    // Find entry tokens in the section matching the pattern
-    const sectionEntries = tokens.filter((t) => t.type === 'entry' && t.parsed && sectionTargetPattern.test(t.parsed.target));
-    let insertLineIndex;
-    let previousEntry;
-    if (sectionEntries.length === 0) {
-        // Empty section: find the section header and insert after it
-        const headerToken = tokens.find((t) => t.type === 'header' || (t.type === 'directive' && sectionTargetPattern.test(t.raw)));
-        if (headerToken) {
-            return { insertIndex: headerToken.lineIndex + 1, previousEntry: undefined };
-        }
-        return { insertIndex: -1, previousEntry: undefined };
-    }
-    // Default: after the last section entry
-    insertLineIndex = (sectionEntries[sectionEntries.length - 1]?.lineIndex ?? 0) + 1;
-    for (const entry of sectionEntries) {
-        if (!entry.parsed)
-            continue;
-        const match = sectionTargetPattern.exec(entry.parsed.target);
-        const key = match?.[1] ?? entry.parsed.target;
-        if (mozbuildSortCompare(key, newKey) > 0) {
-            insertLineIndex = entry.lineIndex;
-            break;
-        }
-        insertLineIndex = entry.lineIndex + 1;
-        previousEntry = entry.raw.trim();
-    }
-    return { insertIndex: insertLineIndex, previousEntry };
-}
-/**
- * Find alphabetical position within tokenized moz.build list items.
- */
-export function findAlphabeticalMozBuildPosition(tokens, newKey) {
-    const items = tokens.filter((t) => t.type === 'list-item');
-    if (items.length === 0) {
-        // Insert after list-open
-        const openToken = tokens.find((t) => t.type === 'list-open');
-        return { insertIndex: (openToken?.lineIndex ?? 0) + 1, previousEntry: undefined };
-    }
-    let insertLineIndex = (items[items.length - 1]?.lineIndex ?? 0) + 1;
-    let previousEntry;
-    for (const item of items) {
-        const key = item.parsed?.value ?? '';
-        if (mozbuildSortCompare(key, newKey) > 0) {
-            insertLineIndex = item.lineIndex;
-            break;
-        }
-        insertLineIndex = item.lineIndex + 1;
-        previousEntry = item.raw.trim();
-    }
-    return { insertIndex: insertLineIndex, previousEntry };
-}
-/**
- * Inserts one entry into a tokenized jar.mn / jar.inc.mn, honouring an
- * explicit `--after` anchor and falling back to alphabetical placement when
- * the anchor is not found.
- *
- * Shared by the two jar.mn registrars (browser content, shared CSS), which
- * differ only in the sort pattern, the sort key and the "could not find the
- * section" message, so the anchor-fallback semantics are defined once:
- * silently fall back rather than refuse, and report `afterFallback` so the
- * caller can say so.
- *
- * This helper is jar.mn-specific: the moz.build list form has no `after` anchor
- * and no section concept, so a single generic helper over both families
- * would carry parameters that are meaningless on one side. See
- * {@link insertMozBuildListEntry} for its twin.
- *
- * @param content - Full manifest text
- * @param entry - The already-formatted line to insert
- * @param options - Sort pattern/key, refusal message, and optional anchor
- * @returns The rewritten text plus where it landed and how
- */
-export function insertJarMnEntry(content, entry, options) {
-    const lines = content.split('\n');
-    const tokens = tokenizeJarMn(lines);
-    let afterFallback = false;
-    let insertIndex;
-    let previousEntry;
-    const alphabetical = () => findAlphabeticalTokenPosition(tokens, options.sortPattern, options.sortKey);
-    if (options.after) {
-        const afterPattern = new RegExp(`(?:^|/)${escapeRegex(options.after)}(?:\\s|\\)|$)`);
-        const afterToken = tokens.find((t) => afterPattern.test(t.raw));
-        if (afterToken) {
-            insertIndex = afterToken.lineIndex + 1;
-            previousEntry = afterToken.raw.trim();
-        }
-        else {
-            afterFallback = true;
-            ({ insertIndex, previousEntry } = alphabetical());
-        }
-    }
-    else {
-        ({ insertIndex, previousEntry } = alphabetical());
-    }
-    if (insertIndex === -1) {
-        throw new GeneralError(options.missingSectionMessage);
-    }
-    lines.splice(insertIndex, 0, entry);
-    return { result: lines.join('\n'), insertIndex, previousEntry, afterFallback };
-}
-/**
- * Inserts one entry alphabetically into a moz.build Python list block.
- *
- * Shared by the two moz.build registrars (module list, browser test
- * manifests), which differ only in the list pattern, the sort key and the
- * refusal message.
- *
- * `tokenizeMozBuildList` mutates `lines` in place when it normalizes the
- * single-line `FOO += []` form into the multi-line shape, and that rewrite is
- * what makes the caller's `splice` land inside the list body. The splice
- * below therefore has to run against the same array the tokenizer was
- * handed. A wrapper that tokenized a copy would silently break it.
- *
- * @param content - Full moz.build text
- * @param entry - The already-formatted line to insert
- * @param options - List pattern, sort key, and refusal message
- * @returns The rewritten text and the entry it landed after
- */
-export function insertMozBuildListEntry(content, entry, options) {
-    const lines = content.split('\n');
-    const listResult = tokenizeMozBuildList(lines, options.listPattern);
-    if (!listResult) {
-        throw new GeneralError(options.missingListMessage);
-    }
-    const { insertIndex, previousEntry } = findAlphabeticalMozBuildPosition(listResult.tokens, options.sortKey);
-    lines.splice(insertIndex, 0, entry);
-    return { result: lines.join('\n'), previousEntry };
-}

package/dist/src/core/moz-manifest-register.d.ts

@@ -1,19 +0,0 @@
-/**
- * Manifest registration barrel. Re-exports all registration targets
- * and the shared RegisterResult interface (which lives in
- * `register-result.ts` so the leaf modules can import it without
- * creating a cycle through this barrel).
- */
-import type { RegisterResult } from './register-result.js';
-export type { RegisterResult } from './register-result.js';
-export { registerBrowserContent } from './register-browser-content.js';
-export { deregisterTestManifest, registerTestManifest } from './register-browser-test.js';
-export { registerFireForgeModule } from './register-module.js';
-export { registerSharedCSS } from './register-shared-css.js';
-/**
- * Registers a widget file (mjs or css) in toolkit/content/jar.mn.
- *
- * Entry format (3-space indent):
- *    content/global/elements/{file}  (widgets/{tagName}/{file})
- */
-export declare function registerToolkitWidget(engineDir: string, tagName: string, fileName: string, dryRun?: boolean): Promise<RegisterResult>;

package/dist/src/core/moz-manifest-register.js

@@ -1,51 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Manifest registration barrel. Re-exports all registration targets
- * and the shared RegisterResult interface (which lives in
- * `register-result.ts` so the leaf modules can import it without
- * creating a cycle through this barrel).
- */
-import { join } from 'node:path';
-import { GeneralError } from '../errors/base.js';
-import { pathExists, readText, writeText } from '../utils/fs.js';
-import { insertJarMnEntry } from './moz-manifest-helpers.js';
-// Re-export from split modules so existing import sites continue working
-export { registerBrowserContent } from './register-browser-content.js';
-export { deregisterTestManifest, registerTestManifest } from './register-browser-test.js';
-export { registerFireForgeModule } from './register-module.js';
-export { registerSharedCSS } from './register-shared-css.js';
-// ---------------------------------------------------------------------------
-// toolkit/content/jar.mn: widget registration
-// ---------------------------------------------------------------------------
-/**
- * Registers a widget file (mjs or css) in toolkit/content/jar.mn.
- *
- * Entry format (3-space indent):
- *    content/global/elements/{file}  (widgets/{tagName}/{file})
- */
-export async function registerToolkitWidget(engineDir, tagName, fileName, dryRun = false) {
-    const manifest = 'toolkit/content/jar.mn';
-    const manifestPath = join(engineDir, manifest);
-    if (!(await pathExists(manifestPath))) {
-        throw new GeneralError(`Manifest not found: ${manifest}`);
-    }
-    const entry = `   content/global/elements/${fileName}  (widgets/${tagName}/${fileName})`.replace(/\\/g, '/');
-    const content = await readText(manifestPath);
-    // Idempotency check
-    if (content.includes(`content/global/elements/${fileName}`)) {
-        return { manifest, entry, skipped: true };
-    }
-    // Tokenized like the other three jar.mn registrars. The hand-rolled
-    // line scan this replaced re-derived the section bounds and the sort
-    // key with its own regexes, so it was the one jar.mn target that did
-    // not inherit fixes made to the shared path.
-    const { result, previousEntry } = insertJarMnEntry(content, entry, {
-        sortPattern: /content\/global\/elements\/([^\s]+)/,
-        sortKey: fileName,
-        missingSectionMessage: 'Could not find content/global/elements/ section in toolkit/content/jar.mn',
-    });
-    if (!dryRun) {
-        await writeText(manifestPath, result);
-    }
-    return { manifest, entry, previousEntry, skipped: false };
-}

package/dist/src/core/moz-manifest-rules.d.ts

@@ -1,58 +0,0 @@
-import type { RegisterResult } from './moz-manifest-register.js';
-/** Pattern rules mapping file paths to manifest types */
-export interface PatternRule {
-    /** Regex to match the file path (relative to engine/) */
-    pattern: RegExp;
-    /** Checks whether the file is already registered in its manifest */
-    isRegistered: (engineDir: string, ...args: string[]) => Promise<boolean>;
-    /** Register function */
-    register: (engineDir: string, after: string | undefined, dryRun: boolean, ...args: string[]) => Promise<RegisterResult>;
-    /** Extract arguments from the regex match */
-    extractArgs: (match: RegExpMatchArray) => string[];
-    /**
-     * Whether this rule's manifest supports `--after` placement.
-     *
-     * Four of the six rules ignore the flag entirely: the CLI accepts
-     * `--after`, the adapter takes it as `_after`, and the operator gets a
-     * silently alphabetical insertion with no indication their placement was
-     * dropped. Declaring it lets {@link registerFile} say so.
-     */
-    supportsAfter: boolean;
-}
-/**
- * Returns manifest registration rules for the supported engine file
- * patterns. `createManifest` (from `register --create-manifest`) lets the
- * module and xpcshell-test rules scaffold a missing manifest (directory
- * moz.build / xpcshell.toml) and wire the parent chain instead of failing
- * with "Manifest not found".
- */
-export declare function getRules(binaryName: string, createManifest?: boolean): PatternRule[];
-/**
- * Checks if a file path matches any known registrable pattern.
- * @param filePath - Path relative to engine/
- * @param binaryName - Binary name from fireforge.json (used for module directory)
- * @returns True if the file matches a known registration pattern
- */
-export declare function matchesRegistrablePattern(filePath: string, binaryName: string): boolean;
-/**
- * Checks whether a supported registrable file is already present in its manifest.
- *
- * @param root - Project root directory
- * @param filePath - Path relative to engine/
- * @returns True if the file is already registered in its manifest
- */
-export declare function isFileRegistered(root: string, filePath: string): Promise<boolean>;
-/**
- * Registers a file in the appropriate build manifest.
- *
- * @param root - Project root directory
- * @param filePath - Path relative to engine/
- * @param dryRun - If true, return what would be done without writing
- * @param after - Optional substring to place entry after (instead of alphabetical)
- * @param options - `createManifest` scaffolds a missing manifest (directory
- *   moz.build / xpcshell.toml) and wires the parent chain instead of failing
- * @returns Registration result
- */
-export declare function registerFile(root: string, filePath: string, dryRun?: boolean, after?: string, options?: {
-    createManifest?: boolean;
-}): Promise<RegisterResult>;