@hominis/fireforge 0.39.0 → 0.41.0

package/dist/src/core/build-baseline-types.d.ts

@@ -6,6 +6,7 @@
  * into it would make the dependency graph cyclic.
  */
 /** Shape of the on-disk baseline marker. */
+export declare const DELETED_FILE_FINGERPRINT = "<deleted>";
 export interface BuildBaseline {
     /** SHA of engine HEAD at the time the build succeeded. */
     engineHeadSha: string;
@@ -32,7 +33,8 @@ export interface BuildBaseline {
      *
      * Keys are engine-relative POSIX paths. Values are hex-encoded
      * SHA-256 digests of the file contents at the moment the baseline
-     * was recorded.
+     * was recorded, or {@link DELETED_FILE_FINGERPRINT} when the successful
+     * build observed a tracked deletion.
      */
     packageableFingerprints?: Record<string, string>;
     /**
@@ -56,14 +58,32 @@ export interface BuildBaseline {
      * checkouts are refused up-front (`AmbiguousBuildArtifactsError`), so at
      * most one obj dir exists per project.
      *
-     * Union/"shared coverage" across successive scoped builds was evaluated
-     * and rejected as unsound — every baseline write refreshes
-     * `packageableFingerprints` for ALL dirty packageable paths, so a union
-     * would whitewash an earlier scope's edited fixtures while
-     * `obj-*`/`_tests/` still holds its stale staging; coverage therefore
-     * REPLACES.
+     * Union/"shared coverage" across successive scoped builds is unsound in
+     * general — every baseline write refreshes `packageableFingerprints` for
+     * ALL dirty packageable paths, so a blind union would whitewash an
+     * earlier scope's edited fixtures while `obj-*`/`_tests/` still holds its
+     * stale staging; coverage therefore REPLACES by default.
+     *
+     * The one exception is `test --build --extend-coverage` (FORGE L1), which
+     * unions only after proving the previous record's anchor still holds:
+     * same engine HEAD, same {@link BuildBaseline.mozconfigHash}, and every
+     * previously fingerprinted path byte-identical — i.e. the wholesale
+     * fingerprint refresh is a no-op for everything the earlier scope's
+     * staging depended on. Any divergence refuses fail-closed. See
+     * `src/core/coverage-extend.ts`, which also documents the one boundary
+     * that guard does not cover (dirty non-packageable fixtures).
      */
     testPackagingCoverage?: TestPackagingCoverage;
+    /**
+     * Hex-encoded SHA-256 of `engine/mozconfig` as it stood for this build.
+     * Recorded because the mozconfig is REGENERATED from project-side
+     * `configs/*.mozconfig` templates plus `fireforge.json` on every build,
+     * so `engineHeadSha` does not cover it: two builds at the same engine SHA
+     * can configure differently. Consumed by the `--extend-coverage` anchor.
+     * Missing on pre-0.41.0 baselines, which `--extend-coverage` refuses
+     * (one plain build re-records it).
+     */
+    mozconfigHash?: string;
     /**
      * Anchor for the compiled StaticComponents table: the engine HEAD SHA of
      * the last FULL-coverage build plus content fingerprints of the
@@ -94,7 +114,8 @@ export interface StaticComponentsBaseline {
     engineHeadSha: string;
     /**
      * Hex-encoded SHA-256 per `components.conf` path that was dirty
-     * (modified-against-HEAD or untracked) when the full build ran. Keys are
+     * (modified-against-HEAD or untracked) when the full build ran. A tracked
+     * deletion is represented by {@link DELETED_FILE_FINGERPRINT}. Keys are
      * engine-relative POSIX paths.
      */
     fingerprints: Record<string, string>;

package/dist/src/core/build-baseline-types.js

@@ -6,4 +6,5 @@
  * itself depends on `build-audit.ts` at runtime, and a type import back
  * into it would make the dependency graph cyclic.
  */
-export {};
+/** Shape of the on-disk baseline marker. */
+export const DELETED_FILE_FINGERPRINT = '<deleted>';

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

@@ -15,7 +15,7 @@
  * on successful build completion; a failed build does not update it, so a
  * subsequent run still audits against the last known-good tree.
  */
-import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
+import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline-types.js';
 /** Name of the last-build marker file under `.fireforge/`. */
 export declare const BUILD_BASELINE_FILENAME = "last-build.json";
 /**
@@ -47,5 +47,13 @@ export declare function readBuildBaseline(projectRoot: string): Promise<BuildBas
  *   `staticComponentsBaseline` forward verbatim — `mach build faster`
  *   does not rebake `components.conf` registrations, so the last FULL
  *   build stays the honest anchor for the compiled StaticComponents table.
+ * @param recordedBy - Invocation shape that produced this baseline.
+ * @param staticComponentsHandling - `'auto'` (default) refreshes the
+ *   static-components anchor whenever the coverage claim is `'full'` or
+ *   absent. `'refresh'` records it even for a scoped coverage claim whose
+ *   implementation escalated to a full build. `'carry-forward'` always keeps the previous anchor: needed by
+ *   `--extend-coverage` (FORGE L1), whose union can EVALUATE to `'full'`
+ *   while the build that produced it was still a scoped `mach build
+ *   faster` that did not rebake the compiled table.
  */
-export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage, previousBaseline?: BuildBaseline, recordedBy?: string): Promise<void>;
+export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage, previousBaseline?: BuildBaseline, recordedBy?: string, staticComponentsHandling?: 'auto' | 'refresh' | 'carry-forward'): Promise<void>;

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

