@hominis/fireforge 0.51.0 → 0.53.0

package/dist/src/core/history-log-file.js

@@ -2,12 +2,12 @@
 /**
  * Where the patch history log lives, and who wrote each record.
  *
- * The log used to be `patches/.fireforge-history.jsonl`, inside the tracked
- * patch queue, so it was committed with every export until consumers
- * gitignored it, and it grew to tens of megabytes. It now defaults to
- * `.fireforge/history.jsonl` (FireForge's own untracked data directory), or
- * `fireforge.json#history.path` when a project sets one. A log left at the
- * old path is moved on the first append.
+ * The log defaults to `.fireforge/history.jsonl` (FireForge's own untracked
+ * data directory), or `fireforge.json#history.path` when a project sets one.
+ * It stays out of the tracked patch queue because it grows to tens of
+ * megabytes and would otherwise be committed with every export. A log found
+ * at `patches/.fireforge-history.jsonl`, inside the queue, is moved on the
+ * first append.
  *
  * Several sessions sharing one checkout all append to the same log, so each
  * record carries the invocation that wrote it, plus a session hint, letting
@@ -21,7 +21,7 @@ import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, verbose } from '../utils/logger.js';
 import { FIREFORGE_DIR } from './config-paths.js';
 import { isValidHistoryPath } from './config-validate-history.js';
-/** Filename of the history log at its pre-0.50 location, inside `patches/`. */
+/** Filename of a history log inside `patches/`, which is moved out of the queue. */
 export const LEGACY_HISTORY_LOG_FILENAME = '.fireforge-history.jsonl';
 /** Default history log location, relative to the project root. */
 export const DEFAULT_HISTORY_LOG_PATH = join(FIREFORGE_DIR, 'history.jsonl');
