@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/config.js

@@ -1,12 +1,12 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Project configuration — barrel module.
+ * Project configuration barrel module.
  *
  * Re-exports from focused sub-modules:
- *   config-paths.ts    — constants and project path derivation
- *   config-validate.ts — fireforge.json schema validation
- *   config-mutate.ts   — immutable config mutation
- *   config-state.ts    — state file management
+ *   config-paths.ts:    constants and project path derivation
+ *   config-validate.ts: fireforge.json schema validation
+ *   config-mutate.ts:   immutable config mutation
+ *   config-state.ts:    state file management
  */
 import { basename } from 'node:path';
 import { ConfigError, ConfigNotFoundError } from '../errors/config.js';
@@ -18,20 +18,10 @@ import { validateConfig } from './config-validate.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
 // ---- re-exports ----
 export { mutateConfig } from './config-mutate.js';
-export { CONFIG_FILENAME, FIREFORGE_DIR, getProjectPaths, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
-export { loadState, saveState, updateState } from './config-state.js';
+export { FIREFORGE_DIR, getProjectPaths, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
+export { loadState, updateState } from './config-state.js';
 export { validateConfig } from './config-validate.js';
 // ---- config I/O (stays here because it bridges paths + validation) ----
-/**
- * Config-file existence probe.
- *
- * Uses {@link pathExistsStrict} deliberately: a permission error probing
- * `fireforge.json` must propagate rather than read as "no config here",
- * which is what plain `pathExists` would report.
- */
-async function configPathExists(path) {
-    return fsUtils.pathExistsStrict(path);
-}
 /**
  * Checks if a fireforge.json exists in the given directory.
  * @param root - Root directory to check
@@ -39,7 +29,9 @@ async function configPathExists(path) {
  */
 export async function configExists(root) {
     const paths = getProjectPaths(root);
-    return configPathExists(paths.config);
+    // Strict probe: a permission error on `fireforge.json` must propagate
+    // rather than read as "no config here", which plain `pathExists` reports.
+    return fsUtils.pathExistsStrict(paths.config);
 }
 /**
  * Loads and validates the fireforge.json configuration.
@@ -49,7 +41,9 @@ export async function configExists(root) {
  */
 export async function loadConfig(root) {
     const paths = getProjectPaths(root);
-    if (!(await configPathExists(paths.config))) {
+    // Strict probe: a permission error on `fireforge.json` must propagate
+    // rather than read as "no config here", which plain `pathExists` reports.
+    if (!(await fsUtils.pathExistsStrict(paths.config))) {
         throw new ConfigNotFoundError(paths.config);
     }
     try {
@@ -65,12 +59,12 @@ export async function loadConfig(root) {
 }
 /**
  * Reads the raw `fireforge.json` document without running it through
- * {@link validateConfig}. Returns every persisted key — including keys
+ * {@link validateConfig}. Returns every persisted key, including keys
  * written via `fireforge config <key> --force` that `validateConfig`
  * would strip from the typed result.
  *
  * Callers that need the validated, typed shape must still use
- * {@link loadConfig}; this helper exists specifically for the `config`
+ * {@link loadConfig}. This helper exists specifically for the `config`
  * read path so `fireforge config <key>` can surface keys the write path
  * accepted under `--force`.
  *
@@ -81,7 +75,9 @@ export async function loadConfig(root) {
  */
 export async function loadRawConfigDocument(root) {
     const paths = getProjectPaths(root);
-    if (!(await configPathExists(paths.config))) {
+    // Strict probe: a permission error on `fireforge.json` must propagate
+    // rather than read as "no config here", which plain `pathExists` reports.
+    if (!(await fsUtils.pathExistsStrict(paths.config))) {
         throw new ConfigNotFoundError(paths.config);
     }
     try {
@@ -129,9 +125,9 @@ export async function writeConfigDocument(root, config) {
  * Runs an operation while holding a sidecar lock on `fireforge.json`.
  *
  * Two concurrent `fireforge config <key> <value>` invocations each run
- * load → mutate → writeJson against the same document; without this lock the
- * second rename lands after the first and silently drops the first writer's
- * key, with both commands exiting 0.
+ * load → mutate → writeJson against the same document. Without this lock
+ * the second rename lands after the first and silently drops the first
+ * writer's key, with both commands exiting 0.
  *
  * Reads (`loadConfig`, `loadRawConfigDocument`) stay lock-free: writers
  * always use `writeJson`'s atomic temp-file + rename, so a reader observes

package/dist/src/core/coverage-extend.d.ts

@@ -3,34 +3,34 @@
  * into the recorded `testPackagingCoverage` instead of replacing it, under
  * an anchor guard.
  *
- * Coverage REPLACES by default for a reason documented in
+ * Coverage replaces by default for a reason documented in
  * `build-baseline-types.ts`: every baseline write refreshes
- * `packageableFingerprints` for ALL dirty packageable paths, so a blind
+ * `packageableFingerprints` for all dirty packageable paths, so a blind
  * union would whitewash an earlier scope's edited fixtures while
  * `obj-*`/`_tests/` still holds that scope's stale staging. Extending is
- * honest only while everything the PREVIOUS record vouched for is still
+ * honest only while everything the previous record vouched for is still
  * true, which is what {@link checkExtendCoverageAnchor} and
  * {@link checkExtendMozconfigAnchor} verify:
  *
- *   1. engine HEAD is unchanged — every committed edit is excluded;
+ *   1. engine HEAD is unchanged, so every committed edit is excluded.
  *   2. every path the previous baseline fingerprinted still hashes to the
  *      recorded digest, so the earlier scope's staging inputs are
- *      byte-identical. Files that became dirty SINCE that build are fine:
+ *      byte-identical. Files that became dirty since that build are fine:
  *      the current whole-tree `mach build faster` repackages `dist/` and
- *      vouches for them;
+ *      vouches for them.
  *   3. the generated `engine/mozconfig` is unchanged. Engine HEAD does not
- *      cover this — the mozconfig is regenerated from project-side
+ *      cover this: the mozconfig is regenerated from project-side
  *      `configs/*.mozconfig` templates plus `fireforge.json` on every build,
  *      so two builds at the same engine SHA can configure differently.
  *
- * Every failure refuses fail-closed; the operator's remedy is always a plain
+ * Every failure refuses fail-closed. The operator's remedy is always a plain
  * scoped build, which resets the claim to the paths it actually vouches for.
  *
- * Known boundary, documented rather than closed: dirty NON-packageable
+ * Known boundary, documented rather than closed: dirty non-packageable
  * fixtures under previously covered paths (plain test files, manifests
  * `isPackageablePath` rejects) are invisible to check 2. Editing one
  * uncommitted between two builds leaves the earlier scope's `_tests/`
- * staging stale while extend still vouches for it. Plain REPLACE has no such
+ * staging stale while extend still vouches for it. Plain replacement has no such
  * window, because the earlier scope simply stops being covered.
  */
 import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline-types.js';
@@ -54,17 +54,17 @@ export type ExtendAnchorResult = {
 export declare function checkExtendCoverageAnchor(engineDir: string, previousBaseline: BuildBaseline | undefined): Promise<ExtendAnchorResult>;
 /**
  * Verifies the mozconfig half of the anchor. Split from
- * {@link checkExtendCoverageAnchor} because it can only run AFTER
- * `prepareBuildEnvironment` regenerates `engine/mozconfig` — that file is
- * the one this build will configure with — and must still run BEFORE mach,
- * so a refusal costs no build time.
+ * {@link checkExtendCoverageAnchor} because it can only run after
+ * `prepareBuildEnvironment` regenerates `engine/mozconfig` (the file this
+ * build will configure with), and must still run before mach, so a refusal
+ * costs no build time.
  * @param engineDir - Path to the engine directory
  * @param previousBaseline - Baseline recorded by the previous build
  */
 export declare function checkExtendMozconfigAnchor(engineDir: string, previousBaseline: BuildBaseline | undefined): Promise<ExtendAnchorResult>;
 /**
  * Unions the newly built paths onto the recorded claim. A `'full'` claim, or
- * an absent one (which means full), stays `'full'` — it already covers
+ * an absent one (which means full), stays `'full'`, since it already covers
  * everything.
  *
  * @param previous - Coverage recorded by the previous build
@@ -84,7 +84,7 @@ export declare function formatExtendCoverageRefusal(result: {
 /**
  * Hex-encoded SHA-256 of an engine-relative file, matching the digest the
  * baseline writer produces. `undefined` on any IO error, which every caller
- * treats as "cannot prove unchanged" — i.e. a refusal.
+ * treats as "cannot prove unchanged", i.e. a refusal.
  * @param engineDir - Path to the engine directory
  * @param relPath - Engine-relative POSIX path
  */

package/dist/src/core/coverage-extend.js

@@ -4,40 +4,40 @@
  * into the recorded `testPackagingCoverage` instead of replacing it, under
  * an anchor guard.
  *
- * Coverage REPLACES by default for a reason documented in
+ * Coverage replaces by default for a reason documented in
  * `build-baseline-types.ts`: every baseline write refreshes
- * `packageableFingerprints` for ALL dirty packageable paths, so a blind
+ * `packageableFingerprints` for all dirty packageable paths, so a blind
  * union would whitewash an earlier scope's edited fixtures while
  * `obj-*`/`_tests/` still holds that scope's stale staging. Extending is
- * honest only while everything the PREVIOUS record vouched for is still
+ * honest only while everything the previous record vouched for is still
  * true, which is what {@link checkExtendCoverageAnchor} and
  * {@link checkExtendMozconfigAnchor} verify:
  *
- *   1. engine HEAD is unchanged — every committed edit is excluded;
+ *   1. engine HEAD is unchanged, so every committed edit is excluded.
  *   2. every path the previous baseline fingerprinted still hashes to the
  *      recorded digest, so the earlier scope's staging inputs are
- *      byte-identical. Files that became dirty SINCE that build are fine:
+ *      byte-identical. Files that became dirty since that build are fine:
  *      the current whole-tree `mach build faster` repackages `dist/` and
- *      vouches for them;
+ *      vouches for them.
  *   3. the generated `engine/mozconfig` is unchanged. Engine HEAD does not
- *      cover this — the mozconfig is regenerated from project-side
+ *      cover this: the mozconfig is regenerated from project-side
  *      `configs/*.mozconfig` templates plus `fireforge.json` on every build,
  *      so two builds at the same engine SHA can configure differently.
  *
- * Every failure refuses fail-closed; the operator's remedy is always a plain
+ * Every failure refuses fail-closed. The operator's remedy is always a plain
  * scoped build, which resets the claim to the paths it actually vouches for.
  *
- * Known boundary, documented rather than closed: dirty NON-packageable
+ * Known boundary, documented rather than closed: dirty non-packageable
  * fixtures under previously covered paths (plain test files, manifests
  * `isPackageablePath` rejects) are invisible to check 2. Editing one
  * uncommitted between two builds leaves the earlier scope's `_tests/`
- * staging stale while extend still vouches for it. Plain REPLACE has no such
+ * staging stale while extend still vouches for it. Plain replacement has no such
  * window, because the earlier scope simply stops being covered.
  */
-import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { sha256Hex } from '../utils/hash.js';
 import { verbose } from '../utils/logger.js';
 import { DELETED_FILE_FINGERPRINT, } from './build-baseline-types.js';
 import { getHead, isMissingHeadError } from './git.js';
@@ -88,10 +88,10 @@ export async function checkExtendCoverageAnchor(engineDir, previousBaseline) {
 }
 /**
  * Verifies the mozconfig half of the anchor. Split from
- * {@link checkExtendCoverageAnchor} because it can only run AFTER
- * `prepareBuildEnvironment` regenerates `engine/mozconfig` — that file is
- * the one this build will configure with — and must still run BEFORE mach,
- * so a refusal costs no build time.
+ * {@link checkExtendCoverageAnchor} because it can only run after
+ * `prepareBuildEnvironment` regenerates `engine/mozconfig` (the file this
+ * build will configure with), and must still run before mach, so a refusal
+ * costs no build time.
  * @param engineDir - Path to the engine directory
  * @param previousBaseline - Baseline recorded by the previous build
  */
@@ -108,7 +108,7 @@ export async function checkExtendMozconfigAnchor(engineDir, previousBaseline) {
 }
 /**
  * Unions the newly built paths onto the recorded claim. A `'full'` claim, or
- * an absent one (which means full), stays `'full'` — it already covers
+ * an absent one (which means full), stays `'full'`, since it already covers
  * everything.
  *
  * @param previous - Coverage recorded by the previous build
@@ -144,7 +144,7 @@ export function formatExtendCoverageRefusal(result) {
                 `longer anchored. ${remedy}`);
         case 'fingerprint-diverged':
             return ('--extend-coverage refused: ' +
-                `${String(result.detail.length)} packageable file(s) the recorded build staged have changed ` +
+                `${result.detail.length} packageable file(s) the recorded build staged have changed ` +
                 `since (${formatDivergedPaths(result.detail)}). Extending would vouch for the earlier scope ` +
                 `while obj-*/_tests/ still holds its stale staging. ${remedy}`);
         case 'mozconfig-changed':
@@ -156,19 +156,19 @@ export function formatExtendCoverageRefusal(result) {
 function formatDivergedPaths(paths) {
     const head = paths.slice(0, MAX_DIVERGED_REPORTED).join(', ');
     const extra = paths.length - Math.min(paths.length, MAX_DIVERGED_REPORTED);
-    return extra > 0 ? `${head}, … (+${String(extra)} more)` : head;
+    return extra > 0 ? `${head}, … (+${extra} more)` : head;
 }
 /**
  * Hex-encoded SHA-256 of an engine-relative file, matching the digest the
  * baseline writer produces. `undefined` on any IO error, which every caller
- * treats as "cannot prove unchanged" — i.e. a refusal.
+ * treats as "cannot prove unchanged", i.e. a refusal.
  * @param engineDir - Path to the engine directory
  * @param relPath - Engine-relative POSIX path
  */
 export async function hashEngineFile(engineDir, relPath) {
     try {
         const buffer = await readFile(join(engineDir, relPath));
-        return createHash('sha256').update(buffer).digest('hex');
+        return sha256Hex(buffer);
     }
     catch (error) {
         if (getNodeErrorCode(error) === 'ENOENT') {

package/dist/src/core/destructive.d.ts

@@ -17,7 +17,7 @@ export declare const HISTORY_LOG_FILENAME = ".fireforge-history.jsonl";
  * A structural conflict that must block the operation even under `--force`.
  *
  * Intended for cases like "reorder would introduce a forward-import" or
- * "delete would orphan a later patch's import" — situations where the
+ * "delete would orphan a later patch's import", situations where the
  * operator almost certainly wants a different fix (re-export --files, etc.)
  * rather than a bypass. `--force-unsafe` is the escape hatch when the
  * operator genuinely accepts the risk.
@@ -35,9 +35,9 @@ export interface DestructiveOpInput {
     /** Short one-line title shown in the prompt. */
     title: string;
     /**
-     * Detailed change summary — every affected patch, file, or renumber row.
-     * Generic "proceed? [y/N]" is insufficient per the destructive-op contract;
-     * callers must list every concrete change here.
+     * Detailed change summary: every affected patch, file, or renumber row.
+     * Generic "proceed? [y/N]" is insufficient per the destructive-op
+     * contract. Callers must list every concrete change here.
      */
     summary: string[];
     /** Whether the caller passed `--yes`. */
@@ -52,9 +52,9 @@ export interface DestructiveOpInput {
 /**
  * Outcome of the destructive-operation contract.
  *
- * `'declined'` means the operator answered "no" — a successful run that
+ * `'declined'` means the operator answered "no", a successful run that
  * chose not to proceed, so callers return normally and the process exits 0.
- * An INTERRUPT (Esc / Ctrl+C) is not represented here: it throws
+ * An interrupt (Esc / Ctrl+C) is not represented here: it throws
  * {@link CancellationError} and exits 130. Collapsing the two would make an
  * interrupted prompt indistinguishable from a declined one.
  */
@@ -73,11 +73,11 @@ export interface HistoryEntry {
     yes?: boolean;
     /** True if `--force-unsafe` was used. */
     unsafeOverride?: boolean;
-    /** Result: `'ok'` on success; other strings describe failure. */
+    /** Result: `'ok'` on success. Other strings describe failure. */
     result: string;
 }
 /**
- * True when BOTH standard handles are real TTYs, i.e. an interactive prompt
+ * True when both standard handles are real TTYs, i.e. an interactive prompt
  * can actually be answered.
  *
  * Named for the condition rather than for confirmation specifically: many
@@ -87,16 +87,16 @@ export interface HistoryEntry {
  * Node types `isTTY` as `boolean`, but at runtime it is `true | undefined`
  * (absent when the handle is not a TTY). Unusual harnesses (vitest stdio
  * capture, CI spawners, mocked pipes) can also leave it unset on only one
- * handle, so every falsy variant — false, undefined, a null-patched mock —
+ * handle, so every falsy variant (false, undefined, a null-patched mock)
  * must route to the non-interactive path.
  */
 export declare function stdioIsInteractive(): boolean;
 /**
- * UP-FRONT non-interactive refusal for a command that will end at
+ * Up-front non-interactive refusal for a command that will end at
  * {@link confirmDestructive}.
  *
  * `confirmDestructive` already refuses a prompt-less run rather than
- * proceeding silently — but it does so at the END, after the command has
+ * proceeding silently, but it does so at the end, after the command has
  * built diffs and run projected per-patch lint. On `patch move-files
  * --create` that is minutes of work before a scripted run learns it needed
  * `--yes`, and the failure reads as an obscure late error rather than a
@@ -117,7 +117,7 @@ export declare function assertConfirmationAvailable(operation: string, options:
  * Executes the destructive-operation contract: summary → conflict refusal →
  * dry-run / force / prompt / non-TTY refusal.
  *
- * Returns the decision for the caller to act on; callers must not execute
+ * Returns the decision for the caller to act on. Callers must not execute
  * the mutation when the result is `'dry-run'` or `'declined'`, and must call
  * {@link appendHistory} only after the mutation succeeds (never on dry-run
  * or decline).
@@ -132,8 +132,8 @@ export declare function confirmDestructive(input: DestructiveOpInput): Promise<D
  *
  * Call order matters: append only after the mutation succeeds, never
  * pre-emptively, so rolled-back failures do not leave ghost entries. The log
- * is append-only and advisory — no code path reads it back; it exists purely
- * so operators have a post-hoc audit trail when something goes wrong.
+ * is append-only and advisory: no code path reads it back. It exists so
+ * operators have a post-hoc audit trail when something goes wrong.
  *
  * @param patchesDir - Path to the patches directory
  * @param entry - Serializable history record

package/dist/src/core/destructive.js

@@ -40,7 +40,7 @@ function printConflicts(conflicts) {
     }
 }
 /**
- * True when BOTH standard handles are real TTYs, i.e. an interactive prompt
+ * True when both standard handles are real TTYs, i.e. an interactive prompt
  * can actually be answered.
  *
  * Named for the condition rather than for confirmation specifically: many
@@ -50,7 +50,7 @@ function printConflicts(conflicts) {
  * Node types `isTTY` as `boolean`, but at runtime it is `true | undefined`
  * (absent when the handle is not a TTY). Unusual harnesses (vitest stdio
  * capture, CI spawners, mocked pipes) can also leave it unset on only one
- * handle, so every falsy variant — false, undefined, a null-patched mock —
+ * handle, so every falsy variant (false, undefined, a null-patched mock)
  * must route to the non-interactive path.
  */
 export function stdioIsInteractive() {
@@ -59,11 +59,11 @@ export function stdioIsInteractive() {
     return stdinIsTTY === true && stdoutIsTTY === true;
 }
 /**
- * UP-FRONT non-interactive refusal for a command that will end at
+ * Up-front non-interactive refusal for a command that will end at
  * {@link confirmDestructive}.
  *
  * `confirmDestructive` already refuses a prompt-less run rather than
- * proceeding silently — but it does so at the END, after the command has
+ * proceeding silently, but it does so at the end, after the command has
  * built diffs and run projected per-patch lint. On `patch move-files
  * --create` that is minutes of work before a scripted run learns it needed
  * `--yes`, and the failure reads as an obscure late error rather than a
@@ -90,7 +90,7 @@ export function assertConfirmationAvailable(operation, options) {
  * Executes the destructive-operation contract: summary → conflict refusal →
  * dry-run / force / prompt / non-TTY refusal.
  *
- * Returns the decision for the caller to act on; callers must not execute
+ * Returns the decision for the caller to act on. Callers must not execute
  * the mutation when the result is `'dry-run'` or `'declined'`, and must call
  * {@link appendHistory} only after the mutation succeeds (never on dry-run
  * or decline).
@@ -146,8 +146,8 @@ export async function confirmDestructive(input) {
         message: `${title} — proceed?`,
         initialValue: false,
     });
-    // An INTERRUPT and a "no" are different outcomes and must not share an
-    // exit code. Esc / Ctrl+C is a real interrupt — 130 is 128+SIGINT and is
+    // An interrupt and a "no" are different outcomes and must not share an
+    // exit code. Esc / Ctrl+C is a real interrupt. 130 is 128+SIGINT and is
     // what a script needs to tell "the operator aborted" from "the operator
     // considered it and declined". Answering "no" is a successful run.
     //
@@ -165,8 +165,8 @@ export async function confirmDestructive(input) {
  *
  * Call order matters: append only after the mutation succeeds, never
  * pre-emptively, so rolled-back failures do not leave ghost entries. The log
- * is append-only and advisory — no code path reads it back; it exists purely
- * so operators have a post-hoc audit trail when something goes wrong.
+ * is append-only and advisory: no code path reads it back. It exists so
+ * operators have a post-hoc audit trail when something goes wrong.
  *
  * @param patchesDir - Path to the patches directory
  * @param entry - Serializable history record

package/dist/src/core/diff-hunks.d.ts

@@ -1,6 +1,6 @@
 /**
  * An edit op produced by {@link computeLineDiff}. Indices are 0-based into the
- * source line arrays; `line` holds the verbatim text so callers do not have to
+ * source line arrays. `line` holds the verbatim text so callers do not have to
  * keep the input arrays around while rendering.
  */
 export interface LineDiffOp {
@@ -60,7 +60,7 @@ export declare function buildHunks(ops: readonly LineDiffOp[], context: number):
 /**
  * Computes a multi-hunk line diff between two strings. This is the public
  * entry point that {@link furnaceDiffCommand} uses. On normal inputs this
- * runs the exact LCS path and returns a proper multi-hunk diff; on inputs
+ * runs the exact LCS path and returns a proper multi-hunk diff. On inputs
  * that exceed {@link LCS_LINE_LIMIT} it falls back to a single coalesced
  * hunk so the command stays useful instead of OOMing.
  */

package/dist/src/core/diff-hunks.js

@@ -5,7 +5,7 @@ import { assert, expectDefined } from '../utils/assert.js';
  * O(m·n) diff and falling back to the simpler single-region coalesce. Chosen
  * so the worst-case Int32Array allocation stays under ~16 MB. Typical
  * Firefox widget files are a few hundred lines, so the fast path handles the
- * everyday case; the fallback keeps the command usable on a very large file.
+ * everyday case. The fallback keeps the command usable on a very large file.
  */
 const LCS_LINE_LIMIT = 2000;
 /** Splits a string on `\n`, discarding a single trailing empty line from a terminal newline. */
@@ -31,7 +31,7 @@ export function computeLineDiff(oldLines, newLines) {
     // The DP below indexes `dp`, `oldLines`, and `newLines` about 4·m·n times
     // for a worst-case pair, so its bounds are established once here rather
     // than re-checked per access. Callers gate on LCS_LINE_LIMIT before
-    // reaching this function; if that gate is ever moved or removed, this is
+    // reaching this function. If that gate is ever moved or removed, this is
     // where the resulting allocation blow-up surfaces as a named failure
     // instead of an out-of-memory crash.
     assert(m <= LCS_LINE_LIMIT && n <= LCS_LINE_LIMIT, () => `line diff inputs are within LCS_LINE_LIMIT (got ${m}x${n}, limit ${LCS_LINE_LIMIT})`);
@@ -48,7 +48,7 @@ export function computeLineDiff(oldLines, newLines) {
      * above, so the non-null assertions encode a property already checked
      * once per call rather than one that is never checked at all. The
      * rendering loops further down, which run O(ops), use `expectDefined`
-     * instead — this exemption is for the quadratic block only.
+     * instead. This exemption is for the quadratic block only.
      */
     for (let i = 1; i <= m; i++) {
         const oldLine = oldLines[i - 1];
@@ -184,8 +184,8 @@ export function buildHunks(ops, context) {
  * Fallback for inputs that exceed {@link LCS_LINE_LIMIT}. Reproduces the
  * original single-region coalesce: match the common prefix and suffix, then
  * emit one hunk containing the middle region plus `context` lines on each
- * side. Intentionally dumb — the fast path handles normal files, and this
- * only keeps the command usable on pathologically large inputs without
+ * side. Kept simple on purpose: the fast path handles normal files, and
+ * this only keeps the command usable on pathologically large inputs without
  * allocating a huge DP table.
  */
 function coalescedHunk(oldLines, newLines, context) {
@@ -218,7 +218,7 @@ function coalescedHunk(oldLines, newLines, context) {
     for (let k = firstDiff; k <= lastNewDiff; k++) {
         hunkLines.push({ marker: '+', content: expectDefined(newLines[k], () => `new line ${k}`) });
     }
-    // Trailing context comes from the common suffix, which lives at DIFFERENT
+    // Trailing context comes from the common suffix, which lives at different
     // indices on each side (lastOldDiff+1… vs lastNewDiff+1…). Mixing the two
     // coordinate spaces emits wrong context on asymmetric edits and drops the
     // trailing lines from the @@ header lengths, so the rendered header
@@ -245,7 +245,7 @@ function coalescedHunk(oldLines, newLines, context) {
 /**
  * Computes a multi-hunk line diff between two strings. This is the public
  * entry point that {@link furnaceDiffCommand} uses. On normal inputs this
- * runs the exact LCS path and returns a proper multi-hunk diff; on inputs
+ * runs the exact LCS path and returns a proper multi-hunk diff. On inputs
  * that exceed {@link LCS_LINE_LIMIT} it falls back to a single coalesced
  * hunk so the command stays useful instead of OOMing.
  */

package/dist/src/core/discard-baseline.d.ts

@@ -2,15 +2,15 @@
  * Patch-aware restore planning for `fireforge discard`.
  *
  * The engine convention is: HEAD = pristine upstream Firefox, and the
- * applied patch queue lives as UNCOMMITTED worktree changes on top of it
+ * applied patch queue lives as uncommitted worktree changes on top of it
  * (`git apply` without `--index` → patch-edited tracked files are unstaged
  * modifications, patch-created files are untracked). A purely git-mechanical
- * discard — restore to HEAD, delete untracked files — therefore reverts
- * patch-backed files PAST their owning patch and deletes patch-created files
+ * discard (restore to HEAD, delete untracked files) therefore reverts
+ * patch-backed files past their owning patch and deletes patch-created files
  * outright.
  *
  * This module classifies each status entry against the patch manifest's
- * ownership claims and plans the correct restore target: the PATCH-APPLIED
+ * ownership claims and plans the correct restore target: the patch-applied
  * baseline (HEAD content folded through every affecting patch in order) for
  * claimed files, and the plain git mechanics for unmanaged ones.
  */
@@ -25,22 +25,22 @@ export interface DiscardBaselinePlan {
     owners: string[];
     /** True when more than one patch claims the path (ownership conflict). */
     conflicted: boolean;
-    /** Baseline content for `entry.file`; null = absent at baseline. Unset for 'unmanaged'. */
+    /** Baseline content for `entry.file` (null = absent at baseline). Unset for 'unmanaged'. */
     expectedContent?: string | null;
     /** Rename/copy only: baseline content for `originalPath` when that side is claimed. */
     expectedOriginalContent?: string | null;
 }
-/** Builds an all-unmanaged plan set — the `--to-upstream` (legacy) shape. */
+/** Builds an all-unmanaged plan set, the `--to-upstream` (legacy) shape. */
 export declare function planUpstreamDiscards(entries: readonly GitStatusEntry[]): DiscardBaselinePlan[];
 /**
  * Plans the restore target for each status entry. Entries claimed by the
- * patch manifest restore to the patch-applied baseline; unclaimed entries
+ * patch manifest restore to the patch-applied baseline. Unclaimed entries
  * keep the plain git mechanics. A missing patches dir or empty manifest
  * degrades every plan to `unmanaged`.
  *
- * A corrupt manifest or an unreconstructible patch baseline REFUSES with a
- * GeneralError naming `--to-upstream` — silently falling back to pristine
- * HEAD is exactly the data-loss path this module exists to close.
+ * A corrupt manifest or an unreconstructible patch baseline refuses with a
+ * GeneralError naming `--to-upstream`. Silently falling back to pristine
+ * HEAD is the data-loss path this module exists to close.
  */
 export declare function planDiscardBaselines(patchesDir: string, engineDir: string, entries: readonly GitStatusEntry[]): Promise<DiscardBaselinePlan[]>;
 /**