@hominis/fireforge 0.15.5 → 0.15.7

package/dist/src/core/build-audit.js

@@ -39,7 +39,9 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
 import { detectPlatformGate } from './build-audit-platform.js';
-import { isTestPath, resolveBestArtifact } from './build-audit-resolve.js';
+import { collectSameBasenameCandidates, findRegisteredTarget, resolveArtifactByRegistration, } from './build-audit-registration.js';
+import { countTrailingSegmentMatches, isTestPath, resolveBestArtifact, } from './build-audit-resolve.js';
+import { resolveArtifactByKnownTransform } from './build-audit-transforms.js';
 import { hasChanges, isMissingHeadError } from './git.js';
 import { git } from './git-base.js';
 import { getUntrackedFiles } from './git-status.js';
@@ -190,6 +192,27 @@ async function resolveTestsRoot(engineDir) {
     }
     return undefined;
 }
+/**
+ * Marker file the `package-tests` make target writes after copying the
+ * full test-source tree under `_tests/`. Its presence is the most reliable
+ * signal that test packaging has actually run for the current obj-dir —
+ * plain `mach build` populates a partial `_tests/` subtree and then stops,
+ * so registered tests are absent even when registration is correct.
+ */
+const PACKAGED_TESTS_MARKER = 'all-tests.json';
+/**
+ * Returns true when the full test-package step has actually run for the
+ * active obj-dir. Without this marker the `_tests/` walk produces false
+ * positives for every correctly-registered mochitest / xpcshell source
+ * on the common "built but tests not packaged" path.
+ *
+ * @param testsRoot Absolute path to the obj-*`/_tests/` tree, or undefined.
+ */
+async function hasPackagedTestsMarker(testsRoot) {
+    if (!testsRoot)
+        return false;
+    return pathExists(join(testsRoot, PACKAGED_TESTS_MARKER));
+}
 /**
  * Resolves the search roots an individual source path should be looked
  * up under. Test-shaped paths get `_tests/`; everything else gets `dist/`.
@@ -200,6 +223,68 @@ function searchRootsFor(source, distRoot, testsRoot) {
     }
     return [distRoot];
 }
+/**
+ * Minimum trailing-segment overlap required for a same-basename dist/
+ * candidate to count as "the packaged artifact" of a source. The
+ * basename always trail-matches (count 1), so a threshold of 2 requires
+ * the immediate parent directory to also agree. Candidates that only
+ * share the basename are classified as missing — warning the operator
+ * to check registration — rather than emitting a misleading stale
+ * comparison against an unrelated file of the same name.
+ *
+ * Cross-tree re-rooting cases (e.g. `branding/<name>/content/foo.css`
+ * landing at `chrome/<area>/content/branding/foo.css`) bypass this
+ * floor because `scoreCandidate` awards a non-generic-segment bonus
+ * that lifts the confidence regardless of trailing overlap; those are
+ * detected below in `isConfidentMatch`.
+ */
+const MIN_TRAILING_SEGMENT_OVERLAP = 2;
+/**
+ * Returns true when the chosen artifact is structurally related to the
+ * source path — either its immediate parent directory trail-matches, or
+ * a non-generic intermediate source segment appears in the candidate
+ * path (the branding-re-root signal already used by the scorer).
+ *
+ * Used to avoid emitting `stale` warnings that point at an unrelated
+ * same-basename file picked up by the basename walker — a class of
+ * warning that is worse than `missing` because it reads as "your build
+ * dropped this file" when in fact the match is spurious.
+ */
+function isConfidentMatch(source, candidate) {
+    if (countTrailingSegmentMatches(source, candidate) >= MIN_TRAILING_SEGMENT_OVERLAP) {
+        return true;
+    }
+    const sourceSegs = source.split('/').filter(Boolean);
+    const candSegs = candidate.split('/').filter(Boolean);
+    const generic = new Set([
+        'content',
+        'chrome',
+        'bin',
+        'browser',
+        'toolkit',
+        'modules',
+        'base',
+        'app',
+        'profile',
+        'shared',
+        'themes',
+        'test',
+        'tests',
+        'unit',
+        'common',
+        'xpcshell',
+        'mochitest',
+    ]);
+    // Skip the basename itself (which trail-matches by definition).
+    for (let i = 0; i < sourceSegs.length - 1; i += 1) {
+        const seg = sourceSegs[i];
+        if (!seg || seg.length <= 2 || generic.has(seg))
+            continue;
+        if (candSegs.includes(seg))
+            return true;
+    }
+    return false;
+}
 /**
  * Audits one engine source path and returns its entry. Pure orchestration
  * helper kept separate so `auditBuildArtifacts` stays under the per-function
@@ -211,7 +296,16 @@ async function auditSinglePath(source, ctx) {
     }
     const gate = await detectPlatformGate(ctx.engineDir, source);
     if (gate.gatedOff) {
-        verbose(`Audit: skipping engine/${source} — gated off by moz.build "${gate.gateExpression ?? '?'}".`);
+        verbose(`Audit: skipping engine/${source} — gated off by "${gate.gateExpression ?? '?'}".`);
+        return { source, artifact: undefined, status: 'skipped' };
+    }
+    // Tests only end up under `_tests/` after `mach package-tests` (or a
+    // test-run that invokes the target) has executed. A plain `mach build`
+    // populates a partial subtree and stops, so every correctly-registered
+    // mochitest / xpcshell source appears "missing" on that common path.
+    // Skip audit for test sources when no packaged-tests marker is present.
+    if (isTestPath(source) && !ctx.testsPackaged) {
+        verbose(`Audit: skipping engine/${source} — _tests/${PACKAGED_TESTS_MARKER} not present; full test packaging has not run for this build.`);
         return { source, artifact: undefined, status: 'skipped' };
     }
     const sourcePath = join(ctx.engineDir, source);
@@ -225,6 +319,40 @@ async function auditSinglePath(source, ctx) {
         return { source, artifact: undefined, status: 'skipped' };
     }
     const roots = searchRootsFor(source, ctx.distRoot, ctx.testsRoot);
+    // Registration-aware resolution first: a `jar.mn` entry whose `(source)`
+    // references this file is authoritative over the basename-similarity
+    // heuristic. The motivating case is a fork that adds `content/foo.js`
+    // in `browser/base/jar.mn` while an unrelated patch registers a pref
+    // file of the same basename elsewhere — the heuristic cannot
+    // distinguish them, so the audit falsely reports "missing" against the
+    // correctly-packaged file.
+    const registered = await resolveArtifactByRegistration(ctx.engineDir, source, roots);
+    if (registered) {
+        return evaluateArtifactMtime(source, registered.artifact, sourceMtime, { registered: true });
+    }
+    // Registration exists but no matching dist entry: explicit miss,
+    // distinct from an unregistered source. This surfaces in the warning so
+    // the operator knows the jar.mn entry is intact and packaging is the
+    // bug, not the source registration.
+    const registrationMissed = await reportRegistrationMiss(ctx.engineDir, source, roots);
+    if (registrationMissed)
+        return registrationMissed;
+    // Known-transform resolution comes before the similarity heuristic so a
+    // source under `browser/base/content/` (or another prefix whose chrome
+    // target is stable across forks) is matched against its expected
+    // `chrome/...` suffix rather than whichever same-basename candidate the
+    // directory walk happened to hit first. Motivating case: a source at
+    // `engine/browser/base/content/foo.js` whose correctly-packaged artifact
+    // lives at `chrome/browser/content/browser/foo.js` but which an unrelated
+    // patch also placed under `browser/defaults/preferences/foo.js`; every
+    // intermediate segment of the source is in the scorer's generic list,
+    // so `resolveBestArtifact` picks whichever hit first and `isConfidentMatch`
+    // rejects every candidate, classifying the correctly-packaged file as
+    // "missing" even though packaging had landed it.
+    const byTransform = await resolveArtifactByKnownTransform(source, roots);
+    if (byTransform) {
+        return evaluateArtifactMtime(source, byTransform, sourceMtime, { registered: true });
+    }
     const artifact = await resolveBestArtifact(source, roots);
     if (!artifact) {
         const where = isTestPath(source) ? '_tests/' : 'dist/';
@@ -235,6 +363,42 @@ async function auditSinglePath(source, ctx) {
             warning: `Audit: engine/${source} was touched but no packaged artifact with basename "${basename(source)}" was found under ${where}. Missing moz.build / jar.mn / package-manifest.in registration?`,
         };
     }
+    return evaluateArtifactMtime(source, artifact, sourceMtime, { registered: false, roots });
+}
+/**
+ * Short-circuits the audit for sources that are registered in a jar.mn
+ * but whose target path is absent from every search root. Returns the
+ * miss entry when the registration lookup saw a `(source)` claim but
+ * no dist candidate endswith the target; undefined otherwise.
+ */
+async function reportRegistrationMiss(engineDir, source, roots) {
+    const hit = await findRegisteredTarget(engineDir, source);
+    if (!hit)
+        return undefined;
+    const where = isTestPath(source) ? '_tests/' : 'dist/';
+    // Name every same-basename hit so the operator sees what did land in
+    // dist, rather than guessing from a single "nearest" pick.
+    const candidates = await collectSameBasenameCandidates(source, roots);
+    const nearHits = describeCandidates(candidates);
+    const manifest = relativeManifestPath(engineDir, hit.jarManifest);
+    return {
+        source,
+        artifact: undefined,
+        status: 'missing',
+        warning: `Audit: engine/${source} is registered in ${manifest} as ` +
+            `"${hit.target}  (${hit.source})" but no packaged artifact ending in "/${hit.target}" ` +
+            `was found under ${where}. Build reported success but the file's path did not ` +
+            `flow through packaging${nearHits ? ` — same-basename hits: ${nearHits}` : ''}.`,
+    };
+}
+/**
+ * Renders packaged-artifact mtime classification (updated / stale / missing-
+ * via-disappearance) for a resolved candidate. Shared by the registration-
+ * anchored path (confident by construction) and the heuristic fallback
+ * (which still applies the structural-relatedness check before claiming
+ * `stale`).
+ */
+async function evaluateArtifactMtime(source, artifact, sourceMtime, mode) {
     let artifactMtime;
     try {
         const artifactStat = await stat(artifact);
@@ -249,6 +413,20 @@ async function auditSinglePath(source, ctx) {
         };
     }
     if (artifactMtime + 1 < sourceMtime) {
+        if (!mode.registered && !isConfidentMatch(source, artifact)) {
+            const where = isTestPath(source) ? '_tests/' : 'dist/';
+            const candidates = await collectSameBasenameCandidates(source, mode.roots);
+            const nearHits = describeCandidates(candidates);
+            return {
+                source,
+                artifact: undefined,
+                status: 'missing',
+                warning: `Audit: engine/${source} was touched but no related packaged artifact with ` +
+                    `basename "${basename(source)}" was found under ${where}` +
+                    (nearHits ? `. Same-basename hits in unrelated subtrees: ${nearHits}` : '') +
+                    `. Missing moz.build / jar.mn / package-manifest.in registration?`,
+            };
+        }
         return {
             source,
             artifact,
@@ -258,6 +436,34 @@ async function auditSinglePath(source, ctx) {
     }
     return { source, artifact, status: 'updated' };
 }
+/** Cap on candidate list rendering before truncating with `(+N more)`. */
+const CANDIDATE_LIST_LIMIT = 5;
+/**
+ * Renders a comma-separated list of same-basename hits for inclusion in a
+ * warning, truncated at {@link CANDIDATE_LIST_LIMIT} with a `(+N more)`
+ * tail. Returns the empty string when no candidates are supplied so
+ * callers can omit the parenthetical entirely rather than render a stub.
+ */
+function describeCandidates(candidates) {
+    if (candidates.length === 0)
+        return '';
+    const head = candidates.slice(0, CANDIDATE_LIST_LIMIT).join(', ');
+    if (candidates.length <= CANDIDATE_LIST_LIMIT)
+        return head;
+    return `${head}, … (+${candidates.length - CANDIDATE_LIST_LIMIT} more)`;
+}
+/**
+ * Formats a manifest path relative to the engine root when it lives
+ * underneath, falling back to the absolute path otherwise. Keeps warning
+ * text short and anchored to `engine/…` when the manifest is in-tree.
+ */
+function relativeManifestPath(engineDir, manifest) {
+    const root = engineDir.replace(/[/\\]+$/, '');
+    if (manifest.startsWith(`${root}/`)) {
+        return `engine/${manifest.slice(root.length + 1)}`;
+    }
+    return manifest;
+}
 /**
  * Runs the post-build audit. Emits per-file warnings for missing or
  * stale artifacts and a summary info line at the end. Always returns
@@ -283,11 +489,12 @@ export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
         return summary;
     }
     const testsRoot = await resolveTestsRoot(engineDir);
+    const testsPackaged = await hasPackagedTestsMarker(testsRoot);
     const changed = await collectChangedFiles(engineDir, baseline);
     if (changed.length === 0) {
         return summary;
     }
-    const ctx = { engineDir, distRoot, testsRoot };
+    const ctx = { engineDir, distRoot, testsRoot, testsPackaged };
     for (const source of changed) {
         const result = await auditSinglePath(source, ctx);
         summary[result.status] += 1;

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

@@ -35,10 +35,12 @@ export declare function validateJarMnEntries(root: string, config: FurnaceConfig
  * linked in at least one chrome host document. Without the link, tokens
  * silently resolve to nothing at runtime.
  *
- * Forks with multiple chrome host documents (e.g. `mybrowser.xhtml` beside
- * `browser.xhtml`) can enumerate them via `tokenHostDocuments` in
- * furnace.json; the warning fires only when NONE of the configured
- * documents link the tokens CSS.
+ * Scan set is the union of (a) the configured `tokenHostDocuments` (or
+ * the upstream default when unset) and (b) any `browser/base/content/*.xhtml`
+ * document that references `tagName` — the auto-detection path catches
+ * forks that mount components from a replacement chrome document without
+ * having configured `tokenHostDocuments`. The warning fires only when
+ * NONE of the documents in the final scan set link the tokens CSS.
  */
 export declare function validateTokenLink(componentDir: string, tagName: string, root: string, tokenPrefix?: string, tokenHostDocuments?: string[]): Promise<ValidationIssue[]>;
 /**

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

@@ -211,15 +211,73 @@ export async function validateJarMnEntries(root, config) {
  * `tokenHostDocuments` is not configured in furnace.json.
  */
 const DEFAULT_TOKEN_HOST_DOCUMENTS = ['browser/base/content/browser.xhtml'];
+/**
+ * Directory scanned for additional chrome host documents that mount the
+ * component under audit. Kept narrow (top-level `browser/base/content/`)
+ * so the auto-detection stays cheap and only triggers on the well-known
+ * location forks use for replacement chrome documents.
+ */
+const AUTO_DETECT_HOST_DIR = 'browser/base/content';
+/**
+ * Scans `browser/base/content/*.xhtml` for chrome documents that reference
+ * `tagName`. Returned paths are engine-relative and deduplicated against
+ * `already`, so callers can merge them with the caller-configured set
+ * without producing double entries in warning output.
+ *
+ * Motivating case: a fork that mounts a custom element from its own
+ * top-level chrome document (e.g. `mybrowser.xhtml`) without setting
+ * `tokenHostDocuments`. The stock `browser.xhtml` was the only thing
+ * scanned, so the tokens CSS link in the ACTUAL host document went
+ * unnoticed and the warning false-fired.
+ *
+ * @param engineDir Absolute engine root.
+ * @param tagName Custom element tag the CSS belongs to.
+ * @param already Paths already in the scan set (POSIX, engine-relative).
+ */
+async function autoDetectTokenHostDocuments(engineDir, tagName, already) {
+    const contentDir = join(engineDir, AUTO_DETECT_HOST_DIR);
+    if (!(await pathExists(contentDir)))
+        return [];
+    let entries;
+    try {
+        entries = await readdir(contentDir);
+    }
+    catch {
+        return [];
+    }
+    const alreadySet = new Set(already);
+    const detected = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.xhtml'))
+            continue;
+        const relPath = `${AUTO_DETECT_HOST_DIR}/${entry}`;
+        if (alreadySet.has(relPath))
+            continue;
+        const absPath = join(contentDir, entry);
+        let content;
+        try {
+            content = await readText(absPath);
+        }
+        catch {
+            continue;
+        }
+        if (content.includes(tagName)) {
+            detected.push(relPath);
+        }
+    }
+    return detected;
+}
 /**
  * Validates that components using design tokens have the tokens CSS
  * linked in at least one chrome host document. Without the link, tokens
  * silently resolve to nothing at runtime.
  *
- * Forks with multiple chrome host documents (e.g. `mybrowser.xhtml` beside
- * `browser.xhtml`) can enumerate them via `tokenHostDocuments` in
- * furnace.json; the warning fires only when NONE of the configured
- * documents link the tokens CSS.
+ * Scan set is the union of (a) the configured `tokenHostDocuments` (or
+ * the upstream default when unset) and (b) any `browser/base/content/*.xhtml`
+ * document that references `tagName` — the auto-detection path catches
+ * forks that mount components from a replacement chrome document without
+ * having configured `tokenHostDocuments`. The warning fires only when
+ * NONE of the documents in the final scan set link the tokens CSS.
  */
 export async function validateTokenLink(componentDir, tagName, root, tokenPrefix, tokenHostDocuments) {
     const issues = [];
@@ -233,7 +291,7 @@ export async function validateTokenLink(componentDir, tagName, root, tokenPrefix
     if (!cssContent.includes(tokenPrefix))
         return issues;
     const { engine: engineDir } = getProjectPaths(root);
-    const hostDocuments = tokenHostDocuments && tokenHostDocuments.length > 0
+    const configuredHosts = tokenHostDocuments && tokenHostDocuments.length > 0
         ? tokenHostDocuments
         : DEFAULT_TOKEN_HOST_DOCUMENTS;
     let tokensCssFile;
@@ -247,6 +305,8 @@ export async function validateTokenLink(componentDir, tagName, root, tokenPrefix
         warn(`Could not resolve token CSS link target for ${tagName} during validation: ${reason}`);
         return issues;
     }
+    const autoDetected = await autoDetectTokenHostDocuments(engineDir, tagName, configuredHosts);
+    const hostDocuments = [...configuredHosts, ...autoDetected];
     const checkedDocuments = [];
     let anyLinks = false;
     for (const relDocPath of hostDocuments) {
@@ -268,7 +328,7 @@ export async function validateTokenLink(componentDir, tagName, root, tokenPrefix
             component: tagName,
             severity: 'warning',
             check: 'missing-token-link',
-            message: `Component uses ${tokenPrefix}* tokens but none of the configured chrome host documents (${docsList}) link ${tokensCssFile}. Tokens will silently resolve to nothing. Configure additional hosts via furnace.json "tokenHostDocuments" if needed.`,
+            message: `Component uses ${tokenPrefix}* tokens but none of the scanned chrome host documents (${docsList}) link ${tokensCssFile}. Tokens will silently resolve to nothing. Configure additional hosts via furnace.json "tokenHostDocuments" if needed.`,
         });
     }
     return issues;

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

@@ -27,3 +27,47 @@ export interface BuildArtifactCheck {
 export declare function hasBuildArtifacts(engineDir: string): Promise<BuildArtifactCheck>;
 /** Builds a user-facing explanation when detected build artifacts belong to another workspace. */
 export declare function buildArtifactMismatchMessage(engineDir: string, buildCheck: BuildArtifactCheck, commandName: string): string | undefined;
+/**
+ * Outcome of an in-place mozinfo.json rewrite attempt. A successful rewrite
+ * returns the paths written; a refused rewrite returns a human-readable
+ * reason so the build flow can surface it alongside the original mismatch
+ * message before falling back to the clean-rebuild instruction.
+ */
+export interface MozinfoRewriteResult {
+    /** Whether mozinfo.json was patched in place. */
+    rewritten: boolean;
+    /** Reason the rewrite was refused (populated when `rewritten === false`). */
+    reason?: string;
+    /** New `topsrcdir` value written to disk (populated on success). */
+    newTopsrcdir?: string;
+    /** New `topobjdir` value written to disk (populated on success). */
+    newTopobjdir?: string;
+    /** New `mozconfig` value written to disk (populated on success when it lived inside topsrcdir). */
+    newMozconfig?: string;
+}
+/**
+ * Safe-relocation rewriter for mozinfo.json under the active obj-* tree.
+ *
+ * Firefox build artefacts bake the topsrcdir into many generated files
+ * (Makefiles, config.status, backend.mk, .deps dependency files — anything
+ * produced by `mach configure`). A fresh `mach configure` rebuilds those
+ * from the top, so the rewriter only needs to patch the one file `mach`
+ * reads to learn where its checkout actually lives. Once mozinfo.json
+ * agrees with the on-disk layout, `mach configure` regenerates the rest.
+ *
+ * Safety rules — the rewrite is refused when any of them are violated:
+ *   - `topsrcdir` and `topobjdir` must both be present and non-empty.
+ *   - `topobjdir` must resolve to `<topsrcdir>/<objDir>`; a non-in-tree
+ *     objdir means the previous workspace was configured differently,
+ *     so a blind prefix-rewrite could point mach at the wrong tree.
+ *   - The computed new `topobjdir` must be `<engineDir>/<objDir>`; if it
+ *     is not, the objDir name itself changed and we cannot prove safety.
+ *
+ * When any rule trips, the caller should fall back to the clean-rebuild
+ * instruction — that's always a correct (if expensive) recovery path.
+ *
+ * @param engineDir Absolute path to the current engine checkout.
+ * @param objDir Name of the obj-* directory to rewrite against.
+ * @returns Result object; callers inspect `rewritten` and surface `reason`.
+ */
+export declare function attemptMozinfoRewrite(engineDir: string, objDir: string): Promise<MozinfoRewriteResult>;

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

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { readdir } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { join, relative, resolve, sep } from 'node:path';
 import { toError } from '../utils/errors.js';
-import { pathExists, readJson } from '../utils/fs.js';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { isObject, isString } from '../utils/validation.js';
 function validateBuildMozinfo(data) {
@@ -112,6 +112,107 @@ export function buildArtifactMismatchMessage(engineDir, buildCheck, commandName)
     }
     return (`${commandName} cannot use copied or relocated build artifacts whose metadata still points at a different Firefox workspace.\n\n` +
         `${details.join('\n')}\n\n` +
-        'Delete the stale obj-* directory in this workspace and run "fireforge build" again so mach regenerates build metadata for the current checkout.');
+        'Delete the stale obj-* directory in this workspace and run "fireforge build" again so mach regenerates build metadata for the current checkout.\n' +
+        'If the workspace was simply moved (same tree, different prefix), "fireforge build --rewrite-mozinfo" will patch mozinfo.json paths in place and run mach configure instead of scrubbing the whole tree.');
+}
+/**
+ * Safe-relocation rewriter for mozinfo.json under the active obj-* tree.
+ *
+ * Firefox build artefacts bake the topsrcdir into many generated files
+ * (Makefiles, config.status, backend.mk, .deps dependency files — anything
+ * produced by `mach configure`). A fresh `mach configure` rebuilds those
+ * from the top, so the rewriter only needs to patch the one file `mach`
+ * reads to learn where its checkout actually lives. Once mozinfo.json
+ * agrees with the on-disk layout, `mach configure` regenerates the rest.
+ *
+ * Safety rules — the rewrite is refused when any of them are violated:
+ *   - `topsrcdir` and `topobjdir` must both be present and non-empty.
+ *   - `topobjdir` must resolve to `<topsrcdir>/<objDir>`; a non-in-tree
+ *     objdir means the previous workspace was configured differently,
+ *     so a blind prefix-rewrite could point mach at the wrong tree.
+ *   - The computed new `topobjdir` must be `<engineDir>/<objDir>`; if it
+ *     is not, the objDir name itself changed and we cannot prove safety.
+ *
+ * When any rule trips, the caller should fall back to the clean-rebuild
+ * instruction — that's always a correct (if expensive) recovery path.
+ *
+ * @param engineDir Absolute path to the current engine checkout.
+ * @param objDir Name of the obj-* directory to rewrite against.
+ * @returns Result object; callers inspect `rewritten` and surface `reason`.
+ */
+export async function attemptMozinfoRewrite(engineDir, objDir) {
+    const mozinfoPath = join(engineDir, objDir, 'mozinfo.json');
+    if (!(await pathExists(mozinfoPath))) {
+        return { rewritten: false, reason: 'mozinfo.json not found in obj directory' };
+    }
+    let raw;
+    try {
+        raw = await readJson(mozinfoPath);
+    }
+    catch (error) {
+        return { rewritten: false, reason: `mozinfo.json is unreadable: ${toError(error).message}` };
+    }
+    if (!isObject(raw)) {
+        return { rewritten: false, reason: 'mozinfo.json is not a JSON object' };
+    }
+    let mozinfo;
+    try {
+        mozinfo = validateBuildMozinfo(raw);
+    }
+    catch (error) {
+        return { rewritten: false, reason: toError(error).message };
+    }
+    const oldSrc = mozinfo.topsrcdir;
+    const oldObj = mozinfo.topobjdir;
+    if (!oldSrc || !oldObj) {
+        return {
+            rewritten: false,
+            reason: 'mozinfo.json is missing topsrcdir or topobjdir; cannot rewrite safely',
+        };
+    }
+    const oldSrcResolved = resolve(oldSrc);
+    const oldObjResolved = resolve(oldObj);
+    const insideTree = oldObjResolved === oldSrcResolved ||
+        oldObjResolved.startsWith(oldSrcResolved + sep) ||
+        oldObjResolved.startsWith(oldSrcResolved + '/');
+    if (!insideTree) {
+        return {
+            rewritten: false,
+            reason: `topobjdir (${oldObjResolved}) is not inside topsrcdir (${oldSrcResolved}) — rewrite would change workspace layout`,
+        };
+    }
+    const relativeObj = relative(oldSrcResolved, oldObjResolved).split(sep).join('/');
+    if (relativeObj !== objDir) {
+        return {
+            rewritten: false,
+            reason: `mozinfo objdir "${relativeObj}" does not match detected objdir "${objDir}" — rewrite would change the obj directory name`,
+        };
+    }
+    const newSrc = resolve(engineDir);
+    const newObj = resolve(engineDir, objDir);
+    const patched = { ...raw, topsrcdir: newSrc, topobjdir: newObj };
+    let newMozconfig;
+    if (mozinfo.mozconfig) {
+        const oldMozconfigResolved = resolve(mozinfo.mozconfig);
+        if (oldMozconfigResolved === oldSrcResolved ||
+            oldMozconfigResolved.startsWith(oldSrcResolved + sep) ||
+            oldMozconfigResolved.startsWith(oldSrcResolved + '/')) {
+            const rel = relative(oldSrcResolved, oldMozconfigResolved);
+            newMozconfig = resolve(newSrc, rel);
+            patched['mozconfig'] = newMozconfig;
+        }
+        // A mozconfig living outside the old topsrcdir is left as-is — it
+        // probably points at a shared configuration file the user kept in
+        // place across the relocation. A relocated checkout that also moved
+        // its mozconfig will still fail configure; operator can re-point
+        // with `MOZCONFIG=…` or run a full clean rebuild.
+    }
+    await writeJson(mozinfoPath, patched);
+    return {
+        rewritten: true,
+        newTopsrcdir: newSrc,
+        newTopobjdir: newObj,
+        ...(newMozconfig ? { newMozconfig } : {}),
+    };
 }
 //# sourceMappingURL=mach-build-artifacts.js.map

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

@@ -1,4 +1,4 @@
-export { type BuildArtifactCheck, buildArtifactMismatchMessage, hasBuildArtifacts, } from './mach-build-artifacts.js';
+export { attemptMozinfoRewrite, type BuildArtifactCheck, buildArtifactMismatchMessage, hasBuildArtifacts, type MozinfoRewriteResult, } from './mach-build-artifacts.js';
 export { generateMozconfig, type MozconfigVariables } from './mach-mozconfig.js';
 export { ensurePython, resetResolvedPython } from './mach-python.js';
 /**

package/dist/src/core/mach.js

@@ -7,7 +7,7 @@ import { exec, execInherit, execInheritCapture, execStream } from '../utils/proc
 import { explainMachError } from './mach-error-hints.js';
 import { getPython } from './mach-python.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
-export { buildArtifactMismatchMessage, hasBuildArtifacts, } from './mach-build-artifacts.js';
+export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, } from './mach-build-artifacts.js';
 export { generateMozconfig } from './mach-mozconfig.js';
 export { ensurePython, resetResolvedPython } from './mach-python.js';
 /**

package/dist/src/core/test-stale-check.d.ts

@@ -0,0 +1,42 @@
+import type { BuildBaseline } from './build-baseline.js';
+/** Result of the stale-build preflight probe. */
+export interface StaleBuildResult {
+    /** True when at least one packageable engine file changed since the baseline. */
+    stale: boolean;
+    /**
+     * Engine-relative paths that would have been packaged but appear to have
+     * changed since the baseline. Sorted and deduplicated. Truncated at
+     * {@link STALE_PATHS_LIMIT} entries for rendering; consult
+     * {@link StaleBuildResult.truncated} to know when to append a `(+N more)`
+     * tail to the warning.
+     */
+    changedPaths: string[];
+    /**
+     * How many paths were dropped from `changedPaths` due to the render cap.
+     * Callers render this as `(+N more)` in the warning body.
+     */
+    truncated: number;
+    /**
+     * The baseline that anchored the diff, or undefined when no previous
+     * successful build exists. A missing baseline is treated as "not stale"
+     * — we have nothing to compare against and a warning would mislead.
+     */
+    baseline: BuildBaseline | undefined;
+}
+/**
+ * Probes the engine tree for packageable changes since the last successful
+ * `fireforge build`. Returns a summary the `fireforge test` handler renders
+ * as an up-front warning when `--build` was NOT passed. The probe never
+ * throws; git failures and a missing baseline both degrade to `stale: false`
+ * so a broken probe cannot block a test run.
+ *
+ * @param projectRoot Root directory of the project.
+ * @param engineDir Path to the engine directory.
+ */
+export declare function checkStaleBuildForTest(projectRoot: string, engineDir: string): Promise<StaleBuildResult>;
+/**
+ * Formats a human-readable warning body from a {@link StaleBuildResult}.
+ * Kept separate from the probe so test code can assert on the structured
+ * result without matching the rendered copy.
+ */
+export declare function formatStaleBuildWarning(result: StaleBuildResult): string;