@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,556 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Manifest I/O: load, save, and mutating operations for patches.json.
- *
- * Mutations (add / remove / renumber) are intended to be the only sanctioned
- * way to change on-disk manifest state. They run under the shared patch
- * directory lock so concurrent commands cannot race each other into
- * inconsistent manifests.
- */
-import { randomUUID } from 'node:crypto';
-import { rename } from 'node:fs/promises';
-import { join } from 'node:path';
-import { FireForgeError } from '../errors/base.js';
-import { ExitCode } from '../errors/codes.js';
-import { PatchError, PatchManifestCorruptError } from '../errors/patch.js';
-import { assert } from '../utils/assert.js';
-import { toError } from '../utils/errors.js';
-import { pathExistsStrict, readJson, removeFile, writeJson } from '../utils/fs.js';
-import { warn } from '../utils/logger.js';
-import { isArray, isObject } from '../utils/validation.js';
-import { assertPatchDirectoryLockHeld } from './patch-lock.js';
-import { canonicalizeManifest } from './patch-manifest-key-order.js';
-import { validatePatchesManifest } from './patch-manifest-validate.js';
-import { manifestWithRetiredSlots } from './patch-retired.js';
-/** Filename for the patches manifest */
-export const PATCHES_MANIFEST = 'patches.json';
-/**
- * Loads and validates the patches manifest, returning full state information.
- * @param patchesDir - Path to the patches directory
- */
-export async function loadPatchesManifestState(patchesDir) {
-    const manifestPath = join(patchesDir, PATCHES_MANIFEST);
-    if (!(await pathExistsStrict(manifestPath))) {
-        return { exists: false, manifest: null, parseError: undefined };
-    }
-    try {
-        const manifest = validatePatchesManifest(await readJson(manifestPath));
-        return {
-            exists: true,
-            manifest,
-            parseError: undefined,
-        };
-    }
-    catch (error) {
-        return {
-            exists: true,
-            manifest: null,
-            parseError: toError(error),
-        };
-    }
-}
-/**
- * Loads the patches manifest if it exists.
- *
- * Read-only callers only: this collapses "absent" and "corrupt" into null.
- * Any code path that writes the manifest (or deletes patch files based
- * on its content) must use {@link loadPatchesManifestForWrite} instead.
- * Treating a corrupt manifest as empty and then saving destroys every
- * existing patch's metadata.
- *
- * @param patchesDir - Path to the patches directory
- * @returns PatchesManifest or null if not found
- */
-export async function loadPatchesManifest(patchesDir) {
-    const state = await loadPatchesManifestState(patchesDir);
-    return state.manifest;
-}
-/**
- * Loads the patches manifest for a mutating operation.
- *
- * Returns null only when the manifest genuinely does not exist. A manifest
- * that exists but fails to parse/validate throws
- * {@link PatchManifestCorruptError} so the caller aborts instead of
- * rebuilding an empty queue over the top of the corrupt file.
- */
-export async function loadPatchesManifestForWrite(patchesDir) {
-    const state = await loadPatchesManifestState(patchesDir);
-    if (state.exists && state.manifest === null) {
-        throw new PatchManifestCorruptError(join(patchesDir, PATCHES_MANIFEST), state.parseError);
-    }
-    return state.manifest;
-}
-/**
- * Saves the patches manifest.
- * @param patchesDir - Path to the patches directory
- * @param manifest - Manifest to save
- */
-export async function savePatchesManifest(patchesDir, manifest) {
-    const manifestPath = join(patchesDir, PATCHES_MANIFEST);
-    await writeJson(manifestPath, canonicalizeManifest(manifest));
-}
-/**
- * Mutates selected manifest rows while preserving the raw JSON fields of every
- * untouched row. This avoids serializing reader-only fallback fields, such as
- * `sourceVersion` derived from legacy `sourceEsrVersion`, into unrelated patch
- * entries during partial metadata updates.
- *
- * Every row's keys (and the manifest's own) are written in canonical order,
- * not only the changed rows', so the working copy matches what `patch stage`
- * and full saves write and no commit flips untouched rows' key order.
- */
-export async function mutatePatchRowsInManifest(patchesDir, filenames, mutator) {
-    const manifestPath = join(patchesDir, PATCHES_MANIFEST);
-    if (!(await pathExistsStrict(manifestPath)))
-        return null;
-    const rawManifest = await readJson(manifestPath);
-    // `validatePatchesManifest` has already rejected a manifest that is not an
-    // object with an array of object rows (it throws the corruption error the
-    // caller expects), so the shape re-checks below are FireForge's own
-    // invariants, not input validation: failing them means the validator and
-    // this walker disagree about the manifest schema, which is a bug here.
-    const beforeManifest = validatePatchesManifest(rawManifest);
-    assert(isObject(rawManifest) && isArray(rawManifest['patches']), 'validated patches.json is a JSON object with a patches array');
-    const filenameSet = new Set(filenames);
-    if (filenameSet.size === 0)
-        return [];
-    const rawPatches = rawManifest['patches'].map((entry, index) => {
-        assert(isObject(entry), () => `validated patches.json row ${index} is an object`);
-        return { ...entry };
-    });
-    const changedIndexes = [];
-    for (const [index, rawPatch] of rawPatches.entries()) {
-        const filename = rawPatch['filename'];
-        if (typeof filename !== 'string' || !filenameSet.has(filename))
-            continue;
-        const existing = beforeManifest.patches[index];
-        if (!existing)
-            continue;
-        // Manifest rows come out of JSON.parse and were object-checked above,
-        // so the JsonObject contract holds. The row stays a plain record
-        // internally because `mutation.set` values carry interface types
-        // (`Partial<PatchMetadata>`) that the compiler cannot relate to
-        // `JsonValue` structurally.
-        const mutation = mutator(existing, rawPatch);
-        if (!mutation)
-            continue;
-        for (const [field, value] of Object.entries(mutation.set ?? {})) {
-            rawPatch[field] = value;
-        }
-        for (const field of mutation.unset ?? []) {
-            rawPatch[field] = undefined;
-        }
-        changedIndexes.push(index);
-    }
-    if (changedIndexes.length === 0)
-        return [];
-    // Every row is put in canonical key order, not only the changed ones:
-    // `patch stage` and full saves canonicalize the whole manifest, so a
-    // row left in any other order flips back and forth between the
-    // working copy and the index. Reordering keys adds no field.
-    const nextRawManifest = canonicalizeManifest({
-        ...rawManifest,
-        patches: rawPatches,
-    });
-    const afterManifest = validatePatchesManifest(nextRawManifest);
-    await writeJson(manifestPath, nextRawManifest);
-    return changedIndexes.map((index) => ({
-        before: beforeManifest.patches[index],
-        after: afterManifest.patches[index],
-    }));
-}
-/**
- * Adds or updates a patch entry in the manifest.
- * @param patchesDir - Path to the patches directory
- * @param metadata - Patch metadata to add/update
- * @param removeFilenames - Optional filenames to remove in the same read-modify-write cycle
- */
-export async function addPatchToManifest(patchesDir, metadata, removeFilenames) {
-    // ForWrite: a corrupt manifest must abort here, not be rebuilt as empty.
-    const manifest = (await loadPatchesManifestForWrite(patchesDir)) ?? {
-        version: 1,
-        patches: [],
-    };
-    // Remove existing entry with same filename if present
-    manifest.patches = manifest.patches.filter((p) => p.filename !== metadata.filename);
-    // Remove superseded entries in the same cycle to avoid race conditions
-    if (removeFilenames && removeFilenames.length > 0) {
-        const removeSet = new Set(removeFilenames);
-        manifest.patches = manifest.patches.filter((p) => !removeSet.has(p.filename));
-    }
-    // Add new entry and sort by order
-    manifest.patches.push(metadata);
-    manifest.patches.sort((a, b) => a.order - b.order);
-    // A patch landing on a retired order fills that slot.
-    await savePatchesManifest(patchesDir, manifestWithRetiredSlots(manifest, manifest.patches));
-}
-/**
- * Removes a single patch entry from the manifest by filename. Leaves the
- * ordinal gap in place. Callers wanting to close the gap must use
- * {@link renumberPatchesInManifest} explicitly. This matches the spec: delete
- * is a row removal, not a resequencing.
- *
- * Not atomic with any on-disk patch file deletion. Callers are expected to
- * remove the .patch file separately under the same lock.
- *
- * @param patchesDir - Path to the patches directory
- * @param filename - Filename of the patch to remove from the manifest
- * @param retiredSlot - Optional placeholder to record for the removed order
- * @returns True when the manifest was written (i.e. an entry was removed),
- *   false when no matching entry existed
- */
-export async function removePatchFromManifest(patchesDir, filename, retiredSlot) {
-    const manifest = await loadPatchesManifestForWrite(patchesDir);
-    if (!manifest)
-        return false;
-    const originalLength = manifest.patches.length;
-    manifest.patches = manifest.patches.filter((p) => p.filename !== filename);
-    if (manifest.patches.length === originalLength) {
-        return false;
-    }
-    if (retiredSlot !== undefined) {
-        // `patch retire`: the row leaves and its order stays spent, in the
-        // same write, so no reader ever sees the gap in between.
-        manifest.retired = [
-            ...(manifest.retired ?? []).filter((slot) => slot.order !== retiredSlot.order),
-            retiredSlot,
-        ].sort((a, b) => a.order - b.order);
-    }
-    await savePatchesManifest(patchesDir, manifest);
-    return true;
-}
-/**
- * Checks the shape a renumbered manifest is supposed to have, immediately
- * before it becomes durable.
- *
- * Three properties, each of which the queue silently depends on: `order` is
- * unique (two patches claiming one slot make apply order arbitrary),
- * `order` matches the numeric prefix of `filename` (the prefix is what an
- * operator reads and what `patch` commands parse back out), and the rows are
- * sorted ascending (readers take manifest order as apply order without
- * re-sorting).
- *
- * Contiguity itself is not checked, on purpose: `patchPolicy.ranges`
- * reserves gaps on purpose, so a hole is a legitimate queue shape.
- *
- * @param patches - The manifest rows about to be written
- */
-function assertRenumberedOrderIsWellFormed(patches) {
-    const seenOrders = new Set();
-    let previousOrder = Number.NEGATIVE_INFINITY;
-    for (const patch of patches) {
-        assert(!seenOrders.has(patch.order), () => `renumbered patch orders are unique (order ${patch.order} appears twice)`);
-        seenOrders.add(patch.order);
-        assert(patch.order >= previousOrder, () => `renumbered manifest rows are sorted by order (${patch.filename} is out of place)`);
-        previousOrder = patch.order;
-        const prefixMatch = /^(\d+)-/.exec(patch.filename);
-        assert(prefixMatch !== null, () => `renumbered patch filename carries a numeric prefix (got "${patch.filename}")`);
-        assert(Number(prefixMatch[1]) === patch.order, () => `renumbered patch filename prefix matches its order ` +
-            `("${patch.filename}" carries order ${patch.order})`);
-    }
-}
-/**
- * Rewrites `stagedDependencies.forwardImports[].owner` and
- * `stagedDependencies.registrations[].owner` references on one patch
- * through a rename lookup. Owners embed exact patch filenames, so any
- * renumber (compact, reorder, placement export, rename) that does not remap
- * them leaves dangling references that surface as false forward-import
- * errors on the next lint.
- *
- * Pure and allocation-conservative: returns the input object unchanged when
- * no owner matches the lookup, so callers can map whole manifests cheaply.
- *
- * @param patch - Manifest row to rewrite
- * @param renameLookup - Maps an old patch filename to its new filename, or
- *   undefined when the filename is not being renamed
- * @returns The same row, or a copy with remapped owners
- */
-export function rewriteStagedDependencyOwners(patch, renameLookup) {
-    const staged = patch.stagedDependencies;
-    if (!staged)
-        return patch;
-    const rewriteOwners = (entries) => {
-        if (!entries || entries.length === 0)
-            return { entries, changed: false };
-        const rewritten = entries.map((entry) => {
-            if (!entry.owner)
-                return entry;
-            const newOwner = renameLookup(entry.owner);
-            if (newOwner === undefined || newOwner === entry.owner)
-                return entry;
-            return { ...entry, owner: newOwner };
-        });
-        return {
-            entries: rewritten,
-            changed: rewritten.some((entry, index) => entry !== entries[index]),
-        };
-    };
-    const forwardImports = rewriteOwners(staged.forwardImports);
-    const registrations = rewriteOwners(staged.registrations);
-    if (!forwardImports.changed && !registrations.changed)
-        return patch;
-    return {
-        ...patch,
-        stagedDependencies: {
-            ...staged,
-            ...(forwardImports.entries !== undefined ? { forwardImports: forwardImports.entries } : {}),
-            ...(registrations.entries !== undefined ? { registrations: registrations.entries } : {}),
-        },
-    };
-}
-/**
- * Renames patch files on disk and rewrites the corresponding manifest rows
- * atomically-ish: file renames use a two-phase staging strategy (rename each
- * entry to a unique temp filename first, then rename the temp to its final
- * target) so cycles like `003 → 005` while `005` also moves do not collide.
- *
- * The manifest is rewritten once at the end with all new filenames and
- * orders. Failure semantics:
- *
- *   - **Phase 1 (stage)**: rolls back by renaming staged files back to
- *     their originals. Manifest is untouched. Best-effort: a rollback
- *     rename failure is warned but not re-thrown.
- *   - **Phase 2 (stage → final)**: rolls back to the pre-operation state
- *     by reversing every partial step: files already at their final
- *     names are renamed back to staging, and all staged files are then
- *     renamed back to their originals. The manifest is untouched. If
- *     the rollback itself fails midway, the thrown error is augmented
- *     with a description of the residue so the operator can inspect.
- *   - **Phase 3 (manifest write)**: by this point all files are on disk
- *     at their new names. A manifest write failure will roll the files
- *     back to their original names before re-throwing so the directory
- *     and manifest stay in agreement. A rollback failure at this stage
- *     is warned (manifest was never mutated) and the original error is
- *     re-thrown.
- *
- * Does not sort the rename map for the caller. The map is the authoritative
- * plan. Entries not present in the map keep their existing filename and
- * order.
- *
- * @param patchesDir - Path to the patches directory
- * @param renameMap - Map from existing filename → new filename/order
- */
-export async function renumberPatchesInManifest(patchesDir, renameMap) {
-    if (renameMap.size === 0)
-        return;
-    await assertPatchDirectoryLockHeld(patchesDir, 'renumbering the patch manifest');
-    const manifest = await loadPatchesManifestForWrite(patchesDir);
-    if (!manifest) {
-        throw new PatchError('Cannot renumber patches: patches.json is missing.');
-    }
-    // Phase 1: rename each old filename to a unique temp staging name so the
-    // later rename to the final target cannot collide with another entry
-    // currently occupying that slot.
-    const stagingId = randomUUID();
-    const stagedRenames = [];
-    try {
-        for (const [oldFilename, entry] of renameMap) {
-            const oldPath = join(patchesDir, oldFilename);
-            if (!(await pathExistsStrict(oldPath))) {
-                throw new PatchError(`Cannot renumber: patch file is missing on disk: ${oldFilename}`, oldFilename);
-            }
-            const stagedName = `.fireforge-renumber-${stagingId}-${oldFilename}`;
-            const stagedPath = join(patchesDir, stagedName);
-            await rename(oldPath, stagedPath);
-            stagedRenames.push({ from: oldFilename, staged: stagedName, toEntry: entry });
-        }
-    }
-    catch (error) {
-        // Roll back phase 1: put any already-staged files back.
-        for (const { from, staged } of stagedRenames) {
-            try {
-                await rename(join(patchesDir, staged), join(patchesDir, from));
-            }
-            catch (rollbackError) {
-                warn(`Rollback warning: could not restore ${from} from staging: ${toError(rollbackError).message}`);
-            }
-        }
-        throw error;
-    }
-    // Phase 2: rename each staged file to its final target, tracking which
-    // entries have completed so we can reverse the partial state on failure.
-    const completedFinalRenames = [];
-    try {
-        for (const stagedEntry of stagedRenames) {
-            const { staged, toEntry } = stagedEntry;
-            const targetPath = join(patchesDir, toEntry.newFilename);
-            if (await pathExistsStrict(targetPath)) {
-                throw new PatchError(`Cannot renumber: target patch filename already exists on disk: ${toEntry.newFilename}`, toEntry.newFilename);
-            }
-            await rename(join(patchesDir, staged), targetPath);
-            // Postcondition assert: confirm the target actually exists on disk
-            // before marking the rename complete. A silent rename failure leaves
-            // the manifest and the filesystem disagreeing: manifest rewritten to
-            // new filenames while the old files stay on disk. If the assert fires,
-            // the Phase 2 rollback undoes prior moves before re-throwing.
-            if (!(await pathExistsStrict(targetPath))) {
-                throw new PatchError(`Rename postcondition failed: expected ${toEntry.newFilename} to exist after rename, but it was not found on disk.`, toEntry.newFilename);
-            }
-            completedFinalRenames.push(stagedEntry);
-        }
-    }
-    catch (error) {
-        // Phase 2 rollback: reverse both the partial final-name moves and
-        // the phase-1 staging. This collapses the directory back to its
-        // pre-operation filenames so the manifest (which was never
-        // touched) remains consistent with what is on disk. If any
-        // individual rollback step itself fails, we warn with the residue
-        // filename so the operator can finish the cleanup by hand, but we
-        // still re-throw the original error so the caller sees the real
-        // cause.
-        const residue = [];
-        for (const completed of completedFinalRenames) {
-            try {
-                await rename(join(patchesDir, completed.toEntry.newFilename), join(patchesDir, completed.staged));
-            }
-            catch (rollbackError) {
-                residue.push(completed.toEntry.newFilename);
-                warn(`Rollback warning: could not revert ${completed.toEntry.newFilename} to staging: ${toError(rollbackError).message}`);
-            }
-        }
-        for (const stagedEntry of stagedRenames) {
-            try {
-                await rename(join(patchesDir, stagedEntry.staged), join(patchesDir, stagedEntry.from));
-            }
-            catch (rollbackError) {
-                residue.push(stagedEntry.staged);
-                warn(`Rollback warning: could not restore ${stagedEntry.from} from staging: ${toError(rollbackError).message}`);
-            }
-        }
-        if (residue.length > 0) {
-            warn(`Renumber phase 2 rollback left residue files (pattern: .fireforge-renumber-${stagingId}-*). ` +
-                `Inspect ${patchesDir} and remove or rename: ${residue.join(', ')}`);
-        }
-        throw error;
-    }
-    // Phase 3: rewrite the manifest rows. Any entry without a rename keeps its
-    // existing metadata. Entries in the map get their filename + order
-    // updated. Sort by the new order so the manifest remains ordered.
-    const filenameUpdates = new Map();
-    for (const [oldFilename, entry] of renameMap) {
-        filenameUpdates.set(oldFilename, entry);
-    }
-    // Owner references live on *other* patches than the renamed ones, so every
-    // row is passed through the staged-dependency rewrite, not just renamed rows.
-    const ownerLookup = (oldFilename) => filenameUpdates.get(oldFilename)?.newFilename;
-    const updatedPatches = manifest.patches.map((p) => {
-        const update = filenameUpdates.get(p.filename);
-        const withOwners = rewriteStagedDependencyOwners(p, ownerLookup);
-        if (!update)
-            return withOwners;
-        return {
-            ...withOwners,
-            filename: update.newFilename,
-            order: update.newOrder,
-        };
-    });
-    updatedPatches.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
-    try {
-        // Phase 3 is the one write that makes the renumber visible. Every file
-        // has already moved on disk, so a manifest that disagrees with the new
-        // filenames is the worst outcome available here, because the queue
-        // would apply in an order nothing on disk reflects. The callers compute
-        // the rename map (compact, reorder, export placement) and each maintains
-        // contiguity on its own. This checks the property they are all supposed
-        // to produce, at the single point where it becomes durable. Inside the
-        // try, so a violation unwinds through the Phase 3 rollback that puts the
-        // filenames back.
-        assertRenumberedOrderIsWellFormed(updatedPatches);
-        // A patch renumbered onto a retired order fills that slot.
-        await savePatchesManifest(patchesDir, manifestWithRetiredSlots(manifest, updatedPatches));
-    }
-    catch (error) {
-        // Phase 3 rollback: reverse every completed rename. The manifest
-        // save failed before it could be persisted, so the on-disk state
-        // must match what the manifest still records. Best-effort: any
-        // individual step that fails gets warned. The original save
-        // error is always re-thrown so the caller sees the real cause.
-        for (const completed of completedFinalRenames) {
-            try {
-                await rename(join(patchesDir, completed.toEntry.newFilename), join(patchesDir, completed.from));
-            }
-            catch (rollbackError) {
-                warn(`Rollback warning: could not revert ${completed.toEntry.newFilename} → ${completed.from} after manifest save failed: ${toError(rollbackError).message}`);
-            }
-        }
-        throw error;
-    }
-}
-/**
- * Thrown when {@link removePatchFileAndManifest} cannot complete the file
- * delete and cannot restore the manifest row afterward, so the on-disk
- * state and manifest state are known to disagree. Carries both the
- * primary delete error and the rollback error so the caller (and the
- * operator) can see the full failure chain instead of only the original
- * error with a warning about the rollback buried in logs.
- *
- * Extends {@link FireForgeError} so the CLI top-level handler routes it
- * through the rich-error formatter rather than the generic unexpected-error
- * path. The dedicated `.name` is kept so programmatic callers and tests
- * can still distinguish it with `instanceof PatchDeleteRollbackError`.
- */
-export class PatchDeleteRollbackError extends FireForgeError {
-    filename;
-    deleteError;
-    rollbackError;
-    code = ExitCode.PATCH_ERROR;
-    constructor(filename, deleteError, rollbackError) {
-        super(`Failed to delete ${filename}, AND failed to restore patches.json afterward. ` +
-            `The patch directory is now inconsistent: the manifest no longer lists ${filename} ` +
-            `but the patch file may still exist on disk. ` +
-            `Delete error: ${deleteError.message}. ` +
-            `Manifest rollback error: ${rollbackError.message}. ` +
-            `Inspect ${filename} in the patches directory and either remove it or restore the manifest row by hand.`);
-        this.filename = filename;
-        this.deleteError = deleteError;
-        this.rollbackError = rollbackError;
-    }
-}
-/**
- * Deletes both a patch file on disk and its manifest row under the caller's
- * lock. This is a convenience for the `patch delete` command. Callers that
- * need different ordering (e.g. deleting the file first without touching the
- * manifest) should call the primitives separately.
- *
- * Failure semantics: if the manifest row was already removed and the
- * file deletion then fails, the original manifest is restored best-effort
- * and the delete error is re-thrown. If the restore itself also fails,
- * a {@link PatchDeleteRollbackError} is thrown that carries both the
- * delete error and the rollback error so neither is hidden behind a
- * warning log. Callers can detect the compound failure with
- * `instanceof PatchDeleteRollbackError`.
- *
- * @param patchesDir - Path to the patches directory
- * @param filename - Patch filename to delete
- * @param retiredSlot - When set (`patch retire`), the placeholder written in
- *   the same manifest update that removes the row
- */
-export async function removePatchFileAndManifest(patchesDir, filename, retiredSlot) {
-    await assertPatchDirectoryLockHeld(patchesDir, 'deleting a patch and its manifest row');
-    const patchPath = join(patchesDir, filename);
-    // ForWrite: deleting the patch file while a corrupt manifest still
-    // references it would strand the queue. Abort on corruption instead.
-    const originalManifest = await loadPatchesManifestForWrite(patchesDir);
-    const removedFromManifest = await removePatchFromManifest(patchesDir, filename, retiredSlot);
-    try {
-        if (await pathExistsStrict(patchPath)) {
-            await removeFile(patchPath);
-        }
-    }
-    catch (error) {
-        const deleteError = toError(error);
-        if (removedFromManifest && originalManifest) {
-            try {
-                await savePatchesManifest(patchesDir, originalManifest);
-            }
-            catch (rollbackError) {
-                // Compound failure: both the delete and the rollback failed, so the
-                // directory is in a known-inconsistent state. A dedicated error type
-                // carrying both causes shows the complete picture instead of the
-                // original delete error with a rollback warning buried in stderr.
-                throw new PatchDeleteRollbackError(filename, deleteError, toError(rollbackError));
-            }
-        }
-        throw deleteError;
-    }
-}

