@hominis/fireforge 0.44.4 → 0.46.0

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

@@ -46,8 +46,8 @@ function findAttachedJsDoc(comments, declStart, source) {
  * loses the param name. String literal types may contain braces too, so
  * quoted runs are skipped verbatim.
  *
- * @returns Index just past the matching close brace, or -1 when the type
- *   expression never closes (malformed doc — caller skips the tag).
+ * @returns Index just past the matching close brace, or undefined when the
+ *   type expression never closes (malformed doc — caller skips the tag).
  */
 function skipBalancedTypeBraces(jsDoc, start) {
     let depth = 0;
@@ -73,7 +73,7 @@ function skipBalancedTypeBraces(jsDoc, start) {
                 return i + 1;
         }
     }
-    return -1;
+    return undefined;
 }
 function extractParamNames(jsDoc) {
     const names = [];
@@ -87,7 +87,7 @@ function extractParamNames(jsDoc) {
         // inline object types or Record<…> generics don't truncate the scan.
         if (jsDoc[i] === '{') {
             const afterType = skipBalancedTypeBraces(jsDoc, i);
-            if (afterType === -1)
+            if (afterType === undefined)
                 continue;
             i = afterType;
             while (i < jsDoc.length && /\s/.test(jsDoc[i] ?? ''))
@@ -124,6 +124,17 @@ function hasPrivateOrInternalTag(jsDoc) {
 function functionReturnsValue(node) {
     return walkForReturn(node.body);
 }
+/**
+ * Narrows an arbitrary child value reached by walking a node's own
+ * properties to an ESTree node. Acorn's AST holds nodes, arrays of nodes,
+ * and plain scalars in the same property positions, so the discriminating
+ * `type` string is the only structural signal available.
+ */
+function isEstreeNode(value) {
+    if (typeof value !== 'object' || value === null || !('type' in value))
+        return false;
+    return typeof value.type === 'string';
+}
 function walkForReturn(node) {
     if (node.type === 'ReturnStatement') {
         return node.argument != null;
@@ -139,20 +150,16 @@ function walkForReturn(node) {
     for (const [key, val] of entries) {
         if (key === 'type')
             continue;
-        if (val && typeof val === 'object') {
-            if (Array.isArray(val)) {
-                for (const child of val) {
-                    if (child && typeof child === 'object' && 'type' in child) {
-                        if (walkForReturn(child))
-                            return true;
-                    }
-                }
-            }
-            else if ('type' in val) {
-                if (walkForReturn(val))
+        if (Array.isArray(val)) {
+            const children = val;
+            for (const child of children) {
+                if (isEstreeNode(child) && walkForReturn(child))
                     return true;
             }
         }
+        else if (isEstreeNode(val) && walkForReturn(val)) {
+            return true;
+        }
     }
     return false;
 }
@@ -183,12 +190,7 @@ function findLocalDeclaration(body, name) {
 // Line number helpers
 // ---------------------------------------------------------------------------
 function lineAt(source, offset) {
-    let line = 1;
-    for (let i = 0; i < offset && i < source.length; i++) {
-        if (source[i] === '\n')
-            line++;
-    }
-    return line;
+    return source.slice(0, offset).split('\n').length;
 }
 /**
  * Validates @param name matching and @returns presence on a function-like
@@ -198,21 +200,19 @@ function lineAt(source, offset) {
  */
 function validateParamsAndReturns(fnNode, jsDoc, issues, ctx) {
     const docText = jsDoc.value;
-    if (!ctx.skipParams) {
-        const actualParams = fnNode.params
-            .map((p) => (p.type === 'Identifier' ? p.name : null))
-            .filter((n) => n !== null);
-        if (actualParams.length > 0) {
-            const docParams = extractParamNames(docText);
-            for (const param of actualParams) {
-                if (!docParams.includes(param)) {
-                    issues.push({
-                        line: ctx.line,
-                        check: ctx.paramCheck,
-                        message: `Exported ${ctx.label} at line ${ctx.line}: @param "${param}" is missing or misnamed in JSDoc.`,
-                        ...(ctx.severity ? { severity: ctx.severity } : {}),
-                    });
-                }
+    const actualParams = fnNode.params
+        .map((p) => (p.type === 'Identifier' ? p.name : null))
+        .filter((n) => n !== null);
+    if (actualParams.length > 0) {
+        const docParams = extractParamNames(docText);
+        for (const param of actualParams) {
+            if (!docParams.includes(param)) {
+                issues.push({
+                    line: ctx.line,
+                    check: ctx.paramCheck,
+                    message: `Exported ${ctx.label} at line ${ctx.line}: @param "${param}" is missing or misnamed in JSDoc.`,
+                    ...(ctx.severity ? { severity: ctx.severity } : {}),
+                });
             }
         }
     }

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

@@ -1,12 +1,6 @@
 import type { PatchLintIssue } from '../types/commands/index.js';
-interface ModuleRegistrationQueueEntry {
-    filename: string;
-    newFiles: ReadonlyMap<string, string>;
-    modifiedFileAdditions: ReadonlyMap<string, string>;
-}
-interface ModuleRegistrationQueueContext {
-    entries: readonly ModuleRegistrationQueueEntry[];
-}
+import type { PatchQueueRegistrationEntry, PatchQueueView } from './patch-lint-queue-types.js';
+type ModuleRegistrationQueueContext = PatchQueueView<PatchQueueRegistrationEntry>;
 /**
  * Maps Firefox's common system-module resource URLs to their source
  * suffix. Exported alongside {@link extractResourceModuleSpecifiers} so

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

@@ -0,0 +1,36 @@
+/**
+ * Optional Prettier pass over patch-owned `.sys.mjs` modules.
+ *
+ * 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/`,
+ * 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,
+ * 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.
+ */
+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
+ *   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
+ * @returns One issue per unformatted file, or a single run-level issue when
+ *   prettier could not be run at all
+ */
+export declare function invokePatchLintPrettier(engineDir: string, projectRoot: string, files: readonly string[], gate: PatchLintSeverityGate): Promise<PatchLintIssue[]>;

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

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Optional Prettier pass over patch-owned `.sys.mjs` modules.
+ *
+ * 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/`,
+ * 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,
+ * 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.
+ */
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { exec } from '../utils/process.js';
+/** How long prettier gets before the pass gives up (ms). */
+const PRETTIER_TIMEOUT_MS = 120_000;
+/** Prettier's per-file `--check` failure line. */
+const PRETTIER_WARN_LINE = /^\[warn]\s+(.+)$/;
+/** Summary lines prettier prints alongside the per-file ones. */
+const PRETTIER_SUMMARY_LINE = /^\[warn]\s+(?:Code style issues|Forgot to run)/;
+/**
+ * Finds prettier, preferring a binary installed in the tree being checked.
+ *
+ * Order matters: the engine's own `node_modules` is the install whose
+ * version matches the engine's config, the project's is the next best
+ * guess, and `npx` is the last resort (it can download, so it is never
+ * preferred over something already present).
+ */
+async function resolvePrettier(engineDir, projectRoot) {
+    for (const root of [engineDir, projectRoot]) {
+        const candidate = join(root, 'node_modules', '.bin', 'prettier');
+        if (await pathExists(candidate)) {
+            return { command: candidate, prefixArgs: [] };
+        }
+    }
+    return { command: 'npx', prefixArgs: ['--no-install', 'prettier'] };
+}
+/**
+ * Runs `prettier --check` over `files` from inside the engine directory.
+ *
+ * @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
+ * @returns One issue per unformatted file, or a single run-level issue when
+ *   prettier could not be run at all
+ */
+export async function invokePatchLintPrettier(engineDir, projectRoot, files, gate) {
+    if (gate === 'off' || files.length === 0)
+        return [];
+    const severity = gate === 'error' ? 'error' : 'warning';
+    const invocation = await resolvePrettier(engineDir, projectRoot);
+    let result;
+    try {
+        result = await exec(invocation.command, [...invocation.prefixArgs, '--check', ...files], {
+            cwd: engineDir,
+            timeout: PRETTIER_TIMEOUT_MS,
+        });
+    }
+    catch (error) {
+        return [
+            {
+                file: '(prettier)',
+                check: 'prettier-format',
+                message: `patchLint.prettier is enabled but prettier could not be run (${toError(error).message}). ` +
+                    'Install prettier in engine/ or the project root, or set "patchLint.prettier": "off".',
+                severity,
+            },
+        ];
+    }
+    // Exit 0: everything formatted. Exit 1: at least one file differs. Any
+    // other code is prettier failing (bad config, unparseable file), which is
+    // a different finding and must not be reported as formatting drift.
+    if (result.exitCode === 0)
+        return [];
+    const output = `${result.stderr}\n${result.stdout}`;
+    if (result.exitCode !== 1) {
+        return [
+            {
+                file: '(prettier)',
+                check: 'prettier-format',
+                message: `prettier exited ${result.exitCode} without completing the check: ` +
+                    output.trim().split('\n').slice(-5).join(' ').slice(0, 400),
+                severity,
+            },
+        ];
+    }
+    const unformatted = new Set();
+    for (const line of output.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (PRETTIER_SUMMARY_LINE.test(trimmed))
+            continue;
+        const match = PRETTIER_WARN_LINE.exec(trimmed);
+        const file = match?.[1]?.trim();
+        if (file !== undefined && file.length > 0)
+            unformatted.add(file);
+    }
+    if (unformatted.size === 0) {
+        verbose('patchLint.prettier: prettier exited 1 but named no file; reporting nothing.');
+        return [];
+    }
+    return [...unformatted].sort().map((file) => ({
+        file,
+        check: 'prettier-format',
+        message: `Not formatted per the project's Prettier configuration. Checked from inside engine/, ` +
+            `so engine/.prettierrc* and engine/.prettierignore apply — the same command run from the ` +
+            `repo root can report a false pass when the root .prettierignore excludes engine/. ` +
+            `Fix with "prettier --write ${file}" run from engine/.`,
+        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`; no registrar, no 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

@@ -0,0 +1,106 @@
+/**
+ * Recognizes the one shape where the undefined-identifier hint sends the
+ * 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
+ * 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
+ * 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.
+ *
+ * Detection is deliberately 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.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+/**
+ * String literals passed anywhere inside a `loadSubScript(...)` call.
+ *
+ * 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.
+ */
+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
+ * 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.
+ */
+export declare function collectTopLevelDeclarations(source: string): Set<string>;
+/** An unmanaged companion a managed head loads, plus what it declares. */
+export interface UnmanagedCompanion {
+    /** Repo-relative path of the companion. */
+    file: string;
+    /** Repo-relative path of the managed head that loads it. */
+    loadedBy: string;
+    /** Top-level names the companion declares. */
+    declarations: Set<string>;
+}
+/**
+ * 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,
+ * and the generic hint applies.
+ *
+ * @param heads - Repo-relative managed head files, with their sources
+ * @param ownedFiles - Every patch-owned repo-relative path
+ * @param readFile - Reads a repo-relative file, or returns undefined
+ */
+export declare function resolveUnmanagedCompanions(heads: ReadonlyArray<{
+    file: string;
+    source: string;
+}>, ownedFiles: ReadonlySet<string>, readFile: (repoRelative: string) => Promise<string | undefined>): Promise<UnmanagedCompanion[]>;
+/**
+ * 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.
+ */
+export declare function formatUnmanagedCompanionHint(companion: UnmanagedCompanion): string;
+/**
+ * Picks the companion that explains EVERY undefined identifier in
+ * `messages`, or undefined when none does.
+ *
+ * @param messages - Diagnostic messages reported for one file
+ * @param companions - Candidates from {@link resolveUnmanagedCompanions}
+ */
+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
+ * 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
+ * hint is actively harmful there.
+ *
+ * Best-effort: an unreadable head simply contributes no companions.
+ */
+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
+ * other issue in the list is returned untouched.
+ */
+export declare function retargetUnmanagedCompanionHints(issues: readonly PatchLintIssue[], companions: readonly UnmanagedCompanion[]): PatchLintIssue[];