@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/core/build-audit-transforms.js

@@ -16,7 +16,7 @@
  * implied chrome suffix is a confident match: the scorer never runs and the
  * structural-relation check is bypassed.
  *
- * Scope is intentionally narrow — only subtrees whose packaging target is
+ * Scope is narrow: only subtrees whose packaging target is
  * stable across forks. A fork that reroutes a known subtree can still win by
  * adding `(source)` annotations in its own `jar.mn`, which
  * `resolveArtifactByRegistration` consults first.
@@ -47,8 +47,8 @@ const KNOWN_TRANSFORMS = [
 ];
 /**
  * Returns the expected chrome-tree suffix for an engine-relative POSIX
- * source path when the path falls under a known transform prefix;
- * undefined otherwise.
+ * source path when the path falls under a known transform prefix.
+ * Returns undefined otherwise.
  *
  * @param source Engine-relative POSIX source path.
  */

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

@@ -3,8 +3,8 @@ import type { BuildBaseline } from './build-baseline-types.js';
 /**
  * True for the build-input manifests the build consumes but never packages
  * (`jar.mn`, `moz.build`, `moz.configure`, `Makefile.in`, `mozbuild.in`).
- * Excluded from the packaging audit and from `packageableFingerprints`;
- * fingerprinted separately as `buildInputFingerprints` so `build-prepare`
+ * Excluded from the packaging audit and from `packageableFingerprints`.
+ * Fingerprinted separately as `buildInputFingerprints` so `build-prepare`
  * can tell "dirty against HEAD" from "changed since the last successful
  * build".
  *
@@ -35,11 +35,11 @@ export interface AuditEntry {
      * updated: an artifact exists and is at least as new as the source.
      * stale:   artifact exists but is older than the source (probable packaging drop).
      * missing: no artifact with a matching basename was found anywhere under dist/.
-     * skipped: the file was not audited; `skipReason` says why.
+     * skipped: the file was not audited. `skipReason` says why.
      */
     status: 'updated' | 'stale' | 'missing' | 'skipped';
     /**
-     * Why a `skipped` entry was skipped. Present only for `skipped`; the
+     * Why a `skipped` entry was skipped. Present only for `skipped`. The
      * reasons used to exist only as verbose log strings, so the summary line
      * could report `4 missing` on a run with zero real misses and nothing in
      * the counts distinguished a structural non-input from an unregistered
@@ -68,11 +68,11 @@ export interface AuditSummary {
  */
 export declare function isPackageablePath(sourcePath: string): boolean;
 /**
- * Decides whether a source path is an XPCOM static-component manifest —
+ * Decides whether a source path is an XPCOM static-component manifest,
  * i.e. a file whose registrations are baked into the compiled
- * StaticComponents table at FULL-build time rather than packaged into
+ * StaticComponents table at full-build time rather than packaged into
  * `dist/`. This basename check is the single extension point for that
- * classification; parsing `moz.build` `XPCOM_MANIFESTS` entries to follow
+ * classification. Parsing `moz.build` `XPCOM_MANIFESTS` entries to follow
  * renamed manifests is out of scope.
  *
  * @param sourcePath Engine-relative POSIX path.
@@ -82,7 +82,7 @@ export declare function isXpcomManifestPath(sourcePath: string): boolean;
 /**
  * Runs the post-build audit. Emits per-file warnings for missing or
  * stale artifacts and a summary info line at the end. Always returns
- * the summary; never throws on audit failure (the audit itself must
+ * the summary. Never throws on audit failure (the audit itself must
  * never fail a successful build).
  * @param projectRoot Root of the project (reserved for future fork-specific rules).
  * @param engineDir Path to the engine directory.

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

@@ -13,7 +13,7 @@
  *     (git-tracked diff + workdir modifications).
  *   - For each file whose path pattern implies packaging, it resolves
  *     the expected dist artifact under obj-star/dist/binary-name-star.
- *   - A warning fires when the expected artifact is missing OR when its
+ *   - A warning fires when the expected artifact is missing or when its
  *     mtime is older than the engine source (the build was reported
  *     successful but that file's path never flowed through packaging).
  *   - False positives are acceptable at this stage: fork-specific packaging
@@ -22,9 +22,9 @@
  *
  * Routing rules:
  *   - Build inputs (jar.mn, moz.build, Makefile.in, moz.configure) are
- *     skipped; they are consumed, not packaged.
+ *     skipped. They are consumed, not packaged.
  *   - Test sources (anything under /test(s)/, browser_*.js, test_*.js)
- *     are looked up under _tests/, not dist/ — that's where mach copies
+ *     are looked up under _tests/, not dist/, which is where mach copies
  *     them.
  *   - Files inside an `if CONFIG[...]:` block in moz.build that gates
  *     off on the current host are skipped (Windows stubinstaller CSS on
@@ -61,12 +61,12 @@ const PACKAGEABLE_EXTENSIONS = [
 ];
 /** Path fragments whose contents are packaged regardless of extension. */
 const PACKAGEABLE_PATH_FRAGMENTS = ['/app/profile/', '/chrome/', '/locales/'];
