@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/core/patch-lint-binary.d.ts

@@ -2,21 +2,21 @@
  * Queue-wide lint for binary patch bodies that cannot recreate their file.
  *
  * `git diff` has two ways to render a binary change. `git diff --binary`
- * emits a `GIT binary patch` section carrying the literal/delta payload —
- * that body can be replayed by `git apply`. Plain `git diff` emits only the
- * informational `Binary files a/x and b/x differ`, which records THAT the
- * bytes changed and carries none of them.
+ * emits a `GIT binary patch` section carrying the literal/delta payload,
+ * and that body can be replayed by `git apply`. Plain `git diff` emits only
+ * the informational `Binary files a/x and b/x differ`, which records that
+ * the bytes changed and carries none of them.
  *
  * The stub form is dangerous rather than merely lossy because it still
  * carries a correct `index <old>..<new>` line. Every identity-shaped check in
- * the codebase — worktree classification, foreign-drift detection — keys on
+ * the codebase (worktree classification, foreign-drift detection) keys on
  * that hash, matches it against the live file, and concludes the patch is
  * backed. So a queue can hold a patch that provably cannot rebuild its own
  * file while every gate reports green, and the loss surfaces only at the next
  * clean-room apply. This rule is the one check that reads the body itself and
  * fails closed, whichever command wrote it.
  *
- * Body-only by design: it needs no engine checkout, so it runs anywhere the
+ * Body-only: it needs no engine checkout, so it runs anywhere the
  * queue context is available and never pulls an engine dependency into the
  * cross-patch lint graph.
  */
@@ -25,7 +25,7 @@ import type { PatchQueueBodyEntry, PatchQueueView } from './patch-lint-queue-typ
 /**
  * Queue view accepted by {@link lintPatchQueueBinaryBodies}. Described
  * structurally rather than by importing `PatchQueueContext` from
- * `patch-lint-cross.ts`, which imports this module back — the shared leaf
+ * `patch-lint-cross.ts`, which imports this module back. The shared leaf
  * type keeps the dependency edge one-way and `dpdm` clean.
  */
 type BinaryBodyQueueContext = PatchQueueView<PatchQueueBodyEntry>;

package/dist/src/core/patch-lint-cache.d.ts

@@ -53,7 +53,7 @@ export interface CachedPerPatchLint {
 }
 /**
  * Returns the cached lint payload for a patch when the stored key still
- * matches AND the entry was computed under the same lint-ignore waiver set.
+ * matches and the entry was computed under the same lint-ignore waiver set.
  * A waiver change makes a replayed verdict actively wrong, so the waiver set
  * is compared explicitly rather than trusted to the key.
  */
