@enspirit/emb 0.0.6 → 0.0.7

package/dist/src/monorepo/operations/components/BuildComponentsOperation.js

@@ -1,79 +1,58 @@
-import { Manager } from '@listr2/manager';
-import { createColors } from 'colorette';
-import { delay, ListrDefaultRendererLogLevels, PRESET_TIMER, } from 'listr2';
+import { getContext } from '../../../index.js';
 import * as z from 'zod';
 import { BuildImageOperation, getSentinelFile, } from '../../../docker/index.js';
-import { findBuildOrder } from '../../utils/findBuildOrder.js';
+import { EMBCollection, findRunOrder, taskManagerFactory, } from '../../index.js';
 import { AbstractOperation } from '../../../operations/index.js';
-import { FilePrerequisitePlugin } from '../../../prerequisites/FilePrerequisitePlugin.js';
-import { PrerequisiteType } from '../../../prerequisites/types.js';
+import { FilePrerequisitePlugin, PrerequisiteType } from '../../../prerequisites/index.js';
 const schema = z.object({
     components: z
         .array(z.string())
         .describe('The list of components to build')
         .optional(),
+    dryRun: z
+        .boolean()
+        .optional()
+        .describe('Do not build but return the config that would be used to build the images'),
 });
 export class BuildComponentsOperation extends AbstractOperation {
     constructor() {
         super(schema);
     }
     async _run(input) {
-        const ordered = findBuildOrder(this.context.monorepo.components, input.components);
+        const { monorepo } = getContext();
+        const manager = taskManagerFactory();
+        const selection = (input.components || []).map((t) => monorepo.component(t));
+        const collection = new EMBCollection(this.context.monorepo.components, {
+            idField: 'name',
+            depField: 'dependencies',
+            forbidIdNameCollision: true,
+        });
+        const ordered = findRunOrder(selection.map((s) => s.name), collection);
         const tasks = await Promise.all(ordered.map((cmp) => {
             return {
                 task: async (context, task) => {
-                    return this.buildComponent(cmp, task);
+                    return this.buildComponent(cmp, task, context, input.dryRun);
                 },
                 title: `Building ${cmp.name}`,
             };
         }));
-        const manager = new Manager({
-            collectErrors: 'minimal',
-            concurrent: false,
-            exitOnError: true,
-            rendererOptions: {
-                collapseErrors: false,
-                collapseSubtasks: false,
-                color: {
-                    // @ts-expect-error not sure why
-                    [ListrDefaultRendererLogLevels.SKIPPED_WITH_COLLAPSE]: createColors().green,
-                },
-                icon: {
-                    [ListrDefaultRendererLogLevels.SKIPPED_WITH_COLLAPSE]: '♺',
-                },
-                timer: {
-                    ...PRESET_TIMER,
-                },
-            },
+        const list = manager.newListr([...tasks], {
+            rendererOptions: { persistentOutput: true },
+            ctx: {},
         });
-        manager.add([
-            {
-                async task(_context, task) {
-                    return task.newListr([...tasks], {
-                        rendererOptions: {
-                            collapseSubtasks: false,
-                        },
-                    });
-                },
-                title: 'Building components',
-            },
-        ]);
-        await manager.runAll();
-        return ordered;
+        const results = await list.run();
+        return results;
     }
-    async buildComponent(cmp, parentTask) {
-        return parentTask.newListr([
+    async buildComponent(cmp, parentTask, parentContext, dryRun = false) {
+        const prereqPlugin = new FilePrerequisitePlugin();
+        const list = parentTask.newListr([
             // Collect all the prerequisites and other build infos
             // (This is when variables are expanded etc)
             {
                 async task(ctx) {
-                    // Reset the context to defaults (as apparently the context is shared amongst branches??)
-                    // TODO understand and fix
-                    ctx.skip = false;
-                    //
-                    ctx.parentTask = parentTask;
+                    // Install the context for this specific component build chain
+                    ctx.cacheHit = false;
                     ctx.sentinelFile = getSentinelFile(cmp);
-                    ctx.plugin = new FilePrerequisitePlugin();
                     ctx.build = await cmp.toDockerBuild();
                 },
                 title: 'Prepare build context',
@@ -81,7 +60,7 @@ export class BuildComponentsOperation extends AbstractOperation {
             // Check for sentinal information to see if the build can be skipped
             {
                 task: async (ctx) => {
-                    ctx.preBuildMeta = await ctx.plugin.meta(cmp, ctx.build.prerequisites, 'pre');
+                    ctx.preBuildMeta = await prereqPlugin.meta(cmp, ctx.build.prerequisites, 'pre');
                     let lastValue;
                     try {
                         lastValue = (await this.context.monorepo.store.readFile(ctx.sentinelFile)).toString();
@@ -90,10 +69,10 @@ export class BuildComponentsOperation extends AbstractOperation {
                         lastValue = undefined;
                     }
                     if (lastValue) {
-                        const diff = await ctx.plugin.diff(cmp, ctx.build.prerequisites, lastValue, ctx.preBuildMeta);
+                        const diff = await prereqPlugin.diff(cmp, ctx.build.prerequisites, lastValue, ctx.preBuildMeta);
                         if (!diff) {
-                            ctx.skip = true;
-                            ctx.parentTask.skip(`${ctx.parentTask.title} (cache hit)`);
+                            ctx.cacheHit = true;
+                            // parentTask.skip(`${parentTask.title} (cache hit)`);
                         }
                     }
                 },
@@ -101,10 +80,9 @@ export class BuildComponentsOperation extends AbstractOperation {
             },
             {
                 task: async (ctx, task) => {
-                    if (ctx.skip) {
+                    if (ctx.cacheHit || ctx.dryRun) {
                         return task.skip();
                     }
-                    await delay(500);
                     const title = `Building image ${ctx.build.name}:${ctx.build.tag}`;
                     task.title = title;
                     const op = new BuildImageOperation((progress) => {
@@ -127,18 +105,26 @@ export class BuildComponentsOperation extends AbstractOperation {
             // Update sentinel file
             {
                 task: async (ctx, task) => {
-                    if (ctx.skip) {
+                    if (ctx.cacheHit || ctx.dryRun) {
                         return task.skip();
                     }
-                    const sentinelValue = await ctx.plugin.meta(cmp, ctx.build.prerequisites, 'post');
+                    const sentinelValue = await prereqPlugin.meta(cmp, ctx.build.prerequisites, 'post');
                     await this.context.monorepo.store.writeFile(ctx.sentinelFile, sentinelValue);
                 },
                 title: 'Dumping cache info',
             },
-        ], {
-            rendererOptions: {
-                collapseSubtasks: true,
+            {
+                // Return build meta data
+                async task(ctx) {
+                    parentContext[cmp.name] = ctx;
+                    if (ctx.dryRun) {
+                        // parentTask.skip(`${parentTask.title} (dry run)`);
+                    }
+                },
             },
+        ], {
+            ctx: { dryRun },
         });
+        return list;
     }
 }

package/dist/src/monorepo/operations/components/GetComponentContainerOperation.d.ts

@@ -1,5 +1,5 @@
 import { ContainerInfo } from 'dockerode';
-import { Component } from '../../component.js';
+import { Component } from '../../index.js';
 import { IOperation } from '../../../operations/index.js';
 export declare class GetComponentContainerOperation implements IOperation<Component, ContainerInfo> {
     run(component: Component | string): Promise<ContainerInfo>;

package/dist/src/monorepo/operations/components/GetComponentContainerOperation.js

@@ -1,6 +1,6 @@
 import { getContext } from '../../../index.js';
 import { ListContainersOperation } from '../../../docker/index.js';
-import { Component } from '../../component.js';
+import { Component } from '../../index.js';
 export class GetComponentContainerOperation {
     async run(component) {
         const { monorepo } = getContext();

package/dist/src/monorepo/operations/shell/ExecuteLocalCommandOperation.d.ts

@@ -1,5 +1,4 @@
-import { ResultPromise } from 'execa';
-import { Writable } from 'node:stream';
+import { Readable } from 'node:stream';
 import * as z from 'zod';
 import { AbstractOperation } from '../../../operations/index.js';
 /**
@@ -10,9 +9,8 @@ declare const schema: z.ZodObject<{
     script: z.ZodString;
     workingDir: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export declare class ExecuteLocalCommandOperation extends AbstractOperation<typeof schema, ResultPromise> {
-    protected out?: Writable | undefined;
-    constructor(out?: Writable | undefined);
-    protected _run(input: z.input<typeof schema>): Promise<ResultPromise>;
+export declare class ExecuteLocalCommandOperation extends AbstractOperation<typeof schema, Readable> {
+    constructor();
+    protected _run(input: z.input<typeof schema>): Promise<Readable>;
 }
 export {};

package/dist/src/monorepo/operations/shell/ExecuteLocalCommandOperation.js

@@ -16,10 +16,8 @@ const schema = z.object({
         .describe('The working directory for the exec process inside the container'),
 });
 export class ExecuteLocalCommandOperation extends AbstractOperation {
-    out;
-    constructor(out) {
+    constructor() {
         super(schema);
-        this.out = out;
     }
     async _run(input) {
         const process = execa(input.script, {
@@ -27,9 +25,6 @@ export class ExecuteLocalCommandOperation extends AbstractOperation {
             cwd: input.workingDir,
             shell: true,
         });
-        if (this.out) {
-            process.all?.pipe(this.out);
-        }
-        return process;
+        return process.all;
     }
 }

package/dist/src/monorepo/operations/tasks/RunTasksOperation.d.ts

@@ -0,0 +1,21 @@
+import { Writable } from 'node:stream';
+import { TaskInfo } from '../../index.js';
+import { IOperation } from '../../../operations/index.js';
+export declare enum ExecutorType {
+    container = "container",
+    local = "local"
+}
+export type RunTasksOperationParams = {
+    tasks: Array<string>;
+    executor?: ExecutorType | undefined;
+};
+export type TaskWithScript = TaskInfo & {
+    script: string;
+};
+export declare class RunTasksOperation implements IOperation<RunTasksOperationParams, Array<TaskInfo>> {
+    protected out?: Writable | undefined;
+    constructor(out?: Writable | undefined);
+    run(params: RunTasksOperationParams): Promise<Array<TaskInfo>>;
+    protected runDocker(task: TaskWithScript, out?: Writable): Promise<void>;
+    protected runLocal(task: TaskWithScript): Promise<import("stream").Readable>;
+}

package/dist/src/monorepo/operations/tasks/RunTasksOperation.js

@@ -0,0 +1,84 @@
+import { getContext } from '../../../index.js';
+import { Manager } from '@listr2/manager';
+import { ContainerExecOperation } from '../../../docker/index.js';
+import { EMBCollection, findRunOrder } from '../../index.js';
+import { ExecuteLocalCommandOperation, GetComponentContainerOperation, } from '../index.js';
+export var ExecutorType;
+(function (ExecutorType) {
+    ExecutorType["container"] = "container";
+    ExecutorType["local"] = "local";
+})(ExecutorType || (ExecutorType = {}));
+export class RunTasksOperation {
+    out;
+    constructor(out) {
+        this.out = out;
+    }
+    async run(params) {
+        const { monorepo } = getContext();
+        // First ensure the selection is valid (user can use task IDs or names)
+        const collection = new EMBCollection(monorepo.tasks, {
+            idField: 'id',
+            depField: 'pre',
+        });
+        const ordered = findRunOrder(params.tasks, collection);
+        const runner = new Manager({
+            concurrent: false,
+            exitOnError: false,
+            rendererOptions: {
+                collapseSubtasks: false,
+                collapseSkips: false,
+            },
+        });
+        const list = runner.newListr(ordered.map((task) => {
+            return {
+                rendererOptions: {
+                    persistentOutput: true,
+                },
+                task: async (context, listrTask) => {
+                    if (!task.script) {
+                        return;
+                    }
+                    const executor = params.executor ??
+                        (task.component ? ExecutorType.container : ExecutorType.local);
+                    if (executor === ExecutorType.container && !task.component) {
+                        throw new Error('Cannot use the container executor with global tasks');
+                    }
+                    switch (executor) {
+                        case ExecutorType.container: {
+                            return this.runDocker(task, listrTask.stdout());
+                        }
+                        case ExecutorType.local: {
+                            return this.runLocal(task);
+                        }
+                        default: {
+                            throw new Error(`Unssuported executor type: ${executor}`);
+                        }
+                    }
+                },
+                title: `Running ${task.id}`,
+            };
+        }));
+        await list.run();
+        return ordered;
+    }
+    async runDocker(task, out) {
+        const { monorepo } = getContext();
+        const containerInfo = await monorepo.run(new GetComponentContainerOperation(), task.component);
+        return monorepo.run(new ContainerExecOperation(out), {
+            attachStderr: true,
+            attachStdout: true,
+            container: containerInfo.Id,
+            script: task.script,
+        });
+    }
+    async runLocal(task) {
+        const { monorepo } = getContext();
+        const cwd = task.component
+            ? monorepo.component(task.component).rootdir
+            : monorepo.rootDir;
+        return monorepo.run(new ExecuteLocalCommandOperation(), {
+            script: task.script,
+            workingDir: cwd,
+        });
+    }
+}

package/dist/src/monorepo/operations/tasks/index.d.ts

@@ -1 +1 @@
-export * from './RunTaskOperation.js';
+export * from './RunTasksOperation.js';

package/dist/src/monorepo/operations/tasks/index.js

@@ -1 +1 @@
-export * from './RunTaskOperation.js';
+export * from './RunTasksOperation.js';

package/dist/src/monorepo/plugins/ComponentDiscoverPlugin.js

@@ -25,8 +25,10 @@ export class ComponentDiscoverPlugin extends AbstractPlugin {
             const name = dirname(path);
             const component = config.components.find((cmp) => cmp.name === name);
             const cfg = {
-                context: name,
                 name,
+                docker: {
+                    context: name,
+                },
             };
             return component ? deepmerge()(component, cfg) : cfg;
         });

package/dist/src/monorepo/plugins/EmbfileLoaderPlugin.d.ts

@@ -1,14 +1,14 @@
 import { Monorepo, MonorepoConfig } from '../index.js';
 import { AbstractPlugin } from './plugin.js';
 export type EmbfileLoaderPluginOptions = {
-    glob?: string;
+    glob?: string | string[];
 };
 export declare const EmbfileLoaderPluginDefaultOptions: {
     glob: string;
 };
-export declare class EmbfileLoaderPlugin extends AbstractPlugin<EmbfileLoaderPluginOptions> {
+export declare class EmbfileLoaderPlugin extends AbstractPlugin<Required<EmbfileLoaderPluginOptions>> {
     protected monorepo: Monorepo;
     static name: string;
-    constructor(config: Partial<EmbfileLoaderPluginOptions>, monorepo: Monorepo);
+    constructor(cfg: Partial<EmbfileLoaderPluginOptions>, monorepo: Monorepo);
     extendConfig(config: MonorepoConfig): Promise<MonorepoConfig>;
 }

package/dist/src/monorepo/plugins/EmbfileLoaderPlugin.js

@@ -8,15 +8,19 @@ export const EmbfileLoaderPluginDefaultOptions = {
 export class EmbfileLoaderPlugin extends AbstractPlugin {
     monorepo;
     static name = 'embfiles';
-    constructor(config, monorepo) {
-        super({
+    constructor(cfg, monorepo) {
+        const config = {
             ...EmbfileLoaderPluginDefaultOptions,
-            ...config,
-        }, monorepo);
+            ...cfg,
+        };
+        if (!Array.isArray(config.glob)) {
+            config.glob = [config.glob];
+        }
+        super(config, monorepo);
         this.monorepo = monorepo;
     }
     async extendConfig(config) {
-        const files = await glob(this.config.glob || EmbfileLoaderPluginDefaultOptions.glob, {
+        const files = await glob(this.config.glob, {
             ...this.config,
             cwd: config.project.rootDir,
         });

package/dist/src/monorepo/store/index.js

@@ -10,9 +10,11 @@ import { dirname, join, normalize } from 'node:path';
 export class EMBStore {
     monorepo;
     path;
-    constructor(monorepo, dirname = '.emb') {
+    constructor(monorepo, dirname) {
         this.monorepo = monorepo;
-        this.path = this.monorepo.join(dirname);
+        // By default, we use the flavor name to build that root of the store
+        // so that logs and sentinel files for different flavors are keps separate
+        this.path = this.monorepo.join(dirname || '.emb');
     }
     async createReadStream(path) {
         await this.mkdirp(dirname(path));
@@ -45,7 +47,7 @@ export class EMBStore {
         }
     }
     join(path) {
-        return join(this.path, path);
+        return join(this.path, this.monorepo.currentFlavor, path);
     }
     async mkdirp(path) {
         // Avoid getting out of the store by ensuring nothing goes past ../

package/dist/src/monorepo/taskManagerFactory.d.ts

@@ -0,0 +1,3 @@
+import { Manager } from '@listr2/manager';
+import { ListrBaseClassOptions } from 'listr2';
+export declare function taskManagerFactory<T extends Record<PropertyKey, unknown>>(override?: ListrBaseClassOptions): Manager<T>;

package/dist/src/monorepo/taskManagerFactory.js

@@ -0,0 +1,20 @@
+import { Manager } from '@listr2/manager';
+import { ListrDefaultRendererLogLevels, PRESET_TIMER, } from 'listr2';
+export function taskManagerFactory(override) {
+    return new Manager({
+        collectErrors: 'minimal',
+        concurrent: false,
+        exitOnError: true,
+        rendererOptions: {
+            collapseErrors: false,
+            collapseSubtasks: false,
+            icon: {
+                [ListrDefaultRendererLogLevels.SKIPPED_WITH_COLLAPSE]: '♺',
+            },
+            timer: {
+                ...PRESET_TIMER,
+            },
+        },
+        ...override,
+    });
+}

package/dist/src/monorepo/types.d.ts

@@ -3,5 +3,6 @@ export type TaskInfo = {
     description?: string;
     id: string;
     name: string;
-    script: string;
+    script?: string;
+    pre?: Array<string>;
 };

package/dist/src/monorepo/utils/findRunOrder.d.ts

@@ -0,0 +1,34 @@
+type DepList = readonly string[] | string[] | undefined;
+type CollectionConfig<IDK extends PropertyKey, DPK extends PropertyKey> = {
+    idField: IDK;
+    depField: DPK;
+    /** If true, throw when an item's id equals some other item's name (or vice versa). */
+    forbidIdNameCollision?: boolean;
+};
+type AmbiguityPolicy = 'error' | 'runAll';
+export declare class EMBCollection<T extends Partial<Record<DPK, DepList>> & Record<IDK, string> & {
+    name: string;
+}, IDK extends keyof T, DPK extends keyof T> {
+    private items;
+    readonly idField: IDK;
+    readonly depField: DPK;
+    private byId;
+    private byName;
+    constructor(items: Iterable<T>, cfg: CollectionConfig<IDK, DPK>);
+    /** All items (stable array iteration) */
+    get all(): Iterable<T>;
+    idOf(t: T): string;
+    depsOf(t: T): readonly string[];
+    matches(ref: string, opts?: {
+        multiple?: false;
+    }): T;
+    matches(ref: string, opts: {
+        multiple: true;
+    }): T[];
+}
+export declare function findRunOrder<T extends Partial<Record<DPK, DepList>> & Record<IDK, string> & {
+    name: string;
+}, IDK extends keyof T, DPK extends keyof T>(selection: readonly string[], collection: EMBCollection<T, IDK, DPK>, { onAmbiguous }?: {
+    onAmbiguous?: AmbiguityPolicy | undefined;
+}): T[];
+export {};

package/dist/src/monorepo/utils/findRunOrder.js

@@ -0,0 +1,165 @@
+import graphlib from 'graphlib';
+export class EMBCollection {
+    items;
+    idField;
+    depField;
+    byId;
+    byName;
+    constructor(items, cfg) {
+        this.items = [];
+        this.idField = cfg.idField;
+        this.depField = cfg.depField;
+        this.byId = new Map();
+        this.byName = new Map();
+        // single-pass validation state
+        const seenIds = new Set();
+        const seenNames = new Set();
+        const dupIdReports = [];
+        const collisions = [];
+        for (const t of items) {
+            const id = t[this.idField];
+            const { name } = t;
+            // duplicate id?
+            if (seenIds.has(id)) {
+                const firstOwner = this.byId.get(id); // first occurrence already stored
+                dupIdReports.push(`id "${id}" used by "${firstOwner.name}" and "${name}"`);
+                // keep the first owner in byId; do not overwrite
+            }
+            else {
+                this.byId.set(id, t);
+                seenIds.add(id);
+            }
+            // --- Optional validation: forbid id <-> name collisions ---
+            const checkCollisions = cfg.forbidIdNameCollision && this.idField !== 'name';
+            if (checkCollisions) {
+                if (seenNames.has(id)) {
+                    const nameOwners = this.byName.get(id) ?? [];
+                    const ownerIds = nameOwners.map((o) => o[this.idField]).join(', ');
+                    collisions.push(`value "${id}" is an id of "${name}" and also a name of item(s) with id(s): [${ownerIds}]`);
+                }
+                if (seenIds.has(name)) {
+                    const idOwner = this.byId.get(name);
+                    collisions.push(`value "${name}" is a name of "${t.name}" and also an id of "${idOwner.name}"`);
+                }
+            }
+            // byName index
+            const list = this.byName.get(name);
+            if (list)
+                list.push(t);
+            else
+                this.byName.set(name, [t]);
+            // keep item list (stable order)
+            this.items.push(t);
+            // record name after checks so current name won’t collide with itself
+            seenNames.add(name);
+        }
+        if (dupIdReports.length > 0 || collisions.length > 0) {
+            const parts = [];
+            if (dupIdReports.length > 0) {
+                parts.push(`Duplicate ${String(this.idField)} values (${dupIdReports.length}):\n` +
+                    dupIdReports.join('\n'));
+            }
+            if (collisions.length > 0) {
+                parts.push(`id↔name collisions (${collisions.length}):\n` +
+                    collisions.join('\n'));
+            }
+            // eslint-disable-next-line unicorn/error-message
+            throw new Error(parts.join('\n\n'));
+        }
+    }
+    /** All items (stable array iteration) */
+    get all() {
+        return this.items;
+    }
+    idOf(t) {
+        return t[this.idField];
+    }
+    depsOf(t) {
+        return (t[this.depField] ?? []);
+    }
+    matches(ref, opts) {
+        const idHit = this.byId.get(ref);
+        if (idHit)
+            return opts?.multiple ? [idHit] : idHit;
+        const nameHits = this.byName.get(ref) ?? [];
+        if (nameHits.length === 0) {
+            throw new Error(`Unknown reference "${ref}"`);
+        }
+        if (opts?.multiple)
+            return nameHits;
+        if (nameHits.length > 1) {
+            const ids = nameHits.map((t) => this.idOf(t)).join(', ');
+            throw new Error(`Ambiguous reference "${ref}" matches multiple ids: [${ids}]`);
+        }
+        return nameHits[0];
+    }
+}
+/* ----------------- run-order helpers unchanged (for completeness) ---------------- */
+function resolveRefSet(col, ref, policy) {
+    if (policy === 'runAll')
+        return col.matches(ref, { multiple: true }).map((t) => col.idOf(t));
+    return [col.idOf(col.matches(ref))];
+}
+function collectPredecessorClosure(g, seeds) {
+    const seen = new Set();
+    const q = [];
+    for (const s of seeds) {
+        if (!seen.has(s)) {
+            seen.add(s);
+            q.push(s);
+        }
+    }
+    while (q.length > 0) {
+        const cur = q.shift();
+        for (const p of g.predecessors(cur) ?? [])
+            if (!seen.has(p)) {
+                seen.add(p);
+                q.push(p);
+            }
+    }
+    return seen;
+}
+function buildGraph(col, policy) {
+    const g = new graphlib.Graph({ directed: true });
+    for (const t of col.all)
+        g.setNode(col.idOf(t));
+    for (const t of col.all) {
+        const toId = col.idOf(t);
+        for (const ref of col.depsOf(t)) {
+            for (const fromId of resolveRefSet(col, ref, policy))
+                g.setEdge(fromId, toId);
+        }
+    }
+    return g;
+}
+export function findRunOrder(selection, collection, { onAmbiguous = 'error' } = {}) {
+    const g = buildGraph(collection, onAmbiguous);
+    const cycles = graphlib.alg.findCycles(g);
+    if (cycles.length > 0) {
+        throw new Error(`Circular dependencies detected: ${JSON.stringify(cycles)}`);
+    }
+    const selectedIds = new Set();
+    for (const ref of selection)
+        for (const id of resolveRefSet(collection, ref, onAmbiguous))
+            selectedIds.add(id);
+    if (selectedIds.size === 0)
+        throw new Error('Selection resolved to no items.');
+    const include = collectPredecessorClosure(g, selectedIds.values());
+    const sub = new graphlib.Graph({ directed: true });
+    for (const id of include)
+        sub.setNode(id);
+    for (const id of include)
+        for (const p of g.predecessors(id) ?? [])
+            if (include.has(p))
+                sub.setEdge(p, id);
+    const ids = graphlib.alg.topsort(sub);
+    const byId = new Map();
+    for (const t of collection.all)
+        byId.set(collection.idOf(t), t);
+    return ids.map((id) => {
+        const t = byId.get(id);
+        if (!t)
+            throw new Error(`Internal error: missing item for id "${id}"`);
+        return t;
+    });
+}