@@ -19,14 +19,22 @@
 import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { toError } from '../utils/errors.js';
+import { mapWithConcurrency } from '../utils/concurrency.js';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
+import { DELETED_FILE_FINGERPRINT, } from './build-baseline-types.js';
 import { FIREFORGE_DIR } from './config-paths.js';
+import { hashEngineFile } from './coverage-extend.js';
 import { getHead, hasChanges, isMissingHeadError } from './git.js';
 import { git } from './git-base.js';
 import { getUntrackedFiles } from './git-status.js';
+/*
+ * Keep the IO fan-out bounded: a patched Firefox checkout can carry hundreds
+ * of dirty packageable paths and serial reads add directly to every build.
+ */
+const FINGERPRINT_IO_CONCURRENCY = 16;
 /** Name of the last-build marker file under `.fireforge/`. */
 export const BUILD_BASELINE_FILENAME = 'last-build.json';
 /**
@@ -73,8 +81,16 @@ export async function readBuildBaseline(projectRoot) {
  *   `staticComponentsBaseline` forward verbatim — `mach build faster`
  *   does not rebake `components.conf` registrations, so the last FULL
  *   build stays the honest anchor for the compiled StaticComponents table.
+ * @param recordedBy - Invocation shape that produced this baseline.
+ * @param staticComponentsHandling - `'auto'` (default) refreshes the
+ *   static-components anchor whenever the coverage claim is `'full'` or
+ *   absent. `'refresh'` records it even for a scoped coverage claim whose
+ *   implementation escalated to a full build. `'carry-forward'` always keeps the previous anchor: needed by
+ *   `--extend-coverage` (FORGE L1), whose union can EVALUATE to `'full'`
+ *   while the build that produced it was still a scoped `mach build
+ *   faster` that did not rebake the compiled table.
  */
