@hominis/fireforge 0.38.0 → 0.40.0

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, TEST_HARNESS_SHIM, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -148,7 +148,7 @@ function createPathsResolver(ts, paths, baseDir, fileExists, onResolved) {
  * @param mode - Strictness preset plus allowlisted compiler-option overrides
  * @returns Diagnostics grouped per owning file plus run-level errors
  */
-export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath, projectRoot, mode) {
+export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath, projectRoot, mode, builtinShimSuffix) {
     const empty = { byFile: new Map(), global: [] };
     if (resolutionOwned.size === 0)
         return empty;
@@ -193,7 +193,11 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
     let shimSource;
     try {
         const composed = await composeShimSource(projectRoot ?? repoDir, extraShimPath);
-        shimSource = composed.source;
+        // The suffix (e.g. the loose test-harness baseline, FORGE G5) goes
+        // AFTER the consumer's extra shim: TypeScript resolves conflicting
+        // `declare var` redeclarations to the FIRST declaration, so a typed
+        // consumer declaration must precede the loose fallback to win.
+        shimSource = builtinShimSuffix ? `${composed.source}\n${builtinShimSuffix}` : composed.source;
         if (composed.extraShimAppended) {
             verbose(`checkJs: extra shim ${extraShimPath ?? ''} appended to Firefox globals shim`);
         }
@@ -312,7 +316,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 +327,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 +346,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 +404,69 @@ 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);
+}
+/**
+ * Runs the checkJs pass over patch-owned test `.js` files (FORGE G5,
+ * `patchLint.checkJsTestFiles`). Each test file gets its OWN small
+ * program — mochitest scripts share top-level scope only with their
+ * directory's `head*.js` helpers, so one multi-script program would emit
+ * false cross-file redeclaration errors — with roots = the test file plus
+ * any same-directory patch-owned `head*.js`, checked against the built-in
+ * Firefox shim + {@link TEST_HARNESS_SHIM} + the optional consumer
+ * `checkJsTestShim`. Only the target file's diagnostics are reported per
+ * program (head helpers report from their own program), and run-level
+ * errors are de-duplicated across programs.
+ *
+ * @param repoDir - Absolute engine (repository) directory
+ * @param testFiles - Patch-owned test-script paths (repo-relative)
+ * @param patchLint - The resolved `patchLint` config block
+ * @param projectRoot - FireForge project root for shim resolution
+ */
+export async function runCheckJsTestFilesGrouped(repoDir, testFiles, patchLint, projectRoot) {
+    const merged = { byFile: new Map(), global: [] };
+    if (testFiles.size === 0)
+        return merged;
+    const mode = modeFromPatchLintConfig(patchLint);
+    const seenGlobal = new Set();
+    const files = [...testFiles].sort((a, b) => a.localeCompare(b));
+    for (const file of files) {
+        const dir = file.slice(0, file.lastIndexOf('/') + 1);
+        const roots = new Set([file]);
+        for (const candidate of files) {
+            if (candidate === file)
+                continue;
+            const base = candidate.split('/').pop() ?? '';
+            if (candidate.startsWith(dir) && /^head(?:_.*)?\.js$/.test(base)) {
+                roots.add(candidate);
+            }
+        }
+        const result = await runCheckJsGrouped(repoDir, roots, patchLint.checkJsTestShim, projectRoot, mode, TEST_HARNESS_SHIM);
+        const own = result.byFile.get(file);
+        if (own && own.length > 0) {
+            merged.byFile.set(file, [...(merged.byFile.get(file) ?? []), ...own]);
+        }
+        for (const globalIssue of result.global) {
+            if (seenGlobal.has(globalIssue.message))
+                continue;
+            seenGlobal.add(globalIssue.message);
+            merged.global.push(globalIssue);
+        }
+    }
+    return merged;
+}
+/** 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 +481,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-css.js

@@ -15,7 +15,7 @@ import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { hasRawCssColors } from '../utils/regex.js';
 import { loadFurnaceConfig } from './furnace-config.js';
-import { extractAddedLinesPerFile } from './patch-lint-diff.js';
+import { extractAddedLineNumbersPerFile, extractAddedLinesPerFile } from './patch-lint-diff.js';
 /**
  * Loads the furnace token-prefix lint inputs gracefully — returns
  * undefined (skipping the token-prefix check) when furnace.json cannot
@@ -38,11 +38,48 @@ async function loadCssTokenContext(repoDir) {
     }
     return undefined;
 }
+/**
+ * Masks CSS block comments with spaces, preserving newlines so line
+ * numbers stay stable. An unclosed trailing `/*` is masked to EOF —
+ * matching how a CSS parser treats it (FORGE G4).
+ */
+function maskCssComments(source) {
+    const masked = source.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+    const openerIndex = masked.indexOf('/*');
+    if (openerIndex === -1)
+        return masked;
+    return (masked.slice(0, openerIndex) +
+        masked
+            .slice(openerIndex)
+            .split('\n')
+            .map((line) => ' '.repeat(line.length))
+            .join('\n'));
+}
+const RAW_COLOR_IGNORE_MARKER = 'fireforge-ignore: raw-color-value';
+/**
+ * Builds the scan source for the diff branch with full-file comment
+ * awareness: comments are masked across the whole post-patch file so a
+ * comment spanning the context/added boundary suppresses its hex, then
+ * only the patch's added line numbers are scanned. Returns undefined
+ * when any added line number falls outside the on-disk file (patch not
+ * applied / drifted) — the caller then falls back to the legacy
+ * joined-added-lines scan rather than misattributing lines.
+ */
+function buildAddedLinesScanSource(rawCss, addedNumbers) {
+    const rawLines = rawCss.split('\n');
+    if (!addedNumbers.every((n) => n >= 1 && n <= rawLines.length))
+        return undefined;
+    const maskedLines = maskCssComments(rawCss).split('\n');
+    return addedNumbers
+        .filter((n) => !(rawLines[n - 1] ?? '').includes(RAW_COLOR_IGNORE_MARKER))
+        .map((n) => maskedLines[n - 1] ?? '')
+        .join('\n');
+}
 /**
  * Raw-color check for one patched CSS file, scoped to introduced lines
  * when diff context is available. Pushes onto `issues`.
  */