package/dist/src/core/patch-manifest-key-order.d.ts

@@ -1,23 +0,0 @@
-/**
- * The one key order every `patches.json` writer uses for a patch row and
- * for the manifest itself, so that every writer (`export`, full-manifest
- * saves, `patch stage`) agrees and a no-op rewrite leaves no key-order-only
- * hunk in the manifest.
- */
-/**
- * Returns a copy of a patch row with its keys in canonical order.
- *
- * @param row - A `PatchMetadata` row, typed or raw
- * @returns The same fields in canonical key order
- */
-export declare function canonicalizePatchRow<T extends object>(row: T): T;
-/**
- * Returns a copy of a manifest with its top-level keys and every row in
- * canonical order.
- *
- * @param manifest - A `PatchesManifest`, typed or raw
- * @returns The manifest in canonical key order
- */
-export declare function canonicalizeManifest<T extends {
-    patches: readonly object[];
-}>(manifest: T): T;

package/dist/src/core/patch-manifest-key-order.js

@@ -1,60 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * The one key order every `patches.json` writer uses for a patch row and
- * for the manifest itself, so that every writer (`export`, full-manifest
- * saves, `patch stage`) agrees and a no-op rewrite leaves no key-order-only
- * hunk in the manifest.
- */
-/** Patch-row keys in the order of the `PatchMetadata` interface. */
-const PATCH_ROW_KEY_ORDER = [
-    'filename',
-    'order',
-    'category',
-    'name',
-    'description',
-    'createdAt',
-    'sourceEsrVersion',
-    'sourceProduct',
-    'sourceVersion',
-    'filesAffected',
-    'lintIgnore',
-    'tier',
-    'stagedDependencies',
-];
-/** Manifest keys in the order of the `PatchesManifest` interface. */
-const MANIFEST_KEY_ORDER = ['version', 'patches', 'retired', 'reserved'];
-function reorder(value, order) {
-    const source = value;
-    const out = {};
-    for (const key of order) {
-        if (Object.hasOwn(source, key))
-            out[key] = source[key];
-    }
-    // Keys this build does not know keep their relative order after the
-    // known ones, so a newer writer's fields survive an older rewrite.
-    for (const key of Object.keys(source)) {
-        if (!Object.hasOwn(out, key))
-            out[key] = source[key];
-    }
-    return out;
-}
-/**
- * Returns a copy of a patch row with its keys in canonical order.
- *
- * @param row - A `PatchMetadata` row, typed or raw
- * @returns The same fields in canonical key order
- */
-export function canonicalizePatchRow(row) {
-    return reorder(row, PATCH_ROW_KEY_ORDER);
-}
-/**
- * Returns a copy of a manifest with its top-level keys and every row in
- * canonical order.
- *
- * @param manifest - A `PatchesManifest`, typed or raw
- * @returns The manifest in canonical key order
- */
-export function canonicalizeManifest(manifest) {
-    const ordered = reorder(manifest, MANIFEST_KEY_ORDER);
-    return { ...ordered, patches: manifest.patches.map((row) => canonicalizePatchRow(row)) };
-}