@hominis/fireforge 0.43.1 → 0.44.1

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

@@ -17,12 +17,11 @@ import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs, resolvePatchOw
 // Cross-patch lint re-exports
 // ---------------------------------------------------------------------------
 //
-// The cross-patch lint infrastructure (queue context builder, duplicate-
-// creation and forward-import rules, ignore marker) lives in
-// `patch-lint-cross.ts` so the per-patch and cross-patch rule bodies can
-// each stay within the project's per-file line budget. Re-export the
-// public surface from `patch-lint-reexports.ts` so callers continue to
-// import from a single module.
+// The cross-patch lint infrastructure (queue context builder,
+// duplicate-creation and forward-import rules, ignore marker) lives in
+// `patch-lint-cross.ts` so the per-patch and cross-patch rule bodies each
+// stay within the per-file line budget. The public surface is re-exported
+// from `patch-lint-reexports.ts` so callers keep importing from one module.
 export * from './patch-lint-reexports.js';
 // The CSS rule bodies live in `patch-lint-css.ts` (same per-file-budget
 // split as the other rule families); re-export the imported binding so
@@ -38,10 +37,10 @@ const FILE_SIZE_THRESHOLDS = {
 };
 /**
  * Counts the lines of `content` the way `wc -l` reports them: a trailing
- * newline terminates the last line rather than starting an empty extra
- * one. A naive `split('\n').length` over-counts by one for any content
- * ending in `\n` (the common case), which made the size rules fire one
- * line early against the operator's own `wc -l` measurement.
+ * newline terminates the last line rather than starting an empty extra one.
+ * A naive `split('\n').length` over-counts by one for any content ending in
+ * `\n` (the common case), making the size rules fire one line early against
+ * the operator's own `wc -l` measurement.
  */
 function countContentLines(content) {
     const lines = content.split('\n');
@@ -94,50 +93,39 @@ 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. Calibrated against:
+     * `browser/branding/<name>/` subtree.
      *
-     * - 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.
+     * Calibrated against a fresh-fork branding export, which lands around
+     * 15–16k lines (localized brand.ftl across many locales + SVG path data +
+     * copied upstream CSS). That is the MINIMUM branding diff, so it must
+     * surface as a soft `notice` rather than a `warning`: the warning band
+     * sits above it with ~13% headroom, and the error band at roughly 2× the
+     * baseline, where non-branding work is probably 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.
+     * 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: 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.
+ * 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.
+ * patches inherently span many files: PNG/ICO icon assets in 7+ sizes, MSIX
+ * manifests, channel-specific configs, locale `.ftl` files, Windows/macOS
+ * launcher resources. A fresh-fork branding bundle is around 56 files, so 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.
+ * 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,
@@ -145,29 +133,25 @@ const PATCH_FILES_THRESHOLDS = {
     branding: 60,
 };
 /**
- * Shared remedy sentence for the over-budget findings: the two
- * places an operator stands when a patch outgrows its budget must name the
- * sanctioned one-transaction way out, or they reach for the wrong tools
- * first (the field report tried two before finding it). One constant, four
- * emission sites — the wording cannot drift.
+ * Shared remedy sentence for the over-budget findings. Both places an
+ * operator stands when a patch outgrows its budget must name the sanctioned
+ * one-transaction way out, or they reach for the wrong tools first. One
+ * constant, four emission sites, so the wording cannot drift.
  */
 const SPLIT_HINT = 'Consider splitting into smaller, focused patches — ' +
     '"fireforge patch move-files <from> <to> --file <path> --create --order <n>" ' +
     'moves files into a new patch in one transaction.';
 /**
  * Fixed allowlist of non-branding sibling paths that real-world Firefox
- * branding patches legitimately need to touch to register the new
- * branding flavor with the top-level configure. The 2026-04-21
- * external eval showed that a branding patch which also touches
- * `browser/moz.configure` (the canonical registration point) fell
- * through to the general lint tier because the original predicate
- * required every file to live under `browser/branding/`. This
- * allowlist stays intentionally narrow — additions require a real
- * operator data point, not a speculative expansion. Add new entries
- * only when a genuine branding patch cannot be expressed without a
- * specific registration sibling.
+ * branding patches legitimately need to touch to register the new branding
+ * flavor with the top-level configure. A predicate requiring every file to
+ * live under `browser/branding/` drops a branding patch that also touches
+ * `browser/moz.configure` — the canonical registration point — into the
+ * general lint tier.
  *
- * Pinned against ESR 140.x conventions at time of writing.
+ * Intentionally narrow: add entries only when a genuine branding patch
+ * cannot be expressed without a specific registration sibling. Pinned
+ * against ESR 140.x conventions at time of writing.
  */
 const BRANDING_REGISTRATION_FILES = new Set([
     'browser/moz.configure',
@@ -235,33 +219,31 @@ function isBrowserChromeTestFile(file) {
 /**
  * Bare assertion-call detection for the `test-needs-assertion` floor.
  *
- * Each alternative must sit at a call boundary: preceded by something that is
- * not an identifier character, `.`, `#`, or `-`. Until 0.41.0 this was a plain
- * `strippedContent.includes(tok)` over the tokens `Assert.`, `ok(`, `is(`,
- * `isnot(`, `isDeeply(`, so any identifier merely *ending* in one satisfied
- * the gate — `this.axis(3)` contains `is(`, `book(` contains `ok(`,
- * `promiseIsDeeply(` contains `isDeeply(`. An assertion-free smoke test using
- * any such call passed the floor, which is exactly what the rule exists to
- * catch.
+ * Each alternative must sit at a call boundary: preceded by something that
+ * is not an identifier character, `.`, `#`, or `-`. A plain
+ * `strippedContent.includes(tok)` over `Assert.`, `ok(`, `is(`, `isnot(`,
+ * `isDeeply(` lets any identifier merely *ending* in one satisfy the gate —
+ * `this.axis(3)` contains `is(`, `book(` contains `ok(`,
+ * `promiseIsDeeply(` contains `isDeeply(` — so an assertion-free smoke test
+ * using any such call clears the floor.
  *
- * The namespaced arm must name a member and a call. Matching the namespace and
- * its dot alone — as `(?:Assert|SimpleTest)\.` did — re-opened the same hole
- * from the other side: `SimpleTest` is mostly *harness* API, so
- * `SimpleTest.finish()`, `SimpleTest.waitForExplicitFinish()` and
- * `SimpleTest.requestCompleteLog()` each cleared the floor on their own. Those
- * are the exact calls an assertion-free smoke test contains. The enumeration
- * below is the mochitest/xpcshell assertion surface both namespaces share, and
- * it is what the user-facing message already names.
+ * The namespaced arm must name a member AND a call. Matching the namespace
+ * and its dot alone re-opens the same hole from the other side:
+ * `SimpleTest` is mostly *harness* API, so `SimpleTest.finish()`,
+ * `SimpleTest.waitForExplicitFinish()` and `SimpleTest.requestCompleteLog()`
+ * would each clear the floor on their own — the exact calls an
+ * assertion-free smoke test contains. The enumeration below is the
+ * mochitest/xpcshell assertion surface both namespaces share, and it is what
+ * the user-facing message names.
  *
- * Two qualified spellings of the bare four still count: `window.ok(...)` (the
- * globals ARE window properties) and an optional-chained `win?.ok(...)`.
- * Blocking those flagged tests whose only assertions are real as
+ * Two qualified spellings of the bare four also count: `window.ok(...)` (the
+ * globals ARE window properties) and an optional-chained `win?.ok(...)`;
+ * blocking those flags tests whose only assertions are real as
  * assertion-free. `SpecialPowers.ok(` stays excluded — that is API surface,
  * not an assertion.
  *
- * Deliberately still textual, not AST-based: this runs over patch bodies
- * rather than resolvable sources, and the surrounding rule is a floor, not a
- * proof.
+ * Deliberately textual, not AST-based: this runs over patch bodies rather
+ * than resolvable sources, and the surrounding rule is a floor, not a proof.
  */
 const ASSERTION_MEMBERS = [
     'ok',
@@ -318,22 +300,18 @@ export function commentStyleForFile(file) {
  * Accepted shapes, in order:
  *  - the project's own header for the file's comment style;
  *  - under `browser/branding/`, ANY recognised license header in the
- *    matching style: the setup-generated branding directory is copied
- *    from Firefox's `unofficial` template and arrives with Mozilla
- *    MPL-2.0 headers — legitimate for copyright purposes (the assets are
- *    Mozilla's) even when the fork's own code is 0BSD / EUPL-1.2 /
- *    GPL-2.0-or-later;
+ *    matching style: the setup-generated branding directory is copied from
+ *    Firefox's `unofficial` template and arrives with Mozilla MPL-2.0
+ *    headers — legitimate for copyright purposes (the assets are Mozilla's)
+ *    even when the fork's own code is 0BSD / EUPL-1.2 / GPL-2.0-or-later;
  *  - on an MPL-2.0 project, any recognised header in the matching style;
  *  - the verbatim upstream MPL-2.0 block header (`/* … *\/`, optionally
- *    behind a leading editor-directive comment) REGARDLESS of the
- *    project license, on any file whose comment syntax is the block form
- *    (JS and CSS): a file copied from the Firefox tree legitimately
- *    keeps Mozilla's header for provenance in an EUPL/GPL/0BSD project
- *    too. 0.35.0 accepted this on JS only; field verification showed a
- *    derived CSS file carrying the identical three-line block header
- *    still needed a patch-level lintIgnore. Only the block form is
- *    accepted — the `// `-style MPL header is FireForge-generated, not
- *    upstream provenance — and `hash`-style files (FTL) stay excluded
+ *    behind a leading editor-directive comment) REGARDLESS of the project
+ *    license, on any file whose comment syntax is the block form (JS and
+ *    CSS): a file copied from the Firefox tree legitimately keeps Mozilla's
+ *    header for provenance in an EUPL/GPL/0BSD project too. Only the block
+ *    form is accepted — the `// `-style MPL header is FireForge-generated,
+ *    not upstream provenance — and `hash`-style files (FTL) stay excluded
  *    because `/* … *\/` is not a comment there.
  *
  * @param file - Engine-relative path of the new file
@@ -588,16 +566,15 @@ export function lintPatchSize(filesAffected, lineCount, patchTier) {
     const issues = [];
     // 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`
-    // 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.
+    // harnesses run into the thousands of lines). Branding patches get their
+    // own tier so a first export of setup-generated branding does not fire the
+    // general hard limit — see `PATCH_LINE_THRESHOLDS.branding` and
+    // `PATCH_FILES_THRESHOLDS.branding` above. 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 fileThreshold = decision.tier === 'test'
         ? PATCH_FILES_THRESHOLDS.test
@@ -687,23 +664,14 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
  * @param affectedFiles - File paths (relative to repoDir) affected by the patch
  * @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.
- * @param patchTier - Optional explicit tier override, threaded from
- *   `PatchMetadata.tier`. When `"branding"` forces the branding
- *   thresholds on the `large-patch-lines` rule. Callers with a
- *   per-patch manifest context (re-export, per-patch lint) should
- *   pass this; aggregate-mode callers without a specific patch
- *   context skip it and fall through to auto-detection.
- * @param options - Optional behaviour switches; see
- *   {@link LintExportedPatchOptions}.
+ * @param options - Optional context and behaviour switches; see
+ *   {@link LintExportedPatchOptions}. Every optional input lives here
+ *   rather than in a positional tail: four of the five call sites had to
+ *   pass `undefined` placeholders to reach the one member they wanted.
  * @returns Array of all lint issues found
  */
-export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx, ignoreChecks, patchTier, options) {
+export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, options) {
+    const { patchQueueCtx, ignoreChecks, patchTier } = options ?? {};
     const newFiles = detectNewFilesInDiff(diffContent);
     const { textLines: lineCount } = countNonBinaryDiffLines(diffContent);
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);

package/dist/src/core/patch-lock.d.ts

@@ -6,7 +6,7 @@ export interface PatchDirectoryLockOptions {
      * Wait up to this many seconds for the patch directory lock instead of the
      * default ~30 s budget. Enables exponential poll backoff (100 ms → 2 s)
      * and a holder-identified progress line roughly every 5 s. `undefined`
-     * preserves the historical behavior exactly.
+     * keeps the default.
      */
     waitLockSeconds?: number | undefined;
     /** Command name recorded in the lock's owner metadata for holder diagnostics. */

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

@@ -3,7 +3,7 @@
  * Filesystem-based lock for serializing patch directory mutations.
  */
 import { join } from 'node:path';
-import { FireForgeError } from '../errors/base.js';
+import { CommandError, FireForgeError } from '../errors/base.js';
 import { PatchError } from '../errors/patch.js';
 import { assert } from '../utils/assert.js';
 import { toError } from '../utils/errors.js';
@@ -56,7 +56,24 @@ export async function assertPatchDirectoryLockHeld(patchesDir, context) {
 export async function withPatchDirectoryLock(patchesDir, operation, options = {}) {
     const lockDir = join(patchesDir, PATCH_DIRECTORY_LOCK);
     const { waitLockSeconds, command } = options;
-    return withFileLock(lockDir, operation, {
+    // Tag whatever the BODY throws so the catch below can tell it apart from a
+    // lock-acquire/release failure. Narrowing by origin rather than by error
+    // shape is what "the rewrap is for lock I/O" actually means: an errno test
+    // would still reclassify an EACCES raised while the body writes a .patch
+    // file, and a class test cannot see a bare `new Error` from a body at all.
+    let bodyFailure;
+    let bodyThrew = false;
+    const trackedOperation = async () => {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            bodyThrew = true;
+            bodyFailure = error;
+            throw error;
+        }
+    };
+    return withFileLock(lockDir, trackedOperation, {
         ...(waitLockSeconds !== undefined
             ? {
                 timeoutMs: waitLockSeconds * 1000,
@@ -71,12 +88,12 @@ export async function withPatchDirectoryLock(patchesDir, operation, options = {}
         ...(command !== undefined
             ? { ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`] }
             : {}),
-        // Reason first, remedy second. The remedy is waiting, not
-        // deleting: bulk exports/re-exports legitimately hold this lock for
-        // minutes, FireForge reaps genuinely stale locks on its own, and the
-        // old advice ("rm -rf" while a holder was alive) destroyed a live
-        // lock. The leading sentence is a message contract; extend, don't
-        // reword. withFileLock appends the holder identification.
+        // Reason first, remedy second. The remedy is waiting, not deleting: bulk
+        // exports/re-exports legitimately hold this lock for minutes, and
+        // FireForge reaps genuinely stale locks on its own — advice to `rm -rf`
+        // while a holder is alive destroys a live lock. The leading sentence is
+        // a message contract; extend, do not reword. withFileLock appends the
+        // holder identification.
         onTimeoutMessage: `Timed out waiting for another FireForge command mutating ${patchesDir}.\n` +
             `Pass --wait-lock [seconds] to wait longer (bare --wait-lock waits up to 60 seconds). ` +
             `FireForge removes genuinely stale locks automatically; only if no other fireforge ` +
@@ -84,9 +101,28 @@ export async function withPatchDirectoryLock(patchesDir, operation, options = {}
         onStaleLockMessage: (ageMs) => `Removing stale patch lock (age: ${Math.round(ageMs / 1000)}s). ` +
             'A previous fireforge process may have crashed.',
     }).catch((error) => {
+        // The body's own failures are never ours to reclassify. Rewrapping them
+        // reports an EACCES writing patches.json, a postcondition failure from
+        // renumberPatchesInManifest, or a plain TypeError from a FireForge bug
+        // as a "Patch Error" carrying three fixed remedies about Firefox-version
+        // compatibility and `fireforge reset` — none of which apply. Worse,
+        // src/cli.ts prints a stack only for non-FireForgeError throwables, so
+        // the rewrap moves real bugs into the branch that discards their stack.
+        if (bodyThrew && error === bodyFailure) {
+            throw error;
+        }
         if (error instanceof FireForgeError) {
             throw error;
         }
-        throw new PatchError(toError(error).message);
+        // CommandError is the one class in src/errors/ that does NOT extend
+        // FireForgeError: it is the sentinel carrying an already-rendered exit
+        // code to the entrypoint. The `instanceof FireForgeError` guard above
+        // misses it, so without this the exit code was replaced by PATCH_ERROR.
+        if (error instanceof CommandError) {
+            throw error;
+        }
+        // What remains is a genuine failure to acquire or release the lock.
+        const cause = toError(error);
+        throw new PatchError(cause.message, undefined, cause);
     });
 }

package/dist/src/core/patch-manifest-consistency.d.ts

@@ -2,6 +2,7 @@
  * Manifest consistency checks and rebuild/recovery operations.
  */
 import type { PatchesManifest } from '../types/commands/index.js';
+import type { PatchDirectoryLockOptions } from './patch-lock.js';
 /** Consistency issue codes for manifest validation. */
 export interface PatchManifestConsistencyIssue {
     code: 'manifest-invalid' | 'manifest-missing' | 'missing-patch-file' | 'untracked-patch-file' | 'files-affected-mismatch' | 'duplicate-manifest-entry';
@@ -14,6 +15,16 @@ export interface PatchManifestConsistencyIssue {
  * @returns Consistency issues between manifest metadata and on-disk patch files
  */
 export declare function validatePatchesManifestConsistency(patchesDir: string): Promise<PatchManifestConsistencyIssue[]>;
+/**
+ * Recovery hint for an unrepaired consistency failure.
+ *
+ * Drift that is only in `filesAffected` is a derived value disagreeing with
+ * the diff it describes, and the narrow repair fixes exactly that. Naming the
+ * whole-manifest rebuild for it — as this hint used to, unconditionally — puts
+ * an operator one keystroke from rewriting every row in the manifest to
+ * correct one list.
+ */
+export declare function recommendManifestRepair(issues: readonly PatchManifestConsistencyIssue[]): string;
 /**
  * Summary of a {@link rebuildPatchesManifest} run. `recoveredFilenames`
  * lists patches whose manifest entry was reconstructed from filename,
@@ -24,21 +35,61 @@ export declare function validatePatchesManifestConsistency(patchesDir: string):
  * invented vs which was restored.
  */
 export interface RebuildPatchesManifestResult {
-    /** Rebuilt manifest, ready to be re-applied by callers (already persisted). */
+    /**
+     * Rebuilt manifest, ready to be re-applied by callers. Persisted unless
+     * the run was a dry run — see {@link RebuildPatchesManifestResult.written}.
+     */
     manifest: PatchesManifest;
     /**
      * Filenames whose manifest entry had no pre-existing metadata to
      * preserve — every descriptive field on these entries is inferred.
      */
     recoveredFilenames: string[];
+    /**
+     * Filenames that had a manifest entry but no patch file on disk, so the
+     * row was dropped. Discarding these silently is how a manifest quietly
+     * loses rows an operator still expected to be there.
+     */
+    droppedFilenames: string[];
+    /** False when the run was a dry run and patches.json was left untouched. */
+    written: boolean;
+}
+/** Options for {@link rebuildPatchesManifest}. */
+export interface RebuildPatchesManifestOptions extends PatchDirectoryLockOptions {
+    /**
+     * Proceed even when patches.json exists but cannot be parsed, in which case
+     * there is no existing metadata to preserve and every descriptive field on
+     * every entry is invented. Refused without this flag — see
+     * {@link rebuildPatchesManifest}.
+     */
+    allowMetadataLoss?: boolean;
+    /** Compute the rebuilt manifest without writing it. */
+    dryRun?: boolean;
 }
 /**
  * Rebuilds patches.json from the patch files currently present on disk.
- * Existing metadata is preserved when possible; missing entries are recovered
- * from filename structure, patch contents, and file mtimes.
+ *
+ * This is a MERGE, not a from-scratch rebuild: only `filesAffected` and
+ * `order` are recomputed from the patch files, and every other field on an
+ * existing entry is carried forward untouched. Entries with no pre-existing
+ * metadata are recovered from filename structure, patch contents, and file
+ * mtimes.
+ *
+ * Refuses when patches.json exists but cannot be parsed, because that is the
+ * one case where nothing can be carried forward and the "merge" silently
+ * becomes a whole-manifest reinvention. Pass `allowMetadataLoss` to accept it.
+ *
  * @param patchesDir - Path to the patches directory
  * @param fallbackSourceEsrVersion - source version to use for recovered legacy entries
- * @returns {@link RebuildPatchesManifestResult} — the persisted manifest
- *   plus the filenames that were reconstructed from generic defaults.
+ * @param options - Lock options plus `allowMetadataLoss` / `dryRun`
+ * @returns {@link RebuildPatchesManifestResult} — the rebuilt manifest, the
+ *   filenames that were reconstructed from generic defaults, and the rows
+ *   dropped because their patch file is gone.
+ */
+export declare function rebuildPatchesManifest(patchesDir: string, fallbackSourceEsrVersion: string, options?: RebuildPatchesManifestOptions): Promise<RebuildPatchesManifestResult>;
+/**
+ * Canonical form of a `filesAffected` list: deduplicated and sorted, so a
+ * comparison between a declared list and one extracted from a patch body is
+ * about membership rather than ordering.
  */
-export declare function rebuildPatchesManifest(patchesDir: string, fallbackSourceEsrVersion: string): Promise<RebuildPatchesManifestResult>;
+export declare function normalizeAffectedFiles(files: string[]): string[];