@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/commands/furnace/rename.js

@@ -77,7 +77,7 @@ async function renameTestFiles(engineDir, projectRoot, oldName, newName, journal
  * deployment. Best-effort: logs a warning but never blocks the rename.
  *
  * Without it, a rename registers and deploys the new name correctly but
- * leaves `engine/toolkit/content/widgets/<old>/` in place — subsequent
+ * leaves `engine/toolkit/content/widgets/<old>/` in place: subsequent
  * `furnace sync` runs cannot clear the stale widget, and packaging pulls in
  * both copies. The snapshot is taken before the remove so the rollback
  * journal restores the old directory if any later step in
@@ -103,7 +103,7 @@ async function removeStaleDeployedComponentDir(engineDir, oldTargetPath, journal
  * accompanying `chrome.toml` entry names the same file. Leaving both
  * unhandled produces a `test_<old>.html` that still imports
  * `chrome://global/content/elements/<old>.mjs` and references
- * `customElements.whenDefined("<old>")` — running against a component that
+ * `customElements.whenDefined("<old>")`, running against a component that
  * no longer exists under that name, and either failing or (if the old
  * component is still deployed) passing for the wrong reason.
  *
@@ -139,7 +139,7 @@ async function renameMochikitTestFiles(engineDir, oldName, newName, journal) {
         }
     }
     // Update `chrome.toml` entry if present. The file may live in the
-    // same widgets/tests directory as the test file itself; upstream
+    // same widgets/tests directory as the test file itself. Upstream
     // convention places exactly one `chrome.toml` there for all widget
     // scaffolds.
     const chromeTomlPath = join(testDir, 'chrome.toml');
@@ -195,9 +195,9 @@ async function performRenameMutations(args) {
             }
             await snapshotDir(journal, oldDir);
             await snapshotFile(journal, args.furnaceConfigPath);
-            // Journal the state file BEFORE step 4 re-keys its checksums, plus
+            // Journal the state file before step 4 re-keys its checksums, plus
             // the new dir and every new-name destination below (a snapshot of a
-            // missing path records {existed: false} → rollback DELETES it).
+            // missing path records {existed: false}, so rollback deletes it).
             // Without these, a failed or SIGINT'd rename stranded the new-name
             // scaffold and kept re-keyed state for a nonexistent component.
             await snapshotFile(journal, getFurnacePaths(projectRoot).furnaceState);
@@ -209,7 +209,7 @@ async function performRenameMutations(args) {
                 if (!entry.isFile())
                     continue;
                 const oldFileName = entry.name;
-                // Rename only when the filename starts with the component name — the
+                // Rename only when the filename starts with the component name. The
                 // scaffolding convention for both create and override is
                 // `${name}.ext`. A plain `replace(oldName, newName)` produces wrong
                 // results when the old name occurs more than once (`foo-foo.mjs`
@@ -276,7 +276,7 @@ async function performRenameMutations(args) {
                 await renameTestFiles(args.engineDir, projectRoot, oldName, newName, journal);
                 // The mochikit scaffold and widgets/chrome.toml live in a different
                 // tree than browser.toml-registered browser-chrome tests, so
-                // renameTestFiles does not reach them — leaving
+                // renameTestFiles does not reach them, leaving
                 // `engine/toolkit/content/tests/widgets/test_<old>.html` and its
                 // `chrome.toml` entry pointing at the old name, which either fails
                 // the test run outright or passes for the wrong component.
@@ -401,8 +401,8 @@ export async function furnaceRenameCommand(projectRoot, oldName, newName) {
         throw new FurnaceError(`A component named "${newName}" already exists in furnace.json.`, newName);
     }
     // The furnace-state key is singular (`custom` / `override`, derived
-    // inside performRenameMutations); the on-disk directory label differs —
-    // custom components live under `components/custom/` (singular) while
+    // inside performRenameMutations). The on-disk directory label differs.
+    // Custom components live under `components/custom/` (singular) while
     // overrides live under `components/overrides/` (plural). Appending an
     // `s` to the state key produces the wrong label `components/customs/`
     // for custom components and is correct for overrides only by

package/dist/src/commands/furnace/scan.js

@@ -59,7 +59,7 @@ async function promptAddComponents(components, tracked, projectRoot) {
 /**
  * Persists discovered component tag names into the `stock` section of
  * furnace.json. Shared by the interactive confirm flow and the
- * non-interactive `--track` flag — without it, scan prints a full inventory
+ * non-interactive `--track` flag. Without it, scan prints a full inventory
  * but persists nothing and says nothing about where the inventory goes.
  *
  * Wraps the furnace.json mutation in the standard furnace lifecycle so the
@@ -81,7 +81,7 @@ async function persistStockComponents(projectRoot, names) {
             // re-filter catches the edge case where the config on disk changed
             // between the scan's read and the write (concurrent scan / manual
             // edit). Without it a duplicate scan would introduce duplicate
-            // entries into stock; writeFurnaceConfig's validator would then
+            // entries into stock. writeFurnaceConfig's validator would then
             // reject the write, but the error would be less actionable than
             // silently de-duplicating here.
             const toAdd = names.filter((s) => !config.stock.includes(s));
@@ -163,7 +163,7 @@ export async function furnaceScanCommand(projectRoot, options = {}) {
     note(`Total: ${components.length}  Tracked: ${trackedCount}  Untracked: ${untrackedCount}`, 'Summary');
     // --track: persist the discovered untracked inventory into the `stock`
     // section without prompting (works non-interactively). Without it, scan
-    // stays report-only; the interactive confirm flow below is the other
+    // stays report-only. The interactive confirm flow below is the other
     // persistence path.
     if (options.track) {
         if (untrackedCount === 0) {

package/dist/src/commands/furnace/status.js

@@ -67,7 +67,7 @@ async function showDetailedComponentStatus(options) {
         outro('Status complete');
         return;
     }
-    // Custom component — run registration consistency check
+    // Custom component: run registration consistency check
     const status = await checkRegistrationConsistency(projectRoot, name, customConfig, ftlDir);
     const lines = [];
     const check = (ok, label) => {
@@ -122,7 +122,7 @@ export async function furnaceStatusCommand(projectRoot, name) {
     // Surface a pendingRepair marker before the normal summary so it cannot
     // be missed. The marker means the last mutation could not roll back
     // cleanly, so the engine and workspace may have drifted in ways apply
-    // cannot detect from checksums alone — doctor is the right next step.
+    // cannot detect from checksums alone, so doctor is the right next step.
     if (state.pendingRepair) {
         warn(`Furnace is in pending-repair state from ${state.pendingRepair.operation} (${state.pendingRepair.timestamp}): ${state.pendingRepair.reason}. Run \`fireforge doctor --repair-furnace\` to reconcile.`);
     }
@@ -154,7 +154,7 @@ export async function furnaceStatusCommand(projectRoot, name) {
     // Surface override baseVersion drift from the project config. This check
     // is cheap (no I/O besides the already-loaded fireforge.json) and catches
     // the single most common silent-drift case: Firefox bumped, overrides
-    // still point at the old version. Advisory only — status never fails.
+    // still point at the old version. Advisory only. Status never fails.
     const forgeConfig = await loadConfig(projectRoot);
     for (const entry of findOverrideBaseVersionDrift(config, forgeConfig.firefox.version)) {
         warn(formatOverrideBaseVersionDriftWarning(entry));
@@ -166,17 +166,17 @@ export async function furnaceStatusCommand(projectRoot, name) {
     if (await pathExists(paths.engine)) {
         // Held in an object rather than two `let`s: the scanner below mutates
         // them from inside a closure, and TS's control-flow analysis does not
-        // propagate that through the call — it would narrow both to the literal
+        // propagate that through the call. It would narrow both to the literal
         // `false` and flag every later read as always-falsy.
         const drift = { workspaceChanged: false, engineDrifted: false };
         /**
          * Scans one component family for workspace or engine drift.
          *
-         * The engine probe sits behind `else if` deliberately: a component whose
+         * The engine probe sits behind `else if` on purpose: a component whose
          * workspace already changed does not need an engine comparison to decide
          * what `status` reports, and the probe is the expensive half (it
-         * re-hashes deployed files). The consequence is that engine drift can go
-         * UNREPORTED for a component that also has workspace changes — the
+         * re-hashes deployed files). The consequence is that engine drift goes
+         * unreported for a component that also has workspace changes. The
          * summary says "workspace changed", not both.
          */
         const scanFamily = async (entries, baseDir, kind, probeEngineDrift) => {

package/dist/src/commands/furnace/sync.js

@@ -91,12 +91,12 @@ export async function furnaceSyncCommand(projectRoot, options = {}) {
     else {
         info('All overrides are up-to-date with the current Firefox version.');
     }
-    // Phase 2.5: post-refresh gates. Refresh deliberately leaves conflict
-    // markers in workspace files and does NOT bump baseVersion on conflict —
-    // so without this gate sync warns about conflicts and then copies the
-    // marker-laden files straight into the engine via Phase 3, producing a
-    // broken build from the one command whose whole purpose is a safe upgrade.
-    // Apply and deploy both enforce a drift gate; sync must not be the back
+    // Phase 2.5: post-refresh gates. Refresh leaves conflict markers in
+    // workspace files and does not bump baseVersion on conflict, so without
+    // this gate sync warns about conflicts and then copies the marker-laden
+    // files straight into the engine via Phase 3, producing a broken build
+    // from the one command meant to make an upgrade safe.
+    // Apply and deploy both enforce a drift gate. Sync must not be the back
     // door around it.
     if (!options.dryRun) {
         const refreshedConfig = await loadFurnaceConfig(projectRoot);

package/dist/src/commands/furnace/test-file-name.d.ts

@@ -9,9 +9,9 @@
  * and silently leave the old test behind:
  *
  * 1. drop the upstream `moz-` custom-element prefix, which never appears in a
- *    test filename;
+ *    test filename.
  * 2. drop a leading `<binaryName>-`, because the test directory is already
- *    named after the binary and the prefix would be doubled;
+ *    named after the binary and the prefix would be doubled.
  * 3. underscore the remaining dashes, matching mozilla-central's
  *    `browser_*.js` convention.
  * @param componentName - Custom-element name, e.g. `moz-mybrowser-sidebar`.

package/dist/src/commands/furnace/test-file-name.js

@@ -10,9 +10,9 @@
  * and silently leave the old test behind:
  *
  * 1. drop the upstream `moz-` custom-element prefix, which never appears in a
- *    test filename;
+ *    test filename.
  * 2. drop a leading `<binaryName>-`, because the test directory is already
- *    named after the binary and the prefix would be doubled;
+ *    named after the binary and the prefix would be doubled.
  * 3. underscore the remaining dashes, matching mozilla-central's
  *    `browser_*.js` convention.
  * @param componentName - Custom-element name, e.g. `moz-mybrowser-sidebar`.

package/dist/src/commands/furnace/validate.js

@@ -78,16 +78,15 @@ async function autoFixIssues(projectRoot, issues) {
             warn(`Could not fix jar.mn for ${componentName}: ${toError(err).message}`);
         }
     }
-    // `wrong-registration-pattern` is deliberately NOT auto-fixed: it means the
-    // component IS registered but in the wrong block, and moving code between
-    // blocks is too risky to do unattended. Only truly missing registrations are
-    // repaired, below.
+    // `wrong-registration-pattern` is not auto-fixed: the component is
+    // registered but in the wrong block, and moving code between blocks is too
+    // risky to do unattended. Only missing registrations are repaired, below.
     // Repair components missing from customElements.js entirely (reported by
     // validate as `missing-custom-element-registration`).
     //
     // Scoped to the components named in `issues`: iterating every entry in
     // `config.custom` makes `furnace validate <one-component> --fix` write
-    // customElements.js registrations for EVERY custom component, outside the
+    // customElements.js registrations for every custom component, outside the
     // issue list it was handed and invisibly, since `fixed` is never
     // incremented here.
     const componentsWithIssues = new Set(issues.map((issue) => issue.component));
@@ -109,7 +108,7 @@ async function autoFixIssues(projectRoot, issues) {
             await addCustomElementRegistration(engineDir, componentName, modulePath);
         }
         catch {
-            // Best-effort repair — the re-validation pass at the call site reports
+            // Best-effort repair. The re-validation pass at the call site reports
             // whatever is still outstanding.
         }
     }
@@ -194,11 +193,11 @@ export async function furnaceValidateCommand(projectRoot, name, options = {}) {
         }
     }
     // Auto-fix fixable issues when --fix is passed. The counter returned by
-    // `autoFixIssues` only counts function calls that did not throw — a write
-    // that succeeded but did not actually resolve the issue (addJarMnEntries
-    // appending to a file mach later ignores) would still bump it. Re-validate
-    // the affected components and compute the *actual* drop in fixable issues
-    // so the reported number is honest.
+    // `autoFixIssues` only counts function calls that did not throw, so a
+    // write that succeeded but did not actually resolve the issue
+    // (addJarMnEntries appending to a file mach later ignores) would still
+    // bump it. Re-validate the affected components and compute the real drop
+    // in fixable issues so the reported number is honest.
     if (options.fix && allIssues.length > 0) {
         const fixableIssues = allIssues.filter((issue) => FIXABLE_CHECKS.has(issue.check));
         if (fixableIssues.length > 0) {
@@ -254,7 +253,7 @@ async function reValidateComponents(projectRoot, config, furnacePaths, component
             componentDir = join(furnacePaths.customDir, componentName);
         }
         else {
-            // Stock or removed components are not local-validated; skip silently.
+            // Stock or removed components are not local-validated, so skip silently.
             continue;
         }
         if (!(await pathExists(componentDir)))

package/dist/src/commands/import.js

@@ -20,9 +20,9 @@ import { pickDefined } from '../utils/options.js';
 /**
  * Errno codes for filesystem-level failures against the working file.
  * These are safe to fall through as "unmanaged" because they describe the
- * *state of the engine directory*, not the integrity of the patch stack.
- * Manifest / patch-parse / PatchError failures do NOT match this set and
- * are re-thrown so the root cause surfaces instead of being silently
+ * state of the engine directory rather than the integrity of the patch
+ * stack. Manifest / patch-parse / PatchError failures do not match this set
+ * and are re-thrown so the root cause surfaces instead of being silently
  * reclassified as a spurious dirty file.
  */
 const SAFE_IO_FALLBACK_CODES = new Set(['ENOENT', 'EACCES', 'EPERM', 'EISDIR', 'EBUSY']);
@@ -48,7 +48,7 @@ async function getUnmanagedDirtyFiles(engineDir, patchesDir, dirtyFiles) {
         }
         catch (error) {
             // PatchError, manifest corruption, and patch-parse failures are
-            // *structural* problems with the patch stack — masking them as
+            // structural problems with the patch stack. Masking them as an
             // "unmanaged dirty file" would let the user `--force` past a real
             // root cause (e.g. "patch 003 missing from manifest") and compound
             // the corruption. Only swallow the pure-IO fallback cases where
@@ -91,7 +91,7 @@ async function checkUncommittedPatchFiles(engineDir, patchesDir, forceImport) {
                 // already carries the patch's effects. The import below still
                 // re-applies each patch (a no-op for files whose contents already
                 // match), so phrase the line as "no resync needed" rather than
-                // "patches already applied" — the latter contradicts the "Applied N
+                // "patches already applied". The latter contradicts the "Applied N
                 // patch(es)" summary `applyPatchesWithContinue` prints next.
                 info('Patch-touched files already match the stored patch stack — no engine resync needed before re-applying.');
             }
@@ -160,7 +160,7 @@ async function checkEngineDrift(engineDir, baseCommit, forceImport, acceptPrompt
     const currentHead = await getHead(engineDir);
     if (currentHead === baseCommit)
         return true;
-    // `--yes` and `--force` both answer this prompt; only `--force` also
+    // `--yes` and `--force` both answer this prompt. Only `--force` also
     // waives the patch-integrity gate further down.
     const promptAnswered = forceImport || acceptPrompts;
     if (!stdioIsInteractive()) {
@@ -193,7 +193,7 @@ async function checkEngineDrift(engineDir, baseCommit, forceImport, acceptPrompt
  * without the `.patch` suffix (matching `applyPatchesWithContinue`'s
  * `untilFilename` resolver).
  *
- * Returns an empty set when no match is found — the caller treats that as
+ * Returns an empty set when no match is found. The caller treats that as
  * "no scope filter applies" so the import behaves identically to an
  * unrecognised `--until` target (which `applyPatchesWithContinue` will
  * later surface as a normal error).
@@ -202,11 +202,11 @@ function buildUntilFilenameSet(patches, until) {
     const set = new Set();
     if (until === undefined)
         return set;
-    // Resolve the identifier with the SAME matcher the apply loop uses
-    // (`matchesUntilFilename` accepts filenames, extension-less names, AND
+    // Resolve the identifier with the same matcher the apply loop uses
+    // (`matchesUntilFilename` accepts filenames, extension-less names, and
     // bare ordinals). A filename-only match makes `import --until 5` produce
-    // an EMPTY scope set — the UI previews "0 patches", the integrity gates
-    // filter every in-range issue away — and the apply loop then applies
+    // an empty scope set: the UI previews "0 patches", the integrity gates
+    // filter every in-range issue away, and the apply loop then applies
     // patches 1..5 anyway.
     const target = patches.find((p) => matchesUntilFilename(p.filename, until));
     if (!target)
@@ -228,8 +228,8 @@ async function assertScopedManifestConsistency(patchesDir, untilFilenameSet, unt
     const manifestConsistencyIssues = await validatePatchesManifestConsistency(patchesDir);
     const scopedManifestIssues = until !== undefined
         ? manifestConsistencyIssues.filter((issue) => 
-        // Global (manifest-level) issues have no specific filename to scope
-        // against — a missing or unparseable patches.json blocks any
+        // Global (manifest-level) issues have no specific filename to
+        // scope against: a missing or unparseable patches.json blocks any
         // import. Per-patch issues only block when the patch is in scope.
         issue.code === 'manifest-missing' ||
             issue.code === 'manifest-invalid' ||
@@ -249,7 +249,7 @@ async function assertScopedManifestConsistency(patchesDir, untilFilenameSet, unt
 /**
  * Prints advisory version-compatibility warnings for every in-scope patch
  * whose recorded source version differs meaningfully from the configured
- * Firefox version. Advisory only — never blocks the import.
+ * Firefox version. Advisory only. Never blocks the import.
  */
 async function warnVersionCompatibility(projectRoot, manifest, untilFilenameSet, until) {
     if (!manifest)
@@ -269,7 +269,7 @@ async function warnVersionCompatibility(projectRoot, manifest, untilFilenameSet,
 }
 /**
  * Patch-integrity gate: surfaces orphaned-modification issues scoped to
- * the `--until` range and decides whether the import may proceed —
+ * the `--until` range and decides whether the import may proceed.
  * `--force` continues with a warning, non-TTY refuses loudly, and an
  * interactive operator is prompted. Returns false when the import should
  * stop (the cancel outro has been printed).
@@ -413,8 +413,8 @@ export async function importCommand(projectRoot, options = {}) {
             success(`  ${result.patch.filename}${suffix}`);
         }
         // The re-applied queue may have moved components.conf away from what
-        // the last full build compiled in — surface that now instead of at the
-        // next test refusal.
+        // the last full build compiled in, so surface that now instead of at
+        // the next test refusal.
         await warnIfStaticComponentsStale(projectRoot, paths.engine);
         outro('All patches applied successfully!');
     }
@@ -432,10 +432,10 @@ export function registerImport(program, { getProjectRoot, withErrorHandling }) {
         .description('Apply patches from the patches directory')
         .option('--continue', 'Continue applying patches even if one fails')
         .option('-f, --force', 'Proceed despite engine drift and overwrite unmanaged changes in patch-touched files')
-        // NOT an alias of --force. `--force` waives two orthogonal things: the
-        // drift prompt AND the patch-integrity gate. `--yes` waives only the
+        // Not an alias of --force. `--force` waives two orthogonal things: the
+        // drift prompt and the patch-integrity gate. `--yes` waives only the
         // prompt, so a scripted import can run unattended while the integrity
-        // refusal stays armed — which is the guard you actually want in CI.
+        // refusal stays armed, which is the guard you want in CI.
         .option('-y, --yes', 'Answer the drift prompt non-interactively. Unlike --force, this does NOT waive the patch-integrity gate.')
         .option('--until <patch>', 'Apply patches only up to and including this patch')
         .option('--dry-run', 'Preview which patches would be applied without modifying the engine')

package/dist/src/commands/lint-per-patch.js

@@ -28,7 +28,7 @@ function emitTierNotice(filename, files, tier) {
 /**
  * Lints one queued patch against its own isolated diff, reusing the cache entry
  * when the cache key matches. Returns the outcome and the patch's (unprefixed)
- * issues without touching shared state — the orchestrator applies the tier
+ * issues without touching shared state. The orchestrator applies the tier
  * notice, issue prefixing, and cache write in patch order after the pool
  * drains, so the bounded concurrency cannot reorder output. Returns `skipped`
  * (no files present / empty diff), `cached`, or `linted`.
@@ -135,8 +135,8 @@ const SUPPRESSED_SIZE_CHECKS = new Set([
  * Applies the per-patch results in patch order so the bounded concurrency
  * cannot reorder output: emits each tier notice, the once-only run-level
  * checkJs errors (before the first freshly linted patch's issues), the
- * filename-prefixed issue rows, and the cache writes — all in the same sequence
- * a serial run produced. Returns the run tallies.
+ * filename-prefixed issue rows, and the cache writes, all in the same
+ * sequence a serial run produced. Returns the run tallies.
  */
 async function applyPerPatchResults(subset, results, issues, checkJs, cache) {
     const totals = {
@@ -158,8 +158,8 @@ async function applyPerPatchResults(subset, results, issues, checkJs, cache) {
         }
         emitTierNotice(patch.filename, result.existingFiles, patch.tier);
         // Run-level checkJs errors are emitted once, before the first
-        // non-skipped patch's own issues — matching the serial emit point.
-        // Deliberately NOT gated on `result.usedCheckJs`: global findings are
+        // non-skipped patch's own issues, matching the serial emit point.
+        // Not gated on `result.usedCheckJs`: global findings are
         // run-level and never cached, so gating drops them entirely on an
         // all-cache-hit run and lets a warm run report fewer errors than a cold
         // one. PerRunCheckJs builds its program lazily, so the cost only
@@ -183,7 +183,7 @@ async function applyPerPatchResults(subset, results, issues, checkJs, cache) {
         for (const issue of result.rawIssues) {
             issues.push({ ...issue, file: `${patch.filename} :: ${issue.file}` });
         }
-        // A waived size finding still reports its MEASUREMENT: the finding stays
+        // A waived size finding still reports its measurement: the finding stays
         // suppressed (no exit-code / --max-warnings effect) but the current count
         // is readable from the tool that enforces it, so a waiver's cited size
         // can be calibrated without hand-measuring.
@@ -331,7 +331,7 @@ function selectPatchSubset(manifest, requested) {
  * queue-level findings are scoped to files those patches touch).
  */
 export async function lintPerPatch(projectRoot, paths, options = {}) {
-    // Read-only to the operator, an index WRITER to git: the per-patch diffs
+    // Read-only to the operator, but an index writer to git: the per-patch diffs
     // run `git diff HEAD` (and, for untracked binaries, a real stage/unstage
     // pair) against the primary checkout. A private index absorbs all of it
     // so a concurrent `fireforge test` still gets an evidential verdict.
@@ -379,7 +379,7 @@ async function lintPerPatchInner(projectRoot, paths, options = {}) {
         });
     }
     // With `--patches`, the checkJs program roots at only the subset's owned
-    // files — the full queue stays resolvable, so a cold subset run costs the
+    // files. The full queue stays resolvable, so a cold subset run costs the
     // subset's import closure instead of the whole queue.
     const checkJs = buildPerRunCheckJs(projectRoot, paths, config, ctx, isSubset ? subsetNames : undefined);
     // Lint patches concurrently, then apply every side effect in patch order so

package/dist/src/commands/lint-per-run-checkjs.d.ts

@@ -3,22 +3,21 @@
  * `re-export`.
  *
  * The dominant fixed cost of patch lint is one `ts.createProgram` over the
- * queue's patch-owned `.sys.mjs` files — tens of seconds on a large queue.
- * This controller builds that program at most ONCE per command invocation
+ * queue's patch-owned `.sys.mjs` files, tens of seconds on a large queue.
+ * This controller builds that program at most once per command invocation
  * (lazily, promise-memoised) and lets callers slice per-patch findings out of
  * the grouped result. Three levers keep the cost paid only when it buys
  * something:
  *
- * - **Lazy build**: nothing is built until the first cache miss asks.
- * - **Root scoping** (`rootScopePatches`): with `--patches <subset>` the
- *   program's roots are only the subset's owned files; the full queue stays
+ * - Lazy build: nothing is built until the first cache miss asks.
+ * - Root scoping (`rootScopePatches`): with `--patches <subset>` the
+ *   program's roots are only the subset's owned files. The full queue stays
  *   resolvable, so cross-patch imports type-check identically while
  *   unrelated files are never parsed.
- * - **Warm-run probe**: run-level ("global") checkJs findings come only from
- *   a missing `typescript` package or an unreadable shim — never from the
- *   built program — so an all-cache-hit run satisfies "warm never reports
- *   less than cold" via `probeCheckJsGlobalIssues` instead of building
- *   anything.
+ * - Warm-run probe: run-level ("global") checkJs findings come only from a
+ *   missing `typescript` package or an unreadable shim, never from the built
+ *   program, so an all-cache-hit run satisfies "warm never reports less than
+ *   cold" via `probeCheckJsGlobalIssues` instead of building anything.
  */
 import { type GroupedCheckJsResult } from '../core/patch-lint-checkjs.js';
 import type { PatchQueueContext } from '../core/patch-lint-cross.js';
@@ -32,7 +31,7 @@ import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
 export interface PerRunCheckJs {
     /** Patch filename → the checkJs-relevant files that patch creates. */
     ownedByPatch: Map<string, Set<string>>;
-    /** Every checkJs-relevant file in the queue (sys + test scripts) — the
+    /** Every checkJs-relevant file in the queue (sys + test scripts), the
      *  resolution universe the program can see. Callers use it to detect
      *  files the hoisted program has never heard of (fresh `--scan`
      *  adoptions) and fall back to a per-patch build. */
@@ -43,10 +42,10 @@ export interface PerRunCheckJs {
     getGrouped: () => Promise<GroupedCheckJsResult>;
     /** Run-level checkJs errors (e.g. TypeScript missing). When the program
      *  was never built (all-warm run) this probes the two global failure
-     * sources directly instead of building it holds because the
+     *  sources directly instead of building it, which is safe because the
      *  built program never contributes globals of its own. */
     getGlobal: () => Promise<PatchLintIssue[]>;
-    /** The byFile slices for `files` (globals deliberately EXCLUDED — they
+    /** The byFile slices for `files` (globals are excluded because they
      *  are run-level, never cached, and emitted once per invocation via
      *  `getGlobal`). Feed to `LintExportedPatchOptions.precomputedCheckJs`. */
     sliceFor: (files: ReadonlySet<string>) => Promise<PatchLintIssue[]>;

package/dist/src/commands/lint-per-run-checkjs.js

@@ -4,22 +4,21 @@
  * `re-export`.
  *
  * The dominant fixed cost of patch lint is one `ts.createProgram` over the
- * queue's patch-owned `.sys.mjs` files — tens of seconds on a large queue.
- * This controller builds that program at most ONCE per command invocation
+ * queue's patch-owned `.sys.mjs` files, tens of seconds on a large queue.
+ * This controller builds that program at most once per command invocation
  * (lazily, promise-memoised) and lets callers slice per-patch findings out of
  * the grouped result. Three levers keep the cost paid only when it buys
  * something:
  *
- * - **Lazy build**: nothing is built until the first cache miss asks.
- * - **Root scoping** (`rootScopePatches`): with `--patches <subset>` the
- *   program's roots are only the subset's owned files; the full queue stays
+ * - Lazy build: nothing is built until the first cache miss asks.
+ * - Root scoping (`rootScopePatches`): with `--patches <subset>` the
+ *   program's roots are only the subset's owned files. The full queue stays
  *   resolvable, so cross-patch imports type-check identically while
  *   unrelated files are never parsed.
- * - **Warm-run probe**: run-level ("global") checkJs findings come only from
- *   a missing `typescript` package or an unreadable shim — never from the
- *   built program — so an all-cache-hit run satisfies "warm never reports
- *   less than cold" via `probeCheckJsGlobalIssues` instead of building
- *   anything.
+ * - Warm-run probe: run-level ("global") checkJs findings come only from a
+ *   missing `typescript` package or an unreadable shim, never from the built
+ *   program, so an all-cache-hit run satisfies "warm never reports less than
+ *   cold" via `probeCheckJsGlobalIssues` instead of building anything.
  */
 import { invokePatchLintCheckJsGrouped, probeCheckJsGlobalIssues, runCheckJsTestFilesGrouped, } from '../core/patch-lint-checkjs.js';
 import { isTestScriptFile, resolvePatchOwnedSysMjs, resolvePatchOwnedTestScripts, } from '../core/patch-lint-ownership.js';
@@ -52,7 +51,7 @@ export function buildPerRunCheckJs(projectRoot, paths, config, ctx, rootScopePat
         for (const f of files)
             resolutionSet.add(f);
     }
-    // The subset's owned files, split by program kind; undefined = full queue.
+    // The subset's owned files, split by program kind. Undefined = full queue.
     let scopedRoots;
     if (rootScopePatches !== undefined) {
         scopedRoots = new Set();
@@ -63,9 +62,9 @@ export function buildPerRunCheckJs(projectRoot, paths, config, ctx, rootScopePat
                 scopedRoots.add(f);
         }
     }
-    // One build for the whole run: the queue-wide `.sys.mjs` program plus —
-    // when `patchLint.checkJsTestFiles` is on — one small
-    // script-scope program per patch-owned test file, merged by file.
+    // One build for the whole run: the queue-wide `.sys.mjs` program, plus
+    // (when `patchLint.checkJsTestFiles` is on) one small script-scope
+    // program per patch-owned test file, merged by file.
     const buildAll = async () => {
         const sys = await invokePatchLintCheckJsGrouped(paths.engine, resolvePatchOwnedSysMjs(new Set(), ctx), patchLint, projectRoot, scopedRoots);
         if (!testFilesEnabled)
@@ -77,7 +76,7 @@ export function buildPerRunCheckJs(projectRoot, paths, config, ctx, rootScopePat
         }
         return { byFile, global: [...sys.global, ...tests.global] };
     };
-    // Memoise the *promise*, not the resolved value: under the bounded pool
+    // Memoise the promise rather than the resolved value: under the bounded pool
     // several patches can reach `getGrouped` before the first build resolves, and
     // `??=` on the promise (a synchronous expression) guarantees a single build.
     let groupedPromise;

package/dist/src/commands/lint-report.d.ts

@@ -1,7 +1,7 @@
 import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
 /**
  * Structural view of one per-patch lint outcome. Mirrors the relevant
- * fields of lint-per-patch's QueuedPatchResult without importing it —
+ * fields of lint-per-patch's QueuedPatchResult without importing it:
  * that module imports this one, and a type back-edge would trip the
  * dpdm cycle gate.
  */
@@ -14,8 +14,8 @@ export interface PerPatchReportResult {
 }
 /**
  * Writes the per-patch lint report JSON. Called after the per-patch
- * results are assembled in patch order; queue-level and policy findings
+ * results are assembled in patch order. Queue-level and policy findings
  * are patch-attributed by their `file`/`filename` fields upstream and
- * are NOT duplicated here — the report is the per-patch view.
+ * are not duplicated here. The report is the per-patch view.
  */
 export declare function writePerPatchLintReport(reportPath: string, subset: readonly PatchMetadata[], results: readonly PerPatchReportResult[]): Promise<void>;

package/dist/src/commands/lint-report.js

@@ -2,11 +2,11 @@
 /**
  * Machine-readable per-patch lint report (`lint --per-patch --report
  * <path>`). One mechanism serves two observability gaps: consumers get each
- * patch's size metrics against the SAME thresholds the size rules fire on,
+ * patch's size metrics against the same thresholds the size rules fire on,
  * instead of mirroring `countNonBinaryDiffLines`, and lintIgnore-suppressed
  * issues stay visible with their measurements rather than vanishing.
  *
- * Helper module consumed by lint-per-patch.ts; no registrar is exported and
+ * Helper module consumed by lint-per-patch.ts. No registrar is exported and
  * none is wanted.
  */
 import { getPatchSizeThresholds, resolvePatchSizeTier, } from '../core/patch-lint.js';
@@ -15,9 +15,9 @@ import { info } from '../utils/logger.js';
 const LINT_REPORT_SCHEMA_VERSION = 1;
 /**
  * Writes the per-patch lint report JSON. Called after the per-patch
- * results are assembled in patch order; queue-level and policy findings
+ * results are assembled in patch order. Queue-level and policy findings
  * are patch-attributed by their `file`/`filename` fields upstream and
- * are NOT duplicated here — the report is the per-patch view.
+ * are not duplicated here. The report is the per-patch view.
  */
 export async function writePerPatchLintReport(reportPath, subset, results) {
     const patches = [];

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

@@ -27,9 +27,9 @@ export interface AggregateLintIgnoreResult {
  * attribute via `issue.file`, which is the offending site and is owned by
  * some patch.
  *
- * Multiple owners: an issue is dropped if **any** owning patch waived the
- * rule. Conservative — never adds new findings, only drops already-waived
- * ones.
+ * Multiple owners: an issue is dropped if any owning patch waived the
+ * rule. This is conservative: it never adds new findings, only drops
+ * already-waived ones.
  *
  * @param issues - Issues collected from the aggregate lint run.
  * @param ctx - Patch queue context used to attribute file → patch.