@hominis/fireforge 0.15.7 → 0.15.9

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

@@ -25,6 +25,26 @@ export interface LintCommandOptions {
      * rejected up-front rather than silently ignored.
      */
     onlyIntroduced?: boolean;
+    /**
+     * Lint each patch in the queue as its own isolated diff, rather than
+     * the aggregate `git diff HEAD` across all applied patches.
+     *
+     * Motivating case: running `fireforge lint` (no args) on a repo where
+     * `fireforge import` or `fireforge rebase` has just applied the full
+     * patch queue produces an aggregate diff (every patch's changes
+     * summed). The patch-size advisory rules (`large-patch-lines`,
+     * `large-patch-files`) then fire against the sum — e.g. "Patch is
+     * 37529 lines" on a queue of 22 individually-fine patches — which
+     * reads as a task-specific regression when it is really an artefact
+     * of the aggregation. `--per-patch` rescopes the diff to each patch's
+     * own `filesAffected`, honours the patch's own `lintIgnore`, and runs
+     * the cross-patch rules once over the whole queue so queue-level
+     * findings (duplicate creations, forward imports) still surface.
+     *
+     * Mutually exclusive with passing explicit file paths — the two
+     * scope contracts are different.
+     */
+    perPatch?: boolean;
 }
 /**
  * Runs the lint command to check engine changes against patch quality rules.

package/dist/src/commands/lint.js

@@ -8,40 +8,27 @@ import { getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, } fro
 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 { loadPatchesManifest } from '../core/patch-manifest.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 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
+ * Resolves the diff the lint command should run against. Returns `null` when
+ * there is nothing to lint (e.g. no matching files, clean tree, or empty
+ * diff content) — callers treat that as the early-exit signal and stop.
+ *
+ * Extracted from {@link lintCommand} so that function stays under the
+ * per-function LOC budget as the command grows; the two file-mode and
+ * aggregate-mode branches share no state with the post-lint reporting
+ * pipeline, so the split is a pure rename rather than a refactor.
  */
