@hominis/fireforge 0.38.0 → 0.39.0

package/dist/src/core/patch-export.js

@@ -75,9 +75,19 @@ export function stripRedundantCategoryPrefix(sanitizedName, category) {
     }
     return stripped.length > 0 ? stripped : sanitizedName;
 }
-/** Sanitizes a patch name and drops redundant category/full-stem prefixes. */
+/**
+ * Sanitizes a patch name and drops redundant category/full-stem prefixes.
+ *
+ * A single trailing `.patch` extension is stripped before sanitisation:
+ * operators frequently pass a full patch FILENAME where a name is expected
+ * (`move-files <from> 348-ui-foo.patch --create`, `rename --to foo.patch`),
+ * and 0.38.0 slugged the extension into `-patch`, producing double-suffixed
+ * `...-patch.patch` files. A name that deliberately ends in a literal
+ * `-patch` slug segment must now be written without the dot form.
+ */
 export function patchNameSlug(name, category) {
-    return stripRedundantCategoryPrefix(sanitizeName(name), category);
+    const stem = name.replace(/\.patch$/i, '');
+    return stripRedundantCategoryPrefix(sanitizeName(stem), category);
 }
 /**
  * Generates the next patch filename with category.

package/dist/src/core/patch-lint-checkjs.d.ts

@@ -25,11 +25,16 @@
  * while reporting only the patch under export.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
-import type { PatchLintCheckJsCompilerOptions, PatchLintConfig } from '../types/config.js';
+import type { PatchLintCheckJsCompilerOptions, PatchLintConfig, PatchLintSeverityGate } from '../types/config.js';
 /** How a checkJs run controls reporting and resolution; see module docs. */
 export interface CheckJsMode {
     strict: boolean;
     compilerOptions?: PatchLintCheckJsCompilerOptions;
+    /**
+     * How to report undefined free identifiers (TS2304/TS2552). Default
+     * 'warning' — see `patchLint.undefinedIdentifiers` (FORGE F12).
+     */
+    undefinedIdentifiers?: PatchLintSeverityGate;
 }
 /**
  * Result of {@link runCheckJsGrouped}: diagnostics attributed to the

package/dist/src/core/patch-lint-checkjs.js

@@ -28,7 +28,7 @@
 import { basename, 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';
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -312,7 +312,7 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
         },
     };
     const program = ts.createProgram(rootFiles, options, host);
-    const byFile = groupOwnedDiagnostics(ts, [...program.getSemanticDiagnostics(), ...program.getSyntacticDiagnostics()], relByAbsolute);
+    const byFile = groupOwnedDiagnostics(ts, [...program.getSemanticDiagnostics(), ...program.getSyntacticDiagnostics()], relByAbsolute, mode?.undefinedIdentifiers ?? 'warning');
     verbose(`checkJs: analyzed ${rootFiles.length - 1} file(s) across ${byFile.size} owning file(s)`);
     return { byFile, global: [] };
 }
@@ -323,11 +323,14 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
  * or shim files are dropped — only owned files (in `relByAbsolute`) carry
  * findings.
  */
