@hominis/fireforge 0.52.0 → 0.54.0

package/dist/src/core/harness-port-reservation.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Mochitest server ports for `fireforge test --jobs <n>`: placeholder
+ * listeners that push every parallel harness instance onto its own ports,
+ * and the parse of the ports each instance actually took.
+ *
+ * Desktop `mach mochitest` has no `--http-port`, `--ssl-port` or
+ * `--websocket-port`. Its `startServers` (`testing/mochitest/runtests.py`)
+ * bind-probes the HTTP server, ssltunnel and WebSocket ports (8888, 4443,
+ * 9988) and moves only a busy one to a free port; see
+ * `harness-port-fallback.ts`. Instances started at the same moment all
+ * pass that probe on a free 8888, then race to bind it: the losers die with
+ * `could not start server on port 8888` before any test runs. Holding the
+ * three ports for the whole parallel run makes every instance's probe fail,
+ * so each one falls back to an OS-assigned port of its own.
+ */
+/** Which mochitest server a port belongs to, as the verdict line names it. */
+export type HarnessServerPortKey = 'http' | 'ssl' | 'ws';
+/** Placeholder listeners held for a parallel run. */
+export interface HarnessPortReservation {
+    /** Ports this process now holds. A port that was already busy is not listed. */
+    held: number[];
+    /** Closes every placeholder. Safe to call more than once. */
+    release(): Promise<void>;
+}
+/**
+ * Holds a placeholder listener on `127.0.0.1` on each mochitest server
+ * port, so the harness's busy-port probe moves every instance elsewhere.
+ * A port that cannot be bound is skipped, not refused: whatever holds it
+ * already makes the probe fail, which is all the placeholder is for (the
+ * preflight has already ruled out this checkout's own stale httpd).
+ *
+ * @param ports - Ports to hold (default: {@link HARNESS_SERVER_PORTS})
+ */
+export declare function reserveHarnessServerPorts(ports?: readonly number[]): Promise<HarnessPortReservation>;
+/** The server ports one harness invocation reported, by server. */
+export type HarnessServerPorts = Partial<Record<HarnessServerPortKey, number>>;
+/**
+ * Records the port one output line reports, if it reports one: the
+ * fallback port of a "falling back" line, or the port itself otherwise.
+ *
+ * @param line - One line of harness output
+ * @param into - Collected ports; a later line for the same server wins
+ */
+export declare function recordHarnessServerPortLine(line: string, into: HarnessServerPorts): void;
+/** Collects server ports from streamed output chunks. */
+export interface HarnessPortTracker {
+    onChunk(stream: 'stdout' | 'stderr', chunk: string): void;
+    /** The ports seen so far, including an unterminated last line. */
+    ports(): HarnessServerPorts;
+}
+/**
+ * A tracker over the full output stream. The ports are printed at harness
+ * start, so the capped capture tail a long run keeps would lose them.
+ */
+export declare function createHarnessPortTracker(): HarnessPortTracker;
+/**
+ * The `http:N,ssl:N,ws:N` value of a `ports=` key, in probe order, or
+ * undefined when no port is known.
+ */
+export declare function formatHarnessServerPorts(ports: HarnessServerPorts | undefined): string | undefined;

