@hominis/fireforge 0.44.4 → 0.46.0

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

@@ -19,7 +19,9 @@ import { discoverPatches } from './patch-files.js';
 import { lintPatchQueueBinaryBodies } from './patch-lint-binary.js';
 import { collectNewFileCreatorsByPath } from './patch-lint-creators.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
+import { lintPatchQueueForwardRegistrations } from './patch-lint-forward-registration.js';
 import { lintPatchQueueModuleRegistrations } from './patch-lint-module-registration.js';
+import { describeRegistrationFailure, findStagedRegistrationFailure, isLaterOwner, quoteRegistrationLine, } from './patch-lint-staged-registration.js';
 import { loadPatchesManifest } from './patch-manifest-io.js';
 import { categoryRangeForOrder, categoryRangeLabel } from './patch-policy.js';
 import { extractNewFileContent } from './patch-transform.js';
@@ -77,6 +79,9 @@ export async function buildPatchQueueContext(patchesDir, config) {
             metadata: metadataByFilename.get(patch.filename) ?? null,
             diff,
             newFiles,
+            // Straight from the detector, before the text-extraction filter above
+            // drops the bodies it cannot decode.
+            createdFiles: newFilePaths,
             modifiedFileAdditions,
         });
     }
@@ -125,24 +130,6 @@ const FORWARD_IMPORTABLE_EXTENSIONS = ['.mjs', '.sys.mjs', '.js', '.jsm'];
 export function isForwardImportableFile(path) {
     return FORWARD_IMPORTABLE_EXTENSIONS.some((ext) => path.endsWith(ext));
 }
