@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/core/tree-store.js

@@ -2,8 +2,8 @@
 /**
  * Verification-tree storage and lifecycle for `fireforge tree`.
  *
- * A tree is a FULL project-root CoW snapshot under
- * `.fireforge/trees/<name>` — `getProjectRoot()` walks up from cwd, so
+ * A tree is a full project-root CoW snapshot under
+ * `.fireforge/trees/<name>`. `getProjectRoot()` walks up from cwd, so
  * every read command (status, lint, typecheck, verify, doctor,
  * `export --dry-run`) runs inside the tree unmodified and its build /
  * engine-session locks key on the tree root automatically. Trees are
@@ -92,23 +92,23 @@ export function getTreeMarkerPath(root) {
  *
  * Only ENOENT/ENOTDIR mean `absent`: any other probe failure (EACCES on the
  * `.fireforge` directory, EIO, …) reports `corrupt`, because "we cannot read
- * the marker" is not evidence that there is no marker — a `pathExists`
+ * the marker" is not evidence that there is no marker: a `pathExists`
  * pre-check classifies a tree with an unreadable `.fireforge` as `absent`
  * and hands it the full mutating command set.
  */
 /**
  * Naming convention for state-file readers:
- *   - `readX(): Promise<XRead>` — the TRI-STATE read: absent, corrupt, or
+ *   - `readX(): Promise<XRead>` is the tri-state read: absent, corrupt, or
  *     valid.
- *   - `tryReadX(): Promise<X | undefined>` — collapses absent and corrupt.
+ *   - `tryReadX(): Promise<X | undefined>` collapses absent and corrupt.
  */
 export async function readTreeMarker(root) {
     const markerPath = getTreeMarkerPath(root);
     try {
         const raw = await readJson(markerPath);
-        // Version FIRST, and reported distinctly. Folding the schemaVersion
-        // check into `isTreeMarker` makes a marker from a NEWER FireForge read
-        // as "missing or mistypes a required field" — and `tree-guard.ts` is
+        // Version first, and reported distinctly. Folding the schemaVersion
+        // check into `isTreeMarker` makes a marker from a newer FireForge read
+        // as "missing or mistypes a required field", and `tree-guard.ts` is
         // default-deny on corrupt, so the operator is locked out of every
         // mutating command inside the tree by a message claiming the file is
         // malformed when it is merely newer.
@@ -135,7 +135,7 @@ export async function readTreeMarker(root) {
 }
 /**
  * Reads the tree marker for a project root, or undefined when it is absent
- * OR unreadable.
+ * or unreadable.
  *
  * For display and best-effort paths only (`tree list` renders an unreadable
  * marker as staleness 'unknown'). Anything that decides whether a mutation may
@@ -150,8 +150,8 @@ export async function tryReadTreeMarker(root) {
  * the one this tree's marker vouched for as rewritten-and-reconfigured. A
  * mismatch means an objdir appeared in the tree through some path other than
  * `tree create --with-objdir` (manual copy, partial restore), so nothing
- * proves it was relocated — running against it could consult primary paths.
- * No-op outside a tree; a corrupt marker is already refused by the guard.
+ * proves it was relocated, and running against it could consult primary paths.
+ * No-op outside a tree. A corrupt marker is already refused by the guard.
  */
 export async function assertObjdirMatchesTreeMarker(projectRoot, objDir) {
     const state = await readTreeMarker(projectRoot);
@@ -214,17 +214,17 @@ export function assertValidTreeName(name) {
 }
 /**
  * Refuses an objdir that is not a plain directory physically inside
- * `engineDir` — every `cp` mode `cloneEntry` uses preserves symlinks, so
+ * `engineDir`. Every `cp` mode `cloneEntry` uses preserves symlinks, so
  * a symlinked `engine/obj-*` would be cloned as a symlink pointing back
  * at the original (primary or fully external) build, and the clone's
  * mozinfo rewrite and `_virtualenvs` removal would then mutate that
  * original through the link. Checks lstat (the entry itself must be a
- * real directory) AND realpath containment (a real directory reached
- * through a symlinked parent resolves elsewhere) — the rewriter's
+ * real directory) and realpath containment (a real directory reached
+ * through a symlinked parent resolves elsewhere). The rewriter's
  * lexical `resolve()` paths cannot detect either. Also validates the
  * name as a single `obj-*` path segment. Role `'primary'` guards before
- * any copying starts; `'cloned'` re-checks the tree's copy before any
- * write goes through it (defense in depth).
+ * any copying starts. Role `'cloned'` re-checks the tree's copy before
+ * any write goes through it (defense in depth).
  */
 async function assertCloneSafeObjdir(engineDir, objDir, role) {
     const where = role === 'primary' ? 'engine/' : "the tree's engine/";
@@ -259,8 +259,8 @@ async function assertCloneSafeObjdir(engineDir, objDir, role) {
  * Materialises the tree at `treeRoot` from `primaryRoot` using `capability`
  * ('none' = plain copy, already gated on --force-copy by the caller).
  *
- * The engine is cloned one TOP-LEVEL entry at a time so unwanted `obj-*`
- * directories are never traversed or materialised — on a Firefox tree, even
+ * The engine is cloned one top-level entry at a time so unwanted `obj-*`
+ * directories are never traversed or materialised. On a Firefox tree, even
  * CoW-cloning and then deleting an objdir touches metadata for millions of
  * build outputs. With `withObjdir` exactly that objdir is included (after
  * {@link assertCloneSafeObjdir} refuses symlinked or engine-escaping objdirs
@@ -272,7 +272,7 @@ async function assertCloneSafeObjdir(engineDir, objDir, role) {
 export async function cloneTree(args) {
     const { primaryRoot, treeRoot, name, capability, createdAt, withObjdir } = args;
     if (withObjdir) {
-        // Refuse a symlinked/escaping primary objdir BEFORE any copying: the
+        // Refuse a symlinked/escaping primary objdir before any copying: the
         // clone would carry the symlink and every later write would land in
         // the original build (see assertCloneSafeObjdir).
         await assertCloneSafeObjdir(join(primaryRoot, 'engine'), withObjdir.objDir, 'primary');
@@ -293,8 +293,8 @@ export async function cloneTree(args) {
         });
     });
     // A selected objdir embeds absolute topsrcdir/topobjdir paths back into
-    // the PRIMARY tree. It is rewritten below before the marker records it as
-    // usable; no other objdir ever enters the snapshot.
+    // the primary tree. It is rewritten below before the marker records it as
+    // usable. No other objdir ever enters the snapshot.
     if (await pathExists(engineDir)) {
         // Defensive: never inherit a mid-operation git index lock.
         await rm(join(engineDir, '.git', 'index.lock'), { force: true });
@@ -302,7 +302,7 @@ export async function cloneTree(args) {
     if (withObjdir) {
         await rewriteClonedObjdir(engineDir, withObjdir.objDir);
         // Regenerate configure output (config.status, backend.mk, Makefile,
-        // config/autoconf.mk) against the tree's paths — the mozinfo rewrite
+        // config/autoconf.mk) against the tree's paths. The mozinfo rewrite
         // alone leaves those naming the primary. A failed reconfigure throws
         // before the marker below records the objdir as usable (fail-closed).
         await withObjdir.reconfigure(engineDir);
@@ -314,7 +314,7 @@ export async function cloneTree(args) {
     }
     if (withObjdir) {
         // The in-tree stale-build and static-components gates anchor on the
-        // last-build baseline; without the copy they would read `undefined`
+        // last-build baseline. Without the copy they would read `undefined`
         // and degrade to first-build semantics inside a fully built tree.
         const baseline = getBuildBaselinePath(primaryRoot);
         if (await pathExists(baseline)) {
@@ -339,7 +339,7 @@ export async function cloneTree(args) {
  * Points the cloned objdir at the tree: rewrites mozinfo.json's
  * topsrcdir/topobjdir (and an in-tree mozconfig) via the same
  * safe-relocation rewriter `build --rewrite-mozinfo` uses, refusing
- * fail-closed when its safety rules cannot prove the rewrite correct —
+ * fail-closed when its safety rules cannot prove the rewrite correct:
  * a tree must never hold an objdir that still names the primary. Before
  * any write, the cloned objdir is re-checked as a real directory inside
  * the tree ({@link assertCloneSafeObjdir}) so no write ever goes through
@@ -347,7 +347,7 @@ export async function cloneTree(args) {
  * removed outright: their scripts carry primary-tree shebang paths, and
  * mach rebuilds venvs in-tree on first use. The configure-generated root
  * files (config.status, backend.mk, Makefile, config/autoconf.mk) still
- * name the primary after this rewrite; they are regenerated by the
+ * name the primary after this rewrite. They are regenerated by the
  * in-tree `mach configure` the caller supplies to {@link cloneTree},
  * which runs before the marker is written.
  */
@@ -391,7 +391,7 @@ export async function listTrees(primaryRoot) {
 }
 /**
  * Classifies a mkdir-style lock directory. Reads the lock's owner file
- * directly (line 1 = PID — the format `file-lock.ts` documents as stable,
+ * directly (line 1 = PID, the format `file-lock.ts` documents as stable,
  * whose name it shares via {@link LOCK_PID_FILE}) instead of exporting
  * file-lock internals.
  *
@@ -402,7 +402,7 @@ export async function listTrees(primaryRoot) {
  *
  * The `unknown` state is not theoretical. `withFileLock` takes the lock by
  * creating the directory and only *then* writes the owner file, treating a
- * write failure as non-fatal — so every acquisition passes through a window
+ * write failure as non-fatal, so every acquisition passes through a window
  * in which the lock is genuinely held and has no readable PID, and a
  * read-only or full filesystem leaves it that way for the lock's whole life.
  * Reporting that as `free` lets `removeTree` recursively delete a tree out
@@ -419,8 +419,9 @@ async function inspectTreeLock(lockPath) {
     }
     catch (error) {
         // A lock cleanly released between the existence probe above and this read
-        // leaves no directory behind — that is a release, not an unreadable owner,
-        // and demanding --force for it would be a spurious refusal.
+        // leaves no directory behind. That is a release rather than an
+        // unreadable owner, and demanding --force for it would be a spurious
+        // refusal.
         if (!existsSync(lockPath))
             return { kind: 'free' };
         return {
@@ -436,16 +437,17 @@ async function inspectTreeLock(lockPath) {
 }
 /**
  * Removes one tree. Refuses when a live process holds the tree's build
- * or engine-session lock — or when a lock directory exists whose ownership
- * cannot be established, which `--force` overrides — and never deletes a path
+ * or engine-session lock, or when a lock directory exists whose ownership
+ * cannot be established (which `--force` overrides). Never deletes a path
  * outside the trees directory (containment check before `rm -rf`).
  */
 export async function removeTree(primaryRoot, name, options = {}) {
     assertValidTreeName(name);
     // Both sides resolved: the containment prefix has to be in the same form as
     // the path it guards. `getTreesDir` is a `join`, so on Windows it yields a
-    // drive-less path while `resolve` below adds the drive letter — the prefix
-    // test then failed for EVERY tree and refused each removal as an escape.
+    // drive-less path while `resolve` below adds the drive letter, so the
+    // prefix test then failed for every tree and refused each removal as an
+    // escape.
     const treesDir = resolve(getTreesDir(primaryRoot));
     const treeRoot = resolve(treesDir, name);
     if (!treeRoot.startsWith(treesDir + sep) || basename(treeRoot) !== name) {

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

@@ -4,7 +4,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.
@@ -13,15 +13,15 @@
 export declare const SHIM_FILENAME = "__fireforge_firefox_globals.d.ts";
 /**
  * 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 declare const TEST_HARNESS_SHIM = "\n// \u2500\u2500 FireForge test-harness shim (loose baseline) \u2500\u2500\ndeclare var TestUtils: any;\ndeclare var BrowserTestUtils: any;\ndeclare var SpecialPowers: any;\ndeclare var EventUtils: any;\ndeclare var SimpleTest: any;\ndeclare var Assert: any;\ndeclare var gTestPath: string;\ndeclare var content: any;\ndeclare function add_task(task: (...args: any[]) => any): any;\ndeclare function add_setup(task: (...args: any[]) => any): any;\ndeclare function ok(condition: any, message?: string): void;\ndeclare function is(actual: any, expected: any, message?: string): void;\ndeclare function isnot(actual: any, expected: any, message?: string): void;\ndeclare function todo(condition: any, message?: string): void;\ndeclare function todo_is(actual: any, expected: any, message?: string): void;\ndeclare function info(message: string): void;\ndeclare function registerCleanupFunction(callback: (...args: any[]) => any): void;\ndeclare function waitForExplicitFinish(): void;\ndeclare function finish(): void;\ndeclare function do_get_profile(): any;\ndeclare function run_test(): any;\n\n";
@@ -32,7 +32,7 @@ export declare const TEST_HARNESS_SHIM = "\n// \u2500\u2500 FireForge test-harne
  * 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.
@@ -44,8 +44,9 @@ export declare const SUPPRESSED_DIAGNOSTIC_CODES: ReadonlySet<number>;
  * 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 declare const UNDEFINED_IDENTIFIER_CODES: ReadonlySet<number>;
 /** Hint appended to reported undefined-identifier diagnostics. */
@@ -62,18 +63,18 @@ export interface ComposedShim {
 /**
  * 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-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.