@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/typecheck-shim.js

@@ -5,7 +5,7 @@
  * `fireforge typecheck` command (`typecheck.ts`).
  *
  * Centralised so both flows agree on the same Firefox-globals shim
- * and the same set of suppressed diagnostic codes — drift between the
+ * and the same set of suppressed diagnostic codes. Drift between the
  * two would mean a patch could lint clean under `fireforge lint` but
  * still fail `fireforge typecheck`, or vice versa, for reasons the
  * operator could not infer from the rule names.
@@ -17,7 +17,7 @@ export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
 /**
  * Minimal `.d.ts` shim for Firefox privileged-scope globals.
  *
- * Firefox source is plain JS — no TypeScript allowed. The shim lets
+ * Firefox source is plain JS, with no TypeScript allowed. The shim lets
  * TS-driven type checking run without reporting "cannot find name"
  * for the most common Mozilla APIs. Types are intentionally loose
  * (`any`) because full Firefox type coverage is out of scope.
@@ -25,7 +25,7 @@ export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
  * Structured globals (`ChromeUtils`, `Localization`) are declared via
  * named global interfaces (`ChromeUtilsShim`, `LocalizationShim`, …)
  * rather than closed object-literal types, so a project's extra shim
- * (`patchLint.checkJsExtraShim` / `typecheck.extraShim`) can ADD members
+ * (`patchLint.checkJsExtraShim` / `typecheck.extraShim`) can add members
  * through TypeScript interface merging:
  *
  *   // my-extra-shim.d.ts
@@ -34,27 +34,27 @@ export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
  *   }
  *
  * (A second `declare var ChromeUtils` in the extra shim remains a
- * duplicate-identifier error by design — merge the interface instead.)
+ * duplicate-identifier error by design. Merge the interface instead.)
  * The member lists track upstream WebIDL additions per Firefox release
- * (`dom/chrome-webidl/ChromeUtils.webidl` for ChromeUtils); when a new
+ * (`dom/chrome-webidl/ChromeUtils.webidl` for ChromeUtils). When a new
  * release adds a commonly-patched member, add a loose signature here.
  *
  * Notable patterns that require shimming:
  * - `const lazy = {};` + `ChromeUtils.defineESModuleGetters(lazy, { ... })`
- *   populates `lazy` at runtime; we declare it as `Record<string, any>`.
+ *   populates `lazy` at runtime, so we declare it as `Record<string, any>`.
  * - `Services.obs`, `Services.prefs`, etc. are XPCOM service accessors.
  * - `Ci`, `Cc`, `Cr`, `Cu` are XPCOM component shortcuts.
  * - Browser chrome globals like `gBrowser`, `gURLBar` are common in
  *   content scripts wired via `browser.js`.
  * - Dynamic `import("resource:-…")` / `import("chrome:-…")` under patch
  *   checkJs: imports of *patch-owned* modules resolve to their real
- *   sources (see `patch-lint-checkjs.ts`); everything else fails host
+ *   sources (see `patch-lint-checkjs.ts`). Everything else fails host
  *   resolution and lands on these URL ambient wildcards, keeping
  *   upstream Firefox imports pragmatically loose, same posture as globals.
  */
 const FIREFOX_GLOBALS_SHIM = `
 declare var Services: any;
-// Extensible via interface merging from a project extra shim — see the
+// Extensible via interface merging from a project extra shim; see the
 // module doc comment in typecheck-shim.ts.
 interface ChromeUtilsShim {
   defineESModuleGetters(target: any, modules: Record<string, string>): void;
@@ -67,7 +67,7 @@ interface ChromeUtilsShim {
   getClassName(obj: any, unwrap?: boolean): string;
   isClassInfo(obj: any): boolean;
   // Firefox 153, dom/chrome-webidl/ChromeUtils.webidl: two overloads
-  // (URI string / nsIURI) with a PredictRemoteTypeOptions dictionary —
+  // (URI string / nsIURI) with a PredictRemoteTypeOptions dictionary,
   // collapsed into one loose signature per the shim's pragmatic posture.
   predictRemoteTypeForURI(uri: string | object | null, options?: object): string | null;
 }
@@ -98,7 +98,7 @@ declare class JSWindowActorParent {
   sendAsyncMessage(name: string, data?: any, transfers?: any[]): void;
   sendQuery(name: string, data?: any, transfers?: any[]): Promise<any>;
 }
-// Fluent localization — a stable chrome global. Members stay loose (any),
+// Fluent localization, a stable chrome global. Members stay loose (any),
 // but the constructor shape is declared so "new Localization([...])" and
 // "new Localization([...], true)" typecheck without a local cast. Both
 // interfaces are extensible via interface merging from a project extra
@@ -122,7 +122,7 @@ interface LocalizationShim {
 }
 declare var Localization: LocalizationShim;
 
-// Shorthand ambient modules — exports from matching URL imports are loosely typed,
+// Shorthand ambient modules: exports from matching URL imports are loosely typed,
 // avoiding noResolve empty-graph namespaces. (Named member access broke when we tried
 // export= Record under moduleResolution Bundler.)
 declare module 'resource:*';
@@ -131,15 +131,15 @@ declare module 'chrome:*';
 `;
 /**
  * Loose declarations for Firefox test-harness globals (mochitest
- * browser-chrome and xpcshell), appended AFTER the composed
+ * browser-chrome and xpcshell), appended after the composed
  * Firefox-globals + consumer shim when `patchLint.checkJsTestFiles`
  * extends the checkJs pass to patch-adopted test scripts.
- * Deliberately `any`-typed — the pragmatic posture matches the main
- * shim. A consumer that wants TYPED harness members (so e.g. a call to
- * a method the harness does not declare fails at the patch boundary)
- * declares them in `patchLint.checkJsTestShim`; because that shim
- * composes BEFORE this baseline and TypeScript resolves conflicting
- * `declare var` redeclarations to the FIRST declaration, the typed
+ * These are `any`-typed, the same pragmatic posture as the main
+ * shim. A consumer that wants typed harness members (so that, say, a call
+ * to a method the harness does not declare fails at the patch boundary)
+ * declares them in `patchLint.checkJsTestShim`. Because that shim
+ * composes before this baseline and TypeScript resolves conflicting
+ * `declare var` redeclarations to the first declaration, the typed
  * consumer declaration wins over the loose fallback here.
  */
 export const TEST_HARNESS_SHIM = `
@@ -174,7 +174,7 @@ declare function run_test(): any;
  * build system: the resolver can't follow `resource://`/`chrome://`
  * URLs and the global shim is intentionally narrow.
  *
