@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/core/module-resolution-preflight.js

@@ -19,12 +19,19 @@
  * no owned file is an upstream Firefox module, which FireForge does not
  * police and cannot cheaply enumerate. Policing only what the fork owns is
  * both the actionable set and the one that produces real incidents.
+ *
+ * An unscoped `verify` widens that set with the engine worktree: changed
+ * files import, and untracked files are targets. A chrome script's lazy
+ * getter for a new, not yet exported `.sys.mjs` with no moz.build line
+ * SIGSEGVed every start of a shared objdir, and neither file was in the
+ * queue yet, so the queue-only scan could not see it.
  */
 import { dirname, join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { escapeRegex } from '../utils/regex.js';
+import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from './git-status.js';
 import { extractResourceModuleSpecifiers, moduleSourceSuffix, } from './patch-lint-module-registration.js';
 /** Extensions whose contents are scanned for resource-module imports. */
 const IMPORTABLE_EXTENSIONS = ['.mjs', '.sys.mjs', '.js', '.jsm'];
@@ -79,20 +86,31 @@ async function isRegisteredInAncestorMozBuild(engineDir, moduleRelPath, mozBuild
         dir = parent;
     }
 }
+/** Lists the engine's changed and untracked files for the worktree scan. */
+export async function collectWorktreeModuleFiles(engineDir) {
+    const entries = await expandUntrackedDirectoryEntries(engineDir, await getWorkingTreeStatus(engineDir));
+    const present = entries.filter((entry) => entry.worktreeStatus !== 'D');
+    return {
+        changed: present.map((entry) => entry.file),
+        untracked: present.filter((entry) => entry.status === '??').map((entry) => entry.file),
+    };
+}
 /**
  * Resolves every `resource://` system-module import made by the
- * queue-owned files and reports the ones a packaged browser could not
- * load.
+ * queue-owned files (and, given `worktree`, by changed engine files) and
+ * reports the ones a packaged browser could not load.
  *
  * @param engineDir - Path to the engine checkout
  * @param ownedFiles - Engine-relative paths the patch queue owns
+ * @param worktree - Changed and untracked engine files to judge as well
  * @returns Findings sorted by module path. Empty when everything resolves
  */
