Add traceAPIDependency debug utility for inspecting transitive API de…

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

@@ -18,12 +18,23 @@ export interface RepluggableAppDebugInfo {
     hmr: RepluggableHMR
 }
 
+export interface DependencyTree {
+    entryPoint: string
+    deps: { api: string; subtree: DependencyTree | null }[]
+}
+
 export interface RepluggableDebugUtils {
     apis(): APIDebugInfo[]
     unReadyEntryPoints(): EntryPoint[]
     getRootUnreadyAPI(): SlotKey<any>
     whyEntryPointUnready(name: string): void
     findAPI(name: string): APIDebugInfo[]
+    getAPIOrEntryPointsDependencies(
+        apisOrEntryPointsNames: string[],
+        entryPoints?: EntryPoint[]
+    ): { entryPoints: EntryPoint[]; apis: AnySlotKey[] }
+    traceAPIDependency(entryPointName: string, apiName: string): DependencyTree | null
+    visualizeDependencyTree(tree: DependencyTree | null): string
 }
 
 export interface RepluggableHMR {

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

@@ -87,6 +87,69 @@ const getRootUnreadyAPI = (host: AppHost) => {
     }
 }
 
+export type DependencyTree = {
+    entryPoint: string
+    deps: Array<{ api: string; subtree: DependencyTree | null }>
+}
+
+const traceAPIDependency = (entryPointName: string, apiName: string, entryPoints: EntryPoint[]): DependencyTree | null => {
+    const apiToDeclarer = mapApiToEntryPoint(entryPoints)
+    const entryPointByName = new Map(entryPoints.map(ep => [ep.name, ep]))
+    if (!entryPointByName.has(entryPointName)) {
+        return null
+    }
+
+    const onPath = new Set<string>()
+
+    const build = (epName: string): DependencyTree | null => {
+        if (onPath.has(epName)) {
+            return null
+        }
+        onPath.add(epName)
+
+        const deps: DependencyTree['deps'] = []
+        const epDeps = entryPointByName.get(epName)?.getDependencyAPIs?.() ?? []
+        for (const dep of epDeps) {
+            if (dep.name === apiName) {
+                deps.push({ api: dep.name, subtree: null })
+            } else {
+                const declarer = apiToDeclarer.get(dep.name)
+                const subtree = declarer ? build(declarer.name) : null
+                if (subtree) {
+                    deps.push({ api: dep.name, subtree })
+                }
+            }
+        }
+
+        onPath.delete(epName)
+        return deps.length > 0 ? { entryPoint: epName, deps } : null
+    }
+
+    return build(entryPointName)
+}
+
+const visualizeDependencyTree = (tree: DependencyTree | null): string => {
+    if (!tree) {
+        return '(no dependency paths)'
+    }
+
+    const lines: string[] = [tree.entryPoint]
+    const render = (node: DependencyTree, prefix: string): void => {
+        node.deps.forEach((edge, i) => {
+            const isLast = i === node.deps.length - 1
+            const connector = isLast ? '└─ ' : '├─ '
+            const nextPrefix = prefix + (isLast ? '   ' : '│  ')
+            const declaredBy = edge.subtree ? ` (declared by ${edge.subtree.entryPoint})` : ''
+            lines.push(`${prefix}${connector}${edge.api}${declaredBy}`)
+            if (edge.subtree) {
+                render(edge.subtree, nextPrefix)
+            }
+        })
+    }
+    render(tree, '')
+    return lines.join('\n')
+}
+
 const getAPIOrEntryPointsDependencies = (
     apisOrEntryPointsNames: string[],
     entryPoints: EntryPoint[]
@@ -167,6 +230,9 @@ export function setupDebugInfo({
             apisOrEntryPointsNames: string[],
             entryPoints = [...addedShells.values()].map(x => x.entryPoint)
         ) => getAPIOrEntryPointsDependencies(apisOrEntryPointsNames, entryPoints),
+        traceAPIDependency: (entryPointName: string, apiName: string): DependencyTree | null =>
+            traceAPIDependency(entryPointName, apiName, [...getUnreadyEntryPoints(), ...[...addedShells.values()].map(x => x.entryPoint)]),
+        visualizeDependencyTree,
         performance: getPerformanceDebug(options, trace, memoizedArr)
     }
 

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

@@ -88,6 +88,136 @@ describe('RepluggableAppDebug', () => {
             expect(unreadyAPIs).toEqual({ name: 'unreadyAPI' })
         })
 
+        it('should return all traversal paths from an entry point to a transitive API', () => {
+            createAppHost([
+                {
+                    name: 'entryPoint A',
+                    getDependencyAPIs: () => [{ name: 'API B' }]
+                },
+                {
+                    name: 'entryPoint B',
+                    declareAPIs: () => [{ name: 'API B' }],
+                    getDependencyAPIs: () => [{ name: 'API C' }]
+                },
+                {
+                    name: 'entryPoint C',
+                    declareAPIs: () => [{ name: 'API C' }]
+                }
+            ])
+
+            const { traceAPIDependency } = globalThis.repluggableAppDebug.utils
+
+            expect(traceAPIDependency('entryPoint A', 'API C')).toEqual({
+                entryPoint: 'entryPoint A',
+                deps: [
+                    {
+                        api: 'API B',
+                        subtree: {
+                            entryPoint: 'entryPoint B',
+                            deps: [{ api: 'API C', subtree: null }]
+                        }
+                    }
+                ]
+            })
+
+            expect(traceAPIDependency('entryPoint A', 'API B')).toEqual({
+                entryPoint: 'entryPoint A',
+                deps: [{ api: 'API B', subtree: null }]
+            })
+
+            expect(traceAPIDependency('entryPoint C', 'API B')).toBeNull()
+            expect(traceAPIDependency('nonexistent', 'API B')).toBeNull()
+        })
+
+        it('should branch the dependency tree when multiple routes reach the target API', () => {
+            createAppHost([
+                {
+                    name: 'entryPoint A',
+                    getDependencyAPIs: () => [{ name: 'API X' }, { name: 'API Y' }]
+                },
+                {
+                    name: 'entryPoint B',
+                    declareAPIs: () => [{ name: 'API X' }],
+                    getDependencyAPIs: () => [{ name: 'API Z' }]
+                },
+                {
+                    name: 'entryPoint C',
+                    declareAPIs: () => [{ name: 'API Y' }],
+                    getDependencyAPIs: () => [{ name: 'API Z' }]
+                },
+                {
+                    name: 'entryPoint D',
+                    declareAPIs: () => [{ name: 'API Z' }]
+                }
+            ])
+
+            const { traceAPIDependency } = globalThis.repluggableAppDebug.utils
+
+            expect(traceAPIDependency('entryPoint A', 'API Z')).toEqual({
+                entryPoint: 'entryPoint A',
+                deps: [
+                    {
+                        api: 'API X',
+                        subtree: {
+                            entryPoint: 'entryPoint B',
+                            deps: [{ api: 'API Z', subtree: null }]
+                        }
+                    },
+                    {
+                        api: 'API Y',
+                        subtree: {
+                            entryPoint: 'entryPoint C',
+                            deps: [{ api: 'API Z', subtree: null }]
+                        }
+                    }
+                ]
+            })
+        })
+
+        it('should visualize the dependency tree, collapsing shared prefixes', () => {
+            createAppHost([
+                {
+                    name: 'entryPoint A',
+                    getDependencyAPIs: () => [{ name: 'API B' }]
+                },
+                {
+                    name: 'entryPoint B',
+                    declareAPIs: () => [{ name: 'API B' }],
+                    getDependencyAPIs: () => [{ name: 'API X' }, { name: 'API Y' }]
+                },
+                {
+                    name: 'entryPoint X',
+                    declareAPIs: () => [{ name: 'API X' }],
+                    getDependencyAPIs: () => [{ name: 'API Z' }]
+                },
+                {
+                    name: 'entryPoint Y',
+                    declareAPIs: () => [{ name: 'API Y' }],
+                    getDependencyAPIs: () => [{ name: 'API Z' }]
+                },
+                {
+                    name: 'entryPoint Z',
+                    declareAPIs: () => [{ name: 'API Z' }]
+                }
+            ])
+
+            const { traceAPIDependency, visualizeDependencyTree } = globalThis.repluggableAppDebug.utils
+            const tree = traceAPIDependency('entryPoint A', 'API Z')
+
+            expect(visualizeDependencyTree(tree)).toBe(
+                [
+                    'entryPoint A',
+                    '└─ API B (declared by entryPoint B)',
+                    '   ├─ API X (declared by entryPoint X)',
+                    '   │  └─ API Z',
+                    '   └─ API Y (declared by entryPoint Y)',
+                    '      └─ API Z'
+                ].join('\n')
+            )
+
+            expect(visualizeDependencyTree(null)).toBe('(no dependency paths)')
+        })
+
         it('should return the root unready API when there is a graph of dependencies (declation order is reversed)', async () => {
             createAppHost(
                 [