@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/core/register-xpcshell-test.d.ts

@@ -2,8 +2,8 @@
  * xpcshell test-file registration. Without it, xpcshell test files (e.g.
  * `<module-dir>/test/unit/test_*.js`) are rejected by `fireforge register`
  * as "Unknown file pattern". This writer inserts the `["test_*.js"]` section
- * into the directory's `xpcshell.toml` (alphabetically, idempotently) and —
- * with `--create-manifest` — creates the manifest and wires
+ * into the directory's `xpcshell.toml` (alphabetically, idempotently). With
+ * `--create-manifest` it also creates the manifest and wires
  * `XPCSHELL_TESTS_MANIFESTS` into the nearest moz.build.
  */
 import type { RegisterResult } from './register-result.js';

package/dist/src/core/register-xpcshell-test.js

@@ -3,8 +3,8 @@
  * xpcshell test-file registration. Without it, xpcshell test files (e.g.
  * `<module-dir>/test/unit/test_*.js`) are rejected by `fireforge register`
  * as "Unknown file pattern". This writer inserts the `["test_*.js"]` section
- * into the directory's `xpcshell.toml` (alphabetically, idempotently) and —
- * with `--create-manifest` — creates the manifest and wires
+ * into the directory's `xpcshell.toml` (alphabetically, idempotently). With
+ * `--create-manifest` it also creates the manifest and wires
  * `XPCSHELL_TESTS_MANIFESTS` into the nearest moz.build.
  */
 import { join } from 'node:path';

package/dist/src/core/run-log-redact.d.ts

@@ -4,31 +4,31 @@
  * A run log is a complete copy of mach's output, and mach echoes its
  * environment in places (configure summaries, `mach env`, harness
  * diagnostics that print the command line). The terminal already showed
- * every byte to the operator who ran it; the file, by contrast, is retained
+ * every byte to the operator who ran it. The file, by contrast, is retained
  * twenty deep and gets attached to bug reports. So the file gets a narrow
  * masking pass and the terminal does not.
  *
- * Deliberately minimal and pattern-based — see {@link redactRunLogText} for
- * the exact contract. It is a seatbelt against the common accidental leak,
- * not a guarantee that a log is free of secrets.
+ * Minimal and pattern-based. See {@link redactRunLogText} for the exact
+ * contract. It is a seatbelt against the common accidental leak, not a
+ * guarantee that a log is free of secrets.
  */
 /**
  * Masks the obvious secret shapes in run-log text, line by line.
  *
  * Redacted:
  * - the value of an env-style assignment `KEY=value` whose KEY matches
- *   `/(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|AUTH)/i` — the value up to the
- *   next whitespace, or a whole quoted string — becomes `KEY=<redacted>`;
- *   the `--flag=value` and `-DNAME=value` spellings of the same shape are
- *   covered (`--password=x` → `--password=<redacted>`);
+ *   `/(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|AUTH)/i`. The value up to the
+ *   next whitespace, or a whole quoted string, becomes `KEY=<redacted>`.
+ *   The `--flag=value` and `-DNAME=value` spellings of the same shape are
+ *   covered (`--password=x` → `--password=<redacted>`).
  * - the credential of an `Authorization:` header (`Bearer`, `Basic` and
- *   `Token` schemes keep the scheme word; anything else masks the whole
- *   value).
+ *   `Token` schemes keep the scheme word, and anything else masks the
+ *   whole value).
  *
- * NOT redacted: secrets that appear without one of those key names or
+ * Not redacted: secrets that appear without one of those key names or
  * headers (a bare token in a URL query string, a space-separated
  * `--password foo` CLI argument, JSON `"token": "..."` fields, cookies).
- * Line structure and every other byte pass through unchanged; `\n`, `\r\n`
+ * Line structure and every other byte pass through unchanged. `\n`, `\r\n`
  * and lone `\r` all delimit lines, so carriage-return-repainted progress
  * output is masked per repaint.
  *

package/dist/src/core/run-log-redact.js

@@ -5,13 +5,13 @@
  * A run log is a complete copy of mach's output, and mach echoes its
  * environment in places (configure summaries, `mach env`, harness
  * diagnostics that print the command line). The terminal already showed
- * every byte to the operator who ran it; the file, by contrast, is retained
+ * every byte to the operator who ran it. The file, by contrast, is retained
  * twenty deep and gets attached to bug reports. So the file gets a narrow
  * masking pass and the terminal does not.
  *
- * Deliberately minimal and pattern-based — see {@link redactRunLogText} for
- * the exact contract. It is a seatbelt against the common accidental leak,
- * not a guarantee that a log is free of secrets.
+ * Minimal and pattern-based. See {@link redactRunLogText} for the exact
+ * contract. It is a seatbelt against the common accidental leak, not a
+ * guarantee that a log is free of secrets.
  */
 /** Env-style keys whose assigned value is masked. */
 const SECRET_KEY_PATTERN = /(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|AUTH)/i;
