Make createAppHostAndWaitForLoading timeout configurable and report all root unready APIs

- new options argument: createAppHostAndWaitForLoading(packages, pacts, { timeout })
  (default 3000 preserves existing behavior)
- on timeout, reject with AppHostLoadingTimeoutError carrying the structured
  UnreadyEntryPointsReport plus a message listing every root unready API with
  its declarer category, blocked entry points, and a rendered dependency path
  (via traceAPIDependency/visualizeDependencyTree)
- clear the timeout timer once loading wins the race (previously left pending)

The timeout message previously surfaced a single, sometimes non-root API from
the deprecated getRootUnreadyAPI walk; the existing failure-path test asserted
a transitively blocked API name and now asserts the actual root cause.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: bodia-uz

packages/repluggable-core/test/testKit.spec.tsx

@@ -12,7 +12,8 @@ import {
     asyncLoadMockPackage,
     dependsOnMockPackageEntryPoint,
     MockPublicAPI,
-    createAppHostAndWaitForLoading
+    createAppHostAndWaitForLoading,
+    AppHostLoadingTimeoutError
 } from '../testKit'
 
 interface APIKeys {
@@ -147,7 +148,61 @@ describe('App Host TestKit', () => {
         it('should throw if failed to load all packages', async () => {
             const hostPromise = createAppHostAndWaitForLoading([dependsOnMockPackageEntryPoint], [])
             jest.runAllTimers()
-            await expect(hostPromise).rejects.toThrow(new RegExp(MockPublicAPI.name))
+            await expect(hostPromise).rejects.toThrow(new RegExp(MockAPI.name))
+        })
+
+        it('should reject with a structured report of all root unready APIs', async () => {
+            const hostPromise = createAppHostAndWaitForLoading(
+                [
+                    {
+                        name: 'entryPoint A',
+                        declareAPIs: () => [{ name: 'API A' }],
+                        getDependencyAPIs: () => [{ name: 'missing A' }]
+                    },
+                    {
+                        name: 'entryPoint B',
+                        declareAPIs: () => [{ name: 'API B' }],
+                        getDependencyAPIs: () => [{ name: 'missing B' }]
+                    }
+                ],
+                []
+            )
+            jest.runAllTimers()
+            const error: AppHostLoadingTimeoutError = await hostPromise.then(
+                () => {
+                    throw new Error('expected hostPromise to reject')
+                },
+                e => e
+            )
+
+            expect(error).toBeInstanceOf(AppHostLoadingTimeoutError)
+            expect(error.report.rootUnreadyAPIs.map(info => info.key.name)).toEqual(['missing A', 'missing B'])
+            expect(error.message).toContain('"missing A"')
+            expect(error.message).toContain('"missing B"')
+            expect(error.message).toContain('required by: entryPoint A')
+            expect(error.message).toContain('required by: entryPoint B')
+        })
+
+        it('should respect a custom loading timeout', async () => {
+            let settled = false
+            const hostPromise = createAppHostAndWaitForLoading([dependsOnMockPackageEntryPoint], [], { timeout: 10000 })
+            hostPromise.catch(() => (settled = true))
+
+            jest.advanceTimersByTime(9999)
+            await Promise.resolve()
+            await Promise.resolve()
+            expect(settled).toBe(false)
+
+            jest.advanceTimersByTime(1)
+            await expect(hostPromise).rejects.toBeInstanceOf(AppHostLoadingTimeoutError)
+        })
+
+        it('should not leave a pending timeout after successful loading', async () => {
+            const hostPromise = createAppHostAndWaitForLoading([dependsOnMockPackageEntryPoint, asyncLoadMockPackage], [])
+            jest.advanceTimersByTime(500)
+            const host = await hostPromise
+            expect(host.getAPI(MockPublicAPI)).toBeDefined()
+            expect(jest.getTimerCount()).toBe(0)
         })
     })
 })

packages/repluggable-core/testKit/index.ts

@@ -1,6 +1,7 @@
 import _ from 'lodash'
 import { EntryPoint, ObservableState } from '../src/API'
 import { AnySlotKey, AppHost, createAppHost as _createAppHost, EntryPointOrPackage, Shell, SlotKey } from '../src/index'
+import { UnreadyEntryPointsReport } from '../src/repluggableAppDebug'
 import { createShellLogger } from '../src/loggers'
 import { emptyLoggerOptions } from './emptyLoggerOptions'
 
@@ -81,34 +82,79 @@ export function createAppHostWithPacts(packages: EntryPointOrPackage[], pacts: P
     })
 }
 
