@hominis/fireforge 0.46.0 → 0.46.1

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

@@ -6,15 +6,15 @@ import { walk } from 'estree-walker';
  * `acorn.parse` produces nodes that carry both the ESTree shape and
  * `start`/`end` offsets at runtime, but its static `acorn.Program` type is
  * nominally distinct from `estree.Program`, so the compiler cannot verify
- * the conversion structurally — hence the double assertion. This helper is
- * the single sanctioned crossing point between the two type worlds.
+ * the conversion structurally, hence the double assertion. This helper is the
+ * only sanctioned crossing point between the two types.
  */
 function toPositionedProgram(program) {
     // eslint-disable-next-line no-restricted-syntax -- the sanctioned acorn→estree bridge this rule's message points at
     return program;
 }
 /**
- * Parse JavaScript source as a **script** (not an ES module).
+ * Parse JavaScript source as a script, not an ES module.
  * All Mozilla chrome JS files (`browser-main.js`, `browser-init.js`,
  * `customElements.js`, etc.) are scripts that run in a privileged scope.
  *
@@ -32,7 +32,7 @@ export function parseScript(content, onComment) {
     return toPositionedProgram(acorn.parse(content, opts));
 }
 /**
- * Parse JavaScript source as an **ES module**.
+ * Parse JavaScript source as an ES module.
  * Used for `.sys.mjs` files which use static import/export syntax.
  *
  * @param content - Source text to parse
@@ -53,12 +53,12 @@ export function parseModule(content, onComment) {
  * Convenience cast from `acorn.Node` (or the generic ESTree union returned
  * by estree-walker callbacks) to a positioned, narrowly-typed node.
  *
- * **Caller obligation: you must already have discriminated on `node.type`.**
- * This performs no runtime check — it exists to attach acorn's `start`/`end`
- * offsets to a node the caller has *already* narrowed, typically inside an
+ * Caller obligation: you must already have discriminated on `node.type`.
+ * This performs no runtime check. It exists to attach acorn's `start`/`end`
+ * offsets to a node the caller has already narrowed, typically inside an
  * `if (node.type === 'CallExpression')` branch or an equivalent walker
  * guard. Calling it on an undiscriminated node produces a value whose type
- * is a lie.
+ * is wrong.
  *
  * No runtime `type` assertion: every call site sits in the hot loop of a lint
  * or registration walker and is already post-narrowing, so the check would

package/dist/src/core/branding.d.ts

@@ -3,12 +3,12 @@ import type { ProjectLicense } from '../types/config.js';
 /**
  * Error thrown when the generated `mozconfig` references a `--with-branding`
  * directory that does not match the branding tree FireForge set up. The
- * mismatch is a silent-corruption hazard — `mach configure` picks the value
+ * mismatch is a silent-corruption hazard: `mach configure` picks the value
  * from mozconfig but the scaffolded branding lives elsewhere, so the build
  * fails deep inside moz.build resolution with a confusing "path does not
  * exist" message. Surface it as an actionable preflight instead.
  *
- * Setup renders templates under `configs/` with `${binaryName}` baked in; a
+ * Setup renders templates under `configs/` with `${binaryName}` baked in. A
  * later edit to `fireforge.json`'s `binaryName` (or a re-setup without
  * re-templating) leaves those names stale while `setupBranding` keeps using
  * the current value. Both directions produce the same class of build break.
@@ -37,8 +37,8 @@ export interface BrandingConfig {
      * Project license (from fireforge.json). Used to stamp the generated
      * `configure.sh`, `brand.properties`, and `brand.ftl` files with the
      * matching header so `patch-lint` does not flag them for
-     * `missing-license-header` when the project is not MPL-2.0. Optional;
-     * falls back to {@link DEFAULT_LICENSE}.
+     * `missing-license-header` when the project is not MPL-2.0. Optional.
+     * Falls back to {@link DEFAULT_LICENSE}.
      */
     license?: ProjectLicense;
 }
