@aeonsparx/pi-unreal 1.0.0 → 1.1.0

package/extensions/unreal/lib/tools.ts

@@ -13,25 +13,37 @@
 
 import { parseUproject, type EngineVersion } from "./descriptors.ts";
 import { cacheDir } from "./cache.ts";
-import { buildPluginIndex, resolveProjectPlugins } from "./plugin-resolver.ts";
+import { buildPluginIndex, resolveProjectPlugins, type PluginReferenceResult, type PluginSummary } from "./plugin-resolver.ts";
 import { findProjectFile, resolveEngineForProject, type ResolverDeps } from "./engine-resolver.ts";
 import { ensureQueryJson, pickTarget, queryCacheState, humanAge, type CachePaths, type TargetChoice } from "./query.ts";
 import {
 	assembleRoots,
+	buildHeaderIndex,
 	buildIndex,
 	contextFor,
 	findFileBySuffix,
 	indexKeyFor,
 	listFiles,
+	headerKeyFor,
+	listHeaderIndexes,
 	listIndexes,
 	listModules,
 	listSymbols,
+	loadHeaderIndex,
+	lookupHeaderPaths,
 	lookupSymbol,
 	moduleFromBuildCs,
+	nameTokens,
+	pickHeaderIndex,
 	pickIndex,
 	readDefines,
+	rootKindsNote,
+	suggestFileNames,
+	suggestHeaderPaths,
 	symbolsInFile,
 	type ContextUnit,
+	type HeaderIndex,
+	type HeaderRow,
 	type IndexState,
 	type LookupResult,
 	type IndexScope,
@@ -53,12 +65,22 @@ export interface Workspace {
 	engineVersion?: EngineVersion;
 	/** Directories of plugins the `.uproject` enables, used as index roots. */
 	pluginDirs: string[];
+	/**
+	 * Declared module names per plugin root dir (from each `.uplugin`). A module directory takes the
+	 * name of its `*.Build.cs` file, which is how `Engine/Plugins/Animation/PoseSearch/Source/Runtime`
+	 * is module `PoseSearch` and not the directory leaf `Runtime`.
+	 */
+	pluginModuleNames: Record<string, string[]>;
+	/** Every `.uproject` reference with its resolved descriptor — the source of 'is this plugin available'. */
+	pluginRefs: PluginReferenceResult[];
+	/** Every plugin descriptor the scan found, including plugins the `.uproject` does not reference. */
+	plugins: PluginSummary[];
 	notes: string[];
 }
 
 export async function resolveWorkspace(cwd: string, fs: FsAdapter = realFs, deps: ResolverDeps = {}): Promise<Workspace> {
 	const notes: string[] = [];
-	const workspace: Workspace = { cwd: normalizePath(cwd), pluginDirs: [], notes };
+	const workspace: Workspace = { cwd: normalizePath(cwd), pluginDirs: [], pluginModuleNames: {}, pluginRefs: [], plugins: [], notes };
 
 	const projectPath = findProjectFile(workspace.cwd, fs, 4);
 	if (!projectPath) {
@@ -88,7 +110,13 @@ export async function resolveWorkspace(cwd: string, fs: FsAdapter = realFs, deps
 			fs,
 		});
 		const refs = resolveProjectPlugins(descriptor, index, workspace.engineVersion);
+		workspace.pluginRefs = refs;
+		workspace.plugins = index.entries;
 		workspace.pluginDirs = refs.filter((ref) => ref.plugin).map((ref) => normalizePath(ref.plugin!.dir));
+		for (const entry of index.entries) {
+			const names = entry.modules.map((module) => module.moduleName).filter(Boolean);
+			if (names.length) workspace.pluginModuleNames[normalizePath(entry.dir)] = names;
+		}
 		const missing = refs.filter((ref) => ref.status === "missing").map((ref) => ref.name);
 		if (missing.length) notes.push(`plugin references with no descriptor: ${missing.join(", ")}`);
 		notes.push(`${workspace.pluginDirs.length} enabled plugin reference(s) resolved for index roots`);
@@ -134,37 +162,49 @@ export async function ensureIndex(request: IndexRequest): Promise<IndexHandle> {
 	const fs = request.fs ?? realFs;
 	const workspace = request.workspace;
 	const engineScope = request.scope === "engine";
+	const areas = engineScope ? (request.engineAreas?.length ? request.engineAreas : DEFAULT_ENGINE_AREAS) : undefined;
 	const roots = assembleRoots({
 		projectRoot: engineScope ? undefined : workspace.projectDir,
-		pluginDirs: engineScope ? [] : workspace.pluginDirs,
+		// Engine-scope indexes carry the project's enabled plugin roots too. `Engine/Source/<area>` alone
+		// answers questions about the engine's own types and nothing else: Mover, PoseSearch,
+		// PhysicsControl, BlendStack, SmartObjects and StateTree are all plugin-shipped, and the plugin
+		// roots are already resolved, so adding them costs no extra scan of things we already know about.
+		pluginDirs: workspace.pluginDirs,
+		pluginModuleNames: workspace.pluginModuleNames,
 		engineRoot: engineScope ? workspace.engineRoot : undefined,
 		includeEngine: engineScope,
-		engineAreas: engineScope ? request.engineAreas : undefined,
+		engineAreas: areas,
 		fs,
 	});
 	const scope: IndexScope = engineScope ? "Engine" : "Project";
+	const rootDirs = roots.roots.map((root) => root.dir);
+	const coverage = { projectRoot: workspace.projectDir, engineRoot: workspace.engineRoot };
 	const notes = [...roots.notes];
 	if (!roots.roots.length) {
 		return { key: "none", built: false, warnings: [`no C++ module roots for scope '${request.scope}'`], notes, roots: [] };
 	}
+	notes.push(`covers ${rootKindsNote(rootDirs, coverage)}`);
 
-	const key = indexKeyFor({ mode: request.mode, roots: roots.roots.map((root) => root.dir), scope, target: request.target, platform: request.platform, configuration: request.configuration });
+	const key = indexKeyFor({ mode: request.mode, roots: rootDirs, scope, target: request.target, platform: request.platform, configuration: request.configuration });
 	if (!request.refresh) {
-		const existing = pickIndex({ key, mode: request.mode, scope, projectRoot: engineScope ? undefined : workspace.projectDir, engineRoot: engineScope ? workspace.engineRoot : undefined, roots: roots.roots.map((root) => root.dir) }).index;
+		const existing = pickIndex({ key, mode: request.mode, scope, projectRoot: engineScope ? undefined : workspace.projectDir, engineRoot: engineScope ? workspace.engineRoot : undefined, roots: rootDirs }).index;
 		if (existing) {
-			notes.push(`using cached index ${existing.key} (${existing.meta.counts.symbols} symbols, ${humanAge(Date.now() - Date.parse(existing.meta.generatedAt))} old)`);
+			notes.push(`using cached index ${existing.key} (${existing.meta.counts.symbols} symbols, ${existing.meta.counts.files} files, ${humanAge(Date.now() - Date.parse(existing.meta.generatedAt))} old)`);
+			const stale = indexCoverageNote(existing);
+			if (stale) notes.push(stale);
 			return { key, index: existing, built: false, warnings: [], notes, roots: roots.roots };
 		}
 	}
 
 	if (engineScope && !request.allowEngineBuild) {
-		const areas = (request.engineAreas?.length ? request.engineAreas : DEFAULT_ENGINE_AREAS).join(", ");
-		notes.push(`no engine index for ${areas}. Building one scans every .h/.cpp in those areas (tens of thousands of files): minutes the first time, cached afterwards.`);
-		notes.push("call unreal_index with scope \"engine\" (engineAreas narrows the scan, e.g. [\"Runtime\"]), then re-run this lookup");
+		const joined = (areas ?? DEFAULT_ENGINE_AREAS).join(", ");
+		notes.push(`no engine index for ${joined}. Building one scans every .h/.cpp in those areas plus ${workspace.pluginDirs.length} enabled plugin root(s) (tens of thousands of files): minutes the first time, cached afterwards.`);
+		notes.push(`call unreal_index with scope "engine" (engineAreas narrows the scan, e.g. ["Runtime"]; add ["Plugins"] for every engine plugin's sources, ["Plugins/Animation/PhysicsControl"] for one)`);
+		notes.push('unreal_index action "headers" answers "does this header exist in this engine version" in seconds without a content scan');
 		return { key, built: false, warnings: [], notes, roots: roots.roots };
 	}
 
-	const scopeNote = request.scope === "engine" ? "indexing Engine/Source (first engine index takes minutes, then it is cached)" : "indexing project and plugin sources";
+	const scopeNote = request.scope === "engine" ? `indexing Engine/Source (${(areas ?? DEFAULT_ENGINE_AREAS).join(", ")}) and ${workspace.pluginDirs.length} enabled plugin tree(s); the first engine index takes minutes, then it is cached` : "indexing project and plugin sources";
 	notes.push(scopeNote);
 	request.onProgress?.(scopeNote);
 	const started = Date.now();
@@ -178,6 +218,7 @@ export async function ensureIndex(request: IndexRequest): Promise<IndexHandle> {
 		target: request.target,
 		platform: request.platform,
 		configuration: request.configuration,
+		areas,
 		scope,
 		queryFiles: request.queryFiles,
 	});
@@ -189,6 +230,213 @@ export async function ensureIndex(request: IndexRequest): Promise<IndexHandle> {
 	return { key, index: loaded, built: true, durationMs: Date.now() - started, warnings, notes, roots: roots.roots };
 }
 
+/** Coverage of an already-built index, read from its own meta — the line a warm cache must print. */
+export function indexCoverageNote(state: IndexState): string {
+	const kinds = Object.entries(state.meta.rootKinds ?? {})
+		.map(([kind, count]) => `${count} ${kind} root(s)`)
+		.join(", ");
+	return `index ${state.key} covers ${kinds || `${state.meta.roots.length} root(s)`}${state.meta.areas?.length ? ` (engineAreas ${state.meta.areas.join(", ")})` : ""}`;
+}
+
+/** What an index actually scanned, in root-kind vocabulary — the only honest form of a 0-row answer. */
+export interface Coverage {
+	key: string;
+	scope: Scope;
+	kinds: string;
+	areas: string[];
+	roots: number;
+}
+
+function coverageOf(handle: IndexHandle, workspace: Workspace, scope: Scope, areas?: string[]): Coverage {
+	return {
+		key: handle.key,
+		scope,
+		kinds: rootKindsNote(handle.roots.map((root) => root.dir), { projectRoot: workspace.projectDir, engineRoot: workspace.engineRoot }),
+		areas: areas ?? [],
+		roots: handle.roots.length,
+	};
+}
+
+/**
+ * Engine plugins present on disk that the `.uproject` does not reference. They are compiled by the
+ * target graph (their modules show up in `TargetModuleReferences`), and they are loaded when
+ * `EnabledByDefault` is true — but they are not index roots, so a symbol lookup cannot see them.
+ * This is the coverage hole behind every "the engine has no such type" answer.
+ */
+export function unreferencedEnginePlugins(workspace: Workspace): { enginePlugins: number; referenced: number; names: string[] } {
+	const referenced = new Set(workspace.pluginRefs.map((ref) => ref.name.toLowerCase()));
+	const seen = new Map<string, true>();
+	for (const plugin of workspace.plugins) {
+		if (plugin.source === "Engine" && !referenced.has(plugin.name.toLowerCase())) seen.set(plugin.name, true);
+	}
+	return { enginePlugins: workspace.plugins.filter((plugin) => plugin.source === "Engine").length, referenced: referenced.size, names: [...seen.keys()].sort() };
+}
+
+function coverageLines(coverage: Coverage[]): string[] {
+	return coverage.map((entry) => `scanned ${entry.scope} index ${entry.key}: ${entry.kinds}${entry.areas.length ? `; engineAreas ${entry.areas.join(", ")}` : ""}${entry.roots === 0 ? " (nothing scanned)" : ""}`);
+}
+
+/** Header index for a resolved engine, if one is already built. Never built here: lookups report, they do not scan. */
+export function headerIndexForEngine(engineRoot?: string): HeaderIndex | undefined {
+	if (!engineRoot) return undefined;
+	const wanted = normalizePath(engineRoot).toLowerCase();
+	return listHeaderIndexes().find((header) => header.healthy && normalizePath(header.meta.engineRoot ?? "").toLowerCase() === wanted);
+}
+
+/** The `engineAreas` dial that scans exactly this plugin: its path under Engine/Plugins. */
+function pluginAreaLabel(workspace: Workspace, plugin: PluginSummary): string {
+	const pluginsRoot = normalizePath(joinPath(workspace.engineRoot ?? "", "Engine/Plugins"));
+	const dir = normalizePath(plugin.dir);
+	if (dir.toLowerCase().startsWith(`${pluginsRoot.toLowerCase()}/`)) return `Plugins/${dir.slice(pluginsRoot.length + 1)}`;
+	return `Plugins/<Category>/${plugin.name}`;
+}
+
+/** Header index for this project's own sources and plugins, if one is already built. */
+export function headerIndexForProject(workspace: Workspace): HeaderIndex | undefined {
+	const roots = projectHeaderRoots(workspace);
+	if (!roots.length) return undefined;
+	return pickHeaderIndex(roots);
+}
+
+function isUnder(path: string, dir?: string): boolean {
+	if (!dir) return false;
+	const p = normalizePath(path).toLowerCase();
+	const d = normalizePath(dir).toLowerCase();
+	return p === d || p.startsWith(`${d}/`);
+}
+
+/** Plugin descriptor that owns a file path, by root prefix (project plugins beat engine ones by path shape anyway). */
+export function pluginForPath(workspace: Workspace, file: string): PluginSummary | undefined {
+	for (const plugin of workspace.plugins) {
+		if (isUnder(file, plugin.dir)) return plugin;
+	}
+	return undefined;
+}
+
+/** Roots a path-only header index needs: engine source areas + every engine plugin's sources. */
+export function engineHeaderRoots(workspace: Workspace, areas?: string[]): ScanRoot[] {
+	if (!workspace.engineRoot) return [];
+	const engineAreas = areas?.length ? areas : ["Runtime", "Plugins"];
+	return assembleRoots({ engineRoot: workspace.engineRoot, includeEngine: true, engineAreas, pluginModuleNames: workspace.pluginModuleNames, fs: realFs }).roots;
+}
+
+/** Roots a path-only header index needs for the project side: its `Source` tree and its plugins' sources. */
+export function projectHeaderRoots(workspace: Workspace, fs: FsAdapter = realFs): string[] {
+	const roots = assembleRoots({ projectRoot: workspace.projectDir, pluginDirs: workspace.pluginDirs, pluginModuleNames: workspace.pluginModuleNames, fs }).roots;
+	return roots.map((root) => root.dir);
+}
+
+export interface HeaderAnswer {
+	name: string;
+	exists: boolean;
+	found: { file: string; module: string; kind: string; match: string; plugin?: string; pluginSource?: PluginSummary["source"]; enabledByDefault?: boolean; referencedInUproject?: boolean; inTargetGraphHint?: string }[];
+	candidates: { file: string; module: string }[];
+	indexKey?: string;
+	rootsScanned: string;
+	notes: string[];
+	warnings: string[];
+}
+
+/**
+ * "Does this header exist in THIS engine version?" — a path question, answered from the header index.
+ *
+ * A definitions index cannot answer it: absence of a symbol row is a statement about the roots that
+ * were scanned, not about the engine. This answers with file paths only, and labels them as file
+ * names, never as types.
+ */
+export function headerLookup(input: { name: string; workspace: Workspace; header?: HeaderIndex; limit?: number }): HeaderAnswer {
+	const name = input.name.trim();
+	const notes: string[] = [];
+	const warnings: string[] = [];
+	const workspace = input.workspace;
+	const header = input.header;
+	if (!header) {
+		const engine = workspace.engineRoot ? "scope engine (Engine/Source areas + every Engine/Plugins source)" : "the project's own sources";
+		return {
+			name,
+			exists: false,
+			found: [],
+			candidates: [],
+			rootsScanned: "none",
+			notes: [...notes, `no header index for ${engine}; build one with unreal_index action "headers" (walks file paths only: seconds, no content scan, cached under the pi cache)`],
+			warnings,
+		};
+	}
+
+	const referenced = new Set(workspace.pluginRefs.map((ref) => ref.name.toLowerCase()));
+	const decorate = (row: HeaderRow) => {
+		const plugin = pluginForPath(workspace, row.file);
+		return {
+			file: row.file,
+			module: row.module,
+			kind: row.kind,
+			match: row.match,
+			plugin: plugin?.name,
+			pluginSource: plugin?.source,
+			enabledByDefault: plugin?.enabledByDefault,
+			referencedInUproject: plugin ? referenced.has(plugin.name.toLowerCase()) : undefined,
+		};
+	};
+
+	const exact = lookupHeaderPaths(header, name, { limit: input.limit ?? 12 });
+	const candidates = exact.length ? [] : suggestHeaderPaths(header, name, { limit: 8 });
+	const rootsScanned = rootKindsNote(header.meta.roots, { projectRoot: header.meta.projectRoot, engineRoot: header.meta.engineRoot });
+	notes.push(`header index ${header.key} (${header.meta.files} header paths, ${rootsScanned})`);
+	if (!exact.length) {
+		notes.push(`'${name}' is not a file path in this engine index`);
+		if (candidates.length) notes.push(`  closest real file names (files, not types):\n${candidates.map((row) => `    ${row.file}  [${row.module}]`).join("\n")}`);
+		warnings.push(`'${name}' was not found; the answer is about file paths, not about C++ types`);
+	}
+	return { name, exists: exact.length > 0, found: exact.map(decorate), candidates: candidates.map((row) => ({ file: row.file, module: row.module })), indexKey: header.key, rootsScanned, notes, warnings };
+}
+
+/** Notes a 0-row answer must carry: what was scanned, what was not, and the exact next call. */
+export function zeroResultNotes(input: { query: string; scope: Scope; workspace: Workspace; coverage: Coverage[]; engineAreas?: string[]; indexes: IndexState[]; header?: HeaderIndex }): string[] {
+	const notes: string[] = [`no definitions matched '${input.query}' in scope '${input.scope}'`];
+	notes.push(...coverageLines(input.coverage));
+
+	const wantsEngine = input.scope === "engine" || input.scope === "all";
+	if (input.workspace.engineRoot) {
+		const gap = unreferencedEnginePlugins(input.workspace);
+		if (wantsEngine) {
+			notes.push(`engine plugins on disk: ${gap.enginePlugins}, referenced by this .uproject: ${gap.referenced}; the engine index scans referenced plugins only`);
+			notes.push(`a plugin the project does not reference is not in any index root: pass engineAreas ["Plugins"] (every Engine/Plugins source, ~2.8x the Runtime scan) or ["Plugins/<Category>/<Plugin>"] for one plugin`);
+			const near = rankNamesByQuery(gap.names, input.query);
+			if (near.length) notes.push(`unreferenced engine plugins whose name matches the query: ${near.slice(0, 6).join(", ")}${gap.names.length > 6 ? ` (of ${gap.names.length} unreferenced engine plugins with sources here)` : ""}`);
+		}
+		notes.push(input.header ? `header index ${input.header.key} covers ${rootKindsNote(input.header.meta.roots, { engineRoot: input.header.meta.engineRoot })}` : `asking whether a header exists is a path question, not a symbol question: unreal_index action "headers" (path walk only, seconds) answers it from ${input.workspace.engineRoot}/Engine/Plugins and Engine/Source`);
+	}
+	if (!wantsEngine) {
+		notes.push("a project index contains the project and its enabled plugins only; engine sources are not scanned: pass scope \"engine\" (first build takes minutes) or scope \"all\"");
+	}
+
+	const suggestions = new Map<string, { file: string; module: string }>();
+	for (const index of input.indexes) {
+		for (const row of suggestFileNames(index, input.query, { limit: 4 })) {
+			if (!suggestions.has(row.file)) suggestions.set(row.file, { file: row.file, module: row.module });
+		}
+	}
+	if (suggestions.size) {
+		notes.push(`closest indexed FILE names (file names, not types — they are not proof a type exists):\n${[...suggestions.values()].slice(0, 6).map((row) => `    ${row.file}  [${row.module}]`).join("\n")}`);
+	}
+
+	notes.push(`next: unreal_symbol query '${input.query.replace(/\.(h|hpp|hxx|inl)$/i, "")}' scope "all" prefix true, or unreal_index action "headers" name "${input.query}"`);
+	return notes;
+}
+
+/** Names ranked by how many of the query's name tokens they contain — the gap list must answer *this* question. */
+function rankNamesByQuery(names: string[], query: string): string[] {
+	const tokens = nameTokens(baseName(query).replace(/\.(h|hpp|hxx|inl|cpp|cc|c)$/i, ""));
+	if (!tokens.length) return names;
+	const scored = names.map((name) => {
+		const mine = new Set(nameTokens(name));
+		let hits = 0;
+		for (const token of tokens) if (mine.has(token)) hits++;
+		return { name, hits };
+	});
+	return scored.filter((entry) => entry.hits > 0).sort((a, b) => b.hits - a.hits || a.name.localeCompare(b.name)).map((entry) => entry.name);
+}
+
 export interface SymbolLookupInput {
 	cwd: string;
 	query: string;
@@ -198,7 +446,7 @@ export interface SymbolLookupInput {
 	substring?: boolean;
 	module?: string;
 	includeEngine?: boolean;
-	/** Engine areas for the engine index (`"Runtime"`, `"Runtime/Core"`, …). Default `Runtime`, `Editor`, `Developer`. */
+	/** Engine areas for the engine index: `"Runtime"`, `"Runtime/Core"`, `"Editor"`, or the plugin dials `"Plugins"` / `"Plugins/Animation/PhysicsControl"`. Default `DEFAULT_ENGINE_AREAS` (`["Runtime"]`). */
 	engineAreas?: string[];
 	/** Opt in to a minutes-long first engine build. Default false: the tool says how, it never stalls. */
 	allowEngineBuild?: boolean;
@@ -215,16 +463,21 @@ export async function symbolLookup(input: SymbolLookupInput) {
 	const workspace = await resolveWorkspace(input.cwd, fs, input.deps);
 	const scope: Scope = input.scope ?? (input.includeEngine ? "all" : "project");
 	const limit = input.limit ?? 25;
-	const indexes: { key: string; scope: Scope; defs: number; generatedAt: number }[] = [];
+	const indexes: { key: string; scope: Scope; defs: number; files: number; generatedAt: number }[] = [];
 	const results: LookupResult[] = [];
+	const coverage: Coverage[] = [];
+	const searched: IndexState[] = [];
 
-	const project = await ensureIndex({ workspace, mode: "definitions", scope: "project", onProgress: input.onProgress, fs });
-	if (project.index) {
-		indexes.push({ key: project.key, scope: "project", defs: project.index.meta.counts.symbols, generatedAt: Date.parse(project.index.meta.generatedAt) });
+	const project = scope === "engine" ? undefined : await ensureIndex({ workspace, mode: "definitions", scope: "project", onProgress: input.onProgress, fs });
+	if (project?.index) {
+		indexes.push({ key: project.key, scope: "project", defs: project.index.meta.counts.symbols, files: project.index.meta.counts.files, generatedAt: Date.parse(project.index.meta.generatedAt) });
+		searched.push(project.index);
 		results.push(...lookupSymbol(project.index, input.query, { limit, prefix: input.prefix, substring: input.substring, module: input.module }));
 	}
-	notes.push(...project.notes);
-	warnings.push(...project.warnings);
+	notes.push(...(project?.notes ?? []));
+	warnings.push(...(project?.warnings ?? []));
+	if (project) coverage.push(coverageOf(project, workspace, "project"));
+	if (scope === "engine") notes.push("scope 'engine' searches the engine index only: Engine/Source areas plus the plugin roots this .uproject enables");
 
 	const wantsEngine = scope === "engine" || scope === "all";
 	if (wantsEngine) {
@@ -232,22 +485,43 @@ export async function symbolLookup(input: SymbolLookupInput) {
 		else {
 			const engine = await ensureIndex({ workspace, mode: "definitions", scope: "engine", engineAreas: input.engineAreas, allowEngineBuild: input.allowEngineBuild, onProgress: input.onProgress, fs });
 			if (engine.index) {
-				indexes.push({ key: engine.key, scope: "engine", defs: engine.index.meta.counts.symbols, generatedAt: Date.parse(engine.index.meta.generatedAt) });
+				indexes.push({ key: engine.key, scope: "engine", defs: engine.index.meta.counts.symbols, files: engine.index.meta.counts.files, generatedAt: Date.parse(engine.index.meta.generatedAt) });
+				searched.push(engine.index);
 				results.push(...lookupSymbol(engine.index, input.query, { limit, prefix: input.prefix, substring: input.substring, module: input.module }));
 			}
 			notes.push(...engine.notes);
 			warnings.push(...engine.warnings);
+			coverage.push(coverageOf(engine, workspace, "engine", input.engineAreas));
 		}
 	} else {
 		const engineIndexes = listIndexes().filter((state) => !!state.meta.engineRoot && !state.meta.projectRoot);
-		if (engineIndexes.length) notes.push(`engine index cached (${engineIndexes[0]?.key}); pass scope 'all' to search it`);
-		else notes.push("engine index not built — pass scope 'engine' or 'all' for engine symbols (first build takes minutes)");
+		if (engineIndexes.length) {
+			const best = engineIndexes[0];
+			notes.push(`engine index cached (${best?.key}; ${best ? rootKindsNote(best.meta.roots, { engineRoot: best.meta.engineRoot }) : "roots unknown"}${best?.meta.areas?.length ? `; areas ${best.meta.areas.join(", ")}` : ""}) — pass scope 'all' to search it`);
+		} else {
+			notes.push("engine index not built — pass scope 'engine' or 'all' for engine symbols (first build takes minutes; engineAreas [\"Plugins\"] adds every engine plugin's sources)");
+		}
 	}
 
+	// A plugin root appears in both the project index and the engine index, so `all` sees the same
+	// declaration twice. Same symbol/file/line is one fact: keep the first, drop the echo.
+	const unique = new Map<string, LookupResult>();
+	for (const row of results) {
+		const id = `${row.symbol}\u0000${row.file}\u0000${row.line}`;
+		const kept = unique.get(id);
+		if (!kept || row.rank < kept.rank) unique.set(id, row);
+	}
+	results.length = 0;
+	results.push(...unique.values());
+
 	// Rank first, kind second: sorting by kind/name is what made a plugin forward declaration beat
 	// the engine's real `UCLASS` row and then get cut by the limit.
 	results.sort((a, b) => a.rank - b.rank || Number(b.marker.includes("forward")) - Number(a.marker.includes("forward")) || a.kind.localeCompare(b.kind) || a.symbol.localeCompare(b.symbol));
-	return { query: input.query, scope, total: results.length, results: results.slice(0, limit), indexes, notes, warnings, workspace: { projectPath: workspace.projectPath, engineRoot: workspace.engineRoot } };
+	const total = results.length;
+	if (!total) {
+		notes.push(...zeroResultNotes({ query: input.query, scope, workspace, coverage, engineAreas: input.engineAreas, indexes: searched, header: wantsEngine ? headerIndexForEngine(workspace.engineRoot) : headerIndexForProject(workspace) }));
+	}
+	return { query: input.query, scope, total, results: results.slice(0, limit), indexes, coverage, notes, warnings, workspace: { projectPath: workspace.projectPath, engineRoot: workspace.engineRoot } };
 }
 
 export interface SymbolListInput {
@@ -269,21 +543,39 @@ export async function symbolList(input: SymbolListInput) {
 	const workspace = await resolveWorkspace(input.cwd, fs, input.deps);
 	const scope: Scope = input.scope ?? "project";
 	const notes: string[] = [];
+	const project = scope === "engine" ? undefined : await ensureIndex({ workspace, mode: "definitions", scope: "project", engineAreas: input.engineAreas, fs });
 	const handles: IndexHandle[] = [];
-	const project = await ensureIndex({ workspace, mode: "definitions", scope: "project", engineAreas: input.engineAreas, fs });
-	handles.push(project);
+	if (project) handles.push(project);
 	if (scope !== "project" && workspace.engineRoot) handles.push(await ensureIndex({ workspace, mode: "definitions", scope: "engine", engineAreas: input.engineAreas, allowEngineBuild: input.allowEngineBuild, fs }));
 
 	const symbols: ReturnType<typeof listSymbols> = [];
+	const seen = new Set<string>();
 	for (const handle of handles) {
 		if (!handle.index) continue;
-		symbols.push(...listSymbols(handle.index, input.prefix, { limit: input.limit ?? 50, kind: input.kind, module: input.module }));
+		for (const row of listSymbols(handle.index, input.prefix, { limit: input.limit ?? 50, kind: input.kind, module: input.module })) {
+			const id = `${row.symbol}\u0000${row.file}\u0000${row.line}`;
+			if (seen.has(id)) continue;
+			seen.add(id);
+			symbols.push(row);
+		}
 		notes.push(...handle.notes);
 	}
 	symbols.sort((a, b) => a.symbol.localeCompare(b.symbol));
 	return { prefix: input.prefix, scope, total: symbols.length, symbols: symbols.slice(0, input.limit ?? 50), notes, indexes: handles.map((handle) => handle.key) };
 }
 
+/** Scope by path shape. Engine plugins are engine sources; project plugins are project sources. */
+export function scopeForPath(file: string, workspace: Workspace): Exclude<Scope, "all"> {
+	const p = normalizePath(file).toLowerCase();
+	if (workspace.engineRoot) {
+		const er = normalizePath(workspace.engineRoot).toLowerCase();
+		if (p.startsWith(`${er}/engine/plugins/`) || p.startsWith(`${er}/engine/source/`)) return "engine";
+	}
+	// An engine-shaped path with no resolved engine root: answer it as engine, say why it failed.
+	if (/\/engine\/plugins\/[^/]+\/source\//.test(p) || /\/engine\/source\//.test(p)) return "engine";
+	return "project";
+}
+
 export interface FileContextInput {
 	cwd: string;
 	file: string;
@@ -332,7 +624,7 @@ export async function fileContext(input: FileContextInput) {
 		}
 	}
 
-	const scope: Scope = file.includes("/Engine/Source/") ? "engine" : "project";
+	const scope: Exclude<Scope, "all"> = scopeForPath(file, workspace);
 	const handle = await ensureIndex({ workspace, mode, scope, target: choice?.target, platform: choice?.platform, configuration: choice?.configuration, queryFiles, refresh: input.refresh, allowEngineBuild: input.allowEngineBuild, engineAreas: input.engineAreas, onProgress: input.onProgress, fs });
 	notes.push(...handle.notes);
 	warnings.push(...handle.warnings);
@@ -360,7 +652,25 @@ export async function fileContext(input: FileContextInput) {
 				return { file, mode: other, module: moduleFromBuildCs(file), context: fromOther, symbols: symbolsInFile(fallback, file, input.limit ?? 40), defines: input.includeDefines ? fromOther.defines : undefined, notes, warnings };
 			}
 		}
-		return { file, mode, notes, warnings, error: `${file} is not in index ${handle.key} (it may be outside the scanned module roots, in ThirdParty, or a generated header in Intermediate/)` };
+		// The path question is answerable even when the symbol question is not: a header can exist in a
+		// plugin this project never indexed, and 'not in index' must not read as 'does not exist'.
+		const header = scope === "engine" ? headerIndexForEngine(workspace.engineRoot) : headerIndexForProject(workspace);
+		if (header) {
+			const rows = lookupHeaderPaths(header, baseName(file), { limit: 6 });
+			const hit = rows.find((row) => row.file.toLowerCase() === file.toLowerCase());
+			if (hit) {
+				const plugin = pluginForPath(workspace, hit.file);
+				const referenced = plugin ? workspace.pluginRefs.some((ref) => ref.name.toLowerCase() === plugin.name.toLowerCase()) : false;
+				notes.push(`file exists in header index ${header.key} (${hit.kind}, module ${hit.module}) but is not in any symbol-index root`);
+				if (plugin) {
+					notes.push(`owning plugin ${plugin.name} [${plugin.source}] · EnabledByDefault ${plugin.enabledByDefault} · .uproject reference ${referenced ? "yes" : "no"}`);
+					notes.push(`compile C++ from it: unreal_index action build scope engine engineAreas ["${pluginAreaLabel(workspace, plugin)}"] (one plugin's sources), then re-run this call`);
+				}
+				return { file, mode, module: hit.module, indexKey: header.key, headerOnly: true, headerKind: hit.kind, pluginName: plugin?.name, pluginSource: plugin?.source, enabledByDefault: plugin?.enabledByDefault, referencedInUproject: referenced, notes, warnings };
+			}
+			notes.push(`header index ${header.key} (${header.meta.files} header paths) has no file named '${baseName(file)}'`);
+		}
+		return { file, mode, notes, warnings, error: `${file} is not in index ${handle.key} (${indexCoverageNote(handle.index)}). It may be outside the scanned module roots, in ThirdParty, or a generated header in Intermediate/. unreal_index action "headers" answers whether the path exists in this engine version.` };
 	}
 
 	const symbols = symbolsInFile(handle.index, file, input.limit ?? 40);
@@ -380,6 +690,42 @@ export async function fileContext(input: FileContextInput) {
 	};
 }
 
+export interface ModuleAvailability {
+	module: string;
+	target: string;
+	inTargetGraph: boolean;
+	directory?: string;
+	type?: string;
+	plugin?: string;
+	pluginSource?: PluginSummary["source"];
+	enabledByDefault?: boolean;
+	referencedInUproject: boolean;
+	notes: string[];
+}
+
+/**
+ * Is this module usable here? Two independent facts the `.uproject` alone cannot answer:
+ * `TargetModuleReferences` says whether the target's graph compiles the module at all, and the plugin
+ * descriptor says who owns it and whether it loads without a reference (`EnabledByDefault`).
+ */
+export function moduleAvailability(input: { workspace: Workspace; moduleRefs: Map<string, UbtModuleRefs>; moduleName: string; target: string }): ModuleAvailability {
+	const { workspace, moduleRefs, moduleName, target } = input;
+	const refs = moduleRefs.get(moduleName);
+	const plugin = (refs?.moduleDirectory ? workspace.plugins.find((entry) => isUnder(refs.moduleDirectory, entry.dir)) : undefined) ?? workspace.plugins.find((entry) => entry.modules.some((module) => module.moduleName === moduleName));
+	const declared = plugin?.modules.find((module) => module.moduleName === moduleName);
+	const referenced = plugin ? workspace.pluginRefs.some((ref) => ref.name.toLowerCase() === plugin.name.toLowerCase()) : false;
+	const type = refs?.type || declared?.type;
+	const notes: string[] = [`  in ${target} module graph: ${refs ? `yes (${refs.moduleDirectory})` : "no — TargetModuleReferences has no entry for it"}`];
+	if (plugin) {
+		notes.push(`  owning plugin ${plugin.name} [${plugin.source}] · declared module Type ${type ?? "unset"}`);
+		notes.push(`  .uproject reference: ${plugin.source === "Engine" ? (referenced ? "referenced" : "NOT referenced") : "not an engine-plugin reference"}`);
+		if (!referenced) notes.push(plugin.enabledByDefault ? "  EnabledByDefault true: it loads with no .uproject reference" : "  EnabledByDefault false: runtime use needs a .uproject reference with Enabled true");
+	} else {
+		notes.push("  no .uplugin declares this module (engine source module, project module, or a name the graph does not contain)");
+	}
+	return { module: moduleName, target, inTargetGraph: Boolean(refs), directory: refs?.moduleDirectory, type, plugin: plugin?.name, pluginSource: plugin?.source, enabledByDefault: plugin?.enabledByDefault, referencedInUproject: referenced, notes };
+}
+
 export interface BuildContextInput {
 	cwd: string;
 	target?: string;
@@ -425,6 +771,9 @@ export async function buildContext(input: BuildContextInput) {
 	if (!refs) notes.push(`no Query entry for module '${wanted ?? ""}'; pass 'module' — ${moduleRefs.size} modules in this target's graph`);
 	else if (!settings) notes.push(`module '${wanted}' has module references but no compile settings entry in TargetDetails`);
 
+	const availability = wanted ? moduleAvailability({ workspace, moduleRefs, moduleName: wanted, target: `${choice.target} ${choice.platform} ${choice.configuration}` }) : undefined;
+	if (availability) notes.push(...availability.notes);
+
 	const headers = refs ? [...refs.public, ...refs.private, ...refs.publicInclude, ...refs.privateInclude] : [];
 	if (refs && !settings) notes.push("compile settings (includePaths, standard, forced includes) live in TargetDetails; this target's TargetDetails entry for the module was empty");
 	const handle = await ensureIndex({ workspace, mode: "definitions", scope: "project", engineAreas: input.engineAreas, fs });
@@ -436,6 +785,7 @@ export async function buildContext(input: BuildContextInput) {
 		isTestTarget: details.isTestTarget,
 		launch: details.launch,
 		module: refs ? { name: wanted, directory: refs.moduleDirectory, dependencies: refs.public.length + refs.private.length, publicHeaders: refs.public.length, privateHeaders: refs.private.length, publicInclude: refs.publicInclude, privateInclude: refs.privateInclude, dynamicallyLoaded: refs.dynamicallyLoaded, circular: refs.circular, standard: settings?.standard, windowsSdkVersion: settings?.windowsSdkVersion, compilerPath: settings?.compilerPath, includePaths: settings?.includePaths.length ?? 0, forcedIncludes: settings?.forcedIncludes ?? [], definesFile: settings?.definesFile } : undefined,
+		availability,
 		headerCount: headers.length,
 		defines: input.includeDefines ? settings?.defines ?? [] : undefined,
 		modulesInTarget: [...moduleRefs.keys()].sort().slice(0, input.limit ?? 40),
@@ -447,7 +797,7 @@ export async function buildContext(input: BuildContextInput) {
 	};
 }
 
-/** What is cached right now: symbol indexes and Query JSON, with ages and costs. */
+/** What is cached right now: symbol indexes, header indexes and Query JSON, with ages, coverage and costs. */
 export function indexStatus(cwd: string, fs: FsAdapter = realFs) {
 	const root = cacheDir(fs);
 	const indexes = listIndexes().map((state) => ({
@@ -462,12 +812,31 @@ export function indexStatus(cwd: string, fs: FsAdapter = realFs) {
 		target: state.meta.target,
 		scope: state.scope,
 		roots: state.meta.roots.length,
+		rootKinds: state.meta.rootKinds,
+		coverage: rootKindsNote(state.meta.roots, { projectRoot: state.meta.projectRoot, engineRoot: state.meta.engineRoot }),
+		areas: state.meta.areas,
 		sizeMb: Math.round(state.meta.sizeBytes / 1024 / 1024),
 		issues: state.issues,
 	}));
+	const headers = listHeaderIndexes().map((header) => ({
+		key: header.key,
+		generatedAt: header.meta.generatedAt,
+		ageMs: header.ageMs,
+		files: header.meta.files,
+		roots: header.meta.roots.length,
+		rootKinds: header.meta.rootKinds,
+		coverage: rootKindsNote(header.meta.roots, { projectRoot: header.meta.projectRoot, engineRoot: header.meta.engineRoot }),
+		areas: header.meta.areas,
+		sizeMb: Math.round(header.meta.sizeBytes / 1024 / 1024),
+		issues: header.issues,
+	}));
 	const choice = pickTarget({ cwd, fs });
 	const query = queryCacheState(root, choice, fs);
-	return { cacheDir: root, indexes, query: { target: choice, usable: query.usable, targetDetails: query.targetDetails, moduleReferences: query.moduleReferences, notes: query.notes } };
+	const notes = [
+		"engine scope covers Engine/Source areas + the project's enabled plugin roots; engine plugins the .uproject does not reference need engineAreas [\"Plugins\"] (~2.8x the Runtime scan) or [\"Plugins/<Category>/<Plugin>\"] (one plugin)",
+		"an index key encodes its root set, so a key that is not listed here is not what the last lookup searched — check the rootKinds line before trusting a 0",
+	];
+	return { cacheDir: root, indexes, headers, notes, query: { target: choice, usable: query.usable, targetDetails: query.targetDetails, moduleReferences: query.moduleReferences, notes: query.notes } };
 }
 
 export { hostPlatform };
@@ -537,12 +906,103 @@ export async function indexBuild(input: IndexBuildInput) {
 	};
 }
 
+/* ─────────────────────────────────────────────── header (path-only) index */
+
+export interface HeaderReportInput {
+	cwd: string;
+	/** Header name or path to answer, e.g. `"PhysicsControlComponent.h"` or `"Mover/Public/MoverTypes.h"`. */
+	name?: string;
+	/** Which side to index. Default `all` (engine plugin sources + engine sources + project sources). */
+	scope?: Exclude<Scope, "all"> | "all";
+	/** Build when absent. Default false: a lookup reports the cost, it never scans on its own. */
+	build?: boolean;
+	/** Engine areas to walk. Default `["Runtime", "Plugins"]` — the whole plugin tree is the point of this index. */
+	engineAreas?: string[];
+	refresh?: boolean;
+	limit?: number;
+	fs?: FsAdapter;
+	deps?: ResolverDeps;
+	onProgress?: (message: string) => void;
+}
+
+/**
+ * The 'does this header exist in THIS engine version' answer.
+ *
+ * A definitions index cannot give it: absence of a symbol row is a statement about the roots that were
+ * scanned. This is a path walk (no content read), cached under the pi cache, and it names the plugin
+ * that owns each hit plus the two availability facts a `.uproject` reader needs — `EnabledByDefault`
+ * and whether the project references the plugin at all.
+ */
+export async function headerReport(input: HeaderReportInput) {
+	const fs = input.fs ?? realFs;
+	const workspace = await resolveWorkspace(input.cwd, fs, input.deps);
+	const scope = input.scope ?? "all";
+	const notes: string[] = [...workspace.notes];
+	const warnings: string[] = [];
+
+	const roots: ScanRoot[] = [];
+	if (scope === "all" || scope === "engine") roots.push(...engineHeaderRoots(workspace, input.engineAreas));
+	if (scope === "all" || scope === "project") roots.push(...assembleRoots({ projectRoot: workspace.projectDir, pluginDirs: workspace.pluginDirs, pluginModuleNames: workspace.pluginModuleNames, fs }).roots);
+	const dirs = roots.map((root) => root.dir);
+	if (!dirs.length) {
+		notes.push("no C++ roots to walk: no project `Source` tree and no resolved engine");
+		return { built: false, exists: false, name: input.name, roots: 0, files: 0, durationMs: 0, rootKinds: "none", found: [], candidates: [], notes, warnings };
+	}
+
+	const kinds = rootKindsNote(dirs, { projectRoot: workspace.projectDir, engineRoot: workspace.engineRoot });
+	let header = pickHeaderIndex(dirs);
+	if (header && !input.refresh) {
+		notes.push(`using cached header index ${header.key} (${header.meta.files} header paths, ${header.ageMs ? humanAge(header.ageMs) : "fresh"} old)`);
+	} else if (!header && !input.build) {
+		notes.push(`no header index for ${kinds}. Build it with unreal_index action "headers" — a path walk only (no content read): seconds, cached afterwards, ~52,000 plugin headers on a UE 5.8 install.`);
+		notes.push(`  engineAreas default here is ["Runtime", "Plugins"]: every Engine/Plugins source tree, which is where Mover, PoseSearch, PhysicsControl, BlendStack, SmartObjects and StateTree live`);
+		return { built: false, exists: false, name: input.name, roots: dirs.length, files: 0, durationMs: 0, rootKinds: kinds, found: [], candidates: [], notes, warnings };
+	} else {
+		const key = headerKeyFor({ roots: dirs, label: scope === "project" ? workspace.projectName : workspace.engineRoot ? baseName(workspace.engineRoot) : "index" });
+		const areaNote = `walking header paths for ${kinds}`;
+		notes.push(areaNote);
+		input.onProgress?.(areaNote);
+		const built = await buildHeaderIndex({ key, roots, engineRoot: workspace.engineRoot, projectRoot: workspace.projectDir, areas: input.engineAreas ?? (scope === "project" ? undefined : ["Runtime", "Plugins"]) });
+		const loaded = loadHeaderIndex(built.key);
+		if (!loaded) warnings.push(`header index ${built.key} was written but could not be reloaded`);
+		header = loaded;
+		notes.push(`built ${built.key}: ${built.files} header paths in ${(built.durationMs / 1000).toFixed(1)}s`);
+	}
+
+	if (!input.name || !header) {
+		return { built: true, name: input.name, key: header?.key, files: header?.meta.files ?? 0, roots: dirs.length, durationMs: 0, rootKinds: kinds, exists: header ? undefined : false, found: [], candidates: [], notes, warnings };
+	}
+
+	const answer = headerLookup({ name: input.name, workspace, header, limit: input.limit });
+	notes.push(...answer.notes);
+	warnings.push(...answer.warnings);
+	return {
+		built: true,
+		key: header.key,
+		files: header.meta.files,
+		roots: dirs.length,
+		rootKinds: kinds,
+		name: input.name,
+		exists: answer.exists,
+		found: answer.found,
+		candidates: answer.candidates,
+		notes,
+		warnings,
+	};
+}
+
 /* ────────────────────────────────────────────────────────────── compile database */
 
-/** Default clangd scope: the project, its enabled plugins, and (with 'engine') Engine/Source. */
+/** Default clangd scope: the project, its enabled plugins, and (with 'engine') all of Engine/Source AND Engine/Plugins sources. */
 export function compileDbScope(input: { projectDir?: string; pluginDirs?: string[]; engineRoot?: string; scope: "project" | "project+engine" }): string[] {
 	const include = [input.projectDir, ...(input.pluginDirs ?? [])].filter((dir): dir is string => Boolean(dir)).map(normalizePath);
-	if (input.scope === "project+engine" && input.engineRoot) include.push(normalizePath(joinPath(input.engineRoot, "Engine/Source")));
+	// Engine plugins ship most of the types a gameplay project overrides (Mover, PoseSearch, PhysicsControl,
+	// SmartObjects, …). Listing only Engine/Source leaves their .cpp bodies out of the database, which is
+	// the same coverage hole the engine symbol scope had.
+	if (input.scope === "project+engine" && input.engineRoot) {
+		include.push(normalizePath(joinPath(input.engineRoot, "Engine/Source")));
+		include.push(normalizePath(joinPath(input.engineRoot, "Engine/Plugins")));
+	}
 	return include;
 }