@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/mach-build-artifacts.js

@@ -38,7 +38,7 @@ function validateBuildMozinfo(data) {
  * Reads the objdir name the engine's mozconfig declares, or undefined when
  * there is no mozconfig, it cannot be read, or it declares nothing.
  *
- * Fail-open by construction: this only ever narrows an ambiguity that would
+ * Fail-open: this only ever narrows an ambiguity that would
  * otherwise refuse, so an unreadable mozconfig costs nothing beyond the
  * refusal the caller was already going to raise.
  */
@@ -57,8 +57,8 @@ async function readDeclaredObjDirName(engineDir) {
 /**
  * Checks if build artifacts exist in the engine directory.
  * Looks for obj-* directories with a dist subdirectory. Detection is
- * deliberately symlink-agnostic — building/running against a symlinked
- * objdir in place is the user's own arrangement; the clone path, where a
+ * symlink-agnostic on purpose: building/running against a symlinked
+ * objdir in place is the user's own arrangement. The clone path, where a
  * symlink would route writes into the original build, refuses separately
  * (`assertCloneSafeObjdir` in tree-store.ts).
  * @param engineDir - Path to the engine directory
@@ -86,7 +86,7 @@ export async function hasBuildArtifacts(engineDir) {
         let declaredObjDir;
         if (validObjDirs.length > 1) {
             // An ambiguous glob is a question the mozconfig may already answer.
-            // Refusing when the active configuration NAMES the objdir sends the
+            // Refusing when the active configuration names the objdir sends the
             // operator to rename a directory to satisfy a scan, when the thing
             // that decides the build has said which one it is. The refusal is
             // kept for the genuinely ambiguous case: a declaration that does not
@@ -148,7 +148,7 @@ export async function hasBuildArtifacts(engineDir) {
 /**
  * Checks whether the built browser's launchable binary exists under
  * `<engineDir>/<objDir>/dist/...`. `hasBuildArtifacts` only confirms that
- * an obj tree with a `dist/` subdir exists; a partial or in-progress build
+ * an obj tree with a `dist/` subdir exists. A partial or in-progress build
  * can satisfy that check without ever writing the executable, which is the
  * failure mode that makes `fireforge run` throw `mach run` after having
  * reported the build as usable. Separating the probes lets `run` fail fast
@@ -158,19 +158,19 @@ export async function hasBuildArtifacts(engineDir) {
  *
  * Platform layout:
  * - macOS: `<objDir>/dist/*.app/Contents/MacOS/<binaryName>` (the `.app`
- *   display casing can differ from `binaryName` — e.g. `MyBrowser.app` for
+ *   display casing can differ from `binaryName`, e.g. `MyBrowser.app` for
  *   binary `mybrowser`, so we enumerate the `*.app` bundles rather than
  *   compute the name.
  * - Linux: `<objDir>/dist/bin/<binaryName>`.
  * - Windows: `<objDir>/dist/bin/<binaryName>.exe`.
  *
  * Returns `runnable: false` with no `expectedPath` when the `objDir`
- * itself cannot be scanned — same degraded contract as `hasBuildArtifacts`.
+ * itself cannot be scanned. Same degraded contract as `hasBuildArtifacts`.
  *
  * @param engineDir Path to the engine directory
  * @param binaryName Lowercase binary name from `fireforge.json`
  * @param objDir The single matching `obj-*` directory name (caller
- *   resolves it; typically from `hasBuildArtifacts().objDir`)
+ *   resolves it, typically from `hasBuildArtifacts().objDir`)
  * @returns Structured check result
  */
 export async function hasRunnableBundle(engineDir, binaryName, objDir) {
@@ -241,26 +241,26 @@ export function buildArtifactMismatchMessage(engineDir, buildCheck, commandName)
  * Safe-relocation rewriter for mozinfo.json under the active obj-* tree.
  *
  * Firefox build artefacts bake the topsrcdir into many generated files
- * (Makefiles, config.status, backend.mk, .deps dependency files — anything
+ * (Makefiles, config.status, backend.mk, .deps dependency files, anything
  * produced by `mach configure`). A fresh `mach configure` rebuilds those
  * from the top, so the rewriter only needs to patch the one file `mach`
  * reads to learn where its checkout actually lives. Once mozinfo.json
  * agrees with the on-disk layout, `mach configure` regenerates the rest.
  *
- * Safety rules — the rewrite is refused when any of them are violated:
+ * Safety rules. The rewrite is refused when any of them are violated:
  *   - `topsrcdir` and `topobjdir` must both be present and non-empty.
- *   - `topobjdir` must resolve to `<topsrcdir>/<objDir>`; a non-in-tree
+ *   - `topobjdir` must resolve to `<topsrcdir>/<objDir>`. A non-in-tree
  *     objdir means the previous workspace was configured differently,
  *     so a blind prefix-rewrite could point mach at the wrong tree.
- *   - The computed new `topobjdir` must be `<engineDir>/<objDir>`; if it
+ *   - The computed new `topobjdir` must be `<engineDir>/<objDir>`. If it
  *     is not, the objDir name itself changed and we cannot prove safety.
  *
  * When any rule trips, the caller should fall back to the clean-rebuild
- * instruction — that's always a correct (if expensive) recovery path.
+ * instruction, which is always a correct (if expensive) recovery path.
  *
  * @param engineDir Absolute path to the current engine checkout.
  * @param objDir Name of the obj-* directory to rewrite against.
- * @returns Result object; callers inspect `rewritten` and surface `reason`.
+ * @returns Result object. Callers inspect `rewritten` and surface `reason`.
  */
 export async function attemptMozinfoRewrite(engineDir, objDir) {
     const mozinfoPath = join(engineDir, objDir, 'mozinfo.json');
@@ -323,10 +323,10 @@ export async function attemptMozinfoRewrite(engineDir, objDir) {
             newMozconfig = resolve(newSrc, rel);
             patched['mozconfig'] = newMozconfig;
         }
-        // A mozconfig living outside the old topsrcdir is left as-is — it
+        // A mozconfig living outside the old topsrcdir is left as-is. It
         // probably points at a shared configuration file the user kept in
         // place across the relocation. A relocated checkout that also moved
-        // its mozconfig will still fail configure; operator can re-point
+        // its mozconfig will still fail configure. The operator can re-point
         // with `MOZCONFIG=…` or run a full clean rebuild.
     }
     await writeJson(mozinfoPath, patched);
@@ -340,7 +340,7 @@ export async function attemptMozinfoRewrite(engineDir, objDir) {
 /**
  * Shared build-artifact preflight: rejects ambiguous multi-objdir checkouts,
  * artifacts whose metadata points at another tree, and (when
- * `requireExisting`) missing or incomplete builds — each with the actionable
+ * `requireExisting`) missing or incomplete builds, each with the actionable
  * message for that case.
  *
  * Takes an already-probed {@link BuildArtifactCheck} rather than probing
@@ -369,13 +369,13 @@ export function assertBuildArtifacts(engineDir, buildCheck, options) {
  * the four configure-generated root files (`config.status`, `backend.mk`,
  * `Makefile`, `config/autoconf.mk`) still names `forbiddenDir` (the
  * primary engine a relocated clone must never consult). Exit code 0 alone
- * proves neither — a stray MOZCONFIG/MOZ_OBJDIR can steer configure at a
+ * proves neither: a stray MOZCONFIG/MOZ_OBJDIR can steer configure at a
  * different objdir entirely. Nested Makefiles are products of the verified
- * `config.status` and are not scanned; `.deps` files are build products a
- * configure cannot regenerate and are explicitly out of scope — any
+ * `config.status` and are not scanned. `.deps` files are build products a
+ * configure cannot regenerate and are explicitly out of scope, and any
  * primary-path strings they retain are read-only staleness corrected by
  * the first in-tree rebuild. Pure checker: returns a human-readable
- * violation, or `undefined` when clean; callers own the error type and
+ * violation, or `undefined` when clean. Callers own the error type and
  * remediation copy. Unreadable metadata is itself a violation (fail
  * closed).
  */
@@ -406,9 +406,9 @@ export async function findObjdirRelocationViolation(args) {
     // The canonical no-primary-paths assertion (mirrored by the opt-in
     // real-mach proof in scripts/run-full-firefox-integration.mjs): substring
     // search on the resolved primary engine dir is collision-safe against the
-    // tree's own paths — `<primary>/.fireforge/trees/<name>/engine` never
+    // tree's own paths: `<primary>/.fireforge/trees/<name>/engine` never
     // contains the substring `<primary>/engine`. Scans exactly the
-    // configure-generated root files; `config.status` is mandatory (checked
+    // configure-generated root files. `config.status` is mandatory (checked
     // above), the rest are optional-if-absent because not every configure
     // backend writes them.
     const forbidden = resolve(forbiddenDir);

package/dist/src/core/mach-error-hints.d.ts

@@ -1,11 +1,11 @@
 /**
  * Pattern-based translator for cryptic mozbuild / mach errors.
  *
- * Each entry maps a stderr regex to an actionable hint. The goal is not to
- * parse every mach failure — it's to convert the handful of errors whose
- * message is non-obvious into a one-line "here's what to change". New
+ * Each entry maps a stderr regex to an actionable hint. The goal is narrow:
+ * convert the handful of errors whose message is non-obvious into a one-line
+ * "here's what to change", rather than parse every mach failure. New
  * entries should only be added when a concrete diagnosis of the cryptic
- * output has been established; low-confidence hints would train operators
+ * output has been established. Low-confidence hints would train operators
  * to ignore the translator.
  */
 /** A single translator entry. */
@@ -15,14 +15,9 @@ export interface MachErrorHint {
     /** Actionable, one-line hint to surface alongside the raw mach output. */
     hint: string;
 }
-/**
- * Registered hint patterns. Order-sensitive: the first match wins per
- * pattern, but multiple distinct patterns may fire for the same stderr.
- */
-export declare const MACH_ERROR_HINTS: MachErrorHint[];
 /**
  * Scans captured stderr for known mach errors and returns matching hints.
- * Pure function — safe to call on any string; never throws.
+ * Pure function. Safe to call on any string and never throws.
  * @param stderr Captured mach stderr.
  * @returns Ordered, de-duplicated list of hint strings. Empty when nothing matches.
  */

package/dist/src/core/mach-error-hints.js

@@ -2,30 +2,30 @@
 /**
  * Pattern-based translator for cryptic mozbuild / mach errors.
  *
- * Each entry maps a stderr regex to an actionable hint. The goal is not to
- * parse every mach failure — it's to convert the handful of errors whose
- * message is non-obvious into a one-line "here's what to change". New
+ * Each entry maps a stderr regex to an actionable hint. The goal is narrow:
+ * convert the handful of errors whose message is non-obvious into a one-line
+ * "here's what to change", rather than parse every mach failure. New
  * entries should only be added when a concrete diagnosis of the cryptic
- * output has been established; low-confidence hints would train operators
+ * output has been established. Low-confidence hints would train operators
  * to ignore the translator.
  */
 /**
  * Registered hint patterns. Order-sensitive: the first match wins per
  * pattern, but multiple distinct patterns may fire for the same stderr.
  */
-export const MACH_ERROR_HINTS = [
+const MACH_ERROR_HINTS = [
     {
         pattern: /mozbuild\.preprocessor\.Preprocessor\.Error[\s\S]*?no preprocessor directives found/,
         hint: 'A file registered under JS_PREFERENCE_PP_FILES contains no preprocessor directives. ' +
             'Use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.',
     },
     {
-        // mozbuild raises `UnsortedError` while READING a moz.build whose
+        // mozbuild raises `UnsortedError` while reading a moz.build whose
         // StrictOrderingOnAppendList entries are out of order, so `mach
         // configure` dies before anything compiles. The ordering rule is the
         // part operators get wrong: mozbuild sorts by `.lower()`
         // (`StrictOrderingOnAppendList.ensure_sorted`), so an uppercase letter
-        // does NOT sort ahead of a lowercase one, and an entry that looks
+        // does not sort ahead of a lowercase one, and an entry that looks
         // correctly placed by byte order can be rejected. mozbuild's own
         // message names both entries ("We expected X but got Y") and survives
         // to the operator through `extractMachConfigureError`, so the hint
@@ -41,7 +41,7 @@ export const MACH_ERROR_HINTS = [
     },
     {
         // `mach package` inside `packager.py` dereferences a `None` sink when
-        // the packaging input set cannot resolve an entry it expected — most
+        // the packaging input set cannot resolve an entry it expected, most
         // commonly running `fireforge package` before a full `fireforge build`
         // has finished, so `obj-*/dist/` is missing pieces the packager assumes
         // exist. The broader "build failed" path has already surfaced the raw
@@ -75,10 +75,10 @@ export const MACH_ERROR_HINTS = [
     },
     {
         // Firefox declares per-release toolchain minimums in-tree
-        // (`build/moz.configure/bindgen.configure` for cbindgen; mozboot's
+        // (`build/moz.configure/bindgen.configure` for cbindgen, and mozboot's
         // MINIMUM_RUST_VERSION for rustc/cargo), and a source hop can move them.
-        // The failure lands ~8s into `mach configure` — e.g. "ERROR: cbindgen
-        // version 0.29.1 is too old. At least version 0.29.4 is required." —
+        // The failure lands ~8s into `mach configure` (e.g. "ERROR: cbindgen
+        // version 0.29.1 is too old. At least version 0.29.4 is required."),
         // and mach's own remediation text names "./mach bootstrap", the wrong
         // entry point for a FireForge-managed repo. Pattern matches configure's
         // cbindgen die() shape.
@@ -90,7 +90,7 @@ export const MACH_ERROR_HINTS = [
     },
     {
         // Same family, rust.configure's die() shapes: "Rust compiler {v} is
-        // too old." / "Cargo package manager {v} is too old." — the minimum
+        // too old." / "Cargo package manager {v} is too old." The minimum
         // is only named further down that message, so the pattern keys on
         // the first line.
         pattern: /\b(?:Rust compiler|Cargo package manager) [\d.]+(?:[\w.-]*)? is too old/i,
@@ -103,7 +103,7 @@ export const MACH_ERROR_HINTS = [
         // When `mach build` fails mid-compile, mach's own shutdown pipeline
         // still runs its trailing "Config object not found by mach. / Configure
         // complete! / Be sure to run |mach build|..." summary on the way out.
-        // Those three lines are plain upstream mach output, printed AFTER the
+        // Those three lines are plain upstream mach output, printed after the
         // non-zero exit code is established, and they read deceptively like a
         // success banner. Nudge the operator that they are cosmetic
         // post-failure output, not a mixed success/failure signal.
@@ -115,7 +115,7 @@ export const MACH_ERROR_HINTS = [
 ];
 /**
  * Scans captured stderr for known mach errors and returns matching hints.
- * Pure function — safe to call on any string; never throws.
+ * Pure function. Safe to call on any string and never throws.
  * @param stderr Captured mach stderr.
  * @returns Ordered, de-duplicated list of hint strings. Empty when nothing matches.
  */

package/dist/src/core/mach-known-noise-filter.d.ts

@@ -4,72 +4,75 @@
  *
  * Headless test runs against recent engines can end with an
  * `AttributeError: 'SystemResourceMonitor' object has no attribute
- * 'stop_time'` traceback at harness teardown — upstream noise that sits
- * exactly where a reader looks for the failure summary. Real failure lines
- * already beat this traceback in CLASSIFICATION; this filter closes the
- * PRESENTATION gap by collapsing the echoed traceback to one labeled line.
+ * 'stop_time'` traceback at harness teardown. That is upstream noise, and
+ * it sits exactly where a reader looks for the failure summary. Real failure
+ * lines already beat this traceback in classification. This filter closes
+ * the presentation gap by collapsing the echoed traceback to one labeled
+ * line.
  *
- * Scope is deliberately narrow:
- *   - Only the terminal ECHO is filtered. The captured stdout/stderr strings
- *     stay raw — the classifier (`test-harness-crash.ts`) depends on the raw
- *     traceback for its green-summary override and secondary-noise
+ * Scope is narrow on purpose:
+ *   - Only the terminal echo is filtered. The captured stdout/stderr strings
+ *     stay raw, because the classifier (`test-harness-crash.ts`) depends on
+ *     the raw traceback for its green-summary override and secondary-noise
  *     detection.
  *   - Only the exact documented incident is collapsed, and every condition
  *     must hold: an `AttributeError` on `SystemResourceMonitor` naming one
- *     of the two known attributes (`stop_time`, `poll_interval`), AND a
- *     `mozsystemmonitor/resourcemonitor.py` stack frame, AND a
+ *     of the two known attributes (`stop_time`, `poll_interval`), and a
+ *     `mozsystemmonitor/resourcemonitor.py` stack frame, and a
  *     previously-seen SUITE_END shutdown marker (shared across the run's
- *     stdout/stderr filter instances — the marker usually lands on stdout
- *     while the traceback lands on stderr). A novel attribute, a novel
+ *     stdout/stderr filter instances, where the marker usually lands on
+ *     stdout while the traceback lands on stderr). A novel attribute, a novel
  *     exception type in resourcemonitor.py, or a pre-shutdown occurrence is
  *     echoed verbatim, always.
- *   - The hold buffer is bounded; on overflow the block is flushed verbatim
+ *   - The hold buffer is bounded. On overflow the block is flushed verbatim
  *     and the filter returns to pass-through, so output is never lost.
  *
- * The COLLAPSE is test-only, deliberately, and not an oversight — the two
- * reasons are worth stating because from outside it reads like one:
+ * The collapse is test-only on purpose, not an oversight. Two reasons,
+ * since from outside they read like one:
  *   1. Recognition requires a previously-seen SUITE_END shutdown marker, and
  *      `mach build` never prints one. Wiring the option into the build
  *      dispatch would therefore be a silent no-op.
  *   2. Relaxing that gate for builds would be wrong on its own terms. The
  *      marker is what separates teardown noise from a traceback raised while
- *      work was still happening; a build has no equivalent boundary, so
+ *      work was still happening. A build has no equivalent boundary, so
  *      FireForge cannot tell the known-cosmetic case from a real build-time
  *      failure and must not withhold the block.
- * The build path instead RECOGNIZES the signature and says so beside the
- * verbatim traceback — see {@link KNOWN_TEARDOWN_NOISE_BUILD_NOTE} and
+ * The build path instead recognizes the signature and says so beside the
+ * verbatim traceback. See {@link KNOWN_TEARDOWN_NOISE_BUILD_NOTE} and
  * `runProtectedMachBuild`.
  */
 /**
- * True when CAPTURED output carries the documented mozsystemmonitor
- * teardown traceback.
+ * Whole-block recognition. Every signal must hold (see module doc). True
+ * when captured output carries the documented mozsystemmonitor teardown
+ * traceback.
  *
- * The echo filter above only affects what a human sees. The CLASSIFIER
+ * The echo filter below only affects what a human sees. The classifier
  * reads the raw capture, and it needs the same recognition to tell "the
  * suite finished clean and then upstream fell over at shutdown" from "the
- * suite did not finish". Deliberately the same two-signal test the echo
- * filter applies — a novel attribute or a traceback from anywhere but
- * `resourcemonitor.py` is NOT this incident and must keep failing the run.
+ * suite did not finish". This is the same two-signal test the echo filter
+ * applies: a novel attribute or a traceback from anywhere but
+ * `resourcemonitor.py` is not this incident and must keep failing the run.
  *
  * The shutdown-marker precondition the echo filter adds is intentionally
- * omitted: the whole point at the classification layer is the case where
- * the teardown crash prevented the shutdown marker from printing.
+ * omitted: at the classification layer the case that matters is exactly
+ * the one where the teardown crash prevented the shutdown marker from
+ * printing.
  *
- * Pure; exported for the classifier and for direct unit testing.
+ * Pure. Exported for the classifier and for direct unit testing.
  *
  * @param output - Raw captured stdout/stderr
  * @returns True when the recognized teardown traceback is present
  */
 export declare function hasKnownTeardownNoise(output: string): boolean;
 /**
- * True when a SINGLE line is the documented teardown family's
+ * True when a single line is the documented teardown family's
  * `AttributeError`.
  *
- * The line-level half of {@link hasKnownTeardownNoise}: the traceback FRAME
+ * The line-level half of {@link hasKnownTeardownNoise}: the traceback frame
  * lives on a neighbouring line, so a per-line test cannot apply the
  * two-signal rule by itself. Callers pair this with
- * `hasKnownTeardownNoise(wholeOutput)` to recover the full recognition —
- * "this capture carries the incident, and THIS line is its header" — which
+ * `hasKnownTeardownNoise(wholeOutput)` to recover the full recognition
+ * ("this capture carries the incident, and this line is its header"), which
  * keeps the closed attribute allowlist (`stop_time`/`poll_interval`) doing
  * the same work it does everywhere else. A novel attribute is not this
  * incident and must stay a candidate failure.
@@ -79,20 +82,21 @@ export declare function hasKnownTeardownNoise(output: string): boolean;
  */
 export declare function isKnownTeardownNoiseLine(line: string): boolean;
 /**
- * Shared across the stdout and stderr filter instances of ONE mach run:
+ * Shared across the stdout and stderr filter instances of one mach run:
  * SUITE_END typically arrives on stdout while the teardown traceback lands
  * on stderr, so the shutdown-seen flag must be visible to both. The two
  * pipes are independent, so a traceback can theoretically beat the marker
- * through — the block then prints verbatim, the correct failure direction.
+ * through. The block then prints verbatim, which is the correct failure
+ * direction.
  */
 export interface TeardownNoiseContext {
     shutdownSeen: boolean;
 }
-/** Fresh per-run context — hand the same instance to both stream filters. */
+/** Fresh per-run context. Hand the same instance to both stream filters. */
 export declare function createTeardownNoiseContext(): TeardownNoiseContext;
 /**
- * Build-phase note for the SAME recognized signature. The build path does
- * not COLLAPSE the traceback (see the module doc's "test-only" note) — it
+ * Build-phase note for the same recognized signature. The build path does
+ * not collapse the traceback (see the module doc's "test-only" note). It
  * prints verbatim and this line is added beside it, so one signature reads
  * the same in both phases without a build losing output it may need.
  */
@@ -101,7 +105,7 @@ export declare const KNOWN_TEARDOWN_NOISE_BUILD_NOTE: string;
 export declare const KNOWN_TEARDOWN_NOISE_ANNOTATION: string;
 /** Chunk-safe, line-buffered echo filter. See module doc. */
 export interface KnownTeardownNoiseFilter {
-    /** Feed a raw chunk; returns the text to echo now (possibly empty). */
+    /** Feed a raw chunk. Returns the text to echo now (possibly empty). */
     transform(chunk: string): string;
     /** Flush any buffered residue verbatim (call after the stream closes). */
     flush(): string;
@@ -109,7 +113,7 @@ export interface KnownTeardownNoiseFilter {
 /**
  * Creates a stateful filter for one output stream. Complete lines outside a
  * traceback pass straight through (only the trailing partial line is held
- * back); a `Traceback (most recent call last)` header switches to hold mode
+ * back). A `Traceback (most recent call last)` header switches to hold mode
  * until the block ends, then either the one-line annotation (recognized
  * signature after a seen shutdown marker) or the verbatim block (anything
  * else) is emitted. Pass the run's shared {@link TeardownNoiseContext} so