@hominis/fireforge 0.45.0 → 0.46.0

package/dist/src/commands/token-list.js

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `token list` and `token show` — the read half of design-token management.
+ *
+ * `token add` requires `--category` and refuses an unknown one, but nothing
+ * reported the categories a project has, so naming one meant hand-parsing a
+ * neighbouring `= Category =` banner out of the tokens CSS. Both commands
+ * read through `token-inventory.ts`, which is built on the same banner and
+ * `:root`-bounds primitives `token add` and `token coverage` use — a second
+ * tokens-CSS parser would let the report and the writer disagree about
+ * which section a token lives in.
+ *
+ * Helper module: no registrar, called from `token.ts`.
+ */
+import { join } from 'node:path';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { collectTokenBlockValues, collectTokenInventory, } from '../core/token-inventory.js';
+import { getTokensCssPath } from '../core/token-manager.js';
+import { GeneralError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { info, intro, outro, setMachineOutputMode, setStdoutSealed } from '../utils/logger.js';
+import { emitMachineError, MACHINE_OUTPUT_SCHEMA_VERSION } from '../utils/machine-output.js';
+/** Reads the project's tokens CSS as lines, refusing when it is absent. */
+async function readTokensCssLines(projectRoot) {
+    const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
+    const tokensCssPath = getTokensCssPath(config.binaryName);
+    const filePath = join(paths.engine, tokensCssPath);
+    if (!(await pathExists(filePath))) {
+        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}. Run "fireforge furnace init" to seed it.`);
+    }
+    return { lines: (await readText(filePath)).split('\n'), tokensCssPath };
+}
+/** Applies the `--category` filter, refusing a name the file does not carry. */
+function filterByCategory(groups, category, tokensCssPath) {
+    const matched = groups.filter((group) => group.category === category);
+    if (matched.length > 0)
+        return matched;
+    // Same "name the alternatives" contract `token add` gives for an unknown
+    // category — a filter that silently prints nothing reads as "this
+    // category is empty", which is a different fact.
+    const available = groups
+        .map((group) => group.category)
+        .filter((name) => name !== null);
+    const suffix = available.length > 0
+        ? `Available categories: ${available.map((name) => `"${name}"`).join(', ')}.`
+        : 'The file declares no category banners.';
+    throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n${suffix}`);
+}
+/**
+ * Lists the categories declared in the tokens CSS with their token names,
+ * in file order.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param options - Filter and output-mode options
+ */
+export async function tokenListCommand(projectRoot, options = {}) {
+    if (options.json === true) {
+        // stdout belongs exclusively to the payload from here on; a later
+        // diagnostic (including withErrorHandling's) routes to stderr.
+        setMachineOutputMode(true);
+        try {
+            const { lines, tokensCssPath } = await readTokensCssLines(projectRoot);
+            const all = collectTokenInventory(lines);
+            const groups = options.category === undefined
+                ? all
+                : filterByCategory(all, options.category, tokensCssPath);
+            process.stdout.write(`${JSON.stringify({
+                schemaVersion: MACHINE_OUTPUT_SCHEMA_VERSION,
+                tokensCssPath,
+                categories: groups.map((group) => ({
+                    category: group.category,
+                    tokens: group.tokens.map((token) => ({
+                        name: token.name,
+                        line: token.line,
+                        value: token.value,
+                    })),
+                })),
+            }, null, 2)}\n`);
+            setStdoutSealed(true);
+        }
+        catch (error) {
+            emitMachineError('token-list-failed', toError(error).message);
+        }
+        finally {
+            setMachineOutputMode(false);
+        }
+        return;
+    }
+    const { lines, tokensCssPath } = await readTokensCssLines(projectRoot);
+    const all = collectTokenInventory(lines);
+    const groups = options.category === undefined ? all : filterByCategory(all, options.category, tokensCssPath);
+    intro('Design Tokens');
+    info(tokensCssPath);
+    if (groups.length === 0) {
+        outro('No token declarations found in the :root block');
+        return;
+    }
+    let total = 0;
+    for (const group of groups) {
+        info(`  ${group.category ?? '(no category)'} — ${String(group.tokens.length)} token(s)`);
+        for (const token of group.tokens) {
+            info(`    ${token.name}`);
+        }
+        total += group.tokens.length;
+    }
+    outro(`${String(groups.length)} category/categories, ${String(total)} token(s)`);
+}
+/**
+ * Reports one token: the category that owns it and the value it takes in
+ * every block that declares it.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param tokenName - Custom-property name, with or without the leading `--`
+ * @param options - Output-mode options
+ */
+export async function tokenShowCommand(projectRoot, tokenName, options = {}) {
+    const emit = async () => {
+        const { lines, tokensCssPath } = await readTokensCssLines(projectRoot);
+        const name = tokenName.startsWith('--') ? tokenName : `--${tokenName}`;
+        const declarations = collectTokenBlockValues(lines, name);
+        if (declarations.length === 0) {
+            throw new GeneralError(`Token "${name}" is not declared in ${tokensCssPath}. ` +
+                'Run "fireforge token list" to see the declared tokens.');
+        }
+        const owning = collectTokenInventory(lines).find((group) => group.tokens.some((token) => token.name === name));
+        return { tokensCssPath, name, category: owning?.category ?? null, declarations };
+    };
+    if (options.json === true) {
+        setMachineOutputMode(true);
+        try {
+            const report = await emit();
+            process.stdout.write(`${JSON.stringify({ schemaVersion: MACHINE_OUTPUT_SCHEMA_VERSION, ...report }, null, 2)}\n`);
+            setStdoutSealed(true);
+        }
+        catch (error) {
+            emitMachineError('token-show-failed', toError(error).message);
+        }
+        finally {
+            setMachineOutputMode(false);
+        }
+        return;
+    }
+    const report = await emit();
+    intro('Design Token');
+    info(`${report.name} — category: ${report.category ?? '(no category)'}`);
+    info(report.tokensCssPath);
+    for (const declaration of report.declarations) {
+        info(`  ${declaration.block}: ${declaration.value}  (line ${String(declaration.line)})`);
+    }
+    outro(`${String(report.declarations.length)} declaration(s)`);
+}

