@hominis/fireforge 0.45.0 → 0.46.0

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

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Skip classification for the post-build packaging audit.
+ *
+ * The audit is warn-only, which makes a false positive cheap individually
+ * and expensive in aggregate: an operator who learns that `Audit:` lines are
+ * usually wrong stops reading the one that is right. Every classifier here
+ * exists to remove a warning whose "missing packaged artifact" claim is
+ * structurally impossible, and each carries its own reason so the
+ * `Packaged:` summary can say what it skipped and why — a run reporting
+ * `4 missing` with zero real misses is what this replaces.
+ */
+import { readText } from '../utils/fs.js';
+import { normalizePathSlashes } from '../utils/paths.js';
+import { escapeRegex } from '../utils/regex.js';
+import { extractWithBrandingPath } from './mach-mozconfig.js';
+/** Render order for the `Packaged:` summary's per-class breakdown. */
+export const AUDIT_SKIP_REASONS = [
+    'not-packageable',
+    'platform-gated',
+    'platform-gated-ancestor',
+    'tests-not-packaged',
+    'source-unreadable',
+    'branding-not-selected',
+    'storybook-story',
+    'declared-unpackaged',
+];
+/**
+ * Suffixes of Storybook story modules.
+ *
+ * Firefox's in-tree Storybook renders these through its own Vite config;
+ * no `jar.mn` or `moz.build` entry packages one, so "no packaged artifact"
+ * is the expected state rather than a missing registration. Kept as a
+ * CLOSED list on purpose: generalising to "anything with a dotted infix"
+ * would swallow `*.worker.js` and `*.sys.mjs`, which are packaged.
+ */
+const STORYBOOK_SUFFIXES = ['.stories.mjs', '.stories.js'];
+/** True for a Storybook story module. */
+export function isStorybookStoryPath(sourcePath) {
+    const normalised = normalizePathSlashes(sourcePath);
+    return STORYBOOK_SUFFIXES.some((suffix) => normalised.endsWith(suffix));
+}
+/** Prefix under which every branding tree lives. */
+const BRANDING_ROOT = 'browser/branding/';
+/**
+ * Reads the branding directory this objdir was configured with.
+ *
+ * FireForge generates `engine/mozconfig` and writes the
+ * `ac_add_options --with-branding=…` line into it, so the selected branding
+ * is knowable from the tree. Returns undefined when the mozconfig cannot be
+ * read or carries no directive — the caller must then keep warning, because
+ * a skip that cannot name its evidence is a masked warning.
+ *
+ * @param engineDir - Absolute path to the engine root
+ * @returns Engine-relative branding path, or undefined
+ */
+export async function resolveSelectedBranding(engineDir) {
+    try {
+        const content = await readText(`${engineDir.replace(/[/\\]+$/, '')}/mozconfig`);
+        const selected = extractWithBrandingPath(content);
+        return selected === undefined ? undefined : normalizePathSlashes(selected).replace(/\/+$/, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when `sourcePath` lives under a branding tree that is NOT the one
+ * this objdir was configured with.
+ *
+ * An unselected branding directory is not an input to this build at all, so
+ * its files can never appear in `dist/`. Worse, the basename walker matched
+ * them against the SELECTED branding's same-named artifact and reported the
+ * unselected file as "newer than its packaged artifact" — a stale warning
+ * about a comparison that has no meaning.
+ *
+ * @param sourcePath - Engine-relative POSIX path
+ * @param selectedBranding - Engine-relative selected branding path
+ */
+export function isUnselectedBrandingPath(sourcePath, selectedBranding) {
+    if (selectedBranding === undefined)
+        return false;
+    const normalised = normalizePathSlashes(sourcePath);
+    if (!normalised.startsWith(BRANDING_ROOT))
+        return false;
+    const selected = `${selectedBranding}/`;
+    return !normalised.startsWith(selected);
+}
+/**
+ * Finds the declaration admitting `sourcePath`, if any.
+ *
+ * Exact match or a `*`-within-one-segment glob, matching the
+ * `support-files` matcher's deliberate narrowness: `**` and other
+ * cross-directory shapes are not accepted, because a carve-out that
+ * silently widens is exactly the failure this feature is warned against.
+ *
+ * @param sourcePath - Engine-relative POSIX path
+ * @param declarations - The project's `buildAudit.unpackaged` entries
+ */
+export function matchUnpackagedDeclaration(sourcePath, declarations) {
+    const normalised = normalizePathSlashes(sourcePath);
+    return declarations.find((declaration) => {
+        const pattern = normalizePathSlashes(declaration.path);
+        if (!pattern.includes('*'))
+            return pattern === normalised;
+        const regex = new RegExp(`^${pattern
+            .split('*')
+            .map((part) => escapeRegex(part))
+            .join('[^/]*')}$`);
+        return regex.test(normalised);
+    });
+}

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

@@ -1,3 +1,4 @@
+import { type AuditSkipReason, type UnpackagedDeclaration } from './build-audit-skip.js';
 import type { BuildBaseline } from './build-baseline-types.js';
 /**
  * True for the build-input manifests the build consumes but never packages
@@ -34,9 +35,17 @@ export interface AuditEntry {
      * updated: an artifact exists and is at least as new as the source.
      * stale:   artifact exists but is older than the source (probable packaging drop).
      * missing: no artifact with a matching basename was found anywhere under dist/.
-     * skipped: the file extension / path does not imply packaging; not counted.
+     * skipped: the file was not audited; `skipReason` says why.
      */
     status: 'updated' | 'stale' | 'missing' | 'skipped';
+    /**
+     * Why a `skipped` entry was skipped. Present only for `skipped`; the
+     * reasons used to exist only as verbose log strings, so the summary line
+     * could report `4 missing` on a run with zero real misses and nothing in
+     * the counts distinguished a structural non-input from an unregistered
+     * file an operator must act on.
+     */
+    skipReason?: AuditSkipReason;
 }
 /** Summary counts for the "Packaged:" end-of-build line. */
 export interface AuditSummary {
@@ -44,6 +53,8 @@ export interface AuditSummary {
     stale: number;
     missing: number;
     skipped: number;
+    /** Per-class skip counts, so the summary can name what it dismissed. */
+    skippedByReason: Record<AuditSkipReason, number>;
     entries: AuditEntry[];
 }
 /**
@@ -78,4 +89,6 @@ export declare function isXpcomManifestPath(sourcePath: string): boolean;
  * @param baseline Optional previous-build baseline marker.
  * @returns Summary of artifact status counts.
  */
-export declare function auditBuildArtifacts(projectRoot: string, engineDir: string, baseline: BuildBaseline | undefined): Promise<AuditSummary>;
+export declare function auditBuildArtifacts(projectRoot: string, engineDir: string, baseline: BuildBaseline | undefined, options?: {
+    unpackaged?: readonly UnpackagedDeclaration[];
+}): Promise<AuditSummary>;

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

@@ -39,9 +39,10 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
 import { normalizePathSlashes } from '../utils/paths.js';
-import { detectPlatformGate } from './build-audit-platform.js';
+import { detectAncestorDirsGate, detectPlatformGate } from './build-audit-platform.js';
 import { collectSameBasenameCandidates, findRegisteredTarget, resolveArtifactByRegistration, } from './build-audit-registration.js';
 import { countTrailingSegmentMatches, GENERIC_PATH_SEGMENTS, isTestPath, resolveBestArtifact, } from './build-audit-resolve.js';
+import { AUDIT_SKIP_REASONS, isStorybookStoryPath, isUnselectedBrandingPath, matchUnpackagedDeclaration, resolveSelectedBranding, } from './build-audit-skip.js';
 import { resolveArtifactByKnownTransform } from './build-audit-transforms.js';
 import { collectChangedEnginePaths } from './engine-changes.js';
 import { loadPatchesManifest } from './patch-manifest-io.js';
@@ -101,6 +102,10 @@ export function isBuildInputPath(sourcePath) {
 export function isJarManifestPath(sourcePath) {
     return sourcePath === 'jar.mn' || sourcePath.endsWith('/jar.mn');
 }
+/** Zeroed per-class skip counters. */
+function emptySkipCounts() {
+    return Object.fromEntries(AUDIT_SKIP_REASONS.map((reason) => [reason, 0]));
+}
 /**
  * Decides whether a source path should be packaged. Returns true for paths
  * whose extension or directory fragment matches a known-packaged pattern,
@@ -147,7 +152,7 @@ export function isPackageablePath(sourcePath) {
  * @returns True when the path is a `components.conf` manifest.
  */
 export function isXpcomManifestPath(sourcePath) {
-    return basename(sourcePath.replace(/\\/g, '/')) === 'components.conf';
+    return basename(normalizePathSlashes(sourcePath)) === 'components.conf';
 }
 /*
  * Finds the unique obj-star directory with a dist subtree, or undefined
@@ -273,6 +278,55 @@ function isConfidentMatch(source, candidate) {
     }
     return false;
 }
+/**
+ * Applies a `buildAudit.unpackaged` carve-out to a classified result.
+ *
+ * Two behaviours, both mirroring the `--expect-unmanaged` model:
+ *
+ *  - An admitted path is LISTED, not silenced. A carve-out nobody can see
+ *    is how one quietly widens, so the run says which paths it admitted and
+ *    on what stated reason.
+ *  - An admitted path that DOES resolve to a packaged artifact is a STALE
+ *    carve-out: the declaration asserts a fact about the tree that is no
+ *    longer true, and suppressing on it would hide a real packaging change.
+ *    That is reported as a warning, not accepted.
+ *
+ * A declaration matching nothing that changed this run says nothing —
+ * unlike `--expect-unmanaged`, whose unseen entries are reported. The
+ * difference is deliberate: that is a per-invocation flag list, where an
+ * unmet entry is probably a typo in the command just typed. This is a
+ * standing config list checked against only the files that happened to
+ * change, so "not met" is the normal case and reporting it would put a
+ * warning on every build.
+ */
+function applyUnpackagedCarveOut(result, ctx) {
+    // Already skipped for a more specific structural reason — the carve-out
+    // is redundant there and reporting it would be noise.
+    if (result.status === 'skipped')
+        return result;
+    const declaration = matchUnpackagedDeclaration(result.source, ctx.unpackaged);
+    if (declaration === undefined)
+        return result;
+    if (result.artifact !== undefined) {
+        return {
+            source: result.source,
+            artifact: result.artifact,
+            status: 'skipped',
+            skipReason: 'declared-unpackaged',
+            warning: `Audit: engine/${result.source} is declared unpackaged in fireforge.json ` +
+                `("${declaration.reason}") but a packaged artifact exists at ${result.artifact}. ` +
+                'The declaration is stale — remove it, or correct its path.',
+        };
+    }
+    return {
+        source: result.source,
+        artifact: undefined,
+        status: 'skipped',
+        skipReason: 'declared-unpackaged',
+        notice: `Audit: engine/${result.source} admitted as unpackaged by ` +
+            `buildAudit.unpackaged "${declaration.path}" — ${declaration.reason}`,
+    };
+}
 /**
  * Audits one engine source path and returns its entry. Pure orchestration
  * helper kept separate so `auditBuildArtifacts` stays under the per-function
@@ -280,12 +334,30 @@ function isConfidentMatch(source, candidate) {
  */
 async function auditSinglePath(source, ctx) {
     if (!isPackageablePath(source)) {
-        return { source, artifact: undefined, status: 'skipped' };
+        return { source, artifact: undefined, status: 'skipped', skipReason: 'not-packageable' };
+    }
+    if (isStorybookStoryPath(source)) {
+        verbose(`Audit: skipping engine/${source} — Storybook story, never packaged.`);
+        return { source, artifact: undefined, status: 'skipped', skipReason: 'storybook-story' };
+    }
+    if (isUnselectedBrandingPath(source, ctx.selectedBranding)) {
+        verbose(`Audit: skipping engine/${source} — branding tree is not the selected ${ctx.selectedBranding ?? '?'}, so it is not an input to this objdir.`);
+        return { source, artifact: undefined, status: 'skipped', skipReason: 'branding-not-selected' };
     }
     const gate = await detectPlatformGate(ctx.engineDir, source);
     if (gate.gatedOff) {
         verbose(`Audit: skipping engine/${source} — gated off by "${gate.gateExpression ?? '?'}".`);
-        return { source, artifact: undefined, status: 'skipped' };
+        return { source, artifact: undefined, status: 'skipped', skipReason: 'platform-gated' };
+    }
+    const ancestorGate = await detectAncestorDirsGate(ctx.engineDir, source);
+    if (ancestorGate.gatedOff) {
+        verbose(`Audit: skipping engine/${source} — its directory is reached through a DIRS entry in engine/${ancestorGate.gateFile ?? '?'} gated by "${ancestorGate.gateExpression ?? '?'}".`);
+        return {
+            source,
+            artifact: undefined,
+            status: 'skipped',
+            skipReason: 'platform-gated-ancestor',
+        };
     }
     // Tests only end up under `_tests/` after `mach package-tests` (or a
     // test-run that invokes the target) has executed. A plain `mach build`
@@ -294,7 +366,7 @@ async function auditSinglePath(source, ctx) {
     // 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' };
+        return { source, artifact: undefined, status: 'skipped', skipReason: 'tests-not-packaged' };
     }
     const sourcePath = join(ctx.engineDir, source);
     let sourceMtime;
@@ -304,7 +376,7 @@ async function auditSinglePath(source, ctx) {
     }
     catch {
         // Deletion that didn't propagate — distinct class of bug, not audited yet.
-        return { source, artifact: undefined, status: 'skipped' };
+        return { source, artifact: undefined, status: 'skipped', skipReason: 'source-unreadable' };
     }
     const roots = searchRootsFor(source, ctx.distRoot, ctx.testsRoot);
     // Registration-aware resolution first: a `jar.mn` entry whose `(source)`
@@ -488,12 +560,13 @@ function describeOwnership(ownersByPath, source) {
  * @param baseline Optional previous-build baseline marker.
  * @returns Summary of artifact status counts.
  */
-export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
+export async function auditBuildArtifacts(projectRoot, engineDir, baseline, options = {}) {
     const summary = {
         updated: 0,
         stale: 0,
         missing: 0,
         skipped: 0,
+        skippedByReason: emptySkipCounts(),
         entries: [],
     };
     const distRoot = await resolveDistRoot(engineDir);
@@ -514,18 +587,45 @@ export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
     // it. FireForge already resolves this for `status --ownership`; carrying
     // it here turns a three-line mystery into three dismissible lines.
     const ownersByPath = await resolveAuditOwnership(projectRoot);
-    const ctx = { engineDir, distRoot, testsRoot, testsPackaged };
+    const ctx = {
+        engineDir,
+        distRoot,
+        testsRoot,
+        testsPackaged,
+        selectedBranding: await resolveSelectedBranding(engineDir),
+        unpackaged: options.unpackaged ?? [],
+    };
     for (const source of changed) {
-        const result = await auditSinglePath(source, ctx);
+        const result = applyUnpackagedCarveOut(await auditSinglePath(source, ctx), ctx);
         summary[result.status] += 1;
+        if (result.status === 'skipped' && result.skipReason !== undefined) {
+            summary.skippedByReason[result.skipReason] += 1;
+        }
         summary.entries.push({
             source: result.source,
             artifact: result.artifact,
             status: result.status,
+            ...(result.skipReason === undefined ? {} : { skipReason: result.skipReason }),
         });
         if (result.warning)
             warn(`${result.warning}${describeOwnership(ownersByPath, result.source)}`);
+        if (result.notice)
+            info(result.notice);
     }
-    info(`Packaged: ${summary.updated} updated, ${summary.stale} stale, ${summary.missing} missing, ${summary.skipped} skipped`);
+    info(`Packaged: ${summary.updated} updated, ${summary.stale} stale, ${summary.missing} missing, ` +
+        `${summary.skipped} skipped${describeSkipBreakdown(summary)}`);
     return summary;
 }
+/**
+ * Renders the per-class skip breakdown appended to the `Packaged:` line.
+ *
+ * Without it the summary reported one undifferentiated `skipped` count, so
+ * a run that dismissed four unselected-branding files and one
+ * ancestor-gated directory looked identical to one that dismissed five
+ * unregistered sources — and the four false `missing` entries downstream
+ * reported had no counterpart in the counts an operator could check.
+ */
+function describeSkipBreakdown(summary) {
+    const parts = AUDIT_SKIP_REASONS.filter((reason) => summary.skippedByReason[reason] > 0).map((reason) => `${reason} ${String(summary.skippedByReason[reason])}`);
+    return parts.length === 0 ? '' : ` (${parts.join(', ')})`;
+}

package/dist/src/core/build-baseline.d.ts

@@ -25,8 +25,6 @@ import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline
  * `'full'`.
  */
 export type BaselineBuildKind = 'full' | 'faster';
-/** Name of the last-build marker file under `.fireforge/`. */
-export declare const BUILD_BASELINE_FILENAME = "last-build.json";
 /**
  * Resolves the on-disk path of the build baseline marker.
  * @param projectRoot - Root directory of the project
@@ -40,36 +38,55 @@ export declare function getBuildBaselinePath(projectRoot: string): string;
  * @param projectRoot - Root directory of the project
  */
 export declare function readBuildBaseline(projectRoot: string): Promise<BuildBaseline | undefined>;
+export interface WriteBuildBaselineOptions {
+    /** Root directory of the project. */
+    projectRoot: string;
+    /** Path to the engine directory. */
+    engineDir: string;
+    /** Current `binaryName` from fireforge.json. */
+    binaryName: string;
+    /**
+     * Coverage claim of the packaged test runtime this build produced
+     * (`'full'`, or the scoped request paths of a `test --build` invocation).
+     * Omitted → field left off the marker.
+     */
+    testPackagingCoverage?: TestPackagingCoverage | undefined;
+    /**
+     * The baseline this write replaces, when the caller has it. A scoped
+     * (non-`'full'`) write carries its `staticComponentsBaseline` forward
+     * verbatim — `mach build faster` does not rebake `components.conf`
+     * registrations, so the last FULL build stays the honest anchor for the
+     * compiled StaticComponents table.
+     */
+    previousBaseline?: BuildBaseline | undefined;
+    /** Invocation shape that produced this baseline. */
+    recordedBy?: string | undefined;
+    /**
+     * `'auto'` (default) refreshes the static-components anchor whenever the
+     * coverage claim is `'full'` or absent. `'refresh'` records it even for a
+     * scoped coverage claim whose implementation escalated to a full build.
+     * `'carry-forward'` always keeps the previous anchor: needed by
+     * `--extend-coverage`, whose union can EVALUATE to `'full'` while the
+     * build that produced it was still a scoped `mach build faster` that did
+     * not rebake the compiled table.
+     */
+    staticComponentsHandling?: 'auto' | 'refresh' | 'carry-forward' | undefined;
+    /**
+     * Which mach build produced this baseline (default `'full'`). A
+     * `'faster'` write carries the previous record's `jar.mn` fingerprints
+     * forward instead of refreshing them — see
+     * {@link BuildBaseline.buildInputFingerprints}. Every caller that ran
+     * `mach build faster` MUST say so, or the next pre-test build skips an
+     * escalation no full build has honoured.
+     */
+    buildKind?: BaselineBuildKind | undefined;
+}
 /**
  * Records a successful build by writing a fresh baseline marker. Captures
  * engine HEAD SHA (or an empty string when the engine has no HEAD yet) and
  * the current binaryName. Caller is responsible for only invoking this
  * after the build exit code was zero.
  *
- * @param projectRoot - Root directory of the project
- * @param engineDir - Path to the engine directory
- * @param binaryName - Current `binaryName` from fireforge.json
- * @param testPackagingCoverage - Coverage claim of the packaged test
- *   runtime this build produced (`'full'`, or the scoped request paths of
- *   a `test --build` invocation). Omitted → field left off the marker.
- * @param previousBaseline - The baseline this write replaces, when the
- *   caller has it. A scoped (non-`'full'`) write carries its
- *   `staticComponentsBaseline` forward verbatim — `mach build faster`
- *   does not rebake `components.conf` registrations, so the last FULL
- *   build stays the honest anchor for the compiled StaticComponents table.
- * @param recordedBy - Invocation shape that produced this baseline.
- * @param staticComponentsHandling - `'auto'` (default) refreshes the
- *   static-components anchor whenever the coverage claim is `'full'` or
- *   absent. `'refresh'` records it even for a scoped coverage claim whose
- *   implementation escalated to a full build. `'carry-forward'` always
- *   keeps the previous anchor: needed by `--extend-coverage`, whose union
- *   can EVALUATE to `'full'` while the build that produced it was still a
- *   scoped `mach build faster` that did not rebake the compiled table.
- * @param buildKind - Which mach build produced this baseline (default
- *   `'full'`). A `'faster'` write carries the previous record's `jar.mn`
- *   fingerprints forward instead of refreshing them — see
- *   {@link BuildBaseline.buildInputFingerprints}. Every caller that ran
- *   `mach build faster` MUST say so, or the next pre-test build skips an
- *   escalation no full build has honoured.
+ * @param options - See {@link WriteBuildBaselineOptions}
  */
-export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage, previousBaseline?: BuildBaseline, recordedBy?: string, staticComponentsHandling?: 'auto' | 'refresh' | 'carry-forward', buildKind?: BaselineBuildKind): Promise<void>;
+export declare function writeBuildBaseline(options: WriteBuildBaselineOptions): Promise<void>;

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

@@ -16,12 +16,12 @@
  * on successful build completion; a failed build does not update it, so a
  * subsequent run still audits against the last known-good tree.
  */
-import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { mapWithConcurrency } from '../utils/concurrency.js';
 import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { sha256Hex } from '../utils/hash.js';
 import { verbose } from '../utils/logger.js';
 import { isBuildInputPath, isJarManifestPath, isPackageablePath, isXpcomManifestPath, } from './build-audit.js';
 import { DELETED_FILE_FINGERPRINT, } from './build-baseline-types.js';
@@ -36,7 +36,7 @@ import { getUntrackedFiles } from './git-status.js';
  */
 const FINGERPRINT_IO_CONCURRENCY = 16;
 /** Name of the last-build marker file under `.fireforge/`. */
-export const BUILD_BASELINE_FILENAME = 'last-build.json';
+const BUILD_BASELINE_FILENAME = 'last-build.json';
 /**
  * Resolves the on-disk path of the build baseline marker.
  * @param projectRoot - Root directory of the project
@@ -71,33 +71,10 @@ export async function readBuildBaseline(projectRoot) {
  * the current binaryName. Caller is responsible for only invoking this
  * after the build exit code was zero.
  *
- * @param projectRoot - Root directory of the project
- * @param engineDir - Path to the engine directory
- * @param binaryName - Current `binaryName` from fireforge.json
- * @param testPackagingCoverage - Coverage claim of the packaged test
- *   runtime this build produced (`'full'`, or the scoped request paths of
- *   a `test --build` invocation). Omitted → field left off the marker.
- * @param previousBaseline - The baseline this write replaces, when the
- *   caller has it. A scoped (non-`'full'`) write carries its
- *   `staticComponentsBaseline` forward verbatim — `mach build faster`
- *   does not rebake `components.conf` registrations, so the last FULL
- *   build stays the honest anchor for the compiled StaticComponents table.
- * @param recordedBy - Invocation shape that produced this baseline.
- * @param staticComponentsHandling - `'auto'` (default) refreshes the
- *   static-components anchor whenever the coverage claim is `'full'` or
- *   absent. `'refresh'` records it even for a scoped coverage claim whose
- *   implementation escalated to a full build. `'carry-forward'` always
- *   keeps the previous anchor: needed by `--extend-coverage`, whose union
- *   can EVALUATE to `'full'` while the build that produced it was still a
- *   scoped `mach build faster` that did not rebake the compiled table.
- * @param buildKind - Which mach build produced this baseline (default
- *   `'full'`). A `'faster'` write carries the previous record's `jar.mn`
- *   fingerprints forward instead of refreshing them — see
- *   {@link BuildBaseline.buildInputFingerprints}. Every caller that ran
- *   `mach build faster` MUST say so, or the next pre-test build skips an
- *   escalation no full build has honoured.
+ * @param options - See {@link WriteBuildBaselineOptions}
  */
-export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline, recordedBy, staticComponentsHandling = 'auto', buildKind = 'full') {
+export async function writeBuildBaseline(options) {
+    const { projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline, recordedBy, staticComponentsHandling = 'auto', buildKind = 'full', } = options;
     let engineHeadSha = '';
     try {
         engineHeadSha = await getHead(engineDir);
@@ -224,7 +201,7 @@ async function collectDirtyFingerprints(engineDir, includePath, contextLabel) {
         const entries = await mapWithConcurrency(included, FINGERPRINT_IO_CONCURRENCY, async (relPath) => {
             try {
                 const buffer = await readFile(join(engineDir, relPath));
-                return [relPath, createHash('sha256').update(buffer).digest('hex')];
+                return [relPath, sha256Hex(buffer)];
             }
             catch (fileError) {
                 if (getNodeErrorCode(fileError) === 'ENOENT') {

package/dist/src/core/build-jar-escalation.js

@@ -30,6 +30,7 @@
  * error direction stays the slow-but-correct one.
  */
 import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { isJarManifestPath } from './build-audit.js';
@@ -82,7 +83,7 @@ export async function evaluateJarManifestEscalation(engineDir, changedPaths, bas
         }
         catch (error) {
             // Fail closed: an unanswerable "is this new?" keeps the old rule.
-            verbose(`jar escalation: could not classify engine/${path} (${String(error)}); escalating.`);
+            verbose(`jar escalation: could not classify engine/${path} (${toError(error).message}); escalating.`);
             causes.push({ path, reason: 'could not determine whether the manifest is new' });
             continue;
         }
@@ -95,7 +96,7 @@ export async function evaluateJarManifestEscalation(engineDir, changedPaths, bas
             body = await readText(join(engineDir, path));
         }
         catch (error) {
-            verbose(`jar escalation: could not read engine/${path} (${String(error)}); escalating.`);
+            verbose(`jar escalation: could not read engine/${path} (${toError(error).message}); escalating.`);
             causes.push({ path, reason: 'manifest could not be read' });
             continue;
         }

package/dist/src/core/build-overwrite-guard.js

@@ -143,7 +143,7 @@ export function formatUnexportedDriftWarning(files) {
         const owner = entry.owner !== undefined ? ` (owned by ${entry.owner})` : '';
         return `  ${entry.file} [${entry.classification}]${owner}`;
     });
-    return (`This build is about to rewrite ${String(files.length)} engine file(s) from FireForge-owned ` +
+    return (`This build is about to rewrite ${files.length} engine file(s) from FireForge-owned ` +
         'sources, and their current content matches NEITHER a patch body NOR the pristine ' +
         'baseline — so the edits below are recorded nowhere and the build will destroy them:\n' +
         `${rows.join('\n')}\n\n` +

package/dist/src/core/build-prepare.d.ts

@@ -36,14 +36,6 @@ export interface PrepareBuildOptions {
      */
     refuseUnexportedDrift?: boolean | undefined;
 }
-/**
- * Packaging manifests whose graph/destination directories MAY need a full
- * build. Path-shape only: {@link evaluateJarManifestEscalation} decides
- * whether a given changed manifest actually forces one (a new manifest, or
- * one that redirects its install base directory), so an entry added to an
- * existing `dist/bin` manifest no longer costs a ~10-minute build.
- */
-export declare function requiresFullBuildForIncrementalTest(path: string): boolean;
 /**
  * Describes an exit code in the shell's 128+N signal convention. Truncated
  * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG

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

@@ -24,16 +24,6 @@ import { generateMozconfig, runMachCapture } from './mach.js';
 import { explainMachError } from './mach-error-hints.js';
 /** Path fragments of files whose edits invalidate the recursive-make backend. */
 const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
-/**
- * Packaging manifests whose graph/destination directories MAY need a full
- * build. Path-shape only: {@link evaluateJarManifestEscalation} decides
- * whether a given changed manifest actually forces one (a new manifest, or
- * one that redirects its install base directory), so an entry added to an
- * existing `dist/bin` manifest no longer costs a ~10-minute build.
- */
-export function requiresFullBuildForIncrementalTest(path) {
-    return isJarManifestPath(path);
-}
 /**
  * Build-input manifests changed since the last SUCCESSFUL build — not
  * merely dirty against HEAD. `collectChangedEnginePaths` unions the
@@ -126,9 +116,14 @@ function buildConfigureFailureError(captured) {
  * @param baseline - Last successful build's baseline
  */
 async function decideJarEscalation(engineDir, changed, baseline) {
-    const decision = await evaluateJarManifestEscalation(engineDir, changed.filter(requiresFullBuildForIncrementalTest), baseline);
+    // Packaging manifests whose graph/destination directories MAY need a full
+    // build. Path-shape only: `evaluateJarManifestEscalation` decides whether a
+    // given changed manifest actually forces one (a new manifest, or one that
+    // redirects its install base directory), so an entry added to an existing
+    // `dist/bin` manifest no longer costs a ~10-minute build.
+    const decision = await evaluateJarManifestEscalation(engineDir, changed.filter(isJarManifestPath), baseline);
     if (decision.cleared.length > 0) {
-        verbose(`jar escalation: ${String(decision.cleared.length)} changed jar.mn add entries to an existing dist/bin manifest; not escalating for ${decision.cleared.join(', ')}.`);
+        verbose(`jar escalation: ${decision.cleared.length} changed jar.mn add entries to an existing dist/bin manifest; not escalating for ${decision.cleared.join(', ')}.`);
     }
     return decision.escalate ? formatJarEscalationNotice(decision) : undefined;
 }

package/dist/src/core/config-paths.d.ts

@@ -2,16 +2,12 @@
  * Project path derivation from a root directory.
  */
 import type { ProjectPaths } from '../types/config.js';
-/** Name of the configuration file */
-export declare const CONFIG_FILENAME = "fireforge.json";
 /** Name of the fireforge data directory */
 export declare const FIREFORGE_DIR = ".fireforge";
-/** Name of the state file */
-export declare const STATE_FILENAME = "state.json";
 /** Supported top-level fireforge.json keys backed by the current schema. */
-export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "test", "externalToolchains", "license", "wire", "patchLint", "patchPolicy", "typecheck", "markerComment"];
+export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "buildAudit", "test", "externalToolchains", "license", "wire", "patchLint", "patchPolicy", "typecheck", "markerComment"];
 /** Supported config paths that can be read or set without --force. */
-export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "firefox.candidate", "build", "build.jobs", "test", "test.canaryPath", "test.canaryTimeoutSeconds", "externalToolchains", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.checkJsTestFiles", "patchLint.checkJsTestShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "firefox.candidate", "firefox.allowUnverifiedDownload", "build", "build.jobs", "test", "test.canaryPath", "test.canaryTimeoutSeconds", "externalToolchains", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.checkJsTestFiles", "patchLint.checkJsTestShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

package/dist/src/core/config-paths.js

@@ -4,11 +4,11 @@
  */
 import { join } from 'node:path';
 /** Name of the configuration file */
-export const CONFIG_FILENAME = 'fireforge.json';
+const CONFIG_FILENAME = 'fireforge.json';
 /** Name of the fireforge data directory */
 export const FIREFORGE_DIR = '.fireforge';
 /** Name of the state file */
-export const STATE_FILENAME = 'state.json';
+const STATE_FILENAME = 'state.json';
 /** Name of the engine directory */
 const ENGINE_DIR = 'engine';
 /** Name of the patches directory */
@@ -25,6 +25,7 @@ export const SUPPORTED_CONFIG_ROOT_KEYS = [
     'binaryName',
     'firefox',
     'build',
+    'buildAudit',
     'test',
     'externalToolchains',
     'license',
@@ -46,6 +47,7 @@ export const SUPPORTED_CONFIG_PATHS = [
     'firefox.product',
     'firefox.sha256',
     'firefox.candidate',
+    'firefox.allowUnverifiedDownload',
     'build',
     'build.jobs',
     'test',