@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/commands/doctor-source-pin.js

@@ -1,91 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Doctor check comparing the configured Firefox source pin against what the
- * engine checkout actually is.
- *
- * `fireforge source set` lands `firefox.version` inside `fireforge.json`,
- * beside hand-maintained policy sections. That is convenient and it is also
- * the whole problem: a routine `git checkout -- fireforge.json` (undoing an
- * accidental reformat, say) silently reverts an uncommitted pin along with
- * it, and nothing afterwards reports that the pin and the checkout have
- * diverged. In the field this showed up as a gate flipping green with no
- * change that should have made it green.
- *
- * This is not a lock and not a refusal: a tree may legitimately be
- * mid-migration between two versions. It only makes a mismatched tree
- * visible, which is all that was missing.
- *
- * Scope is limited by what is actually recorded. `firefox.product`,
- * `firefox.sha256` and `firefox.candidate` have no counterpart anywhere on
- * disk (`.fireforge/state.json` records only `downloadedVersion` and
- * `baseCommit`), so there is nothing to compare them against and the check
- * says nothing about them rather than implying it verified them.
- */
-import { getFirefoxVersion } from '../core/firefox.js';
-import { toError } from '../utils/errors.js';
-import { exec } from '../utils/process.js';
-import { ok, warning } from './doctor-check-core.js';
-const CHECK_NAME = 'Source pin matches engine';
-/**
- * Reports the configured pin beside the two facts that can contradict it:
- * the engine's own `browser/config/version.txt`, and the version the last
- * download recorded into state.
- */
-async function runSourcePinCheck(ctx) {
-    const pinned = ctx.config?.firefox.version;
-    if (pinned === undefined) {
-        // The config failed to load (its own check already reported that), so
-        // there is no pin to compare. Silence beats a second complaint.
-        return ok(CHECK_NAME, 'Skipped: no configured source version');
-    }
-    let actual;
-    try {
-        // A blank or whitespace-only version.txt (a truncated write, a partial
-        // extraction) carries no version to compare, so treat it as absent
-        // rather than reporting the engine as being at version "".
-        const pristine = await exec('git', ['show', 'HEAD:browser/config/version.txt'], {
-            cwd: ctx.paths.engine,
-        }).catch(() => undefined);
-        actual =
-            (pristine?.exitCode === 0
-                ? pristine.stdout
-                : await getFirefoxVersion(ctx.paths.engine))?.trim() || undefined;
-    }
-    catch (error) {
-        // Best-effort: an unreadable version.txt is not a pin mismatch, and a
-        // diagnostic must never turn into a failure of its own.
-        return ok(CHECK_NAME, `Configured ${pinned}; engine version could not be read (${toError(error).message})`);
-    }
-    const downloaded = ctx.state.downloadedVersion;
-    const mismatches = [];
-    // Firefox's version.txt never carries the `esr` suffix (an ESR 153.4.0esr
-    // tree reads 153.4.0), so the engine comparison drops it from the pin. The
-    // last download recorded the full pin, so that comparison keeps it.
-    if (actual !== undefined && actual !== pinned && actual !== pinned.replace(/esr$/, '')) {
-        mismatches.push(`engine baseline browser/config/version.txt reads ${actual}`);
-    }
-    if (downloaded !== undefined && downloaded !== pinned) {
-        mismatches.push(`the last download recorded ${downloaded}`);
-    }
-    if (mismatches.length === 0) {
-        const observed = actual ?? downloaded;
-        return ok(CHECK_NAME, observed === undefined
-            ? `Configured ${pinned}; no engine version to compare against yet`
-            : `Configured ${pinned}, engine ${observed}`);
-    }
-    return warning(CHECK_NAME, `fireforge.json pins Firefox ${pinned}, but ${mismatches.join(' and ')}.`, 'If the pin is right, run "fireforge download" to bring the checkout to it. If the ' +
-        'CHECKOUT is right, run "fireforge source set --version <version>" to record it — a ' +
-        'pin set but not committed is lost by any revert of fireforge.json, which is the most ' +
-        'common way these diverge.');
-}
-/**
- * Pin-vs-checkout reporting. Needs the loaded config, so it declares the
- * dependency on the config check that populates `ctx.config`. It is skipped
- * entirely without an engine, where there is nothing to compare.
- */
-export const SOURCE_PIN_DOCTOR_CHECK = {
-    name: CHECK_NAME,
-    skipIf: (ctx) => !ctx.engineExists,
-    dependsOn: ['fireforge.json is valid'],
-    run: runSourcePinCheck,
-};

