@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,96 +0,0 @@
-/**
- * Status classifier: partitions engine file changes into
- * patch-backed / unmanaged / branding / furnace / conflict buckets.
- *
- * Extracted from `src/commands/status.ts` so that command file stays
- * under the per-file line budget as the number of buckets grows.
- */
-/**
- * Classification buckets for engine file changes:
- * - `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, 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
- *   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
- *   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. 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 {
-    status: string;
-    file: string;
-}
-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
-     * patch-backed entries don't need to expose their owner because the
-     * single claim is fully captured by the classification itself.
-     */
-    claimedBy?: string[];
-    /**
-     * 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
-     * `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
- * classification, verify's cross-claim check, and the ownership table all
- * consume this builder, so they cannot disagree about what "claimed" means.
- */
-export declare function buildPatchClaims(manifestPatches: ReadonlyArray<{
-    filename: string;
-    filesAffected: string[];
-}>): Map<string, string[]>;
-/**
- * Reduces a two-character porcelain XY status to its primary code.
- * 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
- * visible as unmanaged (the Assets.car precedent).
- */
-export declare function isGeneratedBrandingPath(file: string, binaryName: string): boolean;
-/**
- * Classifies files into patch-backed, unmanaged, branding, furnace, or
- * conflict buckets.
- *
- * Tracks patch ownership as a `Map<file, patchFilename[]>` rather than a
- * plain `Set<file>` so the classifier can surface cross-patch ownership
- * conflicts the same way the human `--ownership` mode does. With only a Set,
- * `status --json` reports `classification: "unmanaged"` on files that
- * `--ownership` correctly flags as `CONFLICT`, which lies to machine
- * consumers about the nature of the drift.
- */
-export declare function classifyFiles(files: StatusFile[], engineDir: string, patchesDir: string, binaryName: string, furnacePrefixes: Set<string>): Promise<ClassifiedFile[]>;

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

