@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/core/test-stale-check.d.ts

@@ -6,7 +6,7 @@ export interface StaleBuildResult {
     /**
      * Engine-relative paths that would have been packaged but appear to have
      * changed since the baseline. Sorted and deduplicated. Truncated at
-     * {@link STALE_PATHS_LIMIT} entries for rendering; consult
+     * {@link STALE_PATHS_LIMIT} entries for rendering. Consult
      * {@link StaleBuildResult.truncated} to know when to append a `(+N more)`
      * tail to the warning.
      */
@@ -18,16 +18,16 @@ export interface StaleBuildResult {
     truncated: number;
     /**
      * The baseline that anchored the diff, or undefined when no previous
-     * successful build exists. A missing baseline is treated as "not stale"
-     * — we have nothing to compare against and a warning would mislead.
+     * successful build exists. A missing baseline is treated as "not stale":
+     * we have nothing to compare against and a warning would mislead.
      */
     baseline: BuildBaseline | undefined;
 }
 /**
  * Probes the engine tree for packageable changes since the last successful
  * `fireforge build`. Returns a summary the `fireforge test` handler renders
- * as an up-front warning when `--build` was NOT passed. The probe never
- * throws; git failures and a missing baseline both degrade to `stale: false`
+ * as an up-front warning when `--build` was not passed. The probe never
+ * throws. Git failures and a missing baseline both degrade to `stale: false`
  * so a broken probe cannot block a test run.
  *
  * @param projectRoot Root directory of the project.
@@ -48,25 +48,26 @@ export declare const FULL_SUITE_REQUEST = "(entire suite)";
 /**
  * Compares the requested test paths against the packaged runtime's coverage
  * claim recorded in the baseline. Returns the requested paths the recorded
- * packaging does NOT cover — the runs that would dispatch against missing
+ * packaging does not cover: the runs that would dispatch against missing
  * `_tests/` support fixtures and hang rather than fail.
  *
  * Coverage semantics: an absent claim and `'full'` cover everything. A
  * scoped list covers a request path when the request equals a covered entry,
  * sits beneath a covered directory entry, or shares a manifest granule with
- * a covered entry ({@link toManifestGranule} — a scoped `test --build`
+ * a covered entry (see {@link toManifestGranule}: a scoped `test --build`
  * packages the whole manifest directory, so a same-manifest sibling of a
  * covered file is packaged too). Both sides are normalized to forward
  * slashes so Windows-style CLI input cannot defeat the prefix rule (baseline
  * paths are POSIX by convention). A request with no paths is a full-suite
- * run and is never covered by a scoped list — the {@link FULL_SUITE_REQUEST}
- * sentinel is returned so the refusal can name it.
+ * run and is never covered by a scoped list, so the
+ * {@link FULL_SUITE_REQUEST} sentinel is returned and the refusal can name
+ * it.
  */
 export declare function findUncoveredRequestPaths(coverage: TestPackagingCoverage | undefined, requestedPaths: readonly string[]): string[];
 /**
  * Test manifests changed since the recorded build that sit in (or above)
- * the directory of an uncovered request path — i.e. the manifests that
- * EXPLAIN why this run needs coverage the build never claimed.
+ * the directory of an uncovered request path, i.e. the manifests that
+ * explain why this run needs coverage the build never claimed.
  *
  * Best-effort: a probe failure returns an empty list, so the refusal
  * degrades to exactly its previous text rather than failing differently.
@@ -84,7 +85,7 @@ export declare function findChangedTestManifestsForPaths(engineDir: string, base
  * @param coverage - The recorded scoped coverage claim
  * @param changedManifests - Test manifests changed since the recorded
  *   build that explain an uncovered path (from
- *   {@link findChangedTestManifestsForPaths}); omitted or empty renders
+ *   {@link findChangedTestManifestsForPaths}). Omitted or empty renders
  *   nothing
  */
 export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[], changedManifests?: readonly string[]): string;
