@hominis/fireforge 0.46.0 → 0.46.2

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,7 +139,7 @@ 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) {
@@ -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;
@@ -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.
  */
@@ -38,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.
@@ -51,7 +51,7 @@ 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`);
@@ -62,7 +62,7 @@ export async function probeDomFragmentInsertionPoint(engineDir, domFilePath, tar
     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;
     }
@@ -93,7 +93,7 @@ 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/`.

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;

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * browser-init.js — init expression in onLoad().
+ * browser-init.js: init expression in onLoad().
  */
 import { join } from 'node:path';
 import MagicString from 'magic-string';
@@ -22,8 +22,8 @@ const DEFAULT_MARKER = 'FIREFORGE:';
  * Default insertion point: after the last consecutive fireforge block, or at
  * the top of the method body when there is none.
  *
- * Both callers below — the `--after`-target-not-found fallthrough and the
- * no-`--after` default — must emit identical blocks, since `browser-init.js`
+ * Both callers below (the `--after`-target-not-found fallthrough and the
+ * no-`--after` default) must emit identical blocks, since `browser-init.js`
  * is written through both paths. One implementation enforces that invariant
  * rather than merely tidying.
  */
@@ -48,14 +48,14 @@ function resolveDefaultInsertion(content, body, fireforgeBlocks) {
  *
  * `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 function addInitAST(content, expression, after, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);
     // `validateWireName` accepts both `Foo.bar` and `Foo.bar()` shapes. The
     // template below interpolates the value verbatim, so a bare property
-    // path compiles to `Foo.bar;` — a silent no-op, not a lifecycle
+    // path compiles to `Foo.bar;`, a silent no-op rather than a lifecycle
     // invocation. `coerceToCall` normalises to the function-call form so
     // the emitted block always invokes the hook the operator asked for.
     const callExpression = coerceToCall(expression);
@@ -116,7 +116,7 @@ export function addInitAST(content, expression, after, marker = DEFAULT_MARKER)
  */
 export function legacyAddInit(content, expression, after, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);
-    // See `addInitAST` for the rationale — the AST and fallback paths must
+    // See `addInitAST` for the rationale: the AST and fallback paths must
     // agree on whether the emitted block is a function call, otherwise
     // operators would see different behaviour depending on which parser
     // happened to handle their browser-init.js layout.
@@ -202,7 +202,7 @@ export async function addInitToBrowserInit(engineDir, expression, after, marker
         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.init` invocation that coercion already persisted as `X.init()`.
     const callExpression = coerceToCall(expression);

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

@@ -1,5 +1,5 @@
 /**
- * browser-main.js — loadSubScript registration.
+ * browser-main.js: loadSubScript registration.
  */
 /**
  * AST-based implementation: finds the last try/catch containing

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * browser-main.js — loadSubScript registration.
+ * browser-main.js: loadSubScript registration.
  */
 import { join } from 'node:path';
 import MagicString from 'magic-string';
@@ -45,7 +45,7 @@ export function addSubscriptAST(content, name, marker = DEFAULT_MARKER) {
         indent = detectIndent(content, lastTry.start);
     }
     else {
-        // No existing loadSubScript — insert before last standalone closing brace
+        // No existing loadSubScript: insert before last standalone closing brace
         // Use line-based search to avoid matching braces inside strings/comments
         const allLines = content.split('\n');
         let lastBrace = -1;
@@ -132,7 +132,7 @@ export async function addSubscriptToBrowserMain(engineDir, name, marker = DEFAUL
         throw new GeneralError(`${BROWSER_MAIN_JS} not found in engine`);
     }
     const content = await readText(filePath);
-    // Idempotency check — include closing quote to avoid substring false positives
+    // Idempotency check. Include the closing quote to avoid substring false positives
     if (content.includes(`content/${name}.js"`)) {
         return false;
     }

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

@@ -12,7 +12,7 @@ export declare function validateWireName(value: string, label: string): void;
  * `Startup.init` or `Startup.init()` and get the same wired output.
  *
  * `validateWireName` accepts both shapes, but the generated block
- * interpolates the expression verbatim inside `${expression};` — so a bare
+ * interpolates the expression verbatim inside `${expression};`, so a bare
  * `Startup.init` emits `Startup.init;`, a plain property reference that
  * never invokes the lifecycle hook. The symptom is silent: `wire` reports
  * success and the browser-init block looks plausible, but the hook never
@@ -27,7 +27,7 @@ export declare function coerceToCall(expression: string): string;
  * Tracks multi-line block comment state across calls via the `inBlockComment`
  * parameter, allowing callers to iterate over lines while preserving context.
  *
- * **Regex literal heuristic:** When a `/` follows an operator or keyword-boundary
+ * Regex literal heuristic: when a `/` follows an operator or keyword-boundary
  * character (one of `= ( : , ! | & ? ; ~ ^ { [ \n + - * % < >`), it is treated
  * as a regex literal opener and characters are skipped until the closing `/`.
  * This heuristic can misfire on:
@@ -36,7 +36,7 @@ export declare function coerceToCall(expression: string): string;
  *   - Tagged template literals or unusual formatting.
  *
  * For Firefox source files this heuristic is sufficient because the AST-based
- * parser (via `withParserFallback`) is tried first; this function is only
+ * parser (via `withParserFallback`) is tried first. This function is only
  * used in the regex-based fallback path.
  *
  * @param line - A single line of source text
@@ -66,10 +66,10 @@ export declare function tokenizeXhtml(lines: string[]): XhtmlToken[];
  * advances to the line containing the opening brace.
  *
  * By default this helper is tolerant: when no `{` is found anywhere after
- * the signature, it still returns `braceIndex: methodLine` — which is the
+ * the signature, it still returns `braceIndex: methodLine`, which is the
  * correct answer when the signature and body brace live on the same line,
  * but is ambiguous when the method is abstract or truncated. Opt into
- * stricter behaviour by passing `requireBrace: true`; the function will
+ * stricter behaviour by passing `requireBrace: true`. The function will
  * return `null` instead of guessing, letting the caller surface a clean
  * {@link ParserFallbackError} rather than inserting into a wrong offset.
  *
@@ -86,10 +86,10 @@ export declare function findMethodBraceIndex(lines: string[], pattern: RegExp, o
  * Starting from `startLine`, walks lines using {@link countBraceDepth}
  * until the brace depth returns to zero (i.e., the enclosing block closes).
  *
- * Default behaviour is defensive — if the block never closes, the helper
+ * Default behaviour is defensive: if the block never closes, the helper
  * returns `startLine + 1` so a single malformed file does not stop the
  * entire fallback path. Pass `{ strict: true }` to opt into failing loudly
- * with a {@link ParserFallbackError} instead; new callers should prefer
+ * with a {@link ParserFallbackError} instead. New callers should prefer
  * strict mode so silent mis-insertions surface as the fallback refusing
  * to touch the file.
  *
@@ -120,7 +120,7 @@ export declare function computeFileBraceBalance(content: string): {
  * Round-trip guard used after a legacy fallback mutation: if the file's
  * net brace balance drifts between `before` and `after`, something went
  * wrong and the fallback is refusing to write a corrupted file. Expects
- * the delta to be exactly zero — wire fallbacks only insert whole
+ * the delta to be exactly zero, since wire fallbacks only insert whole
  * try/catch blocks, which always contribute equal opens and closes.
  *
  * @throws {@link ParserFallbackError} when the balance delta is non-zero.
@@ -136,7 +136,7 @@ export declare function findNearestTryLine(lines: string[], fromLine: number, lo
 /**
  * Scans lines starting from `startLine` for consecutive fireforge try-catch
  * blocks (identified by init comments or typeof guards) and returns the
- * line index just after the last such block — i.e., where a new block should
+ * line index just after the last such block, i.e. where a new block should
  * be inserted.
  *
  * Non-fireforge, non-blank, non-comment lines terminate the scan.

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

@@ -24,7 +24,7 @@ export function validateWireName(value, label) {
  * `Startup.init` or `Startup.init()` and get the same wired output.
  *
  * `validateWireName` accepts both shapes, but the generated block
- * interpolates the expression verbatim inside `${expression};` — so a bare
+ * interpolates the expression verbatim inside `${expression};`, so a bare
  * `Startup.init` emits `Startup.init;`, a plain property reference that
  * never invokes the lifecycle hook. The symptom is silent: `wire` reports
  * success and the browser-init block looks plausible, but the hook never
@@ -41,7 +41,7 @@ export function coerceToCall(expression) {
  * Tracks multi-line block comment state across calls via the `inBlockComment`
  * parameter, allowing callers to iterate over lines while preserving context.
  *
- * **Regex literal heuristic:** When a `/` follows an operator or keyword-boundary
+ * Regex literal heuristic: when a `/` follows an operator or keyword-boundary
  * character (one of `= ( : , ! | & ? ; ~ ^ { [ \n + - * % < >`), it is treated
  * as a regex literal opener and characters are skipped until the closing `/`.
  * This heuristic can misfire on:
@@ -50,7 +50,7 @@ export function coerceToCall(expression) {
  *   - Tagged template literals or unusual formatting.
  *
  * For Firefox source files this heuristic is sufficient because the AST-based
- * parser (via `withParserFallback`) is tried first; this function is only
+ * parser (via `withParserFallback`) is tried first. This function is only
  * used in the regex-based fallback path.
  *
  * @param line - A single line of source text
@@ -119,7 +119,7 @@ function isRegexLiteralStart(line, i) {
 }
 /**
  * Scans from the opening `/` of a regex literal to its closing `/`
- * (honouring escapes), returning the index of the closing slash — or the
+ * (honouring escapes), returning the index of the closing slash, or the
  * end of the line when the literal never closes.
  */
 function scanToRegexLiteralEnd(line, start) {
@@ -159,7 +159,7 @@ export function tokenizeXhtml(lines) {
     });
 }
 // ---------------------------------------------------------------------------
-// Legacy (line-based) helpers — shared by fallback implementations in
+// Legacy (line-based) helpers, shared by fallback implementations in
 // the wire target modules.  Extracted to reduce duplication and make the brace-
 // walking logic independently testable.
 // ---------------------------------------------------------------------------
@@ -168,10 +168,10 @@ export function tokenizeXhtml(lines) {
  * advances to the line containing the opening brace.
  *
  * By default this helper is tolerant: when no `{` is found anywhere after
- * the signature, it still returns `braceIndex: methodLine` — which is the
+ * the signature, it still returns `braceIndex: methodLine`, which is the
  * correct answer when the signature and body brace live on the same line,
  * but is ambiguous when the method is abstract or truncated. Opt into
- * stricter behaviour by passing `requireBrace: true`; the function will
+ * stricter behaviour by passing `requireBrace: true`. The function will
  * return `null` instead of guessing, letting the caller surface a clean
  * {@link ParserFallbackError} rather than inserting into a wrong offset.
  *
@@ -194,10 +194,10 @@ export function findMethodBraceIndex(lines, pattern, options) {
  * Starting from `startLine`, walks lines using {@link countBraceDepth}
  * until the brace depth returns to zero (i.e., the enclosing block closes).
  *
- * Default behaviour is defensive — if the block never closes, the helper
+ * Default behaviour is defensive: if the block never closes, the helper
  * returns `startLine + 1` so a single malformed file does not stop the
  * entire fallback path. Pass `{ strict: true }` to opt into failing loudly
- * with a {@link ParserFallbackError} instead; new callers should prefer
+ * with a {@link ParserFallbackError} instead. New callers should prefer
  * strict mode so silent mis-insertions surface as the fallback refusing
  * to touch the file.
  *
@@ -247,7 +247,7 @@ export function computeFileBraceBalance(content) {
  * Round-trip guard used after a legacy fallback mutation: if the file's
  * net brace balance drifts between `before` and `after`, something went
  * wrong and the fallback is refusing to write a corrupted file. Expects
- * the delta to be exactly zero — wire fallbacks only insert whole
+ * the delta to be exactly zero, since wire fallbacks only insert whole
  * try/catch blocks, which always contribute equal opens and closes.
  *
  * @throws {@link ParserFallbackError} when the balance delta is non-zero.
@@ -283,7 +283,7 @@ const FIREFORGE_BLOCK_PATTERN = /\/\/\s*.*init\s*—|typeof\s+\w+\s*!==\s*"undef
 /**
  * Scans lines starting from `startLine` for consecutive fireforge try-catch
  * blocks (identified by init comments or typeof guards) and returns the
- * line index just after the last such block — i.e., where a new block should
+ * line index just after the last such block, i.e. where a new block should
  * be inserted.
  *
  * Non-fireforge, non-blank, non-comment lines terminate the scan.