@hominis/fireforge 0.15.6 → 0.15.7

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

@@ -0,0 +1,187 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Registration-aware artifact resolution for the post-build dist-tree audit.
+ *
+ * The basename-plus-similarity heuristic in `build-audit-resolve.ts` cannot
+ * distinguish two unrelated files that share a source basename. Motivating
+ * case: one fork registers `content/mybrowser.js` in `browser/base/jar.mn`
+ * (packaged under `chrome/browser/content/browser/mybrowser.js`) while an
+ * unrelated patch registers a `mybrowser.js` pref file under
+ * `browser/defaults/preferences/`. The basename walker surfaces both
+ * candidates, `scoreCandidate` awards them an equal trailing-overlap score
+ * (basename only, no meaningful mid-path match), and whichever the
+ * directory walk hits first wins — frequently the wrong one.
+ *
+ * This module anchors resolution to the `(source)` reference inside
+ * `jar.mn`. For a source under audit we walk its ancestor directories for
+ * an owning `jar.mn`, find the entry whose `(source)` resolves to our
+ * path, and expose both the target path recorded in the entry and the
+ * manifest that owns it. Callers in `build-audit.ts` prefer candidates
+ * whose absolute dist-tree path ends with the registered target, and
+ * report an unambiguous "registered but not packaged" miss when no such
+ * candidate exists — rather than falling through to the heuristic which
+ * would pick an unrelated same-basename file.
+ *
+ * Fallback semantics: when no jar.mn registration is found, the caller
+ * is expected to use the similarity heuristic. Registration wins when it
+ * exists; the heuristic fills the gap for sources registered through
+ * moz.build (`FINAL_TARGET_FILES`, `JS_PREFERENCE_FILES`, etc.) or
+ * `package-manifest.in` entries, which this module intentionally does
+ * not parse — supporting every Firefox registration surface would bloat
+ * the audit, and the heuristic's remaining weak case (unrelated same-
+ * basename hits) is surfaced to the operator in the warning copy.
+ */
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { findAllByBasename } from './build-audit-resolve.js';
+/** Ceiling on ancestor-directory hops when searching for an owning jar.mn. */
+const MAX_JAR_MN_SCAN_DEPTH = 8;
+/**
+ * Parses a single jar.mn line into `{ target, source }` when the line is a
+ * content entry with an explicit `(source)` reference. Returns undefined
+ * for comments, headers (`browser.jar:`), `%` manifest directives, blank
+ * lines, and entries without a source reference.
+ *
+ * Accepted entry shapes:
+ *   `        content/browser/foo.js     (content/foo.js)`   bare
+ *   `*       content/browser/foo.js     (content/foo.js)`   `*` = preprocessed
+ *   `en-US.jar:        content/foo.js  (content/foo.js)`    locale-prefixed
+ */
+export function parseJarMnEntry(line) {
+    if (!line)
+        return undefined;
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#') || trimmed.startsWith('%'))
+        return undefined;
+    // Leading `*` (preprocessed) and optional `locale.jar:` prefix are dropped
+    // before matching the target/(source) pair. Both are whitespace-separated
+    // from the target entry.
+    const stripped = trimmed.replace(/^\*\s+/, '').replace(/^[A-Za-z0-9.\-_]+\.jar:\s+/, '');
+    const match = /^(\S+)\s+\(([^)]+)\)\s*$/.exec(stripped);
+    if (!match)
+        return undefined;
+    const target = (match[1] ?? '').trim();
+    const source = (match[2] ?? '').trim();
+    if (!target || !source)
+        return undefined;
+    return { target, source };
+}
+/**
+ * Scans a jar.mn file's contents for an entry whose source reference
+ * matches `relativeSource` (POSIX, relative to the jar.mn directory).
+ * Returns the first match; jar.mn enforces uniqueness of `(source)` in
+ * practice, so a first-match wins behaviour is adequate.
+ */
+export function findJarMnEntryForSource(content, relativeSource) {
+    const normalized = relativeSource.replace(/\\/g, '/');
+    for (const line of content.split('\n')) {
+        const parsed = parseJarMnEntry(line);
+        if (!parsed)
+            continue;
+        if (parsed.source === normalized)
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * Walks from the source's directory upward to the engine root, returning
+ * the first jar.mn entry that registers the given source. Returns undefined
+ * when no ancestor jar.mn claims the source.
+ *
+ * @param engineDir Absolute engine root; walk halts here.
+ * @param source Engine-relative POSIX source path.
+ */
+export async function findRegisteredTarget(engineDir, source) {
+    const sourceAbs = join(engineDir, source);
+    const root = engineDir.replace(/[/\\]+$/, '');
+    let current = dirname(sourceAbs);
+    let depth = 0;
+    while (depth <= MAX_JAR_MN_SCAN_DEPTH &&
+        (current === root || current.startsWith(`${root}/`) || current.startsWith(`${root}\\`))) {
+        const jarMn = join(current, 'jar.mn');
+        if (await pathExists(jarMn)) {
+            let content;
+            try {
+                content = await readText(jarMn);
+            }
+            catch {
+                content = '';
+            }
+            const rel = relative(current, sourceAbs).split(sep).join('/');
+            const entry = findJarMnEntryForSource(content, rel);
+            if (entry) {
+                return { target: entry.target, source: entry.source, jarManifest: jarMn };
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+        depth += 1;
+    }
+    return undefined;
+}
+/**
+ * Normalises an absolute filesystem path to POSIX separators so the
+ * suffix comparison against a jar.mn target (always POSIX) is platform-
+ * independent.
+ */
+function toPosix(path) {
+    return path.split(sep).join('/');
+}
+/**
+ * Probes the dist tree for the artifact registered against the given
+ * source. Returns the matched candidate and the registration hit that
+ * anchored it; undefined when the source has no owning jar.mn or when
+ * no same-basename candidate under the search roots ends with the
+ * registered target path.
+ *
+ * Suffix-matching against the target path is intentional: jar.mn targets
+ * are relative to the jar root (`browser.jar:`, `toolkit.jar:`), but the
+ * dist tree prefixes every entry with a jar-specific directory
+ * (`.../chrome/browser/content/browser/…`). The source basename plus the
+ * target suffix are unambiguous across every packaging convention we
+ * care about.
+ *
+ * @param engineDir Absolute engine root.
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to probe (dist/, _tests/).
+ */
+export async function resolveArtifactByRegistration(engineDir, source, searchRoots) {
+    const hit = await findRegisteredTarget(engineDir, source);
+    if (!hit)
+        return undefined;
+    const name = basename(source);
+    const targetSuffix = `/${hit.target.replace(/^\/+/, '')}`;
+    const candidates = [];
+    for (const root of searchRoots) {
+        const found = await findAllByBasename(root, name);
+        candidates.push(...found);
+    }
+    for (const candidate of candidates) {
+        if (toPosix(candidate).endsWith(targetSuffix)) {
+            return { artifact: candidate, hit };
+        }
+    }
+    return undefined;
+}
+/**
+ * Returns the absolute paths of every same-basename candidate under the
+ * given search roots. Used by the audit to enumerate ALL false-match
+ * candidates when the heuristic fallback downgrades to "missing" — the
+ * operator needs to see the full set, not just the scorer's pick, to
+ * distinguish a registration bug from a genuine packaging drop.
+ *
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to scan.
+ */
+export async function collectSameBasenameCandidates(source, searchRoots) {
+    const name = basename(source);
+    const out = [];
+    for (const root of searchRoots) {
+        const found = await findAllByBasename(root, name);
+        out.push(...found);
+    }
+    return out;
+}
+//# sourceMappingURL=build-audit-registration.js.map

package/dist/src/core/build-audit-transforms.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns the expected chrome-tree suffix for an engine-relative POSIX
+ * source path when the path falls under a known transform prefix;
+ * undefined otherwise.
+ *
+ * @param source Engine-relative POSIX source path.
+ */
+export declare function expectedChromeSuffix(source: string): string | undefined;
+/**
+ * Probes the dist tree for the artifact implied by a known
+ * source→chrome transform. Returns the first absolute candidate whose
+ * POSIX path ends with the expected chrome suffix, or undefined when
+ * no transform applies or no candidate matches.
+ *
+ * The transform check is treated as high-confidence by `build-audit.ts`
+ * (callers pass `{ registered: true }` to `evaluateArtifactMtime`), so
+ * a match bypasses the structural-relation check that rejects generic
+ * basename collisions.
+ *
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to probe (dist/, _tests/).
+ */
+export declare function resolveArtifactByKnownTransform(source: string, searchRoots: readonly string[]): Promise<string | undefined>;

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

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Known source→packaging path transforms for the post-build dist-tree audit.
+ *
+ * Motivating case: a source at `engine/browser/base/content/foo.js` ships
+ * under `chrome/browser/content/browser/foo.js`. If an unrelated patch
+ * registers a different `foo.js` elsewhere in the tree (e.g. a pref file
+ * under `browser/defaults/preferences/foo.js`), the basename walker
+ * surfaces both candidates, `scoreCandidate` awards them an identical
+ * trailing-overlap score (basename only; every intermediate segment is
+ * in the generic list), and whichever the directory walk hits first wins.
+ * The heuristic then declares the chosen candidate "not structurally
+ * related" and reports the correctly-packaged chrome resource as missing.
+ *
+ * The transforms below anchor resolution to the well-known subtree→chrome
+ * conventions used by upstream mozilla-central jar.mn. When a source
+ * matches one of these prefixes, a candidate whose absolute path ends
+ * with the implied chrome suffix is treated as a confident match — the
+ * scorer never runs and the structural-relation check is bypassed.
+ *
+ * Scope is intentionally narrow: only subtrees whose packaging target is
+ * stable across every fork we know about. A fork that reroutes a known
+ * subtree can still win by adding `(source)` annotations in its own
+ * `jar.mn`, which `resolveArtifactByRegistration` consults first.
+ */
+import { basename, sep } from 'node:path';
+import { findAllByBasename } from './build-audit-resolve.js';
+/**
+ * Table of `prefix → chrome-suffix` transforms. Each rule names an
+ * engine-relative subtree prefix and produces the expected dist-tree
+ * suffix for a file under it. Rules are evaluated in array order and
+ * the first-matching prefix wins, so `toolkit/content/widgets/` must
+ * precede the looser `toolkit/content/`.
+ */
+const KNOWN_TRANSFORMS = [
+    {
+        prefix: 'browser/base/content/',
+        build: (rest) => `chrome/browser/content/browser/${rest}`,
+    },
+    {
+        prefix: 'toolkit/content/widgets/',
+        build: (rest) => `chrome/toolkit/content/global/elements/${rest}`,
+    },
+    {
+        prefix: 'toolkit/content/',
+        build: (rest) => `chrome/toolkit/content/global/${rest}`,
+    },
+];
+/**
+ * Returns the expected chrome-tree suffix for an engine-relative POSIX
+ * source path when the path falls under a known transform prefix;
+ * undefined otherwise.
+ *
+ * @param source Engine-relative POSIX source path.
+ */
+export function expectedChromeSuffix(source) {
+    for (const rule of KNOWN_TRANSFORMS) {
+        if (source.startsWith(rule.prefix)) {
+            return rule.build(source.slice(rule.prefix.length));
+        }
+    }
+    return undefined;
+}
+/**
+ * Probes the dist tree for the artifact implied by a known
+ * source→chrome transform. Returns the first absolute candidate whose
+ * POSIX path ends with the expected chrome suffix, or undefined when
+ * no transform applies or no candidate matches.
+ *
+ * The transform check is treated as high-confidence by `build-audit.ts`
+ * (callers pass `{ registered: true }` to `evaluateArtifactMtime`), so
+ * a match bypasses the structural-relation check that rejects generic
+ * basename collisions.
+ *
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to probe (dist/, _tests/).
+ */
+export async function resolveArtifactByKnownTransform(source, searchRoots) {
+    const suffix = expectedChromeSuffix(source);
+    if (!suffix)
+        return undefined;
+    const name = basename(source);
+    const suffixWithSlash = `/${suffix}`;
+    for (const root of searchRoots) {
+        const candidates = await findAllByBasename(root, name);
+        for (const candidate of candidates) {
+            if (candidate.split(sep).join('/').endsWith(suffixWithSlash)) {
+                return candidate;
+            }
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=build-audit-transforms.js.map

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 { 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';
@@ -317,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/';
@@ -327,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);
@@ -341,18 +413,18 @@ async function auditSinglePath(source, ctx) {
         };
     }
     if (artifactMtime + 1 < sourceMtime) {
-        // Before claiming "stale", verify the match is structurally related.
-        // A same-basename hit in an unrelated subtree (e.g. `head.js` in a
-        // completely different upstream test helper) should be reported as
-        // missing — the operator needs to check registration, not puzzle
-        // over why an unrelated file appears "older than the source".
-        if (!isConfidentMatch(source, artifact)) {
+        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} (nearest same-basename file ${artifact} lives in an unrelated subtree). Missing moz.build / jar.mn / package-manifest.in registration?`,
+                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 {
@@ -364,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

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>;