@@ -93,25 +94,25 @@ export interface StaticComponentsStaleResult {
     /** True when at least one `components.conf` genuinely diverged from the anchor. */
     stale: boolean;
     /**
-     * Engine-relative `components.conf` paths changed since the last FULL
-     * build. Sorted; NOT capped — {@link formatStaticComponentsRefusal}
+     * Engine-relative `components.conf` paths changed since the last full
+     * build. Sorted, and not capped. {@link formatStaticComponentsRefusal}
      * applies the render cap.
      */
     changedManifests: string[];
 }
 /**
- * Probes whether any `components.conf` changed since the last FULL
- * `fireforge build` — i.e. since the compiled StaticComponents table was
- * last regenerated. `components.conf` entries bake into compiled code; a
+ * Probes whether any `components.conf` changed since the last full
+ * `fireforge build`, i.e. since the compiled StaticComponents table was
+ * last regenerated. `components.conf` entries bake into compiled code. A
  * scoped `test --build` packages the file but the child process resolves the
- * OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a test
+ * old table and fails with `NS_ERROR_MALFORMED_URI` that reads as a test
  * bug.
  *
  * The diff anchors to the baseline's `staticComponentsBaseline` (the last
- * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`,
+ * full build's engine HEAD SHA), not the baseline's own `engineHeadSha`,
  * which a scoped `test --build` advances. Dirty candidates are hash-checked
  * against the anchor's fingerprints so only genuine content divergence
- * counts. No baseline or no anchor means fresh. Never throws — the probes it
+ * counts. No baseline or no anchor means fresh. Never throws: the probes it
  * composes degrade to verbose lines and empty results on git failure,
  * matching {@link checkStaleBuildForTest}.
  */
