@hominis/fireforge 0.37.0 → 0.39.0

package/dist/src/core/license-headers.d.ts

@@ -34,6 +34,11 @@ export declare function getLicenseHeader(license: ProjectLicense, style: Comment
  * on lines 1–2 with the MPL header on lines 3+, which the raw
  * `startsWith` check would otherwise miss.
  *
+ * The MPL-2.0 header is additionally matched on normalized whitespace
+ * (see {@link normalizeCommentHead}) so upstream files using the older
+ * Mozilla wrap — breaking after "file," instead of "with this" — are
+ * accepted too; only the wrap position differs, never the wording.
+ *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
  */
@@ -51,6 +56,13 @@ export declare function hasAnyLicenseHeader(content: string, style: CommentStyle
  * patch-lint, making it dead code for every other project license and
  * forcing repo-side audit workarounds.
  *
+ * Matching is wrap-agnostic: after the exact `startsWith` fast path, the
+ * leading block comment is compared on normalized whitespace (see
+ * {@link normalizeCommentHead}) so the older upstream wrap — breaking
+ * after "file," instead of "with this", as `ext-browser.js` ships —
+ * passes too. Only the line-break position may differ; altered wording
+ * still rejects.
+ *
  * @param content - File content to check
  */
 export declare function hasUpstreamMplBlockHeader(content: string): boolean;
@@ -69,6 +81,18 @@ export declare function hasAnyLicenseHeaderAnyStyle(content: string): boolean;
  * @param maxLines - Number of leading lines to inspect (default 10)
  */
 export declare function containsUpstreamLicenseText(content: string, maxLines?: number): boolean;
+/**
+ * Returns true when the head of `content` carries a recognized THIRD-PARTY
+ * permissive license banner (MIT / ISC / BSD-2 / BSD-3 / Apache-2.0), in any
+ * comment style. Used by `export` to treat such files as vendored: offering
+ * to prepend the project's own license header onto a byte-identity-pinned
+ * upstream bundle would mislicense third-party code (FORGE F15).
+ *
+ * @param content  - File content to check
+ * @param maxLines - Number of leading lines to inspect (default 30 — full
+ *   MIT/BSD license texts run longer than the 10-line project-header scan)
+ */
+export declare function hasThirdPartyPermissiveBanner(content: string, maxLines?: number): boolean;
 /**
  * Prepends the license header to a file on disk if it is not already present.
  *

package/dist/src/core/license-headers.js

@@ -86,6 +86,59 @@ function stripLeadingEditorDirectives(content) {
     } while (result !== prev);
     return result;
 }
+/**
+ * Collapses all whitespace runs to single spaces and trims, so header
+ * comparisons ignore the exact line-break/wrap positions.
+ */
+function normalizeText(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+/**
+ * The canonical upstream MPL-2.0 notice as a single normalized sentence
+ * (including the `http://mozilla.org/MPL/2.0/.` URL). Wrap-agnostic
+ * header checks match against this instead of an exact rendering.
+ */
+const MPL_HEADER_NORMALIZED = normalizeText(HEADER_LINES['MPL-2.0'].join(' '));
+/**
+ * Extracts ONLY the leading comment span of `content` for the given
+ * comment style and returns it whitespace-normalized:
+ *
+ * - `js`:   a leading run of `//` lines (markers stripped), or — when the
+ *           file opens with a block comment instead — the first
+ *           `/* … *\/` block;
+ * - `css`:  the first `/* … *\/` block, with the ` * ` continuation-line
+ *           prefixes stripped (same collapsing
+ *           {@link normalizeLicenseHeadForScan} does);
+ * - `hash`: a leading run of `#` lines (markers stripped).
+ *
+ * A non-comment first line yields `''`. This lets callers accept a known
+ * header text regardless of where upstream wrapped its lines (e.g. the
+ * older Mozilla wrap that breaks after "file,"), without ever matching
+ * text beyond the leading comment.
+ */
+function normalizeCommentHead(content, style) {
+    const src = content.replace(/\r\n?/g, '\n');
+    const collectLineRun = (marker) => {
+        const parts = [];
+        for (const line of src.split('\n')) {
+            const m = marker.exec(line);
+            if (!m)
+                break;
+            parts.push(m[1] ?? '');
+        }
+        return normalizeText(parts.join(' '));
+    };
+    if (style === 'hash') {
+        return collectLineRun(/^[ \t]*#[ \t]?(.*)$/);
+    }
+    if (style === 'js' && /^[ \t]*\/\//.test(src)) {
+        return collectLineRun(/^[ \t]*\/\/[ \t]?(.*)$/);
+    }
+    const block = /^[ \t]*\/\*([\s\S]*?)\*\//.exec(src);
+    if (!block)
+        return '';
+    return normalizeText((block[1] ?? '').replace(/\n[ \t]*\*[ \t]*/g, ' '));
+}
 /**
  * Returns true if `content` starts with any known license header for the
  * given comment style.
@@ -103,6 +156,11 @@ function stripLeadingEditorDirectives(content) {
  * on lines 1–2 with the MPL header on lines 3+, which the raw
  * `startsWith` check would otherwise miss.
  *
+ * The MPL-2.0 header is additionally matched on normalized whitespace
+ * (see {@link normalizeCommentHead}) so upstream files using the older
+ * Mozilla wrap — breaking after "file," instead of "with this" — are
+ * accepted too; only the wrap position differs, never the wording.
+ *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
  */
@@ -116,6 +174,9 @@ export function hasAnyLicenseHeader(content, style) {
         if (style === 'js' && candidate.startsWith(getLicenseHeader('MPL-2.0', 'css'))) {
             return true;
         }
+        if (normalizeCommentHead(candidate, style).startsWith(MPL_HEADER_NORMALIZED)) {
+            return true;
+        }
     }
     return false;
 }
@@ -132,11 +193,25 @@ export function hasAnyLicenseHeader(content, style) {
  * patch-lint, making it dead code for every other project license and
  * forcing repo-side audit workarounds.
  *
+ * Matching is wrap-agnostic: after the exact `startsWith` fast path, the
+ * leading block comment is compared on normalized whitespace (see
+ * {@link normalizeCommentHead}) so the older upstream wrap — breaking
+ * after "file," instead of "with this", as `ext-browser.js` ships —
+ * passes too. Only the line-break position may differ; altered wording
+ * still rejects.
+ *
  * @param content - File content to check
  */
 export function hasUpstreamMplBlockHeader(content) {
     const blockHeader = getLicenseHeader('MPL-2.0', 'css');
-    return (content.startsWith(blockHeader) || stripLeadingEditorDirectives(content).startsWith(blockHeader));
+    const candidates = [content, stripLeadingEditorDirectives(content)];
+    for (const candidate of candidates) {
+        if (candidate.startsWith(blockHeader))
+            return true;
+        if (normalizeCommentHead(candidate, 'css').startsWith(MPL_HEADER_NORMALIZED))
+            return true;
+    }
+    return false;
 }
 /**
  * Returns true if `content` starts with any known license header in any
@@ -177,6 +252,33 @@ export function containsUpstreamLicenseText(content, maxLines = 10) {
     ];
     return markers.some((marker) => scanText.includes(marker));
 }
+/**
+ * Returns true when the head of `content` carries a recognized THIRD-PARTY
+ * permissive license banner (MIT / ISC / BSD-2 / BSD-3 / Apache-2.0), in any
+ * comment style. Used by `export` to treat such files as vendored: offering
+ * to prepend the project's own license header onto a byte-identity-pinned
+ * upstream bundle would mislicense third-party code (FORGE F15).
+ *
+ * @param content  - File content to check
+ * @param maxLines - Number of leading lines to inspect (default 30 — full
+ *   MIT/BSD license texts run longer than the 10-line project-header scan)
+ */
+export function hasThirdPartyPermissiveBanner(content, maxLines = 30) {
+    const head = content.split('\n').slice(0, maxLines).join('\n');
+    const scanText = normalizeLicenseHeadForScan(head).toLowerCase();
+    const markers = [
+        'mit license',
+        'permission is hereby granted, free of charge',
+        'isc license',
+        'permission to use, copy, modify',
+        'redistribution and use in source and binary forms',
+        'apache license',
+        'licensed under the apache license',
+    ];
+    if (markers.some((marker) => scanText.includes(marker)))
+        return true;
+    return /spdx-license-identifier:\s*(mit|isc|bsd-2-clause|bsd-3-clause|apache-2\.0)\b/.test(scanText);
+}
 /**
  * Prepends the license header to a file on disk if it is not already present.
  *

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

@@ -30,7 +30,16 @@ export declare function sanitizeName(name: string): string;
  * double-prefix incident) also collapses. Exported for direct testing.
  */
 export declare function stripRedundantCategoryPrefix(sanitizedName: string, category: string): string;
-/** 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 declare function patchNameSlug(name: string, category: string): string;
 /**
  * Generates the next patch filename with category.

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.d.ts

@@ -8,6 +8,9 @@ export { lintPatchedCss };
  * Counts the total lines in a unified diff and the number of non-binary
  * text lines, so binary hunks do not inflate patch size checks.
  *
+ * Line counting agrees with `wc -l`: a trailing newline does not add a
+ * phantom empty line to either `total` or the binary-hunk accounting.
+ *
  * @param diffContent - Raw unified diff string
  * @returns Object with `total` line count and `textLines` (total minus binary hunk lines)
  */