package/dist/src/core/harness-port-reservation.js

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Mochitest server ports for `fireforge test --jobs <n>`: placeholder
+ * listeners that push every parallel harness instance onto its own ports,
+ * and the parse of the ports each instance actually took.
+ *
+ * Desktop `mach mochitest` has no `--http-port`, `--ssl-port` or
+ * `--websocket-port`. Its `startServers` (`testing/mochitest/runtests.py`)
+ * bind-probes the HTTP server, ssltunnel and WebSocket ports (8888, 4443,
+ * 9988) and moves only a busy one to a free port; see
+ * `harness-port-fallback.ts`. Instances started at the same moment all
+ * pass that probe on a free 8888, then race to bind it: the losers die with
+ * `could not start server on port 8888` before any test runs. Holding the
+ * three ports for the whole parallel run makes every instance's probe fail,
+ * so each one falls back to an OS-assigned port of its own.
+ */
+import { createServer } from 'node:net';
+/**
+ * The ports `startServers` probes, in the order it probes them. Desktop
+ * mochitest cannot configure them, so the engine defaults are the ports.
+ */
+const HARNESS_SERVER_PORTS = [
+    { key: 'http', port: 8888, label: 'HTTP test server' },
+    { key: 'ssl', port: 4443, label: 'ssltunnel' },
+    { key: 'ws', port: 9988, label: 'WebSocket server' },
+];
+/** Listens on `127.0.0.1:port`, or resolves undefined when the bind fails. */
+async function holdPort(port) {
+    return new Promise((resolve) => {
+        const server = createServer((socket) => {
+            // Nothing should connect: the harness only probes with a bind. Anyone
+            // who does gets a closed socket instead of a hang.
+            socket.destroy();
+        });
+        server.once('error', () => {
+            resolve(undefined);
+        });
+        server.listen({ port, host: '127.0.0.1', exclusive: true }, () => {
+            server.unref();
+            resolve(server);
+        });
+    });
+}
+/**
+ * Holds a placeholder listener on `127.0.0.1` on each mochitest server
+ * port, so the harness's busy-port probe moves every instance elsewhere.
+ * A port that cannot be bound is skipped, not refused: whatever holds it
+ * already makes the probe fail, which is all the placeholder is for (the
+ * preflight has already ruled out this checkout's own stale httpd).
+ *
+ * @param ports - Ports to hold (default: {@link HARNESS_SERVER_PORTS})
+ */
+export async function reserveHarnessServerPorts(ports = HARNESS_SERVER_PORTS.map((spec) => spec.port)) {
+    const servers = (await Promise.all(ports.map(holdPort))).filter((server) => server !== undefined);
+    const held = servers.map((server) => {
+        const address = server.address();
+        return typeof address === 'object' && address !== null ? address.port : 0;
+    });
+    let released = false;
+    return {
+        held,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            await Promise.all(servers.map((server) => new Promise((resolve) => {
+                server.close(() => {
+                    resolve();
+                });
+            })));
+        },
+    };
+}
+const PORT_LINE_PATTERN = /\b(HTTP test server|ssltunnel|WebSocket server) port (\d+)(?: already in use, falling back to port (\d+))?/;
+/**
+ * Records the port one output line reports, if it reports one: the
+ * fallback port of a "falling back" line, or the port itself otherwise.
+ *
+ * @param line - One line of harness output
+ * @param into - Collected ports; a later line for the same server wins
+ */
+export function recordHarnessServerPortLine(line, into) {
+    const match = PORT_LINE_PATTERN.exec(line);
+    if (match === null)
+        return;
+    const spec = HARNESS_SERVER_PORTS.find((entry) => entry.label === match[1]);
+    const port = Number.parseInt(match[3] ?? match[2] ?? '', 10);
+    if (spec !== undefined && Number.isInteger(port))
+        into[spec.key] = port;
+}
+/**
+ * A tracker over the full output stream. The ports are printed at harness
+ * start, so the capped capture tail a long run keeps would lose them.
+ */
+export function createHarnessPortTracker() {
+    const collected = {};
+    const pending = { stdout: '', stderr: '' };
+    return {
+        onChunk(stream, chunk) {
+            const lines = `${pending[stream]}${chunk}`.split(/\r?\n/);
+            pending[stream] = lines.pop() ?? '';
+            for (const line of lines)
+                recordHarnessServerPortLine(line, collected);
+        },
+        ports() {
+            const result = { ...collected };
+            recordHarnessServerPortLine(pending.stdout, result);
+            recordHarnessServerPortLine(pending.stderr, result);
+            return result;
+        },
+    };
+}
+/**
+ * The `http:N,ssl:N,ws:N` value of a `ports=` key, in probe order, or
+ * undefined when no port is known.
+ */
+export function formatHarnessServerPorts(ports) {
+    if (ports === undefined)
+        return undefined;
+    const parts = HARNESS_SERVER_PORTS.flatMap(({ key }) => ports[key] === undefined ? [] : [`${key}:${ports[key]}`]);
+    return parts.length > 0 ? parts.join(',') : undefined;
+}

