@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,129 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Filesystem-based lock for serializing patch directory mutations.
- */
-import { join } from 'node:path';
-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';
-import { info } from '../utils/logger.js';
-import { formatLockQueuePosition, readLockStatus, withFileLock } from './file-lock.js';
-const PATCH_DIRECTORY_LOCK = '.fireforge-patches.lock';
-/**
- * Formats the periodic operator-facing waiting line printed while
- * `--wait-lock` polls a contended patch directory lock. Mirrors the engine
- * session lock's progress line so operators read one shape for both locks.
- */
-function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
-    const progress = `${Math.round(waitedMs / 1000)}s of up to ${Math.round(timeoutMs / 1000)}s`;
-    const position = formatLockQueuePosition(queue);
-    if (holder === undefined) {
-        return `Waiting for the FireForge patch directory lock — ${progress}.${position}`;
-    }
-    const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
-    return `Waiting for the FireForge patch directory lock held by PID ${holder.pid}${details} — ${progress}.${position}`;
-}
-/**
- * Asserts that this process is inside {@link withPatchDirectoryLock} for the
- * given patches directory.
- *
- * The manifest mutators document "under the caller's lock" and are reached
- * from six different command bodies, none of which the mutator can see. This
- * turns that comment into a check at the point it matters: filename
- * allocation and manifest read-modify-writes are only atomic while the lock
- * is held, so an unlocked caller silently reintroduces the interleaving the
- * lock exists to prevent.
- *
- * Fail-open on an unreadable owner record, on purpose: `withFileLock`
- * treats writing that record as non-fatal, so a live holder can legitimately
- * have no readable PID and asserting on its presence would fire on a lock we
- * really do hold.
- *
- * @param patchesDir - The patches directory whose lock must be held
- * @param context - What is about to be done, for the failure message
- * @throws {@link InternalInvariantError} when the lock is not held by us.
- */
-export async function assertPatchDirectoryLockHeld(patchesDir, context) {
-    const status = await readLockStatus(join(patchesDir, PATCH_DIRECTORY_LOCK));
-    assert(status.held, () => `patch directory lock is held before ${context}`);
-    assert(status.holder === undefined || status.holder.pid === process.pid, () => `patch directory lock is owned by this process before ${context} ` +
-        `(held by PID ${status.holder?.pid}, we are ${process.pid})`);
-}
-/**
- * Runs a patch directory mutation while holding an exclusive filesystem lock.
- * This serializes filename allocation and manifest writes across parallel exports.
- */
-export async function withPatchDirectoryLock(patchesDir, operation, options = {}) {
-    const lockDir = join(patchesDir, PATCH_DIRECTORY_LOCK);
-    const { waitLockSeconds, command } = options;
-    // 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,
-                pollMs: 100,
-                pollMaxMs: 2000,
-                waitProgressMs: 5000,
-                onWaitProgress: ({ waitedMs, timeoutMs, holder, queue }) => {
-                    info(formatWaitProgressLine(waitedMs, timeoutMs, holder, queue));
-                },
-            }
-            : {}),
-        ...(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, and
-        // FireForge reaps genuinely stale locks on its own, and 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 ` +
-            `process is running and the timeout persists, remove the lock manually:\n  rm -rf "${lockDir}"`,
-        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;
-        }
-        // 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

