Extract topological sort into a separate util

Author: vbabich

packages/plugin/src/PluginUtils.test.tsx

@@ -28,10 +28,8 @@ import {
   getPluginModuleValue,
   processLoadedModule,
   registerPlugin,
-  sortPluginsByDependency,
   createChainedComponent,
   createChainedPanelComponent,
-  type PluginManifestPluginInfo,
 } from './PluginUtils';
 
 function TestWidget() {
@@ -609,164 +607,6 @@ describe('processLoadedModule', () => {
   });
 });
 
-describe('sortPluginsByDependency', () => {
-  function makeManifestPlugin(
-    name: string,
-    opts?: {
-      package?: string;
-      dependencies?: string[];
-    }
-  ): PluginManifestPluginInfo {
-    return {
-      name,
-      main: 'index.js',
-      version: '1.0.0',
-      package: opts?.package,
-      dependencies: opts?.dependencies,
-    };
-  }
-
-  it('returns plugins in original order when no dependencies', () => {
-    const plugins = [
-      makeManifestPlugin('a'),
-      makeManifestPlugin('b'),
-      makeManifestPlugin('c'),
-    ];
-
-    const sorted = sortPluginsByDependency(plugins);
-
-    expect(sorted.map(p => p.name)).toEqual(['a', 'b', 'c']);
-  });
-
-  it('reorders so dependency loads before consumer', () => {
-    const plugins = [
-      makeManifestPlugin('consumer', {
-        dependencies: ['@scope/dep'],
-      }),
-      makeManifestPlugin('dep', {
-        package: '@scope/dep',
-      }),
-    ];
-
-    const sorted = sortPluginsByDependency(plugins);
-
-    expect(sorted.map(p => p.name)).toEqual(['dep', 'consumer']);
-  });
-
-  it('handles a chain of dependencies: a → b → c', () => {
-    const plugins = [
-      makeManifestPlugin('c', {
-        package: '@scope/c',
-        dependencies: ['@scope/b'],
-      }),
-      makeManifestPlugin('b', {
-        package: '@scope/b',
-        dependencies: ['@scope/a'],
-      }),
-      makeManifestPlugin('a', {
-        package: '@scope/a',
-      }),
-    ];
-
-    const sorted = sortPluginsByDependency(plugins);
-
-    const names = sorted.map(p => p.name);
-    expect(names.indexOf('a')).toBeLessThan(names.indexOf('b'));
-    expect(names.indexOf('b')).toBeLessThan(names.indexOf('c'));
-  });
-
-  it('preserves original order among independent plugins', () => {
-    const plugins = [
-      makeManifestPlugin('x'),
-      makeManifestPlugin('dep', { package: '@scope/dep' }),
-      makeManifestPlugin('y'),
-      makeManifestPlugin('consumer', { dependencies: ['@scope/dep'] }),
-      makeManifestPlugin('z'),
-    ];
-
-    const sorted = sortPluginsByDependency(plugins);
-
-    const names = sorted.map(p => p.name);
-    // dep must come before consumer
-    expect(names.indexOf('dep')).toBeLessThan(names.indexOf('consumer'));
-    // independent plugins keep their relative order
-    expect(names.indexOf('x')).toBeLessThan(names.indexOf('y'));
-    expect(names.indexOf('y')).toBeLessThan(names.indexOf('z'));
-  });
-
-  it('throws on circular dependencies', () => {
-    const plugins = [
-      makeManifestPlugin('a', {
-        package: '@scope/a',
-        dependencies: ['@scope/b'],
-      }),
-      makeManifestPlugin('b', {
-        package: '@scope/b',
-        dependencies: ['@scope/a'],
-      }),
-    ];
-
-    expect(() => sortPluginsByDependency(plugins)).toThrow(
-      /Circular plugin dependency/
-    );
-  });
-
-  it('warns and ignores dependencies not in the manifest', () => {
-    const plugins = [
-      makeManifestPlugin('consumer', {
-        dependencies: ['@scope/nonexistent'],
-      }),
-    ];
-
-    const sorted = sortPluginsByDependency(plugins);
-
-    expect(sorted.map(p => p.name)).toEqual(['consumer']);
-  });
-
-  it('handles multiple dependencies', () => {
-    const plugins = [
-      makeManifestPlugin('consumer', {
-        dependencies: ['@scope/dep-a', '@scope/dep-b'],
-      }),
-      makeManifestPlugin('dep-a', { package: '@scope/dep-a' }),
-      makeManifestPlugin('dep-b', { package: '@scope/dep-b' }),
-    ];
-
-    const sorted = sortPluginsByDependency(plugins);
-
-    const names = sorted.map(p => p.name);
-    expect(names.indexOf('dep-a')).toBeLessThan(names.indexOf('consumer'));
-    expect(names.indexOf('dep-b')).toBeLessThan(names.indexOf('consumer'));
-  });
-
-  it('does not mutate the input array', () => {
-    const plugins = [
-      makeManifestPlugin('consumer', { dependencies: ['@scope/dep'] }),
-      makeManifestPlugin('dep', { package: '@scope/dep' }),
-    ];
-    const original = [...plugins];
-
-    sortPluginsByDependency(plugins);
-
-    expect(plugins).toEqual(original);
-  });
-
-  it('handles empty plugin list', () => {
-    expect(sortPluginsByDependency([])).toEqual([]);
-  });
-
-  it('handles plugins with empty dependencies array', () => {
-    const plugins = [
-      makeManifestPlugin('a', { dependencies: [] }),
-      makeManifestPlugin('b'),
-    ];
-
-    const sorted = sortPluginsByDependency(plugins);
-
-    expect(sorted.map(p => p.name)).toEqual(['a', 'b']);
-  });
-});
-
 describe('createChainedComponent', () => {
   function BaseWidget({ fetch }: WidgetComponentProps) {
     return <div data-testid="base">BaseWidget</div>;

packages/plugin/src/PluginUtils.tsx

@@ -263,111 +263,6 @@ export type PluginManifestPluginInfo = {
 
 export type PluginManifest = { plugins: PluginManifestPluginInfo[] };
 
-/**
- * Topologically sort plugins so that dependencies are loaded before the
- * plugins that depend on them. Plugins without dependencies or whose
- * dependencies are not in the manifest keep their original relative order
- * (stable sort). Throws if a dependency cycle is detected.
- *
- * @param plugins The plugin list from the manifest
- * @returns A new array with plugins sorted so dependencies come first
- */
-export function sortPluginsByDependency<
-  T extends Pick<PluginManifestPluginInfo, 'name' | 'package' | 'dependencies'>,
->(plugins: readonly T[]): T[] {
-  // Build a lookup from package name → plugin index
-  const packageToIndex = new Map<string, number>();
-  plugins.forEach((p, i) => {
-    if (p.package != null) {
-      packageToIndex.set(p.package, i);
-    }
-  });
-
-  // Build adjacency list: index → indices it depends on
-  const depIndices = new Map<number, number[]>();
-  plugins.forEach((p, i) => {
-    if (p.dependencies != null && p.dependencies.length > 0) {
-      const resolved: number[] = [];
-      p.dependencies.forEach(dep => {
-        const idx = packageToIndex.get(dep);
-        if (idx != null) {
-          resolved.push(idx);
-        } else {
-          log.warn(
-            `Plugin '${p.name}' depends on '${dep}' which is not in the manifest`
-          );
-        }
-      });
-      if (resolved.length > 0) {
-        depIndices.set(i, resolved);
-      }
-    }
-  });
-
-  // If no plugin has in-manifest dependencies, return original order
-  if (depIndices.size === 0) {
-    return [...plugins];
-  }
-
-  // Kahn's algorithm for topological sort (stable — preserves original order
-  // among plugins at the same dependency depth)
-  const inDegree = new Array<number>(plugins.length).fill(0);
-
-  // Reverse adjacency: who depends on me?
-  const dependents = new Map<number, number[]>();
-  depIndices.forEach((deps, idx) => {
-    deps.forEach(dep => {
-      if (!dependents.has(dep)) {
-        dependents.set(dep, []);
-      }
-      const depList = dependents.get(dep);
-      if (depList != null) {
-        depList.push(idx);
-      }
-      inDegree[idx] += 1;
-    });
-  });
-
-  // Seed queue with all nodes that have no in-manifest dependencies,
-  // in their original order
-  const queue: number[] = [];
-  for (let i = 0; i < plugins.length; i += 1) {
-    if (inDegree[i] === 0) {
-      queue.push(i);
-    }
-  }
-
-  const sorted: T[] = [];
-  while (queue.length > 0) {
-    const idx = queue.shift();
-    if (idx == null) {
-      break;
-    }
-    sorted.push(plugins[idx]);
-    const deps = dependents.get(idx);
-    if (deps != null) {
-      // Process dependents in original manifest order for stability
-      deps.sort((a, b) => a - b);
-      deps.forEach(depIdx => {
-        inDegree[depIdx] -= 1;
-        if (inDegree[depIdx] === 0) {
-          queue.push(depIdx);
-        }
-      });
-    }
-  }
-
-  if (sorted.length !== plugins.length) {
-    // Find the cycle participants for a useful error message
-    const inCycle = plugins.filter((_, i) => inDegree[i] > 0).map(p => p.name);
-    throw new Error(
-      `Circular plugin dependency detected among: ${inCycle.join(', ')}`
-    );
-  }
-
-  return sorted;
-}
-
 function hasDefaultExport(value: unknown): value is { default: Plugin } {
   return (
     typeof value === 'object' &&

packages/plugin/src/index.ts

@@ -1,6 +1,7 @@
 export * from './PluginsContext';
 export * from './PluginTypes';
 export * from './PluginUtils';
+export * from './pluginSortUtil';
 export * from './TablePlugin';
 export * from './useCustomThemes';
 export * from './useDashboardPlugins';

packages/plugin/src/pluginSortUtil/index.ts

@@ -0,0 +1 @@
+export * from './sortPluginsByDependency';