@@ -61,7 +61,7 @@ export declare function getCachedPerPatchLintIssues(cache: PerPatchLintCacheFile
 export interface SetCachedPerPatchLintIssuesInput {
     /** Cache file to mutate in place. */
     cache: PerPatchLintCacheFile;
-    /** Patch the payload belongs to; also the cache entry key. */
+    /** Patch the payload belongs to, and also the cache entry key. */
     patchFilename: string;
     /** Fingerprint the payload is valid for. */
     key: string;

package/dist/src/core/patch-lint-cache.js

@@ -9,17 +9,17 @@ import { git } from './git-base.js';
 import { collectNewFileCreatorsByPath } from './patch-lint.js';
 // Schema 2: entries additionally carry the lintIgnore-suppressed issues and
 // the measured non-binary line count, so a warm run can report waived size
-// measurements identically to a cold one — a cache hit must never surface
-// LESS than a fresh lint.
+// measurements identically to a cold one. A cache hit must never surface
+// less than a fresh lint.
 // Schema 3: the key additionally content-hashes the
 // `patchLint.checkJsTestShim` file exactly as `checkJsExtraShim`'s already
-// was; without it, editing the test shim in place replays every cached
+// was. Without it, editing the test shim in place replays every cached
 // verdict.
-// Schema 4: each entry RECORDS the lint-ignore waiver set that produced it,
+// Schema 4: each entry records the lint-ignore waiver set that produced it,
 // and a lookup whose effective waiver set differs is refused even when the
 // key matches. The key already hashes `patch.lintIgnore`, so this is
 // belt-and-braces on purpose: a waiver change is the one mutation that makes
-// a replayed verdict actively WRONG (an operator writes a waiver, re-runs,
+// a replayed verdict actively wrong (an operator writes a waiver, re-runs,
 // and is shown the finding they just waived), and the class must not depend
 // on every future key input staying complete. Bumping the schema also
 // discards every pre-4 entry, which is itself the cure for a cache that
@@ -96,7 +96,7 @@ function buildOwnershipFingerprint(files, ctx) {
 export async function buildPerPatchLintCacheKey(input) {
     // Hash in parallel, then insert in sorted order. The sort is load-bearing:
     // `stableHash` below serialises this record, so insertion order is part of
-    // the cache key — assigning as results land would make the key
+    // the cache key, and assigning as results land would make the key
     // nondeterministic.
     const sortedFiles = [...input.existingFiles].sort((a, b) => a.localeCompare(b));
     const hashes = await Promise.all(sortedFiles.map((file) => fileHash(join(input.engineDir, file))));
@@ -110,8 +110,8 @@ export async function buildPerPatchLintCacheKey(input) {
     const shimHashOf = async (shimPath) => shimPath === undefined
         ? null
         : { path: shimPath, hash: await fileHash(resolve(input.projectRoot, shimPath)) };
-    // Both shims feed compiled checkJs programs, so both are content-hashed —
-    // the config block alone only carries their PATHS, and an in-place edit
+    // Both shims feed compiled checkJs programs, so both are content-hashed.
+    // The config block alone only carries their paths, and an in-place edit
     // must invalidate the programs it feeds.
     const [extraShim, testShim] = await Promise.all([
         shimHashOf(input.config.patchLint?.checkJsExtraShim),
@@ -121,9 +121,9 @@ export async function buildPerPatchLintCacheKey(input) {
         cacheSchemaVersion: LINT_CACHE_SCHEMA_VERSION,
         engineHeadSha: input.engineHeadSha ?? null,
         lintImplementationVersion: LINT_IMPLEMENTATION_VERSION,
-        // Deliberately the PLAIN semver, not the +g<sha> build identity:
-        // identity churns every commit at the same version and
-        // would invalidate the cache for no correctness gain.
+        // The plain semver, not the +g<sha> build identity: that identity
+        // churns every commit at the same version and would invalidate the
+        // cache for no correctness gain.
         packageVersion: input.packageVersion ?? getPackageVersion(),
         patchFile: await fileHash(join(input.patchesDir, input.patch.filename)),
         patchMetadata: normalizePatchMetadata(input.patch),
@@ -177,7 +177,7 @@ export async function loadPerPatchLintCache(projectRoot) {
     }
     catch {
         // Any unreadable or malformed cache file is treated as a cold cache. The
-        // cache is a pure optimisation, so discarding it is always safe — the
+        // cache is a pure optimisation, so discarding it is always safe. The
         // alternative is failing lint over a corrupt sidecar.
         return createEmptyPerPatchLintCache();
     }
@@ -199,7 +199,7 @@ function normalizeLintIgnoreSet(lintIgnore) {
 }
 /**
  * Returns the cached lint payload for a patch when the stored key still
- * matches AND the entry was computed under the same lint-ignore waiver set.
+ * matches and the entry was computed under the same lint-ignore waiver set.
  * A waiver change makes a replayed verdict actively wrong, so the waiver set
  * is compared explicitly rather than trusted to the key.
  */

package/dist/src/core/patch-lint-checkjs.d.ts

@@ -3,17 +3,17 @@
  *
  * Loads the TypeScript compiler API via dynamic import so it is only
  * required when `patchLint.checkJs` is enabled in `fireforge.json`.
- * TypeScript remains a dev-dependency — if a user enables checkJs
+ * TypeScript remains a dev-dependency. If a user enables checkJs
  * without installing it, the pass emits a clear error explaining
  * how to fix it.
  *
  * Separated from `patch-lint.ts` to keep both files within the
  * project's per-file line budget. The shim itself and the suppressed
  * diagnostic code list now live in `typecheck-shim.ts` and are shared
- * with the whole-project `fireforge typecheck` command — keeping a
+ * with the whole-project `fireforge typecheck` command, keeping a
  * single source of truth for the Firefox-globals coverage.
  * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`
- * and optional allowlisted `checkJsCompilerOptions`; it does not change
+ * and optional allowlisted `checkJsCompilerOptions`. It does not change
  * shim composition or suppressed diagnostic codes.
  *
  * Resolution scope vs reporting scope: the TS program is built over a
@@ -26,20 +26,20 @@
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
 import type { PatchLintCheckJsCompilerOptions, PatchLintConfig, PatchLintSeverityGate } from '../types/config.js';
-/** How a checkJs run controls reporting and resolution; see module docs. */
+/** How a checkJs run controls reporting and resolution. See module docs. */
 export interface CheckJsMode {
     strict: boolean;
     compilerOptions?: PatchLintCheckJsCompilerOptions;
     /**
      * How to report undefined free identifiers (TS2304/TS2552). Default
-     * 'warning' — see `patchLint.undefinedIdentifiers`.
+     * 'warning'. See `patchLint.undefinedIdentifiers`.
      */
     undefinedIdentifiers?: PatchLintSeverityGate;
 }
 /**
  * Result of {@link runCheckJsGrouped}: diagnostics attributed to the
  * patch-owned file they originate in (`byFile`, keyed by repo-relative
- * path), plus run-level errors that have no owning file (`global` — e.g.
+ * path), plus run-level errors that have no owning file (`global`, e.g.
  * TypeScript missing or an unreadable extra shim).
  */
 export interface GroupedCheckJsResult {
@@ -64,11 +64,11 @@ export interface RunCheckJsGroupedInput {
     projectRoot?: string;
     /** Strictness preset plus allowlisted compiler-option overrides. */
     mode?: CheckJsMode;
-    /** Optional shim text appended AFTER the consumer shim. */
+    /** Optional shim text appended after the consumer shim. */
     builtinShimSuffix?: string;
     /**
-     * When set, only these repo-relative files become program ROOTS;
-     * resolution (and the host allowlist) still spans all of
+     * When set, only these repo-relative files become program roots.
+     * Resolution (and the host allowlist) still spans all of
      * `resolutionOwned`, so a subset root's cross-patch imports type-check
      * against the real owning sources while unrelated owned files are never
      * parsed. `.mjs` files are module-scoped, so a root's diagnostics are
@@ -78,22 +78,22 @@ export interface RunCheckJsGroupedInput {
     rootScope?: ReadonlySet<string>;
 }
 /**
- * Builds the checkJs program **once** over `resolutionOwned` and returns its
+ * Builds the checkJs program once over `resolutionOwned` and returns its
  * diagnostics grouped by originating file. Callers slice the result by their
- * own report scope — per-patch lint attributes each file to its owning patch,
+ * own report scope: per-patch lint attributes each file to its owning patch,
  * export/re-export keeps only the patch under export. Resolution always spans
  * every file in `resolutionOwned`, so cross-patch `resource:///`/`chrome://`
  * imports resolve to real sources.
  *
- * @param input - Program inputs; see {@link RunCheckJsGroupedInput}
+ * @param input - Program inputs. See {@link RunCheckJsGroupedInput}
  * @returns Diagnostics grouped per owning file plus run-level errors
  */
 export declare function runCheckJsGrouped(input: RunCheckJsGroupedInput): Promise<GroupedCheckJsResult>;
 /**
  * Flattens a {@link runCheckJsGrouped} run into a single issue list. When
  * `reportScope` is supplied, only diagnostics from files in that set are
- * returned (resolution still spans every owned file); omitting it reports
- * every owned file's diagnostics — the historical whole-set behaviour.
+ * returned (resolution still spans every owned file). Omitting it reports
+ * every owned file's diagnostics, the historical whole-set behaviour.
  *
  * @param repoDir - Absolute engine (repository) directory
  * @param patchOwnedFiles - Patch-owned `.sys.mjs` paths to resolve against
@@ -120,15 +120,15 @@ export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>
 export declare function invokePatchLintCheckJs(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, reportScope?: ReadonlySet<string>): Promise<PatchLintIssue[]>;
 /**
  * Runs the checkJs pass over patch-owned test `.js` files (
- * `patchLint.checkJsTestFiles`). Each test file gets its OWN small
- * program — mochitest scripts share top-level scope only with their
- * directory's `head*.js` helpers, so one multi-script program would emit
- * false cross-file redeclaration errors — with roots = the test file plus
- * any same-directory patch-owned `head*.js`, checked against the built-in
- * Firefox shim + {@link TEST_HARNESS_SHIM} + the optional consumer
- * `checkJsTestShim`. Only the target file's diagnostics are reported per
- * program (head helpers report from their own program), and run-level
- * errors are de-duplicated across programs.
+ * `patchLint.checkJsTestFiles`). Each test file gets its own small
+ * program, with roots = the test file plus any same-directory patch-owned
+ * `head*.js`, checked against the built-in Firefox shim +
+ * {@link TEST_HARNESS_SHIM} + the optional consumer `checkJsTestShim`.
+ * Mochitest scripts share top-level scope only with their directory's
+ * `head*.js` helpers, so one multi-script program would emit false
+ * cross-file redeclaration errors. Only the target file's diagnostics are
+ * reported per program (head helpers report from their own program), and
+ * run-level errors are de-duplicated across programs.
  *
  * @param repoDir - Absolute engine (repository) directory
  * @param testFiles - Patch-owned test-script paths (repo-relative)
@@ -139,7 +139,7 @@ export declare function runCheckJsTestFilesGrouped(repoDir: string, testFiles: S
 /**
  * Grouped variant of {@link invokePatchLintCheckJs}: builds one queue-wide
  * checkJs program over `patchOwnedFiles` and returns its findings grouped by
- * owning file. The per-patch lint orchestrator calls this **once per run**
+ * owning file. The per-patch lint orchestrator calls this once per run
  * and attributes each file's findings to its owning patch, instead of
  * rebuilding the same program for every patch in the queue.
  *
@@ -148,12 +148,12 @@ export declare function runCheckJsTestFilesGrouped(repoDir: string, testFiles: S
  * @param patchLint - The resolved `patchLint` config block
  * @param projectRoot - FireForge project root for shim resolution
  * @param rootScope - Optional subset of files to use as program roots
- * (`--patches`); resolution still spans the whole queue
+ * (`--patches`). Resolution still spans the whole queue
  */
 export declare function invokePatchLintCheckJsGrouped(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
 /**
  * Cheap probe reproducing the only run-level ("global") checkJs findings the
- * build path can produce — a missing `typescript` package and an unreadable
+ * build path can produce: a missing `typescript` package and an unreadable
  * consumer shim (`checkJsExtraShim`, and `checkJsTestShim` when
  * `checkJsTestFiles` is on). The built program itself never contributes
  * globals (see {@link runCheckJsGrouped}), so a warm all-cache-hit run can

package/dist/src/core/patch-lint-checkjs.js

@@ -4,17 +4,17 @@
  *
  * Loads the TypeScript compiler API via dynamic import so it is only
  * required when `patchLint.checkJs` is enabled in `fireforge.json`.
- * TypeScript remains a dev-dependency — if a user enables checkJs
+ * TypeScript remains a dev-dependency. If a user enables checkJs
  * without installing it, the pass emits a clear error explaining
  * how to fix it.
  *
  * Separated from `patch-lint.ts` to keep both files within the
  * project's per-file line budget. The shim itself and the suppressed
  * diagnostic code list now live in `typecheck-shim.ts` and are shared
- * with the whole-project `fireforge typecheck` command — keeping a
+ * with the whole-project `fireforge typecheck` command, keeping a
  * single source of truth for the Firefox-globals coverage.
  * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`
- * and optional allowlisted `checkJsCompilerOptions`; it does not change
+ * and optional allowlisted `checkJsCompilerOptions`. It does not change
  * shim composition or suppressed diagnostic codes.
  *
  * Resolution scope vs reporting scope: the TS program is built over a
@@ -39,11 +39,12 @@ import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, TEST_HAR
  * Converts a native path into the form TypeScript uses for `fileName`.
  *
  * TypeScript normalizes every path it hands a `CompilerHost` to forward
- * slashes on ALL platforms, while `resolve()` here yields the platform
+ * slashes on all platforms, while `resolve()` here yields the platform
  * separator. On Windows that mismatch made every `ownedAbsolute.has(fileName)`
  * and `relByAbsolute.get(fileName)` lookup miss, so the host served an empty
- * source file for each owned file and the whole pass reported zero findings —
- * silently, because "no diagnostics" is indistinguishable from "clean code".
+ * source file for each owned file and the whole pass reported zero findings.
+ * It did so silently, because "no diagnostics" is indistinguishable from
+ * "clean code".
  * Every path that crosses the TS boundary goes through here.
  */
 function toTsPath(path) {
@@ -55,8 +56,8 @@ function toTsPath(path) {
  * segment uniquely matches an owned file. URL specifiers
  * (chrome://browser/content/Foo.sys.mjs, resource:///modules/Foo.sys.mjs)
  * are matched by basename, with a `.mjs` → `.sys.mjs` fallback for deployed
- * widget URLs. Ambiguous or unknown basenames stay unresolved — loose
- * wildcard typing beats guessing the wrong module — and relative specifiers
+ * widget URLs. Ambiguous or unknown basenames stay unresolved (loose
+ * wildcard typing beats guessing the wrong module), and relative specifiers
  * are left to fail resolution (the relative-import lint rule bans them).
  */
 function createOwnedSpecifierResolver(ts, ownedAbsolute) {
@@ -105,8 +106,8 @@ function extensionForFile(ts, file) {
 }
 /**
  * Builds a resolver for a reviewed `paths` mapping (route 2 of the
- * cross-patch resolution work). Each pattern may contain a single `*`;
- * matching targets are resolved relative to `baseDir` (the engine dir, like
+ * cross-patch resolution work). Each pattern may contain a single `*`.
+ * Matching targets are resolved relative to `baseDir` (the engine dir, like
  * the rest of `patchLint` which is engine-relative). Resolved files are
  * recorded via `onResolved` so the compiler host knows to read them from
  * disk rather than returning empty content. No `baseUrl` is set, so this is
@@ -134,7 +135,7 @@ function createPathsResolver(ts, paths, baseDir, fileExists, onResolved) {
             }
             for (const target of targets) {
                 // A `paths` target carries at most one `*`, and TypeScript substitutes
-                // that one wildcard — spelled as index arithmetic (mirroring the
+                // that one wildcard. It is spelled as index arithmetic (mirroring the
                 // prefix/suffix split on the pattern side above) rather than
                 // `replace('*', …)`, whose first-occurrence-only behaviour reads as an
                 // incomplete rewrite (CodeQL `js/incomplete-sanitization`).
@@ -155,14 +156,14 @@ function createPathsResolver(ts, paths, baseDir, fileExists, onResolved) {
     };
 }
 /**
- * Builds the checkJs program **once** over `resolutionOwned` and returns its
+ * Builds the checkJs program once over `resolutionOwned` and returns its
  * diagnostics grouped by originating file. Callers slice the result by their
- * own report scope — per-patch lint attributes each file to its owning patch,
+ * own report scope: per-patch lint attributes each file to its owning patch,
  * export/re-export keeps only the patch under export. Resolution always spans
  * every file in `resolutionOwned`, so cross-patch `resource:///`/`chrome://`
  * imports resolve to real sources.
  *
- * @param input - Program inputs; see {@link RunCheckJsGroupedInput}
+ * @param input - Program inputs. See {@link RunCheckJsGroupedInput}
  * @returns Diagnostics grouped per owning file plus run-level errors
  */
 export async function runCheckJsGrouped(input) {
@@ -170,7 +171,7 @@ export async function runCheckJsGrouped(input) {
     const empty = { byFile: new Map(), global: [] };
     if (resolutionOwned.size === 0)
         return empty;
-    // Dynamic import — typescript stays as a dev dependency
+    // Dynamic import: typescript stays as a dev dependency
     let ts;
     try {
         ts = await import('typescript');
@@ -191,7 +192,7 @@ export async function runCheckJsGrouped(input) {
     }
     // Resolve absolute paths for root files, filtering to files that exist.
     // Under a rootScope, non-scoped owned files stay resolvable (host
-    // allowlist + relByAbsolute) but are not program roots — they are only
+    // allowlist + relByAbsolute) but are not program roots. They are only
     // parsed if a scoped root's import closure reaches them.
     const rootFiles = [];
     const ownedAbsolute = new Set();
@@ -208,16 +209,16 @@ export async function runCheckJsGrouped(input) {
     if (rootFiles.length === 0)
         return empty;
     // Compose the shim. `extraShimPath` is project-relative (validated
-    // by config-validate); resolve it against `projectRoot`. When the
-    // caller passes neither, fall back to `repoDir` — the only way the
+    // by config-validate). Resolve it against `projectRoot`. When the
+    // caller passes neither, fall back to `repoDir`. The only way the
     // shim path is ever read in that case is when extraShimPath is
     // also undefined, so the resolution target is irrelevant.
     let shimSource;
     try {
         const composed = await composeShimSource(input.projectRoot ?? repoDir, extraShimPath);
         // The suffix (e.g. the loose test-harness baseline) goes
-        // AFTER the consumer's extra shim: TypeScript resolves conflicting
-        // `declare var` redeclarations to the FIRST declaration, so a typed
+        // after the consumer's extra shim: TypeScript resolves conflicting
+        // `declare var` redeclarations to the first declaration, so a typed
         // consumer declaration must precede the loose fallback to win.
         shimSource = input.builtinShimSuffix
             ? `${composed.source}\n${input.builtinShimSuffix}`
@@ -245,12 +246,12 @@ export async function runCheckJsGrouped(input) {
     const strictness = strict
         ? { strict: true, noImplicitAny: true }
         : {
-            // Loose default — implicit `any` is allowed unless `patchLint.checkJsStrict`.
+            // Loose default: implicit `any` is allowed unless `patchLint.checkJsStrict`.
             strict: false,
             noImplicitAny: false,
         };
-    // Allowlisted overrides. Booleans merge directly; a reviewed `paths`
-    // mapping is applied to the compiler options AND wired into the host
+    // Allowlisted overrides. Booleans merge directly. A reviewed `paths`
+    // mapping is applied to the compiler options and wired into the host
     // resolver below so patch-owned modules can be typed from their real
     // sources without a hand-generated ambient stub shim.
     const overrides = {};
@@ -281,10 +282,10 @@ export async function runCheckJsGrouped(input) {
         // Module resolution is host-controlled (see resolveOwnedSpecifier
         // below): imports that match a patch-owned file resolve to the real
         // source so JSDoc type-guard predicates and @template generics
-        // survive the module boundary; everything else deliberately fails
+        // survive the module boundary. Everything else is left to fail
         // resolution, falling back to the chrome:*/resource:* ambient
         // wildcards plus the suppressed "cannot find module" codes. The
-        // host resolver is authoritative — TS never crawls the Firefox
+        // host resolver is authoritative: TS never crawls the Firefox
         // tree looking for upstream modules.
         ...strictness,
         ...overrides,
@@ -294,7 +295,7 @@ export async function runCheckJsGrouped(input) {
     // the shim for the shim path, and returns empty content for
     // anything else to avoid reading the full Firefox tree.
     const defaultHost = ts.createCompilerHost(options);
-    // Files pulled in via a reviewed `paths` mapping — outside the owned set
+    // Files pulled in via a reviewed `paths` mapping: outside the owned set
     // but read from disk so the resolver's targets actually type-check.
     const pathsResolved = new Set();
     const resolveViaPaths = pathsMapping
@@ -348,7 +349,7 @@ export async function runCheckJsGrouped(input) {
  * Groups TS diagnostics by the patch-owned file they originate in,
  * suppressing module-resolution / unknown-name noise inherent to checking
  * Firefox JS outside Mozilla's build system. Diagnostics from `paths`-resolved
- * or shim files are dropped — only owned files (in `relByAbsolute`) carry
+ * or shim files are dropped. Only owned files (in `relByAbsolute`) carry
  * findings.
  */
 function groupOwnedDiagnostics(ts, diagnostics, relByAbsolute, undefinedIdentifiers = 'warning') {
@@ -393,8 +394,8 @@ function groupOwnedDiagnostics(ts, diagnostics, relByAbsolute, undefinedIdentifi
 /**
  * Flattens a {@link runCheckJsGrouped} run into a single issue list. When
  * `reportScope` is supplied, only diagnostics from files in that set are
- * returned (resolution still spans every owned file); omitting it reports
- * every owned file's diagnostics — the historical whole-set behaviour.
+ * returned (resolution still spans every owned file). Omitting it reports
+ * every owned file's diagnostics, the historical whole-set behaviour.
  *
  * @param repoDir - Absolute engine (repository) directory
  * @param patchOwnedFiles - Patch-owned `.sys.mjs` paths to resolve against
@@ -438,15 +439,15 @@ export async function invokePatchLintCheckJs(repoDir, patchOwnedFiles, patchLint
 }
 /**
  * Runs the checkJs pass over patch-owned test `.js` files (
- * `patchLint.checkJsTestFiles`). Each test file gets its OWN small
- * program — mochitest scripts share top-level scope only with their
- * directory's `head*.js` helpers, so one multi-script program would emit
- * false cross-file redeclaration errors — with roots = the test file plus
- * any same-directory patch-owned `head*.js`, checked against the built-in
- * Firefox shim + {@link TEST_HARNESS_SHIM} + the optional consumer
- * `checkJsTestShim`. Only the target file's diagnostics are reported per
- * program (head helpers report from their own program), and run-level
- * errors are de-duplicated across programs.
+ * `patchLint.checkJsTestFiles`). Each test file gets its own small
+ * program, with roots = the test file plus any same-directory patch-owned
+ * `head*.js`, checked against the built-in Firefox shim +
+ * {@link TEST_HARNESS_SHIM} + the optional consumer `checkJsTestShim`.
+ * Mochitest scripts share top-level scope only with their directory's
+ * `head*.js` helpers, so one multi-script program would emit false
+ * cross-file redeclaration errors. Only the target file's diagnostics are
+ * reported per program (head helpers report from their own program), and
+ * run-level errors are de-duplicated across programs.
  *
  * @param repoDir - Absolute engine (repository) directory
  * @param testFiles - Patch-owned test-script paths (repo-relative)
@@ -519,7 +520,7 @@ function modeFromPatchLintConfig(patchLint) {
 /**
  * Grouped variant of {@link invokePatchLintCheckJs}: builds one queue-wide
  * checkJs program over `patchOwnedFiles` and returns its findings grouped by
- * owning file. The per-patch lint orchestrator calls this **once per run**
+ * owning file. The per-patch lint orchestrator calls this once per run
  * and attributes each file's findings to its owning patch, instead of
  * rebuilding the same program for every patch in the queue.
  *
@@ -528,7 +529,7 @@ function modeFromPatchLintConfig(patchLint) {
  * @param patchLint - The resolved `patchLint` config block
  * @param projectRoot - FireForge project root for shim resolution
  * @param rootScope - Optional subset of files to use as program roots
- * (`--patches`); resolution still spans the whole queue
+ * (`--patches`). Resolution still spans the whole queue
  */
 export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, patchLint, projectRoot, rootScope) {
     return runCheckJsGrouped({
@@ -544,7 +545,7 @@ export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, pa
 }
 /**
  * Cheap probe reproducing the only run-level ("global") checkJs findings the
- * build path can produce — a missing `typescript` package and an unreadable
+ * build path can produce: a missing `typescript` package and an unreadable
  * consumer shim (`checkJsExtraShim`, and `checkJsTestShim` when
  * `checkJsTestFiles` is on). The built program itself never contributes
  * globals (see {@link runCheckJsGrouped}), so a warm all-cache-hit run can

package/dist/src/core/patch-lint-chrome-jsdoc.d.ts

@@ -4,30 +4,29 @@
  * `.js` files loaded via `Services.scriptloader.loadSubScript`).
  *
  * Why a separate module from {@link ./patch-lint-jsdoc.ts}: chrome
- * subscripts are NOT ES modules. They are parsed as scripts (no static
+ * subscripts are not ES modules. They are parsed as scripts (no static
  * `export`) and their top-level `class`/`function` declarations are
  * exposed to the loading window as globals rather than declared exports.
  * The export-walker in `patch-lint-jsdoc.ts` would never visit them.
  *
- * The rule shape — "every top-level class needs a JSDoc, every method
- * needs one when `chromeScriptJsDoc` is at `warning`/`error`, every
- * top-level function needs a matching @param/@returns block" — is
- * identical to the `.sys.mjs` rule once you remove the `export` framing,
- * so the per-declaration validators are reused verbatim from the export
- * module.
+ * The rule shape is identical to the `.sys.mjs` rule once you remove the
+ * `export` framing: every top-level class needs a JSDoc, every method
+ * needs one when `chromeScriptJsDoc` is at `warning`/`error`, and every
+ * top-level function needs a matching @param/@returns block. So the
+ * per-declaration validators are reused verbatim from the export module.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
 import type { PatchLintSeverityGate } from '../types/config.js';
 import type { JsDocIssue, ValidateExportJsDocOptions } from './patch-lint-jsdoc.js';
 /**
  * Validates JSDoc on top-level declarations in a chrome-subscript `.js`
- * source file. A parse failure returns an empty issue list — chrome
+ * source file. A parse failure returns an empty issue list. Chrome
  * subscripts that use module-only syntax (rare) silently disable the
  * rule rather than emitting confusing parse-error issues.
  *
  * @param source - File content
  * @param options - Optional gates (e.g. class-method JSDoc severity).
- *   `classMethodMode` defaults to `'off'` — the orchestrator passes the
+ *   `classMethodMode` defaults to `'off'`. The orchestrator passes the
  *   `chromeScriptJsDoc` severity here so a single knob controls both
  *   class-level and method-level enforcement.
  * @returns Array of JSDoc issues found

package/dist/src/core/patch-lint-chrome-jsdoc.js

@@ -5,29 +5,28 @@
  * `.js` files loaded via `Services.scriptloader.loadSubScript`).
  *
  * Why a separate module from {@link ./patch-lint-jsdoc.ts}: chrome
- * subscripts are NOT ES modules. They are parsed as scripts (no static
+ * subscripts are not ES modules. They are parsed as scripts (no static
  * `export`) and their top-level `class`/`function` declarations are
  * exposed to the loading window as globals rather than declared exports.
  * The export-walker in `patch-lint-jsdoc.ts` would never visit them.
  *
- * The rule shape — "every top-level class needs a JSDoc, every method
- * needs one when `chromeScriptJsDoc` is at `warning`/`error`, every
- * top-level function needs a matching @param/@returns block" — is
- * identical to the `.sys.mjs` rule once you remove the `export` framing,
- * so the per-declaration validators are reused verbatim from the export
- * module.
+ * The rule shape is identical to the `.sys.mjs` rule once you remove the
+ * `export` framing: every top-level class needs a JSDoc, every method
+ * needs one when `chromeScriptJsDoc` is at `warning`/`error`, and every
+ * top-level function needs a matching @param/@returns block. So the
+ * per-declaration validators are reused verbatim from the export module.
  */
 import { parseScript } from './ast-utils.js';
 import { validateClassDecl, validateClassMethods, validateFunctionDecl, } from './patch-lint-jsdoc.js';
 /**
  * Validates JSDoc on top-level declarations in a chrome-subscript `.js`
- * source file. A parse failure returns an empty issue list — chrome
+ * source file. A parse failure returns an empty issue list. Chrome
  * subscripts that use module-only syntax (rare) silently disable the
  * rule rather than emitting confusing parse-error issues.
  *
  * @param source - File content
  * @param options - Optional gates (e.g. class-method JSDoc severity).
- *   `classMethodMode` defaults to `'off'` — the orchestrator passes the
+ *   `classMethodMode` defaults to `'off'`. The orchestrator passes the
  *   `chromeScriptJsDoc` severity here so a single knob controls both
  *   class-level and method-level enforcement.
  * @returns Array of JSDoc issues found
@@ -43,7 +42,7 @@ export function validateChromeScriptJsDoc(source, options) {
         // Deliberate carve-out, unlike the `.sys.mjs` walker in
         // `patch-lint-jsdoc.ts` (which reports a parse failure as an issue).
         // `parseScript` rejects `import`/`export`, so a chrome subscript that was
-        // misclassified as a `.js` file — or that mistakenly uses module syntax —
+        // misclassified as a `.js` file (or that mistakenly uses module syntax)
         // would emit a pseudo-issue for every rule here. The orchestrator already
         // runs the export walker on `.sys.mjs` separately, so silently declining
         // to lint an unparseable script is the correct degradation for this file
@@ -63,7 +62,7 @@ export function validateChromeScriptJsDoc(source, options) {
             }
         }
         // Top-level `var Foo = class {...}` / `let Foo = function() {...}`
-        // patterns are intentionally out of scope for V1 — chrome subscripts
+        // patterns are out of scope for V1: chrome subscripts
         // overwhelmingly use bare `class`/`function` declarations and the
         // variable-init form would require unwrapping the initializer. Add
         // it later if a real chrome subscript uses that shape.

package/dist/src/core/patch-lint-creators.d.ts

@@ -6,8 +6,8 @@
  *
  * Memoised per context object: ownership resolution and cache-key
  * fingerprints call this 2-3× per linted patch, and each call otherwise
- * re-runs `detectNewFilesInDiff` over EVERY queue entry's diff. Keyed weakly
- * so a discarded context frees its map; a caller that mutates a context
+ * re-runs `detectNewFilesInDiff` over every queue entry's diff. Keyed weakly
+ * so a discarded context frees its map. A caller that mutates a context
  * entry in place must call {@link invalidateNewFileCreatorsCache}.
  */
 import type { PatchQueueBodyEntry, PatchQueueView } from './patch-lint-queue-types.js';
@@ -20,7 +20,7 @@ export declare function invalidateNewFileCreatorsCache(ctx: CreatorsContext): vo
  * mode` by at least one patch in the queue. Paths created by only one
  * patch are also included so callers can distinguish "no creator" from
  * "exactly one creator" without re-scanning the diffs. The returned map
- * is memoised and shared — treat it as read-only.
+ * is memoised and shared, so treat it as read-only.
  */
 export declare function collectNewFileCreatorsByPath(ctx: CreatorsContext): Map<string, string[]>;
 export {};