@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/core/build-jar-escalation.js

@@ -4,19 +4,19 @@
  * escalate from `mach build faster` to a full `mach build`.
  *
  * The 0.41.0 rule was `any changed jar.mn ⇒ full build`, which costs ~10
- * minutes against ~20 s for a chrome-only slice and is paid TWICE per
+ * minutes against ~20 s for a chrome-only slice and is paid twice per
  * green/no-change pair on a Furnace-touching slice. A downstream experiment
  * (two clean runs, 2026-08-29, against 0.44.4) showed the rule is over-broad
- * for the common case: a jar-only registration of a NEW content file added
- * to an EXISTING `dist/bin` manifest was installed by a plain
- * `fireforge build --ui` both times — `faster/install_dist_bin_browser` named
+ * for the common case: a jar-only registration of a new content file added
+ * to an existing `dist/bin` manifest was installed by a plain
+ * `fireforge build --ui` both times: `faster/install_dist_bin_browser` named
  * the destination, the file landed in `dist/bin/…/content/browser/` and in
  * the `.app` bundle, and a plain `fireforge test` fetched it over
  * `chrome://` at runtime. Neither run escalated, and neither needed to.
  *
- * What the experiment did NOT exercise, and what therefore still escalates:
+ * What the experiment did not exercise, and what therefore still escalates:
  *
- *  - a NEW `jar.mn` file. The install manifest for a manifest the backend
+ *  - a new `jar.mn` file. The install manifest for a manifest the backend
  *    has never seen does not exist yet, and `mach build faster` consumes
  *    install manifests rather than regenerating the backend that writes
  *    them.
@@ -38,7 +38,7 @@ import { getUntrackedFilesInDir } from './git-status.js';
 /**
  * A jar declaration line: an optional bracketed base-directory prefix, then
  * the jar name. Matched at column zero because entry lines inside a section
- * are indented — an indented `foo.jar:` is content, not a declaration.
+ * are indented. An indented `foo.jar:` is content, not a declaration.
  */
 const JAR_DECLARATION_PATTERN = /^(\[[^\]]*\]\s*)?[^\s[\]]+\.jar:\s*$/;
 /** True when the jar declaration redirects the install base directory. */
