@hominis/fireforge 0.52.0 → 0.53.0

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

@@ -22,6 +22,8 @@
  * legitimately have a fresh `dist/` with no FireForge-recorded baseline
  * update.
  */
+import { stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { verbose, warn } from '../utils/logger.js';
 import { normalizePathSlashes } from '../utils/paths.js';
@@ -30,6 +32,8 @@ import { readBuildBaseline } from './build-baseline.js';
 import { hashEngineFile } from './coverage-extend.js';
 import { isTestManifestPath } from './coverage-records.js';
 import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
+import { readLinkedAt } from './launchable-build.js';
+import { isCompiledSourcePath } from './negative-control-compiled.js';
 import { formatStaleExemptions, partitionStaleCandidates, } from './test-stale-exempt.js';
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
@@ -91,6 +95,83 @@ export function formatStaleBuildWarning(result) {
         '"fireforge build --ui") first. Passing --build skips this check.' +
         exemptLine);
 }
+/**
+ * Path segments whose compiled sources never reach the binary under test
+ * (gtests, cppunittests, CI config YAML): an edit there must not make the
+ * browser read as stale.
+ */
+const NON_RUNTIME_SEGMENTS = new Set(['test', 'tests', 'gtest', 'testing', 'taskcluster']);
+/**
+ * Changed compiled sources (C++, Rust, IDL, WebIDL, IPDL, StaticPrefList
+ * YAML, …) whose mtime is newer than the launchable build's last link.
+ * `mach build faster` compiles none of them, so such a run tests the
+ * binary from before the edit, which reads as a failed fix rather than a
+ * stale build. Candidates are the engine paths changed since the baseline
+ * plus every workdir edit; a fork's persistent patch diff is older than any
+ * build that followed it, so only genuine post-build edits remain.
+ * Returns undefined when there is nothing to compare against (no
+ * launchable binary).
+ *
+ * @param engineDir - Absolute engine directory
+ * @param baseline - Last-build baseline, when one exists
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export async function findCompiledSourcesNewerThanBinary(engineDir, baseline, launchablePath) {
+    if (launchablePath === undefined)
+        return undefined;
+    const linked = await readLinkedAt(engineDir, launchablePath);
+    if (linked === undefined)
+        return undefined;
+    const changed = await collectChangedEnginePaths(engineDir, baseline, 'Stale-compiled preflight');
+    const candidates = changed.filter((path) => isCompiledSourcePath(path) &&
+        !path.split('/').some((segment) => NON_RUNTIME_SEGMENTS.has(segment)));
+    const paths = [];
+    for (const path of candidates) {
+        try {
+            const { mtimeMs } = await stat(join(engineDir, path));
+            if (mtimeMs > linked.mtimeMs)
+                paths.push(path);
+        }
+        catch {
+            // A deleted source cannot be newer than anything; the build that
+            // drops it is the stale-build check's business.
+        }
+    }
+    return {
+        paths: paths.sort(),
+        linkedPath: relative(engineDir, linked.path),
+        linkedAt: new Date(linked.mtimeMs),
+    };
+}
+/**
+ * The `stale-compiled` refusal (or, under `--allow-stale-build`, warning).
+ *
+ * @param result - A non-empty {@link StaleCompiledResult}
+ */
+export function formatStaleCompiledRefusal(result) {
+    const head = result.paths.slice(0, STALE_PATHS_LIMIT).map((path) => `engine/${path}`);
+    const truncated = result.paths.length - head.length;
+    const list = head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
+    return (`Compiled sources changed after the binary under test was linked ` +
+        `(engine/${result.linkedPath}, ${result.linkedAt.toISOString()}): ${list}.\n` +
+        'The run would test the binary from before those edits, so a red reads as a failed fix ' +
+        'and a green proves nothing about them. Run "fireforge build" first, or rerun with ' +
+        '"fireforge test --build", which escalates to a full mach build when compiled sources ' +
+        'changed. --allow-stale-build turns this refusal into a warning.');
+}
+/**
+ * The notice that explains why a `test --build` pre-test build escalated
+ * to a full `mach build` for stale compiled sources.
+ *
+ * @param result - A non-empty {@link StaleCompiledResult}
+ */
+export function formatStaleCompiledBuildNotice(result) {
+    const head = result.paths.slice(0, STALE_PATHS_LIMIT).map((path) => `engine/${path}`);
+    const truncated = result.paths.length - head.length;
+    return (`Compiled sources changed after the binary was linked (${head.join(', ')}` +
+        `${truncated > 0 ? `, … (+${truncated} more)` : ''}); escalating this pre-test build to a ` +
+        'full mach build, since mach build faster compiles nothing.');
+}
 /**
  * Sentinel returned by {@link findUncoveredRequestPaths} when a full-suite
  * request (no paths) is checked against a scoped coverage record.
@@ -200,7 +281,7 @@ export function formatTestCoverageRefusal(uncovered, coverage, changedManifests
     };
     const rebuildTargets = uncovered.filter((p) => p !== FULL_SUITE_REQUEST);
     // Per-path retention is the default, so rebuilding only the uncovered
-    // paths no longer costs anyone else's claim. Saying so is what keeps a
+    // paths costs no one else's claim. Saying so is what keeps a
     // peer from rebuilding everything "to be safe".
     const keepHint = rebuildTargets.length > 0
         ? ' That scoped build keeps every other recorded path whose own staging inputs (manifest directory and the fixtures its manifest names) and engine/mozconfig are unchanged.'

package/dist/src/core/test-stall-triage.js

@@ -37,9 +37,8 @@ const NO_OUTPUT_STALL_CONTROL_STEP = 'First, run a known-good control test. If t
  *  - (4) is mechanical and was root-caused downstream: the harness serves
  *    its manifest from `server.js` on 8888, and a survivor of an
  *    interrupted run keeps the port. Its probe is exact, and the preflight
- *    in `mochitest-server-port.ts` now refuses it before a run starts.
- *  - (3) is now mechanical and root-caused, replacing the correlation an
- *    earlier revision recorded. A `chrome://` (or `resource://`) URL that
+ *    in `mochitest-server-port.ts` refuses it before a run starts.
+ *  - (3) is mechanical and root-caused. A `chrome://` (or `resource://`) URL that
  *    resolves to nothing reaches `CheckForBrokenChromeURL`
  *    (netwerk/base/nsNetUtil.cpp), which outside automation only
  *    `printf_stderr`s `Missing chrome or resource URL: <uri>`, but under
@@ -47,9 +46,8 @@ const NO_OUTPUT_STALL_CONTROL_STEP = 'First, run a known-good control test. If t
  *    `MOZ_CRASH_UNSAFE_PRINTF("Missing chrome or resource URLs: %s")`. A
  *    downstream reproduction symbolicated the faulting frame as
  *    `CheckForBrokenChromeURL`, which is the established diagnosis the bar
- *    in `mach-error-hints.ts` asks for. The discredited "stalls first
- *    paint" story an even earlier revision asserted must not come back: a
- *    failed image load in Gecko fires `error` and does not gate the
+ *    in `mach-error-hints.ts` asks for. It is not a "stalls first paint"
+ *    problem: a failed image load in Gecko fires `error` and does not gate the
  *    document load event.
  *
  * Detection by log line is not specified for (3), because of the mechanism
@@ -62,7 +60,7 @@ const NO_OUTPUT_STALL_CONTROL_STEP = 'First, run a known-good control test. If t
  * the census points at the two artefacts that do carry it: the OS crash
  * report (whose faulting frame names `CheckForBrokenChromeURL`) and the
  * out-of-automation smoke probe (which prints the non-crashing spelling
- * and, since 0.45.0, counts it as an unallowed error so the exit code
+ * and counts it as an unallowed error so the exit code
  * agrees with the capture).
  */
 const NO_OUTPUT_STALL_TRIAGE = [

package/dist/src/core/token-category.js

@@ -18,8 +18,8 @@ import { escapeRegex } from '../utils/regex.js';
  * Body of the first `/* … *\/` comment on `line`, or `undefined` when the
  * line carries no closed block comment.
  *
- * This uses index arithmetic rather than a regex: every regex spelling of
- * "banner comment" this module used to carry was super-linear on a line that
+ * This uses index arithmetic rather than a regex: the natural regex
+ * spellings of "banner comment" are super-linear on a line that
  * repeats the opening shape (CodeQL `js/polynomial-redos`), and `tokens.css`
  * is a file FireForge reads out of a consumer's engine tree, so a
  * pathological line needs no attacker to arrive.

package/dist/src/core/token-inventory.js

@@ -4,9 +4,9 @@
  * tokens each declares, and what a single token resolves to in every theme
  * block that mentions it.
  *
- * `token add` requires `--category` and, until now, nothing reported the
- * categories a project actually has, so the only way to name one correctly
- * was to hand-parse a neighbouring `= Category =` banner out of the file.
+ * `token add` requires `--category`, so it needs a report of the categories
+ * a project actually has; without one, the only way to name one correctly
+ * is to hand-parse a neighbouring `= Category =` banner out of the file.
  * This module is that report. It reuses the banner and
  * category-region model from `token-category.ts` rather than parsing
  * tokens CSS a second way: two readers that disagree on what a banner is

package/dist/src/core/token-manager.d.ts

@@ -4,7 +4,7 @@ import { type TokenDeclarationLocation } from './token-category.js';
  *
  * Derived from {@link TOKEN_MODES} so the runtime allowlist and the type
  * cannot drift: adding a member here without updating the list (or the
- * reverse) is no longer possible, because there is only one list.
+ * reverse) is impossible, because there is only one list.
  */
 export declare const TOKEN_MODES: readonly ["auto", "static", "override"];
 /** Dark mode behaviour for a token. */
