Add getUnreadyEntryPointsReport debug util reporting all root unready APIs

The previous getRootUnreadyAPI walk was structurally lossy: it started from an
arbitrary first unready entry point, abandoned sibling dependency branches when
descending into a declarer, could loop forever on dependency cycles, and
returned at most one API when real failures often have several independent
roots.

getUnreadyEntryPointsReport computes the full picture with set math instead:
- all root unready APIs (a dependency of an unready entry point that is
  neither ready nor declared by another unready entry point), each categorized
  as declared-by-nobody (missing package/pact) or declared by an installed
  shell whose contribution never completed
- which entry points are directly blocked on each root
- a probable-dependency-cycle flag for hosts running with circular-dependency
  validation disabled

getRootUnreadyAPI is kept as a deprecated shim over the report, which also
makes it cycle-safe.

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

Author: bodia-uz

packages/repluggable-core/src/repluggableAppDebug/debug.d.ts

@@ -23,10 +23,25 @@ export interface DependencyTree {
     deps: { api: string; subtree: DependencyTree | null }[]
 }
 
+export interface RootUnreadyAPIInfo {
+    key: AnySlotKey
+    declaredBy: 'nobody' | { entryPointName: string }
+    requiredBy: string[]
+}
+
+export interface UnreadyEntryPointsReport {
+    unreadyEntryPoints: EntryPoint[]
+    rootUnreadyAPIs: RootUnreadyAPIInfo[]
+    rootUnreadyEntryPoints: EntryPoint[]
+    probableDependencyCycle: boolean
+}
+
 export interface RepluggableDebugUtils {
     apis(): APIDebugInfo[]
     unReadyEntryPoints(): EntryPoint[]
-    getRootUnreadyAPI(): SlotKey<any>
+    getUnreadyEntryPointsReport(): UnreadyEntryPointsReport
+    /** @deprecated use getUnreadyEntryPointsReport() - this returns only the first of possibly many root unready APIs */
+    getRootUnreadyAPI(): SlotKey<any> | undefined
     whyEntryPointUnready(name: string): void
     findAPI(name: string): APIDebugInfo[]
     getAPIOrEntryPointsDependencies(

packages/repluggable-core/src/repluggableAppDebug/index.ts

@@ -1 +1 @@
-export { setupDebugInfo } from './repluggableAppDebug'
+export { setupDebugInfo, RootUnreadyAPIInfo, UnreadyEntryPointsReport } from './repluggableAppDebug'

packages/repluggable-core/src/repluggableAppDebug/repluggableAppDebug.ts

@@ -36,54 +36,74 @@ function mapApiToEntryPoint(allPackages: EntryPoint[]) {
     return apiToEntryPoint
 }
 
-/**
- * a function that returns all the entry points in the system with their declared APIs and dependencies
- */
-const getAllEntryPoints = () => {
-    return [
-        ...globalThis.repluggableAppDebug.utils.unReadyEntryPoints(),
-        ...[...globalThis.repluggableAppDebug.addedShells].map(([_, shell]) => shell.entryPoint)
-    ]
+export interface RootUnreadyAPIInfo {
+    key: AnySlotKey
+    /**
+     * 'nobody'  -> not declared by any entry point in the host (missing package / pact)
+     * otherwise -> declared by an INSTALLED shell whose contributeAPI never completed (hung async contribution)
+     */
+    declaredBy: 'nobody' | { entryPointName: string }
+    /** names of unready entry points directly blocked on this API */
+    requiredBy: string[]
+}
+
+export interface UnreadyEntryPointsReport {
+    unreadyEntryPoints: EntryPoint[]
+    rootUnreadyAPIs: RootUnreadyAPIInfo[]
+    /** unready entry points directly blocked on a root unready API */
+    rootUnreadyEntryPoints: EntryPoint[]
+    /** true when entry points are unready but no root unready API exists - their dependencies form a cycle */
+    probableDependencyCycle: boolean
 }
 
+type UnreadyReportParams = Pick<SetupDebugInfoParams, 'readyAPIs' | 'getOwnSlotKey' | 'getUnreadyEntryPoints' | 'addedShells'>
+
 /**
- * this function is used to get the root unready API in case there are too many to understand.
- * for example if you have 200 unready entry points, running this function will give you the first unready API that
- * will unblock the rest of the entry point (note that there might be more than one)
- *
- * this function basically takes the first unready entry point, get its dependencies and iterates over them to find an API that is not ready
- * at this point it follows the same process recursively until it reaced the target API.
+ * Computes all root unready APIs at once: dependencies of unready entry points that are neither ready
+ * nor declared by another unready entry point (i.e. the APIs actually blocking the host from loading).
  */
-const getRootUnreadyAPI = (host: AppHost) => {
-    return () => {
-        // get all unready entry points
-        const allEntryPoints = getAllEntryPoints()
-        const unReadyAPIsArray = []
-        // get the depdenencies of the first unready entry point
-        let dependenciesOfUnreadyEntryPoint = allEntryPoints?.[0]?.getDependencyAPIs?.()
-
-        while (dependenciesOfUnreadyEntryPoint?.length) {
-            const currentAPI = dependenciesOfUnreadyEntryPoint.pop()
-
-            if (!currentAPI) {
-                continue
-            }
-            // try to get the API from this host, we are looking for an API that is not ready
-            try {
-                const api = host.getAPI(currentAPI as SlotKey<any>)
-                if (api) {
-                    continue
+const createGetUnreadyEntryPointsReport = ({ readyAPIs, getOwnSlotKey, getUnreadyEntryPoints, addedShells }: UnreadyReportParams) => {
+    return (): UnreadyEntryPointsReport => {
+        const unreadyEntryPoints = getUnreadyEntryPoints()
+        const isReady = (key: AnySlotKey) => readyAPIs.has(getOwnSlotKey(key as SlotKey<any>))
+
+        const declaredByUnready = new Set<string>()
+        unreadyEntryPoints.forEach(entryPoint => entryPoint.declareAPIs?.().forEach(key => declaredByUnready.add(key.name)))
+
+        const declaredByInstalled = new Map<string, string>()
+        for (const shell of addedShells.values()) {
+            shell.entryPoint.declareAPIs?.().forEach(key => declaredByInstalled.set(key.name, shell.entryPoint.name))
+        }
+
+        const rootByName = new Map<string, RootUnreadyAPIInfo>()
+        unreadyEntryPoints.forEach(entryPoint => {
+            entryPoint.getDependencyAPIs?.().forEach(key => {
+                if (isReady(key) || declaredByUnready.has(key.name)) {
+                    return
                 }
-            } catch (e) {
-                unReadyAPIsArray.push(currentAPI)
-                // we found an API that is unready, lets find which entry point declares it
-                const declarer = allEntryPoints.find(entryPointData =>
-                    entryPointData.declareAPIs?.().some(api => currentAPI?.name === api.name)
-                )
-                dependenciesOfUnreadyEntryPoint = declarer?.getDependencyAPIs?.()
-            }
+                const declarerName = declaredByInstalled.get(key.name)
+                const info = rootByName.get(key.name) ?? {
+                    key,
+                    declaredBy: declarerName ? { entryPointName: declarerName } : ('nobody' as const),
+                    requiredBy: []
+                }
+                info.requiredBy.push(entryPoint.name)
+                rootByName.set(key.name, info)
+            })
+        })
+
+        const rootUnreadyAPIs = [...rootByName.values()]
+        const rootAPINames = new Set(rootByName.keys())
+        const rootUnreadyEntryPoints = unreadyEntryPoints.filter(entryPoint =>
+            entryPoint.getDependencyAPIs?.().some(key => rootAPINames.has(key.name))
+        )
+
+        return {
+            unreadyEntryPoints,
+            rootUnreadyAPIs,
+            rootUnreadyEntryPoints,
+            probableDependencyCycle: unreadyEntryPoints.length > 0 && rootUnreadyAPIs.length === 0
         }
-        return unReadyAPIsArray.reverse()[0]
     }
 }
 
@@ -207,7 +227,9 @@ export function setupDebugInfo({
                 }
             })
         },
-        getRootUnreadyAPI: getRootUnreadyAPI(host),
+        getUnreadyEntryPointsReport: createGetUnreadyEntryPointsReport({ readyAPIs, getOwnSlotKey, getUnreadyEntryPoints, addedShells }),
+        /** @deprecated use getUnreadyEntryPointsReport() - this returns only the first of possibly many root unready APIs */
+        getRootUnreadyAPI: (): AnySlotKey | undefined => utils.getUnreadyEntryPointsReport().rootUnreadyAPIs[0]?.key,
         unReadyEntryPoints: (): EntryPoint[] => getUnreadyEntryPoints(),
         whyEntryPointUnready: (name: string) => {
             const unreadyEntryPoint = _.find(

packages/repluggable-core/test/repluggableAppDebug.spec.ts

@@ -245,4 +245,154 @@ describe('RepluggableAppDebug', () => {
             expect(unreadyAPIs).toEqual({ name: 'unreadyAPI' })
         })
     })
+
+    describe('getUnreadyEntryPointsReport', () => {
+        const getReport = async () => {
+            await new Promise(resolve => setTimeout(resolve, 0))
+            return globalThis.repluggableAppDebug.utils.getUnreadyEntryPointsReport()
+        }
+
+        it('should report no unready entry points when all are loaded', async () => {
+            createAppHost([
+                {
+                    name: 'entryPoint',
+                    declareAPIs: () => []
+                }
+            ])
+
+            const report = await getReport()
+
+            expect(report).toEqual({
+                unreadyEntryPoints: [],
+                rootUnreadyAPIs: [],
+                rootUnreadyEntryPoints: [],
+                probableDependencyCycle: false
+            })
+        })
+
+        it('should report all root unready APIs of independent unready clusters', async () => {
+            createAppHost([
+                {
+                    name: 'entryPoint A',
+                    getDependencyAPIs: () => [{ name: 'missing A' }]
+                },
+                {
+                    name: 'entryPoint B',
+                    getDependencyAPIs: () => [{ name: 'missing B' }]
+                }
+            ])
+
+            const report = await getReport()
+
+            expect(report.rootUnreadyAPIs).toEqual([
+                { key: { name: 'missing A' }, declaredBy: 'nobody', requiredBy: ['entryPoint A'] },
+                { key: { name: 'missing B' }, declaredBy: 'nobody', requiredBy: ['entryPoint B'] }
+            ])
+            expect(report.rootUnreadyEntryPoints.map(entryPoint => entryPoint.name)).toEqual(['entryPoint A', 'entryPoint B'])
+            expect(report.probableDependencyCycle).toBe(false)
+        })
+
+        it('should report only the root API of a transitively blocked chain', async () => {
+            createAppHost([
+                {
+                    name: 'entryPoint A',
+                    getDependencyAPIs: () => [{ name: 'API B' }]
+                },
+                {
+                    name: 'entryPoint B',
+                    declareAPIs: () => [{ name: 'API B' }],
+                    getDependencyAPIs: () => [unreadAPI]
+                }
+            ])
+
+            const report = await getReport()
+
+            expect(report.rootUnreadyAPIs).toEqual([{ key: unreadAPI, declaredBy: 'nobody', requiredBy: ['entryPoint B'] }])
+            expect(report.rootUnreadyEntryPoints.map(entryPoint => entryPoint.name)).toEqual(['entryPoint B'])
+            expect(report.unreadyEntryPoints.map(entryPoint => entryPoint.name)).toEqual(['entryPoint A', 'entryPoint B'])
+        })
+
+        it('should report roots of sibling branches, including APIs declared by an installed shell that never contributed them', async () => {
+            createAppHost([
+                {
+                    name: 'entryPoint 0',
+                    getDependencyAPIs: () => [{ name: 'missing API' }, { name: 'API B' }]
+                },
+                {
+                    name: 'entryPoint 1',
+                    declareAPIs: () => [{ name: 'API B' }]
+                }
+            ])
+
+            const report = await getReport()
+
+            expect(report.rootUnreadyAPIs).toEqual([
+                { key: { name: 'missing API' }, declaredBy: 'nobody', requiredBy: ['entryPoint 0'] },
+                { key: { name: 'API B' }, declaredBy: { entryPointName: 'entryPoint 1' }, requiredBy: ['entryPoint 0'] }
+            ])
+        })
+
+        it('should aggregate all entry points blocked on the same root API', async () => {
+            createAppHost([
+                {
+                    name: 'entryPoint A',
+                    getDependencyAPIs: () => [unreadAPI]
+                },
+                {
+                    name: 'entryPoint B',
+                    getDependencyAPIs: () => [unreadAPI]
+                }
+            ])
+
+            const report = await getReport()
+
+            expect(report.rootUnreadyAPIs).toEqual([{ key: unreadAPI, declaredBy: 'nobody', requiredBy: ['entryPoint A', 'entryPoint B'] }])
+        })
+
+        it('should flag a probable dependency cycle when unready entry points have no root unready API', async () => {
+            createAppHost(
+                [
+                    {
+                        name: 'entryPoint A',
+                        declareAPIs: () => [{ name: 'API X' }],
+                        getDependencyAPIs: () => [{ name: 'API Y' }]
+                    },
+                    {
+                        name: 'entryPoint B',
+                        declareAPIs: () => [{ name: 'API Y' }],
+                        getDependencyAPIs: () => [{ name: 'API X' }]
+                    }
+                ],
+                { monitoring: {}, disableCheckCircularDependencies: true }
+            )
+
+            const report = await getReport()
+
+            expect(report.rootUnreadyAPIs).toEqual([])
+            expect(report.unreadyEntryPoints.map(entryPoint => entryPoint.name)).toEqual(['entryPoint A', 'entryPoint B'])
+            expect(report.probableDependencyCycle).toBe(true)
+        })
+
+        it('should not hang getRootUnreadyAPI on a dependency cycle', async () => {
+            createAppHost(
+                [
+                    {
+                        name: 'entryPoint A',
+                        declareAPIs: () => [{ name: 'API X' }],
+                        getDependencyAPIs: () => [{ name: 'API Y' }]
+                    },
+                    {
+                        name: 'entryPoint B',
+                        declareAPIs: () => [{ name: 'API Y' }],
+                        getDependencyAPIs: () => [{ name: 'API X' }]
+                    }
+                ],
+                { monitoring: {}, disableCheckCircularDependencies: true }
+            )
+
+            const unreadyAPIs = await getUnreadyAPIs()
+
+            expect(unreadyAPIs).toBeUndefined()
+        }, 3000)
+    })
 })