@@ -1,95 +0,0 @@
-/**
- * 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';
-    filename: string;
-    message: string;
-}
-/**
- * Validates that patches.json and the patch directory describe the same patch set.
- * @param patchesDir - Path to the patches directory
- * @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 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,
- * mtime, and diff alone (no pre-existing manifest entry to preserve).
- * These entries carry generic descriptions and mtime-based
- * timestamps. Callers like `doctor --repair-patches-manifest` surface
- * a per-patch review warning so operators know which metadata was
- * invented vs which was restored.
- */
-export interface RebuildPatchesManifestResult {
-    /**
-     * 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.
- *
- * 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 entries that carry none
- * @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 normalizeAffectedFiles(files: string[]): string[];

package/dist/src/core/patch-manifest-consistency.js

@@ -1,256 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Manifest consistency checks and rebuild/recovery operations.
- */
-import { stat } from 'node:fs/promises';
-import { GeneralError } from '../errors/base.js';
-import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
-import { withPatchDirectoryLock } from './patch-lock.js';
-import { loadPatchesManifestState, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest-io.js';
-import { inferPatchMetadataFromFilename } from './patch-manifest-validate.js';
-import { manifestWithRetiredSlots } from './patch-retired.js';
-/**
- * Validates that patches.json and the patch directory describe the same patch set.
- * @param patchesDir - Path to the patches directory
- * @returns Consistency issues between manifest metadata and on-disk patch files
- */
-export async function validatePatchesManifestConsistency(patchesDir) {
-    const manifestState = await loadPatchesManifestState(patchesDir);
-    const patches = await discoverPatches(patchesDir);
-    const issues = [];
-    if (manifestState.parseError) {
-        issues.push({
-            code: 'manifest-invalid',
-            filename: PATCHES_MANIFEST,
-            message: `patches.json exists but could not be parsed: ${manifestState.parseError.message}`,
-        });
-        return issues;
-    }
-    if (!manifestState.exists) {
-        if (patches.length > 0) {
-            issues.push({
-                code: 'manifest-missing',
-                filename: PATCHES_MANIFEST,
-                message: `patches.json is missing while ${patches.length} patch file(s) exist.`,
-            });
-        }
-        return issues;
-    }
-    const manifest = manifestState.manifest;
-    if (!manifest) {
-        return issues;
-    }
-    const patchByFilename = new Map(patches.map((patch) => [patch.filename, patch]));
-    const seenManifestEntries = new Set();
-    for (const metadata of manifest.patches) {
-        if (seenManifestEntries.has(metadata.filename)) {
-            issues.push({
-                code: 'duplicate-manifest-entry',
-                filename: metadata.filename,
-                message: `patches.json contains duplicate metadata entries for ${metadata.filename}.`,
-            });
-            continue;
-        }
-        seenManifestEntries.add(metadata.filename);
-        const patch = patchByFilename.get(metadata.filename);
-        if (!patch) {
-            issues.push({
-                code: 'missing-patch-file',
-                filename: metadata.filename,
-                message: `${metadata.filename} is listed in patches.json but the patch file is missing.`,
-            });
-            continue;
-        }
-        const declaredFiles = normalizeAffectedFiles(metadata.filesAffected);
-        const actualFiles = normalizeAffectedFiles(await getAllTargetFilesFromPatch(patch.path));
-        if (!sameStringArray(declaredFiles, actualFiles)) {
-            issues.push({
-                code: 'files-affected-mismatch',
-                filename: metadata.filename,
-                message: `${metadata.filename} declares [${declaredFiles.join(', ')}] in patches.json ` +
-                    `but the patch file targets [${actualFiles.join(', ')}].`,
-            });
-        }
-        patchByFilename.delete(metadata.filename);
-    }
-    for (const orphanPatch of patchByFilename.values()) {
-        issues.push({
-            code: 'untracked-patch-file',
-            filename: orphanPatch.filename,
-            message: `${orphanPatch.filename} exists on disk but is not tracked in patches.json.`,
-        });
-    }
-    return issues;
-}
-/**
- * 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 puts
- * an operator one keystroke from rewriting every row in the manifest to
- * correct one list.
- */
-export function recommendManifestRepair(issues) {
-    const filesAffectedOnly = issues.length > 0 && issues.every((issue) => issue.code === 'files-affected-mismatch');
-    return filesAffectedOnly
-        ? 'Run "fireforge doctor --repair-files-affected" to recompute filesAffected from the patch ' +
-            'bodies (add --dry-run to preview). It rewrites only the drifted lists and leaves every ' +
-            'other manifest field untouched.'
-        : 'Run "fireforge doctor --repair-patches-manifest" to rebuild patches.json from the patch ' +
-            'files (add --dry-run to preview). Only filesAffected and order are recomputed; every ' +
-            'other field on an existing entry is preserved.';
-}
-/**
- * Rebuilds patches.json from the patch files currently present on disk.
- *
- * 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 entries that carry none
- * @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 async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion, options = {}) {
-    // The whole read → discover → rebuild → save cycle runs under the shared
-    // patch-directory lock (invariant 2, docs/lifecycle-invariants.md):
-    // manifest writes serialize on this lock, so without it a repair racing a
-    // concurrent export/reorder can clobber the other writer's manifest. Not
-    // reentrant: callers must not already hold it.
-    //
-    // A dry run takes the lock too: it reads the same manifest and patch bodies
-    // a real run would, and a projection computed against a queue being
-    // rewritten underneath is worth less than no projection at all.
-    return withPatchDirectoryLock(patchesDir, () => rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion, options), options);
-}
-async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion, options) {
-    const manifestState = await loadPatchesManifestState(patchesDir);
-    const existingEntries = new Map();
-    // An unparseable manifest yields `manifest: null`, which the merge below
-    // cannot distinguish from "no manifest at all". Every entry would be
-    // treated as new and every descriptive field reinvented. `filesAffected`
-    // is the only field a .patch body can yield. `stagedDependencies`,
-    // `lintIgnore`, `tier`, `description`, `category`, `createdAt` and the
-    // source version cannot be reconstructed from a diff at all. Refuse rather
-    // than write that, since the write is what makes it unrecoverable on a
-    // queue that is not under version control.
-    if (manifestState.exists && manifestState.parseError && options.allowMetadataLoss !== true) {
-        throw new GeneralError(`Refusing to rebuild ${PATCHES_MANIFEST}: it exists but could not be parsed ` +
-            `(${manifestState.parseError.message}). None of its metadata can be carried ` +
-            'forward, so every entry would be rebuilt with an invented description, an ' +
-            'mtime-based createdAt and an inferred category, and any stagedDependencies, ' +
-            'lintIgnore or tier declarations would be lost — a patch body carries none of ' +
-            'them.\n' +
-            `Fix the JSON in ${PATCHES_MANIFEST} (restore it from version control if you ` +
-            'can) and re-run, or pass --allow-metadata-loss to accept the reinvention.');
-    }
-    if (manifestState.manifest) {
-        for (const entry of manifestState.manifest.patches) {
-            existingEntries.set(entry.filename, entry);
-        }
-    }
-    const patches = await discoverPatches(patchesDir);
-    const rebuiltPatches = [];
-    const recoveredFilenames = [];
-    const highestFiniteOrder = patches.reduce((highest, patch) => {
-        return Number.isFinite(patch.order) ? Math.max(highest, patch.order) : highest;
-    }, 0);
-    let nextRecoveredOrder = highestFiniteOrder + 1;
-    // Prefetch the two independent per-patch reads concurrently. This runs
-    // while the patch-directory lock is held, and as two serialised awaits per
-    // patch it costs 58 round-trips on a 29-patch queue. The fold below stays
-    // sequential because `nextRecoveredOrder` is loop-carried: parallelising
-    // the assignment would scramble the recovered ordinals.
-    const prefetched = await Promise.all(patches.map(async (patch) => ({
-        filesAffected: normalizeAffectedFiles(await getAllTargetFilesFromPatch(patch.path)),
-        patchStats: await stat(patch.path),
-    })));
-    for (const [index, patch] of patches.entries()) {
-        const existing = existingEntries.get(patch.filename);
-        const prefetch = prefetched[index];
-        if (!prefetch)
-            continue;
-        const { filesAffected, patchStats } = prefetch;
-        const inferred = inferPatchMetadataFromFilename(patch.filename);
-        const recoveredOrder = Number.isFinite(patch.order) ? patch.order : nextRecoveredOrder++;
-        if (!existing) {
-            // Track every filename that had no pre-existing manifest entry so
-            // callers can warn the operator per-patch. A missing entry means every
-            // descriptive field (`description`, `createdAt`, `category`) was
-            // invented rather than preserved, and FireForge patch files carry no
-            // header metadata that could carry a human description forward, so
-            // visibility is the best available, and silent overwrites of
-            // human-written descriptions during a recovery run are the failure to
-            // avoid.
-            recoveredFilenames.push(patch.filename);
-        }
-        // The rebuild owns exactly two fields: `filesAffected` (recomputed from
-        // the patch body) and `order` (from the filename ordinal). Everything
-        // else on an existing entry is carried forward by the spread, so a field
-        // a .patch cannot express (`stagedDependencies`, `lintIgnore`, `tier`,
-        // and whatever is added to PatchMetadata next) survives a repair without
-        // anyone remembering to list it here. It was an enumerated literal until
-        // `stagedDependencies` was dropped from every entry that had one, which
-        // is the failure this shape prevents from recurring.
-        const rebuilt = {
-            ...(existing ?? {}),
-            filename: patch.filename,
-            order: recoveredOrder,
-            category: existing?.category ?? inferred.category,
-            name: existing?.name ?? inferred.name,
-            description: existing?.description ??
-                `Recovered manifest entry for ${patch.filename}. Review description and source version.`,
-            createdAt: existing?.createdAt ?? new Date(patchStats.mtimeMs).toISOString(),
-            sourceEsrVersion: existing?.sourceEsrVersion ?? fallbackSourceEsrVersion,
-            sourceVersion: existing?.sourceVersion ?? existing?.sourceEsrVersion ?? fallbackSourceEsrVersion,
-            filesAffected,
-        };
-        // Copy the arrays rather than aliasing the loaded manifest's, so a caller
-        // mutating the rebuilt entry cannot reach back into `manifestState`.
-        if (existing?.lintIgnore !== undefined) {
-            rebuilt.lintIgnore = existing.lintIgnore.map((entry) => typeof entry === 'string' ? entry : { ...entry });
-        }
-        rebuiltPatches.push(rebuilt);
-        existingEntries.delete(patch.filename);
-    }
-    rebuiltPatches.sort((left, right) => left.order - right.order || left.filename.localeCompare(right.filename));
-    // Retired slots have no patch file to recover them from, so they ride
-    // along from the loaded manifest like the per-row fields above.
-    const rebuiltManifest = manifestWithRetiredSlots(manifestState.manifest, rebuiltPatches);
-    // Whatever is left in the map had a manifest row but no patch file, so the
-    // rebuild drops it. That is the correct outcome, since the file is the
-    // source of truth, but dropping rows without naming them is
-    // indistinguishable from never having had them.
-    const droppedFilenames = [...existingEntries.keys()].sort((left, right) => left.localeCompare(right));
-    if (options.dryRun === true) {
-        return {
-            manifest: rebuiltManifest,
-            recoveredFilenames,
-            droppedFilenames,
-            written: false,
-        };
-    }
-    await savePatchesManifest(patchesDir, rebuiltManifest);
-    return { manifest: rebuiltManifest, recoveredFilenames, droppedFilenames, written: true };
-}
-/**
- * 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 function normalizeAffectedFiles(files) {
-    return Array.from(new Set(files)).sort((left, right) => left.localeCompare(right));
-}
-function sameStringArray(left, right) {
-    return left.length === right.length && left.every((value, index) => value === right[index]);
-}

package/dist/src/core/patch-manifest-files-affected.d.ts

@@ -1,43 +0,0 @@
-/**
- * Narrow repair for `filesAffected`, the one manifest field a `.patch` body
- * can actually yield.
- *
- * A `files-affected-mismatch` is pure derived-value drift: the manifest's list
- * disagrees with the diff it describes, and the diff is right by definition.
- * Rebuilding the whole manifest to fix it is a much larger operation than the
- * failure calls for, so this repair recomputes one field on the drifted rows
- * and leaves every other row byte-identical.
- */
-import type { PatchDirectoryLockOptions } from './patch-lock.js';
-/** One row whose `filesAffected` list disagreed with its patch body. */
-export interface FilesAffectedRepair {
-    /** Patch filename. */
-    filename: string;
-    /** The list the manifest declared, normalized for comparison. */
-    before: string[];
-    /** The list the patch body actually targets. */
-    after: string[];
-}
-/** Summary of a {@link repairPatchesFilesAffected} run. */
-export interface RepairFilesAffectedResult {
-    /** Rows that drifted and were (or would be) corrected. */
-    repairs: FilesAffectedRepair[];
-    /** Requested filenames with no manifest row, or no patch file on disk. */
-    skippedFilenames: string[];
-    /** False when the run was a dry run and patches.json was left untouched. */
-    written: boolean;
-}
-/** Options for {@link repairPatchesFilesAffected}. */
-export interface RepairFilesAffectedOptions extends PatchDirectoryLockOptions {
-    /** Compute the corrections without writing them. */
-    dryRun?: boolean;
-}
-/**
- * Recomputes `filesAffected` from the patch body for the named patches.
- *
- * @param patchesDir - Path to the patches directory
- * @param filenames - Patch filenames to repair
- * @param options - Lock options plus `dryRun`
- * @returns The corrections applied (or projected) and the filenames skipped
- */
-export declare function repairPatchesFilesAffected(patchesDir: string, filenames: readonly string[], options?: RepairFilesAffectedOptions): Promise<RepairFilesAffectedResult>;

package/dist/src/core/patch-manifest-files-affected.js

@@ -1,77 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Narrow repair for `filesAffected`, the one manifest field a `.patch` body
- * can actually yield.
- *
- * A `files-affected-mismatch` is pure derived-value drift: the manifest's list
- * disagrees with the diff it describes, and the diff is right by definition.
- * Rebuilding the whole manifest to fix it is a much larger operation than the
- * failure calls for, so this repair recomputes one field on the drifted rows
- * and leaves every other row byte-identical.
- */
-import { GeneralError } from '../errors/base.js';
-import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
-import { withPatchDirectoryLock } from './patch-lock.js';
-import { normalizeAffectedFiles } from './patch-manifest-consistency.js';
-import { loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, } from './patch-manifest-io.js';
-/**
- * Recomputes `filesAffected` from the patch body for the named patches.
- *
- * @param patchesDir - Path to the patches directory
- * @param filenames - Patch filenames to repair
- * @param options - Lock options plus `dryRun`
- * @returns The corrections applied (or projected) and the filenames skipped
- */
-export async function repairPatchesFilesAffected(patchesDir, filenames, options = {}) {
-    // Same lock contract as the full rebuild (invariant 2,
-    // docs/lifecycle-invariants.md): a manifest write serializes on the
-    // patch-directory lock, and a dry run reads under it so its projection
-    // cannot be computed against a queue being rewritten underneath.
-    return withPatchDirectoryLock(patchesDir, () => repairPatchesFilesAffectedUnderLock(patchesDir, filenames, options), options);
-}
-async function repairPatchesFilesAffectedUnderLock(patchesDir, filenames, options) {
-    // ForWrite: a corrupt manifest must abort here rather than be treated as
-    // empty. This repair exists precisely so that a one-field drift never
-    // reaches a whole-manifest rewrite, and silently writing over unparseable
-    // metadata would be a larger version of what it avoids.
-    const manifest = await loadPatchesManifestForWrite(patchesDir);
-    if (!manifest) {
-        throw new GeneralError(`Cannot repair filesAffected: ${PATCHES_MANIFEST} does not exist in ${patchesDir}.`);
-    }
-    const patchPathByFilename = new Map((await discoverPatches(patchesDir)).map((patch) => [patch.filename, patch.path]));
-    const rowByFilename = new Map(manifest.patches.map((entry) => [entry.filename, entry]));
-    const repairs = [];
-    const skippedFilenames = [];
-    for (const filename of new Set(filenames)) {
-        const patchPath = patchPathByFilename.get(filename);
-        const row = rowByFilename.get(filename);
-        if (patchPath === undefined || !row) {
-            // A missing patch file or a missing row is a different consistency
-            // issue with a different remedy. This repair reports it rather than
-            // inventing a row or deleting one.
-            skippedFilenames.push(filename);
-            continue;
-        }
-        const before = normalizeAffectedFiles(row.filesAffected);
-        const after = normalizeAffectedFiles(await getAllTargetFilesFromPatch(patchPath));
-        if (sameFiles(before, after))
-            continue;
-        repairs.push({ filename, before, after });
-    }
-    skippedFilenames.sort((left, right) => left.localeCompare(right));
-    if (repairs.length === 0 || options.dryRun === true) {
-        return { repairs, skippedFilenames, written: false };
-    }
-    const correctedByFilename = new Map(repairs.map((repair) => [repair.filename, repair.after]));
-    // Row-scoped mutation, so every untouched entry keeps its exact JSON shape:
-    // no re-sorted `filesAffected` lists and no reader-only fallback fields
-    // serialized into rows this repair has no business touching.
-    await mutatePatchRowsInManifest(patchesDir, [...correctedByFilename.keys()], (existing) => {
-        const corrected = correctedByFilename.get(existing.filename);
-        return corrected ? { set: { filesAffected: corrected } } : null;
-    });
-    return { repairs, skippedFilenames, written: true };
-}
-function sameFiles(left, right) {
-    return left.length === right.length && left.every((value, index) => value === right[index]);
-}