package/dist/src/commands/token.js

@@ -10,6 +10,7 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { normalizeTokenName } from '../utils/validation.js';
 import { tokenCoverageCommand } from './token-coverage.js';
+import { tokenListCommand, tokenShowCommand } from './token-list.js';
 async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
     if (rawTokenName.startsWith('--')) {
         return normalizeTokenName(rawTokenName);
@@ -52,7 +53,7 @@ function reportSkippedToken(tokenName, result, options) {
         ? `:root${options.variant}`
         : `category "${result.skippedExisting?.category ?? options.category ?? ''}"`;
     const where = result.skippedExisting
-        ? ` in ${scope} (line ${String(result.skippedExisting.line)}), unchanged`
+        ? ` in ${scope} (line ${result.skippedExisting.line}), unchanged`
         : '';
     info(`Token ${tokenName} already exists${where} (skipped)`);
 }
@@ -201,6 +202,21 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
             }),
         });
     }));
+    token
+        .command('list')
+        .description('List the design-token categories declared in the tokens CSS with their token names, in file order')
+        .option('--category <name>', 'Restrict the report to one category')
+        .option('--json', 'Emit the machine-readable envelope on stdout (see docs/machine-output.md)')
+        .action(withErrorHandling(async (options) => {
+        await tokenListCommand(getProjectRoot(), pickDefined({ category: options.category, json: options.json }));
+    }));
+    token
+        .command('show <token-name>')
+        .description('Show one token: its category, the value it takes in every declaring block, and where it is defined. The leading `--` is optional; with it, use the `--` separator first (e.g. `fireforge token show -- --my-token`).')
+        .option('--json', 'Emit the machine-readable envelope on stdout (see docs/machine-output.md)')
+        .action(withErrorHandling(async (tokenName, options) => {
+        await tokenShowCommand(getProjectRoot(), tokenName, pickDefined({ json: options.json }));
+    }));
     token
         .command('coverage')
         .description('Measure design token usage across modified CSS files')

package/dist/src/commands/tree.js

@@ -290,7 +290,7 @@ async function treeExecCommand(projectRoot, name, args) {
         setStdoutSealed(true);
     });
     if (exitCode !== 0) {
-        throw new GeneralError(`tree exec: fireforge ${args.join(' ')} exited with code ${String(exitCode)}.`);
+        throw new GeneralError(`tree exec: fireforge ${args.join(' ')} exited with code ${exitCode}.`);
     }
 }
 /** Registers the tree command group on the CLI program. */