-export async function findUnresolvedSystemModuleImports(engineDir, ownedFiles) {
-    const owned = [...new Set(ownedFiles)];
-    /** specifier → importing owned files. */
+export async function findUnresolvedSystemModuleImports(engineDir, ownedFiles, worktree) {
+    const owned = [...new Set([...ownedFiles, ...(worktree?.untracked ?? [])])];
+    const importing = [...new Set([...owned, ...(worktree?.changed ?? [])])];
+    /** specifier → importing files. */
     const importersBySpecifier = new Map();
-    for (const file of owned) {
+    for (const file of importing) {
         if (!IMPORTABLE_EXTENSIONS.some((extension) => file.endsWith(extension)))
             continue;
         const content = await readIfPresent(join(engineDir, file));

package/dist/src/core/negative-control-compiled.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Which negative-control targets only a build can deliver.
+ *
+ * A control is applied after the pre-test build and right before dispatch,
+ * which is right for a file the runtime reads from the source tree or the
+ * objdir links to. A C++ (or Rust, IDL, …) source edited at that point is
+ * never compiled: the run tests the unmutated binary and reports
+ * `control=missed`, which reads as a test that cannot fail. Such a target
+ * is now refused without `--build`, and with `--build` the control is
+ * applied before the build so the binary under test carries it.
+ */
+/**
+ * The engine-relative targets that reach the runtime only through a
+ * compile: a compiled-source extension and no install-manifest entry that
+ * ships the file itself.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param enginePaths - The control's engine-relative targets
+ */
+export declare function findCompiledControlTargets(engineDir: string, enginePaths: readonly string[]): Promise<string[]>;
+/**
+ * The refusal for a compiled control without `--build`, naming the manual
+ * procedure for a run that wants to keep its build out of FireForge.
+ *
+ * @param compiled - Engine-relative compiled targets
+ */
+export declare function formatCompiledControlRefusal(compiled: readonly string[]): string;

package/dist/src/core/negative-control-compiled.js

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Which negative-control targets only a build can deliver.
+ *
+ * A control is applied after the pre-test build and right before dispatch,
+ * which is right for a file the runtime reads from the source tree or the
+ * objdir links to. A C++ (or Rust, IDL, …) source edited at that point is
+ * never compiled: the run tests the unmutated binary and reports
+ * `control=missed`, which reads as a test that cannot fail. Such a target
+ * is now refused without `--build`, and with `--build` the control is
+ * applied before the build so the binary under test carries it.
+ */
+import { extname } from 'node:path';
+import { classifyRuntimeDelivery } from './objdir-install-manifests.js';
+import { loadEngineInstallIndex } from './test-stale-exempt.js';
+/** Extensions of sources the build compiles or code-generates into the binary. */
+const COMPILED_EXTENSIONS = new Set([
+    '.c',
+    '.cc',
+    '.cpp',
+    '.cxx',
+    '.h',
+    '.hh',
+    '.hpp',
+    '.m',
+    '.mm',
+    '.rs',
+    '.idl',
+    '.webidl',
+    '.ipdl',
+    '.ipdlh',
+    '.yaml',
+    '.yml',
+]);
+/**
+ * The engine-relative targets that reach the runtime only through a
+ * compile: a compiled-source extension and no install-manifest entry that
+ * ships the file itself.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param enginePaths - The control's engine-relative targets
+ */
+export async function findCompiledControlTargets(engineDir, enginePaths) {
+    const candidates = enginePaths.filter((path) => COMPILED_EXTENSIONS.has(extname(path)));
+    if (candidates.length === 0)
+        return [];
+    const index = await loadEngineInstallIndex(engineDir);
+    if (index === undefined)
+        return candidates;
+    const compiled = [];
+    for (const path of candidates) {
+        if ((await classifyRuntimeDelivery(index, engineDir, path)) === 'unlisted') {
+            compiled.push(path);
+        }
+    }
+    return compiled;
+}
+/**
+ * The refusal for a compiled control without `--build`, naming the manual
+ * procedure for a run that wants to keep its build out of FireForge.
+ *
+ * @param compiled - Engine-relative compiled targets
+ */
+export function formatCompiledControlRefusal(compiled) {
+    const files = compiled.map((path) => `engine/${path}`).join(', ');
+    return (`This negative control edits compiled source (${files}). Applied right before dispatch, ` +
+        'it would never be compiled: the run would test the unmutated binary and report ' +
+        'control=missed. Add --build: the control is then applied before the pre-test build, so ' +
+        'the binary under test carries it, and restored afterwards with a fresh mtime so the next ' +
+        'build recompiles the original. To run it by hand instead: copy the mutated file in, ' +
+        '`touch` it, `fireforge build`, `fireforge test`, restore the file byte-exact, `touch` it ' +
+        'again and rebuild.');
+}

package/dist/src/core/negative-control-diff.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Parsing and strict application of a `fireforge test --negative-control`
+ * diff.
+ *
+ * A control is a reviewed mutation, so the applier is deliberately strict:
+ * every context and removed line must match exactly, the only tolerance is
+ * a line offset (the same one `git apply` allows, never fuzz), and a hunk
+ * that does not apply refuses the whole control before any file is
+ * written. Only plain text modifications of existing files are accepted: a
+ * created, deleted, renamed or binary file has no byte-exact restore story
+ * that is worth its risk for a neuter.
+ */
+import { type ParsedHunk } from './patch-parse.js';
+/** One file of a control diff. */
+export interface ControlDiffFile {
+    /** The path the diff names, without git's `a/`/`b/` prefix. */
+    path: string;
+    /** The hunks to apply, in file order. */
+    hunks: ParsedHunk[];
+}
+/** Options for {@link parseControlDiff}. */
+export interface ParseControlDiffOptions {
+    /**
+     * Called for a section whose old and new paths differ. Returns the path
+     * the control targets (a `git diff --no-index <file> <edited copy>` names
+     * the copy on its new side), or undefined for a real rename, which is
+     * refused.
+     */
+    resolveRename?: (sourcePath: string, targetPath: string) => string | undefined;
+}
+/**
+ * Parses a control diff. Accepts `git diff` output (a `diff --git` header
+ * per file), which is what `git -C engine diff -- <file>` or a project-root
+ * `git diff` writes, a plain unified diff (`diff -u`), and, through
+ * `resolveRename`, a `git diff --no-index` against an edited copy.
+ *
+ * @param content - The diff file's text
+ * @param options - See {@link ParseControlDiffOptions}
+ * @returns One entry per file, in diff order
+ */
+export declare function parseControlDiff(content: string, options?: ParseControlDiffOptions): ControlDiffFile[];
+/**
+ * Applies `hunks` to `original`, strictly.
+ *
+ * @param original - The file's current text
+ * @param hunks - Hunks parsed from the control diff
+ * @param label - File label for refusal messages
+ * @returns The mutated text
+ * @throws GeneralError when any hunk does not apply
+ */
+export declare function applyControlHunks(original: string, hunks: readonly ParsedHunk[], label: string): string;

package/dist/src/core/negative-control-diff.js

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Parsing and strict application of a `fireforge test --negative-control`
+ * diff.
+ *
+ * A control is a reviewed mutation, so the applier is deliberately strict:
+ * every context and removed line must match exactly, the only tolerance is
+ * a line offset (the same one `git apply` allows, never fuzz), and a hunk
+ * that does not apply refuses the whole control before any file is
+ * written. Only plain text modifications of existing files are accepted: a
+ * created, deleted, renamed or binary file has no byte-exact restore story
+ * that is worth its risk for a neuter.
+ */
+import { GeneralError } from '../errors/base.js';
+import { isContainedRelativePath, normalizePathSlashes } from '../utils/paths.js';
+import { parseDiffSections } from './patch-parse.js';
+function refuse(message) {
+    throw new GeneralError(`Negative control diff refused: ${message}`);
+}
+/** A `---`/`+++` file name, without a trailing timestamp or git's `a/`/`b/`. */
+function plainDiffPath(raw) {
+    const name = raw.split('\t')[0]?.trim() ?? '';
+    return name.startsWith('a/') || name.startsWith('b/') ? name.slice(2) : name;
+}
+/**
+ * Gives a plain unified diff (`diff -u`, no `diff --git` lines) the git
+ * header the section parser keys on, one per `---`/`+++` pair. A diff that
+ * already carries `diff --git` headers is returned unchanged.
+ *
+ * @param content - The diff file's text
+ */
+function withGitHeaders(content) {
+    const lines = content.split('\n');
+    if (lines.some((line) => line.startsWith('diff --git ')))
+        return content;
+    const out = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        const next = lines[index + 1] ?? '';
+        if (line.startsWith('--- ') && next.startsWith('+++ ')) {
+            const oldPath = plainDiffPath(line.slice(4));
+            const newPath = plainDiffPath(next.slice(4));
+            index += 1;
+            if (oldPath === '/dev/null' || newPath === '/dev/null') {
+                // Kept as a create/delete, which the parser below refuses by name.
+                const path = oldPath === '/dev/null' ? newPath : oldPath;
+                out.push(`diff --git a/${path} b/${path}`, oldPath === '/dev/null' ? 'new file mode 100644' : 'deleted file mode 100644', oldPath === '/dev/null' ? '--- /dev/null' : `--- a/${path}`, newPath === '/dev/null' ? '+++ /dev/null' : `+++ b/${path}`);
+                continue;
+            }
+            out.push(`diff --git a/${oldPath} b/${newPath}`, `--- a/${oldPath}`, `+++ b/${newPath}`);
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}
+/**
+ * Parses a control diff. Accepts `git diff` output (a `diff --git` header
+ * per file), which is what `git -C engine diff -- <file>` or a project-root
+ * `git diff` writes, a plain unified diff (`diff -u`), and, through
+ * `resolveRename`, a `git diff --no-index` against an edited copy.
+ *
+ * @param content - The diff file's text
+ * @param options - See {@link ParseControlDiffOptions}
+ * @returns One entry per file, in diff order
+ */
+export function parseControlDiff(content, options = {}) {
+    const sections = parseDiffSections(withGitHeaders(content));
+    if (sections.length === 0) {
+        refuse('no diff sections found. Write the control with git, e.g. ' +
+            '`git -C engine diff -- <file> > control.diff` after making the edit, then revert the edit.');
+    }
+    const seen = new Set();
+    return sections.map((section) => {
+        let path = normalizePathSlashes(section.targetPath);
+        if (section.isBinary)
+            refuse(`${path} is a binary section.`);
+        if (section.isNewFile || section.isDeletedFile) {
+            refuse(`${path} creates or deletes a file; a control may only modify existing text files.`);
+        }
+        if (section.sourcePath !== section.targetPath) {
+            const resolved = options.resolveRename?.(section.sourcePath, section.targetPath);
+            if (resolved === undefined) {
+                refuse(`${section.sourcePath} -> ${path} is a rename; a control may only modify files.`);
+            }
+            path = normalizePathSlashes(resolved);
+        }
+        if (!isContainedRelativePath(path)) {
+            refuse(`${path} is not a contained relative path.`);
+        }
+        if (section.hunks.length === 0)
+            refuse(`${path} has no hunks.`);
+        if (seen.has(path))
+            refuse(`${path} appears in more than one section.`);
+        seen.add(path);
+        return { path, hunks: section.hunks };
+    });
+}
+function hunkSides(hunk, label, index) {
+    const oldLines = [];
+    const newLines = [];
+    for (const line of hunk.lines) {
+        const body = line.slice(1);
+        if (line.startsWith(' ') || line.startsWith('-'))
+            oldLines.push(body);
+        if (line.startsWith(' ') || line.startsWith('+'))
+            newLines.push(body);
+    }
+    if (oldLines.length !== hunk.oldCount || newLines.length !== hunk.newCount) {
+        refuse(`hunk ${index + 1} of ${label} is malformed: its header counts ` +
+            `(-${hunk.oldCount} +${hunk.newCount}) do not match its body ` +
+            `(-${oldLines.length} +${newLines.length}).`);
+    }
+    return { oldLines, newLines };
+}
+function matchesAt(lines, block, position) {
+    if (position < 0 || position + block.length > lines.length)
+        return false;
+    return block.every((line, offset) => lines[position + offset] === line);
+}
+/**
+ * The position nearest `anchor`, at or after `floor`, where `block`
+ * matches, or -1.
+ */
+function findBlock(lines, block, anchor, floor) {
+    const start = Math.max(anchor, floor);
+    for (let delta = 0; delta <= lines.length; delta += 1) {
+        if (matchesAt(lines, block, start + delta))
+            return start + delta;
+        const below = anchor - delta;
+        if (delta > 0 && below >= floor && matchesAt(lines, block, below))
+            return below;
+    }
+    return -1;
+}
+/**
+ * Applies `hunks` to `original`, strictly.
+ *
+ * @param original - The file's current text
+ * @param hunks - Hunks parsed from the control diff
+ * @param label - File label for refusal messages
+ * @returns The mutated text
+ * @throws GeneralError when any hunk does not apply
+ */
+export function applyControlHunks(original, hunks, label) {
+    const hasFinalNewline = original.endsWith('\n');
+    const lines = original === '' ? [] : (hasFinalNewline ? original.slice(0, -1) : original).split('\n');
+    const result = [];
+    let cursor = 0;
+    let finalNewline = hasFinalNewline;
+    hunks.forEach((hunk, index) => {
+        const { oldLines, newLines } = hunkSides(hunk, label, index);
+        const anchor = hunk.oldCount === 0 ? hunk.oldStart : hunk.oldStart - 1;
+        const position = oldLines.length === 0
+            ? anchor >= cursor && anchor <= lines.length
+                ? anchor
+                : -1
+            : findBlock(lines, oldLines, anchor, cursor);
+        const reachesEnd = position + oldLines.length === lines.length;
+        const endMatches = position >= 0 &&
+            (reachesEnd && oldLines.length > 0
+                ? hunk.noNewlineAtEndOld === !hasFinalNewline
+                : !hunk.noNewlineAtEndOld);
+        if (position < 0 || !endMatches) {
+            const alreadyApplied = newLines.length > 0 && findBlock(lines, newLines, Math.max(0, hunk.newStart - 1), 0) >= 0;
+            refuse(`hunk ${index + 1} of ${label} (@@ -${hunk.oldStart},${hunk.oldCount} ` +
+                `+${hunk.newStart},${hunk.newCount} @@) does not apply to the current file.` +
+                (alreadyApplied
+                    ? ' Its new side is already present: the mutation looks applied already (an earlier control that was not restored?).'
+                    : ' The file changed since the diff was written; regenerate the control against it.'));
+        }
+        result.push(...lines.slice(cursor, position), ...newLines);
+        cursor = position + oldLines.length;
+        if (reachesEnd)
+            finalNewline = !hunk.noNewlineAtEndNew;
+    });
+    result.push(...lines.slice(cursor));
+    return result.join('\n') + (finalNewline && result.length > 0 ? '\n' : '');
+}

package/dist/src/core/negative-control.d.ts

@@ -0,0 +1,150 @@
+/**
+ * `fireforge test --negative-control <diff>`: apply a reviewed mutation to
+ * engine sources for exactly one harness dispatch, then put every byte back.
+ *
+ * Safety model (also stated in docs/testing.md):
+ *
+ *  - The control is applied and restored only while the caller holds the
+ *    engine-session lock, after the pre-test build has packaged and before
+ *    the harness spawns, so no peer build or test can observe it and a
+ *    Furnace deploy cannot overwrite it.
+ *  - Before the first mutated byte is written, the original bytes of every
+ *    target go to `.fireforge/negative-control/` together with a journal
+ *    recording each file's original and mutated SHA-256, mode and
+ *    timestamps. A killed FireForge therefore leaves enough on disk to undo
+ *    the control, and the next `fireforge test` does so before anything else.
+ *  - Restore writes the original bytes back atomically, re-applies the
+ *    original mode and timestamps, and reads the file back to prove the
+ *    bytes match. It only overwrites a file that still holds exactly the
+ *    bytes the control wrote: anything else means someone edited the file
+ *    while the control ran, and that edit is kept, never clobbered, with the
+ *    original left in the journal directory and the conflict reported.
+ *  - A SIGINT or SIGTERM restores through {@link restoreActiveNegativeControlsForSignal},
+ *    which the entry point runs after the harness has shut down and before
+ *    it releases the held locks.
+ */
+import type { ParsedHunk } from './patch-parse.js';
+/** One file a control mutates. */
+export interface NegativeControlTarget {
+    /** The path as the diff names it. */
+    diffPath: string;
+    /** The engine-relative file the control mutates. */
+    enginePath: string;
+    /** Hunks to apply to the engine file. */
+    hunks: ParsedHunk[];
+    /** True when the diff named a `components/` source mapped to its deployed copy. */
+    fromComponents: boolean;
+}
+/** A parsed, resolved control, ready to apply. */
+export interface NegativeControlPlan {
+    /** The diff file, as the operator passed it. */
+    diffFile: string;
+    targets: NegativeControlTarget[];
+    /**
+     * Engine-relative targets only a build delivers (compiled sources). A
+     * control with any must be applied before the pre-test build, and is
+     * restored with a fresh mtime. See `negative-control-compiled.ts`.
+     */
+    compiled?: string[];
+}
+/** Locations a control works against. */
+export interface NegativeControlPaths {
+    engineDir: string;
+    /** The project's `.fireforge/` directory. */
+    fireforgeDir: string;
+}
+interface JournalEntry {
+    enginePath: string;
+    backup: string;
+    originalSha256: string;
+    mutatedSha256: string;
+    mode: number;
+    atimeMs: number;
+    mtimeMs: number;
+    /**
+     * Restore with the current time as mtime, not the original: a compiled
+     * source restored with its old mtime is skipped by the incremental build,
+     * which would leave the mutated code in the binary.
+     */
+    freshMtime?: boolean;
+}
+interface Journal {
+    version: 1;
+    diffFile: string;
+    appliedAt: string;
+    entries: JournalEntry[];
+}
+/** A control currently applied to the engine. */
+export interface ActiveNegativeControl {
+    paths: NegativeControlPaths;
+    journal: Journal;
+    /**
+     * The one restore in flight, set synchronously by whichever path (the
+     * run's own `finally`, or the signal handler) gets there first, so the
+     * other awaits the same restore instead of racing or skipping it.
+     */
+    restoring?: Promise<NegativeControlRestoreResult>;
+}
+/**
+ * Reads, parses and resolves a control diff, and (unless `deferApplyCheck`)
+ * proves every hunk applies to the current engine file, so a broken control
+ * is refused before any build time is spent.
+ *
+ * `deferApplyCheck` is for a run that builds first: Furnace redeploys a
+ * component's engine copy during the build, so a `components/` control can
+ * only be checked against what the build left behind.
+ *
+ * @param projectRoot - Project root; the diff path resolves against it
+ * @param engineDir - Absolute engine directory
+ * @param diffFile - The `--negative-control` argument
+ * @param options - `deferApplyCheck` skips the up-front apply check for
+ *   `components/` targets
+ */
+export declare function planNegativeControl(projectRoot: string, engineDir: string, diffFile: string, options?: {
+    deferApplyCheck?: boolean;
+}): Promise<NegativeControlPlan>;
+/**
+ * Applies the control: every target is computed first (a hunk that does
+ * not apply refuses with nothing written), the originals and the journal
+ * are persisted, then the mutated bytes are written. Runs as a signal
+ * critical section, so a Ctrl+C mid-apply waits for the apply to finish
+ * and the signal path then restores a complete journal.
+ *
+ * @returns The handle {@link restoreNegativeControl} takes
+ */
+export declare function applyNegativeControl(paths: NegativeControlPaths, plan: NegativeControlPlan): Promise<ActiveNegativeControl>;
+/** What happened to each file of a restored control. */
+export interface NegativeControlRestoreResult {
+    /** Engine-relative files put back to their original bytes. */
+    restored: string[];
+    /** Engine-relative files that held neither the control's bytes nor the original. */
+    conflicts: string[];
+}
+/**
+ * Restores a control applied by {@link applyNegativeControl}. Idempotent:
+ * a second caller (the signal handler racing the run's own `finally`)
+ * receives the restore already in flight.
+ *
+ * @throws GeneralError when a file changed under the control (the edit is
+ *   kept and the original stays in the journal directory) or did not read
+ *   back byte-exact
+ */
+export declare function restoreNegativeControl(control: ActiveNegativeControl): Promise<NegativeControlRestoreResult>;
+/**
+ * Restores every applied control on the way out of a SIGINT/SIGTERM. Called
+ * by the entry point after child shutdown and before the held locks are
+ * force-released. Never throws: a failure is reported on stderr and the
+ * journal stays for the next run's recovery.
+ */
+export declare function restoreActiveNegativeControlsForSignal(): Promise<void>;
+/**
+ * Undoes a control a killed FireForge left applied. Called at the start of
+ * every `fireforge test`, under the engine-session lock. A file that still
+ * holds the control's bytes is restored; a file somebody changed since is
+ * refused rather than overwritten.
+ *
+ * @throws PreflightRefusalError (`note=negative-control-pending`) when a
+ *   journal entry cannot be restored safely
+ */
+export declare function recoverPendingNegativeControl(paths: NegativeControlPaths): Promise<void>;
+export {};