@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -0,0 +1,57 @@
+/**
+ * Why a changed engine path was not audited.
+ *
+ * The first four name skips that already existed as unstructured
+ * `verbose()` strings. The last four are the 0.46.0 classifiers.
+ */
+export type AuditSkipReason = 'not-packageable' | 'platform-gated' | 'platform-gated-ancestor' | 'tests-not-packaged' | 'source-unreadable' | 'branding-not-selected' | 'storybook-story' | 'declared-unpackaged';
+/** Render order for the `Packaged:` summary's per-class breakdown. */
+export declare const AUDIT_SKIP_REASONS: readonly AuditSkipReason[];
+/** True for a Storybook story module. */
+export declare function isStorybookStoryPath(sourcePath: string): boolean;
+/**
+ * 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 declare function resolveSelectedBranding(engineDir: string): Promise<string | 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 declare function isUnselectedBrandingPath(sourcePath: string, selectedBranding: string | undefined): boolean;
+/** One `buildAudit.unpackaged` carve-out from `fireforge.json`. */
+export interface UnpackagedDeclaration {
+    /** Engine-relative path or glob. */
+    path: string;
+    /** Why this file is deliberately never packaged. Required, non-empty. */
+    reason: string;
+}
+/**
+ * Finds the declaration admitting `sourcePath`, if any.
+ *
+ * Exact match or a `*`-within-one-segment glob, matching the
+ * `support-files` matcher's narrowness: `**` and other cross-directory
+ * shapes are not accepted, because a carve-out that silently widens is the
+ * failure this feature is warned against.
+ *
+ * @param sourcePath - Engine-relative POSIX path
+ * @param declarations - The project's `buildAudit.unpackaged` entries
+ */
+export declare function matchUnpackagedDeclaration(sourcePath: string, declarations: readonly UnpackagedDeclaration[]): UnpackagedDeclaration | undefined;

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. This replaces a run
+ * reporting `4 missing` with zero real misses.
+ */
+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 narrowness: `**` and other cross-directory
+ * shapes are not accepted, because a carve-out that silently widens is 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-transforms.d.ts

@@ -1,7 +1,7 @@
 /**
  * Returns the expected chrome-tree suffix for an engine-relative POSIX
- * source path when the path falls under a known transform prefix;
- * undefined otherwise.
+ * source path when the path falls under a known transform prefix.
+ * Returns undefined otherwise.
  *
  * @param source Engine-relative POSIX source path.
  */

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

@@ -16,7 +16,7 @@
  * implied chrome suffix is a confident match: the scorer never runs and the
  * structural-relation check is bypassed.
  *
- * Scope is intentionally narrow — only subtrees whose packaging target is
+ * Scope is narrow: only subtrees whose packaging target is
  * stable across forks. A fork that reroutes a known subtree can still win by
  * adding `(source)` annotations in its own `jar.mn`, which
  * `resolveArtifactByRegistration` consults first.
@@ -47,8 +47,8 @@ const KNOWN_TRANSFORMS = [
 ];
 /**
  * Returns the expected chrome-tree suffix for an engine-relative POSIX
- * source path when the path falls under a known transform prefix;
- * undefined otherwise.
+ * source path when the path falls under a known transform prefix.
+ * Returns undefined otherwise.
  *
  * @param source Engine-relative POSIX source path.
  */

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

@@ -1,9 +1,10 @@
+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
  * (`jar.mn`, `moz.build`, `moz.configure`, `Makefile.in`, `mozbuild.in`).
- * Excluded from the packaging audit and from `packageableFingerprints`;
- * fingerprinted separately as `buildInputFingerprints` so `build-prepare`
+ * Excluded from the packaging audit and from `packageableFingerprints`.
+ * Fingerprinted separately as `buildInputFingerprints` so `build-prepare`
  * can tell "dirty against HEAD" from "changed since the last successful
  * build".
  *
