@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/mozbuild/mozbuild.js

@@ -0,0 +1,321 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `moz.build`: the list assignments (`EXTRA_JS_MODULES += [...]`,
+ * `EXTRA_JS_MODULES.ns += [...]`, `FOO["x"] = [...]`) and the edits that keep
+ * them valid. moz.build is Python; this reads only list literals of strings
+ * at statement level and tells whether each sits inside an `if` block.
+ */
+import { resolveManifestPath, TEST_MANIFEST_VARIABLES, } from './paths.js';
+import { compareInsensitive, joinSource, manifestError, scanStringList, sortedInsertIndex, spliceLines, splitSource, } from './text.js';
+const LIST_START = /^(\s*)([A-Z_][A-Z_0-9]*)((?:\.[A-Za-z_]\w*)|(?:\[[^\]]+\]))?\s*(\+=|=)\s*\[/;
+const BLOCK_KEYWORD = /^\s*(if|elif|else|for|with|while|try|except|finally|def|class)\b/;
+/** A line without its trailing `#` comment; strings are not modelled, which moz.build headers do not need. */
+function code(line) {
+    return line.replace(/#.*$/, '').trimEnd();
+}
+/**
+ * The last line of a block header starting at `index`: the line where the
+ * brackets opened on the header close and the text ends with `:`, so
+ * `if (\n    a\n    and b\n):` is one header. Undefined when no such line
+ * follows (the keyword starts no block).
+ */
+function headerEnd(lines, index) {
+    let depth = 0;
+    for (let at = index; at < lines.length; at++) {
+        const text = code(lines[at]?.text ?? '');
+        for (const char of text) {
+            if ('([{'.includes(char))
+                depth++;
+            else if (')]}'.includes(char))
+                depth--;
+        }
+        if (depth <= 0)
+            return text.endsWith(':') ? at : undefined;
+    }
+    return undefined;
+}
+/**
+ * Parses a moz.build. Never throws: statements it does not recognise are
+ * skipped, so partial text (the added lines of a diff) parses as well. A
+ * list is conditional inside an `if`/`elif`/`else` block, and whenever it is
+ * indented: an indented statement belongs to some block, and an edit must
+ * not treat a list a block may skip as the file's own.
+ *
+ * @param text - moz.build text
+ */
+export function parseMozBuild(text) {
+    const lines = splitSource(text);
+    const lists = [];
+    const blocks = [];
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index]?.text ?? '';
+        if (line.trim() === '' || line.trimStart().startsWith('#'))
+            continue;
+        const indent = line.length - line.trimStart().length;
+        while ((blocks.at(-1)?.indent ?? -1) >= indent)
+            blocks.pop();
+        const start = LIST_START.exec(line);
+        if (start !== null) {
+            const scan = scanStringList(lines, index, start[0].length);
+            if (scan !== undefined) {
+                lists.push({
+                    variable: (start[2] ?? '') + (start[3] ?? ''),
+                    name: start[2] ?? '',
+                    operator: start[4] === '=' ? '=' : '+=',
+                    startLine: index,
+                    endLine: scan.endLine,
+                    indent: start[1] ?? '',
+                    conditional: indent > 0 || blocks.some((block) => block.conditional),
+                    items: scan.items,
+                });
+                index = scan.endLine;
+            }
+            continue;
+        }
+        const keyword = BLOCK_KEYWORD.exec(line)?.[1];
+        const end = keyword === undefined ? undefined : headerEnd(lines, index);
+        if (keyword !== undefined && end !== undefined) {
+            blocks.push({ indent, conditional: ['if', 'elif', 'else'].includes(keyword) });
+            index = end;
+        }
+    }
+    return { lines, lists };
+}
+/**
+ * The lists assigned to `variable` (exactly as written, so
+ * `EXTRA_JS_MODULES.ns` is not `EXTRA_JS_MODULES`).
+ *
+ * @param text - moz.build text
+ * @param variable - Assignment target
+ * @param selector - Which lists count
+ */
+export function findMozBuildLists(text, variable, selector = {}) {
+    return selectLists(parseMozBuild(text), variable, selector);
+}
+function selectLists(file, variable, selector) {
+    return file.lists.filter((list) => list.variable === variable &&
+        (selector.line === undefined
+            ? selector.conditional === true || !list.conditional
+            : list.startLine === selector.line));
+}
+function single(file, variable, selector) {
+    const matches = selectLists(file, variable, selector);
+    if (matches.length > 1) {
+        throw manifestError(`${variable} is assigned in several places.`, 'Select one list with the line option.');
+    }
+    return matches[0];
+}
+function quoted(value, quote) {
+    return `${quote}${value}${quote}`;
+}
+/** Comment lines directly above `line` belong to the item on it. */
+function blockStart(lines, line, floor) {
+    let start = line;
+    while (start - 1 > floor && (lines[start - 1]?.text ?? '').trimStart().startsWith('#'))
+        start--;
+    return start;
+}
+/** Rewrites a one-line list as the multi-line shape, with its items on their own lines. */
+function expandList(file, list, extra) {
+    const text = file.lines[list.startLine]?.text ?? '';
+    const quote = list.items[0]?.quote ?? '"';
+    const open = text.slice(0, LIST_START.exec(text)?.[0].length ?? 0);
+    const close = text.slice(text.lastIndexOf(']'));
+    const itemIndent = `${list.indent}    `;
+    const values = list.items.map((item) => item.value);
+    const sorted = values.every((value, i) => i === 0 || compareInsensitive(values[i - 1] ?? '', value) <= 0);
+    const all = [...values];
+    all.splice(sorted ? sortedInsertIndex(values, extra) : values.length, 0, extra);
+    const body = all.map((value) => `${itemIndent}${quoted(value, quote)},`);
+    return spliceLines(file.lines, list.startLine, 1, [open, ...body, `${list.indent}${close}`]);
+}
+/**
+ * Adds `value` to a list of `variable`, in sort order when the list is
+ * sorted (case-insensitively, as mozbuild checks) and last when it is not.
+ * A one-line list becomes a multi-line one. An item already present changes
+ * nothing; two candidate lists, or none without `create`, are refused.
+ *
+ * @param text - moz.build text
+ * @param variable - Assignment target
+ * @param value - The string to add
+ * @param options - Which list, and whether to create one
+ */
+export function addToMozBuildList(text, variable, value, options = {}) {
+    const file = parseMozBuild(text);
+    const list = single(file, variable, options);
+    if (list === undefined) {
+        if (options.create !== true)
+            throw manifestError(`No list assigned to ${variable} was found.`);
+        return appendList(file, variable, value);
+    }
+    const present = list.items.find((item) => item.value === value);
+    if (present !== undefined)
+        return { text, changed: false, line: present.line };
+    if (list.startLine === list.endLine) {
+        return {
+            text: joinSource(expandList(file, list, value)),
+            changed: true,
+            line: list.startLine + 1,
+        };
+    }
+    return insertItemLine(file, list, value);
+}
+/** Adds a new `variable += [...]` statement at the end of the file. */
+function appendList(file, variable, value) {
+    const kept = [...file.lines];
+    while (kept.length > 0 && (kept.at(-1)?.text ?? '').trim() === '')
+        kept.pop();
+    const block = [...(kept.length > 0 ? [''] : []), `${variable} += [`, `    "${value}",`, ']'];
+    return {
+        text: joinSource(spliceLines(kept, kept.length, 0, block)),
+        changed: true,
+        line: kept.length + (kept.length > 0 ? 1 : 0),
+    };
+}
+/** Puts a new item on its own line of a multi-line list, copying a neighbour's indentation and quotes. */
+function insertItemLine(file, list, value) {
+    const slots = list.items.filter((item) => item.ownLine);
+    const index = sortedInsertIndex(slots.map((slot) => slot.value), value);
+    const next = slots[index];
+    const previous = slots[index - 1];
+    const at = next === undefined
+        ? (previous?.line ?? list.startLine) + 1
+        : blockStart(file.lines, next.line, previous?.line ?? list.startLine);
+    const neighbour = previous ?? next;
+    const indent = neighbour === undefined
+        ? `${list.indent}    `
+        : (file.lines[neighbour.line]?.text.slice(0, neighbour.start) ?? '');
+    let lines = [...file.lines];
+    const before = previous === undefined ? undefined : lines[previous.line];
+    if (previous !== undefined && before !== undefined) {
+        if (!before.text.slice(previous.end).trimStart().startsWith(',')) {
+            const text = `${before.text.slice(0, previous.end)},${before.text.slice(previous.end)}`;
+            lines[previous.line] = { ...before, text };
+        }
+    }
+    lines = spliceLines(lines, at, 0, [`${indent}${quoted(value, neighbour?.quote ?? '"')},`]);
+    const result = { text: joinSource(lines), changed: true, line: at };
+    if (before !== undefined)
+        result.previous = before.text.trim();
+    return result;
+}
+/**
+ * Removes `value` from a list of `variable`. An item alone on its line takes
+ * the line with it; one sharing a line takes only itself and a neighbouring
+ * comma.
+ *
+ * @param text - moz.build text
+ * @param variable - Assignment target
+ * @param value - The string to remove
+ * @param selector - Which list
+ */
+export function removeFromMozBuildList(text, variable, value, selector = {}) {
+    const file = parseMozBuild(text);
+    const list = single(file, variable, selector);
+    const item = list?.items.find((candidate) => candidate.value === value);
+    if (item === undefined)
+        return { text, changed: false };
+    if (item.ownLine && (list?.startLine ?? item.line) !== item.line) {
+        return { text: joinSource(spliceLines(file.lines, item.line, 1, [])), changed: true };
+    }
+    const line = file.lines[item.line];
+    if (line === undefined)
+        return { text, changed: false };
+    const after = /^\s*,\s*/.exec(line.text.slice(item.end));
+    const before = /,\s*$/.exec(line.text.slice(0, item.start));
+    const from = after === null && before !== null ? item.start - before[0].length : item.start;
+    const to = item.end + (after?.[0].length ?? 0);
+    const lines = [...file.lines];
+    lines[item.line] = { ...line, text: line.text.slice(0, from) + line.text.slice(to) };
+    return { text: joinSource(lines), changed: true };
+}
+/**
+ * The paths a moz.build lists, resolved against its directory. Only list
+ * items count; strings elsewhere (conditions, `with Files("...")`) are not
+ * paths the build reads.
+ *
+ * @param manifestPath - Engine-relative path of the moz.build
+ * @param text - moz.build text
+ */
+export function mozBuildReferences(manifestPath, text) {
+    const file = parseMozBuild(text);
+    const references = [];
+    for (const list of file.lists) {
+        for (const item of list.items) {
+            if (!item.value.includes('.') && !item.value.includes('/'))
+                continue;
+            const matcher = resolveManifestPath(manifestPath, item.value);
+            if (matcher === undefined)
+                continue;
+            references.push({
+                kind: 'list-item',
+                token: item.value,
+                line: item.line,
+                text: (file.lines[item.line]?.text ?? '').trim(),
+                matcher,
+            });
+        }
+    }
+    return references;
+}
+/**
+ * The test manifests a moz.build lists in its `*_MANIFESTS` variables, with
+ * the flavour each variable declares. Conditional lists count: the manifest
+ * is a test manifest whether or not this build runs it.
+ *
+ * @param manifestPath - Engine-relative path of the moz.build
+ * @param text - moz.build text
+ */
+export function mozBuildTestManifests(manifestPath, text) {
+    const listed = [];
+    for (const list of parseMozBuild(text).lists) {
+        const flavor = TEST_MANIFEST_VARIABLES[list.name];
+        if (flavor === undefined)
+            continue;
+        for (const item of list.items) {
+            const path = resolveManifestPath(manifestPath, item.value)?.exact;
+            if (path !== undefined)
+                listed.push({ path, flavor, variable: list.name, value: item.value });
+        }
+    }
+    return listed;
+}
+/**
+ * Variables mozbuild declares as strict-ordering lists: configure refuses an
+ * out-of-order append. `DIRS` is not among them, since directory order
+ * matters. A dotted namespace inherits its variable's rule.
+ */
+const STRICT_ORDERED = new Set([
+    'EXTRA_COMPONENTS',
+    'EXTRA_JS_MODULES',
+    'EXTRA_PP_COMPONENTS',
+    'EXPORTS',
+    'PYTHON_UNITTEST_MANIFESTS',
+    'TESTING_JS_MODULES',
+    'XPIDL_SOURCES',
+]);
+/**
+ * The strict-ordering lists of a moz.build that are not sorted, with the
+ * first out-of-place item of each, as mozbuild reports them at configure time.
+ *
+ * @param text - moz.build text
+ */
+export function mozBuildSortViolations(text) {
+    const violations = [];
+    for (const list of parseMozBuild(text).lists) {
+        if (!STRICT_ORDERED.has(list.name))
+            continue;
+        const values = list.items.map((item) => item.value);
+        const sorted = [...values].sort(compareInsensitive);
+        const at = values.findIndex((value, i) => value !== sorted[i]);
+        if (at === -1)
+            continue;
+        violations.push({
+            variable: list.variable,
+            line: list.items[at]?.line ?? list.startLine,
+            expected: sorted[at] ?? '',
+            got: values[at] ?? '',
+        });
+    }
+    return violations;
+}

