@hominis/fireforge 0.39.0 → 0.41.0

package/dist/src/core/tree-store.js

@@ -0,0 +1,452 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Verification-tree storage and lifecycle for `fireforge tree` (FORGE G15).
+ *
+ * A tree is a FULL project-root CoW snapshot under
+ * `.fireforge/trees/<name>` — `getProjectRoot()` walks up from cwd, so
+ * every read command (status, lint, typecheck, verify, doctor,
+ * `export --dry-run`) runs inside the tree unmodified and its build /
+ * engine-session locks key on the tree root automatically. Trees are
+ * snapshots by design: there is no merge-back model, mutation commands
+ * are refused via the tree marker (see `tree-guard.ts`), and refresh is
+ * `tree remove` + `tree create`.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { lstat, readdir, readFile, realpath, rm } from 'node:fs/promises';
+import { basename, join, resolve, sep } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { mapWithConcurrency } from '../utils/concurrency.js';
+import { getNodeErrorCode, isProcessAlive, toError } from '../utils/errors.js';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { verbose, warn } from '../utils/logger.js';
+import { isObject } from '../utils/validation.js';
+import { getBuildBaselinePath } from './build-baseline.js';
+import { LOCK_PID_FILE, withFileLock } from './file-lock.js';
+import { git } from './git-base.js';
+import { getAllDiff } from './git-diff.js';
+import { attemptMozinfoRewrite } from './mach-build-artifacts.js';
+import { cloneEntry } from './tree-cow.js';
+const TREE_MARKER_FILENAME = 'tree.json';
+const TREES_DIRNAME = 'trees';
+const TREE_CLONE_CONCURRENCY = 8;
+/**
+ * Top-level entries never cloned into a tree: per-tree state must start
+ * clean (`.fireforge/`), locks are never inherited, the destructive-
+ * operation audit log stays primary-only, and dependency dirs are
+ * neither needed nor cheap.
+ */
+function isExcludedRootEntry(name) {
+    return (name === '.fireforge' ||
+        name === 'node_modules' ||
+        name === '.fireforge-history.jsonl' ||
+        name.endsWith('.lock'));
+}
+/** Absolute trees directory for a primary root. */
+export function getTreesDir(primaryRoot) {
+    return join(primaryRoot, '.fireforge', TREES_DIRNAME);
+}
+/** Serialises tree create/remove against each other (primary-side sidecar lock). */
+export async function withTreeLifecycleLock(primaryRoot, operation) {
+    return withFileLock(join(primaryRoot, '.fireforge', 'trees.lock'), operation, {
+        timeoutMs: 30_000,
+        onTimeoutMessage: 'Another fireforge tree create/remove is in progress. Wait for it to finish, then retry.',
+    });
+}
+/**
+ * Validates every field of a tree marker.
+ *
+ * The read below checked only `schemaVersion` and `name` and asserted the
+ * rest, but the unvalidated fields are consumed unguarded: `primaryRoot`
+ * reaches a user-facing refusal message (`tree-guard.ts:105`), and
+ * `engineHead`/`patchesFingerprint` feed the staleness compare, where an
+ * `undefined` from a truncated marker reports every tree as stale.
+ */
+function isTreeMarker(value) {
+    if (!isObject(value))
+        return false;
+    return (value['schemaVersion'] === 1 &&
+        typeof value['name'] === 'string' &&
+        typeof value['primaryRoot'] === 'string' &&
+        typeof value['createdAt'] === 'string' &&
+        (typeof value['engineHead'] === 'string' || value['engineHead'] === null) &&
+        (value['engineFingerprint'] === undefined ||
+            typeof value['engineFingerprint'] === 'string' ||
+            value['engineFingerprint'] === null) &&
+        (typeof value['patchesFingerprint'] === 'string' || value['patchesFingerprint'] === null) &&
+        (value['clonedObjdir'] === undefined || typeof value['clonedObjdir'] === 'string'));
+}
+/** Absolute path of a root's tree marker. */
+export function getTreeMarkerPath(root) {
+    return join(root, '.fireforge', TREE_MARKER_FILENAME);
+}
+/**
+ * Reads the tree marker for a project root, distinguishing "not a tree" from
+ * "a tree whose marker we could not read". Callers that make a safety decision
+ * (the guard hook, the no-nesting refusal) must use this rather than
+ * {@link readTreeMarker}.
+ *
+ * Only ENOENT/ENOTDIR mean `absent`: any other probe failure (EACCES on the
+ * `.fireforge` directory, EIO, …) reports `corrupt`, because "we cannot read
+ * the marker" is not evidence that there is no marker — a `pathExists`
+ * pre-check here classified a tree with an unreadable `.fireforge` as
+ * `absent` and handed it the full mutating command set.
+ */
+export async function readTreeMarkerState(root) {
+    const markerPath = getTreeMarkerPath(root);
+    try {
+        const raw = await readJson(markerPath);
+        if (!isTreeMarker(raw)) {
+            verbose(`Malformed tree marker at ${markerPath}`);
+            return { kind: 'corrupt', reason: 'the marker is missing or mistypes a required field' };
+        }
+        return { kind: 'valid', marker: raw };
+    }
+    catch (error) {
+        const code = getNodeErrorCode(error);
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return { kind: 'absent' };
+        verbose(`Unreadable tree marker at ${markerPath}: ${String(error)}`);
+        return { kind: 'corrupt', reason: `the marker could not be read (${toError(error).message})` };
+    }
+}
+/**
+ * Reads the tree marker for a project root, or undefined when it is absent
+ * OR unreadable.
+ *
+ * For display and best-effort paths only (`tree list` renders an unreadable
+ * marker as staleness 'unknown'). Anything that decides whether a mutation may
+ * proceed must call {@link readTreeMarkerState} and handle `corrupt`.
+ */
+export async function readTreeMarker(root) {
+    const state = await readTreeMarkerState(root);
+    return state.kind === 'valid' ? state.marker : undefined;
+}
+/**
+ * Refuses a build-less in-tree `test` when the objdir preflight found is not
+ * the one this tree's marker vouched for as rewritten-and-reconfigured. A
+ * mismatch means an objdir appeared in the tree through some path other than
+ * `tree create --with-objdir` (manual copy, partial restore), so nothing
+ * proves it was relocated — running against it could consult primary paths.
+ * No-op outside a tree; a corrupt marker is already refused by the guard.
+ */
+export async function assertObjdirMatchesTreeMarker(projectRoot, objDir) {
+    const state = await readTreeMarkerState(projectRoot);
+    if (state.kind !== 'valid' || state.marker.clonedObjdir === undefined)
+        return;
+    if (objDir !== state.marker.clonedObjdir) {
+        throw new GeneralError(`This verification tree's marker records "${state.marker.clonedObjdir}" as its cloned build, ` +
+            `but the preflight found ${objDir === undefined ? 'no objdir' : `"${objDir}"`}. ` +
+            'Only the objdir cloned by tree create --with-objdir is proven to be relocated to this tree. ' +
+            'Remove and re-create the tree (fireforge tree remove/create).');
+    }
+}
+/** Current primary-side snapshot identity, including dirty source and patch bodies. */
+export async function computePrimaryFingerprint(primaryRoot) {
+    const engineDir = join(primaryRoot, 'engine');
+    let engineHead;
+    try {
+        engineHead = (await git(['rev-parse', 'HEAD'], engineDir)).trim();
+    }
+    catch {
+        // An engine that is missing, unborn, or not a git checkout has no HEAD to
+        // fingerprint. `null` is a legal marker value and reads as 'unknown', which
+        // `listTrees` renders as staleness 'unknown' rather than a false 'fresh'.
+        engineHead = null;
+    }
+    let engineFingerprint;
+    try {
+        engineFingerprint = createHash('sha256')
+            .update(await getAllDiff(engineDir))
+            .digest('hex');
+    }
+    catch {
+        engineFingerprint = null;
+    }
+    const patchesDir = join(primaryRoot, 'patches');
+    let patchesFingerprint = null;
+    try {
+        if (await pathExists(patchesDir)) {
+            const hash = createHash('sha256');
+            for (const name of (await readdir(patchesDir))
+                .filter((entry) => entry.endsWith('.patch') || entry === 'patches.json')
+                .sort()) {
+                hash
+                    .update(name)
+                    .update('\0')
+                    .update(await readFile(join(patchesDir, name)))
+                    .update('\0');
+            }
+            patchesFingerprint = hash.digest('hex');
+        }
+    }
+    catch {
+        patchesFingerprint = null;
+    }
+    return { engineHead, engineFingerprint, patchesFingerprint };
+}
+/** Validates a tree name: one path segment, no traversal. */
+export function assertValidTreeName(name) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name.includes('..')) {
+        throw new GeneralError(`Invalid tree name "${name}". Use a single path segment of letters, digits, ".", "_" or "-".`);
+    }
+}
+/**
+ * Refuses an objdir that is not a plain directory physically inside
+ * `engineDir` — every `cp` mode `cloneEntry` uses preserves symlinks, so
+ * a symlinked `engine/obj-*` would be cloned as a symlink pointing back
+ * at the original (primary or fully external) build, and the clone's
+ * mozinfo rewrite and `_virtualenvs` removal would then mutate that
+ * original through the link. Checks lstat (the entry itself must be a
+ * real directory) AND realpath containment (a real directory reached
+ * through a symlinked parent resolves elsewhere) — the rewriter's
+ * lexical `resolve()` paths cannot detect either. Also validates the
+ * name as a single `obj-*` path segment. Role `'primary'` guards before
+ * any copying starts; `'cloned'` re-checks the tree's copy before any
+ * write goes through it (defense in depth).
+ */
+async function assertCloneSafeObjdir(engineDir, objDir, role) {
+    const where = role === 'primary' ? 'engine/' : "the tree's engine/";
+    if (!/^obj-[A-Za-z0-9][A-Za-z0-9._-]*$/.test(objDir) || objDir.includes('..')) {
+        throw new GeneralError(`Invalid objdir name "${objDir}". Expected a single obj-* path segment of letters, digits, ".", "_" or "-".`);
+    }
+    const objDirPath = join(engineDir, objDir);
+    let stats;
+    try {
+        stats = await lstat(objDirPath);
+    }
+    catch (error) {
+        throw new GeneralError(`tree create --with-objdir cannot stat ${where}${objDir}: ${toError(error).message}`);
+    }
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+        throw new GeneralError(`tree create --with-objdir refuses ${where}${objDir}: it is ${stats.isSymbolicLink() ? 'a symlink' : 'not a directory'}. A cloned symlinked objdir would be rewritten through the link, mutating the ` +
+            'original build it points at. Replace it with a real directory or create the tree ' +
+            'without --with-objdir.');
+    }
+    const [realObjDir, realEngineDir] = await Promise.all([
+        realpath(objDirPath),
+        realpath(engineDir),
+    ]);
+    if (realObjDir !== join(realEngineDir, objDir)) {
+        throw new GeneralError(`tree create --with-objdir refuses ${where}${objDir}: it resolves to ${realObjDir}, ` +
+            `outside ${realEngineDir}. An objdir reached through a symlink would be rewritten ` +
+            'in place, mutating the original build. Replace it with a real directory or create ' +
+            'the tree without --with-objdir.');
+    }
+}
+/**
+ * Materialises the tree at `treeRoot` from `primaryRoot` using
+ * `capability` ('none' = plain copy, already gated on --force-copy by
+ * the caller). The engine is cloned one TOP-LEVEL entry at a time so unwanted
+ * `obj-*` directories are never traversed or materialised. That distinction
+ * is substantial on Firefox trees: even CoW-cloning and deleting an objdir
+ * touches metadata for millions of build outputs. With `withObjdir` exactly
+ * that objdir is included — after {@link assertCloneSafeObjdir}
+ * refuses symlinked or engine-escaping objdirs before any copying —
+ * rewritten to the tree (see below), and
+ * reconfigured in-tree via the caller-supplied `reconfigure` hook. A
+ * fresh `.fireforge/` is created with only `state.json` (when present),
+ * the last-build baseline (withObjdir only), and the tree marker.
+ */
+export async function cloneTree(args) {
+    const { primaryRoot, treeRoot, name, capability, createdAt, withObjdir } = args;
+    const { mkdir, cp } = await import('node:fs/promises');
+    if (withObjdir) {
+        // Refuse a symlinked/escaping primary objdir BEFORE any copying: the
+        // clone would carry the symlink and every later write would land in
+        // the original build (see assertCloneSafeObjdir).
+        await assertCloneSafeObjdir(join(primaryRoot, 'engine'), withObjdir.objDir, 'primary');
+    }
+    await mkdir(treeRoot, { recursive: true });
+    const rootEntries = (await readdir(primaryRoot)).filter((entry) => !isExcludedRootEntry(entry));
+    const engineDir = join(treeRoot, 'engine');
+    await mapWithConcurrency(rootEntries, TREE_CLONE_CONCURRENCY, async (entry) => {
+        if (entry !== 'engine') {
+            await cloneEntry(capability, join(primaryRoot, entry), join(treeRoot, entry));
+            return;
+        }
+        const primaryEngineDir = join(primaryRoot, 'engine');
+        await mkdir(engineDir, { recursive: true });
+        const engineEntries = (await readdir(primaryEngineDir)).filter((engineEntry) => !engineEntry.startsWith('obj-') || engineEntry === withObjdir?.objDir);
+        await mapWithConcurrency(engineEntries, TREE_CLONE_CONCURRENCY, async (engineEntry) => {
+            await cloneEntry(capability, join(primaryEngineDir, engineEntry), join(engineDir, engineEntry));
+        });
+    });
+    // A selected objdir embeds absolute topsrcdir/topobjdir paths back into
+    // the PRIMARY tree. It is rewritten below before the marker records it as
+    // usable; no other objdir ever enters the snapshot.
+    if (await pathExists(engineDir)) {
+        // Defensive: never inherit a mid-operation git index lock.
+        await rm(join(engineDir, '.git', 'index.lock'), { force: true });
+    }
+    if (withObjdir) {
+        await rewriteClonedObjdir(engineDir, withObjdir.objDir);
+        // Regenerate configure output (config.status, backend.mk, Makefile,
+        // config/autoconf.mk) against the tree's paths — the mozinfo rewrite
+        // alone leaves those naming the primary. A failed reconfigure throws
+        // before the marker below records the objdir as usable (fail-closed).
+        await withObjdir.reconfigure(engineDir);
+    }
+    await mkdir(join(treeRoot, '.fireforge'), { recursive: true });
+    const stateJson = join(primaryRoot, '.fireforge', 'state.json');
+    if (await pathExists(stateJson)) {
+        await cp(stateJson, join(treeRoot, '.fireforge', 'state.json'));
+    }
+    if (withObjdir) {
+        // The in-tree stale-build and static-components gates anchor on the
+        // last-build baseline; without the copy they would read `undefined`
+        // and degrade to first-build semantics inside a fully built tree.
+        const baseline = getBuildBaselinePath(primaryRoot);
+        if (await pathExists(baseline)) {
+            await cp(baseline, getBuildBaselinePath(treeRoot));
+        }
+    }
+    const { engineHead, engineFingerprint, patchesFingerprint } = await computePrimaryFingerprint(primaryRoot);
+    const marker = {
+        schemaVersion: 1,
+        name,
+        primaryRoot,
+        createdAt,
+        engineHead,
+        engineFingerprint: engineFingerprint ?? null,
+        patchesFingerprint,
+        ...(withObjdir ? { clonedObjdir: withObjdir.objDir } : {}),
+    };
+    await writeJson(join(treeRoot, '.fireforge', TREE_MARKER_FILENAME), marker);
+    return marker;
+}
+/**
+ * Points the cloned objdir at the tree: rewrites mozinfo.json's
+ * topsrcdir/topobjdir (and an in-tree mozconfig) via the same
+ * safe-relocation rewriter `build --rewrite-mozinfo` uses, refusing
+ * fail-closed when its safety rules cannot prove the rewrite correct —
+ * a tree must never hold an objdir that still names the primary. Before
+ * any write, the cloned objdir is re-checked as a real directory inside
+ * the tree ({@link assertCloneSafeObjdir}) so no write ever goes through
+ * a symlink into the original build. The cloned `_virtualenvs` are
+ * removed outright: their scripts carry primary-tree shebang paths, and
+ * mach rebuilds venvs in-tree on first use. The configure-generated root
+ * files (config.status, backend.mk, Makefile, config/autoconf.mk) still
+ * name the primary after this rewrite; they are regenerated by the
+ * in-tree `mach configure` the caller supplies to {@link cloneTree},
+ * which runs before the marker is written.
+ */
+async function rewriteClonedObjdir(engineDir, objDir) {
+    await assertCloneSafeObjdir(engineDir, objDir, 'cloned');
+    const rewrite = await attemptMozinfoRewrite(engineDir, objDir);
+    if (!rewrite.rewritten) {
+        throw new GeneralError(`Cannot keep the cloned build: ${rewrite.reason ?? 'mozinfo.json rewrite refused'}. ` +
+            'The objdir would still operate against the primary tree. ' +
+            'Re-run tree create without --with-objdir, or rebuild the primary objdir with "fireforge build" and retry.');
+    }
+    await rm(join(engineDir, objDir, '_virtualenvs'), { recursive: true, force: true });
+}
+/** Lists trees with staleness against the current primary state. */
+export async function listTrees(primaryRoot) {
+    const treesDir = getTreesDir(primaryRoot);
+    if (!(await pathExists(treesDir)))
+        return [];
+    const current = await computePrimaryFingerprint(primaryRoot);
+    const entries = [];
+    for (const name of (await readdir(treesDir)).sort((a, b) => a.localeCompare(b))) {
+        if (name.endsWith('.lock'))
+            continue;
+        const path = join(treesDir, name);
+        const marker = await readTreeMarker(path);
+        if (!marker) {
+            entries.push({ name, path, createdAt: '(no marker)', staleness: 'unknown' });
+            continue;
+        }
+        const staleness = marker.engineHead !== current.engineHead
+            ? 'stale (engine advanced)'
+            : marker.engineFingerprint !== undefined &&
+                marker.engineFingerprint !== current.engineFingerprint
+                ? 'stale (engine worktree changed)'
+                : marker.patchesFingerprint !== current.patchesFingerprint
+                    ? 'stale (patches changed)'
+                    : 'fresh';
+        entries.push({ name, path, createdAt: marker.createdAt, staleness });
+    }
+    return entries;
+}
+/**
+ * Classifies a mkdir-style lock directory. Reads the lock's owner file
+ * directly (line 1 = PID — the format `file-lock.ts` documents as stable,
+ * whose name it shares via {@link LOCK_PID_FILE}) instead of exporting
+ * file-lock internals.
+ *
+ * Liveness comes from the shared {@link isProcessAlive}, which treats EPERM
+ * as alive. The local copy this replaced returned `false` for EPERM, so a
+ * tree whose build lock was held by a live process running under a different
+ * uid passed the guard below and was `rm -rf`'d mid-build.
+ *
+ * The `unknown` state is not a theoretical case. `withFileLock` takes the lock
+ * by creating the directory and only *then* writes the owner file, treating a
+ * write failure as non-fatal — so every acquisition passes through a window in
+ * which the lock is genuinely held and has no readable PID, and a read-only or
+ * full filesystem leaves it that way for the lock's whole life. Reporting that
+ * as `free` let `removeTree` recursively delete a tree out from under a live
+ * build. `file-lock.ts` reaches the same conclusion for its own stale
+ * recovery, where an unreadable PID falls back to an age-only heuristic rather
+ * than assuming the lock is abandoned.
+ */
+async function inspectTreeLock(lockPath) {
+    if (!existsSync(lockPath))
+        return { kind: 'free' };
+    let pidLine;
+    try {
+        pidLine = (await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8')).split('\n')[0] ?? '';
+    }
+    catch (error) {
+        // A lock cleanly released between the existence probe above and this read
+        // leaves no directory behind — that is a release, not an unreadable owner,
+        // and demanding --force for it would be a spurious refusal.
+        if (!existsSync(lockPath))
+            return { kind: 'free' };
+        return {
+            kind: 'unknown',
+            reason: `its owner record is missing or unreadable (${toError(error).message})`,
+        };
+    }
+    const pid = parseInt(pidLine.trim(), 10);
+    if (!Number.isFinite(pid)) {
+        return { kind: 'unknown', reason: 'its owner record does not name a process id' };
+    }
+    return isProcessAlive(pid) ? { kind: 'held', pid } : { kind: 'free' };
+}
+/**
+ * Removes one tree. Refuses when a live process holds the tree's build
+ * or engine-session lock — or when a lock directory exists whose ownership
+ * cannot be established, which `--force` overrides — and never deletes a path
+ * outside the trees directory (containment check before `rm -rf`).
+ */
+export async function removeTree(primaryRoot, name, options = {}) {
+    assertValidTreeName(name);
+    const treesDir = getTreesDir(primaryRoot);
+    const treeRoot = resolve(treesDir, name);
+    if (!treeRoot.startsWith(treesDir + sep) || basename(treeRoot) !== name) {
+        throw new GeneralError(`Refusing to remove "${name}": resolved path escapes the trees directory.`);
+    }
+    if (!(await pathExists(treeRoot))) {
+        throw new GeneralError(`No verification tree named "${name}" exists under ${treesDir}.`);
+    }
+    for (const lockPath of [
+        join(treeRoot, '.fireforge-build.lock'),
+        join(treeRoot, '.fireforge', 'engine-session.lock'),
+    ]) {
+        const state = await inspectTreeLock(lockPath);
+        if (state.kind === 'held') {
+            throw new GeneralError(`Refusing to remove tree "${name}": a live process (pid ${String(state.pid)}) holds ${lockPath}. ` +
+                'Wait for it to finish, then retry.');
+        }
+        if (state.kind === 'unknown' && options.force !== true) {
+            throw new GeneralError(`Refusing to remove tree "${name}": ${lockPath} exists but ${state.reason}, so it may be ` +
+                'held by a live process. Wait for any in-flight build or test to finish; if none is ' +
+                'running, re-run with --force to delete the tree and the stale lock.');
+        }
+        if (state.kind === 'unknown') {
+            warn(`Removing tree "${name}" through ${lockPath}, whose ownership is unknown (--force).`);
+        }
+    }
+    await rm(treeRoot, { recursive: true, force: true });
+}

package/dist/src/core/typecheck-shim.d.ts

@@ -11,6 +11,20 @@
  */
 /** Filename used for the synthetic Firefox-globals shim source file. */
 export declare const SHIM_FILENAME = "__fireforge_firefox_globals.d.ts";
+/**
+ * Loose declarations for Firefox test-harness globals (mochitest
+ * browser-chrome and xpcshell), appended AFTER the composed
+ * Firefox-globals + consumer shim when `patchLint.checkJsTestFiles`
+ * extends the checkJs pass to patch-adopted test scripts (FORGE G5).
+ * Deliberately `any`-typed — the pragmatic posture matches the main
+ * shim. A consumer that wants TYPED harness members (so e.g. a call to
+ * a method the harness does not declare fails at the patch boundary)
+ * declares them in `patchLint.checkJsTestShim`; because that shim
+ * composes BEFORE this baseline and TypeScript resolves conflicting
+ * `declare var` redeclarations to the FIRST declaration, the typed
+ * consumer declaration wins over the loose fallback here.
+ */
+export declare const TEST_HARNESS_SHIM = "\n// \u2500\u2500 FireForge test-harness shim (loose baseline) \u2500\u2500\ndeclare var TestUtils: any;\ndeclare var BrowserTestUtils: any;\ndeclare var SpecialPowers: any;\ndeclare var EventUtils: any;\ndeclare var SimpleTest: any;\ndeclare var Assert: any;\ndeclare var gTestPath: string;\ndeclare var content: any;\ndeclare function add_task(task: (...args: any[]) => any): any;\ndeclare function add_setup(task: (...args: any[]) => any): any;\ndeclare function ok(condition: any, message?: string): void;\ndeclare function is(actual: any, expected: any, message?: string): void;\ndeclare function isnot(actual: any, expected: any, message?: string): void;\ndeclare function todo(condition: any, message?: string): void;\ndeclare function todo_is(actual: any, expected: any, message?: string): void;\ndeclare function info(message: string): void;\ndeclare function registerCleanupFunction(callback: (...args: any[]) => any): void;\ndeclare function waitForExplicitFinish(): void;\ndeclare function finish(): void;\ndeclare function do_get_profile(): any;\ndeclare function run_test(): any;\n\n";
 /**
  * TS diagnostic codes suppressed by both the patch-lint checkJs pass
  * and the whole-project typecheck command. Each is a known false

package/dist/src/core/typecheck-shim.js

@@ -128,6 +128,44 @@ declare var Localization: LocalizationShim;
 declare module 'resource:*';
 declare module 'chrome:*';
 
+`;
+/**
+ * Loose declarations for Firefox test-harness globals (mochitest
+ * browser-chrome and xpcshell), appended AFTER the composed
+ * Firefox-globals + consumer shim when `patchLint.checkJsTestFiles`
+ * extends the checkJs pass to patch-adopted test scripts (FORGE G5).
+ * Deliberately `any`-typed — the pragmatic posture matches the main
+ * shim. A consumer that wants TYPED harness members (so e.g. a call to
+ * a method the harness does not declare fails at the patch boundary)
+ * declares them in `patchLint.checkJsTestShim`; because that shim
+ * composes BEFORE this baseline and TypeScript resolves conflicting
+ * `declare var` redeclarations to the FIRST declaration, the typed
+ * consumer declaration wins over the loose fallback here.
+ */
+export const TEST_HARNESS_SHIM = `
+// ── FireForge test-harness shim (loose baseline) ──
+declare var TestUtils: any;
+declare var BrowserTestUtils: any;
+declare var SpecialPowers: any;
+declare var EventUtils: any;
+declare var SimpleTest: any;
+declare var Assert: any;
+declare var gTestPath: string;
+declare var content: any;
+declare function add_task(task: (...args: any[]) => any): any;
+declare function add_setup(task: (...args: any[]) => any): any;
+declare function ok(condition: any, message?: string): void;
+declare function is(actual: any, expected: any, message?: string): void;
+declare function isnot(actual: any, expected: any, message?: string): void;
+declare function todo(condition: any, message?: string): void;
+declare function todo_is(actual: any, expected: any, message?: string): void;
+declare function info(message: string): void;
+declare function registerCleanupFunction(callback: (...args: any[]) => any): void;
+declare function waitForExplicitFinish(): void;
+declare function finish(): void;
+declare function do_get_profile(): any;
+declare function run_test(): any;
+
 `;
 /**
  * TS diagnostic codes suppressed by both the patch-lint checkJs pass
@@ -226,8 +264,9 @@ async function inlineTripleSlashReferences(source, baseDir, seen) {
  * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
  */
 export async function composeShimSource(projectRoot, extraShimPath) {
+    const base = FIREFOX_GLOBALS_SHIM;
     if (!extraShimPath) {
-        return { source: FIREFOX_GLOBALS_SHIM, extraShimAppended: false };
+        return { source: base, extraShimAppended: false };
     }
     const absoluteShim = resolve(projectRoot, extraShimPath);
     if (!(await pathExists(absoluteShim))) {
@@ -237,7 +276,7 @@ export async function composeShimSource(projectRoot, extraShimPath) {
     const extra = await readText(absoluteShim);
     const inlinedExtra = await inlineTripleSlashReferences(extra, dirname(absoluteShim), new Set([absoluteShim]));
     return {
-        source: `${FIREFOX_GLOBALS_SHIM}\n// ── extraShim: ${extraShimPath} ──\n${inlinedExtra}`,
+        source: `${base}\n// ── extraShim: ${extraShimPath} ──\n${inlinedExtra}`,
         extraShimAppended: true,
     };
 }

package/dist/src/core/typecheck.js

@@ -19,6 +19,7 @@
  * at `npm install typescript`.
  */
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
@@ -113,7 +114,7 @@ export async function runTypecheck(projectRoot, cfg) {
         catch (err) {
             // A missing or unreadable shim fails only the project(s) that use it,
             // not the whole run — projects with a different (or no) shim still run.
-            const message = err instanceof Error ? err.message : String(err);
+            const message = toError(err).message;
             results.push({
                 project: projectPath,
                 issues: [

package/dist/src/core/wire-destroy.js

@@ -8,7 +8,7 @@ import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { escapeRegex } from '../utils/regex.js';
-import { detectIndent, parseScript } from './ast-utils.js';
+import { asEstree, detectIndent, parseScript } from './ast-utils.js';
 import { withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, coerceToCall, extractNameFromExpression, findMethodBody, findMethodBraceIndex, validateWireName, } from './wire-utils.js';
 const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
@@ -36,7 +36,10 @@ export function addDestroyAST(content, expression, marker = DEFAULT_MARKER) {
         throw new BuildError('Could not find onUnload/uninit method body via AST');
     }
     // Insert at top of method body (LIFO ordering)
-    const firstStmt = body.body[0];
+    // `noUncheckedIndexedAccess` makes this `Statement | undefined`; narrow
+    // before casting rather than laundering the undefined through the cast.
+    const firstRaw = body.body[0];
+    const firstStmt = firstRaw ? asEstree(firstRaw) : undefined;
     let insertPos;
     let indent;
     if (firstStmt) {
@@ -114,7 +117,15 @@ export async function addDestroyToBrowserInit(engineDir, expression, marker = DE
     if (destroyPattern.test(content)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addDestroyAST(content, expression, marker), () => legacyAddDestroy(content, expression, marker), BROWSER_INIT_JS);
+    const { value, usedFallback } = withParserFallback(() => addDestroyAST(content, expression, marker), () => legacyAddDestroy(content, expression, marker), BROWSER_INIT_JS, 
+    // Rethrow only the internal-invariant GeneralErrors ("Unexpected empty
+    // …array"): those are programming bugs, and retrying the legacy scanner
+    // cannot fix a broken invariant — it just buries the stack. Everything
+    // else still falls back, which is load-bearing: the AST path raises a raw
+    // acorn SyntaxError on chrome sources acorn cannot parse (preprocessor
+    // directives), and BuildError when the file's shape is unexpected. Both
+    // are exactly what the legacy scanner is here to handle.
+    (error) => error instanceof GeneralError);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_INIT_JS);
     }