@hominis/fireforge 0.44.3 → 0.45.0

package/dist/src/core/patch-apply.js

@@ -3,19 +3,19 @@
  * Patch orchestration — coordinates patch discovery, application, and validation.
  * Pure parsing, content transformation, and lock management are in separate modules.
  */
-import { lstat, readlink, realpath } from 'node:fs/promises';
+import { lstat, readFile, readlink, realpath, rm } from 'node:fs/promises';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 import { PatchError } from '../errors/patch.js';
 import { toError } from '../utils/errors.js';
-import { pathExists, readText, writeText } from '../utils/fs.js';
+import { pathExists, readText, writeFileAtomic, writeText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { isContainedRelativePath } from '../utils/paths.js';
 import { applyPatchIdempotent, reversePatch } from './git.js';
 import { getFileContentFromHead } from './git-file-ops.js';
 import { discoverPatches } from './patch-files.js';
 import { loadPatchesManifest } from './patch-manifest.js';
-import { extractAffectedFiles, extractConflictingFiles, isNewFileInPatch } from './patch-parse.js';
-import { applyPatchTextToContent, extractNewFileContent } from './patch-transform.js';
+import { extractAffectedFiles, extractConflictingFiles, isNewFileInPatch, parseDiffSections, } from './patch-parse.js';
+import { applyPatchTextToContent, extractNewFileContentFromDiff } from './patch-transform.js';
 // Re-export from split modules so existing import sites continue working
 export { PatchError } from '../errors/patch.js';
 export { countPatches, discoverPatches, getAllTargetFilesFromPatch, getTargetFileFromPatch, isNewFilePatch, } from './patch-files.js';
@@ -53,28 +53,57 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
         const applyError = toError(error);
         // Check if this is a resolvable "new file" conflict
         let resolvedNewFiles = false;
-        // Save original content for files we might overwrite, so we can restore on failure
+        // Save original BYTES of files we might overwrite, so we can restore on
+        // failure. Raw buffers rather than decoded text: the same snapshot has to
+        // restore a binary target byte-for-byte, and a Buffer round-trips text
+        // losslessly where a utf-8 decode of a binary file does not.
         const savedContents = new Map();
+        // New-file sections keyed by target, so the binary discrimination below
+        // reads the ALREADY-parsed section instead of re-scanning the body per
+        // file.
+        const newFileSections = new Map(parseDiffSections(patchContent)
+            .filter((section) => section.isNewFile)
+            .map((section) => [section.targetPath, section]));
         try {
             for (const file of affectedFiles) {
-                if (isNewFileInPatch(patchContent, file)) {
-                    const targetPath = join(engineDir, file);
-                    if (await pathExists(targetPath)) {
-                        savedContents.set(file, await readText(targetPath));
-                        const content = await extractNewFileContent(patch.path, file);
-                        await writeText(targetPath, content);
-                        resolvedNewFiles = true;
+                if (!isNewFileInPatch(patchContent, file))
+                    continue;
+                const targetPath = join(engineDir, file);
+                if (!(await pathExists(targetPath)))
+                    continue;
+                savedContents.set(file, await readFile(targetPath));
+                const section = newFileSections.get(file);
+                if (section?.isBinary === true) {
+                    // A binary new file cannot be resolved by writing extracted text —
+                    // the payload is base85, whose alphabet includes '+'. It does not
+                    // need to be: `git apply` decodes a `GIT binary patch` itself. So
+                    // the resolution is to REMOVE the blocking file and let the retry
+                    // below create it from the payload, which is exactly what the
+                    // text branch achieves by overwriting.
+                    if (!section.hasBinaryDelta) {
+                        // `Binary files … differ` records THAT the bytes changed and
+                        // carries none of them, so nothing can recreate the file. Fail
+                        // honestly rather than deleting a file we cannot put back.
+                        throw new PatchError(`Cannot resolve the new-file conflict for ${file}: the patch's binary section ` +
+                            'carries no replayable payload (`Binary files … differ` rather than `GIT binary ' +
+                            'patch`), so the file cannot be recreated. Re-export the patch with a binary-aware ' +
+                            'diff.', file);
                     }
+                    await rm(targetPath, { force: true });
                 }
+                else {
+                    await writeText(targetPath, extractNewFileContentFromDiff(patchContent, file));
+                }
+                resolvedNewFiles = true;
             }
         }
         catch (extractError) {
-            // extractNewFileContent threw for a LATER target (e.g. a binary
-            // section) after earlier targets were already overwritten — restore
-            // them before reporting failure, instead of letting the exception
-            // skip the restore loop entirely and crash the whole import.
+            // Resolution threw for a LATER target after earlier targets were
+            // already overwritten or removed — restore them before reporting
+            // failure, instead of letting the exception skip the restore loop
+            // entirely and crash the whole import.
             for (const [file, originalContent] of savedContents) {
-                await writeText(join(engineDir, file), originalContent);
+                await writeFileAtomic(join(engineDir, file), originalContent);
             }
             return { patch, success: false, error: toError(extractError).message };
         }
@@ -91,9 +120,9 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
             }
             catch (retryError) {
                 verbose(`Auto-resolved new-file retry failed for ${patch.filename}: ${toError(retryError).message}`);
-                // Restore original file content before falling through to --reject
+                // Restore original file bytes before falling through to --reject
                 for (const [file, originalContent] of savedContents) {
-                    await writeText(join(engineDir, file), originalContent);
+                    await writeFileAtomic(join(engineDir, file), originalContent);
                 }
             }
         }
@@ -138,7 +167,7 @@ async function rollbackPatches(results, engineDir) {
         if (result.autoResolvedOriginals) {
             for (const [file, originalContent] of result.autoResolvedOriginals) {
                 try {
-                    await writeText(join(engineDir, file), originalContent);
+                    await writeFileAtomic(join(engineDir, file), originalContent);
                     verbose(`Restored pre-existing content of ${file} after rollback`);
                 }
                 catch (restoreError) {

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

@@ -30,6 +30,7 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { normalizePathSlashes } from '../utils/paths.js';
+import { collectUnmanagedCompanions, retargetUnmanagedCompanionHints, } from './patch-lint-unmanaged-companion.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, TEST_HARNESS_SHIM, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
 // ---------------------------------------------------------------------------
 // Public API
@@ -464,6 +465,7 @@ export async function runCheckJsTestFilesGrouped(repoDir, testFiles, patchLint,
     const mode = modeFromPatchLintConfig(patchLint);
     const seenGlobal = new Set();
     const files = [...testFiles].sort((a, b) => a.localeCompare(b));
+    const companions = await collectUnmanagedCompanions(repoDir, files, testFiles);
     for (const file of files) {
         // Under a rootScope only the scoped files get their own program, but
         // head.js helper discovery still spans the full owned set so a scoped
@@ -483,7 +485,10 @@ export async function runCheckJsTestFilesGrouped(repoDir, testFiles, patchLint,
         const result = await runCheckJsGrouped(repoDir, roots, patchLint.checkJsTestShim, projectRoot, mode, TEST_HARNESS_SHIM);
         const own = result.byFile.get(file);
         if (own && own.length > 0) {
-            merged.byFile.set(file, [...(merged.byFile.get(file) ?? []), ...own]);
+            merged.byFile.set(file, [
+                ...(merged.byFile.get(file) ?? []),
+                ...retargetUnmanagedCompanionHints(own, companions),
+            ]);
         }
         for (const globalIssue of result.global) {
             if (seenGlobal.has(globalIssue.message))

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 ${String(lineCount)} lines (error threshold: ${String(thresholds.error)}). Consider ${verb}.`;
+    }
+    return (`${label} has ${String(lineCount)} lines (warning threshold: ${String(thresholds.warning)}, ` +
+        `error threshold: ${String(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-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 ${String(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-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[];