@hominis/fireforge 0.38.0 → 0.40.0

package/dist/src/core/typecheck.js

@@ -21,7 +21,7 @@
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
-import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES } from './typecheck-shim.js';
+import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
 /**
  * Sentinel string surfaced as a `TypecheckIssue.message` when the
  * project's jsconfig sets `checkJs: false`. Exported so tests can
@@ -131,7 +131,7 @@ export async function runTypecheck(projectRoot, cfg) {
             });
             continue;
         }
-        results.push(await runTypecheckForProject(ts, projectRoot, projectPath, shimSource));
+        results.push(await runTypecheckForProject(ts, projectRoot, projectPath, shimSource, cfg.undefinedIdentifiers ?? 'warning'));
     }
     return results;
 }
@@ -149,7 +149,7 @@ function resolveProjectExtraShim(cfg, projectPath) {
     return cfg.extraShim;
 }
 /** Runs typecheck for a single jsconfig path, isolating its failures. */
-async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource) {
+async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource, undefinedIdentifiers = 'warning') {
     const absConfig = resolve(projectRoot, projectPath);
     if (!(await pathExists(absConfig))) {
         return {
@@ -268,6 +268,17 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource)
         // can't act on them and they would clutter CI logs.
         if (diag.file?.fileName === shimPath)
             continue;
+        if (UNDEFINED_IDENTIFIER_CODES.has(diag.code)) {
+            if (undefinedIdentifiers === 'off')
+                continue;
+            const issue = diagnosticToIssue(ts, diag, absConfig, projectPath);
+            issues.push({
+                ...issue,
+                category: undefinedIdentifiers,
+                message: `${issue.message} ${UNDEFINED_IDENTIFIER_HINT}`,
+            });
+            continue;
+        }
         issues.push(diagnosticToIssue(ts, diag, absConfig, projectPath));
     }
     verbose(`typecheck: ${projectPath} — analyzed ${String(parsed.fileNames.length)} file(s), found ${String(issues.length)} issue(s)`);

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

@@ -160,6 +160,12 @@ export interface ResetOptions {
  * Options for the discard command.
  */
 export interface DiscardOptions {
+    /**
+     * Restore to pristine upstream (HEAD) instead of the patch-applied
+     * baseline; deletes patch-created files (the pre-0.39.0 semantics —
+     * FORGE F1).
+     */
+    toUpstream?: boolean;
     /** Show what would be discarded without doing it */
     dryRun?: boolean;
     /** Skip confirmation prompt */
@@ -273,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
@@ -795,8 +811,27 @@ export interface StatusOptions {
      * patch as an ownership conflict.
      */
     ownership?: boolean;
+    /**
+     * Print the recorded test-packaging coverage of the last build baseline
+     * (scope, timestamp, recording invocation) and exit. Read-only — the
+     * counterpart to the out-of-coverage test refusal (FORGE F11).
+     */
+    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.
@@ -888,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;
     /**
@@ -911,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

@@ -181,6 +181,14 @@ export interface TypecheckConfig {
      * mismatch). A narrowed project sets `null` here to stay clean.
      */
     projectOverrides?: Record<string, string | null>;
+    /**
+     * How to report undefined free identifiers (TS2304/TS2552). These were
+     * historically suppressed as shim-gap noise, which also hid genuine
+     * missing imports until they crashed at runtime (FORGE F12). Default
+     * `'warning'`: visible without failing the gate. `'error'` makes them
+     * blocking; `'off'` restores the historical suppression.
+     */
+    undefinedIdentifiers?: PatchLintSeverityGate;
 }
 /**
  * Wire command configuration.
@@ -245,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'. */
@@ -262,6 +289,13 @@ export interface PatchLintConfig {
      * 'off'.
      */
     chromeScriptJsDoc?: PatchLintSeverityGate;
+    /**
+     * How the checkJs pass reports undefined free identifiers
+     * (TS2304/TS2552). Same semantics as `typecheck.undefinedIdentifiers`
+     * (FORGE F12); the two flows share the suppression policy so a patch
+     * cannot pass one and fail the other. Default: 'warning'.
+     */
+    undefinedIdentifiers?: PatchLintSeverityGate;
 }
 /**
  * Build mode for mach.

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.38.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",