@hominis/fireforge 0.44.4 → 0.45.0

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[];

package/dist/src/core/patch-lint-unmanaged-companion.js

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * 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 { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { UNDEFINED_IDENTIFIER_HINT } from './typecheck-shim.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 function findLoadSubScriptTargets(source) {
+    const targets = [];
+    // Scanned to the statement terminator rather than to a closing paren:
+    // the idiomatic argument is itself a call (`getRootDirectory(gTestPath) +
+    // "head_settings.js"`), so a non-greedy `\)` stops on the INNER paren and
+    // never reaches the literal.
+    for (const call of source.matchAll(/loadSubScript\s*\(/g)) {
+        const from = call.index + call[0].length;
+        const semicolon = source.indexOf(';', from);
+        const to = semicolon === -1 ? from + CALL_SCAN_LIMIT : Math.min(semicolon, from + CALL_SCAN_LIMIT);
+        for (const literal of source.slice(from, to).matchAll(/["'`]([^"'`]*\.js)["'`]/g)) {
+            const value = literal[1];
+            if (value !== undefined && value.length > 0)
+                targets.push(value);
+        }
+    }
+    return targets;
+}
+/** How far past a `loadSubScript(` the argument scan looks. */
+const CALL_SCAN_LIMIT = 400;
+/**
+ * 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 function collectTopLevelDeclarations(source) {
+    const names = new Set();
+    const patterns = [
+        /^(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/gm,
+        /^(?:const|let|var)\s+([A-Za-z_$][\w$]*)/gm,
+        /^class\s+([A-Za-z_$][\w$]*)/gm,
+    ];
+    for (const pattern of patterns) {
+        for (const match of source.matchAll(pattern)) {
+            const name = match[1];
+            if (name !== undefined)
+                names.add(name);
+        }
+    }
+    return names;
+}
+/**
+ * Extracts the identifier from a `Cannot find name 'X'` diagnostic message,
+ * or undefined when the message is not one.
+ */
+function extractUndefinedIdentifier(message) {
+    const match = /Cannot find name '([^']+)'/.exec(message);
+    return match?.[1];
+}
+/**
+ * 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 async function resolveUnmanagedCompanions(heads, ownedFiles, readFile) {
+    const companions = [];
+    const seen = new Set();
+    for (const head of heads) {
+        const dir = head.file.slice(0, head.file.lastIndexOf('/') + 1);
+        for (const target of findLoadSubScriptTargets(head.source)) {
+            // Only same-directory targets: the runtime path is computed from the
+            // test's own directory, and a bare basename is what that idiom yields.
+            const candidate = `${dir}${target.slice(target.lastIndexOf('/') + 1)}`;
+            if (candidate === head.file || ownedFiles.has(candidate) || seen.has(candidate))
+                continue;
+            seen.add(candidate);
+            const source = await readFile(candidate);
+            if (source === undefined)
+                continue;
+            companions.push({
+                file: candidate,
+                loadedBy: head.file,
+                declarations: collectTopLevelDeclarations(source),
+            });
+        }
+    }
+    return companions;
+}
+/**
+ * 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 function formatUnmanagedCompanionHint(companion) {
+    return (`(undefined identifier — every one of them is declared in ${companion.file}, which ` +
+        `${companion.loadedBy} loads via loadSubScript but which NO patch owns yet, so the ` +
+        `per-patch program cannot see it. Adopt it with ` +
+        `"fireforge re-export <patch> --scan --scan-file ${companion.file}". Do NOT add these ` +
+        `globals to the extra shim: that silences these warnings and every future genuinely ` +
+        `missing helper with them.)`);
+}
+/**
+ * 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 function explainUndefinedIdentifiers(messages, companions) {
+    const names = messages
+        .map((message) => extractUndefinedIdentifier(message))
+        .filter((name) => name !== undefined);
+    if (names.length === 0)
+        return undefined;
+    // Only the undefined-identifier diagnostics are explained here; a file
+    // carrying OTHER type errors still gets those reported untouched.
+    return companions.find((companion) => names.every((name) => companion.declarations.has(name)));
+}
+/**
+ * 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 async function collectUnmanagedCompanions(repoDir, files, ownedFiles) {
+    const heads = [];
+    for (const file of files) {
+        const base = file.split('/').pop() ?? '';
+        if (!/^head(?:_.*)?\.js$/.test(base))
+            continue;
+        try {
+            heads.push({ file, source: await readFile(join(repoDir, file), 'utf8') });
+        }
+        catch {
+            continue;
+        }
+    }
+    if (heads.length === 0)
+        return [];
+    return resolveUnmanagedCompanions(heads, ownedFiles, async (rel) => {
+        try {
+            return await readFile(join(repoDir, rel), 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
+/**
+ * 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 function retargetUnmanagedCompanionHints(issues, companions) {
+    if (companions.length === 0)
+        return [...issues];
+    const undefinedIssues = issues.filter((issue) => issue.message.includes(UNDEFINED_IDENTIFIER_HINT));
+    if (undefinedIssues.length === 0)
+        return [...issues];
+    const companion = explainUndefinedIdentifiers(undefinedIssues.map((issue) => issue.message), companions);
+    if (!companion)
+        return [...issues];
+    const hint = formatUnmanagedCompanionHint(companion);
+    return issues.map((issue) => issue.message.includes(UNDEFINED_IDENTIFIER_HINT)
+        ? { ...issue, message: issue.message.replace(UNDEFINED_IDENTIFIER_HINT, hint) }
+        : issue);
+}