@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/patch-lint-unmanaged-companion.js

@@ -1,27 +1,27 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Recognizes the one shape where the undefined-identifier hint sends the
- * operator at the wrong remedy — and where taking that remedy would MASK a
+ * operator at the wrong remedy, and where taking that remedy would mask a
  * real bug.
  *
  * The shape: helpers are hoisted out of duplicated test files into a new
  * `head_settings.js` that a managed `head.js` pulls in with
  * `loadSubScript`. Until that companion is exported it belongs to no patch,
- * so the per-patch checkJs program — which only ever loads patch-owned
- * roots — cannot see any of its declarations. Every use of every hoisted
+ * so the per-patch checkJs program, which only ever loads patch-owned
+ * roots, cannot see any of its declarations. Every use of every hoisted
  * helper is then reported as `Cannot find name`, and the generic hint
  * offers three remedies of which the shim is the easiest: adding the
- * globals to `extraShim` makes all of the warnings disappear AND makes a
+ * globals to `extraShim` makes all of the warnings disappear and makes a
  * genuinely missing helper undetectable forever after.
  *
- * The warnings themselves are correct — the per-patch program's honest view
- * of a file that is in no patch. Only the advice is wrong. FireForge
- * already knows ownership, so when every undefined name in a file is
- * declared at the top level of an UNMANAGED file that a managed head loads,
- * it can name that file and the adoption command instead.
+ * The warnings themselves are correct: they are the per-patch program's
+ * honest view of a file that is in no patch. Only the advice is wrong.
+ * FireForge already knows ownership, so when every undefined name in a file
+ * is declared at the top level of an unmanaged file that a managed head
+ * loads, it can name that file and the adoption command instead.
  *
- * Detection is deliberately conservative on both halves: a companion must
- * be reachable from an actual `loadSubScript` call, and EVERY undefined
+ * Detection is conservative on both halves: a companion must
+ * be reachable from an actual `loadSubScript` call, and every undefined
  * name must resolve inside it. One unresolved name means the file may
  * genuinely be missing a helper, and the generic hint stays.
  */
@@ -34,13 +34,13 @@ import { UNDEFINED_IDENTIFIER_HINT } from './typecheck-shim.js';
  * The mochitest idiom is
  * `Services.scriptloader.loadSubScript(getRootDirectory(gTestPath) + "head_settings.js", this)`,
  * so the useful signal is the `.js` literal inside the call, not a