package/dist/src/commands/doctor-working-tree.d.ts

@@ -1,27 +0,0 @@
-/**
- * Ownership-aware working-tree check for `fireforge doctor`.
- *
- * Partitions engine-tree dirtiness into `branding`, `patch-backed`,
- * `furnace`, `conflict`, and `unmanaged` buckets, and only warns on the
- * last two. Everything else is tool-managed state that the operator
- * did not author directly.
- *
- * Split out of `doctor.ts` so that file stays under the per-file LOC
- * budget. See the call site in `runEngineGitChecks`.
- */
-import type { DoctorCheck } from '../types/commands/index.js';
-import type { DoctorCheckContext } from './doctor-check-core.js';
-/**
- * Inspects the engine working tree and returns a single `DoctorCheck`.
- * Ownership-aware: patch-backed / branding / furnace rows are reported as OK
- * with an ownership summary. Unmanaged drift warns. Cross-patch conflicts
- * warn loudly with a pointer at `fireforge status --ownership` +
- * `fireforge verify`.
- *
- * Ownership is what makes the advice safe: warning on every dirty row and
- * telling the operator to export/discard/reset is actively destructive on a
- * patch-backed import, where the suggested fix would drop the entire patch
- * stack. Returns `undefined` when the worktree is clean so the caller can
- * emit its own ok() row.
- */
-export declare function inspectEngineWorkingTree(ctx: DoctorCheckContext): Promise<DoctorCheck | undefined>;

package/dist/src/commands/doctor-working-tree.js

