@hominis/fireforge 0.46.0 → 0.46.2

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

@@ -34,11 +34,11 @@ export async function tokenCoverageCommand(projectRoot) {
         .map((f) => f.file);
     // Also scan CSS files deployed by Furnace custom components. Deployed
     // files can be committed (and therefore absent from `git status`) while
-    // still being the primary surface where token adoption matters; looking
+    // still being the primary surface where token adoption matters. Looking
     // only at modified files silently undercounts projects where Furnace
     // writes many component-CSS files into the engine.
     const furnaceCssFiles = await collectFurnaceCustomCssFiles(projectRoot, paths.engine, tokensCssPath);
-    // De-dupe so a file that is both a custom deploy target AND modified is
+    // De-dupe so a file that is both a custom deploy target and modified is
     // scanned exactly once.
     const cssFiles = [...new Set([...statusCssFiles, ...furnaceCssFiles])];
     const tokenSourceFiles = [...new Set(statusTokenCssFiles)];
@@ -129,7 +129,7 @@ async function validateTokenSourceFiles(engineDir, tokenSourceFiles, tokenPrefix
 /**
  * Returns engine-relative `.css` paths deployed by every Furnace custom
  * component registered in `furnace.json`. Only files that actually exist
- * on disk are included — a component whose deploy target is missing (e.g.
+ * on disk are included. A component whose deploy target is missing (e.g.
  * `furnace apply` has not run yet) is skipped silently so a fresh
  * `furnace init` followed immediately by `token coverage` does not error.
  *

package/dist/src/commands/token-list.js

@@ -1,13 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `token list` and `token show` — the read half of design-token management.
+ * `token list` and `token show`: the read half of design-token management.
  *
  * `token add` requires `--category` and refuses an unknown one, but nothing
  * reported the categories a project has, so naming one meant hand-parsing a
  * neighbouring `= Category =` banner out of the tokens CSS. Both commands
  * read through `token-inventory.ts`, which is built on the same banner and
- * `:root`-bounds primitives `token add` and `token coverage` use — a second
- * tokens-CSS parser would let the report and the writer disagree about
+ * `:root`-bounds primitives `token add` and `token coverage` use, because
+ * a second tokens-CSS parser would let the report and the writer disagree about
  * which section a token lives in.
  *
  * Helper module: no registrar, called from `token.ts`.
@@ -38,7 +38,7 @@ function filterByCategory(groups, category, tokensCssPath) {
     if (matched.length > 0)
         return matched;
     // Same "name the alternatives" contract `token add` gives for an unknown
-    // category — a filter that silently prints nothing reads as "this
+    // category: a filter that silently prints nothing reads as "this
     // category is empty", which is a different fact.
     const available = groups
         .map((group) => group.category)
@@ -57,7 +57,7 @@ function filterByCategory(groups, category, tokensCssPath) {
  */
 export async function tokenListCommand(projectRoot, options = {}) {
     if (options.json === true) {
-        // stdout belongs exclusively to the payload from here on; a later
+        // stdout belongs exclusively to the payload from here on. A later
         // diagnostic (including withErrorHandling's) routes to stderr.
         setMachineOutputMode(true);
         try {

package/dist/src/commands/token.js

@@ -21,7 +21,7 @@ async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
             const strippedPrefix = furnaceConfig.tokenPrefix.replace(/^--/, '').replace(/-$/, '');
             const strippedName = rawTokenName.replace(/^--/, '');
             // A bare name that already starts with the configured prefix text is
-            // treated as fully qualified — blindly prepending would silently
+            // treated as fully qualified. Blindly prepending would silently
             // produce a double-prefixed token (e.g. "--hominis-hominis-shadow-low").
             if (strippedName === strippedPrefix || strippedName.startsWith(`${strippedPrefix}-`)) {
                 info(`Token name "${rawTokenName}" already starts with the configured prefix ` +
@@ -37,12 +37,12 @@ async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
     return normalizeTokenName(rawTokenName);
 }
 /**
- * Reports a no-op add, naming WHERE the existing declaration lives.
+ * Reports a no-op add, naming where the existing declaration lives.
  *
- * A variant skip has no category to name — the declaration lives in a
- * `:root<selector>` block — so the location reads as that block. The
+ * A variant skip has no category to name, because the declaration lives in
+ * a `:root<selector>` block, so the location reads as that block. The
  * variant path used to report no location at all, so a re-run meant to
- * CHANGE a value exited 0 having silently changed nothing.
+ * change a value exited 0 having silently changed nothing.
  *
  * @param tokenName - Full token name including prefix
  * @param result - Result carrying the skip location, when known
@@ -69,8 +69,8 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
     intro('Token Add');
     // A fresh project without furnace.json otherwise fails deep inside the
     // token-manager's `assertTokenCategoryExists` with "Token CSS file not
-    // found: browser/themes/shared/<binary>-tokens.css" — technically correct,
-    // but the operator's actual next step is to initialize Furnace, which
+    // found: browser/themes/shared/<binary>-tokens.css", which is technically
+    // correct, but the operator's actual next step is to initialize Furnace, which
     // scaffolds the tokens CSS file. Catching the uninitialized case here
     // gives the right guidance before the generic "file not found" error.
     if (!(await furnaceConfigExists(projectRoot))) {
@@ -171,9 +171,9 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
     // Commander's argument parsing.
     // Description ends with `(required)` because Commander's
     // `makeOptionMandatory` does not render a required marker in `--help`
-    // output — only `.requiredOption` does that, and switching to
+    // output. Only `.requiredOption` does that, and switching to
     // `.requiredOption` would lose the `.choices()` enforcement. The
-    // explicit suffix keeps the runtime validation AND surfaces required
+    // explicit suffix keeps the runtime validation and surfaces required
     // status in help alongside the other options that use `.requiredOption`.
     new Option('--mode <mode>', 'Dark mode behavior (required)')
         .choices(['auto', 'static', 'override'])

package/dist/src/commands/tree.js

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge tree` — copy-on-write verification clones.
+ * `fireforge tree`: copy-on-write verification clones.
  *
- * Trees enable concurrent READ-MOSTLY verification (lint, typecheck, status,
+ * Trees enable concurrent read-mostly verification (lint, typecheck, status,
  * verify, doctor, export dry-runs) beside a busy primary tree. Exports and
- * every other mutation stay strictly serial in the primary — a tree's
+ * every other mutation stay strictly serial in the primary, because a tree's
  * patches/components are snapshots with no merge model, and the tree guard
  * (cli.ts preAction + core/tree-guard.ts) refuses mutating commands inside a
  * tree.
@@ -13,8 +13,8 @@
  * directory, rewrites its mozinfo.json to the tree, and runs `mach configure`
  * inside the tree so the remaining configure output (config.status,
  * backend.mk, Makefile, config/autoconf.mk) stops naming the primary. That is
- * fail-closed by design — mach objdirs embed absolute source paths, and an
- * unrelocated clone would silently operate against the primary — and it is
+ * fail-closed by design (mach objdirs embed absolute source paths, and an
+ * unrelocated clone would silently operate against the primary), and it is
  * what admits build-less `fireforge test` inside that tree.
  */
 import { spawn } from 'node:child_process';
@@ -61,14 +61,14 @@ async function resolveObjdirForClone(projectRoot) {
 /**
  * Runs `mach configure` inside the tree's engine so the configure-generated
  * root files (config.status, backend.mk, Makefile, config/autoconf.mk) are
- * regenerated against the tree's paths — the mozinfo rewrite alone leaves
+ * regenerated against the tree's paths. The mozinfo rewrite alone leaves
  * those naming the primary, and a build-less in-tree `test` must never
  * consult primary state. Exit code 0 is not trusted on its own: configure
  * obeys MOZCONFIG / MOZ_OBJDIR, so the postcondition is verified afterwards
- * via `findObjdirRelocationViolation` — the intended objdir was configured,
+ * via `findObjdirRelocationViolation`: the intended objdir was configured,
  * its mozinfo points into the tree, and none of those root files still
  * names the primary engine (nested Makefiles are products of the verified
- * config.status; `.deps` build products are out of scope — see the
+ * config.status, and `.deps` build products are out of scope, see the
  * checker's doc). A failure throws before `cloneTree` writes the marker,
  * so the tree is removed and `clonedObjdir` is never recorded (fail-closed).
  */
@@ -102,7 +102,7 @@ export async function treeCreateCommand(projectRoot, name, options = {}) {
     intro('FireForge Tree Create');
     assertValidTreeName(name);
     // A marker we cannot parse still means "something claims this is a tree", so
-    // it must block nesting too — otherwise a corrupt marker is a licence to
+    // it must block nesting too. Otherwise a corrupt marker is a licence to
     // clone a snapshot into itself.
     const markerState = await readTreeMarker(projectRoot);
     if (markerState.kind !== 'absent') {
@@ -128,15 +128,15 @@ export async function treeCreateCommand(projectRoot, name, options = {}) {
             warn('No copy-on-write support detected — performing a full physical copy (--force-copy).');
         }
         // Courtesy fast-fail: refuse obvious no-build cases before waiting on
-        // locks. The result is DISCARDED — a build can still start before the
+        // locks. The result is discarded: a build can still start before the
         // locks below are held, so only the re-resolution under the build lock
         // is authoritative for what actually gets cloned.
         if (options.withObjdir === true) {
             await resolveObjdirForClone(projectRoot);
         }
-        // Snapshot under the PRIMARY engine-session lock so a mid-mutation
-        // state (half-applied export, furnace deploy) is never captured; an
-        // objdir snapshot additionally holds the primary BUILD lock, under
+        // Snapshot under the primary engine-session lock so a mid-mutation
+        // state (half-applied export, furnace deploy) is never captured. An
+        // objdir snapshot additionally holds the primary build lock, under
         // which the objdir is re-validated immediately before cloning so a
         // concurrent `fireforge build` can neither tear the obj-* mid-write
         // nor swap it after preflight. A failed clone (including the
@@ -183,8 +183,8 @@ export async function treeCreateCommand(projectRoot, name, options = {}) {
 export async function treeListCommand(projectRoot, options = {}) {
     if (options.json === true) {
         // stdout belongs exclusively to the JSON payload: engage machine mode so
-        // any diagnostic — including a listTrees failure rendered later by
-        // withErrorHandling, which also resets the mode — routes to stderr.
+        // any diagnostic, including a listTrees failure rendered later by
+        // withErrorHandling (which also resets the mode), routes to stderr.
         setMachineOutputMode(true);
         try {
             const trees = await listTrees(projectRoot);
@@ -280,13 +280,13 @@ async function treeExecCommand(projectRoot, name, args) {
             resolvePromise(code ?? 1);
         });
     }).finally(() => {
-        // With `stdio: 'inherit'` the child owned stdout — including any
-        // FIREFORGE-VERDICT line it emitted as its LAST stdout write. From here
+        // With `stdio: 'inherit'` the child owned stdout, including any
+        // FIREFORGE-VERDICT line it emitted as its last stdout write. From here
         // on the parent must not write stdout again, or its own refusal text
-        // (the GeneralError below, rendered by withErrorHandling) prints AFTER
+        // (the GeneralError below, rendered by withErrorHandling) prints after
         // the child's verdict and breaks the "verdict is the run's last stdout
         // line" contract at the tree-exec boundary. Sealing routes the parent's
-        // remaining output to stderr; withErrorHandling's finally clears it.
+        // remaining output to stderr. withErrorHandling's finally clears it.
         setStdoutSealed(true);
     });
     if (exitCode !== 0) {

package/dist/src/commands/typecheck.d.ts

@@ -1,10 +1,10 @@
 /**
- * `fireforge typecheck` — whole-project TypeScript type checking driven by
+ * `fireforge typecheck`: whole-project TypeScript type checking driven by
  * user-supplied jsconfig.json paths.
  *
  * Distinct from `patchLint.checkJs`: that pass is patch-hygiene (scoped to
- * patch-owned `.sys.mjs`, run automatically by `fireforge lint`); this
- * command is CI-grade — it runs whole projects with the user's own compiler
+ * patch-owned `.sys.mjs`, run automatically by `fireforge lint`). This
+ * command is CI-grade: it runs whole projects with the user's own compiler
  * options. The two share their Firefox-globals shim and the same
  * suppressed-diagnostic set so a file that lints clean cannot fail typecheck
  * for a reason the operator could not have inferred from the docs.
@@ -21,15 +21,15 @@ import type { TypecheckProjectResult } from '../types/typecheck.js';
 export interface TypecheckCommandOptions {
     /**
      * Override `typecheck.projects` with a single jsconfig.json path
-     * for one-off verification. Replaces (does not augment) the config
-     * — useful to re-run a single project after fixing one of its
+     * for one-off verification. Replaces (does not augment) the config,
+     * which is useful to re-run a single project after fixing one of its
      * issues without waiting for the full set.
      */
     project?: string;
 }
 /**
  * Resolves the project list to type-check. `--project` wins over
- * config; if neither is set, throws a clear error pointing at both
+ * config. If neither is set, throws a clear error pointing at both
  * paths to a fix (add the config field or pass --project).
  */
 export declare function resolveTypecheckProjects(configTypecheck: TypecheckConfig | undefined, override: string | undefined): TypecheckConfig;

package/dist/src/commands/typecheck.js

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge typecheck` — whole-project TypeScript type checking driven by
+ * `fireforge typecheck`: whole-project TypeScript type checking driven by
  * user-supplied jsconfig.json paths.
  *
  * Distinct from `patchLint.checkJs`: that pass is patch-hygiene (scoped to
- * patch-owned `.sys.mjs`, run automatically by `fireforge lint`); this
- * command is CI-grade — it runs whole projects with the user's own compiler
+ * patch-owned `.sys.mjs`, run automatically by `fireforge lint`). This
+ * command is CI-grade: it runs whole projects with the user's own compiler
  * options. The two share their Firefox-globals shim and the same
  * suppressed-diagnostic set so a file that lints clean cannot fail typecheck
  * for a reason the operator could not have inferred from the docs.
@@ -26,7 +26,7 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
 /**
  * Resolves the project list to type-check. `--project` wins over
- * config; if neither is set, throws a clear error pointing at both
+ * config. If neither is set, throws a clear error pointing at both
  * paths to a fix (add the config field or pass --project).
  */
 export function resolveTypecheckProjects(configTypecheck, override) {
@@ -75,7 +75,7 @@ export async function typecheckCommand(projectRoot, options) {
 }
 async function runTypecheckCommandBody(projectRoot, options) {
     // Validate project is initialised. `loadConfig` throws on missing
-    // fireforge.json — withErrorHandling at the CLI layer renders the
+    // fireforge.json, and withErrorHandling at the CLI layer renders the
     // resulting `ConfigNotFoundError` cleanly, so we don't need to
     // re-wrap.
     getProjectPaths(projectRoot);
@@ -101,8 +101,8 @@ async function runTypecheckCommandBody(projectRoot, options) {
     reportResults(projectRoot, results, patchIssues);
 }
 /**
- * Runs the per-patch-lint checkJs pass — the same program `export` and
- * `lint --per-patch` use — and returns its findings.
+ * Runs the per-patch-lint checkJs pass (the same program `export` and
+ * `lint --per-patch` use) and returns its findings.
  *
  * Returns an empty list when `patchLint.checkJs` is off or the project has
  * no patch queue: there is no second authority to reconcile then.

package/dist/src/commands/verify.d.ts

@@ -1,10 +1,10 @@
 /**
- * `fireforge verify` — read-only fsck for the patch queue.
+ * `fireforge verify`: read-only fsck for the patch queue.
  *
  * Combines the manifest consistency check (orphan files, missing entries,
  * files-affected mismatch, duplicate entries) with the cross-patch lint
  * rules (duplicate /dev/null creation, forward imports). Does not run
- * `planExport` per patch — that is intentionally out of scope because it
+ * `planExport` per patch. That is out of scope because it
  * would couple verify to engine state and make the command too slow to be
  * useful as a pre-flight gate. Engine-level patch application issues are
  * still covered by the existing `fireforge doctor` and `fireforge import`
@@ -35,7 +35,7 @@ export interface PatchQueueHealth {
 export declare function collectPatchQueueHealth(projectRoot: string): Promise<PatchQueueHealth>;
 /**
  * Runs the `verify` command: manifest consistency + cross-patch lint.
- * Read-only; exits non-zero on any error-severity finding.
+ * Read-only. Exits non-zero on any error-severity finding.
  *
  * @param projectRoot - Project root directory
  */

package/dist/src/commands/verify.js

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge verify` — read-only fsck for the patch queue.
+ * `fireforge verify`: read-only fsck for the patch queue.
  *
  * Combines the manifest consistency check (orphan files, missing entries,
  * files-affected mismatch, duplicate entries) with the cross-patch lint
  * rules (duplicate /dev/null creation, forward imports). Does not run
- * `planExport` per patch — that is intentionally out of scope because it
+ * `planExport` per patch. That is out of scope because it
  * would couple verify to engine state and make the command too slow to be
  * useful as a pre-flight gate. Engine-level patch application issues are
  * still covered by the existing `fireforge doctor` and `fireforge import`
@@ -34,16 +34,16 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
 /**
  * Walks each patch body in the manifest, extracts the set of
  * component-shaped registration references it adds (widget paths
- * implied by jar.mn + customElements.js; FTL paths implied by locale
+ * implied by jar.mn + customElements.js, and FTL paths implied by locale
  * jar.mn), and confirms every reference is either created by some
- * patch in the queue OR present as a tracked file in engine/. Any
- * unreachable reference is a dangling-registration error — the patch
+ * patch in the queue or present as a tracked file in engine/. Any
+ * unreachable reference is a dangling-registration error: the patch
  * registers a file that nothing in the world supplies, which fails at
  * install time.
  */
 async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
     // Aggregate the set of all paths any patch in the queue is responsible for
-    // (per `filesAffected`). Individual patch bodies are deliberately NOT
+    // (per `filesAffected`). Individual patch bodies are deliberately not
     // parsed for new-file creations here: `filesAffected` is already the
     // contract manifest callers rely on, and
     // `validatePatchesManifestConsistency` has already ensured the two are in
@@ -65,7 +65,7 @@ async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
         }
         catch {
             // Bad file read is surfaced by the manifest consistency check
-            // already — skipping here avoids double-reporting the same issue.
+            // already. Skipping here avoids double-reporting the same issue.
             continue;
         }
         const refs = collectPatchRegistrationReferences(body);
@@ -77,7 +77,7 @@ async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
             // Engine existence check: if the target file is already present in
             // engine/ (upstream Firefox ships it, or a separate baseline branch
             // has it), the registration is not dangling. "Is this tracked by git"
-            // cannot be probed without a git round-trip; existence on disk is a
+            // cannot be probed without a git round-trip. Existence on disk is a
             // close-enough proxy for verify's read-only context.
             if (await pathExists(join(engineDir, ref.targetPath)))
                 continue;
@@ -170,7 +170,7 @@ export async function collectPatchQueueHealth(projectRoot) {
         }
         // Engine-aware module-resolution preflight. The queue-level
         // `unregistered-system-module` rule only sees modules a patch NEWLY
-        // CREATES; this asks the same question of the engine, so an import ADDED
+        // CREATES. This asks the same question of the engine, so an import ADDED
         // to an existing module is named as text instead of surfacing later as a
         // bare `xpcshell return code: -11` with zero output.
         if (await pathExists(paths.engine)) {
@@ -253,7 +253,7 @@ export async function collectPatchQueueHealth(projectRoot) {
 }
 /**
  * Runs the `verify` command: manifest consistency + cross-patch lint.
- * Read-only; exits non-zero on any error-severity finding.
+ * Read-only. Exits non-zero on any error-severity finding.
  *
  * @param projectRoot - Project root directory
  */

package/dist/src/commands/watch.js

@@ -17,7 +17,7 @@ const WATCHMAN_PROBE_TIMEOUT_MS = 5000;
  * in PATH but cannot respond (corrupt install, server crashed mid-session,
  * permission denied on the state directory) would otherwise surface as a
  * confusing mid-watch failure. Returns the trimmed version string when
- * the probe succeeds; throws a {@link GeneralError} with actionable
+ * the probe succeeds. Throws a {@link GeneralError} with actionable
  * remediation when it does not.
  */
 async function probeWatchman() {
@@ -64,7 +64,7 @@ function hasWatchPermissionFailure(output) {
  *
  * @param exitCode - Exit code returned by `mach watch`
  * @param watchmanPath - Optional absolute path to the resolved watchman
- *   binary; surfaced in the guidance so the operator can see whether
+ *   binary, surfaced in the guidance so the operator can see whether
  *   FireForge actually found one.
  * @returns User-facing failure guidance
  */
@@ -106,10 +106,10 @@ export async function watchCommand(projectRoot) {
     // Check if engine exists
     await assertEngineExists(paths.engine);
     // Resolve the watchman binary to an absolute path up-front so we can (a)
-    // refuse fast when it is missing AND (b) prepend its directory to the mach
+    // refuse fast when it is missing and (b) prepend its directory to the mach
     // subprocess PATH. On macOS, `which watchman` from an interactive shell
     // returns `/opt/homebrew/bin/watchman`, but the Node subprocess PATH
-    // frequently omits `/opt/homebrew/bin` — so the shell probe passes and
+    // frequently omits `/opt/homebrew/bin`, so the shell probe passes and
     // mach's `watch-project` call then times out on its own failed PATH
     // lookup. Threading the directory through the subprocess env fixes it.
     const watchmanPath = await findExecutable('watchman');
@@ -117,7 +117,7 @@ export async function watchCommand(projectRoot) {
         throw new GeneralError('Watch mode requires watchman to be installed and available in PATH.\n\n' +
             'Install watchman first, then rerun "fireforge watch".');
     }
-    // Verify watchman actually responds — a binary that is in PATH but
+    // Verify watchman actually responds: a binary that is in PATH but
     // unable to respond (broken install, crashed server, bad state dir
     // permissions) would otherwise surface as a confusing mid-build failure
     // instead of an actionable preflight error.
@@ -125,7 +125,7 @@ export async function watchCommand(projectRoot) {
     // Check for build artifacts before starting watch
     // The mismatch rung rejects copied or relocated obj-* dirs whose mozinfo
     // metadata (topsrcdir, topobjdir, mozconfig) still points at a different
-    // source tree; mach watch against stale metadata produces confusing errors.
+    // source tree. mach watch against stale metadata produces confusing errors.
     const buildCheck = await hasBuildArtifacts(paths.engine);
     assertBuildArtifacts(paths.engine, buildCheck, {
         label: 'Watch mode',
@@ -136,7 +136,7 @@ export async function watchCommand(projectRoot) {
     // Report bundle state alongside the "Using build artifacts..." banner
     // so an operator watching a mid-build tree can see why `fireforge run`
     // would refuse right now while watch is still going. Watch remains
-    // permissive (it exists to drive rebuilds) — this is informational.
+    // permissive (it exists to drive rebuilds), so this is informational.
     // The `hasBuildArtifacts` check already passed at this point, so
     // `objDir` is always defined.
     const bundleCheck = buildCheck.objDir
@@ -148,7 +148,7 @@ export async function watchCommand(projectRoot) {
     info(`Using build artifacts from ${buildCheck.objDir}/${bundleSuffix}`);
     // Advisory: warn when Furnace components have drifted since the last
     // apply so the user doesn't launch watch-mode builds with stale
-    // components baked in. Mirrors the check in `fireforge run` — without
+    // components baked in. Mirrors the check in `fireforge run`: without
     // it, users editing a component then running `watch` would see their
     // change never surface in the rebuilt browser.
     await warnIfFurnaceStale(projectRoot);
@@ -173,7 +173,7 @@ export async function watchCommand(projectRoot) {
     const watchmanDir = dirname(watchmanPath);
     const existingPath = process.env['PATH'] ?? '';
     const pathSegments = existingPath.split(delimiter).filter((segment) => segment.length > 0);
-    // Both arms filter identically; the cast this replaced laundered
+    // Both arms filter identically. The cast this replaced laundered
     // `string | undefined` on one arm while the other built the annotated shape
     // honestly.
     const baseEnv = {};
@@ -197,8 +197,8 @@ export async function watchCommand(projectRoot) {
     }
     // On Ctrl+C the bin signal handler now waits for the mach child to shut
     // down (waitForActiveChildShutdown) before exiting, so this continuation
-    // can run and whitelist the SIGINT exit code — though the bin may still
-    // win the race and terminate first; both outcomes are acceptable.
+    // can run and whitelist the SIGINT exit code, though the bin may still
+    // win the race and terminate first. Both outcomes are acceptable.
     if (result.exitCode !== 0 && result.exitCode !== 130) {
         const combinedOutput = `${result.stdout}\n${result.stderr}`;
         if (hasConfigureTimeWatchmanFailure(combinedOutput)) {

package/dist/src/commands/wire.js

@@ -20,8 +20,8 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPa
     info(`  source: ${subscriptDir}/${name}.js`);
     info(`  browser-main.js: loadSubScript("chrome://browser/content/${name}.js")`);
     if (options.init) {
-        // Show the coerced form so the preview matches the emitted block —
-        // echoing the raw input ("X.init") does not reflect that the real run
+        // Show the coerced form so the preview matches the emitted block.
+        // Echoing the raw input ("X.init") does not reflect that the real run
         // writes `X.init();` to browser-init.js.
         info(`  browser-init.js: ${coerceToCall(options.init)}`);
     }
@@ -42,11 +42,11 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPa
  * Preference order:
  *   1. `--target <path>` CLI flag (explicit caller intent)
  *   2. First entry of `furnace.json.tokenHostDocuments` (fork-configured
- *      chrome doc list; already consumed by the missing-token-link
+ *      chrome doc list, already consumed by the missing-token-link
  *      validator and the doctor check)
  *   3. `browser/base/content/browser.xhtml` (upstream default)
  *
- * Step 2 is silent — a missing / invalid furnace.json falls through to the
+ * Step 2 is silent: a missing or invalid furnace.json falls through to the
  * upstream default rather than surfacing a warning, because forks that don't
  * use furnace shouldn't have to configure anything.
  */
@@ -63,7 +63,7 @@ async function resolveDomTargetPath(projectRoot, explicit) {
             }
         }
         catch {
-            // Fall through to default — a broken furnace.json should not block
+            // Fall through to the default. A broken furnace.json should not block
             // the wire command. The doctor surfaces that issue separately.
         }
     }
@@ -85,7 +85,7 @@ function validateWireName(name) {
     }
 }
 /**
- * Asserts that the resolved chrome document both exists on disk AND exposes
+ * Asserts that the resolved chrome document both exists on disk and exposes
  * an insertion anchor (`#include browser-sets.inc` or `<html:body>`) that
  * `addDomFragment` can splice into. Fires in dry-run and real-run mode
  * alike, so the preview and execution agree on whether the target is
@@ -146,7 +146,7 @@ async function ensureSubscriptSourceExists(projectRoot, subscriptDir, name, dryR
 /**
  * Validates the `--dom` fragment argument and computes its engine-root-
  * relative path. Accepts absolute, repo-root-relative (`engine/...`), and
- * engine-relative inputs; rejects missing files and paths escaping
+ * engine-relative inputs. Rejects missing files and paths escaping
  * engine/. Returns undefined when `--dom` was not supplied.
  */
 async function resolveDomFragmentPath(projectRoot, dom) {
@@ -278,10 +278,10 @@ export async function wireCommand(projectRoot, name, options = {}) {
         // --after and have it forwarded unchanged to the lookup layer.
         validateWireName(options.after);
     }
-    // Validate init/destroy expressions BEFORE the dry-run/real fork so both
+    // Validate init/destroy expressions before the dry-run/real fork so both
     // paths enforce the same contract. Validating only inside
-    // `addInitToBrowserInit`/`addDestroyToBrowserInit` — the real-execution
-    // path — lets `--dry-run --init 'void 0'` succeed and render a plausible
+    // `addInitToBrowserInit`/`addDestroyToBrowserInit` (the real-execution
+    // path) lets `--dry-run --init 'void 0'` succeed and render a plausible
     // preview even though the real run rejects the same arguments.
     if (options.init !== undefined) {
         validateWireExpression(options.init, 'init expression');
@@ -293,8 +293,8 @@ export async function wireCommand(projectRoot, name, options = {}) {
     const subscriptDir = await resolveWireSubscriptDir(projectRoot, options);
     const domFilePath = await resolveDomFragmentPath(projectRoot, options.dom);
     // Resolve the chrome document the `#include` directive will land in. Only
-    // consulted when `--dom` is supplied — resolved here anyway so the dry-run
-    // plan can print the target accurately.
+    // consulted when `--dom` is supplied, but resolved here anyway so the
+    // dry-run plan can print the target accurately.
     //
     // `stripEnginePrefix` is applied so
     // `--target engine/browser/base/browser.xhtml` and
@@ -317,7 +317,7 @@ export async function wireCommand(projectRoot, name, options = {}) {
     // setup scripts rely on.
     //
     // The check stays advisory rather than fatal in dry-run because
-    // "wire first, create file after" is a legitimate use of preview — but a
+    // "wire first, create file after" is a legitimate use of preview. But a
     // dry-run over a typo would otherwise produce a plausible plan and the
     // real command then refuse with `Subscript file not found`. The info line
     // surfaces the mismatch in preview mode.

package/dist/src/core/ast-utils.d.ts

@@ -4,7 +4,7 @@ import { walk } from 'estree-walker';
 /**
  * An ESTree node augmented with acorn's character-offset positions.
  * At runtime `acorn.parse` produces objects that carry both the ESTree
- * shape *and* `start`/`end` indices, but the type system doesn't know that.
+ * shape and `start`/`end` indices, but the type system doesn't know that.
  * This intersection type bridges the gap so we can safely use both APIs.
  */
 export type AcornESTreeNode<T extends estree.Node = estree.Node> = T & {
@@ -12,7 +12,7 @@ export type AcornESTreeNode<T extends estree.Node = estree.Node> = T & {
     end: number;
 };
 /**
- * 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.
  *
@@ -22,7 +22,7 @@ export type AcornESTreeNode<T extends estree.Node = estree.Node> = T & {
  */
 export declare function parseScript(content: string, onComment?: acorn.Comment[]): AcornESTreeNode<estree.Program>;
 /**
- * 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
@@ -34,12 +34,12 @@ export declare function parseModule(content: string, onComment?: acorn.Comment[]
  * 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