@hominis/fireforge 0.15.1 → 0.15.3

package/dist/src/commands/furnace/create.js

@@ -15,7 +15,9 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
 import { cancel, intro, isCancel, note, outro, success, warn } from '../../utils/logger.js';
+import { scaffoldMochikitTestFiles } from './create-mochikit.js';
 import { generateCssContent, generateFtlContent, generateMjsContent } from './create-templates.js';
+import { scaffoldXpcshellTestFiles } from './create-xpcshell.js';
 async function loadAuthoringFurnaceConfig(projectRoot) {
     if (await furnaceConfigExists(projectRoot)) {
         return loadFurnaceConfig(projectRoot);
@@ -223,6 +225,35 @@ async function writeComponentFiles(componentDir, componentName, className, descr
     }
     return files;
 }
+/**
+ * Collapses `--with-tests`, `--xpcshell`, and `--test-style` into the single
+ * scaffold dispatch used inside the mutation phase.
+ *
+ * Backwards-compat invariants:
+ * - `--xpcshell` alone is equivalent to `--test-style=xpcshell`.
+ * - `--with-tests` alone (no `--test-style`) now defaults to `mochikit`
+ *   (previously it defaulted to browser-chrome; the dogfooding pass
+ *   flagged browser-chrome as unrunnable against non-tabbrowser chrome).
+ *   Operators who need the old behavior can pass
+ *   `--with-tests --test-style=browser-chrome`.
+ * - `--xpcshell --with-tests` is rejected as ambiguous.
+ * @throws InvalidArgumentError when flags conflict.
+ */
+export function resolveTestStyle(options) {
+    const xpcshellFlag = options.xpcshell ?? false;
+    const withTests = options.withTests ?? false;
+    const explicit = options.testStyle;
+    if (xpcshellFlag && explicit && explicit !== 'xpcshell') {
+        throw new InvalidArgumentError(`--xpcshell cannot be combined with --test-style=${explicit}; choose one.`, 'testStyle');
+    }
+    if (explicit)
+        return explicit;
+    if (xpcshellFlag)
+        return 'xpcshell';
+    if (withTests)
+        return 'mochikit';
+    return 'none';
+}
 /**
  * Performs the transactional mutation phase of furnace create. All file
  * writes and the config update are recorded in a rollback journal so a
@@ -258,10 +289,18 @@ async function performCreateMutations(args) {
         args.config.custom[args.componentName] = customEntry;
         await snapshotFile(journal, args.furnacePaths.furnaceConfig);
         await writeFurnaceConfig(args.projectRoot, args.config);
-        if (args.withTests) {
+        if (args.testStyle === 'browser-chrome') {
             const scafFiles = await scaffoldTestFiles(args.componentName, args.license, args.forgeConfig, args.paths, journal);
             testFiles.push(...scafFiles);
         }
+        else if (args.testStyle === 'xpcshell') {
+            const xpcshellFiles = await scaffoldXpcshellTestFiles(args.componentName, args.license, args.forgeConfig, args.paths, journal);
+            testFiles.push(...xpcshellFiles);
+        }
+        else if (args.testStyle === 'mochikit') {
+            const mochikitFiles = await scaffoldMochikitTestFiles(args.componentName, args.license, args.paths, journal);
+            testFiles.push(...mochikitFiles);
+        }
     }
     catch (error) {
         try {
@@ -395,13 +434,13 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         return;
     }
     const { localized, register } = featureSelection;
-    // --with-tests writes files under engine/browser/base/content/test/ and
-    // registers them in moz.build. Guard against a missing engine now rather
-    // than letting scaffoldTestFiles fabricate a partial engine tree with
-    // ensureDir.
-    const withTests = options.withTests ?? false;
-    if (withTests && !(await pathExists(paths.engine))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first to use --with-tests.', componentName);
+    // Collapse --with-tests / --xpcshell / --test-style into the single
+    // scaffold selection used by the mutation phase. The resolver validates
+    // incompatible combinations up-front so a bad flag set never strands a
+    // partial mutation behind.
+    const testStyle = resolveTestStyle(options);
+    if (testStyle !== 'none' && !(await pathExists(paths.engine))) {
+        throw new FurnaceError('Engine directory not found. Run "fireforge download" first to use --with-tests, --xpcshell, or --test-style.', componentName);
     }
     // --- Generate component files ---
     const className = tagNameToClassName(componentName);
@@ -437,7 +476,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         forgeConfig,
         paths,
         license,
-        withTests,
+        testStyle,
         ftlChromeSubPath,
         operationContext: ctx,
     }));
@@ -445,9 +484,17 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     let noteParts = `Files created in components/custom/${componentName}/:\n` +
         files.map((f) => `  ${f}`).join('\n');
     if (testFiles.length > 0) {
-        noteParts +=
-            `\n\nTest files in engine/browser/base/content/test/${forgeConfig.binaryName}/:\n` +
-                testFiles.map((f) => `  ${f}`).join('\n');
+        let testRoot;
+        if (testStyle === 'xpcshell') {
+            testRoot = `engine/browser/base/content/test/${forgeConfig.binaryName}-xpcshell/${componentName}/`;
+        }
+        else if (testStyle === 'mochikit') {
+            testRoot = 'engine/toolkit/content/tests/widgets/';
+        }
+        else {
+            testRoot = `engine/browser/base/content/test/${forgeConfig.binaryName}/`;
+        }
+        noteParts += `\n\nTest files in ${testRoot}:\n` + testFiles.map((f) => `  ${f}`).join('\n');
     }
     noteParts +=
         '\n\n' +

package/dist/src/commands/furnace/index.d.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
 import { furnaceApplyCommand } from './apply.js';
+import { furnaceChromeDocCreateCommand } from './chrome-doc.js';
 import { furnaceCreateCommand } from './create.js';
 import { furnaceDeployCommand } from './deploy.js';
 import { furnaceDiffCommand } from './diff.js';
@@ -15,6 +16,6 @@ import { furnaceScanCommand } from './scan.js';
 import { furnaceStatusCommand } from './status.js';
 import { furnaceSyncCommand } from './sync.js';
 import { furnaceValidateCommand } from './validate.js';
-export { furnaceApplyCommand, furnaceBatchOverrideCommand, furnaceCreateCommand, furnaceDeployCommand, furnaceDiffCommand, furnaceInitCommand, furnaceListCommand, furnaceOverrideCommand, furnacePreviewCommand, furnaceRefreshCommand, furnaceRemoveCommand, furnaceRenameCommand, furnaceScanCommand, furnaceStatusCommand, furnaceSyncCommand, furnaceValidateCommand, };
+export { furnaceApplyCommand, furnaceBatchOverrideCommand, furnaceChromeDocCreateCommand, furnaceCreateCommand, furnaceDeployCommand, furnaceDiffCommand, furnaceInitCommand, furnaceListCommand, furnaceOverrideCommand, furnacePreviewCommand, furnaceRefreshCommand, furnaceRemoveCommand, furnaceRenameCommand, furnaceScanCommand, furnaceStatusCommand, furnaceSyncCommand, furnaceValidateCommand, };
 /** Registers the furnace command on the CLI program. */
 export declare function registerFurnace(program: Command, context: CommandContext): void;

package/dist/src/commands/furnace/index.js

@@ -2,6 +2,7 @@
 import { Option } from 'commander';
 import { pickDefined } from '../../utils/options.js';
 import { furnaceApplyCommand } from './apply.js';
+import { furnaceChromeDocCreateCommand } from './chrome-doc.js';
 import { furnaceCreateCommand } from './create.js';
 import { furnaceDeployCommand } from './deploy.js';
 import { furnaceDiffCommand } from './diff.js';
@@ -16,7 +17,7 @@ import { furnaceScanCommand } from './scan.js';
 import { furnaceStatusCommand } from './status.js';
 import { furnaceSyncCommand } from './sync.js';
 import { furnaceValidateCommand } from './validate.js';
-export { furnaceApplyCommand, furnaceBatchOverrideCommand, furnaceCreateCommand, furnaceDeployCommand, furnaceDiffCommand, furnaceInitCommand, furnaceListCommand, furnaceOverrideCommand, furnacePreviewCommand, furnaceRefreshCommand, furnaceRemoveCommand, furnaceRenameCommand, furnaceScanCommand, furnaceStatusCommand, furnaceSyncCommand, furnaceValidateCommand, };
+export { furnaceApplyCommand, furnaceBatchOverrideCommand, furnaceChromeDocCreateCommand, furnaceCreateCommand, furnaceDeployCommand, furnaceDiffCommand, furnaceInitCommand, furnaceListCommand, furnaceOverrideCommand, furnacePreviewCommand, furnaceRefreshCommand, furnaceRemoveCommand, furnaceRenameCommand, furnaceScanCommand, furnaceStatusCommand, furnaceSyncCommand, furnaceValidateCommand, };
 /**
  * Registers Furnace commands for querying component state: status, scan,
  * and action commands like apply, deploy, and create.
@@ -71,11 +72,28 @@ function registerFurnaceInfoCommands(furnace, context) {
         .option('-d, --description <desc>', 'Component description')
         .option('--localized', 'Include Fluent l10n support')
         .option('--no-register', 'Skip customElements.js registration')
-        .option('--with-tests', 'Scaffold Mochitest directory and register in moz.build')
+        .option('--with-tests', 'Scaffold a test harness (defaults to MochiKit; see --test-style)')
+        .option('--xpcshell', 'Scaffold an xpcshell test harness (for storage-layer code on forks without tabbrowser); equivalent to --test-style=xpcshell')
+        .option('--test-style <style>', "Override the harness written by --with-tests: mochikit (default, runs against non-tabbrowser chrome), browser-chrome (today's scaffold, needs tabbrowser), or xpcshell (headless)", (value) => {
+        if (value !== 'mochikit' && value !== 'browser-chrome' && value !== 'xpcshell') {
+            throw new Error(`--test-style must be one of: mochikit, browser-chrome, xpcshell. Got: "${value}".`);
+        }
+        return value;
+    })
         .option('--compose <tags>', 'Record stock tags composed internally (metadata only, comma-separated)', (val) => val.split(',').map((s) => s.trim()))
         .action(withErrorHandling(async (name, options) => {
         await furnaceCreateCommand(getProjectRoot(), name, options);
     }));
+    const chromeDoc = furnace
+        .command('chrome-doc')
+        .description('Scaffold top-level chrome documents (xhtml + js + css + ftl + jar.mn)');
+    chromeDoc
+        .command('create <name>')
+        .description('Scaffold a new top-level chrome document')
+        .option('--no-titlebar', 'Frameless overlay-style document (omits titlebar-buttonbox)')
+        .action(withErrorHandling(async (name, options) => {
+        await furnaceChromeDocCreateCommand(getProjectRoot(), name, pickDefined(options));
+    }));
 }
 /**
  * Registers Furnace commands for authoring, inspection, and maintenance:

package/dist/src/commands/lint.d.ts

@@ -1,10 +1,22 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
+/** Options controlling how the lint command filters and tags its output. */
+export interface LintCommandOptions {
+    /**
+     * When set, tag each issue as `introduced` or `cumulative` based on
+     * whether its file changed since this git revision (e.g. `HEAD`, a
+     * branch name, or a SHA). Issues are not filtered — the full set still
+     * prints and the exit code is unchanged — but a diff-scoped summary
+     * makes it trivial to see which errors the current task introduced.
+     */
+    since?: string;
+}
 /**
  * Runs the lint command to check engine changes against patch quality rules.
  * @param projectRoot - Root directory of the project
  * @param files - Optional file/directory paths to lint (relative to engine/)
+ * @param options - Additional lint options such as `--since` diff-scoping
  */
-export declare function lintCommand(projectRoot: string, files: string[]): Promise<void>;
+export declare function lintCommand(projectRoot: string, files: string[], options?: LintCommandOptions): Promise<void>;
 /** Registers the lint command on the CLI program. */
 export declare function registerLint(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/lint.js

@@ -7,6 +7,7 @@ import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { buildPatchQueueContext, lintExportedPatch, lintPatchQueue } from '../core/patch-lint.js';
+import { collectDiffFilePaths, tagLintIssues } from '../core/patch-lint-diff-tag.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
@@ -14,8 +15,9 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
  * Runs the lint command to check engine changes against patch quality rules.
  * @param projectRoot - Root directory of the project
  * @param files - Optional file/directory paths to lint (relative to engine/)
+ * @param options - Additional lint options such as `--since` diff-scoping
  */
-export async function lintCommand(projectRoot, files) {
+export async function lintCommand(projectRoot, files, options = {}) {
     intro('FireForge Lint');
     const paths = getProjectPaths(projectRoot);
     if (!(await pathExists(paths.engine))) {
@@ -105,19 +107,38 @@ export async function lintCommand(projectRoot, files) {
         outro('Lint passed');
         return;
     }
+    // Diff-scoping: tag each issue as introduced-in-current-task vs
+    // cumulative-pre-existing-drift. Never filters — full set still prints
+    // and exit code semantics are unchanged — but the per-line prefix and
+    // summary make triage trivial on a large patch series.
+    const sinceActive = Boolean(options.since);
+    if (options.since) {
+        const diffFiles = await collectDiffFilePaths(paths.engine, options.since);
+        tagLintIssues(issues, diffFiles);
+    }
     const errors = issues.filter((i) => i.severity === 'error');
     const warnings = issues.filter((i) => i.severity === 'warning');
     const notices = issues.filter((i) => i.severity === 'notice');
+    const tagPrefix = (issue) => sinceActive && issue.tag ? `[${issue.tag}] ` : '';
     for (const issue of notices) {
-        info(`NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
+        info(`${tagPrefix(issue)}NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
     }
     for (const issue of warnings) {
-        warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
+        warn(`${tagPrefix(issue)}[${issue.check}] ${issue.file}: ${issue.message}`);
     }
     for (const issue of errors) {
-        warn(`ERROR [${issue.check}] ${issue.file}: ${issue.message}`);
+        warn(`${tagPrefix(issue)}ERROR [${issue.check}] ${issue.file}: ${issue.message}`);
+    }
+    if (sinceActive) {
+        const introducedErrors = errors.filter((i) => i.tag === 'introduced').length;
+        const introducedWarnings = warnings.filter((i) => i.tag === 'introduced').length;
+        const cumulativeErrors = errors.length - introducedErrors;
+        const cumulativeWarnings = warnings.length - introducedWarnings;
+        info(`\nLint: ${introducedErrors} introduced error(s), ${introducedWarnings} introduced warning(s); ${cumulativeErrors} cumulative error(s), ${cumulativeWarnings} cumulative warning(s)`);
+    }
+    else {
+        info(`\nLint: ${errors.length} error(s), ${warnings.length} warning(s)`);
     }
-    info(`\nLint: ${errors.length} error(s), ${warnings.length} warning(s)`);
     if (errors.length > 0) {
         outro('Lint failed');
         throw new GeneralError(`Patch lint found ${errors.length} error(s). Fix these before exporting.`);
@@ -129,8 +150,13 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('lint [paths...]')
         .description('Lint engine changes against patch quality rules')
-        .action(withErrorHandling(async (paths) => {
-        await lintCommand(getProjectRoot(), paths);
+        .option('--since <git-rev>', 'Tag issues as [introduced] or [cumulative] based on whether the file changed since <git-rev> (e.g. HEAD, a branch, a SHA)')
+        .action(withErrorHandling(async (paths, options) => {
+        const lintOptions = {};
+        if (options.since !== undefined) {
+            lintOptions.since = options.since;
+        }
+        await lintCommand(getProjectRoot(), paths, lintOptions);
     }));
 }
 //# sourceMappingURL=lint.js.map

package/dist/src/commands/setup.d.ts

@@ -8,4 +8,4 @@ import type { SetupOptions } from '../types/commands/index.js';
  */
 export declare function setupCommand(projectRoot: string, options?: SetupOptions): Promise<void>;
 /** Registers the setup command on the CLI program. */
-export declare function registerSetup(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;
+export declare function registerSetup(program: Command, { withErrorHandling }: CommandContext): void;

package/dist/src/commands/setup.js

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { resolve } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { Option } from 'commander';
 import { configExists } from '../core/config.js';
@@ -57,7 +58,7 @@ export async function setupCommand(projectRoot, options = {}) {
     }
 }
 /** Registers the setup command on the CLI program. */
-export function registerSetup(program, { getProjectRoot, withErrorHandling }) {
+export function registerSetup(program, { withErrorHandling }) {
     program
         .command('setup')
         .description('Initialize a new FireForge project')
@@ -88,7 +89,7 @@ export function registerSetup(program, { getProjectRoot, withErrorHandling }) {
                 setupOptions.license = parsedLicense;
             }
         }
-        await setupCommand(getProjectRoot(), setupOptions);
+        await setupCommand(resolve(process.cwd()), setupOptions);
     }));
 }
 //# sourceMappingURL=setup.js.map

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

@@ -0,0 +1,46 @@
+import type { BuildBaseline } from './build-baseline.js';
+/** Result of a single artifact lookup. */
+export interface AuditEntry {
+    /** Engine-relative source file path (POSIX separators). */
+    source: string;
+    /**
+     * Resolved artifact path inside the dist tree, or undefined when no
+     * candidate bundle location was found. An entry with an undefined path
+     * and status "missing" means the source was packageable but nothing
+     * that looked like its artifact showed up in the bundle.
+     */
+    artifact: string | undefined;
+    /**
+     * 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.
+     */
+    status: 'updated' | 'stale' | 'missing' | 'skipped';
+}
+/** Summary counts for the "Packaged:" end-of-build line. */
+export interface AuditSummary {
+    updated: number;
+    stale: number;
+    missing: number;
+    skipped: number;
+    entries: AuditEntry[];
+}
+/**
+ * Decides whether a source path should be packaged. Returns true for paths
+ * whose extension or directory fragment matches a known-packaged pattern.
+ * @param sourcePath Engine-relative POSIX path (for example browser/app/profile/pref.js).
+ * @returns True when the path implies packaging.
+ */
+export declare function isPackageablePath(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
+ * 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>;

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

@@ -0,0 +1,251 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Post-build dist-tree audit.
+ *
+ * Purpose: catch the class of bug where a file under engine/ was edited
+ * but never registered in moz.build, jar.mn, or package-manifest.in, so
+ * the mach build reports success but the packaged bundle carries stale
+ * or missing content. A fork-specific pref file that was never registered
+ * for packaging is the motivating case.
+ *
+ * The audit is best-effort and warn-only:
+ *   - It enumerates engine files changed since the previous build baseline
+ *     (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
+ *     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
+ *     tricks FireForge doesn't know about will surface as warnings an
+ *     operator can investigate. The audit never fails the build.
+ */
+import { stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { info, verbose, warn } from '../utils/logger.js';
+import { hasChanges, isMissingHeadError } from './git.js';
+import { git } from './git-base.js';
+import { getUntrackedFiles } from './git-status.js';
+/** Path extensions that are conventionally packaged into the Firefox bundle. */
+const PACKAGEABLE_EXTENSIONS = [
+    '.js',
+    '.mjs',
+    '.jsm',
+    '.css',
+    '.ftl',
+    '.xhtml',
+    '.xul',
+    '.html',
+    '.properties',
+];
+/** 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. */
+const IGNORE_PATH_FRAGMENTS = ['obj-', 'node_modules/', '.git/', '.cargo/', '.mozbuild/'];
+/*
+ * Finds the first file with the given basename anywhere under the dist
+ * bundle. Scans the darwin Contents/Resources layout and the linux/win
+ * top-level layout with a depth-limited traversal so deeply-nested
+ * node_modules in the dist copy do not dominate the audit wall clock.
+ */
+async function findArtifactByBasename(distRoot, name, maxDepth = 10) {
+    const { readdir } = await import('node:fs/promises');
+    const stack = [{ dir: distRoot, depth: 0 }];
+    while (stack.length > 0) {
+        const entry = stack.pop();
+        if (!entry)
+            break;
+        if (entry.depth > maxDepth)
+            continue;
+        let children;
+        try {
+            children = await readdir(entry.dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const child of children) {
+            const fullPath = join(entry.dir, child.name);
+            if (child.isDirectory()) {
+                // Skip the symlinked mozbuild cache tree which contains full copies
+                // and would dominate the scan on macOS.
+                if (child.name.startsWith('.'))
+                    continue;
+                stack.push({ dir: fullPath, depth: entry.depth + 1 });
+                continue;
+            }
+            if (child.name === name) {
+                return fullPath;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Decides whether a source path should be packaged. Returns true for paths
+ * whose extension or directory fragment matches a known-packaged pattern.
+ * @param sourcePath Engine-relative POSIX path (for example browser/app/profile/pref.js).
+ * @returns True when the path implies packaging.
+ */
+export function isPackageablePath(sourcePath) {
+    for (const fragment of IGNORE_PATH_FRAGMENTS) {
+        if (sourcePath.includes(fragment))
+            return false;
+    }
+    for (const ext of PACKAGEABLE_EXTENSIONS) {
+        if (sourcePath.endsWith(ext))
+            return true;
+    }
+    for (const fragment of PACKAGEABLE_PATH_FRAGMENTS) {
+        if (sourcePath.includes(fragment))
+            return true;
+    }
+    return false;
+}
+/**
+ * Collects engine-relative paths changed since the baseline's HEAD SHA.
+ * Always includes modified + untracked workdir paths. When the baseline is
+ * missing or the engine has no HEAD yet, falls back to workdir-only diffs.
+ */
+async function collectChangedFiles(engineDir, baseline) {
+    const collected = new Set();
+    if (baseline?.engineHeadSha) {
+        try {
+            const output = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
+            for (const line of output.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+        }
+        catch (error) {
+            if (!isMissingHeadError(error)) {
+                verbose(`Audit: could not diff against baseline SHA — ${toError(error).message}`);
+            }
+        }
+    }
+    try {
+        if (await hasChanges(engineDir)) {
+            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
+            for (const line of worktreeDiff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+            const untracked = await getUntrackedFiles(engineDir);
+            for (const file of untracked) {
+                collected.add(file);
+            }
+        }
+    }
+    catch (error) {
+        verbose(`Audit: could not enumerate workdir changes — ${toError(error).message}`);
+    }
+    return [...collected].sort();
+}
+/*
+ * Finds the unique obj-star directory with a dist subtree, or undefined
+ * when zero or multiple match. The ambiguous case is already rejected
+ * by pre-flight in build.ts, so the auditor only has to handle
+ * one-or-none.
+ */
+async function resolveDistRoot(engineDir) {
+    const { readdir } = await import('node:fs/promises');
+    let entries;
+    try {
+        entries = await readdir(engineDir);
+    }
+    catch {
+        return undefined;
+    }
+    const objDirs = entries.filter((e) => e.startsWith('obj-'));
+    for (const objDir of objDirs) {
+        const distPath = join(engineDir, objDir, 'dist');
+        if (await pathExists(distPath)) {
+            return distPath;
+        }
+    }
+    return undefined;
+}
+/**
+ * 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
+ * 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) {
+    void projectRoot;
+    const summary = {
+        updated: 0,
+        stale: 0,
+        missing: 0,
+        skipped: 0,
+        entries: [],
+    };
+    const distRoot = await resolveDistRoot(engineDir);
+    if (!distRoot) {
+        verbose('Audit skipped: no dist tree found under obj-*/dist/.');
+        return summary;
+    }
+    const changed = await collectChangedFiles(engineDir, baseline);
+    if (changed.length === 0) {
+        return summary;
+    }
+    for (const source of changed) {
+        if (!isPackageablePath(source)) {
+            summary.skipped += 1;
+            summary.entries.push({ source, artifact: undefined, status: 'skipped' });
+            continue;
+        }
+        const sourcePath = join(engineDir, source);
+        let sourceMtime;
+        try {
+            const sourceStat = await stat(sourcePath);
+            sourceMtime = sourceStat.mtimeMs;
+        }
+        catch {
+            // File was deleted since the diff was computed. Skip — a deletion
+            // that didn't propagate to the dist tree is a distinct class of bug
+            // we don't audit yet.
+            summary.skipped += 1;
+            summary.entries.push({ source, artifact: undefined, status: 'skipped' });
+            continue;
+        }
+        const artifact = await findArtifactByBasename(distRoot, basename(source));
+        if (!artifact) {
+            summary.missing += 1;
+            summary.entries.push({ source, artifact: undefined, status: 'missing' });
+            warn(`Audit: engine/${source} was touched but no packaged artifact with basename "${basename(source)}" was found under ${distRoot}. Missing moz.build / jar.mn / package-manifest.in registration?`);
+            continue;
+        }
+        let artifactMtime;
+        try {
+            const artifactStat = await stat(artifact);
+            artifactMtime = artifactStat.mtimeMs;
+        }
+        catch {
+            // Disappeared after the directory scan; treat as missing.
+            summary.missing += 1;
+            summary.entries.push({ source, artifact, status: 'missing' });
+            warn(`Audit: engine/${source} has no readable packaged artifact at ${artifact} (disappeared during audit).`);
+            continue;
+        }
+        if (artifactMtime + 1 < sourceMtime) {
+            summary.stale += 1;
+            summary.entries.push({ source, artifact, status: 'stale' });
+            warn(`Audit: engine/${source} is newer than its packaged artifact ${artifact}. Build reported success but the file's path may not flow through packaging — check moz.build / jar.mn entries.`);
+            continue;
+        }
+        summary.updated += 1;
+        summary.entries.push({ source, artifact, status: 'updated' });
+    }
+    info(`Packaged: ${summary.updated} updated, ${summary.stale} stale, ${summary.missing} missing, ${summary.skipped} skipped`);
+    return summary;
+}
+//# sourceMappingURL=build-audit.js.map