package/dist/src/mozbuild/paths.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * What a file name says about a manifest, and how a path written inside a
+ * manifest resolves to engine paths.
+ */
+import { posix } from 'node:path';
+import { globToRegExp } from '../kernel/glob.js';
+/** The moz.build variables that list test manifests, and the flavour each one declares. */
+export const TEST_MANIFEST_VARIABLES = {
+    BROWSER_CHROME_MANIFESTS: 'browser-chrome',
+    XPCSHELL_TESTS_MANIFESTS: 'xpcshell',
+    MOCHITEST_MANIFESTS: 'mochitest',
+    MOCHITEST_CHROME_MANIFESTS: 'chrome',
+    A11Y_MANIFESTS: 'a11y',
+};
+/**
+ * Test manifest names: a flavour word, optionally followed by a suffix
+ * (`browser-srd.toml`, `browserNova.toml`, `xpcshell_snap.toml`). The
+ * moz.build that lists a manifest is the authority; this covers the names
+ * Firefox uses for nearly all of them. A pattern such as "any `.toml`"
+ * would sweep in Cargo and taskcluster files whose keys mean something else.
+ */
+const TEST_MANIFEST_NAME = /^(browser|xpcshell|mochitest|chrome|a11y)(?:[-_.][\w.-]*|[A-Z][\w-]*)?\.(?:toml|ini)$/;
+const NAME_FLAVOR = {
+    browser: 'browser-chrome',
+    xpcshell: 'xpcshell',
+    mochitest: 'mochitest',
+    chrome: 'chrome',
+    a11y: 'a11y',
+};
+/** `jar.mn`, `addon-jar.mn`, `desktop-jar.inc.mn`, `minimal-toolkit.jar.inc.mn`, and included `*.inc.mn`. */
+const JAR_NAME = /^(?:(?:[\w-]+[.-])?jar(?:\.[\w-]+)*|[\w.-]+\.inc)\.mn$/;
+function fileName(path) {
+    return path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\')) + 1);
+}
+/**
+ * The manifest format a path names, or undefined when it is none of them.
+ *
+ * @param path - A path with either separator
+ */
+export function manifestKind(path) {
+    const name = fileName(path);
+    if (JAR_NAME.test(name))
+        return 'jar';
+    if (name === 'moz.build')
+        return 'moz-build';
+    if (TEST_MANIFEST_NAME.test(name))
+        return 'test-manifest';
+    return undefined;
+}
+/**
+ * The flavour a test manifest's name declares, or undefined when the name
+ * is not a test manifest's.
+ *
+ * @param path - A path with either separator
+ */
+export function testManifestFlavor(path) {
+    const word = TEST_MANIFEST_NAME.exec(fileName(path))?.[1];
+    return word === undefined ? undefined : NAME_FLAVOR[word];
+}
+/**
+ * Resolves a path written in a manifest to a matcher over engine-relative
+ * paths. The path is relative to the manifest's directory (`../` allowed);
+ * `/` and `!/` start at the engine root. `*` and `?` stay inside a segment
+ * and `**` crosses segments. Anything that names no engine path returns
+ * undefined: an objdir path (`!foo`), a build-time substitution
+ * (`@AB_CD@`), a path with whitespace, or one that climbs out of the tree.
+ *
+ * @param manifestPath - Engine-relative path of the manifest
+ * @param written - The path as written, without quotes
+ * @param options - How the carrying file reads paths
+ */
+export function resolveManifestPath(manifestPath, written, options = {}) {
+    if (written === '' || /\s/.test(written) || /@[A-Za-z_]+@/.test(written))
+        return undefined;
+    const rooted = /^!?\//.test(written);
+    if (!rooted && written.startsWith('!'))
+        return undefined;
+    const base = posix.dirname(manifestPath.replaceAll('\\', '/'));
+    const joined = rooted ? written.replace(/^!?\/+/, '') : posix.join(base, written);
+    const resolved = posix.normalize(joined).replace(/\/+$/, '');
+    if (resolved === '' || resolved === '.' || resolved === '..' || resolved.startsWith('../')) {
+        return undefined;
+    }
+    if (/[*?]/.test(resolved)) {
+        const pattern = globToRegExp(resolved);
+        return { matches: (path) => pattern.test(path) };
+    }
+    if (options.directories === true) {
+        return {
+            matches: (path) => path === resolved || path.startsWith(`${resolved}/`),
+            exact: resolved,
+        };
+    }
+    return { matches: (path) => path === resolved, exact: resolved };
+}

