@hominis/fireforge 0.39.0 → 0.40.0

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

@@ -0,0 +1,214 @@
+// 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 { readdir, readFile, rm } from 'node:fs/promises';
+import { basename, join, resolve, sep } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { withFileLock } from './file-lock.js';
+import { git } from './git-base.js';
+import { cloneEntry } from './tree-cow.js';
+const TREE_MARKER_FILENAME = 'tree.json';
+const TREES_DIRNAME = 'trees';
+/**
+ * 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.',
+    });
+}
+/** Reads the tree marker for a project root, or undefined when not a tree. */
+export async function readTreeMarker(root) {
+    const markerPath = join(root, '.fireforge', TREE_MARKER_FILENAME);
+    if (!(await pathExists(markerPath)))
+        return undefined;
+    try {
+        const raw = await readJson(markerPath);
+        if (raw.schemaVersion !== 1 || typeof raw.name !== 'string')
+            return undefined;
+        return raw;
+    }
+    catch (error) {
+        verbose(`Unreadable tree marker at ${markerPath}: ${String(error)}`);
+        return undefined;
+    }
+}
+/** Current primary-side snapshot identity (engine HEAD + patches.json hash). */
+export async function computePrimaryFingerprint(primaryRoot) {
+    let engineHead;
+    try {
+        engineHead = (await git(['rev-parse', 'HEAD'], join(primaryRoot, 'engine'))).trim();
+    }
+    catch {
+        engineHead = null;
+    }
+    const patchesJson = join(primaryRoot, 'patches', 'patches.json');
+    const patchesFingerprint = (await pathExists(patchesJson))
+        ? createHash('sha256')
+            .update(await readFile(patchesJson))
+            .digest('hex')
+        : null;
+    return { engineHead, 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 "-".`);
+    }
+}
+/**
+ * Materialises the tree at `treeRoot` from `primaryRoot` using
+ * `capability` ('none' = plain copy, already gated on --force-copy by
+ * the caller). The engine tree is cloned whole and its `obj-*` build
+ * directories removed afterwards — CoW removal is cheap, and per-entry
+ * recursion into a Firefox tree is fragile. A fresh `.fireforge/` is
+ * created with only `state.json` (when present) and the tree marker.
+ */
+export async function cloneTree(args) {
+    const { primaryRoot, treeRoot, name, capability, createdAt } = args;
+    const { mkdir, cp } = await import('node:fs/promises');
+    await mkdir(treeRoot, { recursive: true });
+    for (const entry of await readdir(primaryRoot)) {
+        if (isExcludedRootEntry(entry))
+            continue;
+        await cloneEntry(capability, join(primaryRoot, entry), join(treeRoot, entry));
+    }
+    // A cloned objdir embeds absolute topsrcdir/topobjdir paths back into
+    // the PRIMARY tree (mach-build-artifacts.ts parses exactly those), so
+    // in-tree builds/tests would silently operate against the primary —
+    // remove the clones; `tree` is read-verification only in 0.40.0.
+    const engineDir = join(treeRoot, 'engine');
+    if (await pathExists(engineDir)) {
+        for (const entry of await readdir(engineDir)) {
+            if (entry.startsWith('obj-')) {
+                await rm(join(engineDir, entry), { recursive: true, force: true });
+            }
+        }
+        // Defensive: never inherit a mid-operation git index lock.
+        await rm(join(engineDir, '.git', 'index.lock'), { force: true });
+    }
+    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'));
+    }
+    const { engineHead, patchesFingerprint } = await computePrimaryFingerprint(primaryRoot);
+    const marker = {
+        schemaVersion: 1,
+        name,
+        primaryRoot,
+        createdAt,
+        engineHead,
+        patchesFingerprint,
+    };
+    await writeJson(join(treeRoot, '.fireforge', TREE_MARKER_FILENAME), marker);
+    return marker;
+}
+/** 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.patchesFingerprint !== current.patchesFingerprint
+                ? 'stale (patches changed)'
+                : 'fresh';
+        entries.push({ name, path, createdAt: marker.createdAt, staleness });
+    }
+    return entries;
+}
+/** Uses `kill(pid, 0)` — no signal sent, just an existence check. */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns the live holder PID of a mkdir-style lock directory, if any.
+ * Reads the lock's `pid` file directly (line 1 = PID — the format
+ * `file-lock.ts` documents as stable) instead of exporting file-lock
+ * internals.
+ */
+async function liveLockHolder(lockPath) {
+    try {
+        const pidLine = (await readFile(join(lockPath, 'pid'), 'utf-8')).split('\n')[0] ?? '';
+        const pid = parseInt(pidLine.trim(), 10);
+        if (Number.isFinite(pid) && isProcessAlive(pid))
+            return pid;
+    }
+    catch {
+        // No lock / unreadable pid file — treat as not held.
+    }
+    return undefined;
+}
+/**
+ * Removes one tree. Refuses when a live process holds the tree's build
+ * or engine-session lock, and never deletes a path outside the trees
+ * directory (containment check before `rm -rf`).
+ */
+export async function removeTree(primaryRoot, name) {
+    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 holder = await liveLockHolder(lockPath);
+        if (holder !== undefined) {
+            throw new GeneralError(`Refusing to remove tree "${name}": a live process (pid ${String(holder)}) holds ${lockPath}. ` +
+                'Wait for it to finish, then retry.');
+        }
+    }
+    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/xpcshell-profile-dir.d.ts

@@ -0,0 +1,12 @@
+export declare const XPCSHELL_PROFILE_ENV_VAR = "XPCSHELL_TEST_PROFILE_DIR";
+/**
+ * Runs `fn` with a fresh per-invocation xpcshell profile directory
+ * injected into the environment, removing the directory afterwards
+ * (best-effort — a failure to clean up warns and leaves the mkdtemp dir
+ * for the OS tmp reaper; the harness may still hold files briefly).
+ *
+ * An operator-provided `XPCSHELL_TEST_PROFILE_DIR` (in `baseEnv` or the
+ * process environment) is respected verbatim: no directory is minted and
+ * NOTHING is deleted — we never remove a directory we did not create.
+ */
+export declare function withXpcshellProfileDir<T>(baseEnv: Record<string, string> | undefined, fn: (env: Record<string, string>) => Promise<T>): Promise<T>;

package/dist/src/core/xpcshell-profile-dir.js

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Per-invocation xpcshell profile directory (FORGE G15b).
+ *
+ * Firefox's xpcshell harness defaults `XPCSHELL_TEST_PROFILE_DIR` to a
+ * FIXED path (`$TMPDIR/firefox/xpcshellprofile`), so two overlapping
+ * harness invocations — concurrent `fireforge test` processes, or future
+ * verification-tree shards — corrupt each other's profiles. FireForge
+ * never set the variable; this helper mints a fresh `mkdtemp` directory
+ * per harness invocation and exports it through the mach env channel.
+ */
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { warn } from '../utils/logger.js';
+export const XPCSHELL_PROFILE_ENV_VAR = 'XPCSHELL_TEST_PROFILE_DIR';
+/**
+ * Runs `fn` with a fresh per-invocation xpcshell profile directory
+ * injected into the environment, removing the directory afterwards
+ * (best-effort — a failure to clean up warns and leaves the mkdtemp dir
+ * for the OS tmp reaper; the harness may still hold files briefly).
+ *
+ * An operator-provided `XPCSHELL_TEST_PROFILE_DIR` (in `baseEnv` or the
+ * process environment) is respected verbatim: no directory is minted and
+ * NOTHING is deleted — we never remove a directory we did not create.
+ */
+export async function withXpcshellProfileDir(baseEnv, fn) {
+    const operatorProvided = baseEnv?.[XPCSHELL_PROFILE_ENV_VAR] ?? process.env[XPCSHELL_PROFILE_ENV_VAR];
+    if (operatorProvided !== undefined && operatorProvided !== '') {
+        return fn({ ...baseEnv, [XPCSHELL_PROFILE_ENV_VAR]: operatorProvided });
+    }
+    const profileDir = await mkdtemp(join(tmpdir(), 'fireforge-xpcshell-profile-'));
+    try {
+        return await fn({ ...baseEnv, [XPCSHELL_PROFILE_ENV_VAR]: profileDir });
+    }
+    finally {
+        try {
+            await rm(profileDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            warn(`Could not clean up xpcshell profile dir ${profileDir}: ${toError(error).message}`);
+        }
+    }
+}

package/dist/src/errors/git.d.ts

@@ -39,6 +39,14 @@ export declare class GitIndexLockError extends GitError {
     constructor(lockPath: string, ageMs?: number | undefined);
     get userMessage(): string;
 }
+/**
+ * Detects transient git `index.lock` contention — an external git process
+ * holding `.git/index.lock` while we stage or diff. Mirrors the message
+ * heuristics `core/git.ts` uses when wrapping stale-lock failures during
+ * download, but lives here so command modules can consult it without
+ * importing (frequently vi.mocked) core git internals.
+ */
+export declare function isGitIndexLockConflict(error: unknown): boolean;
 /**
  * Error thrown when `git add` (monolithic or chunked) exceeds the
  * configured timeout while indexing the Firefox source tree.

package/dist/src/errors/git.js

@@ -96,6 +96,23 @@ export class GitIndexLockError extends GitError {
             '  3. Re-run "fireforge download --force"');
     }
 }
+/**
+ * Detects transient git `index.lock` contention — an external git process
+ * holding `.git/index.lock` while we stage or diff. Mirrors the message
+ * heuristics `core/git.ts` uses when wrapping stale-lock failures during
+ * download, but lives here so command modules can consult it without
+ * importing (frequently vi.mocked) core git internals.
+ */
+export function isGitIndexLockConflict(error) {
+    if (error instanceof GitIndexLockError) {
+        return true;
+    }
+    if (!(error instanceof GitError)) {
+        return false;
+    }
+    return (/index\.lock/i.test(error.message) &&
+        /(unable to create|another git process seems to be running|file exists|locked)/i.test(error.message));
+}
 /**
  * Error thrown when `git add` (monolithic or chunked) exceeds the
  * configured timeout while indexing the Firefox source tree.

package/dist/src/index.d.ts

@@ -14,6 +14,8 @@ export { loadConfig, validateConfig } from './core/config.js';
 export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
+export type { PatchSizeTierDecision } from './core/patch-lint.js';
+export { countNonBinaryDiffLines, getPatchSizeThresholds, resolvePatchSizeTier, } from './core/patch-lint.js';
 export type { AddTokenOptions, AddTokenResult, TokenMode } from './core/token-manager.js';
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';

package/dist/src/index.js

@@ -15,6 +15,7 @@ export { loadConfig, validateConfig } from './core/config.js';
 export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
+export { countNonBinaryDiffLines, getPatchSizeThresholds, resolvePatchSizeTier, } from './core/patch-lint.js';
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';
 export { ExitCode } from './errors/codes.js';

package/dist/src/types/commands/options.d.ts

@@ -279,6 +279,16 @@ export interface ReExportOptions {
      * the command implementation ignores it.
      */
     waitLock?: number | boolean;
+    /**
+     * Refuse (non-zero exit, patch not written) a scan-less re-export when
+     * unmanaged files exist adjacent to the patch's ownership, instead of
+     * warning. Gate-driven workflows use this so a freshly created file
+     * beside a patch's owned files cannot be silently left out of the
+     * refreshed body. Only meaningful on the plain path — mutually
+     * exclusive with `--scan` and `--files`, which set filesAffected
+     * explicitly.
+     */
+    refuseAdjacentUnmanaged?: boolean;
 }
 /**
  * Options for the `fireforge patch tier` subcommand. Sets or clears the
@@ -809,6 +819,19 @@ export interface StatusOptions {
     testCoverage?: boolean;
     /** Output machine-readable JSON instead of human-readable text. */
     json?: boolean;
+    /**
+     * Exit non-zero when any classification in the fail policy is
+     * non-empty (default policy: unmanaged, patch-owned-drift, conflict).
+     * Composes with the default view and `--json`; refused alongside
+     * `--raw`/`--unmanaged`/`--ownership`/`--test-coverage` (FORGE G1).
+     */
+    check?: boolean;
+    /**
+     * Comma-separated classification list replacing the default `--check`
+     * policy. Implies `--check`. Unknown values refuse, naming the valid
+     * classification set.
+     */
+    failOn?: string;
 }
 /**
  * Options for the token add command.
@@ -900,8 +923,9 @@ export interface LintCommandOptions {
      * the cross-patch rules once over the whole queue so queue-level
      * findings (duplicate creations, forward imports) still surface.
      *
-     * Mutually exclusive with passing explicit file paths — the two
-     * scope contracts are different.
+     * Positional file arguments change meaning under this flag: they are
+     * PATCH selectors resolved like {@link patches} entries, not engine
+     * file paths (FORGE G14).
      */
     perPatch?: boolean;
     /**
@@ -923,4 +947,11 @@ export interface LintCommandOptions {
      * for CLI consistency, but only `--per-patch` currently uses the cache.
      */
     noCache?: boolean;
+    /**
+     * With `--per-patch`, write a machine-readable JSON report (schemaVersion
+     * 1: per-patch lineCount, filesAffected, tier, thresholds, issues, and
+     * lintIgnore-suppressed issues) to this path (FORGE G9/G10). Requires
+     * {@link perPatch}.
+     */
+    report?: string;
 }

package/dist/src/types/config.d.ts

@@ -253,6 +253,25 @@ export interface PatchLintConfig {
      * behaviour (built-in shim only).
      */
     checkJsExtraShim?: string;
+    /**
+     * Extend the checkJs pass to patch-owned test `.js` files
+     * (`browser_*` / `test_*` / `xpcshell_*` basenames and files under a
+     * `/test/` path), each checked as its own small script-scope program
+     * with same-directory patch-owned `head*.js` helpers included (FORGE
+     * G5 — a harness global that does not exist should fail at the patch
+     * boundary where the test was authored, not in a downstream
+     * jsconfig-project run). Opt-in: it is a new failure surface with
+     * nonzero compile cost. Requires `checkJs: true`.
+     */
+    checkJsTestFiles?: boolean;
+    /**
+     * Project-relative `.d.ts` appended to the built-in test-harness shim
+     * (loose `TestUtils`/`BrowserTestUtils`/`add_task`/… declarations) for
+     * the `checkJsTestFiles` pass — a consumer-typed `TestUtils` here is
+     * what turns a call to a nonexistent harness member into a TS2339 at
+     * export time. Requires `checkJsTestFiles: true`.
+     */
+    checkJsTestShim?: string;
     /** File paths exempt from the raw-color-value check (exact or basename match) */
     rawColorAllowlist?: string[];
     /** Enforce JSDoc on class-method exports in patch-owned .sys.mjs files. Default: 'off'. */

package/dist/src/utils/validation.d.ts

@@ -128,6 +128,16 @@ export declare function validateTokenName(name: string): string | undefined;
  * @throws InvalidArgumentError if the resulting name is not a valid CSS custom property.
  */
 export declare function normalizeTokenName(name: string): string;
+/**
+ * Normalizes a patch display name against its category (FORGE G13):
+ * strips a trailing `.patch` and any redundant `NNN-<category>-` /
+ * `<category>-` prefixes, case-insensitively and repeatedly, mirroring
+ * the filename slug pipeline's require-the-category-token rule — a bare
+ * leading number is never stripped, so names like `2-step-verification`
+ * survive intact. Falls back to the `.patch`-stripped stem when the
+ * strip would empty the name.
+ */
+export declare function normalizePatchDisplayName(name: string, category: string): string;
 /**
  * Validates a patch name.
  * @param name - The patch name to validate

package/dist/src/utils/validation.js

@@ -251,6 +251,35 @@ export function normalizeTokenName(name) {
     const stripped = name.replace(/^--/, '');
     return `--${stripped}`;
 }
+/**
+ * Normalizes a patch display name against its category (FORGE G13):
+ * strips a trailing `.patch` and any redundant `NNN-<category>-` /
+ * `<category>-` prefixes, case-insensitively and repeatedly, mirroring
+ * the filename slug pipeline's require-the-category-token rule — a bare
+ * leading number is never stripped, so names like `2-step-verification`
+ * survive intact. Falls back to the `.patch`-stripped stem when the
+ * strip would empty the name.
+ */
+export function normalizePatchDisplayName(name, category) {
+    const stem = name.trim().replace(/\.patch$/i, '');
+    const escaped = category.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const prefixes = [
+        new RegExp(`^\\d+[-_ ]+${escaped}[-_ ]+`, 'i'),
+        new RegExp(`^${escaped}[-_ ]+`, 'i'),
+    ];
+    let stripped = stem;
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const prefix of prefixes) {
+            if (prefix.test(stripped)) {
+                stripped = stripped.replace(prefix, '');
+                changed = true;
+            }
+        }
+    }
+    return stripped.length > 0 ? stripped : stem;
+}
 /**
  * Validates a patch name.
  * @param name - The patch name to validate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -58,7 +58,7 @@
     "commander": "^15.0.0",
     "estree-walker": "^3.0.3",
     "jsonc-parser": "^3.3.1",
-    "magic-string": "^0.30.17",
+    "magic-string": "^1.1.0",
     "picocolors": "^1.1.0"
   },
   "devDependencies": {
@@ -66,16 +66,16 @@
     "@types/estree": "^1.0.8",
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.2",
-    "dpdm": "4.2.0",
+    "dpdm": "4.3.0",
     "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jsdoc": "^63.0.0",
-    "eslint-plugin-simple-import-sort": "^13.0.0",
+    "eslint-plugin-simple-import-sort": "^14.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "knip": "6.26.0",
+    "knip": "6.29.0",
     "lint-staged": "^17.0.4",
-    "prettier": "3.9.5",
+    "prettier": "3.9.6",
     "tsx": "^4.7.0",
     "typescript": "~6.0.0",
     "typescript-eslint": "^8.0.0",