@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/commands/setup.js

@@ -73,7 +73,7 @@ export function registerSetup(program, { withErrorHandling }) {
         .option('-f, --force', 'Overwrite existing configuration without prompting')
         // `--yes` is a plain alias here: `setup`'s only bypass is the overwrite
         // prompt, so the two flags mean exactly the same thing. Seventeen other
-        // commands spell this bypass `--yes`; accepting it means a scripted
+        // commands spell this bypass `--yes`. Accepting it means a scripted
         // sequence can use one spelling throughout.
         .option('-y, --yes', 'Alias for --force: skip the overwrite confirmation')
         .action(withErrorHandling(async (options) => {

package/dist/src/commands/source.js

@@ -10,7 +10,7 @@ function cloneRawConfig(raw) {
     if (!isObject(cloned)) {
         throw new GeneralError('Cannot update fireforge.json: config clone was not an object.');
     }
-    // A structured clone of a JSON document is itself a JSON document; the
+    // A structured clone of a JSON document is itself a JSON document. The
     // object check above is the only invariant left to establish.
     return cloned;
 }

package/dist/src/commands/status-check.d.ts

@@ -4,8 +4,8 @@
  * classification outside {patch-backed, branding, furnace}, and
  * `--fail-on <class,...>` replaces that set for finer control.
  *
- * Helper module consumed by status.ts (which sits at the max-lines budget);
- * no top-level registrar is exported and none is wanted.
+ * Helper module consumed by status.ts, which sits at the max-lines budget.
+ * No top-level registrar is exported and none is wanted.
  */
 import type { ClassifiedFile, FileClassification } from '../core/status-classify.js';
 /** Resolved `--check`/`--fail-on` policy for one status invocation. */
@@ -15,7 +15,7 @@ export interface StatusCheckPolicy {
 }
 /**
  * Resolves the enforcement policy from the raw flags: `--fail-on` implies
- * `--check` and replaces the default set; both are refused alongside the
+ * `--check` and replaces the default set. Both are refused alongside the
  * modes that skip (or elide) classification.
  */
 export declare function resolveStatusCheckPolicy(options: {

package/dist/src/commands/status-check.js

@@ -10,9 +10,9 @@ const ALL_CLASSIFICATIONS = [
 ];
 /**
  * Default `--check` policy: everything outside {patch-backed, branding,
- * furnace, binary-unsupported} fails. `binary-unsupported` is deliberately
- * excluded — an honest "cannot compare" must not keep the gate permanently
- * red; strict CI can opt in via `--fail-on binary-unsupported`.
+ * furnace, binary-unsupported} fails. `binary-unsupported` is excluded so
+ * an honest "cannot compare" does not keep the gate permanently red.
+ * Strict CI can opt in via `--fail-on binary-unsupported`.
  */
 const DEFAULT_FAIL_CLASSIFICATIONS = [
     'unmanaged',
@@ -21,7 +21,7 @@ const DEFAULT_FAIL_CLASSIFICATIONS = [
 ];
 /**
  * Resolves the enforcement policy from the raw flags: `--fail-on` implies
- * `--check` and replaces the default set; both are refused alongside the
+ * `--check` and replaces the default set. Both are refused alongside the
  * modes that skip (or elide) classification.
  */
 export function resolveStatusCheckPolicy(options) {

package/dist/src/commands/status-json.d.ts

@@ -1,31 +1,32 @@
 /**
  * `status --json` payload rendering (schemaVersion 1). Helper module
- * consumed by status.ts (which sits at the max-lines budget); no top-level
+ * consumed by status.ts (which sits at the max-lines budget). No top-level
  * registrar is exported and none is wanted.
  *
  * Two shapes share one counting pass:
- * - the full payload (`renderJsonStatus`) with the per-file `files[]` list;
+ * - the full payload (`renderJsonStatus`) with the per-file `files[]` list,
  * - the `--summary` gate payload (`renderJsonSummaryStatus`), which omits
- *   `files[]` entirely — engine-clean gates need the verdict, per-class
- *   counts, and offender names, not a payload that grows with the queue
- *   (175 KB+ on a large one).
+ *   `files[]` entirely, because engine-clean gates need the verdict,
+ *   per-class counts, and offender names, not a payload that grows with
+ *   the queue (175 KB+ on a large one).
  */
 import type { ClassifiedFile } from '../core/status-classify.js';
 import { type StatusCheckPolicy } from './status-check.js';
 import type { OwnershipJsonBlock } from './status-ownership.js';
 /**
- * Full `--json` payload: summary plus the per-file `files[]` list, and —
- * under `--include-ownership` — the additive `ownership` block.
+ * Full `--json` payload: summary plus the per-file `files[]` list, and,
+ * under `--include-ownership`, the additive `ownership` block.
  * Additive within schemaVersion 1: a consumer that does not ask for the
  * block never sees the key.
  */
 export declare function renderJsonStatus(classified: readonly ClassifiedFile[], ownership?: OwnershipJsonBlock): void;
 /**
- * Summary-only `--json --summary` payload: counts always; when the
- * `--check`/`--fail-on` policy is active, a `check` block with the active
- * fail set, the verdict, and the offending files per fail-set
- * classification (sourced from the same collector as the human `--check`
- * message, so the two views can never disagree). The absent `files[]` is
- * the mode signal within schemaVersion 1 — consumers opt in via the flag.
+ * Summary-only `--json --summary` payload. Counts are always present. When
+ * the `--check`/`--fail-on` policy is active, the payload adds a `check`
+ * block with the active fail set, the verdict, and the offending files per
+ * fail-set classification (sourced from the same collector as the human
+ * `--check` message, so the two views can never disagree). The absent
+ * `files[]` is the mode signal within schemaVersion 1. Consumers opt in via
+ * the flag.
  */
 export declare function renderJsonSummaryStatus(classified: readonly ClassifiedFile[], policy: StatusCheckPolicy, ownership?: OwnershipJsonBlock): void;

package/dist/src/commands/status-json.js

@@ -16,8 +16,8 @@ function countByClassification(classified) {
     return byClassification;
 }
 /**
- * Full `--json` payload: summary plus the per-file `files[]` list, and —
- * under `--include-ownership` — the additive `ownership` block.
+ * Full `--json` payload: summary plus the per-file `files[]` list, and,
+ * under `--include-ownership`, the additive `ownership` block.
  * Additive within schemaVersion 1: a consumer that does not ask for the
  * block never sees the key.
  */
@@ -48,12 +48,13 @@ export function renderJsonStatus(classified, ownership) {
     setStdoutSealed(true);
 }
 /**
- * Summary-only `--json --summary` payload: counts always; when the
- * `--check`/`--fail-on` policy is active, a `check` block with the active
- * fail set, the verdict, and the offending files per fail-set
- * classification (sourced from the same collector as the human `--check`
- * message, so the two views can never disagree). The absent `files[]` is
- * the mode signal within schemaVersion 1 — consumers opt in via the flag.
+ * Summary-only `--json --summary` payload. Counts are always present. When
+ * the `--check`/`--fail-on` policy is active, the payload adds a `check`
+ * block with the active fail set, the verdict, and the offending files per
+ * fail-set classification (sourced from the same collector as the human
+ * `--check` message, so the two views can never disagree). The absent
+ * `files[]` is the mode signal within schemaVersion 1. Consumers opt in via
+ * the flag.
  */
 export function renderJsonSummaryStatus(classified, policy, ownership) {
     const output = {

package/dist/src/commands/status-output.d.ts

@@ -14,10 +14,10 @@ export declare function renderUnmanagedOnly(unmanagedFiles: ClassifiedFile[], to
 /** Renders the default classified status buckets. */
 export declare function renderDefaultStatus(totalModified: number, buckets: ClassifiedBuckets, projectRoot: string, binaryName: string): Promise<void>;
 /**
- * Renders `fireforge status --test-coverage`: a READ-ONLY view of the last
+ * Renders `fireforge status --test-coverage`: a read-only view of the last
  * build baseline's test-packaging coverage. Without it, the only way to
- * learn the recorded coverage scope — which concurrent sessions sharing one
- * engine tree overwrite constantly — is to trip the out-of-coverage refusal
+ * learn the recorded coverage scope (which concurrent sessions sharing one
+ * engine tree overwrite constantly) is to trip the out-of-coverage refusal
  * on a real test run.
  */
 export declare function renderTestCoverageStatus(baseline: BuildBaseline | undefined): void;

package/dist/src/commands/status-output.js

@@ -191,10 +191,10 @@ export async function renderDefaultStatus(totalModified, buckets, projectRoot, b
     outro(parts.join(', '));
 }
 /**
- * Renders `fireforge status --test-coverage`: a READ-ONLY view of the last
+ * Renders `fireforge status --test-coverage`: a read-only view of the last
  * build baseline's test-packaging coverage. Without it, the only way to
- * learn the recorded coverage scope — which concurrent sessions sharing one
- * engine tree overwrite constantly — is to trip the out-of-coverage refusal
+ * learn the recorded coverage scope (which concurrent sessions sharing one
+ * engine tree overwrite constantly) is to trip the out-of-coverage refusal
  * on a real test run.
  */
 export function renderTestCoverageStatus(baseline) {

package/dist/src/commands/status-ownership.d.ts

@@ -1,11 +1,11 @@
 /**
  * Ownership-table assembly for `status`, split out of `status.ts` so the
  * human `--ownership` mode and the additive `ownership` block on the
- * `--json` payload build the SAME rows from the SAME scan.
+ * `--json` payload build the same rows from the same scan.
  *
  * A separate `--ownership` branch re-implements the shared scan and inlines
  * a second copy of the classification call, then discards everything but
- * each file's classification — so three back-to-back `status` invocations in
+ * each file's classification, so three back-to-back `status` invocations in
  * a gate pay three full worktree scans. Both callers hand this module the
  * already-classified files instead.
  *
@@ -29,7 +29,7 @@ export interface OwnershipJsonBlock {
 /**
  * Builds the flat path→owning-patch rows. Sources are the manifest's
  * `filesAffected`, worktree drift, and the cross-patch
- * duplicate-new-file-creation map produced by walking each patch body — the
+ * duplicate-new-file-creation map produced by walking each patch body, the
  * last being what keeps `status --ownership` aligned with `fireforge verify`
  * (see `buildOwnershipTable`'s header).
  *

package/dist/src/commands/status-ownership.js

@@ -2,11 +2,11 @@
 /**
  * Ownership-table assembly for `status`, split out of `status.ts` so the
  * human `--ownership` mode and the additive `ownership` block on the
- * `--json` payload build the SAME rows from the SAME scan.
+ * `--json` payload build the same rows from the same scan.
  *
  * A separate `--ownership` branch re-implements the shared scan and inlines
  * a second copy of the classification call, then discards everything but
- * each file's classification — so three back-to-back `status` invocations in
+ * each file's classification, so three back-to-back `status` invocations in
  * a gate pay three full worktree scans. Both callers hand this module the
  * already-classified files instead.
  *
@@ -19,7 +19,7 @@ import { pathExists } from '../utils/fs.js';
 /**
  * Builds the flat path→owning-patch rows. Sources are the manifest's
  * `filesAffected`, worktree drift, and the cross-patch
- * duplicate-new-file-creation map produced by walking each patch body — the
+ * duplicate-new-file-creation map produced by walking each patch body, the
  * last being what keeps `status --ownership` aligned with `fireforge verify`
  * (see `buildOwnershipTable`'s header).
  *

package/dist/src/commands/status.js

@@ -29,7 +29,7 @@ function renderRawStatus(files) {
     }
 }
 // Resolved lazily at first use (shared with core/git-status): this module
-// is imported by the command manifest for EVERY command, so a
+// is imported by the command manifest for every command, so a
 // module-load-time parse printed the status-specific env warning during
 // `fireforge build` etc.
 let maxUntrackedFilesPerDir;
@@ -54,8 +54,8 @@ async function expandDirectoryEntries(files, engineDir) {
             const individualFiles = await getUntrackedFilesInDir(engineDir, entry.file);
             const cap = getMaxUntrackedFilesPerDir();
             if (individualFiles.length > cap) {
-                // Recorded once here, reported once by renderTruncationBanner —
-                // the previous per-directory warn duplicated the banner's content.
+                // Recorded once here, reported once by renderTruncationBanner. The
+                // previous per-directory warn duplicated the banner's content.
                 truncations.push({
                     dir: entry.file,
                     total: individualFiles.length,
@@ -78,7 +78,7 @@ async function expandDirectoryEntries(files, engineDir) {
  * FireForge's own `writeText` produces (see
  * {@link import('../utils/fs.js').FIREFORGE_TMP_PATH_PATTERN}). Those
  * files only exist for the duration of a write + rename and should
- * never appear in `status` output; filtering them here keeps every
+ * never appear in `status` output. Filtering them here keeps every
  * status mode (default, raw, unmanaged, ownership, json) symmetric so
  * the operator never sees a `.mozconfig.fireforge-tmp-<pid>-<uuid>`
  * entry mid-write. Files named for unrelated reasons (e.g. a user's
@@ -116,11 +116,11 @@ async function scanEngineStatusFiles(engineDir, requireGitRepository) {
 }
 /**
  * Emits the `--json` payload (full or `--summary`) and applies the `--check`
- * policy, which stays the SOLE exit driver on this path.
+ * policy, which stays the only exit driver on this path.
  *
- * `--include-ownership` is a MODIFIER, not a mode: it appends an ownership
- * block without touching exit semantics, so an ownership conflict still
- * fails only the human `--ownership` mode.
+ * `--include-ownership` is a modifier rather than a mode: it appends an
+ * ownership block without touching exit semantics, so an ownership
+ * conflict still fails only the human `--ownership` mode.
  *
  * @param classified - Classified worktree entries
  * @param files - The same entries pre-classification, for ownership rows
@@ -141,8 +141,8 @@ async function renderJsonMode(classified, files, paths, options, checkPolicy) {
     runStatusCheck(classified, checkPolicy);
 }
 /**
- * Detects the "unborn HEAD" aftermath of an interrupted `fireforge download`
- * — git init succeeded but the initial Firefox source commit was never
+ * Detects the "unborn HEAD" aftermath of an interrupted `fireforge download`:
+ * git init succeeded but the initial Firefox source commit was never
  * created, so every file in engine/ reads as untracked. On a ~600 MB
  * Firefox tree this would flood the output with hundreds of thousands of
  * entries and a truncation warning, which is technically correct but not
@@ -189,7 +189,7 @@ export async function statusCommand(projectRoot, options = {}) {
     if (shouldUseMachineOutput) {
         setMachineOutputMode(true);
     }
-    // On a throw, machine mode deliberately stays ENGAGED: withErrorHandling
+    // On a throw, machine mode stays engaged: withErrorHandling
     // routes the styled error to stderr while the mode is on and resets it
     // centrally. A mid-throw restore here would put the refusal on stdout
     // after the JSON payload.
@@ -198,7 +198,7 @@ export async function statusCommand(projectRoot, options = {}) {
         setMachineOutputMode(previousMachineOutputMode);
     }
 }
-/** The status body proper; the machine-mode lifecycle lives in {@link statusCommand}. */
+/** The status body proper. The machine-mode lifecycle lives in {@link statusCommand}. */
 async function runStatusCommandBody(projectRoot, options) {
     const modeCount = [
         options.raw,
@@ -211,12 +211,12 @@ async function runStatusCommandBody(projectRoot, options) {
     if (modeCount > 1) {
         throw new GeneralError('Cannot use --raw, --unmanaged, --ownership, --test-coverage, --lock, and --json together. Pick at most one.');
     }
-    // --summary elides the files[] payload for gate consumers;
-    // it only makes sense on the JSON shape.
+    // --summary elides the files[] payload for gate consumers. It only
+    // makes sense on the JSON shape.
     if (options.summary === true && options.json !== true) {
         throw new InvalidArgumentError('--summary requires --json.', '--summary');
     }
-    // --include-ownership adds a block to the JSON payload; it is meaningless
+    // --include-ownership adds a block to the JSON payload. It is meaningless
     // on the human views, where --ownership is the mode that renders the
     // table.
     if (options.includeOwnership === true && options.json !== true) {
@@ -253,18 +253,18 @@ async function runStatusCommandBody(projectRoot, options) {
     const config = await loadConfig(projectRoot);
     // Shared envelope: see src/utils/machine-output.ts and
     // docs/machine-output.md. `status` was the only command that had one.
-    // Ownership mode is a flat file→patch table; sources are the manifest's
+    // Ownership mode is a flat file→patch table. Sources are the manifest's
     // filesAffected, any worktree drift, and the cross-patch
     // duplicate-new-file-creation map produced by walking each patch body. The
     // last is what keeps `status --ownership` aligned with `fireforge verify`
-    // — see buildOwnershipTable's header. Runs before the default classify
+    // (see buildOwnershipTable's header). Runs before the default classify
     // path so it can short-circuit without computing patch-backed state.
     if (options.ownership) {
-        // Rung 1 only, deliberately — see the note below on why this branch
-        // does not take the full assertEngineGitReady ladder.
+        // Rung 1 only. See the note below on why this branch does not take the
+        // full assertEngineGitReady ladder.
         await assertEngineExists(paths.engine);
         const manifest = await loadPatchesManifest(paths.patches);
-        // Same scan and the SAME classification pass as every other mode.
+        // The same scan and the same classification pass as every other mode.
         // This branch keeps its historical guard shape on purpose:
         // no baseline-commit assertion, and a non-git engine degrades to an
         // empty table rather than the recovery banner.
@@ -286,7 +286,7 @@ async function runStatusCommandBody(projectRoot, options) {
         return;
     }
     // Not routed through assertEngineExists: the --json contract requires a
-    // machine-readable payload on stdout BEFORE the throw, so scripted
+    // machine-readable payload on stdout before the throw, so scripted
     // consumers get a parseable refusal instead of a bare non-zero exit. The
     // message is kept identical to the helper's on purpose.
     if (!(await pathExists(paths.engine))) {
@@ -316,7 +316,7 @@ async function runStatusCommandBody(projectRoot, options) {
     }
     // `--raw` consumers parse the native `git status --porcelain` output
     // directly. On a clean tree the raw mode should produce nothing on
-    // stdout — the human "Working tree clean" banner would contaminate the
+    // stdout: the human "Working tree clean" banner would contaminate the
     // pipe. Short-circuit before the human clean-tree branch below.
     if (options.raw && files.length === 0) {
         return;

package/dist/src/commands/test-build-phase.d.ts

@@ -8,7 +8,7 @@ import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
 import type { HarnessClassification } from './test-modes.js';
 /**
  * Runs the pre-test build (or the stale-build gate when no build was
- * requested). Returns `true` when the run is COMPLETE — the `--build-only`
+ * requested). Returns `true` when the run is complete: the `--build-only`
  * union-build shape, which packages every requested path
  * (mixed harnesses legal, nothing dispatches), prints the per-harness
  * next steps, and emits the run's single `PASS` verdict.

package/dist/src/commands/test-build-phase.js

@@ -28,7 +28,7 @@ async function runPreTestBuild(options) {
         // Pass the previous baseline exactly like `fireforge build` does, so
         // auto-configure runs under the same conditions on both paths. The
         // pre-test build must never invalidate more of the objdir than a plain
-        // `mach build faster` would — a failed pre-test build followed by a full
+        // `mach build faster` would: a failed pre-test build followed by a full
         // rebuild is an hour where an incremental one would have sufficed.
         const previousBaseline = await readBuildBaseline(projectRoot);
         const preparation = await prepareBuildEnvironment(projectRoot, paths, projectConfig, {
@@ -37,8 +37,8 @@ async function runPreTestBuild(options) {
         });
         // The mozconfig half of the --extend-coverage anchor can
         // only be checked once prepareBuildEnvironment has regenerated
-        // engine/mozconfig — that is the file this build will configure with —
-        // and must still be checked before mach, so a refusal costs no build.
+        // engine/mozconfig (the file this build will configure with), and must
+        // still be checked before mach, so a refusal costs no build.
         if (extend !== undefined) {
             const mozconfigAnchor = await checkExtendMozconfigAnchor(paths.engine, previousBaseline);
             if (!mozconfigAnchor.ok) {
@@ -47,7 +47,7 @@ async function runPreTestBuild(options) {
         }
         const buildKind = preparation.fullBuildRequired ? 'full' : 'faster';
         if (preparation.fullBuildRequired) {
-            // Warning severity, not info: agent-facing output filters
+            // Warning severity rather than info: agent-facing output filters
             // keep warnings and errors only, and this is the line that explains an
             // otherwise unexplained multi-minute build.
             notice(preparation.fullBuildReason ??
@@ -60,7 +60,7 @@ async function runPreTestBuild(options) {
         // `fireforge build` / `build --ui`: in-venv resource-monitor guard plus
         // the uniform recognized-crash retry budget, with a fresh mach process
         // (and fresh guard install) per attempt. prepareBuildEnvironment runs
-        // ONCE, outside the retry loop — retries never re-run mach configure.
+        // once, outside the retry loop. Retries never re-run mach configure.
         const result = await runProtectedMachBuild(buildKind, paths.engine, {
             retries: harnessRetries,
             onRetry: (signature, nextAttempt, maxAttempts) => {
@@ -77,10 +77,10 @@ async function runPreTestBuild(options) {
             // coverage claim is scoped to the requested test paths, since a
             // file-scoped `test --build` only guarantees packaging for those
             // manifests. The previous baseline is passed through so a scoped write
-            // carries the static-components anchor forward — `mach build faster`
-            // does not rebake components.conf into the compiled table.
+            // carries the static-components anchor forward, since `mach build
+            // faster` does not rebake components.conf into the compiled table.
             try {
-                // Under --extend-coverage the claim is the UNION of the previous
+                // Under --extend-coverage the claim is the union of the previous
                 // record and this build's paths, and the static-components anchor
                 // is always carried forward: that union can evaluate to 'full'
                 // while the build behind it was a scoped `mach build faster` that
@@ -115,10 +115,10 @@ async function runPreTestBuild(options) {
     });
 }
 /**
- * `--extend-coverage` only means something for a SCOPED build: it unions
+ * `--extend-coverage` only means something for a scoped build: it unions
  * this build's paths onto the recorded claim. Without `--build`/
  * `--build-only` there is no build to extend from, and a path-less build
- * records `'full'`, which already covers everything — refusing both is more
+ * records `'full'`, which already covers everything. Refusing both is more
  * honest than silently ignoring the flag.
  */
 function assertExtendCoverageUsage(options, normalizedPaths) {
@@ -131,9 +131,9 @@ function assertExtendCoverageUsage(options, normalizedPaths) {
 }
 /**
  * Refuses `--refuse-unexported-drift` on a run that dispatches no build.
- * The flag governs the PRE-TEST build only, so accepting it without
- * `--build`/`--build-only` would arm a belt over work that never happens —
- * exactly the silent no-op this release fixes elsewhere.
+ * The flag governs the pre-test build only, so accepting it without
+ * `--build`/`--build-only` would arm a belt over work that never happens,
+ * the same silent no-op this release fixes elsewhere.
  */
 function assertRefuseUnexportedDriftUsage(options) {
     if (options.refuseUnexportedDrift !== true)
@@ -151,7 +151,7 @@ function describeBuildInvocation(extending, coverage) {
 }
 /**
  * Runs the pre-test build (or the stale-build gate when no build was
- * requested). Returns `true` when the run is COMPLETE — the `--build-only`
+ * requested). Returns `true` when the run is complete: the `--build-only`
  * union-build shape, which packages every requested path
  * (mixed harnesses legal, nothing dispatches), prints the per-harness
  * next steps, and emits the run's single `PASS` verdict.
@@ -164,8 +164,8 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
     }
     assertRefuseUnexportedDriftUsage(options);
     if (options.build || options.buildOnly) {
-        // A path-less `test --build` runs (and packages for) the full suite;
-        // a scoped invocation only vouches for the requested paths. A SCOPED
+        // A path-less `test --build` runs (and packages for) the full suite.
+        // A scoped invocation only vouches for the requested paths. A scoped
         // rebuild also cannot regenerate the compiled StaticComponents table,
         // so it runs the components.conf gate up-front (the path-less shape
         // refreshes the anchor itself and skips it).
@@ -195,7 +195,7 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
         if (options.buildOnly) {
             // Union build for mixed harnesses: the coverage claim
             // above lists every requested path, so each harness half can run
-            // build-less against this packaging. Nothing dispatches here; the
+            // build-less against this packaging. Nothing dispatches here. The
             // run still ends with exactly one verdict line.
             reportBuildOnlyCompletion(classification, normalizedPaths);
             emitPassVerdict();

package/dist/src/commands/test-diagnose.d.ts

@@ -11,7 +11,7 @@ import type { TestRunOutcome } from './test-run.js';
 /**
  * Applies the harness-run verdict for a single (non-sharded) invocation:
  * exhausted harness-crash retries and silent zero-TEST-START runs are
- * harness problems with their own messages; everything else flows into
+ * harness problems with their own messages. Everything else flows into
  * the regular non-zero-exit diagnosis chain.
  */
 export declare function finalizeSingleRunOutcome(outcome: TestRunOutcome, normalizedPaths: string[], binaryName: string, postRebuildContext: PostRebuildFailureContext | undefined, headless?: boolean): void;

package/dist/src/commands/test-diagnose.js

@@ -34,11 +34,11 @@ function buildStaleBuildMessage(postRebuild) {
         'Re-run "fireforge build --ui" or "fireforge test --build" and then retry.');
 }
 function hasStaleBuildArtifactsSignal(output) {
-    // Deliberately narrow: only fire on branding-specific resource paths that
+    // Narrow on purpose: only fire on branding-specific resource paths that
     // are always a stale-artifact symptom. A pattern that also matches
     // `resource:///modules/distribution.sys.mjs` fires on real packaging and
-    // module-resolution failures too — a fork's own `.sys.mjs` missing from
-    // the installed app dir after a successful build — pushing operators
+    // module-resolution failures too (a fork's own `.sys.mjs` missing from
+    // the installed app dir after a successful build), pushing operators
     // toward "rebuild" advice for a module-registration issue.
     return (/chrome:\/\/branding\/locale\/brand\.properties/i.test(output) ||
         /browser\/branding\/[^/\s]+\/moz\.build/i.test(output));
@@ -48,7 +48,7 @@ function hasStaleBuildArtifactsSignal(output) {
  *
  * A fork's test failing with `Failed to load
  * resource:///modules/<binary>/Store.sys.mjs` can also match the branding
- * pattern, because the harness prints a branding warning during teardown —
+ * pattern, because the harness prints a branding warning during teardown,
  * and the stale-build branch then wins by precedence, telling the operator
  * to rebuild when the real fix is to register the module in the fork's
  * `browser/modules/<binary>/moz.build`. Matching a
@@ -56,8 +56,8 @@ function hasStaleBuildArtifactsSignal(output) {
  */
 function hasForkModuleSignal(output, binaryName) {
     // `binaryName` comes from fireforge.json, and config validation bars only
-    // `..`, path separators, NUL and absolute paths — regex metacharacters get
-    // through. A hand-written character class is easy to get wrong (one that
+    // `..`, path separators, NUL and absolute paths, so regex metacharacters
+    // get through. A hand-written character class is easy to get wrong (one that
     // closes early after an escaped backslash escapes nothing), which makes
     // `my.browser` match `myXbrowser` and lets an unbalanced `(` or `[` throw
     // a SyntaxError out of the failure-diagnosis path, replacing the real test
@@ -77,8 +77,8 @@ function buildForkModuleMessage(binaryName) {
         '/<file>.sys.mjs` to add the EXTRA_JS_MODULES entry if it is missing.');
 }
 // Detects the broader xpcshell symptom where every `resource:///modules/...`
-// import fails — the signature of xpcshell running with the wrong app-dir on
-// a manifest that sets `firefox-appdir = "browser"`. Checked AFTER the
+// import fails, the signature of xpcshell running with the wrong app-dir on
+// a manifest that sets `firefox-appdir = "browser"`. Checked after the
 // stale-build signal (which matches the narrower `distribution.sys.mjs`
 // path) so the more specific diagnosis wins when both patterns apply.
 function hasXpcshellAppdirSignal(output) {
@@ -110,7 +110,7 @@ function buildHarnessSymlinkMessage() {
 }
 // Detects the `AttributeError: 'MochitestDesktop' object has no attribute
 // 'http3Server'` teardown crash. The attribute is lazy-initialized inside
-// harness code paths that presume chrome://branding resolves correctly; a
+// harness code paths that presume chrome://branding resolves correctly. A
 // missing or miswired branding registration short-circuits the setup and
 // leaves the cleanup path looking up an attribute that was never assigned.
 function hasMochitestHttp3ServerSignal(output) {
@@ -136,7 +136,7 @@ function buildMochitestHttp3ServerMessage() {
 function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted, binaryName, postRebuildContext, 
 /**
  * The classified verdict, when one was reached. Carries the failing-test
- * evidence the final throw names; every branch ABOVE that throw is a
+ * evidence the final throw names. Every branch above that throw is a
  * different diagnosis and does not use it.
  */
 verdict) {
@@ -176,7 +176,7 @@ verdict) {
     // fails to resolve, the fix really is "rebuild", not "pass --app-path".
     // The stale-build check is narrow enough not to match
     // `resource:///modules/distribution.sys.mjs` alone, which produced
-    // false-positive rebuild advice on fork-custom module-load failures; those
+    // false-positive rebuild advice on fork-custom module-load failures. Those
     // cases fall through to xpcshell-appdir, the more useful diagnosis for
     // `Failed to load resource:///modules/…`.
     if (hasStaleBuildArtifactsSignal(combinedOutput)) {
@@ -198,7 +198,7 @@ verdict) {
         info('Run "fireforge register <test-path>" to register it.');
     }
     // Last, and additive rather than a branch of its own: the run really did
-    // fail (exit code stays 5), so this only says WHICH KIND of failure it is.
+    // fail (exit code stays 5), so this only says which kind of failure it is.
     // Every branch above is a different diagnosis and outranks it.
     const changedPrefNoise = describeChangedPrefNoise(combinedOutput);
     const failureBlocks = formatFailureBlocks(verdict?.realFailureBlocks);
@@ -209,12 +209,12 @@ verdict) {
 /**
  * Applies the harness-run verdict for a single (non-sharded) invocation:
  * exhausted harness-crash retries and silent zero-TEST-START runs are
- * harness problems with their own messages; everything else flows into
+ * harness problems with their own messages. Everything else flows into
  * the regular non-zero-exit diagnosis chain.
  */
 export function finalizeSingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuildContext, headless = false) {
-    // The FIREFORGE-VERDICT line is the LAST stdout write of the run, on the
-    // pass return and every throw path alike — written raw (not via clack,
+    // The FIREFORGE-VERDICT line is the last stdout write of the run, on the
+    // pass return and every throw path alike, written raw (not via clack,
     // whose renderer drops output under non-TTY capture) so harness-verdict
     // consumers grep one stable line instead of mach internals.
     try {
@@ -248,12 +248,12 @@ function applySingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuild
     }
     if (outcome.verdict.kind === 'no-tests' && outcome.result.exitCode === 0) {
         // The silent false green: exit 0 plus a "Passed: 0"-style summary with
-        // zero TEST-START lines must fail, not pass.
+        // zero TEST-START lines must fail rather than pass.
         throw new GeneralError(buildNoTestsRanMessage(0, normalizedPaths));
     }
-    // A green-LOOKING summary rejected on crash/truncation evidence gets its
-    // own explanation instead of the generic exit-code message — the operator
-    // must see WHY the green counts were not trusted.
+    // A green-looking summary rejected on crash/truncation evidence gets its
+    // own explanation instead of the generic exit-code message, so the
+    // operator can see why the green counts were not trusted.
     if (outcome.verdict.greenSummaryRejected) {
         throw new GeneralError(buildGreenSummaryRejectedMessage(outcome.verdict.greenSummaryRejected, outcome.result.exitCode));
     }
@@ -300,7 +300,7 @@ export function diagnoseShardOutcome(outcome, path, binaryName, postRebuildConte
 function formatFailureBlocks(blocks) {
     if (blocks === undefined || blocks.length === 0)
         return undefined;
-    // The collector appends a `…(+N more …)` note when it truncated; that
+    // The collector appends a `…(+N more …)` note when it truncated. That
     // note is not a failure block, so it does not count toward the header.
     const shown = blocks.filter((block) => !block.startsWith('…(')).length;
     return `Unexpected test failures (first ${shown}):\n${blocks.join('\n\n')}`;

package/dist/src/commands/test-modes.d.ts

@@ -23,11 +23,11 @@ export interface HarnessClassification {
  * dispatch, so refusing it before spending minutes in a pre-test build
  * is strictly better. A nonexistent path classifies as
  * nonXpcshell (findNearestXpcshellManifest returns null), so classifying
- * before assertTestPathsExist is harmless — existence is still asserted
+ * before assertTestPathsExist is harmless: existence is still asserted
  * after the stale/coverage gates, preserving their precedence over
  * missing-path errors. `xpcshellOnly` (non-empty request, zero
  * nonXpcshell paths) gates the Marionette preflight and the mochitest
- * client flags; pathless runs keep the full-suite behavior.
+ * client flags. Pathless runs keep the full-suite behavior.
  */
 export declare function classifyBeforeDispatch(engineDir: string, normalizedPaths: string[], options?: {
     allowMixed?: boolean;