@hominis/fireforge 0.46.0 → 0.46.2

package/dist/src/core/git-diff.js

@@ -16,7 +16,7 @@ import { getUntrackedFiles, getUntrackedFilesInDir } from './git-status.js';
  * `--binary` is load-bearing: without it git degrades a binary file's section
  * to the informational `Binary files a/x and b/x differ`, which carries none
  * of the bytes and cannot be replayed by `git apply`. It only expands the
- * BINARY section's index line to full hashes (text sections keep their
+ * binary section's index line to full hashes (text sections keep their
  * abbreviated form), so text output stays byte-identical.
  * @param repoDir - Repository directory
  * @param filePath - Path to the file (relative to repo)
@@ -42,7 +42,7 @@ function abbreviateBlobHash(fullHash) {
 /**
  * Pure formatter for a new (untracked) file's unified diff. Shared by the
  * batched cold-run path in {@link getDiffForFilesAgainstHead} and the
- * standalone {@link generateNewFileDiff} — the only thing that differs is
+ * standalone {@link generateNewFileDiff}. The only thing that differs is
  * where `blobHash` comes from (a single batched `git hash-object` vs a
  * per-file one), never the formatting. Preserves the empty-file form, the
  * trailing-newline handling, and the "No newline at end of file" marker
@@ -151,9 +151,9 @@ export async function generateFullFilePatch(repoDir, filePath) {
 /**
  * Gets the diff for all modified files, including untracked (new) files.
  *
- * Tracked binary files round-trip through `git diff --binary`; untracked ones
+ * Tracked binary files round-trip through `git diff --binary`. Untracked ones
  * go through {@link generateBinaryFilePatch} below. Both arms must stay
- * binary-aware — see {@link getFileDiff} for why.
+ * binary-aware. See {@link getFileDiff} for why.
  * @param repoDir - Repository directory
  * @returns Diff content
  */
@@ -164,8 +164,8 @@ export async function getAllDiff(repoDir) {
     const untrackedFiles = await getUntrackedFiles(repoDir);
     // Classify first. `readNewFileContent` reads the file directly and spawns
     // nothing, so the only per-file process in this loop would be the
-    // `git hash-object` inside `generateNewFileDiff` — one spawn per untracked
-    // TEXT file, uncapped, against a Firefox tree where "untracked" can mean a
+    // `git hash-object` inside `generateNewFileDiff`: one spawn per untracked
+    // text file, uncapped, against a Firefox tree where "untracked" can mean a
     // very large number. Hence classify → one batched hash → render. The
     // classification carries each text file's content so it is read once.
     //
@@ -183,7 +183,7 @@ export async function getAllDiff(repoDir) {
     const textHashes = await hashObjectBatch(repoDir, untrackedFiles
         .filter((file) => classified.get(file)?.binary === false)
         .map((file) => join(repoDir, file)));
-    // Binary patches stage into the index and must stay serial; text patches
+    // Binary patches stage into the index and must stay serial. Text patches
     // are pure formatting over the already-batched hashes.
     const binaryDiffs = new Map();
     for (const file of untrackedFiles) {
@@ -203,7 +203,7 @@ export async function getAllDiff(repoDir) {
         const fullPath = join(repoDir, file);
         untrackedDiffs.push(buildNewFileDiffBody(file, entry.content, abbreviateBlobHash(textHashes.get(fullPath))));
     }
-    // Combine all diffs — each already ends with \n, so concatenate directly
+    // Combine all diffs. Each already ends with \n, so concatenate directly
     // to avoid inserting blank lines between diff sections.
     const allDiffs = [trackedDiff, ...untrackedDiffs].filter((d) => d.trim().length > 0);
     const combined = allDiffs.join('');
@@ -215,8 +215,8 @@ export async function getAllDiff(repoDir) {
  * to (but not including) the next such line. Boundary detection is anchored to
  * column 0 because every diff *body* line is prefixed by a space, `+`, `-`,
  * `\`, or `@`, so a context or added line that merely contains the text
- * `diff --git` can never be mistaken for a header. Paths are deliberately NOT
- * parsed out of the header here — see {@link buildTrackedSections}.
+ * `diff --git` can never be mistaken for a header. Paths are not parsed out
+ * of the header here on purpose. See {@link buildTrackedSections}.
  * @param combined - Combined `git diff` stdout
  * @returns File sections in git's emission order
  */
@@ -243,18 +243,18 @@ function splitDiffSections(combined) {
  *
  * `--binary` is load-bearing: a tracked binary file would otherwise degrade to
  * the un-appliable `Binary files a/x and b/x differ` stub. It expands only the
- * binary section's index line to full hashes, so text sections are unaffected
- * — see {@link getFileDiff}.
+ * binary section's index line to full hashes, so text sections are
+ * unaffected. See {@link getFileDiff}.
  *
  * `--no-renames` is load-bearing: a multi-path diff under a user's
  * `diff.renames=true`/`=copies` could otherwise emit a single 2-path rename
  * section (`a/<old> b/<new>`) that a single-path `git diff HEAD -- <file>` can
- * never produce; `--no-renames` re-splits it into the same delete + add bytes
+ * never produce. `--no-renames` re-splits it into the same delete + add bytes
  * the per-file loop emitted.
  *
- * Sections are attributed to paths by POSITION against a companion
+ * Sections are attributed to paths by position against a companion
  * `git diff --no-renames HEAD -z --name-only` (raw, unquoted, NUL-delimited
- * paths, emitted in the same order as the sections) — never by parsing the
+ * paths, emitted in the same order as the sections), never by parsing the
  * `diff --git` header, which is ambiguous or unparseable under `core.quotePath`
  * (non-ASCII paths are C-quoted), paths containing spaces, or
  * `diff.noprefix`/`diff.mnemonicPrefix`. If the section and name counts ever
@@ -273,14 +273,14 @@ async function buildTrackedSections(repoDir, trackedFiles) {
         const sections = splitDiffSections(combined);
         if (sections.length === names.length) {
             for (let i = 0; i < names.length; i++) {
-                // Exact-path keys (raw git bytes, same encoding as the inputs) — never
+                // Exact-path keys (raw git bytes, same encoding as the inputs), never
                 // a substring/startsWith match, so `foo.txt` cannot capture
                 // `foo.txt.bak`'s section.
                 sectionsByPath.set(names[i], sections[i]);
             }
             continue;
         }
-        // Counts disagree — recover the exact pre-batch per-file bytes for this
+        // Counts disagree, so recover the exact pre-batch per-file bytes for this
         // chunk rather than risk dropping or mis-keying a section.
         for (const file of chunk) {
             const diff = await getFileDiff(repoDir, file);
@@ -293,7 +293,7 @@ async function buildTrackedSections(repoDir, trackedFiles) {
 /**
  * Builds a combined diff against HEAD for the provided files without touching
  * the real git index. Tracked files use `git diff --binary HEAD` (binary
- * sections included); untracked files use synthesized new-file diffs, or
+ * sections included). Untracked files use synthesized new-file diffs, or
  * {@link generateBinaryFilePatch} when the file is binary.
  *
  * Performance: the work is batched into a handful of `git` invocations (one
@@ -314,7 +314,7 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
     // that feeds the aggregate working-tree state into this function must not
     // trigger an EISDIR when the diff pass reads `dir/` as if it were a file.
     // The caller-side expansion in `lint.ts` and `export-all.ts` covers the
-    // common path; guarding here makes a single bad call site harmless.
+    // common path. Guarding here makes a single bad call site harmless.
     const expandedFiles = [];
     for (const file of files) {
         if (file.endsWith('/')) {
@@ -336,7 +336,7 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
     const trackedSections = await buildTrackedSections(repoDir, uniqueFiles.filter((file) => tracked.has(file)));
     // Classify the non-tracked files. Directory and binary entries keep their
     // per-file handling (rare, and binary patches mutate the index so they must
-    // stay serial); plain new text files are collected for a single batched
+    // stay serial). Plain new text files are collected for a single batched
     // `git hash-object`. Results land in `sectionByFile`, keyed by path, to be
     // emitted in sorted order below.
     const sectionByFile = new Map();
@@ -353,7 +353,7 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
         // the trailing slash `expandUntrackedDirectoryEntries` would have
         // produced (caller stripped it, submodule entry, tracked-file-replaced-
         // by-dir). Expand it via the same helper used by the slash branch and
-        // recurse so each contained file is diffed individually; fail loud when
+        // recurse so each contained file is diffed individually. Fail loud when
         // the directory has no readable content rather than silently skipping it.
         const fileStat = await stat(fullPath);
         if (fileStat.isDirectory()) {
@@ -366,8 +366,8 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
                 sectionByFile.set(file, innerDiff);
             continue;
         }
-        // Binary — by git's NUL heuristic or because the bytes are not valid
-        // UTF-8 — takes the byte-faithful binary-patch arm.
+        // Binary (by git's NUL heuristic or because the bytes are not valid
+        // UTF-8) takes the byte-faithful binary-patch arm.
         const newFile = await readNewFileContent(repoDir, file);
         if (newFile.binary) {
             const diff = await generateBinaryFilePatch(repoDir, file);
@@ -390,7 +390,7 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
         if (body.trim())
             sectionByFile.set(file, body);
     }
-    // Reassemble in the sorted `uniqueFiles` order — NOT git's section order,
+    // Reassemble in the sorted `uniqueFiles` order, not git's section order,
     // which uses git's own collation and diverges from JS `.sort()` for
     // non-ASCII paths. Driving emission off `uniqueFiles` (as the previous
     // per-file loop did) keeps the combined output byte-identical. Do not change
@@ -422,7 +422,7 @@ export async function getStagedDiffForFiles(repoDir, files) {
 /**
  * Serializes the index-mutating untracked-binary path. The bounded per-patch
  * lint pool can call {@link getDiffForFilesAgainstHead} (and thus this) for
- * several patches at once; two concurrent `git add --intent-to-add` / `git
+ * several patches at once. Two concurrent `git add --intent-to-add` / `git
  * reset` sequences would collide on `.git/index.lock` (a hard failure) or
  * interleave one file's stage with another's unstage. This process-level
  * promise chain runs the staging sequences one at a time. Read-only callers
@@ -460,16 +460,16 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
  * @returns The binary diff string, or empty string if no diff
  */
 async function generateBinaryFilePatchWithConfig(repoDir, filePath, gitConfigArgs) {
-    // Try tracked file diff first (read-only — no index lock needed)
+    // Try tracked file diff first (read-only, so no index lock needed)
     const tracked = await git([...gitConfigArgs, 'diff', '--binary', 'HEAD', '--', filePath], repoDir);
     if (tracked.trim())
         return tracked;
     // The diff for an untracked file has to come from an index entry, so one
-    // has to be written. Writing it to a PRIVATE index is what keeps that
+    // has to be written. Writing it to a private index is what keeps that
     // write invisible: the primary `.git/index` never moves, so a concurrent
     // `fireforge test` fingerprinting `engine/` with `git status` cannot
     // observe the transient `--intent-to-add` entry and void its own verdict
-    // on our bookkeeping. That was a real failure mode — parallel gate lanes
+    // on our bookkeeping. That was a real failure mode: parallel gate lanes
     // killed three runs with `FAIL reason=inconclusive` on branding PNGs
     // flapping between `A` and `??`.
     //
@@ -498,8 +498,8 @@ async function generateBinaryFilePatchWithConfig(repoDir, filePath, gitConfigArg
     verbose(`Binary patch for ${filePath} is staging on the shared index (no private index).`);
     return runWithBinaryStagingLock(async () => {
         // Snapshot the path's exact index entry before touching it. A blanket
-        // `git reset HEAD -- <file>` cleanup restores the path to its HEAD state
-        // — for a path absent from HEAD that means *removing* whatever entry the
+        // `git reset HEAD -- <file>` cleanup restores the path to its HEAD state.
+        // For a path absent from HEAD that means *removing* whatever entry the
         // index carried, silently discarding any staged state that arrived
         // between the read-only diff above and this staging block (a concurrent
         // writer, or a staged-add whose worktree file was deleted). Restoring
@@ -517,11 +517,12 @@ async function generateBinaryFilePatchWithConfig(repoDir, filePath, gitConfigArg
 /**
  * Restores a path's index entry to a previously captured `ls-files --stage`
  * snapshot after a temporary `--intent-to-add` staging. No prior entry means
- * the temporary entry is dropped via `reset HEAD` (the path's HEAD state IS
- * "absent" — this branch only runs for files untracked in HEAD). A prior
+ * the temporary entry is dropped via `reset HEAD` (the path's HEAD state is
+ * "absent", and this branch only runs for files untracked in HEAD). A prior
  * stage-0 entry is re-pointed at its recorded mode and blob. Unmerged entries
- * (stages 1–3) cannot be rebuilt through `--cacheinfo`; that degenerate state
- * keeps the legacy reset-to-HEAD behavior rather than corrupting the conflict.
+ * (stages 1 to 3) cannot be rebuilt through `--cacheinfo`. That degenerate
+ * state keeps the legacy reset-to-HEAD behavior rather than corrupting the
+ * conflict.
  * @param repoDir - Repository directory
  * @param filePath - File path (relative to repo root)
  * @param priorEntry - Raw `git ls-files --stage -- <file>` output from before staging

package/dist/src/core/git-file-ops.d.ts

@@ -33,10 +33,10 @@ export declare function fileExistsInHead(repoDir: string, filePath: string): Pro
 /**
  * Batched equivalent of {@link fileExistsInHead}: returns the subset of
  * `files` that are tracked in HEAD, using a single `git ls-tree` per ARG_MAX
- * chunk instead of one spawn per file. This is the cold-run hot path — a
- * Firefox-sized checkout has hundreds of affected files.
+ * chunk instead of one spawn per file. This is the cold-run hot path, and
+ * a Firefox-sized checkout has hundreds of affected files.
  *
- * `-r` lists nested blobs by full repo-relative path; `--name-only -z` makes
+ * `-r` lists nested blobs by full repo-relative path. `--name-only -z` makes
  * the output a trivial NUL-split with no quoting to undo. Membership in the
  * returned Set is exactly `await fileExistsInHead(repoDir, file)` for any
  * non-directory `file`. Throws (via {@link git}) when HEAD itself is
@@ -56,10 +56,10 @@ export declare function listTrackedInHead(repoDir: string, files: string[]): Pro
  * Uses {@link import('../utils/process.js').exec} rather than {@link git}
  * (which throws on a non-zero exit) because `git hash-object f1 f2 …` is
  * all-or-nothing: it aborts at the first unreadable path and emits nothing
- * for the rest. To keep the per-file contract — where one bad path zeroes
- * only its own index line — a chunk that does not return exactly one hash
+ * for the rest. To keep the per-file contract, where one bad path zeroes
+ * only its own index line, a chunk that does not return exactly one hash
  * per input falls back to hashing that chunk's paths individually. A path
- * that is still unhashable is left out of the map; the caller applies the
+ * that is still unhashable is left out of the map. The caller applies the
  * `0000000000` zero-hash fallback for any miss. Hashing stays in git rather
  * than in-process so filters and `.gitattributes` are applied per path and
  * the result cannot diverge under `core.autocrlf`/`text` attributes.

package/dist/src/core/git-file-ops.js

@@ -76,10 +76,10 @@ export async function fileExistsInHead(repoDir, filePath) {
 /**
  * Batched equivalent of {@link fileExistsInHead}: returns the subset of
  * `files` that are tracked in HEAD, using a single `git ls-tree` per ARG_MAX
- * chunk instead of one spawn per file. This is the cold-run hot path — a
- * Firefox-sized checkout has hundreds of affected files.
+ * chunk instead of one spawn per file. This is the cold-run hot path, and
+ * a Firefox-sized checkout has hundreds of affected files.
  *
- * `-r` lists nested blobs by full repo-relative path; `--name-only -z` makes
+ * `-r` lists nested blobs by full repo-relative path. `--name-only -z` makes
  * the output a trivial NUL-split with no quoting to undo. Membership in the
  * returned Set is exactly `await fileExistsInHead(repoDir, file)` for any
  * non-directory `file`. Throws (via {@link git}) when HEAD itself is
@@ -98,7 +98,7 @@ export async function listTrackedInHead(repoDir, files) {
         const output = await git(['ls-tree', '-r', 'HEAD', '--name-only', '-z', '--', ...chunk], repoDir);
         for (const name of output.split('\0')) {
             // `ls-tree -r` can surface entries beyond the literal inputs only when an
-            // input is itself a directory in HEAD; intersect with `wanted` so the
+            // input is itself a directory in HEAD. Intersect with `wanted` so the
             // result is always a subset of the requested files, never a superset.
             if (name.length > 0 && wanted.has(name))
                 tracked.add(name);
@@ -115,10 +115,10 @@ export async function listTrackedInHead(repoDir, files) {
  * Uses {@link import('../utils/process.js').exec} rather than {@link git}
  * (which throws on a non-zero exit) because `git hash-object f1 f2 …` is
  * all-or-nothing: it aborts at the first unreadable path and emits nothing
- * for the rest. To keep the per-file contract — where one bad path zeroes
- * only its own index line — a chunk that does not return exactly one hash
+ * for the rest. To keep the per-file contract, where one bad path zeroes
+ * only its own index line, a chunk that does not return exactly one hash
  * per input falls back to hashing that chunk's paths individually. A path
- * that is still unhashable is left out of the map; the caller applies the
+ * that is still unhashable is left out of the map. The caller applies the
  * `0000000000` zero-hash fallback for any miss. Hashing stays in git rather
  * than in-process so filters and `.gitattributes` are applied per path and
  * the result cannot diverge under `core.autocrlf`/`text` attributes.

package/dist/src/core/git-readonly-index.d.ts

@@ -1,25 +1,25 @@
 /**
- * Private-index scope for FireForge's READ-ONLY git plumbing.
+ * Private-index scope for FireForge's read-only git plumbing.
  *
  * `git status` and `git diff HEAD` are read-only in the sense operators care
- * about — they never change tracked content — but they are NOT read-only to
+ * about (they never change tracked content), but they are not read-only to
  * git: both refresh the index's stat cache and write `.git/index` (through
  * `.git/index.lock`) when a file's stat data has moved. That makes
- * `fireforge verify` / `lint --per-patch` / `typecheck` a second WRITER of
+ * `fireforge verify` / `lint --per-patch` / `typecheck` a second writer of
  * the primary `engine/` checkout, even when the command was pointed at a CoW
  * tree clone.
  *
  * The consequence is not cosmetic. A concurrent `fireforge test`
  * fingerprints `engine/` before and after the harness run and refuses a
  * verdict taken across a change (`FAIL reason=inconclusive`). That refusal is
- * CORRECT and stays; the defect is FireForge's own read-only commands
+ * correct and stays. The defect is FireForge's own read-only commands
  * tripping it.
  *
- * The fix is the standard git one: point the plumbing at a PRIVATE index
+ * The fix is the standard git one: point the plumbing at a private index
  * (`GIT_INDEX_FILE`) seeded from the repository's own, in a temp directory.
- * Refreshes land there and are thrown away; the primary `.git/index` — and
- * `.git/index.lock`, which is what makes a concurrent `git status` fail
- * outright rather than merely churn — is never touched.
+ * Refreshes land there and are thrown away. The primary `.git/index` is
+ * never touched, and neither is `.git/index.lock`, which is what makes a
+ * concurrent `git status` fail outright rather than merely churn.
  *
  * Fail-open by design: if the git dir or the index cannot be resolved or
  * copied, the scope does not activate and the commands behave exactly as
@@ -56,7 +56,7 @@ export declare function withPrivateGitIndex<T>(repoDir: string, operation: () =>
 /**
  * A private index file plus the cleanup that removes it.
  *
- * `env` is meant to be handed to a SINGLE git invocation (or a small
+ * `env` is meant to be handed to a single git invocation (or a small
  * sequence of them), rather than installed process-wide the way
  * {@link withPrivateGitIndex} installs a scope.
  */
@@ -68,20 +68,20 @@ export interface DisposableGitIndex {
 }
 /**
  * Mints a private index seeded from `repoDir`'s own, for a caller that
- * needs to WRITE the index without the write being visible to anyone else.
+ * needs to write the index without the write being visible to anyone else.
  *
  * The distinction from {@link withPrivateGitIndex} matters. That one exists
  * so a read-only command's incidental index refreshes do not touch the
  * primary checkout, and it is process-global, non-reentrant, and fail-open,
  * all of which are right for that job. This one serves a caller whose index
- * write is DELIBERATE and whose visibility is the defect: it is per-call, so
+ * write is intentional and whose visibility is the defect: it is per-call, so
  * two concurrent callers cannot collide, and it never depends on an ambient
  * scope having been installed by whichever command happens to be running.
  *
  * The seed is a plain copy, which is safe against a concurrent writer: git
  * writes the index through `index.lock` and an atomic rename, so a reader
  * sees either the old file or the new one, never a torn one. Seeding is
- * REQUIRED rather than merely tidy — an empty index makes a tracked,
+ * required rather than merely tidy: an empty index makes a tracked,
  * unmodified file look like a fresh add.
  *
  * @param repoDir - Repository whose index should be shadowed

package/dist/src/core/git-readonly-index.js

@@ -1,26 +1,26 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Private-index scope for FireForge's READ-ONLY git plumbing.
+ * Private-index scope for FireForge's read-only git plumbing.
  *
  * `git status` and `git diff HEAD` are read-only in the sense operators care
- * about — they never change tracked content — but they are NOT read-only to
+ * about (they never change tracked content), but they are not read-only to
  * git: both refresh the index's stat cache and write `.git/index` (through
  * `.git/index.lock`) when a file's stat data has moved. That makes
- * `fireforge verify` / `lint --per-patch` / `typecheck` a second WRITER of
+ * `fireforge verify` / `lint --per-patch` / `typecheck` a second writer of
  * the primary `engine/` checkout, even when the command was pointed at a CoW
  * tree clone.
  *
  * The consequence is not cosmetic. A concurrent `fireforge test`
  * fingerprints `engine/` before and after the harness run and refuses a
  * verdict taken across a change (`FAIL reason=inconclusive`). That refusal is
- * CORRECT and stays; the defect is FireForge's own read-only commands
+ * correct and stays. The defect is FireForge's own read-only commands
  * tripping it.
  *
- * The fix is the standard git one: point the plumbing at a PRIVATE index
+ * The fix is the standard git one: point the plumbing at a private index
  * (`GIT_INDEX_FILE`) seeded from the repository's own, in a temp directory.
- * Refreshes land there and are thrown away; the primary `.git/index` — and
- * `.git/index.lock`, which is what makes a concurrent `git status` fail
- * outright rather than merely churn — is never touched.
+ * Refreshes land there and are thrown away. The primary `.git/index` is
+ * never touched, and neither is `.git/index.lock`, which is what makes a
+ * concurrent `git status` fail outright rather than merely churn.
  *
  * Fail-open by design: if the git dir or the index cannot be resolved or
  * copied, the scope does not activate and the commands behave exactly as
@@ -66,7 +66,7 @@ export function readOnlyGitIndexEnv(cwd) {
 }
 /**
  * Resolves a repository's git directory. Returns undefined for anything
- * that is not a readable git checkout — `engine/` is not always one
+ * that is not a readable git checkout. `engine/` is not always one
  * (`fireforge download` extracts a source tarball).
  */
 async function resolveGitDir(repoDir) {
@@ -115,20 +115,20 @@ export async function withPrivateGitIndex(repoDir, operation) {
 }
 /**
  * Mints a private index seeded from `repoDir`'s own, for a caller that
- * needs to WRITE the index without the write being visible to anyone else.
+ * needs to write the index without the write being visible to anyone else.
  *
  * The distinction from {@link withPrivateGitIndex} matters. That one exists
  * so a read-only command's incidental index refreshes do not touch the
  * primary checkout, and it is process-global, non-reentrant, and fail-open,
  * all of which are right for that job. This one serves a caller whose index
- * write is DELIBERATE and whose visibility is the defect: it is per-call, so
+ * write is intentional and whose visibility is the defect: it is per-call, so
  * two concurrent callers cannot collide, and it never depends on an ambient
  * scope having been installed by whichever command happens to be running.
  *
  * The seed is a plain copy, which is safe against a concurrent writer: git
  * writes the index through `index.lock` and an atomic rename, so a reader
  * sees either the old file or the new one, never a torn one. Seeding is
- * REQUIRED rather than merely tidy — an empty index makes a tracked,
+ * required rather than merely tidy: an empty index makes a tracked,
  * unmodified file look like a fresh add.
  *
  * @param repoDir - Repository whose index should be shadowed

package/dist/src/core/git-status.d.ts

@@ -2,8 +2,8 @@ import type { GitStatusEntry } from './git-base.js';
 /**
  * Parses NUL-delimited porcelain status output.
  *
- * A rename or copy occupies TWO NUL records (`XY new\0old\0`), and the `R`/`C`
- * may sit in EITHER column: git >= 2.18 detects renames in the worktree too
+ * A rename or copy occupies two NUL records (`XY new\0old\0`), and the `R`/`C`
+ * may sit in either column: git >= 2.18 detects renames in the worktree too
  * (`status.renames`), emitting ` R new\0old\0` for an unstaged rename and
  * `RM`/`R ` for a staged one. Only consuming the second record for an index
  * `R`/`C` turned the worktree form's `old` field into a bogus extra entry
@@ -30,8 +30,8 @@ export declare function resolveMaxUntrackedFilesPerDir(): number;
  *
  * Expansion is capped per directory (FIREFORGE_MAX_UNTRACKED_FILES, default
  * 5000) with a warning on overflow. Without the cap, `reset --dry-run` after
- * an interrupted download — unborn HEAD, the entire ~300k file tree
- * untracked — enumerates and prints every file.
+ * an interrupted download (unborn HEAD, the entire ~300k file tree
+ * untracked) enumerates and prints every file.
  *
  * @param repoDir - Repository directory
  * @param entries - Parsed status entries

package/dist/src/core/git-status.js

@@ -14,8 +14,8 @@ function isRenameOrCopyColumn(column) {
 /**
  * Parses NUL-delimited porcelain status output.
  *
- * A rename or copy occupies TWO NUL records (`XY new\0old\0`), and the `R`/`C`
- * may sit in EITHER column: git >= 2.18 detects renames in the worktree too
+ * A rename or copy occupies two NUL records (`XY new\0old\0`), and the `R`/`C`
+ * may sit in either column: git >= 2.18 detects renames in the worktree too
  * (`status.renames`), emitting ` R new\0old\0` for an unstaged rename and
  * `RM`/`R ` for a staged one. Only consuming the second record for an index
  * `R`/`C` turned the worktree form's `old` field into a bogus extra entry
@@ -84,8 +84,8 @@ export function resolveMaxUntrackedFilesPerDir() {
  *
  * Expansion is capped per directory (FIREFORGE_MAX_UNTRACKED_FILES, default
  * 5000) with a warning on overflow. Without the cap, `reset --dry-run` after
- * an interrupted download — unborn HEAD, the entire ~300k file tree
- * untracked — enumerates and prints every file.
+ * an interrupted download (unborn HEAD, the entire ~300k file tree
+ * untracked) enumerates and prints every file.
  *
  * @param repoDir - Repository directory
  * @param entries - Parsed status entries

package/dist/src/core/git.d.ts

@@ -17,7 +17,7 @@ export declare function isGitRepository(dir: string): Promise<boolean>;
 export declare function ensureOriginRemote(dir: string): Promise<void>;
 /**
  * Stages all files in the repository.
- * Tries a monolithic `git add -A` first; if that times out, falls back to
+ * Tries a monolithic `git add -A` first. If that times out, falls back to
  * directory-by-directory staged adds.
  */
 export declare function stageAllFiles(dir: string, options?: {
@@ -56,8 +56,8 @@ export declare function applyPatch(patchPath: string, repoDir: string, options?:
  * @param patchPath - Path to the patch file
  * @param repoDir - Repository directory
  * @param options.reject - Fall back to `git apply --reject`
- * @param options.protectedFiles - Files that must NOT be reset to HEAD by the
- *   recovery step. Callers applying a patch QUEUE pass the files already
+ * @param options.protectedFiles - Files that must not be reset to HEAD by the
+ *   recovery step. Callers applying a patch queue pass the files already
  *   touched by previously applied patches in the same run: two overlapping
  *   patches (an `--allow-overlap` queue) share files, and a blanket
  *   `checkout HEAD` would wipe the earlier patch's changes from the shared

package/dist/src/core/git.js

@@ -41,8 +41,8 @@ export async function ensureOriginRemote(dir) {
 const GIT_ADD_ENV = { GIT_INDEX_THREADS: '0' };
 /**
  * Returns true when the error looks like a process killed by the spawn
- * timeout (SIGTERM → exit code 143) OR an AbortError raised by
- * `AbortSignal.timeout` — Node's `child_process` layer rejects with an
+ * timeout (SIGTERM → exit code 143) or an AbortError raised by
+ * `AbortSignal.timeout`. Node's `child_process` layer rejects with an
  * AbortError when the signal fires, so both shapes have to be recognised.
  */
 function isTimeoutError(error) {
@@ -76,7 +76,7 @@ async function cleanupIndexLock(dir) {
  * other exclusion mechanism git considers, e.g. `.git/info/exclude`,
  * core.excludesFile). Used by the chunked staging fallback to skip entries
  * that would otherwise fail `git add -- <path>` with the fatal "The
- * following paths are ignored by one of your .gitignore files" error — a
+ * following paths are ignored by one of your .gitignore files" error, a
  * state the monolithic `git add -A` path silently handles. A Firefox
  * checkout's top-level `.vscode/` is the common case: without this, the
  * chunked invocation aborts the whole fallback and turns a recoverable
@@ -93,7 +93,7 @@ async function isPathIgnored(dir, relativePath) {
         return true;
     if (result.exitCode === 1)
         return false;
-    // Any other shape is "we don't know" — let the caller proceed and
+    // Any other shape is "we don't know", so let the caller proceed and
     // surface the real error if `git add` rejects the path.
     return false;
 }
@@ -104,7 +104,7 @@ async function isPathIgnored(dir, relativePath) {
  *
  * A chunked pass that hits its own timeout raises a typed
  * {@link GitIndexingTimeoutError} rather than an opaque `AbortError: The
- * operation was aborted`; the typed error carries the environment-variable
+ * operation was aborted`. The typed error carries the environment-variable
  * override so the operator can extend the budget and re-run.
  */
 async function stageAllFilesChunked(dir, scan, options = {}) {
@@ -134,7 +134,7 @@ async function stageAllFilesChunked(dir, scan, options = {}) {
         options.onProgress?.(`Staging directory ${stagedDirectories}/${directories.length}: ${dirName}/...`);
         await runChunk(['add', '--', dirName], dirName);
     }
-    // Stage any top-level files (excluding gitignored ones — `git add`
+    // Stage any top-level files (excluding gitignored ones, because `git add`
     // on an explicit ignored path errors out, which would otherwise
     // abort the chunked fallback after the monolithic path has already
     // timed out).
@@ -154,7 +154,7 @@ async function stageAllFilesChunked(dir, scan, options = {}) {
 /**
  * Interval between heartbeat progress messages during the monolithic
  * `git add -A`. On a fresh ~600 MB Firefox tree the monolithic add runs
- * 60–120 seconds, during which git emits nothing to stdout/stderr. Without a
+ * 60 to 120 seconds, during which git emits nothing to stdout/stderr. Without a
  * heartbeat the CLI spinner stays pinned on "Indexing Firefox source …" for
  * the full window and looks hung, which invites a SIGINT mid-way.
  */
@@ -175,7 +175,7 @@ async function scanTopLevelSource(dir) {
 }
 /**
  * Stages all files in the repository.
- * Tries a monolithic `git add -A` first; if that times out, falls back to
+ * Tries a monolithic `git add -A` first. If that times out, falls back to
  * directory-by-directory staged adds.
  */
 export async function stageAllFiles(dir, options = {}) {
@@ -184,7 +184,7 @@ export async function stageAllFiles(dir, options = {}) {
     reportProgress?.('Scanning Firefox source tree before indexing...');
     const scan = await scanTopLevelSource(dir);
     reportProgress?.(`Source scan complete: ${scan.directories.length} top-level director${scan.directories.length === 1 ? 'y' : 'ies'}, ${scan.topLevelFiles.length} top-level file${scan.topLevelFiles.length === 1 ? '' : 's'}`);
-    // The heartbeat tracks a PER-PHASE start timestamp and labels each tick
+    // The heartbeat tracks a per-phase start timestamp and labels each tick
     // with the phase. A single start time set at function entry reports
     // cumulative elapsed for the whole `stageAllFiles` invocation, so after a
     // monolithic timeout the chunked-phase ticks name numbers that already
@@ -392,8 +392,8 @@ export async function applyPatch(patchPath, repoDir, options = {}) {
  * @param patchPath - Path to the patch file
  * @param repoDir - Repository directory
  * @param options.reject - Fall back to `git apply --reject`
- * @param options.protectedFiles - Files that must NOT be reset to HEAD by the
- *   recovery step. Callers applying a patch QUEUE pass the files already
+ * @param options.protectedFiles - Files that must not be reset to HEAD by the
+ *   recovery step. Callers applying a patch queue pass the files already
  *   touched by previously applied patches in the same run: two overlapping
  *   patches (an `--allow-overlap` queue) share files, and a blanket
  *   `checkout HEAD` would wipe the earlier patch's changes from the shared
@@ -424,14 +424,14 @@ export async function applyPatchIdempotent(patchPath, repoDir, options = {}) {
     await applyPatch(patchPath, repoDir, options);
 }
 /**
- * Restores `files` to their HEAD state, deleting files the patch would CREATE
- * (present on disk from a partial apply but absent in HEAD — for those,
+ * Restores `files` to their HEAD state, deleting files the patch would create
+ * (present on disk from a partial apply but absent in HEAD, where
  * `git checkout HEAD --` fails, and ignoring that failure leaves stray files
  * that make the subsequent forward apply die with "already exists" and no
  * hint why).
  *
  * Every git invocation is chunked via {@link chunkPathspecs} so a very large
- * patch cannot hit `E2BIG`, and every exit code is checked — a silent failed
+ * patch cannot hit `E2BIG`, and every exit code is checked. A silent failed
  * restore is the confusing state this recovery step exists to prevent.
  */
 async function restoreFilesToHead(repoDir, patchPath, files) {