@hominis/fireforge 0.46.0 → 0.46.1

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

@@ -20,7 +20,7 @@ export declare function validatePatchesManifestConsistency(patchesDir: string):
  *
  * 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
+ * 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.
  */
@@ -30,19 +30,19 @@ export declare function recommendManifestRepair(issues: readonly PatchManifestCo
  * 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
+ * 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}.
+     * 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.
+     * preserve. Every descriptive field on these entries is inferred.
      */
     recoveredFilenames: string[];
     /**
@@ -59,7 +59,7 @@ 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
+     * every entry is invented. Refused without this flag. See
      * {@link rebuildPatchesManifest}.
      */
     allowMetadataLoss?: boolean;
@@ -69,7 +69,7 @@ export interface RebuildPatchesManifestOptions extends PatchDirectoryLockOptions
 /**
  * Rebuilds patches.json from the patch files currently present on disk.
  *
- * This is a MERGE, not a from-scratch rebuild: only `filesAffected` and
+ * 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
@@ -82,7 +82,7 @@ export interface RebuildPatchesManifestOptions extends PatchDirectoryLockOptions
  * @param patchesDir - Path to the patches directory
  * @param fallbackSourceEsrVersion - source version to use for recovered legacy entries
  * @param options - Lock options plus `allowMetadataLoss` / `dryRun`
- * @returns {@link RebuildPatchesManifestResult} — the rebuilt manifest, the
+ * @returns {@link RebuildPatchesManifestResult}: the rebuilt manifest, the
  *   filenames that were reconstructed from generic defaults, and the rows
  *   dropped because their patch file is gone.
  */

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