-/**
- * Regex-level extractor for module specifiers in ES module / subscript files.
- *
- * Intentionally conservative. Catches:
- * - `import ... from "specifier"`   (ES module static imports)
- * - `import "specifier"`            (side-effect imports — the `from`
- *                                   clause is optional in the regex)
- * - `import("specifier")`           (dynamic imports)
- * - ChromeUtils.importESModule("specifier")
- * - ChromeUtils.defineESModuleGetters(obj, { Name: "specifier", ... })
- *
- * Returns the raw specifier strings — callers should take the leaf basename
- * to match against the newFileIndex, because we do not resolve `resource://`
- * URLs to engine file paths.
- */
-export function extractImportSpecifiers(source) {
-    return extractImportSpecifiersWithLines(source).map((item) => item.specifier);
-}
 function buildLineOffsets(source) {
     const offsets = [0];
     for (let i = 0; i < source.length; i++) {
@@ -236,7 +223,7 @@ function collectGetterSpecifiers(stripped, results, offsetToLine) {
 }
 /**
  * Returns import specifiers plus 0-indexed line numbers, preserving the
- * same matching behavior as {@link extractImportSpecifiers}.
+ * same matching behavior as {@link extractImportSpecifiersWithLines}.
  */
 export function extractImportSpecifiersWithLines(source) {
     // stripJsComments replaces comment bodies with space runs of equal
@@ -290,8 +277,8 @@ 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] ?? '');
+    for (const [i, line] of lines.entries()) {
+        const match = BARE_GETTER_PROPERTY_LINE.exec(line);
         if (match?.[1])
             results.push({ specifier: match[1], line: i });
     }
@@ -323,9 +310,8 @@ export const FORWARD_IMPORT_IGNORE_MARKER = 'fireforge-ignore: forward-import';
 export function findForwardImportIgnoreLines(source) {
     const lines = source.split('\n');
     const ignored = new Set();
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        if (line && line.includes(FORWARD_IMPORT_IGNORE_MARKER)) {
+    for (const [i, line] of lines.entries()) {
+        if (line.includes(FORWARD_IMPORT_IGNORE_MARKER)) {
             ignored.add(i);
             ignored.add(i + 1);
         }
@@ -348,29 +334,44 @@ function findMatchingStagedDependency(entry, sitePath, specifier, laterOwners) {
         laterOwners.some((owner) => owner.fullPath === dependency.creates &&
             (dependency.owner === undefined || dependency.owner === owner.filename)));
 }
-/**
- * Later-in-apply-order predicate shared by the forward-import scan and the
- * registration validation: strictly higher ordinal, or same ordinal with a
- * lexicographically later filename (the apply loop's tiebreak).
- */
-function isLaterOwner(owner, entry) {
-    return (owner.order > entry.order || (owner.order === entry.order && owner.filename > entry.filename));
-}
-/** Builds the basename → later-creators index used by the forward-import scan. */
-function buildNewFileIndex(ctx) {
-    const newFileIndex = new Map();
+/** Builds a basename → creators index from one path set per entry. */
+function buildCreatorIndex(ctx, pathsOf) {
+    const index = new Map();
     for (const entry of ctx.entries) {
-        for (const fullPath of entry.newFiles.keys()) {
+        for (const fullPath of pathsOf(entry)) {
             const leaf = basename(fullPath);
-            let owners = newFileIndex.get(leaf);
+            let owners = index.get(leaf);
             if (!owners) {
                 owners = [];
-                newFileIndex.set(leaf, owners);
+                index.set(leaf, owners);
             }
             owners.push({ filename: entry.filename, order: entry.order, fullPath });
         }
     }
-    return newFileIndex;
+    return index;
+}
+/**
+ * Basename → later-creators index for the forward-IMPORT scan.
+ *
+ * Keyed on `newFiles` deliberately: this index answers "which patch creates
+ * the module this specifier resolves to", and a binary is not a module.
+ */
+function buildNewFileIndex(ctx) {
+    return buildCreatorIndex(ctx, (entry) => entry.newFiles.keys());
+}
+/**
+ * Basename → creators index for the staged-REGISTRATION rules.
+ *
+ * Keyed on `createdFiles`, which includes binary creations. A registration
+ * (`support-files`, a jar.mn line, an actor entry) points at a file that
+ * must EXIST after apply; whether its body was text or a `GIT binary patch`
+ * has nothing to do with it. Resolving this from `newFiles` made a declared
+ * dependency on a binary fixture report `creates-unresolved`, so the
+ * declaration read as stale on every lint run and removing it changed
+ * nothing either — the failure was symmetric and therefore invisible.
+ */
+function buildCreatedFileIndex(ctx) {
+    return buildCreatorIndex(ctx, (entry) => entry.createdFiles);
 }
 /**
  * Visits every forward-import site (an import whose leaf is created by a
@@ -389,9 +390,9 @@ function eachForwardImportSite(ctx, newFileIndex, visit) {
             // 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)}`));
+            const seen = new Set(sites.map((site) => `${site.specifier}|${site.line}`));
             for (const extra of extractBareGetterSpecifiers(content)) {
-                if (!seen.has(`${extra.specifier}|${String(extra.line)}`))
+                if (!seen.has(`${extra.specifier}|${extra.line}`))
                     sites.push(extra);
             }
         }
@@ -453,6 +454,7 @@ export function collectForwardImportEdges(ctx) {
  */
 export function lintPatchQueueForwardImports(ctx) {
     const newFileIndex = buildNewFileIndex(ctx);
+    const createdFileIndex = buildCreatedFileIndex(ctx);
     const issues = [];
     const usedStagedDeclarations = new Set();
     eachForwardImportSite(ctx, newFileIndex, (entry, sitePath, specifier, cleaned, laterOwners) => {
@@ -531,7 +533,7 @@ export function lintPatchQueueForwardImports(ctx) {
         // (with `owner`, when set, naming that patch) — mirroring
         // findMatchingStagedDependency for the import kind.
         for (const registration of entry.metadata?.stagedDependencies?.registrations ?? []) {
-            const failure = findStagedRegistrationFailure(entry, registration, newFileIndex);
+            const failure = findStagedRegistrationFailure(entry, registration, createdFileIndex);
             if (failure === undefined)
                 continue;
             issues.push({
@@ -541,62 +543,16 @@ export function lintPatchQueueForwardImports(ctx) {
                 fingerprint: `staged-dependency-unused|${entry.filename}|${registration.file}|reg:${registration.line}|${registration.creates}|${registration.owner ?? ''}`,
                 message: `${entry.filename} declares a staged registration in ${registration.file} ` +
                     `("${registration.line}") for ${registration.creates}, but ${describeRegistrationFailure(failure)} ` +
-                    'Remove the stale declaration with "fireforge patch staged-dependency --remove --kind registration" or update it to match the patch and queue.',
+                    'Remove the stale declaration with: ' +
+                    `fireforge patch staged-dependency ${entry.filename} --remove --kind registration ` +
+                    `--file ${registration.file} --line "${quoteRegistrationLine(registration.line)}" ` +
+                    `--creates ${registration.creates}; or update it to match the patch and queue.`,
                 severity: 'warning',
             });
         }
     }
     return issues;
 }
-/**
- * Validates one registration-kind declaration against the patch content
- * and the queue, mirroring {@link findMatchingStagedDependency}: the
- * declared line must be added by this patch, `creates` must exactly match
- * a file a LATER-ordered patch creates (an earlier-only creator means the
- * dependency is already satisfied and the declaration is stale), and
- * `owner`, when set, must name one of those creating patches. Returns
- * undefined when valid.
- */
-function findStagedRegistrationFailure(entry, registration, newFileIndex) {
-    if (!isRegistrationLinePresent(entry, registration))
-        return { kind: 'line-absent' };
-    const creators = (newFileIndex.get(basename(registration.creates)) ?? []).filter((owner) => owner.fullPath === registration.creates && isLaterOwner(owner, entry));
-    if (creators.length === 0)
-        return { kind: 'creates-unresolved' };
-    if (registration.owner !== undefined &&
-        !creators.some((owner) => owner.filename === registration.owner)) {
-        return { kind: 'owner-mismatch', creators };
-    }
-    return undefined;
-}
-/** Message tail for each {@link StagedRegistrationFailure} shape. */
-function describeRegistrationFailure(failure) {
-    switch (failure.kind) {
-        case 'line-absent':
-            return 'the patch does not add that line.';
-        case 'creates-unresolved':
-            return ('no later-ordered patch creates that file — the declaration is stale, ' +
-                'or the queue order no longer stages it.');
-        case 'owner-mismatch':
-            return `that file is created by ${failure.creators.map((o) => o.filename).join(', ')}, not the declared owner.`;
-    }
-}
-/**
- * True when the declared registration/packaging line appears (trimmed)
- * among the lines the patch introduces in the declaring file — either as a
- * newly-created file's content or as added lines to an existing file
- * (where jar.mn / customElements.js / actor-registration edits land).
- */
-function isRegistrationLinePresent(entry, registration) {
-    const declared = registration.line.trim();
-    if (declared.length === 0)
-        return false;
-    const introduced = [
-        entry.newFiles.get(registration.file),
-        entry.modifiedFileAdditions.get(registration.file),
-    ];
-    return introduced.some((content) => content !== undefined && content.split('\n').some((line) => line.trim() === declared));
-}
 /**
  * Cross-patch lint orchestrator. Runs every cross-patch rule against the
  * provided context and returns combined issues.
@@ -614,6 +570,7 @@ export function lintPatchQueue(ctx) {
         ...lintPatchQueueDuplicateCreations(ctx),
         ...lintPatchQueueForwardImports(ctx),
         ...lintPatchQueueModuleRegistrations(ctx),
+        ...lintPatchQueueForwardRegistrations(ctx),
         ...lintPatchQueueBinaryBodies(ctx),
     ];
 }

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

@@ -73,11 +73,8 @@ function buildAddedLinesScanSource(rawCss, addedNumbers) {
         .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, addedLineNumbersByFile, config, issues) {
+function checkRawColorValues(input) {
+    const { file, rawCss, addedLinesByFile, addedLineNumbersByFile, config, issues } = input;
     // 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
@@ -207,7 +204,14 @@ 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, addedLineNumbersByFile, config, issues);
+        checkRawColorValues({
+            file,
+            rawCss,
+            addedLinesByFile,
+            addedLineNumbersByFile,
+            config,
+            issues,
+        });
         checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues);
     }
     return issues;

package/dist/src/core/patch-lint-file-size.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The `file-too-large` thresholds and their rendered message.
+ *
+ * Its own module for two reasons: the config validator needs the DEFAULTS
+ * to validate an override triple against the merged result, and importing
+ * `patch-lint.ts` from `config-validate.ts` for a constant would draw an
+ * import edge (and a cycle) between the rule bodies and config parsing.
+ *
+ * On the vocabulary: the bands were `notice` / `warning` / `error` with the
+ * middle one described as a "soft limit". That description is false under
+ * the posture FireForge itself recommends for a release gate,
+ * `--max-warnings 0`, where a warning is a hard failure — so a file at 751
+ * lines failed a gate with a message calling 750 soft. The message below
+ * says what the band IS (a warning) and what a zero-warning gate does with
+ * it, and the thresholds are now tunable, so a project whose file-size
+ * policy differs has a dial instead of an argument.
+ */
+import type { PatchLintFileSizeThresholds } from '../types/config.js';
+/** A fully resolved threshold triple. */
+export interface ResolvedFileSizeTier {
+    notice: number;
+    warning: number;
+    error: number;
+}
+/** Built-in defaults, per file class. */
+export declare const DEFAULT_FILE_SIZE_THRESHOLDS: {
+    general: ResolvedFileSizeTier;
+    test: ResolvedFileSizeTier;
+};
+/**
+ * Merges a configured override over the defaults for one file class.
+ *
+ * @param overrides - The `patchLint.fileSizeThresholds` block, if any
+ * @param isTest - Whether the file counts as a test file
+ * @returns The effective triple for this file
+ */
+export declare function resolveFileSizeThresholds(overrides: PatchLintFileSizeThresholds | undefined, isTest: boolean): ResolvedFileSizeTier;
+/**
+ * Renders the `file-too-large` message for a given band.
+ *
+ * The `warning` and `notice` bands name the gate consequence explicitly:
+ * the number is advisory to patch-lint and blocking to a `--max-warnings 0`
+ * gate, and an operator deciding whether to decompose a file needs to know
+ * which of those they are looking at.
+ */
+export declare function formatFileTooLargeMessage(args: {
+    label: string;
+    lineCount: number;
+    thresholds: ResolvedFileSizeTier;
+    band: 'notice' | 'warning' | 'error';
+    verb: string;
+}): string;

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

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The `file-too-large` thresholds and their rendered message.
+ *
+ * Its own module for two reasons: the config validator needs the DEFAULTS
+ * to validate an override triple against the merged result, and importing
+ * `patch-lint.ts` from `config-validate.ts` for a constant would draw an
+ * import edge (and a cycle) between the rule bodies and config parsing.
+ *
+ * On the vocabulary: the bands were `notice` / `warning` / `error` with the
+ * middle one described as a "soft limit". That description is false under
+ * the posture FireForge itself recommends for a release gate,
+ * `--max-warnings 0`, where a warning is a hard failure — so a file at 751
+ * lines failed a gate with a message calling 750 soft. The message below
+ * says what the band IS (a warning) and what a zero-warning gate does with
+ * it, and the thresholds are now tunable, so a project whose file-size
+ * policy differs has a dial instead of an argument.
+ */
+/** Built-in defaults, per file class. */
+export const DEFAULT_FILE_SIZE_THRESHOLDS = {
+    general: { notice: 500, warning: 750, error: 900 },
+    test: { notice: 1200, warning: 1400, error: 1600 },
+};
+/**
+ * Merges a configured override over the defaults for one file class.
+ *
+ * @param overrides - The `patchLint.fileSizeThresholds` block, if any
+ * @param isTest - Whether the file counts as a test file
+ * @returns The effective triple for this file
+ */
+export function resolveFileSizeThresholds(overrides, isTest) {
+    const key = isTest ? 'test' : 'general';
+    const configured = overrides?.[key] ?? {};
+    return { ...DEFAULT_FILE_SIZE_THRESHOLDS[key], ...configured };
+}
+/**
+ * Renders the `file-too-large` message for a given band.
+ *
+ * The `warning` and `notice` bands name the gate consequence explicitly:
+ * the number is advisory to patch-lint and blocking to a `--max-warnings 0`
+ * gate, and an operator deciding whether to decompose a file needs to know
+ * which of those they are looking at.
+ */
+export function formatFileTooLargeMessage(args) {
+    const { label, lineCount, thresholds, band, verb } = args;
+    if (band === 'error') {
+        return `${label} has ${lineCount} lines (error threshold: ${thresholds.error}). Consider ${verb}.`;
+    }
+    return (`${label} has ${lineCount} lines (warning threshold: ${thresholds.warning}, ` +
+        `error threshold: ${thresholds.error}). Consider ${verb}. ` +
+        `Reported as a ${band}, which a gate running --max-warnings 0 treats as a failure; ` +
+        `tune "patchLint.fileSizeThresholds" if these limits are wrong for this project.`);
+}

package/dist/src/core/patch-lint-forward-registration.d.ts

@@ -0,0 +1,58 @@
+import type { PatchLintIssue } from '../types/commands/index.js';
+import type { PatchQueueForwardRegistrationEntry, PatchQueueView } from './patch-lint-queue-types.js';
+/**
+ * One `support-files` entry, with the line the patch actually adds it on.
+ *
+ * The entry alone is not enough for the discharge command the rule prints:
+ * `--line` is compared, whitespace-trimmed, against the lines the patch
+ * ADDS, and a synthesised `support-files = ["<entry>"]` only ever matches a
+ * manifest whose array is single-line and single-entry. Carrying the source
+ * line keeps the remedy and the validation talking about the same text.
+ */
+export interface SupportFileEntry {
+    /** The entry as written inside the manifest (e.g. `fixtures/*.sqlite`). */
+    entry: string;
+    /** The first added line, whitespace-trimmed, that spells the entry out. */
+    line: string;
+    /**
+     * How many distinct added lines spell it out. Above one, the printed
+     * command quotes the first and says so: one declaration covers the file
+     * either way, because the declared check keys on file + creates.
+     */
+    occurrences: number;
+}
+/**
+ * Extracts the `support-files` entries declared in `content`, each paired
+ * with the manifest line it is written on.
+ *
+ * Handles the TOML array on one line and spread over several, and the
+ * whitespace-separated `.ini` spelling. Anything else — a computed value, a
+ * shape this does not recognise — yields nothing, because a rule that
+ * guesses at a manifest it cannot parse refuses correct queues.
+ *
+ * Quoted tokens are matched per physical line rather than over the whole
+ * accumulated array body, so a multi-line array attributes each element to
+ * its own line. Entries are deduplicated: a manifest that lists the same
+ * file under two per-test sections needs one declaration, not two.
+ */
+export declare function extractSupportFileEntries(content: string): SupportFileEntry[];
+/**
+ * Resolves one `support-files` entry, relative to its manifest's directory,
+ * into a matcher over engine-relative paths.
+ *
+ * Only a `*` inside a single path segment is expanded — the shape the
+ * downstream report uses (`fixtures/*.sqlite`). `**`, `!` exclusions and
+ * absolute `/`-rooted entries return undefined: they either cross directory
+ * boundaries or subtract, and a matcher that guessed at them would attribute
+ * a creation to the wrong manifest.
+ */
+export declare function buildSupportFileMatcher(manifestPath: string, entry: string): ((candidate: string) => boolean) | undefined;
+/**
+ * Flags every `support-files` registration a patch introduces that names a
+ * file only a later-ordered patch creates, unless the staged dependency is
+ * declared.
+ *
+ * @param ctx - Projected queue in application order
+ * @returns One issue per undeclared forward registration
+ */
+export declare function lintPatchQueueForwardRegistrations(ctx: PatchQueueView<PatchQueueForwardRegistrationEntry>): PatchLintIssue[];

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

@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Cross-patch lint rule: a test manifest that registers a file a
+ * LATER-ordered patch creates, without declaring the staged dependency.
+ *
+ * The import kind has had this arm since forward-import shipped; the
+ * registration kind never did. `--kind registration` metadata was only ever
+ * checked for STALENESS once declared, so a patch whose `xpcshell.toml`
+ * carried `support-files = ["fixtures/*.sqlite"]` for a fixture the next
+ * patch creates passed lint in both arms — declaring the dependency and
+ * removing the declaration produced identical silence, which is what made
+ * the gap invisible rather than merely absent.
+ *
+ * Scope is deliberately narrow: test-manifest `support-files` only. A
+ * jar.mn packaging line or an actor/customElements registration names its
+ * target through indirection the linter cannot resolve without the build
+ * system, and a rule that guesses there would refuse correct queues on a
+ * Firefox-sized tree. The staged-registration declaration remains the
+ * documented escape hatch for a deliberate stage.
+ */
+import { basename, dirname, posix } from 'node:path';
+import { normalizePathSlashes } from '../utils/paths.js';
+import { escapeRegex } from '../utils/regex.js';
+import { isLaterOwner, quoteRegistrationLine } from './patch-lint-staged-registration.js';
+/**
+ * Manifest basenames whose `support-files` key registers auxiliary files
+ * for a test suite. Closed and documented on purpose — a pattern like
+ * "anything .toml" would sweep in Cargo and taskcluster manifests, whose
+ * `support-files`-shaped keys mean something else entirely.
+ */
+const TEST_MANIFEST_BASENAMES = new Set([
+    'xpcshell.toml',
+    'xpcshell.ini',
+    'mochitest.toml',
+    'mochitest.ini',
+    'browser.toml',
+    'browser.ini',
+    'chrome.toml',
+    'chrome.ini',
+    'a11y.toml',
+    'a11y.ini',
+]);
+/** True for a path whose basename is a recognised test manifest. */
+function isTestManifestPath(path) {
+    return TEST_MANIFEST_BASENAMES.has(basename(normalizePathSlashes(path)));
+}
+/** Matches the start of a `support-files` assignment. */
+const SUPPORT_FILES_PATTERN = /^\s*support-files\s*=\s*(.*)$/;
+/**
+ * Extracts the `support-files` entries declared in `content`, each paired
+ * with the manifest line it is written on.
+ *
+ * Handles the TOML array on one line and spread over several, and the
+ * whitespace-separated `.ini` spelling. Anything else — a computed value, a
+ * shape this does not recognise — yields nothing, because a rule that
+ * guesses at a manifest it cannot parse refuses correct queues.
+ *
+ * Quoted tokens are matched per physical line rather than over the whole
+ * accumulated array body, so a multi-line array attributes each element to
+ * its own line. Entries are deduplicated: a manifest that lists the same
+ * file under two per-test sections needs one declaration, not two.
+ */
+export function extractSupportFileEntries(content) {
+    const lines = content.split('\n');
+    const order = [];
+    const sourceLines = new Map();
+    const record = (entry, source) => {
+        let seen = sourceLines.get(entry);
+        if (seen === undefined) {
+            seen = [];
+            sourceLines.set(entry, seen);
+            order.push(entry);
+        }
+        const trimmed = source.trim();
+        if (!seen.includes(trimmed))
+            seen.push(trimmed);
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? '';
+        const match = SUPPORT_FILES_PATTERN.exec(raw);
+        if (!match)
+            continue;
+        const head = match[1] ?? '';
+        if (!head.trimStart().startsWith('[')) {
+            // `.ini` spelling: whitespace-separated bare paths on one line.
+            for (const token of head.split(/\s+/).filter((t) => t.length > 0))
+                record(token, raw);
+            continue;
+        }
+        // TOML array: walk the physical lines until the closing bracket,
+        // bounded so an unterminated array in a malformed manifest cannot walk
+        // the file.
+        let body = head;
+        let scanned = 0;
+        let current = raw;
+        for (;;) {
+            for (const quoted of current.matchAll(/["']([^"']+)["']/g)) {
+                if (quoted[1] !== undefined)
+                    record(quoted[1], current);
+            }
+            if (body.includes(']') || i + 1 >= lines.length || scanned >= 200)
+                break;
+            i += 1;
+            scanned += 1;
+            current = lines[i] ?? '';
+            body += `\n${current}`;
+        }
+    }
+    return order.map((entry) => {
+        const seen = sourceLines.get(entry) ?? [];
+        return { entry, line: seen[0] ?? '', occurrences: seen.length };
+    });
+}
+/**
+ * Resolves one `support-files` entry, relative to its manifest's directory,
+ * into a matcher over engine-relative paths.
+ *
+ * Only a `*` inside a single path segment is expanded — the shape the
+ * downstream report uses (`fixtures/*.sqlite`). `**`, `!` exclusions and
+ * absolute `/`-rooted entries return undefined: they either cross directory
+ * boundaries or subtract, and a matcher that guessed at them would attribute
+ * a creation to the wrong manifest.
+ */
+export function buildSupportFileMatcher(manifestPath, entry) {
+    if (entry.startsWith('!') || entry.includes('**') || entry.startsWith('/'))
+        return undefined;
+    const resolved = posix.normalize(posix.join(normalizePathSlashes(dirname(manifestPath)), normalizePathSlashes(entry)));
+    if (resolved.startsWith('..'))
+        return undefined;
+    if (!resolved.includes('*')) {
+        return (candidate) => normalizePathSlashes(candidate) === resolved;
+    }
+    const pattern = new RegExp(`^${resolved
+        .split('*')
+        .map((part) => escapeRegex(part))
+        .join('[^/]*')}$`);
+    return (candidate) => pattern.test(normalizePathSlashes(candidate));
+}
+/** True when this patch already declares the staged registration. */
+function isDeclared(entry, manifestPath, createdPath) {
+    return (entry.metadata?.stagedDependencies?.registrations ?? []).some((registration) => normalizePathSlashes(registration.file) === normalizePathSlashes(manifestPath) &&
+        normalizePathSlashes(registration.creates) === normalizePathSlashes(createdPath));
+}
+/**
+ * Flags every `support-files` registration a patch introduces that names a
+ * file only a later-ordered patch creates, unless the staged dependency is
+ * declared.
+ *
+ * @param ctx - Projected queue in application order
+ * @returns One issue per undeclared forward registration
+ */
+export function lintPatchQueueForwardRegistrations(ctx) {
+    const issues = [];
+    for (const entry of ctx.entries) {
+        // Both arms: a manifest this patch CREATES and one it MODIFIES can each
+        // introduce a registration line.
+        const manifests = [
+            ...entry.newFiles,
+            ...entry.modifiedFileAdditions,
+        ].filter(([path]) => isTestManifestPath(path));
+        for (const [manifestPath, content] of manifests) {
+            for (const { entry: raw, line: addedLine, occurrences } of extractSupportFileEntries(content)) {
+                const matches = buildSupportFileMatcher(manifestPath, raw);
+                if (matches === undefined)
+                    continue;
+                // `--line` is the line as the patch adds it, which is what the
+                // declared arm compares and what `--remove` matches on. Synthesising
+                // `support-files = ["<entry>"]` instead only ever matched a
+                // single-line single-entry array, so the pasted command left the
+                // declaring patch red with staged-dependency-unused.
+                const declaredLine = quoteRegistrationLine(addedLine);
+                const ambiguity = occurrences > 1
+                    ? ` (the entry is spelled out on ${occurrences} added lines here; ` +
+                        'the first is quoted, and one declaration covers the file either way ' +
+                        'because the declared check keys on --file and --creates.)'
+                    : '';
+                for (const later of ctx.entries) {
+                    // Same predicate the declared-registration arm validates against,
+                    // tiebreak included: two spellings of "later" would let one rule
+                    // flag a pair the other considers already satisfied.
+                    if (!isLaterOwner(later, entry))
+                        continue;
+                    for (const created of later.createdFiles) {
+                        if (!matches(created))
+                            continue;
+                        if (isDeclared(entry, manifestPath, created))
+                            continue;
+                        issues.push({
+                            file: manifestPath,
+                            check: 'forward-registration',
+                            patches: [entry.filename],
+                            fingerprint: `forward-registration|${entry.filename}|${manifestPath}|${raw}|${created}|${later.filename}`,
+                            message: `${manifestPath} in ${entry.filename} registers "${raw}" as a support file, ` +
+                                `but ${created} is created by the later patch ${later.filename}. ` +
+                                'Applying the queue up to this patch leaves the registration dangling. ' +
+                                'Reorder the patches so the file is created first, move the registration into ' +
+                                'the later patch, or declare the intentional staged dependency with: ' +
+                                `fireforge patch staged-dependency ${entry.filename} --add --kind registration ` +
+                                `--file ${manifestPath} --line "${declaredLine}" ` +
+                                `--creates ${created} --owner ${later.filename}` +
+                                ambiguity,
+                            severity: 'error',
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return issues;
+}