package/dist/src/core/history-log-file.d.ts

@@ -1,4 +1,4 @@
-/** Filename of the history log at its pre-0.50 location, inside `patches/`. */
+/** Filename of a history log inside `patches/`, which is moved out of the queue. */
 export declare const LEGACY_HISTORY_LOG_FILENAME = ".fireforge-history.jsonl";
 /** Default history log location, relative to the project root. */
 export declare const DEFAULT_HISTORY_LOG_PATH: string;
@@ -29,30 +29,30 @@ export declare function historyRecordIdentity(): HistoryRecordIdentity;
  */
 export declare function resolveHistoryLogPath(projectRoot: string): Promise<string>;
 /**
- * Moves a history log left at the legacy `patches/` path to `target`.
+ * Moves a history log found at the `patches/` path to `target`.
  *
  * Records are never dropped, whatever else is happening:
- * - The legacy file is first claimed by renaming it aside, so of two
+ * - The in-queue file is first claimed by renaming it aside, so of two
  *   commands migrating at once exactly one does the work and neither
  *   duplicates it.
  * - When `target` does not exist yet (the first run), the claimed file is
  *   hard-linked into place, which cannot overwrite a log another command
  *   created in the meantime, and keeps a large log a constant-time move.
- * - When both exist (an older FireForge appended to the legacy path after
- *   a migration, or `history.path` changed), the legacy records are
+ * - When both exist (a log reappeared at the `patches/` path after a
+ *   migration, or `history.path` changed), the in-queue records are
  *   appended to the target in one write. They then follow newer records;
  *   every record carries its own `ts`.
  *
  * A crash between the claim and the move leaves the records in a
- * `.migrating-*` file next to the legacy path, never deleted.
+ * `.migrating-*` file next to the in-queue path, never deleted.
  *
- * @param patchesDir - The patches directory that may hold a legacy log
+ * @param patchesDir - The patches directory that may hold an in-queue log
  * @param target - Absolute path of the history log
  */
 export declare function migrateLegacyHistoryLog(patchesDir: string, target: string): Promise<void>;
 /**
- * Appends one serialized record to the project's history log, migrating a
- * legacy log first.
+ * Appends one serialized record to the project's history log, first moving
+ * a log found inside `patches/`.
  *
  * @param patchesDir - The project's `patches/` directory; the project root is
  *   its parent, as every caller derives it from `getProjectPaths`

package/dist/src/core/history-log-file.js

@@ -2,12 +2,12 @@
 /**
  * Where the patch history log lives, and who wrote each record.
  *
- * The log used to be `patches/.fireforge-history.jsonl`, inside the tracked
- * patch queue, so it was committed with every export until consumers
- * gitignored it, and it grew to tens of megabytes. It now defaults to
- * `.fireforge/history.jsonl` (FireForge's own untracked data directory), or
- * `fireforge.json#history.path` when a project sets one. A log left at the
- * old path is moved on the first append.
+ * The log defaults to `.fireforge/history.jsonl` (FireForge's own untracked
+ * data directory), or `fireforge.json#history.path` when a project sets one.
+ * It stays out of the tracked patch queue because it grows to tens of
+ * megabytes and would otherwise be committed with every export. A log found
+ * at `patches/.fireforge-history.jsonl`, inside the queue, is moved on the
+ * first append.
  *
  * Several sessions sharing one checkout all append to the same log, so each
  * record carries the invocation that wrote it, plus a session hint, letting
@@ -21,7 +21,7 @@ import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, verbose } from '../utils/logger.js';
 import { FIREFORGE_DIR } from './config-paths.js';
 import { isValidHistoryPath } from './config-validate-history.js';
-/** Filename of the history log at its pre-0.50 location, inside `patches/`. */
+/** Filename of a history log inside `patches/`, which is moved out of the queue. */
 export const LEGACY_HISTORY_LOG_FILENAME = '.fireforge-history.jsonl';
 /** Default history log location, relative to the project root. */
 export const DEFAULT_HISTORY_LOG_PATH = join(FIREFORGE_DIR, 'history.jsonl');
