@hominis/fireforge 0.46.0 → 0.46.2

package/dist/src/core/token-variant.js

@@ -12,7 +12,7 @@
  */
 import { findBlockCloseIndex, stripBlockCommentsInLines } from './token-dark-mode.js';
 /**
- * ONE attribute selector fragment: `[data-private]` (boolean attribute) or
+ * One attribute selector fragment: `[data-private]` (boolean attribute) or
  * `[data-skin=precision]` / `[data-skin="precision"]` (attribute with
  * value). The name and value halves are restricted to identifier-safe
  * characters so the fragment can be spliced into CSS verbatim without
@@ -26,15 +26,15 @@ import { findBlockCloseIndex, stripBlockCommentsInLines } from './token-dark-mod
 const ATTRIBUTE_FRAGMENT_PATTERN = /^\[[a-zA-Z][a-zA-Z0-9_-]*(?:=(?:"[a-zA-Z0-9_-]+"|'[a-zA-Z0-9_-]+'|[a-zA-Z0-9_-]+))?\]$/;
 /**
  * A pseudo-class tail: `:not(…)`, `:hover`, and friends. The parenthesised
- * argument is captured rather than validated here — it is a fragment run of
+ * argument is captured rather than validated here. It is a fragment run of
  * its own and goes through the same per-group check.
  */
 const QUALIFIER_PATTERN = /^:[a-zA-Z][a-zA-Z0-9-]*(?:\(([^()]*)\))?$/;
 /**
  * Splits a run of consecutive attribute fragments into its groups, or
- * returns `undefined` when the run is not exactly that — a group that does not
- * open with `[`, an unclosed group, an empty run, or a group whose name or
- * value is not identifier-safe.
+ * returns `undefined` when the run is not exactly that: a group that does
+ * not open with `[`, an unclosed group, an empty run, or a group whose name
+ * or value is not identifier-safe.
  *
  * @param run - The `[…][…]` text with no `:root` prefix
  * @returns The individual fragments, or undefined when the run is not valid
@@ -67,12 +67,12 @@ function normalizeAttributeFragment(group) {
  * form to the double-quoted `="value"` shape (Mozilla convention).
  * Boolean-attribute fragments are returned unchanged.
  *
- * Structure is decided by {@link rootAttributeSelector} — the matcher's own
- * parse — rather than by a second regex. That is the point: 0.44.2 widened
+ * Structure is decided by {@link rootAttributeSelector}, the matcher's own
+ * parse, rather than by a second regex. 0.44.2 widened
  * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
  * tail, and the validator did not move with it, so
  * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
- * could FIND but would not let you NAME. Running both halves off one parse
+ * could find but would not let you name. Running both halves off one parse
  * is what stops them drifting apart again. Character-level safety stays a
  * separate, per-group check, because the matcher finds bracket boundaries
  * and validates no characters at all.
@@ -93,7 +93,7 @@ export function validateVariantSelector(raw) {
     if (value === '')
         return reject;
     const parts = rootAttributeSelector(`:root${value} {`);
-    // The parse must have consumed the WHOLE fragment: anything it declined to
+    // The parse must have consumed the whole fragment: anything it declined to
     // read (a stray space, a trailing combinator) is text the matcher would
     // not see either, so accepting it would author a block nothing can find.
     if (parts === undefined || `${parts.attributes}${parts.qualifier}` !== `:root${value}`)
@@ -138,19 +138,19 @@ function canonicalSelector(selector) {
  * (CodeQL `js/polynomial-redos`). This walk is linear and allocation-free
  * per group.
  *
- * It consumes CONSECUTIVE `[…]` groups and stops at the first character that
- * is not `[`. The previous implementation instead sliced to the LAST `]`
+ * It consumes consecutive `[…]` groups and stops at the first character that
+ * is not `[`. The previous implementation instead sliced to the last `]`
  * before the brace, which kept multi-attribute selectors comparing as a
- * whole — that property is preserved here, since consecutive groups are all
- * consumed — but it also swallowed a pseudo-class tail. On
+ * whole (that property is preserved here, since consecutive groups are all
+ * consumed) but it also swallowed a pseudo-class tail. On
  * `:root[data-theme="light"]:not([data-private]) {` the last `]` is the one
  * inside `:not(…)`, so the computed fragment was
  * `:root[data-theme="light"]:not([data-private]` and the canonical
  * comparison could never match. The unqualified
  * `:root[data-theme="dark"] { }` beside it matched fine, and that asymmetry
- * WAS the bug: an override add mirrored itself into the dark block and
- * silently skipped the light one, which is precisely the half-finished
- * themed edit `THEME_ATTRIBUTE_VARIANTS` exists to prevent.
+ * was the bug: an override add mirrored itself into the dark block and
+ * silently skipped the light one, the half-finished themed edit
+ * `THEME_ATTRIBUTE_VARIANTS` exists to prevent.
  */
 function rootAttributeSelector(line) {
     const start = line.indexOf(':root[');
@@ -177,14 +177,14 @@ function rootAttributeSelector(line) {
  * closing-brace line indices, or `undefined` when no such block exists.
  *
  * Scans a comment-stripped mirror of `lines` so braces inside comments do
- * not offset the depth counter; the returned indices line up with the
+ * not offset the depth counter. The returned indices line up with the
  * original array.
  */
 function findVariantBlock(lines, variant) {
     const stripped = stripBlockCommentsInLines(lines);
     // The request goes through the same parse as the candidate lines, so a
     // variant carrying its own `:not(…)` tail is compared tail-to-tail rather
-    // than being folded into the attribute run — where it would match nothing
+    // than being folded into the attribute run, where it would match nothing
     // and every add would splice a fresh duplicate block.
     const requested = rootAttributeSelector(`:root${variant} {`);
     const want = canonicalSelector(requested?.attributes ?? `:root${variant}`);
@@ -193,10 +193,10 @@ function findVariantBlock(lines, variant) {
         const selector = rootAttributeSelector(line);
         if (selector === undefined || canonicalSelector(selector.attributes) !== want)
             continue;
-        // An UNqualified request still matches a qualified block: that is the
+        // An unqualified request still matches a qualified block: that is the
         // 0.44.2 behaviour `variantBlockQualifier` exists to report, since
         // silently skipping the block is the worse failure. A request that names
-        // a qualifier, though, means it — so it must match.
+        // a qualifier, though, means it, so it must match.
         if (wantQualifier !== '' && canonicalSelector(selector.qualifier) !== wantQualifier)
             continue;
         let openLine = /\{/.test(line) ? i : -1;
@@ -240,7 +240,7 @@ function findVariantBlockInsertionPoint(lines) {
 /**
  * True when a top-level `:root<variant>` block exists in `lines`. Used by
  * the override path to write theme-attribute blocks only when the scaffold
- * already declares them — `insertVariantDeclaration` would otherwise create
+ * already declares them. `insertVariantDeclaration` would otherwise create
  * the block, which is only wanted for the explicit `--variant` flow.
  */
 export function variantBlockExists(lines, variant) {
@@ -250,13 +250,13 @@ export function variantBlockExists(lines, variant) {
  * The pseudo-class qualifier on the matched `:root<variant>` block, or
  * `undefined` when no block matched. `''` for an unqualified block.
  *
- * A qualifier such as `:not([data-private])` is semantically LOAD-BEARING:
- * writing into that block scopes the declaration to the qualified case, and
- * that may not be what the operator meant. Matching it is still the right
- * call — silently skipping it is the worse failure, and the one that
- * shipped — but the override path uses this to say out loud which selector
- * it wrote through, so the narrowing is a visible decision rather than a
- * theme bug discovered later.
+ * A qualifier such as `:not([data-private])` is load-bearing: writing into
+ * that block scopes the declaration to the qualified case, and that may not
+ * be what the operator meant. Matching it is still the right call, since
+ * silently skipping it is the worse failure and the one that shipped, but
+ * the override path uses this to say out loud which selector it wrote
+ * through, so the narrowing is a visible decision rather than a theme bug
+ * discovered later.
  *
  * @param lines - Tokens CSS split into lines
  * @param variant - Attribute selector fragment, e.g. `[data-theme="light"]`
@@ -275,8 +275,8 @@ export function variantBlockHasToken(lines, variant, tokenName) {
  * not exist).
  *
  * The located form of {@link variantBlockHasToken}: the variant add path
- * reports a skip the way the base path does — naming the block and the
- * line — instead of returning a bare boolean that leaves a no-op re-run
+ * reports a skip the way the base path does, naming the block and the
+ * line, instead of returning a bare boolean that leaves a no-op re-run
  * indistinguishable from a write.
  *
  * @param lines - Tokens CSS split into lines
@@ -288,11 +288,11 @@ export function findVariantBlockDeclaration(lines, variant, tokenName) {
     const block = findVariantBlock(lines, variant);
     if (!block)
         return undefined;
-    // Comments are stripped across the WHOLE block before scanning, matching
+    // Comments are stripped across the whole block before scanning, matching
     // what the boolean form always did: a `/* … */` spanning several lines
     // must not leave its tail looking like a declaration.
     const blockLines = lines.slice(block.open, block.close + 1);
-    // Blank the comment's CHARACTERS rather than deleting it: removing a
+    // Blank the comment's characters rather than deleting it: removing a
     // multi-line comment outright collapses its lines and shifts every line
     // number after it, which is the one thing this function exists to report.
     const stripped = blockLines

package/dist/src/core/toolchain-preflight.d.ts

@@ -1,27 +1,27 @@
 /**
  * Toolchain-minimum awareness for Firefox source hops.
  *
- * When `fireforge download --force` moves the engine to a new Firefox MAJOR
+ * When `fireforge download --force` moves the engine to a new Firefox major
  * version, the tree's declared toolchain minimums (cbindgen, Rust)
- * frequently move with it — and the first `fireforge build` then dies a few
+ * frequently move with it, and the first `fireforge build` then dies a few
  * seconds into `mach configure` with a message whose remediation text names
  * `./mach bootstrap`, the wrong tool for a FireForge-managed repo (e.g.
  * `ERROR: cbindgen version 0.29.1 is too old. At least version 0.29.4 is
  * required.`).
  *
  * Two layers:
- *  1. {@link formatMajorVersionHopNotice} — a post-download nudge when the
+ *  1. {@link formatMajorVersionHopNotice}, a post-download nudge when the
  *     downloaded major differs from the previously downloaded one.
- *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing the
+ *  2. {@link runToolchainPreflight}, a cheap pre-build probe comparing the
  *     minimums the tree itself declares against the host binaries
  *     `mach configure` will resolve, probing configure's own candidate
  *     order: env override first, then the `~/.mozbuild` state-directory copy
  *     bootstrap installs, then PATH. Probing env-or-PATH alone blocks builds
  *     whose current tool lives in the state dir behind a stale PATH copy.
- *     Deliberately FAIL-SOFT: it reports a mismatch only when a minimum was
- *     positively parsed AND at least one candidate resolved AND every
- *     resolved candidate is definitively lower. Any uncertainty (file moved
- *     upstream, unparseable output, no candidate found) skips silently — the
+ *     Fail-soft: it reports a mismatch only when a minimum was positively
+ *     parsed, at least one candidate resolved, and every resolved candidate
+ *     is definitively lower. Any uncertainty (file moved upstream,
+ *     unparseable output, no candidate found) skips silently. The
  *     mach-error-hints translator still catches the real configure failure
  *     downstream.
  */
@@ -41,16 +41,16 @@ export interface ToolchainMismatch {
     /** Engine-relative file the minimum was parsed from. */
     declaredIn: string;
     /**
-     * Every candidate that resolved — all of them below the minimum
+     * Every candidate that resolved, all of them below the minimum
      * (mach-resolution order: env override, mozbuild state dir, PATH).
      */
     candidates: ToolchainCandidate[];
 }
 /**
  * Returns the one-line notice to print after a download that hopped the
- * Firefox MAJOR version, or undefined when no notice is warranted (first
- * download, same major, or unparseable versions — an unparseable version
- * must not spam every download with a false hint).
+ * Firefox major version, or undefined when no notice is warranted (first
+ * download, same major, or unparseable versions, since an unparseable
+ * version must not spam every download with a false hint).
  *
  * @param previousVersion - `downloadedVersion` recorded in state before this download
  * @param newVersion - Version that was just downloaded
@@ -59,14 +59,14 @@ export declare function formatMajorVersionHopNotice(previousVersion: string | un
 /**
  * Reads the toolchain minimums the engine tree itself declares. Any file
  * that is missing or no longer matches the expected declaration shape
- * yields undefined for that tool — never an error.
+ * yields undefined for that tool, never an error.
  */
 export declare function readDeclaredToolchainMinimums(engineDir: string): Promise<Partial<Record<ToolchainTool, string>>>;
 /**
  * Compares the tree-declared toolchain minimums against the host binaries
  * `mach configure` will resolve, in configure's own candidate order (env
- * override, mozbuild state dir, PATH). A tool fails ONLY when at least
- * one candidate resolved and none of them meets the minimum; any single
+ * override, mozbuild state dir, PATH). A tool fails only when at least
+ * one candidate resolved and none of them meets the minimum. Any single
  * passing candidate passes the tool (configure will find it), and a tool
  * with no resolvable candidate skips silently (see module header for the
  * fail-soft rationale).

package/dist/src/core/toolchain-preflight.js

@@ -2,27 +2,27 @@
 /**
  * Toolchain-minimum awareness for Firefox source hops.
  *
- * When `fireforge download --force` moves the engine to a new Firefox MAJOR
+ * When `fireforge download --force` moves the engine to a new Firefox major
  * version, the tree's declared toolchain minimums (cbindgen, Rust)
- * frequently move with it — and the first `fireforge build` then dies a few
+ * frequently move with it, and the first `fireforge build` then dies a few
  * seconds into `mach configure` with a message whose remediation text names
  * `./mach bootstrap`, the wrong tool for a FireForge-managed repo (e.g.
  * `ERROR: cbindgen version 0.29.1 is too old. At least version 0.29.4 is
  * required.`).
  *
  * Two layers:
- *  1. {@link formatMajorVersionHopNotice} — a post-download nudge when the
+ *  1. {@link formatMajorVersionHopNotice}, a post-download nudge when the
  *     downloaded major differs from the previously downloaded one.
- *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing the
+ *  2. {@link runToolchainPreflight}, a cheap pre-build probe comparing the
  *     minimums the tree itself declares against the host binaries
  *     `mach configure` will resolve, probing configure's own candidate
  *     order: env override first, then the `~/.mozbuild` state-directory copy
  *     bootstrap installs, then PATH. Probing env-or-PATH alone blocks builds
  *     whose current tool lives in the state dir behind a stale PATH copy.
- *     Deliberately FAIL-SOFT: it reports a mismatch only when a minimum was
- *     positively parsed AND at least one candidate resolved AND every
- *     resolved candidate is definitively lower. Any uncertainty (file moved
- *     upstream, unparseable output, no candidate found) skips silently — the
+ *     Fail-soft: it reports a mismatch only when a minimum was positively
+ *     parsed, at least one candidate resolved, and every resolved candidate
+ *     is definitively lower. Any uncertainty (file moved upstream,
+ *     unparseable output, no candidate found) skips silently. The
  *     mach-error-hints translator still catches the real configure failure
  *     downstream.
  */
@@ -62,16 +62,16 @@ const MINIMUM_DECLARATIONS = {
  *
  * `stateDirRelPaths` are the mach-state-directory locations
  * `fireforge bootstrap` (via mozboot) installs the tool to. mach's configure
- * tries the state directory BEFORE the PATH candidates —
- * bindgen.configure's toolchain search path lists `~/.mozbuild/cbindgen/
- * cbindgen` first — so the probe must too. Probing only env-or-PATH fails a
+ * tries the state directory before the PATH candidates (bindgen.configure's
+ * toolchain search path lists `~/.mozbuild/cbindgen/cbindgen` first), so the
+ * probe must too. Probing only env-or-PATH fails a
  * build configure would have accepted whenever an old `~/.cargo/bin/
  * cbindgen` shadows a current bootstrap-installed copy. Rust has no
- * state-dir install — rustup owns it — so its list is empty.
+ * state-dir install, since rustup owns it, so its list is empty.
  */
 const HOST_PROBES = {
     // `mach configure` honours the CBINDGEN env option (bindgen.configure's
-    // `option(env="CBINDGEN", ...)`), so the probe must too — otherwise the
+    // `option(env="CBINDGEN", ...)`), so the probe must too. Otherwise the
     // preflight could veto a build configure would have accepted.
     cbindgen: {
         envVar: 'CBINDGEN',
@@ -82,7 +82,7 @@ const HOST_PROBES = {
 };
 /**
  * Parses a dotted version string into numeric components. Trailing
- * non-numeric suffixes are ignored; returns undefined when the string
+ * non-numeric suffixes are ignored. Returns undefined when the string
  * does not start with a number. (Same posture as the furnace version
  * drift classifier, kept local so the two modules stay decoupled.)
  */
@@ -92,7 +92,7 @@ function parseVersionComponents(version) {
         return undefined;
     return match[1].split('.').map(Number);
 }
-/** Component-wise comparison; missing components count as 0. */
+/** Component-wise comparison. Missing components count as 0. */
 function isVersionLower(candidate, minimum) {
     const length = Math.max(candidate.length, minimum.length);
     for (let i = 0; i < length; i += 1) {
@@ -105,9 +105,9 @@ function isVersionLower(candidate, minimum) {
 }
 /**
  * Returns the one-line notice to print after a download that hopped the
- * Firefox MAJOR version, or undefined when no notice is warranted (first
- * download, same major, or unparseable versions — an unparseable version
- * must not spam every download with a false hint).
+ * Firefox major version, or undefined when no notice is warranted (first
+ * download, same major, or unparseable versions, since an unparseable
+ * version must not spam every download with a false hint).
  *
  * @param previousVersion - `downloadedVersion` recorded in state before this download
  * @param newVersion - Version that was just downloaded
@@ -128,7 +128,7 @@ export function formatMajorVersionHopNotice(previousVersion, newVersion) {
 /**
  * Reads the toolchain minimums the engine tree itself declares. Any file
  * that is missing or no longer matches the expected declaration shape
- * yields undefined for that tool — never an error.
+ * yields undefined for that tool, never an error.
  */
 export async function readDeclaredToolchainMinimums(engineDir) {
     const entries = Object.entries(MINIMUM_DECLARATIONS);
@@ -173,7 +173,7 @@ async function probeBinaryVersion(binary, versionPattern) {
 }
 /**
  * Probes every candidate binary for a tool in mach's resolution order:
- * the env override (which, when set, is the ONLY candidate — configure
+ * the env override (which, when set, is the only candidate, since configure
  * uses it even when a better binary exists elsewhere), then the mozbuild
  * state-directory copy bootstrap installs, then PATH. Candidates that
  * fail to run or to parse are dropped silently.
@@ -196,8 +196,8 @@ async function probeHostToolCandidates(tool) {
 /**
  * Compares the tree-declared toolchain minimums against the host binaries
  * `mach configure` will resolve, in configure's own candidate order (env
- * override, mozbuild state dir, PATH). A tool fails ONLY when at least
- * one candidate resolved and none of them meets the minimum; any single
+ * override, mozbuild state dir, PATH). A tool fails only when at least
+ * one candidate resolved and none of them meets the minimum. Any single
  * passing candidate passes the tool (configure will find it), and a tool
  * with no resolvable candidate skips silently (see module header for the
  * fail-soft rationale).

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

@@ -1,4 +1,4 @@
-/** Runs a clone command; throws on non-zero exit. */
+/** Runs a clone command. Throws on non-zero exit. */
 export type CloneExecutor = (command: string, args: string[]) => Promise<void>;
 /** How this host can materialise a tree. */
 export type CowCapability = 'clonefile' | 'reflink' | 'none';
@@ -9,8 +9,8 @@ export type CowCapability = 'clonefile' | 'reflink' | 'none';
 export declare function detectCowSupport(dir: string, platform?: NodeJS.Platform, executor?: CloneExecutor): Promise<CowCapability>;
 /**
  * Copies one directory entry (file or directory, recursively) from
- * `sourcePath` to `destinationPath` using the given capability —
+ * `sourcePath` to `destinationPath` using the given capability:
  * clonefile/reflink when available, a plain physical copy under
- * 'none' (the `--force-copy` path; the CALLER gates on the flag).
+ * 'none' (the `--force-copy` path, and the caller gates on the flag).
  */
 export declare function cloneEntry(capability: CowCapability, sourcePath: string, destinationPath: string, platform?: NodeJS.Platform, executor?: CloneExecutor): Promise<void>;

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

@@ -2,10 +2,10 @@
 /**
  * Copy-on-write cloning for `fireforge tree`.
  *
- * Capability is probed BY DOING — a tiny `cp -c` (APFS clonefile) or
- * `cp --reflink=always` (btrfs/XFS) in the actual destination directory —
- * so the verdict is truthful for the volume the trees will live on. A
- * filesystem without CoW support REFUSES honestly; `--force-copy` opts
+ * Capability is probed by doing it: a tiny `cp -c` (APFS clonefile) or
+ * `cp --reflink=always` (btrfs/XFS) runs in the actual destination
+ * directory, so the verdict is truthful for the volume the trees will live
+ * on. A filesystem without CoW support refuses honestly. `--force-copy` opts
  * into a full physical copy but is never implied (a Firefox tree can be
  * tens of gigabytes).
  *
@@ -57,9 +57,9 @@ export async function detectCowSupport(dir, platform = process.platform, executo
 }
 /**
  * Copies one directory entry (file or directory, recursively) from
- * `sourcePath` to `destinationPath` using the given capability —
+ * `sourcePath` to `destinationPath` using the given capability:
  * clonefile/reflink when available, a plain physical copy under
- * 'none' (the `--force-copy` path; the CALLER gates on the flag).
+ * 'none' (the `--force-copy` path, and the caller gates on the flag).
  */
 export async function cloneEntry(capability, sourcePath, destinationPath, platform = process.platform, executor = defaultExecutor) {
     const args = capability === 'none'

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

@@ -1,14 +1,14 @@
 import { type TreeMarker } 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 declare const TREE_COMMAND_VERDICTS: Readonly<Record<string, 'allowed' | 'refused' | 'conditional'>>;
 interface ConditionalInput {
     /** Subcommand chain below the top-level command (e.g. ['staged-dependency']). */
     subcommands: readonly string[];
-    /** Merged options of the ACTION command (leaf). */
+    /** Merged options of the action command (leaf). */
     options: Readonly<Record<string, unknown>>;
     /** Positional args of the action command. */
     args: readonly unknown[];

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?: {