@@ -128,7 +129,7 @@ export declare function formatStaticComponentsRefusal(changedManifests: string[]
  * `fireforge import` when `components.conf` diverged from the last full
  * build. Same probe as {@link formatStaticComponentsRefusal},
  * different moment: this fires at mutation time so the operator learns a
- * full build is needed BEFORE the next gate run refuses.
+ * full build is needed before the next gate run refuses.
  */
 export declare function formatPostMutationStaticComponentsWarning(changedManifests: string[]): string;
 /**

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

@@ -5,9 +5,9 @@
  * Without this preflight, an operator who edits engine chrome / packaged
  * resources (`jar.mn` entries, `.xhtml`/`.mjs`/`.css` under chrome trees,
  * pref files) and then runs `fireforge test <path>` only discovers the build
- * is stale AFTER xpcshell / mach test starts and errors out with
- * `NS_ERROR_FILE_NOT_FOUND` against a `chrome://browser/content/…` URI —
- * which reads as a test bug, not a rebuild prompt. Scaffolding a new
+ * is stale after xpcshell / mach test starts and errors out with
+ * `NS_ERROR_FILE_NOT_FOUND` against a `chrome://browser/content/…` URI,
+ * which reads as a test bug rather than a rebuild prompt. Scaffolding a new
  * top-level chrome document plus an xpcshell test is the canonical case: the
  * test file exists, the manifests are registered, but `dist/` still holds
  * the pre-edit bundle and chrome URIs resolve to nothing.
@@ -16,7 +16,7 @@
  * baseline (`.fireforge/last-build.json`), filters to paths that imply
  * packaging, and returns a compact summary. `fireforge test` prints a
  * warning up-front so the operator sees "you edited X, Y, Z since the last
- * build — rerun with `--build` to refresh" BEFORE mach test launches.
+ * build, rerun with `--build` to refresh" before mach test launches.
  * Detection stays advisory (warn-only) because a fork that rebuilds
  * out-of-band (a separate `./mach build` invocation, an IDE plugin) can
  * legitimately have a fresh `dist/` with no FireForge-recorded baseline
@@ -34,8 +34,8 @@ const STALE_PATHS_LIMIT = 10;
 /**
  * Probes the engine tree for packageable changes since the last successful
  * `fireforge build`. Returns a summary the `fireforge test` handler renders
- * as an up-front warning when `--build` was NOT passed. The probe never
- * throws; git failures and a missing baseline both degrade to `stale: false`
+ * as an up-front warning when `--build` was not passed. The probe never
+ * throws. Git failures and a missing baseline both degrade to `stale: false`
  * so a broken probe cannot block a test run.
  *
  * @param projectRoot Root directory of the project.
@@ -58,8 +58,8 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     // Furnace-applied components always has a persistent workdir diff against
     // HEAD, so `git diff --name-only HEAD` returns that diff on every build
     // and the stale check fires immediately after a successful one. The
-    // fingerprints capture "these files had this content when the build ran";
-    // a path stays stale only when its live hash diverges.
+    // fingerprints capture "these files had this content when the build ran".
+    // A path stays stale only when its live hash diverges.
     packageable = await dropPathsMatchingFingerprints(engineDir, packageable, baseline.packageableFingerprints);
     if (packageable.length === 0) {
         return { stale: false, changedPaths: [], truncated: 0, baseline };
@@ -89,19 +89,20 @@ export const FULL_SUITE_REQUEST = '(entire suite)';
 /**
  * Compares the requested test paths against the packaged runtime's coverage
  * claim recorded in the baseline. Returns the requested paths the recorded
- * packaging does NOT cover — the runs that would dispatch against missing
+ * packaging does not cover: the runs that would dispatch against missing
  * `_tests/` support fixtures and hang rather than fail.
  *
  * Coverage semantics: an absent claim and `'full'` cover everything. A
  * scoped list covers a request path when the request equals a covered entry,
  * sits beneath a covered directory entry, or shares a manifest granule with
- * a covered entry ({@link toManifestGranule} — a scoped `test --build`
+ * a covered entry (see {@link toManifestGranule}: a scoped `test --build`
  * packages the whole manifest directory, so a same-manifest sibling of a
  * covered file is packaged too). Both sides are normalized to forward
  * slashes so Windows-style CLI input cannot defeat the prefix rule (baseline
  * paths are POSIX by convention). A request with no paths is a full-suite
- * run and is never covered by a scoped list — the {@link FULL_SUITE_REQUEST}
- * sentinel is returned so the refusal can name it.
+ * run and is never covered by a scoped list, so the
+ * {@link FULL_SUITE_REQUEST} sentinel is returned and the refusal can name
+ * it.
  */
 export function findUncoveredRequestPaths(coverage, requestedPaths) {
     if (coverage === undefined || coverage === 'full') {
@@ -121,10 +122,10 @@ export function findUncoveredRequestPaths(coverage, requestedPaths) {
  * Maps a normalized request/coverage path to the "manifest granule" the
  * packaged runtime actually staged: an extension-bearing basename (a test
  * FILE) maps to its containing directory, a directory (no dot in the
- * basename) maps to itself. Purely lexical — the directory-as-manifest
+ * basename) maps to itself. Purely lexical: the directory-as-manifest
  * approximation holds because xpcshell/mochitest manifests live next to
  * their test files and a scoped `test --build` stages the whole manifest
- * directory into `obj-*`/`_tests/`, not single files. Caveat: a DIRECTORY
+ * directory into `obj-*`/`_tests/`, not single files. Caveat: a directory
  * whose basename contains a dot is misread as a file and mapped to its
  * parent, which widens (never narrows) the covered granule.
  */
@@ -142,7 +143,7 @@ function normalizeCoveragePath(path) {
 }
 /**
  * Formats the refusal shown when a non-`--build` run requests paths the
- * packaged runtime's scoped `test --build` coverage does not include —
+ * packaged runtime's scoped `test --build` coverage does not include. It is
  * enforced on every such run, with or without `--allow-stale-build`. Kept
  * separate from the matcher so tests can pin structure and copy
  * independently (same split as {@link formatStaleBuildWarning}).
@@ -150,7 +151,7 @@ function normalizeCoveragePath(path) {
 /**
  * Basenames of the test manifests whose entries decide what a packaged test
  * runtime stages. A manifest that gained an entry is the single most common
- * reason a run needs coverage the last build never claimed — and it is a
+ * reason a run needs coverage the last build never claimed, and it is a
  * fact FireForge already holds but never said, leaving the operator to
  * rediscover it after a correct refusal.
  */
@@ -173,8 +174,8 @@ function isTestManifestPath(path) {
 }
 /**
  * Test manifests changed since the recorded build that sit in (or above)
- * the directory of an uncovered request path — i.e. the manifests that
- * EXPLAIN why this run needs coverage the build never claimed.
+ * the directory of an uncovered request path, i.e. the manifests that
+ * explain why this run needs coverage the build never claimed.
  *
  * Best-effort: a probe failure returns an empty list, so the refusal
  * degrades to exactly its previous text rather than failing differently.
@@ -211,7 +212,7 @@ export async function findChangedTestManifestsForPaths(engineDir, baseline, unco
  * @param coverage - The recorded scoped coverage claim
  * @param changedManifests - Test manifests changed since the recorded
  *   build that explain an uncovered path (from
- *   {@link findChangedTestManifestsForPaths}); omitted or empty renders
+ *   {@link findChangedTestManifestsForPaths}). Omitted or empty renders
  *   nothing
  */
 export function formatTestCoverageRefusal(uncovered, coverage, changedManifests = []) {
@@ -222,7 +223,7 @@ export function formatTestCoverageRefusal(uncovered, coverage, changedManifests
     };
     const rebuildTargets = uncovered.filter((p) => p !== FULL_SUITE_REQUEST);
     // Name --extend-coverage here or it is undiscoverable: a scoped build
-    // REPLACES the claim, so under several concurrent sessions a peer's build
+    // replaces the claim, so under several concurrent sessions a peer's build
     // for an unrelated path erases coverage you legitimately still hold, and
     // the union that fixes it is a flag the operator has no reason to know
     // exists at the moment they need it. The anchor conditions are stated
@@ -233,7 +234,7 @@ export function formatTestCoverageRefusal(uncovered, coverage, changedManifests
     const rebuildHint = rebuildTargets.length > 0
         ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.${extendHint}`
         : 'Run "fireforge build" (or a path-less "fireforge test --build") for full coverage first.';
-    // Why THIS run needs new coverage, when a changed manifest explains it: a
+    // Why this run needs new coverage, when a changed manifest explains it: a
     // manifest that gained an entry is not covered by a build claim recorded
     // for other paths, and a browser-chrome claim never covers xpcshell.
     const manifestLine = changedManifests.length > 0
@@ -246,18 +247,18 @@ export function formatTestCoverageRefusal(uncovered, coverage, changedManifests
         '(--allow-stale-build does not bypass this check — it accepts stale content, not missing coverage.)');
 }
 /**
- * Probes whether any `components.conf` changed since the last FULL
- * `fireforge build` — i.e. since the compiled StaticComponents table was
- * last regenerated. `components.conf` entries bake into compiled code; a
+ * Probes whether any `components.conf` changed since the last full
+ * `fireforge build`, i.e. since the compiled StaticComponents table was
+ * last regenerated. `components.conf` entries bake into compiled code. A
  * scoped `test --build` packages the file but the child process resolves the
- * OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a test
+ * old table and fails with `NS_ERROR_MALFORMED_URI` that reads as a test
  * bug.
  *
  * The diff anchors to the baseline's `staticComponentsBaseline` (the last
- * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`,
+ * full build's engine HEAD SHA), not the baseline's own `engineHeadSha`,
  * which a scoped `test --build` advances. Dirty candidates are hash-checked
  * against the anchor's fingerprints so only genuine content divergence
- * counts. No baseline or no anchor means fresh. Never throws — the probes it
+ * counts. No baseline or no anchor means fresh. Never throws: the probes it
  * composes degrade to verbose lines and empty results on git failure,
  * matching {@link checkStaleBuildForTest}.
  */
@@ -300,7 +301,7 @@ export function formatStaticComponentsRefusal(changedManifests) {
  * `fireforge import` when `components.conf` diverged from the last full
  * build. Same probe as {@link formatStaticComponentsRefusal},
  * different moment: this fires at mutation time so the operator learns a
- * full build is needed BEFORE the next gate run refuses.
+ * full build is needed before the next gate run refuses.
  */
 export function formatPostMutationStaticComponentsWarning(changedManifests) {
     const head = changedManifests.slice(0, STALE_PATHS_LIMIT);

package/dist/src/core/test-stale-symlink.d.ts

@@ -5,7 +5,7 @@
  * Removes one stale xpcshell `_tests` symlink when mach reports a
  * FileExistsError during test installation.
  *
- * The guard rails are deliberately narrow: only quoted FileExistsError
+ * The guard rails are narrow: only quoted FileExistsError
  * destinations inside the active objdir's `_tests` tree are considered, and
  * only when lstat confirms the destination itself is a symlink.
  */

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

@@ -17,7 +17,7 @@ function isInsideDirectory(parent, candidate) {
  * Removes one stale xpcshell `_tests` symlink when mach reports a
  * FileExistsError during test installation.
  *
- * The guard rails are deliberately narrow: only quoted FileExistsError
+ * The guard rails are narrow: only quoted FileExistsError
  * destinations inside the active objdir's `_tests` tree are considered, and
  * only when lstat confirms the destination itself is a symlink.
  */

package/dist/src/core/test-stall-triage.d.ts

@@ -1,8 +1,8 @@
 /**
  * Operator-facing triage for the `timed out … with no output` / `Ran 0
- * checks` stall — the shape where the harness dies before ANY test output.
+ * checks` stall: the shape where the harness dies before any test output.
  *
- * Split out of `test-harness-crash.ts`, which CLASSIFIES runs; this module
+ * Split out of `test-harness-crash.ts`, which classifies runs. This module
  * only renders advice about one already-classified shape. Keeping the two
  * apart matters because the census below carries claims of unequal
  * evidential strength, and the rules for editing it are not the rules for
@@ -10,23 +10,23 @@
  * the output or not, while a cause in the census is an assertion about the
  * world that an operator will act on.
  *
- * Everything here is pure — the platform and the probed display state are
+ * Everything here is pure. The platform and the probed display state are
  * injected, so unit tests need no mocking.
  */
 import type { DisplaySleepState } from './display-state.js';
 import type { HarnessCrashSignature } from './test-harness-signature.js';
 /**
- * Optional hint appended to the harness-crash message when a HEADED run on
+ * Optional hint appended to the harness-crash message when a headed run on
  * macOS died at the no-output timeout.
  *
- * When `displayState` names a MEASURED display state, the hint states it as
- * fact rather than as one of three possibilities — that is the point of
- * probing: an operator staring at a bare test failure should not have to
+ * When `displayState` names a measured display state, the hint states it as
+ * fact rather than as one of three possibilities, which is what probing is
+ * for: an operator staring at a bare test failure should not have to
  * rediscover that their machine dimmed. `caffeinate` is described accurately
- * (it prevents sleep; it cannot wake an already-sleeping display), so
+ * (it prevents sleep, and cannot wake an already-sleeping display), so
  * operators are not sent to a command that could not have helped them.
  *
- * Pure — the platform and the probed state are injected so unit tests need
+ * Pure. The platform and the probed state are injected so unit tests need
  * no mocking.
  *
  * @param signature - The recognized crash shape

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

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Operator-facing triage for the `timed out … with no output` / `Ran 0
- * checks` stall — the shape where the harness dies before ANY test output.
+ * checks` stall: the shape where the harness dies before any test output.
  *
- * Split out of `test-harness-crash.ts`, which CLASSIFIES runs; this module
+ * Split out of `test-harness-crash.ts`, which classifies runs. This module
  * only renders advice about one already-classified shape. Keeping the two
  * apart matters because the census below carries claims of unequal
  * evidential strength, and the rules for editing it are not the rules for
@@ -11,14 +11,14 @@
  * the output or not, while a cause in the census is an assertion about the
  * world that an operator will act on.
  *
- * Everything here is pure — the platform and the probed display state are
+ * Everything here is pure. The platform and the probed display state are
  * injected, so unit tests need no mocking.
  */
 /**
  * First step for the `timed out … with no output` / `Ran 0 checks`
- * signature, printed ABOVE the cause list. Running a known-good control
+ * signature, printed above the cause list. Running a known-good control
  * separates "this test" from "this build" and is the correct opening move
- * for EVERY cause below — it is not specific to any one of them, so
+ * for every cause below. It is not specific to any one of them, so
  * attaching it to a single entry made reaching that entry informationally
  * empty.
  */
@@ -26,23 +26,23 @@ const NO_OUTPUT_STALL_CONTROL_STEP = 'First, run a known-good control test. If t
     'under investigation, and the list below applies to the build or the host.';
 /**
  * Recorded causes of the `timed out … with no output` / `Ran 0 checks`
- * signature, each paired with the probe that DISCRIMINATES it from the
+ * signature, each paired with the probe that discriminates it from the
  * others. Printed verbatim under the hint.
  *
- * Evidence per entry is deliberately unequal, and the text says so:
+ * Evidence per entry is unequal, and the text says so:
  *
- *  - (1) is MEASURED — `probeDisplaySleepState` reads the display's power
+ *  - (1) is measured: `probeDisplaySleepState` reads the display's power
  *    state, so the hint states it as fact rather than as a possibility.
  *  - (2) is discriminated by `--headless`.
- *  - (4) is MECHANICAL and was root-caused downstream: the harness serves
+ *  - (4) is mechanical and was root-caused downstream: the harness serves
  *    its manifest from `server.js` on 8888, and a survivor of an
  *    interrupted run keeps the port. Its probe is exact, and the preflight
  *    in `mochitest-server-port.ts` now refuses it before a run starts.
- *  - (3) is now MECHANICAL and root-caused, replacing the correlation an
+ *  - (3) is now mechanical and root-caused, replacing the correlation an
  *    earlier revision recorded. A `chrome://` (or `resource://`) URL that
  *    resolves to nothing reaches `CheckForBrokenChromeURL`
  *    (netwerk/base/nsNetUtil.cpp), which outside automation only
- *    `printf_stderr`s `Missing chrome or resource URL: <uri>` — but under
+ *    `printf_stderr`s `Missing chrome or resource URL: <uri>`, but under
  *    `xpc::IsInAutomation()` the same condition is
  *    `MOZ_CRASH_UNSAFE_PRINTF("Missing chrome or resource URLs: %s")`. A
  *    downstream reproduction symbolicated the faulting frame as
@@ -52,13 +52,13 @@ const NO_OUTPUT_STALL_CONTROL_STEP = 'First, run a known-good control test. If t
  *    failed image load in Gecko fires `error` and does not gate the
  *    document load event.
  *
- * Detection by log line is deliberately NOT specified for (3), and the
- * reason is the mechanism itself: in the reproduction the crash landed in a
- * CONTENT process (`plugin-container`, a child of the browser) with the
+ * Detection by log line is not specified for (3), because of the mechanism
+ * itself: in the reproduction the crash landed in a content
+ * process (`plugin-container`, a child of the browser) with the
  * crash reporter compiled out, so the harness log carried neither the crash
- * message nor a crash line — only the no-output timeout, `Ran 0 checks`,
+ * message nor a crash line, only the no-output timeout, `Ran 0 checks`,
  * and mochitest's "Can't trigger Breakpad, just killing process". Under
- * automation the message is in the process that DIED, not in the log, so
+ * automation the message is in the process that died, not in the log, so
  * the census points at the two artefacts that do carry it: the OS crash
  * report (whose faulting frame names `CheckForBrokenChromeURL`) and the
  * out-of-automation smoke probe (which prints the non-crashing spelling
@@ -90,17 +90,17 @@ const NO_OUTPUT_STALL_TRIAGE = [
         'reach a stall only on a host where the port could not be probed.',
 ];
 /**
- * Optional hint appended to the harness-crash message when a HEADED run on
+ * Optional hint appended to the harness-crash message when a headed run on
  * macOS died at the no-output timeout.
  *
- * When `displayState` names a MEASURED display state, the hint states it as
- * fact rather than as one of three possibilities — that is the point of
- * probing: an operator staring at a bare test failure should not have to
+ * When `displayState` names a measured display state, the hint states it as
+ * fact rather than as one of three possibilities, which is what probing is
+ * for: an operator staring at a bare test failure should not have to
  * rediscover that their machine dimmed. `caffeinate` is described accurately
- * (it prevents sleep; it cannot wake an already-sleeping display), so
+ * (it prevents sleep, and cannot wake an already-sleeping display), so
  * operators are not sent to a command that could not have helped them.
  *
- * Pure — the platform and the probed state are injected so unit tests need
+ * Pure. The platform and the probed state are injected so unit tests need
  * no mocking.
  *
  * @param signature - The recognized crash shape

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

@@ -1,6 +1,6 @@
 /**
  * True when `lines` contain a category header (single-line or multi-line
- * banner shape) whose name EQUALS `category`. Shared by the pre-add
+ * banner shape) whose name equals `category`. Shared by the pre-add
  * assertion, the banner creation path, and the section finder so all
  * agree on what "exists" means.
  */
@@ -15,11 +15,11 @@ export declare function categoryHeaderExists(lines: string[], category: string):
  * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
  *   closing `*\/`.
  *
- * This helper exists as a pure inspector; it never throws on malformed
+ * This helper exists as a pure inspector. It never throws on malformed
  * headers and silently skips shapes it cannot parse.
  */
 /**
- * Category name declared by the banner STARTING at `index`, or `undefined`
+ * Category name declared by the banner starting at `index`, or `undefined`
  * when that line opens no banner.
  *
  * The single reader for both banner shapes, so the inventory walk, the
@@ -66,7 +66,7 @@ export interface TokenDeclarationLocation {
 /**
  * Finds an existing declaration of `tokenName` inside the base `:root`
  * block. Dark `@media` and `:root[variant]` companion blocks are
- * deliberately excluded — they mirror the base declaration, they do not
+ * excluded: they mirror the base declaration, they do not
  * own the token. Comment content never matches, and the name match is
  * exact (`--foo-bar` does not match `--x-foo-bar`).
  */

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

@@ -3,11 +3,12 @@
  * Category banner and token-declaration helpers for the tokens CSS file.
  * Split out of `token-manager.ts` to stay inside the per-file line budget.
  *
- * Banner matching is EXACT: the text between the `=` runs (single-line
+ * Banner matching is exact: the text between the `=` runs (single-line
  * shape) or on the block line (multi-line shape) must equal the category
- * after trimming. A substring match lets a TOC comment or a longer banner
- * (`Colors — Canvas` for `Colors`) satisfy the lookup, so `token add` writes
- * into the wrong section — or no-ops — with exit 0.
+ * after trimming. With a substring match, a TOC comment or a longer banner
+ * whose name merely starts with the category (a canvas colors banner
+ * satisfying a lookup for `Colors`) would also match, and `token add` would
+ * then write into the wrong section, or no-op, with exit 0.
  */
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
@@ -23,7 +24,7 @@ function multiLineBlockNameMatches(blockLine, category) {
  * Body of the first `/* … *\/` comment on `line`, or `undefined` when the
  * line carries no closed block comment.
  *
- * Deliberately index arithmetic rather than a regex: every regex spelling of
+ * This uses index arithmetic rather than a regex: every regex spelling of
  * "banner comment" this module used to carry was super-linear on a line that
  * repeats the opening shape (CodeQL `js/polynomial-redos`), and `tokens.css`
  * is a file FireForge reads out of a consumer's engine tree, so a
@@ -39,7 +40,7 @@ function blockCommentBody(line) {
     return line.slice(open + 2, close);
 }
 /**
- * True when `line` carries a single-line banner comment — a closed block
+ * True when `line` carries a single-line banner comment: a closed block
  * comment whose body both opens and closes with `=`. Recognises the decorative
  * all-`=` rule as well as a named `= Foo =` banner, which is what the section
  * scan wants: either shape ends the preceding section.
@@ -51,7 +52,7 @@ function isSingleLineBannerLine(line) {
 /**
  * Name declared by a single-line banner (`/* = Foo = *\/` → `Foo`), or
  * `undefined` when the line is not a named banner. The `=` runs on both sides
- * are required; a decorative all-`=` rule carries no name and yields
+ * are required. A decorative all-`=` rule carries no name and yields
  * `undefined`.
  */
 function singleLineBannerName(line) {
@@ -79,7 +80,7 @@ function singleLineBannerName(line) {
 }
 /**
  * True when `lines` contain a category header (single-line or multi-line
- * banner shape) whose name EQUALS `category`. Shared by the pre-add
+ * banner shape) whose name equals `category`. Shared by the pre-add
  * assertion, the banner creation path, and the section finder so all
  * agree on what "exists" means.
  */
@@ -112,11 +113,11 @@ export function categoryHeaderExists(lines, category) {
  * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
  *   closing `*\/`.
  *
- * This helper exists as a pure inspector; it never throws on malformed
+ * This helper exists as a pure inspector. It never throws on malformed
  * headers and silently skips shapes it cannot parse.
  */
 /**
- * Category name declared by the banner STARTING at `index`, or `undefined`
+ * Category name declared by the banner starting at `index`, or `undefined`
  * when that line opens no banner.
  *
  * The single reader for both banner shapes, so the inventory walk, the
@@ -211,7 +212,7 @@ export function findCategorySection(lines, category, tokensCssPath) {
             categoryLine = i;
             break;
         }
-        // Check multi-line format: line opens a block comment with === but does NOT close it
+        // Check multi-line format: line opens a block comment with === but does not close it
         if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
             for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
                 const blockLine = lines[j] ?? '';
@@ -278,7 +279,7 @@ export function maskCommentLines(lines) {
 /**
  * Finds an existing declaration of `tokenName` inside the base `:root`
  * block. Dark `@media` and `:root[variant]` companion blocks are
- * deliberately excluded — they mirror the base declaration, they do not
+ * excluded: they mirror the base declaration, they do not
  * own the token. Comment content never matches, and the name match is
  * exact (`--foo-bar` does not match `--x-foo-bar`).
  */

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

@@ -8,16 +8,15 @@ import { loadFurnaceConfig } from './furnace-config.js';
 /**
  * Default platform prefixes treated as allowlisted upstream vars. Any
  * `var(--moz-*)` usage in a fork's CSS is a Firefox platform variable the
- * fork does not own and must not count as an unknown — otherwise a
+ * fork does not own and must not count as an unknown. Otherwise a
  * `furnace override moz-button -t css-only` plus one fork token reports 1%
  * coverage, because the ~84 upstream `--moz-*` vars in the copied baseline
  * all count against it.
  *
  * Forks that want to opt out can override this via
- * `furnace.json.platformPrefixes = []`; forks that want more can extend it
- * (e.g. `['--moz-', '--in-content-']`). The config is additive — nothing is
- * removed from the defaults unless the operator explicitly writes a shorter
- * list.
+ * `furnace.json.platformPrefixes = []`. Forks that want more can extend it
+ * (e.g. `['--moz-', '--in-content-']`). The config is additive: nothing is
+ * removed from the defaults unless the operator writes a shorter list.
  */
 const DEFAULT_PLATFORM_PREFIXES = ['--moz-'];
 /**

package/dist/src/core/token-dark-mode.d.ts

@@ -2,8 +2,8 @@
  * Dark-mode insertion helpers for the tokens CSS scaffold.
  *
  * `fireforge token add --mode override --dark-value ...` must land the dark
- * declaration INSIDE the nested `:root { }` of the
- * `@media (prefers-color-scheme: dark)` block; landing after that block has
+ * declaration inside the nested `:root { }` of the
+ * `@media (prefers-color-scheme: dark)` block. Landing after that block has
  * closed produces a declaration outside any rule. The helpers here scan the
  * comment-stripped source lines to find the *inner* `:root` block's closing
  * `}` and return a line index the caller can splice into. When the inner
@@ -19,28 +19,28 @@
  * into the original array at the same index.
  *
  * We blank the comment body with spaces (rather than removing it) so
- * any downstream consumer that indexes by column — or derives an
- * insertion index as a line number in the original array — still
+ * any downstream consumer that indexes by column (or derives an
+ * insertion index as a line number in the original array) still
  * agrees on line numbers.
  */
 export declare function stripBlockCommentsInLines(lines: string[]): string[];
 /**
  * Finds the closing `}` line of the nested `:root { ... }` block inside
  * a `@media (prefers-color-scheme: dark)` block. Returns `-1` when the
- * media block exists but the nested `:root` block is missing; returns
+ * media block exists but the nested `:root` block is missing. Returns
  * `null` when the `@media` block itself is absent.
  *
  * Runs the scan over a comment-stripped mirror of the source lines so
  * braces inside CSS comments (`/* before { after *\/`) do not offset
- * the depth counter. The scan is deliberately line-indexed so callers
+ * the depth counter. The scan is line-indexed so callers
  * can splice into the original `lines` array at the returned index.
  */
 export declare function findDarkRootInsertionIndex(lines: string[]): number | null;
 /**
  * Depth-counts braces from `startLine` (whose lines must already have
  * block comments stripped), returning the index of the line on which the
- * block opened there returns to its entry depth — i.e. the line carrying
- * the block's closing `}` — or -1 when the block never closes. The first
+ * block opened there returns to its entry depth, i.e. the line carrying
+ * the block's closing `}`, or -1 when the block never closes. The first
  * `{` encountered sets the entry depth, so the scan may start on the
  * selector/at-rule line itself rather than on the opener.
  */
@@ -48,7 +48,7 @@ export declare function findBlockCloseIndex(stripped: string[], startLine: numbe
 /**
  * Finds the closing `}` of the outermost
  * `@media (prefers-color-scheme: dark)` block. Used as the fallback
- * landing site when the scaffold has no nested `:root { }` — the
+ * landing site when the scaffold has no nested `:root { }`. The
  * insertion helper uses this index to splice a brand-new `:root`
  * wrapper containing the dark declaration, rather than dropping the
  * value.