@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/patch-lint-module-registration.js

@@ -1,97 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Queue-wide registration lint for newly-created Firefox system modules.
- */
-import { basename } from 'node:path';
-import { escapeRegex, stripJsComments } from '../utils/regex.js';
-const IMPORTABLE_EXTENSIONS = ['.mjs', '.sys.mjs', '.js', '.jsm'];
-/**
- * Maps Firefox's common system-module resource URLs to their source
- * suffix. Exported alongside {@link extractResourceModuleSpecifiers} so
- * the resolution preflight resolves specifiers identically.
- */
-export function moduleSourceSuffix(specifier) {
-    const cleaned = specifier.split(/[?#]/)[0] ?? specifier;
-    for (const prefix of ['resource:///modules/', 'resource://gre/modules/']) {
-        if (cleaned.startsWith(prefix))
-            return `/modules/${cleaned.slice(prefix.length)}`;
-    }
-    return undefined;
-}
-/**
- * Resource-module strings in actual code (comments removed), de-duplicated.
- * Exported for the engine-aware resolution preflight, which must recognise
- * exactly the same specifier shapes this queue-level rule does. Two
- * extractors would drift.
- */
-export function extractResourceModuleSpecifiers(content) {
-    const stripped = stripJsComments(content);
-    const found = new Set();
-    const pattern = /["'](resource:\/\/(?:\/|gre\/)modules\/[^"']+\.sys\.mjs(?:[?#][^"']*)?)["']/g;
-    for (const match of stripped.matchAll(pattern)) {
-        if (match[1] !== undefined)
-            found.add(match[1]);
-    }
-    return [...found];
-}
-/** True when some patch in the projected queue adds the module to moz.build. */
-function queueRegistersModule(ctx, leaf) {
-    const escaped = escapeRegex(leaf);
-    const quotedLeaf = new RegExp(`["']${escaped}["']`);
-    for (const entry of ctx.entries) {
-        for (const [path, content] of [...entry.newFiles, ...entry.modifiedFileAdditions]) {
-            if ((path === 'moz.build' || path.endsWith('/moz.build')) && quotedLeaf.test(content)) {
-                return true;
-            }
-        }
-    }
-    return false;
-}
-/**
- * Flags a new `.sys.mjs` imported through a Firefox resource URL when the
- * projected queue never adds it to a moz.build list.
- */
-export function lintPatchQueueModuleRegistrations(ctx) {
-    const imported = new Map();
-    const collect = (entry, path, content) => {
-        if (!IMPORTABLE_EXTENSIONS.some((extension) => path.endsWith(extension)))
-            return;
-        for (const specifier of extractResourceModuleSpecifiers(content)) {
-            const suffix = moduleSourceSuffix(specifier);
-            if (suffix === undefined)
-                continue;
-            const importers = imported.get(suffix) ?? new Set();
-            importers.add(entry.filename);
-            imported.set(suffix, importers);
-        }
-    };
-    for (const entry of ctx.entries) {
-        for (const [path, content] of entry.newFiles)
-            collect(entry, path, content);
-        for (const [path, content] of entry.modifiedFileAdditions)
-            collect(entry, path, content);
-    }
-    const issues = [];
-    for (const entry of ctx.entries) {
-        for (const path of entry.newFiles.keys()) {
-            if (!path.endsWith('.sys.mjs'))
-                continue;
-            const matched = [...imported.entries()].find(([suffix]) => path.endsWith(suffix));
-            if (!matched || queueRegistersModule(ctx, basename(path)))
-                continue;
-            const [suffix, importers] = matched;
-            issues.push({
-                file: path,
-                check: 'unregistered-system-module',
-                patches: [...new Set([entry.filename, ...importers])],
-                fingerprint: `unregistered-system-module|${path}|${suffix}`,
-                message: `${path} is newly created and imported as a resource module, but no patch adds ` +
-                    `${basename(path)} to a moz.build list. Register it in EXTRA_JS_MODULES (or the ` +
-                    'appropriate namespaced list) before export; source-level typechecks can resolve the ' +
-                    'file even though the packaged browser cannot.',
-                severity: 'error',
-            });
-        }
-    }
-    return issues;
-}

package/dist/src/core/patch-lint-mozbuild.d.ts

@@ -1,18 +0,0 @@
-/**
- * Per-patch lint check for moz.build sorted-list violations.
- *
- * mozbuild enforces alphabetical ordering on `StrictOrderingOnAppendList`
- * variables and raises `mozbuild.util.UnsortedError: … expected "X" but got
- * "Y"`, but only at configure time, i.e. minutes into a `fireforge build`
- * or `fireforge test --build` dispatch. This check reads the patched
- * `moz.build` files from the engine tree (the working tree carries the
- * applied patch state, same as every other per-patch rule) and reports the
- * exact expected/got pair before any build starts.
- */
-import type { PatchLintIssue } from '../types/commands/index.js';
-/**
- * Lints the patched content of every `moz.build` file the patch touches for
- * unsorted strict-ordered lists, mirroring mozbuild's `UnsortedError`
- * report: the first index where the list diverges from its sorted copy.
- */
-export declare function lintMozBuildSortedLists(repoDir: string, affectedFiles: string[]): Promise<PatchLintIssue[]>;

package/dist/src/core/patch-lint-mozbuild.js

@@ -1,192 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Per-patch lint check for moz.build sorted-list violations.
- *
- * mozbuild enforces alphabetical ordering on `StrictOrderingOnAppendList`
- * variables and raises `mozbuild.util.UnsortedError: … expected "X" but got
- * "Y"`, but only at configure time, i.e. minutes into a `fireforge build`
- * or `fireforge test --build` dispatch. This check reads the patched
- * `moz.build` files from the engine tree (the working tree carries the
- * applied patch state, same as every other per-patch rule) and reports the
- * exact expected/got pair before any build starts.
- */
-import { join } from 'node:path';
-import { pathExists, readText } from '../utils/fs.js';
-import { mozbuildSortCompare } from './moz-manifest-helpers.js';
-/**
- * moz.build list variables mozbuild declares as `StrictOrderingOnAppendList`
- * (python/mozbuild/mozbuild/frontend/context.py). configure raises
- * `UnsortedError` on append when out of order. `DIRS` is absent on purpose:
- * directory order is meaningful and not strict-ordered. Dotted namespaces
- * (`EXTRA_JS_MODULES.<subdir>`, `EXPORTS.<ns>`) inherit strict ordering
- * from their parent variable.
- */
-const STRICT_ORDERED_MOZBUILD_LISTS = [
-    'EXTRA_COMPONENTS',
-    'EXTRA_JS_MODULES',
-    'EXTRA_PP_COMPONENTS',
-    'EXPORTS',
-    'PYTHON_UNITTEST_MANIFESTS',
-    'TESTING_JS_MODULES',
-    'XPIDL_SOURCES',
-];
-const LIST_OPENER = new RegExp(`^\\s*((?:${STRICT_ORDERED_MOZBUILD_LISTS.join('|')})(?:\\.[A-Za-z_][A-Za-z0-9_]*)*)\\s*\\+?=\\s*\\[`);
-/**
- * Strips a Python trailing comment from a moz.build line.
- *
- * `#` inside a quoted string is not a comment, so the scan tracks quote state
- * rather than using `indexOf('#')`.
- */
-/**
- * True when `line` contains a `]` outside any quoted span. A bracket inside an
- * item (`"icons[2x].png"`) is filename text, not the list's close. Reading it
- * as one truncated the item set and left every later item unchecked.
- */
-function hasUnquotedCloseBracket(line) {
-    let quote;
-    for (let i = 0; i < line.length; i++) {
-        const ch = line[i];
-        if (quote !== undefined) {
-            if (ch === '\\')
-                i += 1;
-            else if (ch === quote)
-                quote = undefined;
-        }
-        else if (ch === '"' || ch === "'") {
-            quote = ch;
-        }
-        else if (ch === ']') {
-            return true;
-        }
-    }
-    return false;
-}
-function stripMozBuildComment(line) {
-    let quote;
-    for (let i = 0; i < line.length; i++) {
-        const ch = line[i];
-        if (quote !== undefined) {
-            if (ch === '\\')
-                i += 1;
-            else if (ch === quote)
-                quote = undefined;
-        }
-        else if (ch === '"' || ch === "'") {
-            quote = ch;
-        }
-        else if (ch === '#') {
-            return line.slice(0, i);
-        }
-    }
-    return line;
-}
-/**
- * Extracts every strict-ordered list (with items in file order) from
- * moz.build content.
- *
- * Comments are stripped before both the item scan and the close-bracket
- * test, because moz.build is Python:
- *
- * - a quoted string in a trailing comment would otherwise be scraped in as a
- *   phantom list item (`"Zeta.cpp",  # replaces "Beta.cpp"` yielding a
- *   `Beta.cpp` entry), so the sort check reports an unsorted list naming a
- *   file that is not in it, with a fingerprint that can never stabilise,
- *   because the item does not exist to be moved.
- * - a `]` anywhere in a comment (`# see foo[0]`) would close the list early
- *   and silently truncate the item set.
- *
- * The scan also does not advance the caller's loop counter: an unterminated
- * list would otherwise consume the rest of the file and skip every later
- * list in it.
- *
- * Nor does an unterminated list borrow the next list's bracket. The forward
- * scan stops at the next list opener rather than reading through it.
- * Otherwise an unclosed `EXTRA_COMPONENTS` swallows the following
- * `EXTRA_JS_MODULES`, merging its items into the first list and accepting
- * its `]` as the first list's close, reporting a sorting error against a
- * variable that never contained those items.
- */
-function collectStrictOrderedLists(content) {
-    const lines = content.split('\n');
-    const occurrences = [];
-    for (let i = 0; i < lines.length; i++) {
-        const opener = LIST_OPENER.exec(lines[i] ?? '');
-        if (!opener)
-            continue;
-        const varName = opener[1] ?? '';
-        const items = [];
-        // Items may start on the opener line (`VAR += ["a", "b"]`) or span
-        // following lines until the closing bracket.
-        let rest = stripMozBuildComment((lines[i] ?? '').slice(opener[0].length));
-        let closed = false;
-        // Scan ahead on a local cursor so an unterminated list costs only itself.
-        let cursor = i;
-        for (;;) {
-            // Quote types are matched pairwise so an apostrophe inside a
-            // double-quoted item ("don't.cpp") cannot terminate the match early and
-            // scrape in a phantom item.
-            for (const quoted of rest.matchAll(/"([^"]+)"|'([^']+)'/g)) {
-                items.push(quoted[1] ?? quoted[2] ?? '');
-            }
-            if (hasUnquotedCloseBracket(rest)) {
-                closed = true;
-                break;
-            }
-            cursor += 1;
-            if (cursor >= lines.length)
-                break;
-            rest = stripMozBuildComment(lines[cursor] ?? '');
-            if (LIST_OPENER.test(rest)) {
-                // A new list starts here, so the previous one never closed. Rewind so
-                // the outer loop examines this line as its own opener.
-                cursor -= 1;
-                break;
-            }
-            if (/^\s*\]/.test(rest)) {
-                closed = true;
-                break;
-            }
-        }
-        if (closed) {
-            occurrences.push({ varName, items });
-            // Resume after the list we just consumed. A list that never closed
-            // leaves `i` untouched so the next line is still examined.
-            i = cursor;
-        }
-    }
-    return occurrences;
-}
-/**
- * Lints the patched content of every `moz.build` file the patch touches for
- * unsorted strict-ordered lists, mirroring mozbuild's `UnsortedError`
- * report: the first index where the list diverges from its sorted copy.
- */
-export async function lintMozBuildSortedLists(repoDir, affectedFiles) {
-    const issues = [];
-    for (const file of affectedFiles) {
-        if (!(file === 'moz.build' || file.endsWith('/moz.build')))
-            continue;
-        const filePath = join(repoDir, file);
-        if (!(await pathExists(filePath)))
-            continue;
-        const content = await readText(filePath);
-        for (const { varName, items } of collectStrictOrderedLists(content)) {
-            const sorted = [...items].sort(mozbuildSortCompare);
-            const divergence = items.findIndex((item, index) => item !== sorted[index]);
-            if (divergence === -1)
-                continue;
-            const expected = sorted[divergence] ?? '';
-            const got = items[divergence] ?? '';
-            issues.push({
-                file,
-                check: 'mozbuild-unsorted-list',
-                fingerprint: `mozbuild-unsorted-list|${file}|${varName}|${expected}|${got}`,
-                message: `moz.build list ${varName} is not alphabetically sorted: ` +
-                    `expected "${expected}" but got "${got}" ` +
-                    '(mozbuild will fail at configure time with UnsortedError)',
-                severity: 'error',
-            });
-        }
-    }
-    return issues;
-}