-export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline, recordedBy) {
+export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline, recordedBy, staticComponentsHandling = 'auto') {
     let engineHeadSha = '';
     try {
         engineHeadSha = await getHead(engineDir);
@@ -93,15 +109,19 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName, tes
     // just recompiled the StaticComponents table, so it anchors the table to
     // the current engine state. A scoped write did not — carry the previous
     // anchor forward verbatim.
-    const staticComponentsBaseline = testPackagingCoverage === undefined || testPackagingCoverage === 'full'
+    const staticComponentsBaseline = staticComponentsHandling === 'refresh' ||
+        (staticComponentsHandling === 'auto' &&
+            (testPackagingCoverage === undefined || testPackagingCoverage === 'full'))
         ? await collectStaticComponentsBaseline(engineDir, engineHeadSha)
         : previousBaseline?.staticComponentsBaseline;
+    const mozconfigHash = await hashEngineFile(engineDir, 'mozconfig');
     const baseline = {
         engineHeadSha,
         builtAt: new Date().toISOString(),
         binaryName,
         ...(packageableFingerprints !== undefined ? { packageableFingerprints } : {}),
         ...(testPackagingCoverage !== undefined ? { testPackagingCoverage } : {}),
+        ...(mozconfigHash !== undefined ? { mozconfigHash } : {}),
         ...(staticComponentsBaseline !== undefined ? { staticComponentsBaseline } : {}),
         ...(recordedBy !== undefined ? { recordedBy } : {}),
     };
@@ -165,18 +185,29 @@ async function collectDirtyFingerprints(engineDir, includePath, contextLabel) {
         if (included.length === 0) {
             return {};
         }
-        const fingerprints = {};
-        for (const relPath of included) {
+        const entries = await mapWithConcurrency(included, FINGERPRINT_IO_CONCURRENCY, async (relPath) => {
             try {
                 const buffer = await readFile(join(engineDir, relPath));
-                fingerprints[relPath] = createHash('sha256').update(buffer).digest('hex');
+                return [relPath, createHash('sha256').update(buffer).digest('hex')];
             }
             catch (fileError) {
+                if (getNodeErrorCode(fileError) === 'ENOENT') {
+                    // A path reported by git but absent on disk is normally a tracked
+                    // deletion, not a failed fingerprint. Recording the tombstone lets
+                    // the next stale check prove that deletion was already built.
+                    return [relPath, DELETED_FILE_FINGERPRINT];
+                }
                 // A file that disappeared between status probe and hash is
-                // expected in concurrent scenarios; skip it without failing the
-                // whole baseline write.
+                // expected in concurrent scenarios; non-ENOENT failures remain
+                // untrusted and are skipped without failing the whole baseline write.
                 verbose(`Build baseline: skipping ${contextLabel} for ${relPath} — ${toError(fileError).message}`);
+                return undefined;
             }
+        });
+        const fingerprints = {};
+        for (const entry of entries) {
+            if (entry !== undefined)
+                fingerprints[entry[0]] = entry[1];
         }
         return fingerprints;
     }

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

@@ -12,6 +12,8 @@ export interface BuildPreparation {
     furnaceApplied: number;
     /** True when `mach configure` was auto-run to refresh a stale backend. */
     reconfigured: boolean;
+    /** A changed packaging manifest cannot be safely handled by `mach build faster`. */
+    fullBuildRequired?: boolean;
 }
 /** Options for {@link prepareBuildEnvironment}. */
 export interface PrepareBuildOptions {
@@ -24,6 +26,8 @@ export interface PrepareBuildOptions {
      */
     previousBaseline?: BuildBaseline | undefined;
 }
+/** Packaging manifests whose graph/destination directories need a full build. */
+export declare function requiresFullBuildForIncrementalTest(path: string): boolean;
 /**
  * Describes an exit code in the shell's 128+N signal convention. Truncated
  * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG

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

@@ -20,6 +20,10 @@ import { generateMozconfig, runMachCapture } from './mach.js';
 import { explainMachError } from './mach-error-hints.js';
 /** Path fragments of files whose edits invalidate the recursive-make backend. */
 const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
+/** Packaging manifests whose graph/destination directories need a full build. */
+export function requiresFullBuildForIncrementalTest(path) {
+    return path === 'jar.mn' || path.endsWith('/jar.mn');
+}
 /**
  * Extracts the tail of captured `mach configure` output so the underlying
  * mozbuild failure (e.g. `mozbuild.util.UnsortedError: ... is not in sorted
@@ -112,9 +116,11 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
     // before the build step. Prevents incremental builds from silently skipping
     // work against a stale recursive-make backend.
     let reconfigured = false;
+    let fullBuildRequired = false;
     if (options.previousBaseline) {
         const changed = await collectChangedEnginePaths(paths.engine, options.previousBaseline, 'Auto-configure');
         const invalidating = changed.filter(isBackendInvalidatingFile);
+        fullBuildRequired = changed.some(requiresFullBuildForIncrementalTest);
         if (invalidating.length > 0) {
             info(`Backend config changed; running backend regeneration first (${invalidating.length} file${invalidating.length === 1 ? '' : 's'} touched).`);
             info(`Backend command: mach configure`);
@@ -233,5 +239,5 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
         mozconfigSpinner.error('Failed to generate mozconfig');
         throw error;
     }
-    return { furnaceApplied, reconfigured };
+    return { furnaceApplied, reconfigured, fullBuildRequired };
 }

package/dist/src/core/config-paths.d.ts

@@ -11,7 +11,7 @@ export declare const STATE_FILENAME = "state.json";
 /** Supported top-level fireforge.json keys backed by the current schema. */
 export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "test", "externalToolchains", "license", "wire", "patchLint", "patchPolicy", "typecheck", "markerComment"];
 /** Supported config paths that can be read or set without --force. */
-export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "firefox.candidate", "build", "build.jobs", "test", "test.canaryPath", "test.canaryTimeoutSeconds", "externalToolchains", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "firefox.candidate", "build", "build.jobs", "test", "test.canaryPath", "test.canaryTimeoutSeconds", "externalToolchains", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.checkJsTestFiles", "patchLint.checkJsTestShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

package/dist/src/core/config-paths.js

@@ -59,6 +59,8 @@ export const SUPPORTED_CONFIG_PATHS = [
     'patchLint.checkJsStrict',
     'patchLint.checkJsCompilerOptions',
     'patchLint.checkJsExtraShim',
+    'patchLint.checkJsTestFiles',
+    'patchLint.checkJsTestShim',
     'patchLint.rawColorAllowlist',
     'patchLint.jsdocClassMethods',
     'patchLint.testAssertionFloor',

package/dist/src/core/config-validate-test-toolchains.js

@@ -2,6 +2,7 @@
 import { ConfigError } from '../errors/config.js';
 import { parseObject } from '../utils/parse.js';
 import { isContainedRelativePath } from '../utils/paths.js';
+import { isObject } from '../utils/validation.js';
 function optionalConfigString(rec, key, label) {
     const value = rec.raw(key);
     if (value === undefined)
@@ -56,7 +57,7 @@ export function parseExternalToolchainsBlock(rec, config) {
         throw new ConfigError('Config field "externalToolchains" must be an array');
     }
     config.externalToolchains = raw.map((entry, index) => {
-        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+        if (!isObject(entry)) {
             throw new ConfigError(`Config field "externalToolchains[${String(index)}]" must be an object`);
         }
         const item = entry;
@@ -76,7 +77,7 @@ export function parseExternalToolchainsBlock(rec, config) {
 }
 function parseExternalToolRequirement(tool, index, toolIndex) {
     const label = `externalToolchains[${String(index)}].tools[${String(toolIndex)}]`;
-    if (typeof tool !== 'object' || tool === null || Array.isArray(tool)) {
+    if (!isObject(tool)) {
         throw new ConfigError(`Config field "${label}" must be an object`);
     }
     const toolRec = tool;

package/dist/src/core/config-validate.js

@@ -6,7 +6,7 @@ import { ConfigError } from '../errors/config.js';
 import { verbose } from '../utils/logger.js';
 import { parseObject } from '../utils/parse.js';
 import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.js';
-import { isValidAppId, isValidFirefoxCandidate, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, validateFirefoxProductVersionCompatibility, } from '../utils/validation.js';
+import { isObject, isValidAppId, isValidFirefoxCandidate, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, validateFirefoxProductVersionCompatibility, } from '../utils/validation.js';
 import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
 import { parsePatchPolicyBlock } from './config-validate-patch-policy.js';
 import { parseExternalToolchainsBlock, parseTestBlock } from './config-validate-test-toolchains.js';
@@ -257,7 +257,7 @@ const PATCH_LINT_CHECKJS_COMPILER_OPTION_KEYS = [
  * be typed from their real sources without an ambient stub shim.
  */
 function parseCheckJsPathsMapping(raw) {
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    if (!isObject(raw)) {
         throw new ConfigError('Config field "patchLint.checkJsCompilerOptions.paths" must be a plain object');
     }
     const rec = raw;
@@ -274,7 +274,7 @@ function parseCheckJsPathsMapping(raw) {
     return out;
 }
 function parsePatchLintCheckJsCompilerOptions(raw) {
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    if (!isObject(raw)) {
         throw new ConfigError('Config field "patchLint.checkJsCompilerOptions" must be a plain object');
     }
     const rec = raw;
@@ -304,22 +304,35 @@ function parseSeverityGate(raw, label) {
     }
     return raw;
 }
+/**
+ * Reads an optional boolean `patchLint` field, rejecting a non-boolean with
+ * the field-named message. Three identical inline copies of this shape were
+ * part of what held `parsePatchLintBlock` at complexity 25/30.
+ */
+function optionalPatchLintBoolean(rec, key) {
+    const value = rec.raw(key);
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean') {
+        throw new ConfigError(`Config field "patchLint.${key}" must be a boolean`);
+    }
+    return value;
+}
+/** Severity-gate fields, each parsed and assigned identically. */
+const PATCH_LINT_SEVERITY_GATE_KEYS = [
+    'jsdocClassMethods',
+    'testAssertionFloor',
+    'chromeScriptJsDoc',
+    'undefinedIdentifiers',
+];
 function parsePatchLintBlock(rec) {
     const out = {};
-    const checkJs = rec.raw('checkJs');
-    if (checkJs !== undefined) {
-        if (typeof checkJs !== 'boolean') {
-            throw new ConfigError('Config field "patchLint.checkJs" must be a boolean');
-        }
+    const checkJs = optionalPatchLintBoolean(rec, 'checkJs');
+    if (checkJs !== undefined)
         out.checkJs = checkJs;
-    }
-    const checkJsStrict = rec.raw('checkJsStrict');
-    if (checkJsStrict !== undefined) {
-        if (typeof checkJsStrict !== 'boolean') {
-            throw new ConfigError('Config field "patchLint.checkJsStrict" must be a boolean');
-        }
+    const checkJsStrict = optionalPatchLintBoolean(rec, 'checkJsStrict');
+    if (checkJsStrict !== undefined)
         out.checkJsStrict = checkJsStrict;
-    }
     const checkJsCompilerOptionsRaw = rec.raw('checkJsCompilerOptions');
     if (checkJsCompilerOptionsRaw !== undefined) {
         out.checkJsCompilerOptions = parsePatchLintCheckJsCompilerOptions(checkJsCompilerOptionsRaw);
@@ -328,6 +341,13 @@ function parsePatchLintBlock(rec) {
     if (checkJsExtraShim !== undefined) {
         out.checkJsExtraShim = parseShimPath(checkJsExtraShim, 'patchLint.checkJsExtraShim');
     }
+    const checkJsTestFiles = optionalPatchLintBoolean(rec, 'checkJsTestFiles');
+    if (checkJsTestFiles !== undefined)
+        out.checkJsTestFiles = checkJsTestFiles;
+    const checkJsTestShim = rec.raw('checkJsTestShim');
+    if (checkJsTestShim !== undefined) {
+        out.checkJsTestShim = parseShimPath(checkJsTestShim, 'patchLint.checkJsTestShim');
+    }
     const rawColorAllowlist = rec.raw('rawColorAllowlist');
     if (rawColorAllowlist !== undefined) {
         if (!Array.isArray(rawColorAllowlist) ||
@@ -336,21 +356,10 @@ function parsePatchLintBlock(rec) {
         }
         out.rawColorAllowlist = rawColorAllowlist;
     }
-    const jsdocClassMethods = parseSeverityGate(rec.raw('jsdocClassMethods'), 'patchLint.jsdocClassMethods');
-    if (jsdocClassMethods !== undefined) {
-        out.jsdocClassMethods = jsdocClassMethods;
-    }
-    const testAssertionFloor = parseSeverityGate(rec.raw('testAssertionFloor'), 'patchLint.testAssertionFloor');
-    if (testAssertionFloor !== undefined) {
-        out.testAssertionFloor = testAssertionFloor;
-    }
-    const chromeScriptJsDoc = parseSeverityGate(rec.raw('chromeScriptJsDoc'), 'patchLint.chromeScriptJsDoc');
-    if (chromeScriptJsDoc !== undefined) {
-        out.chromeScriptJsDoc = chromeScriptJsDoc;
-    }
-    const undefinedIdentifiers = parseSeverityGate(rec.raw('undefinedIdentifiers'), 'patchLint.undefinedIdentifiers');
-    if (undefinedIdentifiers !== undefined) {
-        out.undefinedIdentifiers = undefinedIdentifiers;
+    for (const key of PATCH_LINT_SEVERITY_GATE_KEYS) {
+        const gate = parseSeverityGate(rec.raw(key), `patchLint.${key}`);
+        if (gate !== undefined)
+            out[key] = gate;
     }
     if (out.checkJsStrict === true && out.checkJs !== true) {
         throw new ConfigError('Config field "patchLint.checkJsStrict" requires "patchLint.checkJs": true');
@@ -358,6 +367,12 @@ function parsePatchLintBlock(rec) {
     if (out.checkJsCompilerOptions !== undefined && out.checkJsStrict !== true) {
         throw new ConfigError('Config field "patchLint.checkJsCompilerOptions" requires "patchLint.checkJsStrict": true');
     }
+    if (out.checkJsTestFiles === true && out.checkJs !== true) {
+        throw new ConfigError('Config field "patchLint.checkJsTestFiles" requires "patchLint.checkJs": true');
+    }
+    if (out.checkJsTestShim !== undefined && out.checkJsTestFiles !== true) {
+        throw new ConfigError('Config field "patchLint.checkJsTestShim" requires "patchLint.checkJsTestFiles": true');
+    }
     return out;
 }
 /**

package/dist/src/core/config.js

@@ -12,6 +12,7 @@ import { basename } from 'node:path';
 import { ConfigError, ConfigNotFoundError } from '../errors/config.js';
 import { toError } from '../utils/errors.js';
 import * as fsUtils from '../utils/fs.js';
+import { isObject } from '../utils/validation.js';
 import { getProjectPaths } from './config-paths.js';
 import { validateConfig } from './config-validate.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
@@ -21,9 +22,21 @@ export { CONFIG_FILENAME, FIREFORGE_DIR, getProjectPaths, STATE_FILENAME, SUPPOR
 export { loadState, saveState, updateState } from './config-state.js';
 export { validateConfig } from './config-validate.js';
 // ---- config I/O (stays here because it bridges paths + validation) ----
+/**
+ * Config-file existence probe.
+ *
+ * Uses {@link pathExistsStrict} deliberately: a permission error probing
+ * `fireforge.json` must propagate rather than read as "no config here", which
+ * is what plain `pathExists` would report.
+ *
+ * The `fsUtils as typeof fsUtils & { pathExistsStrict?: … }` cast this
+ * replaced re-declared a real, non-optional export as optional so a partial
+ * `vi.mock` of `utils/fs.js` would fall back to `pathExists` — production code
+ * shaped around a test double, and shaped around the *wrong* function, since
+ * the two differ precisely on whether EACCES propagates.
+ */
 async function configPathExists(path) {
-    const fs = fsUtils;
-    return (fs.pathExistsStrict ?? fsUtils.pathExists)(path);
+    return fsUtils.pathExistsStrict(path);
 }
 /**
  * Checks if a fireforge.json exists in the given directory.
@@ -79,7 +92,7 @@ export async function loadRawConfigDocument(root) {
     }
     try {
         const data = await fsUtils.readJson(paths.config);
-        if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        if (!isObject(data)) {
             throw new ConfigError(`Invalid fireforge.json at ${paths.config}: expected an object`);
         }
         return data;

package/dist/src/core/coverage-extend.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `test --build/--build-only --extend-coverage` (FORGE L1): unions the
+ * requested paths into the recorded `testPackagingCoverage` instead of
+ * replacing it, under an anchor guard.
+ *
+ * Coverage REPLACES by default for a documented reason
+ * (`build-baseline-types.ts`): every baseline write refreshes
+ * `packageableFingerprints` for ALL dirty packageable paths, so a blind
+ * union would whitewash an earlier scope's edited fixtures while
+ * `obj-*`/`_tests/` still holds that scope's stale staging. Extending is
+ * honest only while everything the PREVIOUS record vouched for is still
+ * true, which is what {@link checkExtendCoverageAnchor} and
+ * {@link checkExtendMozconfigAnchor} verify:
+ *
+ *   1. engine HEAD is unchanged — every committed edit is excluded;
+ *   2. every path the previous baseline fingerprinted still hashes to the
+ *      recorded digest — the earlier scope's staging inputs are byte-identical.
+ *      Files that became dirty SINCE that build are fine: the current
+ *      whole-tree `mach build faster` repackages `dist/` and vouches for them;
+ *   3. the generated `engine/mozconfig` is unchanged. Engine HEAD does not
+ *      cover this — the mozconfig is regenerated from project-side
+ *      `configs/*.mozconfig` templates plus `fireforge.json` on every build,
+ *      so two builds at the same engine SHA can configure differently.
+ *
+ * Every failure refuses fail-closed; the operator's remedy is always a plain
+ * scoped build, which resets the claim to the paths it actually vouches for.
+ *
+ * Known boundary, documented rather than closed: dirty NON-packageable
+ * fixtures under previously covered paths (plain test files, manifests
+ * `isPackageablePath` rejects) are invisible to check 2. Editing one
+ * uncommitted between two builds leaves the earlier scope's `_tests/`
+ * staging stale while extend still vouches for it. Plain REPLACE has no
+ * such window, because the earlier scope simply stops being covered.
+ */
+import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline-types.js';
+/** Why `--extend-coverage` could not union onto the recorded claim. */
+export type ExtendAnchorReason = 'no-baseline' | 'no-fingerprints' | 'no-mozconfig-hash' | 'head-moved' | 'fingerprint-diverged' | 'mozconfig-changed';
+/** Outcome of an anchor check: either extend is sound, or it is refused. */
+export type ExtendAnchorResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: ExtendAnchorReason;
+    detail: string[];
+};
+/**
+ * Verifies the parts of the anchor knowable before the build runs: a usable
+ * previous baseline, an unchanged engine HEAD, and byte-identical content
+ * for every path that baseline fingerprinted.
+ * @param engineDir - Path to the engine directory
+ * @param previousBaseline - Baseline recorded by the previous build
+ */
+export declare function checkExtendCoverageAnchor(engineDir: string, previousBaseline: BuildBaseline | undefined): Promise<ExtendAnchorResult>;
+/**
+ * Verifies the mozconfig half of the anchor. Split from
+ * {@link checkExtendCoverageAnchor} because it can only run AFTER
+ * `prepareBuildEnvironment` regenerates `engine/mozconfig` — that file is
+ * the one this build will configure with — and must still run BEFORE mach,
+ * so a refusal costs no build time.
+ * @param engineDir - Path to the engine directory
+ * @param previousBaseline - Baseline recorded by the previous build
+ */
+export declare function checkExtendMozconfigAnchor(engineDir: string, previousBaseline: BuildBaseline | undefined): Promise<ExtendAnchorResult>;
+/**
+ * Unions the newly built paths onto the recorded claim. A `'full'` claim
+ * (or a pre-0.37.0 absent one, which means full historically) stays
+ * `'full'` — it already covers everything.
+ * @param previous - Coverage recorded by the previous build
+ * @param requested - Normalized request paths this build packaged
+ */
+export declare function unionTestPackagingCoverage(previous: TestPackagingCoverage | undefined, requested: readonly string[]): TestPackagingCoverage;
+/**
+ * Renders the fail-closed refusal for an anchor check that did not pass.
+ * Kept separate from the probes so tests can assert the structured result
+ * without matching copy.
+ * @param result - Failing result from an anchor check
+ */
+export declare function formatExtendCoverageRefusal(result: {
+    reason: ExtendAnchorReason;
+    detail: string[];
+}): string;
+/**
+ * Hex-encoded SHA-256 of an engine-relative file, matching the digest the
+ * baseline writer produces. `undefined` on any IO error, which every caller
+ * treats as "cannot prove unchanged" — i.e. a refusal.
+ * @param engineDir - Path to the engine directory
+ * @param relPath - Engine-relative POSIX path
+ */
+export declare function hashEngineFile(engineDir: string, relPath: string): Promise<string | undefined>;