@@ -21,8 +21,8 @@ const SECRET_KEY_PATTERN = /(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|AUTH)/i;
  * the assignment anchored at a token boundary so `x.y=z` is not split
  * mid-token. A hyphen IS a boundary: mach and configure echo their argv, so
  * `--token=…`, `--password=…` and `-DAUTH_TOKEN=…` are exactly the forms a
- * retained log would otherwise carry verbatim (the lead keeps the dash; the
- * key is what follows it). Empty values are left alone (nothing to hide).
+ * retained log would otherwise carry verbatim (the lead keeps the dash, and
+ * the key is what follows it). Empty values are left alone (nothing to hide).
  */
 const ENV_ASSIGNMENT_PATTERN = /(^|[\s"'([{,;-])([A-Za-z_][A-Za-z0-9_]*)=("(?:[^"\\]|\\.)*"|'[^']*'|[^\s"',;)\]}]+)/g;
 /** `Authorization: <scheme> <credential>` (scheme optional) in HTTP dumps. */
@@ -39,18 +39,18 @@ function redactLine(line) {
  *
  * Redacted:
  * - the value of an env-style assignment `KEY=value` whose KEY matches
- *   `/(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|AUTH)/i` — the value up to the
- *   next whitespace, or a whole quoted string — becomes `KEY=<redacted>`;
- *   the `--flag=value` and `-DNAME=value` spellings of the same shape are
- *   covered (`--password=x` → `--password=<redacted>`);
+ *   `/(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|AUTH)/i`. The value up to the
+ *   next whitespace, or a whole quoted string, becomes `KEY=<redacted>`.
+ *   The `--flag=value` and `-DNAME=value` spellings of the same shape are
+ *   covered (`--password=x` → `--password=<redacted>`).
  * - the credential of an `Authorization:` header (`Bearer`, `Basic` and
- *   `Token` schemes keep the scheme word; anything else masks the whole
- *   value).
+ *   `Token` schemes keep the scheme word, and anything else masks the
+ *   whole value).
  *
- * NOT redacted: secrets that appear without one of those key names or
+ * Not redacted: secrets that appear without one of those key names or
  * headers (a bare token in a URL query string, a space-separated
  * `--password foo` CLI argument, JSON `"token": "..."` fields, cookies).
- * Line structure and every other byte pass through unchanged; `\n`, `\r\n`
+ * Line structure and every other byte pass through unchanged. `\n`, `\r\n`
  * and lone `\r` all delimit lines, so carriage-return-repainted progress
  * output is masked per repaint.
  *
