@hominis/fireforge 0.46.0 → 0.46.2

package/dist/src/core/ownership-table.js

@@ -6,7 +6,7 @@ import { buildPatchClaims } from './status-classify.js';
  *
  * Populated from three sources:
  *
- *   1. Every path in every patch's `filesAffected` — so managed paths show up
+ *   1. Every path in every patch's `filesAffected`, so managed paths show up
  *      even when they are not currently modified on disk.
  *   2. Any worktree status entries not claimed by any patch (flagged as
  *      `unmanaged`).
@@ -21,11 +21,11 @@ import { buildPatchClaims } from './status-classify.js';
  * `conflictReason` so the output can disambiguate.
  *
  * @param manifestPatches - Manifest rows, each with its `filesAffected`
- * @param worktreeFiles - Raw worktree status entries; untracked and modified
+ * @param worktreeFiles - Raw worktree status entries. Untracked and modified
  *   both acceptable
  * @param newFileCreatorsByPath - Map produced by
- *   {@link import('../core/patch-lint.js').collectNewFileCreatorsByPath};
- *   paths with a `.length > 1` owner list become duplicate-create conflicts
+ *   {@link import('../core/patch-lint.js').collectNewFileCreatorsByPath}.
+ *   Paths with a `.length > 1` owner list become duplicate-create conflicts
  */
 export function buildOwnershipTable(manifestPatches, worktreeFiles, newFileCreatorsByPath, classifications = new Map()) {
     const ownersByPath = buildPatchClaims(manifestPatches);
@@ -57,7 +57,7 @@ export function buildOwnershipTable(manifestPatches, worktreeFiles, newFileCreat
         const duplicateOwners = duplicateCreateByPath.get(path);
         const isFilesAffectedConflict = owners.length > 1;
         const isDuplicateCreateConflict = duplicateOwners !== undefined;
-        // Prefer the filesAffected reason when both apply — it's the older
+        // Prefer the filesAffected reason when both apply: it's the older
         // source of drift and the operator will usually want to fix the
         // manifest rows even when the bodies also duplicate-create.
         const conflictReason = isFilesAffectedConflict
@@ -105,7 +105,7 @@ export function buildOwnershipTable(manifestPatches, worktreeFiles, newFileCreat
  * `files-affected` drift (two manifest rows claiming the same path) from
  * `duplicate-create` drift (two patches both hitting `/dev/null → b/path`
  * in their bodies) so the operator can tell at a glance which fix
- * applies — the former wants `re-export --files`, the latter wants
+ * applies. The former wants `re-export --files`, the latter wants
  * `patch delete`.
  */
 function renderConflictCell(row) {
@@ -134,7 +134,7 @@ function renderStateCell(row) {
 /**
  * Renders the ownership table as a GitHub-flavored Markdown pipe table.
  * Using markdown-table's own serializer would require a seed document to
- * graft onto, which is overkill for ad-hoc status output; the rendering
+ * graft onto, which is overkill for ad-hoc status output. The rendering
  * here is trivial enough to inline.
  */
 export function renderOwnershipTable(rows) {

package/dist/src/core/parser-fallback.d.ts

@@ -14,8 +14,8 @@ export declare function consumeParserFallbackEvents(): ParserFallbackEvent[];
  *
  * Rethrows internal-invariant `GeneralError`s ("Unexpected empty …array"):
  * those are programming bugs, and retrying the legacy scanner cannot fix a
- * broken invariant — it just buries the stack. Everything else still falls
- * back, which is load-bearing: the AST path raises a raw acorn SyntaxError
+ * broken invariant, it just buries the stack. Everything else still falls
+ * back, which matters: the AST path raises a raw acorn SyntaxError
  * on chrome sources acorn cannot parse (preprocessor directives), and
  * BuildError when the file's shape is unexpected. Both are exactly what the
  * legacy scanner is here to handle.
@@ -43,7 +43,7 @@ export interface ParserResult<T> {
  * @param primary - The modern parser implementation
  * @param fallback - The legacy fallback implementation
  * @param context - File/context name used in the warning message
- * @param rethrowIf - Optional predicate; if it returns true for the caught
+ * @param rethrowIf - Optional predicate. If it returns true for the caught
  *   error the error is re-thrown instead of falling back (useful for
  *   domain-specific errors that should not be swallowed).
  */

package/dist/src/core/parser-fallback.js

@@ -19,8 +19,8 @@ export function consumeParserFallbackEvents() {
  *
  * Rethrows internal-invariant `GeneralError`s ("Unexpected empty …array"):
  * those are programming bugs, and retrying the legacy scanner cannot fix a
- * broken invariant — it just buries the stack. Everything else still falls
- * back, which is load-bearing: the AST path raises a raw acorn SyntaxError
+ * broken invariant, it just buries the stack. Everything else still falls
+ * back, which matters: the AST path raises a raw acorn SyntaxError
  * on chrome sources acorn cannot parse (preprocessor directives), and
  * BuildError when the file's shape is unexpected. Both are exactly what the
  * legacy scanner is here to handle.
@@ -42,7 +42,7 @@ export function isInternalInvariantFailure(error) {
  * @param primary - The modern parser implementation
  * @param fallback - The legacy fallback implementation
  * @param context - File/context name used in the warning message
- * @param rethrowIf - Optional predicate; if it returns true for the caught
+ * @param rethrowIf - Optional predicate. If it returns true for the caught
  *   error the error is re-thrown instead of falling back (useful for
  *   domain-specific errors that should not be swallowed).
  */

package/dist/src/core/patch-apply-fuzz.d.ts

@@ -3,17 +3,17 @@
  *
  * Tries an exact `git apply` first, then retries with git's real
  * drift-tolerance knob: `-C<n>` (reduced context matching). `git apply` has
- * NO `--fuzz` option — that flag belongs to GNU `patch(1)`, and passing it
+ * no `--fuzz` option. That flag belongs to GNU `patch(1)`, and passing it
  * makes git exit 129 with a usage error that an escalation loop will happily
  * swallow, so every "fuzzy" attempt silently fails and patches that would
  * have applied with context drift are reported as hard conflicts. If all
  * context-reduction levels fail, falls through to `git apply --reject` so
  * the user gets `.rej` files for manual resolution.
  *
- * Semantics note: GNU fuzz *fuzzily matches* context; `-C<n>` *ignores*
+ * Semantics note: GNU fuzz *fuzzily matches* context. `-C<n>` *ignores*
  * outer context lines instead. Step k maps to `-C(3-k)` (git's default
  * context width is 3), so the final step `-C0` matches on line positions and
- * -/+ content alone — the rough analogue of GNU `--fuzz=3` on a 3-context
+ * -/+ content alone, the rough analogue of GNU `--fuzz=3` on a 3-context
  * patch.
  */
 export interface FuzzyApplyResult {
@@ -38,8 +38,8 @@ export interface FuzzyApplyResult {
  * @param maxFuzz   - Maximum context-reduction steps to try (default 3,
  *   0 = exact only). Values above 3 are capped: git cannot reduce below
  *   `-C0`.
- * @throws InvalidArgumentError when `maxFuzz` is not a non-negative integer —
- *   a NaN or negative value would silently skip every apply attempt
+ * @throws InvalidArgumentError when `maxFuzz` is not a non-negative integer.
+ *   A NaN or negative value would silently skip every apply attempt
  *   (including the exact-match one) and fall straight through to `--reject`
  */
 export declare function applyPatchWithFuzz(patchPath: string, engineDir: string, maxFuzz?: number): Promise<FuzzyApplyResult>;

package/dist/src/core/patch-apply-fuzz.js

@@ -4,24 +4,24 @@
  *
  * Tries an exact `git apply` first, then retries with git's real
  * drift-tolerance knob: `-C<n>` (reduced context matching). `git apply` has
- * NO `--fuzz` option — that flag belongs to GNU `patch(1)`, and passing it
+ * no `--fuzz` option. That flag belongs to GNU `patch(1)`, and passing it
  * makes git exit 129 with a usage error that an escalation loop will happily
  * swallow, so every "fuzzy" attempt silently fails and patches that would
  * have applied with context drift are reported as hard conflicts. If all
  * context-reduction levels fail, falls through to `git apply --reject` so
  * the user gets `.rej` files for manual resolution.
  *
- * Semantics note: GNU fuzz *fuzzily matches* context; `-C<n>` *ignores*
+ * Semantics note: GNU fuzz *fuzzily matches* context. `-C<n>` *ignores*
  * outer context lines instead. Step k maps to `-C(3-k)` (git's default
  * context width is 3), so the final step `-C0` matches on line positions and
- * -/+ content alone — the rough analogue of GNU `--fuzz=3` on a 3-context
+ * -/+ content alone, the rough analogue of GNU `--fuzz=3` on a 3-context
  * patch.
  */
 import { InvalidArgumentError } from '../errors/base.js';
 import { verbose } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
 import { ensureGit } from './git-base.js';
-/** Git's default diff context width — the ceiling for reduction steps. */
+/** Git's default diff context width, the ceiling for reduction steps. */
 const GIT_DEFAULT_CONTEXT = 3;
 // ── Implementation ──
 /**
@@ -36,8 +36,8 @@ const GIT_DEFAULT_CONTEXT = 3;
  * @param maxFuzz   - Maximum context-reduction steps to try (default 3,
  *   0 = exact only). Values above 3 are capped: git cannot reduce below
  *   `-C0`.
- * @throws InvalidArgumentError when `maxFuzz` is not a non-negative integer —
- *   a NaN or negative value would silently skip every apply attempt
+ * @throws InvalidArgumentError when `maxFuzz` is not a non-negative integer.
+ *   A NaN or negative value would silently skip every apply attempt
  *   (including the exact-match one) and fall straight through to `--reject`
  */
 export async function applyPatchWithFuzz(patchPath, engineDir, maxFuzz = 3) {
@@ -63,7 +63,7 @@ export async function applyPatchWithFuzz(patchPath, engineDir, maxFuzz = 3) {
                 }
                 return { success: true, fuzzFactor: step };
             }
-            // Unlikely: --check passed but apply failed; fall through to next step
+            // Unlikely: --check passed but apply failed. Fall through to next step
             verbose(`git apply -C${GIT_DEFAULT_CONTEXT - step} --check passed but apply failed: ${apply.stderr.trim()}`);
         }
     }
@@ -88,8 +88,8 @@ export async function applyPatchWithFuzz(patchPath, engineDir, maxFuzz = 3) {
  *   Rejected hunk #1.
  *
  * The reject file is `<file>.rej` next to the target. Matching GNU
- * `patch(1)`'s "saving rejects to file X.rej" phrasing instead — which git
- * never prints — leaves `rejectFiles` always empty and the
+ * `patch(1)`'s "saving rejects to file X.rej" phrasing instead, which git
+ * never prints, leaves `rejectFiles` always empty and the
  * conflict-summary ".rej files created" hint never fires.
  */
 function extractRejectFiles(stderr) {

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

@@ -1,5 +1,5 @@
 /**
- * Patch orchestration — coordinates patch discovery, application, and validation.
+ * Patch orchestration. Coordinates patch discovery, application, and validation.
  * Pure parsing, content transformation, and lock management are in separate modules.
  */
 import type { ImportSummary, PatchInfo, PatchMetadata } from '../types/commands/index.js';
@@ -27,14 +27,14 @@ export interface ApplyPatchesOptions {
  * The identifier is one of three shapes and the three shapes must stay
  * disjoint so the operator can reason about which patch they picked:
  *
- *   1. **Exact filename** — `005-foo.patch`. Matches only that filename.
- *   2. **Filename without extension** — `005-foo`. Matches `005-foo.patch`.
- *   3. **Bare numeric ordinal** — `5` or `005`. Matches the patch whose
+ *   1. Exact filename, `005-foo.patch`. Matches only that filename.
+ *   2. Filename without extension, `005-foo`. Matches `005-foo.patch`.
+ *   3. Bare numeric ordinal, `5` or `005`. Matches the patch whose
  *      order prefix parses to the same integer (so `5` and `005` both match
  *      `005-foo.patch`, and `05` matches too because parseInt normalizes
  *      leading zeros).
  *
- * A purely-numeric identifier is treated **only** as an ordinal: it does not
+ * A purely-numeric identifier is treated only as an ordinal: it does not
  * also match a filename that happens to literally equal the digits. That
  * would require a patch literally named `5` or `005`, which would collide
  * with the filename prefix anyway.
@@ -66,10 +66,10 @@ export interface PatchedContentContext {
 }
 /**
  * Builds a batched patched-content context that loads the manifest and
- * discovers patch files ONCE for many lookups, and memoizes each patch body
+ * discovers patch files once for many lookups, and memoizes each patch body
  * read across the batch. A per-call helper re-runs `loadPatchesManifest` +
- * `discoverPatches` and re-reads every affecting patch body for every file —
- * O(dirtyFiles × patches) redundant IO when classifying a broad engine edit
- * session during `status` or `import`.
+ * `discoverPatches` and re-reads every affecting patch body for every file,
+ * which is O(dirtyFiles × patches) redundant IO when classifying a broad
+ * engine edit session during `status` or `import`.
  */
 export declare function createPatchedContentContext(patchesDir: string, engineDir: string): Promise<PatchedContentContext>;

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Patch orchestration — coordinates patch discovery, application, and validation.
+ * Patch orchestration. Coordinates patch discovery, application, and validation.
  * Pure parsing, content transformation, and lock management are in separate modules.
  */
 import { lstat, readFile, readlink, realpath, rm } from 'node:fs/promises';
@@ -27,7 +27,7 @@ export { extractAffectedFiles } from './patch-parse.js';
  * @param patch - Patch info
  * @param engineDir - Path to the engine directory
  * @param protectedFiles - Files touched by patches already applied in the
- *   current run; the idempotent-recovery reset must not wipe them (see
+ *   current run. The idempotent-recovery reset must not wipe them (see
  *   applyPatchIdempotent). Overlapping queues (`--allow-overlap`) share files
  *   between patches, and resetting a shared file to HEAD during a later
  *   patch's recovery silently discards the earlier patch's changes.
@@ -58,7 +58,7 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
         // losslessly where a utf-8 decode of a binary file does not.
         const savedContents = new Map();
         // New-file sections keyed by target, so the binary discrimination below
-        // reads the ALREADY-parsed section instead of re-scanning the body per
+        // reads the already-parsed section instead of re-scanning the body per
         // file.
         const newFileSections = new Map(parseDiffSections(patchContent)
             .filter((section) => section.isNewFile)
@@ -73,14 +73,14 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
                 savedContents.set(file, await readFile(targetPath));
                 const section = newFileSections.get(file);
                 if (section?.isBinary === true) {
-                    // A binary new file cannot be resolved by writing extracted text —
-                    // the payload is base85, whose alphabet includes '+'. It does not
-                    // need to be: `git apply` decodes a `GIT binary patch` itself. So
-                    // the resolution is to REMOVE the blocking file and let the retry
-                    // below create it from the payload, which is exactly what the
-                    // text branch achieves by overwriting.
+                    // A binary new file cannot be resolved by writing extracted
+                    // text, because the payload is base85, whose alphabet includes
+                    // '+'. It does not need to be: `git apply` decodes a `GIT binary
+                    // patch` itself. So the resolution is to remove the blocking file
+                    // and let the retry below create it from the payload, which is
+                    // exactly what the text branch achieves by overwriting.
                     if (!section.hasBinaryDelta) {
-                        // `Binary files … differ` records THAT the bytes changed and
+                        // `Binary files … differ` records that the bytes changed and
                         // carries none of them, so nothing can recreate the file. Fail
                         // honestly rather than deleting a file we cannot put back.
                         throw new PatchError(`Cannot resolve the new-file conflict for ${file}: the patch's binary section ` +
@@ -97,8 +97,8 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
             }
         }
         catch (extractError) {
-            // Resolution threw for a LATER target after earlier targets were
-            // already overwritten or removed — restore them before reporting
+            // Resolution threw for a later target after earlier targets were
+            // already overwritten or removed. Restore them before reporting
             // failure, instead of letting the exception skip the restore loop
             // entirely and crash the whole import.
             for (const [file, originalContent] of savedContents) {
@@ -111,7 +111,7 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
                 await applyPatchIdempotent(patch.path, engineDir, {
                     ...(protectedFiles ? { protectedFiles } : {}),
                 });
-                // Keep the originals: rollbackPatches needs them if a LATER patch
+                // Keep the originals: rollbackPatches needs them if a later patch
                 // fails, since reverse-applying this new-file patch deletes the
                 // target and would otherwise permanently discard the pre-existing
                 // content (recoverable from git only if it was tracked at HEAD).
@@ -161,8 +161,8 @@ async function rollbackPatches(results, engineDir) {
         catch (rollbackError) {
             verbose(`Failed to roll back ${result.patch.filename}: ${toError(rollbackError).message}`);
         }
-        // Reversing an auto-resolved new-file patch deletes the target; put
-        // back the pre-existing content the auto-resolve overwrote.
+        // Reversing an auto-resolved new-file patch deletes the target, so
+        // put back the pre-existing content the auto-resolve overwrote.
         if (result.autoResolvedOriginals) {
             for (const [file, originalContent] of result.autoResolvedOriginals) {
                 try {
@@ -179,7 +179,7 @@ async function rollbackPatches(results, engineDir) {
 async function validatePatchTargets(patch, affectedFiles, engineDir) {
     // realpath the engine root once so containment is checked against the
     // physical tree (the root itself may sit behind a symlink, e.g. /tmp on
-    // macOS). An unresolvable engine dir skips the symlink checks — a missing
+    // macOS). An unresolvable engine dir skips the symlink checks. A missing
     // engine surfaces through `git apply --check` with a better message.
     const engineRoot = engineDir ? await realpath(engineDir).catch(() => null) : null;
     for (const file of affectedFiles) {
@@ -206,7 +206,7 @@ async function validatePatchTargets(patch, affectedFiles, engineDir) {
  * - Dangling symlink: `realpath` rejects it, but a write through the link
  *   would still be created at the link target, so the target is resolved
  *   against the link's (real) parent directory. The link target is taken
- *   textually — a loop or nested dangling link fails at apply time anyway.
+ *   textually. A loop or nested dangling link fails at apply time anyway.
  * - Not-yet-existing file: resolved against the nearest existing ancestor's
  *   real path. Components below that ancestor do not exist, so they cannot
  *   be symlinks and are appended verbatim.
@@ -240,14 +240,14 @@ async function resolvePatchWriteDestination(targetPath) {
  * The identifier is one of three shapes and the three shapes must stay
  * disjoint so the operator can reason about which patch they picked:
  *
- *   1. **Exact filename** — `005-foo.patch`. Matches only that filename.
- *   2. **Filename without extension** — `005-foo`. Matches `005-foo.patch`.
- *   3. **Bare numeric ordinal** — `5` or `005`. Matches the patch whose
+ *   1. Exact filename, `005-foo.patch`. Matches only that filename.
+ *   2. Filename without extension, `005-foo`. Matches `005-foo.patch`.
+ *   3. Bare numeric ordinal, `5` or `005`. Matches the patch whose
  *      order prefix parses to the same integer (so `5` and `005` both match
  *      `005-foo.patch`, and `05` matches too because parseInt normalizes
  *      leading zeros).
  *
- * A purely-numeric identifier is treated **only** as an ordinal: it does not
+ * A purely-numeric identifier is treated only as an ordinal: it does not
  * also match a filename that happens to literally equal the digits. That
  * would require a patch literally named `5` or `005`, which would collide
  * with the filename prefix anyway.
@@ -280,9 +280,9 @@ export async function applyPatchesWithContinue(patchesDir, engineDir, options =
     const patches = await discoverPatches(patchesDir);
     // Resolve the --until stop index up front so callers get an immediate
     // error on an unknown identifier instead of a silent no-op. Detect
-    // ambiguity (two patches matching the same needle — should never happen
-    // in a well-formed manifest but surfaces queue corruption loudly
-    // instead of silently picking the first match).
+    // ambiguity (two patches matching the same needle). That should never
+    // happen in a well-formed manifest, but it surfaces queue corruption
+    // loudly instead of silently picking the first match.
     let stopIndex = patches.length - 1;
     if (untilFilename !== undefined) {
         const matchingIndexes = [];
@@ -314,8 +314,8 @@ export async function applyPatchesWithContinue(patchesDir, engineDir, options =
         if (!patch)
             continue;
         if (i > stopIndex) {
-            // Patches beyond the --until cutoff are intentionally skipped. They
-            // are not failures — record them in `skipped` so the summary still
+            // Patches beyond the --until cutoff are skipped on purpose. They
+            // are not failures. Record them in `skipped` so the summary still
             // reflects what the full queue contained.
             skipped.push(patch);
             continue;
@@ -358,11 +358,11 @@ export async function applyPatchesWithContinue(patchesDir, engineDir, options =
 }
 /**
  * Builds a batched patched-content context that loads the manifest and
- * discovers patch files ONCE for many lookups, and memoizes each patch body
+ * discovers patch files once for many lookups, and memoizes each patch body
  * read across the batch. A per-call helper re-runs `loadPatchesManifest` +
- * `discoverPatches` and re-reads every affecting patch body for every file —
- * O(dirtyFiles × patches) redundant IO when classifying a broad engine edit
- * session during `status` or `import`.
+ * `discoverPatches` and re-reads every affecting patch body for every file,
+ * which is O(dirtyFiles × patches) redundant IO when classifying a broad
+ * engine edit session during `status` or `import`.
  */
 export async function createPatchedContentContext(patchesDir, engineDir) {
     const manifest = await loadPatchesManifest(patchesDir);

package/dist/src/core/patch-export-update.d.ts

@@ -18,7 +18,7 @@ export interface UpdatePatchAndMetadataOptions {
     patchesDir: string;
     /** Patch file to rewrite. */
     filename: string;
-    /** New patch body; an identical body skips the write. */
+    /** New patch body. An identical body skips the write. */
     newContent: string;
     /** Manifest-row fields to merge into the patch's metadata. */
     updates: Partial<PatchMetadata>;
@@ -36,11 +36,11 @@ export interface UpdatePatchAndMetadataOptions {
  *
  * The body write is skipped when the normalized new content is byte-identical
  * to what is already on disk. A bulk `re-export --all` refreshes every patch
- * in the queue, including ones the working tree never touched; rewriting an
+ * in the queue, including ones the working tree never touched. Rewriting an
  * unchanged body churns its mtime and reports "Re-exported" for a patch
  * nothing happened to, which is exactly the noise that hides a real
- * unexpected rewrite in `git status`. Metadata still moves either way — only
- * the redundant byte-for-byte write is elided.
+ * unexpected rewrite in `git status`. Metadata still moves either way, and
+ * only the redundant byte-for-byte write is elided.
  *
  * @param options - See {@link UpdatePatchAndMetadataOptions}
  * @returns True when the patch body on disk changed, false when it was

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

@@ -14,11 +14,11 @@ import { buildProjectedManifest, enforcePatchPolicy } from './patch-policy.js';
  *
  * The body write is skipped when the normalized new content is byte-identical
  * to what is already on disk. A bulk `re-export --all` refreshes every patch
- * in the queue, including ones the working tree never touched; rewriting an
+ * in the queue, including ones the working tree never touched. Rewriting an
  * unchanged body churns its mtime and reports "Re-exported" for a patch
  * nothing happened to, which is exactly the noise that hides a real
- * unexpected rewrite in `git status`. Metadata still moves either way — only
- * the redundant byte-for-byte write is elided.
+ * unexpected rewrite in `git status`. Metadata still moves either way, and
+ * only the redundant byte-for-byte write is elided.
  *
  * @param options - See {@link UpdatePatchAndMetadataOptions}
  * @returns True when the patch body on disk changed, false when it was

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

@@ -7,7 +7,7 @@ export { mutatePatchMetadata, updatePatchMetadata } from './patch-export-metadat
 export { updatePatchAndMetadata } from './patch-export-update.js';
 /**
  * Projects the planning subset out of a wider export input (commit input,
- * dry-run preview input) — the fields `planExport` /
+ * dry-run preview input): the fields `planExport` /
  * `computeExportPlanUnderLock` read. Optional fields are copied only when
  * present so the plan input never carries explicit `undefined` keys, which
  * would otherwise leak into the written metadata via spread. The commit
@@ -33,7 +33,7 @@ export declare function getNextPatchNumber(patchesDir: string): Promise<string>;
 export declare function sanitizeName(name: string): string;
 /**
  * Strips a leading `NNN-<category>-` prefix from a sanitized name slug.
- * Operators frequently pass the DESIRED FILENAME stem to `--name`
+ * Operators frequently pass the desired filename stem to `--name`
  * (`--name 203-ui-foo --category ui`), which would otherwise double-prefix
  * into `203-ui-203-ui-foo.patch`. The filename builders prepend the order
  * and category themselves, so a matching prefix in the name is always
@@ -45,7 +45,7 @@ export declare function stripRedundantCategoryPrefix(sanitizedName: string, cate
  * Sanitizes a patch name and drops redundant category/full-stem prefixes.
  *
  * A single trailing `.patch` extension is stripped before sanitisation:
- * operators frequently pass a full patch FILENAME where a name is expected
+ * operators frequently pass a full patch filename where a name is expected
  * (`move-files <from> 348-ui-foo.patch --create`, `rename --to foo.patch`),
  * and slugging the extension produces double-suffixed `...-patch.patch`
  * files. A name that deliberately ends in a literal `-patch` slug segment
@@ -115,7 +115,7 @@ export declare function updatePatch(patchPath: string, newContent: string): Prom
  * Dry-run and the real write both go through {@link computeExportPlanUnderLock}
  * so their filename allocation, supersede detection, and projected
  * post-write manifest cannot drift. `planExport` exposes the rich coverage
- * form for preview rendering; {@link commitExportedPatch} consumes the bare
+ * form for preview rendering. {@link commitExportedPatch} consumes the bare
  * `PatchInfo[]` form of the same underlying data.
  */
 export interface ExportPlan {
@@ -145,13 +145,13 @@ export interface PlanExportInput {
     /**
      * Optional `PatchMetadata.tier` opt-in carried from the CLI flag.
      * Only `"branding"` is currently recognised. When provided the field
-     * is written into the new patch's metadata; when absent the field
+     * is written into the new patch's metadata. When absent the field
      * stays unset and tier resolution falls back to auto-detection.
      */
     tier?: 'branding';
     /**
      * Optional `PatchMetadata.lintIgnore` carried from the CLI flag.
-     * Empty arrays are treated as "field absent" — the validator only
+     * Empty arrays are treated as "field absent": the validator only
      * preserves the field when it has at least one entry.
      */
     lintIgnore?: string[];
@@ -159,16 +159,16 @@ export interface PlanExportInput {
     config?: FireForgeConfig;
 }
 /**
- * Read-only planning function — computes everything a real export would
+ * Read-only planning function. Computes everything a real export would
  * do without writing anything to disk. Takes the patch directory lock
  * briefly, runs {@link computeExportPlanUnderLock}, releases the lock,
  * and returns the plan for preview rendering.
  *
  * Shares {@link computeExportPlanUnderLock} with {@link commitExportedPatch}
  * so the dry-run preview cannot drift from the real write. The real write
- * path does NOT reuse a prior plan object (another export may have landed
- * between dry-run and commit, which would stale the filename allocation);
- * it re-runs the same helper under a fresh lock. The guarantee is "same
+ * path does not reuse a prior plan object (another export may have landed
+ * between dry-run and commit, which would stale the filename allocation).
+ * It re-runs the same helper under a fresh lock. The guarantee is "same
  * code, possibly different data," not "same plan object."
  */
 export declare function planExport(input: PlanExportInput): Promise<ExportPlan>;

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

@@ -14,7 +14,7 @@ export { mutatePatchMetadata, updatePatchMetadata } from './patch-export-metadat
 export { updatePatchAndMetadata } from './patch-export-update.js';
 /**
  * Projects the planning subset out of a wider export input (commit input,
- * dry-run preview input) — the fields `planExport` /
+ * dry-run preview input): the fields `planExport` /
  * `computeExportPlanUnderLock` read. Optional fields are copied only when
  * present so the plan input never carries explicit `undefined` keys, which
  * would otherwise leak into the written metadata via spread. The commit
@@ -71,7 +71,7 @@ export function sanitizeName(name) {
 }
 /**
  * Strips a leading `NNN-<category>-` prefix from a sanitized name slug.
- * Operators frequently pass the DESIRED FILENAME stem to `--name`
+ * Operators frequently pass the desired filename stem to `--name`
  * (`--name 203-ui-foo --category ui`), which would otherwise double-prefix
  * into `203-ui-203-ui-foo.patch`. The filename builders prepend the order
  * and category themselves, so a matching prefix in the name is always
@@ -100,7 +100,7 @@ export function stripRedundantCategoryPrefix(sanitizedName, category) {
  * Sanitizes a patch name and drops redundant category/full-stem prefixes.
  *
  * A single trailing `.patch` extension is stripped before sanitisation:
- * operators frequently pass a full patch FILENAME where a name is expected
+ * operators frequently pass a full patch filename where a name is expected
  * (`move-files <from> 348-ui-foo.patch --create`, `rename --to foo.patch`),
  * and slugging the extension produces double-suffixed `...-patch.patch`
  * files. A name that deliberately ends in a literal `-patch` slug segment
@@ -153,7 +153,7 @@ export async function commitExportedPatch(input) {
             // Patch bodies are written byte-for-byte as git produced them, including the
             // single-space rendering of a blank context line.
             //
-            // Do NOT add a whitespace-trimming pass here or at any other write site.
+            // Do not add a whitespace-trimming pass here or at any other write site.
             // Stripping marker lines whose payload is pure whitespace (`/^[ +-]\s+$/` →
             // bare marker) corrupts real content: Firefox sources contain whitespace-only
             // lines, so a ` `/`-` line whose payload was two spaces no longer matches the
@@ -220,16 +220,16 @@ export async function updatePatch(patchPath, newContent) {
     await writeText(patchPath, newContent);
 }
 /**
- * Internal planning helper. Does NOT take the patch directory lock — the
- * caller must already hold it — because the two public entry points
+ * Internal planning helper. It does not take the patch directory lock (the
+ * caller must already hold it), because the two public entry points
  * ({@link planExport} and {@link commitExportedPatch}) each take their own
  * lock for the full operation. Sharing this single pure computation is how
- * dry-run previews and real writes stay in lockstep by construction
- * instead of by parallel implementations that can drift.
+ * dry-run previews and real writes stay in lockstep, instead of relying on
+ * parallel implementations that can drift.
  */
 async function computeExportPlanUnderLock(input) {
     // ForWrite: a corrupt manifest read as null here would produce a
-    // manifestAfter containing ONLY the new patch — committing that plan
+    // manifestAfter containing only the new patch. Committing that plan
     // wipes the queue metadata, and the rollback path would then delete
     // patches.json entirely because manifestBefore looked absent.
     const manifestBefore = await loadPatchesManifestForWrite(input.patchesDir);
@@ -280,16 +280,16 @@ async function computeExportPlanUnderLock(input) {
     };
 }
 /**
- * Read-only planning function — computes everything a real export would
+ * Read-only planning function. Computes everything a real export would
  * do without writing anything to disk. Takes the patch directory lock
  * briefly, runs {@link computeExportPlanUnderLock}, releases the lock,
  * and returns the plan for preview rendering.
  *
  * Shares {@link computeExportPlanUnderLock} with {@link commitExportedPatch}
  * so the dry-run preview cannot drift from the real write. The real write
- * path does NOT reuse a prior plan object (another export may have landed
- * between dry-run and commit, which would stale the filename allocation);
- * it re-runs the same helper under a fresh lock. The guarantee is "same
+ * path does not reuse a prior plan object (another export may have landed
+ * between dry-run and commit, which would stale the filename allocation).
+ * It re-runs the same helper under a fresh lock. The guarantee is "same
  * code, possibly different data," not "same plan object."
  */
 export async function planExport(input) {

package/dist/src/core/patch-identifier-suggest.d.ts

@@ -15,6 +15,6 @@ import type { PatchMetadata } from '../types/commands/index.js';
  * Formats the user-facing "patch not found" error message used by
  * `patch delete`, `patch reorder`, `patch tier`, and
  * `patch lint-ignore`. Returns a single string suitable for the
- * `InvalidArgumentError` body — never the full queue enumeration.
+ * `InvalidArgumentError` body, never the full queue enumeration.
  */
 export declare function formatPatchNotFoundError(identifier: string, patches: readonly PatchMetadata[]): string;

package/dist/src/core/patch-identifier-suggest.js

@@ -22,7 +22,7 @@ const MIN_PREFIX_MATCH_LENGTH = 4;
 const SUGGESTION_LIMIT = 3;
 /**
  * Computes the Levenshtein edit distance between two strings. Used by
- * `formatPatchNotFoundError` to rank candidate identifiers; the small
+ * `formatPatchNotFoundError` to rank candidate identifiers. The small
  * upper bound on input lengths (filenames, ordinals, names) makes the
  * O(m*n) implementation trivially fast.
  */
@@ -87,13 +87,13 @@ function rankSuggestions(identifier, candidates) {
     return candidates
         .map((candidate) => {
         const lower = candidate.toLowerCase();
-        // Prefix relation in EITHER direction is a stronger signal than edit
+        // Prefix relation in either direction is a stronger signal than edit
         // distance and is not bounded by it: a partial ordinal or an
         // abbreviated slug ("ui-foo" for "002-ui-foo.patch") is many edits away
         // from the full identifier yet is obviously the intended target.
         // `lower.startsWith(needle)`: the operator typed an abbreviation of a
         // real identifier. The reverse relation is only meaningful when the
-        // candidate is substantial — otherwise the single-character ordinal
+        // candidate is substantial. Otherwise the single-character ordinal
         // "9" would "match" every input starting with a 9.
         const prefixMatch = needle.length >= MIN_PREFIX_MATCH_LENGTH &&
             (lower.startsWith(needle) ||
@@ -115,7 +115,7 @@ function rankSuggestions(identifier, candidates) {
  * Formats the user-facing "patch not found" error message used by
  * `patch delete`, `patch reorder`, `patch tier`, and
  * `patch lint-ignore`. Returns a single string suitable for the
- * `InvalidArgumentError` body — never the full queue enumeration.
+ * `InvalidArgumentError` body, never the full queue enumeration.
  */
 export function formatPatchNotFoundError(identifier, patches) {
     const accepted = collectAcceptedIdentifiers(patches);