@hominis/fireforge 0.18.1 → 0.18.2

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

@@ -63,6 +63,8 @@ export async function commitExportedPatch(input) {
             description: input.description,
             filesAffected: input.filesAffected,
             sourceEsrVersion: input.sourceEsrVersion,
+            ...(input.tier !== undefined ? { tier: input.tier } : {}),
+            ...(input.lintIgnore !== undefined ? { lintIgnore: input.lintIgnore } : {}),
         });
         const patchPath = plan.patchPath;
         const originalPatchContent = (await pathExists(patchPath)) ? await readText(patchPath) : null;
@@ -236,13 +238,50 @@ export async function updatePatchAndMetadata(patchesDir, filename, newContent, u
         }
     });
 }
+/**
+ * Merges `updates` onto `existing` and removes the listed `unset`
+ * fields. The unset path is an explicit switch over the
+ * {@link ClearablePatchMetadataField} union rather than a dynamic
+ * `delete obj[k]` so the typecheck-time guarantee that only optional
+ * fields can be cleared survives the runtime erasure — and so the lint
+ * rule against dynamic deletes does not have to be silenced. Adding a
+ * new clearable field requires extending both the union and this
+ * switch in lockstep, which is exactly the constraint we want.
+ */
+function applyMetadataUpdate(existing, updates, unset) {
+    const next = { ...existing, ...updates };
+    for (const field of unset) {
+        switch (field) {
+            case 'tier':
+                delete next.tier;
+                break;
+            case 'lintIgnore':
+                delete next.lintIgnore;
+                break;
+        }
+    }
+    return next;
+}
 /**
  * Updates metadata for a patch in the manifest.
+ *
+ * Required-field updates go through the `updates` partial. Clearing an
+ * optional field (e.g. removing the `tier` override) goes through
+ * `unsetFields` because TypeScript's `exactOptionalPropertyTypes` does
+ * not let `Partial<PatchMetadata>` carry an explicit `undefined` value
+ * for fields whose declared type does not include `undefined`. The
+ * implementation deletes the listed keys from the merged record before
+ * writing, so the on-disk JSON omits them and the validator's
+ * "preserve only when present" contract is preserved.
+ *
  * @param patchesDir - Path to the patches directory
  * @param filename - Patch filename
- * @param updates - Partial metadata updates
+ * @param updates - Field values to set. Pass an empty object when only
+ *   clearing fields.
+ * @param unsetFields - Optional fields to remove from the entry (so
+ *   serialization drops them).
  */