@@ -1,244 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Status classifier: partitions engine file changes into
- * patch-backed / unmanaged / branding / furnace / conflict buckets.
- *
- * Extracted from `src/commands/status.ts` so that command file stays
- * under the per-file line budget as the number of buckets grows.
- */
-import { join } from 'node:path';
-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 { isBinaryFile } from './git-file-ops.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
- * classification, verify's cross-claim check, and the ownership table all
- * consume this builder, so they cannot disagree about what "claimed" means.
- */
-export function buildPatchClaims(manifestPatches) {
-    const ownersByPath = new Map();
-    for (const patch of manifestPatches) {
-        for (const file of patch.filesAffected) {
-            const existing = ownersByPath.get(file) ?? [];
-            existing.push(patch.filename);
-            ownersByPath.set(file, existing);
-        }
-    }
-    return ownersByPath;
-}
-/**
- * Reduces a two-character porcelain XY status to its primary code.
- * Single source of truth, and status-output.ts renders from the same logic.
- */
-export function getPrimaryStatusCode(status) {
-    if (status.includes('?'))
-        return '?';
-    if (status.includes('!'))
-        return '!';
-    for (const code of status) {
-        if (code !== ' ') {
-            return code;
-        }
-    }
-    return 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
- * visible as unmanaged (the Assets.car precedent).
- */
-export function isGeneratedBrandingPath(file, binaryName) {
-    const normalized = normalizePathSlashes(file);
-    const brandingRoot = `browser/branding/${binaryName}`;
-    return (normalized === 'browser/moz.configure' ||
-        normalized === `${brandingRoot}/configure.sh` ||
-        normalized === `${brandingRoot}/locales/en-US/brand.properties` ||
-        normalized === `${brandingRoot}/locales/en-US/brand.ftl`);
-}
-/**
- * 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,
- * `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
-    // 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.
-    const binaryResult = await classifyBinaryOwnedFile({
-        entry,
-        engineDir,
-        patchesDir,
-        matchClassification,
-        owner,
-        fileMissing: getPrimaryStatusCode(entry.status) === 'D',
-        lookup: ctx,
-    });
-    if (binaryResult !== null) {
-        return binaryResult;
-    }
-    if (getPrimaryStatusCode(entry.status) === 'D') {
-        // Deleted file: content matches only if the patch expects deletion
-        const expected = await ctx.computePatched(entry.file);
-        return {
-            ...entry,
-            classification: expected === null ? matchClassification : 'patch-owned-drift',
-            owner,
-        };
-    }
-    // File exists on disk: compare actual vs expected
-    try {
-        const [expected, actual] = await Promise.all([
-            ctx.computePatched(entry.file),
-            readText(join(engineDir, entry.file)),
-        ]);
-        return {
-            ...entry,
-            classification: actual === expected ? matchClassification : 'patch-owned-drift',
-            owner,
-        };
-    }
-    catch (error) {
-        verbose(`Treating ${entry.file} as patch-owned drift because patch-backed classification failed: ${toError(error).message}`);
-        return { ...entry, classification: 'patch-owned-drift', owner };
-    }
-}
-/**
- * Classifies files into patch-backed, unmanaged, branding, furnace, or
- * conflict buckets.
- *
- * Tracks patch ownership as a `Map<file, patchFilename[]>` rather than a
- * plain `Set<file>` so the classifier can surface cross-patch ownership
- * conflicts the same way the human `--ownership` mode does. With only a Set,
- * `status --json` reports `classification: "unmanaged"` on files that
- * `--ownership` correctly flags as `CONFLICT`, which lies to machine
- * consumers about the nature of the drift.
- */
-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
-    // every dirty file (O(dirtyFiles × patches) redundant IO on a broad
-    // engine edit session).
-    const ctx = await createPatchedContentContext(patchesDir, engineDir);
-    // Build a multimap from file path → list of claiming patch filenames so
-    // cross-patch ownership conflicts are detectable. A plain `Set<string>`
-    // captures only whether a path was claimed, not by whom, and collapses
-    // multi-owner files into the single-owner branch where the
-    // expected-vs-actual content comparison then routes them into `unmanaged`
-    // when the content matches neither owner's expectation.
-    const patchClaims = buildPatchClaims(ctx.manifestPatches);
-    await prefetchSingleOwnerContent(files, engineDir, patchClaims, ctx);
-    const deps = {
-        engineDir,
-        patchesDir,
-        binaryName,
-        furnacePrefixes,
-        patchClaims,
-        ctx,
-    };
-    // Bounded pool over per-file classification. 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));
-}
-/**
- * Fetches, in two git processes, what the per-file comparison would
- * otherwise spawn git for file by file: the HEAD content of every
- * single-owner path (one `cat-file --batch`) and the live blob hash of every
- * one that is binary on disk (one `hash-object` per ARG_MAX chunk). On a
- * 1,600-file Firefox scan that was ~1,550 `git show` and `hash-object`
- * spawns. Fetching for a path the classifier ends up routing elsewhere
- * (a branding path, say) costs a few bytes, never a wrong answer.
- */
-async function prefetchSingleOwnerContent(files, engineDir, patchClaims, ctx) {
-    const singleOwner = files.filter((entry) => patchClaims.get(entry.file)?.length === 1);
-    if (singleOwner.length === 0)
-        return;
-    await ctx.prefetchBase(singleOwner.map((entry) => entry.file));
-    const present = singleOwner.filter((entry) => getPrimaryStatusCode(entry.status) !== 'D');
-    const binary = await mapWithConcurrency(present, CLASSIFY_CONCURRENCY, async (entry) => {
-        try {
-            return (await isBinaryFile(engineDir, entry.file)) ? join(engineDir, entry.file) : undefined;
-        }
-        catch {
-            // The per-file path probes again and settles the failure itself.
-            return undefined;
-        }
-    });
-    await ctx.prefetchLiveBlobHashes(binary.filter((path) => path !== undefined));
-}
-/** 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. */
-async function classifyEntry(entry, deps) {
-    const { engineDir, patchesDir, binaryName, furnacePrefixes, patchClaims, ctx } = deps;
-    const owners = patchClaims.get(entry.file);
-    const primaryCode = getPrimaryStatusCode(entry.status);
-    // Ownership is a structural invariant and takes precedence over the
-    // content-management bucket. Otherwise a branding/Furnace prefix hides a
-    // multi-patch claim from status --check/--json even though --ownership
-    // reports the same path as CONFLICT.
-    if (owners && owners.length >= 2) {
-        return {
-            ...entry,
-            classification: 'conflict',
-            claimedBy: [...owners],
-        };
-    }
-    // Branding paths are tool-managed for generated edits, but a brand-new
-    // unowned branding asset must not disappear from `status --unmanaged`:
-    // classifying every branding path before checking ownership hides a new
-    // patch candidate (an Assets.car appearing under the active branding tree,
-    // for instance) as "branding" even though no patch claims it yet.
-    const isUnownedNewFile = owners === undefined && (primaryCode === '?' || primaryCode === 'A');
-    if (isBrandingManagedPath(entry.file, binaryName) &&
-        (!isUnownedNewFile || isGeneratedBrandingPath(entry.file, binaryName))) {
-        return { ...entry, classification: 'branding' };
-    }
-    // Furnace-managed component paths
-    if (furnacePrefixes.size > 0) {
-        let isFurnace = false;
-        for (const prefix of furnacePrefixes) {
-            if (entry.file.startsWith(prefix)) {
-                isFurnace = true;
-                break;
-            }
-        }
-        if (isFurnace) {
-            // A furnace path claimed by exactly one patch gets the same
-            // expected-vs-actual comparison as any other single-owner path: after
-            // a `furnace deploy` of an edited component the deployed copy has
-            // content the owning patch's body lacks, and an unconditional
-            // short-circuit here would silently bucket that drift as `furnace`.
-            // Multi-owner and unowned furnace paths keep the short-circuit.
-            if (owners && owners.length === 1 && owners[0] !== undefined) {
-                return classifySingleOwnerFile(entry, engineDir, patchesDir, 'furnace', owners[0], ctx);
-            }
-            return { ...entry, classification: 'furnace' };
-        }
-    }
-    // Not in any patch → unmanaged
-    if (!owners) {
-        return { ...entry, classification: 'unmanaged' };
-    }
-    // File is claimed by exactly one patch: compare content.
-    const owner = owners[0];
-    if (owner === undefined) {
-        return { ...entry, classification: 'unmanaged' };
-    }
-    return classifySingleOwnerFile(entry, engineDir, patchesDir, 'patch-backed', owner, ctx);
-}

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