-function groupOwnedDiagnostics(ts, diagnostics, relByAbsolute) {
+function groupOwnedDiagnostics(ts, diagnostics, relByAbsolute, undefinedIdentifiers = 'warning') {
     const byFile = new Map();
     for (const diag of diagnostics) {
         if (SUPPRESSED_DIAGNOSTIC_CODES.has(diag.code))
             continue;
+        const isUndefinedIdentifier = UNDEFINED_IDENTIFIER_CODES.has(diag.code);
+        if (isUndefinedIdentifier && undefinedIdentifiers === 'off')
+            continue;
         const sourceFile = diag.file;
         if (!sourceFile)
             continue;
@@ -339,12 +342,20 @@ function groupOwnedDiagnostics(ts, diagnostics, relByAbsolute) {
         const messageText = typeof diag.messageText === 'string'
             ? diag.messageText
             : ts.flattenDiagnosticMessageText(diag.messageText, '\n');
-        const severity = diag.category === ts.DiagnosticCategory.Error ? 'error' : 'warning';
+        const severity = isUndefinedIdentifier
+            ? undefinedIdentifiers === 'error'
+                ? 'error'
+                : 'warning'
+            : diag.category === ts.DiagnosticCategory.Error
+                ? 'error'
+                : 'warning';
         const bucket = byFile.get(relPath) ?? [];
         bucket.push({
             file: relPath,
             check: 'checkjs-type-error',
-            message: `Line ${line}: ${messageText}`,
+            message: isUndefinedIdentifier
+                ? `Line ${line}: ${messageText} ${UNDEFINED_IDENTIFIER_HINT}`
+                : `Line ${line}: ${messageText}`,
             severity,
         });
         byFile.set(relPath, bucket);
@@ -389,11 +400,20 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
  *   not surface other patches' diagnostics)
  */
 export async function invokePatchLintCheckJs(repoDir, patchOwnedFiles, patchLint, projectRoot, reportScope) {
+    return runCheckJs(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, modeFromPatchLintConfig(patchLint), reportScope);
+}
+/** Derives the {@link CheckJsMode} from a `patchLint` config block. */
+function modeFromPatchLintConfig(patchLint) {
     const strict = patchLint.checkJsStrict === true;
-    const mode = strict && patchLint.checkJsCompilerOptions
-        ? { strict, compilerOptions: patchLint.checkJsCompilerOptions }
-        : { strict };
-    return runCheckJs(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, mode, reportScope);
+    return {
+        strict,
+        ...(strict && patchLint.checkJsCompilerOptions
+            ? { compilerOptions: patchLint.checkJsCompilerOptions }
+            : {}),
+        ...(patchLint.undefinedIdentifiers !== undefined
+            ? { undefinedIdentifiers: patchLint.undefinedIdentifiers }
+            : {}),
+    };
 }
 /**
  * Grouped variant of {@link invokePatchLintCheckJs}: builds one queue-wide
@@ -408,9 +428,5 @@ export async function invokePatchLintCheckJs(repoDir, patchOwnedFiles, patchLint
  * @param projectRoot - FireForge project root for shim resolution
  */
 export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, patchLint, projectRoot) {
-    const strict = patchLint.checkJsStrict === true;
-    const mode = strict && patchLint.checkJsCompilerOptions
-        ? { strict, compilerOptions: patchLint.checkJsCompilerOptions }
-        : { strict };
-    return runCheckJsGrouped(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, mode);
+    return runCheckJsGrouped(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, modeFromPatchLintConfig(patchLint));
 }

package/dist/src/core/patch-lint-cross.d.ts

@@ -10,6 +10,7 @@
  * single module.
  */
 import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
+import type { FireForgeConfig, PatchPolicyConfig } from '../types/config.js';
 /**
  * One patch's contribution to {@link PatchQueueContext}.
  *
@@ -57,6 +58,13 @@ export interface PatchQueueEntry {
 export interface PatchQueueContext {
     /** Entries in application order (lowest `order` first). */
     entries: PatchQueueEntry[];
+    /**
+     * Optional patchPolicy config. When present, the forward-import rule
+     * validates its "Closest legal ordinal" suggestion against the importing
+     * patch's category range and suppresses it when no legal ordinal exists
+     * (FORGE F14). Absent = current behavior (hint always printed).
+     */
+    patchPolicy?: PatchPolicyConfig;
 }
 /**
  * Builds a {@link PatchQueueContext} by reading every .patch file in the
@@ -70,7 +78,7 @@ export interface PatchQueueContext {
  *
  * @param patchesDir - Path to the patches directory
  */
-export declare function buildPatchQueueContext(patchesDir: string): Promise<PatchQueueContext>;
+export declare function buildPatchQueueContext(patchesDir: string, config?: FireForgeConfig): Promise<PatchQueueContext>;
 /**
  * Returns the raw `path → patches[]` map of files created in `new file
  * mode` by at least one patch in the queue. Paths created by only one

package/dist/src/core/patch-lint-cross.js

@@ -18,6 +18,7 @@ import { stripJsComments } from '../utils/regex.js';
 import { discoverPatches } from './patch-files.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
 import { loadPatchesManifest } from './patch-manifest-io.js';
+import { categoryRangeForOrder, categoryRangeLabel } from './patch-policy.js';
 import { extractNewFileContent } from './patch-transform.js';
 /**
  * Builds a {@link PatchQueueContext} by reading every .patch file in the
@@ -31,7 +32,7 @@ import { extractNewFileContent } from './patch-transform.js';
  *
  * @param patchesDir - Path to the patches directory
  */
-export async function buildPatchQueueContext(patchesDir) {
+export async function buildPatchQueueContext(patchesDir, config) {
     const patches = await discoverPatches(patchesDir);
     const manifest = await loadPatchesManifest(patchesDir);
     const metadataByFilename = new Map();
@@ -78,7 +79,7 @@ export async function buildPatchQueueContext(patchesDir) {
     }
     // Sort by order so rules can rely on entries being in apply order.
     entries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
-    return { entries };
+    return { entries, ...(config?.patchPolicy ? { patchPolicy: config.patchPolicy } : {}) };
 }
 /**
  * Returns the raw `path → patches[]` map of files created in `new file
@@ -292,6 +293,34 @@ export function extractImportSpecifiersWithLines(source) {
     collectGetterSpecifiers(stripped, results, offsetToLine);
     return results;
 }
+/**
+ * Bare `Name: "url"` property lines added inside a PRE-EXISTING
+ * `defineESModuleGetters` (or `XPCOMUtils` lazy-getter) map. Applied ONLY to
+ * `modifiedFileAdditions`: a patch that inserts one property into an
+ * existing getter object never carries the `defineESModuleGetters(` opener
+ * in its added lines, so the balanced-brace walk in
+ * {@link extractImportSpecifiersWithLines} cannot see it (FORGE F3). The
+ * URL-scheme restriction keeps ordinary object literals
+ * (`label: "Foo.sys.mjs"`) out; the leaf-extension filter downstream does
+ * the rest.
+ */
+const BARE_GETTER_PROPERTY_LINE = /^\s*(?:["'])?[A-Za-z_$][\w$]*(?:["'])?\s*:\s*["']((?:resource|chrome|moz-src):\/\/[^"']+)["']\s*,?\s*$/;
+/**
+ * Extracts specifiers from bare getter-property lines in added-lines-only
+ * content. Comment stripping preserves line alignment, so the reported line
+ * numbers match what {@link findForwardImportIgnoreLines} walks.
+ */
+function extractBareGetterSpecifiers(source) {
+    const stripped = stripJsComments(source);
+    const results = [];
+    const lines = stripped.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const match = BARE_GETTER_PROPERTY_LINE.exec(lines[i] ?? '');
+        if (match?.[1])
+            results.push({ specifier: match[1], line: i });
+    }
+    return results;
+}
 /**
  * Marker comment operators can use to suppress the forward-import rule
  * for imports that resolve to a basename false positive (two unrelated
@@ -376,11 +405,22 @@ function buildNewFileIndex(ctx) {
  * pre-existing HEAD imports that happen to collide with a later-created file.
  */
 function eachForwardImportSite(ctx, newFileIndex, visit) {
-    const checkSite = (entry, sitePath, content) => {
+    const checkSite = (entry, sitePath, content, includeBareGetterLines = false) => {
         if (!isForwardImportableFile(sitePath))
             return;
+        const sites = extractImportSpecifiersWithLines(content);
+        if (includeBareGetterLines) {
+            // Dedupe by (specifier, line): a patch that adds the whole getter
+            // call carries both the opener (found by the balanced walk) and the
+            // property line (found here) — report each site once.
+            const seen = new Set(sites.map((site) => `${site.specifier}|${String(site.line)}`));
+            for (const extra of extractBareGetterSpecifiers(content)) {
+                if (!seen.has(`${extra.specifier}|${String(extra.line)}`))
+                    sites.push(extra);
+            }
+        }
         const ignoreLines = findForwardImportIgnoreLines(content);
-        for (const { specifier, line } of extractImportSpecifiersWithLines(content)) {
+        for (const { specifier, line } of sites) {
             if (ignoreLines.has(line))
                 continue;
             const cleaned = specifier.split(/[?#]/)[0] ?? specifier;
@@ -400,7 +440,7 @@ function eachForwardImportSite(ctx, newFileIndex, visit) {
         for (const [path, content] of entry.newFiles)
             checkSite(entry, path, content);
         for (const [path, added] of entry.modifiedFileAdditions)
-            checkSite(entry, path, added);
+            checkSite(entry, path, added, true);
     }
 }
 /**
@@ -454,8 +494,28 @@ export function lintPatchQueueForwardImports(ctx) {
             .join(',');
         // Lowest ordinal that lands AFTER every later-ordered creator —
         // turns the operator's "guess and re-run" loop into a single shot
-        // when the only fix is reordering.
+        // when the only fix is reordering. When patchPolicy is available and
+        // that ordinal falls outside the importing patch's category range,
+        // `patch reorder` would refuse it — suppress the hint and point at
+        // the staged-dependency remedy instead (FORGE F14).
         const suggestedOrder = Math.max(...laterOwners.map((o) => o.order)) + 1;
+        const category = entry.metadata?.category ?? /^\d+-([a-z]+)-/.exec(entry.filename)?.[1];
+        let ordinalHint = `Closest legal ordinal that satisfies this dependency: ${suggestedOrder}.`;
+        if (ctx.patchPolicy &&
+            category !== undefined &&
+            categoryRangeForOrder(ctx.patchPolicy, category, suggestedOrder) === null) {
+            const label = categoryRangeLabel(ctx.patchPolicy.ranges, category);
+            ordinalHint =
+                `No legal ordinal in the ${category} category range (${label}) lands after the ` +
+                    'creating patch(es); declaring the staged dependency is the recommended remedy.';
+        }
+        // The exact per-owner invocation turns the refusal into a paste-and-run
+        // remedy instead of a flag-discovery exercise (FORGE F3).
+        const stagedCommands = laterOwners
+            .map((o) => `fireforge patch staged-dependency ${entry.filename} --add ` +
+            `--file ${sitePath} --specifier "${specifier}" ` +
+            `--creates ${o.fullPath} --owner ${o.filename}`)
+            .join('; ');
         issues.push({
             file: sitePath,
             check: 'forward-import',
@@ -463,10 +523,10 @@ export function lintPatchQueueForwardImports(ctx) {
             message: `${sitePath} in ${entry.filename} imports "${specifier}", ` +
                 `but the matching new file is created by a later patch: ${ownersSummary}. ` +
                 'Reorder the patches so the dependency is created first, move the import ' +
-                'into the later patch, declare the intentional staged dependency with ' +
-                '"fireforge patch staged-dependency --add", or mark the import with ' +
+                'into the later patch, declare the intentional staged dependency with: ' +
+                `${stagedCommands}; or mark the import with ` +
                 `"// ${FORWARD_IMPORT_IGNORE_MARKER}" if the basename collision is a false positive. ` +
-                `Closest legal ordinal that satisfies this dependency: ${suggestedOrder}.`,
+                ordinalHint,
             severity: 'error',
         });
     });

package/dist/src/core/patch-lint-mozbuild.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Per-patch lint check for moz.build sorted-list violations (FORGE F2).
+ *
+ * mozbuild enforces alphabetical ordering on `StrictOrderingOnAppendList`
+ * variables and raises `mozbuild.util.UnsortedError: … expected "X" but got
+ * "Y"` — but only at CONFIGURE time, i.e. minutes into a `fireforge build`
+ * or `fireforge test --build` dispatch. This check reads the patched
+ * `moz.build` files from the engine tree (the working tree carries the
+ * applied patch state, same as every other per-patch rule) and reports the
+ * exact expected/got pair before any build starts.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+/**
+ * Lints the patched content of every `moz.build` file the patch touches for
+ * unsorted strict-ordered lists, mirroring mozbuild's `UnsortedError`
+ * report: the first index where the list diverges from its sorted copy.
+ */
+export declare function lintMozBuildSortedLists(repoDir: string, affectedFiles: string[]): Promise<PatchLintIssue[]>;

package/dist/src/core/patch-lint-mozbuild.js

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Per-patch lint check for moz.build sorted-list violations (FORGE F2).
+ *
+ * mozbuild enforces alphabetical ordering on `StrictOrderingOnAppendList`
+ * variables and raises `mozbuild.util.UnsortedError: … expected "X" but got
+ * "Y"` — but only at CONFIGURE time, i.e. minutes into a `fireforge build`
+ * or `fireforge test --build` dispatch. This check reads the patched
+ * `moz.build` files from the engine tree (the working tree carries the
+ * applied patch state, same as every other per-patch rule) and reports the
+ * exact expected/got pair before any build starts.
+ */
+import { join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { mozbuildSortCompare } from './manifest-helpers.js';
+/**
+ * moz.build list variables mozbuild declares as `StrictOrderingOnAppendList`
+ * (python/mozbuild/mozbuild/frontend/context.py). configure raises
+ * `UnsortedError` on append when out of order. `DIRS` is deliberately absent
+ * — directory order is meaningful and not strict-ordered. Dotted namespaces
+ * (`EXTRA_JS_MODULES.<subdir>`, `EXPORTS.<ns>`) inherit strict ordering
+ * from their parent variable.
+ */
+const STRICT_ORDERED_MOZBUILD_LISTS = [
+    'EXTRA_COMPONENTS',
+    'EXTRA_JS_MODULES',
+    'EXTRA_PP_COMPONENTS',
+    'EXPORTS',
+    'PYTHON_UNITTEST_MANIFESTS',
+    'TESTING_JS_MODULES',
+    'XPIDL_SOURCES',
+];
+const LIST_OPENER = new RegExp(`^\\s*((?:${STRICT_ORDERED_MOZBUILD_LISTS.join('|')})(?:\\.[A-Za-z_][A-Za-z0-9_]*)*)\\s*\\+?=\\s*\\[`);
+/** Extracts every strict-ordered list (with items in file order) from moz.build content. */
+function collectStrictOrderedLists(content) {
+    const lines = content.split('\n');
+    const occurrences = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        const opener = LIST_OPENER.exec(line);
+        if (!opener)
+            continue;
+        const varName = opener[1] ?? '';
+        const items = [];
+        // Items may start on the opener line (`VAR += ["a", "b"]`) or span
+        // following lines until the closing bracket.
+        let rest = line.slice(opener[0].length);
+        let closed = false;
+        for (;;) {
+            for (const quoted of rest.matchAll(/["']([^"']+)["']/g)) {
+                items.push(quoted[1] ?? '');
+            }
+            if (/\]/.test(rest)) {
+                closed = true;
+                break;
+            }
+            i += 1;
+            if (i >= lines.length)
+                break;
+            rest = lines[i] ?? '';
+            if (/^\s*\]/.test(rest)) {
+                closed = true;
+                break;
+            }
+        }
+        if (closed)
+            occurrences.push({ varName, items });
+    }
+    return occurrences;
+}
+/**
+ * Lints the patched content of every `moz.build` file the patch touches for
+ * unsorted strict-ordered lists, mirroring mozbuild's `UnsortedError`
+ * report: the first index where the list diverges from its sorted copy.
+ */
+export async function lintMozBuildSortedLists(repoDir, affectedFiles) {
+    const issues = [];
+    for (const file of affectedFiles) {
+        if (!(file === 'moz.build' || file.endsWith('/moz.build')))
+            continue;
+        const filePath = join(repoDir, file);
+        if (!(await pathExists(filePath)))
+            continue;
+        const content = await readText(filePath);
+        for (const { varName, items } of collectStrictOrderedLists(content)) {
+            const sorted = [...items].sort(mozbuildSortCompare);
+            const divergence = items.findIndex((item, index) => item !== sorted[index]);
+            if (divergence === -1)
+                continue;
+            const expected = sorted[divergence] ?? '';
+            const got = items[divergence] ?? '';
+            issues.push({
+                file,
+                check: 'mozbuild-unsorted-list',
+                fingerprint: `mozbuild-unsorted-list|${file}|${varName}|${expected}|${got}`,
+                message: `moz.build list ${varName} is not alphabetically sorted: ` +
+                    `expected "${expected}" but got "${got}" ` +
+                    '(mozbuild will fail at configure time with UnsortedError)',
+                severity: 'error',
+            });
+        }
+    }
+    return issues;
+}

package/dist/src/core/patch-lint.js

@@ -10,6 +10,7 @@ import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-dif
 import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
 import { hasRelativeImport } from './patch-lint-imports.js';
 import { validateExportJsDoc } from './patch-lint-jsdoc.js';
+import { lintMozBuildSortedLists } from './patch-lint-mozbuild.js';
 import { lintObserverTopics } from './patch-lint-observer.js';
 import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
 // ---------------------------------------------------------------------------
@@ -616,11 +617,12 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     const { textLines: lineCount } = countNonBinaryDiffLines(diffContent);
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);
     const patchOwnedChromeScripts = resolvePatchOwnedChromeScripts(newFiles, patchQueueCtx);
-    const [cssIssues, headerIssues, jsIssues, modifiedHeaderIssues] = await Promise.all([
+    const [cssIssues, headerIssues, jsIssues, modifiedHeaderIssues, mozBuildIssues] = await Promise.all([
         lintPatchedCss(repoDir, affectedFiles, diffContent, config),
         lintNewFileHeaders(repoDir, [...newFiles], config),
         lintPatchedJs(repoDir, affectedFiles, newFiles, config, patchOwnedFiles, patchOwnedChromeScripts),
         lintModifiedFileHeaders(repoDir, affectedFiles, newFiles),
+        lintMozBuildSortedLists(repoDir, affectedFiles),
     ]);
     const modCommentIssues = lintModificationComments(diffContent, config);
     const sizeIssues = options?.skipPatchSize
@@ -633,6 +635,7 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         ...modifiedHeaderIssues,
         ...jsIssues,
         ...modCommentIssues,
+        ...mozBuildIssues,
     ];
     if (options?.precomputedCheckJs) {
         // Per-patch lint built one queue-wide program and already attributed

package/dist/src/core/patch-policy.d.ts

@@ -7,7 +7,7 @@
  * `patch reorder`, etc.).
  */
 import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
-import type { FireForgeConfig } from '../types/config.js';
+import type { FireForgeConfig, PatchPolicyConfig, PatchPolicyRange } from '../types/config.js';
 /** Stable issue codes returned by patch policy evaluation. */
 export type PatchPolicyIssueCode = 'filename-pattern' | 'filename-captures' | 'filename-metadata-mismatch' | 'order-collision' | 'category-range' | 'reserved-range' | 'reserved-documentation' | 'reserved-files' | 'description-required' | 'numeric-gap';
 /** A single patch policy validation finding. */
@@ -28,6 +28,19 @@ export interface PatchPolicyEnforcementInput {
 export declare function getPatchPolicyCategories(config: FireForgeConfig): string[];
 /** Checks whether a category is accepted by legacy defaults or the policy ranges. */
 export declare function isCategoryAllowedByConfig(config: FireForgeConfig, category: string): boolean;
+/**
+ * Human-readable label for a category's configured ranges, e.g. `300-399`.
+ * Exported for the forward-import hint (FORGE F14), which must render the
+ * range it found no legal ordinal in.
+ */
+export declare function categoryRangeLabel(ranges: readonly PatchPolicyRange[], category: string): string;
+/**
+ * Returns the configured range that contains `order` for `category`, or
+ * null when no such range exists. Exported for the forward-import hint
+ * (FORGE F14), which suppresses ordinal suggestions the reorder policy
+ * would refuse.
+ */
+export declare function categoryRangeForOrder(cfg: PatchPolicyConfig, category: string, order: number): PatchPolicyRange | null;
 /** Evaluates an entire patch manifest against the configured policy. */
 export declare function evaluatePatchPolicy(config: FireForgeConfig, manifest: PatchesManifest): PatchPolicyIssue[];
 /** Builds a sorted manifest snapshot from projected patch metadata. */

package/dist/src/core/patch-policy.js

@@ -45,7 +45,12 @@ export function isCategoryAllowedByConfig(config, category) {
 function rangeLabel(range) {
     return `${String(range.from).padStart(3, '0')}-${String(range.to).padStart(3, '0')}`;
 }
-function categoryRangeLabel(ranges, category) {
+/**
+ * Human-readable label for a category's configured ranges, e.g. `300-399`.
+ * Exported for the forward-import hint (FORGE F14), which must render the
+ * range it found no legal ordinal in.
+ */
+export function categoryRangeLabel(ranges, category) {
     const matches = ranges.filter((range) => range.category === category);
     if (matches.length === 0)
         return '(no configured range)';
@@ -54,7 +59,13 @@ function categoryRangeLabel(ranges, category) {
 function reservedRangeForOrder(cfg, order) {
     return cfg.reservedRanges?.find((range) => order >= range.from && order <= range.to) ?? null;
 }
-function categoryRangeForOrder(cfg, category, order) {
+/**
+ * Returns the configured range that contains `order` for `category`, or
+ * null when no such range exists. Exported for the forward-import hint
+ * (FORGE F14), which suppresses ordinal suggestions the reorder policy
+ * would refuse.
+ */
+export function categoryRangeForOrder(cfg, category, order) {
     return (cfg.ranges.find((range) => {
         return range.category === category && order >= range.from && order <= range.to;
     }) ?? null);

package/dist/src/core/test-harness-crash.d.ts

@@ -154,6 +154,16 @@ export declare function classifyHarnessRun(exitCode: number, output: string, req
 export declare function buildGreenSummaryRejectedMessage(rejection: GreenSummaryRejection, exitCode: number): string;
 /** Builds the operator-facing failure message after retries are exhausted. */
 export declare function buildHarnessCrashMessage(signature: HarnessCrashSignature, attempts: number, commandLabel?: string): string;
+/**
+ * Optional hint appended to the harness-crash message when a HEADED run on
+ * macOS died at the no-output timeout: the display may have slept and frozen
+ * the headed browser before any test started (FORGE F17). Pure — the
+ * platform is injected so unit tests need no mocking.
+ */
+export declare function headedNoOutputTimeoutHint(signature: HarnessCrashSignature, context: {
+    headless: boolean;
+    platform: string;
+}): string | undefined;
 /**
  * Builds the message for a run that produced no `TEST-START` despite
  * requesting paths — including exit-code-zero runs whose `Passed: 0`

package/dist/src/core/test-harness-crash.js

@@ -537,6 +537,22 @@ export function buildHarnessCrashMessage(signature, attempts, commandLabel = 'ma
         'If it persists across many runs, inspect the mach virtualenv (mach resyncs psutil on its own; ' +
         'patching it manually does not stick).');
 }
+/**
+ * Optional hint appended to the harness-crash message when a HEADED run on
+ * macOS died at the no-output timeout: the display may have slept and frozen
+ * the headed browser before any test started (FORGE F17). Pure — the
+ * platform is injected so unit tests need no mocking.
+ */
+export function headedNoOutputTimeoutHint(signature, context) {
+    if (context.platform !== 'darwin' || context.headless)
+        return undefined;
+    if (!signature.reason.includes('no-output timeout'))
+        return undefined;
+    return ('Hint: this was a HEADED run on macOS that died at the no-output timeout. ' +
+        'A common cause is the display going to sleep mid-run, which freezes the headed browser ' +
+        'before any test starts. Wrap headed runs in `caffeinate -dimsu <command>` to keep the ' +
+        'display awake, or pass --headless.');
+}
 /**
  * Builds the message for a run that produced no `TEST-START` despite
  * requesting paths — including exit-code-zero runs whose `Passed: 0`

package/dist/src/core/test-stale-check.d.ts

@@ -108,3 +108,18 @@ export declare function checkStaticComponentsStale(engineDir: string, baseline:
  * independently.
  */
 export declare function formatStaticComponentsRefusal(changedManifests: string[]): string;
+/**
+ * Formats the post-mutation advisory printed by `fireforge reset` /
+ * `fireforge import` when `components.conf` diverged from the last full
+ * build (FORGE F13). Same probe as {@link formatStaticComponentsRefusal},
+ * different moment: this fires at mutation time so the operator learns a
+ * full build is needed BEFORE the next gate run refuses.
+ */
+export declare function formatPostMutationStaticComponentsWarning(changedManifests: string[]): string;
+/**
+ * Post-mutation advisory used by `fireforge reset` / `fireforge import`:
+ * warns (never throws, never blocks) when `components.conf` now differs
+ * from the last full-build anchor. Silently skipped when no baseline or
+ * anchor exists, or when any probe fails.
+ */
+export declare function warnIfStaticComponentsStale(projectRoot: string, engineDir: string): Promise<void>;

package/dist/src/core/test-stale-check.js

@@ -27,7 +27,7 @@ import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
-import { verbose } from '../utils/logger.js';
+import { verbose, warn } from '../utils/logger.js';
 import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
 import { collectChangedEnginePaths } from './engine-changes.js';
@@ -245,3 +245,39 @@ export function formatStaticComponentsRefusal(changedManifests) {
         'it accepts stale packaged content, not a stale compiled registration. Pass ' +
         '--allow-stale-components only if you rebuilt out-of-band and accept the risk.)');
 }
+/**
+ * Formats the post-mutation advisory printed by `fireforge reset` /
+ * `fireforge import` when `components.conf` diverged from the last full
+ * build (FORGE F13). Same probe as {@link formatStaticComponentsRefusal},
+ * different moment: this fires at mutation time so the operator learns a
+ * full build is needed BEFORE the next gate run refuses.
+ */
+export function formatPostMutationStaticComponentsWarning(changedManifests) {
+    const head = changedManifests.slice(0, STALE_PATHS_LIMIT);
+    const truncated = changedManifests.length - head.length;
+    const list = head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
+    return (`components.conf changed relative to the last full "fireforge build": ${list}.\n` +
+        'The compiled StaticComponents table in obj-* no longer matches the tree, so the next ' +
+        '"fireforge test" will require a full "fireforge build" first — a scoped ' +
+        '"fireforge test --build" cannot regenerate the compiled table.');
+}
+/**
+ * Post-mutation advisory used by `fireforge reset` / `fireforge import`:
+ * warns (never throws, never blocks) when `components.conf` now differs
+ * from the last full-build anchor. Silently skipped when no baseline or
+ * anchor exists, or when any probe fails.
+ */
+export async function warnIfStaticComponentsStale(projectRoot, engineDir) {
+    try {
+        const baseline = await readBuildBaseline(projectRoot);
+        if (baseline === undefined)
+            return;
+        const result = await checkStaticComponentsStale(engineDir, baseline);
+        if (!result.stale)
+            return;
+        warn(formatPostMutationStaticComponentsWarning(result.changedManifests));
+    }
+    catch (error) {
+        verbose(`Static-components post-mutation check skipped: ${toError(error).message}`);
+    }
+}