package/dist/src/core/patch-lint-observer.d.ts

@@ -1,37 +0,0 @@
-/**
- * `observer-topic-naming` rule body, extracted from `patch-lint.ts`.
- *
- * Capturing the first string literal after the call's opening paren on a
- * single line mis-attributes string literals in complex subject arguments
- * and silently skips multi-line call sites. This scans the balanced argument
- * list (across newlines, string-aware), takes the *topic* argument by
- * position, and allowlists well-known Firefox-owned topics so tests that
- * simulate upstream notifications are not pushed toward renaming real
- * topics.
- */
-import type { PatchLintIssue } from '../types/commands/index.js';
-/**
- * Firefox-owned observer topics a fork legitimately observes or simulates.
- * These must never be flagged for fork-prefix naming, even when a fork's
- * binaryName happens to be a substring of one. `quit-application*` is
- * handled as a prefix family in {@link isKnownFirefoxTopic}.
- *
- * The list is conservative: it only needs to cover topics
- * whose text could plausibly contain a fork's binaryName, plus the
- * high-traffic lifecycle topics seen in downstream test simulations.
- */
-export declare const KNOWN_FIREFOX_OBSERVER_TOPICS: ReadonlySet<string>;
-/** True for allowlisted Firefox topics, including the quit-application family. */
-export declare function isKnownFirefoxTopic(topic: string): boolean;
-/**
- * Lints observer-service call sites in `strippedContent` (comments already
- * removed) for fork topic naming. Only topics that embed `binaryName` and
- * do not follow the `<binary>-<noun>-<verb>` convention are flagged.
- * Allowlisted Firefox topics and constant-named topics are skipped.
- *
- * @param strippedContent - Source with comments stripped
- * @param file - File path for issue attribution
- * @param binaryName - Lowercased fork binary name
- * @returns Observer-topic naming issues
- */
-export declare function lintObserverTopics(strippedContent: string, file: string, binaryName: string): PatchLintIssue[];