-/** Directories that are build artifacts, not source — never audited. */
+/** Directories that are build artifacts, not source. Never audited. */
 const IGNORE_PATH_FRAGMENTS = ['obj-', 'node_modules/', '.git/', '.cargo/', '.mozbuild/'];
 /**
  * Basenames that are build-system inputs, not packaged artifacts. `jar.mn`
- * is consumed to produce chrome registrations; `moz.build` / `moz.configure`
- * / `Makefile.in` feed the build backend; none ship in the bundle. Auditing
+ * is consumed to produce chrome registrations. `moz.build` / `moz.configure`
+ * / `Makefile.in` feed the build backend. None ship in the bundle. Auditing
  * them guarantees a false positive on every edit, and worse, an unrelated
  * upstream `moz.build` sitting at e.g. `MyBrowser.app/Contents/moz.build`
  * gets matched as a "stale artifact" of an entirely different file.
@@ -81,8 +81,8 @@ const BUILD_INPUT_BASENAMES = new Set([
 /**
  * True for the build-input manifests the build consumes but never packages
  * (`jar.mn`, `moz.build`, `moz.configure`, `Makefile.in`, `mozbuild.in`).
- * Excluded from the packaging audit and from `packageableFingerprints`;
- * fingerprinted separately as `buildInputFingerprints` so `build-prepare`
+ * Excluded from the packaging audit and from `packageableFingerprints`.
+ * Fingerprinted separately as `buildInputFingerprints` so `build-prepare`
  * can tell "dirty against HEAD" from "changed since the last successful
  * build".
  *
@@ -123,7 +123,7 @@ export function isPackageablePath(sourcePath) {
     if (isBuildInputPath(sourcePath))
         return false;
     // `.inc.xhtml` fragments are consumed via `#include` from a registered
-    // chrome document and resolved at packaging time — they never ship as a
+    // chrome document and resolved at packaging time. They never ship as a
     // standalone packaged artifact, so auditing them flags a wired
     // `*.inc.xhtml` as "missing packaged artifact" even though `register`
     // correctly refuses to register it. Mirror the carve-out the register
@@ -141,11 +141,11 @@ export function isPackageablePath(sourcePath) {
     return false;
 }
 /**
- * Decides whether a source path is an XPCOM static-component manifest —
+ * Decides whether a source path is an XPCOM static-component manifest,
  * i.e. a file whose registrations are baked into the compiled
- * StaticComponents table at FULL-build time rather than packaged into
+ * StaticComponents table at full-build time rather than packaged into
  * `dist/`. This basename check is the single extension point for that
- * classification; parsing `moz.build` `XPCOM_MANIFESTS` entries to follow
+ * classification. Parsing `moz.build` `XPCOM_MANIFESTS` entries to follow
  * renamed manifests is out of scope.
  *
  * @param sourcePath Engine-relative POSIX path.
@@ -204,8 +204,8 @@ async function resolveTestsRoot(engineDir) {
 /**
  * Marker file the `package-tests` make target writes after copying the
  * full test-source tree under `_tests/`. Its presence is the most reliable
- * signal that test packaging has actually run for the current obj-dir —
- * plain `mach build` populates a partial `_tests/` subtree and then stops,
+ * signal that test packaging has actually run for the current obj-dir.
+ * Plain `mach build` populates a partial `_tests/` subtree and then stops,
  * so registered tests are absent even when registration is correct.
  */
 const PACKAGED_TESTS_MARKER = 'all-tests.json';
