@hominis/fireforge 0.45.0 → 0.46.1

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/test-xpcshell-retry.d.ts

@@ -1,14 +1,33 @@
-import { type MachCommandResult } from './mach.js';
+import { type MachCommandResult, type MachTestSuiteKind } from './mach.js';
 export interface XpcshellRetryClassification {
     xpcshell: readonly string[];
     nonXpcshell: readonly string[];
 }
-/** Dispatches a (possibly suite-specific) mach test run, mirroring `testWithOutput`. */
-export type TestDispatch = (engineDir: string, testPaths: string[], args: string[], env?: Record<string, string>, fullOutput?: boolean) => Promise<MachCommandResult>;
+export interface XpcshellRetryOptions {
+    /** Engine checkout the run happened in. */
+    engineDir: string;
+    /** Object directory the run used, when one is configured. */
+    objDir: string | undefined;
+    /** Result of the run that may need repairing and retrying. */
+    result: MachCommandResult;
+    /** Which of the requested paths are xpcshell tests, and which are not. */
+    classification: XpcshellRetryClassification;
+    /** Test paths, normalized, as handed to mach. */
+    normalizedPaths: string[];
+    /** Extra mach arguments the run was started with. */
+    extraArgs: string[];
+    /** Environment overlay for the retried run. */
+    env?: Record<string, string> | undefined;
+    /** Mach command kind to retry with. Defaults to the generic `test`. */
+    kind?: MachTestSuiteKind | undefined;
+    /** Whether the run was started with full harness output. */
+    fullOutput?: boolean | undefined;
+}
 /**
  * Removes a stale xpcshell install symlink and retries the focused mach test
- * once. The retry uses the same `dispatch` (suite-specific or generic) the
- * caller is already running on, so an xpcshell-suite run repairs and re-runs
- * via `mach xpcshell-test` rather than falling back to the generic command.
+ * once. The retry uses the same mach command `kind` (suite-specific or
+ * generic) the caller is already running on, so an xpcshell-suite run repairs
+ * and re-runs via `mach xpcshell-test` rather than falling back to the
+ * generic command.
  */
-export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[], env?: Record<string, string>, dispatch?: TestDispatch, fullOutput?: boolean): Promise<MachCommandResult>;
+export declare function retryAfterXpcshellSymlinkRepair(options: XpcshellRetryOptions): Promise<MachCommandResult>;

package/dist/src/core/test-xpcshell-retry.js

@@ -1,13 +1,15 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { testWithOutput } from './mach.js';
+import { runMachTestSuite } from './mach.js';
 import { tryRepairStaleXpcshellTestSymlink } from './test-stale-symlink.js';
 /**
  * Removes a stale xpcshell install symlink and retries the focused mach test
- * once. The retry uses the same `dispatch` (suite-specific or generic) the
- * caller is already running on, so an xpcshell-suite run repairs and re-runs
- * via `mach xpcshell-test` rather than falling back to the generic command.
+ * once. The retry uses the same mach command `kind` (suite-specific or
+ * generic) the caller is already running on, so an xpcshell-suite run repairs
+ * and re-runs via `mach xpcshell-test` rather than falling back to the
+ * generic command.
  */