-export async function lintCommand(projectRoot, files, options = {}) {
-    intro('FireForge Lint');
-    // `--only-introduced` scopes the exit code to `--since`-tagged issues, so
-    // without a revision to anchor the diff there is no "introduced" subset
-    // to scope to — reject the combination up-front so a misconfigured CI
-    // invocation fails loud instead of silently treating every error as
-    // cumulative and passing.
-    if (options.onlyIntroduced && !options.since) {
-        throw new GeneralError('--only-introduced requires --since <git-rev> so introduced-vs-cumulative can be distinguished.');
-    }
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.engine))) {
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-    }
-    if (!(await isGitRepository(paths.engine))) {
-        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
-    }
-    let diff;
+async function resolveLintDiff(engineDir, files) {
     if (files.length > 0) {
-        // Collect specific files/directories
         const collectedFiles = new Set();
         let fileStatuses;
         let untrackedFiles;
         for (const inputPath of files) {
-            const fullInputPath = join(paths.engine, inputPath);
+            const fullInputPath = join(engineDir, inputPath);
             let isDirectory = false;
             try {
                 const fileStat = await stat(fullInputPath);
@@ -52,47 +39,87 @@ export async function lintCommand(projectRoot, files, options = {}) {
             }
             if (isDirectory) {
                 const dirPath = inputPath.endsWith('/') ? inputPath.slice(0, -1) : inputPath;
-                const modifiedFiles = await getModifiedFilesInDir(paths.engine, dirPath);
-                const dirUntrackedFiles = await getUntrackedFilesInDir(paths.engine, dirPath);
+                const modifiedFiles = await getModifiedFilesInDir(engineDir, dirPath);
+                const dirUntrackedFiles = await getUntrackedFilesInDir(engineDir, dirPath);
                 for (const f of modifiedFiles)
                     collectedFiles.add(f);
                 for (const f of dirUntrackedFiles)
                     collectedFiles.add(f);
             }
             else {
-                if (!fileStatuses) {
-                    fileStatuses = await getStatusWithCodes(paths.engine);
-                }
-                if (!untrackedFiles) {
-                    untrackedFiles = await getUntrackedFiles(paths.engine);
-                }
+                if (!fileStatuses)
+                    fileStatuses = await getStatusWithCodes(engineDir);
+                if (!untrackedFiles)
+                    untrackedFiles = await getUntrackedFiles(engineDir);
                 const hasStatus = fileStatuses.some((s) => s.file === inputPath) || untrackedFiles.includes(inputPath);
-                if (hasStatus) {
+                if (hasStatus)
                     collectedFiles.add(inputPath);
-                }
             }
         }
         if (collectedFiles.size === 0) {
             info('No modified files found in the specified paths.');
             outro('Nothing to lint');
-            return;
+            return null;
         }
-        diff = await getDiffForFilesAgainstHead(paths.engine, [...collectedFiles].sort());
-    }
-    else {
-        // Lint all changes
-        if (!(await hasChanges(paths.engine))) {
-            info('No changes to lint.');
+        const diff = await getDiffForFilesAgainstHead(engineDir, [...collectedFiles].sort());
+        if (!diff.trim()) {
+            info('No diff content to lint.');
             outro('Nothing to lint');
-            return;
+            return null;
         }
-        diff = await getAllDiff(paths.engine);
+        return diff;
     }
+    if (!(await hasChanges(engineDir))) {
+        info('No changes to lint.');
+        outro('Nothing to lint');
+        return null;
+    }
+    const diff = await getAllDiff(engineDir);
     if (!diff.trim()) {
         info('No diff content to lint.');
         outro('Nothing to lint');
+        return null;
+    }
+    return diff;
+}
+/**
+ * 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, options = {}) {
+    intro('FireForge Lint');
+    // `--only-introduced` scopes the exit code to `--since`-tagged issues, so
+    // without a revision to anchor the diff there is no "introduced" subset
+    // to scope to — reject the combination up-front so a misconfigured CI
+    // invocation fails loud instead of silently treating every error as
+    // cumulative and passing.
+    if (options.onlyIntroduced && !options.since) {
+        throw new GeneralError('--only-introduced requires --since <git-rev> so introduced-vs-cumulative can be distinguished.');
+    }
+    // `--per-patch` rescopes the diff from "aggregate engine state" to "each
+    // patch's own filesAffected". Mixing in explicit file paths would produce
+    // an ambiguous set — is the file list an additional filter, or does it
+    // replace the per-patch scope? Reject up-front so the operator gets a
+    // clear error rather than a silently-narrowed result.
+    if (options.perPatch && files.length > 0) {
+        throw new GeneralError('--per-patch cannot be combined with explicit file paths. Pass either --per-patch or a file list, not both.');
+    }
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.engine))) {
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
+    }
+    if (!(await isGitRepository(paths.engine))) {
+        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
+    }
+    if (options.perPatch) {
+        await lintPerPatch(projectRoot, paths);
         return;
     }
+    const diff = await resolveLintDiff(paths.engine, files);
+    if (diff === null)
+        return;
     const config = await loadConfig(projectRoot);
     const filesAffected = extractAffectedFiles(diff);
     // Build patch queue context once so it can be shared between the
@@ -110,6 +137,19 @@ export async function lintCommand(projectRoot, files, options = {}) {
     if (ctx) {
         issues.push(...lintPatchQueue(ctx));
     }
+    // When a queue manifest exists AND files were NOT scoped explicitly, the
+    // "diff" we just linted is every applied patch summed together. Patch-
+    // size rules (`large-patch-lines`, `large-patch-files`) then fire against
+    // the aggregate rather than any individual patch, producing counts like
+    // "Patch is 37529 lines" that read as a task-specific regression but are
+    // really an artefact of aggregation. Surface a one-line note pointing at
+    // `--per-patch` so the operator knows the per-patch scope exists before
+    // they read the error message as "my queue is broken".
+    const aggregateHintApplicable = files.length === 0 && ctx !== undefined && ctx.entries.length > 1;
+    if (aggregateHintApplicable &&
+        issues.some((i) => i.check === 'large-patch-lines' || i.check === 'large-patch-files')) {
+        info('NOTE: aggregate diff across all applied patches. Use `fireforge lint --per-patch` to lint each patch individually; patch-size rules fire against the sum in aggregate mode.');
+    }
     if (issues.length === 0) {
         success('No lint issues found.');
         outro('Lint passed');
@@ -164,13 +204,83 @@ export async function lintCommand(projectRoot, files, options = {}) {
     }
     outro('Lint passed with warnings');
 }
+/**
+ * Lints each patch in the queue as its own isolated diff, honouring
+ * per-patch `lintIgnore` entries. Cross-patch rules still run once over
+ * the whole queue so queue-level findings (duplicate creations, forward
+ * imports) are not lost by the rescoping.
+ *
+ * Kept separate from {@link lintCommand}'s aggregate path because the
+ * two scopes have genuinely different contracts — the aggregate path
+ * reports what `git diff HEAD` looks like right now, the per-patch
+ * path reports what each patch's own slice of that diff looks like.
+ * Sharing a loop would hide the distinction and force the caller to
+ * decide semantics mid-function.
+ */
+async function lintPerPatch(projectRoot, paths) {
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        info('No patches in manifest — nothing to lint per-patch.');
+        outro('Nothing to lint');
+        return;
+    }
+    const config = await loadConfig(projectRoot);
+    const ctx = await buildPatchQueueContext(paths.patches);
+    const issues = [];
+    let linted = 0;
+    for (const patch of manifest.patches) {
+        const existing = [];
+        for (const f of patch.filesAffected) {
+            if (await pathExists(join(paths.engine, f)))
+                existing.push(f);
+        }
+        if (existing.length === 0)
+            continue;
+        const diff = await getDiffForFilesAgainstHead(paths.engine, existing);
+        if (!diff.trim())
+            continue;
+        const ignore = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
+        const patchIssues = await lintExportedPatch(paths.engine, existing, diff, config, ctx, ignore);
+        for (const issue of patchIssues) {
+            issues.push({ ...issue, file: `${patch.filename} :: ${issue.file}` });
+        }
+        linted++;
+    }
+    // Cross-patch rules over the whole queue — rescoping per-patch would
+    // lose these findings, so they run exactly once against the full
+    // context.
+    issues.push(...lintPatchQueue(ctx));
+    if (issues.length === 0) {
+        success(`No lint issues found across ${linted} patch(es).`);
+        outro('Lint passed');
+        return;
+    }
+    const errors = issues.filter((i) => i.severity === 'error');
+    const warnings = issues.filter((i) => i.severity === 'warning');
+    const notices = issues.filter((i) => i.severity === 'notice');
+    for (const issue of notices)
+        info(`NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
+    for (const issue of warnings)
+        warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
+    for (const issue of errors)
+        warn(`ERROR [${issue.check}] ${issue.file}: ${issue.message}`);
+    info(`\nLint (per-patch over ${linted} patch(es)): ${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) across ${linted} patch(es). Fix these before exporting.`);
+    }
+    outro('Lint passed with warnings');
+}
 /** Registers the lint command on the CLI program. */
 export function registerLint(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('lint [paths...]')
-        .description('Lint engine changes against patch quality rules')
+        .description('Lint engine changes against patch quality rules. Default: aggregate diff against HEAD ' +
+        '(every applied patch summed). Use --per-patch for per-patch scope, or pass explicit ' +
+        'file paths to narrow to those.')
         .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)')
         .option('--only-introduced', 'Fail only on issues tagged [introduced] (requires --since). Cumulative errors still print but do not set a non-zero exit.')
+        .option('--per-patch', "Lint each patch in the queue as its own isolated diff. Rescopes patch-size rules so they fire against individual patches rather than the aggregate. Honours each patch's `lintIgnore` entries.")
         .action(withErrorHandling(async (paths, options) => {
         const lintOptions = {};
         if (options.since !== undefined) {
@@ -179,6 +289,9 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         if (options.onlyIntroduced !== undefined) {
             lintOptions.onlyIntroduced = options.onlyIntroduced;
         }
+        if (options.perPatch !== undefined) {
+            lintOptions.perPatch = options.perPatch;
+        }
         await lintCommand(getProjectRoot(), paths, lintOptions);
     }));
 }

package/dist/src/commands/re-export-files.js

@@ -71,8 +71,12 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
             'Remove those paths from --files or modify them before retrying.', '--files');
     }
     // Run the per-patch lint against the projected diff. This mirrors what
-    // runPatchLint does in the standard re-export path.
-    await runPatchLint(paths.engine, actualProjectedFiles, projectedDiff, config, options.skipLint);
+    // runPatchLint does in the standard re-export path. The target patch's
+    // `lintIgnore` threads through so a shrink of an advisory-noisy-but-
+    // intentional patch (branding bundle, localised-resource pack) does not
+    // have to choose between `--skip-lint` (blunt) and the full rebase path.
+    const ignoreChecks = target.lintIgnore?.length ? new Set(target.lintIgnore) : undefined;
+    await runPatchLint(paths.engine, actualProjectedFiles, projectedDiff, config, options.skipLint, undefined, ignoreChecks);
     // Project the cross-patch context: replace the target entry with its
     // would-be shrunken self (new diff + new newFiles + new
     // modifiedFileAdditions). The projected entry must repopulate both

package/dist/src/commands/re-export.js

@@ -6,7 +6,7 @@ import { isGitRepository } from '../core/git.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
-import { getClaimedFiles, loadPatchesManifest, resolvePatchIdentifier, } from '../core/patch-manifest.js';
+import { getClaimedFiles, loadPatchesManifest, resolvePatchIdentifier, stampPatchVersions, } from '../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
@@ -97,7 +97,14 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         warn(`Skipped ${patch.filename}: no changes (files unchanged from HEAD)`);
         return false;
     }
-    await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint);
+    // Thread the patch's own `lintIgnore` list through so the per-patch
+    // suppression honoured by export/export-all is also honoured here.
+    // Without this, `re-export` could not refresh an advisory-noisy but
+    // intentional patch (a cohesive branding bundle, a localised-resource
+    // pack) without either `--skip-lint` (too blunt) or falling through to
+    // the full `rebase` flow (which internally skips the lint pipeline).
+    const ignoreChecks = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
+    await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint, undefined, ignoreChecks);
     if (isDryRun) {
         info(`[dry-run] ${patch.filename}: ${existingFiles.length} file(s)`);
     }
@@ -219,13 +226,16 @@ export async function reExportCommand(projectRoot, patches, options) {
     }
     const config = await loadConfig(projectRoot);
     let reExported = 0;
+    const reExportedFilenames = [];
     const progress = spinner('Preparing re-export...');
     for (const patch of selectedPatches) {
         progress.message(`Re-exporting ${patch.filename}...`);
         try {
             const exported = await reExportSinglePatch(patch, paths, manifest, options, isDryRun, config);
-            if (exported)
+            if (exported) {
                 reExported++;
+                reExportedFilenames.push(patch.filename);
+            }
         }
         catch (error) {
             warn(`Failed to re-export ${patch.filename}`);
@@ -236,14 +246,34 @@ export async function reExportCommand(projectRoot, patches, options) {
         progress.error('Re-export failed');
         throw new GeneralError('All selected patches failed to re-export. Check the errors above.');
     }
+    // `--stamp` only fires on a run where every selected patch refreshed
+    // cleanly. A partial success would leave some patches with a stale body
+    // but a new version — the opposite of the "what I tested, what the
+    // manifest says" invariant `sourceEsrVersion` exists to record. A
+    // non-empty `reExportedFilenames` with fewer entries than `selectedPatches`
+    // means a lint failure or missing-file skip landed somewhere in the loop,
+    // which we refuse to version-stamp through.
+    const shouldStamp = options.stamp === true && !isDryRun && reExported > 0 && reExported === selectedPatches.length;
+    if (shouldStamp) {
+        await stampPatchVersions(paths.patches, reExportedFilenames, config.firefox.version);
+    }
     if (isDryRun) {
         progress.stop('Dry run complete');
         success(`[dry-run] Would re-export ${reExported} of ${selectedPatches.length} patch(es)`);
+        if (options.stamp === true) {
+            info(`[dry-run] Would stamp sourceEsrVersion=${config.firefox.version} on ${reExported} patch(es)`);
+        }
         outro('Dry run complete');
     }
     else {
         progress.stop('Re-export complete');
         success(`Re-exported ${reExported} of ${selectedPatches.length} patch(es)`);
+        if (shouldStamp) {
+            success(`Stamped sourceEsrVersion=${config.firefox.version} on ${reExportedFilenames.length} patch(es)`);
+        }
+        else if (options.stamp === true && reExported !== selectedPatches.length) {
+            warn('--stamp was requested but some patches failed or were skipped; refusing to stamp a partial set.');
+        }
         outro('Re-export complete');
     }
 }
@@ -251,7 +281,9 @@ export async function reExportCommand(projectRoot, patches, options) {
 export function registerReExport(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('re-export [patches...]')
-        .description('Re-export existing patches from current engine state')
+        .description('Refresh existing patch bodies (and filesAffected with --scan) from the current engine ' +
+        'state. Does NOT change sourceEsrVersion by default — use --stamp or run rebase for ' +
+        'version stamping.')
         .option('-a, --all', 'Re-export all patches')
         .option('-s, --scan', 'Scan directories for new/removed files and update filesAffected')
         .option('--files <paths>', 'Restrict the re-exported filesAffected to this comma-separated list (single target patch only)', (value) => value
@@ -262,6 +294,7 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
         .option('-y, --yes', 'Skip confirmation when --files shrinks a patch (required for non-TTY)')
         .option('--force-unsafe', 'Bypass cross-patch lint refusal when --files shrinks a patch')
+        .option('--stamp', "After every selected patch refreshes cleanly, stamp each re-exported patch's sourceEsrVersion in patches.json to firefox.version from fireforge.json. No effect on a partial run.")
         .action(withErrorHandling(async (patches, options) => {
         await reExportCommand(getProjectRoot(), patches, pickDefined(options));
     }));

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

@@ -1,9 +1,23 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
+import type { RunOptions } from '../types/commands/index.js';
+/**
+ * Exit code returned by smoke-run mode when the captured console stream
+ * produced one or more error lines that did NOT match the operator's
+ * allowlist.
+ */
+export declare const SMOKE_EXIT_FAILURE: 12;
+/**
+ * Exit code returned by smoke-run mode when the browser itself exited
+ * with a non-clean status before the smoke window elapsed — i.e. a
+ * launch-side failure we could NOT observe as a console error line
+ * (crash before console wiring, missing profile, etc.).
+ */
+export declare const SMOKE_LAUNCH_FAILURE: 13;
 /**
  * Runs the run command to launch the built browser.
  * @param projectRoot - Root directory of the project
  */
-export declare function runCommand(projectRoot: string): Promise<void>;
+export declare function runCommand(projectRoot: string, options?: RunOptions): Promise<void>;
 /** Registers the run command on the CLI program. */
 export declare function registerRun(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;