@hominis/fireforge 0.47.0 → 0.48.0

package/dist/src/core/patch-lint-forward-registration.js

@@ -11,17 +11,20 @@
  * removing the declaration produced identical silence, so the gap was
  * invisible rather than merely absent.
  *
- * Scope is narrow on purpose: test-manifest `support-files` only. A
- * jar.mn packaging line or an actor/customElements registration names its
- * target through indirection the linter cannot resolve without the build
- * system, and a rule that guesses there would refuse correct queues on a
- * Firefox-sized tree. The staged-registration declaration remains the
- * documented escape hatch for a deliberate stage.
+ * Scope is narrow by default: test-manifest `support-files` only. The
+ * carriers whose target resolves without the build system (jar.mn pair
+ * lines, moz.build path tokens, test-manifest sections, customElements.js
+ * chrome URLs) are opt-in through `patchLint.forwardRegistration:
+ * "extended"` (see `patch-lint-forward-registration-extended.ts`), since a
+ * queue that predates them can carry such edges on a ratchet and a new
+ * error on install would red its gate. The staged-registration declaration
+ * remains the documented escape hatch for a deliberate stage.
  */
 import { basename, dirname, posix } from 'node:path';
 import { normalizePathSlashes } from '../utils/paths.js';
 import { escapeRegex } from '../utils/regex.js';
-import { isLaterOwner, quoteRegistrationLine } from './patch-lint-staged-registration.js';
+import { findExtendedForwardRegistrations, formatRegistrationDeclaration, } from './patch-lint-forward-registration-extended.js';
+import { isLaterOwner } from './patch-lint-staged-registration.js';
 /**
  * Manifest basenames whose `support-files` key registers auxiliary files
  * for a test suite. Closed and documented on purpose: a pattern like
@@ -142,15 +145,15 @@ function isDeclared(entry, manifestPath, createdPath) {
         normalizePathSlashes(registration.creates) === normalizePathSlashes(createdPath));
 }
 /**
- * Flags every `support-files` registration a patch introduces that names a
+ * Finds every `support-files` registration a patch introduces that names a
  * file only a later-ordered patch creates, unless the staged dependency is
  * declared.
  *
  * @param ctx - Projected queue in application order
- * @returns One issue per undeclared forward registration
+ * @returns One record per (patch, manifest, entry, created file)
  */
