@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/test-harness-verdict-notes.d.ts

@@ -2,7 +2,7 @@
  * Verdict-note helpers for the harness classifier.
  *
  * Split out of `test-harness-crash.ts` (at its per-file line budget). These
- * decide the ADVISORY parenthetical on the `FIREFORGE-VERDICT:` line; none
+ * decide the advisory parenthetical on the `FIREFORGE-VERDICT:` line. None
  * of them changes a status or a reason key, which the verdict contract's
  * consumers parse.
  */
@@ -21,12 +21,12 @@ interface SummaryCountsView {
  * `Unexpected results: 0`, yet the run is still classified `test-failures`
  * on evidence lines that carry NO `TEST-UNEXPECTED-*` marker.
  *
- * `unexpected=0` printed beside `reason=test-failures` is the tell that the
- * verdict rests on pattern matching rather than on a harness result, and a
+ * `unexpected=0` printed beside `reason=test-failures` means the verdict
+ * rests on pattern matching rather than on a harness result, and a
  * reader who cannot see that spends hours attributing a red run to the
  * change under test. The note says so on the verdict line itself.
  *
- * Deliberately a NOTE and not a reclassification: a non-zero exit with no
+ * This is a note and not a reclassification: a non-zero exit with no
  * green-shaped summary is still a failing run, and inventing a new `reason`
  * would break the `FIREFORGE-VERDICT:` contract its consumers parse.
  */
@@ -36,16 +36,15 @@ export declare function truncateEvidence(line: string): string;
 /**
  * Outcome of the green-teardown belt.
  *
- * `accepted` is the pass. A rejection carries `rejectedBy` ONLY when the
- * recognized teardown noise was present — i.e. when the belt was the thing
- * that could have applied and did not. That distinction is the whole point
- * of the field: a run with no teardown traceback was never a candidate and
- * naming a "rejecting condition" for it would be noise, whereas a run that
- * DOES carry the traceback and still fails is the shape an operator
- * otherwise cannot diagnose from outside — every condition is
- * all-or-nothing, so the failing verdict looks identical whichever one
- * rejected it, and a downstream report spent a re-run and a filed-bug's
- * worth of effort guessing between them.
+ * `accepted` is the pass. A rejection carries `rejectedBy` only when the
+ * recognized teardown noise was present, i.e. when the belt was the thing
+ * that could have applied and did not. That is what the field is for: a run
+ * with no teardown traceback was never a candidate and naming a "rejecting
+ * condition" for it would be noise, whereas a run that does carry the
+ * traceback and still fails is the shape an operator otherwise cannot
+ * diagnose from outside. Every condition is all-or-nothing, so the failing
+ * verdict looks identical whichever one rejected it, and a downstream report
+ * spent a re-run and a filed-bug's worth of effort guessing between them.
  */
 export interface GreenTeardownOverride {
     accepted: boolean;

package/dist/src/core/test-harness-verdict-notes.js

@@ -3,7 +3,7 @@
  * Verdict-note helpers for the harness classifier.
  *
  * Split out of `test-harness-crash.ts` (at its per-file line budget). These
- * decide the ADVISORY parenthetical on the `FIREFORGE-VERDICT:` line; none
+ * decide the advisory parenthetical on the `FIREFORGE-VERDICT:` line. None
  * of them changes a status or a reason key, which the verdict contract's
  * consumers parse.
  */
@@ -19,12 +19,12 @@ const UNEXPECTED_MARKER = /TEST-UNEXPECTED-\w+/;
  * `Unexpected results: 0`, yet the run is still classified `test-failures`
  * on evidence lines that carry NO `TEST-UNEXPECTED-*` marker.
  *
- * `unexpected=0` printed beside `reason=test-failures` is the tell that the
- * verdict rests on pattern matching rather than on a harness result, and a
+ * `unexpected=0` printed beside `reason=test-failures` means the verdict
+ * rests on pattern matching rather than on a harness result, and a
  * reader who cannot see that spends hours attributing a red run to the
  * change under test. The note says so on the verdict line itself.
  *
- * Deliberately a NOTE and not a reclassification: a non-zero exit with no
+ * This is a note and not a reclassification: a non-zero exit with no
  * green-shaped summary is still a failing run, and inventing a new `reason`
  * would break the `FIREFORGE-VERDICT:` contract its consumers parse.
  */

package/dist/src/core/test-path-scope.d.ts

@@ -1,22 +1,22 @@
 /**
  * Directory-argument scope analysis for `fireforge test`.
  *
- * mozbuild's test resolver matches command-line paths by STRING PREFIX, so
+ * mozbuild's test resolver matches command-line paths by string prefix, so
  * `fireforge test browser/base/content/test/hominis` also runs the sibling
- * directory `browser/base/content/test/hominis-tiles` — silently, and with
+ * directory `browser/base/content/test/hominis-tiles`, silently, and with
  * no indication the scope widened.
  *
- * FireForge therefore treats a directory argument as meaning EXACTLY that
+ * FireForge therefore treats a directory argument as meaning exactly that
  * directory: {@link analyzeTestPathScopes} enumerates the test files of
- * exactly that directory and dispatches THAT explicit file list to mach,
+ * exactly that directory and dispatches that explicit file list to mach,
  * because a file list cannot prefix-match anything. Normalizing the
- * directory with a trailing `/` does NOT work — mach still sweeps in the
+ * directory with a trailing `/` does not work. Mach still sweeps in the
  * prefix-named sibling. The prefix-matching sibling directories are still
  * reported so the command layer can tell the operator what was excluded.
  *
  * FireForge already rejects non-existent paths up front, so raw
- * prefix-widening was never something an operator could invoke
- * deliberately — it only ever happened by accident.
+ * prefix-widening was never something an operator could invoke on purpose.
+ * It only ever happened by accident.
  */
 /** A sibling directory the raw mach prefix match would have included. */
 export interface SiblingPrefixMatch {
@@ -34,7 +34,7 @@ export interface TestPathScope {
      * list for a directory (mach cannot prefix-widen an explicit file
      * list), or the argument unchanged for files. A directory containing
      * no enumerable test files falls back to the trailing-`/` directory
-     * form — there is nothing to list, and mach owns the "no tests found"
+     * form: there is nothing to list, and mach owns the "no tests found"
      * failure.
      */
     dispatchPaths: string[];

package/dist/src/core/test-path-scope.js

@@ -2,22 +2,22 @@
 /**
  * Directory-argument scope analysis for `fireforge test`.
  *
- * mozbuild's test resolver matches command-line paths by STRING PREFIX, so
+ * mozbuild's test resolver matches command-line paths by string prefix, so
  * `fireforge test browser/base/content/test/hominis` also runs the sibling
- * directory `browser/base/content/test/hominis-tiles` — silently, and with
+ * directory `browser/base/content/test/hominis-tiles`, silently, and with
  * no indication the scope widened.
  *
- * FireForge therefore treats a directory argument as meaning EXACTLY that
+ * FireForge therefore treats a directory argument as meaning exactly that
  * directory: {@link analyzeTestPathScopes} enumerates the test files of
- * exactly that directory and dispatches THAT explicit file list to mach,
+ * exactly that directory and dispatches that explicit file list to mach,
  * because a file list cannot prefix-match anything. Normalizing the
- * directory with a trailing `/` does NOT work — mach still sweeps in the
+ * directory with a trailing `/` does not work. Mach still sweeps in the
  * prefix-named sibling. The prefix-matching sibling directories are still
  * reported so the command layer can tell the operator what was excluded.
  *
  * FireForge already rejects non-existent paths up front, so raw
- * prefix-widening was never something an operator could invoke
- * deliberately — it only ever happened by accident.
+ * prefix-widening was never something an operator could invoke on purpose.
+ * It only ever happened by accident.
  */
 import { readdir, stat } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
@@ -26,7 +26,7 @@ const TEST_FILE_PATTERN = /^(?:browser|test)_.*\.(?:m?js|x?html)$/;
 /**
  * Recursively enumerates test-implementation files under a directory,
  * returned engine-relative and sorted for deterministic dispatch order.
- * Returns [] when the directory cannot be read — the caller then falls
+ * Returns [] when the directory cannot be read. The caller then falls
  * back to the directory form and mach owns the failure.
  */
 async function collectTestFiles(dir, relPrefix) {
@@ -95,13 +95,13 @@ async function analyzeTestPathScope(engineDir, requestedPath) {
         }
     }
     catch {
-        // Unreadable parent: skip the sibling probe; exactness via the
+        // Unreadable parent: skip the sibling probe. Exactness via the
         // explicit file list is preserved regardless.
     }
     const testFiles = await collectTestFiles(absolute, `${stripped}/`);
     return {
         requestedPath,
-        // The explicit file list is what makes the selection exact; an empty
+        // The explicit file list is what makes the selection exact. An empty
         // enumeration falls back to the directory form.
         dispatchPaths: testFiles.length > 0 ? testFiles : [`${stripped}/`],
         isDirectory: true,
@@ -135,7 +135,7 @@ export function formatScopeNotice(scope) {
         .join(', ');
     if (scope.testFileCount === 0) {
         // Fallback dispatch: with nothing to enumerate, the raw directory form
-        // goes to mach, whose prefix matching CAN sweep the siblings in.
+        // goes to mach, whose prefix matching can sweep the siblings in.
         // Claiming exclusion here would be a lie.
         return (`${requestedDir}/ contains no enumerable test files, so the directory is passed to mach ` +
             `as-is — mach resolves paths by string prefix, which may also select: ${siblings}.`);

package/dist/src/core/test-stale-check.d.ts

@@ -1,6 +1,4 @@
-import { isXpcomManifestPath } from './build-audit.js';
 import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
-export { isXpcomManifestPath };
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
     /** True when at least one packageable engine file changed since the baseline. */
@@ -8,7 +6,7 @@ export interface StaleBuildResult {
     /**
      * Engine-relative paths that would have been packaged but appear to have
      * changed since the baseline. Sorted and deduplicated. Truncated at
-     * {@link STALE_PATHS_LIMIT} entries for rendering; consult
+     * {@link STALE_PATHS_LIMIT} entries for rendering. Consult
      * {@link StaleBuildResult.truncated} to know when to append a `(+N more)`
      * tail to the warning.
      */
@@ -20,16 +18,16 @@ export interface StaleBuildResult {
     truncated: number;
     /**
      * The baseline that anchored the diff, or undefined when no previous
-     * successful build exists. A missing baseline is treated as "not stale"
-     * — we have nothing to compare against and a warning would mislead.
+     * successful build exists. A missing baseline is treated as "not stale":
+     * we have nothing to compare against and a warning would mislead.
      */
     baseline: BuildBaseline | undefined;
 }
 /**
  * Probes the engine tree for packageable changes since the last successful
  * `fireforge build`. Returns a summary the `fireforge test` handler renders
- * as an up-front warning when `--build` was NOT passed. The probe never
- * throws; git failures and a missing baseline both degrade to `stale: false`
+ * as an up-front warning when `--build` was not passed. The probe never
+ * throws. Git failures and a missing baseline both degrade to `stale: false`
  * so a broken probe cannot block a test run.
  *
  * @param projectRoot Root directory of the project.
@@ -50,25 +48,26 @@ export declare const FULL_SUITE_REQUEST = "(entire suite)";
 /**
  * Compares the requested test paths against the packaged runtime's coverage
  * claim recorded in the baseline. Returns the requested paths the recorded
- * packaging does NOT cover — the runs that would dispatch against missing
+ * packaging does not cover: the runs that would dispatch against missing
  * `_tests/` support fixtures and hang rather than fail.
  *
  * Coverage semantics: an absent claim and `'full'` cover everything. A
  * scoped list covers a request path when the request equals a covered entry,
  * sits beneath a covered directory entry, or shares a manifest granule with
- * a covered entry ({@link toManifestGranule} — a scoped `test --build`
+ * a covered entry (see {@link toManifestGranule}: a scoped `test --build`
  * packages the whole manifest directory, so a same-manifest sibling of a
  * covered file is packaged too). Both sides are normalized to forward
  * slashes so Windows-style CLI input cannot defeat the prefix rule (baseline
  * paths are POSIX by convention). A request with no paths is a full-suite
- * run and is never covered by a scoped list — the {@link FULL_SUITE_REQUEST}
- * sentinel is returned so the refusal can name it.
+ * run and is never covered by a scoped list, so the
+ * {@link FULL_SUITE_REQUEST} sentinel is returned and the refusal can name
+ * it.
  */
 export declare function findUncoveredRequestPaths(coverage: TestPackagingCoverage | undefined, requestedPaths: readonly string[]): string[];
 /**
  * Test manifests changed since the recorded build that sit in (or above)
- * the directory of an uncovered request path — i.e. the manifests that
- * EXPLAIN why this run needs coverage the build never claimed.
+ * the directory of an uncovered request path, i.e. the manifests that
+ * explain why this run needs coverage the build never claimed.
  *
  * Best-effort: a probe failure returns an empty list, so the refusal
  * degrades to exactly its previous text rather than failing differently.
@@ -86,7 +85,7 @@ export declare function findChangedTestManifestsForPaths(engineDir: string, base
  * @param coverage - The recorded scoped coverage claim
  * @param changedManifests - Test manifests changed since the recorded
  *   build that explain an uncovered path (from
- *   {@link findChangedTestManifestsForPaths}); omitted or empty renders
+ *   {@link findChangedTestManifestsForPaths}). Omitted or empty renders
  *   nothing
  */
 export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[], changedManifests?: readonly string[]): string;
@@ -95,25 +94,25 @@ export interface StaticComponentsStaleResult {
     /** True when at least one `components.conf` genuinely diverged from the anchor. */
     stale: boolean;
     /**
-     * Engine-relative `components.conf` paths changed since the last FULL
-     * build. Sorted; NOT capped — {@link formatStaticComponentsRefusal}
+     * Engine-relative `components.conf` paths changed since the last full
+     * build. Sorted, and not capped. {@link formatStaticComponentsRefusal}
      * applies the render cap.
      */
     changedManifests: string[];
 }
 /**
- * Probes whether any `components.conf` changed since the last FULL
- * `fireforge build` — i.e. since the compiled StaticComponents table was
- * last regenerated. `components.conf` entries bake into compiled code; a
+ * Probes whether any `components.conf` changed since the last full
+ * `fireforge build`, i.e. since the compiled StaticComponents table was
+ * last regenerated. `components.conf` entries bake into compiled code. A
  * scoped `test --build` packages the file but the child process resolves the
- * OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a test
+ * old table and fails with `NS_ERROR_MALFORMED_URI` that reads as a test
  * bug.
  *
  * The diff anchors to the baseline's `staticComponentsBaseline` (the last
- * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`,
+ * full build's engine HEAD SHA), not the baseline's own `engineHeadSha`,
  * which a scoped `test --build` advances. Dirty candidates are hash-checked
  * against the anchor's fingerprints so only genuine content divergence
- * counts. No baseline or no anchor means fresh. Never throws — the probes it
+ * counts. No baseline or no anchor means fresh. Never throws: the probes it
  * composes degrade to verbose lines and empty results on git failure,
  * matching {@link checkStaleBuildForTest}.
  */
@@ -130,7 +129,7 @@ export declare function formatStaticComponentsRefusal(changedManifests: string[]
  * `fireforge import` when `components.conf` diverged from the last full
  * build. Same probe as {@link formatStaticComponentsRefusal},
  * different moment: this fires at mutation time so the operator learns a
- * full build is needed BEFORE the next gate run refuses.
+ * full build is needed before the next gate run refuses.
  */
 export declare function formatPostMutationStaticComponentsWarning(changedManifests: string[]): string;
 /**

package/dist/src/core/test-stale-check.js

@@ -5,9 +5,9 @@
  * Without this preflight, an operator who edits engine chrome / packaged
  * resources (`jar.mn` entries, `.xhtml`/`.mjs`/`.css` under chrome trees,
  * pref files) and then runs `fireforge test <path>` only discovers the build
- * is stale AFTER xpcshell / mach test starts and errors out with
- * `NS_ERROR_FILE_NOT_FOUND` against a `chrome://browser/content/…` URI —
- * which reads as a test bug, not a rebuild prompt. Scaffolding a new
+ * is stale after xpcshell / mach test starts and errors out with
+ * `NS_ERROR_FILE_NOT_FOUND` against a `chrome://browser/content/…` URI,
+ * which reads as a test bug rather than a rebuild prompt. Scaffolding a new
  * top-level chrome document plus an xpcshell test is the canonical case: the
  * test file exists, the manifests are registered, but `dist/` still holds
  * the pre-edit bundle and chrome URIs resolve to nothing.
@@ -16,7 +16,7 @@
  * baseline (`.fireforge/last-build.json`), filters to paths that imply
  * packaging, and returns a compact summary. `fireforge test` prints a
  * warning up-front so the operator sees "you edited X, Y, Z since the last
- * build — rerun with `--build` to refresh" BEFORE mach test launches.
+ * build, rerun with `--build` to refresh" before mach test launches.
  * Detection stays advisory (warn-only) because a fork that rebuilds
  * out-of-band (a separate `./mach build` invocation, an IDE plugin) can
  * legitimately have a fresh `dist/` with no FireForge-recorded baseline
@@ -24,18 +24,18 @@
  */
 import { toError } from '../utils/errors.js';
 import { verbose, warn } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
 import { hashEngineFile } from './coverage-extend.js';
 import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
-export { isXpcomManifestPath };
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
 /**
  * Probes the engine tree for packageable changes since the last successful
  * `fireforge build`. Returns a summary the `fireforge test` handler renders
- * as an up-front warning when `--build` was NOT passed. The probe never
- * throws; git failures and a missing baseline both degrade to `stale: false`
+ * as an up-front warning when `--build` was not passed. The probe never
+ * throws. Git failures and a missing baseline both degrade to `stale: false`
  * so a broken probe cannot block a test run.
  *
  * @param projectRoot Root directory of the project.
@@ -58,8 +58,8 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     // Furnace-applied components always has a persistent workdir diff against
     // HEAD, so `git diff --name-only HEAD` returns that diff on every build
     // and the stale check fires immediately after a successful one. The
-    // fingerprints capture "these files had this content when the build ran";
-    // a path stays stale only when its live hash diverges.
+    // fingerprints capture "these files had this content when the build ran".
+    // A path stays stale only when its live hash diverges.
     packageable = await dropPathsMatchingFingerprints(engineDir, packageable, baseline.packageableFingerprints);
     if (packageable.length === 0) {
         return { stale: false, changedPaths: [], truncated: 0, baseline };
@@ -89,19 +89,20 @@ export const FULL_SUITE_REQUEST = '(entire suite)';
 /**
  * Compares the requested test paths against the packaged runtime's coverage
  * claim recorded in the baseline. Returns the requested paths the recorded
- * packaging does NOT cover — the runs that would dispatch against missing
+ * packaging does not cover: the runs that would dispatch against missing
  * `_tests/` support fixtures and hang rather than fail.
  *
  * Coverage semantics: an absent claim and `'full'` cover everything. A
  * scoped list covers a request path when the request equals a covered entry,
  * sits beneath a covered directory entry, or shares a manifest granule with
- * a covered entry ({@link toManifestGranule} — a scoped `test --build`
+ * a covered entry (see {@link toManifestGranule}: a scoped `test --build`
  * packages the whole manifest directory, so a same-manifest sibling of a
  * covered file is packaged too). Both sides are normalized to forward
  * slashes so Windows-style CLI input cannot defeat the prefix rule (baseline
  * paths are POSIX by convention). A request with no paths is a full-suite
- * run and is never covered by a scoped list — the {@link FULL_SUITE_REQUEST}
- * sentinel is returned so the refusal can name it.
+ * run and is never covered by a scoped list, so the
+ * {@link FULL_SUITE_REQUEST} sentinel is returned and the refusal can name
+ * it.
  */
 export function findUncoveredRequestPaths(coverage, requestedPaths) {
     if (coverage === undefined || coverage === 'full') {
@@ -121,10 +122,10 @@ export function findUncoveredRequestPaths(coverage, requestedPaths) {
  * Maps a normalized request/coverage path to the "manifest granule" the
  * packaged runtime actually staged: an extension-bearing basename (a test
  * FILE) maps to its containing directory, a directory (no dot in the
- * basename) maps to itself. Purely lexical — the directory-as-manifest
+ * basename) maps to itself. Purely lexical: the directory-as-manifest
  * approximation holds because xpcshell/mochitest manifests live next to
  * their test files and a scoped `test --build` stages the whole manifest
- * directory into `obj-*`/`_tests/`, not single files. Caveat: a DIRECTORY
+ * directory into `obj-*`/`_tests/`, not single files. Caveat: a directory
  * whose basename contains a dot is misread as a file and mapped to its
  * parent, which widens (never narrows) the covered granule.
  */
@@ -138,11 +139,11 @@ function toManifestGranule(path) {
 }
 /** Normalizes a path for coverage comparison: forward slashes, no trailing slash. */
 function normalizeCoveragePath(path) {
-    return path.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+    return normalizePathSlashes(path.trim()).replace(/\/+$/, '');
 }
 /**
  * Formats the refusal shown when a non-`--build` run requests paths the
- * packaged runtime's scoped `test --build` coverage does not include —
+ * packaged runtime's scoped `test --build` coverage does not include. It is
  * enforced on every such run, with or without `--allow-stale-build`. Kept
  * separate from the matcher so tests can pin structure and copy
  * independently (same split as {@link formatStaleBuildWarning}).
@@ -150,7 +151,7 @@ function normalizeCoveragePath(path) {
 /**
  * Basenames of the test manifests whose entries decide what a packaged test
  * runtime stages. A manifest that gained an entry is the single most common
- * reason a run needs coverage the last build never claimed — and it is a
+ * reason a run needs coverage the last build never claimed, and it is a
  * fact FireForge already holds but never said, leaving the operator to
  * rediscover it after a correct refusal.
  */
@@ -173,8 +174,8 @@ function isTestManifestPath(path) {
 }
 /**
  * Test manifests changed since the recorded build that sit in (or above)
- * the directory of an uncovered request path — i.e. the manifests that
- * EXPLAIN why this run needs coverage the build never claimed.
+ * the directory of an uncovered request path, i.e. the manifests that
+ * explain why this run needs coverage the build never claimed.
  *
  * Best-effort: a probe failure returns an empty list, so the refusal
  * degrades to exactly its previous text rather than failing differently.
@@ -211,7 +212,7 @@ export async function findChangedTestManifestsForPaths(engineDir, baseline, unco
  * @param coverage - The recorded scoped coverage claim
  * @param changedManifests - Test manifests changed since the recorded
  *   build that explain an uncovered path (from
- *   {@link findChangedTestManifestsForPaths}); omitted or empty renders
+ *   {@link findChangedTestManifestsForPaths}). Omitted or empty renders
  *   nothing
  */
 export function formatTestCoverageRefusal(uncovered, coverage, changedManifests = []) {
@@ -222,7 +223,7 @@ export function formatTestCoverageRefusal(uncovered, coverage, changedManifests
     };
     const rebuildTargets = uncovered.filter((p) => p !== FULL_SUITE_REQUEST);
     // Name --extend-coverage here or it is undiscoverable: a scoped build
-    // REPLACES the claim, so under several concurrent sessions a peer's build
+    // replaces the claim, so under several concurrent sessions a peer's build
     // for an unrelated path erases coverage you legitimately still hold, and
     // the union that fixes it is a flag the operator has no reason to know
     // exists at the moment they need it. The anchor conditions are stated
@@ -233,7 +234,7 @@ export function formatTestCoverageRefusal(uncovered, coverage, changedManifests
     const rebuildHint = rebuildTargets.length > 0
         ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.${extendHint}`
         : 'Run "fireforge build" (or a path-less "fireforge test --build") for full coverage first.';
-    // Why THIS run needs new coverage, when a changed manifest explains it: a
+    // Why this run needs new coverage, when a changed manifest explains it: a
     // manifest that gained an entry is not covered by a build claim recorded
     // for other paths, and a browser-chrome claim never covers xpcshell.
     const manifestLine = changedManifests.length > 0
@@ -246,18 +247,18 @@ export function formatTestCoverageRefusal(uncovered, coverage, changedManifests
         '(--allow-stale-build does not bypass this check — it accepts stale content, not missing coverage.)');
 }
 /**
- * Probes whether any `components.conf` changed since the last FULL
- * `fireforge build` — i.e. since the compiled StaticComponents table was
- * last regenerated. `components.conf` entries bake into compiled code; a
+ * Probes whether any `components.conf` changed since the last full
+ * `fireforge build`, i.e. since the compiled StaticComponents table was
+ * last regenerated. `components.conf` entries bake into compiled code. A
  * scoped `test --build` packages the file but the child process resolves the
- * OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a test
+ * old table and fails with `NS_ERROR_MALFORMED_URI` that reads as a test
  * bug.
  *
  * The diff anchors to the baseline's `staticComponentsBaseline` (the last
- * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`,
+ * full build's engine HEAD SHA), not the baseline's own `engineHeadSha`,
  * which a scoped `test --build` advances. Dirty candidates are hash-checked
  * against the anchor's fingerprints so only genuine content divergence
- * counts. No baseline or no anchor means fresh. Never throws — the probes it
+ * counts. No baseline or no anchor means fresh. Never throws: the probes it
  * composes degrade to verbose lines and empty results on git failure,
  * matching {@link checkStaleBuildForTest}.
  */
@@ -300,7 +301,7 @@ export function formatStaticComponentsRefusal(changedManifests) {
  * `fireforge import` when `components.conf` diverged from the last full
  * build. Same probe as {@link formatStaticComponentsRefusal},
  * different moment: this fires at mutation time so the operator learns a
- * full build is needed BEFORE the next gate run refuses.
+ * full build is needed before the next gate run refuses.
  */
 export function formatPostMutationStaticComponentsWarning(changedManifests) {
     const head = changedManifests.slice(0, STALE_PATHS_LIMIT);

package/dist/src/core/test-stale-symlink.d.ts

@@ -5,7 +5,7 @@
  * Removes one stale xpcshell `_tests` symlink when mach reports a
  * FileExistsError during test installation.
  *
- * The guard rails are deliberately narrow: only quoted FileExistsError
+ * The guard rails are narrow: only quoted FileExistsError
  * destinations inside the active objdir's `_tests` tree are considered, and
  * only when lstat confirms the destination itself is a symlink.
  */

package/dist/src/core/test-stale-symlink.js

@@ -17,7 +17,7 @@ function isInsideDirectory(parent, candidate) {
  * Removes one stale xpcshell `_tests` symlink when mach reports a
  * FileExistsError during test installation.
  *
- * The guard rails are deliberately narrow: only quoted FileExistsError
+ * The guard rails are narrow: only quoted FileExistsError
  * destinations inside the active objdir's `_tests` tree are considered, and
  * only when lstat confirms the destination itself is a symlink.
  */

package/dist/src/core/test-stall-triage.d.ts

@@ -1,8 +1,8 @@
 /**
  * Operator-facing triage for the `timed out … with no output` / `Ran 0
- * checks` stall — the shape where the harness dies before ANY test output.
+ * checks` stall: the shape where the harness dies before any test output.
  *
- * Split out of `test-harness-crash.ts`, which CLASSIFIES runs; this module
+ * Split out of `test-harness-crash.ts`, which classifies runs. This module
  * only renders advice about one already-classified shape. Keeping the two
  * apart matters because the census below carries claims of unequal
  * evidential strength, and the rules for editing it are not the rules for
@@ -10,23 +10,23 @@
  * the output or not, while a cause in the census is an assertion about the
  * world that an operator will act on.
  *
- * Everything here is pure — the platform and the probed display state are
+ * Everything here is pure. The platform and the probed display state are
  * injected, so unit tests need no mocking.
  */
 import type { DisplaySleepState } from './display-state.js';
 import type { HarnessCrashSignature } from './test-harness-signature.js';
 /**
- * Optional hint appended to the harness-crash message when a HEADED run on
+ * Optional hint appended to the harness-crash message when a headed run on
  * macOS died at the no-output timeout.
  *
- * When `displayState` names a MEASURED display state, the hint states it as
- * fact rather than as one of three possibilities — that is the point of
- * probing: an operator staring at a bare test failure should not have to
+ * When `displayState` names a measured display state, the hint states it as
+ * fact rather than as one of three possibilities, which is what probing is
+ * for: an operator staring at a bare test failure should not have to
  * rediscover that their machine dimmed. `caffeinate` is described accurately
- * (it prevents sleep; it cannot wake an already-sleeping display), so
+ * (it prevents sleep, and cannot wake an already-sleeping display), so
  * operators are not sent to a command that could not have helped them.
  *
- * Pure — the platform and the probed state are injected so unit tests need
+ * Pure. The platform and the probed state are injected so unit tests need
  * no mocking.
  *
  * @param signature - The recognized crash shape