@@ -47,7 +47,7 @@ export interface BrandingConfig {
  * `toolkit/moz.configure` composes `CFBundleIdentifier` as
  * `<--with-distribution-id>.<MOZ_MACBUNDLE_ID>` (the distribution id
  * defaults to `org.mozilla`), so branding `configure.sh` must carry only the
- * LEAF segment while the generated mozconfig carries the remainder as
+ * leaf segment while the generated mozconfig carries the remainder as
  * `--with-distribution-id`. Writing the full appId into `MOZ_MACBUNDLE_ID`
  * double-prefixes the shipped bundle id. Config validation guarantees a
  * reverse-domain id, so the split always has both halves.

package/dist/src/core/branding.js

@@ -18,12 +18,12 @@ class BrandingError extends FireForgeError {
 /**
  * Error thrown when the generated `mozconfig` references a `--with-branding`
  * directory that does not match the branding tree FireForge set up. The
- * mismatch is a silent-corruption hazard — `mach configure` picks the value
+ * mismatch is a silent-corruption hazard: `mach configure` picks the value
  * from mozconfig but the scaffolded branding lives elsewhere, so the build
  * fails deep inside moz.build resolution with a confusing "path does not
  * exist" message. Surface it as an actionable preflight instead.
  *
- * Setup renders templates under `configs/` with `${binaryName}` baked in; a
+ * Setup renders templates under `configs/` with `${binaryName}` baked in. A
  * later edit to `fireforge.json`'s `binaryName` (or a re-setup without
  * re-templating) leaves those names stale while `setupBranding` keeps using
  * the current value. Both directions produce the same class of build break.
@@ -57,7 +57,7 @@ export class BrandingMozconfigMismatchError extends FireForgeError {
  * `toolkit/moz.configure` composes `CFBundleIdentifier` as
  * `<--with-distribution-id>.<MOZ_MACBUNDLE_ID>` (the distribution id
  * defaults to `org.mozilla`), so branding `configure.sh` must carry only the
- * LEAF segment while the generated mozconfig carries the remainder as
+ * leaf segment while the generated mozconfig carries the remainder as
  * `--with-distribution-id`. Writing the full appId into `MOZ_MACBUNDLE_ID`
  * double-prefixes the shipped bundle id. Config validation guarantees a
  * reverse-domain id, so the split always has both halves.

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

@@ -30,7 +30,7 @@ export interface WireOptions {
      * replacement path here.
      */
     domTargetPath?: string | undefined;
-    /** Dry run — don't write any files */
+    /** Dry run: don't write any files */
     dryRun?: boolean | undefined;
     /** Insert init block after the block containing this name */
     after?: string | undefined;

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

@@ -86,9 +86,9 @@ export async function wireSubscript(root, name, options = {}) {
         let initAdded = false;
         if (options.init) {
             // The snapshot above is taken when init or destroy is `!== undefined`
-            // while these writes fire on truthiness — close, but two separate
-            // conditions over the same file, which is exactly the pairing that
-            // drifts when a third writer is added later.
+            // while these writes fire on truthiness. Close, but two separate
+            // conditions over the same file, and that kind of pairing drifts when
+            // a third writer is added later.
             assertSnapshotted(journal, join(engineDir, 'browser/base/content/browser-init.js'), 'browser wire init');
             initAdded = await addInitToBrowserInit(engineDir, options.init, options.after, marker);
         }
@@ -119,7 +119,7 @@ export async function wireSubscript(root, name, options = {}) {
         // original wire failure and the rollback failure so the operator knows
         // the engine may be in a partially-wired state that needs manual
         // attention. The original error's message is preserved so the user sees
-        // *why* the wire failed (e.g. "Could not find insertion point in chrome
+        // why the wire failed (e.g. "Could not find insertion point in chrome
         // document") alongside any rollback diagnosis.
         const originalMessage = toError(error).message;
         try {

package/dist/src/core/build-audit-platform.d.ts

@@ -25,10 +25,10 @@ export declare function findEnclosingGate(content: string, basename: string): st
 /**
  * Determines whether the given source file is gated off on the current
  * host by an enclosing `if CONFIG[...]:` block in its owning moz.build,
- * OR by a path-convention rule for installer-tree subdirectories that
+ * or by a path-convention rule for installer-tree subdirectories that
  * are packaged via Makefile.in recipes the audit does not parse.
- * Returns `gatedOff: false` and no expression when no gate is found —
- * the file is not platform-restricted, so the caller should audit it
+ * Returns `gatedOff: false` and no expression when no gate is found. The
+ * file is not platform-restricted, so the caller should audit it
  * normally.
  *
  * @param engineDir Absolute path to the engine root
@@ -48,8 +48,8 @@ export interface AncestorDirsGateResult {
     gateFile?: string;
 }
 /**
- * Determines whether the source file's DIRECTORY is excluded from this
- * build by a gate in an ANCESTOR `moz.build`.
+ * Determines whether the source file's directory is excluded from this
+ * build by a gate in an ancestor `moz.build`.
  *
  * `detectPlatformGate` reads only the file's own nearest `moz.build`, which
  * misses the common Firefox shape where the whole subtree is reached
@@ -57,7 +57,7 @@ export interface AncestorDirsGateResult {
  * `toolkit/mozapps/defaultagent/moz.build` says "Windows only", yet none of
  * it is built on macOS.
  *
- * Errs toward NOT skipping, like the rest of this module: an unreadable or
+ * Errs toward not skipping, like the rest of this module: an unreadable or
  * oversized ancestor, or a directory no `DIRS` entry names, yields
  * `gatedOff: false`.
  *

package/dist/src/core/build-audit-platform.js

@@ -6,27 +6,27 @@
  * `if CONFIG["MAKENSISU"]:` (Windows-only stubinstaller) or
  * `if CONFIG["OS_TARGET"] == "Darwin":` (macOS-only artwork). On a host that
  * does not match the gate, the wrapped files are never processed by the
- * build, so they cannot appear under `dist/` — without this detection the
+ * build, so they cannot appear under `dist/`. Without this detection the
  * audit warns about every gated file on every off-platform build.
  *
  * Two gate sources are consulted, in order:
  *   1. Python-style `if CONFIG[...]:` blocks in the owning `moz.build`.
- *   2. Path-convention gates — certain directory fragments are packaged by
+ *   2. Path-convention gates: certain directory fragments are packaged by
  *      platform-specific Makefile.in / NSIS recipes that FireForge does not
  *      parse, so a file under `browser/installer/windows/` or any
  *      `/stubinstaller/` subtree is Windows-only regardless of what its
  *      nearest moz.build says.
  *
- * The detection is intentionally lightweight: walk up from the source file
+ * The detection is lightweight: walk up from the source file
  * to the closest `moz.build`, scan it for the source basename inside an
  * `if CONFIG[...]:` block, and check whether the gate matches the host. The
  * path-convention pass runs only when no moz.build gate is found, so an
  * explicit gate always wins.
  *
- * Best-effort by design. False negatives (missing a gate and warning anyway)
- * are tolerable — the audit is warn-only. False positives (skipping a file
- * that should ship on this host) are not, so it errs toward NOT skipping
- * when uncertain.
+ * Best-effort. False negatives (missing a gate and warning anyway) are
+ * tolerable because the audit is warn-only. False positives (skipping a file
+ * that should ship on this host) are not tolerable, so it errs toward not
+ * skipping when uncertain.
  */
 import { stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
@@ -35,7 +35,7 @@ import { getPlatform } from '../utils/platform.js';
 import { escapeRegex } from '../utils/regex.js';
 /**
  * Tokens that uniquely identify a Windows-only `if CONFIG[...]:` block.
- * `MAKENSISU` is the Windows stubinstaller compiler; `OS_TARGET ==
+ * `MAKENSISU` is the Windows stubinstaller compiler. `OS_TARGET ==
  * "WINNT"` and `MOZ_WIDGET_TOOLKIT == "windows"` are the conventional
  * platform discriminators.
  */
@@ -53,7 +53,7 @@ function isGateOffHost(expression, host) {
     const matchesDarwin = DARWIN_ONLY_GATE_TOKENS.some((t) => expression.includes(t));
     const matchesLinux = LINUX_ONLY_GATE_TOKENS.some((t) => expression.includes(t));
     // Negation gates (`!= "WINNT"`, `not CONFIG["MAKENSISU"]`) flip the
-    // semantics. Keep this conservative — if we cannot confidently parse
+    // semantics. Keep this conservative: if we cannot confidently parse
     // a negation, return false so we don't wrongly suppress a warning.
     const negated = /\bnot\b|!=/.test(expression);
     if (negated)
@@ -69,7 +69,7 @@ function isGateOffHost(expression, host) {
 /**
  * Walks from a starting directory up to (but not above) the engine root,
  * yielding the first `moz.build` encountered. Returns undefined when no
- * ancestor has one — typically only for files that live above any
+ * ancestor has one, typically only for files that live above any
  * moz.build entry point, which would not be packageable anyway.
  */
 async function findOwningMozBuild(engineDir, sourceDir) {
@@ -185,10 +185,10 @@ function findPathConventionGate(sourcePath) {
 /**
  * Determines whether the given source file is gated off on the current
  * host by an enclosing `if CONFIG[...]:` block in its owning moz.build,
- * OR by a path-convention rule for installer-tree subdirectories that
+ * or by a path-convention rule for installer-tree subdirectories that
  * are packaged via Makefile.in recipes the audit does not parse.
- * Returns `gatedOff: false` and no expression when no gate is found —
- * the file is not platform-restricted, so the caller should audit it
+ * Returns `gatedOff: false` and no expression when no gate is found. The
+ * file is not platform-restricted, so the caller should audit it
  * normally.
  *
  * @param engineDir Absolute path to the engine root
@@ -235,7 +235,7 @@ export async function detectPlatformGate(engineDir, sourcePath) {
 /**
  * Maximum ancestor levels walked looking for a gating `DIRS` entry, and the
  * largest `moz.build` read while doing it. The audit runs on every build, so
- * a pathological tree must not be able to make it slow; beyond these bounds
+ * a pathological tree must not be able to make it slow. Beyond these bounds
  * the walk gives up and the caller keeps today's behaviour (warn).
  */
 const MAX_ANCESTOR_DEPTH = 12;
@@ -243,21 +243,21 @@ const MAX_MOZ_BUILD_BYTES = 256 * 1024;
 /** Matches a line that begins a `DIRS` assignment. */
 const DIRS_ASSIGNMENT_PATTERN = /^\s*DIRS\s*\+?=/;
 /**
- * Collects the FULL stack of `if CONFIG[…]:` expressions enclosing the
+ * Collects the full stack of `if CONFIG[…]:` expressions enclosing the
  * `DIRS` entry whose value equals `relDir`.
  *
  * Two differences from {@link findEnclosingGate}, both load-bearing here:
  * only quoted values inside a `DIRS` assignment are considered (an
  * unrelated string literal elsewhere in the file must not gate a
- * directory), and EVERY enclosing expression is returned rather than the
- * innermost. Firefox nests these — `toolkit/moz.build` reaches
+ * directory), and every enclosing expression is returned rather than the
+ * innermost. Firefox nests these: `toolkit/moz.build` reaches
  * `mozapps/defaultagent` inside `OS_ARCH == "WINNT"`, then a `CC_TYPE`
- * test, then `MOZ_DEFAULT_BROWSER_AGENT` — and it is the OUTERMOST one that
+ * test, then `MOZ_DEFAULT_BROWSER_AGENT`, and it is the outermost one that
  * excludes the directory on a macOS host.
  *
  * @param content - `moz.build` file content
  * @param relDir - Directory path relative to the `moz.build`, POSIX-separated
- * @returns Enclosing gate expressions, outermost first; empty when ungated
+ * @returns Enclosing gate expressions, outermost first. Empty when ungated
  *   or when no `DIRS` entry reaches `relDir`
  */
 function findDirsEntryGates(content, relDir) {
@@ -283,7 +283,7 @@ function findDirsEntryGates(content, relDir) {
             continue;
         }
         if (DIRS_ASSIGNMENT_PATTERN.test(line)) {
-            // A `DIRS += [` list body continues on later lines; a single-line
+            // A `DIRS += [` list body continues on later lines. A single-line
             // `DIRS += ["x"]` is fully handled by the match below.
             inDirs = !line.includes(']');
             if (dirsLineNames(line, relDir))
@@ -305,8 +305,8 @@ function dirsLineNames(line, relDir) {
     return new RegExp(`["']${escaped}\\/?["']`).test(line);
 }
 /**
- * Determines whether the source file's DIRECTORY is excluded from this
- * build by a gate in an ANCESTOR `moz.build`.
+ * Determines whether the source file's directory is excluded from this
+ * build by a gate in an ancestor `moz.build`.
  *
  * `detectPlatformGate` reads only the file's own nearest `moz.build`, which
  * misses the common Firefox shape where the whole subtree is reached
@@ -314,7 +314,7 @@ function dirsLineNames(line, relDir) {
  * `toolkit/mozapps/defaultagent/moz.build` says "Windows only", yet none of
  * it is built on macOS.
  *
- * Errs toward NOT skipping, like the rest of this module: an unreadable or
+ * Errs toward not skipping, like the rest of this module: an unreadable or
  * oversized ancestor, or a directory no `DIRS` entry names, yields
  * `gatedOff: false`.
  *
@@ -330,7 +330,7 @@ export async function detectAncestorDirsGate(engineDir, sourcePath) {
         return { gatedOff: false };
     }
     const segments = sourcePath.split('/').filter(Boolean);
-    // Drop the basename: the walk is over DIRECTORIES.
+    // Drop the basename: the walk is over directories.
     segments.pop();
     const root = engineDir.replace(/[/\\]+$/, '');
     const depth = Math.min(segments.length, MAX_ANCESTOR_DEPTH);
@@ -365,8 +365,8 @@ export async function detectAncestorDirsGate(engineDir, sourcePath) {
                 gateFile: [...ancestorSegments, 'moz.build'].join('/'),
             };
         }
-        // The directory IS reached from here and this host passes every gate;
-        // a further ancestor cannot un-reach it.
+        // The directory is reached from here and this host passes every gate.
+        // A further ancestor cannot un-reach it.
         return { gatedOff: false };
     }
     return { gatedOff: false };

package/dist/src/core/build-audit-registration.d.ts

@@ -32,7 +32,7 @@ export declare function parseJarMnEntry(line: string): {
 /**
  * Scans a jar.mn file's contents for an entry whose source reference
  * matches `relativeSource` (POSIX, relative to the jar.mn directory).
- * Returns the first match; jar.mn enforces uniqueness of `(source)` in
+ * Returns the first match. jar.mn enforces uniqueness of `(source)` in
  * practice, so a first-match wins behaviour is adequate.
  */
 export declare function findJarMnEntryForSource(content: string, relativeSource: string): {
@@ -44,14 +44,14 @@ export declare function findJarMnEntryForSource(content: string, relativeSource:
  * the first jar.mn entry that registers the given source. Returns undefined
  * when no ancestor jar.mn claims the source.
  *
- * @param engineDir Absolute engine root; walk halts here.
+ * @param engineDir Absolute engine root. The walk halts here.
  * @param source Engine-relative POSIX source path.
  */
 export declare function findRegisteredTarget(engineDir: string, source: string): Promise<RegistrationHit | undefined>;
 /**
  * Probes the dist tree for the artifact registered against the given
  * source. Returns the matched candidate and the registration hit that
- * anchored it; undefined when the source has no owning jar.mn or when
+ * anchored it. Undefined when the source has no owning jar.mn or when
  * no same-basename candidate under the search roots ends with the
  * registered target path.
  *
@@ -69,8 +69,8 @@ export declare function findRegisteredTarget(engineDir: string, source: string):
 export declare function resolveArtifactByRegistration(engineDir: string, source: string, searchRoots: readonly string[]): Promise<RegistrationProbeResult | undefined>;
 /**
  * Returns the absolute paths of every same-basename candidate under the
- * given search roots. Used by the audit to enumerate ALL false-match
- * candidates when the heuristic fallback downgrades to "missing" — the
+ * given search roots. Used by the audit to enumerate all false-match
+ * candidates when the heuristic fallback downgrades to "missing". The
  * operator needs to see the full set, not just the scorer's pick, to
  * distinguish a registration bug from a genuine packaging drop.
  *

package/dist/src/core/build-audit-registration.js

@@ -18,7 +18,7 @@
  * report an unambiguous "registered but not packaged" miss when none exists.
  *
  * When no jar.mn registration is found, the caller falls back to the
- * similarity heuristic — which covers sources registered through moz.build
+ * similarity heuristic, which covers sources registered through moz.build
  * (`FINAL_TARGET_FILES`, `JS_PREFERENCE_FILES`) or `package-manifest.in`.
  * Parsing every Firefox registration surface would bloat the audit, and the
  * heuristic's weak case is surfaced to the operator in the warning copy.
@@ -62,7 +62,7 @@ export function parseJarMnEntry(line) {
 /**
  * Scans a jar.mn file's contents for an entry whose source reference
  * matches `relativeSource` (POSIX, relative to the jar.mn directory).
- * Returns the first match; jar.mn enforces uniqueness of `(source)` in
+ * Returns the first match. jar.mn enforces uniqueness of `(source)` in
  * practice, so a first-match wins behaviour is adequate.
  */
 export function findJarMnEntryForSource(content, relativeSource) {
@@ -81,7 +81,7 @@ export function findJarMnEntryForSource(content, relativeSource) {
  * the first jar.mn entry that registers the given source. Returns undefined
  * when no ancestor jar.mn claims the source.
  *
- * @param engineDir Absolute engine root; walk halts here.
+ * @param engineDir Absolute engine root. The walk halts here.
  * @param source Engine-relative POSIX source path.
  */
 export async function findRegisteredTarget(engineDir, source) {
@@ -98,7 +98,7 @@ export async function findRegisteredTarget(engineDir, source) {
                 content = await readText(jarMn);
             }
             catch {
-                // An unreadable jar.mn contributes no registration hints; the resolver falls
+                // An unreadable jar.mn contributes no registration hints. The resolver falls
                 // through to its other strategies.
                 content = '';
             }
@@ -127,7 +127,7 @@ function toPosix(path) {
 /**
  * Probes the dist tree for the artifact registered against the given
  * source. Returns the matched candidate and the registration hit that
- * anchored it; undefined when the source has no owning jar.mn or when
+ * anchored it. Undefined when the source has no owning jar.mn or when
  * no same-basename candidate under the search roots ends with the
  * registered target path.
  *
@@ -162,8 +162,8 @@ export async function resolveArtifactByRegistration(engineDir, source, searchRoo
 }
 /**
  * Returns the absolute paths of every same-basename candidate under the
- * given search roots. Used by the audit to enumerate ALL false-match
- * candidates when the heuristic fallback downgrades to "missing" — the
+ * given search roots. Used by the audit to enumerate all false-match
+ * candidates when the heuristic fallback downgrades to "missing". The
  * operator needs to see the full set, not just the scorer's pick, to
  * distinguish a registration bug from a genuine packaging drop.
  *

package/dist/src/core/build-audit-resolve.d.ts

@@ -1,5 +1,5 @@
 /**
- * Heuristic test for "this looks like a packaged-test source file" — the
+ * Heuristic test for "this looks like a packaged-test source file". The
  * audit routes such paths to `_tests/` instead of `dist/`. Matches
  * mochitest / xpcshell / browser-chrome conventions: any source under a
  * `/test/` or `/tests/` directory, anywhere under a `testing/` subtree
@@ -27,7 +27,7 @@ export declare function countTrailingSegmentMatches(a: string, b: string): numbe
 /**
  * Path segments too common to identify an artifact on their own.
  *
- * Shared deliberately: this set governs two halves of ONE decision —
+ * Shared on purpose: this set governs two halves of one decision,
  * `scoreCandidate` (selection) and `isConfidentMatch` (confirmation, in
  * `build-audit.ts`). When the halves kept separate copies they disagreed,
  * so a source path could earn a selection bonus for a segment that
@@ -44,14 +44,14 @@ export declare const GENERIC_PATH_SEGMENTS: ReadonlySet<string>;
  *
  * The bonus exists because Firefox packaging often re-roots files: a source
  * `branding/<name>/content/aboutDialog.css` lands at
- * `chrome/browser/content/branding/aboutDialog.css` — only the basename
+ * `chrome/browser/content/branding/aboutDialog.css`. Only the basename
  * trails-match, but the `branding` segment moved into the middle of the
  * candidate path. Without the bonus that candidate ties with the unrelated
  * `chrome/browser/content/browser/aboutDialog.css`.
  *
  * @param sourcePath Engine-relative POSIX path
  * @param candidatePath Absolute path under the dist tree
- * @returns Numeric score; higher means better match
+ * @returns Numeric score, where higher means better match
  */
 export declare function scoreCandidate(sourcePath: string, candidatePath: string): number;
 /**
@@ -69,7 +69,7 @@ export declare function findAllByBasename(root: string, name: string, maxDepth?:
 /**
  * Resolves the best-matching artifact for a source path under one or
  * more search roots. Returns the highest-scoring candidate by trailing
- * segment overlap; ties go to the first-found path (deterministic via
+ * segment overlap. Ties go to the first-found path (deterministic via
  * the directory-walk order). Returns undefined when no candidate exists.
  *
  * @param sourcePath Engine-relative POSIX source path

package/dist/src/core/build-audit-resolve.js

@@ -24,7 +24,7 @@ import { normalizePathSlashes } from '../utils/paths.js';
 /** Maximum directory depth to traverse when scanning a tree root. */
 const MAX_SCAN_DEPTH = 12;
 /**
- * Heuristic test for "this looks like a packaged-test source file" — the
+ * Heuristic test for "this looks like a packaged-test source file". The
  * audit routes such paths to `_tests/` instead of `dist/`. Matches
  * mochitest / xpcshell / browser-chrome conventions: any source under a
  * `/test/` or `/tests/` directory, anywhere under a `testing/` subtree
@@ -59,7 +59,7 @@ export function isTestPath(sourcePath) {
  *
  * Separators are normalized first because the candidates come from `join()`
  * over a `readdir` walk of the dist tree: on Windows those carry backslashes,
- * which a `/`-only split collapses into a SINGLE segment. Every candidate then
+ * which a `/`-only split collapses into a single segment. Every candidate then
  * scores the same, so the trailing-overlap heuristic that disambiguates
  * same-basename artifacts (`branding/…/aboutDialog.css` versus
  * `browser/…/aboutDialog.css`) silently picks an arbitrary one.
@@ -94,7 +94,7 @@ export function countTrailingSegmentMatches(a, b) {
 /**
  * Path segments too common to identify an artifact on their own.
  *
- * Shared deliberately: this set governs two halves of ONE decision —
+ * Shared on purpose: this set governs two halves of one decision,
  * `scoreCandidate` (selection) and `isConfidentMatch` (confirmation, in
  * `build-audit.ts`). When the halves kept separate copies they disagreed,
  * so a source path could earn a selection bonus for a segment that
@@ -129,14 +129,14 @@ export const GENERIC_PATH_SEGMENTS = new Set([
  *
  * The bonus exists because Firefox packaging often re-roots files: a source
  * `branding/<name>/content/aboutDialog.css` lands at
- * `chrome/browser/content/branding/aboutDialog.css` — only the basename
+ * `chrome/browser/content/branding/aboutDialog.css`. Only the basename
  * trails-match, but the `branding` segment moved into the middle of the
  * candidate path. Without the bonus that candidate ties with the unrelated
  * `chrome/browser/content/browser/aboutDialog.css`.
  *
  * @param sourcePath Engine-relative POSIX path
  * @param candidatePath Absolute path under the dist tree
- * @returns Numeric score; higher means better match
+ * @returns Numeric score, where higher means better match
  */
 export function scoreCandidate(sourcePath, candidatePath) {
     const trailing = countTrailingSegmentMatches(sourcePath, candidatePath);
@@ -210,7 +210,7 @@ export async function findAllByBasename(root, name, maxDepth = MAX_SCAN_DEPTH) {
 /**
  * Resolves the best-matching artifact for a source path under one or
  * more search roots. Returns the highest-scoring candidate by trailing
- * segment overlap; ties go to the first-found path (deterministic via
+ * segment overlap. Ties go to the first-found path (deterministic via
  * the directory-walk order). Returns undefined when no candidate exists.
  *
  * @param sourcePath Engine-relative POSIX source path

package/dist/src/core/build-audit-skip.d.ts

@@ -2,7 +2,7 @@
  * Why a changed engine path was not audited.
  *
  * The first four name skips that already existed as unstructured
- * `verbose()` strings; the last four are the 0.46.0 classifiers.
+ * `verbose()` strings. The last four are the 0.46.0 classifiers.
  */
 export type AuditSkipReason = 'not-packageable' | 'platform-gated' | 'platform-gated-ancestor' | 'tests-not-packaged' | 'source-unreadable' | 'branding-not-selected' | 'storybook-story' | 'declared-unpackaged';
 /** Render order for the `Packaged:` summary's per-class breakdown. */
@@ -15,7 +15,7 @@ export declare function isStorybookStoryPath(sourcePath: string): boolean;
  * FireForge generates `engine/mozconfig` and writes the
  * `ac_add_options --with-branding=…` line into it, so the selected branding
  * is knowable from the tree. Returns undefined when the mozconfig cannot be
- * read or carries no directive — the caller must then keep warning, because
+ * read or carries no directive. The caller must then keep warning, because
  * a skip that cannot name its evidence is a masked warning.
  *
  * @param engineDir - Absolute path to the engine root
@@ -23,13 +23,13 @@ export declare function isStorybookStoryPath(sourcePath: string): boolean;
  */
 export declare function resolveSelectedBranding(engineDir: string): Promise<string | undefined>;
 /**
- * True when `sourcePath` lives under a branding tree that is NOT the one
+ * True when `sourcePath` lives under a branding tree that is not the one
  * this objdir was configured with.
  *
  * An unselected branding directory is not an input to this build at all, so
  * its files can never appear in `dist/`. Worse, the basename walker matched
- * them against the SELECTED branding's same-named artifact and reported the
- * unselected file as "newer than its packaged artifact" — a stale warning
+ * them against the selected branding's same-named artifact and reported the
+ * unselected file as "newer than its packaged artifact", a stale warning
  * about a comparison that has no meaning.
  *
  * @param sourcePath - Engine-relative POSIX path
@@ -47,9 +47,9 @@ export interface UnpackagedDeclaration {
  * Finds the declaration admitting `sourcePath`, if any.
  *
  * Exact match or a `*`-within-one-segment glob, matching the
- * `support-files` matcher's deliberate narrowness: `**` and other
- * cross-directory shapes are not accepted, because a carve-out that
- * silently widens is exactly the failure this feature is warned against.
+ * `support-files` matcher's narrowness: `**` and other cross-directory
+ * shapes are not accepted, because a carve-out that silently widens is the
+ * failure this feature is warned against.
  *
  * @param sourcePath - Engine-relative POSIX path
  * @param declarations - The project's `buildAudit.unpackaged` entries

package/dist/src/core/build-audit-skip.js

@@ -7,8 +7,8 @@
  * usually wrong stops reading the one that is right. Every classifier here
  * exists to remove a warning whose "missing packaged artifact" claim is
  * structurally impossible, and each carries its own reason so the
- * `Packaged:` summary can say what it skipped and why — a run reporting
- * `4 missing` with zero real misses is what this replaces.
+ * `Packaged:` summary can say what it skipped and why. This replaces a run
+ * reporting `4 missing` with zero real misses.
  */
 import { readText } from '../utils/fs.js';
 import { normalizePathSlashes } from '../utils/paths.js';
@@ -28,10 +28,10 @@ export const AUDIT_SKIP_REASONS = [
 /**
  * Suffixes of Storybook story modules.
  *
- * Firefox's in-tree Storybook renders these through its own Vite config;
- * no `jar.mn` or `moz.build` entry packages one, so "no packaged artifact"
+ * Firefox's in-tree Storybook renders these through its own Vite config.
+ * No `jar.mn` or `moz.build` entry packages one, so "no packaged artifact"
  * is the expected state rather than a missing registration. Kept as a
- * CLOSED list on purpose: generalising to "anything with a dotted infix"
+ * closed list on purpose: generalising to "anything with a dotted infix"
  * would swallow `*.worker.js` and `*.sys.mjs`, which are packaged.
  */
 const STORYBOOK_SUFFIXES = ['.stories.mjs', '.stories.js'];
@@ -48,7 +48,7 @@ const BRANDING_ROOT = 'browser/branding/';
  * FireForge generates `engine/mozconfig` and writes the
  * `ac_add_options --with-branding=…` line into it, so the selected branding
  * is knowable from the tree. Returns undefined when the mozconfig cannot be
- * read or carries no directive — the caller must then keep warning, because
+ * read or carries no directive. The caller must then keep warning, because
  * a skip that cannot name its evidence is a masked warning.
  *
  * @param engineDir - Absolute path to the engine root
@@ -65,13 +65,13 @@ export async function resolveSelectedBranding(engineDir) {
     }
 }
 /**
- * True when `sourcePath` lives under a branding tree that is NOT the one
+ * True when `sourcePath` lives under a branding tree that is not the one
  * this objdir was configured with.
  *
  * An unselected branding directory is not an input to this build at all, so
  * its files can never appear in `dist/`. Worse, the basename walker matched
- * them against the SELECTED branding's same-named artifact and reported the
- * unselected file as "newer than its packaged artifact" — a stale warning
+ * them against the selected branding's same-named artifact and reported the
+ * unselected file as "newer than its packaged artifact", a stale warning
  * about a comparison that has no meaning.
  *
  * @param sourcePath - Engine-relative POSIX path
@@ -90,9 +90,9 @@ export function isUnselectedBrandingPath(sourcePath, selectedBranding) {
  * Finds the declaration admitting `sourcePath`, if any.
  *
  * Exact match or a `*`-within-one-segment glob, matching the
- * `support-files` matcher's deliberate narrowness: `**` and other
- * cross-directory shapes are not accepted, because a carve-out that
- * silently widens is exactly the failure this feature is warned against.
+ * `support-files` matcher's narrowness: `**` and other cross-directory
+ * shapes are not accepted, because a carve-out that silently widens is the
+ * failure this feature is warned against.
  *
  * @param sourcePath - Engine-relative POSIX path
  * @param declarations - The project's `buildAudit.unpackaged` entries

package/dist/src/core/build-audit-transforms.d.ts

@@ -1,7 +1,7 @@
 /**
  * Returns the expected chrome-tree suffix for an engine-relative POSIX
- * source path when the path falls under a known transform prefix;
- * undefined otherwise.
+ * source path when the path falls under a known transform prefix.
+ * Returns undefined otherwise.
  *
  * @param source Engine-relative POSIX source path.
  */