@@ -298,7 +298,12 @@ export function registerTree(program, context) {
     const { getProjectRoot, withErrorHandling } = context;
     const tree = program
         .command('tree')
-        .description('Manage copy-on-write verification clones of this project for concurrent read-mostly work (lint, typecheck, status, verify, export/re-export --dry-run; build-less test with create --with-objdir). Mutation commands are refused inside a tree.');
+        .description('Manage copy-on-write verification clones of this project for concurrent read-mostly work (lint, typecheck, status, verify, export/re-export --dry-run; build-less test with create --with-objdir). Mutation commands are refused inside a tree.')
+        // No-subcommand contract shared with `patch`/`token`/`furnace`: help on
+        // stdout, exit 0 (see `handleParseError` for the groups without an action).
+        .action(() => {
+        tree.outputHelp();
+    });
     addWaitLockOption(tree
         .command('create <name>')
         .description('Clone the project (engine included, obj-* excluded) into .fireforge/trees/<name> using filesystem copy-on-write (APFS clonefile / btrfs-XFS reflink). Refuses on filesystems without CoW support unless --force-copy explicitly accepts a full physical copy.')

package/dist/src/commands/typecheck.js

@@ -57,8 +57,8 @@ export function resolveTypecheckProjects(configTypecheck, override) {
  */
 function formatIssue(projectRoot, issue) {
     const file = relativeForDisplay(projectRoot, issue.file);
-    const codeLabel = issue.code > 0 ? ` TS${String(issue.code)}` : '';
-    return `[${issue.project}] ${file}:${String(issue.line)}:${String(issue.column)}${codeLabel} ${issue.message}`;
+    const codeLabel = issue.code > 0 ? ` TS${issue.code}` : '';
+    return `[${issue.project}] ${file}:${issue.line}:${issue.column}${codeLabel} ${issue.message}`;
 }
 /**
  * Top-level entry point invoked by the registered Commander action.
@@ -87,7 +87,7 @@ async function runTypecheckCommandBody(projectRoot, options) {
     // session never touched. Run the same reconciler `furnace deploy`/`sync`
     // use so typecheck checks against the current workspace.
     await regenerateStaleGeneratedJsconfig(projectRoot);
-    info(`Running typecheck across ${String(cfg.projects.length)} project(s): ${cfg.projects.join(', ')}`);
+    info(`Running typecheck across ${cfg.projects.length} project(s): ${cfg.projects.join(', ')}`);
     const results = await runTypecheck(projectRoot, cfg);
     // Fold the EXPORT-TIME authority into this pass. Per-patch lint runs
     // checkJs over the queue's patch-owned modules in relative isolation and
@@ -139,8 +139,8 @@ async function regenerateStaleGeneratedJsconfig(projectRoot) {
     if (!drift.changed)
         return;
     info(`Regenerating stale generated jsconfig ${furnaceConfig.typecheckJsconfig} before typecheck ` +
-        `(+${String(drift.added.length)} added, ~${String(drift.updated.length)} updated, ` +
-        `-${String(drift.pruned.length)} pruned).`);
+        `(+${drift.added.length} added, ~${drift.updated.length} updated, ` +
+        `-${drift.pruned.length} pruned).`);
     await syncFurnaceJsconfigPaths(projectRoot, furnaceConfig);
 }
 /**
@@ -171,10 +171,10 @@ export function reportResults(projectRoot, results, patchLintIssues = []) {
         for (const issue of errors)
             warn(formatIssue(projectRoot, issue));
     }
-    const summary = `Typecheck: ${String(totalErrors)} error(s), ${String(totalWarnings)} warning(s) across ` +
-        `${String(results.length)} project(s)` +
+    const summary = `Typecheck: ${totalErrors} error(s), ${totalWarnings} warning(s) across ` +
+        `${results.length} project(s)` +
         (patchLintIssues.length > 0
-            ? ` (including ${String(patchLintIssues.length)} per-patch checkJs finding(s))`
+            ? ` (including ${patchLintIssues.length} per-patch checkJs finding(s))`
             : '');
     if (totalErrors === 0) {
         success(summary);
@@ -183,7 +183,7 @@ export function reportResults(projectRoot, results, patchLintIssues = []) {
     }
     info(summary);
     outro('Typecheck failed');
-    throw new GeneralError(`Typecheck found ${String(totalErrors)} error(s) across ${String(results.length)} project(s).`);
+    throw new GeneralError(`Typecheck found ${totalErrors} error(s) across ${results.length} project(s).`);
 }
 /**
  * Registers the `typecheck` command on the CLI program.

package/dist/src/commands/wire.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join, relative } from 'node:path';
 import { Command } from 'commander';
-import { DEFAULT_BROWSER_SUBSCRIPT_DIR, wireSubscript } from '../core/browser-wire.js';
+import { DEFAULT_BROWSER_SUBSCRIPT_DIR, wireSubscript, } from '../core/browser-wire.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { furnaceConfigExists as checkFurnaceConfigExists, loadFurnaceConfig, } from '../core/furnace-config.js';
 import { consumeParserFallbackEvents } from '../core/parser-fallback.js';
@@ -13,6 +13,7 @@ import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { isContainedRelativePath, isExplicitAbsolutePath, isPathInsideRoot, stripEnginePrefix, toRootRelativePath, } from '../utils/paths.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 const BROWSER_BASE_DIR = 'browser/base';
 function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPath, options) {
     info('[dry-run] Would wire subscript:');
@@ -28,10 +29,10 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPa
         info(`  browser-init.js onUnload(): ${coerceToCall(options.destroy)}`);
     }
     if (domFilePath) {
-        const includePath = relative(join(engineDir, subscriptDir), join(engineDir, domFilePath)).replace(/\\/g, '/');
+        const includePath = normalizePathSlashes(relative(join(engineDir, subscriptDir), join(engineDir, domFilePath)));
         info(`  ${domTargetPath}: #include ${includePath}`);
     }
-    const relPath = relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)).replace(/\\/g, '/');
+    const relPath = normalizePathSlashes(relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)));
     info(`  jar.mn: content/browser/${name}.js (${relPath}/${name}.js)`);
     outro('Dry run complete');
 }

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

@@ -1,12 +1,5 @@
 import { FireForgeError } from '../errors/base.js';
 import type { ProjectLicense } from '../types/config.js';
-/**
- * Error thrown when branding operations fail.
- */
-export declare class BrandingError extends FireForgeError {
-    readonly code: 6;
-    get userMessage(): string;
-}
 /**
  * Error thrown when the generated `mozconfig` references a `--with-branding`
  * directory that does not match the branding tree FireForge set up. The

package/dist/src/core/branding.js

@@ -4,11 +4,12 @@ import { FireForgeError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
 import { copyDir, pathExists, readText, writeTextIfChanged } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { DEFAULT_LICENSE, getLicenseHeader } from './license-headers.js';
 /**
  * Error thrown when branding operations fail.
  */
-export class BrandingError extends FireForgeError {
+class BrandingError extends FireForgeError {
     code = ExitCode.PATCH_ERROR;
     get userMessage() {
         return `Branding Error: ${this.message}\n\nBranding is required to set MOZ_APP_VENDOR, MOZ_MACBUNDLE_ID, and other Firefox identity values.`;
@@ -361,7 +362,7 @@ export async function isBrandingSetup(engineDir, config) {
  * @returns true if the path is managed by branding tooling
  */
 export function isBrandingManagedPath(file, binaryName) {
-    const normalized = file.replace(/\\/g, '/');
+    const normalized = normalizePathSlashes(file);
     const brandingRoot = `browser/branding/${binaryName}`;
     return (normalized === 'browser/moz.configure' ||
         normalized === brandingRoot ||

package/dist/src/core/browser-wire.js

@@ -4,11 +4,14 @@ import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
 import { toRootRelativePath } from '../utils/paths.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { assertSnapshotted, createRollbackJournal, restoreRollbackJournal, snapshotFile, } from './furnace-rollback.js';
 import { registerBrowserContent } from './moz-manifest-register.js';
-import { DEFAULT_DOM_TARGET } from './wire-dom-fragment.js';
-import { addDestroyToBrowserInit, addDomFragment, addInitToBrowserInit, addSubscriptToBrowserMain, } from './wire-targets.js';
+import { addDestroyToBrowserInit } from './wire-destroy.js';
+import { addDomFragment, DEFAULT_DOM_TARGET } from './wire-dom-fragment.js';
+import { addInitToBrowserInit } from './wire-init.js';
+import { addSubscriptToBrowserMain } from './wire-subscript.js';
 export const DEFAULT_BROWSER_SUBSCRIPT_DIR = 'browser/base/content';
 const BROWSER_BASE_DIR = 'browser/base';
 /**
@@ -25,7 +28,7 @@ export async function wireSubscript(root, name, options = {}) {
     // Compute jar.mn source path relative to browser/base/
     let jarMnSourcePath;
     if (subscriptDir !== DEFAULT_BROWSER_SUBSCRIPT_DIR) {
-        const relPath = relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)).replace(/\\/g, '/');
+        const relPath = normalizePathSlashes(relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)));
         jarMnSourcePath = `${relPath}/${name}.js`;
     }
     if (options.dryRun) {

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

@@ -36,3 +36,32 @@ export declare function findEnclosingGate(content: string, basename: string): st
  * @returns Detection result
  */
 export declare function detectPlatformGate(engineDir: string, sourcePath: string): Promise<PlatformGateResult>;
+/**
+ * Result of an ancestor `DIRS +=` gate lookup.
+ */
+export interface AncestorDirsGateResult {
+    /** True when an ancestor's `DIRS` entry is gated off on this host. */
+    gatedOff: boolean;
+    /** The gate expression that excluded the directory. */
+    gateExpression?: string;
+    /** Engine-relative path of the `moz.build` carrying the gate. */
+    gateFile?: string;
+}
+/**
+ * Determines whether the source file's DIRECTORY is excluded from this
+ * build by a gate in an ANCESTOR `moz.build`.
+ *
+ * `detectPlatformGate` reads only the file's own nearest `moz.build`, which
+ * misses the common Firefox shape where the whole subtree is reached
+ * through a conditional `DIRS +=` one or more levels up: nothing in
+ * `toolkit/mozapps/defaultagent/moz.build` says "Windows only", yet none of
+ * it is built on macOS.
+ *
+ * Errs toward NOT skipping, like the rest of this module: an unreadable or
+ * oversized ancestor, or a directory no `DIRS` entry names, yields
+ * `gatedOff: false`.
+ *
+ * @param engineDir - Absolute path to the engine root
+ * @param sourcePath - Engine-relative POSIX path of the source file
+ */
+export declare function detectAncestorDirsGate(engineDir: string, sourcePath: string): Promise<AncestorDirsGateResult>;

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

@@ -28,6 +28,7 @@
  * that should ship on this host) are not, so it errs toward NOT skipping
  * when uncertain.
  */
+import { stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { getPlatform } from '../utils/platform.js';
@@ -231,3 +232,142 @@ export async function detectPlatformGate(engineDir, sourcePath) {
     }
     return { gatedOff: false };
 }
+/**
+ * Maximum ancestor levels walked looking for a gating `DIRS` entry, and the
+ * largest `moz.build` read while doing it. The audit runs on every build, so
+ * a pathological tree must not be able to make it slow; beyond these bounds
+ * the walk gives up and the caller keeps today's behaviour (warn).
+ */
+const MAX_ANCESTOR_DEPTH = 12;
+const MAX_MOZ_BUILD_BYTES = 256 * 1024;
+/** Matches a line that begins a `DIRS` assignment. */
+const DIRS_ASSIGNMENT_PATTERN = /^\s*DIRS\s*\+?=/;
+/**
+ * Collects the FULL stack of `if CONFIG[…]:` expressions enclosing the
+ * `DIRS` entry whose value equals `relDir`.
+ *
+ * Two differences from {@link findEnclosingGate}, both load-bearing here:
+ * only quoted values inside a `DIRS` assignment are considered (an
+ * unrelated string literal elsewhere in the file must not gate a
+ * directory), and EVERY enclosing expression is returned rather than the
+ * innermost. Firefox nests these — `toolkit/moz.build` reaches
+ * `mozapps/defaultagent` inside `OS_ARCH == "WINNT"`, then a `CC_TYPE`
+ * test, then `MOZ_DEFAULT_BROWSER_AGENT` — and it is the OUTERMOST one that
+ * excludes the directory on a macOS host.
+ *
+ * @param content - `moz.build` file content
+ * @param relDir - Directory path relative to the `moz.build`, POSIX-separated
+ * @returns Enclosing gate expressions, outermost first; empty when ungated
+ *   or when no `DIRS` entry reaches `relDir`
+ */
+function findDirsEntryGates(content, relDir) {
+    const lines = content.split('\n');
+    const stack = [];
+    let inDirs = false;
+    for (const line of lines) {
+        if (line.trim() === '')
+            continue;
+        const indent = (/^(\s*)/.exec(line)?.[1] ?? '').length;
+        while (stack.length > 0) {
+            const top = stack[stack.length - 1];
+            if (top && indent <= top.indent) {
+                stack.pop();
+                continue;
+            }
+            break;
+        }
+        const ifMatch = /^\s*if\s+(.+?):\s*(?:#.*)?$/.exec(line);
+        if (ifMatch?.[1]) {
+            stack.push({ indent, expression: ifMatch[1] });
+            inDirs = false;
+            continue;
+        }
+        if (DIRS_ASSIGNMENT_PATTERN.test(line)) {
+            // A `DIRS += [` list body continues on later lines; a single-line
+            // `DIRS += ["x"]` is fully handled by the match below.
+            inDirs = !line.includes(']');
+            if (dirsLineNames(line, relDir))
+                return stack.map((entry) => entry.expression);
+            continue;
+        }
+        if (inDirs) {
+            if (dirsLineNames(line, relDir))
+                return stack.map((entry) => entry.expression);
+            if (line.includes(']'))
+                inDirs = false;
+        }
+    }
+    return undefined;
+}
+/** True when `line` carries `relDir` as a quoted value. */
+function dirsLineNames(line, relDir) {
+    const escaped = escapeRegex(relDir.replace(/\/+$/, ''));
+    return new RegExp(`["']${escaped}\\/?["']`).test(line);
+}
+/**
+ * Determines whether the source file's DIRECTORY is excluded from this
+ * build by a gate in an ANCESTOR `moz.build`.
+ *
+ * `detectPlatformGate` reads only the file's own nearest `moz.build`, which
+ * misses the common Firefox shape where the whole subtree is reached
+ * through a conditional `DIRS +=` one or more levels up: nothing in
+ * `toolkit/mozapps/defaultagent/moz.build` says "Windows only", yet none of
+ * it is built on macOS.
+ *
+ * Errs toward NOT skipping, like the rest of this module: an unreadable or
+ * oversized ancestor, or a directory no `DIRS` entry names, yields
+ * `gatedOff: false`.
+ *
+ * @param engineDir - Absolute path to the engine root
+ * @param sourcePath - Engine-relative POSIX path of the source file
+ */
+export async function detectAncestorDirsGate(engineDir, sourcePath) {
+    let host;
+    try {
+        host = getPlatform();
+    }
+    catch {
+        return { gatedOff: false };
+    }
+    const segments = sourcePath.split('/').filter(Boolean);
+    // Drop the basename: the walk is over DIRECTORIES.
+    segments.pop();
+    const root = engineDir.replace(/[/\\]+$/, '');
+    const depth = Math.min(segments.length, MAX_ANCESTOR_DEPTH);
+    // Start at the immediate parent of the file's directory and walk up, so
+    // the nearest gating ancestor is found first.
+    for (let cut = segments.length - 1; cut >= segments.length - depth; cut -= 1) {
+        const ancestorSegments = segments.slice(0, cut);
+        const relDir = segments.slice(cut).join('/');
+        if (relDir === '')
+            continue;
+        const mozBuild = join(root, ...ancestorSegments, 'moz.build');
+        if (!(await pathExists(mozBuild)))
+            continue;
+        let content;
+        try {
+            const stats = await stat(mozBuild);
+            if (stats.size > MAX_MOZ_BUILD_BYTES)
+                continue;
+            content = await readText(mozBuild);
+        }
+        catch {
+            continue;
+        }
+        const gates = findDirsEntryGates(content, relDir);
+        if (gates === undefined)
+            continue;
+        const offHost = gates.find((expression) => isGateOffHost(expression, host));
+        if (offHost !== undefined) {
+            return {
+                gatedOff: true,
+                gateExpression: offHost,
+                gateFile: [...ancestorSegments, 'moz.build'].join('/'),
+            };
+        }
+        // The directory IS reached from here and this host passes every gate;
+        // a further ancestor cannot un-reach it.
+        return { gatedOff: false };
+    }
+    return { gatedOff: false };
+}

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

@@ -25,6 +25,7 @@
  */
 import { basename, dirname, join, relative, sep } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
+import { normalizePathSlashes } from '../utils/paths.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;
@@ -65,7 +66,7 @@ export function parseJarMnEntry(line) {
  * practice, so a first-match wins behaviour is adequate.
  */
 export function findJarMnEntryForSource(content, relativeSource) {
-    const normalized = relativeSource.replace(/\\/g, '/');
+    const normalized = normalizePathSlashes(relativeSource);
     for (const line of content.split('\n')) {
         const parsed = parseJarMnEntry(line);
         if (!parsed)
@@ -121,7 +122,7 @@ export async function findRegisteredTarget(engineDir, source) {
  * independent.
  */
 function toPosix(path) {
-    return path.split(sep).join('/');
+    return normalizePathSlashes(path);
 }
 /**
  * Probes the dist tree for the artifact registered against the given

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 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 declare function matchUnpackagedDeclaration(sourcePath: string, declarations: readonly UnpackagedDeclaration[]): UnpackagedDeclaration | undefined;