- * Widening this set should be deliberate and per-code — silently
+ * Widening this set should be deliberate and per-code: silently
  * suppressing more codes hides real type errors. The same set is used
  * by both flows so a patch can't pass one and fail the other for a
  * reason the operator couldn't infer from the docs.
@@ -193,8 +193,9 @@ export const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
  * a module reference a name with no import or declaration anywhere and still
  * typecheck with 0 errors, so the failure surfaces as a runtime
  * `ReferenceError`. Both flows report these at a configurable severity
- * (default `'warning'`: visible without breaking gates; genuine shim gaps
- * are silenced by adding the global to `extraShim`, or per-run via `'off'`).
+ * (default `'warning'`: visible without breaking gates, while genuine shim
+ * gaps are silenced by adding the global to `extraShim`, or per-run via
+ * `'off'`).
  */
 export const UNDEFINED_IDENTIFIER_CODES = new Set([
     2304, // Cannot find name '{0}'.
@@ -243,18 +244,18 @@ async function inlineTripleSlashReferences(source, baseDir, seen) {
 /**
  * Composes the synthetic shim source by concatenating the built-in Firefox
  * globals shim with the contents of an optional user-supplied `.d.ts` file.
- * The user file is appended verbatim — the augment direction is intentional
+ * The user file is appended verbatim. The augment direction is intentional
  * (declarations later in concat order augment earlier ones), so a project
  * that wants to refine `Services` with a more specific type can do so in the
- * extra shim, and members can be ADDED to the structured globals by merging
- * their interfaces (`interface ChromeUtilsShim { newMember(): any }` — see
+ * extra shim, and members can be added to the structured globals by merging
+ * their interfaces (`interface ChromeUtilsShim { newMember(): any }`, see
  * the module doc comment). Any triple-slash `/// <reference path="…">`
  * directives inside the extra shim are inlined (resolved against the extra
  * shim's own directory) so they are not silently dropped at the synthetic
  * shim path.
  *
  * Missing extra-shim files raise a clear error rather than failing silently
- * with a confusing "type not found" downstream — this is the one
+ * with a confusing "type not found" downstream. This is the one
  * config-driven path where a user typo in `fireforge.json` produces a
  * runtime error, so it needs to be unmistakable.
  *

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

@@ -4,8 +4,8 @@
  * command.
  *
  * Distinct from `patch-lint-checkjs.ts` (patch-hygiene): patchLint is
- * scoped, fireforge-controlled, and runs as part of `fireforge lint`;
- * this command runs whole projects with user-controlled compiler
+ * scoped, fireforge-controlled, and runs as part of `fireforge lint`.
+ * This command runs whole projects with user-controlled compiler
  * options and is intended as a CI gate. The two share the Firefox
  * globals shim and suppressed-code list (via `typecheck-shim.ts`) so
  * a file that lints clean cannot fail typecheck for a reason the
@@ -13,7 +13,7 @@
  *
  * Loads the TypeScript compiler API via dynamic import so it is only
  * required when `typecheck.projects` is configured. TypeScript
- * remains a dev-dependency — if a user invokes `fireforge typecheck`
+ * remains a dev-dependency. If a user invokes `fireforge typecheck`
  * without installing it, the function returns a clear error pointing
  * at `npm install typescript`.
  */
@@ -22,7 +22,7 @@ import type { TypecheckProjectResult } from '../types/typecheck.js';
 /**
  * Sentinel string surfaced as a `TypecheckIssue.message` when the
  * project's jsconfig sets `checkJs: false`. Exported so tests can
- * pin the contract — operators rely on it to spot opted-out projects
+ * pin the contract, since operators rely on it to spot opted-out projects
  * in CI logs.
  */
 export declare const CHECK_JS_DISABLED_NOTICE = "Project sets \"checkJs: false\" \u2014 skipping (override the jsconfig to enable typecheck).";
@@ -31,20 +31,20 @@ export declare const CHECK_JS_DISABLED_NOTICE = "Project sets \"checkJs: false\"
  *
  * Per-project flow:
  *   1. Read the jsconfig via the TS API. JSON parse / config-spec
- *      errors are surfaced as issues, not thrown — a single broken
- *      project must not abort the rest of the run.
+ *      errors are surfaced as issues rather than thrown, because a single
+ *      broken project must not abort the rest of the run.
  *   2. Compute final compiler options from the user's options. We
- *      only force `noEmit: true` (this is a typecheck, not a build);
- *      we honour `strict`, `target`, `lib`, `module`, `paths`,
+ *      only force `noEmit: true` (this is a typecheck, not a build).
+ *      We honour `strict`, `target`, `lib`, `module`, `paths`,
  *      `include`, `exclude`. `allowJs` and `checkJs` default to
- *      `true` only when the user has not set them — if the user set
+ *      `true` only when the user has not set them. If the user set
  *      `checkJs: false` we treat that as an explicit opt-out and
  *      skip the project with a single notice (see {@link CHECK_JS_DISABLED_NOTICE}).
  *   3. Inject the synthetic shim (built-in + optional extraShim) as
  *      a virtual root file that the custom CompilerHost serves.
- *   4. Build the program; collect semantic, syntactic, options, and
- *      global diagnostics. The patchLint flow only reads semantic +
- *      syntactic — fine for hygiene, but a CI gate needs the full
+ *   4. Build the program and collect semantic, syntactic, options,
+ *      and global diagnostics. The patchLint flow only reads semantic +
+ *      syntactic, which is fine for hygiene, but a CI gate needs the full
  *      set so misconfigured `lib`/`paths` entries fail loudly.
  *   5. Drop diagnostics whose code is in `SUPPRESSED_DIAGNOSTIC_CODES`
  *      and any diagnostic originating in the synthetic shim itself.

package/dist/src/core/typecheck.js

@@ -5,8 +5,8 @@
  * command.
  *
  * Distinct from `patch-lint-checkjs.ts` (patch-hygiene): patchLint is
- * scoped, fireforge-controlled, and runs as part of `fireforge lint`;
- * this command runs whole projects with user-controlled compiler
+ * scoped, fireforge-controlled, and runs as part of `fireforge lint`.
+ * This command runs whole projects with user-controlled compiler
  * options and is intended as a CI gate. The two share the Firefox
  * globals shim and suppressed-code list (via `typecheck-shim.ts`) so
  * a file that lints clean cannot fail typecheck for a reason the
@@ -14,7 +14,7 @@
  *
  * Loads the TypeScript compiler API via dynamic import so it is only
  * required when `typecheck.projects` is configured. TypeScript
- * remains a dev-dependency — if a user invokes `fireforge typecheck`
+ * remains a dev-dependency. If a user invokes `fireforge typecheck`
  * without installing it, the function returns a clear error pointing
  * at `npm install typescript`.
  */
@@ -27,7 +27,7 @@ import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, UNDEFINE
 /**
  * Sentinel string surfaced as a `TypecheckIssue.message` when the
  * project's jsconfig sets `checkJs: false`. Exported so tests can
- * pin the contract — operators rely on it to spot opted-out projects
+ * pin the contract, since operators rely on it to spot opted-out projects
  * in CI logs.
  */
 export const CHECK_JS_DISABLED_NOTICE = 'Project sets "checkJs: false" — skipping (override the jsconfig to enable typecheck).';
@@ -36,20 +36,20 @@ export const CHECK_JS_DISABLED_NOTICE = 'Project sets "checkJs: false" — skipp
  *
  * Per-project flow:
  *   1. Read the jsconfig via the TS API. JSON parse / config-spec
- *      errors are surfaced as issues, not thrown — a single broken
- *      project must not abort the rest of the run.
+ *      errors are surfaced as issues rather than thrown, because a single
+ *      broken project must not abort the rest of the run.
  *   2. Compute final compiler options from the user's options. We
- *      only force `noEmit: true` (this is a typecheck, not a build);
- *      we honour `strict`, `target`, `lib`, `module`, `paths`,
+ *      only force `noEmit: true` (this is a typecheck, not a build).
+ *      We honour `strict`, `target`, `lib`, `module`, `paths`,
  *      `include`, `exclude`. `allowJs` and `checkJs` default to
- *      `true` only when the user has not set them — if the user set
+ *      `true` only when the user has not set them. If the user set
  *      `checkJs: false` we treat that as an explicit opt-out and
  *      skip the project with a single notice (see {@link CHECK_JS_DISABLED_NOTICE}).
  *   3. Inject the synthetic shim (built-in + optional extraShim) as
  *      a virtual root file that the custom CompilerHost serves.
- *   4. Build the program; collect semantic, syntactic, options, and
- *      global diagnostics. The patchLint flow only reads semantic +
- *      syntactic — fine for hygiene, but a CI gate needs the full
+ *   4. Build the program and collect semantic, syntactic, options,
+ *      and global diagnostics. The patchLint flow only reads semantic +
+ *      syntactic, which is fine for hygiene, but a CI gate needs the full
  *      set so misconfigured `lib`/`paths` entries fail loudly.
  *   5. Drop diagnostics whose code is in `SUPPRESSED_DIAGNOSTIC_CODES`
  *      and any diagnostic originating in the synthetic shim itself.
@@ -61,8 +61,8 @@ export const CHECK_JS_DISABLED_NOTICE = 'Project sets "checkJs: false" — skipp
  *   and computing the exit code.
  */
 export async function runTypecheck(projectRoot, cfg) {
-    // Dynamic import — typescript stays a dev dependency. Same pattern
-    // as `patch-lint-checkjs.ts`; the empty-projects-array case is
+    // Dynamic import, so typescript stays a dev dependency. Same pattern
+    // as `patch-lint-checkjs.ts`. The empty-projects-array case is
     // already rejected by config-validate, so we don't gate the import
     // on `cfg.projects.length`.
     let ts;
@@ -86,7 +86,7 @@ export async function runTypecheck(projectRoot, cfg) {
             filesChecked: 0,
         }));
     }
-    // Compose the shim PER project: the effective extraShim is the per-project
+    // Compose the shim per project: the effective extraShim is the per-project
     // override (a path, or `null` to opt out) when present, else the shared
     // top-level extraShim. A project that narrows `lib`/`types` can opt out of
     // a Gecko-lib shim hub that another project needs, so the composed shim is
@@ -114,7 +114,7 @@ export async function runTypecheck(projectRoot, cfg) {
         }
         catch (err) {
             // A missing or unreadable shim fails only the project(s) that use it,
-            // not the whole run — projects with a different (or no) shim still run.
+            // not the whole run. Projects with a different (or no) shim still run.
             const message = toError(err).message;
             results.push({
                 project: projectPath,
@@ -139,12 +139,12 @@ export async function runTypecheck(projectRoot, cfg) {
 }
 /**
  * Resolves the effective extra shim for a single project: a `projectOverrides`
- * entry wins (a string path overrides; `null` opts out → `undefined`), else
+ * entry wins (a string path overrides, `null` opts out → `undefined`), else
  * the shared top-level `extraShim` applies.
  */
 function resolveProjectExtraShim(cfg, projectPath) {
     const overrides = cfg.projectOverrides;
-    if (overrides && Object.prototype.hasOwnProperty.call(overrides, projectPath)) {
+    if (overrides && Object.hasOwn(overrides, projectPath)) {
         const value = overrides[projectPath];
         return value === null ? undefined : value;
     }
@@ -171,7 +171,7 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
         };
     }
     // 1) Read the JSON config. ts.readConfigFile reports JSON-shape
-    // errors via the returned diagnostic; missing files fall back to
+    // errors via the returned diagnostic. Missing files fall back to
     // pathExists above, which gives a more directly actionable message.
     const readResult = ts.readConfigFile(absConfig, (path) => ts.sys.readFile(path));
     if (readResult.error) {
@@ -183,7 +183,7 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
     }
     // 2) Parse the config content. This is what surfaces config-spec
     // errors (unknown options, mismatched types in `compilerOptions`,
-    // bad `include` patterns, etc.) — TS5xxx codes. We surface them
+    // bad `include` patterns, etc.), the TS5xxx codes. We surface them
     // alongside semantic diagnostics so the operator sees the same
     // output `tsc -p` would have produced.
     const parsed = ts.parseJsonConfigFileContent(readResult.config, ts.sys, dirname(absConfig), 
@@ -196,7 +196,7 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
     }
     // 3) Honour explicit `checkJs: false`. The user has opted out for
     // an IDE reason (likely "checkJs floods my workflow with non-actionable
-    // notes"); flipping it on here would surface ~hundreds of issues that
+    // notes"). Flipping it on here would surface ~hundreds of issues that
     // the operator already evaluated and rejected. Surface a single
     // notice so it is visible in CI logs rather than silently passing.
     const rawConfig = readResult.config;
@@ -212,10 +212,10 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
         });
         return { project: projectPath, issues, filesChecked: parsed.fileNames.length };
     }
-    // 4) Compute final compiler options. `noEmit: true` is forced — we
+    // 4) Compute final compiler options. `noEmit: true` is forced, so we
     // never write artifacts. `allowJs` / `checkJs` default to true
     // *only* when unset (so a user can flip them off without us
-    // overriding); if the user set `allowJs: false` they're saying
+    // overriding). If the user set `allowJs: false` they're saying
     // "don't even include JS in this typecheck", which is rare but
     // legitimate (e.g. an isolated `.d.ts`-only project).
     const options = {
@@ -225,26 +225,26 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
         checkJs: parsed.options.checkJs ?? true,
         // No incremental sidecar, ever. A user jsconfig under `engine/` that sets
         // `incremental` (or names a `tsBuildInfoFile`) would have this command
-        // drop a `.tsbuildinfo` inside the primary engine checkout — a second
+        // drop a `.tsbuildinfo` inside the primary engine checkout: a second
         // writer that invalidates a concurrent `fireforge test`'s engine
         // fingerprint. This command emits nothing, so the sidecar buys nothing
         // either.
         incremental: false,
-        // skipLibCheck is not forced; the user owns it via their jsconfig.
+        // skipLibCheck is not forced. The user owns it via their jsconfig.
     };
     // `exactOptionalPropertyTypes` forbids assigning `undefined` to an
     // optional `string`, so the sidecar path is dropped rather than unset.
     delete options.tsBuildInfoFile;
     // 5) The synthetic shim file. Use a project-rooted path with a
     // hidden-style prefix so it is unlikely to collide with any real
-    // file — and never write it to disk. The CompilerHost below serves
+    // file, and never write it to disk. The CompilerHost below serves
     // it from `shimSource` for `fileExists`/`readFile`/`getSourceFile`.
     const projectDir = dirname(absConfig);
-    // Forward slashes deliberately: TypeScript normalizes every `fileName` it
+    // Forward slashes on purpose: TypeScript normalizes every `fileName` it
     // hands a CompilerHost, on every platform. A shim path carrying Windows
     // separators never matches those callbacks, so the shim is not served (its
     // globals report as undefined identifiers) and its own diagnostics are not
-    // filtered out below — the pass reports failures that do not exist.
+    // filtered out below, so the pass reports failures that do not exist.
     const shimPath = normalizePathSlashes(resolve(projectDir, `.fireforge-${SHIM_FILENAME}`));
     const rootFiles = [...parsed.fileNames, shimPath];
     const defaultHost = ts.createCompilerHost(options);
@@ -269,7 +269,7 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
     };
     const program = ts.createProgram(rootFiles, options, host);
     // Collect the full diagnostic set. patchLint reads only semantic +