@@ -224,7 +224,7 @@ async function hasPackagedTestsMarker(testsRoot) {
 }
 /**
  * Resolves the search roots an individual source path should be looked
- * up under. Test-shaped paths get `_tests/`; everything else gets `dist/`.
+ * up under. Test-shaped paths get `_tests/`. Everything else gets `dist/`.
  */
 function searchRootsFor(source, distRoot, testsRoot) {
     if (isTestPath(source)) {
@@ -237,7 +237,7 @@ function searchRootsFor(source, distRoot, testsRoot) {
  * candidate to count as "the packaged artifact" of a source. The basename
  * always trail-matches (count 1), so a threshold of 2 requires the immediate
  * parent directory to agree too. Candidates sharing only the basename are
- * classified as missing — warning the operator to check registration —
+ * classified as missing (warning the operator to check registration)
  * rather than emitting a misleading stale comparison against an unrelated
  * file of the same name.
  *
@@ -249,21 +249,21 @@ function searchRootsFor(source, distRoot, testsRoot) {
 const MIN_TRAILING_SEGMENT_OVERLAP = 2;
 /**
  * Returns true when the chosen artifact is structurally related to the
- * source path — either its immediate parent directory trail-matches, or
+ * source path: either its immediate parent directory trail-matches, or
  * a non-generic intermediate source segment appears in the candidate
  * path (the branding-re-root signal already used by the scorer).
  *
  * Used to avoid emitting `stale` warnings that point at an unrelated
- * same-basename file picked up by the basename walker — a class of
- * warning that is worse than `missing` because it reads as "your build
- * dropped this file" when in fact the match is spurious.
+ * same-basename file picked up by the basename walker. That class of
+ * warning is worse than `missing` because it reads as "your build
+ * dropped this file" when the match is spurious.
  */
 function isConfidentMatch(source, candidate) {
     if (countTrailingSegmentMatches(source, candidate) >= MIN_TRAILING_SEGMENT_OVERLAP) {
         return true;
     }
     // The candidate is an absolute path built by `join` over a dist/ walk, so on
-    // Windows it arrives backslash-separated; a `/`-only split collapses it into
+    // Windows it arrives backslash-separated. A `/`-only split collapses it into
     // one segment and the non-generic-segment bonus can never fire.
     const sourceSegs = normalizePathSlashes(source).split('/').filter(Boolean);
     const candSegs = normalizePathSlashes(candidate).split('/').filter(Boolean);
@@ -283,24 +283,25 @@ function isConfidentMatch(source, candidate) {
  *
  * Two behaviours, both mirroring the `--expect-unmanaged` model:
  *
- *  - An admitted path is LISTED, not silenced. A carve-out nobody can see
+ *  - An admitted path is listed, not silenced. A carve-out nobody can see
  *    is how one quietly widens, so the run says which paths it admitted and
  *    on what stated reason.
- *  - An admitted path that DOES resolve to a packaged artifact is a STALE
+ *  - An admitted path that does resolve to a packaged artifact is a stale
  *    carve-out: the declaration asserts a fact about the tree that is no
  *    longer true, and suppressing on it would hide a real packaging change.
  *    That is reported as a warning, not accepted.
  *
- * A declaration matching nothing that changed this run says nothing —
+ * A declaration matching nothing that changed this run says nothing,
  * unlike `--expect-unmanaged`, whose unseen entries are reported. The
- * difference is deliberate: that is a per-invocation flag list, where an
- * unmet entry is probably a typo in the command just typed. This is a
+ * difference is intended: `--expect-unmanaged` is a per-invocation flag
+ * list, where an unmet entry is probably a typo in the command just typed.
+ * This is a
  * standing config list checked against only the files that happened to
  * change, so "not met" is the normal case and reporting it would put a
  * warning on every build.
  */
 function applyUnpackagedCarveOut(result, ctx) {
-    // Already skipped for a more specific structural reason — the carve-out
+    // Already skipped for a more specific structural reason. The carve-out
     // is redundant there and reporting it would be noise.
     if (result.status === 'skipped')
         return result;
@@ -375,7 +376,7 @@ async function auditSinglePath(source, ctx) {
         sourceMtime = sourceStat.mtimeMs;
     }
     catch {
-        // Deletion that didn't propagate — distinct class of bug, not audited yet.
+        // Deletion that didn't propagate. Distinct class of bug, not audited yet.
         return { source, artifact: undefined, status: 'skipped', skipReason: 'source-unreadable' };
     }
     const roots = searchRootsFor(source, ctx.distRoot, ctx.testsRoot);
@@ -422,7 +423,7 @@ async function auditSinglePath(source, ctx) {
  * Short-circuits the audit for sources that are registered in a jar.mn
  * but whose target path is absent from every search root. Returns the
  * miss entry when the registration lookup saw a `(source)` claim but
- * no dist candidate endswith the target; undefined otherwise.
+ * no dist candidate endswith the target. Undefined otherwise.
  */
 async function reportRegistrationMiss(engineDir, source, roots) {
     const hit = await findRegisteredTarget(engineDir, source);
@@ -447,7 +448,7 @@ async function reportRegistrationMiss(engineDir, source, roots) {
 /**
  * Renders packaged-artifact mtime classification (updated / stale / missing-
  * via-disappearance) for a resolved candidate. Shared by the registration-
- * anchored path (confident by construction) and the heuristic fallback
+ * anchored path (already confident) and the heuristic fallback
  * (which still applies the structural-relatedness check before claiming
  * `stale`).
  */
@@ -538,8 +539,9 @@ async function resolveAuditOwnership(projectRoot) {
 /**
  * Renders the ownership suffix for one audit notice: the owning patch, or
  * an explicit `unmanaged` mark. An empty map (no queue, unreadable
- * manifest) renders nothing rather than claiming everything is unmanaged —
- * "unmanaged" must mean "checked and unowned", never "could not check".
+ * manifest) renders nothing rather than claiming everything is unmanaged,
+ * since "unmanaged" must mean "checked and unowned", never "could not
+ * check".
  */
 function describeOwnership(ownersByPath, source) {
     if (ownersByPath.size === 0)
@@ -553,7 +555,7 @@ function describeOwnership(ownersByPath, source) {
 /**
  * Runs the post-build audit. Emits per-file warnings for missing or
  * stale artifacts and a summary info line at the end. Always returns
- * the summary; never throws on audit failure (the audit itself must
+ * the summary. Never throws on audit failure (the audit itself must
  * never fail a successful build).
  * @param projectRoot Root of the project (reserved for future fork-specific rules).
  * @param engineDir Path to the engine directory.
@@ -582,10 +584,10 @@ export async function auditBuildArtifacts(projectRoot, engineDir, baseline, opti
     }
     // Ownership, resolved once for the whole audit. The notices key on "was
     // touched", which on a shared checkout means any concurrent session's
-    // dirty files — so an operator gets a registration-shaped warning about a
+    // dirty files, so an operator gets a registration-shaped warning about a
     // file they never edited and has to census ownership by hand to dismiss
-    // it. FireForge already resolves this for `status --ownership`; carrying
-    // it here turns a three-line mystery into three dismissible lines.
+    // it. FireForge already resolves this for `status --ownership`. Carrying
+    // it here lets the operator dismiss those lines directly.
     const ownersByPath = await resolveAuditOwnership(projectRoot);
     const ctx = {
         engineDir,
@@ -622,7 +624,7 @@ export async function auditBuildArtifacts(projectRoot, engineDir, baseline, opti
  * Without it the summary reported one undifferentiated `skipped` count, so
  * a run that dismissed four unselected-branding files and one
  * ancestor-gated directory looked identical to one that dismissed five
- * unregistered sources — and the four false `missing` entries downstream
+ * unregistered sources, and the four false `missing` entries downstream
  * reported had no counterpart in the counts an operator could check.
  */
 function describeSkipBreakdown(summary) {

package/dist/src/core/build-baseline-types.d.ts

@@ -1,7 +1,7 @@
 /**
  * Type of the last-build baseline marker, split out of `build-baseline.ts`
  * so its consumers (`build-audit`, `build-prepare`, `test-stale-check`) can
- * import the shape without importing the I/O module — `build-baseline.ts`
+ * import the shape without importing the I/O module. `build-baseline.ts`
  * itself depends on `build-audit.ts` at runtime, and a type import back
  * into it would make the dependency graph cyclic.
  */
@@ -11,7 +11,7 @@ export interface BuildBaseline {
     /** SHA of engine HEAD at the time the build succeeded. */
     engineHeadSha: string;
     /**
-     * ISO-8601 timestamp of when the baseline was recorded. Informational —
+     * ISO-8601 timestamp of when the baseline was recorded. Informational:
      * downstream code keys off `engineHeadSha` for diffs, but the timestamp
      * helps operators reason about stale markers.
      */
@@ -46,19 +46,20 @@ export interface BuildBaseline {
      * neither re-runs `mach configure` nor escalates a pre-test build to a
      * full `mach build`. Without this the persistent worktree diff every
      * fork carries (imported patches + Furnace-applied components) made a
-     * patch-touched `jar.mn` "changed" on EVERY run, and each `test --build`
+     * patch-touched `jar.mn` "changed" on every run, and each `test --build`
      * after a full build paid the full build again.
      *
      * Refresh rules, per entry kind:
      * - backend inputs (`moz.build` & co) are refreshed on every successful
-     *   write — every baseline-writing path ran the auto-configure preflight
-     *   against the previous baseline, so a changed one was reconfigured;
-     * - `jar.mn` entries are refreshed only by a FULL build and carried
+     *   write, because every baseline-writing path ran the auto-configure
+     *   preflight against the previous baseline, so a changed one was
+     *   reconfigured.
+     * - `jar.mn` entries are refreshed only by a full build and carried
      *   forward verbatim from the previous record on a `faster` write, since
      *   `fireforge build --ui` never escalates and recording a `jar.mn` no
      *   full build has installed would hide the next escalation.
      *
-     * Absent on baselines written before the field existed; `build-prepare`
+     * Absent on baselines written before the field existed. `build-prepare`
      * then falls back to the path-only comparison (every dirty build input
      * counts as changed).
      */
@@ -66,7 +67,7 @@ export interface BuildBaseline {
     /**
      * What the packaged test runtime produced by the recorded build covers.
      *
-     * - `'full'`: the build packaged the full test set — written by
+     * - `'full'`: the build packaged the full test set, written by
      *   `fireforge build` / `build --ui` and by a path-less
      *   `fireforge test --build` (full-suite run).
      * - `string[]`: engine-relative POSIX request paths of the file/directory-
@@ -83,15 +84,15 @@ export interface BuildBaseline {
      * most one obj dir exists per project.
      *
      * Union/"shared coverage" across successive scoped builds is unsound in
-     * general — every baseline write refreshes `packageableFingerprints` for
-     * ALL dirty packageable paths, so a blind union would whitewash an
+     * general: every baseline write refreshes `packageableFingerprints` for
+     * all dirty packageable paths, so a blind union would whitewash an
      * earlier scope's edited fixtures while `obj-*`/`_tests/` still holds its
-     * stale staging. Coverage therefore REPLACES by default.
+     * stale staging. Coverage therefore replaces by default.
      *
      * The one exception is `test --build --extend-coverage`, which unions only
      * after proving the previous record's anchor still holds: same engine
      * HEAD, same {@link BuildBaseline.mozconfigHash}, and every previously
-     * fingerprinted path byte-identical — i.e. the wholesale fingerprint
+     * fingerprinted path byte-identical, i.e. the wholesale fingerprint
      * refresh is a no-op for everything the earlier scope's staging depended
      * on. Any divergence refuses fail-closed. See `src/core/coverage-extend.ts`
      * for the one boundary that guard does not cover (dirty non-packageable
@@ -100,7 +101,7 @@ export interface BuildBaseline {
     testPackagingCoverage?: TestPackagingCoverage;
     /**
      * Hex-encoded SHA-256 of `engine/mozconfig` as it stood for this build.
-     * Recorded because the mozconfig is REGENERATED from project-side
+     * Recorded because the mozconfig is regenerated from project-side
      * `configs/*.mozconfig` templates plus `fireforge.json` on every build, so
      * `engineHeadSha` does not cover it: two builds at the same engine SHA can
      * configure differently. Consumed by the `--extend-coverage` anchor, which
@@ -109,10 +110,10 @@ export interface BuildBaseline {
     mozconfigHash?: string;
     /**
      * Anchor for the compiled StaticComponents table: the engine HEAD SHA of
-     * the last FULL-coverage build plus content fingerprints of the
+     * the last full-coverage build plus content fingerprints of the
      * `components.conf` manifests that were dirty at that moment. Written
-     * fresh only on FULL-coverage baseline writes (`fireforge build`,
-     * `build --ui`, path-less `test --build`); a scoped `test --build` carries
+     * fresh only on full-coverage baseline writes (`fireforge build`,
+     * `build --ui`, path-less `test --build`). A scoped `test --build` carries
      * the previous record forward verbatim, because `mach build faster` does
      * not rebake `components.conf` registrations into the compiled table. When
      * absent, the static-components stale check degrades to "fresh".
@@ -121,13 +122,13 @@ export interface BuildBaseline {
     /**
      * Invocation shape that recorded this baseline (`'fireforge build'`,
      * `'fireforge build --ui'`, `'fireforge test --build [paths]'`).
-     * Informational — surfaced by `fireforge status --test-coverage`. Render
+     * Informational, surfaced by `fireforge status --test-coverage`. Render
      * as "unknown" when absent.
      */
     recordedBy?: string;
 }
 /**
- * State of the engine at the last FULL build, as far as compiled-in XPCOM
+ * State of the engine at the last full build, as far as compiled-in XPCOM
  * component registration is concerned. See
  * {@link BuildBaseline.staticComponentsBaseline}.
  */

package/dist/src/core/build-baseline-types.js

@@ -2,7 +2,7 @@
 /**
  * Type of the last-build baseline marker, split out of `build-baseline.ts`
  * so its consumers (`build-audit`, `build-prepare`, `test-stale-check`) can
- * import the shape without importing the I/O module — `build-baseline.ts`
+ * import the shape without importing the I/O module. `build-baseline.ts`
  * itself depends on `build-audit.ts` at runtime, and a type import back
  * into it would make the dependency graph cyclic.
  */

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

@@ -12,7 +12,7 @@
  *     recursive-make backend isn't stale.
  *
  * The marker lives under `.fireforge/last-build.json`. It is written only
- * on successful build completion; a failed build does not update it, so a
+ * on successful build completion. A failed build does not update it, so a
  * subsequent run still audits against the last known-good tree.
  */
 import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline-types.js';
@@ -21,7 +21,7 @@ import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline
  * the `jar.mn` half of {@link BuildBaseline.buildInputFingerprints} is
  * refreshed (`'full'`) or carried forward from the previous record
  * (`'faster'`). `fireforge build --ui` and a non-escalated `test --build`
- * are `'faster'`; `fireforge build` and an escalated `test --build` are
+ * are `'faster'`. `fireforge build` and an escalated `test --build` are
  * `'full'`.
  */
 export type BaselineBuildKind = 'full' | 'faster';
@@ -33,7 +33,7 @@ export type BaselineBuildKind = 'full' | 'faster';
 export declare function getBuildBaselinePath(projectRoot: string): string;
 /**
  * Reads the last-build baseline if present. Returns undefined when no
- * previous successful build has been recorded — callers must tolerate that
+ * previous successful build has been recorded. Callers must tolerate that
  * path (first build, cleaned workspace).
  * @param projectRoot - Root directory of the project
  */
@@ -54,8 +54,8 @@ export interface WriteBuildBaselineOptions {
     /**
      * The baseline this write replaces, when the caller has it. A scoped
      * (non-`'full'`) write carries its `staticComponentsBaseline` forward
-     * verbatim — `mach build faster` does not rebake `components.conf`
-     * registrations, so the last FULL build stays the honest anchor for the
+     * verbatim, because `mach build faster` does not rebake `components.conf`
+     * registrations, so the last full build stays the anchor for the
      * compiled StaticComponents table.
      */
     previousBaseline?: BuildBaseline | undefined;
@@ -66,7 +66,7 @@ export interface WriteBuildBaselineOptions {
      * coverage claim is `'full'` or absent. `'refresh'` records it even for a
      * scoped coverage claim whose implementation escalated to a full build.
      * `'carry-forward'` always keeps the previous anchor: needed by
-     * `--extend-coverage`, whose union can EVALUATE to `'full'` while the
+     * `--extend-coverage`, whose union can evaluate to `'full'` while the
      * build that produced it was still a scoped `mach build faster` that did
      * not rebake the compiled table.
      */
@@ -74,9 +74,9 @@ export interface WriteBuildBaselineOptions {
     /**
      * Which mach build produced this baseline (default `'full'`). A
      * `'faster'` write carries the previous record's `jar.mn` fingerprints
-     * forward instead of refreshing them — see
+     * forward instead of refreshing them. See
      * {@link BuildBaseline.buildInputFingerprints}. Every caller that ran
-     * `mach build faster` MUST say so, or the next pre-test build skips an
+     * `mach build faster` must say so, or the next pre-test build skips an
      * escalation no full build has honoured.
      */
     buildKind?: BaselineBuildKind | undefined;

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

@@ -13,7 +13,7 @@
  *     recursive-make backend isn't stale.
  *
  * The marker lives under `.fireforge/last-build.json`. It is written only
- * on successful build completion; a failed build does not update it, so a
+ * on successful build completion. A failed build does not update it, so a
  * subsequent run still audits against the last known-good tree.
  */
 import { readFile } from 'node:fs/promises';
@@ -47,7 +47,7 @@ export function getBuildBaselinePath(projectRoot) {
 }
 /**
  * Reads the last-build baseline if present. Returns undefined when no
- * previous successful build has been recorded — callers must tolerate that
+ * previous successful build has been recorded. Callers must tolerate that
  * path (first build, cleaned workspace).
  * @param projectRoot - Root directory of the project
  */
@@ -60,7 +60,7 @@ export async function readBuildBaseline(projectRoot) {
         return await readJson(path);
     }
     catch {
-        // A corrupt marker is equivalent to no marker — the audit/auto-configure
+        // A corrupt marker is equivalent to no marker: the audit/auto-configure
         // will treat it as "first build" rather than block on the inconsistency.
         return undefined;
     }
@@ -80,10 +80,10 @@ export async function writeBuildBaseline(options) {
         engineHeadSha = await getHead(engineDir);
     }
     catch (error) {
-        // Engine may be an unborn branch (freshly cloned + reset, or mid-import)
-        // — record an empty SHA and let downstream fall back to "no prior state"
-        // behavior. Any other git failure is bubbled up; we don't want to
-        // silently write a garbage marker.
+        // Engine may be an unborn branch (freshly cloned + reset, or
+        // mid-import). Record an empty SHA and let downstream fall back to "no
+        // prior state" behavior. Any other git failure is bubbled up, because
+        // we don't want to silently write a garbage marker.
         if (!isMissingHeadError(error)) {
             throw error;
         }
@@ -92,7 +92,7 @@ export async function writeBuildBaseline(options) {
     const buildInputFingerprints = await collectBuildInputFingerprints(engineDir, previousBaseline, buildKind);
     // A full-coverage write (and the legacy no-claim `fireforge build` shape)
     // just recompiled the StaticComponents table, so it anchors the table to
-    // the current engine state. A scoped write did not — carry the previous
+    // the current engine state. A scoped write did not, so carry the previous
     // anchor forward verbatim.
     const staticComponentsBaseline = staticComponentsHandling === 'refresh' ||
         (staticComponentsHandling === 'auto' &&
@@ -122,7 +122,7 @@ export async function writeBuildBaseline(options) {
  * or new one means the file is genuinely stale.
  *
  * Returns `undefined` on any git failure so a broken probe never corrupts
- * the on-disk baseline with `{}`; the stale-check then falls back to a
+ * the on-disk baseline with `{}`. The stale-check then falls back to a
  * path-only comparison.
  */
 async function collectPackageableFingerprints(engineDir) {
@@ -133,9 +133,9 @@ async function collectPackageableFingerprints(engineDir) {
  * ({@link isBuildInputPath}) this build consumed. Backend inputs
  * (`moz.build` & co) are always taken from the live tree: the
  * auto-configure preflight reconfigured against them before this build
- * ran. `jar.mn` entries are taken from the live tree only after a FULL
- * build; a `faster` write carries the previous record's `jar.mn` entries
- * forward verbatim, because `mach build faster` is exactly the build the
+ * ran. `jar.mn` entries are taken from the live tree only after a full
+ * build. A `faster` write carries the previous record's `jar.mn` entries
+ * forward verbatim, because `mach build faster` is the build the
  * `jar.mn` escalation exists to bypass, and recording a `jar.mn` it did
  * not install would silence the next escalation. Returns `undefined` on
  * probe failure so the field is omitted rather than written as `{}`.
@@ -159,7 +159,7 @@ async function collectBuildInputFingerprints(engineDir, previousBaseline, buildK
 /**
  * Anchor for the compiled StaticComponents table: the engine HEAD SHA of
  * this (full) build plus content fingerprints of the `components.conf`
- * manifests dirty right now — the same dirty-path probe family as
+ * manifests dirty right now, using the same dirty-path probe family as
  * {@link collectPackageableFingerprints}, filtered to XPCOM manifests.
  * Returns `undefined` on probe failure so a broken probe omits the field
  * (the static-components stale check then degrades to "fresh") rather than
@@ -211,7 +211,7 @@ async function collectDirtyFingerprints(engineDir, includePath, contextLabel) {
                     return [relPath, DELETED_FILE_FINGERPRINT];
                 }
                 // A file that disappeared between status probe and hash is
-                // expected in concurrent scenarios; non-ENOENT failures remain
+                // expected in concurrent scenarios. Non-ENOENT failures remain
                 // untrusted and are skipped without failing the whole baseline write.
                 verbose(`Build baseline: skipping ${contextLabel} for ${relPath} — ${toError(fileError).message}`);
                 return undefined;

package/dist/src/core/build-jar-escalation.d.ts

@@ -3,19 +3,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.
@@ -42,7 +42,7 @@ export interface JarEscalationDecision {
     escalate: boolean;
     /** One entry per manifest that forces the escalation. */
     causes: JarEscalationCause[];
-    /** Manifests the narrowing cleared; kept for the verbose explanation. */
+    /** Manifests the narrowing cleared. Kept for the verbose explanation. */
     cleared: string[];
 }
 /**
@@ -57,7 +57,7 @@ export interface JarEscalationDecision {
  */
 export declare function evaluateJarManifestEscalation(engineDir: string, changedPaths: readonly string[], baseline: BuildBaseline | undefined): Promise<JarEscalationDecision>;
 /**
- * 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.
  */