@hominis/fireforge 0.43.1 → 0.44.0

package/dist/src/core/furnace-validate-registration.js

@@ -7,6 +7,7 @@ import { pathExists, readText } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 import { escapeRegex, stripJsComments } from '../utils/regex.js';
 import { getProjectPaths, loadConfig } from './config.js';
+import { normalizeForChecksum } from './furnace-checksum-utils.js';
 import { getFurnacePaths } from './furnace-config.js';
 import { CUSTOM_ELEMENTS_JS, FTL_DIR, JAR_MN } from './furnace-constants.js';
 import { expandCssFragments, listFragmentIncludes } from './furnace-css-fragments.js';
@@ -124,8 +125,12 @@ export async function checkRegistrationConsistency(root, name, config, ftlDir) {
                 }
             }
             const destContent = await readText(destPath);
-            const srcHash = createHash('sha256').update(srcContent).digest('hex');
-            const destHash = createHash('sha256').update(destContent).digest('hex');
+            // Same normalization the checksums written by apply use. These three
+            // comparisons hashed raw bytes, so on a CRLF checkout `furnace status`
+            // and `furnace validate` reported drift for files apply had just
+            // decided were identical.
+            const srcHash = createHash('sha256').update(normalizeForChecksum(srcContent)).digest('hex');
+            const destHash = createHash('sha256').update(normalizeForChecksum(destContent)).digest('hex');
             if (srcHash !== destHash) {
                 status.driftedFiles.push(entry.name);
                 status.filesInSync = false;
@@ -150,8 +155,10 @@ export async function checkRegistrationConsistency(root, name, config, ftlDir) {
             else {
                 const srcContent = await readText(ftlSrc);
                 const destContent = await readText(ftlDest);
-                const srcHash = createHash('sha256').update(srcContent).digest('hex');
-                const destHash = createHash('sha256').update(destContent).digest('hex');
+                const srcHash = createHash('sha256').update(normalizeForChecksum(srcContent)).digest('hex');
+                const destHash = createHash('sha256')
+                    .update(normalizeForChecksum(destContent))
+                    .digest('hex');
                 if (srcHash !== destHash) {
                     status.driftedFiles.push(ftlName);
                     status.filesInSync = false;
@@ -225,11 +232,9 @@ export async function validateJarMnEntries(root, config) {
         }
     }
     // Stale registrations: lines pointing at component files that no longer
-    // exist in the workspace (left behind by a rename/delete under an older
-    // FireForge). These break `mach build` at packaging ("File ... not
-    // found"), so they are errors and `--fix` prunes them (0.34.0 field
-    // report: both validate --fix and doctor --repair-furnace reported
-    // success without pruning).
+    // exist in the workspace, left behind by a rename or delete. These break
+    // `mach build` at packaging ("File ... not found"), so they are errors and
+    // `--fix` prunes them.
     const staleEntries = await findStaleJarMnEntries(engineDir, furnacePaths.customDir, Object.keys(config.custom));
     for (const stale of staleEntries) {
         issues.push({
@@ -261,47 +266,106 @@ const AUTO_DETECT_HOST_DIR = 'browser/base/content';
  * `already`, so callers can merge them with the caller-configured set
  * without producing double entries in warning output.
  *
- * Motivating case: a fork that mounts a custom element from its own
- * top-level chrome document (e.g. `mybrowser.xhtml`) without setting
- * `tokenHostDocuments`. The stock `browser.xhtml` was the only thing
- * scanned, so the tokens CSS link in the ACTUAL host document went
- * unnoticed and the warning false-fired.
+ * This catches a fork that mounts a custom element from its own top-level
+ * chrome document (e.g. `mybrowser.xhtml`) without setting
+ * `tokenHostDocuments`: scanning only the stock `browser.xhtml` would miss
+ * the tokens CSS link in the ACTUAL host document and false-fire the
+ * warning.
  *
  * @param engineDir Absolute engine root.
  * @param tagName Custom element tag the CSS belongs to.
  * @param already Paths already in the scan set (POSIX, engine-relative).
  */
-async function autoDetectTokenHostDocuments(engineDir, tagName, already) {
-    const contentDir = join(engineDir, AUTO_DETECT_HOST_DIR);
-    if (!(await pathExists(contentDir)))
-        return [];
-    let entries;
+/**
+ * Per-run caches for work that is invariant across components.
+ *
+ * `validateAllComponents` walks every component, and re-parsing
+ * `fireforge.json` plus re-scanning every `.xhtml` under the chrome-document
+ * directory per component is one config parse and one full directory read
+ * PER COMPONENT, for work that depends only on the project and the engine.
+ *
+ * Keyed by root/engine dir and cleared by
+ * {@link resetRegistrationValidationCaches} at the start of each run, so a
+ * long-lived process (the test suite, `watch`) never serves a stale read.
+ */
+const tokensCssFileNameCache = new Map();
+const chromeDocumentCache = new Map();
+/**
+ * Whether a batch validation is in flight.
+ *
+ * The caches are consulted ONLY while this is set. Outside a batch — a direct
+ * `validateComponent` call from `furnace status`, from apply's consistency
+ * check, or from a test — every read goes to disk, so a caller that mutates
+ * the engine between calls can never be served a stale document.
+ */
+let batchInFlight = false;
+/**
+ * Runs `body` with the per-run caches enabled, then clears them.
+ *
+ * @param body - The batch to run
+ * @returns Whatever `body` resolves to
+ */
+export async function withRegistrationValidationCache(body) {
+    const outer = batchInFlight;
+    batchInFlight = true;
     try {
-        entries = await readdir(contentDir);
+        return await body();
     }
-    catch {
-        // No readable chrome-document directory means no documents reference the
-        // tag, which is the same verdict as an empty directory.
-        return [];
+    finally {
+        batchInFlight = outer;
+        if (!outer) {
+            tokensCssFileNameCache.clear();
+            chromeDocumentCache.clear();
+        }
     }
-    const alreadySet = new Set(already);
-    const detected = [];
-    for (const entry of entries) {
-        if (!entry.endsWith('.xhtml'))
-            continue;
-        const relPath = `${AUTO_DETECT_HOST_DIR}/${entry}`;
-        if (alreadySet.has(relPath))
-            continue;
-        const absPath = join(contentDir, entry);
-        let content;
+}
+/**
+ * Reads every chrome document under the auto-detect directory once per run.
+ *
+ * @param engineDir - Absolute path to the engine checkout
+ * @returns Map of engine-relative document path to its content
+ */
+async function loadChromeDocuments(engineDir) {
+    const cached = batchInFlight ? chromeDocumentCache.get(engineDir) : undefined;
+    if (cached)
+        return cached;
+    const documents = new Map();
+    const contentDir = join(engineDir, AUTO_DETECT_HOST_DIR);
+    if (await pathExists(contentDir)) {
+        let entries;
         try {
-            content = await readText(absPath);
+            entries = await readdir(contentDir);
         }
         catch {
-            // An unreadable chrome document cannot be searched for the tag; skip it and
-            // keep scanning the rest.
-            continue;
+            // No readable chrome-document directory means no documents reference
+            // the tag, which is the same verdict as an empty directory.
+            entries = [];
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith('.xhtml'))
+                continue;
+            const rel = `${AUTO_DETECT_HOST_DIR}/${entry}`;
+            try {
+                documents.set(rel, await readText(join(contentDir, entry)));
+            }
+            catch {
+                // Unreadable document: treated as not referencing the tag.
+            }
         }
+    }
+    if (batchInFlight)
+        chromeDocumentCache.set(engineDir, documents);
+    return documents;
+}
+async function autoDetectTokenHostDocuments(engineDir, tagName, already) {
+    // Reads the directory ONCE per run rather than once per component: only the
+    // tag being searched for differs between components.
+    const documents = await loadChromeDocuments(engineDir);
+    const alreadySet = new Set(already);
+    const detected = [];
+    for (const [relPath, content] of documents) {
+        if (alreadySet.has(relPath))
+            continue;
         if (content.includes(tagName)) {
             detected.push(relPath);
         }
@@ -337,9 +401,19 @@ export async function validateTokenLink(componentDir, tagName, root, tokenPrefix
         : DEFAULT_TOKEN_HOST_DOCUMENTS;
     let tokensCssFile;
     try {
-        const forgeConfig = await loadConfig(root);
-        const segments = getTokensCssPath(forgeConfig.binaryName).split('/');
-        tokensCssFile = segments[segments.length - 1] ?? '';
+        // Cached per run: the filename depends on `binaryName` alone, so parsing
+        // fireforge.json once per token-using component was pure repetition.
+        const cachedName = batchInFlight ? tokensCssFileNameCache.get(root) : undefined;
+        if (cachedName !== undefined) {
+            tokensCssFile = cachedName;
+        }
+        else {
+            const forgeConfig = await loadConfig(root);
+            const segments = getTokensCssPath(forgeConfig.binaryName).split('/');
+            tokensCssFile = segments[segments.length - 1] ?? '';
+            if (batchInFlight)
+                tokensCssFileNameCache.set(root, tokensCssFile);
+        }
     }
     catch (error) {
         const reason = toError(error).message;

package/dist/src/core/furnace-validate.d.ts

@@ -23,3 +23,19 @@ export declare function validateComponent(componentDir: string, tagName: string,
  * @returns Map of component name to its validation issues
  */
 export declare function validateAllComponents(root: string): Promise<Map<string, ValidationIssue[]>>;
+/**
+ * Flags engine-side files that a previous deploy of `tagName` left behind
+ * after their workspace source was renamed or removed.
+ *
+ * Detection keys on the furnace state file: every `appliedChecksums` entry
+ * under `custom/<tagName>/` whose workspace source no longer exists but whose
+ * engine target is still present is an orphan. The next deploy prunes it, but
+ * until then jar.mn and the deployed directory disagree with the workspace,
+ * and a re-export could capture the stale state into a patch.
+ *
+ * Custom components only: override undeploys restore the upstream baseline
+ * rather than deleting files, so "orphan" has no meaning there.
+ */
+export declare function findOrphanedEngineFiles(root: string, config: FurnaceConfig, tagName: string, state: {
+    appliedChecksums?: Record<string, string>;
+}, ftlDir: string): Promise<ValidationIssue[]>;

package/dist/src/core/furnace-validate.js

@@ -4,13 +4,15 @@ import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { getProjectPaths, loadConfig } from './config.js';
+import { extractComponentChecksums } from './furnace-checksum-utils.js';
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState } from './furnace-config.js';
 import { resolveFtlDir, xpcshellTestParentDir } from './furnace-constants.js';
 import { validateCssFragments } from './furnace-css-fragments.js';
 import { detectComposesCycles, validateComposesReferences } from './furnace-graph-utils.js';
 import { findJsconfigPathsDrift } from './furnace-jsconfig.js';
 import { validateAccessibility, validateCompatibility, validateJarMnEntries, validateRegistrationPatterns, validateStructure, validateTokenLink, } from './furnace-validate-checks.js';
-import { findOrphanedEngineFiles } from './furnace-validate-helpers.js';
+import { createIssue } from './furnace-validate-helpers.js';
+import { withRegistrationValidationCache } from './furnace-validate-registration.js';
 import { findOverrideBaseVersionDrift, } from './furnace-version-drift.js';
 function buildOverrideVersionDriftIssues(config, currentVersion, tagName) {
     return findOverrideBaseVersionDrift(config, currentVersion)
@@ -59,9 +61,8 @@ export async function validateComponent(componentDir, tagName, type, config, roo
     if (root) {
         issues.push(...(await validateTokenLink(componentDir, tagName, root, config?.tokenPrefix, config?.tokenHostDocuments)));
     }
-    // CSS fragment checks (field report D2): missing fragment files are
-    // structural errors; stale deployed expansions are drift the next deploy
-    // refreshes.
+    // CSS fragment checks: missing fragment files are structural errors;
+    // stale deployed expansions are drift the next deploy refreshes.
     if (type === 'custom') {
         const furnacePaths = getFurnacePaths(root ?? join(componentDir, '..', '..', '..'));
         const engineTargetDir = root && config?.custom[tagName]
@@ -69,11 +70,10 @@ export async function validateComponent(componentDir, tagName, type, config, roo
             : undefined;
         issues.push(...(await validateCssFragments(componentDir, tagName, furnacePaths.sharedDir, engineTargetDir)));
     }
-    // Engine-side orphan detection (field report D1): files a previous deploy
-    // placed in the engine whose workspace source has since been renamed or
-    // deleted. Surfaces as drift even when every current workspace file is
-    // in sync, which is exactly the gap that let stale jar.mn lines reach a
-    // later re-export.
+    // Engine-side orphan detection: files a previous deploy placed in the
+    // engine whose workspace source has since been renamed or deleted.
+    // Surfaces as drift even when every current workspace file is in sync,
+    // which is the gap that lets stale jar.mn lines reach a later re-export.
     if (root && config && type === 'custom') {
         const state = await loadFurnaceState(root);
         issues.push(...(await findOrphanedEngineFiles(root, config, tagName, state, resolveFtlDir(config.ftlBasePath))));
@@ -102,160 +102,165 @@ export async function validateComponent(componentDir, tagName, type, config, roo
  * @returns Map of component name to its validation issues
  */
 export async function validateAllComponents(root) {
-    const config = await loadFurnaceConfig(root);
-    const furnacePaths = getFurnacePaths(root);
-    const results = new Map();
-    // Validate composition graph integrity (dangling references and cycles)
-    try {
-        validateComposesReferences(config.stock, config.overrides, config.custom);
-    }
-    catch (err) {
-        const message = toError(err).message;
-        // Attribute the issue to the first custom component with a bad composes reference
-        for (const [name, cfg] of Object.entries(config.custom)) {
-            if (cfg.composes) {
-                const existing = results.get(name) ?? [];
-                existing.push({
-                    component: name,
-                    severity: 'error',
-                    check: 'composes-dangling-reference',
-                    message,
-                });
-                results.set(name, existing);
-                break;
+    // Wrapped so the config parse and the chrome-document scan happen once for
+    // the whole batch instead of once per component. The caches are inert
+    // outside this window, so a direct `validateComponent` caller is never
+    // served a stale read.
+    return await withRegistrationValidationCache(async () => {
+        const config = await loadFurnaceConfig(root);
+        const furnacePaths = getFurnacePaths(root);
+        const results = new Map();
+        // Validate composition graph integrity (dangling references and cycles)
+        try {
+            validateComposesReferences(config.stock, config.overrides, config.custom);
+        }
+        catch (err) {
+            const message = toError(err).message;
+            // Attribute the issue to the first custom component with a bad composes reference
+            for (const [name, cfg] of Object.entries(config.custom)) {
+                if (cfg.composes) {
+                    const existing = results.get(name) ?? [];
+                    existing.push({
+                        component: name,
+                        severity: 'error',
+                        check: 'composes-dangling-reference',
+                        message,
+                    });
+                    results.set(name, existing);
+                    break;
+                }
             }
         }
-    }
-    try {
-        detectComposesCycles(config.custom);
-    }
-    catch (err) {
-        const message = toError(err).message;
-        // Attribute the cycle issue to the first custom component in the cycle
-        for (const name of Object.keys(config.custom)) {
-            if (config.custom[name]?.composes) {
-                const existing = results.get(name) ?? [];
-                existing.push({
-                    component: name,
-                    severity: 'error',
-                    check: 'composes-cycle',
-                    message,
-                });
-                results.set(name, existing);
-                break;
+        try {
+            detectComposesCycles(config.custom);
+        }
+        catch (err) {
+            const message = toError(err).message;
+            // Attribute the cycle issue to the first custom component in the cycle
+            for (const name of Object.keys(config.custom)) {
+                if (config.custom[name]?.composes) {
+                    const existing = results.get(name) ?? [];
+                    existing.push({
+                        component: name,
+                        severity: 'error',
+                        check: 'composes-cycle',
+                        message,
+                    });
+                    results.set(name, existing);
+                    break;
+                }
             }
         }
-    }
-    // Override components
-    for (const name of Object.keys(config.overrides)) {
-        const componentDir = join(furnacePaths.overridesDir, name);
-        if (!(await pathExists(componentDir))) {
-            results.set(name, [
-                {
-                    component: name,
-                    severity: 'error',
-                    check: 'missing-component-dir',
-                    message: `Component directory not found: components/overrides/${name}`,
-                },
-            ]);
-            continue;
+        // Override components
+        for (const name of Object.keys(config.overrides)) {
+            const componentDir = join(furnacePaths.overridesDir, name);
+            if (!(await pathExists(componentDir))) {
+                results.set(name, [
+                    {
+                        component: name,
+                        severity: 'error',
+                        check: 'missing-component-dir',
+                        message: `Component directory not found: components/overrides/${name}`,
+                    },
+                ]);
+                continue;
+            }
+            const issues = await validateComponent(componentDir, name, 'override', config, root);
+            results.set(name, issues);
         }
-        const issues = await validateComponent(componentDir, name, 'override', config, root);
-        results.set(name, issues);
-    }
-    // Custom components
-    for (const name of Object.keys(config.custom)) {
-        const componentDir = join(furnacePaths.customDir, name);
-        if (!(await pathExists(componentDir))) {
-            results.set(name, [
-                {
-                    component: name,
-                    severity: 'error',
-                    check: 'missing-component-dir',
-                    message: `Component directory not found: components/custom/${name}`,
-                },
-            ]);
-            continue;
+        // Custom components
+        for (const name of Object.keys(config.custom)) {
+            const componentDir = join(furnacePaths.customDir, name);
+            if (!(await pathExists(componentDir))) {
+                results.set(name, [
+                    {
+                        component: name,
+                        severity: 'error',
+                        check: 'missing-component-dir',
+                        message: `Component directory not found: components/custom/${name}`,
+                    },
+                ]);
+                continue;
+            }
+            // Pass root so that per-component token link validation runs.
+            // Skip registration/jar.mn checks inside validateComponent — the aggregate
+            // validators below run them exactly once across all components, which both
+            // surfaces cross-component issues and avoids double-counting.
+            const issues = await validateComponent(componentDir, name, 'custom', config, root, {
+                skipAggregateChecks: true,
+            });
+            results.set(name, issues);
         }
-        // Pass root so that per-component token link validation runs.
-        // Skip registration/jar.mn checks inside validateComponent — the aggregate
-        // validators below run them exactly once across all components, which both
-        // surfaces cross-component issues and avoids double-counting.
-        const issues = await validateComponent(componentDir, name, 'custom', config, root, {
-            skipAggregateChecks: true,
-        });
-        results.set(name, issues);
-    }
-    // Registration pattern validation (customElements.js Pattern A vs B)
-    const registrationIssues = await validateRegistrationPatterns(root, config);
-    for (const issue of registrationIssues) {
-        const existing = results.get(issue.component) ?? [];
-        existing.push(issue);
-        results.set(issue.component, existing);
-    }
-    // jar.mn entry validation
-    const jarMnIssues = await validateJarMnEntries(root, config);
-    for (const issue of jarMnIssues) {
-        const existing = results.get(issue.component) ?? [];
-        existing.push(issue);
-        results.set(issue.component, existing);
-    }
-    // 2026-04-24 eval Finding 5: orphan xpcshell scaffold detection.
-    // `furnace create --with-tests --xpcshell` scaffolds a test directory
-    // at `browser/base/content/test/<binary>-xpcshell/<name>/`, and prior
-    // `furnace remove` + `furnace rename` flows did not touch that tree.
-    // A leftover scaffold whose `<name>` is not in furnace.json is almost
-    // always the aftermath of one of those incomplete flows; flag it as
-    // an `orphan-xpcshell-scaffold` error so operators know to delete or
-    // re-create the scaffold instead of discovering the mismatch only at
-    // test run time. Missing engine or missing scaffold parent directory
-    // both degrade silently — this check never introduces noise on a
-    // project that never used xpcshell scaffolding.
-    try {
-        const orphanIssues = await findOrphanXpcshellScaffolds(root, config);
-        for (const issue of orphanIssues) {
+        // Registration pattern validation (customElements.js Pattern A vs B)
+        const registrationIssues = await validateRegistrationPatterns(root, config);
+        for (const issue of registrationIssues) {
             const existing = results.get(issue.component) ?? [];
             existing.push(issue);
             results.set(issue.component, existing);
         }
-    }
-    catch {
-        // Validation degrades gracefully — the absence of an engine
-        // directory, permission denial reading the scaffold tree, or any
-        // other transient fs issue should never cascade into false
-        // "orphan" reports.
-    }
-    // jsconfig chrome-module paths drift (field report D3): when
-    // `typecheckJsconfig` is configured, deploy maintains a paths mapping per
-    // deployed module file; missing or stale entries mean typed cross-module
-    // imports are silently degrading to `any` in the consumer's typecheck.
-    if (config.typecheckJsconfig) {
+        // jar.mn entry validation
+        const jarMnIssues = await validateJarMnEntries(root, config);
+        for (const issue of jarMnIssues) {
+            const existing = results.get(issue.component) ?? [];
+            existing.push(issue);
+            results.set(issue.component, existing);
+        }
+        // Orphan xpcshell scaffold detection.
+        // `furnace create --with-tests --xpcshell` scaffolds a test directory at
+        // `browser/base/content/test/<binary>-xpcshell/<name>/`. A leftover
+        // scaffold whose `<name>` is not in furnace.json is almost always the
+        // aftermath of an incomplete `furnace remove` or `rename`; flag it as an
+        // `orphan-xpcshell-scaffold` error so operators delete or re-create the
+        // scaffold instead of discovering the mismatch at test run time. A
+        // missing engine or scaffold parent directory degrades silently, so this
+        // check never adds noise on a project that never used xpcshell
+        // scaffolding.
         try {
-            const drift = await findJsconfigPathsDrift(root, config);
-            if (drift.changed) {
-                const detail = [
-                    ...drift.added.map((key) => `missing: ${key}`),
-                    ...drift.updated.map((key) => `stale: ${key}`),
-                    ...drift.pruned.map((key) => `orphaned: ${key}`),
-                ].join('; ');
-                const issue = {
-                    component: 'furnace',
-                    severity: 'warning',
-                    check: 'jsconfig-paths-drift',
-                    message: `${config.typecheckJsconfig} chrome-module paths are out of sync with the workspace (${detail}). ` +
-                        'Run "fireforge furnace deploy" to update them.',
-                };
+            const orphanIssues = await findOrphanXpcshellScaffolds(root, config);
+            for (const issue of orphanIssues) {
                 const existing = results.get(issue.component) ?? [];
                 existing.push(issue);
                 results.set(issue.component, existing);
             }
         }
         catch {
-            // Drift detection must not break validation when the jsconfig is
-            // missing or unparsable — deploy reports those cases with guidance.
+            // Validation degrades gracefully — the absence of an engine
+            // directory, permission denial reading the scaffold tree, or any
+            // other transient fs issue should never cascade into false
+            // "orphan" reports.
         }
-    }
-    return results;
+        // jsconfig chrome-module paths drift: when `typecheckJsconfig` is
+        // configured, deploy maintains a paths mapping per deployed module file;
+        // missing or stale entries mean typed cross-module imports are silently
+        // degrading to `any` in the consumer's typecheck.
+        if (config.typecheckJsconfig) {
+            try {
+                const drift = await findJsconfigPathsDrift(root, config);
+                if (drift.changed) {
+                    const detail = [
+                        ...drift.added.map((key) => `missing: ${key}`),
+                        ...drift.updated.map((key) => `stale: ${key}`),
+                        ...drift.pruned.map((key) => `orphaned: ${key}`),
+                    ].join('; ');
+                    const issue = {
+                        component: 'furnace',
+                        severity: 'warning',
+                        check: 'jsconfig-paths-drift',
+                        message: `${config.typecheckJsconfig} chrome-module paths are out of sync with the workspace (${detail}). ` +
+                            'Run "fireforge furnace deploy" to update them.',
+                    };
+                    const existing = results.get(issue.component) ?? [];
+                    existing.push(issue);
+                    results.set(issue.component, existing);
+                }
+            }
+            catch {
+                // Drift detection must not break validation when the jsconfig is
+                // missing or unparsable — deploy reports those cases with guidance.
+            }
+        }
+        return results;
+    });
 }
 /**
  * Scans the per-binary xpcshell scaffold directory for entries whose
@@ -300,3 +305,41 @@ async function findOrphanXpcshellScaffolds(root, config) {
     }
     return issues;
 }
+/**
+ * Flags engine-side files that a previous deploy of `tagName` left behind
+ * after their workspace source was renamed or removed.
+ *
+ * Detection keys on the furnace state file: every `appliedChecksums` entry
+ * under `custom/<tagName>/` whose workspace source no longer exists but whose
+ * engine target is still present is an orphan. The next deploy prunes it, but
+ * until then jar.mn and the deployed directory disagree with the workspace,
+ * and a re-export could capture the stale state into a patch.
+ *
+ * Custom components only: override undeploys restore the upstream baseline
+ * rather than deleting files, so "orphan" has no meaning there.
+ */
+export async function findOrphanedEngineFiles(root, config, tagName, state, ftlDir) {
+    const customConfig = config.custom[tagName];
+    if (!customConfig)
+        return [];
+    const previous = extractComponentChecksums(state.appliedChecksums, 'custom', tagName);
+    const fileNames = Object.keys(previous);
+    if (fileNames.length === 0)
+        return [];
+    const { engine: engineDir, componentsDir } = getProjectPaths(root);
+    const componentDir = join(componentsDir, 'custom', tagName);
+    const issues = [];
+    for (const fileName of fileNames) {
+        if (await pathExists(join(componentDir, fileName)))
+            continue;
+        const enginePath = fileName.endsWith('.ftl')
+            ? join(engineDir, ftlDir, fileName)
+            : join(engineDir, customConfig.targetPath, fileName);
+        if (!(await pathExists(enginePath)))
+            continue;
+        issues.push(createIssue(tagName, 'warning', 'orphaned-engine-file', `Engine file ${fileName} was deployed by a previous apply but its workspace source ` +
+            `is gone (renamed or deleted). The deployed copy${customConfig.register ? ' and any stale jar.mn entry' : ''} ` +
+            `will linger until the next deploy prunes it. Run "fireforge furnace deploy ${tagName}".`));
+    }
+    return issues;
+}