@@ -1,89 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Ownership-aware working-tree check for `fireforge doctor`.
- *
- * Partitions engine-tree dirtiness into `branding`, `patch-backed`,
- * `furnace`, `conflict`, and `unmanaged` buckets, and only warns on the
- * last two. Everything else is tool-managed state that the operator
- * did not author directly.
- *
- * Split out of `doctor.ts` so that file stays under the per-file LOC
- * budget. See the call site in `runEngineGitChecks`.
- */
-import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
-import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
-import { classifyFiles } from '../core/status-classify.js';
-import { ok, warning } from './doctor-check-core.js';
-function summarizeWorkingTreeChangeCount(changeCount) {
-    return `Engine working tree has ${changeCount} local change${changeCount === 1 ? '' : 's'}. Some FireForge commands assume a clean baseline and may behave differently until these are exported, discarded, or committed.`;
-}
-function formatManagedDetail(counts) {
-    return [
-        counts.patchBacked > 0 ? `${counts.patchBacked} patch-backed` : null,
-        counts.patchOwnedDrift > 0 ? `${counts.patchOwnedDrift} patch-owned drift` : null,
-        counts.branding > 0 ? `${counts.branding} branding` : null,
-        counts.furnace > 0 ? `${counts.furnace} furnace` : null,
-    ]
-        .filter((part) => part !== null)
-        .join(', ');
-}
-/**
- * Inspects the engine working tree and returns a single `DoctorCheck`.
- * Ownership-aware: patch-backed / branding / furnace rows are reported as OK
- * with an ownership summary. Unmanaged drift warns. Cross-patch conflicts
- * warn loudly with a pointer at `fireforge status --ownership` +
- * `fireforge verify`.
- *
- * Ownership is what makes the advice safe: warning on every dirty row and
- * telling the operator to export/discard/reset is actively destructive on a
- * patch-backed import, where the suggested fix would drop the entire patch
- * stack. Returns `undefined` when the worktree is clean so the caller can
- * emit its own ok() row.
- */
-export async function inspectEngineWorkingTree(ctx) {
-    const { paths } = ctx;
-    const rawStatus = await getWorkingTreeStatus(paths.engine);
-    const workingTreeStatus = await expandUntrackedDirectoryEntries(paths.engine, rawStatus);
-    if (workingTreeStatus.length === 0) {
-        return ok('Engine working tree');
-    }
-    if (!ctx.config) {
-        return warning('Engine working tree', summarizeWorkingTreeChangeCount(workingTreeStatus.length), 'Use "fireforge status" to review changes, then export, discard, or reset them as appropriate.');
-    }
-    const furnacePrefixes = await collectFurnaceManagedPrefixes(ctx.projectRoot);
-    const classified = await classifyFiles(workingTreeStatus.map((entry) => ({ status: entry.status, file: entry.file })), paths.engine, paths.patches, ctx.config.binaryName, furnacePrefixes);
-    const counts = {
-        branding: 0,
-        furnace: 0,
-        patchBacked: 0,
-        patchOwnedDrift: 0,
-        conflict: 0,
-        unmanaged: 0,
-    };
-    for (const entry of classified) {
-        if (entry.classification === 'branding')
-            counts.branding++;
-        else if (entry.classification === 'furnace')
-            counts.furnace++;
-        else if (entry.classification === 'patch-backed')
-            counts.patchBacked++;
-        else if (entry.classification === 'patch-owned-drift')
-            counts.patchOwnedDrift++;
-        else if (entry.classification === 'conflict')
-            counts.conflict++;
-        else
-            counts.unmanaged++;
-    }
-    if (counts.conflict > 0) {
-        return warning('Engine working tree', `Engine working tree has ${counts.conflict} cross-patch ownership conflict${counts.conflict === 1 ? '' : 's'}. Multiple patches in patches.json claim the same file.`, 'Run "fireforge status --ownership" to see the conflicting patches, then run "fireforge verify" and resolve the overlap.');
-    }
-    const managedTotal = counts.branding + counts.furnace + counts.patchBacked + counts.patchOwnedDrift;
-    if (counts.unmanaged === 0) {
-        const managedDetail = formatManagedDetail(counts);
-        return ok('Engine working tree', `${managedTotal} tool-managed change${managedTotal === 1 ? '' : 's'} (${managedDetail}), 0 unmanaged. Use "fireforge status --ownership" for details.`);
-    }
-    const managedTail = managedTotal > 0
-        ? ` (${managedTotal} other change${managedTotal === 1 ? '' : 's'} are tool-managed: ${formatManagedDetail(counts)}).`
-        : '';
-    return warning('Engine working tree', `Engine working tree has ${counts.unmanaged} unmanaged change${counts.unmanaged === 1 ? '' : 's'}.${managedTail}`, 'Use "fireforge status --ownership" to separate patch-backed from unmanaged files, then export, discard, or reset only the unmanaged set.');
-}

package/dist/src/commands/doctor.d.ts