@@ -1,30 +0,0 @@
-/**
- * Recognizer for the one mochitest failure shape that is a function of run
- * 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
- * question and one that only grows as more such shapes are recorded.
- */
-/**
- * Describes a failure set that consists entirely of changed-preference
- * checks on {@link TIME_DRIVEN_PREF_NAMES}.
- *
- * 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.
- *
- * @param output - Combined harness stdout+stderr
- * @returns Operator-facing explanation, or undefined
- */
-export declare function describeChangedPrefNoise(output: string): string | undefined;
-/** Short verdict-line note for the changed-preference-noise shape. */
-export declare function changedPrefNoiseVerdictNote(output: string): string | undefined;

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

@@ -1,93 +0,0 @@
-// 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
- * 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
- * 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,
- * 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
- * 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.
- *
- * Matched as substrings: the harness prints fully-qualified pref names and
- * the leading namespace has moved upstream more than once.
- */
-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
- * checks on {@link TIME_DRIVEN_PREF_NAMES}.
- *
- * 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.
- *
- * @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;
-    const namesSeen = new Set();
-    for (const block of blocks) {
-        if (!CHANGED_PREF_BLOCK_PATTERN.test(block))
-            return undefined;
-        const matched = TIME_DRIVEN_PREF_NAMES.filter((name) => block.includes(name));
-        if (matched.length === 0)
-            return undefined;
-        for (const name of matched)
-            namesSeen.add(name);
-    }
-    return namesSeen;
-}
-/** Short verdict-line note for the changed-preference-noise shape. */
-export function changedPrefNoiseVerdictNote(output) {
-    return matchedTimeDrivenPrefNames(output) === undefined
-        ? undefined
-        : 'all unexpected results are time-driven changed-pref checks';
-}