@@ -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[];
 }
 /**
@@ -57,11 +68,11 @@ export interface AuditSummary {
  */
 export declare function isPackageablePath(sourcePath: string): boolean;
 /**
- * Decides whether a source path is an XPCOM static-component manifest —
+ * Decides whether a source path is an XPCOM static-component manifest,
  * i.e. a file whose registrations are baked into the compiled
- * StaticComponents table at FULL-build time rather than packaged into
+ * StaticComponents table at full-build time rather than packaged into
  * `dist/`. This basename check is the single extension point for that
- * classification; parsing `moz.build` `XPCOM_MANIFESTS` entries to follow
+ * classification. Parsing `moz.build` `XPCOM_MANIFESTS` entries to follow
  * renamed manifests is out of scope.
  *
  * @param sourcePath Engine-relative POSIX path.
@@ -71,11 +82,13 @@ export declare function isXpcomManifestPath(sourcePath: string): boolean;
 /**
  * Runs the post-build audit. Emits per-file warnings for missing or
  * stale artifacts and a summary info line at the end. Always returns
- * the summary; never throws on audit failure (the audit itself must
+ * the summary. Never throws on audit failure (the audit itself must
  * never fail a successful build).
  * @param projectRoot Root of the project (reserved for future fork-specific rules).
  * @param engineDir Path to the engine directory.
  * @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

@@ -13,7 +13,7 @@
  *     (git-tracked diff + workdir modifications).
  *   - For each file whose path pattern implies packaging, it resolves
  *     the expected dist artifact under obj-star/dist/binary-name-star.
- *   - A warning fires when the expected artifact is missing OR when its
+ *   - A warning fires when the expected artifact is missing or when its
  *     mtime is older than the engine source (the build was reported
  *     successful but that file's path never flowed through packaging).
  *   - False positives are acceptable at this stage: fork-specific packaging
@@ -22,9 +22,9 @@
  *
  * Routing rules:
  *   - Build inputs (jar.mn, moz.build, Makefile.in, moz.configure) are
- *     skipped; they are consumed, not packaged.
+ *     skipped. They are consumed, not packaged.
  *   - Test sources (anything under /test(s)/, browser_*.js, test_*.js)
- *     are looked up under _tests/, not dist/ — that's where mach copies
+ *     are looked up under _tests/, not dist/, which is where mach copies
  *     them.
  *   - Files inside an `if CONFIG[...]:` block in moz.build that gates
  *     off on the current host are skipped (Windows stubinstaller CSS on
@@ -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';
@@ -60,12 +61,12 @@ const PACKAGEABLE_EXTENSIONS = [
 ];
 /** Path fragments whose contents are packaged regardless of extension. */
 const PACKAGEABLE_PATH_FRAGMENTS = ['/app/profile/', '/chrome/', '/locales/'];