- * resolvable URL — the path half is computed at runtime.
+ * resolvable URL. The path half is computed at runtime.
  */
 export function findLoadSubScriptTargets(source) {
     const targets = [];
     // Scanned to the statement terminator rather than to a closing paren:
     // the idiomatic argument is itself a call (`getRootDirectory(gTestPath) +
-    // "head_settings.js"`), so a non-greedy `\)` stops on the INNER paren and
+    // "head_settings.js"`), so a non-greedy `\)` stops on the inner paren and
     // never reaches the literal.
     for (const call of source.matchAll(/loadSubScript\s*\(/g)) {
         const from = call.index + call[0].length;
@@ -60,7 +60,7 @@ const CALL_SCAN_LIMIT = 400;
  * Top-level declaration names in a script-scope file.
  *
  * Regex rather than a TS program on purpose: this runs only to decide the
- * WORDING of a hint, the file is by definition outside every program the
+ * wording of a hint, the file is outside every program the
  * pass built, and a missed declaration degrades to the generic hint rather
  * than to a wrong answer. Matching is anchored at column zero so a nested
  * declaration inside a function body is not mistaken for a global.
@@ -93,8 +93,8 @@ function extractUndefinedIdentifier(message) {
  * Resolves the unmanaged companions reachable from a set of managed head
  * files, given a reader for repo-relative file content.
  *
- * A candidate qualifies only when it is NOT in `ownedFiles` and its content
- * can be read — an unreadable or absent target is simply not a companion,
+ * A candidate qualifies only when it is not in `ownedFiles` and its content
+ * can be read. An unreadable or absent target is simply not a companion,
  * and the generic hint applies.
  *
  * @param heads - Repo-relative managed head files, with their sources
@@ -129,10 +129,10 @@ export async function resolveUnmanagedCompanions(heads, ownedFiles, readFile) {
  * The replacement hint, when every undefined name resolves in one
  * unmanaged companion.
  *
- * States the ownership fact first (that is the diagnosis), then the
- * adoption command, and explicitly rules the shim OUT — the shim is what an
- * operator reaches for by default here, and it is the one remedy that
- * permanently hides a genuinely missing helper.
+ * States the ownership fact first (the diagnosis), then the adoption
+ * command, and explicitly rules the shim out. The shim is what an operator
+ * reaches for by default here, and it is the one remedy that permanently
+ * hides a genuinely missing helper.
  */
 export function formatUnmanagedCompanionHint(companion) {
     return (`(undefined identifier — every one of them is declared in ${companion.file}, which ` +
@@ -143,7 +143,7 @@ export function formatUnmanagedCompanionHint(companion) {
         `missing helper with them.)`);
 }
 /**
- * Picks the companion that explains EVERY undefined identifier in
+ * Picks the companion that explains every undefined identifier in
  * `messages`, or undefined when none does.
  *
  * @param messages - Diagnostic messages reported for one file
@@ -155,16 +155,16 @@ export function explainUndefinedIdentifiers(messages, companions) {
         .filter((name) => name !== undefined);
     if (names.length === 0)
         return undefined;
-    // Only the undefined-identifier diagnostics are explained here; a file
-    // carrying OTHER type errors still gets those reported untouched.
+    // Only the undefined-identifier diagnostics are explained here. A file
+    // carrying other type errors still gets those reported untouched.
     return companions.find((companion) => names.every((name) => companion.declarations.has(name)));
 }
 /**
- * Reads the head files in the owned test set and resolves the UNMANAGED
+ * Reads the head files in the owned test set and resolves the unmanaged
  * companions they pull in with `loadSubScript`. Hoisting shared helpers
  * into such a companion leaves it unowned until export, and every use of
  * every helper then reports `Cannot find name` from an honest per-patch
- * program — see `patch-lint-unmanaged-companion.ts` for why the generic
+ * program. See `patch-lint-unmanaged-companion.ts` for why the generic
  * hint is actively harmful there.
  *
  * Best-effort: an unreadable head simply contributes no companions.
@@ -195,7 +195,7 @@ export async function collectUnmanagedCompanions(repoDir, files, ownedFiles) {
 }
 /**
  * Swaps the generic undefined-identifier hint for the ownership hint when
- * one unmanaged companion explains EVERY undefined name in the file. Any
+ * one unmanaged companion explains every undefined name in the file. Any
  * other issue in the list is returned untouched.
  */
 export function retargetUnmanagedCompanionHints(issues, companions) {

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

@@ -2,11 +2,12 @@ import type { PatchLintIssue } from '../types/commands/index.js';
 import type { FireForgeConfig, ProjectLicense } from '../types/config.js';
 import { type CommentStyle } from './license-headers.js';
 import { lintPatchedCss } from './patch-lint-css.js';
-export * from './patch-lint-reexports.js';
+export * from './patch-lint-cross.js';
+export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
 export { lintPatchedCss };
 /**
- * Canonical `[check] file: message` rendering of a patch-lint issue — the
- * one string shape every reporter and refusal message uses, so operators
+ * Canonical `[check] file: message` rendering of a patch-lint issue. It is
+ * the one string shape every reporter and refusal message uses, so operators
  * can grep one format across lint output and refusal details.
  */
 export declare function formatPatchLintIssue(issue: Pick<PatchLintIssue, 'check' | 'file' | 'message'>): string;
@@ -37,27 +38,28 @@ export declare function hasBrowserChromeAssertion(strippedContent: string): bool
  */
 export declare function commentStyleForFile(file: string): CommentStyle | null;
 /**
- * Decides whether a NEW file's leading header satisfies the
- * `missing-license-header` rule. Single owner of the acceptance policy —
- * `lintNewFileHeaders` (the rule) and `autoFixLicenseHeaders` (the
+ * Decides whether a new file's leading header satisfies the
+ * `missing-license-header` rule. It is the single owner of the acceptance
+ * policy: `lintNewFileHeaders` (the rule) and `autoFixLicenseHeaders` (the
  * interactive export fixer) must agree, or the fixer offers to stack a
  * second header onto a file the lint already accepts.
  *
  * Accepted shapes, in order:
- *  - the project's own header for the file's comment style;
- *  - under `browser/branding/`, ANY recognised license header in the
+ *  - the project's own header for the file's comment style.
+ *  - under `browser/branding/`, any recognised license header in the
  *    matching style: the setup-generated branding directory is copied from
  *    Firefox's `unofficial` template and arrives with Mozilla MPL-2.0
- *    headers — legitimate for copyright purposes (the assets are Mozilla's)
- *    even when the fork's own code is 0BSD / EUPL-1.2 / GPL-2.0-or-later;
- *  - on an MPL-2.0 project, any recognised header in the matching style;
+ *    headers, legitimate for copyright purposes (the assets are Mozilla's)
+ *    even when the fork's own code is 0BSD / EUPL-1.2 / GPL-2.0-or-later.
+ *  - on an MPL-2.0 project, any recognised header in the matching style.
  *  - the verbatim upstream MPL-2.0 block header (`/* … *\/`, optionally
- *    behind a leading editor-directive comment) REGARDLESS of the project
+ *    behind a leading editor-directive comment) regardless of the project
  *    license, on any file whose comment syntax is the block form (JS and
  *    CSS): a file copied from the Firefox tree legitimately keeps Mozilla's
  *    header for provenance in an EUPL/GPL/0BSD project too. Only the block
- *    form is accepted — the `// `-style MPL header is FireForge-generated,
- *    not upstream provenance — and `hash`-style files (FTL) stay excluded
+ *    form is accepted, because the `// `-style MPL header is
+ *    FireForge-generated rather than upstream provenance, and `hash`-style
+ *    files (FTL) stay excluded
  *    because `/* … *\/` is not a comment there.
  *
  * @param file - Engine-relative path of the new file
@@ -87,7 +89,7 @@ export declare function lintNewFileHeaders(repoDir: string, newFiles: string[],
  * @param patchOwnedFiles - Optional set of patch-owned `.sys.mjs` paths for scoped JSDoc enforcement
  * @param patchOwnedChromeScripts - Optional set of patch-owned chrome
  *   subscripts (`.js` non-`.sys.mjs`) for scoped chrome-script JSDoc
- *   enforcement. Built by {@link resolvePatchOwnedChromeScripts}; passed
+ *   enforcement. Built by {@link resolvePatchOwnedChromeScripts}. Passed
  *   separately from `patchOwnedFiles` so the `runCheckJs` consumer (which
  *   only accepts `.sys.mjs`) is not silently broadened.
  * @returns Array of lint issues
@@ -120,7 +122,7 @@ export type PatchSizeTierDecision = {
  * Decides which `large-patch-lines` threshold tier applies to a patch.
  * Exported so `runPatchLint` and the per-patch `lint` command can
  * surface the tier choice to the operator *without* depending on
- * `lintPatchSize`'s internal return shape — the rule itself stays a
+ * `lintPatchSize`'s internal return shape. The rule itself stays a
  * pure issues-array API, and the decision is computed separately for
  * the sole purpose of reporting.
  *
@@ -128,25 +130,29 @@ export type PatchSizeTierDecision = {
  * The test tier beats branding because a table-driven regression test
  * is legitimately large independent of whether the patch also claims
  * branding shape, and the test-tier thresholds are already more
- * permissive than branding — so "tests beat branding" is the
+ * permissive than branding, so "tests beat branding" is the
  * defensive-for-tests choice.
  */
 export declare function resolvePatchSizeTier(filesAffected: ReadonlyArray<string>, patchTier?: 'branding'): PatchSizeTierDecision;
-/**
- * Read-only view of the size thresholds a tier enforces.
- * Public-API companion to {@link resolvePatchSizeTier} /
- * {@link countNonBinaryDiffLines} so consumers can build waiver-freshness
- * checks against the SAME numbers `large-patch-lines` /
- * `large-patch-files` fire on instead of mirroring them.
- */
-export declare function getPatchSizeThresholds(tier: 'general' | 'test' | 'branding'): {
+/** Line and file-count thresholds governing one patch-size tier. */
+export interface PatchSizeThresholds {
+    /** Added-line counts at which notice/warning/error issues fire. */
     lines: {
         notice: number;
         warning: number;
         error: number;
     };
+    /** Maximum number of files a patch may touch before an issue fires. */
     maxFiles: number;
-};
+}
+/**
+ * Read-only view of the size thresholds a tier enforces.
+ * Public-API companion to {@link resolvePatchSizeTier} /
+ * {@link countNonBinaryDiffLines} so consumers can build waiver-freshness
+ * checks against the same numbers `large-patch-lines` /
+ * `large-patch-files` fire on instead of mirroring them.
+ */
+export declare function getPatchSizeThresholds(tier: 'general' | 'test' | 'branding'): PatchSizeThresholds;
 /**
  * Checks patch size and emits advisory warnings.
  *
@@ -176,7 +182,7 @@ export declare function lintModifiedFileHeaders(repoDir: string, affectedFiles:
 export interface LintExportedPatchOptions {
     /**
      * Cross-patch context for ownership resolution. Present whenever the
-     * caller has a loaded patch queue; absent for the ad-hoc single-diff
+     * caller has a loaded patch queue. Absent for the ad-hoc single-diff
      * paths that have no queue to resolve against.
      */
     patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext;
@@ -192,7 +198,7 @@ export interface LintExportedPatchOptions {
      * Explicit tier override, threaded from `PatchMetadata.tier`. When
      * `"branding"` forces the branding thresholds on the
      * `large-patch-lines` rule. Callers with a per-patch manifest context
-     * (re-export, per-patch lint) should pass this; aggregate-mode callers
+     * (re-export, per-patch lint) should pass this. Aggregate-mode callers
      * without a specific patch context omit it and fall through to
      * auto-detection.
      */
@@ -202,12 +208,12 @@ export interface LintExportedPatchOptions {
      * The ad-hoc `fireforge lint <files>` path passes a cross-patch file
      * list that does not correspond to a single patch, so it suppresses the
      * synthetic combined-list size check here and re-evaluates the size
-     * rules per owning patch instead — never synthesising a phantom
+     * rules per owning patch instead, never synthesising a phantom
      * oversized patch from the operator's file selection.
      */
     skipPatchSize?: boolean;
     /**
-     * Restrict checkJs diagnostics to these repo-relative files; module
+     * Restrict checkJs diagnostics to these repo-relative files. Module
      * resolution still spans every owned file in `patchQueueCtx`. Export and
      * re-export pass the patch under export so cross-patch `resource:///`
      * imports resolve against the whole queue while only that patch's
@@ -216,15 +222,15 @@ export interface LintExportedPatchOptions {
     checkJsReportScope?: ReadonlySet<string>;
     /**
      * Pre-computed checkJs issues for this patch. When provided, the internal
-     * checkJs invocation is skipped and these are appended verbatim — the
+     * checkJs invocation is skipped and these are appended verbatim: the
      * per-patch lint path builds one queue-wide checkJs program and
      * attributes findings per patch instead of rebuilding per patch.
      */
     precomputedCheckJs?: readonly PatchLintIssue[];
     /**
-     * Invoked with the issues DROPPED by the `ignoreChecks` waiver filter,
-     * when any were. Suppression semantics are unchanged — the
-     * returned issue list still excludes them — but the caller can report
+     * Invoked with the issues dropped by the `ignoreChecks` waiver filter,
+     * when any were. Suppression semantics are unchanged (the returned issue
+     * list still excludes them), but the caller can report
      * the measurement a waived size finding carried (per-patch NOTICE lines
      * and the `--report` JSON) instead of losing it entirely.
      */
@@ -237,7 +243,7 @@ export interface LintExportedPatchOptions {
  * @param affectedFiles - File paths (relative to repoDir) affected by the patch
  * @param diffContent - Raw unified diff string
  * @param config - Project configuration
- * @param options - Optional context and behaviour switches; see
+ * @param options - Optional context and behaviour switches. See
  *   {@link LintExportedPatchOptions}. Every optional input lives here
  *   rather than in a positional tail: four of the five call sites had to
  *   pass `undefined` placeholders to reach the one member they wanted.

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

@@ -22,11 +22,12 @@ import { invokePatchLintPrettier } from './patch-lint-prettier.js';
 // The cross-patch lint infrastructure (queue context builder,
 // duplicate-creation and forward-import rules, ignore marker) lives in
 // `patch-lint-cross.ts` so the per-patch and cross-patch rule bodies each
-// stay within the per-file line budget. The public surface is re-exported
-// from `patch-lint-reexports.ts` so callers keep importing from one module.
-export * from './patch-lint-reexports.js';
+// stay within the per-file line budget. Its surface is re-exported here so
+// callers keep importing from one module.
+export * from './patch-lint-cross.js';
+export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
 // The CSS rule bodies live in `patch-lint-css.ts` (same per-file-budget
-// split as the other rule families); re-export the imported binding so
+// split as the other rule families). Re-export the imported binding so
 // callers and tests keep importing `lintPatchedCss` from this module.
 export { lintPatchedCss };
 // ---------------------------------------------------------------------------
@@ -47,8 +48,8 @@ function countContentLines(content) {
     return lines.length;
 }
 /**
- * Canonical `[check] file: message` rendering of a patch-lint issue — the
- * one string shape every reporter and refusal message uses, so operators
+ * Canonical `[check] file: message` rendering of a patch-lint issue. It is
+ * the one string shape every reporter and refusal message uses, so operators
  * can grep one format across lint output and refusal details.
  */
 export function formatPatchLintIssue(issue) {
@@ -94,8 +95,8 @@ const PATCH_LINE_THRESHOLDS = {
      * `browser/branding/<name>/` subtree.
      *
      * Calibrated against a fresh-fork branding export, which lands around
-     * 15–16k lines (localized brand.ftl across many locales + SVG path data +
-     * copied upstream CSS). That is the MINIMUM branding diff, so it must
+     * 15-16k lines (localized brand.ftl across many locales + SVG path data +
+     * copied upstream CSS). That is the minimum branding diff, so it must
      * surface as a soft `notice` rather than a `warning`: the warning band
      * sits above it with ~13% headroom, and the error band at roughly 2× the
      * baseline, where non-branding work is probably bundled in.
@@ -110,7 +111,7 @@ const PATCH_LINE_THRESHOLDS = {
 /**
  * File-count thresholds for the `large-patch-files` rule, mirroring the tier
  * shape of {@link PATCH_LINE_THRESHOLDS}. A single warning-only threshold
- * per tier is intentional — file count expresses scope, not blast radius,
+ * per tier is intentional: file count expresses scope, not blast radius,
  * and there is no error band that would block export.
  *
  * The branding tier sits well above the typical floor because branding
@@ -121,7 +122,7 @@ const PATCH_LINE_THRESHOLDS = {
  * genuinely bloated patch.
  *
  * Test tier matches general because a test-only patch rarely touches many
- * files (a single regression test usually adds 1–3 fixtures); the elevation
+ * files (a single regression test usually adds 1-3 fixtures). The elevation
  * in {@link PATCH_LINE_THRESHOLDS.test} addresses big table-driven test
  * bodies, not file fan-out.
  */
@@ -144,10 +145,10 @@ const SPLIT_HINT = 'Consider splitting into smaller, focused patches — ' +
  * branding patches legitimately need to touch to register the new branding
  * flavor with the top-level configure. A predicate requiring every file to
  * live under `browser/branding/` drops a branding patch that also touches
- * `browser/moz.configure` — the canonical registration point — into the
+ * `browser/moz.configure` (the canonical registration point) into the
  * general lint tier.
  *
- * Intentionally narrow: add entries only when a genuine branding patch
+ * Narrow on purpose: add entries only when a genuine branding patch
  * cannot be expressed without a specific registration sibling. Pinned
  * against ESR 140.x conventions at time of writing.
  */
@@ -158,7 +159,7 @@ const BRANDING_REGISTRATION_FILES = new Set([
 /**
  * Returns true when a patch qualifies for the branding threshold tier:
  * every file lives either under `browser/branding/` or in the narrow
- * registration allowlist, AND the patch contains at least one file
+ * registration allowlist, and the patch contains at least one file
  * under `browser/branding/` (guard against a config-only patch
  * accidentally qualifying as branding).
  *
@@ -200,7 +201,7 @@ export function isTestFile(file) {
     return /^(?:browser_|test_|xpcshell_).*\.js$/.test(basename);
 }
 /**
- * Narrower scope than `isTestFile` — only browser-chrome test files
+ * Narrower scope than `isTestFile`: only browser-chrome test files
  * (`browser_*.js` under a `/test/` or `/tests/` directory). Excludes
  * `head.js` and `head_*.js` test helpers.
  */
@@ -220,28 +221,29 @@ function isBrowserChromeTestFile(file) {
  * Each alternative must sit at a call boundary: preceded by something that
  * is not an identifier character, `.`, `#`, or `-`. A plain
  * `strippedContent.includes(tok)` over `Assert.`, `ok(`, `is(`, `isnot(`,
- * `isDeeply(` lets any identifier merely *ending* in one satisfy the gate —
- * `this.axis(3)` contains `is(`, `book(` contains `ok(`,
- * `promiseIsDeeply(` contains `isDeeply(` — so an assertion-free smoke test
+ * `isDeeply(` lets any identifier merely *ending* in one satisfy the gate:
+ * `this.axis(3)` contains `is(`, `book(` contains `ok(`, and
+ * `promiseIsDeeply(` contains `isDeeply(`, so an assertion-free smoke test
  * using any such call clears the floor.
  *
- * The namespaced arm must name a member AND a call. Matching the namespace
+ * The namespaced arm must name a member and a call. Matching the namespace
  * and its dot alone re-opens the same hole from the other side:
  * `SimpleTest` is mostly *harness* API, so `SimpleTest.finish()`,
  * `SimpleTest.waitForExplicitFinish()` and `SimpleTest.requestCompleteLog()`
- * would each clear the floor on their own — the exact calls an
+ * would each clear the floor on their own, which are the exact calls an
  * assertion-free smoke test contains. The enumeration below is the
  * mochitest/xpcshell assertion surface both namespaces share, and it is what
  * the user-facing message names.
  *
  * Two qualified spellings of the bare four also count: `window.ok(...)` (the
- * globals ARE window properties) and an optional-chained `win?.ok(...)`;
- * blocking those flags tests whose only assertions are real as
- * assertion-free. `SpecialPowers.ok(` stays excluded — that is API surface,
+ * globals are window properties) and an optional-chained `win?.ok(...)`.
+ * Blocking those flags tests whose only assertions are real as
+ * assertion-free. `SpecialPowers.ok(` stays excluded: that is API surface,
  * not an assertion.
  *
- * Deliberately textual, not AST-based: this runs over patch bodies rather
- * than resolvable sources, and the surrounding rule is a floor, not a proof.
+ * Textual rather than AST-based, on purpose: this runs over patch bodies
+ * rather than resolvable sources, and the surrounding rule is a floor, not
+ * a proof.
  */
 const ASSERTION_MEMBERS = [
     'ok',
@@ -262,7 +264,7 @@ const ASSERTION_MEMBERS = [
     'stringContains',
     'throws',
     'rejects',
-    // `todo`, `todo_is`, `todo_isnot`, `info`-free — todo* record an expected
+    // `todo`, `todo_is`, `todo_isnot`, `info`-free: todo* record an expected
     // failure, which is still a recorded assertion outcome.
     'todo',
     'todo_is',
@@ -289,27 +291,28 @@ export function commentStyleForFile(file) {
 // License header lint
 // ---------------------------------------------------------------------------
 /**
- * Decides whether a NEW file's leading header satisfies the
- * `missing-license-header` rule. Single owner of the acceptance policy —
- * `lintNewFileHeaders` (the rule) and `autoFixLicenseHeaders` (the
+ * Decides whether a new file's leading header satisfies the
+ * `missing-license-header` rule. It is the single owner of the acceptance
+ * policy: `lintNewFileHeaders` (the rule) and `autoFixLicenseHeaders` (the
  * interactive export fixer) must agree, or the fixer offers to stack a
  * second header onto a file the lint already accepts.
  *
  * Accepted shapes, in order:
- *  - the project's own header for the file's comment style;
- *  - under `browser/branding/`, ANY recognised license header in the
+ *  - the project's own header for the file's comment style.
+ *  - under `browser/branding/`, any recognised license header in the
  *    matching style: the setup-generated branding directory is copied from
  *    Firefox's `unofficial` template and arrives with Mozilla MPL-2.0
- *    headers — legitimate for copyright purposes (the assets are Mozilla's)
- *    even when the fork's own code is 0BSD / EUPL-1.2 / GPL-2.0-or-later;
- *  - on an MPL-2.0 project, any recognised header in the matching style;
+ *    headers, legitimate for copyright purposes (the assets are Mozilla's)
+ *    even when the fork's own code is 0BSD / EUPL-1.2 / GPL-2.0-or-later.
+ *  - on an MPL-2.0 project, any recognised header in the matching style.
  *  - the verbatim upstream MPL-2.0 block header (`/* … *\/`, optionally
- *    behind a leading editor-directive comment) REGARDLESS of the project
+ *    behind a leading editor-directive comment) regardless of the project
  *    license, on any file whose comment syntax is the block form (JS and
  *    CSS): a file copied from the Firefox tree legitimately keeps Mozilla's
  *    header for provenance in an EUPL/GPL/0BSD project too. Only the block
- *    form is accepted — the `// `-style MPL header is FireForge-generated,
- *    not upstream provenance — and `hash`-style files (FTL) stay excluded
+ *    form is accepted, because the `// `-style MPL header is
+ *    FireForge-generated rather than upstream provenance, and `hash`-style
+ *    files (FTL) stay excluded
  *    because `/* … *\/` is not a comment there.
  *
  * @param file - Engine-relative path of the new file
@@ -373,7 +376,7 @@ export async function lintNewFileHeaders(repoDir, newFiles, config) {
  * @param patchOwnedFiles - Optional set of patch-owned `.sys.mjs` paths for scoped JSDoc enforcement
  * @param patchOwnedChromeScripts - Optional set of patch-owned chrome
  *   subscripts (`.js` non-`.sys.mjs`) for scoped chrome-script JSDoc
- *   enforcement. Built by {@link resolvePatchOwnedChromeScripts}; passed
+ *   enforcement. Built by {@link resolvePatchOwnedChromeScripts}. Passed
  *   separately from `patchOwnedFiles` so the `runCheckJs` consumer (which
  *   only accepts `.sys.mjs`) is not silently broadened.
  * @returns Array of lint issues
@@ -447,7 +450,7 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
         const chromeMode = config.patchLint?.chromeScriptJsDoc;
         issues.push(...lintChromeScriptJsDocForFile(file, content, isChromeOwned, chromeMode));
         // 3b. Assertion floor for browser-chrome tests touched by this patch
-        // (covers both newly introduced files and modified upstream tests —
+        // (covers both newly introduced files and modified upstream tests:
         // a patch that strips the last `Assert.equal` from an existing
         // browser_*.js silently passed under the old `isNew` gate).
         const assertionFloor = config.patchLint?.testAssertionFloor;
@@ -505,7 +508,7 @@ export function lintModificationComments(diffContent, config) {
  * Decides which `large-patch-lines` threshold tier applies to a patch.
  * Exported so `runPatchLint` and the per-patch `lint` command can
  * surface the tier choice to the operator *without* depending on
- * `lintPatchSize`'s internal return shape — the rule itself stays a
+ * `lintPatchSize`'s internal return shape. The rule itself stays a
  * pure issues-array API, and the decision is computed separately for
  * the sole purpose of reporting.
  *
@@ -513,7 +516,7 @@ export function lintModificationComments(diffContent, config) {
  * The test tier beats branding because a table-driven regression test
  * is legitimately large independent of whether the patch also claims
  * branding shape, and the test-tier thresholds are already more
- * permissive than branding — so "tests beat branding" is the
+ * permissive than branding, so "tests beat branding" is the
  * defensive-for-tests choice.
  */
 export function resolvePatchSizeTier(filesAffected, patchTier) {
@@ -530,7 +533,7 @@ export function resolvePatchSizeTier(filesAffected, patchTier) {
  * Read-only view of the size thresholds a tier enforces.
  * Public-API companion to {@link resolvePatchSizeTier} /
  * {@link countNonBinaryDiffLines} so consumers can build waiver-freshness
- * checks against the SAME numbers `large-patch-lines` /
+ * checks against the same numbers `large-patch-lines` /
  * `large-patch-files` fire on instead of mirroring them.
  */
 export function getPatchSizeThresholds(tier) {
@@ -557,7 +560,7 @@ export function lintPatchSize(filesAffected, lineCount, patchTier) {
     // thresholds because a big regression test is legitimate (table-driven
     // harnesses run into the thousands of lines). Branding patches get their
     // own tier so a first export of setup-generated branding does not fire the
-    // general hard limit — see `PATCH_LINE_THRESHOLDS.branding` and
+    // general hard limit. See `PATCH_LINE_THRESHOLDS.branding` and
     // `PATCH_FILES_THRESHOLDS.branding` above. An explicit `patchTier` opt-in
     // forces branding even when `isBrandingOnlyPatch` cannot reach the patch's
     // actual shape (a branding patch that also touches a non-allowlisted
@@ -653,7 +656,7 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
  * @param affectedFiles - File paths (relative to repoDir) affected by the patch
  * @param diffContent - Raw unified diff string
  * @param config - Project configuration
- * @param options - Optional context and behaviour switches; see
+ * @param options - Optional context and behaviour switches. See
  *   {@link LintExportedPatchOptions}. Every optional input lives here
  *   rather than in a positional tail: four of the five call sites had to
  *   pass `undefined` placeholders to reach the one member they wanted.
@@ -687,7 +690,7 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     ];
     if (options?.precomputedCheckJs) {
         // Per-patch lint built one queue-wide program and already attributed
-        // this patch's findings — append them instead of rebuilding the program.
+        // this patch's findings, so append them instead of rebuilding the program.
         issues.push(...options.precomputedCheckJs);
     }
     else if (config.patchLint?.checkJs) {
@@ -704,10 +707,10 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
             }
         }
     }
-    // Prettier over patch-owned .sys.mjs. Deliberately NOT part of the
-    // precomputedCheckJs short-circuit: it is a separate tool with its own
-    // gate, and a queue-wide program has no equivalent to share. Scoped to
-    // the files THIS patch owns, run from engine/ so the engine's own config
+    // Prettier over patch-owned .sys.mjs. Kept out of the
+    // precomputedCheckJs short-circuit on purpose: it is a separate tool with
+    // its own gate, and a queue-wide program has no equivalent to share.
+    // Scoped to the files this patch owns, run from engine/ so its own config
     // and ignore file decide (see `patch-lint-prettier.ts`).
     const prettierGate = config.patchLint?.prettier ?? 'off';
     if (prettierGate !== 'off' && patchOwnedFiles.size > 0) {
@@ -716,7 +719,7 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     }
     // Filter out ignored checks last so every rule still runs (keeps the
     // implementation uniform) but suppressed rules do not surface. We do not
-    // reclassify severities — an ignored error simply drops, mirroring how
+    // reclassify severities: an ignored error simply drops, mirroring how
     // inline `fireforge-ignore: <check>` markers work in the CSS and
     // forward-import rules.
     if (ignoreChecks && ignoreChecks.size > 0) {

package/dist/src/core/patch-lock.d.ts

@@ -23,7 +23,7 @@ export interface PatchDirectoryLockOptions {
  * is held, so an unlocked caller silently reintroduces the interleaving the
  * lock exists to prevent.
  *
- * Fail-open on an unreadable owner record, deliberately: `withFileLock`
+ * Fail-open on an unreadable owner record, on purpose: `withFileLock`
  * treats writing that record as non-fatal, so a live holder can legitimately
  * have no readable PID and asserting on its presence would fire on a lock we
  * really do hold.