@hominis/fireforge 0.32.0 → 0.33.0

package/dist/src/core/furnace-apply-ftl.js

@@ -11,10 +11,106 @@
  */
 import { join, relative } from 'node:path';
 import { toError } from '../utils/errors.js';
-import { copyFile, pathExists } from '../utils/fs.js';
+import { copyFile, pathExists, readText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
 import { resolveFtlChromeSubPath, resolveFtlLocaleJarMnPath } from './furnace-constants.js';
 import { addLocaleFtlJarMnEntry, removeLocaleFtlJarMnEntry } from './furnace-registration.js';
 import { snapshotFile } from './furnace-rollback.js';
+/**
+ * Builds the presence regex for a per-widget locale jar.mn line
+ * (`locale/@AB_CD@/<chromeSubPath>/<tagName>.ftl`). Shared by the prune
+ * helper and its dry-run describer so both agree on what "dangling" means.
+ */
+function perWidgetLocaleEntryPattern(chromeSubPath, tagName) {
+    return new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapeRegex(chromeSubPath)}\\/${escapeRegex(tagName)}\\.ftl`, 'm');
+}
+/**
+ * Resolves the engine-relative locale jar.mn and the per-widget entry regex
+ * for a `sharedFtl` widget, or `undefined` when the FTL tree exposes no
+ * locale jar.mn we can confidently name.
+ */
+function resolveSharedFtlPruneTarget(name, ftlDir) {
+    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
+    const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
+    if (chromeSubPath === undefined || localeJarRel === undefined)
+        return undefined;
+    return { localeJarRel, pattern: perWidgetLocaleEntryPattern(chromeSubPath, name) };
+}
+/**
+ * Removes a dangling per-widget locale jar.mn entry for a `sharedFtl` widget.
+ *
+ * A `localized: true` widget that opts into a feature-scoped `sharedFtl`
+ * bundle (its strings live under `browser/...` and load via
+ * `insertFTLIfNeeded`) must NOT carry a per-widget
+ * `locale/@AB_CD@/<chromeSubPath>/<name>.ftl` line. Such a line — written by
+ * an older FireForge before the sharedFtl apply guard, or by a layout
+ * migration — points at a `.ftl` that does not exist, so `mach build` fails
+ * hard (`Cannot find <chromeSubPath>/<name>.ftl`) and blocks every build.
+ *
+ * The pruned line is the per-widget toolkit entry only; the shared bundle's
+ * own line (a different chrome sub-path / base name) is never matched, so
+ * pruning one widget cannot orphan the shared bundle. Idempotent: when no
+ * dangling entry exists the file is left untouched (no journal churn).
+ * Returns the engine-relative jar.mn path when a line was removed, else
+ * `undefined`.
+ */
+async function pruneSharedFtlPerWidgetLocaleEntry(engineDir, name, ftlDir, config, rollbackJournal) {
+    if (!config.sharedFtl)
+        return undefined;
+    const target = resolveSharedFtlPruneTarget(name, ftlDir);
+    if (!target)
+        return undefined;
+    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
+    if (chromeSubPath === undefined)
+        return undefined;
+    const localeJarAbs = join(engineDir, target.localeJarRel);
+    if (!(await pathExists(localeJarAbs)))
+        return undefined;
+    if (!target.pattern.test(await readText(localeJarAbs)))
+        return undefined;
+    if (rollbackJournal) {
+        await snapshotFile(rollbackJournal, localeJarAbs);
+    }
+    await removeLocaleFtlJarMnEntry(engineDir, target.localeJarRel, name, chromeSubPath);
+    return target.localeJarRel;
+}
+/**
+ * Apply-path wrapper around {@link pruneSharedFtlPerWidgetLocaleEntry} that
+ * records the affected path / step error in the caller's collectors, mirroring
+ * {@link applyCustomFtlFile}'s contract so the main apply helper stays terse.
+ */
+export async function applySharedFtlPrune(engineDir, name, ftlDir, config, affectedPaths, stepErrors, rollbackJournal) {
+    try {
+        const prunedPath = await pruneSharedFtlPerWidgetLocaleEntry(engineDir, name, ftlDir, config, rollbackJournal);
+        if (prunedPath)
+            affectedPaths.push(prunedPath);
+    }
+    catch (error) {
+        stepErrors.push({ step: 'locale jar.mn prune', error: toError(error).message });
+    }
+}
+/**
+ * Read-only dry-run describer for {@link pruneSharedFtlPerWidgetLocaleEntry}:
+ * returns an action when a dangling per-widget locale entry exists for a
+ * `sharedFtl` widget, else `undefined`.
+ */
+export async function describeSharedFtlPrune(engineDir, name, ftlDir, config) {
+    if (!config.sharedFtl)
+        return undefined;
+    const target = resolveSharedFtlPruneTarget(name, ftlDir);
+    if (!target)
+        return undefined;
+    const localeJarAbs = join(engineDir, target.localeJarRel);
+    if (!(await pathExists(localeJarAbs)))
+        return undefined;
+    if (!target.pattern.test(await readText(localeJarAbs)))
+        return undefined;
+    return {
+        component: name,
+        action: 'register-jar',
+        description: `Remove dangling per-widget locale entry for ${name} from ${target.localeJarRel} (sharedFtl bundle owns its strings)`,
+    };
+}
 /**
  * Copies a component's `.ftl` into the FTL tree and registers the chrome URI
  * in the locale jar.mn.

package/dist/src/core/furnace-apply-helpers.js

@@ -6,10 +6,11 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { copyFile, ensureDir, pathExists, readText, removeFile } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
-import { applyCustomFtlFile, describeLocaleFtlJarMnRegistration, removeCustomFtlJarMnEntry, } from './furnace-apply-ftl.js';
+import { buildCustomDryRunActions } from './furnace-apply-dry-run.js';
+import { applyCustomFtlFile, applySharedFtlPrune, removeCustomFtlJarMnEntry, } from './furnace-apply-ftl.js';
 import { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
-import { deployFileWithFragments, describeFragmentExpansion, SHARED_FRAGMENTS_DIR, } from './furnace-css-fragments.js';
-import { addCustomElementRegistration, addJarMnEntries, validateCustomElementRegistration, validateJarMnInsertionForFiles, } from './furnace-registration.js';
+import { deployFileWithFragments, SHARED_FRAGMENTS_DIR } from './furnace-css-fragments.js';
+import { addCustomElementRegistration, addJarMnEntries } from './furnace-registration.js';
 import { recordCreatedDir, snapshotFile } from './furnace-rollback.js';
 import { checkRegistrationConsistency } from './furnace-validate-registration.js';
 import { isGitRepository } from './git.js';
@@ -278,83 +279,6 @@ export async function hasCustomEngineDrift(root, name, componentDir, config, ftl
     }
     return false;
 }
-async function buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries, ftlDir) {
-    const actions = [];
-    const stepErrors = [];
-    for (const entry of entries) {
-        if (!isRegularFile(entry))
-            continue;
-        if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.css'))
-            continue;
-        const fragmentNote = await describeFragmentExpansion(join(componentDir, entry.name));
-        actions.push({
-            component: name,
-            action: fragmentNote ? 'expand-fragments' : 'copy',
-            source: join(componentDir, entry.name),
-            target: join(targetDir, entry.name),
-            description: `Copy ${entry.name} to ${config.targetPath}${fragmentNote}`,
-        });
-    }
-    // Per-component .ftl handling is skipped when the component opts into a
-    // shared feature-scoped bundle via `sharedFtl`. The shared file is
-    // registered (and copied) by whoever owns the feature bundle, so
-    // emitting a copy-ftl / register-jar action here would duplicate (or
-    // later orphan) the entry.
-    if (config.localized && !config.sharedFtl) {
-        const ftlFile = `${name}.ftl`;
-        const ftlSrc = join(componentDir, ftlFile);
-        if (await pathExists(ftlSrc)) {
-            actions.push({
-                component: name,
-                action: 'copy-ftl',
-                source: ftlSrc,
-                target: join(engineDir, ftlDir, ftlFile),
-                description: `Copy ${ftlFile} to ${ftlDir}`,
-            });
-            const localeAction = describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile);
-            if (localeAction) {
-                actions.push(localeAction);
-            }
-        }
-    }
-    if (config.register) {
-        try {
-            const modulePath = `chrome://global/content/elements/${name}.mjs`;
-            await validateCustomElementRegistration(engineDir, name, modulePath);
-        }
-        catch (error) {
-            stepErrors.push({
-                step: 'customElements.js registration',
-                error: toError(error).message,
-            });
-        }
-        actions.push({
-            component: name,
-            action: 'register-ce',
-            description: `Register ${name} in customElements.js (DOMContentLoaded block)`,
-        });
-    }
-    const copiedFileNames = entries
-        .filter((entry) => isRegularFile(entry) && (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')))
-        .map((entry) => entry.name);
-    if (copiedFileNames.length > 0) {
-        try {
-            await validateJarMnInsertionForFiles(engineDir, name, copiedFileNames);
-        }
-        catch (error) {
-            stepErrors.push({
-                step: 'jar.mn registration',
-                error: toError(error).message,
-            });
-        }
-        actions.push({
-            component: name,
-            action: 'register-jar',
-            description: `Add ${copiedFileNames.join(', ')} to jar.mn`,
-        });
-    }
-    return { actions, stepErrors };
-}
 /** Applies a custom component into the engine tree and captures registration step errors. */
 export async function applyCustomComponent(engineDir, name, componentDir, config, ftlDir, dryRun = false, rollbackJournal, applyOptions = {}) {
     if (!/^[a-z][a-z0-9-]*$/.test(name)) {
@@ -406,6 +330,12 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
     if (config.localized && !config.sharedFtl) {
         await applyCustomFtlFile(engineDir, name, componentDir, ftlDir, affectedPaths, stepErrors, rollbackJournal);
     }
+    else if (config.localized && config.sharedFtl) {
+        // Drop any dangling per-widget locale jar.mn entry that would point at a
+        // non-existent `<chromeSubPath>/<name>.ftl` and fail `mach build`. The
+        // shared bundle (a different chrome path/base name) is never touched.
+        await applySharedFtlPrune(engineDir, name, ftlDir, config, affectedPaths, stepErrors, rollbackJournal);
+    }
     if (config.register) {
         try {
             const modulePath = `chrome://global/content/elements/${name}.mjs`;

package/dist/src/core/mach-resource-shim.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resource-monitor degrade shim for `mach build`.
+ *
+ * mozbuild's build resource monitor calls `psutil.virtual_memory()` at
+ * startup (`start_resource_recording`). On some hosts (psutil vs Darwin 27)
+ * that raises `RuntimeError: host_statistics64(HOST_VM_INFO64) syscall
+ * failed`, which aborts `mach build` / `mach build faster` before any work
+ * happens — so a raw `./mach build faster` dies while the build never
+ * reaches the compiler. The suite-specific test commands sidestep the
+ * monitor entirely, but the build commands have no such escape.
+ *
+ * FireForge writes a tiny `sitecustomize.py` and points the mach
+ * subprocess's `PYTHONPATH` at it. Python imports `sitecustomize` at
+ * interpreter startup (before mach runs), so the shim wraps
+ * `psutil.virtual_memory` / `swap_memory` to downgrade the host syscall
+ * failure into a non-fatal `UserWarning` and return a zeroed reading. The
+ * build then proceeds regardless of which mach entry point spawned it. When
+ * psutil works normally the wrapper is a transparent pass-through.
+ */
+/** Ensures the shim exists and returns the mach `env` overlay that enables it. */
+export declare function resolveMachBuildEnv(): Promise<Record<string, string>>;

package/dist/src/core/mach-resource-shim.js

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Resource-monitor degrade shim for `mach build`.
+ *
+ * mozbuild's build resource monitor calls `psutil.virtual_memory()` at
+ * startup (`start_resource_recording`). On some hosts (psutil vs Darwin 27)
+ * that raises `RuntimeError: host_statistics64(HOST_VM_INFO64) syscall
+ * failed`, which aborts `mach build` / `mach build faster` before any work
+ * happens — so a raw `./mach build faster` dies while the build never
+ * reaches the compiler. The suite-specific test commands sidestep the
+ * monitor entirely, but the build commands have no such escape.
+ *
+ * FireForge writes a tiny `sitecustomize.py` and points the mach
+ * subprocess's `PYTHONPATH` at it. Python imports `sitecustomize` at
+ * interpreter startup (before mach runs), so the shim wraps
+ * `psutil.virtual_memory` / `swap_memory` to downgrade the host syscall
+ * failure into a non-fatal `UserWarning` and return a zeroed reading. The
+ * build then proceeds regardless of which mach entry point spawned it. When
+ * psutil works normally the wrapper is a transparent pass-through.
+ */
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { ensureDir, writeText } from '../utils/fs.js';
+/** Directory name (under the OS temp dir) holding the generated shim. */
+const RESOURCE_SHIM_DIRNAME = 'fireforge-mach-resource-shim';
+/**
+ * `sitecustomize.py` body. Defensive: a missing/broken psutil leaves mach
+ * untouched, and the wrapper only intercepts the failure path.
+ */
+const SITECUSTOMIZE_SOURCE = `# Generated by FireForge — do not edit.
+# Degrades a broken host resource monitor (psutil vs Darwin) from a fatal
+# RuntimeError in start_resource_recording into a non-fatal warning, so
+# \`mach build\` does not abort before the build runs. Loaded via PYTHONPATH
+# so it patches psutil before mach's resource monitor starts.
+import warnings
+
+try:
+    import psutil
+except Exception:
+    psutil = None
+
+if psutil is not None:
+    class _DegradedReading(object):
+        total = available = used = free = active = inactive = wired = 0
+        percent = 0.0
+
+        def __getattr__(self, _name):
+            return 0
+
+    def _guard(orig):
+        def wrapper(*args, **kwargs):
+            try:
+                return orig(*args, **kwargs)
+            except Exception as exc:  # noqa: BLE001
+                warnings.warn(
+                    "FireForge: host resource monitor degraded (%s); build continues." % exc
+                )
+                return _DegradedReading()
+
+        return wrapper
+
+    for _name in ("virtual_memory", "swap_memory"):
+        _orig = getattr(psutil, _name, None)
+        if _orig is not None:
+            setattr(psutil, _name, _guard(_orig))
+`;
+/**
+ * Writes the `sitecustomize.py` degrade shim into a stable FireForge-owned
+ * temp directory and returns that directory. Idempotent — overwriting the
+ * file each call keeps it in sync with this source if FireForge upgrades.
+ */
+async function ensureMachResourceShim() {
+    const dir = join(tmpdir(), RESOURCE_SHIM_DIRNAME);
+    await ensureDir(dir);
+    await writeText(join(dir, 'sitecustomize.py'), SITECUSTOMIZE_SOURCE);
+    return dir;
+}
+/**
+ * Builds the `env` overlay (merged over `process.env` by the exec layer)
+ * that prepends the shim directory to `PYTHONPATH`, so the mach subprocess
+ * imports the degrade `sitecustomize` without clobbering an existing
+ * `PYTHONPATH`.
+ */
+function machResourceShimEnv(shimDir, baseEnv = process.env) {
+    const existing = baseEnv['PYTHONPATH'];
+    return { PYTHONPATH: existing ? `${shimDir}${delimiter}${existing}` : shimDir };
+}
+/** Ensures the shim exists and returns the mach `env` overlay that enables it. */
+export async function resolveMachBuildEnv() {
+    return machResourceShimEnv(await ensureMachResourceShim());
+}
+//# sourceMappingURL=mach-resource-shim.js.map

package/dist/src/core/mach.js

@@ -8,6 +8,7 @@ import { createSiblingLockPath, withFileLock } from './file-lock.js';
 import { ensureFirefoxIgnorefileCompatibility } from './firefox-ignorefile.js';
 import { explainMachError } from './mach-error-hints.js';
 import { getPython } from './mach-python.js';
+import { resolveMachBuildEnv } from './mach-resource-shim.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
 export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, } from './mach-build-artifacts.js';
 export { generateMozconfig } from './mach-mozconfig.js';
@@ -156,7 +157,10 @@ export async function build(engineDir, jobs) {
     if (jobs !== undefined) {
         args.push('-j', String(jobs));
     }
-    const result = await runMachInheritCapture(args, engineDir);
+    // Inject the resource-monitor degrade shim so a host psutil failure does
+    // not abort the build regardless of which mach entry FireForge spawns.
+    const env = await resolveMachBuildEnv();
+    const result = await runMachInheritCapture(args, engineDir, { env });
     if (result.exitCode !== 0) {
         surfaceMachErrorHints(result);
     }
@@ -170,7 +174,10 @@ export async function build(engineDir, jobs) {
  * @returns Captured mach result
  */
 export async function buildUI(engineDir) {
-    const result = await runMachInheritCapture(['build', 'faster'], engineDir);
+    // Same resource-monitor degrade shim as the full build: raw
+    // `./mach build faster` aborts on the host psutil monitor without it.
+    const env = await resolveMachBuildEnv();
+    const result = await runMachInheritCapture(['build', 'faster'], engineDir, { env });
     if (result.exitCode !== 0) {
         surfaceMachErrorHints(result);
     }

package/dist/src/core/manifest-helpers.js

@@ -1,3 +1,28 @@
+/**
+ * Ordering comparator matching mozbuild's `StrictOrderingOnAppendList`
+ * (`mozbuild.util.UnsortedError`): entries are compared **case-insensitively**,
+ * so `HominisAppearanceController` (`appe`) sorts before
+ * `HominisAppMenuIntegration` (`appm`) even though a raw byte comparison
+ * places the uppercase `M` (0x4D) before the lowercase `e` (0x65).
+ *
+ * A naive `a > b` insertion landed the new entry in byte order, which
+ * `mach configure` then rejected with `UnsortedError`, aborting the build.
+ * Ties on the lower-cased key fall back to byte order so the comparison is
+ * total and stable.
+ */
+function mozbuildSortCompare(a, b) {
+    const la = a.toLowerCase();
+    const lb = b.toLowerCase();
+    if (la < lb)
+        return -1;
+    if (la > lb)
+        return 1;
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
 /**
  * Inserts a line into an array of lines in alphabetical order within a
  * specified range. The comparison key is extracted from each line.
@@ -16,7 +41,7 @@ export function findAlphabeticalPosition(lines, startLine, endLine, newKey, extr
             existingKeys.push(key);
         }
     }
-    const isSorted = existingKeys.every((k, idx) => idx === 0 || k.localeCompare(existingKeys[idx - 1] ?? '') >= 0);
+    const isSorted = existingKeys.every((k, idx) => idx === 0 || mozbuildSortCompare(k, existingKeys[idx - 1] ?? '') >= 0);
     if (!isSorted) {
         return { insertIndex: endLine, previousEntry: undefined };
     }
@@ -29,7 +54,7 @@ export function findAlphabeticalPosition(lines, startLine, endLine, newKey, extr
         const key = extractKey(line);
         if (key === undefined)
             continue;
-        if (key > newKey) {
+        if (mozbuildSortCompare(key, newKey) > 0) {
             insertIndex = i;
             break;
         }
@@ -61,7 +86,7 @@ export function findAlphabeticalTokenPosition(tokens, sectionTargetPattern, newK
             continue;
         const match = sectionTargetPattern.exec(entry.parsed.target);
         const key = match?.[1] ?? entry.parsed.target;
-        if (key > newKey) {
+        if (mozbuildSortCompare(key, newKey) > 0) {
             insertLineIndex = entry.lineIndex;
             break;
         }
@@ -84,7 +109,7 @@ export function findAlphabeticalMozBuildPosition(tokens, newKey) {
     let previousEntry;
     for (const item of items) {
         const key = item.parsed?.value ?? '';
-        if (key > newKey) {
+        if (mozbuildSortCompare(key, newKey) > 0) {
             insertLineIndex = item.lineIndex;
             break;
         }

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

@@ -180,6 +180,37 @@ export declare function findForwardImportIgnoreLines(source: string): Set<number
  *   engine file — not our concern).
  * - Imports on a line suppressed by the ignore marker.
  */
+/** One discovered forward-import edge: a site importing a later-created file. */
+export interface ForwardImportEdge {
+    /** Importing patch filename. */
+    entry: string;
+    /** Importing file path relative to engine/. */
+    sitePath: string;
+    /** Exact import specifier as it appears in source. */
+    specifier: string;
+    /** Specifier with any query/hash stripped (used for fingerprints). */
+    cleaned: string;
+    /** Later-ordered patch creating the imported file. */
+    owner: string;
+    /** Path of the later-created file (relative to engine/). */
+    creates: string;
+}
+/**
+ * Returns every forward-import edge in the queue, one per (site, later
+ * creator) pair, regardless of any staged-dependency declarations. Used by
+ * `patch split` to discover the forward edges it introduces into the new
+ * patch so it can auto-declare them (and so its projected lint matches the
+ * real per-patch gate).
+ */
+export declare function collectForwardImportEdges(ctx: PatchQueueContext): ForwardImportEdge[];
+/**
+ * Cross-patch lint rule: flag imports of a module a later-ordered patch is
+ * responsible for creating, unless the patch declares an exact staged
+ * forward-import for it. Also warns on staged-dependency declarations that
+ * never matched (stale). Matching is conservative — by basename, not by
+ * resolving `resource://`/`chrome://` URLs — with an inline ignore marker as
+ * an escape hatch for unrelated basename collisions.
+ */
 export declare function lintPatchQueueForwardImports(ctx: PatchQueueContext): PatchLintIssue[];
 /**
  * Cross-patch lint orchestrator. Runs every cross-patch rule against the

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

@@ -343,27 +343,8 @@ function findMatchingStagedDependency(entry, sitePath, specifier, laterOwners) {
         laterOwners.some((owner) => owner.fullPath === dependency.creates &&
             (dependency.owner === undefined || dependency.owner === owner.filename)));
 }
-/**
- * Cross-patch lint rule: a patch imports a module that a later patch is
- * responsible for creating.
- *
- * Approach is deliberately conservative — we do not resolve `resource://`
- * URLs to engine file paths. Instead we build a cross-queue index of
- * newly-created files keyed by their basename, and flag imports whose leaf
- * matches an entry owned by a later-ordered patch. False positives from
- * unrelated basename collisions (two different directories happening to
- * create files named `Helper.sys.mjs`) are possible; the README documents
- * the limitation and the inline ignore marker above provides an escape
- * hatch.
- *
- * Rules out:
- * - Imports whose leaf matches a newly-created file in the *same* or an
- *   *earlier* patch (legitimate use).
- * - Imports whose leaf is not in the new-file index at all (pre-existing
- *   engine file — not our concern).
- * - Imports on a line suppressed by the ignore marker.
- */
-export function lintPatchQueueForwardImports(ctx) {
+/** Builds the basename → later-creators index used by the forward-import scan. */
+function buildNewFileIndex(ctx) {
     const newFileIndex = new Map();
     for (const entry of ctx.entries) {
         for (const fullPath of entry.newFiles.keys()) {
@@ -376,23 +357,24 @@ export function lintPatchQueueForwardImports(ctx) {
             owners.push({ filename: entry.filename, order: entry.order, fullPath });
         }
     }
-    const issues = [];
-    const usedStagedDeclarations = new Set();
-    // Runs the forward-import check against one source site — either a file
-    // the patch creates (`content` = full file) or a file the patch modifies
-    // (`content` = concatenated added lines only). We deliberately scan added
-    // lines rather than the full resulting file for modifications: we only
-    // want to flag imports *this patch introduces*, not imports that already
-    // exist on HEAD and happen to match a later-created file by coincidence.
+    return newFileIndex;
+}
+/**
+ * Visits every forward-import site (an import whose leaf is created by a
+ * later-ordered patch). Shared by {@link lintPatchQueueForwardImports} (which
+ * resolves/reports each) and {@link collectForwardImportEdges} (which returns
+ * them structurally). We scan a created file's full body and a modified
+ * file's added lines only — flagging imports *this patch introduces*, not
+ * pre-existing HEAD imports that happen to collide with a later-created file.
+ */
+function eachForwardImportSite(ctx, newFileIndex, visit) {
     const checkSite = (entry, sitePath, content) => {
         if (!isForwardImportableFile(sitePath))
             return;
         const ignoreLines = findForwardImportIgnoreLines(content);
-        const extracted = extractImportSpecifiersWithLines(content);
-        for (const { specifier, line } of extracted) {
+        for (const { specifier, line } of extractImportSpecifiersWithLines(content)) {
             if (ignoreLines.has(line))
                 continue;
-            // Take the leaf and strip query/hash if any.
             const cleaned = specifier.split(/[?#]/)[0] ?? specifier;
             const leaf = basename(cleaned);
             if (!leaf || !isForwardImportableFile(leaf))
@@ -400,41 +382,11 @@ export function lintPatchQueueForwardImports(ctx) {
             const owners = newFileIndex.get(leaf);
             if (!owners)
                 continue;
-            // Is the owner a later-ordered patch (or one ordered equal but
-            // lexicographically later as a tiebreaker)?
             const laterOwners = owners.filter((owner) => owner.order > entry.order ||
                 (owner.order === entry.order && owner.filename > entry.filename));
             if (laterOwners.length === 0)
                 continue;
-            const stagedDependency = findMatchingStagedDependency(entry, sitePath, specifier, laterOwners);
-            if (stagedDependency) {
-                usedStagedDeclarations.add(stagedDependencyKey(entry, stagedDependency));
-                continue;
-            }
-            const ownersSummary = laterOwners
-                .map((o) => `${o.filename} (creates ${o.fullPath})`)
-                .join(', ');
-            const fingerprintOwners = [...laterOwners]
-                .map((o) => `${o.filename}:${o.fullPath}`)
-                .sort((a, b) => a.localeCompare(b))
-                .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.
-            const suggestedOrder = Math.max(...laterOwners.map((o) => o.order)) + 1;
-            issues.push({
-                file: sitePath,
-                check: 'forward-import',
-                fingerprint: `forward-import|${sitePath}|${cleaned}|${fingerprintOwners}`,
-                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 ' +
-                    `"// ${FORWARD_IMPORT_IGNORE_MARKER}" if the basename collision is a false positive. ` +
-                    `Closest legal ordinal that satisfies this dependency: ${suggestedOrder}.`,
-                severity: 'error',
-            });
+            visit(entry, sitePath, specifier, cleaned, laterOwners);
         }
     };
     for (const entry of ctx.entries) {
@@ -443,6 +395,74 @@ export function lintPatchQueueForwardImports(ctx) {
         for (const [path, added] of entry.modifiedFileAdditions)
             checkSite(entry, path, added);
     }
+}
+/**
+ * Returns every forward-import edge in the queue, one per (site, later
+ * creator) pair, regardless of any staged-dependency declarations. Used by
+ * `patch split` to discover the forward edges it introduces into the new
+ * patch so it can auto-declare them (and so its projected lint matches the
+ * real per-patch gate).
+ */
+export function collectForwardImportEdges(ctx) {
+    const newFileIndex = buildNewFileIndex(ctx);
+    const edges = [];
+    eachForwardImportSite(ctx, newFileIndex, (entry, sitePath, specifier, cleaned, laterOwners) => {
+        for (const owner of laterOwners) {
+            edges.push({
+                entry: entry.filename,
+                sitePath,
+                specifier,
+                cleaned,
+                owner: owner.filename,
+                creates: owner.fullPath,
+            });
+        }
+    });
+    return edges;
+}
+/**
+ * Cross-patch lint rule: flag imports of a module a later-ordered patch is
+ * responsible for creating, unless the patch declares an exact staged
+ * forward-import for it. Also warns on staged-dependency declarations that
+ * never matched (stale). Matching is conservative — by basename, not by
+ * resolving `resource://`/`chrome://` URLs — with an inline ignore marker as
+ * an escape hatch for unrelated basename collisions.
+ */
+export function lintPatchQueueForwardImports(ctx) {
+    const newFileIndex = buildNewFileIndex(ctx);
+    const issues = [];
+    const usedStagedDeclarations = new Set();
+    eachForwardImportSite(ctx, newFileIndex, (entry, sitePath, specifier, cleaned, laterOwners) => {
+        const stagedDependency = findMatchingStagedDependency(entry, sitePath, specifier, laterOwners);
+        if (stagedDependency) {
+            usedStagedDeclarations.add(stagedDependencyKey(entry, stagedDependency));
+            return;
+        }
+        const ownersSummary = laterOwners
+            .map((o) => `${o.filename} (creates ${o.fullPath})`)
+            .join(', ');
+        const fingerprintOwners = [...laterOwners]
+            .map((o) => `${o.filename}:${o.fullPath}`)
+            .sort((a, b) => a.localeCompare(b))
+            .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.
+        const suggestedOrder = Math.max(...laterOwners.map((o) => o.order)) + 1;
+        issues.push({
+            file: sitePath,
+            check: 'forward-import',
+            fingerprint: `forward-import|${sitePath}|${cleaned}|${fingerprintOwners}`,
+            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 ' +
+                `"// ${FORWARD_IMPORT_IGNORE_MARKER}" if the basename collision is a false positive. ` +
+                `Closest legal ordinal that satisfies this dependency: ${suggestedOrder}.`,
+            severity: 'error',
+        });
+    });
     for (const entry of ctx.entries) {
         for (const dependency of entry.metadata?.stagedDependencies?.forwardImports ?? []) {
             if (usedStagedDeclarations.has(stagedDependencyKey(entry, dependency)))

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

@@ -2,5 +2,5 @@
  * Public re-exports for {@link ./patch-lint.ts}. Split out so the
  * orchestrator stays within the ESLint `max-lines` budget.
  */
-export { buildPatchQueueContext, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, type PatchQueueContext, type PatchQueueEntry, } from './patch-lint-cross.js';
+export { buildPatchQueueContext, collectForwardImportEdges, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, type ForwardImportEdge, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, type PatchQueueContext, type PatchQueueEntry, } from './patch-lint-cross.js';
 export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';