@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -4,7 +4,7 @@
  *
  * 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`
+ * "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
@@ -16,8 +16,8 @@ import { mozbuildSortCompare } from './moz-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
+ * `UnsortedError` on append when out of order. `DIRS` is absent on purpose:
+ * directory order is meaningful and not strict-ordered. Dotted namespaces
  * (`EXTRA_JS_MODULES.<subdir>`, `EXPORTS.<ns>`) inherit strict ordering
  * from their parent variable.
  */
@@ -39,7 +39,7 @@ const LIST_OPENER = new RegExp(`^\\s*((?:${STRICT_ORDERED_MOZBUILD_LISTS.join('|
  */
 /**
  * True when `line` contains a `]` outside any quoted span. A bracket inside an
- * item (`"icons[2x].png"`) is filename text, not the list's close — reading it
+ * item (`"icons[2x].png"`) is filename text, not the list's close. Reading it
  * as one truncated the item set and left every later item unchecked.
  */
 function hasUnquotedCloseBracket(line) {
@@ -90,8 +90,8 @@ function stripMozBuildComment(line) {
  * - a quoted string in a trailing comment would otherwise be scraped in as a
  *   phantom list item (`"Zeta.cpp",  # replaces "Beta.cpp"` yielding a
  *   `Beta.cpp` entry), so the sort check reports an unsorted list naming a
- *   file that is not in it — with a fingerprint that can never stabilise,
- *   because the item does not exist to be moved;
+ *   file that is not in it, with a fingerprint that can never stabilise,
+ *   because the item does not exist to be moved.
  * - a `]` anywhere in a comment (`# see foo[0]`) would close the list early
  *   and silently truncate the item set.
  *
@@ -99,9 +99,9 @@ function stripMozBuildComment(line) {
  * list would otherwise consume the rest of the file and skip every later
  * list in it.
  *
- * Nor does an unterminated list borrow the NEXT list's bracket. The forward
- * scan stops at the next list opener rather than reading through it —
- * otherwise an unclosed `EXTRA_COMPONENTS` swallows the following
+ * Nor does an unterminated list borrow the next list's bracket. The forward
+ * scan stops at the next list opener rather than reading through it.
+ * Otherwise an unclosed `EXTRA_COMPONENTS` swallows the following
  * `EXTRA_JS_MODULES`, merging its items into the first list and accepting
  * its `]` as the first list's close, reporting a sorting error against a
  * variable that never contained those items.
@@ -149,7 +149,7 @@ function collectStrictOrderedLists(content) {
         }
         if (closed) {
             occurrences.push({ varName, items });
-            // Resume after the list we just consumed; a list that never closed
+            // Resume after the list we just consumed. A list that never closed
             // leaves `i` untouched so the next line is still examined.
             i = cursor;
         }

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

@@ -16,7 +16,7 @@ import type { PatchLintIssue } from '../types/commands/index.js';
  * binaryName happens to be a substring of one. `quit-application*` is
  * handled as a prefix family in {@link isKnownFirefoxTopic}.
  *
- * The list is deliberately conservative: it only needs to cover topics
+ * The list is conservative: it only needs to cover topics
  * whose text could plausibly contain a fork's binaryName, plus the
  * high-traffic lifecycle topics seen in downstream test simulations.
  */
@@ -26,8 +26,8 @@ export declare function isKnownFirefoxTopic(topic: string): boolean;
 /**
  * Lints observer-service call sites in `strippedContent` (comments already
  * removed) for fork topic naming. Only topics that embed `binaryName` and
- * do not follow the `<binary>-<noun>-<verb>` convention are flagged;
- * allowlisted Firefox topics and constant-named topics are skipped.
+ * do not follow the `<binary>-<noun>-<verb>` convention are flagged.
+ * Allowlisted Firefox topics and constant-named topics are skipped.
  *
  * @param strippedContent - Source with comments stripped
  * @param file - File path for issue attribution

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

@@ -16,7 +16,7 @@
  * binaryName happens to be a substring of one. `quit-application*` is
  * handled as a prefix family in {@link isKnownFirefoxTopic}.
  *
- * The list is deliberately conservative: it only needs to cover topics
+ * The list is conservative: it only needs to cover topics
  * whose text could plausibly contain a fork's binaryName, plus the
  * high-traffic lifecycle topics seen in downstream test simulations.
  */
@@ -49,7 +49,7 @@ export function isKnownFirefoxTopic(topic) {
  * commas inside nested calls, object literals, or strings do not split.
  *
  * @returns The argument texts, or null when the span never closes within
- *   `maxLength` characters (malformed or truncated source — caller skips).
+ *   `maxLength` characters (malformed or truncated source, caller skips).
  */
 function extractCallArguments(content, openParen, maxLength = 2000) {
     const args = [];
@@ -103,9 +103,9 @@ function extractCallArguments(content, openParen, maxLength = 2000) {
 /**
  * Returns the literal string value when `arg` is exactly one plain string
  * literal (no concatenation, no `${}` interpolation), otherwise null.
- * Constant-named topics (identifiers, member expressions) intentionally
- * return null — hoisting a literal into a named constant is a supported
- * way to mark a topic as deliberate.
+ * Constant-named topics (identifiers, member expressions) return null on
+ * purpose: hoisting a literal into a named constant is a supported way to
+ * mark a topic as deliberate.
  */
 function asStringLiteral(arg) {
     const trimmed = arg.trim();
@@ -126,8 +126,8 @@ function asStringLiteral(arg) {
 /**
  * Lints observer-service call sites in `strippedContent` (comments already
  * removed) for fork topic naming. Only topics that embed `binaryName` and
- * do not follow the `<binary>-<noun>-<verb>` convention are flagged;
- * allowlisted Firefox topics and constant-named topics are skipped.
+ * do not follow the `<binary>-<noun>-<verb>` convention are flagged.
+ * Allowlisted Firefox topics and constant-named topics are skipped.
  *
  * @param strippedContent - Source with comments stripped
  * @param file - File path for issue attribution

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

@@ -8,9 +8,9 @@
  *
  * The two resolvers are kept separate (one per extension predicate)
  * because the downstream rules differ: `.sys.mjs` files go through
- * `runCheckJs` (TypeScript checkJs) and the export-walker JSDoc rule;
- * chrome subscripts (`.js` non-`.sys.mjs`) only get the script-walker
- * JSDoc rule. Mixing them in a single set would silently broaden
+ * `runCheckJs` (TypeScript checkJs) and the export-walker JSDoc rule,
+ * while chrome subscripts (`.js` non-`.sys.mjs`) only get the
+ * script-walker JSDoc rule. Mixing them in a single set would silently broaden
  * `runCheckJs` to chrome subscripts, which it is not designed for.
  */
 import type { PatchQueueContext } from './patch-lint-cross.js';
@@ -32,7 +32,7 @@ import type { PatchQueueContext } from './patch-lint-cross.js';
 export declare function resolvePatchOwnedSysMjs(currentNewFiles: Set<string>, patchQueueCtx?: PatchQueueContext): Set<string>;
 /**
  * Returns the set of file paths that are patch-owned chrome subscripts
- * (`.js` files that are not `.sys.mjs` modules — typically
+ * (`.js` files that are not `.sys.mjs` modules, typically
  * `browser/base/content/<binaryName>*.js` and similar). Same ownership
  * semantics as {@link resolvePatchOwnedSysMjs}.
  *
@@ -45,7 +45,7 @@ export declare function resolvePatchOwnedChromeScripts(currentNewFiles: Set<stri
  * Test-script predicate for the `checkJsTestFiles` pass:
  * 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`'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`.
@@ -53,7 +53,7 @@ export declare function resolvePatchOwnedChromeScripts(currentNewFiles: Set<stri
 export declare function isTestScriptFile(file: string): boolean;
 /**
  * Returns the set of patch-owned test `.js` files. Same
- * ownership semantics as {@link resolvePatchOwnedSysMjs}; consumed by the
+ * ownership semantics as {@link resolvePatchOwnedSysMjs}. Consumed by the
  * `patchLint.checkJsTestFiles` pass, which checks each as its own small
  * script-scope program.
  *

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

@@ -9,9 +9,9 @@
  *
  * The two resolvers are kept separate (one per extension predicate)
  * because the downstream rules differ: `.sys.mjs` files go through
- * `runCheckJs` (TypeScript checkJs) and the export-walker JSDoc rule;
- * chrome subscripts (`.js` non-`.sys.mjs`) only get the script-walker
- * JSDoc rule. Mixing them in a single set would silently broaden
+ * `runCheckJs` (TypeScript checkJs) and the export-walker JSDoc rule,
+ * while chrome subscripts (`.js` non-`.sys.mjs`) only get the
+ * script-walker JSDoc rule. Mixing them in a single set would silently broaden
  * `runCheckJs` to chrome subscripts, which it is not designed for.
  */
 import { collectNewFileCreatorsByPath } from './patch-lint-cross.js';
@@ -56,7 +56,7 @@ export function resolvePatchOwnedSysMjs(currentNewFiles, patchQueueCtx) {
 }
 /**
  * Returns the set of file paths that are patch-owned chrome subscripts
- * (`.js` files that are not `.sys.mjs` modules — typically
+ * (`.js` files that are not `.sys.mjs` modules, typically
  * `browser/base/content/<binaryName>*.js` and similar). Same ownership
  * semantics as {@link resolvePatchOwnedSysMjs}.
  *
@@ -71,7 +71,7 @@ export function resolvePatchOwnedChromeScripts(currentNewFiles, patchQueueCtx) {
  * Test-script predicate for the `checkJsTestFiles` pass:
  * 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`'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`.
@@ -86,7 +86,7 @@ export function isTestScriptFile(file) {
 }
 /**
  * Returns the set of patch-owned test `.js` files. Same
- * ownership semantics as {@link resolvePatchOwnedSysMjs}; consumed by the
+ * ownership semantics as {@link resolvePatchOwnedSysMjs}. Consumed by the
  * `patchLint.checkJsTestFiles` pass, which checks each as its own small
  * script-scope program.
  *

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

@@ -4,32 +4,32 @@
  * Until 0.45.0 no tier of the chain ran Prettier on `.sys.mjs` at all, so
  * module formatting drift was caught by nothing and survived to a human
  * reviewer. Worse, the obvious manual check was misleading in the same
- * direction: a fork's ROOT `.prettierignore` typically excludes `engine/`,
+ * direction: a fork's root `.prettierignore` typically excludes `engine/`,
  * so `prettier --check --config engine/.prettierrc.js <engine files>` run
  * from the repo root reports "all files use Prettier code style" for files
  * that fail the identical check run from inside `engine/`. A root-level
  * spot-check falsely refuted a correct reviewer finding on exactly this.
  *
- * This pass therefore runs prettier with `cwd` set to the ENGINE directory,
+ * This pass therefore runs prettier with `cwd` set to the engine directory,
  * so the engine's own `.prettierrc*` and `.prettierignore` resolve the way
  * they do for anyone working in that tree, and the FireForge result agrees
  * with the operator's own command.
  *
  * Opt-in (`patchLint.prettier`, default `'off'`): it spawns a process per
  * lint and is a new failure surface on queues that never had one. When it
- * is off, formatting is explicitly out of scope for the per-patch tier —
- * that is the contract, not an accident.
+ * is off, formatting is explicitly out of scope for the per-patch tier.
+ * That is the contract, not an accident.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
 import type { PatchLintSeverityGate } from '../types/config.js';
 /**
  * Runs `prettier --check` over `files` from inside the engine directory.
  *
- * @param engineDir - Absolute engine directory; also the `cwd`, which is
+ * @param engineDir - Absolute engine directory. Also the `cwd`, which is
  *   what makes the engine's own config and ignore file authoritative
  * @param projectRoot - FireForge project root, for the fallback binary
  * @param files - Engine-relative patch-owned `.sys.mjs` paths
- * @param gate - Severity for reported issues; `'off'` skips the pass
+ * @param gate - Severity for reported issues. `'off'` skips the pass
  * @returns One issue per unformatted file, or a single run-level issue when
  *   prettier could not be run at all
  */

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

@@ -5,21 +5,21 @@
  * Until 0.45.0 no tier of the chain ran Prettier on `.sys.mjs` at all, so
  * module formatting drift was caught by nothing and survived to a human
  * reviewer. Worse, the obvious manual check was misleading in the same
- * direction: a fork's ROOT `.prettierignore` typically excludes `engine/`,
+ * direction: a fork's root `.prettierignore` typically excludes `engine/`,
  * so `prettier --check --config engine/.prettierrc.js <engine files>` run
  * from the repo root reports "all files use Prettier code style" for files
  * that fail the identical check run from inside `engine/`. A root-level
  * spot-check falsely refuted a correct reviewer finding on exactly this.
  *
- * This pass therefore runs prettier with `cwd` set to the ENGINE directory,
+ * This pass therefore runs prettier with `cwd` set to the engine directory,
  * so the engine's own `.prettierrc*` and `.prettierignore` resolve the way
  * they do for anyone working in that tree, and the FireForge result agrees
  * with the operator's own command.
  *
  * Opt-in (`patchLint.prettier`, default `'off'`): it spawns a process per
  * lint and is a new failure surface on queues that never had one. When it
- * is off, formatting is explicitly out of scope for the per-patch tier —
- * that is the contract, not an accident.
+ * is off, formatting is explicitly out of scope for the per-patch tier.
+ * That is the contract, not an accident.
  */
 import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
@@ -52,11 +52,11 @@ async function resolvePrettier(engineDir, projectRoot) {
 /**
  * Runs `prettier --check` over `files` from inside the engine directory.
  *
- * @param engineDir - Absolute engine directory; also the `cwd`, which is
+ * @param engineDir - Absolute engine directory. Also the `cwd`, which is
  *   what makes the engine's own config and ignore file authoritative
  * @param projectRoot - FireForge project root, for the fallback binary
  * @param files - Engine-relative patch-owned `.sys.mjs` paths
- * @param gate - Severity for reported issues; `'off'` skips the pass
+ * @param gate - Severity for reported issues. `'off'` skips the pass
  * @returns One issue per unformatted file, or a single run-level issue when
  *   prettier could not be run at all
  */
@@ -94,7 +94,7 @@ export async function invokePatchLintPrettier(engineDir, projectRoot, files, gat
             {
                 file: '(prettier)',
                 check: 'prettier-format',
-                message: `prettier exited ${String(result.exitCode)} without completing the check: ` +
+                message: `prettier exited ${result.exitCode} without completing the check: ` +
                     output.trim().split('\n').slice(-5).join(' ').slice(0, 400),
                 severity,
             },

package/dist/src/core/patch-lint-queue-types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Structural views of the cross-patch lint queue context.
+ *
+ * A leaf module by design: it imports nothing, so the individual rule
+ * modules can describe the slice of `PatchQueueContext` they read without
+ * importing `patch-lint-cross.ts` (which imports them back). Previously each
+ * rule re-declared its own private `{ entries }` interface. Sharing them here
+ * keeps the dependency edge one-way and `dpdm` clean while stating the shape
+ * once.
+ */
+/**
+ * The slice of a queue entry consumed by rules that read raw patch bodies
+ * (the new-file creators map, the binary-body check).
+ */
+export interface PatchQueueBodyEntry {
+    /** Filename on disk and in the manifest. */
+    filename: string;
+    /** Raw unified-diff content of the patch body. */
+    diff: string;
+}
+/**
+ * The slice of a queue entry consumed by the module-registration rule: the
+ * per-path content maps rather than the raw diff.
+ */
+export interface PatchQueueRegistrationEntry {
+    /** Filename on disk and in the manifest. */
+    filename: string;
+    /** Newly-created file path → the content the patch would produce. */
+    newFiles: ReadonlyMap<string, string>;
+    /** Existing file path → the lines the patch adds to it. */
+    modifiedFileAdditions: ReadonlyMap<string, string>;
+}
+/**
+ * Structural queue view: the `entries` field of a `PatchQueueContext`,
+ * narrowed to whichever entry slice a rule needs.
+ */
+export interface PatchQueueView<TEntry> {
+    /** Entries in application order (lowest `order` first). */
+    entries: readonly TEntry[];
+}
+/**
+ * The slice consumed by the forward-registration rule: the same content maps
+ * the module-registration rule reads, plus the body-kind-agnostic creation
+ * set and the ordering/metadata needed to decide "later" and "declared".
+ */
+export interface PatchQueueForwardRegistrationEntry extends PatchQueueRegistrationEntry {
+    /** Order number from the manifest (or filename prefix fallback). */
+    order: number;
+    /** Every path this patch creates, whatever the body kind. */
+    createdFiles: ReadonlySet<string>;
+    /** Manifest metadata. Null when the patch file exists but has no entry. */
+    metadata: {
+        stagedDependencies?: {
+            registrations?: readonly {
+                file: string;
+                creates: string;
+            }[];
+        };
+    } | null;
+}

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

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Structural views of the cross-patch lint queue context.
+ *
+ * A leaf module by design: it imports nothing, so the individual rule
+ * modules can describe the slice of `PatchQueueContext` they read without
+ * importing `patch-lint-cross.ts` (which imports them back). Previously each
+ * rule re-declared its own private `{ entries }` interface. Sharing them here
+ * keeps the dependency edge one-way and `dpdm` clean while stating the shape
+ * once.
+ */
+export {};

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

@@ -0,0 +1,61 @@
+import type { PatchStagedRegistration } from '../types/commands/index.js';
+/** A patch that creates a given path, with its position in the queue. */
+export interface NewFileOwner {
+    filename: string;
+    order: number;
+    fullPath: string;
+}
+/** The ordering fields `isLaterOwner` compares an owner against. */
+export interface QueuePosition {
+    filename: string;
+    order: number;
+}
+/**
+ * Later-in-apply-order predicate shared by the forward-import scan, the
+ * forward-registration rule and the registration validation: strictly
+ * higher ordinal, or same ordinal with a lexicographically later filename
+ * (the apply loop's tiebreak).
+ *
+ * @param owner - The creating patch
+ * @param entry - The referencing patch
+ * @returns True when `owner` applies after `entry`
+ */
+export declare function isLaterOwner(owner: QueuePosition, entry: QueuePosition): boolean;
+/** The slice of a queue entry the registration validation reads. */
+export interface StagedRegistrationEntry extends QueuePosition {
+    newFiles: ReadonlyMap<string, string>;
+    modifiedFileAdditions: ReadonlyMap<string, string>;
+}
+/** Why a staged registration declaration failed validation. */
+export type StagedRegistrationFailure = {
+    kind: 'line-absent';
+} | {
+    kind: 'creates-unresolved';
+} | {
+    kind: 'owner-mismatch';
+    creators: readonly NewFileOwner[];
+};
+/**
+ * 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.
+ */
+export declare function findStagedRegistrationFailure(entry: StagedRegistrationEntry, registration: PatchStagedRegistration, createdFileIndex: Map<string, NewFileOwner[]>): StagedRegistrationFailure | undefined;
+/** Message tail for each {@link StagedRegistrationFailure} shape. */
+export declare function describeRegistrationFailure(failure: StagedRegistrationFailure): string;
+/**
+ * Renders `line` for the `--line "…"` argument of a paste-and-run
+ * `patch staged-dependency` command.
+ *
+ * A registration line is quoted for the shell in the messages that print
+ * the command, and a `support-files` element carries its own quotes
+ * (`"file_tiles_find.html",` is what a multi-line TOML array adds). Without
+ * escaping, the shell would eat them and the declaration would be written
+ * with a line the patch never adds, the exact mismatch that made the
+ * forward-registration remedy leave the declaring patch red.
+ */
+export declare function quoteRegistrationLine(line: string): string;

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

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Validation of `--kind registration` staged-dependency declarations.
+ *
+ * Split out of `patch-lint-cross.ts` to keep that file inside the per-file
+ * line budget, and because the forward-registration rule needs the same
+ * apply-order predicate: two spellings of "later in the queue" would let the
+ * rule that flags an undeclared registration and the rule that validates a
+ * declared one disagree about the very same pair of patches.
+ *
+ * Exports helpers consumed by `patch-lint-cross.ts` and
+ * `patch-lint-forward-registration.ts`, with no registrar or rule of its own.
+ */
+import { basename } from 'node:path';
+/**
+ * Later-in-apply-order predicate shared by the forward-import scan, the
+ * forward-registration rule and the registration validation: strictly
+ * higher ordinal, or same ordinal with a lexicographically later filename
+ * (the apply loop's tiebreak).
+ *
+ * @param owner - The creating patch
+ * @param entry - The referencing patch
+ * @returns True when `owner` applies after `entry`
+ */
+export function isLaterOwner(owner, entry) {
+    return (owner.order > entry.order || (owner.order === entry.order && owner.filename > entry.filename));
+}
+/**
+ * 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.
+ */
+export function findStagedRegistrationFailure(entry, registration, createdFileIndex) {
+    if (!isRegistrationLinePresent(entry, registration))
+        return { kind: 'line-absent' };
+    const creators = (createdFileIndex.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. */
+export 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));
+}
+/**
+ * Renders `line` for the `--line "…"` argument of a paste-and-run
+ * `patch staged-dependency` command.
+ *
+ * A registration line is quoted for the shell in the messages that print
+ * the command, and a `support-files` element carries its own quotes
+ * (`"file_tiles_find.html",` is what a multi-line TOML array adds). Without
+ * escaping, the shell would eat them and the declaration would be written
+ * with a line the patch never adds, the exact mismatch that made the
+ * forward-registration remedy leave the declaring patch red.
+ */
+export function quoteRegistrationLine(line) {
+    return line.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}

package/dist/src/core/patch-lint-unmanaged-companion.d.ts

@@ -1,26 +1,26 @@
 /**
  * Recognizes the one shape where the undefined-identifier hint sends the
- * operator at the wrong remedy — and where taking that remedy would MASK a
+ * operator at the wrong remedy, and where taking that remedy would mask a
  * real bug.
  *
  * The shape: helpers are hoisted out of duplicated test files into a new
  * `head_settings.js` that a managed `head.js` pulls in with
  * `loadSubScript`. Until that companion is exported it belongs to no patch,
- * so the per-patch checkJs program — which only ever loads patch-owned
- * roots — cannot see any of its declarations. Every use of every hoisted
+ * so the per-patch checkJs program, which only ever loads patch-owned
+ * roots, cannot see any of its declarations. Every use of every hoisted
  * helper is then reported as `Cannot find name`, and the generic hint
  * offers three remedies of which the shim is the easiest: adding the
- * globals to `extraShim` makes all of the warnings disappear AND makes a
+ * globals to `extraShim` makes all of the warnings disappear and makes a
  * genuinely missing helper undetectable forever after.
  *
- * The warnings themselves are correct — the per-patch program's honest view
- * of a file that is in no patch. Only the advice is wrong. FireForge
- * already knows ownership, so when every undefined name in a file is
- * declared at the top level of an UNMANAGED file that a managed head loads,
- * it can name that file and the adoption command instead.
+ * The warnings themselves are correct: they are the per-patch program's
+ * honest view of a file that is in no patch. Only the advice is wrong.
+ * FireForge already knows ownership, so when every undefined name in a file
+ * is declared at the top level of an unmanaged file that a managed head
+ * loads, it can name that file and the adoption command instead.
  *
- * Detection is deliberately conservative on both halves: a companion must
- * be reachable from an actual `loadSubScript` call, and EVERY undefined
+ * Detection is conservative on both halves: a companion must
+ * be reachable from an actual `loadSubScript` call, and every undefined
  * name must resolve inside it. One unresolved name means the file may
  * genuinely be missing a helper, and the generic hint stays.
  */
@@ -31,14 +31,14 @@ import type { PatchLintIssue } from '../types/commands/index.js';
  * The mochitest idiom is
  * `Services.scriptloader.loadSubScript(getRootDirectory(gTestPath) + "head_settings.js", this)`,
  * so the useful signal is the `.js` literal inside the call, not a
- * resolvable URL — the path half is computed at runtime.
+ * resolvable URL. The path half is computed at runtime.
  */
 export declare function findLoadSubScriptTargets(source: string): string[];
 /**
  * Top-level declaration names in a script-scope file.
  *
  * Regex rather than a TS program on purpose: this runs only to decide the
- * WORDING of a hint, the file is by definition outside every program the
+ * wording of a hint, the file is outside every program the
  * pass built, and a missed declaration degrades to the generic hint rather
  * than to a wrong answer. Matching is anchored at column zero so a nested
  * declaration inside a function body is not mistaken for a global.
@@ -57,8 +57,8 @@ export interface UnmanagedCompanion {
  * Resolves the unmanaged companions reachable from a set of managed head
  * files, given a reader for repo-relative file content.
  *
- * A candidate qualifies only when it is NOT in `ownedFiles` and its content
- * can be read — an unreadable or absent target is simply not a companion,
+ * A candidate qualifies only when it is not in `ownedFiles` and its content
+ * can be read. An unreadable or absent target is simply not a companion,
  * and the generic hint applies.
  *
  * @param heads - Repo-relative managed head files, with their sources
@@ -73,14 +73,14 @@ export declare function resolveUnmanagedCompanions(heads: ReadonlyArray<{
  * The replacement hint, when every undefined name resolves in one
  * unmanaged companion.
  *
- * States the ownership fact first (that is the diagnosis), then the
- * adoption command, and explicitly rules the shim OUT — the shim is what an
- * operator reaches for by default here, and it is the one remedy that
- * permanently hides a genuinely missing helper.
+ * States the ownership fact first (the diagnosis), then the adoption
+ * command, and explicitly rules the shim out. The shim is what an operator
+ * reaches for by default here, and it is the one remedy that permanently
+ * hides a genuinely missing helper.
  */
 export declare function formatUnmanagedCompanionHint(companion: UnmanagedCompanion): string;
 /**
- * Picks the companion that explains EVERY undefined identifier in
+ * Picks the companion that explains every undefined identifier in
  * `messages`, or undefined when none does.
  *
  * @param messages - Diagnostic messages reported for one file
@@ -88,11 +88,11 @@ export declare function formatUnmanagedCompanionHint(companion: UnmanagedCompani
  */
 export declare function explainUndefinedIdentifiers(messages: readonly string[], companions: readonly UnmanagedCompanion[]): UnmanagedCompanion | undefined;
 /**
- * Reads the head files in the owned test set and resolves the UNMANAGED
+ * Reads the head files in the owned test set and resolves the unmanaged
  * companions they pull in with `loadSubScript`. Hoisting shared helpers
  * into such a companion leaves it unowned until export, and every use of
  * every helper then reports `Cannot find name` from an honest per-patch
- * program — see `patch-lint-unmanaged-companion.ts` for why the generic
+ * program. See `patch-lint-unmanaged-companion.ts` for why the generic
  * hint is actively harmful there.
  *
  * Best-effort: an unreadable head simply contributes no companions.
@@ -100,7 +100,7 @@ export declare function explainUndefinedIdentifiers(messages: readonly string[],
 export declare function collectUnmanagedCompanions(repoDir: string, files: readonly string[], ownedFiles: ReadonlySet<string>): Promise<UnmanagedCompanion[]>;
 /**
  * Swaps the generic undefined-identifier hint for the ownership hint when
- * one unmanaged companion explains EVERY undefined name in the file. Any
+ * one unmanaged companion explains every undefined name in the file. Any
  * other issue in the list is returned untouched.
  */
 export declare function retargetUnmanagedCompanionHints(issues: readonly PatchLintIssue[], companions: readonly UnmanagedCompanion[]): PatchLintIssue[];