-export async function createAppHostAndWaitForLoading(packages: EntryPointOrPackage[], pacts: PactAPIBase[]): Promise<AppHost> {
+export interface WaitForLoadingOptions {
+    /** milliseconds to wait for host loading before rejecting with an unready entry points report (default: 3000) */
+    timeout?: number
+}
+
+export class AppHostLoadingTimeoutError extends Error {
+    constructor(message: string, public readonly report: UnreadyEntryPointsReport) {
+        super(message)
+        this.name = 'AppHostLoadingTimeoutError'
+    }
+}
+
+const WAIT_FOR_LOADING_PROBE_SHELL = 'Depends on all declared APIs'
+
+const formatUnreadyReport = (timeout: number, report: UnreadyEntryPointsReport): string => {
+    const { utils } = globalThis.repluggableAppDebug
+    const isProbeShell = (name: string) => name === WAIT_FOR_LOADING_PROBE_SHELL
+    const header = `createAppHostAndWaitForLoading - host not ready within ${timeout}ms.`
+    const unreadyEntryPoints = report.unreadyEntryPoints.filter(entryPoint => !isProbeShell(entryPoint.name))
+    const rootUnreadyEntryPoints = report.rootUnreadyEntryPoints.filter(entryPoint => !isProbeShell(entryPoint.name))
+
+    if (report.probableDependencyCycle) {
+        const names = unreadyEntryPoints.map(entryPoint => `"${entryPoint.name}"`).join(', ')
+        return `${header}
+No root unready API found while ${unreadyEntryPoints.length} entry points are unready - probable dependency cycle between: ${names}`
+    }
+
+    const roots = report.rootUnreadyAPIs.map((info, index) => {
+        const declaredBy =
+            info.declaredBy === 'nobody'
+                ? 'declared by NO entry point (missing package or pact?)'
+                : `declared by "${info.declaredBy.entryPointName}" (installed, but its contribution never completed - hung async contributeAPI?)`
+        const requiredBy = info.requiredBy.filter(name => !isProbeShell(name))
+        const lines = [`${index + 1}. "${info.key.name}" - ${declaredBy}`]
+        if (requiredBy.length) {
+            lines.push(`   required by: ${requiredBy.join(', ')}`)
+            const tree = utils.visualizeDependencyTree(utils.traceAPIDependency(requiredBy[0], info.key.name))
+            lines.push(...tree.split('\n').map(line => `   ${line}`))
+        }
+        return lines.join('\n')
+    })
+
+    return `${header}
+
+Root unready APIs (${report.rootUnreadyAPIs.length}):
+${roots.join('\n')}
+
+Unready entry points: ${rootUnreadyEntryPoints.length} blocked directly on root APIs, ${unreadyEntryPoints.length} total.`
+}
+
+export async function createAppHostAndWaitForLoading(
+    packages: EntryPointOrPackage[],
+    pacts: PactAPIBase[],
+    { timeout = 3000 }: WaitForLoadingOptions = {}
+): Promise<AppHost> {
     const appHost = createAppHostWithPacts(packages, pacts)
     const declaredAPIs = _(packages)
         .flatten()
         .value()
         .flatMap((entryPoint: EntryPoint) => (entryPoint.declareAPIs ? entryPoint.declareAPIs() : []))
 
-    const timeoutPromise = new Promise((resolve, reject) => {
-        setTimeout(() => {
-            const readyAPIs = Array.from(globalThis.repluggableAppDebug.readyAPIs)
-            const unreadyAPIs = declaredAPIs.filter(api => !readyAPIs.some(readyAPI => readyAPI.name === api.name))
-            const rootUnreadyAPI = globalThis.repluggableAppDebug.utils.getRootUnreadyAPI()
-
-            reject(
-                new Error(
-                    `createAppHostAndWaitForLoading - waiting for loading timed out.
-there's a high chance this missing API is the main reason for it: ${JSON.stringify(rootUnreadyAPI)}
-
-in addition here's the full list of declared APIs that have not been contributed: ${JSON.stringify(unreadyAPIs)}`
-                )
-            )
-        }, 3000)
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const timeoutPromise = new Promise<never>((resolve, reject) => {
+        timer = setTimeout(() => {
+            const report = globalThis.repluggableAppDebug.utils.getUnreadyEntryPointsReport()
+            reject(new AppHostLoadingTimeoutError(formatUnreadyReport(timeout, report), report))
+        }, timeout)
     })
 
     const loadingPromise = new Promise<void>(async resolve => {
         await appHost.addShells([
             {
-                name: 'Depends on all declared APIs',
+                name: WAIT_FOR_LOADING_PROBE_SHELL,
                 getDependencyAPIs() {
                     return declaredAPIs
                 },
@@ -119,7 +165,14 @@ in addition here's the full list of declared APIs that have not been contributed
         ])
     })
 
-    return Promise.race([timeoutPromise, loadingPromise]).then(() => appHost)
+    try {
+        await Promise.race([timeoutPromise, loadingPromise])
+        return appHost
+    } finally {
+        if (timer) {
+            clearTimeout(timer)
+        }
+    }
 }
 
 type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>