@@ -49,14 +49,14 @@ function declaresNonDefaultBase(line) {
     return match[1] !== undefined;
 }
 /**
- * True when a changed `jar.mn` is NEW to the last successful build.
+ * True when a changed `jar.mn` is new to the last successful build.
  *
- * Untracked in the engine repo is the reliable tell: a fork's engine tree is
- * a checkout of upstream with patches applied to the WORKTREE, so a manifest
- * a patch created is untracked and one that shipped upstream is tracked. The
- * baseline's fingerprints cannot answer this on their own — they record only
- * the paths that were DIRTY at the last build, so a clean pre-existing
- * manifest has no entry either.
+ * Untracked in the engine repo is the reliable signal: a fork's engine tree
+ * is a checkout of upstream with patches applied to the worktree, so a
+ * manifest a patch created is untracked and one that shipped upstream is
+ * tracked. The baseline's fingerprints cannot answer this on their own: they
+ * record only the paths that were dirty at the last build, so a clean
+ * pre-existing manifest has no entry either.
  */
 async function isNewJarManifest(engineDir, path) {
     const untracked = await getUntrackedFilesInDir(engineDir, path);
@@ -116,7 +116,7 @@ export async function evaluateJarManifestEscalation(engineDir, changedPaths, bas
     return { escalate: causes.length > 0, causes, cleared };
 }
 /**
- * Renders the operator-facing escalation notice. Names the manifest AND the
+ * Renders the operator-facing escalation notice. Names the manifest and the
  * reason: "a jar.mn changed" is the sentence that made the previous rule
  * impossible to argue with from outside.
  */

package/dist/src/core/build-overwrite-guard.d.ts

@@ -1,15 +1,15 @@
 /**
- * Loud guard against silently reverting UNEXPORTED engine drift.
+ * Loud guard against silently reverting unexported engine drift.
  *
  * `build-prepare` rewrites engine files from FireForge-owned sources before
  * every build: the branding tree, every Furnace-managed component, and
  * `mozconfig`. On a multi-session checkout that is a silent destructive
- * write — one session edits a file in `engine/` while another holds the
+ * write: one session edits a file in `engine/` while another holds the
  * engine lock, the lock-holder's build rewrites it back to its patch
  * baseline, and the editing session's later `re-export --wait-lock`
- * captures a HYBRID file that every gate then passes.
+ * captures a hybrid file that every gate then passes.
  *
- * This guard runs BEFORE the writes, classifies the engine's dirty files
+ * This guard runs before the writes, classifies the engine's dirty files
  * with the same classifier `fireforge status` uses, and reports the ones
  * whose content is explained by neither a patch body nor the pristine
  * baseline. Advisory by default (a warning naming every file), refusing

package/dist/src/core/build-overwrite-guard.js

@@ -1,16 +1,16 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Loud guard against silently reverting UNEXPORTED engine drift.
+ * Loud guard against silently reverting unexported engine drift.
  *
  * `build-prepare` rewrites engine files from FireForge-owned sources before
  * every build: the branding tree, every Furnace-managed component, and
  * `mozconfig`. On a multi-session checkout that is a silent destructive
- * write — one session edits a file in `engine/` while another holds the
+ * write: one session edits a file in `engine/` while another holds the
  * engine lock, the lock-holder's build rewrites it back to its patch
  * baseline, and the editing session's later `re-export --wait-lock`
- * captures a HYBRID file that every gate then passes.
+ * captures a hybrid file that every gate then passes.
  *
- * This guard runs BEFORE the writes, classifies the engine's dirty files
+ * This guard runs before the writes, classifies the engine's dirty files
  * with the same classifier `fireforge status` uses, and reports the ones
  * whose content is explained by neither a patch body nor the pristine
  * baseline. Advisory by default (a warning naming every file), refusing
@@ -23,12 +23,12 @@ import { collectFurnaceManagedPrefixes } from './furnace-config.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from './git-status.js';
 import { classifyFiles } from './status-classify.js';
 /**
- * Classifications whose on-disk content is explained by NEITHER a patch
- * body nor the pristine baseline — exactly the content a build-prepare
+ * Classifications whose on-disk content is explained by neither a patch
+ * body nor the pristine baseline, which is the content a build-prepare
  * overwrite would destroy without a record anywhere.
  *
- * `patch-backed` and `furnace` are excluded because their content IS the
- * recorded state; `branding` is excluded because the branding writer
+ * `patch-backed` and `furnace` are excluded because their content is the
+ * recorded state. `branding` is excluded because the branding writer
  * preserves unmanaged lines rather than overwriting them.
  */
 const AT_RISK_CLASSIFICATIONS = new Set(['unmanaged', 'patch-owned-drift', 'conflict']);
@@ -58,15 +58,15 @@ function isOverwrittenByBuildPrepare(file, binaryName, furnacePrefixes) {
  * Narrows the status entries to the ones build-prepare can overwrite,
  * expanding collapsed untracked directories on the way.
  *
- * Git reports a WHOLLY untracked directory as a single `?? dir/` entry
+ * Git reports a wholly untracked directory as a single `?? dir/` entry
  * rather than listing the files under it. A directory entry has no content
  * to compare, so `classifyFiles` matches it against neither a patch body nor
- * the pristine baseline and buckets it `unmanaged` — an at-risk
- * classification. Expanding here is what keeps this guard and
- * `status --unmanaged`, which expands, agreeing by construction.
+ * the pristine baseline and buckets it `unmanaged`, an at-risk
+ * classification. Expanding here keeps this guard in agreement with
+ * `status --unmanaged`, which also expands.
  *
  * Expansion is scoped to build-prepare-owned prefixes on both sides of the
- * walk: a collapsed directory that merely CONTAINS an owned prefix
+ * walk: a collapsed directory that merely contains an owned prefix
  * (`components/` when `components/custom/` is Furnace-managed) is rewritten
  * to the owned prefixes beneath it, so the enumeration never walks an
  * unrelated subtree and never trips the per-directory expansion cap.

package/dist/src/core/build-prepare.d.ts

@@ -26,20 +26,20 @@ export interface PrepareBuildOptions {
      * Previous successful-build baseline, used to detect `moz.build` /
      * `moz.configure` / `Makefile.in` changes that require a fresh
      * `mach configure` before the build. When undefined, the auto-configure
-     * step is skipped — there's no reference point for what "changed since"
-     * means.
+     * step is skipped, since there's no reference point for what "changed
+     * since" means.
      */
     previousBaseline?: BuildBaseline | undefined;
     /**
      * Turn the unexported-drift warning into a hard refusal.
-     * Scripted gates want the stop; an interactive build wants the warning.
+     * Scripted gates want the stop. An interactive build wants the warning.
      */
     refuseUnexportedDrift?: boolean | undefined;
 }
 /**
  * Describes an exit code in the shell's 128+N signal convention. Truncated
  * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG
- * on macOS) are environmental interruptions, not compiler failures — naming
+ * on macOS) are environmental interruptions, not compiler failures. Naming
  * that in the failure text saves the operator a fruitless log hunt.
  * Returns undefined for codes <= 128 (regular failures) and
  * for codes past the conventional signal range, so callers append nothing.

package/dist/src/core/build-prepare.js

@@ -25,7 +25,7 @@ import { explainMachError } from './mach-error-hints.js';
 /** Path fragments of files whose edits invalidate the recursive-make backend. */
 const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
 /**
- * Build-input manifests changed since the last SUCCESSFUL build — not
+ * Build-input manifests changed since the last successful build, not
  * merely dirty against HEAD. `collectChangedEnginePaths` unions the
  * baseline-to-HEAD diff with every worktree modification, and a fork's
  * worktree is permanently dirty (imported patches, Furnace-applied
@@ -33,8 +33,8 @@ const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.i
  * `moz.build` as changed on every run: `mach configure` re-ran and the
  * pre-test build escalated to a full `mach build` after each full build
  * that had already consumed exactly this content. The baseline's
- * `buildInputFingerprints` say what the last successful build saw;
- * anything byte-identical to that is dropped here. A baseline without the
+ * `buildInputFingerprints` say what the last successful build saw.
+ * Anything byte-identical to that is dropped here. A baseline without the
  * field (written before it existed) keeps every dirty input, which is the
  * old behaviour.
  *
@@ -56,8 +56,9 @@ async function collectChangedBuildInputs(engineDir, baseline) {
  * Extracts the tail of captured `mach configure` output so the underlying
  * mozbuild failure (e.g. `mozbuild.util.UnsortedError: ... is not in sorted
  * order`) is carried into the thrown `BuildError` instead of being reduced to
- * a bare exit code. mozbuild writes the error and its traceback to stderr;
- * stdout is included as a fallback for shells that interleave the streams.
+ * a bare exit code. mozbuild writes the error and its traceback to stderr,
+ * and stdout is included as a fallback for shells that interleave the
+ * streams.
  * Returns an empty string when nothing useful was captured.
  */
 function extractMachConfigureError(result) {
@@ -69,7 +70,7 @@ function extractMachConfigureError(result) {
 /**
  * Describes an exit code in the shell's 128+N signal convention. Truncated
  * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG
- * on macOS) are environmental interruptions, not compiler failures — naming
+ * on macOS) are environmental interruptions, not compiler failures. Naming
  * that in the failure text saves the operator a fruitless log hunt.
  * Returns undefined for codes <= 128 (regular failures) and
  * for codes past the conventional signal range, so callers append nothing.
@@ -91,7 +92,7 @@ export function describeSignalShapedExit(exitCode) {
  * Builds the `BuildError` for a non-zero auto-configure exit: the output
  * tail (so the underlying mozbuild failure survives), any matched
  * mach-error hints (so e.g. a toolchain minimum that moved with a source
- * hop names `fireforge bootstrap` on this path too, exactly like the
+ * hop names `fireforge bootstrap` on this path too, just like the
  * protected build dispatch), and the stop rationale.
  */
 function buildConfigureFailureError(captured) {
@@ -116,7 +117,7 @@ function buildConfigureFailureError(captured) {
  * @param baseline - Last successful build's baseline
  */
 async function decideJarEscalation(engineDir, changed, baseline) {
-    // Packaging manifests whose graph/destination directories MAY need a full
+    // Packaging manifests whose graph/destination directories may need a full
     // build. Path-shape only: `evaluateJarManifestEscalation` decides whether a
     // given changed manifest actually forces one (a new manifest, or one that
     // redirects its install base directory), so an entry added to an existing
@@ -139,10 +140,10 @@ export function isBackendInvalidatingFile(path) {
     return false;
 }
 /**
- * Loud before the overwrite, not silent after it.
+ * Warns before the overwrite rather than after it.
  *
- * Every write `prepareBuildEnvironment` performs — branding, Furnace
- * components, `mozconfig` — rewrites engine files from a FireForge-owned
+ * Every write `prepareBuildEnvironment` performs (branding, Furnace
+ * components, `mozconfig`) rewrites engine files from a FireForge-owned
  * source. Content recorded in neither a patch body nor the pristine baseline
  * is destroyed by that, and on a multi-session checkout the destruction is
  * what lets a later re-export capture a half-reverted hybrid that every gate
@@ -215,9 +216,9 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
                 const exitCode = captured.exitCode;
                 if (exitCode !== 0) {
                     configureSpinner.error(`mach configure failed with exit code ${exitCode}`);
-                    // Surface the underlying mozbuild error (e.g. UnsortedError) instead
-                    // of a bare exit code — the generic message hid the actual cause —
-                    // plus any matched mach-error hints (see the helper).
+                    // Surface the underlying mozbuild error (e.g. UnsortedError)
+                    // instead of a bare exit code, since the generic message hid the
+                    // actual cause, plus any matched mach-error hints (see the helper).
                     throw buildConfigureFailureError(captured);
                 }
                 else {
@@ -241,7 +242,7 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
     // Set up custom branding directory and patch moz.configure. Thread the
     // project license through so `buildConfigureScriptContent` /
     // `buildBrandPropertiesContent` / `buildBrandFtlContent` stamp the
-    // generated files with a matching SPDX header — otherwise `patch-lint`
+    // generated files with a matching SPDX header. Otherwise `patch-lint`
     // flags them with `missing-license-header` on every subsequent export when
     // the project is not MPL-2.0.
     const brandingConfig = {

package/dist/src/core/config-mutate.js

@@ -18,10 +18,10 @@ function cloneConfigDocument(config) {
     return cloned;
 }
 /**
- * The error every sentinel-segment refusal raises. Only the MESSAGE lives
+ * The error every sentinel-segment refusal raises. Only the message lives
  * here: the comparison itself is spelled inline at each write site, because
  * that is what both a reader and CodeQL's `js/prototype-pollution-utility`
- * barrier detection need — the latter is not interprocedural, so a check
+ * barrier detection need. That detection is not interprocedural, so a check
  * hidden behind a helper leaves the descent below looking unguarded.
  */
 function sentinelSegmentError(key, part) {
@@ -41,8 +41,8 @@ function getOrCreateChildRecord(parent, key) {
 export function mutateConfig(config, key, value, skipValidation = false) {
     const parts = key.split('.');
     const raw = cloneConfigDocument(config);
-    // Every segment is checked at the point it is USED as a property name —
-    // the descent below and the leaf assignment — rather than once up front,
+    // Every segment is checked at the point it is used as a property name
+    // (the descent below and the leaf assignment) rather than once up front,
     // so `--force` cannot be used to mutate Object.prototype and neither write
     // can drift out from behind the guard. `raw` is a private clone, so a
     // refusal here has mutated nothing the caller can observe.

package/dist/src/core/config-state.js

@@ -35,9 +35,9 @@ function sanitizeProjectState(data) {
             continue;
         }
         if (key === 'buildMode') {
-            // Validate and assign in ONE block so the predicate's narrowing reaches
+            // Validate and assign in one block so the predicate's narrowing reaches
             // the assignment. Split across two `key === 'buildMode'` guards,
-            // TypeScript cannot correlate them and the assignment needed a cast —
+            // TypeScript cannot correlate them and the assignment needed a cast,
             // which is what let the untyped allowlist drift from the union.
             if (!isBuildMode(value)) {
                 issues.push(`field "buildMode" must be one of: ${BUILD_MODES.join(', ')}`);

package/dist/src/core/config-validate-build-audit.js

@@ -5,8 +5,8 @@
  * Split out of `config-validate.ts`, which is at its per-file line budget,
  * following the `config-validate-file-size.ts` precedent.
  *
- * The rules here are stricter than the schema strictly needs, and
- * deliberately so: every entry is a standing suppression of a warning the
+ * The rules here are stricter than the schema strictly needs, on purpose:
+ * every entry is a standing suppression of a warning the
  * audit would otherwise raise. A malformed one must fail loudly at config
  * load rather than quietly admit nothing (leaving the operator believing a
  * path is carved out) or quietly admit everything.
@@ -40,7 +40,7 @@ function parseUnpackagedEntry(raw, field) {
     const reason = raw['reason'];
     if (typeof reason !== 'string' || reason.trim().length === 0) {
         // Required on purpose: this is the one audit class FireForge cannot
-        // derive from the tree, so the declaration IS the evidence.
+        // derive from the tree, so the declaration is the evidence.
         throw new ConfigError(`Config field "${field}.reason" must be a non-empty string explaining why the file is never packaged`);
     }
     return { path, reason };

package/dist/src/core/config-validate-file-size.d.ts

@@ -6,7 +6,7 @@
 import type { PatchLintFileSizeThresholds } from '../types/config.js';
 /**
  * Parses the `patchLint.fileSizeThresholds` block. Ordering is validated
- * against the MERGED triple (overrides on top of the defaults), so setting
+ * against the merged triple (overrides on top of the defaults), so setting
  * only `warning` cannot land below the default `notice`.
  */
 export declare function parsePatchLintFileSizeThresholds(raw: unknown): PatchLintFileSizeThresholds;

package/dist/src/core/config-validate-file-size.js

@@ -9,7 +9,7 @@ import { isObject } from '../utils/validation.js';
 import { DEFAULT_FILE_SIZE_THRESHOLDS } from './patch-lint-file-size.js';
 /**
  * Parses one `patchLint.fileSizeThresholds.<tier>` triple. Every field is
- * optional and merges over the built-in default; values must be positive
+ * optional and merges over the built-in default. Values must be positive
  * integers and stay ordered `notice <= warning <= error`, because an
  * out-of-order triple would silently disable a band instead of failing.
  */
@@ -36,7 +36,7 @@ function parseFileSizeTier(raw, field) {
 }
 /**
  * Parses the `patchLint.fileSizeThresholds` block. Ordering is validated
- * against the MERGED triple (overrides on top of the defaults), so setting
+ * against the merged triple (overrides on top of the defaults), so setting
  * only `warning` cannot land below the default `notice`.
  */
 export function parsePatchLintFileSizeThresholds(raw) {

package/dist/src/core/config-validate.js

@@ -21,7 +21,7 @@ import { parseExternalToolchainsBlock, parseTestBlock } from './config-validate-
 function parseIdentityFields(rec) {
     // Empty strings would technically pass the
     // typeof-check below but are never valid for any of these identifier
-    // fields — rejecting them here prevents downstream code (Firefox build,
+    // fields. Rejecting them here prevents downstream code (Firefox build,
     // launcher binary lookup, AppID assertions) from failing with confusing
     // errors much later.
     const name = requireConfigString(rec, 'name');
@@ -72,7 +72,7 @@ function parseFirefoxBlock(rec) {
     }
     const firefoxProduct = requireConfigString(firefoxRec, 'product', 'firefox.product');
     // Uses the shared guard rather than a fourth copy of the member list. This
-    // is the fireforge.json READ path: a product added to the union but not to
+    // is the fireforge.json read path: a product added to the union but not to
     // the copy that used to live here would have been silently rejected from
     // every project config.
     if (!isValidFirefoxProduct(firefoxProduct)) {
@@ -170,7 +170,7 @@ export function validateConfig(data) {
     parseExternalToolchainsBlock(rec, config);
     parseWireBlock(rec, config);
     parseLicenseField(rec, config);
-    // Marker comment — appended to lines FireForge writes into upstream files.
+    // Marker comment, appended to lines FireForge writes into upstream files.
     const markerComment = parseMarkerComment(rec.raw('markerComment'));
     if (markerComment !== undefined) {
         config.markerComment = markerComment;
@@ -185,7 +185,7 @@ export function validateConfig(data) {
     if (patchPolicyRec) {
         config.patchPolicy = parsePatchPolicyBlock(patchPolicyRec);
     }
-    // Typecheck (top-level, distinct from patchLint — see TypecheckConfig docs).
+    // Typecheck (top-level, distinct from patchLint). See TypecheckConfig docs.
     const typecheckRec = optionalConfigObject(rec, 'typecheck');
     if (typecheckRec) {
         config.typecheck = parseTypecheckBlock(typecheckRec);
@@ -400,10 +400,9 @@ function parsePatchLintBlock(rec) {
  * file. Shared between `patchLint.checkJsExtraShim` and
  * `typecheck.extraShim` so both fields reject the same absolute-path /
  * traversal / empty-string inputs with consistent error messages. The
- * file's existence is intentionally not checked here — that lives at
- * the engine layer where a missing file produces a typed runtime error
- * pointing at the actual command, rather than blocking config reads
- * for unrelated commands.
+ * file's existence is not checked here. That lives at the engine layer,
+ * where a missing file produces a typed runtime error pointing at the
+ * actual command, rather than blocking config reads for unrelated commands.
  */
 function parseShimPath(raw, label) {
     if (typeof raw !== 'string' || raw.trim() === '') {
@@ -417,7 +416,7 @@ function parseShimPath(raw, label) {
 /**
  * Validates the optional top-level `typecheck` block. Empty `projects`
  * is rejected because a silent no-op for `fireforge typecheck` is a
- * footgun — operators set the block expecting it to do something. Each
+ * footgun, since operators set the block expecting it to do something. Each
  * project path must be a contained relative path so `--project` / CLI
  * scripts can't escape the project root.
  */

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

@@ -1,11 +1,11 @@
 /**
- * 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 type { FireForgeConfig } from '../types/config.js';
 import type { JsonObject } from '../types/json.js';
@@ -28,12 +28,12 @@ export declare function configExists(root: string): Promise<boolean>;
 export declare function loadConfig(root: string): Promise<FireForgeConfig>;
 /**
  * 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`.
  *
@@ -67,9 +67,9 @@ export declare function writeConfigDocument(root: string, config: FireForgeConfi
  * 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/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';
@@ -59,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`.
  *
@@ -125,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
  */