@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/wire-init.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * browser-init.js — init expression in onLoad().
+ * browser-init.js: init expression in onLoad().
  */
 import { join } from 'node:path';
 import MagicString from 'magic-string';
@@ -22,8 +22,8 @@ const DEFAULT_MARKER = 'FIREFORGE:';
  * Default insertion point: after the last consecutive fireforge block, or at
  * the top of the method body when there is none.
  *
- * Both callers below — the `--after`-target-not-found fallthrough and the
- * no-`--after` default — must emit identical blocks, since `browser-init.js`
+ * Both callers below (the `--after`-target-not-found fallthrough and the
+ * no-`--after` default) must emit identical blocks, since `browser-init.js`
  * is written through both paths. One implementation enforces that invariant
  * rather than merely tidying.
  */
@@ -48,14 +48,14 @@ function resolveDefaultInsertion(content, body, fireforgeBlocks) {
  *
  * `marker` is prepended (uppercased) to the generated comment line so the
  * emitted block carries the patch-lint `// <MARKER>:` signature that
- * `lintModificationComments` looks for; otherwise the first export after
+ * `lintModificationComments` looks for. Otherwise the first export after
  * `wire` trips `missing-modification-comment` on wire-generated edits.
  */
 export function addInitAST(content, expression, after, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);
     // `validateWireName` accepts both `Foo.bar` and `Foo.bar()` shapes. The
     // template below interpolates the value verbatim, so a bare property
-    // path compiles to `Foo.bar;` — a silent no-op, not a lifecycle
+    // path compiles to `Foo.bar;`, a silent no-op rather than a lifecycle
     // invocation. `coerceToCall` normalises to the function-call form so
     // the emitted block always invokes the hook the operator asked for.
     const callExpression = coerceToCall(expression);
@@ -116,7 +116,7 @@ export function addInitAST(content, expression, after, marker = DEFAULT_MARKER)
  */
 export function legacyAddInit(content, expression, after, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);
-    // See `addInitAST` for the rationale — the AST and fallback paths must
+    // See `addInitAST` for the rationale: the AST and fallback paths must
     // agree on whether the emitted block is a function call, otherwise
     // operators would see different behaviour depending on which parser
     // happened to handle their browser-init.js layout.
@@ -202,7 +202,7 @@ export async function addInitToBrowserInit(engineDir, expression, after, marker
         throw new GeneralError(`${BROWSER_INIT_JS} not found in engine`);
     }
     const content = await readText(filePath);
-    // Idempotency check — look for the coerced (call) form because that is
+    // Idempotency check: look for the coerced (call) form because that is
     // what the emitter writes. Matching against the raw input would miss a
     // bare `X.init` invocation that coercion already persisted as `X.init()`.
     const callExpression = coerceToCall(expression);

package/dist/src/core/wire-subscript.d.ts

@@ -1,5 +1,5 @@
 /**
- * browser-main.js — loadSubScript registration.
+ * browser-main.js: loadSubScript registration.
  */
 /**
  * AST-based implementation: finds the last try/catch containing

package/dist/src/core/wire-subscript.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * browser-main.js — loadSubScript registration.
+ * browser-main.js: loadSubScript registration.
  */
 import { join } from 'node:path';
 import MagicString from 'magic-string';
@@ -45,7 +45,7 @@ export function addSubscriptAST(content, name, marker = DEFAULT_MARKER) {
         indent = detectIndent(content, lastTry.start);
     }
     else {
-        // No existing loadSubScript — insert before last standalone closing brace
+        // No existing loadSubScript: insert before last standalone closing brace
         // Use line-based search to avoid matching braces inside strings/comments
         const allLines = content.split('\n');
         let lastBrace = -1;
@@ -132,7 +132,7 @@ export async function addSubscriptToBrowserMain(engineDir, name, marker = DEFAUL
         throw new GeneralError(`${BROWSER_MAIN_JS} not found in engine`);
     }
     const content = await readText(filePath);
-    // Idempotency check — include closing quote to avoid substring false positives
+    // Idempotency check. Include the closing quote to avoid substring false positives
     if (content.includes(`content/${name}.js"`)) {
         return false;
     }

package/dist/src/core/wire-utils.d.ts

@@ -12,7 +12,7 @@ export declare function validateWireName(value: string, label: string): void;
  * `Startup.init` or `Startup.init()` and get the same wired output.
  *
  * `validateWireName` accepts both shapes, but the generated block
- * interpolates the expression verbatim inside `${expression};` — so a bare
+ * interpolates the expression verbatim inside `${expression};`, so a bare
  * `Startup.init` emits `Startup.init;`, a plain property reference that
  * never invokes the lifecycle hook. The symptom is silent: `wire` reports
  * success and the browser-init block looks plausible, but the hook never
@@ -27,7 +27,7 @@ export declare function coerceToCall(expression: string): string;
  * Tracks multi-line block comment state across calls via the `inBlockComment`
  * parameter, allowing callers to iterate over lines while preserving context.
  *
- * **Regex literal heuristic:** When a `/` follows an operator or keyword-boundary
+ * Regex literal heuristic: when a `/` follows an operator or keyword-boundary
  * character (one of `= ( : , ! | & ? ; ~ ^ { [ \n + - * % < >`), it is treated
  * as a regex literal opener and characters are skipped until the closing `/`.
  * This heuristic can misfire on:
@@ -36,7 +36,7 @@ export declare function coerceToCall(expression: string): string;
  *   - Tagged template literals or unusual formatting.
  *
  * For Firefox source files this heuristic is sufficient because the AST-based
- * parser (via `withParserFallback`) is tried first; this function is only
+ * parser (via `withParserFallback`) is tried first. This function is only
  * used in the regex-based fallback path.
  *
  * @param line - A single line of source text
@@ -66,10 +66,10 @@ export declare function tokenizeXhtml(lines: string[]): XhtmlToken[];
  * advances to the line containing the opening brace.
  *
  * By default this helper is tolerant: when no `{` is found anywhere after
- * the signature, it still returns `braceIndex: methodLine` — which is the
+ * the signature, it still returns `braceIndex: methodLine`, which is the
  * correct answer when the signature and body brace live on the same line,
  * but is ambiguous when the method is abstract or truncated. Opt into
- * stricter behaviour by passing `requireBrace: true`; the function will
+ * stricter behaviour by passing `requireBrace: true`. The function will
  * return `null` instead of guessing, letting the caller surface a clean
  * {@link ParserFallbackError} rather than inserting into a wrong offset.
  *
@@ -86,10 +86,10 @@ export declare function findMethodBraceIndex(lines: string[], pattern: RegExp, o
  * Starting from `startLine`, walks lines using {@link countBraceDepth}
  * until the brace depth returns to zero (i.e., the enclosing block closes).
  *
- * Default behaviour is defensive — if the block never closes, the helper
+ * Default behaviour is defensive: if the block never closes, the helper
  * returns `startLine + 1` so a single malformed file does not stop the
  * entire fallback path. Pass `{ strict: true }` to opt into failing loudly
- * with a {@link ParserFallbackError} instead; new callers should prefer
+ * with a {@link ParserFallbackError} instead. New callers should prefer
  * strict mode so silent mis-insertions surface as the fallback refusing
  * to touch the file.
  *
@@ -120,7 +120,7 @@ export declare function computeFileBraceBalance(content: string): {
  * Round-trip guard used after a legacy fallback mutation: if the file's
  * net brace balance drifts between `before` and `after`, something went
  * wrong and the fallback is refusing to write a corrupted file. Expects
- * the delta to be exactly zero — wire fallbacks only insert whole
+ * the delta to be exactly zero, since wire fallbacks only insert whole
  * try/catch blocks, which always contribute equal opens and closes.
  *
  * @throws {@link ParserFallbackError} when the balance delta is non-zero.
@@ -136,7 +136,7 @@ export declare function findNearestTryLine(lines: string[], fromLine: number, lo
 /**
  * Scans lines starting from `startLine` for consecutive fireforge try-catch
  * blocks (identified by init comments or typeof guards) and returns the
- * line index just after the last such block — i.e., where a new block should
+ * line index just after the last such block, i.e. where a new block should
  * be inserted.
  *
  * Non-fireforge, non-blank, non-comment lines terminate the scan.

package/dist/src/core/wire-utils.js

@@ -24,7 +24,7 @@ export function validateWireName(value, label) {
  * `Startup.init` or `Startup.init()` and get the same wired output.
  *
  * `validateWireName` accepts both shapes, but the generated block
- * interpolates the expression verbatim inside `${expression};` — so a bare
+ * interpolates the expression verbatim inside `${expression};`, so a bare
  * `Startup.init` emits `Startup.init;`, a plain property reference that
  * never invokes the lifecycle hook. The symptom is silent: `wire` reports
  * success and the browser-init block looks plausible, but the hook never
@@ -41,7 +41,7 @@ export function coerceToCall(expression) {
  * Tracks multi-line block comment state across calls via the `inBlockComment`
  * parameter, allowing callers to iterate over lines while preserving context.
  *
- * **Regex literal heuristic:** When a `/` follows an operator or keyword-boundary
+ * Regex literal heuristic: when a `/` follows an operator or keyword-boundary
  * character (one of `= ( : , ! | & ? ; ~ ^ { [ \n + - * % < >`), it is treated
  * as a regex literal opener and characters are skipped until the closing `/`.
  * This heuristic can misfire on:
@@ -50,7 +50,7 @@ export function coerceToCall(expression) {
  *   - Tagged template literals or unusual formatting.
  *
  * For Firefox source files this heuristic is sufficient because the AST-based
- * parser (via `withParserFallback`) is tried first; this function is only
+ * parser (via `withParserFallback`) is tried first. This function is only
  * used in the regex-based fallback path.
  *
  * @param line - A single line of source text
@@ -119,7 +119,7 @@ function isRegexLiteralStart(line, i) {
 }
 /**
  * Scans from the opening `/` of a regex literal to its closing `/`
- * (honouring escapes), returning the index of the closing slash — or the
+ * (honouring escapes), returning the index of the closing slash, or the
  * end of the line when the literal never closes.
  */
 function scanToRegexLiteralEnd(line, start) {
@@ -159,8 +159,8 @@ export function tokenizeXhtml(lines) {
     });
 }
 // ---------------------------------------------------------------------------
-// Legacy (line-based) helpers — shared by fallback implementations in
-// wire-targets.ts.  Extracted to reduce duplication and make the brace-
+// Legacy (line-based) helpers, shared by fallback implementations in
+// the wire target modules.  Extracted to reduce duplication and make the brace-
 // walking logic independently testable.
 // ---------------------------------------------------------------------------
 /**
@@ -168,10 +168,10 @@ export function tokenizeXhtml(lines) {
  * advances to the line containing the opening brace.
  *
  * By default this helper is tolerant: when no `{` is found anywhere after
- * the signature, it still returns `braceIndex: methodLine` — which is the
+ * the signature, it still returns `braceIndex: methodLine`, which is the
  * correct answer when the signature and body brace live on the same line,
  * but is ambiguous when the method is abstract or truncated. Opt into
- * stricter behaviour by passing `requireBrace: true`; the function will
+ * stricter behaviour by passing `requireBrace: true`. The function will
  * return `null` instead of guessing, letting the caller surface a clean
  * {@link ParserFallbackError} rather than inserting into a wrong offset.
  *
@@ -179,24 +179,12 @@ export function tokenizeXhtml(lines) {
  *   found (or, under `requireBrace`, no brace follows the signature).
  */
 export function findMethodBraceIndex(lines, pattern, options) {
-    let methodLine = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (pattern.test(lines[i] ?? '')) {
-            methodLine = i;
-            break;
-        }
-    }
+    const methodLine = lines.findIndex((line) => pattern.test(line));
     if (methodLine === -1)
         return null;
-    let braceIndex = methodLine;
-    let braceFound = false;
-    for (let i = methodLine; i < lines.length; i++) {
-        if (lines[i]?.includes('{')) {
-            braceIndex = i;
-            braceFound = true;
-            break;
-        }
-    }
+    const braceOffset = lines.slice(methodLine).findIndex((line) => line.includes('{'));
+    const braceFound = braceOffset !== -1;
+    const braceIndex = braceFound ? methodLine + braceOffset : methodLine;
     if (!braceFound && options?.requireBrace) {
         return null;
     }
@@ -206,10 +194,10 @@ export function findMethodBraceIndex(lines, pattern, options) {
  * Starting from `startLine`, walks lines using {@link countBraceDepth}
  * until the brace depth returns to zero (i.e., the enclosing block closes).
  *
- * Default behaviour is defensive — if the block never closes, the helper
+ * Default behaviour is defensive: if the block never closes, the helper
  * returns `startLine + 1` so a single malformed file does not stop the
  * entire fallback path. Pass `{ strict: true }` to opt into failing loudly
- * with a {@link ParserFallbackError} instead; new callers should prefer
+ * with a {@link ParserFallbackError} instead. New callers should prefer
  * strict mode so silent mis-insertions surface as the fallback refusing
  * to touch the file.
  *
@@ -259,7 +247,7 @@ export function computeFileBraceBalance(content) {
  * Round-trip guard used after a legacy fallback mutation: if the file's
  * net brace balance drifts between `before` and `after`, something went
  * wrong and the fallback is refusing to write a corrupted file. Expects
- * the delta to be exactly zero — wire fallbacks only insert whole
+ * the delta to be exactly zero, since wire fallbacks only insert whole
  * try/catch blocks, which always contribute equal opens and closes.
  *
  * @throws {@link ParserFallbackError} when the balance delta is non-zero.
@@ -295,7 +283,7 @@ const FIREFORGE_BLOCK_PATTERN = /\/\/\s*.*init\s*—|typeof\s+\w+\s*!==\s*"undef
 /**
  * Scans lines starting from `startLine` for consecutive fireforge try-catch
  * blocks (identified by init comments or typeof guards) and returns the
- * line index just after the last such block — i.e., where a new block should
+ * line index just after the last such block, i.e. where a new block should
  * be inserted.
  *
  * Non-fireforge, non-blank, non-comment lines terminate the scan.

package/dist/src/core/xpcshell-appdir.d.ts

@@ -9,7 +9,7 @@
  * override as `mozInfo["appname"] + "-appdir"`. On a stock Firefox build the
  * key is `firefox-appdir`, so the very common `firefox-appdir = "browser"`
  * directive is honoured. On a rebranded fork (appname=`mybrowser`) the
- * harness looks for `mybrowser-appdir` — the literal `firefox-appdir` line
+ * harness looks for `mybrowser-appdir`, so the literal `firefox-appdir` line
  * is silently ignored, `appPath` falls back to `xrePath`, and every
  * `resource:///modules/…` import throws `Failed to load
  * resource:///modules/<name>.sys.mjs` because xpcshell resolves the
@@ -21,7 +21,7 @@
  *    `xpcshell.toml`. If none exists, the test is not an xpcshell test and
  *    there is nothing to inject.
  * 2. Read the manifest's `[DEFAULT]` section. Look for `<appname>-appdir`
- *    first — if present, the harness already finds it. Fall back to
+ *    first. If present, the harness already finds it. Fall back to
  *    `firefox-appdir`. This ordering matches upstream precedence and avoids
  *    overriding an operator who already migrated.
  * 3. If only `firefox-appdir` is present and `appname != "firefox"`, compute
@@ -30,7 +30,7 @@
  *    `dist/<bundle>.app/Contents/Resources/<value>` for the macOS packaged
  *    layout) and return it as the value to pass to `--app-path`.
  * 4. If multiple test paths disagree on the resolved value, refuse injection
- *    and return null — the operator can drop down to `--mach-arg`.
+ *    and return null. The operator can drop down to `--mach-arg`.
  *
  * Operator escape hatch: `--mach-arg=--app-path=…` always wins (handled in
  * test.ts, which skips injection when `--app-path=` already appears in the
@@ -60,7 +60,7 @@ export interface AppdirResolveResult {
  *  - Single- or double-quoted values
  *  - Whitespace either side of `=`
  *  - Continuation comments (`#` or `;`) at the end of the line
- *  - Bare unquoted bareword values (e.g. `firefox-appdir = browser`) — some
+ *  - Bare unquoted bareword values (e.g. `firefox-appdir = browser`). Some
  *    operators omit the quotes and the harness honours either form.
  *
  * Returns `undefined` when the key is absent or sits outside `[DEFAULT]`.
@@ -74,10 +74,10 @@ export declare function parseAppdirFromToml(tomlText: string, key: string): {
  * returns the absolute path of the first sibling `xpcshell.toml` found.
  * Stops at `engineDir` (inclusive) and returns null on miss.
  *
- * Special-cases `startPath` itself when it already ends with `xpcshell.toml`
- * — operators sometimes pass a manifest path directly.
+ * Special-cases `startPath` itself when it already ends with
+ * `xpcshell.toml`, since operators sometimes pass a manifest path directly.
  *
- * When `startPath` is a DIRECTORY, the walk starts at the directory itself
+ * When `startPath` is a directory, the walk starts at the directory itself
  * (checking `<dir>/xpcshell.toml` first) rather than at its parent.
  * Starting at the parent misses a directory's own manifest, so
  * `fireforge test <dir>` classifies it non-xpcshell and dispatches to the
@@ -86,31 +86,31 @@ export declare function parseAppdirFromToml(tomlText: string, key: string): {
 export declare function findNearestXpcshellManifest(engineDir: string, startPath: string): Promise<string | null>;
 /**
  * Reads `<objDir>/mozinfo.json` for the active app name. Returns
- * `"firefox"` when mozinfo cannot be read or the field is missing — that
+ * `"firefox"` when mozinfo cannot be read or the field is missing. That
  * is the safe default because it matches stock Firefox behaviour and
  * means the resolver will not inject anything (the manifest's
- * `firefox-appdir` value WILL be honoured by the upstream harness when
+ * `firefox-appdir` value is honoured by the upstream harness when
  * appname is firefox).
  */
 export declare function readMozinfoAppname(objDirPath: string): Promise<string>;
 /**
  * Probes the obj-dir's `dist/` subtree for the absolute path the harness
  * would have computed if the manifest key had been honoured. Returns null
- * when no candidate exists — better to skip injection silently than to point
+ * when no candidate exists: better to skip injection silently than to point
  * the harness at a path that does not exist, which fails with a different
  * error than the original symptom and confuses triage.
  *
  * Probe order differs by host platform:
  *
- * - **macOS (`darwin`)**: prefer
- *   `<objDir>/dist/<App>.app/Contents/Resources/<value>` FIRST, then fall
+ * - macOS (`darwin`): prefer
+ *   `<objDir>/dist/<App>.app/Contents/Resources/<value>` first, then fall
  *   back to `<objDir>/dist/bin/<value>`. On macOS `dist/bin` is symlinked to
- *   `dist/<App>.app/Contents/MacOS/` (the *binaries* directory), so
- *   `dist/bin/browser` resolves to `<App>.app/Contents/MacOS/browser/` —
- *   NOT where `resource:///modules/` is rooted. Injecting that path looks
- *   successful in the log but points at a directory with no modules tree, so
- *   every `resource:///modules/…` import still throws.
- * - **non-macOS**: `dist/bin/<value>` first,
+ *   `dist/<App>.app/Contents/MacOS/` (the binaries directory), so
+ *   `dist/bin/browser` resolves to `<App>.app/Contents/MacOS/browser/`,
+ *   which is not where `resource:///modules/` is rooted. Injecting that path
+ *   looks successful in the log but points at a directory with no modules
+ *   tree, so every `resource:///modules/…` import still throws.
+ * - non-macOS: `dist/bin/<value>` first,
  *   `.app/Contents/Resources/<value>` as fallback.
  *
  * On both platforms the final `.app` fallback iterates every `*.app` entry
@@ -121,7 +121,7 @@ export declare function resolveAbsoluteAppPath(objDirAbs: string, relativeAppdir
  * Outcome carrier for {@link resolveXpcshellAppdirArg}. Distinguishes the
  * three "did nothing" cases so callers can shape diagnostics:
  *  - `none`: no manifest under any test path needs injection.
- *  - `mismatch`: at least two manifests resolved to different values; we
+ *  - `mismatch`: at least two manifests resolved to different values. We
  *    refuse to guess which one the operator meant.
  *  - `unresolved`: the manifest asks for `firefox-appdir = "<value>"` but
  *    no `dist/` candidate exists for that value.
@@ -143,7 +143,7 @@ export type XpcshellAppdirOutcome = {
 /**
  * Top-level resolver. Walks every test path, reads the nearest
  * xpcshell.toml, and returns the single absolute path to inject (or a
- * structured "no injection" outcome). Never throws — every fs / parse
+ * structured "no injection" outcome). Never throws: every fs / parse
  * error is folded into a `none` outcome so the test command always falls
  * through to the diagnostic hint instead of dying inside a helper.
  */

package/dist/src/core/xpcshell-appdir.js

@@ -10,7 +10,7 @@
  * override as `mozInfo["appname"] + "-appdir"`. On a stock Firefox build the
  * key is `firefox-appdir`, so the very common `firefox-appdir = "browser"`
  * directive is honoured. On a rebranded fork (appname=`mybrowser`) the
- * harness looks for `mybrowser-appdir` — the literal `firefox-appdir` line
+ * harness looks for `mybrowser-appdir`, so the literal `firefox-appdir` line
  * is silently ignored, `appPath` falls back to `xrePath`, and every
  * `resource:///modules/…` import throws `Failed to load
  * resource:///modules/<name>.sys.mjs` because xpcshell resolves the
@@ -22,7 +22,7 @@
  *    `xpcshell.toml`. If none exists, the test is not an xpcshell test and
  *    there is nothing to inject.
  * 2. Read the manifest's `[DEFAULT]` section. Look for `<appname>-appdir`
- *    first — if present, the harness already finds it. Fall back to
+ *    first. If present, the harness already finds it. Fall back to
  *    `firefox-appdir`. This ordering matches upstream precedence and avoids
  *    overriding an operator who already migrated.
  * 3. If only `firefox-appdir` is present and `appname != "firefox"`, compute
@@ -31,7 +31,7 @@
  *    `dist/<bundle>.app/Contents/Resources/<value>` for the macOS packaged
  *    layout) and return it as the value to pass to `--app-path`.
  * 4. If multiple test paths disagree on the resolved value, refuse injection
- *    and return null — the operator can drop down to `--mach-arg`.
+ *    and return null. The operator can drop down to `--mach-arg`.
  *
  * Operator escape hatch: `--mach-arg=--app-path=…` always wins (handled in
  * test.ts, which skips injection when `--app-path=` already appears in the
@@ -51,7 +51,7 @@ import { isObject, isString } from '../utils/validation.js';
  *  - Single- or double-quoted values
  *  - Whitespace either side of `=`
  *  - Continuation comments (`#` or `;`) at the end of the line
- *  - Bare unquoted bareword values (e.g. `firefox-appdir = browser`) — some
+ *  - Bare unquoted bareword values (e.g. `firefox-appdir = browser`). Some
  *    operators omit the quotes and the harness honours either form.
  *
  * Returns `undefined` when the key is absent or sits outside `[DEFAULT]`.
@@ -64,8 +64,7 @@ export function parseAppdirFromToml(tomlText, key) {
     // comment further along the file is not mistaken for the directive.
     const escapedKey = escapeRegex(key);
     const keyPattern = new RegExp('^\\s*' + escapedKey + '\\s*=\\s*(.+?)\\s*(?:[#;].*)?$');
-    for (let i = 0; i < lines.length; i += 1) {
-        const line = lines[i] ?? '';
+    for (const [i, line] of lines.entries()) {
         const sectionMatch = /^\s*\[([^\]]+)\]\s*$/.exec(line);
         if (sectionMatch) {
             sectionSeen = true;
@@ -94,7 +93,7 @@ function stripQuotes(raw) {
     if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
         return raw.slice(1, -1);
     }
-    // Bareword: must not contain whitespace; otherwise we are looking at
+    // Bareword: must not contain whitespace. Otherwise we are looking at
     // commentary that the regex's optional comment tail did not strip.
     if (/\s/.test(raw))
         return undefined;
@@ -105,10 +104,10 @@ function stripQuotes(raw) {
  * returns the absolute path of the first sibling `xpcshell.toml` found.
  * Stops at `engineDir` (inclusive) and returns null on miss.
  *
- * Special-cases `startPath` itself when it already ends with `xpcshell.toml`
- * — operators sometimes pass a manifest path directly.
+ * Special-cases `startPath` itself when it already ends with
+ * `xpcshell.toml`, since operators sometimes pass a manifest path directly.
  *
- * When `startPath` is a DIRECTORY, the walk starts at the directory itself
+ * When `startPath` is a directory, the walk starts at the directory itself
  * (checking `<dir>/xpcshell.toml` first) rather than at its parent.
  * Starting at the parent misses a directory's own manifest, so
  * `fireforge test <dir>` classifies it non-xpcshell and dispatches to the
@@ -123,8 +122,8 @@ export async function findNearestXpcshellManifest(engineDir, startPath) {
     const engineAbs = resolve(engineDir);
     let current = absStart;
     // First iteration resolves the starting directory (the path itself for a
-    // directory argument, its parent for a file); subsequent ones walk up.
-    // Cap iterations defensively — a pathological symlink loop would
+    // directory argument, its parent for a file). Subsequent ones walk up.
+    // Cap iterations defensively: a pathological symlink loop would
     // otherwise spin until the call stack overflows.
     for (let i = 0; i < 64; i += 1) {
         const dir = i === 0 ? (startIsDirectory ? absStart : dirname(absStart)) : dirname(current);
@@ -139,10 +138,10 @@ export async function findNearestXpcshellManifest(engineDir, startPath) {
 }
 /**
  * Reads `<objDir>/mozinfo.json` for the active app name. Returns
- * `"firefox"` when mozinfo cannot be read or the field is missing — that
+ * `"firefox"` when mozinfo cannot be read or the field is missing. That
  * is the safe default because it matches stock Firefox behaviour and
  * means the resolver will not inject anything (the manifest's
- * `firefox-appdir` value WILL be honoured by the upstream harness when
+ * `firefox-appdir` value is honoured by the upstream harness when
  * appname is firefox).
  */
 export async function readMozinfoAppname(objDirPath) {
@@ -157,28 +156,28 @@ export async function readMozinfoAppname(objDirPath) {
     }
     catch {
         // Malformed mozinfo is a build-system problem out of scope for the
-        // appdir resolver; treat as if appname were missing.
+        // appdir resolver. Treat as if appname were missing.
     }
     return 'firefox';
 }
 /**
  * Probes the obj-dir's `dist/` subtree for the absolute path the harness
  * would have computed if the manifest key had been honoured. Returns null
- * when no candidate exists — better to skip injection silently than to point
+ * when no candidate exists: better to skip injection silently than to point
  * the harness at a path that does not exist, which fails with a different
  * error than the original symptom and confuses triage.
  *
  * Probe order differs by host platform:
  *
- * - **macOS (`darwin`)**: prefer
- *   `<objDir>/dist/<App>.app/Contents/Resources/<value>` FIRST, then fall
+ * - macOS (`darwin`): prefer
+ *   `<objDir>/dist/<App>.app/Contents/Resources/<value>` first, then fall
  *   back to `<objDir>/dist/bin/<value>`. On macOS `dist/bin` is symlinked to
- *   `dist/<App>.app/Contents/MacOS/` (the *binaries* directory), so
- *   `dist/bin/browser` resolves to `<App>.app/Contents/MacOS/browser/` —
- *   NOT where `resource:///modules/` is rooted. Injecting that path looks
- *   successful in the log but points at a directory with no modules tree, so
- *   every `resource:///modules/…` import still throws.
- * - **non-macOS**: `dist/bin/<value>` first,
+ *   `dist/<App>.app/Contents/MacOS/` (the binaries directory), so
+ *   `dist/bin/browser` resolves to `<App>.app/Contents/MacOS/browser/`,
+ *   which is not where `resource:///modules/` is rooted. Injecting that path
+ *   looks successful in the log but points at a directory with no modules
+ *   tree, so every `resource:///modules/…` import still throws.
+ * - non-macOS: `dist/bin/<value>` first,
  *   `.app/Contents/Resources/<value>` as fallback.
  *
  * On both platforms the final `.app` fallback iterates every `*.app` entry
@@ -223,7 +222,7 @@ export async function resolveAbsoluteAppPath(objDirAbs, relativeAppdir) {
 /**
  * Top-level resolver. Walks every test path, reads the nearest
  * xpcshell.toml, and returns the single absolute path to inject (or a
- * structured "no injection" outcome). Never throws — every fs / parse
+ * structured "no injection" outcome). Never throws: every fs / parse
  * error is folded into a `none` outcome so the test command always falls
  * through to the diagnostic hint instead of dying inside a helper.
  */
@@ -232,7 +231,7 @@ export async function resolveXpcshellAppdirArg(engineDir, testPaths, objDirName)
         return { kind: 'none' };
     const objDirAbs = resolve(engineDir, objDirName);
     const appname = await readMozinfoAppname(objDirAbs);
-    // When appname IS "firefox" the upstream harness reads `firefox-appdir`
+    // When appname is "firefox" the upstream harness reads `firefox-appdir`
     // natively. Injecting in that case would be a no-op at best and an
     // override at worst, so bail out before doing any IO per-path.
     if (appname === 'firefox')
@@ -248,11 +247,11 @@ export async function resolveXpcshellAppdirArg(engineDir, testPaths, objDirName)
             body = await readText(manifestPath);
         }
         catch {
-            // An unreadable manifest cannot declare an appdir; skip it and keep
+            // An unreadable manifest cannot declare an appdir. Skip it and keep
             // walking the remaining candidates.
             continue;
         }
-        // Operator already migrated — harness will read the appname-keyed
+        // Operator already migrated. The harness will read the appname-keyed
         // value directly. Nothing to do.
         if (parseAppdirFromToml(body, appnameKey) !== undefined)
             continue;
@@ -290,8 +289,7 @@ export async function resolveXpcshellAppdirArg(engineDir, testPaths, objDirName)
  * wins.
  */
 export function operatorAlreadySetAppPath(extraArgs) {
-    for (let i = 0; i < extraArgs.length; i += 1) {
-        const arg = extraArgs[i] ?? '';
+    for (const [i, arg] of extraArgs.entries()) {
         if (arg === '--app-path' && i + 1 < extraArgs.length)
             return true;
         if (arg.startsWith('--app-path='))

package/dist/src/core/xpcshell-profile-dir.d.ts

@@ -2,11 +2,11 @@ export declare const XPCSHELL_PROFILE_ENV_VAR = "XPCSHELL_TEST_PROFILE_DIR";
 /**
  * Runs `fn` with a fresh per-invocation xpcshell profile directory
  * injected into the environment, removing the directory afterwards
- * (best-effort — a failure to clean up warns and leaves the mkdtemp dir
- * for the OS tmp reaper; the harness may still hold files briefly).
+ * (best-effort: a failure to clean up warns and leaves the mkdtemp dir
+ * for the OS tmp reaper, and the harness may still hold files briefly).
  *
  * An operator-provided `XPCSHELL_TEST_PROFILE_DIR` (in `baseEnv` or the
  * process environment) is respected verbatim: no directory is minted and
- * NOTHING is deleted — we never remove a directory we did not create.
+ * nothing is deleted, because we never remove a directory we did not create.
  */
 export declare function withXpcshellProfileDir<T>(baseEnv: Record<string, string> | undefined, fn: (env: Record<string, string>) => Promise<T>): Promise<T>;

package/dist/src/core/xpcshell-profile-dir.js

@@ -3,10 +3,10 @@
  * Per-invocation xpcshell profile directory.
  *
  * Firefox's xpcshell harness defaults `XPCSHELL_TEST_PROFILE_DIR` to a
- * FIXED path (`$TMPDIR/firefox/xpcshellprofile`), so two overlapping
- * harness invocations — concurrent `fireforge test` processes, or future
- * verification-tree shards — corrupt each other's profiles. FireForge
- * never set the variable; this helper mints a fresh `mkdtemp` directory
+ * fixed path (`$TMPDIR/firefox/xpcshellprofile`), so two overlapping
+ * harness invocations (concurrent `fireforge test` processes, or future
+ * verification-tree shards) corrupt each other's profiles. FireForge
+ * never set the variable. This helper mints a fresh `mkdtemp` directory
  * per harness invocation and exports it through the mach env channel.
  */
 import { mkdtemp, rm } from 'node:fs/promises';
@@ -18,12 +18,12 @@ export const XPCSHELL_PROFILE_ENV_VAR = 'XPCSHELL_TEST_PROFILE_DIR';
 /**
  * Runs `fn` with a fresh per-invocation xpcshell profile directory
  * injected into the environment, removing the directory afterwards
- * (best-effort — a failure to clean up warns and leaves the mkdtemp dir
- * for the OS tmp reaper; the harness may still hold files briefly).
+ * (best-effort: a failure to clean up warns and leaves the mkdtemp dir
+ * for the OS tmp reaper, and the harness may still hold files briefly).
  *
  * An operator-provided `XPCSHELL_TEST_PROFILE_DIR` (in `baseEnv` or the
  * process environment) is respected verbatim: no directory is minted and
- * NOTHING is deleted — we never remove a directory we did not create.
+ * nothing is deleted, because we never remove a directory we did not create.
  */
 export async function withXpcshellProfileDir(baseEnv, fn) {
     const operatorProvided = baseEnv?.[XPCSHELL_PROFILE_ENV_VAR] ?? process.env[XPCSHELL_PROFILE_ENV_VAR];