@@ -1,49 +0,0 @@
-import { Command } from 'commander';
-import { ExitCode } from '../errors/codes.js';
-import type { CommandContext } from '../types/cli.js';
-import type { DoctorCheck, DoctorOptions } from '../types/commands/index.js';
-import type { DoctorCheckDefinition } from './doctor-check-core.js';
-/**
- * Validates that every check's `dependsOn` entries appear earlier in the
- * registry. Called once at module load time so a broken reorder surfaces
- * immediately as a thrown error rather than producing a subtle
- * context-population bug at runtime.
- *
- * Exported so tests can exercise the forward-only invariant against
- * fixtures. The real DOCTOR_CHECKS list is also validated at import
- * time, but a targeted unit test makes the contract explicit and
- * prevents regressions if the validator is ever relaxed.
- */
-export declare function validateCheckDependencies(checks: readonly DoctorCheckDefinition[]): void;
-/**
- * Ordered list of the doctor check names, exported for tests. Pinning
- * the order here is intentional: any reorder that breaks the
- * context-population dependency chain (see {@link DOCTOR_CHECKS}) must
- * also update this list, which gives us a single place to notice and
- * think through the consequences.
- *
- * @internal Exported only so tests can reach it. Not part of the public surface.
- */
-export declare const DOCTOR_CHECK_ORDER: readonly string[];
-/**
- * Renders a list of doctor checks to the console and returns the
- * appropriate exit code (success when no errors, general error otherwise).
- * @param checks - The check results to display
- * @returns The exit code reflecting the overall result
- */
-export declare function reportDoctorResults(checks: DoctorCheck[], mutations?: readonly string[]): ExitCode;
-/**
- * Result of the doctor command, carrying the exit code so the caller
- * (or test) can inspect it without relying on process.exitCode.
- */
-export interface DoctorResult {
-    checks: DoctorCheck[];
-    exitCode: number;
-}
-/**
- * Runs the doctor command to diagnose issues.
- * @param projectRoot - Root directory of the project
- */
-export declare function doctorCommand(projectRoot: string, options?: DoctorOptions): Promise<DoctorResult>;
-/** Registers the doctor command on the CLI program. */
-export declare function registerDoctor(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/download.d.ts

@@ -1,11 +0,0 @@
-import { Command } from 'commander';
-import type { CommandContext } from '../types/cli.js';
-import type { DownloadOptions } from '../types/commands/index.js';
-/**
- * Runs the download command.
- * @param projectRoot - Root directory of the project
- * @param options - Download options
- */
-export declare function downloadCommand(projectRoot: string, options: DownloadOptions): Promise<void>;
-/** Registers the download command on the CLI program. */
-export declare function registerDownload(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/export-adopt-check.d.ts

@@ -1,37 +0,0 @@
-/**
- * The advice an export placement refusal appends for new files: "register
- * first" when a new system module only lacks its moz.build line, and
- * adopt-then-split for a real moved-code block, but only after checking
- * that the adopt itself would pass.
- *
- * The moved-code heuristic alone is not enough: it can advise adopting
- * several new modules into an existing patch when the only error is the
- * missing registration, and the adopt then refuses a module for importing
- * later patches, or without it breaches the source patch's hard size limit.
- * Split out of export-flow.ts for the line budget.
- */
-import { type PatchQueueContext } from '../core/patch-lint.js';
-import type { PatchLintIssue } from '../types/commands/index.js';
-/**
- * Why adopting `diff` into `sourceFilename` would itself be refused: the
- * forward imports the adopted files would give the source patch, and the
- * source patch's hard size limit. Empty when the adopt is clean.
- *
- * @param baseCtx - The current queue
- * @param sourceFilename - The patch the adopt would grow
- * @param diff - The pending export's diff
- */
-export declare function findAdoptBlockers(baseCtx: PatchQueueContext, sourceFilename: string, diff: string): string[];
-/**
- * Detail lines for a placement refusal: register-first and moved-code
- * advice, each only when the projection supports it.
- *
- * @param baseCtx - The current queue
- * @param diff - The pending export's diff
- * @param projectedIssues - Error findings of the placement projection
- * @param plan - The placement's new filename and order
- */
-export declare function describePlacementAdvice(baseCtx: PatchQueueContext, diff: string, projectedIssues: readonly PatchLintIssue[], plan: {
-    newFilename: string;
-    insertionOrder: number;
-}): string[];

package/dist/src/commands/export-adopt-check.js

@@ -1,97 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * The advice an export placement refusal appends for new files: "register
- * first" when a new system module only lacks its moz.build line, and
- * adopt-then-split for a real moved-code block, but only after checking
- * that the adopt itself would pass.
- *
- * The moved-code heuristic alone is not enough: it can advise adopting
- * several new modules into an existing patch when the only error is the
- * missing registration, and the adopt then refuses a module for importing
- * later patches, or without it breaches the source patch's hard size limit.
- * Split out of export-flow.ts for the line budget.
- */
-import { detectMovedCodeOverlaps, formatMovedCodeAdvice } from '../core/export-moved-code-shape.js';
-import { countNonBinaryDiffLines, getPatchSizeThresholds, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
-import { computeProjectedLintRegressions } from '../core/patch-lint-projection.js';
-import { projectEntryBody } from './patch/entry-projection.js';
-/**
- * Why adopting `diff` into `sourceFilename` would itself be refused: the
- * forward imports the adopted files would give the source patch, and the
- * source patch's hard size limit. Empty when the adopt is clean.
- *
- * @param baseCtx - The current queue
- * @param sourceFilename - The patch the adopt would grow
- * @param diff - The pending export's diff
- */
-export function findAdoptBlockers(baseCtx, sourceFilename, diff) {
-    const source = baseCtx.entries.find((entry) => entry.filename === sourceFilename);
-    if (source === undefined)
-        return [];
-    const blockers = [];
-    const pending = projectEntryBody(diff);
-    const adopted = {
-        ...source,
-        diff: `${source.diff}\n${diff}`,
-        newFiles: new Map([...source.newFiles, ...pending.newFiles]),
-        createdFiles: new Set([...source.createdFiles, ...pending.createdFiles]),
-        modifiedFileAdditions: new Map([
-            ...source.modifiedFileAdditions,
-            ...pending.modifiedFileAdditions,
-        ]),
-    };
-    const isError = (issue) => issue.severity === 'error';
-    const baseline = lintPatchQueue(baseCtx).filter(isError);
-    const projected = lintPatchQueue({
-        ...baseCtx,
-        entries: baseCtx.entries.map((entry) => (entry.filename === sourceFilename ? adopted : entry)),
-    }).filter(isError);
-    for (const issue of computeProjectedLintRegressions(baseline, projected)) {
-        if (issue.check !== 'forward-import' || !issue.patches?.includes(sourceFilename))
-            continue;
-        for (const declaration of issue.stagedDeclarations ?? []) {
-            blockers.push(`${declaration.file} imports "${declaration.specifier ?? ''}", created by ` +
-                `${declaration.owner}, which applies after ${sourceFilename} (forward-import)`);
-        }
-    }
-    if (!(source.metadata?.lintIgnore ?? []).includes('large-patch-lines')) {
-        const tier = resolvePatchSizeTier([...(source.metadata?.filesAffected ?? []), ...pending.newFiles.keys()], source.metadata?.tier);
-        const limit = getPatchSizeThresholds(tier.tier).lines.error;
-        const lines = countNonBinaryDiffLines(source.diff).textLines + countNonBinaryDiffLines(diff).textLines;
-        if (lines > limit) {
-            blockers.push(`${sourceFilename} would grow to about ${lines} lines, over its ${tier.tier} hard limit ` +
-                `of ${limit} (large-patch-lines)`);
-        }
-    }
-    return blockers;
-}
-/**
- * Detail lines for a placement refusal: register-first and moved-code
- * advice, each only when the projection supports it.
- *
- * @param baseCtx - The current queue
- * @param diff - The pending export's diff
- * @param projectedIssues - Error findings of the placement projection
- * @param plan - The placement's new filename and order
- */
-export function describePlacementAdvice(baseCtx, diff, projectedIssues, plan) {
-    const newFiles = projectEntryBody(diff).newFiles;
-    const exported = projectedIssues.filter((issue) => issue.patches?.includes(plan.newFilename) ?? issue.message.includes(plan.newFilename));
-    const unregisteredModules = [
-        ...new Set(exported
-            .filter((issue) => issue.check === 'unregistered-system-module' && newFiles.has(issue.file))
-            .map((issue) => issue.file)),
-    ];
-    const registrationResolvesAll = unregisteredModules.length > 0 &&
-        exported.every((issue) => issue.check === 'unregistered-system-module');
-    const overlaps = registrationResolvesAll ? [] : detectMovedCodeOverlaps(diff, baseCtx.entries);
-    const strongest = overlaps[0];
-    return formatMovedCodeAdvice({
-        overlaps,
-        newPatchName: plan.newFilename,
-        insertionOrder: plan.insertionOrder,
-        unregisteredModules,
-        registrationResolvesAll,
-        adoptBlockers: strongest !== undefined ? findAdoptBlockers(baseCtx, strongest.sourcePatch, diff) : [],
-    });
-}

package/dist/src/commands/export-all.d.ts

@@ -1,11 +0,0 @@
-import { Command } from 'commander';
-import type { CommandContext } from '../types/cli.js';
-import type { ExportOptions } from '../types/commands/index.js';
-/**
- * Runs the export-all command to export all changes as a patch.
- * @param projectRoot - Root directory of the project
- * @param options - Export options
- */
-export declare function exportAllCommand(projectRoot: string, options?: ExportOptions): Promise<void>;
-/** Registers the export-all command on the CLI program. */
-export declare function registerExportAll(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;