@@ -87,24 +87,24 @@ export async function resolveHistoryLogPath(projectRoot) {
     return resolve(projectRoot, configured ?? DEFAULT_HISTORY_LOG_PATH);
 }
 /**
- * Moves a history log left at the legacy `patches/` path to `target`.
+ * Moves a history log found at the `patches/` path to `target`.
  *
  * Records are never dropped, whatever else is happening:
- * - The legacy file is first claimed by renaming it aside, so of two
+ * - The in-queue file is first claimed by renaming it aside, so of two
  *   commands migrating at once exactly one does the work and neither
  *   duplicates it.
  * - When `target` does not exist yet (the first run), the claimed file is
  *   hard-linked into place, which cannot overwrite a log another command
  *   created in the meantime, and keeps a large log a constant-time move.
- * - When both exist (an older FireForge appended to the legacy path after
- *   a migration, or `history.path` changed), the legacy records are
+ * - When both exist (a log reappeared at the `patches/` path after a
+ *   migration, or `history.path` changed), the in-queue records are
  *   appended to the target in one write. They then follow newer records;
  *   every record carries its own `ts`.
  *
  * A crash between the claim and the move leaves the records in a
- * `.migrating-*` file next to the legacy path, never deleted.
+ * `.migrating-*` file next to the in-queue path, never deleted.
  *
- * @param patchesDir - The patches directory that may hold a legacy log
+ * @param patchesDir - The patches directory that may hold an in-queue log
  * @param target - Absolute path of the history log
  */
 export async function migrateLegacyHistoryLog(patchesDir, target) {
@@ -149,8 +149,8 @@ export async function migrateLegacyHistoryLog(patchesDir, target) {
         'Nothing reads it back; it is an audit trail only.');
 }
 /**
- * Appends one serialized record to the project's history log, migrating a
- * legacy log first.
+ * Appends one serialized record to the project's history log, first moving
+ * a log found inside `patches/`.
  *
  * @param patchesDir - The project's `patches/` directory; the project root is
  *   its parent, as every caller derives it from `getProjectPaths`

package/dist/src/core/history-log.d.ts

@@ -3,13 +3,13 @@ import type { HistoryEntry } from './destructive.js';
  * Appends a history entry for a mutation that has already committed, degrading
  * to a warning when the log cannot be written.
  *
- * Eleven call sites across `export-flow` and the `patch` subcommands had each
- * grown the same `try { await appendHistory(...) } catch { warn(...) }` block.
+ * This is the one `try { await appendHistory(...) } catch { warn(...) }`
+ * block for every call site across `export-flow` and the `patch` subcommands.
  * The swallow is intentional: the patch files and the manifest
  * are already on disk by the time this runs, so letting a failed log write
  * reject would report a completed, irreversible mutation as a failure and send
  * the operator looking for damage that is not there. Because that reasoning is
- * easy to lose in a copy, it now lives in one place.
+ * easy to lose in a copy, it lives in one place.
  * @param patchesDir - The project's `patches/` directory (the log itself lives
  *   under `.fireforge/` or `history.path`; see `history-log-file.ts`).
  * @param entry - The entry to append.

package/dist/src/core/history-log.js

@@ -6,13 +6,13 @@ import { appendHistory } from './destructive.js';
  * Appends a history entry for a mutation that has already committed, degrading
  * to a warning when the log cannot be written.
  *
- * Eleven call sites across `export-flow` and the `patch` subcommands had each
- * grown the same `try { await appendHistory(...) } catch { warn(...) }` block.
+ * This is the one `try { await appendHistory(...) } catch { warn(...) }`
+ * block for every call site across `export-flow` and the `patch` subcommands.
  * The swallow is intentional: the patch files and the manifest
  * are already on disk by the time this runs, so letting a failed log write
  * reject would report a completed, irreversible mutation as a failure and send
  * the operator looking for damage that is not there. Because that reasoning is
- * easy to lose in a copy, it now lives in one place.
+ * easy to lose in a copy, it lives in one place.
  * @param patchesDir - The project's `patches/` directory (the log itself lives
  *   under `.fireforge/` or `history.path`; see `history-log-file.ts`).
  * @param entry - The entry to append.

package/dist/src/core/launchable-build.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Facts about the launchable build a test run will exercise: its build id
+ * and when its compiled code was last linked.
+ *
+ * A green or red against a binary older than the C++ under test reads as a
+ * verdict on that C++ unless the run says which binary it was. The
+ * build id goes on the verdict line (`build-id=`), and the link time anchors
+ * the stale-compiled preflight (`findCompiledSourcesNewerThanBinary` in
+ * `test-stale-check.ts`).
+ */
+/**
+ * The `application.ini` beside a launchable binary: `Contents/Resources`
+ * of the `.app` bundle on macOS, the binary's own directory (`dist/bin`)
+ * elsewhere.
+ *
+ * @param binaryPath - Absolute launchable binary path
+ */
+export declare function applicationIniPath(binaryPath: string): string;
+/**
+ * Reads the `BuildID=` of the launchable build (the `moz:buildID` the
+ * browser reports). Undefined when the file or the key is missing, so a
+ * caller can simply leave the attribute off.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export declare function readBuildId(engineDir: string, launchablePath: string): Promise<string | undefined>;
+/**
+ * When the launchable build's compiled code was last linked: the newest
+ * mtime of the binary and the `libxul` beside it. Undefined when neither
+ * can be read.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export declare function readLinkedAt(engineDir: string, launchablePath: string): Promise<{
+    mtimeMs: number;
+    path: string;
+} | undefined>;

package/dist/src/core/launchable-build.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Facts about the launchable build a test run will exercise: its build id
+ * and when its compiled code was last linked.
+ *
+ * A green or red against a binary older than the C++ under test reads as a
+ * verdict on that C++ unless the run says which binary it was. The
+ * build id goes on the verdict line (`build-id=`), and the link time anchors
+ * the stale-compiled preflight (`findCompiledSourcesNewerThanBinary` in
+ * `test-stale-check.ts`).
+ */
+import { stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { readText } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+/**
+ * The compiled libraries a build links next to the launchable binary.
+ * `libxul` carries nearly all compiled engine code (C++, Rust, generated
+ * bindings, prefs), so it, not the small launcher executable, is what a
+ * compiled-source edit relinks.
+ */
+const LINKED_LIBRARY_NAMES = ['XUL', 'libxul.so', 'xul.dll'];
+/**
+ * The `application.ini` beside a launchable binary: `Contents/Resources`
+ * of the `.app` bundle on macOS, the binary's own directory (`dist/bin`)
+ * elsewhere.
+ *
+ * @param binaryPath - Absolute launchable binary path
+ */
+export function applicationIniPath(binaryPath) {
+    const binaryDir = dirname(binaryPath);
+    if (basename(binaryDir) === 'MacOS' && basename(dirname(binaryDir)) === 'Contents') {
+        return join(dirname(binaryDir), 'Resources', 'application.ini');
+    }
+    return join(binaryDir, 'application.ini');
+}
+/**
+ * Reads the `BuildID=` of the launchable build (the `moz:buildID` the
+ * browser reports). Undefined when the file or the key is missing, so a
+ * caller can simply leave the attribute off.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export async function readBuildId(engineDir, launchablePath) {
+    const iniPath = applicationIniPath(join(engineDir, launchablePath));
+    let content;
+    try {
+        content = await readText(iniPath);
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) !== 'ENOENT') {
+            verbose(`Build id: could not read ${iniPath} — ${toError(error).message}`);
+        }
+        return undefined;
+    }
+    const match = /^BuildID=(\S+)\s*$/m.exec(content);
+    return match?.[1];
+}
+/**
+ * When the launchable build's compiled code was last linked: the newest
+ * mtime of the binary and the `libxul` beside it. Undefined when neither
+ * can be read.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export async function readLinkedAt(engineDir, launchablePath) {
+    const binary = join(engineDir, launchablePath);
+    const candidates = [binary, ...LINKED_LIBRARY_NAMES.map((name) => join(dirname(binary), name))];
+    let newest;
+    for (const path of candidates) {
+        try {
+            // stat follows the dist/bin symlinks to the linked objdir file.
+            const { mtimeMs } = await stat(path);
+            if (newest === undefined || mtimeMs > newest.mtimeMs)
+                newest = { mtimeMs, path };
+        }
+        catch {
+            // A platform's other library names are simply absent.
+        }
+    }
+    return newest;
+}

package/dist/src/core/marionette-port.js

@@ -247,9 +247,7 @@ async function probeWithLsof(port) {
     catch {
         // `lsof` missing, or its stdout did not parse. Either way the port state
         // is unknown, and an unknown port is reported as free so the probe never
-        // blocks a run on its own uncertainty. (The errno test that used to sit
-        // here returned the same value as this fallthrough, so it decided
-        // nothing.)
+        // blocks a run on its own uncertainty.
         return { inUse: false };
     }
 }

package/dist/src/core/moz-manifest-rules.js

@@ -77,11 +77,12 @@ export function getRules(binaryName, createManifest = false) {
             // scaffolded and wired via XPCSHELL_TESTS_MANIFESTS.
             pattern: /^(?!browser\/base\/content\/test\/)(.+)\/(test_[^/]+\.js)$/,
             isRegistered: (engineDir, dirRel, fileName) => isXpcshellTestRegistered(engineDir, dirRel, fileName),
-            register: (engineDir, _after, dryRun, dirRel, fileName) => registerXpcshellTest(engineDir, dirRel, fileName, dryRun, createManifest),
+            register: (engineDir, after, dryRun, dirRel, fileName) => registerXpcshellTest(engineDir, dirRel, fileName, dryRun, createManifest, after),
             // Both groups are guaranteed by the pattern, so slice avoids dead
             // fallback branches.
             extractArgs: (m) => m.slice(1, 3),
-            supportsAfter: false,
+            // `--after <entry>` places the section after that entry's block.
+            supportsAfter: true,
         },
     ];
 }

package/dist/src/core/negative-control-compiled.d.ts

@@ -6,18 +6,37 @@
  * objdir links to. A C++ (or Rust, IDL, …) source edited at that point is
  * never compiled: the run tests the unmutated binary and reports
  * `control=missed`, which reads as a test that cannot fail. Such a target
- * is now refused without `--build`, and with `--build` the control is
- * applied before the build so the binary under test carries it.
+ * is refused without `--build`, and with `--build` the control is
+ * applied before the build so the binary under test carries it. That build
+ * is a full `mach build`: the pre-test build is otherwise `mach build
+ * faster`, which compiles nothing, so the control would still miss.
  */
+/**
+ * Whether an engine-relative path has a compiled-source extension: a file
+ * the build compiles or code-generates into the binary. This is the
+ * extension test only. {@link findCompiledControlTargets} additionally
+ * drops non-header files an install manifest ships as-is.
+ *
+ * @param path - Engine-relative path
+ */
+export declare function isCompiledSourcePath(path: string): boolean;
 /**
  * The engine-relative targets that reach the runtime only through a
  * compile: a compiled-source extension and no install-manifest entry that
- * ships the file itself.
+ * ships the file itself. Headers are always compiled, even when an
+ * `EXPORTS` manifest installs them into `dist/include`.
  *
  * @param engineDir - Absolute engine directory
  * @param enginePaths - The control's engine-relative targets
  */
 export declare function findCompiledControlTargets(engineDir: string, enginePaths: readonly string[]): Promise<string[]>;
+/**
+ * The notice that explains why a compiled control's pre-test build is a
+ * full `mach build` instead of `mach build faster`.
+ *
+ * @param compiled - Engine-relative compiled targets
+ */
+export declare function formatCompiledControlBuildNotice(compiled: readonly string[]): string;
 /**
  * The refusal for a compiled control without `--build`, naming the manual
  * procedure for a run that wants to keep its build out of FireForge.

package/dist/src/core/negative-control-compiled.js

@@ -7,8 +7,10 @@
  * objdir links to. A C++ (or Rust, IDL, …) source edited at that point is
  * never compiled: the run tests the unmutated binary and reports
  * `control=missed`, which reads as a test that cannot fail. Such a target
- * is now refused without `--build`, and with `--build` the control is
- * applied before the build so the binary under test carries it.
+ * is refused without `--build`, and with `--build` the control is
+ * applied before the build so the binary under test carries it. That build
+ * is a full `mach build`: the pre-test build is otherwise `mach build
+ * faster`, which compiles nothing, so the control would still miss.
  */
 import { extname } from 'node:path';
 import { classifyRuntimeDelivery } from './objdir-install-manifests.js';
@@ -32,29 +34,63 @@ const COMPILED_EXTENSIONS = new Set([
     '.yaml',
     '.yml',
 ]);
+/**
+ * Header extensions. An `EXPORTS` install manifest names many headers (it
+ * copies them into `dist/include`), but that copy only feeds other
+ * compiles: the runtime never reads a header, so a header edit reaches the
+ * binary through a compile whatever the manifests say.
+ */
+const HEADER_EXTENSIONS = new Set(['.h', '.hh', '.hpp', '.ipdlh']);
+/**
+ * Whether an engine-relative path has a compiled-source extension: a file
+ * the build compiles or code-generates into the binary. This is the
+ * extension test only. {@link findCompiledControlTargets} additionally
+ * drops non-header files an install manifest ships as-is.
+ *
+ * @param path - Engine-relative path
+ */
+export function isCompiledSourcePath(path) {
+    return COMPILED_EXTENSIONS.has(extname(path));
+}
 /**
  * The engine-relative targets that reach the runtime only through a
  * compile: a compiled-source extension and no install-manifest entry that
- * ships the file itself.
+ * ships the file itself. Headers are always compiled, even when an
+ * `EXPORTS` manifest installs them into `dist/include`.
  *
  * @param engineDir - Absolute engine directory
  * @param enginePaths - The control's engine-relative targets
  */
 export async function findCompiledControlTargets(engineDir, enginePaths) {
-    const candidates = enginePaths.filter((path) => COMPILED_EXTENSIONS.has(extname(path)));
+    const candidates = enginePaths.filter(isCompiledSourcePath);
     if (candidates.length === 0)
         return [];
+    if (candidates.every((path) => HEADER_EXTENSIONS.has(extname(path))))
+        return candidates;
     const index = await loadEngineInstallIndex(engineDir);
     if (index === undefined)
         return candidates;
     const compiled = [];
     for (const path of candidates) {
-        if ((await classifyRuntimeDelivery(index, engineDir, path)) === 'unlisted') {
+        if (HEADER_EXTENSIONS.has(extname(path)) ||
+            (await classifyRuntimeDelivery(index, engineDir, path)) === 'unlisted') {
             compiled.push(path);
         }
     }
     return compiled;
 }
+/**
+ * The notice that explains why a compiled control's pre-test build is a
+ * full `mach build` instead of `mach build faster`.
+ *
+ * @param compiled - Engine-relative compiled targets
+ */
+export function formatCompiledControlBuildNotice(compiled) {
+    const files = compiled.map((path) => `engine/${path}`).join(', ');
+    return (`The negative control edits compiled source (${files}); escalating this pre-test build to ` +
+        'a full mach build, since mach build faster compiles nothing and the binary under test ' +
+        'would not carry the control.');
+}
 /**
  * The refusal for a compiled control without `--build`, naming the manual
  * procedure for a run that wants to keep its build out of FireForge.

package/dist/src/core/parser-fallback.d.ts

@@ -13,12 +13,12 @@ export declare function consumeParserFallbackEvents(): ParserFallbackEvent[];
  * The `rethrowIf` predicate every AST-primary caller wants.
  *
  * Rethrows internal-invariant `GeneralError`s ("Unexpected empty …array"):
- * those are programming bugs, and retrying the legacy scanner cannot fix a
+ * those are programming bugs, and retrying the fallback scanner cannot fix a
  * broken invariant, it just buries the stack. Everything else still falls
  * back, which matters: the AST path raises a raw acorn SyntaxError
  * on chrome sources acorn cannot parse (preprocessor directives), and
  * BuildError when the file's shape is unexpected. Both are exactly what the
- * legacy scanner is here to handle.
+ * fallback scanner is here to handle.
  *
  * @param error - The error the primary parser threw
  * @returns True when the error must propagate instead of falling back
@@ -33,15 +33,15 @@ export interface ParserResult<T> {
     fallbackReason?: string;
 }
 /**
- * Wraps a primary (AST/tokenizer) parser with a legacy (regex/line-based)
+ * Wraps a primary (AST/tokenizer) parser with a regex/line-based
  * fallback. If the primary throws, a warning is logged and the fallback is
  * used instead.
  *
  * Returns a {@link ParserResult} so callers (and tests) can detect which
  * code path was taken and surface it in logs or assertions.
  *
- * @param primary - The modern parser implementation
- * @param fallback - The legacy fallback implementation
+ * @param primary - The primary parser implementation
+ * @param fallback - The regex/line-based fallback implementation
  * @param context - File/context name used in the warning message
  * @param rethrowIf - Optional predicate. If it returns true for the caught
  *   error the error is re-thrown instead of falling back (useful for

package/dist/src/core/parser-fallback.js

@@ -18,12 +18,12 @@ export function consumeParserFallbackEvents() {
  * The `rethrowIf` predicate every AST-primary caller wants.
  *
  * Rethrows internal-invariant `GeneralError`s ("Unexpected empty …array"):
- * those are programming bugs, and retrying the legacy scanner cannot fix a
+ * those are programming bugs, and retrying the fallback scanner cannot fix a
  * broken invariant, it just buries the stack. Everything else still falls
  * back, which matters: the AST path raises a raw acorn SyntaxError
  * on chrome sources acorn cannot parse (preprocessor directives), and
  * BuildError when the file's shape is unexpected. Both are exactly what the
- * legacy scanner is here to handle.
+ * fallback scanner is here to handle.
  *
  * @param error - The error the primary parser threw
  * @returns True when the error must propagate instead of falling back
@@ -32,15 +32,15 @@ export function isInternalInvariantFailure(error) {
     return error instanceof GeneralError;
 }
 /**
- * Wraps a primary (AST/tokenizer) parser with a legacy (regex/line-based)
+ * Wraps a primary (AST/tokenizer) parser with a regex/line-based
  * fallback. If the primary throws, a warning is logged and the fallback is
  * used instead.
  *
  * Returns a {@link ParserResult} so callers (and tests) can detect which
  * code path was taken and surface it in logs or assertions.
  *
- * @param primary - The modern parser implementation
- * @param fallback - The legacy fallback implementation
+ * @param primary - The primary parser implementation
+ * @param fallback - The regex/line-based fallback implementation
  * @param context - File/context name used in the warning message
  * @param rethrowIf - Optional predicate. If it returns true for the caught
  *   error the error is re-thrown instead of falling back (useful for

package/dist/src/core/patch-identifier-suggest.d.ts

@@ -18,3 +18,9 @@ import type { PatchMetadata } from '../types/commands/index.js';
  * `InvalidArgumentError` body, never the full queue enumeration.
  */
 export declare function formatPatchNotFoundError(identifier: string, patches: readonly PatchMetadata[]): string;
+/**
+ * The nearest-match half of {@link formatPatchNotFoundError}: the closest
+ * accepted identifiers and the queue size, never the full queue. For
+ * callers that word their own lead, such as the `--patches` subset.
+ */
+export declare function formatPatchSuggestions(identifier: string, patches: readonly PatchMetadata[]): string;

package/dist/src/core/patch-identifier-suggest.js

@@ -118,11 +118,18 @@ function rankSuggestions(identifier, candidates) {
  * `InvalidArgumentError` body, never the full queue enumeration.
  */
 export function formatPatchNotFoundError(identifier, patches) {
-    const accepted = collectAcceptedIdentifiers(patches);
-    const suggestions = rankSuggestions(identifier, accepted);
     const lead = `Patch "${identifier}" not found. Accepted identifiers: ordinal (e.g. 2), filename (e.g. 002-ui-foo.patch), or manifest name (e.g. ui-foo).`;
+    return `${lead} ${formatPatchSuggestions(identifier, patches)}`;
+}
+/**
+ * The nearest-match half of {@link formatPatchNotFoundError}: the closest
+ * accepted identifiers and the queue size, never the full queue. For
+ * callers that word their own lead, such as the `--patches` subset.
+ */
+export function formatPatchSuggestions(identifier, patches) {
+    const suggestions = rankSuggestions(identifier, collectAcceptedIdentifiers(patches));
     if (suggestions.length > 0) {
-        return `${lead} Did you mean: ${suggestions.join(', ')}? (${patches.length} patches in queue — run "fireforge patch list" for the full list.)`;
+        return `Did you mean: ${suggestions.join(', ')}? (${patches.length} patches in queue — run "fireforge patch list" for the full list.)`;
     }
-    return `${lead} No close match found among ${patches.length} patches in the queue. Run "fireforge patch list" to see them.`;
+    return `No close match found among ${patches.length} patches in the queue. Run "fireforge patch list" to see them.`;
 }

package/dist/src/core/patch-lint-checkjs.d.ts

@@ -9,7 +9,7 @@
  *
  * Separated from `patch-lint.ts` to keep both files within the
  * project's per-file line budget. The shim itself and the suppressed
- * diagnostic code list now live in `typecheck-shim.ts` and are shared
+ * diagnostic code list live in `typecheck-shim.ts` and are shared
  * with the whole-project `fireforge typecheck` command, keeping a
  * single source of truth for the Firefox-globals coverage.
  * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`

package/dist/src/core/patch-lint-checkjs.js

@@ -10,7 +10,7 @@
  *
  * Separated from `patch-lint.ts` to keep both files within the
  * project's per-file line budget. The shim itself and the suppressed
- * diagnostic code list now live in `typecheck-shim.ts` and are shared
+ * diagnostic code list live in `typecheck-shim.ts` and are shared
  * with the whole-project `fireforge typecheck` command, keeping a
  * single source of truth for the Firefox-globals coverage.
  * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`

package/dist/src/core/patch-lint-css.js

@@ -65,7 +65,7 @@ const RAW_COLOR_IGNORE_MARKER = 'fireforge-ignore: raw-color-value';
  * comment spanning the context/added boundary suppresses its hex, then
  * only the patch's added line numbers are scanned. Returns undefined
  * when any added line number falls outside the on-disk file (patch not
- * applied / drifted). The caller then falls back to the legacy
+ * applied / drifted). The caller then falls back to the
  * joined-added-lines scan rather than misattributing lines.
  */
 function buildAddedLinesScanSource(rawCss, addedNumbers) {
@@ -100,7 +100,7 @@ function checkRawColorValues(input) {
         suppressedContent = buildAddedLinesScanSource(rawCss, addedNumbers);
     }
     if (suppressedContent === undefined) {
-        // Legacy scan: full file (no diff), or the joined added lines when
+        // Fallback scan: full file (no diff), or the joined added lines when
         // the diff and on-disk file disagree. Waiver lines are filtered
         // against the pre-strip text so the CSS comment marker is present.
         const sourceForSuppression = addedLinesByFile

package/dist/src/core/patch-lint-file-size.d.ts

@@ -6,13 +6,11 @@
  * `patch-lint.ts` from `config-validate.ts` for a constant would draw an
  * import edge (and a cycle) between the rule bodies and config parsing.
  *
- * On the vocabulary: the bands were `notice` / `warning` / `error` with the
- * middle one described as a "soft limit". That description is false under
- * the posture FireForge itself recommends for a release gate,
- * `--max-warnings 0`, where a warning is a hard failure, so a file at 751
- * lines failed a gate with a message calling 750 soft. The message below
- * says what the band is (a warning) and what a zero-warning gate does with
- * it, and the thresholds are now tunable, so a project whose file-size
+ * On the vocabulary: the bands are `notice` / `warning` / `error`, and the
+ * middle one is not a "soft limit". Under the posture FireForge itself
+ * recommends for a release gate, `--max-warnings 0`, a warning is a hard
+ * failure. The message below therefore says what the band is (a warning)
+ * and what a zero-warning gate does with it, and the thresholds are tunable, so a project whose file-size
  * policy differs has a dial instead of an argument. The notice band is the
  * design target: advisory, and its message says so rather than borrowing
  * the warning band's gate sentence.

package/dist/src/core/patch-lint-file-size.js

@@ -7,13 +7,11 @@
  * `patch-lint.ts` from `config-validate.ts` for a constant would draw an
  * import edge (and a cycle) between the rule bodies and config parsing.
  *
- * On the vocabulary: the bands were `notice` / `warning` / `error` with the
- * middle one described as a "soft limit". That description is false under
- * the posture FireForge itself recommends for a release gate,
- * `--max-warnings 0`, where a warning is a hard failure, so a file at 751
- * lines failed a gate with a message calling 750 soft. The message below
- * says what the band is (a warning) and what a zero-warning gate does with
- * it, and the thresholds are now tunable, so a project whose file-size
+ * On the vocabulary: the bands are `notice` / `warning` / `error`, and the
+ * middle one is not a "soft limit". Under the posture FireForge itself
+ * recommends for a release gate, `--max-warnings 0`, a warning is a hard
+ * failure. The message below therefore says what the band is (a warning)
+ * and what a zero-warning gate does with it, and the thresholds are tunable, so a project whose file-size
  * policy differs has a dial instead of an argument. The notice band is the
  * design target: advisory, and its message says so rather than borrowing
  * the warning band's gate sentence.

package/dist/src/core/patch-lint-ignore.d.ts

@@ -3,9 +3,9 @@
  *
  * An entry is either a bare check ID, which suppresses that rule at any
  * size, or a ceiling `{ rule, max, reason }`, which suppresses a size rule
- * only while its measurement is at or below `max`. The bare form let a
- * waived file grow without bound: nothing re-examined the waiver once it
- * was written, so a 950-line file waived at review time was still waived at
+ * only while its measurement is at or below `max`. The bare form lets a
+ * waived file grow without bound: nothing re-examines the waiver once it
+ * is written, so a 950-line file waived at review time is still waived at
  * 2,000 lines. The ceiling makes growth past the reviewed size fire again,
  * and lets a gate say when the waiver is no longer needed at all.
  *

package/dist/src/core/patch-lint-ignore.js

@@ -4,9 +4,9 @@
  *
  * An entry is either a bare check ID, which suppresses that rule at any
  * size, or a ceiling `{ rule, max, reason }`, which suppresses a size rule
- * only while its measurement is at or below `max`. The bare form let a
- * waived file grow without bound: nothing re-examined the waiver once it
- * was written, so a 950-line file waived at review time was still waived at
+ * only while its measurement is at or below `max`. The bare form lets a
+ * waived file grow without bound: nothing re-examines the waiver once it
+ * is written, so a 950-line file waived at review time is still waived at
  * 2,000 lines. The ceiling makes growth past the reviewed size fire again,
  * and lets a gate say when the waiver is no longer needed at all.
  *

package/dist/src/core/patch-lint-prettier.d.ts

@@ -1,14 +1,12 @@
 /**
  * Optional Prettier pass over patch-owned `.sys.mjs` modules.
  *
- * Until 0.45.0 no tier of the chain ran Prettier on `.sys.mjs` at all, so
- * module formatting drift was caught by nothing and survived to a human
- * reviewer. Worse, the obvious manual check was misleading in the same
- * direction: a fork's root `.prettierignore` typically excludes `engine/`,
+ * Without this pass no tier of the chain runs Prettier on `.sys.mjs`, so
+ * module formatting drift survives to a human reviewer. The obvious manual
+ * check is misleading in the same direction: a fork's root `.prettierignore` typically excludes `engine/`,
  * so `prettier --check --config engine/.prettierrc.js <engine files>` run
  * from the repo root reports "all files use Prettier code style" for files
- * that fail the identical check run from inside `engine/`. A root-level
- * spot-check falsely refuted a correct reviewer finding on exactly this.
+ * that fail the identical check run from inside `engine/`.
  *
  * This pass therefore runs prettier with `cwd` set to the engine directory,
  * so the engine's own `.prettierrc*` and `.prettierignore` resolve the way