@@ -21,7 +21,7 @@ export interface AddTokenOptions {
     value: string;
     /**
      * Token category matching section headers in the CSS file. Required for a
-     * base declaration. Ignored, and no longer required, under
+     * base declaration. Ignored, and not required, under
      * {@link AddTokenOptions.variant}, which routes into a `:root<selector>`
      * block and never touches a category section.
      */

package/dist/src/core/token-manager.js

@@ -17,7 +17,7 @@ import { findVariantBlockDeclaration, insertVariantDeclaration, validateVariantS
  *
  * Derived from {@link TOKEN_MODES} so the runtime allowlist and the type
  * cannot drift: adding a member here without updating the list (or the
- * reverse) is no longer possible, because there is only one list.
+ * reverse) is impossible, because there is only one list.
  */
 export const TOKEN_MODES = ['auto', 'static', 'override'];
 /** Narrows an arbitrary string to a {@link TokenMode}. */
@@ -109,12 +109,10 @@ function normalizeVariantOption(options) {
  * Narrows {@link AddTokenOptions.category} for the base-declaration path,
  * which cannot proceed without one.
  *
- * `--category` used to be unconditionally required, including under
- * `--variant`, where the declaration is routed into a `:root<selector>`
- * block and the category names nothing about where the token lands. The
- * requirement existed so the argument would not be silently discarded,
- * a fair goal that produced a mandatory argument describing nothing. Under
- * a variant it is now optional. Everywhere else this states the reason
+ * `--category` is optional under `--variant`, where the declaration is
+ * routed into a `:root<selector>` block and the category names nothing
+ * about where the token lands, so requiring it there would make a
+ * mandatory argument describing nothing. Everywhere else this states the reason
  * rather than leaving commander to print a bare "required option not
  * specified".
  *

package/dist/src/core/token-variant.d.ts

@@ -28,12 +28,12 @@ export type VariantValidation = {
  * Boolean-attribute fragments are returned unchanged.
  *
  * Structure is decided by {@link rootAttributeSelector}, the matcher's own
- * parse, rather than by a second regex. 0.44.2 widened
- * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
- * tail, and the validator did not move with it, so
- * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
- * could find but would not let you name. Running both halves off one parse
- * is what stops them drifting apart again. Character-level safety stays a
+ * parse, rather than by a second regex. The matcher consumes consecutive
+ * `[…]` groups and stops at a pseudo-class tail, and a separate validator
+ * that does not follow it leaves blocks such as
+ * `:root[data-skin="humanist"]:not([data-private])` findable but
+ * unnameable. Running both halves off one parse keeps them from drifting
+ * apart. Character-level safety stays a
  * separate, per-group check, because the matcher finds bracket boundaries
  * and validates no characters at all.
  *

package/dist/src/core/token-variant.js

@@ -68,12 +68,12 @@ function normalizeAttributeFragment(group) {
  * Boolean-attribute fragments are returned unchanged.
  *
  * Structure is decided by {@link rootAttributeSelector}, the matcher's own
- * parse, rather than by a second regex. 0.44.2 widened
- * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
- * tail, and the validator did not move with it, so
- * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
- * could find but would not let you name. Running both halves off one parse
- * is what stops them drifting apart again. Character-level safety stays a
+ * parse, rather than by a second regex. The matcher consumes consecutive
+ * `[…]` groups and stops at a pseudo-class tail, and a separate validator
+ * that does not follow it leaves blocks such as
+ * `:root[data-skin="humanist"]:not([data-private])` findable but
+ * unnameable. Running both halves off one parse keeps them from drifting
+ * apart. Character-level safety stays a
  * separate, per-group check, because the matcher finds bracket boundaries
  * and validates no characters at all.
  *
@@ -194,7 +194,7 @@ function findVariantBlock(lines, variant) {
         if (selector === undefined || canonicalSelector(selector.attributes) !== want)
             continue;
         // An unqualified request still matches a qualified block: that is the
-        // 0.44.2 behaviour `variantBlockQualifier` exists to report, since
+        // behaviour `variantBlockQualifier` exists to report, since
         // silently skipping the block is the worse failure. A request that names
         // a qualifier, though, means it, so it must match.
         if (wantQualifier !== '' && canonicalSelector(selector.qualifier) !== wantQualifier)

package/dist/src/core/typecheck-shim.js

@@ -291,7 +291,7 @@ export const UNDEFINED_IDENTIFIER_CODES = new Set([
 ]);
 /**
  * Typed Lit, opt-in through `typecheck.litTypes`. Declares the two chrome
- * modules widgets import Lit from, so they no longer fall to the
+ * modules widgets import Lit from, so they do not fall to the
  * `chrome:*` wildcard as `any`: `LitElement` (with `ReactiveElement`'s
  * lifecycle) and `MozLitElement` carry closed member lists, so a misspelt
  * member of a widget host is TS2339, as `Cu` is in the built-in shim.

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

@@ -11,7 +11,7 @@
  */
 export declare function addDestroyAST(content: string, expression: string, marker?: string): string;
 /**
- * Legacy regex/line-based implementation preserved as fallback.
+ * Regex/line-based fallback implementation.
  */
 export declare function legacyAddDestroy(content: string, expression: string, marker?: string): string;
 /**

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

@@ -65,7 +65,7 @@ export function addDestroyAST(content, expression, marker = DEFAULT_MARKER) {
     return ms.toString();
 }
 /**
- * Legacy regex/line-based implementation preserved as fallback.
+ * Regex/line-based fallback implementation.
  */
 export function legacyAddDestroy(content, expression, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);

package/dist/src/core/wire-dom-fragment.js

@@ -66,7 +66,7 @@ export async function probeDomFragmentInsertionPoint(engineDir, domFilePath, tar
         // dry-run is allowed to proceed too.
         return;
     }
-    // Check the tokenised and legacy insertion paths symmetrically with
+    // Check the tokenised and line-based insertion paths symmetrically with
     // the real run. Either helper returning without throwing is sufficient
     // evidence that the real run can land the directive.
     addDomFragmentTokenized(content, includeDirective);

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

@@ -13,7 +13,7 @@
  */
 export declare function addInitAST(content: string, expression: string, after?: string, marker?: string): string;
 /**
- * Legacy regex/line-based implementation preserved as fallback.
+ * Regex/line-based fallback implementation.
  */
 export declare function legacyAddInit(content: string, expression: string, after?: string, marker?: string): string;
 /**

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

@@ -112,7 +112,7 @@ export function addInitAST(content, expression, after, marker = DEFAULT_MARKER)
     return ms.toString();
 }
 /**
- * Legacy regex/line-based implementation preserved as fallback.
+ * Regex/line-based fallback implementation.
  */
 export function legacyAddInit(content, expression, after, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);

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

@@ -10,7 +10,7 @@
  */
 export declare function addSubscriptAST(content: string, name: string, marker?: string): string;
 /**
- * Legacy regex/line-based implementation preserved as fallback.
+ * Regex/line-based fallback implementation.
  */
 export declare function legacyAddSubscript(content: string, name: string, marker?: string): string;
 /**

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

@@ -73,7 +73,7 @@ export function addSubscriptAST(content, name, marker = DEFAULT_MARKER) {
     return ms.toString();
 }
 /**
- * Legacy regex/line-based implementation preserved as fallback.
+ * Regex/line-based fallback implementation.
  */
 export function legacyAddSubscript(content, name, marker = DEFAULT_MARKER) {
     const lines = content.split('\n');

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

@@ -104,7 +104,7 @@ export declare function walkToTryBlockEnd(lines: string[], startLine: number, op
 }): number;
 /**
  * Scans the entire file and returns the net brace balance so callers can
- * assert that a legacy fallback mutation did not silently introduce or
+ * assert that a line-based fallback mutation did not silently introduce or
  * drop a `{` / `}`. The helper reuses {@link countBraceDepth} so strings,
  * comments, and regex literals are handled consistently with the walker.
  *
@@ -117,7 +117,7 @@ export declare function computeFileBraceBalance(content: string): {
     balanced: boolean;
 };
 /**
- * Round-trip guard used after a legacy fallback mutation: if the file's
+ * Round-trip guard used after a line-based 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, since wire fallbacks only insert whole

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

@@ -159,7 +159,7 @@ export function tokenizeXhtml(lines) {
     });
 }
 // ---------------------------------------------------------------------------
-// Legacy (line-based) helpers, shared by fallback implementations in
+// Line-based helpers, shared by fallback implementations in
 // the wire target modules.  Extracted to reduce duplication and make the brace-
 // walking logic independently testable.
 // ---------------------------------------------------------------------------
@@ -224,7 +224,7 @@ export function walkToTryBlockEnd(lines, startLine, options) {
 }
 /**
  * Scans the entire file and returns the net brace balance so callers can
- * assert that a legacy fallback mutation did not silently introduce or
+ * assert that a line-based fallback mutation did not silently introduce or
  * drop a `{` / `}`. The helper reuses {@link countBraceDepth} so strings,
  * comments, and regex literals are handled consistently with the walker.
  *
@@ -244,7 +244,7 @@ export function computeFileBraceBalance(content) {
     return { depth, balanced: depth === 0 };
 }
 /**
- * Round-trip guard used after a legacy fallback mutation: if the file's
+ * Round-trip guard used after a line-based 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, since wire fallbacks only insert whole

package/dist/src/errors/base.d.ts

@@ -80,7 +80,7 @@ export declare class InternalInvariantError extends FireForgeError {
     get userMessage(): string;
 }
 /**
- * Raised when a legacy regex/brace-depth fallback parser decides it
+ * Raised when a regex/brace-depth fallback parser decides it
  * cannot safely perform its mutation, e.g. because a block it expected
  * to walk never closes, because the inserted result fails a round-trip
  * brace balance check, or because an expected pattern is missing.

package/dist/src/errors/base.js

@@ -106,7 +106,7 @@ export class InternalInvariantError extends FireForgeError {
     }
 }
 /**
- * Raised when a legacy regex/brace-depth fallback parser decides it
+ * Raised when a regex/brace-depth fallback parser decides it
  * cannot safely perform its mutation, e.g. because a block it expected
  * to walk never closes, because the inserted result fails a round-trip
  * brace balance check, or because an expected pattern is missing.

package/dist/src/errors/rebase.d.ts

@@ -33,7 +33,7 @@ export declare class CorruptRebaseSessionError extends RebaseError {
 }
 /**
  * Thrown by `rebase --dry-run` when the replay rejects at least one patch.
- * A dry run that exited 0 regardless used to read as "the rebase is ready".
+ * A dry run that exited 0 regardless would read as "the rebase is ready".
  */
 export declare class RebaseDryRunRejectError extends RebaseError {
     readonly rejected: readonly string[];

package/dist/src/errors/rebase.js

@@ -51,7 +51,7 @@ export class CorruptRebaseSessionError extends RebaseError {
 }
 /**
  * Thrown by `rebase --dry-run` when the replay rejects at least one patch.
- * A dry run that exited 0 regardless used to read as "the rebase is ready".
+ * A dry run that exited 0 regardless would read as "the rebase is ready".
  */
 export class RebaseDryRunRejectError extends RebaseError {
     rejected;

package/dist/src/types/commands/options.d.ts

@@ -516,6 +516,8 @@ export interface PatchSplitOptions extends Confirmable, PatchLockWaitable, Unsaf
     skipLint?: boolean;
     /** Where a refusal writes its one `--from`-ready declaration report. */
     declarationsOut?: string;
+    /** Write the committed old-to-new filename map of renumbered patches here as JSON. */
+    mapOut?: string;
 }
 /**
  * Options for the `fireforge patch move-files` subcommand. Without
@@ -541,6 +543,16 @@ export interface PatchMoveFilesOptions extends Confirmable, PatchLockWaitable, U
     skipLint?: boolean;
     /** Where a refusal writes its one `--from`-ready declaration report. */
     declarationsOut?: string;
+    /**
+     * New engine files no patch owns, adopted into the destination in the
+     * same transaction (engine-relative, repeatable).
+     */
+    scanFile?: string[];
+    /**
+     * Allow the move to empty the source: re-point the declarations it owns
+     * to the destination and retire its slot. Not valid with `create`.
+     */
+    retireEmpty?: boolean;
 }
 /**
  * Options for the rebase command.
@@ -673,8 +685,8 @@ export interface TestOptions extends EngineLockWaitable {
      * build would overwrite engine content recorded in neither a patch body
      * nor the pristine baseline. Same meaning as `fireforge build`'s flag of
      * the same name. A scripted `test --build` is exactly the shape the
-     * multi-session hazard shows up in, and until now it was the one shape
-     * that could not arm the refusal. Valid only with `--build`/`--build-only`.
+     * multi-session hazard shows up in, so it must be able to arm the
+     * refusal too. Valid only with `--build`/`--build-only`.
      */
     refuseUnexportedDrift?: boolean;
     /**
@@ -1073,7 +1085,7 @@ export interface PatchRenameOptions extends Confirmable, DryRunnable, PatchLockW
     /**
      * New category (validated against configured categories). Rewrites
      * the filename prefix and the manifest row in one transaction, so
-     * recategorising no longer requires `patch delete` + fresh export.
+     * recategorising does not require `patch delete` + fresh export.
      */
     category?: string;
     /**
@@ -1096,6 +1108,17 @@ export interface PatchReorderOptions extends PatchLockWaitable {
     to?: number;
     before?: string;
     after?: string;
+    /**
+     * Shift a run of patches up by this many orders (`--shift <n> --from
+     * <order> [--through <order>]`) instead of moving one patch.
+     */
+    shift?: number;
+    /** First order of the run `shift` moves. */
+    from?: number;
+    /** Last order of the run `shift` moves (default: the end of the run). */
+    through?: number;
+    /** Write the committed old-to-new filename map here as JSON. */
+    mapOut?: string;
     yes?: boolean;
     dryRun?: boolean;
     forceUnsafe?: boolean;

package/dist/src/types/config.d.ts

@@ -433,11 +433,10 @@ export interface PatchLintFileSizeTier {
 /**
  * Overrides for the `file-too-large` thresholds, per file class.
  *
- * These were module constants until 0.45.0, and nothing in `fireforge.json`
- * could move them. That is a problem specifically because the recommended
- * gate posture is `--max-warnings 0`: under it the `warning` band is not a
- * soft limit at all, so a project whose controllers legitimately sit a few
- * lines over 750 has a hard failure with no dial, at exactly the moment
+ * Configurable because the recommended gate posture is `--max-warnings 0`:
+ * under it the `warning` band is not a soft limit at all, so with fixed
+ * thresholds a project whose controllers legitimately sit a few lines over
+ * 750 would have a hard failure with no dial, at exactly the moment
  * someone is deciding whether to restructure a file.
  */
 export interface PatchLintFileSizeThresholds {
@@ -466,8 +465,7 @@ export interface PatchLintPatchSizeTier {
 /**
  * Overrides for the patch-size thresholds, per tier.
  *
- * Module constants until 0.50.0. The defaults are the old constants: lines
- * general 800/1500/3000, test 1500/3000/6000, branding 8000/18000/30000;
+ * Defaults: lines general 800/1500/3000, test 1500/3000/6000, branding 8000/18000/30000;
  * files warn above 5 (general, test) or 60 (branding). The files triple has
  * no notice or error band by default: an unset `files.notice` follows the
  * effective `files.warning`, and an unset `files.error` never fires.

package/dist/src/utils/options.js

@@ -71,8 +71,8 @@ export const WAIT_LOCK_ENV_VAR = 'FIREFORGE_WAIT_LOCK';
 /**
  * Bounds shared by the flag and the environment variable. The ceiling is a
  * day: on a shared engine a re-export or `test --build` queued behind a
- * peer's long series can need more than the hour the cap used to be, and a
- * longer wait then had to be a requeue after exit 15.
+ * peer's long series can need more than an hour, and a cap below that turns
+ * a longer wait into a requeue after exit 15.
  */
 const MIN_WAIT_LOCK_SECONDS = 1;
 export const MAX_WAIT_LOCK_SECONDS = 86_400;

package/dist/src/utils/process.js

@@ -173,7 +173,7 @@ async function spawnTracked(spec) {
         let rejection;
         child.on('error', (error) => {
             // Abort/startup failure: make sure a partially-started tree does not
-            // outlive the dispatch (a mach dying at startup used to strand
+            // outlive the dispatch (a mach dying at startup would otherwise strand
             // multiprocessing workers).
             if (options.processGroup === true) {
                 killProcessTree(child, 'SIGKILL', usesProcessGroup);
@@ -229,7 +229,7 @@ export async function execStream(command, args, options = {}) {
         args,
         options,
         graceMs: 1500,
-        // A detached group leader no longer receives the terminal's Ctrl+C, so
+        // A detached group leader does not receive the terminal's Ctrl+C, so
         // the forwarder is mandatory (not just graceful-UX) when processGroup
         // is set. A plain streamed child does not get one.
         forwardWithoutProcessGroup: false,

package/dist/src/utils/regex.d.ts

@@ -18,7 +18,7 @@ export declare function hasRawCssColors(content: string): boolean;
  * the line is blanked, corrupting whatever lint pass consumes the stripped
  * text. The source is tokenized as a module, then as a script. Firefox
  * chrome sources can contain constructs acorn tokenizes under neither goal.
- * Those fall back to the legacy regex strip, which handles strings but not
+ * Those fall back to the regex-only strip, which handles strings but not
  * regex literals.
  */
 export declare function stripJsComments(source: string): string;
@@ -30,7 +30,7 @@ export declare function stripJsComments(source: string): string;
  * legacy octal escape is a tokenizer error only under the module goal.
  * Callers that must not under-count when tokenizing fails (the code-line
  * size metric) read the `null` and pick their own fallback rather than the
- * legacy regex strip, which can blank code.
+ * regex-only strip, which can blank code.
  */
 export declare function stripJsCommentsParsed(source: string): string | null;
 /**

package/dist/src/utils/regex.js

@@ -34,7 +34,7 @@ export function hasRawCssColors(content) {
  * the line is blanked, corrupting whatever lint pass consumes the stripped
  * text. The source is tokenized as a module, then as a script. Firefox
  * chrome sources can contain constructs acorn tokenizes under neither goal.
- * Those fall back to the legacy regex strip, which handles strings but not
+ * Those fall back to the regex-only strip, which handles strings but not
  * regex literals.
  */
 export function stripJsComments(source) {
@@ -48,7 +48,7 @@ export function stripJsComments(source) {
  * legacy octal escape is a tokenizer error only under the module goal.
  * Callers that must not under-count when tokenizing fails (the code-line
  * size metric) read the `null` and pick their own fallback rather than the
- * legacy regex strip, which can blank code.
+ * regex-only strip, which can blank code.
  */
 export function stripJsCommentsParsed(source) {
     const comments = collectJsComments(source, 'module') ?? collectJsComments(source, 'script');
@@ -91,7 +91,7 @@ function collectJsComments(source, sourceType) {
     return comments;
 }
 /**
- * Legacy pure-regex comment strip, used only when acorn cannot tokenize
+ * Pure-regex comment strip, used only when acorn cannot tokenize
  * the source (preprocessor directives, syntax errors). Strings survive.
  * Regex literals are not modeled, so `//` inside a regex blanks the rest
  * of the line.

package/dist/src/utils/sleep.d.ts

@@ -1,12 +1,11 @@
 /**
  * The single awaitable delay used across FireForge.
  *
- * Five modules had grown a private copy of this (`sleep`, `delay`,
- * `sweepDelay`) and four more sites inlined
- * `new Promise((resolve) => setTimeout(resolve, ms))`. The copies disagreed on
- * the one property that actually matters (whether the pending timer holds
- * the event loop open) and the disagreement was invisible at each call site.
- * Both behaviours now live here, and callers state which one they need.
+ * Callers use this rather than a private `sleep`/`delay` or an inline
+ * `new Promise((resolve) => setTimeout(resolve, ms))`, because such copies
+ * disagree on the one property that actually matters (whether the pending
+ * timer holds the event loop open) and the disagreement is invisible at each
+ * call site. Both behaviours live here, and callers state which one they need.
  *
  * The default is a ref'd timer, because the dangerous mistake is the other
  * one: an unref'd delay awaited between a SIGTERM and its escalation lets Node