@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/harness-orphans.d.ts

@@ -1,29 +1,29 @@
 /**
- * Preflight census of ORPHANED test-harness helper processes.
+ * Preflight census of orphaned test-harness helper processes.
  *
  * Stopping a long mochitest run mid-flight does not necessarily take its
  * helpers with it. A downstream incident left `xpcshell` (the harness
  * httpd, pegged at 100% CPU), `pywebsocket`, `ssltunnel` and `moz-http2`
- * alive for an hour. Every subsequent run crawled — a three-second suite
- * took six minutes of wall clock and audio-start waits timed out — and
- * nothing in FireForge's output connected the slowness to the survivors.
+ * alive for an hour. Every subsequent run crawled: a three-second suite
+ * took six minutes of wall clock and audio-start waits timed out. Nothing
+ * in FireForge's output connected the slowness to the survivors.
  * The hour was spent mis-attributing it to the change under test.
  *
  * Visibility alone would have collapsed that hour, which is why the census
  * runs by default and the kill does not. Two rules keep it honest:
  *
- *  - The census runs at PREFLIGHT, before this run spawns anything, so
- *    every matching process is by construction a survivor of an earlier
- *    run. No age heuristic is needed, and none is used.
+ *  - The census runs at preflight, before this run spawns anything, so
+ *    every matching process must be a survivor of an earlier run. No age
+ *    heuristic is needed, and none is used.
  *  - A match must be anchored to a Firefox OBJDIR. `xpcshell` and
- *    `server.js` are far too generic on their own; the same rule
+ *    `server.js` are far too generic on their own. The same rule
  *    `mochitest-server-port.ts` applies to the httpd holder applies here,
- *    for the same reason — FireForge has no business reporting, let alone
+ *    for the same reason. FireForge has no business reporting, let alone
  *    terminating, a process it cannot attribute to the harness.
  *
  * `--reap-orphans` opts into termination. Without it the census is
  * report-only, exactly like the `Orphaned harness workers` doctor check
- * (which covers a DIFFERENT shape: reparented Python multiprocessing
+ * (which covers a different shape: reparented Python multiprocessing
  * workers, matched on PPID 1 and accumulated CPU time).
  */
 /** One surviving harness helper process. */
@@ -38,10 +38,10 @@ export interface OrphanedHarnessProcess {
 }
 /**
  * Scans `ps -axo pid=,ppid=,etime=,command=` output for surviving harness
- * helpers. Pure — fixture-testable without spawning anything.
+ * helpers. Pure, so it is fixture-testable without spawning anything.
  *
  * @param psOutput - Raw `ps` output
- * @param objDir - Absolute objdir of this project, when known; widens the
+ * @param objDir - Absolute objdir of this project, when known. Widens the
  *   provenance test beyond the generic `obj-…` path segment
  * @param selfPid - This process's pid, excluded so FireForge cannot report
  *   itself
@@ -57,11 +57,11 @@ export declare function formatOrphanReport(orphans: readonly OrphanedHarnessProc
  * Preflight census of surviving harness helpers, run before a test
  * dispatch.
  *
- * Best-effort by construction: a host without a usable `ps` (Windows, a
- * locked-down container) logs at verbose and runs exactly as before. It
- * never refuses a run — unlike the server-port preflight, a survivor here
- * degrades performance rather than making the run dispatch against the
- * wrong server, so the correct response is to say so loudly, not to stop.
+ * Best-effort: a host without a usable `ps` (Windows, a locked-down
+ * container) logs at verbose and runs exactly as before. It never refuses a
+ * run. Unlike the server-port preflight, a survivor here degrades
+ * performance rather than making the run dispatch against the wrong server,
+ * so the correct response is to say so loudly rather than to stop.
  *
  * @param objDir - Absolute objdir of this project, when known
  * @param options - `reap` terminates each recognized survivor (SIGTERM,

package/dist/src/core/harness-orphans.js

@@ -1,39 +1,40 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Preflight census of ORPHANED test-harness helper processes.
+ * Preflight census of orphaned test-harness helper processes.
  *
  * Stopping a long mochitest run mid-flight does not necessarily take its
  * helpers with it. A downstream incident left `xpcshell` (the harness
  * httpd, pegged at 100% CPU), `pywebsocket`, `ssltunnel` and `moz-http2`
- * alive for an hour. Every subsequent run crawled — a three-second suite
- * took six minutes of wall clock and audio-start waits timed out — and
- * nothing in FireForge's output connected the slowness to the survivors.
+ * alive for an hour. Every subsequent run crawled: a three-second suite
+ * took six minutes of wall clock and audio-start waits timed out. Nothing
+ * in FireForge's output connected the slowness to the survivors.
  * The hour was spent mis-attributing it to the change under test.
  *
  * Visibility alone would have collapsed that hour, which is why the census
  * runs by default and the kill does not. Two rules keep it honest:
  *
- *  - The census runs at PREFLIGHT, before this run spawns anything, so
- *    every matching process is by construction a survivor of an earlier
- *    run. No age heuristic is needed, and none is used.
+ *  - The census runs at preflight, before this run spawns anything, so
+ *    every matching process must be a survivor of an earlier run. No age
+ *    heuristic is needed, and none is used.
  *  - A match must be anchored to a Firefox OBJDIR. `xpcshell` and
- *    `server.js` are far too generic on their own; the same rule
+ *    `server.js` are far too generic on their own. The same rule
  *    `mochitest-server-port.ts` applies to the httpd holder applies here,
- *    for the same reason — FireForge has no business reporting, let alone
+ *    for the same reason. FireForge has no business reporting, let alone
  *    terminating, a process it cannot attribute to the harness.
  *
  * `--reap-orphans` opts into termination. Without it the census is
  * report-only, exactly like the `Orphaned harness workers` doctor check
- * (which covers a DIFFERENT shape: reparented Python multiprocessing
+ * (which covers a different shape: reparented Python multiprocessing
  * workers, matched on PPID 1 and accumulated CPU time).
  */
 import { toError } from '../utils/errors.js';
 import { info, verbose, warn } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
 import { parsePsDuration } from '../utils/ps-duration.js';