package/dist/src/mozbuild/references.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { jarReferences } from './jar.js';
+import { mozBuildReferences } from './mozbuild.js';
+import { manifestKind } from './paths.js';
+import { testManifestReferences } from './testManifest.js';
+/**
+ * The engine paths a manifest names, whatever its format: jar sources,
+ * moz.build list items, or the tests and support files of a test manifest.
+ * A path that is not a manifest, or an entry that names no engine path
+ * (substitution, objdir, out-of-tree), yields nothing.
+ *
+ * @param manifestPath - Engine-relative path of the manifest
+ * @param text - Manifest text, or just the lines to read
+ */
+export function manifestReferences(manifestPath, text) {
+    switch (manifestKind(manifestPath)) {
+        case 'jar':
+            return jarReferences(manifestPath, text);
+        case 'moz-build':
+            return mozBuildReferences(manifestPath, text);
+        case 'test-manifest':
+            return testManifestReferences(manifestPath, text);
+        case undefined:
+            return [];
+    }
+}
+/**
+ * Whether a manifest references an engine file: relative to the manifest's
+ * directory (`../` included), from the engine root with `/` or `!/`, by
+ * glob (`*`, `?`, `**`), or, for test-manifest support entries, as a
+ * directory that covers everything beneath it.
+ *
+ * @param manifestPath - Engine-relative path of the manifest
+ * @param text - Manifest text
+ * @param file - Engine-relative path of the file
+ */
+export function manifestReferencesFile(manifestPath, text, file) {
+    return manifestReferences(manifestPath, text).some((reference) => reference.matcher.matches(file));
+}