@hominis/fireforge 0.45.0 → 0.46.1

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();
         }

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

@@ -7,34 +7,34 @@
  */
 /**
  * Classification buckets for engine file changes:
- * - `patch-backed`: content matches the expected post-patch state — normal
+ * - `patch-backed`: content matches the expected post-patch state. Normal
  *   after `fireforge import`.
  * - `patch-owned-drift`: the file is claimed by exactly one patch, but the
  *   live engine content no longer matches that patch's expected post-apply
  *   content. This includes furnace-prefixed paths: a path can be both
  *   Furnace-managed and patch-claimed (export a deployed component, then
- *   edit the workspace source and `furnace deploy` again — the deployed copy
- *   now has content the patch body lacks). Checking the furnace prefix first
- *   would bucket such files as `furnace` and report the stale patch as
- *   owned.
- * - `unmanaged`: edits not explained by any patch or tool — local drift to
+ *   edit the workspace source and `furnace deploy` again, and the deployed
+ *   copy now has content the patch body lacks). Checking the furnace
+ *   prefix first would bucket such files as `furnace` and report the stale
+ *   patch as owned.
+ * - `unmanaged`: edits not explained by any patch or tool. Local drift to
  *   export or discard.
  * - `branding`: files under tool-managed branding paths, written by
  *   FireForge's branding pipeline.
  * - `furnace`: files under Furnace-managed component prefixes. When exactly
  *   one patch also claims the path, this bucket asserts the live content
- *   matches that patch's expected post-apply content — a mismatch is
+ *   matches that patch's expected post-apply content. A mismatch is
  *   reported as `patch-owned-drift` instead (see above).
  * - `conflict`: the file is claimed by two or more patches in
  *   `patches.json`. The human `--ownership` mode surfaces this bucket as
- *   `CONFLICT`; carrying the classification through the JSON pipeline lets
+ *   `CONFLICT`. Carrying the classification through the JSON pipeline lets
  *   machine consumers detect the same ownership breakage rather than seeing
  *   it rolled into `unmanaged` as routine local drift.
  * - `binary-unsupported`: the file's comparison is binary and the owning
- *   patch body records no usable blob hash to compare against — an honest
- *   "binary — comparison unsupported" instead of a permanent false
- *   `patch-owned-drift`. Deliberately NOT in the default `--check` fail set;
- *   opt in with `--fail-on binary-unsupported`.
+ *   patch body records no usable blob hash to compare against. It reports an
+ *   honest "binary, comparison unsupported" instead of a permanent false
+ *   `patch-owned-drift`. Not in the default `--check` fail set. Opt in
+ *   with `--fail-on binary-unsupported`.
  */
 export type FileClassification = 'patch-backed' | 'patch-owned-drift' | 'unmanaged' | 'branding' | 'furnace' | 'conflict' | 'binary-unsupported';
 export interface StatusFile {
@@ -45,7 +45,7 @@ export interface ClassifiedFile extends StatusFile {
     classification: FileClassification;
     /**
      * Names of patch files that claim this path in `patches.json`.
-     * Populated only when `classification === 'conflict'` — single-claim
+     * Populated only when `classification === 'conflict'`. Single-claim
      * patch-backed entries don't need to expose their owner because the
      * single claim is fully captured by the classification itself.
      */
@@ -54,14 +54,14 @@ export interface ClassifiedFile extends StatusFile {
      * Owning patch filename when exactly one patch claims this path
      * (patch-backed, patch-owned-drift, and single-owner furnace entries).
      * Unset for unowned, branding-generated, unowned-furnace, and conflict
-     * entries — conflicts carry `claimedBy` instead. Exposed through
+     * entries. Conflicts carry `claimedBy` instead. Exposed through
      * `status --json` as the `patch` field.
      */
     owner?: string;
 }
 /**
  * Builds the file → owning-patch-filenames multimap from manifest rows.
- * Single source of truth for cross-patch claim detection — status
+ * Single source of truth for cross-patch claim detection: status
  * classification, verify's cross-claim check, and the ownership table all
  * consume this builder (they used to each rebuild it, one drift away from
  * disagreeing about what "claimed" means).
@@ -72,14 +72,14 @@ export declare function buildPatchClaims(manifestPatches: ReadonlyArray<{
 }>): Map<string, string[]>;
 /**
  * Reduces a two-character porcelain XY status to its primary code.
- * Single source of truth — status-output.ts renders from the same logic.
+ * Single source of truth, and status-output.ts renders from the same logic.
  */
 export declare function getPrimaryStatusCode(status: string): string;
 /**
  * True for the branding paths whose content FireForge generates itself
  * (configure.sh, brand.properties/ftl, browser/moz.configure). Unlike the
  * broader branding-root test, a brand-new unowned file under the branding
- * directory is NOT generated — it is a patch candidate and must stay
+ * directory is not generated: it is a patch candidate and must stay
  * visible as unmanaged (the Assets.car precedent).
  */
 export declare function isGeneratedBrandingPath(file: string, binaryName: string): boolean;

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

@@ -11,12 +11,13 @@ import { mapWithConcurrency } from '../utils/concurrency.js';
 import { toError } from '../utils/errors.js';
 import { readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { isBrandingManagedPath } from './branding.js';
 import { createPatchedContentContext } from './patch-apply.js';
 import { classifyBinaryOwnedFile } from './status-binary.js';
 /**
  * Builds the file → owning-patch-filenames multimap from manifest rows.
- * Single source of truth for cross-patch claim detection — status
+ * Single source of truth for cross-patch claim detection: status
  * classification, verify's cross-claim check, and the ownership table all
  * consume this builder (they used to each rebuild it, one drift away from
  * disagreeing about what "claimed" means).
@@ -34,7 +35,7 @@ export function buildPatchClaims(manifestPatches) {
 }
 /**
  * Reduces a two-character porcelain XY status to its primary code.
- * Single source of truth — status-output.ts renders from the same logic.
+ * Single source of truth, and status-output.ts renders from the same logic.
  */
 export function getPrimaryStatusCode(status) {
     if (status.includes('?'))
@@ -52,11 +53,11 @@ export function getPrimaryStatusCode(status) {
  * True for the branding paths whose content FireForge generates itself
  * (configure.sh, brand.properties/ftl, browser/moz.configure). Unlike the
  * broader branding-root test, a brand-new unowned file under the branding
- * directory is NOT generated — it is a patch candidate and must stay
+ * directory is not generated: it is a patch candidate and must stay
  * visible as unmanaged (the Assets.car precedent).
  */
 export function isGeneratedBrandingPath(file, binaryName) {
-    const normalized = file.replace(/\\/g, '/');
+    const normalized = normalizePathSlashes(file);
     const brandingRoot = `browser/branding/${binaryName}`;
     return (normalized === 'browser/moz.configure' ||
         normalized === `${brandingRoot}/configure.sh` ||
@@ -66,15 +67,15 @@ export function isGeneratedBrandingPath(file, binaryName) {
 /**
  * Compares a single-owner file's live engine content against its owning
  * patch's expected post-apply content. `matchClassification` is what a
- * clean match reports — `patch-backed` for ordinary patch-claimed paths,
+ * clean match reports: `patch-backed` for ordinary patch-claimed paths,
  * `furnace` for furnace-prefixed paths so healthy deployed components
  * keep landing in the pinned furnace bucket. Any mismatch (including a
  * deletion the patch does not expect, or a failed comparison) reports
  * `patch-owned-drift`.
  */
 async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassification, owner, ctx) {
-    // Binary comparisons cannot go through the utf-8 content path below —
-    // binary patch bodies parse to zero hunks, so the patched-content
+    // Binary comparisons cannot go through the utf-8 content path below.
+    // Binary patch bodies parse to zero hunks, so the patched-content
     // computation returned HEAD content unchanged and the comparison
     // reported `patch-owned-drift` forever. Settle by blob hash,
     // or classify explicitly as `binary-unsupported` when no hash exists.
@@ -99,7 +100,7 @@ async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassi
             owner,
         };
     }
-    // File exists on disk — compare actual vs expected
+    // File exists on disk: compare actual vs expected
     try {
         const [expected, actual] = await Promise.all([
             ctx.computePatched(entry.file),
@@ -129,7 +130,7 @@ async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassi
  */
 export async function classifyFiles(files, engineDir, patchesDir, binaryName, furnacePrefixes) {
     // One manifest load + patch discovery + memoized body reads for the
-    // whole batch — the previous per-file computation re-ran all three for
+    // whole batch. The previous per-file computation re-ran all three for
     // every dirty file (O(dirtyFiles × patches) redundant IO on a broad
     // engine edit session).
     const ctx = await createPatchedContentContext(patchesDir, engineDir);
@@ -149,14 +150,14 @@ export async function classifyFiles(files, engineDir, patchesDir, binaryName, fu
         ctx,
     };
     // Bounded pool over per-file classification (each single-owner file
-    // spawns git); order preserved by the mapper. Per-file failures settle
+    // spawns git). Order preserved by the mapper. Per-file failures settle
     // inside classifySingleOwnerFile's catch, so one bad file never rejects
     // the batch.
     return mapWithConcurrency(files, CLASSIFY_CONCURRENCY, (entry) => classifyEntry(entry, deps));
 }
 /** Concurrency bound for per-file classification (matches import's guard). */
 const CLASSIFY_CONCURRENCY = 8;
-/** Classifies one status entry; extracted so the pool worker stays flat. */
+/** Classifies one status entry. Extracted so the pool worker stays flat. */
 async function classifyEntry(entry, deps) {
     const { engineDir, patchesDir, binaryName, furnacePrefixes, patchClaims, ctx } = deps;
     const owners = patchClaims.get(entry.file);
@@ -208,7 +209,7 @@ async function classifyEntry(entry, deps) {
     if (!owners) {
         return { ...entry, classification: 'unmanaged' };
     }
-    // File is claimed by exactly one patch — compare content.
+    // File is claimed by exactly one patch: compare content.
     const owner = owners[0];
     if (owner === undefined) {
         return { ...entry, classification: 'unmanaged' };

package/dist/src/core/test-changed-prefs.d.ts

@@ -1,26 +1,26 @@
 /**
  * Recognizer for the one mochitest failure shape that is a function of run
- * LENGTH rather than of the code under test: the time-driven
+ * length rather than of the code under test: the time-driven
  * changed-preference checks.
  *
  * Separate from `test-harness-crash.ts` because it is not a crash
- * classification — the run failed, and the classifier's verdict is correct.
- * What this adds is which KIND of failure it was, which is a different
+ * classification. The run failed, and the classifier's verdict is correct.
+ * What this adds is which kind of failure it was, which is a different
  * question and one that only grows as more such shapes are recorded.
  */
 /**
- * Describes a failure set that consists ENTIRELY of changed-preference
+ * Describes a failure set that consists entirely of changed-preference
  * checks on {@link TIME_DRIVEN_PREF_NAMES}.
  *
- * Deliberately keyed on the pref NAMES rather than on the harness's phrasing
- * of its changed-preference report: the phrasing is upstream copy that has
- * no stable contract with us, and the names are the part that identifies the
- * shape. A single block that names anything else — a real assertion, a
- * different pref — disqualifies the whole set, because the point is to
- * describe a run whose every failure is this noise, never to explain away
- * one real failure sitting beside it.
+ * Keyed on the pref names rather than on the harness's phrasing of its
+ * changed-preference report: the phrasing is upstream copy that has no
+ * stable contract with us, and the names are the part that identifies the
+ * shape. A single block that names anything else (a real assertion, a
+ * different pref) disqualifies the whole set, so that this describes a run
+ * whose every failure is this noise, and never explains away one real
+ * failure sitting beside it.
  *
- * Pure; returns undefined when the shape does not apply.
+ * Pure. Returns undefined when the shape does not apply.
  *
  * @param output - Combined harness stdout+stderr
  * @returns Operator-facing explanation, or undefined

package/dist/src/core/test-changed-prefs.js

@@ -1,23 +1,23 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Recognizer for the one mochitest failure shape that is a function of run
- * LENGTH rather than of the code under test: the time-driven
+ * length rather than of the code under test: the time-driven
  * changed-preference checks.
  *
  * Separate from `test-harness-crash.ts` because it is not a crash
- * classification — the run failed, and the classifier's verdict is correct.
- * What this adds is which KIND of failure it was, which is a different
+ * classification. The run failed, and the classifier's verdict is correct.
+ * What this adds is which kind of failure it was, which is a different
  * question and one that only grows as more such shapes are recorded.
  */
 import { collectUnexpectedFailureBlocks } from './test-harness-crash.js';
 /**
- * Preferences that move on their own as a function of how LONG a run takes,
+ * Preferences that move on their own as a function of how long a run takes,
  * not of what it tested.
  *
  * Both are time-driven: a long run crosses the cold-startup check interval
  * and the pref moves under the harness. The observable consequence is that
  * chunk length, not the change under test, decides whether the suite is
- * red — the same work at a smaller `--chunk` passes. FireForge cannot
+ * red. The same work at a smaller `--chunk` passes. FireForge cannot
  * suppress the check (it is the harness's, not ours) but it can stop the
  * pair being indistinguishable from two real assertion failures, which is
  * the whole cost of the shape.
@@ -29,23 +29,47 @@ const TIME_DRIVEN_PREF_NAMES = ['lastColdStartupCheck', 'globalprivacycontrol'];
 /** A failure block that is a changed-preference report rather than an assertion. */
 const CHANGED_PREF_BLOCK_PATTERN = /pref(?:erence)?s?\b/i;
 /**
- * Describes a failure set that consists ENTIRELY of changed-preference
+ * Describes a failure set that consists entirely of changed-preference
  * checks on {@link TIME_DRIVEN_PREF_NAMES}.
  *
- * Deliberately keyed on the pref NAMES rather than on the harness's phrasing
- * of its changed-preference report: the phrasing is upstream copy that has
- * no stable contract with us, and the names are the part that identifies the
- * shape. A single block that names anything else — a real assertion, a
- * different pref — disqualifies the whole set, because the point is to
- * describe a run whose every failure is this noise, never to explain away
- * one real failure sitting beside it.
+ * Keyed on the pref names rather than on the harness's phrasing of its
+ * changed-preference report: the phrasing is upstream copy that has no
+ * stable contract with us, and the names are the part that identifies the
+ * shape. A single block that names anything else (a real assertion, a
+ * different pref) disqualifies the whole set, so that this describes a run
+ * whose every failure is this noise, and never explains away one real
+ * failure sitting beside it.
  *
- * Pure; returns undefined when the shape does not apply.
+ * Pure. Returns undefined when the shape does not apply.
  *
  * @param output - Combined harness stdout+stderr
  * @returns Operator-facing explanation, or undefined
  */
 export function describeChangedPrefNoise(output) {
+    const namesSeen = matchedTimeDrivenPrefNames(output);
+    if (namesSeen === undefined)
+        return undefined;
+    return (`Every unexpected result in this run is a changed-preference check on ${[...namesSeen].join(' / ')}. ` +
+        'Those preferences are TIME-DRIVEN: they move once a run is long enough to cross the ' +
+        'cold-startup check interval, so they correlate with run LENGTH rather than with the ' +
+        'change under test or with the build. The first probe is to halve the chunk size ' +
+        '(`--chunk 8` where a 40-row chunk tripped it) and see whether the same work passes; ' +
+        'if it does, this was harness noise, not a regression. FireForge cannot forgive the ' +
+        'check — it belongs to the harness — only tell you which kind of failure you are ' +
+        'looking at.');
+}
+/** Failure blocks inspected before the changed-pref shape is abandoned. */
+const CHANGED_PREF_BLOCK_LIMIT = 20;
+/**
+ * The recognizer half of the shape, split from the formatting so a caller
+ * that only needs the yes/no answer does not build the ~500-character
+ * explanation to throw it away.
+ *
+ * @param output - Combined harness stdout+stderr
+ * @returns The time-driven pref names seen, or undefined when the shape does
+ *   not apply
+ */
+function matchedTimeDrivenPrefNames(output) {
     const blocks = collectUnexpectedFailureBlocks(output, CHANGED_PREF_BLOCK_LIMIT).filter((block) => !block.startsWith('…'));
     if (blocks.length === 0)
         return undefined;
@@ -59,20 +83,11 @@ export function describeChangedPrefNoise(output) {
         for (const name of matched)
             namesSeen.add(name);
     }
-    return (`Every unexpected result in this run is a changed-preference check on ${[...namesSeen].join(' / ')}. ` +
-        'Those preferences are TIME-DRIVEN: they move once a run is long enough to cross the ' +
-        'cold-startup check interval, so they correlate with run LENGTH rather than with the ' +
-        'change under test or with the build. The first probe is to halve the chunk size ' +
-        '(`--chunk 8` where a 40-row chunk tripped it) and see whether the same work passes; ' +
-        'if it does, this was harness noise, not a regression. FireForge cannot forgive the ' +
-        'check — it belongs to the harness — only tell you which kind of failure you are ' +
-        'looking at.');
+    return namesSeen;
 }
-/** Failure blocks inspected before the changed-pref shape is abandoned. */
-const CHANGED_PREF_BLOCK_LIMIT = 20;
 /** Short verdict-line note for the changed-preference-noise shape. */
 export function changedPrefNoiseVerdictNote(output) {
-    return describeChangedPrefNoise(output) === undefined
+    return matchedTimeDrivenPrefNames(output) === undefined
         ? undefined
         : 'all unexpected results are time-driven changed-pref checks';
 }