@@ -87,24 +87,24 @@ export async function resolveHistoryLogPath(projectRoot) {
     return resolve(projectRoot, configured ?? DEFAULT_HISTORY_LOG_PATH);
 }
 /**
- * Moves a history log left at the legacy `patches/` path to `target`.
+ * Moves a history log found at the `patches/` path to `target`.
  *
  * Records are never dropped, whatever else is happening:
- * - The legacy file is first claimed by renaming it aside, so of two
+ * - The in-queue file is first claimed by renaming it aside, so of two
  *   commands migrating at once exactly one does the work and neither
  *   duplicates it.
  * - When `target` does not exist yet (the first run), the claimed file is
  *   hard-linked into place, which cannot overwrite a log another command
  *   created in the meantime, and keeps a large log a constant-time move.
- * - When both exist (an older FireForge appended to the legacy path after
- *   a migration, or `history.path` changed), the legacy records are
+ * - When both exist (a log reappeared at the `patches/` path after a
+ *   migration, or `history.path` changed), the in-queue records are
  *   appended to the target in one write. They then follow newer records;
  *   every record carries its own `ts`.
  *
  * A crash between the claim and the move leaves the records in a
- * `.migrating-*` file next to the legacy path, never deleted.
+ * `.migrating-*` file next to the in-queue path, never deleted.
  *
- * @param patchesDir - The patches directory that may hold a legacy log
+ * @param patchesDir - The patches directory that may hold an in-queue log
  * @param target - Absolute path of the history log
  */
 export async function migrateLegacyHistoryLog(patchesDir, target) {
@@ -149,8 +149,8 @@ export async function migrateLegacyHistoryLog(patchesDir, target) {
         'Nothing reads it back; it is an audit trail only.');
 }
 /**
- * Appends one serialized record to the project's history log, migrating a
- * legacy log first.
+ * Appends one serialized record to the project's history log, first moving
+ * a log found inside `patches/`.
  *
  * @param patchesDir - The project's `patches/` directory; the project root is
  *   its parent, as every caller derives it from `getProjectPaths`

package/dist/src/core/history-log.d.ts

@@ -3,13 +3,13 @@ import type { HistoryEntry } from './destructive.js';
  * Appends a history entry for a mutation that has already committed, degrading
  * to a warning when the log cannot be written.
  *
- * Eleven call sites across `export-flow` and the `patch` subcommands had each
- * grown the same `try { await appendHistory(...) } catch { warn(...) }` block.
+ * This is the one `try { await appendHistory(...) } catch { warn(...) }`
+ * block for every call site across `export-flow` and the `patch` subcommands.
  * The swallow is intentional: the patch files and the manifest
  * are already on disk by the time this runs, so letting a failed log write
  * reject would report a completed, irreversible mutation as a failure and send
  * the operator looking for damage that is not there. Because that reasoning is
- * easy to lose in a copy, it now lives in one place.
+ * easy to lose in a copy, it lives in one place.
  * @param patchesDir - The project's `patches/` directory (the log itself lives
  *   under `.fireforge/` or `history.path`; see `history-log-file.ts`).
  * @param entry - The entry to append.

package/dist/src/core/history-log.js

@@ -6,13 +6,13 @@ import { appendHistory } from './destructive.js';
  * Appends a history entry for a mutation that has already committed, degrading
  * to a warning when the log cannot be written.
  *
- * Eleven call sites across `export-flow` and the `patch` subcommands had each
- * grown the same `try { await appendHistory(...) } catch { warn(...) }` block.
+ * This is the one `try { await appendHistory(...) } catch { warn(...) }`
+ * block for every call site across `export-flow` and the `patch` subcommands.
  * The swallow is intentional: the patch files and the manifest
  * are already on disk by the time this runs, so letting a failed log write
  * reject would report a completed, irreversible mutation as a failure and send
  * the operator looking for damage that is not there. Because that reasoning is
- * easy to lose in a copy, it now lives in one place.
+ * easy to lose in a copy, it lives in one place.
  * @param patchesDir - The project's `patches/` directory (the log itself lives
  *   under `.fireforge/` or `history.path`; see `history-log-file.ts`).
  * @param entry - The entry to append.

package/dist/src/core/launchable-build.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Facts about the launchable build a test run will exercise: its build id
+ * and when its compiled code was last linked.
+ *
+ * A green or red against a binary older than the C++ under test reads as a
+ * verdict on that C++ unless the run says which binary it was. The
+ * build id goes on the verdict line (`build-id=`), and the link time anchors
+ * the stale-compiled preflight (`findCompiledSourcesNewerThanBinary` in
+ * `test-stale-check.ts`).
+ */
+/**
+ * The `application.ini` beside a launchable binary: `Contents/Resources`
+ * of the `.app` bundle on macOS, the binary's own directory (`dist/bin`)
+ * elsewhere.
+ *
+ * @param binaryPath - Absolute launchable binary path
+ */
+export declare function applicationIniPath(binaryPath: string): string;
+/**
+ * Reads the `BuildID=` of the launchable build (the `moz:buildID` the
+ * browser reports). Undefined when the file or the key is missing, so a
+ * caller can simply leave the attribute off.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export declare function readBuildId(engineDir: string, launchablePath: string): Promise<string | undefined>;
+/**
+ * When the launchable build's compiled code was last linked: the newest
+ * mtime of the binary and the `libxul` beside it. Undefined when neither
+ * can be read.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export declare function readLinkedAt(engineDir: string, launchablePath: string): Promise<{
+    mtimeMs: number;
+    path: string;
+} | undefined>;

package/dist/src/core/launchable-build.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Facts about the launchable build a test run will exercise: its build id
+ * and when its compiled code was last linked.
+ *
+ * A green or red against a binary older than the C++ under test reads as a
+ * verdict on that C++ unless the run says which binary it was. The
+ * build id goes on the verdict line (`build-id=`), and the link time anchors
+ * the stale-compiled preflight (`findCompiledSourcesNewerThanBinary` in
+ * `test-stale-check.ts`).
+ */
+import { stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { readText } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+/**
+ * The compiled libraries a build links next to the launchable binary.
+ * `libxul` carries nearly all compiled engine code (C++, Rust, generated
+ * bindings, prefs), so it, not the small launcher executable, is what a
+ * compiled-source edit relinks.
+ */
+const LINKED_LIBRARY_NAMES = ['XUL', 'libxul.so', 'xul.dll'];
+/**
+ * The `application.ini` beside a launchable binary: `Contents/Resources`
+ * of the `.app` bundle on macOS, the binary's own directory (`dist/bin`)
+ * elsewhere.
+ *
+ * @param binaryPath - Absolute launchable binary path
+ */
+export function applicationIniPath(binaryPath) {
+    const binaryDir = dirname(binaryPath);
+    if (basename(binaryDir) === 'MacOS' && basename(dirname(binaryDir)) === 'Contents') {
+        return join(dirname(binaryDir), 'Resources', 'application.ini');
+    }
+    return join(binaryDir, 'application.ini');
+}
+/**
+ * Reads the `BuildID=` of the launchable build (the `moz:buildID` the
+ * browser reports). Undefined when the file or the key is missing, so a
+ * caller can simply leave the attribute off.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export async function readBuildId(engineDir, launchablePath) {
+    const iniPath = applicationIniPath(join(engineDir, launchablePath));
+    let content;
+    try {
+        content = await readText(iniPath);
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) !== 'ENOENT') {
+            verbose(`Build id: could not read ${iniPath} — ${toError(error).message}`);
+        }
+        return undefined;
+    }
+    const match = /^BuildID=(\S+)\s*$/m.exec(content);
+    return match?.[1];
+}
+/**
+ * When the launchable build's compiled code was last linked: the newest
+ * mtime of the binary and the `libxul` beside it. Undefined when neither
+ * can be read.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export async function readLinkedAt(engineDir, launchablePath) {
+    const binary = join(engineDir, launchablePath);
+    const candidates = [binary, ...LINKED_LIBRARY_NAMES.map((name) => join(dirname(binary), name))];
+    let newest;
+    for (const path of candidates) {
+        try {
+            // stat follows the dist/bin symlinks to the linked objdir file.
+            const { mtimeMs } = await stat(path);
+            if (newest === undefined || mtimeMs > newest.mtimeMs)
+                newest = { mtimeMs, path };
+        }
+        catch {
+            // A platform's other library names are simply absent.
+        }
+    }
+    return newest;
+}

package/dist/src/core/marionette-port.js

@@ -247,9 +247,7 @@ async function probeWithLsof(port) {
     catch {
         // `lsof` missing, or its stdout did not parse. Either way the port state
         // is unknown, and an unknown port is reported as free so the probe never
-        // blocks a run on its own uncertainty. (The errno test that used to sit
-        // here returned the same value as this fallthrough, so it decided
-        // nothing.)
+        // blocks a run on its own uncertainty.
         return { inUse: false };
     }
 }

package/dist/src/core/moz-manifest-rules.js

@@ -77,11 +77,12 @@ export function getRules(binaryName, createManifest = false) {
             // scaffolded and wired via XPCSHELL_TESTS_MANIFESTS.
             pattern: /^(?!browser\/base\/content\/test\/)(.+)\/(test_[^/]+\.js)$/,
             isRegistered: (engineDir, dirRel, fileName) => isXpcshellTestRegistered(engineDir, dirRel, fileName),
-            register: (engineDir, _after, dryRun, dirRel, fileName) => registerXpcshellTest(engineDir, dirRel, fileName, dryRun, createManifest),
+            register: (engineDir, after, dryRun, dirRel, fileName) => registerXpcshellTest(engineDir, dirRel, fileName, dryRun, createManifest, after),
             // Both groups are guaranteed by the pattern, so slice avoids dead
             // fallback branches.
             extractArgs: (m) => m.slice(1, 3),
-            supportsAfter: false,
+            // `--after <entry>` places the section after that entry's block.
+            supportsAfter: true,
         },
     ];
 }

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

@@ -6,15 +6,25 @@
  * 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
+ * is refused without `--build`, and with `--build` the control is
  * applied before the build so the binary under test carries it. That build
  * is a full `mach build`: the pre-test build is otherwise `mach build
- * faster`, which compiles nothing, so the control still missed.
+ * faster`, which compiles nothing, so the control would still miss.
  */
+/**
+ * Whether an engine-relative path has a compiled-source extension: a file
+ * the build compiles or code-generates into the binary. This is the
+ * extension test only. {@link findCompiledControlTargets} additionally
+ * drops non-header files an install manifest ships as-is.
+ *
+ * @param path - Engine-relative path
+ */
+export declare function isCompiledSourcePath(path: string): boolean;
 /**
  * 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.
+ * ships the file itself. Headers are always compiled, even when an
+ * `EXPORTS` manifest installs them into `dist/include`.
  *
  * @param engineDir - Absolute engine directory
  * @param enginePaths - The control's engine-relative targets

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

@@ -7,10 +7,10 @@
  * 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
+ * is refused without `--build`, and with `--build` the control is
  * applied before the build so the binary under test carries it. That build
  * is a full `mach build`: the pre-test build is otherwise `mach build
- * faster`, which compiles nothing, so the control still missed.
+ * faster`, which compiles nothing, so the control would still miss.
  */
 import { extname } from 'node:path';
 import { classifyRuntimeDelivery } from './objdir-install-manifests.js';
@@ -34,24 +34,46 @@ const COMPILED_EXTENSIONS = new Set([
     '.yaml',
     '.yml',
 ]);
+/**
+ * Header extensions. An `EXPORTS` install manifest names many headers (it
+ * copies them into `dist/include`), but that copy only feeds other
+ * compiles: the runtime never reads a header, so a header edit reaches the
+ * binary through a compile whatever the manifests say.
+ */
+const HEADER_EXTENSIONS = new Set(['.h', '.hh', '.hpp', '.ipdlh']);
+/**
+ * Whether an engine-relative path has a compiled-source extension: a file
+ * the build compiles or code-generates into the binary. This is the
+ * extension test only. {@link findCompiledControlTargets} additionally
+ * drops non-header files an install manifest ships as-is.
+ *
+ * @param path - Engine-relative path
+ */
+export function isCompiledSourcePath(path) {
+    return COMPILED_EXTENSIONS.has(extname(path));
+}
 /**
  * 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.
+ * ships the file itself. Headers are always compiled, even when an
+ * `EXPORTS` manifest installs them into `dist/include`.
  *
  * @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)));
+    const candidates = enginePaths.filter(isCompiledSourcePath);
     if (candidates.length === 0)
         return [];
+    if (candidates.every((path) => HEADER_EXTENSIONS.has(extname(path))))
+        return candidates;
     const index = await loadEngineInstallIndex(engineDir);
     if (index === undefined)
         return candidates;
     const compiled = [];
     for (const path of candidates) {
-        if ((await classifyRuntimeDelivery(index, engineDir, path)) === 'unlisted') {
+        if (HEADER_EXTENSIONS.has(extname(path)) ||
+            (await classifyRuntimeDelivery(index, engineDir, path)) === 'unlisted') {
             compiled.push(path);
         }
     }

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

@@ -70,8 +70,8 @@ export function parseControlDiff(content, options = {}) {
         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) => {
+    const files = new Map();
+    for (const section of sections) {
         let path = normalizePathSlashes(section.targetPath);
         if (section.isBinary)
             refuse(`${path} is a binary section.`);
@@ -90,11 +90,36 @@ export function parseControlDiff(content, options = {}) {
         }
         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 };
+        const existing = files.get(path);
+        if (existing === undefined) {
+            files.set(path, { path, hunks: [...section.hunks], sections: 1 });
+        }
+        else {
+            existing.hunks.push(...section.hunks);
+            existing.sections += 1;
+        }
+    }
+    return [...files.values()].map(({ path, hunks, sections: count }) => ({
+        path,
+        hunks: count === 1 ? hunks : mergeSectionHunks(path, hunks),
+    }));
+}
+/**
+ * Orders the hunks of a file that several sections name (a generator that
+ * writes one section per edit) as one section's would be. Hunks that
+ * overlap cannot be applied one after another, so they are refused.
+ */
+function mergeSectionHunks(path, hunks) {
+    const ordered = [...hunks].sort((left, right) => left.oldStart - right.oldStart);
+    ordered.forEach((hunk, index) => {
+        const previous = ordered[index - 1];
+        if (previous !== undefined && previous.oldStart + previous.oldCount > hunk.oldStart) {
+            refuse(`${path} appears in more than one section, and hunks from them overlap ` +
+                `(@@ -${previous.oldStart},${previous.oldCount} @@ and @@ -${hunk.oldStart},${hunk.oldCount} @@). ` +
+                'Make every edit to the file, then write one section for it with `git -C engine diff -- <file>`.');
+        }
     });
+    return ordered;
 }
 function hunkSides(hunk, label, index) {
     const oldLines = [];