-    // syntactic — fine for hygiene, wrong for CI: a misconfigured
+    // syntactic, which is fine for hygiene but wrong for CI: a misconfigured
     // `lib: ["es2015"]` or a missing `paths` target should fail
     // typecheck loudly via getOptionsDiagnostics / getGlobalDiagnostics.
     const allDiagnostics = [
@@ -281,7 +281,7 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
     for (const diag of allDiagnostics) {
         if (SUPPRESSED_DIAGNOSTIC_CODES.has(diag.code))
             continue;
-        // Drop diagnostics that originate in the synthetic shim — operators
+        // Drop diagnostics that originate in the synthetic shim. Operators
         // can't act on them and they would clutter CI logs.
         if (diag.file?.fileName === shimPath)
             continue;
@@ -298,7 +298,7 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
         }
         issues.push(diagnosticToIssue(ts, diag, absConfig, projectPath));
     }
-    verbose(`typecheck: ${projectPath} — analyzed ${String(parsed.fileNames.length)} file(s), found ${String(issues.length)} issue(s)`);
+    verbose(`typecheck: ${projectPath} — analyzed ${parsed.fileNames.length} file(s), found ${issues.length} issue(s)`);
     return {
         project: projectPath,
         issues,
@@ -308,7 +308,7 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
 /**
  * Converts a TS Diagnostic to a TypecheckIssue. The `fallbackFile`
  * is used when the diagnostic carries no source file (typical for
- * options diagnostics) — typically the absolute jsconfig path or
+ * options diagnostics). It is typically the absolute jsconfig path or
  * the project-relative form for surface-level errors. `project` is
  * threaded through so the CLI can group issues by project without
  * a second pass.
@@ -328,7 +328,7 @@ function diagnosticToIssue(ts, diag, fallbackFile, project) {
     const message = typeof diag.messageText === 'string'
         ? diag.messageText
         : ts.flattenDiagnosticMessageText(diag.messageText, '\n');
-    // Suggestion + Message categories collapse to 'warning'; only
+    // Suggestion + Message categories collapse to 'warning'. Only
     // Error stays an error. This matches what the CLI then displays.
     const category = diag.category === ts.DiagnosticCategory.Error ? 'error' : 'warning';
     return {

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

@@ -1,5 +1,5 @@
 /**
- * browser-init.js — destroy expression in onUnload()/uninit().
+ * browser-init.js: destroy expression in onUnload()/uninit().
  */
 /**
  * AST-based implementation: finds onUnload()/uninit() method body and
@@ -16,7 +16,7 @@ export declare function addDestroyAST(content: string, expression: string, marke
 export declare function legacyAddDestroy(content: string, expression: string, marker?: string): string;
 /**
  * Adds a destroy expression to the top of onUnload() or uninit() in
- * browser-init.js (LIFO ordering — newest first).
+ * browser-init.js (LIFO ordering, newest first).
  *
  * @param engineDir - Engine source root
  * @param expression - The destroy expression (e.g., "MyComponent.destroy()")

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * browser-init.js — destroy expression in onUnload()/uninit().
+ * browser-init.js: destroy expression in onUnload()/uninit().
  */
 import { join } from 'node:path';
 import MagicString from 'magic-string';
@@ -36,7 +36,7 @@ export function addDestroyAST(content, expression, marker = DEFAULT_MARKER) {
         throw new BuildError('Could not find onUnload/uninit method body via AST');
     }
     // Insert at top of method body (LIFO ordering)
-    // `noUncheckedIndexedAccess` makes this `Statement | undefined`; narrow
+    // `noUncheckedIndexedAccess` makes this `Statement | undefined`. Narrow
     // before casting rather than laundering the undefined through the cast.
     const firstRaw = body.body[0];
     const firstStmt = firstRaw ? asEstree(firstRaw) : undefined;
@@ -47,7 +47,7 @@ export function addDestroyAST(content, expression, marker = DEFAULT_MARKER) {
         indent = detectIndent(content, firstStmt.start);
     }
     else {
-        // Empty method body — insert after opening {
+        // Empty method body: insert after opening {
         insertPos = body.start + 1;
         indent = '    ';
     }
@@ -95,7 +95,7 @@ export function legacyAddDestroy(content, expression, marker = DEFAULT_MARKER) {
 }
 /**
  * Adds a destroy expression to the top of onUnload() or uninit() in
- * browser-init.js (LIFO ordering — newest first).
+ * browser-init.js (LIFO ordering, newest first).
  *
  * @param engineDir - Engine source root
  * @param expression - The destroy expression (e.g., "MyComponent.destroy()")
@@ -108,7 +108,7 @@ export async function addDestroyToBrowserInit(engineDir, expression, marker = DE
         throw new GeneralError(`${BROWSER_INIT_JS} not found in engine`);
     }
     const content = await readText(filePath);
-    // Idempotency check — look for the coerced (call) form because that is
+    // Idempotency check: look for the coerced (call) form because that is
     // what the emitter writes. Matching against the raw input would miss a
     // bare `X.destroy` invocation that coercion already persisted as
     // `X.destroy()`.

package/dist/src/core/wire-dom-fragment.d.ts

@@ -1,9 +1,9 @@
 /**
- * Top-level chrome document — DOM fragment insertion.
+ * Top-level chrome document: DOM fragment insertion.
  *
  * Default target is `browser/base/content/browser.xhtml`. Forks that replace
  * browser.xhtml with a custom top-level chrome document pass the replacement
- * path in via `targetPath`; the insertion logic is shape-agnostic (looks for
+ * path in via `targetPath`. The insertion logic is shape-agnostic (looks for
  * `#include browser-sets.inc`, then falls back to `<html:body>`), so any
  * browser.xhtml-shaped xhtml works.
  */
@@ -15,7 +15,7 @@ export declare function addDomFragmentTokenized(content: string, includeDirectiv
 /**
  * Dry-run precheck for `addDomFragment`. Reads the resolved chrome document
  * and verifies it either already contains the `#include` directive (the
- * idempotent-skip case) OR offers a locatable insertion point via
+ * idempotent-skip case) or offers a locatable insertion point via
  * {@link addDomFragmentTokenized} / {@link legacyAddDomFragment}. Throws the
  * same `Could not find insertion point in chrome document` error the real
  * run would throw when neither condition holds.

package/dist/src/core/wire-dom-fragment.js

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Top-level chrome document — DOM fragment insertion.
+ * Top-level chrome document: DOM fragment insertion.
  *
  * Default target is `browser/base/content/browser.xhtml`. Forks that replace
  * browser.xhtml with a custom top-level chrome document pass the replacement
- * path in via `targetPath`; the insertion logic is shape-agnostic (looks for
+ * path in via `targetPath`. The insertion logic is shape-agnostic (looks for
  * `#include browser-sets.inc`, then falls back to `<html:body>`), so any
  * browser.xhtml-shaped xhtml works.
  */
@@ -12,6 +12,7 @@ import { dirname, join, relative } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { toRootRelativePath } from '../utils/paths.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { escapeRegex } from '../utils/regex.js';
 import { tokenizeXhtml } from './wire-utils.js';
 export const DEFAULT_DOM_TARGET = 'browser/base/content/browser.xhtml';
@@ -22,23 +23,11 @@ export function addDomFragmentTokenized(content, includeDirective) {
     const lines = content.split('\n');
     const tokens = tokenizeXhtml(lines);
     // Find the #include browser-sets.inc token
-    let insertIndex = -1;
-    for (let i = 0; i < tokens.length; i++) {
-        const token = tokens[i];
-        if (token && token.type === 'macro' && token.raw.includes('browser-sets.inc')) {
-            insertIndex = i;
-            break;
-        }
-    }
+    let insertIndex = tokens.findIndex((token) => token.type === 'macro' && token.raw.includes('browser-sets.inc'));
     if (insertIndex === -1) {
         // Fallback: after <html:body>
-        for (let i = 0; i < tokens.length; i++) {
-            const token = tokens[i];
-            if (token && token.type === 'xml' && /<html:body/.test(token.raw)) {
-                insertIndex = i + 1;
-                break;
-            }
-        }
+        const bodyIndex = tokens.findIndex((token) => token.type === 'xml' && /<html:body/.test(token.raw));
+        insertIndex = bodyIndex === -1 ? -1 : bodyIndex + 1;
     }
     if (insertIndex === -1) {
         throw new GeneralError('Could not find insertion point in chrome document');
@@ -49,7 +38,7 @@ export function addDomFragmentTokenized(content, includeDirective) {
 /**
  * Dry-run precheck for `addDomFragment`. Reads the resolved chrome document
  * and verifies it either already contains the `#include` directive (the
- * idempotent-skip case) OR offers a locatable insertion point via
+ * idempotent-skip case) or offers a locatable insertion point via
  * {@link addDomFragmentTokenized} / {@link legacyAddDomFragment}. Throws the
  * same `Could not find insertion point in chrome document` error the real
  * run would throw when neither condition holds.
@@ -62,18 +51,18 @@ export async function probeDomFragmentInsertionPoint(engineDir, domFilePath, tar
     const targetAbsPath = join(engineDir, targetPath);
     if (!(await pathExists(targetAbsPath))) {
         // The callers in `wire.ts` run their own existence probe before
-        // invoking this helper, but a well-behaved probe is paranoid — if
+        // invoking this helper, but a well-behaved probe is careful: if
         // something changed between the two checks, fail with the same
         // error the real run would surface.
         throw new GeneralError(`${targetPath} not found in engine`);
     }
     const safeDomFilePath = toRootRelativePath(engineDir, domFilePath);
     const targetDir = dirname(targetPath);
-    const includePath = relative(targetDir, safeDomFilePath).replace(/\\/g, '/');
+    const includePath = normalizePathSlashes(relative(targetDir, safeDomFilePath));
     const includeDirective = `#include ${includePath}`;
     const content = await readText(targetAbsPath);
     if (new RegExp(`^${escapeRegex(includeDirective)}$`, 'm').test(content)) {
-        // Already wired — the real run would idempotent-skip here, so
+        // Already wired. The real run would idempotent-skip here, so
         // dry-run is allowed to proceed too.
         return;
     }
@@ -104,12 +93,12 @@ export async function addDomFragment(engineDir, domFilePath, targetPath = DEFAUL
     if (!(await pathExists(targetAbsPath))) {
         throw new GeneralError(`${targetPath} not found in engine`);
     }
-    // Compute include path relative to the target's directory — the `#include`
+    // Compute include path relative to the target's directory. The `#include`
     // directive is resolved by the preprocessor relative to the file that
     // contains it, so this must track the chrome doc's location, not a
     // hardcoded `browser/base/content/`.
     const targetDir = dirname(targetPath);
-    const includePath = relative(targetDir, safeDomFilePath).replace(/\\/g, '/');
+    const includePath = normalizePathSlashes(relative(targetDir, safeDomFilePath));
     const includeDirective = `#include ${includePath}`;
     let content = await readText(targetAbsPath);
     // Idempotency: check if the #include directive already exists (line-anchored to avoid substring matches)

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

@@ -1,5 +1,5 @@
 /**
- * browser-init.js — init expression in onLoad().
+ * browser-init.js: init expression in onLoad().
  */
 /**
  * AST-based implementation: finds onLoad() method body, locates existing
@@ -8,7 +8,7 @@
  *
  * `marker` is prepended (uppercased) to the generated comment line so the
  * emitted block carries the patch-lint `// <MARKER>:` signature that
- * `lintModificationComments` looks for; otherwise the first export after
+ * `lintModificationComments` looks for. Otherwise the first export after
  * `wire` trips `missing-modification-comment` on wire-generated edits.
  */
 export declare function addInitAST(content: string, expression: string, after?: string, marker?: string): string;