-export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, dispatch = testWithOutput, fullOutput) {
+export async function retryAfterXpcshellSymlinkRepair(options) {
+    const { engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, kind = 'test', fullOutput, } = options;
     if (result.exitCode !== 0 &&
         classification.xpcshell.length > 0 &&
         classification.nonXpcshell.length === 0) {
@@ -15,12 +17,13 @@ export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result,
         if (repaired) {
             // The repaired re-run is the same logical invocation, so it keeps
             // the verbosity the run was started with.
-            if (fullOutput === true) {
-                return dispatch(engineDir, normalizedPaths, extraArgs, env, true);
-            }
-            return env
-                ? dispatch(engineDir, normalizedPaths, extraArgs, env)
-                : dispatch(engineDir, normalizedPaths, extraArgs);
+            return runMachTestSuite(kind, {
+                engineDir,
+                testPaths: normalizedPaths,
+                args: extraArgs,
+                env,
+                fullOutput,
+            });
         }
     }
     return result;

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

@@ -1,10 +1,36 @@
 /**
  * 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.
  */
 export declare function categoryHeaderExists(lines: string[], category: string): boolean;
+/**
+ * Scans a tokens CSS file for category header comments and returns the
+ * category names in document order. Used to enrich the "category not
+ * found" error body with concrete alternatives the operator can copy.
+ *
+ * Mirrors the shapes `findCategorySection` recognises:
+ * - Single-line: `/* = Foo = *\/`
+ * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
+ *   closing `*\/`.
+ *
+ * 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`
+ * when that line opens no banner.
+ *
+ * The single reader for both banner shapes, so the inventory walk, the
+ * "available categories" error body and the section finder cannot drift on
+ * what counts as a header.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param index - 0-based line index to test
+ * @returns The declared category name, or undefined
+ */
+export declare function categoryBannerNameAt(lines: string[], index: number): string | undefined;
 /**
  * Asserts the category banner exists (or that creation was requested).
  * Throws a GeneralError naming the available categories and the
@@ -23,6 +49,13 @@ export declare function findCategorySection(lines: string[], category: string, t
     categoryLine: number;
     sectionEnd: number;
 };
+/** 0-based open/close line indices of the base `:root {` block. */
+export declare function findBaseRootBounds(lines: string[]): {
+    open: number;
+    close: number;
+} | undefined;
+/** Masks block-comment content per line so declarations inside comments never match. */
+export declare function maskCommentLines(lines: string[]): string[];
 /** Location of an existing base-`:root` token declaration. */
 export interface TokenDeclarationLocation {
     /** 1-based line number in the tokens CSS file. */
@@ -33,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';
@@ -20,10 +21,10 @@ function multiLineBlockNameMatches(blockLine, category) {
     return blockLine.replace(/^\s*\*\s*/, '').trim() === category;
 }
 /**
- * Body of the first `/* … *\/` comment on `line`, or `null` when the line
- * carries no closed block comment.
+ * 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
@@ -32,14 +33,14 @@ function multiLineBlockNameMatches(blockLine, category) {
 function blockCommentBody(line) {
     const open = line.indexOf('/*');
     if (open === -1)
-        return null;
+        return undefined;
     const close = line.indexOf('*/', open + 2);
     if (close === -1)
-        return null;
+        return undefined;
     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.
@@ -49,14 +50,15 @@ function isSingleLineBannerLine(line) {
     return body !== undefined && body.length >= 2 && body.startsWith('=') && body.endsWith('=');
 }
 /**
- * Name declared by a single-line banner (`/* = Foo = *\/` → `Foo`), or `null`
- * when the line is not a named banner. The `=` runs on both sides are
- * required; a decorative all-`=` rule carries no name and yields `null`.
+ * 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
+ * `undefined`.
  */
 function singleLineBannerName(line) {
     const body = blockCommentBody(line);
-    if (body === null)
-        return null;
+    if (body === undefined)
+        return undefined;
     let start = 0;
     let end = body.length;
     while (start < end && /\s/.test(body[start] ?? ''))
@@ -65,27 +67,26 @@ function singleLineBannerName(line) {
     while (start < end && body[start] === '=')
         start++;
     if (start === leadingEqStart)
-        return null;
+        return undefined;
     while (end > start && /\s/.test(body[end - 1] ?? ''))
         end--;
     const trailingEqEnd = end;
     while (end > start && body[end - 1] === '=')
         end--;
     if (end === trailingEqEnd)
-        return null;
+        return undefined;
     const name = body.slice(start, end).trim();
-    return name.length > 0 ? name : null;
+    return name.length > 0 ? name : undefined;
 }
 /**
  * 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.
  */
 export function categoryHeaderExists(lines, category) {
     const singleLinePattern = singleLineBannerPattern(category);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
+    for (const [i, line] of lines.entries()) {
         if (singleLinePattern.test(line)) {
             return true;
         }
@@ -112,32 +113,47 @@ 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`
+ * when that line opens no banner.
+ *
+ * The single reader for both banner shapes, so the inventory walk, the
+ * "available categories" error body and the section finder cannot drift on
+ * what counts as a header.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param index - 0-based line index to test
+ * @returns The declared category name, or undefined
+ */
+export function categoryBannerNameAt(lines, index) {
+    const line = lines[index] ?? '';
+    const extracted = singleLineBannerName(line);
+    if (extracted !== undefined)
+        return extracted;
+    if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+        for (let j = index + 1; j < Math.min(index + 6, lines.length); j++) {
+            const blockLine = lines[j] ?? '';
+            if (/\*\//.test(blockLine))
+                break;
+            const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
+            if (trimmed.length === 0)
+                continue;
+            if (/^=+$/.test(trimmed))
+                continue;
+            return trimmed;
+        }
+    }
+    return undefined;
+}
 function discoverCategoryHeaders(lines) {
     const categories = new Set();
     for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        const extracted = singleLineBannerName(line);
-        if (extracted !== null) {
-            categories.add(extracted);
-            continue;
-        }
-        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
-            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
-                const blockLine = lines[j] ?? '';
-                if (/\*\//.test(blockLine))
-                    break;
-                const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
-                if (trimmed.length === 0)
-                    continue;
-                if (/^=+$/.test(trimmed))
-                    continue;
-                categories.add(trimmed);
-                break;
-            }
-        }
+        const name = categoryBannerNameAt(lines, i);
+        if (name !== undefined)
+            categories.add(name);
     }
     return [...categories];
 }
@@ -177,7 +193,7 @@ export async function assertTokenCategoryExists(engineDir, tokensCssPath, catego
  */
 export function declareCategoryBanner(lines, category, tokensCssPath) {
     const bounds = findBaseRootBounds(lines);
-    if (bounds === null) {
+    if (bounds === undefined) {
         throw new GeneralError(`Cannot create category "${category}": no :root block found in ${tokensCssPath}. ` +
             'Run "fireforge furnace init --force" to re-scaffold the tokens CSS file.');
     }
@@ -190,14 +206,13 @@ export function declareCategoryBanner(lines, category, tokensCssPath) {
 export function findCategorySection(lines, category, tokensCssPath) {
     const singleLinePattern = singleLineBannerPattern(category);
     let categoryLine = -1;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
+    for (const [i, line] of lines.entries()) {
         // Check single-line format: /* = Category = */
         if (singleLinePattern.test(line)) {
             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] ?? '';
@@ -245,16 +260,10 @@ export function findCategorySection(lines, category, tokensCssPath) {
     return { categoryLine, sectionEnd };
 }
 /** 0-based open/close line indices of the base `:root {` block. */
-function findBaseRootBounds(lines) {
-    let open = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (/:root\s*\{/.test(lines[i] ?? '')) {
-            open = i;
-            break;
-        }
-    }
+export function findBaseRootBounds(lines) {
+    const open = lines.findIndex((line) => /:root\s*\{/.test(line));
     if (open === -1)
-        return null;
+        return undefined;
     for (let i = open + 1; i < lines.length; i++) {
         if (/^\s*\}/.test(lines[i] ?? '')) {
             return { open, close: i };
@@ -263,20 +272,20 @@ function findBaseRootBounds(lines) {
     return { open, close: -1 };
 }
 /** Masks block-comment content per line so declarations inside comments never match. */
-function maskCommentLines(lines) {
+export function maskCommentLines(lines) {
     const masked = lines.join('\n').replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
     return masked.split('\n');
 }
 /**
  * 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`).
  */
 export function findTokenDeclarationInRoot(lines, tokenName) {
     const bounds = findBaseRootBounds(lines);
-    if (bounds === null || bounds.close === -1)
+    if (bounds === undefined || bounds.close === -1)
         return undefined;
     const masked = maskCommentLines(lines);
     const declPattern = new RegExp(`^\\s*${escapeRegex(tokenName)}\\s*:`);

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.