-function checkRawColorValues(file, rawCss, addedLinesByFile, config, issues) {
+function checkRawColorValues(file, rawCss, addedLinesByFile, addedLineNumbersByFile, config, issues) {
     // Check only introduced raw color values when diff context is available.
     // Skip files on the raw-color allowlist (exact path or basename match) and
     // auto-exempt files under `browser/branding/` — those are the fork's
@@ -55,25 +92,33 @@ function checkRawColorValues(file, rawCss, addedLinesByFile, config, issues) {
     const allowlist = config?.patchLint?.rawColorAllowlist;
     const isAllowlisted = allowlist?.some((entry) => file === entry || file.endsWith('/' + entry));
     const isBranding = file.startsWith('browser/branding/');
-    if (!isAllowlisted && !isBranding) {
-        // Strip lines with inline fireforge-ignore: raw-color-value suppression.
-        // Check against rawCss (before comment stripping) so the CSS comment marker is still present.
+    if (isAllowlisted || isBranding)
+        return;
+    let suppressedContent;
+    const addedNumbers = addedLineNumbersByFile?.get(file);
+    if (addedNumbers !== undefined) {
+        suppressedContent = buildAddedLinesScanSource(rawCss, addedNumbers);
+    }
+    if (suppressedContent === undefined) {
+        // Legacy scan: full file (no diff), or the joined added lines when
+        // the diff and on-disk file disagree. Waiver lines are filtered
+        // against the pre-strip text so the CSS comment marker is present.
         const sourceForSuppression = addedLinesByFile
             ? (addedLinesByFile.get(file) ?? []).join('\n')
             : rawCss;
-        const suppressedContent = sourceForSuppression
+        suppressedContent = sourceForSuppression
             .split('\n')
-            .filter((line) => !line.includes('fireforge-ignore: raw-color-value'))
+            .filter((line) => !line.includes(RAW_COLOR_IGNORE_MARKER))
             .join('\n')
             .replace(/\/\*[\s\S]*?\*\//g, '');
-        if (hasRawCssColors(suppressedContent)) {
-            issues.push({
-                file,
-                check: 'raw-color-value',
-                message: 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.',
-                severity: 'error',
-            });
-        }
+    }
+    if (hasRawCssColors(suppressedContent)) {
+        issues.push({
+            file,
+            check: 'raw-color-value',
+            message: 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.',
+            severity: 'error',
+        });
     }
 }
 /**
@@ -157,6 +202,9 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
     const tokenContext = await loadCssTokenContext(repoDir);
     const issues = [];
     const addedLinesByFile = diffContent ? extractAddedLinesPerFile(diffContent) : undefined;
+    const addedLineNumbersByFile = diffContent
+        ? extractAddedLineNumbersPerFile(diffContent)
+        : undefined;
     for (const file of cssFiles) {
         const filePath = join(repoDir, file);
         if (!(await pathExists(filePath)))
@@ -164,7 +212,7 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
         const rawCss = await readText(filePath);
         // Strip block comments before scanning
         const cssContent = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
-        checkRawColorValues(file, rawCss, addedLinesByFile, config, issues);
+        checkRawColorValues(file, rawCss, addedLinesByFile, addedLineNumbersByFile, config, issues);
         checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues);
     }
     return issues;

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

@@ -18,6 +18,14 @@ export declare function detectNewFilesInDiff(diffContent: string): Set<string>;
  * Returns a map of file path → array of added line contents (without the leading `+`).
  */
 export declare function extractAddedLinesPerFile(diffContent: string): Map<string, string[]>;
+/**
+ * Extracts 1-based post-patch line numbers of added lines per file from a
+ * unified diff. Walking each hunk with a new-file line counter (`+` and
+ * context lines advance it, `-` lines do not) lets rules that need
+ * full-file context — e.g. comment masking across the context/added
+ * boundary (FORGE G4) — map the patch's additions onto the applied file.
+ */
+export declare function extractAddedLineNumbersPerFile(diffContent: string): Map<string, number[]>;
 /**
  * Builds the `modifiedFileAdditions` map the cross-patch lint expects for
  * a given unified diff. Exposed so callers that construct synthetic /

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

@@ -45,6 +45,37 @@ export function extractAddedLinesPerFile(diffContent) {
     }
     return result;
 }
+/**
+ * Extracts 1-based post-patch line numbers of added lines per file from a
+ * unified diff. Walking each hunk with a new-file line counter (`+` and
+ * context lines advance it, `-` lines do not) lets rules that need
+ * full-file context — e.g. comment masking across the context/added
+ * boundary (FORGE G4) — map the patch's additions onto the applied file.
+ */
+export function extractAddedLineNumbersPerFile(diffContent) {
+    const result = new Map();
+    for (const section of parseDiffSections(diffContent)) {
+        for (const hunk of section.hunks) {
+            let newLine = hunk.newStart;
+            for (const line of hunk.lines) {
+                if (line.startsWith('\\'))
+                    continue; // ""
+                if (line.startsWith('-'))
+                    continue;
+                if (line.startsWith('+')) {
+                    let arr = result.get(section.targetPath);
+                    if (!arr) {
+                        arr = [];
+                        result.set(section.targetPath, arr);
+                    }
+                    arr.push(newLine);
+                }
+                newLine++;
+            }
+        }
+    }
+    return result;
+}
 /**
  * Builds the `modifiedFileAdditions` map the cross-patch lint expects for
  * a given unified diff. Exposed so callers that construct synthetic /

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

@@ -41,3 +41,24 @@ export declare function resolvePatchOwnedSysMjs(currentNewFiles: Set<string>, pa
  * @returns Set of patch-owned chrome-subscript file paths
  */
 export declare function resolvePatchOwnedChromeScripts(currentNewFiles: Set<string>, patchQueueCtx?: PatchQueueContext): Set<string>;
+/**
+ * Test-script predicate for the `checkJsTestFiles` pass (FORGE G5):
+ * plain `.js` files (not `.sys.mjs` modules) that live under a `/test/`
+ * path or carry a `browser_` / `test_` / `xpcshell_` basename. Duplicates
+ * `patch-lint.ts`'s `isTestFile` shape rather than importing it —
+ * patch-lint.ts imports this module, so the reverse edge would create an
+ * import cycle (dpdm gate). The agreement is pinned by
+ * `patch-lint-ownership.test.ts`.
+ */
+export declare function isTestScriptFile(file: string): boolean;
+/**
+ * Returns the set of patch-owned test `.js` files (FORGE G5). Same
+ * ownership semantics as {@link resolvePatchOwnedSysMjs}; consumed by the
+ * `patchLint.checkJsTestFiles` pass, which checks each as its own small
+ * script-scope program.
+ *
+ * @param currentNewFiles - Files newly created in the current diff
+ * @param patchQueueCtx - Optional cross-patch context for queue-wide ownership
+ * @returns Set of patch-owned test-script file paths
+ */
+export declare function resolvePatchOwnedTestScripts(currentNewFiles: Set<string>, patchQueueCtx?: PatchQueueContext): Set<string>;