+import { sleep } from '../utils/sleep.js';
 /**
  * Harness helper executables/scripts. Every one of these is started by the
- * mochitest/xpcshell harness and is expected to die with it; none of them
+ * mochitest/xpcshell harness and is expected to die with it. None of them
  * is a thing a developer runs by hand.
  */
 const HARNESS_HELPER_PATTERN = /\b(?:xpcshell|pywebsocket\w*|websocket_server\.py|ssltunnel|moz-http2|http2_server|httpd\.js|server\.js|runtests\.py|runxpcshelltests\.py)\b/;
@@ -47,10 +48,10 @@ function isObjdirAnchored(command, objDir) {
 }
 /**
  * Scans `ps -axo pid=,ppid=,etime=,command=` output for surviving harness
- * helpers. Pure — fixture-testable without spawning anything.
+ * helpers. Pure, so it is fixture-testable without spawning anything.
  *
  * @param psOutput - Raw `ps` output
- * @param objDir - Absolute objdir of this project, when known; widens the
+ * @param objDir - Absolute objdir of this project, when known. Widens the
  *   provenance test beyond the generic `obj-…` path segment
  * @param selfPid - This process's pid, excluded so FireForge cannot report
  *   itself
@@ -93,10 +94,10 @@ const COMMAND_EXCERPT_LIMIT = 160;
  */
 export function formatOrphanReport(orphans) {
     const rows = orphans
-        .map((p) => `  PID ${String(p.pid)} (up ${p.elapsed}): ${p.command.slice(0, COMMAND_EXCERPT_LIMIT)}`)
+        .map((p) => `  PID ${p.pid} (up ${p.elapsed}): ${p.command.slice(0, COMMAND_EXCERPT_LIMIT)}`)
         .join('\n');
     const pids = orphans.map((p) => String(p.pid)).join(' ');
-    return (`${String(orphans.length)} harness helper process(es) from an EARLIER run are still alive ` +
+    return (`${orphans.length} harness helper process(es) from an EARLIER run are still alive ` +
         `(this preflight runs before the current run spawns anything, so none of these belong to ` +
         `it):\n${rows}\n` +
         `Survivors like these slow every later run without appearing anywhere in its output — a ` +
@@ -107,7 +108,7 @@ export function formatOrphanReport(orphans) {
 async function listSystemProcesses() {
     const result = await exec('ps', ['-axo', 'pid=,ppid=,etime=,command='], { timeout: 10000 });
     if (result.exitCode !== 0) {
-        throw new Error(`ps exited ${String(result.exitCode)}`);
+        throw new Error(`ps exited ${result.exitCode}`);
     }
     return result.stdout;
 }
@@ -115,11 +116,11 @@ async function listSystemProcesses() {
  * Preflight census of surviving harness helpers, run before a test
  * dispatch.
  *
- * Best-effort by construction: a host without a usable `ps` (Windows, a
- * locked-down container) logs at verbose and runs exactly as before. It
- * never refuses a run — unlike the server-port preflight, a survivor here
- * degrades performance rather than making the run dispatch against the
- * wrong server, so the correct response is to say so loudly, not to stop.
+ * Best-effort: a host without a usable `ps` (Windows, a locked-down
+ * container) logs at verbose and runs exactly as before. It never refuses a
+ * run. Unlike the server-port preflight, a survivor here degrades
+ * performance rather than making the run dispatch against the wrong server,
+ * so the correct response is to say so loudly rather than to stop.
  *
  * @param objDir - Absolute objdir of this project, when known
  * @param options - `reap` terminates each recognized survivor (SIGTERM,
@@ -150,8 +151,8 @@ export async function reportOrphanedHarnessProcesses(objDir, options = {}) {
 }
 /**
  * Terminates each census entry: SIGTERM first, then SIGKILL for anything
- * still alive. Failures are reported, never thrown — a process that exited
- * between the census and the signal is the common case, not an error.
+ * still alive. Failures are reported, never thrown. A process that exited
+ * between the census and the signal is the common case rather than an error.
  */
 async function reapOrphanedHarnessProcesses(orphans) {
     for (const orphan of orphans) {
@@ -159,13 +160,13 @@ async function reapOrphanedHarnessProcesses(orphans) {
             process.kill(orphan.pid, 'SIGTERM');
         }
         catch (error) {
-            verbose(`--reap-orphans: SIGTERM to ${String(orphan.pid)} failed (${toError(error).message}).`);
+            verbose(`--reap-orphans: SIGTERM to ${orphan.pid} failed (${toError(error).message}).`);
             continue;
         }
         // Grace period before escalating: the httpd shape in the field
         // incident ignored SIGTERM while spinning, but an ordinary helper exits
         // promptly and must not be SIGKILLed for being slow by a millisecond.
-        await new Promise((resolve) => setTimeout(resolve, REAP_GRACE_MS));
+        await sleep(REAP_GRACE_MS);
         let alive = true;
         try {
             process.kill(orphan.pid, 0);
@@ -178,9 +179,9 @@ async function reapOrphanedHarnessProcesses(orphans) {
                 process.kill(orphan.pid, 'SIGKILL');
             }
             catch (error) {
-                verbose(`--reap-orphans: SIGKILL to ${String(orphan.pid)} failed (${toError(error).message}).`);
+                verbose(`--reap-orphans: SIGKILL to ${orphan.pid} failed (${toError(error).message}).`);
             }
         }
-        info(`--reap-orphans: terminated PID ${String(orphan.pid)}.`);
+        info(`--reap-orphans: terminated PID ${orphan.pid}.`);
     }
 }

package/dist/src/core/history-log.d.ts

@@ -0,0 +1,19 @@
+import type { HistoryEntry } from './destructive.js';
+/**
+ * Appends a history entry for a mutation that has already committed, degrading
+ * to a warning when the log cannot be written.
+ *
+ * Eleven call sites across `export-flow` and the `patch` subcommands had each
+ * grown the same `try { await appendHistory(...) } catch { warn(...) }` block.
+ * The swallow is intentional: the patch files and the manifest
+ * are already on disk by the time this runs, so letting a failed log write
+ * reject would report a completed, irreversible mutation as a failure and send
+ * the operator looking for damage that is not there. Because that reasoning is
+ * easy to lose in a copy, it now lives in one place.
+ * @param patchesDir - The `patches/` directory holding the history log.
+ * @param entry - The entry to append.
+ * @param context - What just committed, rendered into
+ *   `History log append failed after <context>: <reason>`, e.g.
+ *   `patch tier committed (007-foo.patch)`.
+ */
+export declare function appendHistoryBestEffort(patchesDir: string, entry: HistoryEntry, context: string): Promise<void>;

package/dist/src/core/history-log.js

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { toError } from '../utils/errors.js';
+import { warn } from '../utils/logger.js';
+import { appendHistory } from './destructive.js';
+/**
+ * Appends a history entry for a mutation that has already committed, degrading
+ * to a warning when the log cannot be written.
+ *
+ * Eleven call sites across `export-flow` and the `patch` subcommands had each
+ * grown the same `try { await appendHistory(...) } catch { warn(...) }` block.
+ * The swallow is intentional: the patch files and the manifest
+ * are already on disk by the time this runs, so letting a failed log write
+ * reject would report a completed, irreversible mutation as a failure and send
+ * the operator looking for damage that is not there. Because that reasoning is
+ * easy to lose in a copy, it now lives in one place.
+ * @param patchesDir - The `patches/` directory holding the history log.
+ * @param entry - The entry to append.
+ * @param context - What just committed, rendered into
+ *   `History log append failed after <context>: <reason>`, e.g.
+ *   `patch tier committed (007-foo.patch)`.
+ */
+export async function appendHistoryBestEffort(patchesDir, entry, context) {
+    try {
+        await appendHistory(patchesDir, entry);
+    }
+    catch (historyError) {
+        warn(`History log append failed after ${context}: ${toError(historyError).message}`);
+    }
+}

package/dist/src/core/license-headers.d.ts

@@ -1,9 +1,9 @@
 import type { ProjectLicense } from '../types/config.js';
 /**
  * Comment style for license header formatting.
- * - `js`   — `// ...` line comments
- * - `css`  — block comments
- * - `hash` — `# ...` line comments (FTL, shell, etc.)
+ * - `js`:   `// ...` line comments
+ * - `css`:  block comments
+ * - `hash`: `# ...` line comments (FTL, shell, etc.)
  */
 export type CommentStyle = 'js' | 'css' | 'hash';
 /** Default license when fireforge.json omits the license field. */
@@ -23,19 +23,19 @@ export declare function getLicenseHeader(license: ProjectLicense, style: Comment
  *
  * For `js` files, MPL-2.0 is also accepted in the upstream Mozilla block-
  * comment form (`/* ... *\/`) used by the Firefox source tree, not just the
- * `// ` line-comment form `getLicenseHeader` emits — otherwise a new JS file
+ * `// ` line-comment form `getLicenseHeader` emits. Otherwise a new JS file
  * copied from upstream Firefox hits `missing-license-header` even with a
  * verbatim standard MPL header.
  *
  * Editor-directive block comments (`/* -*- ... -*- *\/`, `/* vim: ... *\/`)
  * leading the file are tolerated: Mozilla's canonical layout puts those on
- * lines 1–2 with the MPL header on lines 3+, which a raw `startsWith` check
+ * lines 1 and 2 with the MPL header on lines 3+, which a raw `startsWith` check
  * would miss.
  *
  * The MPL-2.0 header is additionally matched on normalized whitespace (see
  * {@link normalizeCommentHead}) so upstream files using the older Mozilla
- * wrap — breaking after "file," instead of "with this" — are accepted too;
- * only the wrap position differs, never the wording.
+ * wrap (breaking after "file," instead of "with this") are accepted too.
+ * Only the wrap position differs, never the wording.
  *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
@@ -44,18 +44,18 @@ export declare function hasAnyLicenseHeader(content: string, style: CommentStyle
 /**
  * Returns true if `content` starts with the verbatim upstream Mozilla
  * MPL-2.0 block header (`/* This Source Code Form … *\/`), optionally
- * preceded by editor-directive comments — the exact shape a JS file copied
+ * preceded by editor-directive comments, the exact shape a JS file copied
  * from the Firefox source tree carries.
  *
- * Deliberately independent of the project license: a new JS file that
+ * Independent of the project license: a new JS file that
  * legitimately keeps its upstream MPL block header is valid in an
  * EUPL/GPL/0BSD project too.
  *
  * Matching is wrap-agnostic: after the exact `startsWith` fast path, the
  * leading block comment is compared on normalized whitespace (see
- * {@link normalizeCommentHead}) so the older upstream wrap — breaking after
- * "file," instead of "with this", as `ext-browser.js` ships — passes too.
- * Only the line-break position may differ; altered wording still rejects.
+ * {@link normalizeCommentHead}) so the older upstream wrap (breaking after
+ * "file," instead of "with this", as `ext-browser.js` ships) passes too.
+ * Only the line-break position may differ. Altered wording still rejects.
  *
  * @param content - File content to check
  */
@@ -69,7 +69,7 @@ export declare function hasUpstreamMplBlockHeader(content: string): boolean;
 export declare function hasAnyLicenseHeaderAnyStyle(content: string): boolean;
 /**
  * Returns true if the first few lines of `content` contain a recognized
- * upstream license identifier string — Mozilla's MPL boilerplate, an SPDX
+ * upstream license identifier string: Mozilla's MPL boilerplate, an SPDX
  * tag, the common permissive/copyleft license names, or the CC0
  * public-domain dedication upstream test files carry.
  *
@@ -78,17 +78,18 @@ export declare function hasAnyLicenseHeaderAnyStyle(content: string): boolean;
  */
 export declare function containsUpstreamLicenseText(content: string, maxLines?: number): boolean;
 /**
- * Returns true when the head of `content` carries a recognized THIRD-PARTY
+ * Returns true when the head of `content` carries a recognized third-party
  * permissive license banner (MIT / ISC / BSD-2 / BSD-3 / Apache-2.0) or the
  * CC0 public-domain dedication, in any comment style. Used by `export` to
  * treat such files as vendored: offering to prepend the project's own
- * license header onto a byte-identity-pinned upstream bundle — or onto a
- * test file Mozilla dedicated to the public domain — would mislicense code
+ * license header onto a byte-identity-pinned upstream bundle, or onto a
+ * test file Mozilla dedicated to the public domain, would mislicense code
  * the project does not own.
  *
  * @param content  - File content to check
- * @param maxLines - Number of leading lines to inspect (default 30 — full
- *   MIT/BSD license texts run longer than the 10-line project-header scan)
+ * @param maxLines - Number of leading lines to inspect (default 30, because
+ *   full MIT/BSD license texts run longer than the 10-line project-header
+ *   scan)
  */
 export declare function hasThirdPartyPermissiveBanner(content: string, maxLines?: number): boolean;
 /**

package/dist/src/core/license-headers.js

@@ -55,7 +55,7 @@ export function getLicenseHeader(license, style) {
 }
 /**
  * Single-line `/* ... *\/` block comments containing either an Emacs
- * file-mode marker (`-*-`) or a vim modeline (`vim:`) — Mozilla's
+ * file-mode marker (`-*-`) or a vim modeline (`vim:`). These are Mozilla's
  * canonical first-line editor directives that legitimately precede the
  * license header in many Firefox source files.
  *
@@ -69,9 +69,9 @@ const EDITOR_DIRECTIVE_BLOCK_COMMENT = /^[ \t]*\/\*[^\r\n]*?(?:-\*-|\bvim:)[^\r\
  *
  * Mozilla's coding convention places editor directives like
  * `/* -*- Mode: javascript; ... -*- *\/` and `/* vim: set ... *\/` on
- * lines 1–2, with the canonical license header following on lines 3+.
+ * lines 1 and 2, with the canonical license header following on lines 3+.
  * The raw `content.startsWith(...)` check used by {@link hasAnyLicenseHeader}
- * never matches in that shape; this helper lets the caller test the
+ * never matches in that shape. This helper lets the caller test the
  * post-directive prefix as a fallback.
  *
  * @param content - File content to strip
@@ -100,15 +100,15 @@ function normalizeText(text) {
  */
 const MPL_HEADER_NORMALIZED = normalizeText(HEADER_LINES['MPL-2.0'].join(' '));
 /**
- * Extracts ONLY the leading comment span of `content` for the given
+ * Extracts only the leading comment span of `content` for the given
  * comment style and returns it whitespace-normalized:
  *
- * - `js`:   a leading run of `//` lines (markers stripped), or — when the
- *           file opens with a block comment instead — the first
- *           `/* … *\/` block;
+ * - `js`:   a leading run of `//` lines (markers stripped), or (when the
+ *           file opens with a block comment instead) the first
+ *           `/* … *\/` block.
  * - `css`:  the first `/* … *\/` block, with the ` * ` continuation-line
  *           prefixes stripped (same collapsing
- *           {@link normalizeLicenseHeadForScan} does);
+ *           {@link normalizeLicenseHeadForScan} does).
  * - `hash`: a leading run of `#` lines (markers stripped).
  *
  * A non-comment first line yields `''`. This lets callers accept a known
@@ -145,19 +145,19 @@ function normalizeCommentHead(content, style) {
  *
  * For `js` files, MPL-2.0 is also accepted in the upstream Mozilla block-
  * comment form (`/* ... *\/`) used by the Firefox source tree, not just the
- * `// ` line-comment form `getLicenseHeader` emits — otherwise a new JS file
+ * `// ` line-comment form `getLicenseHeader` emits. Otherwise a new JS file
  * copied from upstream Firefox hits `missing-license-header` even with a
  * verbatim standard MPL header.
  *
  * Editor-directive block comments (`/* -*- ... -*- *\/`, `/* vim: ... *\/`)
  * leading the file are tolerated: Mozilla's canonical layout puts those on
- * lines 1–2 with the MPL header on lines 3+, which a raw `startsWith` check
+ * lines 1 and 2 with the MPL header on lines 3+, which a raw `startsWith` check
  * would miss.
  *
  * The MPL-2.0 header is additionally matched on normalized whitespace (see
  * {@link normalizeCommentHead}) so upstream files using the older Mozilla
- * wrap — breaking after "file," instead of "with this" — are accepted too;
- * only the wrap position differs, never the wording.
+ * wrap (breaking after "file," instead of "with this") are accepted too.
+ * Only the wrap position differs, never the wording.
  *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
@@ -181,18 +181,18 @@ export function hasAnyLicenseHeader(content, style) {
 /**
  * Returns true if `content` starts with the verbatim upstream Mozilla
  * MPL-2.0 block header (`/* This Source Code Form … *\/`), optionally
- * preceded by editor-directive comments — the exact shape a JS file copied
+ * preceded by editor-directive comments, the exact shape a JS file copied
  * from the Firefox source tree carries.
  *
- * Deliberately independent of the project license: a new JS file that
+ * Independent of the project license: a new JS file that
  * legitimately keeps its upstream MPL block header is valid in an
  * EUPL/GPL/0BSD project too.
  *
  * Matching is wrap-agnostic: after the exact `startsWith` fast path, the
  * leading block comment is compared on normalized whitespace (see
- * {@link normalizeCommentHead}) so the older upstream wrap — breaking after
- * "file," instead of "with this", as `ext-browser.js` ships — passes too.
- * Only the line-break position may differ; altered wording still rejects.
+ * {@link normalizeCommentHead}) so the older upstream wrap (breaking after
+ * "file," instead of "with this", as `ext-browser.js` ships) passes too.
+ * Only the line-break position may differ. Altered wording still rejects.
  *
  * @param content - File content to check
  */
@@ -233,23 +233,23 @@ function normalizeLicenseHeadForScan(head) {
  *
  * - the prose (`Any copyright is dedicated to the Public Domain.`), which
  *   the block, `//` and `#` comment forms all reduce to after
- *   {@link normalizeLicenseHeadForScan};
+ *   {@link normalizeLicenseHeadForScan}.
  * - the dedication URL (`creativecommons.org/publicdomain/zero/1.0/`, with
- *   either scheme);
+ *   either scheme).
  * - the SPDX identifier `CC0-1.0`.
  *
- * Deliberately narrow: a bare "public domain" mention, a different Creative
+ * Narrow on purpose: a bare "public domain" mention, a different Creative
  * Commons license (`licenses/by/4.0/`, `CC-BY-4.0`) or a made-up
- * `publicdomain/zero/2.0/` is NOT a CC0 dedication and must not be
+ * `publicdomain/zero/2.0/` is not a CC0 dedication and must not be
  * accepted as one. `scanText` must already be normalized (and may be
- * lowercased — the match is case-insensitive).
+ * lowercased, since the match is case-insensitive).
  */
 function hasCc0Dedication(scanText) {
     return /dedicated to the public domain|creativecommons\.org\/publicdomain\/zero\/1\.0|spdx-license-identifier:\s*cc0-1\.0\b/i.test(scanText);
 }
 /**
  * Returns true if the first few lines of `content` contain a recognized
- * upstream license identifier string — Mozilla's MPL boilerplate, an SPDX
+ * upstream license identifier string: Mozilla's MPL boilerplate, an SPDX
  * tag, the common permissive/copyleft license names, or the CC0
  * public-domain dedication upstream test files carry.
  *
@@ -269,17 +269,18 @@ export function containsUpstreamLicenseText(content, maxLines = 10) {
     return markers.some((marker) => scanText.includes(marker)) || hasCc0Dedication(scanText);
 }
 /**
- * Returns true when the head of `content` carries a recognized THIRD-PARTY
+ * Returns true when the head of `content` carries a recognized third-party
  * permissive license banner (MIT / ISC / BSD-2 / BSD-3 / Apache-2.0) or the
  * CC0 public-domain dedication, in any comment style. Used by `export` to
  * treat such files as vendored: offering to prepend the project's own
- * license header onto a byte-identity-pinned upstream bundle — or onto a
- * test file Mozilla dedicated to the public domain — would mislicense code
+ * license header onto a byte-identity-pinned upstream bundle, or onto a
+ * test file Mozilla dedicated to the public domain, would mislicense code
  * the project does not own.
  *
  * @param content  - File content to check
- * @param maxLines - Number of leading lines to inspect (default 30 — full
- *   MIT/BSD license texts run longer than the 10-line project-header scan)
+ * @param maxLines - Number of leading lines to inspect (default 30, because
+ *   full MIT/BSD license texts run longer than the 10-line project-header
+ *   scan)
  */
 export function hasThirdPartyPermissiveBanner(content, maxLines = 30) {
     const head = content.split('\n').slice(0, maxLines).join('\n');

package/dist/src/core/mach-build-artifacts.d.ts

@@ -14,7 +14,7 @@ export interface BuildArtifactCheck {
      * Objdir name the active mozconfig declares via `MOZ_OBJDIR`, when the
      * candidates were ambiguous and the declaration did not resolve to exactly
      * one of them. Carried so the refusal can say the declaration was seen and
-     * did not help — that is itself the diagnosis.
+     * did not help. That is itself the diagnosis.
      */
     declaredObjDir?: string;
     /** Build metadata points at a different source or objdir */
@@ -28,8 +28,8 @@ export interface BuildArtifactCheck {
 /**
  * Checks if build artifacts exist in the engine directory.
  * Looks for obj-* directories with a dist subdirectory. Detection is
- * deliberately symlink-agnostic — building/running against a symlinked
- * objdir in place is the user's own arrangement; the clone path, where a
+ * symlink-agnostic on purpose: building/running against a symlinked
+ * objdir in place is the user's own arrangement. The clone path, where a
  * symlink would route writes into the original build, refuses separately
  * (`assertCloneSafeObjdir` in tree-store.ts).
  * @param engineDir - Path to the engine directory
@@ -43,15 +43,15 @@ export declare function hasBuildArtifacts(engineDir: string): Promise<BuildArtif
  * message instead of the generic build-artifacts-missing line.
  */
 export interface RunnableBundleCheck {
-    /** True when an objdir is present AND the expected binary was found under it. */
+    /** True when an objdir is present and the expected binary was found under it. */
     runnable: boolean;
-    /** Repo-relative (engine-rooted) path we probed; populated even on failure for error copy. */
+    /** Repo-relative (engine-rooted) path we probed. Populated even on failure for error copy. */
     expectedPath?: string;
 }
 /**
  * Checks whether the built browser's launchable binary exists under
  * `<engineDir>/<objDir>/dist/...`. `hasBuildArtifacts` only confirms that
- * an obj tree with a `dist/` subdir exists; a partial or in-progress build
+ * an obj tree with a `dist/` subdir exists. A partial or in-progress build
  * can satisfy that check without ever writing the executable, which is the
  * failure mode that makes `fireforge run` throw `mach run` after having
  * reported the build as usable. Separating the probes lets `run` fail fast
@@ -61,19 +61,19 @@ export interface RunnableBundleCheck {
  *
  * Platform layout:
  * - macOS: `<objDir>/dist/*.app/Contents/MacOS/<binaryName>` (the `.app`
- *   display casing can differ from `binaryName` — e.g. `MyBrowser.app` for
+ *   display casing can differ from `binaryName`, e.g. `MyBrowser.app` for
  *   binary `mybrowser`, so we enumerate the `*.app` bundles rather than
  *   compute the name.
  * - Linux: `<objDir>/dist/bin/<binaryName>`.
  * - Windows: `<objDir>/dist/bin/<binaryName>.exe`.
  *
  * Returns `runnable: false` with no `expectedPath` when the `objDir`
- * itself cannot be scanned — same degraded contract as `hasBuildArtifacts`.
+ * itself cannot be scanned. Same degraded contract as `hasBuildArtifacts`.
  *
  * @param engineDir Path to the engine directory
  * @param binaryName Lowercase binary name from `fireforge.json`
  * @param objDir The single matching `obj-*` directory name (caller
- *   resolves it; typically from `hasBuildArtifacts().objDir`)
+ *   resolves it, typically from `hasBuildArtifacts().objDir`)
  * @returns Structured check result
  */
 export declare function hasRunnableBundle(engineDir: string, binaryName: string, objDir: string): Promise<RunnableBundleCheck>;
@@ -81,7 +81,7 @@ export declare function hasRunnableBundle(engineDir: string, binaryName: string,
 export declare function buildArtifactMismatchMessage(engineDir: string, buildCheck: BuildArtifactCheck, commandName: string): string | undefined;
 /**
  * Outcome of an in-place mozinfo.json rewrite attempt. A successful rewrite
- * returns the paths written; a refused rewrite returns a human-readable
+ * returns the paths written. A refused rewrite returns a human-readable
  * reason so the build flow can surface it alongside the original mismatch
  * message before falling back to the clean-rebuild instruction.
  */
@@ -101,26 +101,26 @@ export interface MozinfoRewriteResult {
  * Safe-relocation rewriter for mozinfo.json under the active obj-* tree.
  *
  * Firefox build artefacts bake the topsrcdir into many generated files
- * (Makefiles, config.status, backend.mk, .deps dependency files — anything
+ * (Makefiles, config.status, backend.mk, .deps dependency files, anything
  * produced by `mach configure`). A fresh `mach configure` rebuilds those
  * from the top, so the rewriter only needs to patch the one file `mach`
  * reads to learn where its checkout actually lives. Once mozinfo.json
  * agrees with the on-disk layout, `mach configure` regenerates the rest.
  *
- * Safety rules — the rewrite is refused when any of them are violated:
+ * Safety rules. The rewrite is refused when any of them are violated:
  *   - `topsrcdir` and `topobjdir` must both be present and non-empty.
- *   - `topobjdir` must resolve to `<topsrcdir>/<objDir>`; a non-in-tree
+ *   - `topobjdir` must resolve to `<topsrcdir>/<objDir>`. A non-in-tree
  *     objdir means the previous workspace was configured differently,
  *     so a blind prefix-rewrite could point mach at the wrong tree.
- *   - The computed new `topobjdir` must be `<engineDir>/<objDir>`; if it
+ *   - The computed new `topobjdir` must be `<engineDir>/<objDir>`. If it
  *     is not, the objDir name itself changed and we cannot prove safety.
  *
  * When any rule trips, the caller should fall back to the clean-rebuild
- * instruction — that's always a correct (if expensive) recovery path.
+ * instruction, which is always a correct (if expensive) recovery path.
  *
  * @param engineDir Absolute path to the current engine checkout.
  * @param objDir Name of the obj-* directory to rewrite against.
- * @returns Result object; callers inspect `rewritten` and surface `reason`.
+ * @returns Result object. Callers inspect `rewritten` and surface `reason`.
  */
 export declare function attemptMozinfoRewrite(engineDir: string, objDir: string): Promise<MozinfoRewriteResult>;
 /** Per-command wording for {@link assertBuildArtifacts}. */
@@ -141,7 +141,7 @@ export interface BuildArtifactPreflightOptions {
 /**
  * Shared build-artifact preflight: rejects ambiguous multi-objdir checkouts,
  * artifacts whose metadata points at another tree, and (when
- * `requireExisting`) missing or incomplete builds — each with the actionable
+ * `requireExisting`) missing or incomplete builds, each with the actionable
  * message for that case.
  *
  * Takes an already-probed {@link BuildArtifactCheck} rather than probing
@@ -156,13 +156,13 @@ export declare function assertBuildArtifacts(engineDir: string, buildCheck: Buil
  * the four configure-generated root files (`config.status`, `backend.mk`,
  * `Makefile`, `config/autoconf.mk`) still names `forbiddenDir` (the
  * primary engine a relocated clone must never consult). Exit code 0 alone
- * proves neither — a stray MOZCONFIG/MOZ_OBJDIR can steer configure at a
+ * proves neither: a stray MOZCONFIG/MOZ_OBJDIR can steer configure at a
  * different objdir entirely. Nested Makefiles are products of the verified
- * `config.status` and are not scanned; `.deps` files are build products a
- * configure cannot regenerate and are explicitly out of scope — any
+ * `config.status` and are not scanned. `.deps` files are build products a
+ * configure cannot regenerate and are explicitly out of scope, and any
  * primary-path strings they retain are read-only staleness corrected by
  * the first in-tree rebuild. Pure checker: returns a human-readable
- * violation, or `undefined` when clean; callers own the error type and
+ * violation, or `undefined` when clean. Callers own the error type and
  * remediation copy. Unreadable metadata is itself a violation (fail
  * closed).
  */