@@ -60,8 +60,8 @@ function redactLine(line) {
 export function redactRunLogText(text) {
     if (text.length === 0)
         return text;
-    // Split with a capturing group so the terminators survive the round trip;
-    // odd indices are the terminators themselves.
+    // Split with a capturing group so the terminators survive the round trip.
+    // Odd indices are the terminators themselves.
     return text
         .split(/(\r\n|\n|\r)/)
         .map((part, index) => (index % 2 === 0 ? redactLine(part) : part))

package/dist/src/core/run-log.d.ts

@@ -2,19 +2,19 @@
  * Per-run output logs under `.fireforge/logs/`.
  *
  * A run's diagnosis used to exist in exactly one place: the terminal. Piping
- * through `tail`/`grep` — the ergonomic default when output is long — keeps
- * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say WHAT
+ * through `tail`/`grep`, the ergonomic default when output is long, keeps
+ * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say what
  * broke, and it launders the exit code besides. The operator rule ("never
  * pipe a run") was written down three times downstream and broken after each
- * writing, which is the tell that it is not an operator problem: the tool is
- * the only party that can make the log survive the mistake.
+ * writing, so this is not an operator problem: the tool is the only party
+ * that can make the log survive the mistake.
  *
  * So `test` and `build` write their own complete copy as they stream, and the
  * `FIREFORGE-VERDICT:` line names the path. A piped, truncated, or
  * backgrounded run then still leaves a re-readable artifact.
  *
- * Everything here is BEST-EFFORT by construction. A log is a diagnostic aid;
- * a run must never fail because one could not be opened, written, or pruned.
+ * Everything here is best-effort. A log is a diagnostic aid, and a run must
+ * never fail because one could not be opened, written, or pruned.
  * Every entry point swallows its errors and degrades to "no log", which is
  * exactly the behaviour that existed before this module.
  */
@@ -24,7 +24,7 @@ export interface RunLog {
     path: string;
     /**
      * Appends output. Complete lines pass through {@link redactRunLogText}
-     * before hitting disk; a trailing partial line is held until its newline
+     * before hitting disk. A trailing partial line is held until its newline
      * arrives (or until `close`). Silently drops on any stream error.
      */
     write: (chunk: string) => void;
@@ -59,10 +59,10 @@ export declare function writeToActiveRunLog(chunk: string): void;
  */
 export declare function closeActiveRunLog(): Promise<void>;
 /**
- * A writable that forwards to `base` AND to the active run log.
+ * A writable that forwards to `base` and to the active run log.
  *
  * Used by the stdio-inheriting capture path, whose collectors take a mirror
- * stream rather than per-chunk callbacks — so the tee reuses the mirror the
+ * stream rather than per-chunk callbacks, so the tee reuses the mirror the
  * exec layer already supports instead of growing a second hook.
  *
  * @param base - The stream to forward to (normally `process.stdout`)

package/dist/src/core/run-log.js

@@ -3,19 +3,19 @@
  * Per-run output logs under `.fireforge/logs/`.
  *
  * A run's diagnosis used to exist in exactly one place: the terminal. Piping
- * through `tail`/`grep` — the ergonomic default when output is long — keeps
- * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say WHAT
+ * through `tail`/`grep`, the ergonomic default when output is long, keeps
+ * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say what
  * broke, and it launders the exit code besides. The operator rule ("never
  * pipe a run") was written down three times downstream and broken after each
- * writing, which is the tell that it is not an operator problem: the tool is
- * the only party that can make the log survive the mistake.
+ * writing, so this is not an operator problem: the tool is the only party
+ * that can make the log survive the mistake.
  *
  * So `test` and `build` write their own complete copy as they stream, and the
  * `FIREFORGE-VERDICT:` line names the path. A piped, truncated, or
  * backgrounded run then still leaves a re-readable artifact.
  *
- * Everything here is BEST-EFFORT by construction. A log is a diagnostic aid;
- * a run must never fail because one could not be opened, written, or pruned.
+ * Everything here is best-effort. A log is a diagnostic aid, and a run must
+ * never fail because one could not be opened, written, or pruned.
  * Every entry point swallows its errors and degrades to "no log", which is
  * exactly the behaviour that existed before this module.
  */
@@ -39,19 +39,19 @@ const RETAINED_LOGS_PER_COMMAND = 20;
 /**
  * Cap on the partial line held back between writes. A child emitting one
  * enormous unterminated line (a minified dump on stderr) would otherwise
- * grow the buffer without bound — and, because each write rebuilds
- * `pending + chunk`, quadratically — with nothing reaching disk until
- * close. Past the cap the tail is redacted and written as-is; a `KEY=value`
+ * grow the buffer without bound (and, because each write rebuilds
+ * `pending + chunk`, quadratically), with nothing reaching disk until
+ * close. Past the cap the tail is redacted and written as-is. A `KEY=value`
  * split exactly at the cap boundary is the accepted cost. Same figure as
  * `line-dispatch.ts` uses for the stream matchers.
  */
 const MAX_PENDING_LINE_SIZE = 1024 * 1024;
 /**
  * Index just past the last line terminator in `text`, or -1 when there is
- * none. `\n` and lone `\r` both terminate — progress-bar output (mach,
+ * none. `\n` and lone `\r` both terminate: progress-bar output (mach,
  * cargo) repaints a line with carriage returns and may never send a
  * newline, which would otherwise pin the whole run in `pending`. A single
- * trailing `\r` is NOT a terminator yet: it may be the first half of a
+ * trailing `\r` is not a terminator yet: it may be the first half of a
  * `\r\n` split across chunks.
  */
 function lastLineEnd(text) {
@@ -67,7 +67,7 @@ export function getRunLogDir(projectRoot) {
 /**
  * Makes room for one new log by deleting the oldest, so that at most
  * {@link RETAINED_LOGS_PER_COMMAND} logs for `command` exist once the new
- * one is created. Pruning runs BEFORE the file is opened — hence the
+ * one is created. Pruning runs before the file is opened, hence the
  * `- 1`, without which the directory settles at N + 1.
  *
  * Best-effort: a failure here must not stop the run that is about to be
@@ -211,10 +211,10 @@ export async function closeActiveRunLog() {
     await log?.close();
 }
 /**
- * A writable that forwards to `base` AND to the active run log.
+ * A writable that forwards to `base` and to the active run log.
  *
  * Used by the stdio-inheriting capture path, whose collectors take a mirror
- * stream rather than per-chunk callbacks — so the tee reuses the mirror the
+ * stream rather than per-chunk callbacks, so the tee reuses the mirror the
  * exec layer already supports instead of growing a second hook.
  *
  * @param base - The stream to forward to (normally `process.stdout`)

package/dist/src/core/shared-ftl.d.ts

@@ -2,13 +2,13 @@
  * Structural rules for the `sharedFtl` field on a custom component.
  *
  * Both the `--shared-ftl` CLI flag path (`furnace create`) and the
- * furnace.json parser apply the same rules — extracting them here
+ * furnace.json parser apply the same rules. Extracting them here
  * avoids drift between the two entry points and lets the `.mjs`
  * template generator assume the value is safe to interpolate verbatim.
  */
 /**
  * Outcome of {@link validateSharedFtl}. `ok: true` carries the trimmed
- * (operator-safe) value; `ok: false` carries a human-readable message
+ * (operator-safe) value. `ok: false` carries a human-readable message
  * suitable for throwing as a `FurnaceError` or `InvalidArgumentError`.
  */
 export type SharedFtlValidation = {

package/dist/src/core/shared-ftl.js

@@ -3,18 +3,18 @@
  * Structural rules for the `sharedFtl` field on a custom component.
  *
  * Both the `--shared-ftl` CLI flag path (`furnace create`) and the
- * furnace.json parser apply the same rules — extracting them here
+ * furnace.json parser apply the same rules. Extracting them here
  * avoids drift between the two entry points and lets the `.mjs`
  * template generator assume the value is safe to interpolate verbatim.
  */
 /**
  * Characters that must not appear in `sharedFtl`.
  *
- * A POLICY rule about what a sensible FTL path looks like, not the safety
- * boundary for the generated `.mjs`: the scaffold escapes the value at its
- * sink with `JSON.stringify` (`commands/furnace/create-templates.ts`), which
- * is what actually makes interpolation safe and what covers the two inputs
- * this rule never catches — a `"` and a raw newline.
+ * This is a policy rule about what a sensible FTL path looks like, not the
+ * safety boundary for the generated `.mjs`. The scaffold escapes the value at
+ * its sink with `JSON.stringify` (`commands/furnace/create-templates.ts`),
+ * which is what actually makes interpolation safe, and what covers the two
+ * inputs this rule never catches: a `"` and a raw newline.
  *
  * Kept because each remains a real sign of a malformed path:
  *  - `\` is a path-escape we do not want to interpret.

package/dist/src/core/signal-critical.d.ts

@@ -13,7 +13,7 @@
  * for the slot to clear before calling `process.exit`, so a signal that
  * lands mid-body is held until the body's state write finishes.
  *
- * This module is a pure runtime registry — it installs no signal handlers
+ * This module is a pure runtime registry. It installs no signal handlers
  * itself. The bin entry point is responsible for awaiting
  * `waitForActiveCriticalSections` before terminating.
  */
@@ -23,7 +23,7 @@
  * SIGTERM that arrives during `fn` will hold exit until `fn` returns (or
  * rejects).
  *
- * `fn` should be short — anything that takes longer than the bounded wait in
+ * `fn` should be short. Anything that takes longer than the bounded wait in
  * the bin handler (`SIGNAL_CRITICAL_SECTION_TIMEOUT_MS`) will time out and
  * the handler will exit anyway. The intent is "guard the apply + state
  * persist pair," not "postpone exit indefinitely."

package/dist/src/core/signal-critical.js

@@ -14,7 +14,7 @@
  * for the slot to clear before calling `process.exit`, so a signal that
  * lands mid-body is held until the body's state write finishes.
  *
- * This module is a pure runtime registry — it installs no signal handlers
+ * This module is a pure runtime registry. It installs no signal handlers
  * itself. The bin entry point is responsible for awaiting
  * `waitForActiveCriticalSections` before terminating.
  */
@@ -26,7 +26,7 @@ const activeSections = new Set();
  * SIGTERM that arrives during `fn` will hold exit until `fn` returns (or
  * rejects).
  *
- * `fn` should be short — anything that takes longer than the bounded wait in
+ * `fn` should be short. Anything that takes longer than the bounded wait in
  * the bin handler (`SIGNAL_CRITICAL_SECTION_TIMEOUT_MS`) will time out and
  * the handler will exit anyway. The intent is "guard the apply + state
  * persist pair," not "postpone exit indefinitely."

package/dist/src/core/smoke-patterns.d.ts

@@ -12,14 +12,14 @@
  */
 /**
  * Returns `true` when `line` matches any pattern in
- * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step
+ * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist. That step
  * lives in {@link matchAllowlist}, so the smoke runner can count
  * allowlisted hits separately from raw error matches for its summary.
  */
 export declare function matchesSmokeError(line: string): boolean;
 /**
  * One compiled allowlist entry with its provenance retained so the smoke
- * summary can attribute hits per entry — an entry that silently
+ * summary can attribute hits per entry. An entry that silently
  * stops matching (its suppressed shape changed upstream) is only
  * detectable when zero-hit entries are visible.
  */
@@ -32,16 +32,16 @@ export interface CompiledAllowlistEntry {
 }
 /**
  * Returns the index of the FIRST entry in `allow` matching `line`, or -1.
- * First-match attribution is deterministic and cheap; a line matching
+ * First-match attribution is deterministic and cheap. A line matching
  * several entries credits the earliest one. Safe to call with an empty
  * allowlist (always returns -1).
  */
 export declare function matchAllowlist(line: string, allow: readonly CompiledAllowlistEntry[]): number;
 /**
- * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
+ * Parses a newline-delimited allowlist file body. Lines are trimmed. Blank
  * lines and `#`-prefixed comments are skipped. Each remaining line is
  * compiled as a RegExp with its `<file>:<line>` origin retained. A bad
- * pattern throws immediately — better to fail fast at CLI parse time than
+ * pattern throws immediately: better to fail fast at CLI parse time than
  * to silently let a typo match nothing.
  */
 export declare function compileAllowlistFromFile(body: string, sourcePath: string): CompiledAllowlistEntry[];

package/dist/src/core/smoke-patterns.js

@@ -16,25 +16,25 @@
  * process. A hit on any of these patterns is a smoke failure unless the
  * line also matches the caller-supplied allowlist.
  *
- * Additions here should be conservative — false positives turn every
+ * Additions here should be conservative. False positives turn every
  * smoke run into noise for operators and every CI run into flake.
  */
 import { toError } from '../utils/errors.js';
 const SMOKE_ERROR_PATTERNS = [
-    // Firefox chrome error lines — `JavaScript error: chrome://…, line N: TypeError: …`.
+    // Firefox chrome error lines: `JavaScript error: chrome://…, line N: TypeError: …`.
     /^\s*JavaScript error:/i,
     // Some log paths prefix browser-console `console.error(...)` with the literal label below.
     /^\s*console\.error:/i,
     // Older bracketed-prefix variant still seen in some chrome logs / test runs.
     /^\s*\[JavaScript (Error|Warning)\]/i,
-    // IPC-layer fatal assertions — Firefox prints `###!!! [Parent] Error: …` on content-process crashes.
+    // IPC-layer fatal assertions. Firefox prints `###!!! [Parent] Error: …` on content-process crashes.
     /^\s*###!!! \[Parent\]/,
     // A chrome:// or resource:// URL that resolves to nothing. Outside
     // automation Gecko only PRINTS this (printf_stderr in
-    // `CheckForBrokenChromeURL`, netwerk/base/nsNetUtil.cpp); under
+    // `CheckForBrokenChromeURL`, netwerk/base/nsNetUtil.cpp). Under
     // `xpc::IsInAutomation()` the same condition is a
     // `MOZ_CRASH_UNSAFE_PRINTF` in whichever process opened the channel. So
-    // the smoke probe — which runs OUTSIDE automation — sees the printed
+    // the smoke probe, which runs outside automation, sees the printed
     // line for the same defect that hard-crashes every harness run, and a
     // probe that exits 0 on it reports "startup is healthy" for a build that
     // hangs at "Waiting for browser…". Both spellings are matched: the
@@ -44,7 +44,7 @@ const SMOKE_ERROR_PATTERNS = [
 ];
 /**
  * Returns `true` when `line` matches any pattern in
- * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step
+ * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist. That step
  * lives in {@link matchAllowlist}, so the smoke runner can count
  * allowlisted hits separately from raw error matches for its summary.
  */
@@ -58,7 +58,7 @@ export function matchesSmokeError(line) {
 }
 /**
  * Returns the index of the FIRST entry in `allow` matching `line`, or -1.
- * First-match attribution is deterministic and cheap; a line matching
+ * First-match attribution is deterministic and cheap. A line matching
  * several entries credits the earliest one. Safe to call with an empty
  * allowlist (always returns -1).
  */
@@ -66,10 +66,10 @@ export function matchAllowlist(line, allow) {
     return allow.findIndex((entry) => entry.pattern.test(line));
 }
 /**
- * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
+ * Parses a newline-delimited allowlist file body. Lines are trimmed. Blank
  * lines and `#`-prefixed comments are skipped. Each remaining line is
  * compiled as a RegExp with its `<file>:<line>` origin retained. A bad
- * pattern throws immediately — better to fail fast at CLI parse time than
+ * pattern throws immediately: better to fail fast at CLI parse time than
  * to silently let a typo match nothing.
  */
 export function compileAllowlistFromFile(body, sourcePath) {

package/dist/src/core/state-file.d.ts

@@ -17,11 +17,11 @@ export declare function quarantineStateFile(statePath: string, reason?: string):
  * Outcome of a version check on a persisted FireForge document.
  *
  * The distinction that matters is `newer` vs `corrupt`. A document written
- * by a NEWER FireForge is not damaged — the operator simply needs to upgrade
- * — but a check that collapses the two offers destructive remedies. The
+ * by a newer FireForge is not damaged. The operator simply needs to upgrade.
+ * A check that collapses the two offers destructive remedies. The
  * sharpest case is the tree marker, whose `schemaVersion` check inside a
  * boolean type guard makes a `schemaVersion: 2` marker read as "missing or
- * mistypes a required field"; `tree-guard.ts` is default-deny on corrupt, so
+ * mistypes a required field". `tree-guard.ts` is default-deny on corrupt, so
  * a newer FireForge would lock the operator out of every mutating command
  * inside that tree.
  *

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

@@ -2,21 +2,21 @@
  * Binary-aware drift classification for patch-owned files.
  *
  * The text classifier compares utf-8 decoded content against
- * `computePatchedContent`, which cannot apply `GIT binary patch` bodies — so
+ * `computePatchedContent`, which cannot apply `GIT binary patch` bodies, so
  * a binary file exported into a patch classifies as `patch-owned-drift`
  * forever, keeping the engine-clean gate permanently red with nothing
- * actually un-durable. A `GIT binary patch` section DOES carry the ground
+ * actually un-durable. A `GIT binary patch` section does carry the ground
  * truth: `git diff --binary` always records full blob hashes on the section's
  * `index <old>..<new>` line. Comparing the live file's `git hash-object`
  * against the last owning section's new-side hash settles the classification
  * exactly. Bodies without a usable hash (hand-written diffs) classify as
- * `binary-unsupported` — an honest "cannot compare" instead of a false "not
+ * `binary-unsupported`: an honest "cannot compare" instead of a false "not
  * durable".
  *
- * That hash is trusted ONLY when the section carries a replayable payload
+ * That hash is trusted only when the section carries a replayable payload
  * (`hasBinaryDelta`). A `Binary files … differ` stub carries a correct index
  * line too, so hashing against it reports `patch-backed` for a body that
- * cannot rebuild the file at all — precisely the dishonesty this module
+ * cannot rebuild the file at all, which is the dishonesty this module
  * exists to avoid. Such a body is `binary-unsupported` here, and an error
  * from the `binary-body-not-reconstructable` queue lint.
  *
@@ -40,8 +40,8 @@ export interface BinaryClassifiedFile {
 }
 /**
  * Classifies a single-owner file whose comparison is binary. Returns
- * `null` when the comparison is NOT binary — the live file is text and
- * (for deletions) the owning section is text — so the caller falls
+ * `null` when the comparison is not binary (the live file is text and,
+ * for deletions, the owning section is text), so the caller falls
  * through to the existing utf-8 content comparison unchanged.
  *
  * @param args.fileMissing - True when the porcelain status reports the
@@ -57,6 +57,6 @@ export declare function classifyBinaryOwnedFile(args: {
     matchClassification: 'patch-backed' | 'furnace';
     owner: string;
     fileMissing?: boolean;
-    /** Batched lookup; when absent, falls back to per-file manifest queries. */
+    /** Batched lookup. When absent, falls back to per-file manifest queries. */
     lookup?: AffectingPatchLookup;
 }): Promise<BinaryClassifiedFile | null>;

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

@@ -3,21 +3,21 @@
  * Binary-aware drift classification for patch-owned files.
  *
  * The text classifier compares utf-8 decoded content against
- * `computePatchedContent`, which cannot apply `GIT binary patch` bodies — so
+ * `computePatchedContent`, which cannot apply `GIT binary patch` bodies, so
  * a binary file exported into a patch classifies as `patch-owned-drift`
  * forever, keeping the engine-clean gate permanently red with nothing
- * actually un-durable. A `GIT binary patch` section DOES carry the ground
+ * actually un-durable. A `GIT binary patch` section does carry the ground
  * truth: `git diff --binary` always records full blob hashes on the section's
  * `index <old>..<new>` line. Comparing the live file's `git hash-object`
  * against the last owning section's new-side hash settles the classification
  * exactly. Bodies without a usable hash (hand-written diffs) classify as
- * `binary-unsupported` — an honest "cannot compare" instead of a false "not
+ * `binary-unsupported`: an honest "cannot compare" instead of a false "not
  * durable".
  *
- * That hash is trusted ONLY when the section carries a replayable payload
+ * That hash is trusted only when the section carries a replayable payload
  * (`hasBinaryDelta`). A `Binary files … differ` stub carries a correct index
  * line too, so hashing against it reports `patch-backed` for a body that
- * cannot rebuild the file at all — precisely the dishonesty this module
+ * cannot rebuild the file at all, which is the dishonesty this module
  * exists to avoid. Such a body is `binary-unsupported` here, and an error
  * from the `binary-body-not-reconstructable` queue lint.
  *
@@ -35,7 +35,7 @@ import { parseDiffSections } from './patch-parse.js';
 /** Finds the LAST diff section affecting `file` across the owning patches, in queue order. */
 async function findLastAffectingSection(patchesDir, file, lookup) {
     // The lookup shares one manifest load + memoized body reads across the
-    // whole classification batch; the fallback keeps single-file callers
+    // whole classification batch. The fallback keeps single-file callers
     // (and existing direct tests) working without a context.
     const patches = lookup !== undefined
         ? lookup.getAffectingPatches(file)
@@ -53,8 +53,8 @@ async function findLastAffectingSection(patchesDir, file, lookup) {
 }
 /**
  * Classifies a single-owner file whose comparison is binary. Returns
- * `null` when the comparison is NOT binary — the live file is text and
- * (for deletions) the owning section is text — so the caller falls
+ * `null` when the comparison is not binary (the live file is text and,
+ * for deletions, the owning section is text), so the caller falls
  * through to the existing utf-8 content comparison unchanged.
  *
  * @param args.fileMissing - True when the porcelain status reports the
@@ -68,8 +68,8 @@ export async function classifyBinaryOwnedFile(args) {
         classification: 'binary-unsupported',
         owner,
     });
-    // Until the comparison is KNOWN to be binary, every failure defers to
-    // the existing text path (`return null`) — classifying a text file as
+    // Until the comparison is known to be binary, every failure defers to
+    // the existing text path (`return null`). Classifying a text file as
     // `binary-unsupported` because a probe failed would hide real drift.
     let section;
     try {
@@ -89,12 +89,12 @@ export async function classifyBinaryOwnedFile(args) {
     try {
         if (section === undefined) {
             // Claimed in filesAffected but no diff section touches the file.
-            // A missing file keeps the existing deletion logic; a live binary
+            // A missing file keeps the existing deletion logic. A live binary
             // has nothing recorded to compare against.
             return fileMissing ? null : unsupported();
         }
         if (!section.isBinary) {
-            // Text section: deletions settle fine through the text path; a
+            // Text section: deletions settle fine through the text path. A
             // live binary against a text body has no comparable recording.
             return fileMissing ? null : unsupported();
         }