@celilo/cli 0.1.5 → 0.1.6

package/src/services/update/dep-graph.test.ts

@@ -0,0 +1,214 @@
+import { describe, expect, test } from 'bun:test';
+import type { ModuleManifest } from '../../manifest/schema';
+import {
+  DependencyCycleError,
+  buildModuleGraph,
+  levelsOf,
+  topologicalOrder,
+  transitiveConsumers,
+} from './dep-graph';
+
+function makeManifest(
+  id: string,
+  opts: {
+    provides?: string[];
+    requires?: string[];
+    optional?: string[];
+  } = {},
+): ModuleManifest {
+  return {
+    id,
+    name: id,
+    version: '1.0.0',
+    celilo_contract: '1.0',
+    provides: opts.provides
+      ? {
+          capabilities: opts.provides.map((name) => ({
+            name,
+            version: '1.0.0',
+            data: {},
+            functions: [],
+          })),
+        }
+      : { capabilities: [] },
+    requires: opts.requires
+      ? { capabilities: opts.requires.map((name) => ({ name, version: '1.0.0' })) }
+      : { capabilities: [] },
+    optional: opts.optional
+      ? { capabilities: opts.optional.map((name) => ({ name, version: '1.0.0' })) }
+      : undefined,
+  } as unknown as ModuleManifest;
+}
+
+describe('buildModuleGraph', () => {
+  test('empty input → empty graph', () => {
+    const g = buildModuleGraph([]);
+    expect(g.nodes.size).toBe(0);
+    expect(g.edges.size).toBe(0);
+  });
+
+  test('module with no deps → node with no edges', () => {
+    const g = buildModuleGraph([makeManifest('iptables', { provides: ['firewall'] })]);
+    expect(g.nodes.size).toBe(1);
+    expect(g.edges.get('iptables')?.size).toBe(0);
+  });
+
+  test('builds consumer → provider edge', () => {
+    const g = buildModuleGraph([
+      makeManifest('iptables', { provides: ['firewall'] }),
+      makeManifest('caddy', { requires: ['firewall'] }),
+    ]);
+    expect([...(g.edges.get('caddy') ?? [])]).toEqual(['iptables']);
+    expect([...(g.reverseEdges.get('iptables') ?? [])]).toEqual(['caddy']);
+  });
+
+  test('optional capabilities also create edges', () => {
+    const g = buildModuleGraph([
+      makeManifest('namecheap', { provides: ['dns_registrar'] }),
+      makeManifest('caddy', { optional: ['dns_registrar'] }),
+    ]);
+    expect([...(g.edges.get('caddy') ?? [])]).toEqual(['namecheap']);
+  });
+
+  test('skips edges to missing providers (no provider for declared capability)', () => {
+    const g = buildModuleGraph([makeManifest('caddy', { requires: ['nonexistent'] })]);
+    expect(g.edges.get('caddy')?.size).toBe(0);
+  });
+
+  test('skips self-edges when a module consumes its own capability', () => {
+    const g = buildModuleGraph([makeManifest('weird', { provides: ['x'], requires: ['x'] })]);
+    expect(g.edges.get('weird')?.size).toBe(0);
+  });
+
+  test('first declared provider wins when multiple modules provide the same capability', () => {
+    const g = buildModuleGraph([
+      makeManifest('a', { provides: ['firewall'] }),
+      makeManifest('b', { provides: ['firewall'] }),
+      makeManifest('caddy', { requires: ['firewall'] }),
+    ]);
+    expect([...(g.edges.get('caddy') ?? [])]).toEqual(['a']);
+  });
+});
+
+describe('topologicalOrder', () => {
+  test('empty graph yields empty list', () => {
+    expect(topologicalOrder(buildModuleGraph([]))).toEqual([]);
+  });
+
+  test('places provider before consumer', () => {
+    const g = buildModuleGraph([
+      makeManifest('caddy', { requires: ['firewall'] }),
+      makeManifest('iptables', { provides: ['firewall'] }),
+    ]);
+    const order = topologicalOrder(g);
+    expect(order.indexOf('iptables')).toBeLessThan(order.indexOf('caddy'));
+  });
+
+  test('respects multi-level chain', () => {
+    const g = buildModuleGraph([
+      makeManifest('namecheap', { provides: ['dns_registrar'] }),
+      makeManifest('caddy', { requires: ['firewall', 'dns_registrar'], provides: ['public_web'] }),
+      makeManifest('iptables', { provides: ['firewall'] }),
+      makeManifest('lunacycle', { requires: ['public_web'] }),
+    ]);
+    const order = topologicalOrder(g);
+    expect(order.indexOf('iptables')).toBeLessThan(order.indexOf('caddy'));
+    expect(order.indexOf('namecheap')).toBeLessThan(order.indexOf('caddy'));
+    expect(order.indexOf('caddy')).toBeLessThan(order.indexOf('lunacycle'));
+  });
+
+  test('alphabetical tiebreak among siblings', () => {
+    const g = buildModuleGraph([
+      makeManifest('zebra'),
+      makeManifest('alpha'),
+      makeManifest('mango'),
+    ]);
+    expect(topologicalOrder(g)).toEqual(['alpha', 'mango', 'zebra']);
+  });
+
+  test('throws DependencyCycleError on a 2-cycle', () => {
+    const g = buildModuleGraph([
+      makeManifest('a', { provides: ['cap_a'], requires: ['cap_b'] }),
+      makeManifest('b', { provides: ['cap_b'], requires: ['cap_a'] }),
+    ]);
+    expect(() => topologicalOrder(g)).toThrow(DependencyCycleError);
+  });
+
+  test('cycle error contains the cycle path', () => {
+    const g = buildModuleGraph([
+      makeManifest('a', { provides: ['cap_a'], requires: ['cap_b'] }),
+      makeManifest('b', { provides: ['cap_b'], requires: ['cap_a'] }),
+    ]);
+    try {
+      topologicalOrder(g);
+      throw new Error('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(DependencyCycleError);
+      expect((err as DependencyCycleError).cycle.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('transitiveConsumers', () => {
+  test('returns all downstream modules', () => {
+    const g = buildModuleGraph([
+      makeManifest('iptables', { provides: ['firewall'] }),
+      makeManifest('caddy', { requires: ['firewall'], provides: ['public_web'] }),
+      makeManifest('lunacycle', { requires: ['public_web'] }),
+      makeManifest('celilo-website', { requires: ['public_web'] }),
+    ]);
+
+    expect(transitiveConsumers(g, 'iptables').sort()).toEqual([
+      'caddy',
+      'celilo-website',
+      'lunacycle',
+    ]);
+    expect(transitiveConsumers(g, 'caddy').sort()).toEqual(['celilo-website', 'lunacycle']);
+    expect(transitiveConsumers(g, 'lunacycle')).toEqual([]);
+  });
+
+  test('returns empty for a module with no consumers', () => {
+    const g = buildModuleGraph([makeManifest('iptables', { provides: ['firewall'] })]);
+    expect(transitiveConsumers(g, 'iptables')).toEqual([]);
+  });
+
+  test('returns empty for a module not in the graph', () => {
+    const g = buildModuleGraph([makeManifest('iptables', { provides: ['firewall'] })]);
+    expect(transitiveConsumers(g, 'nonexistent')).toEqual([]);
+  });
+});
+
+describe('levelsOf', () => {
+  test('flat dependency tree → all level 0', () => {
+    const g = buildModuleGraph([makeManifest('a'), makeManifest('b'), makeManifest('c')]);
+    const levels = levelsOf(g);
+    expect(levels[0].sort()).toEqual(['a', 'b', 'c']);
+    expect(levels.length).toBe(1);
+  });
+
+  test('linear chain assigns level per depth', () => {
+    const g = buildModuleGraph([
+      makeManifest('iptables', { provides: ['firewall'] }),
+      makeManifest('caddy', { requires: ['firewall'], provides: ['public_web'] }),
+      makeManifest('lunacycle', { requires: ['public_web'] }),
+    ]);
+    const levels = levelsOf(g);
+    expect(levels[0]).toEqual(['iptables']);
+    expect(levels[1]).toEqual(['caddy']);
+    expect(levels[2]).toEqual(['lunacycle']);
+  });
+
+  test('module depending on multiple providers gets max(deps)+1', () => {
+    const g = buildModuleGraph([
+      makeManifest('iptables', { provides: ['firewall'] }),
+      makeManifest('namecheap', { provides: ['dns_registrar'] }),
+      makeManifest('caddy', { requires: ['firewall'], provides: ['public_web'] }),
+      makeManifest('mixed', { requires: ['public_web', 'dns_registrar'] }),
+    ]);
+    const levels = levelsOf(g);
+    // iptables, namecheap → 0; caddy → 1; mixed → 2 (max of caddy:1, namecheap:0)
+    expect(levels[0].sort()).toEqual(['iptables', 'namecheap']);
+    expect(levels[1]).toEqual(['caddy']);
+    expect(levels[2]).toEqual(['mixed']);
+  });
+});

package/src/services/update/dep-graph.ts

@@ -0,0 +1,215 @@
+/**
+ * Module dependency graph.
+ *
+ * Builds a directed graph from a set of module manifests where an edge
+ * `consumer → provider` exists iff the consumer's `requires` or
+ * `optional` capabilities list a name that the provider declares in
+ * `provides`. The graph is used by both `system audit` (to render the
+ * dependency tree) and `system update` (to walk in topological order
+ * so providers upgrade before consumers).
+ *
+ * Pure data structures and pure operations — no I/O, no logging.
+ * Used by tests directly.
+ */
+
+import type { ModuleManifest } from '../../manifest/schema';
+
+/**
+ * The id used to identify a module in the graph. Always equals
+ * `manifest.id` so callers don't need a separate keyspace.
+ */
+export type ModuleId = string;
+
+export interface ModuleNode {
+  id: ModuleId;
+  manifest: ModuleManifest;
+  /**
+   * Capability names this module provides (the keys in
+   * `manifest.provides.capabilities[].name`). Cached for graph
+   * construction.
+   */
+  provides: string[];
+  /**
+   * Required + optional capability names. Optional reqs participate
+   * in the graph the same way required ones do — they shape the
+   * upgrade order — but they don't block deploy if absent.
+   */
+  consumes: string[];
+}
+
+export interface ModuleGraph {
+  nodes: Map<ModuleId, ModuleNode>;
+  /** consumer → providers it depends on */
+  edges: Map<ModuleId, Set<ModuleId>>;
+  /** provider → consumers that depend on it (reverse index) */
+  reverseEdges: Map<ModuleId, Set<ModuleId>>;
+}
+
+/** Internal: build an index of capability name → providing module id. */
+function indexProviders(modules: ModuleNode[]): Map<string, ModuleId> {
+  const index = new Map<string, ModuleId>();
+  for (const m of modules) {
+    for (const cap of m.provides) {
+      // First provider wins. The capability-loader's chain logic handles
+      // multi-provider scenarios at deploy time; for graph-walking
+      // purposes one edge per capability is enough.
+      if (!index.has(cap)) index.set(cap, m.id);
+    }
+  }
+  return index;
+}
+
+export function buildModuleGraph(manifests: ModuleManifest[]): ModuleGraph {
+  const nodes = new Map<ModuleId, ModuleNode>();
+  for (const m of manifests) {
+    const provides = (m.provides?.capabilities ?? []).map((c) => c.name);
+    const required = (m.requires?.capabilities ?? []).map((c) => c.name);
+    const optional = (m.optional?.capabilities ?? []).map((c) => c.name);
+    nodes.set(m.id, {
+      id: m.id,
+      manifest: m,
+      provides,
+      consumes: [...required, ...optional],
+    });
+  }
+
+  const providerIndex = indexProviders([...nodes.values()]);
+  const edges = new Map<ModuleId, Set<ModuleId>>();
+  const reverseEdges = new Map<ModuleId, Set<ModuleId>>();
+
+  for (const node of nodes.values()) {
+    edges.set(node.id, new Set());
+    reverseEdges.set(node.id, reverseEdges.get(node.id) ?? new Set());
+
+    for (const cap of node.consumes) {
+      const providerId = providerIndex.get(cap);
+      // Skip self-edges (a module that consumes its own capability —
+      // unusual but legal) and missing providers (deploy preflight
+      // handles those; graph just routes around them).
+      if (!providerId || providerId === node.id) continue;
+
+      edges.get(node.id)?.add(providerId);
+      const rev = reverseEdges.get(providerId) ?? new Set();
+      rev.add(node.id);
+      reverseEdges.set(providerId, rev);
+    }
+  }
+
+  return { nodes, edges, reverseEdges };
+}
+
+export class DependencyCycleError extends Error {
+  readonly cycle: readonly ModuleId[];
+  constructor(cycle: readonly ModuleId[]) {
+    super(`Dependency cycle detected: ${cycle.join(' → ')} → ${cycle[0]}`);
+    this.name = 'DependencyCycleError';
+    this.cycle = cycle;
+  }
+}
+
+/**
+ * Return module ids in dependency-safe order: every provider precedes
+ * every consumer. Throws `DependencyCycleError` if the graph contains
+ * a cycle (manifest declares mutual dependency, which is a bug in
+ * the manifests).
+ *
+ * Tie-breaks alphabetically so the order is deterministic across runs.
+ */
+export function topologicalOrder(graph: ModuleGraph): ModuleId[] {
+  const order: ModuleId[] = [];
+  const visited = new Set<ModuleId>();
+  const visiting = new Set<ModuleId>();
+
+  function visit(id: ModuleId, path: ModuleId[]): void {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) {
+      const cycleStart = path.indexOf(id);
+      throw new DependencyCycleError(path.slice(cycleStart));
+    }
+    visiting.add(id);
+
+    // Visit providers first (deterministic order).
+    const providers = [...(graph.edges.get(id) ?? [])].sort();
+    for (const dep of providers) {
+      visit(dep, [...path, id]);
+    }
+
+    visiting.delete(id);
+    visited.add(id);
+    order.push(id);
+  }
+
+  // Iterate in alphabetical order so callers without explicit deps
+  // get a stable order.
+  const ids = [...graph.nodes.keys()].sort();
+  for (const id of ids) {
+    visit(id, []);
+  }
+
+  return order;
+}
+
+/**
+ * Return all consumers (transitively) of `moduleId`. Used during update
+ * to find the subtree that should be skipped when a provider's upgrade
+ * fails (subject to the version-aware short-circuit in D3).
+ */
+export function transitiveConsumers(graph: ModuleGraph, moduleId: ModuleId): ModuleId[] {
+  const result: ModuleId[] = [];
+  const seen = new Set<ModuleId>([moduleId]);
+  const stack = [...(graph.reverseEdges.get(moduleId) ?? [])];
+
+  while (stack.length > 0) {
+    const next = stack.pop();
+    if (next === undefined || seen.has(next)) continue;
+    seen.add(next);
+    result.push(next);
+    const consumers = graph.reverseEdges.get(next);
+    if (consumers) stack.push(...consumers);
+  }
+
+  return result.sort();
+}
+
+/**
+ * Group nodes into "levels" where level 0 has no dependencies inside
+ * the graph, level 1 depends only on level 0, etc. Useful for
+ * rendering the audit / dry-run output as an indented tree.
+ */
+export function levelsOf(graph: ModuleGraph): ModuleId[][] {
+  const levelByModule = new Map<ModuleId, number>();
+
+  function levelOf(id: ModuleId, path: Set<ModuleId>): number {
+    const cached = levelByModule.get(id);
+    if (cached !== undefined) return cached;
+    if (path.has(id)) {
+      // Cycle — return 0 so the topological-order check surfaces a clearer error.
+      return 0;
+    }
+    const deps = graph.edges.get(id);
+    if (!deps || deps.size === 0) {
+      levelByModule.set(id, 0);
+      return 0;
+    }
+    const next = new Set(path);
+    next.add(id);
+    let max = 0;
+    for (const d of deps) {
+      max = Math.max(max, levelOf(d, next) + 1);
+    }
+    levelByModule.set(id, max);
+    return max;
+  }
+
+  for (const id of graph.nodes.keys()) {
+    levelOf(id, new Set());
+  }
+
+  const levels: ModuleId[][] = [];
+  for (const [id, lvl] of levelByModule) {
+    while (levels.length <= lvl) levels.push([]);
+    levels[lvl].push(id);
+  }
+  for (const lvl of levels) lvl.sort();
+  return levels;
+}