@hominis/fireforge 0.43.1 → 0.44.0

package/dist/src/core/mach-build-artifacts.d.ts

@@ -10,6 +10,13 @@ export interface BuildArtifactCheck {
     ambiguous?: boolean;
     /** All candidate obj-* directories with build artifacts */
     objDirs?: string[];
+    /**
+     * Objdir name the active mozconfig declares via `MOZ_OBJDIR`, when the
+     * candidates were ambiguous and the declaration did not resolve to exactly
+     * one of them. Carried so the refusal can say the declaration was seen and
+     * did not help — that is itself the diagnosis.
+     */
+    declaredObjDir?: string;
     /** Build metadata points at a different source or objdir */
     metadataMismatch?: {
         objDir: string;
@@ -139,15 +146,8 @@ export interface BuildArtifactPreflightOptions {
  *
  * Takes an already-probed {@link BuildArtifactCheck} rather than probing
  * itself, so it stays a pure validator: callers keep their own
- * `hasBuildArtifacts` call (which their suites already stub) and this function
- * needs no test double of its own.
- *
- * Five commands carried a character-identical copy of this ladder, including
- * the same `ambiguous && objDirs && objDirs.length > 0` expression that
- * `BuildArtifactCheck`'s boolean-plus-optionals shape forces at every reader.
- * The shape itself is unchanged — it has several producers and a documented
- * refusal contract (see the containment predicates below) — but it is now
- * destructured in exactly one place.
+ * `hasBuildArtifacts` call (which their suites already stub) and this
+ * function needs no test double of its own.
  */
 export declare function assertBuildArtifacts(engineDir: string, buildCheck: BuildArtifactCheck, options: BuildArtifactPreflightOptions): void;
 /**

package/dist/src/core/mach-build-artifacts.js

@@ -8,6 +8,7 @@ import { pathExists, readJson, readText, writeJson } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { getPlatform } from '../utils/platform.js';
 import { isObject, isString } from '../utils/validation.js';
+import { extractMozObjdirName } from './mach-mozconfig.js';
 function validateBuildMozinfo(data) {
     if (!isObject(data)) {
         throw new Error('mozinfo metadata must be an object');
@@ -33,6 +34,26 @@ function validateBuildMozinfo(data) {
     }
     return mozinfo;
 }
+/**
+ * Reads the objdir name the engine's mozconfig declares, or undefined when
+ * there is no mozconfig, it cannot be read, or it declares nothing.
+ *
+ * Fail-open by construction: this only ever narrows an ambiguity that would
+ * otherwise refuse, so an unreadable mozconfig costs nothing beyond the
+ * refusal the caller was already going to raise.
+ */
+async function readDeclaredObjDirName(engineDir) {
+    try {
+        const mozconfigPath = join(engineDir, 'mozconfig');
+        if (!(await pathExists(mozconfigPath)))
+            return undefined;
+        return extractMozObjdirName(await readText(mozconfigPath));
+    }
+    catch (error) {
+        verbose(`Could not read mozconfig for MOZ_OBJDIR: ${toError(error).message}`);
+        return undefined;
+    }
+}
 /**
  * Checks if build artifacts exist in the engine directory.
  * Looks for obj-* directories with a dist subdirectory. Detection is
@@ -61,10 +82,33 @@ export async function hasBuildArtifacts(engineDir) {
             const firstObjDir = objDirs[0];
             return firstObjDir ? { exists: false, objDir: firstObjDir } : { exists: false };
         }
+        let resolvedObjDirs = validObjDirs;
+        let declaredObjDir;
         if (validObjDirs.length > 1) {
-            return { exists: true, ambiguous: true, objDirs: validObjDirs };
+            // An ambiguous glob is a question the mozconfig may already answer.
+            // Refusing when the active configuration NAMES the objdir sends the
+            // operator to rename a directory to satisfy a scan, when the thing
+            // that decides the build has said which one it is. The refusal is
+            // kept for the genuinely ambiguous case: a declaration that does not
+            // resolve to exactly one candidate selects nothing.
+            declaredObjDir = await readDeclaredObjDirName(engineDir);
+            const declaredMatches = declaredObjDir === undefined
+                ? []
+                : validObjDirs.filter((candidate) => candidate === declaredObjDir);
+            if (declaredMatches.length === 1) {
+                verbose(`Objdir ambiguity resolved by mozconfig MOZ_OBJDIR: ${declaredMatches[0] ?? ''}.`);
+                resolvedObjDirs = declaredMatches;
+            }
+            else {
+                return {
+                    exists: true,
+                    ambiguous: true,
+                    objDirs: validObjDirs,
+                    ...(declaredObjDir !== undefined ? { declaredObjDir } : {}),
+                };
+            }
         }
-        const selectedObjDir = validObjDirs[0];
+        const selectedObjDir = resolvedObjDirs[0];
         if (!selectedObjDir) {
             return { exists: false };
         }
@@ -301,19 +345,12 @@ export async function attemptMozinfoRewrite(engineDir, objDir) {
  *
  * Takes an already-probed {@link BuildArtifactCheck} rather than probing
  * itself, so it stays a pure validator: callers keep their own
- * `hasBuildArtifacts` call (which their suites already stub) and this function
- * needs no test double of its own.
- *
- * Five commands carried a character-identical copy of this ladder, including
- * the same `ambiguous && objDirs && objDirs.length > 0` expression that
- * `BuildArtifactCheck`'s boolean-plus-optionals shape forces at every reader.
- * The shape itself is unchanged — it has several producers and a documented
- * refusal contract (see the containment predicates below) — but it is now
- * destructured in exactly one place.
+ * `hasBuildArtifacts` call (which their suites already stub) and this
+ * function needs no test double of its own.
  */
 export function assertBuildArtifacts(engineDir, buildCheck, options) {
     if (buildCheck.ambiguous && buildCheck.objDirs && buildCheck.objDirs.length > 0) {
-        throw new AmbiguousBuildArtifactsError(buildCheck.objDirs);
+        throw new AmbiguousBuildArtifactsError(buildCheck.objDirs, buildCheck.declaredObjDir);
     }
     const mismatchMessage = buildArtifactMismatchMessage(engineDir, buildCheck, options.label);
     if (mismatchMessage) {
@@ -366,13 +403,14 @@ export async function findObjdirRelocationViolation(args) {
     if (actualObjDir !== expectedObjDir) {
         return `${objDir}/mozinfo.json topobjdir resolves to ${actualObjDir ?? '(absent)'}, expected ${expectedObjDir}`;
     }
-    // The canonical no-primary-paths assertion (mirrors the opt-in real-mach
-    // proof in scripts/run-full-firefox-integration.mjs): substring search on
-    // the resolved primary engine dir is collision-safe against the tree's own
-    // paths — `<primary>/.fireforge/trees/<name>/engine` never contains the
-    // substring `<primary>/engine`. Scans exactly the configure-generated
-    // root files; `config.status` is mandatory (checked above), the rest are
-    // optional-if-absent because not every configure backend writes them.
+    // The canonical no-primary-paths assertion (mirrored by the opt-in
+    // real-mach proof in scripts/run-full-firefox-integration.mjs): substring
+    // search on the resolved primary engine dir is collision-safe against the
+    // tree's own paths — `<primary>/.fireforge/trees/<name>/engine` never
+    // contains the substring `<primary>/engine`. Scans exactly the
+    // configure-generated root files; `config.status` is mandatory (checked
+    // above), the rest are optional-if-absent because not every configure
+    // backend writes them.
     const forbidden = resolve(forbiddenDir);
     for (const name of ['config.status', 'backend.mk', 'Makefile', 'config/autoconf.mk']) {
         const filePath = join(objDirPath, ...name.split('/'));

package/dist/src/core/mach-error-hints.js

@@ -19,14 +19,33 @@ export const MACH_ERROR_HINTS = [
         hint: 'A file registered under JS_PREFERENCE_PP_FILES contains no preprocessor directives. ' +
             'Use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.',
     },
+    {
+        // mozbuild raises `UnsortedError` while READING a moz.build whose
+        // StrictOrderingOnAppendList entries are out of order, so `mach
+        // configure` dies before anything compiles. The ordering rule is the
+        // part operators get wrong: mozbuild sorts by `.lower()`
+        // (`StrictOrderingOnAppendList.ensure_sorted`), so an uppercase letter
+        // does NOT sort ahead of a lowercase one, and an entry that looks
+        // correctly placed by byte order can be rejected. mozbuild's own
+        // message names both entries ("We expected X but got Y") and survives
+        // to the operator through `extractMachConfigureError`, so the hint
+        // supplies only the rule and the remedy.
+        pattern: /mozbuild\.util\.UnsortedError|\bUnsortedError\b/,
+        hint: 'A moz.build list is out of order — mozbuild rejects the file while reading it, so ' +
+            'configure dies before any compile. The entries are compared CASE-INSENSITIVELY ' +
+            '(mozbuild lowercases before comparing), so uppercase does not sort before lowercase: ' +
+            '"HominisEditorFilePaths.sys.mjs" belongs BEFORE "HominisEditorFiles.sys.mjs" ' +
+            '("filep" < "files"). The mozbuild error above names the file and both entries — move ' +
+            'the entry to the position it names. "fireforge lint --per-patch" checks this ' +
+            '(mozbuild-unsorted-list) before a build, which is the cheaper place to catch it.',
+    },
     {
         // `mach package` inside `packager.py` dereferences a `None` sink when
-        // the packaging input set cannot resolve an entry it expected — the
-        // most common real-world cause is running `fireforge package` before
-        // a full `fireforge build` has finished, so `obj-*/dist/` is missing
-        // pieces the packager assumes exist. The hint points at that root
-        // cause specifically; the broader "build failed" path has already
-        // surfaced the raw traceback above this hint.
+        // the packaging input set cannot resolve an entry it expected — most
+        // commonly running `fireforge package` before a full `fireforge build`
+        // has finished, so `obj-*/dist/` is missing pieces the packager assumes
+        // exist. The broader "build failed" path has already surfaced the raw
+        // traceback above this hint.
         pattern: /packager\.py[\s\S]*?AttributeError: 'NoneType' object has no attribute 'open'|AttributeError: 'NoneType' object has no attribute 'open'[\s\S]*?packager\.py/,
         hint: '`mach package` tripped a `NoneType.open` inside `packager.py`. This is almost always a ' +
             'symptom of the packager being handed an incomplete `obj-*/dist/` tree — e.g. running ' +
@@ -37,14 +56,12 @@ export const MACH_ERROR_HINTS = [
     {
         // Upstream bindgen on some macOS libc++ SDK versions emits
         // `pub type basic_string___self_view = root::std::__1::basic_string_view<_CharT>;`
-        // inside gecko-profiler's generated `bindings.rs`, but `_CharT` is
-        // not in scope where the alias lands — so the Rust compile fails
-        // with "cannot find type `_CharT`". The symptom is obscure and the
-        // fix is external: a downstream consumer's patch queue may ship
-        // `990-infra-bindgen-basic-string-workaround.patch`, which strips
-        // the offending alias line post-generation. This hint surfaces the
-        // workaround pointer alongside the raw bindgen output so operators
-        // don't have to reverse-engineer the failure.
+        // inside gecko-profiler's generated `bindings.rs`, but `_CharT` is not
+        // in scope where the alias lands, so the Rust compile fails with
+        // "cannot find type `_CharT`". The fix is external: a consumer's patch
+        // queue may ship a workaround patch that strips the offending alias line
+        // post-generation. This hint surfaces that pointer alongside the raw
+        // bindgen output.
         pattern: /cannot find type `_CharT` in this scope[\s\S]*?gecko-profiler-|gecko-profiler-[\s\S]*?cannot find type `_CharT` in this scope/,
         hint: 'The Rust compile failed on a bindgen-generated `basic_string___self_view` alias in ' +
             'gecko-profiler/bindings.rs. This is an upstream bindgen output bug against some ' +
@@ -59,13 +76,12 @@ export const MACH_ERROR_HINTS = [
     {
         // Firefox declares per-release toolchain minimums in-tree
         // (`build/moz.configure/bindgen.configure` for cbindgen; mozboot's
-        // MINIMUM_RUST_VERSION for rustc/cargo), and a source hop can move
-        // them. The 152.0b7 → 153.0b8 source-refresh drill hit exactly this:
-        // the first post-hop build died ~8s into `mach configure` with
-        // "ERROR: cbindgen version 0.29.1 is too old. At least version
-        // 0.29.4 is required." — and mach's own remediation text names
-        // "./mach bootstrap", the wrong entry point for a FireForge-managed
-        // repo. Pattern matches configure's cbindgen die() shape.
+        // MINIMUM_RUST_VERSION for rustc/cargo), and a source hop can move them.
+        // The failure lands ~8s into `mach configure` — e.g. "ERROR: cbindgen
+        // version 0.29.1 is too old. At least version 0.29.4 is required." —
+        // and mach's own remediation text names "./mach bootstrap", the wrong
+        // entry point for a FireForge-managed repo. Pattern matches configure's
+        // cbindgen die() shape.
         pattern: /\bversion [\d.]+ is too old\.?\s+At least version [\d.]+ is required/i,
         hint: 'A toolchain component is older than the minimum this Firefox source declares — typical ' +
             'after "fireforge download --force" moved the engine to a new Firefox major version. ' +
@@ -84,16 +100,13 @@ export const MACH_ERROR_HINTS = [
             'the build.',
     },
     {
-        // When `mach build` fails mid-compile, mach's own shutdown pipeline still
-        // runs its trailing "Config object not found by mach. / Configure
+        // When `mach build` fails mid-compile, mach's own shutdown pipeline
+        // still runs its trailing "Config object not found by mach. / Configure
         // complete! / Be sure to run |mach build|..." summary on the way out.
         // Those three lines are plain upstream mach output, printed AFTER the
-        // non-zero exit code has already been established, and they look
-        // deceptively like a success banner — the eval's Darwin 25 log had
-        // operators double-checking whether `make` had actually failed. We do
-        // not own those lines, but we can give the operator a specific nudge
-        // that they are cosmetic post-failure output rather than a mixed
-        // success/failure signal.
+        // non-zero exit code is established, and they read deceptively like a
+        // success banner. Nudge the operator that they are cosmetic
+        // post-failure output, not a mixed success/failure signal.
         pattern: /Config object not found by mach\.[\s\S]*?Configure complete!/,
         hint: 'Ignore the trailing "Config object not found by mach. / Configure complete!" block — ' +
             "that is mach's post-failure configure summary printed after the build already failed, " +

package/dist/src/core/mach-known-noise-filter.d.ts

@@ -1,29 +1,28 @@
 /**
- * Terminal-echo filter for the KNOWN upstream mozsystemmonitor teardown
- * traceback (0.37.0 item 8).
+ * Terminal-echo filter for the known upstream mozsystemmonitor teardown
+ * traceback.
  *
- * Every headless test run against the 153-beta engine ends with an
+ * Headless test runs against recent engines can end with an
  * `AttributeError: 'SystemResourceMonitor' object has no attribute
  * 'stop_time'` traceback at harness teardown — upstream noise that sits
- * exactly where a reader looks for the failure summary. 0.36.0 already made
- * real failure lines beat this traceback in CLASSIFICATION; this filter
- * closes the PRESENTATION gap by collapsing the echoed traceback to one
- * labeled line.
+ * exactly where a reader looks for the failure summary. Real failure lines
+ * already beat this traceback in CLASSIFICATION; this filter closes the
+ * PRESENTATION gap by collapsing the echoed traceback to one labeled line.
  *
  * Scope is deliberately narrow:
  *   - Only the terminal ECHO is filtered. The captured stdout/stderr strings
- *     stay raw — the classifier (`test-harness-crash.ts`) depends on the
- *     raw traceback for its green-summary override and secondary-noise
+ *     stay raw — the classifier (`test-harness-crash.ts`) depends on the raw
+ *     traceback for its green-summary override and secondary-noise
  *     detection.
  *   - Only the exact documented incident is collapsed, and every condition
  *     must hold: an `AttributeError` on `SystemResourceMonitor` naming one
- *     of the two known attributes (`stop_time`, `poll_interval` — the
- *     0.34.0 guard family), AND a `mozsystemmonitor/resourcemonitor.py`
- *     stack frame, AND a previously-seen SUITE_END shutdown marker (shared
- *     across the run's stdout/stderr filter instances — the marker usually
- *     lands on stdout while the traceback lands on stderr). A novel
- *     attribute, a novel exception type in resourcemonitor.py, or a
- *     pre-shutdown occurrence is echoed verbatim, always.
+ *     of the two known attributes (`stop_time`, `poll_interval`), AND a
+ *     `mozsystemmonitor/resourcemonitor.py` stack frame, AND a
+ *     previously-seen SUITE_END shutdown marker (shared across the run's
+ *     stdout/stderr filter instances — the marker usually lands on stdout
+ *     while the traceback lands on stderr). A novel attribute, a novel
+ *     exception type in resourcemonitor.py, or a pre-shutdown occurrence is
+ *     echoed verbatim, always.
  *   - The hold buffer is bounded; on overflow the block is flushed verbatim
  *     and the filter returns to pass-through, so output is never lost.
  */

package/dist/src/core/mach-known-noise-filter.js

@@ -1,30 +1,29 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Terminal-echo filter for the KNOWN upstream mozsystemmonitor teardown
- * traceback (0.37.0 item 8).
+ * Terminal-echo filter for the known upstream mozsystemmonitor teardown
+ * traceback.
  *
- * Every headless test run against the 153-beta engine ends with an
+ * Headless test runs against recent engines can end with an
  * `AttributeError: 'SystemResourceMonitor' object has no attribute
  * 'stop_time'` traceback at harness teardown — upstream noise that sits
- * exactly where a reader looks for the failure summary. 0.36.0 already made
- * real failure lines beat this traceback in CLASSIFICATION; this filter
- * closes the PRESENTATION gap by collapsing the echoed traceback to one
- * labeled line.
+ * exactly where a reader looks for the failure summary. Real failure lines
+ * already beat this traceback in CLASSIFICATION; this filter closes the
+ * PRESENTATION gap by collapsing the echoed traceback to one labeled line.
  *
  * Scope is deliberately narrow:
  *   - Only the terminal ECHO is filtered. The captured stdout/stderr strings
- *     stay raw — the classifier (`test-harness-crash.ts`) depends on the
- *     raw traceback for its green-summary override and secondary-noise
+ *     stay raw — the classifier (`test-harness-crash.ts`) depends on the raw
+ *     traceback for its green-summary override and secondary-noise
  *     detection.
  *   - Only the exact documented incident is collapsed, and every condition
  *     must hold: an `AttributeError` on `SystemResourceMonitor` naming one
- *     of the two known attributes (`stop_time`, `poll_interval` — the
- *     0.34.0 guard family), AND a `mozsystemmonitor/resourcemonitor.py`
- *     stack frame, AND a previously-seen SUITE_END shutdown marker (shared
- *     across the run's stdout/stderr filter instances — the marker usually
- *     lands on stdout while the traceback lands on stderr). A novel
- *     attribute, a novel exception type in resourcemonitor.py, or a
- *     pre-shutdown occurrence is echoed verbatim, always.
+ *     of the two known attributes (`stop_time`, `poll_interval`), AND a
+ *     `mozsystemmonitor/resourcemonitor.py` stack frame, AND a
+ *     previously-seen SUITE_END shutdown marker (shared across the run's
+ *     stdout/stderr filter instances — the marker usually lands on stdout
+ *     while the traceback lands on stderr). A novel attribute, a novel
+ *     exception type in resourcemonitor.py, or a pre-shutdown occurrence is
+ *     echoed verbatim, always.
  *   - The hold buffer is bounded; on overflow the block is flushed verbatim
  *     and the filter returns to pass-through, so output is never lost.
  */
@@ -32,10 +31,9 @@ const TRACEBACK_HEADER_PATTERN = /^Traceback \(most recent call last\)/;
 const CHAINED_EXCEPTION_CONNECTOR_PATTERN = /^(?:During handling of the above exception, another exception occurred:|The above exception was the direct cause of the following exception:)\s*$/;
 /**
  * Closed allowlist of the documented teardown family's attributes:
- * `stop_time` (the 0.37.0 item-8 incident) and `poll_interval` (the same
- * mozsystemmonitor init failure the 0.34.0 resource-guard family covers —
- * `test-harness-crash.ts` already classifies it as recognized noise). Any
- * other missing attribute is a NEW upstream defect and must print verbatim.
+ * `stop_time` and `poll_interval` (the same mozsystemmonitor init failure
+ * `test-harness-crash.ts` already classifies as recognized noise). Any other
+ * missing attribute is a NEW upstream defect and must print verbatim.
  */
 const KNOWN_TEARDOWN_ATTRIBUTE_ERROR_PATTERN = /AttributeError: 'SystemResourceMonitor' object has no attribute '(?:stop_time|poll_interval)'/;
 const RESOURCEMONITOR_FRAME_PATTERN = /mozsystemmonitor[/\\]resourcemonitor\.py/;

package/dist/src/core/mach-mozconfig.d.ts

@@ -17,6 +17,20 @@ export interface MozconfigVariables {
  * Exported for testing.
  */
 export declare function extractWithBrandingPath(mozconfigContent: string): string | undefined;
+/**
+ * Extracts the objdir NAME a mozconfig declares — the single trailing path
+ * segment, which is what the `obj-*` scan enumerates.
+ *
+ * `@TOPSRCDIR@` and a leading `./` are both spellings of "beside the
+ * source", which is the only arrangement FireForge's scan can see anyway;
+ * an absolute path outside the engine directory reduces to its basename and
+ * simply will not match a candidate, which is the correct outcome — a
+ * declaration that names something the scan cannot see must not select
+ * anything.
+ *
+ * Returns undefined when nothing is declared. Exported for testing.
+ */
+export declare function extractMozObjdirName(mozconfigContent: string): string | undefined;
 /**
  * Preflights the just-written mozconfig against the branding tree FireForge
  * set up. A drift between the two is silent-corruption territory — the

package/dist/src/core/mach-mozconfig.js

@@ -41,6 +41,36 @@ export function extractWithBrandingPath(mozconfigContent) {
     const last = matches.at(-1);
     return last?.[1];
 }
+/**
+ * Matches a `MOZ_OBJDIR=<path>` declaration in a mozconfig. Both spellings
+ * mach honours are accepted (`mk_add_options MOZ_OBJDIR=…`, the documented
+ * one, and a bare `export MOZ_OBJDIR=…`), and the value may be quoted.
+ * Last-write-wins for the same reason as {@link WITH_BRANDING_PATTERN}: a
+ * mozconfig is shell.
+ */
+const MOZ_OBJDIR_PATTERN = /^\s*(?:mk_add_options\s+|export\s+)?MOZ_OBJDIR\s*=\s*["']?([^"'\s#]+)/gm;
+/**
+ * Extracts the objdir NAME a mozconfig declares — the single trailing path
+ * segment, which is what the `obj-*` scan enumerates.
+ *
+ * `@TOPSRCDIR@` and a leading `./` are both spellings of "beside the
+ * source", which is the only arrangement FireForge's scan can see anyway;
+ * an absolute path outside the engine directory reduces to its basename and
+ * simply will not match a candidate, which is the correct outcome — a
+ * declaration that names something the scan cannot see must not select
+ * anything.
+ *
+ * Returns undefined when nothing is declared. Exported for testing.
+ */
+export function extractMozObjdirName(mozconfigContent) {
+    const matches = [...mozconfigContent.matchAll(MOZ_OBJDIR_PATTERN)];
+    const raw = matches.at(-1)?.[1];
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.replace(/\/+$/, '');
+    const segment = trimmed.split('/').at(-1);
+    return segment !== undefined && segment.length > 0 ? segment : undefined;
+}
 /**
  * Preflights the just-written mozconfig against the branding tree FireForge
  * set up. A drift between the two is silent-corruption territory — the