-/** Directories that are build artifacts, not source — never audited. */
+/** Directories that are build artifacts, not source. Never audited. */
 const IGNORE_PATH_FRAGMENTS = ['obj-', 'node_modules/', '.git/', '.cargo/', '.mozbuild/'];
 /**
  * Basenames that are build-system inputs, not packaged artifacts. `jar.mn`
- * is consumed to produce chrome registrations; `moz.build` / `moz.configure`
- * / `Makefile.in` feed the build backend; none ship in the bundle. Auditing
+ * is consumed to produce chrome registrations. `moz.build` / `moz.configure`
+ * / `Makefile.in` feed the build backend. None ship in the bundle. Auditing
  * them guarantees a false positive on every edit, and worse, an unrelated
  * upstream `moz.build` sitting at e.g. `MyBrowser.app/Contents/moz.build`
  * gets matched as a "stale artifact" of an entirely different file.
@@ -80,8 +81,8 @@ const BUILD_INPUT_BASENAMES = new Set([
 /**
  * True for the build-input manifests the build consumes but never packages
  * (`jar.mn`, `moz.build`, `moz.configure`, `Makefile.in`, `mozbuild.in`).
- * Excluded from the packaging audit and from `packageableFingerprints`;
- * fingerprinted separately as `buildInputFingerprints` so `build-prepare`
+ * Excluded from the packaging audit and from `packageableFingerprints`.
+ * Fingerprinted separately as `buildInputFingerprints` so `build-prepare`
  * can tell "dirty against HEAD" from "changed since the last successful
  * build".
  *
@@ -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,
@@ -118,7 +123,7 @@ export function isPackageablePath(sourcePath) {
     if (isBuildInputPath(sourcePath))
         return false;
     // `.inc.xhtml` fragments are consumed via `#include` from a registered
-    // chrome document and resolved at packaging time — they never ship as a
+    // chrome document and resolved at packaging time. They never ship as a
     // standalone packaged artifact, so auditing them flags a wired
     // `*.inc.xhtml` as "missing packaged artifact" even though `register`
     // correctly refuses to register it. Mirror the carve-out the register
@@ -136,18 +141,18 @@ export function isPackageablePath(sourcePath) {
     return false;
 }
 /**
- * Decides whether a source path is an XPCOM static-component manifest —
+ * Decides whether a source path is an XPCOM static-component manifest,
  * i.e. a file whose registrations are baked into the compiled
- * StaticComponents table at FULL-build time rather than packaged into
+ * StaticComponents table at full-build time rather than packaged into
  * `dist/`. This basename check is the single extension point for that
- * classification; parsing `moz.build` `XPCOM_MANIFESTS` entries to follow
+ * classification. Parsing `moz.build` `XPCOM_MANIFESTS` entries to follow
  * renamed manifests is out of scope.
  *
  * @param sourcePath Engine-relative POSIX path.
  * @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
@@ -199,8 +204,8 @@ async function resolveTestsRoot(engineDir) {
 /**
  * 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,
+ * 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';
@@ -219,7 +224,7 @@ async function hasPackagedTestsMarker(testsRoot) {
 }
 /**
  * Resolves the search roots an individual source path should be looked
- * up under. Test-shaped paths get `_tests/`; everything else gets `dist/`.
+ * up under. Test-shaped paths get `_tests/`. Everything else gets `dist/`.
  */
 function searchRootsFor(source, distRoot, testsRoot) {
     if (isTestPath(source)) {
@@ -232,7 +237,7 @@ function searchRootsFor(source, distRoot, testsRoot) {
  * 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 agree too. Candidates sharing only the basename are
- * classified as missing — warning the operator to check registration —
+ * classified as missing (warning the operator to check registration)
  * rather than emitting a misleading stale comparison against an unrelated
  * file of the same name.
  *
@@ -244,21 +249,21 @@ function searchRootsFor(source, distRoot, testsRoot) {
 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
+ * 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.
+ * same-basename file picked up by the basename walker. That class of
+ * warning is worse than `missing` because it reads as "your build
+ * dropped this file" when the match is spurious.
  */
 function isConfidentMatch(source, candidate) {
     if (countTrailingSegmentMatches(source, candidate) >= MIN_TRAILING_SEGMENT_OVERLAP) {
         return true;
     }
     // The candidate is an absolute path built by `join` over a dist/ walk, so on
-    // Windows it arrives backslash-separated; a `/`-only split collapses it into
+    // Windows it arrives backslash-separated. A `/`-only split collapses it into
     // one segment and the non-generic-segment bonus can never fire.
     const sourceSegs = normalizePathSlashes(source).split('/').filter(Boolean);
     const candSegs = normalizePathSlashes(candidate).split('/').filter(Boolean);
@@ -273,6 +278,56 @@ 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 intended: `--expect-unmanaged` 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 +335,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 +367,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;
@@ -303,8 +376,8 @@ async function auditSinglePath(source, ctx) {
         sourceMtime = sourceStat.mtimeMs;
     }
     catch {
-        // Deletion that didn't propagate — distinct class of bug, not audited yet.
-        return { source, artifact: undefined, status: 'skipped' };
+        // Deletion that didn't propagate. Distinct class of bug, not audited yet.
+        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)`
@@ -350,7 +423,7 @@ async function auditSinglePath(source, ctx) {
  * 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.
+ * no dist candidate endswith the target. Undefined otherwise.
  */
 async function reportRegistrationMiss(engineDir, source, roots) {
     const hit = await findRegisteredTarget(engineDir, source);
@@ -375,7 +448,7 @@ async function reportRegistrationMiss(engineDir, source, roots) {
 /**
  * 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
+ * anchored path (already confident) and the heuristic fallback
  * (which still applies the structural-relatedness check before claiming
  * `stale`).
  */
@@ -466,8 +539,9 @@ async function resolveAuditOwnership(projectRoot) {
 /**
  * Renders the ownership suffix for one audit notice: the owning patch, or
  * an explicit `unmanaged` mark. An empty map (no queue, unreadable
- * manifest) renders nothing rather than claiming everything is unmanaged —
- * "unmanaged" must mean "checked and unowned", never "could not check".
+ * manifest) renders nothing rather than claiming everything is unmanaged,
+ * since "unmanaged" must mean "checked and unowned", never "could not
+ * check".
  */
 function describeOwnership(ownersByPath, source) {
     if (ownersByPath.size === 0)
@@ -481,19 +555,20 @@ function describeOwnership(ownersByPath, source) {
 /**
  * Runs the post-build audit. Emits per-file warnings for missing or
  * stale artifacts and a summary info line at the end. Always returns
- * the summary; never throws on audit failure (the audit itself must
+ * the summary. Never throws on audit failure (the audit itself must
  * never fail a successful build).
  * @param projectRoot Root of the project (reserved for future fork-specific rules).
  * @param engineDir Path to the engine directory.
  * @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);
@@ -509,23 +584,50 @@ export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
     }
     // Ownership, resolved once for the whole audit. The notices key on "was
     // touched", which on a shared checkout means any concurrent session's
-    // dirty files — so an operator gets a registration-shaped warning about a
+    // dirty files, so an operator gets a registration-shaped warning about a
     // file they never edited and has to census ownership by hand to dismiss
-    // it. FireForge already resolves this for `status --ownership`; carrying
-    // it here turns a three-line mystery into three dismissible lines.
+    // it. FireForge already resolves this for `status --ownership`. Carrying
+    // it here lets the operator dismiss those lines directly.
     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(', ')})`;
+}