@hominis/fireforge 0.15.8 → 0.15.9

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## 0.15.0
 
+### Re-export — opt-in `--stamp` and per-patch `lintIgnore`
+
+- New `fireforge re-export --stamp` stamps `sourceEsrVersion` on every successfully re-exported patch to the current `firefox.version` from `fireforge.json`. Previously `re-export` only ever refreshed patch bodies and `filesAffected`; version stamping was exclusive to `rebase`'s `stampPatchVersions` call (plus `doctor --repair-patches-manifest`). An operator asked to "re-export targeting a new ESR" had no in-surface signal that the command could not deliver the version half of that request, and had to route through the full rebase flow (which requires a Firefox source re-download) purely to update a version string. `--stamp` closes that gap for the case where the re-export cleanly refreshes every selected patch — a partial run (any skipped or failed patch) refuses to stamp and the success line notes the refusal, so a torn "some bodies refreshed at old version, some at new" state is not representable. The command description and `--help` text now explicitly call out that `re-export` does NOT change `sourceEsrVersion` by default.
+- New optional `lintIgnore: string[]` field on each patch entry in `patches.json` lists lint check IDs to suppress for that patch specifically. Surgical alternative to `--skip-lint` (which downgrades _every_ error to a warning) for the class of patch that is advisory-noisy by nature — cohesive branding bundles, localised-resource packs, auto-generated manifests — where a rule like `large-patch-lines` is not actionable. Threaded through `lintExportedPatch` as an optional `ignoreChecks` filter, honoured by `re-export`, `re-export --files`, and `lint --per-patch`. The file-level `fireforge-ignore:` comment markers for `raw-color-value` and `forward-import` are unchanged; `lintIgnore` fills the gap at the patch level where no per-line marker can exist (the `.patch` body is regenerated on every export). Unknown check IDs are a no-op so the metadata documents the _intent_ to suppress even if the rule is renamed later.
+- Motivating case: re-exporting a 22-patch queue onto 140.9.0esr after `download --force` failed on `001-branding-branding-assets` with `ERROR [large-patch-lines] (patch): Patch is 15665 lines (hard limit: 3000)` — a 57-file branding bundle that genuinely cannot be split. The only escape was `--skip-lint` (downgrades 22 patches' worth of errors) or the full `rebase` flow (already-wasted Firefox download). With `lintIgnore: ["large-patch-lines", "large-patch-files"]` on that one patch, `re-export --all --scan --stamp` now completes in one call.
+
+### Lint — `--per-patch` scope and aggregate-mode hint
+
+- New `fireforge lint --per-patch` scopes the lint diff to each patch's own `filesAffected` in turn rather than the aggregate `git diff HEAD` across every applied patch. Motivating case: running `fireforge lint` (no args) after `fireforge import` / `fireforge rebase` has just applied a 22-patch queue produces an aggregate diff of every patch summed, which means the patch-size advisory rules (`large-patch-lines`, `large-patch-files`) fire against the sum — e.g. `Patch is 37529 lines`, `Patch affects 126 files` — with `Lint failed` and a non-zero exit code on a repo that is actually in a good state. The aggregate framing reads as a task-specific regression when it is really an artefact of aggregation. `--per-patch` restates the scope so each patch lints as its own isolated diff, honours the patch's own `lintIgnore` entries, and runs the cross-patch rules (`duplicate-new-file-creation`, `forward-import`) once over the whole queue so queue-level findings are not lost by the rescoping. Mutually exclusive with explicit file paths (the two scope contracts are different).
+- Aggregate-mode runs that would otherwise surface a `large-patch-lines` / `large-patch-files` error against a multi-patch queue now print a one-line `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.` ahead of the failure message, so the operator reaches the per-patch escape hatch without having to read the help text first. The note fires only when the patches directory has at least two entries AND the rule that fired is a patch-size rule — a single-patch queue or a non-size rule behaves identically to before.
+- Per-patch output namespaces every issue with its owning patch filename (`ERROR [relative-import] 001-ui-test.patch :: browser/base/content/a.ts: …`) so triage can attribute findings without cross-referencing patches.json. The passing summary reports how many patches were actually linted (patches with no files on disk or an empty projected diff are silently skipped — they are not a finding).
+
 ### Test — xpcshell appdir auto-injection
 
 - `fireforge test` now auto-injects `--app-path=<absolute>` into mach test invocations whose nearest `xpcshell.toml` sets `firefox-appdir = "browser"` on a rebranded fork (appname != `firefox`). Without this, every `resource:///modules/<name>.sys.mjs` import inside the harness throws because the upstream xpcshell harness reads the appdir override under the appname-keyed manifest field (`<appname>-appdir`) — the literal `firefox-appdir = "browser"` directive is silently ignored when `appname` is anything other than `firefox`, so `appPath` falls back to `xrePath` (one level above the real app root). The resolver lives in the new `src/core/xpcshell-appdir.ts`: it walks each test path to the nearest `xpcshell.toml`, reads `mozinfo.json` for the active appname, prefers any `<appname>-appdir` already in the manifest (so an operator who already migrated is not overridden), and otherwise probes `<objDir>/dist/bin/<value>` and `<objDir>/dist/<bundle>.app/Contents/Resources/<value>` for the absolute target. Operator overrides via `--mach-arg=--app-path=…` always win and the resolver is skipped silently when one is detected. Mismatches across multiple test paths (different manifests resolving to different app dirs) and unresolvable manifest values (no candidate under `dist/`) are surfaced as warnings rather than guessed at, so triage can reach the underlying cause instead of debugging a wrong path.

package/README.md

@@ -64,8 +64,7 @@ npx fireforge export browser/base/content/browser.js --name "custom-toolbar" --c
 ```
 
 3. Your patch is now in `patches/`.
-
-# 4. Reset and import to verify everything applies cleanly:
+4. Reset and import to verify everything applies cleanly:
 
 ```bash
 npx fireforge reset --yes
@@ -139,6 +138,13 @@ fireforge export browser/base/content/browser.js --before 005-ui-sidebar.patch -
 
 # Restrict a re-export to a specific file subset
 fireforge re-export --files browser/base/content/browser.js 002-ui-toolbar
+
+# Refresh every patch AND stamp sourceEsrVersion from fireforge.json onto each
+# one. Only stamps when every selected patch refreshes cleanly — partial
+# runs refuse to stamp. Use when you re-exported after a manual Firefox
+# bump that did not go through `rebase`. By default `re-export` refreshes
+# patch bodies and filesAffected but does NOT change sourceEsrVersion.
+fireforge re-export --all --scan --stamp
 ```
 
 ### Rebasing on top of a new Firefox version
@@ -176,12 +182,15 @@ This re-exports the fixed patch and continues applying the remaining stack.
       "description": "Replaces default Firefox branding with custom logo",
       "createdAt": "2025-01-15T10:30:00Z",
       "sourceEsrVersion": "140.9.0esr",
-      "filesAffected": ["browser/branding/official/logo.png"]
+      "filesAffected": ["browser/branding/official/logo.png"],
+      "lintIgnore": ["large-patch-lines", "large-patch-files"]
     }
   ]
 }
 ```
 
+The optional `lintIgnore` field lists lint check IDs to suppress for that patch specifically. Useful for the class of patch that is advisory-noisy by nature — a cohesive branding bundle, a localised-resource pack, an auto-generated manifest — where `--skip-lint` is too blunt and a per-line marker cannot exist (the `.patch` body is regenerated on every export). Threaded through `export`, `re-export`, `re-export --files`, and `lint --per-patch`. Unknown check IDs are a no-op.
+
 If the manifest drifts after an interrupted export or manual edits, `fireforge import` will stop rather then silently applying a stale stack. Use `fireforge doctor --repair-patches-manifest` to rebuild it from disk. Because the rebuild is deterministic, the result will always be consistent with what is actually on the filesystem.
 
 </details>
@@ -191,6 +200,8 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 
 `fireforge lint` runs automatically during export, export-all and re-export. Use `--skip-lint` to downgrade errors to warnings. Errors block the export; warnings are printed but do not block.
 
+By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed. On a repo where `fireforge import` or `fireforge rebase` has just applied the full queue, the patch-size rules (`large-patch-lines`, `large-patch-files`) fire against the sum, which reads as "my queue is broken" when it is really an artefact of aggregation. Use `fireforge lint --per-patch` to rescope the diff to each patch's own `filesAffected`, honouring the patch's own `lintIgnore`. Cross-patch rules (`duplicate-new-file-creation`, `forward-import`) still run once over the whole queue either way. Pass explicit file paths to narrow the scope further; the three modes (aggregate, file-scoped, per-patch) are mutually exclusive.
+
 | Check                          | Scope                                                                     | Severity                 |
 | ------------------------------ | ------------------------------------------------------------------------- | ------------------------ |
 | `missing-license-header`       | New files (JS/CSS/FTL)                                                    | error                    |

package/dist/src/commands/export-shared.d.ts

@@ -11,8 +11,13 @@ import type { SpinnerHandle } from '../utils/logger.js';
  * @param config - Project configuration
  * @param skipLint - If true, downgrade errors to warnings
  * @param patchQueueCtx - Optional cross-patch context for ownership resolution
+ * @param ignoreChecks - Optional per-patch set of `check` IDs to suppress
+ *   (threaded from `PatchMetadata.lintIgnore`). Surgical alternative to
+ *   `--skip-lint` when exactly one advisory rule does not apply to a
+ *   specific patch — e.g. `large-patch-lines` on a cohesive branding
+ *   bundle that genuinely cannot be split.
  */
-export declare function runPatchLint(engineDir: string, filesAffected: string[], diffContent: string, config: FireForgeConfig, skipLint?: boolean, patchQueueCtx?: import('../core/patch-lint-cross.js').PatchQueueContext): Promise<void>;
+export declare function runPatchLint(engineDir: string, filesAffected: string[], diffContent: string, config: FireForgeConfig, skipLint?: boolean, patchQueueCtx?: import('../core/patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>): Promise<void>;
 /**
  * Resolves patch metadata interactively or from flags, with shared validation.
  * @param options - Export command options

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

@@ -18,9 +18,14 @@ import { isValidPatchCategory, PATCH_CATEGORIES, validatePatchName } from '../ut
  * @param config - Project configuration
  * @param skipLint - If true, downgrade errors to warnings
  * @param patchQueueCtx - Optional cross-patch context for ownership resolution
+ * @param ignoreChecks - Optional per-patch set of `check` IDs to suppress
+ *   (threaded from `PatchMetadata.lintIgnore`). Surgical alternative to
+ *   `--skip-lint` when exactly one advisory rule does not apply to a
+ *   specific patch — e.g. `large-patch-lines` on a cohesive branding
+ *   bundle that genuinely cannot be split.
  */
-export async function runPatchLint(engineDir, filesAffected, diffContent, config, skipLint, patchQueueCtx) {
-    const issues = await lintExportedPatch(engineDir, filesAffected, diffContent, config, patchQueueCtx);
+export async function runPatchLint(engineDir, filesAffected, diffContent, config, skipLint, patchQueueCtx, ignoreChecks) {
+    const issues = await lintExportedPatch(engineDir, filesAffected, diffContent, config, patchQueueCtx, ignoreChecks);
     if (issues.length === 0)
         return;
     const errors = issues.filter((i) => i.severity === 'error');

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/core/patch-lint.d.ts

@@ -89,6 +89,11 @@ export declare function lintModifiedFileHeaders(repoDir: string, affectedFiles:
  * @param diffContent - Raw unified diff string
  * @param config - Project configuration
  * @param patchQueueCtx - Optional cross-patch context for ownership resolution
+ * @param ignoreChecks - Optional set of per-patch `check` IDs to drop from the
+ *   returned issues. Threaded from `PatchMetadata.lintIgnore` so a patch that
+ *   is advisory-noisy by nature (a cohesive branding bundle, auto-generated
+ *   manifest, etc.) can opt out of a specific rule without reaching for the
+ *   blunt `--skip-lint` hammer. Not mutated by this function.
  * @returns Array of all lint issues found
  */
-export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext): Promise<PatchLintIssue[]>;
+export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>): Promise<PatchLintIssue[]>;

package/dist/src/core/patch-lint.js

@@ -455,9 +455,14 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
  * @param diffContent - Raw unified diff string
  * @param config - Project configuration
  * @param patchQueueCtx - Optional cross-patch context for ownership resolution
+ * @param ignoreChecks - Optional set of per-patch `check` IDs to drop from the
+ *   returned issues. Threaded from `PatchMetadata.lintIgnore` so a patch that
+ *   is advisory-noisy by nature (a cohesive branding bundle, auto-generated
+ *   manifest, etc.) can opt out of a specific rule without reaching for the
+ *   blunt `--skip-lint` hammer. Not mutated by this function.
  * @returns Array of all lint issues found
  */
-export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx) {
+export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx, ignoreChecks) {
     const newFiles = detectNewFilesInDiff(diffContent);
     const { textLines: lineCount } = countNonBinaryDiffLines(diffContent);
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);
@@ -482,6 +487,14 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         const checkJsIssues = await runCheckJs(repoDir, patchOwnedFiles);
         issues.push(...checkJsIssues);
     }
+    // Filter out ignored checks last so every rule still runs (keeps the
+    // implementation uniform) but suppressed rules do not surface. We do not
+    // reclassify severities — an ignored error simply drops, mirroring how
+    // inline `fireforge-ignore: <check>` markers work in the CSS and
+    // forward-import rules.
+    if (ignoreChecks && ignoreChecks.size > 0) {
+        return issues.filter((issue) => !ignoreChecks.has(issue.check));
+    }
     return issues;
 }
 //# sourceMappingURL=patch-lint.js.map

package/dist/src/types/commands/options.d.ts

@@ -155,6 +155,16 @@ export interface ReExportOptions {
     yes?: boolean;
     /** Bypass cross-patch lint refusal on projected shrink state */
     forceUnsafe?: boolean;
+    /**
+     * After every selected patch re-exports cleanly, stamp each re-exported
+     * patch's `sourceEsrVersion` in `patches.json` to the current
+     * `firefox.version` from `fireforge.json`. Opt-in because the default
+     * contract of `re-export` is "refresh the patch body and filesAffected";
+     * version stamping is normally a `rebase` responsibility. Use this when
+     * re-exporting after a manual Firefox bump that did not go through
+     * `rebase`.
+     */
+    stamp?: boolean;
 }
 /**
  * Options for the rebase command.

package/dist/src/types/commands/patches.d.ts

@@ -51,6 +51,28 @@ export interface PatchMetadata {
     sourceEsrVersion: string;
     /** Array of file paths affected by this patch */
     filesAffected: string[];
+    /**
+     * Optional per-patch list of lint check IDs to suppress when this patch
+     * is the target of `export`, `export-all`, or `re-export`. Exists for
+     * the class of patch that is advisory-noisy by nature — a cohesive
+     * branding bundle, a localised-resource pack, an auto-generated
+     * manifest — where the generic `large-patch-lines` / `large-patch-files`
+     * thresholds do not apply but `--skip-lint` (which silences *all*
+     * errors, not just the one that does not apply) is too coarse a hammer.
+     *
+     * Previously the only escape hatches were `--skip-lint` (blunt) or the
+     * full `rebase` flow (refreshes the same patch through a code path that
+     * silently skips `runPatchLint` — an asymmetry that forced operators
+     * through a multi-minute Firefox source re-download just to refresh
+     * one patch body).
+     *
+     * Values are free-form check IDs (e.g. `"large-patch-lines"`,
+     * `"large-patch-files"`). Checks not listed here still run normally.
+     * An entry for an unknown check ID is a no-op — the patch metadata
+     * documents the *intent* to suppress even if the check is later
+     * renamed or removed.
+     */
+    lintIgnore?: string[];
 }
 /**
  * Schema for patches/patches.json file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.15.8",
+  "version": "0.15.9",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",