@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -4,10 +4,10 @@
  *
  * A tree is a snapshot: its `patches/` and `components/` are copies with
  * no merge-back model, so any command that mutates project or engine
- * state must run in the primary tree. Enforcement is DEFAULT-DENY via an
- * explicit verdict table over every top-level command — a newly added
+ * state must run in the primary tree. Enforcement is default-deny via an
+ * explicit verdict table over every top-level command, so a newly added
  * command is refused inside trees until its author classifies it (the
- * drift test in `tree-guard.test.ts` fails otherwise) — and lives in ONE
+ * drift test in `tree-guard.test.ts` fails otherwise). It lives in one
  * commander `preAction` hook installed by `createProgram()`, so the
  * guard fires no matter how the cwd ended up inside a tree (`tree exec`
  * or a plain `cd`).
@@ -17,8 +17,8 @@ import { dirname, join, resolve } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { getTreeMarkerPath, readTreeMarker, } from './tree-store.js';
 /**
- * Per-command verdicts. `allowed` runs unconditionally; `refused` never
- * runs in a tree; `conditional` consults `TREE_CONDITIONAL_CHECKS` with
+ * Per-command verdicts. `allowed` runs unconditionally. `refused` never
+ * runs in a tree. `conditional` consults `TREE_CONDITIONAL_CHECKS` with
  * the invoked subcommand chain, parsed options, and the tree marker.
  */
 export const TREE_COMMAND_VERDICTS = {
@@ -41,7 +41,7 @@ export const TREE_COMMAND_VERDICTS = {
     package: 'refused',
     watch: 'refused',
     // Build-less runs only, and only in trees whose marker records a cloned
-    // (mozinfo-rewritten) objdir — see the conditional check below.
+    // (mozinfo-rewritten) objdir. See the conditional check below.
     test: 'conditional',
     config: 'conditional',
     doctor: 'conditional',
@@ -52,8 +52,8 @@ export const TREE_COMMAND_VERDICTS = {
     typecheck: 'allowed',
     verify: 'allowed',
     furnace: 'refused',
-    // No nesting; `tree list` inside a tree is pointless but harmless — the
-    // subcommand check below allows only `list`.
+    // No nesting. `tree list` inside a tree is pointless but harmless, and
+    // the subcommand check below allows only `list`.
     tree: 'conditional',
 };
 /** The command set named in refusal messages. */
@@ -61,29 +61,29 @@ const ALLOWED_SUMMARY = 'Verification trees support: status, lint, typecheck, ve
     'config (read), export --dry-run, export-all --dry-run, re-export --dry-run, and — ' +
     'in trees created with --with-objdir — build-less test.';
 const TREE_CONDITIONAL_CHECKS = {
-    // Exports write patches/ + patches.json; only the dry-run preview is a read.
+    // Exports write patches/ + patches.json. Only the dry-run preview is a read.
     export: ({ options }) => options['dryRun'] === true,
     'export-all': ({ options }) => options['dryRun'] === true,
     // Same rule for refreshing existing patches: the dry-run projection is a
     // read (proven side-effect free and runtime-enforced by
-    // withDryRunPurityGuard); a real re-export writes patches/.
+    // withDryRunPurityGuard). A real re-export writes patches/.
     're-export': ({ options }) => options['dryRun'] === true,
-    // `config` with no positional value prints; with a value it writes.
+    // `config` with no positional value prints. With a value it writes.
     config: ({ args }) => args.filter((a) => typeof a === 'string').length <= 1,
     // Doctor reads unless a repair flag is set.
     doctor: ({ options }) => options['repairFurnace'] !== true && options['fix'] !== true,
     // Build-less test needs the objdir the marker records as cloned,
-    // mozinfo-rewritten AND reconfigured in-tree; `test --build` rebuilds
+    // mozinfo-rewritten and reconfigured in-tree. `test --build` rebuilds
     // the engine and stays primary-only (a tree is a snapshot with no
     // merge-back model, so build outputs mutated in-tree go nowhere).
     test: ({ options }, marker) => marker.clonedObjdir !== undefined && options['build'] !== true,
-    // No tree lifecycle inside a tree; `tree list` is the only read.
+    // No tree lifecycle inside a tree. `tree list` is the only read.
     tree: ({ subcommands }) => subcommands[0] === 'list',
 };
 /**
- * Command-specific refusal hints appended after the generic sentence —
- * for verdicts where "mutates project or engine state" alone would
- * misdiagnose the actual reason.
+ * Command-specific refusal hints appended after the generic sentence, for
+ * verdicts where "mutates project or engine state" alone would misdiagnose
+ * the actual reason.
  */
 const TREE_REFUSAL_HINTS = {
     test: ({ options }, marker) => {
@@ -149,13 +149,13 @@ export async function runTreeGuardHook(rootCommandName, actionCommand) {
     const state = located.state;
     if (state.kind === 'absent')
         return;
-    // A marker we cannot read is not evidence that this is not a tree — it is
+    // A marker we cannot read is not evidence that this is not a tree. It is
     // evidence that we cannot tell. Treating it as "not a tree" would grant the
     // full mutating command set to a snapshot on the strength of a file that
-    // failed to parse, which is exactly backwards for a default-deny guard.
-    // A marker from a NEWER FireForge is not damaged, so the corrupt branch's
-    // remedies — recreate the tree, delete the stray marker — are actively
-    // wrong for it. Refuse with the upgrade instruction instead, and do NOT
+    // failed to parse, which is backwards for a default-deny guard.
+    // A marker from a newer FireForge is not damaged, so the corrupt branch's
+    // remedies (recreate the tree, delete the stray marker) are actively
+    // wrong for it. Refuse with the upgrade instruction instead, and do not
     // offer --ignore-corrupt-tree-marker: proceeding would mean acting on a
     // marker whose fields this build does not understand.
     if (state.kind === 'unsupported') {
@@ -166,8 +166,8 @@ export async function runTreeGuardHook(rootCommandName, actionCommand) {
     if (state.kind === 'corrupt') {
         if (options['ignoreCorruptTreeMarker'] === true)
             return;
-        // Unconditionally-allowed commands never consult marker fields — their
-        // verdict is the same in every tree — so an unreadable marker cannot
+        // Unconditionally-allowed commands never consult marker fields, and
+        // their verdict is the same in every tree, so an unreadable marker cannot
         // change their answer. Letting them through keeps read-only diagnostics
         // (status, lint) usable on the very tree the operator needs to inspect.
         // 'conditional' verdicts stay refused: their predicates can write.

package/dist/src/core/tree-store.d.ts

@@ -1,5 +1,5 @@
 import { type CowCapability } from './tree-cow.js';
-/** `.fireforge/tree.json` — identifies a directory as a verification tree. */
+/** `.fireforge/tree.json`, which identifies a directory as a verification tree. */
 export interface TreeMarker {
     schemaVersion: 1;
     name: string;
@@ -11,10 +11,10 @@ export interface TreeMarker {
     patchesFingerprint: string | null;
     /**
      * Name of the obj-* directory cloned into this tree, written only after
-     * its mozinfo.json was successfully rewritten to the tree's paths AND the
+     * its mozinfo.json was successfully rewritten to the tree's paths and the
      * caller's in-tree reconfigure regenerated the remaining configure output.
      * Its presence is what lets the guard admit build-less `test` in-tree
-     * (`tree-guard.ts`); absent on trees created without `--with-objdir`.
+     * (`tree-guard.ts`). Absent on trees created without `--with-objdir`.
      */
     clonedObjdir?: string;
 }
@@ -35,7 +35,7 @@ export declare function withTreeLifecycleLock<T>(primaryRoot: string, operation:
  * The three states must stay distinct because they carry opposite safety
  * meanings. `absent` means "this directory is not a tree", which is what
  * lets every mutating command run. `corrupt` means "this directory claims to
- * be a tree but we cannot read the claim" — collapsing it into `absent` (as
+ * be a tree but we cannot read the claim". Collapsing it into `absent` (as
  * a bare `undefined` return does) hands a snapshot the full mutating command
  * set on the strength of a file we failed to parse, inverting
  * `tree-guard.ts`'s default-deny design. Deleting one field from a marker is
@@ -51,7 +51,7 @@ export type TreeMarkerRead = {
     reason: string;
 }
 /**
- * Written by a NEWER FireForge. Distinct from `corrupt` because the remedy
+ * Written by a newer FireForge. Distinct from `corrupt` because the remedy
  * is the opposite: upgrade, do not delete.
  */
  | {
@@ -68,20 +68,20 @@ export declare function getTreeMarkerPath(root: string): string;
  *
  * 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 declare function readTreeMarker(root: string): Promise<TreeMarkerRead>;
 /**
  * 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
@@ -93,8 +93,8 @@ export declare function tryReadTreeMarker(root: string): Promise<TreeMarker | un
  * 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 declare function assertObjdirMatchesTreeMarker(projectRoot: string, objDir: string | undefined): Promise<void>;
 /** Current primary-side snapshot identity, including dirty source and patch bodies. */
@@ -109,8 +109,8 @@ export declare function assertValidTreeName(name: string): void;
  * 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
@@ -134,8 +134,8 @@ export declare function cloneTree(args: {
 export declare function listTrees(primaryRoot: string): Promise<TreeListEntry[]>;
 /**
  * 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 declare function removeTree(primaryRoot: string, name: string, options?: {

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
@@ -19,6 +19,7 @@ import { GeneralError } from '../errors/base.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
 import { getNodeErrorCode, isProcessAlive, toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { sha256Hex } from '../utils/hash.js';
 import { verbose, warn } from '../utils/logger.js';
 import { isObject } from '../utils/validation.js';
 import { getBuildBaselinePath } from './build-baseline.js';
@@ -91,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.
@@ -128,13 +129,13 @@ export async function readTreeMarker(root) {
         const code = getNodeErrorCode(error);
         if (code === 'ENOENT' || code === 'ENOTDIR')
             return { kind: 'absent' };
-        verbose(`Unreadable tree marker at ${markerPath}: ${String(error)}`);
+        verbose(`Unreadable tree marker at ${markerPath}: ${toError(error).message}`);
         return { kind: 'corrupt', reason: `the marker could not be read (${toError(error).message})` };
     }
 }
 /**
  * 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
@@ -149,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);
@@ -178,9 +179,7 @@ export async function computePrimaryFingerprint(primaryRoot) {
     }
     let engineFingerprint;
     try {
-        engineFingerprint = createHash('sha256')
-            .update(await getAllDiff(engineDir))
-            .digest('hex');
+        engineFingerprint = sha256Hex(await getAllDiff(engineDir));
     }
     catch {
         engineFingerprint = null;
@@ -215,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/";
@@ -260,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
@@ -273,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');
@@ -294,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 });
@@ -303,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);
@@ -315,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)) {
@@ -340,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
@@ -348,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.
  */
@@ -392,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.
  *
@@ -403,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
@@ -420,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 {
@@ -437,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) {
@@ -461,7 +462,7 @@ export async function removeTree(primaryRoot, name, options = {}) {
     ]) {
         const state = await inspectTreeLock(lockPath);
         if (state.kind === 'held') {
-            throw new GeneralError(`Refusing to remove tree "${name}": a live process (pid ${String(state.pid)}) holds ${lockPath}. ` +
+            throw new GeneralError(`Refusing to remove tree "${name}": a live process (pid ${state.pid}) holds ${lockPath}. ` +
                 'Wait for it to finish, then retry.');
         }
         if (state.kind === 'unknown' && options.force !== true) {

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.
  *