-export function lintPatchQueueForwardRegistrations(ctx) {
-    const issues = [];
+function findSupportFileForwardRegistrations(ctx) {
+    const found = [];
     for (const entry of ctx.entries) {
         // Both arms: a manifest this patch creates and one it modifies can each
         // introduce a registration line.
@@ -163,17 +166,6 @@ export function lintPatchQueueForwardRegistrations(ctx) {
                 const matches = buildSupportFileMatcher(manifestPath, raw);
                 if (matches === undefined)
                     continue;
-                // `--line` is the line as the patch adds it, which is what the
-                // declared arm compares and what `--remove` matches on. Synthesising
-                // `support-files = ["<entry>"]` instead only ever matched a
-                // single-line single-entry array, so the pasted command left the
-                // declaring patch red with staged-dependency-unused.
-                const declaredLine = quoteRegistrationLine(addedLine);
-                const ambiguity = occurrences > 1
-                    ? ` (the entry is spelled out on ${occurrences} added lines here; ` +
-                        'the first is quoted, and one declaration covers the file either way ' +
-                        'because the declared check keys on --file and --creates.)'
-                    : '';
                 for (const later of ctx.entries) {
                     // Same predicate the declared-registration arm validates against,
                     // tiebreak included: two spellings of "later" would let one rule
@@ -185,26 +177,80 @@ export function lintPatchQueueForwardRegistrations(ctx) {
                             continue;
                         if (isDeclared(entry, manifestPath, created))
                             continue;
-                        issues.push({
+                        found.push({
+                            patch: entry.filename,
+                            kind: 'support-files',
                             file: manifestPath,
-                            check: 'forward-registration',
-                            patches: [entry.filename],
-                            fingerprint: `forward-registration|${entry.filename}|${manifestPath}|${raw}|${created}|${later.filename}`,
-                            message: `${manifestPath} in ${entry.filename} registers "${raw}" as a support file, ` +
-                                `but ${created} is created by the later patch ${later.filename}. ` +
-                                'Applying the queue up to this patch leaves the registration dangling. ' +
-                                'Reorder the patches so the file is created first, move the registration into ' +
-                                'the later patch, or declare the intentional staged dependency with: ' +
-                                `fireforge patch staged-dependency ${entry.filename} --add --kind registration ` +
-                                `--file ${manifestPath} --line "${declaredLine}" ` +
-                                `--creates ${created} --owner ${later.filename}` +
-                                ambiguity,
-                            severity: 'error',
+                            // `--line` is the line as the patch adds it, which is what the
+                            // declared arm compares and what `--remove` matches on.
+                            // Synthesising `support-files = ["<entry>"]` instead only ever
+                            // matched a single-line single-entry array, so the pasted
+                            // command left the declaring patch red with
+                            // staged-dependency-unused.
+                            line: addedLine,
+                            token: raw,
+                            creates: created,
+                            owner: later.filename,
+                            occurrences,
+                            command: formatRegistrationDeclaration(entry.filename, manifestPath, addedLine, created, later.filename),
                         });
                     }
                 }
             }
         }
     }
-    return issues;
+    return found;
+}
+/**
+ * Every undeclared forward registration in the queue, over the carriers
+ * `scope` selects: `support-files` (the default) or `extended` (adds
+ * jar.mn, moz.build, test-manifest sections and customElements.js; see
+ * `patch-lint-forward-registration-extended.ts`).
+ *
+ * @param ctx - Queue in application order
+ * @param scope - Which carriers to check
+ */
+export function collectForwardRegistrations(ctx, scope = 'support-files') {
+    const found = findSupportFileForwardRegistrations(ctx);
+    if (scope === 'extended')
+        found.push(...findExtendedForwardRegistrations(ctx));
+    return found;
+}
+const KIND_PHRASES = {
+    'support-files': 'as a support file',
+    'jar-mn': 'for packaging',
+    'moz-build': 'in the build',
+    'test-manifest': 'as a test',
+    'custom-elements': 'as a custom element',
+};
+/**
+ * Flags every forward registration the queue's scope selects, unless the
+ * staged dependency is declared.
+ *
+ * @param ctx - Projected queue in application order, with its
+ *   `forwardRegistration` scope (default `support-files`)
+ * @returns One issue per undeclared forward registration
+ */
+export function lintPatchQueueForwardRegistrations(ctx) {
+    return collectForwardRegistrations(ctx, ctx.forwardRegistration).map((found) => {
+        const ambiguity = found.occurrences > 1
+            ? ` (the entry is spelled out on ${found.occurrences} added lines here; ` +
+                'the first is quoted, and one declaration covers the file either way ' +
+                'because the declared check keys on --file and --creates.)'
+            : '';
+        return {
+            file: found.file,
+            check: 'forward-registration',
+            patches: [found.patch],
+            fingerprint: `forward-registration|${found.patch}|${found.file}|${found.token}|${found.creates}|${found.owner}`,
+            message: `${found.file} in ${found.patch} registers "${found.token}" ${KIND_PHRASES[found.kind]}, ` +
+                `but ${found.creates} is created by the later patch ${found.owner}. ` +
+                'Applying the queue up to this patch leaves the registration dangling. ' +
+                'Reorder the patches so the file is created first, move the registration into ' +
+                'the later patch, or declare the intentional staged dependency with: ' +
+                found.command +
+                ambiguity,
+            severity: 'error',
+        };
+    });
 }

package/dist/src/core/patch-lint.d.ts

@@ -25,6 +25,17 @@ export declare function countNonBinaryDiffLines(diffContent: string): {
     total: number;
     textLines: number;
 };
+/**
+ * The files the `file-too-large` rule measures for a patch: the JS files
+ * (`.js`, `.mjs`, `.sys.mjs`, …) the patch creates. A modified file is
+ * never measured, and neither is a new file of another kind (CSS, FTL,
+ * markup), however long. This is the rule's own predicate, not a mirror
+ * of it: the rule selects its files through the same function.
+ *
+ * @param patchText - Unified-diff body of one patch
+ * @returns Engine-relative paths the rule would size-check
+ */
+export declare function filesMeasuredByFileTooLarge(patchText: string): Set<string>;
 /**
  * Returns true if the file path looks like a test file.
  * Matches paths containing `/test/` or filenames starting with

package/dist/src/core/patch-lint.js

@@ -189,6 +189,23 @@ function isBrandingOnlyPatch(files) {
 function isJsFile(file) {
     return JS_EXTENSIONS.some((ext) => file.endsWith(ext));
 }
+/** The subset of a patch's new files that `file-too-large` measures. */
+function measuredByFileTooLarge(newFiles) {
+    return new Set([...newFiles].filter(isJsFile));
+}
+/**
+ * The files the `file-too-large` rule measures for a patch: the JS files
+ * (`.js`, `.mjs`, `.sys.mjs`, …) the patch creates. A modified file is
+ * never measured, and neither is a new file of another kind (CSS, FTL,
+ * markup), however long. This is the rule's own predicate, not a mirror
+ * of it: the rule selects its files through the same function.
+ *
+ * @param patchText - Unified-diff body of one patch
+ * @returns Engine-relative paths the rule would size-check
+ */
+export function filesMeasuredByFileTooLarge(patchText) {
+    return measuredByFileTooLarge(detectNewFilesInDiff(patchText));
+}
 /**
  * Returns true if the file path looks like a test file.
  * Matches paths containing `/test/` or filenames starting with
@@ -387,6 +404,7 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
         return [];
     const issues = [];
     const binaryName = config.binaryName.toLowerCase();
+    const sizeMeasured = measuredByFileTooLarge(newFiles);
     for (const file of jsFiles) {
         const filePath = join(repoDir, file);
         if (!(await pathExists(filePath)))
@@ -404,8 +422,8 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
                 severity: 'error',
             });
         }
-        // 2. File size check (new files only)
-        if (isNew) {
+        // 2. File size check (new JS files only; see filesMeasuredByFileTooLarge)
+        if (sizeMeasured.has(file)) {
             const lineCount = countContentLines(content);
             const isTest = isTestFile(file);
             const thresholds = resolveFileSizeThresholds(config.patchLint?.fileSizeThresholds, isTest);

package/dist/src/core/patch-transform.d.ts

@@ -4,10 +4,8 @@
  */
 /**
  * Extracts the complete file content from a "new file" patch given a raw
- * diff string already in memory. Callers with a patch file path should
- * prefer {@link extractNewFileContent}. This helper exists for code paths
- * that already hold the diff (e.g. the in-flight export planner) and do
- * not want to round-trip through the filesystem.
+ * diff string already in memory. A caller with only a patch file path
+ * reads it first; every caller holds the diff already.
  *
  * @param diff - Raw unified-diff content
  * @param targetFile - Optional target file to scope extraction to
@@ -18,6 +16,18 @@
  *   binary new-file conflicts as unresolvable rather than auto-resolving.
  */
 export declare function extractNewFileContentFromDiff(diff: string, targetFile?: string): string;
+/**
+ * {@link extractNewFileContentFromDiff} for many targets over one parse of
+ * the diff. Each target gets exactly what the single-target call returns;
+ * a target whose sections include a binary one (which that call refuses)
+ * is left out of the map and named in `refused`.
+ * @param diff - Raw unified-diff content
+ * @param targetFiles - Files whose created content to extract
+ */
+export declare function extractNewFileContentsFromDiff(diff: string, targetFiles: Iterable<string>): {
+    contents: Map<string, string>;
+    refused: string[];
+};
 /**
  * Projects every text new file a diff creates into a path → content map, for
  * the cross-patch lint projections that build a synthetic patch-queue entry.
@@ -39,15 +49,6 @@ export declare function extractNewFileContentFromDiff(diff: string, targetFile?:
  * call sites previously did.
  */
 export declare function buildNewFileTextProjection(diff: string): Map<string, string>;
-/**
- * Extracts the complete file content from a "new file" patch.
- * When targetFile is provided, only extracts content for that file
- * (required for multi-file patches).
- * @param patchPath - Path to the patch file
- * @param targetFile - Optional target file to scope extraction to
- * @returns The file content that the patch would create
- */
-export declare function extractNewFileContent(patchPath: string, targetFile?: string): Promise<string>;
 /**
  * Applies an already-read patch body to content. Batched callers that hold
  * many (patch, file) pairs use this to read each patch body once instead of

package/dist/src/core/patch-transform.js

@@ -4,14 +4,11 @@
  * These operate on file content strings without filesystem side effects.
  */
 import { PatchError } from '../errors/patch.js';
-import { readText } from '../utils/fs.js';
 import { isNewFileInPatch, parseDiffSections, parseHunksForFile } from './patch-parse.js';
 /**
  * Extracts the complete file content from a "new file" patch given a raw
- * diff string already in memory. Callers with a patch file path should
- * prefer {@link extractNewFileContent}. This helper exists for code paths
- * that already hold the diff (e.g. the in-flight export planner) and do
- * not want to round-trip through the filesystem.
+ * diff string already in memory. A caller with only a patch file path
+ * reads it first; every caller holds the diff already.
  *
  * @param diff - Raw unified-diff content
  * @param targetFile - Optional target file to scope extraction to
@@ -29,6 +26,33 @@ export function extractNewFileContentFromDiff(diff, targetFile) {
     }
     return contentFromSections(sections);
 }
+/**
+ * {@link extractNewFileContentFromDiff} for many targets over one parse of
+ * the diff. Each target gets exactly what the single-target call returns;
+ * a target whose sections include a binary one (which that call refuses)
+ * is left out of the map and named in `refused`.
+ * @param diff - Raw unified-diff content
+ * @param targetFiles - Files whose created content to extract
+ */
+export function extractNewFileContentsFromDiff(diff, targetFiles) {
+    const sectionsByTarget = new Map();
+    for (const section of parseDiffSections(diff)) {
+        const list = sectionsByTarget.get(section.targetPath) ?? [];
+        list.push(section);
+        sectionsByTarget.set(section.targetPath, list);
+    }
+    const contents = new Map();
+    const refused = [];
+    for (const target of targetFiles) {
+        const sections = sectionsByTarget.get(target) ?? [];
+        if (sections.some((section) => section.isBinary)) {
+            refused.push(target);
+            continue;
+        }
+        contents.set(target, contentFromSections(sections));
+    }
+    return { contents, refused };
+}
 /**
  * Walks the added (`+`) lines of already-parsed sections into file content.
  * Shared by {@link extractNewFileContentFromDiff} and
@@ -89,18 +113,6 @@ export function buildNewFileTextProjection(diff) {
     }
     return newFiles;
 }
-/**
- * Extracts the complete file content from a "new file" patch.
- * When targetFile is provided, only extracts content for that file
- * (required for multi-file patches).
- * @param patchPath - Path to the patch file
- * @param targetFile - Optional target file to scope extraction to
- * @returns The file content that the patch would create
- */
-export async function extractNewFileContent(patchPath, targetFile) {
-    const content = await readText(patchPath);
-    return extractNewFileContentFromDiff(content, targetFile);
-}
 /**
  * Applies an already-read patch body to content. Batched callers that hold
  * many (patch, file) pairs use this to read each patch body once instead of

package/dist/src/core/rebase-dry-run.d.ts

@@ -0,0 +1,48 @@
+/** A patch to replay, in queue order. */
+export interface DryRunPatch {
+    filename: string;
+    path: string;
+}
+/** What the real rebase loop would do with one patch. */
+export type DryRunVerdict = {
+    filename: string;
+    outcome: 'clean';
+} | {
+    filename: string;
+    outcome: 'reduced-context';
+    step: number;
+    contextArg: string;
+} | {
+    filename: string;
+    outcome: 'reject';
+    /** Files git named as not applying. Empty when stderr named none. */
+    files: string[];
+    /** git's own explanation, from the exact-context `--check`. */
+    detail: string;
+};
+/** Result of a full queue replay. */
+export interface DryRunReplay {
+    verdicts: DryRunVerdict[];
+    /**
+     * Index of the first reject, or `undefined`. Verdicts after it were
+     * computed without that patch applied, so a reject there may cascade from
+     * the earlier one rather than be a conflict of its own.
+     */
+    firstRejectIndex: number | undefined;
+}
+/**
+ * Parses the file names out of `git apply --check` failure output. Git
+ * reports a context mismatch as `error: patch failed: <file>:<line>` and
+ * `error: <file>: patch does not apply`, and a missing or pre-existing
+ * target as `error: <file>: does not exist in index` /
+ * `error: <file>: already exists in index`.
+ */
+export declare function parseApplyCheckFailures(stderr: string): string[];
+/**
+ * Replays `patches` onto the engine's HEAD tree in a private index.
+ * @param engineDir - Engine repository root
+ * @param patches - Patches in queue order
+ * @param maxFuzz - Maximum context-reduction steps, as for the real rebase
+ * @returns One verdict per patch
+ */
+export declare function replayQueueIndexOnly(engineDir: string, patches: readonly DryRunPatch[], maxFuzz: number): Promise<DryRunReplay>;

package/dist/src/core/rebase-dry-run.js

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `rebase --dry-run`: replays the patch queue against the engine's base
+ * commit without touching `engine/`.
+ *
+ * The replay runs on a private index seeded from HEAD (`GIT_INDEX_FILE`
+ * plus `git read-tree HEAD`) and applies each patch there with
+ * `git apply --cached`, in queue order, so a later patch sees what the
+ * earlier ones did, exactly as the real loop's worktree does. Each patch
+ * walks the same context-reduction ladder as {@link applyPatchWithFuzz}.
+ * The worktree and the real index are never written. The private index is
+ * deleted when the replay ends.
+ */
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { GitError } from '../errors/git.js';
+import { exec } from '../utils/process.js';
+import { ensureGit } from './git-base.js';
+import { assertValidMaxFuzz, contextReductionSteps } from './patch-apply-fuzz.js';
+/**
+ * Parses the file names out of `git apply --check` failure output. Git
+ * reports a context mismatch as `error: patch failed: <file>:<line>` and
+ * `error: <file>: patch does not apply`, and a missing or pre-existing
+ * target as `error: <file>: does not exist in index` /
+ * `error: <file>: already exists in index`.
+ */
+export function parseApplyCheckFailures(stderr) {
+    const files = new Set();
+    for (const line of stderr.split('\n')) {
+        const failed = /^error: patch failed: (.+):\d+$/.exec(line);
+        if (failed?.[1]) {
+            files.add(failed[1]);
+            continue;
+        }
+        const named = /^error: (.+?): (?:patch does not apply|does not exist in index|already exists in index)$/.exec(line);
+        if (named?.[1])
+            files.add(named[1]);
+    }
+    return [...files];
+}
+/**
+ * Replays `patches` onto the engine's HEAD tree in a private index.
+ * @param engineDir - Engine repository root
+ * @param patches - Patches in queue order
+ * @param maxFuzz - Maximum context-reduction steps, as for the real rebase
+ * @returns One verdict per patch
+ */
+export async function replayQueueIndexOnly(engineDir, patches, maxFuzz) {
+    assertValidMaxFuzz(maxFuzz);
+    await ensureGit();
+    const scratch = await mkdtemp(join(tmpdir(), 'fireforge-rebase-dry-run-'));
+    const env = { GIT_INDEX_FILE: join(scratch, 'index') };
+    try {
+        const seeded = await exec('git', ['read-tree', 'HEAD'], { cwd: engineDir, env });
+        if (seeded.exitCode !== 0) {
+            throw new GitError(seeded.stderr.trim() || 'Could not seed a private index from HEAD', 'read-tree HEAD');
+        }
+        const ladder = contextReductionSteps(maxFuzz);
+        const verdicts = [];
+        let firstRejectIndex;
+        for (const patch of patches) {
+            let verdict;
+            let exactFailure = '';
+            for (const [step, contextArgs] of ladder.entries()) {
+                const check = await exec('git', ['apply', '--cached', '--check', ...contextArgs, '--', patch.path], { cwd: engineDir, env });
+                if (check.exitCode !== 0) {
+                    if (step === 0)
+                        exactFailure = check.stderr;
+                    continue;
+                }
+                const apply = await exec('git', ['apply', '--cached', ...contextArgs, '--', patch.path], {
+                    cwd: engineDir,
+                    env,
+                });
+                if (apply.exitCode !== 0)
+                    continue;
+                verdict =
+                    step === 0
+                        ? { filename: patch.filename, outcome: 'clean' }
+                        : {
+                            filename: patch.filename,
+                            outcome: 'reduced-context',
+                            step,
+                            contextArg: contextArgs[0] ?? '',
+                        };
+                break;
+            }
+            if (verdict === undefined) {
+                verdict = {
+                    filename: patch.filename,
+                    outcome: 'reject',
+                    files: parseApplyCheckFailures(exactFailure),
+                    detail: exactFailure.trim(),
+                };
+                firstRejectIndex ??= verdicts.length;
+            }
+            verdicts.push(verdict);
+        }
+        return { verdicts, firstRejectIndex };
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}

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

@@ -0,0 +1,50 @@
+/** Directory-name prefix of every FireForge-owned temporary run profile. */
+export declare const RUN_PROFILE_PREFIX = "fireforge-run-profile-";
+/** The profile a run launches with, and how to release it afterwards. */
+export interface RunProfile {
+    /** Program parameters to append to `mach run` (empty for mach's default). */
+    args: string[];
+    /** Absolute profile directory, when one was chosen. */
+    dir?: string;
+    /** Whether FireForge created the directory and will delete it. */
+    temporary: boolean;
+    /** Removes a temporary profile. A no-op otherwise. Never throws. */
+    dispose: () => Promise<void>;
+}
+/** Inputs to {@link resolveRunProfile}. */
+export interface RunProfileRequest {
+    /** `--profile <path>`: launch with this directory, left in place. */
+    profile?: string | undefined;
+    /** `--temp-profile`: launch with a fresh directory removed afterwards. */
+    tempProfile?: boolean | undefined;
+    /**
+     * Whether this is a `--smoke-exit` run. A smoke run with neither flag gets
+     * a temporary profile: the step exists to prove what the build does on a
+     * clean start, and the developer's profile-default carries whatever state
+     * the last session left.
+     */
+    smoke: boolean;
+    /** Base directory for temporary profiles (defaults to the OS tmpdir). */
+    tempRoot?: string | undefined;
+}
+/**
+ * Removes every temporary run profile this process still holds. Called by
+ * the CLI entry point's signal handler after child shutdown. Never throws.
+ */
+export declare function removeActiveRunProfiles(): Promise<void>;
+/**
+ * Chooses the profile for a run.
+ * @param request - The run's profile flags
+ * @returns The profile arguments and their release handle
+ */
+export declare function resolveRunProfile(request: RunProfileRequest): Promise<RunProfile>;
+/**
+ * Removes temporary run profiles whose owning FireForge process is gone.
+ * The `finally` that releases a profile covers a clean exit, a failed run
+ * and a forwarded SIGINT/SIGTERM, but not a SIGKILL of FireForge itself;
+ * this sweep is the backstop for that case. A directory whose marker is
+ * missing or unreadable is left alone: nothing proves it is abandoned.
+ * @param tempRoot - Base directory to sweep (defaults to the OS tmpdir)
+ * @returns The number of directories removed
+ */
+export declare function sweepAbandonedRunProfiles(tempRoot?: string): Promise<number>;