-export async function updatePatchMetadata(patchesDir, filename, updates) {
+export async function updatePatchMetadata(patchesDir, filename, updates, unsetFields = []) {
     await withPatchDirectoryLock(patchesDir, async () => {
         const manifest = await loadPatchesManifest(patchesDir);
         if (!manifest)
@@ -252,11 +291,47 @@ export async function updatePatchMetadata(patchesDir, filename, updates) {
             return;
         const existingPatch = manifest.patches[patchIndex];
         if (existingPatch) {
-            manifest.patches[patchIndex] = { ...existingPatch, ...updates };
+            manifest.patches[patchIndex] = applyMetadataUpdate(existingPatch, updates, unsetFields);
             await savePatchesManifest(patchesDir, manifest);
         }
     });
 }
+/**
+ * Reads a patch's metadata under the directory lock, applies a mutator
+ * function to compute the update, and writes the result back — all
+ * under a single lock so a concurrent writer cannot interleave a
+ * read-modify-write cycle. Useful for operations that need to compute
+ * the new value from the old (e.g. unioning a `lintIgnore` list,
+ * removing a specific entry), which {@link updatePatchMetadata}'s flat
+ * merge cannot express on its own.
+ *
+ * The mutator returns `{ set, unset }` so it can both write fields
+ * and drop optional ones. `set` and `unset` are merged before write:
+ * `set` runs first via spread, then `unset` deletes the listed keys.
+ *
+ * @returns The pre/post metadata pair when the patch is found and the
+ *   write succeeds; `null` when the manifest is missing or the named
+ *   patch is not in it. Callers should treat `null` as "no-op, nothing
+ *   to log".
+ */
+export async function mutatePatchMetadata(patchesDir, filename, mutator) {
+    return await withPatchDirectoryLock(patchesDir, async () => {
+        const manifest = await loadPatchesManifest(patchesDir);
+        if (!manifest)
+            return null;
+        const patchIndex = manifest.patches.findIndex((p) => p.filename === filename);
+        if (patchIndex === -1)
+            return null;
+        const existingPatch = manifest.patches[patchIndex];
+        if (!existingPatch)
+            return null;
+        const { set = {}, unset = [] } = mutator(existingPatch);
+        const updatedPatch = applyMetadataUpdate(existingPatch, set, unset);
+        manifest.patches[patchIndex] = updatedPatch;
+        await savePatchesManifest(patchesDir, manifest);
+        return { before: existingPatch, after: updatedPatch };
+    });
+}
 /**
  * Finds patches that are completely superseded by newer patches.
  * A patch is superseded if all its affected files are covered by newer patches.
@@ -419,6 +494,10 @@ async function computeExportPlanUnderLock(input) {
         createdAt: new Date().toISOString(),
         sourceEsrVersion: input.sourceEsrVersion,
         filesAffected: input.filesAffected,
+        ...(input.tier !== undefined ? { tier: input.tier } : {}),
+        ...(input.lintIgnore !== undefined && input.lintIgnore.length > 0
+            ? { lintIgnore: input.lintIgnore }
+            : {}),
     };
     const supersedeMatches = await findAllPatchesForFilesWithDetails(input.patchesDir, input.filesAffected, patchFilename);
     const supersededDetails = supersedeMatches.map((m) => ({

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

@@ -65,14 +65,55 @@ const PATCH_LINE_THRESHOLDS = {
      * Branding patches have a legitimate reason to be large: they include
      * every locale's `brand.ftl`, copied upstream CSS/PNG assets, and the
      * fork-specific `configure.sh` / `brand.properties` under a single
-     * `browser/branding/<name>/` subtree. The general hard limit of 3000
-     * lines fires on even a first-export branding patch (the eval saw 15904
-     * lines for a freshly-setup fork), which is loud but not actionable —
-     * the patch already is the minimum branding diff. A dedicated tier keeps
-     * the size guidance while moving the hard limit to a threshold that
-     * corresponds to "something other than branding is bundled in here too".
+     * `browser/branding/<name>/` subtree. Calibrated against:
+     *
+     * - The 2026-04-21 eval baseline: a fresh-fork branding export landed
+     *   at 15904 lines (localized brand.ftl across many locales + SVG path
+     *   data + copied upstream CSS).
+     * - The 2026-04-25 operator data point: a freshly setup branding patch
+     *   (post-binary-exclusion, after Phase 1+2 patch splits) landed at
+     *   15650 lines — within 2% of the eval baseline.
+     *
+     * Both data points need to surface as a soft `notice` rather than a
+     * `warning`, since they represent the *minimum* branding diff. The
+     * pre-2026-04-25 calibration {3000/8000/20000} put 15904 firmly in the
+     * `warning` band, contradicting the docstring's "loud but not
+     * actionable" intent. The current calibration moves the warning band
+     * above the eval baseline (with ~13% headroom) and the error band to
+     * roughly 2× the baseline — reaching `error` strongly suggests
+     * non-branding work is bundled in.
+     *
+     * Permissive thresholds are safe because the *gate* into this tier is
+     * narrow (auto-detect requires every file under `browser/branding/`
+     * plus a tight registration allowlist, or an explicit
+     * `PatchMetadata.tier: "branding"` opt-in). A non-branding patch
+     * cannot accidentally land here.
      */
-    branding: { notice: 3000, warning: 8000, error: 20000 },
+    branding: { notice: 8000, warning: 18000, error: 30000 },
+};
+/**
+ * File-count thresholds for the `large-patch-files` rule, mirroring the
+ * tier shape of {@link PATCH_LINE_THRESHOLDS}. A single warning-only
+ * threshold per tier is intentional — file count expresses scope, not
+ * blast radius, and there is no error band that would block export.
+ *
+ * The branding tier sits well above the typical floor because branding
+ * patches inherently span many files: PNG/ICO icon assets in 7+ sizes,
+ * MSIX manifests, channel-specific configs, locale `.ftl` files,
+ * Windows/macOS launcher resources. The 2026-04-25 operator data point
+ * reported a 56-file fresh-fork branding bundle as the minimum shape;
+ * 60 leaves headroom for additional channels/locales while still firing
+ * on a genuinely bloated patch.
+ *
+ * Test tier matches general because a test-only patch rarely touches
+ * many files (a single regression test usually adds 1–3 fixtures); the
+ * elevation in {@link PATCH_LINE_THRESHOLDS.test} addresses big
+ * table-driven test bodies, not file fan-out.
+ */
+const PATCH_FILES_THRESHOLDS = {
+    general: 5,
+    test: 5,
+    branding: 60,
 };
 /**
  * Fixed allowlist of non-branding sibling paths that real-world Firefox
@@ -502,50 +543,58 @@ export function resolvePatchSizeTier(filesAffected, patchTier) {
  */
 export function lintPatchSize(filesAffected, lineCount, patchTier) {
     const issues = [];
-    if (filesAffected.length > 5) {
-        issues.push({
-            file: AGGREGATE_PATCH_FILE,
-            check: 'large-patch-files',
-            message: `Patch affects ${filesAffected.length} files (recommended: ≤5). Consider splitting into smaller, focused patches.`,
-            severity: 'warning',
-        });
-    }
     // Tier selection: test > branding > general. Tests keep their elevated
     // thresholds because a big regression test is legitimate (table-driven
-    // harnesses run into the thousands of lines). Branding patches get their
-    // own tier so a first-export of setup-generated branding doesn't fire
-    // the general hard limit — see `PATCH_LINE_THRESHOLDS.branding` above
-    // for the eval data motivating this tier. An explicit `patchTier`
-    // opt-in forces branding even when `isBrandingOnlyPatch` cannot reach
-    // the patch's actual shape (a branding patch that also touches a
-    // non-allowlisted sibling like a vendor-specific icon resource).
+    // harnesses run into the thousands of lines). Branding patches get
+    // their own tier so a first-export of setup-generated branding doesn't
+    // fire the general hard limit — see `PATCH_LINE_THRESHOLDS.branding`
+    // and `PATCH_FILES_THRESHOLDS.branding` above for the eval data
+    // motivating this tier. An explicit `patchTier` opt-in forces branding
+    // even when `isBrandingOnlyPatch` cannot reach the patch's actual
+    // shape (a branding patch that also touches a non-allowlisted sibling
+    // like a vendor-specific icon resource). Both checks read off the
+    // same decision so the file-count and line-count rules cannot
+    // disagree about which tier applies.
     const decision = resolvePatchSizeTier(filesAffected, patchTier);
-    const thresholds = decision.tier === 'test'
+    const fileThreshold = decision.tier === 'test'
+        ? PATCH_FILES_THRESHOLDS.test
+        : decision.tier === 'branding'
+            ? PATCH_FILES_THRESHOLDS.branding
+            : PATCH_FILES_THRESHOLDS.general;
+    const lineThresholds = decision.tier === 'test'
         ? PATCH_LINE_THRESHOLDS.test
         : decision.tier === 'branding'
             ? PATCH_LINE_THRESHOLDS.branding
             : PATCH_LINE_THRESHOLDS.general;
-    if (lineCount >= thresholds.error) {
+    if (filesAffected.length > fileThreshold) {
+        issues.push({
+            file: AGGREGATE_PATCH_FILE,
+            check: 'large-patch-files',
+            message: `Patch affects ${filesAffected.length} files (recommended: ≤${fileThreshold}). Consider splitting into smaller, focused patches.`,
+            severity: 'warning',
+        });
+    }
+    if (lineCount >= lineThresholds.error) {
         issues.push({
             file: AGGREGATE_PATCH_FILE,
             check: 'large-patch-lines',
-            message: `Patch is ${lineCount} lines (hard limit: ${thresholds.error}). Consider splitting into smaller, focused patches.`,
+            message: `Patch is ${lineCount} lines (hard limit: ${lineThresholds.error}). Consider splitting into smaller, focused patches.`,
             severity: 'error',
         });
     }
-    else if (lineCount >= thresholds.warning) {
+    else if (lineCount >= lineThresholds.warning) {
         issues.push({
             file: AGGREGATE_PATCH_FILE,
             check: 'large-patch-lines',
-            message: `Patch is ${lineCount} lines (soft limit: ${thresholds.warning}, hard limit: ${thresholds.error}). Consider splitting into smaller, focused patches.`,
+            message: `Patch is ${lineCount} lines (soft limit: ${lineThresholds.warning}, hard limit: ${lineThresholds.error}). Consider splitting into smaller, focused patches.`,
             severity: 'warning',
         });
     }
-    else if (lineCount >= thresholds.notice) {
+    else if (lineCount >= lineThresholds.notice) {
         issues.push({
             file: AGGREGATE_PATCH_FILE,
             check: 'large-patch-lines',
-            message: `Patch is ${lineCount} lines (soft limit: ${thresholds.warning}, hard limit: ${thresholds.error}). Consider splitting into smaller, focused patches.`,
+            message: `Patch is ${lineCount} lines (soft limit: ${lineThresholds.warning}, hard limit: ${lineThresholds.error}). Consider splitting into smaller, focused patches.`,
             severity: 'notice',
         });
     }

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

@@ -1,6 +1,6 @@
 /**
  * Re-exports all command-related types from focused sub-modules.
  */
-export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchReorderOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
+export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchReorderOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
 export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, } from './patches.js';
 export type { DoctorCheck, ProjectStatus, TokenCoverageFileEntry, TokenCoverageReport, } from './project.js';

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

@@ -93,6 +93,24 @@ export interface ExportOptions {
      * another patch, because the resulting queue fails `verify` immediately.
      */
     allowOverlap?: boolean;
+    /**
+     * Force a tier override on the new patch's `PatchMetadata.tier`. Only
+     * `"branding"` is currently recognised — Commander rejects other values
+     * before the handler runs. Use when a branding patch legitimately
+     * touches a non-allowlisted sibling that `isBrandingOnlyPatch` cannot
+     * reach (a fork-specific theme override under `browser/themes/<name>/`,
+     * a vendor-specific icon resource, etc.).
+     */
+    tier?: 'branding';
+    /**
+     * Lint check IDs to suppress on this patch. Writes to
+     * `PatchMetadata.lintIgnore`. Repeatable on the CLI; each occurrence
+     * appends to the list. Useful when a patch is advisory-noisy by nature
+     * (a cohesive branding bundle, an auto-generated manifest) and a
+     * specific check does not apply, but `--skip-lint` is too coarse a
+     * hammer.
+     */
+    lintIgnore?: string[];
 }
 /**
  * Options for the reset command.
@@ -172,6 +190,55 @@ export interface ReExportOptions {
      * `rebase`.
      */
     stamp?: boolean;
+    /**
+     * Force a tier override on the selected patch(es). Only `"branding"` is
+     * currently recognised. Mutually exclusive with `--all` — mass tier
+     * changes are virtually always footguns, since different patches in
+     * the queue have different shapes.
+     */
+    tier?: 'branding';
+    /**
+     * Lint check IDs to suppress, **appended** (union) to the patch's
+     * existing `lintIgnore` list. De-duplicated. Mutually exclusive with
+     * `--all`. To remove an entry or clear the list entirely, use the
+     * `fireforge patch lint-ignore` subcommand (which has explicit
+     * `--add` / `--remove` / `--clear` modes); re-export's append-only
+     * semantics match the operator's most common intent ("I want this
+     * patch to also suppress X").
+     */
+    lintIgnore?: string[];
+}
+/**
+ * Options for the `fireforge patch tier` subcommand. Sets or clears the
+ * `PatchMetadata.tier` field on a single patch without rewriting the
+ * `.patch` file body — the manifest is the only thing that changes.
+ */
+export interface PatchTierOptions {
+    /** Force the named tier on the patch. Only `"branding"` is recognised. */
+    tier?: 'branding';
+    /** Remove the `tier` override entirely, restoring auto-detection. */
+    clear?: boolean;
+    /** Print the planned change without writing. */
+    dryRun?: boolean;
+    /** Skip the confirmation prompt (required for non-TTY). */
+    yes?: boolean;
+}
+/**
+ * Options for the `fireforge patch lint-ignore` subcommand. Modes are
+ * mutually exclusive — exactly one of `add`, `remove`, or `clear` must
+ * be set per invocation.
+ */
+export interface PatchLintIgnoreOptions {
+    /** Lint check IDs to add to the patch's `lintIgnore` list (union, de-duped). */
+    add?: string[];
+    /** Lint check IDs to remove from the patch's `lintIgnore` list. */
+    remove?: string[];
+    /** Drop the `lintIgnore` field entirely. */
+    clear?: boolean;
+    /** Print the planned change without writing. */
+    dryRun?: boolean;
+    /** Skip the confirmation prompt (required for non-TTY). */
+    yes?: boolean;
 }
 /**
  * Options for the rebase command.

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

@@ -86,11 +86,12 @@ export interface PatchMetadata {
      * limit on what is legitimately one branding diff.
      *
      * Declaring `tier: "branding"` here forces the branding thresholds
-     * (notice 3000 / warning 8000 / error 20000) regardless of
-     * `filesAffected`. The tier is the weaker claim than test — a patch
-     * of all-tests still lands in the test tier even if this field is
-     * set, because the test-tier thresholds are already more permissive
-     * and a test that is also branding-shaped is vanishingly rare.
+     * (notice 8000 / warning 18000 / error 30000 lines, ≤60 files)
+     * regardless of `filesAffected`. The tier is the weaker claim than
+     * test — a patch of all-tests still lands in the test tier even if
+     * this field is set, because the test-tier thresholds are already
+     * more permissive and a test that is also branding-shaped is
+     * vanishingly rare.
      *
      * Only `"branding"` is currently recognised. Unknown values are
      * rejected by the manifest validator, not silently stripped.

package/package.json

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