@@ -86,7 +86,7 @@ export async function validatePatchesManifestConsistency(patchesDir) {
  *
  * 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
+ * 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.
  */
@@ -103,7 +103,7 @@ export function recommendManifestRepair(issues) {
 /**
  * Rebuilds patches.json from the patch files currently present on disk.
  *
- * This is a MERGE, not a from-scratch rebuild: only `filesAffected` and
+ * 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
@@ -116,7 +116,7 @@ export function recommendManifestRepair(issues) {
  * @param patchesDir - Path to the patches directory
  * @param fallbackSourceEsrVersion - source version to use for recovered legacy entries
  * @param options - Lock options plus `allowMetadataLoss` / `dryRun`
- * @returns {@link RebuildPatchesManifestResult} — the rebuilt manifest, the
+ * @returns {@link RebuildPatchesManifestResult}: the rebuilt manifest, the
  *   filenames that were reconstructed from generic defaults, and the rows
  *   dropped because their patch file is gone.
  */
@@ -125,7 +125,7 @@ export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersio
     // 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.
+    // 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
@@ -136,9 +136,9 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
     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
+    // 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`,
+    // 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
@@ -187,21 +187,20 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
             // 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
+            // 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 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 by
-        // construction rather than by someone 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.
+        // 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,
@@ -228,9 +227,9 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
         patches: 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 — the file is the source of
-    // truth — but dropping rows without naming them is indistinguishable from
-    // never having had them.
+    // 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 {

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

@@ -1,5 +1,5 @@
 /**
- * Narrow repair for `filesAffected` — the one manifest field a `.patch` body
+ * 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

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Narrow repair for `filesAffected` — the one manifest field a `.patch` body
+ * 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
@@ -47,7 +47,7 @@ async function repairPatchesFilesAffectedUnderLock(patchesDir, filenames, option
         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
+            // issue with a different remedy. This repair reports it rather than
             // inventing a row or deleting one.
             skippedFilenames.push(filename);
             continue;
@@ -63,7 +63,7 @@ async function repairPatchesFilesAffectedUnderLock(patchesDir, filenames, option
         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 —
+    // 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) => {

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

@@ -39,10 +39,10 @@ export declare function loadPatchesManifestState(patchesDir: string): Promise<Lo
 /**
  * Loads the patches manifest if it exists.
  *
- * READ-ONLY callers only: this collapses "absent" and "corrupt" into null.
- * Any code path that will WRITE the manifest (or delete patch files based
- * on its content) must use {@link loadPatchesManifestForWrite} instead —
- * treating a corrupt manifest as empty and then saving destroys every
+ * 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
@@ -52,7 +52,7 @@ export declare function loadPatchesManifest(patchesDir: string): Promise<Patches
 /**
  * Loads the patches manifest for a mutating operation.
  *
- * Returns null only when the manifest genuinely does not exist; a manifest
+ * 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.
@@ -80,11 +80,11 @@ export declare function mutatePatchRowsInManifest(patchesDir: string, filenames:
 export declare function addPatchToManifest(patchesDir: string, metadata: PatchMetadata, removeFilenames?: string[]): Promise<void>;
 /**
  * Removes a single patch entry from the manifest by filename. Leaves the
- * ordinal gap in place — callers wanting to close the gap must use
+ * 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
+ * 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
@@ -99,7 +99,7 @@ export declare function removePatchFromManifest(patchesDir: string, filename: st
 export interface PatchRenameEntry {
     /** New filename (e.g. `005-ui-sidebar.patch`). */
     newFilename: string;
-    /** New numeric order — must match the prefix of `newFilename`. */
+    /** New numeric order. Must match the prefix of `newFilename`. */
     newOrder: number;
 }
 /**
@@ -129,7 +129,7 @@ export declare function rewriteStagedDependencyOwners(patch: PatchMetadata, rena
  * orders. Failure semantics:
  *
  *   - **Phase 1 (stage)**: rolls back by renaming staged files back to
- *     their originals. Manifest is untouched. Best-effort — a rollback
+ *     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
@@ -138,13 +138,13 @@ export declare function rewriteStagedDependencyOwners(patch: PatchMetadata, rena
  *     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
+ *     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
+ * 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.
  *
@@ -154,7 +154,7 @@ export declare function rewriteStagedDependencyOwners(patch: PatchMetadata, rena
 export declare function renumberPatchesInManifest(patchesDir: string, renameMap: Map<string, PatchRenameEntry>): Promise<void>;
 /**
  * Thrown when {@link removePatchFileAndManifest} cannot complete the file
- * delete AND cannot restore the manifest row afterward, so the on-disk
+ * 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
@@ -162,7 +162,7 @@ export declare function renumberPatchesInManifest(patchesDir: string, renameMap:
  *
  * 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
+ * path. The dedicated `.name` is kept so programmatic callers and tests
  * can still distinguish it with `instanceof PatchDeleteRollbackError`.
  */
 export declare class PatchDeleteRollbackError extends FireForgeError {
@@ -174,7 +174,7 @@ export declare class PatchDeleteRollbackError extends FireForgeError {
 }
 /**
  * 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
+ * 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.
  *

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

@@ -50,10 +50,10 @@ export async function loadPatchesManifestState(patchesDir) {
 /**
  * Loads the patches manifest if it exists.
  *
- * READ-ONLY callers only: this collapses "absent" and "corrupt" into null.
- * Any code path that will WRITE the manifest (or delete patch files based
- * on its content) must use {@link loadPatchesManifestForWrite} instead —
- * treating a corrupt manifest as empty and then saving destroys every
+ * 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
@@ -66,7 +66,7 @@ export async function loadPatchesManifest(patchesDir) {
 /**
  * Loads the patches manifest for a mutating operation.
  *
- * Returns null only when the manifest genuinely does not exist; a manifest
+ * 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.
@@ -175,11 +175,11 @@ export async function addPatchToManifest(patchesDir, metadata, removeFilenames)
 }
 /**
  * Removes a single patch entry from the manifest by filename. Leaves the
- * ordinal gap in place — callers wanting to close the gap must use
+ * 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
+ * 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
@@ -210,7 +210,7 @@ export async function removePatchFromManifest(patchesDir, filename) {
  * sorted ascending (readers take manifest order as apply order without
  * re-sorting).
  *
- * Contiguity itself is deliberately NOT checked: `patchPolicy.ranges`
+ * 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
@@ -288,7 +288,7 @@ export function rewriteStagedDependencyOwners(patch, renameLookup) {
  * orders. Failure semantics:
  *
  *   - **Phase 1 (stage)**: rolls back by renaming staged files back to
- *     their originals. Manifest is untouched. Best-effort — a rollback
+ *     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
@@ -297,13 +297,13 @@ export function rewriteStagedDependencyOwners(patch, renameLookup) {
  *     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
+ *     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
+ * 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.
  *
@@ -360,7 +360,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
             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
+            // 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))) {
@@ -370,7 +370,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
         }
     }
     catch (error) {
-        // Phase 2 rollback — reverse both the partial final-name moves and
+        // 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
@@ -404,7 +404,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
         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
+    // 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) {
@@ -428,13 +428,13 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
     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 — 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.
+        // 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);
         await savePatchesManifest(patchesDir, {
             ...manifest,
@@ -445,7 +445,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
         // 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
+        // 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 {
@@ -460,7 +460,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
 }
 /**
  * Thrown when {@link removePatchFileAndManifest} cannot complete the file
- * delete AND cannot restore the manifest row afterward, so the on-disk
+ * 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
@@ -468,7 +468,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
  *
  * 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
+ * path. The dedicated `.name` is kept so programmatic callers and tests
  * can still distinguish it with `instanceof PatchDeleteRollbackError`.
  */
 export class PatchDeleteRollbackError extends FireForgeError {
@@ -490,7 +490,7 @@ export class PatchDeleteRollbackError extends FireForgeError {
 }
 /**
  * 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
+ * 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.
  *
@@ -508,8 +508,8 @@ export class PatchDeleteRollbackError extends FireForgeError {
 export async function removePatchFileAndManifest(patchesDir, filename) {
     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.
+    // 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);
     try {

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

@@ -45,7 +45,7 @@ export declare function validatePatchIntegrity(patchesDir: string, engineDir: st
  *
  * Acquires the shared patch-directory lock for the read-modify-write, so a
  * concurrent export/reorder/metadata update cannot interleave with the stamp.
- * The lock is not reentrant — callers must NOT invoke this while already
+ * The lock is not reentrant: callers must not invoke this while already
  * holding {@link withPatchDirectoryLock} on the same patches directory.
  *
  * @param patchesDir - Path to the patches directory

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

@@ -80,9 +80,9 @@ export async function validatePatchIntegrity(patchesDir, engineDir) {
     const issues = [];
     const patches = await discoverPatches(patchesDir);
     // Collect every modification target first, then resolve HEAD existence in
-    // ONE batched ls-tree pass (chunked for ARG_MAX). The per-file
+    // one batched ls-tree pass (chunked for ARG_MAX). The per-file
     // fileExistsInHead fan-out spawned one git process per (patch × target) on
-    // every import — a 56-file branding patch alone cost ~56 spawns before a
+    // every import: a 56-file branding patch alone cost ~56 spawns before a
     // single patch was applied.
     const modificationTargets = [];
     for (const patch of patches) {
@@ -90,7 +90,7 @@ export async function validatePatchIntegrity(patchesDir, engineDir) {
         const patchContent = await readText(patch.path);
         const targetFiles = await getAllTargetFilesFromPatch(patch.path);
         for (const targetFile of targetFiles) {
-            // Skip new-file sections — they don't need to exist in HEAD
+            // Skip new-file sections. They don't need to exist in HEAD
             if (isNewFileInPatch(patchContent, targetFile))
                 continue;
             modificationTargets.push({ filename: patch.filename, targetFile });
@@ -114,7 +114,7 @@ export async function validatePatchIntegrity(patchesDir, engineDir) {
  *
  * Acquires the shared patch-directory lock for the read-modify-write, so a
  * concurrent export/reorder/metadata update cannot interleave with the stamp.
- * The lock is not reentrant — callers must NOT invoke this while already
+ * The lock is not reentrant: callers must not invoke this while already
  * holding {@link withPatchDirectoryLock} on the same patches directory.
  *
  * @param patchesDir - Path to the patches directory

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

@@ -2,12 +2,12 @@ import type { PatchMetadata } from '../types/commands/index.js';
 /**
  * Resolves a patch identifier to its manifest entry. Accepts:
  *
- *   1. An ordinal number (e.g. `2`) — matches `PatchMetadata.order`.
- *   2. A full filename with `.patch` suffix (e.g. `002-ui-foo.patch`) —
- *      matches `PatchMetadata.filename`.
- *   3. A filename without the `.patch` suffix — the command appends it
+ *   1. An ordinal number (e.g. `2`), matching `PatchMetadata.order`.
+ *   2. A full filename with `.patch` suffix (e.g. `002-ui-foo.patch`),
+ *      matching `PatchMetadata.filename`.
+ *   3. A filename without the `.patch` suffix. The command appends it
  *      before matching (e.g. `002-ui-foo`).
- *   4. The manifest `name` field (e.g. `furnace-token-override`) — the short
+ *   4. The manifest `name` field (e.g. `furnace-token-override`), the short
  *      logical handle the export workflow stamps onto the patch and the
  *      natural identifier an operator keeps in their notes. The CLI help
  *      says `<name>`, so rejecting it forces the operator to copy the full

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

@@ -1,12 +1,12 @@
 /**
  * Resolves a patch identifier to its manifest entry. Accepts:
  *
- *   1. An ordinal number (e.g. `2`) — matches `PatchMetadata.order`.
- *   2. A full filename with `.patch` suffix (e.g. `002-ui-foo.patch`) —
- *      matches `PatchMetadata.filename`.
- *   3. A filename without the `.patch` suffix — the command appends it
+ *   1. An ordinal number (e.g. `2`), matching `PatchMetadata.order`.
+ *   2. A full filename with `.patch` suffix (e.g. `002-ui-foo.patch`),
+ *      matching `PatchMetadata.filename`.
+ *   3. A filename without the `.patch` suffix. The command appends it
  *      before matching (e.g. `002-ui-foo`).
- *   4. The manifest `name` field (e.g. `furnace-token-override`) — the short
+ *   4. The manifest `name` field (e.g. `furnace-token-override`), the short
  *      logical handle the export workflow stamps onto the patch and the
  *      natural identifier an operator keeps in their notes. The CLI help
  *      says `<name>`, so rejecting it forces the operator to copy the full
@@ -22,14 +22,14 @@ export function resolvePatchIdentifier(identifier, patches) {
         const order = parseInt(identifier, 10);
         return patches.find((p) => p.order === order) ?? null;
     }
-    // Filename lookup — try the input as-is first (covers both the
+    // Filename lookup: try the input as-is first (covers both the
     // full `.patch` form and a bare name, because `endsWith` treats the
     // bare form as a miss and falls through to the appended variant).
     const normalized = identifier.endsWith('.patch') ? identifier : `${identifier}.patch`;
     const byFilename = patches.find((p) => p.filename === normalized || p.filename === identifier);
     if (byFilename)
         return byFilename;
-    // Name-field lookup — the short logical handle stamped into the
+    // Name-field lookup: the short logical handle stamped into the
     // manifest at export time. See function docstring.
     return patches.find((p) => p.name === identifier) ?? null;
 }

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

@@ -92,12 +92,12 @@ function validatePatchMetadata(data, index) {
         throw new Error(`patches[${index}].sourceEsrVersion must be a valid Firefox version string`);
     }
     const filesAffected = rec.stringArray('filesAffected');
-    // Optional fields. These are easy to strip silently — an escape hatch
+    // Optional fields. These are easy to strip silently: an escape hatch
     // that round-trips only through test fixtures mocking
     // `loadPatchesManifest` looks fine while real operator edits to
     // `patches.json` are dropped on every load, so a patch relying on
     // `lintIgnore` to suppress a rule is quietly re-tripped the next time the
-    // manifest validates. Preserve both `lintIgnore` and `tier` here; future
+    // manifest validates. Preserve both `lintIgnore` and `tier` here. Future
     // optional fields follow the same template.
     const lintIgnore = rec.optionalStringArray('lintIgnore');
     const rawTier = rec.raw('tier');
@@ -143,7 +143,7 @@ export function validatePatchesManifest(data) {
     if (!isObject(data)) {
         throw new Error('patches.json must be a JSON object');
     }
-    // A manifest from a NEWER FireForge is not corrupt. The bare "version must
+    // A manifest from a newer FireForge is not corrupt. The bare "version must
     // be 1" this replaced sent the operator looking for damage in a file that
     // only needed a newer build to read it.
     const version = checkDocumentVersion(data, 'version', PATCHES_MANIFEST_VERSION);

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

@@ -1,7 +1,7 @@
 /**
- * Patches manifest — re-exports from focused sub-modules.
+ * Patches manifest: re-exports from focused sub-modules.
  *
- * Callers should continue to import from this module; the internal split
+ * Callers should continue to import from this module. The internal split
  * is an implementation detail.
  */
 export { type PatchManifestConsistencyIssue, rebuildPatchesManifest, recommendManifestRepair, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';

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

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Patches manifest — re-exports from focused sub-modules.
+ * Patches manifest: re-exports from focused sub-modules.
  *
- * Callers should continue to import from this module; the internal split
+ * Callers should continue to import from this module. The internal split
  * is an implementation detail.
  */
 export { rebuildPatchesManifest, recommendManifestRepair, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';