package/dist/src/core/patch-lint-observer.js

@@ -1,167 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * `observer-topic-naming` rule body, extracted from `patch-lint.ts`.
- *
- * Capturing the first string literal after the call's opening paren on a
- * single line mis-attributes string literals in complex subject arguments
- * and silently skips multi-line call sites. This scans the balanced argument
- * list (across newlines, string-aware), takes the *topic* argument by
- * position, and allowlists well-known Firefox-owned topics so tests that
- * simulate upstream notifications are not pushed toward renaming real
- * topics.
- */
-/**
- * Firefox-owned observer topics a fork legitimately observes or simulates.
- * These must never be flagged for fork-prefix naming, even when a fork's
- * binaryName happens to be a substring of one. `quit-application*` is
- * handled as a prefix family in {@link isKnownFirefoxTopic}.
- *
- * The list is conservative: it only needs to cover topics
- * whose text could plausibly contain a fork's binaryName, plus the
- * high-traffic lifecycle topics seen in downstream test simulations.
- */
-export const KNOWN_FIREFOX_OBSERVER_TOPICS = new Set([
-    'idle-daily',
-    'profile-after-change',
-    'profile-before-change',
-    'xpcom-shutdown',
-    'xpcom-will-shutdown',
-    'final-ui-startup',
-    'browser-delayed-startup-finished',
-    'sessionstore-windows-restored',
-    'document-element-inserted',
-    'content-document-global-created',
-    'http-on-modify-request',
-    'http-on-examine-response',
-    'nsPref:changed',
-    'browser-window-before-show',
-    'domwindowopened',
-    'domwindowclosed',
-]);
-/** True for allowlisted Firefox topics, including the quit-application family. */
-export function isKnownFirefoxTopic(topic) {
-    return KNOWN_FIREFOX_OBSERVER_TOPICS.has(topic) || topic.startsWith('quit-application');
-}
-/**
- * Scans a balanced `( … )` argument span starting at `openParen` (which
- * must point at the opening paren) and splits it into top-level argument
- * strings. Tracks paren/brace/bracket depth and skips quoted runs, so
- * commas inside nested calls, object literals, or strings do not split.
- *
- * @returns The argument texts, or null when the span never closes within
- *   `maxLength` characters (malformed or truncated source, caller skips).
- */
-function extractCallArguments(content, openParen, maxLength = 2000) {
-    const args = [];
-    let current = '';
-    let depth = 0;
-    let quote = null;
-    const end = Math.min(content.length, openParen + maxLength);
-    for (let i = openParen; i < end; i++) {
-        const ch = content[i] ?? '';
-        if (quote !== null) {
-            current += ch;
-            if (ch === '\\') {
-                current += content[i + 1] ?? '';
-                i++;
-            }
-            else if (ch === quote) {
-                quote = null;
-            }
-            continue;
-        }
-        if (ch === "'" || ch === '"' || ch === '`') {
-            quote = ch;
-            current += ch;
-            continue;
-        }
-        if (ch === '(' || ch === '{' || ch === '[') {
-            depth++;
-            if (depth === 1 && ch === '(')
-                continue; // the call's own paren
-            current += ch;
-            continue;
-        }
-        if (ch === ')' || ch === '}' || ch === ']') {
-            depth--;
-            if (depth === 0 && ch === ')') {
-                args.push(current.trim());
-                return args;
-            }
-            current += ch;
-            continue;
-        }
-        if (ch === ',' && depth === 1) {
-            args.push(current.trim());
-            current = '';
-            continue;
-        }
-        current += ch;
-    }
-    return null;
-}
-/**
- * Returns the literal string value when `arg` is exactly one plain string
- * literal (no concatenation, no `${}` interpolation), otherwise null.
- * Constant-named topics (identifiers, member expressions) return null on
- * purpose: hoisting a literal into a named constant is a supported way to
- * mark a topic as deliberate.
- */
-function asStringLiteral(arg) {
-    const trimmed = arg.trim();
-    if (trimmed.length < 2)
-        return null;
-    const quoteChar = trimmed[0];
-    if (quoteChar !== "'" && quoteChar !== '"' && quoteChar !== '`')
-        return null;
-    if (trimmed[trimmed.length - 1] !== quoteChar)
-        return null;
-    const inner = trimmed.slice(1, -1);
-    if (inner.includes(quoteChar))
-        return null; // concatenation like "a" + "b"
-    if (quoteChar === '`' && inner.includes('${'))
-        return null;
-    return inner;
-}
-/**
- * Lints observer-service call sites in `strippedContent` (comments already
- * removed) for fork topic naming. Only topics that embed `binaryName` and
- * do not follow the `<binary>-<noun>-<verb>` convention are flagged.
- * Allowlisted Firefox topics and constant-named topics are skipped.
- *
- * @param strippedContent - Source with comments stripped
- * @param file - File path for issue attribution
- * @param binaryName - Lowercased fork binary name
- * @returns Observer-topic naming issues
- */
-export function lintObserverTopics(strippedContent, file, binaryName) {
-    const issues = [];
-    const callPattern = /\b(?:addObserver|removeObserver|notifyObservers)\s*\(/g;
-    let callMatch;
-    while ((callMatch = callPattern.exec(strippedContent)) !== null) {
-        const openParen = callMatch.index + callMatch[0].length - 1;
-        const args = extractCallArguments(strippedContent, openParen);
-        if (!args)
-            continue;
-        // Topic is the second argument for all three observer-service methods:
-        // addObserver(observer, topic[, weak]), removeObserver(observer, topic),
-        // notifyObservers(subject, topic[, data]).
-        const topicArg = args[1];
-        if (topicArg === undefined)
-            continue;
-        const topic = asStringLiteral(topicArg);
-        if (topic === null)
-            continue;
-        if (isKnownFirefoxTopic(topic))
-            continue;
-        if (topic.toLowerCase().includes(binaryName) && !/^[\w]+-[a-z]+-[a-z]+/.test(topic)) {
-            issues.push({
-                file,
-                check: 'observer-topic-naming',
-                message: `Observer topic "${topic}" should follow "${binaryName}-<noun>-<verb>" naming convention.`,
-                severity: 'warning',
-            });
-        }
-    }
-    return issues;
-}

package/dist/src/core/patch-lint-ownership.d.ts

@@ -1,74 +0,0 @@
-/**
- * Patch ownership resolution for JS-shaped files.
- *
- * A file is "patch-owned" when it was created by the project's patch
- * queue rather than being an upstream Firefox file that happens to be
- * modified. This module computes the set of patch-owned paths so lint
- * rules can scope enforcement to project code only.
- *
- * The two resolvers are kept separate (one per extension predicate)
- * because the downstream rules differ: `.sys.mjs` files go through
- * `runCheckJs` (TypeScript checkJs) and the export-walker JSDoc rule,
- * while chrome subscripts (`.js` non-`.sys.mjs`) only get the
- * script-walker JSDoc rule. Mixing them in a single set would silently broaden
- * `runCheckJs` to chrome subscripts, which it is not designed for.
- */
-import type { PatchQueueContext } from './patch-lint-cross.js';
-/**
- * Returns the set of file paths that are patch-owned `.sys.mjs` files.
- *
- * A file is patch-owned if:
- * 1. It is newly created in the current diff, OR
- * 2. It was created by an existing patch already in the queue.
- *
- * When no queue context is provided the result is limited to (1),
- * which matches the pre-ownership behavior and keeps callers that
- * do not have access to the patches directory working correctly.
- *
- * @param currentNewFiles - Files newly created in the current diff
- * @param patchQueueCtx - Optional cross-patch context for queue-wide ownership
- * @returns Set of patch-owned `.sys.mjs` file paths
- */
-export declare function resolvePatchOwnedSysMjs(currentNewFiles: Set<string>, patchQueueCtx?: PatchQueueContext): Set<string>;
-/**
- * Returns the set of file paths that are patch-owned chrome subscripts
- * (`.js` files that are not `.sys.mjs` modules, typically
- * `browser/base/content/<binaryName>*.js` and similar). Same ownership
- * semantics as {@link resolvePatchOwnedSysMjs}.
- *
- * @param currentNewFiles - Files newly created in the current diff
- * @param patchQueueCtx - Optional cross-patch context for queue-wide ownership
- * @returns Set of patch-owned chrome-subscript file paths
- */
-export declare function resolvePatchOwnedChromeScripts(currentNewFiles: Set<string>, patchQueueCtx?: PatchQueueContext): Set<string>;
-/**
- * Test-script predicate for the `checkJsTestFiles` pass:
- * plain `.js` files (not `.sys.mjs` modules) that live under a `/test/`
- * path or carry a `browser_` / `test_` / `xpcshell_` basename. Duplicates
- * `patch-lint.ts`'s `isTestFile` shape rather than importing it:
- * patch-lint.ts imports this module, so the reverse edge would create an
- * import cycle (dpdm gate). The agreement is pinned by
- * `patch-lint-ownership.test.ts`.
- */
-export declare function isTestScriptFile(file: string): boolean;
-/**
- * For each test script, the ES modules (`.mjs`, `.sys.mjs`) the queue
- * creates up to and including the test's own patch: what its imports can
- * resolve to in a per-test checkJs program. A test no patch touches sees
- * every module the queue creates.
- *
- * @param patchQueueCtx - The queue, in apply order
- * @returns Lookup from a test script path to its resolvable modules
- */
-export declare function resolvableModulesForTests(patchQueueCtx: PatchQueueContext): (testFile: string) => ReadonlySet<string>;
-/**
- * Returns the set of patch-owned test `.js` files. Same
- * ownership semantics as {@link resolvePatchOwnedSysMjs}. Consumed by the
- * `patchLint.checkJsTestFiles` pass, which checks each as its own small
- * script-scope program.
- *
- * @param currentNewFiles - Files newly created in the current diff
- * @param patchQueueCtx - Optional cross-patch context for queue-wide ownership
- * @returns Set of patch-owned test-script file paths
- */
-export declare function resolvePatchOwnedTestScripts(currentNewFiles: Set<string>, patchQueueCtx?: PatchQueueContext): Set<string>;