@synap-core/workspace-templates 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synap-core/workspace-templates",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "packageManager": "pnpm@9.15.4",
   "description": "Canonical workspace definitions — YAML source + typed exports for browser, backend, CLI, and marketplace",

package/src/composition-graph.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Unit tests for the `layerTemplateGraph` KEYSTONE engine.
+ * Run: `npx tsx --test src/composition-graph.test.ts`
+ *
+ * These test the SOURCE (`./composition-graph.js` → composition-graph.ts),
+ * never `dist/`, so no build is required and there is no stale-generated-
+ * output trap (same convention as `catalog.test.ts`).
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { layerTemplateGraph, type CompositionGraph } from "./composition-graph.js";
+import type { TemplateDependency } from "./types.js";
+
+/** Build a small `edgesOf` from a plain adjacency map, for test fixtures. */
+function edgesFrom(map: Record<string, TemplateDependency[]>) {
+  return (slug: string): readonly TemplateDependency[] => map[slug] ?? [];
+}
+
+function flat(graph: CompositionGraph): string[] {
+  return graph.layers.flat().map((n) => n.slug);
+}
+
+// ── Longest-path: deeper occurrence wins (bedrock behavior) ────────────────
+test("longest-path: a node required at depth 1 by one root and depth 3 by another lands at the deeper layer", () => {
+  // root-a -> shared (depth 1)
+  // root-b -> mid -> deep -> shared (depth 3)
+  const edgesOf = edgesFrom({
+    "root-a": [{ slug: "shared" }],
+    "root-b": [{ slug: "mid" }],
+    mid: [{ slug: "deep" }],
+    deep: [{ slug: "shared" }],
+  });
+
+  const graph = layerTemplateGraph({ roots: ["root-a", "root-b"], edgesOf });
+  const shared = graph.nodes.get("shared")!;
+  assert.equal(shared.layer, 3, "shared must sink to the DEEPER of its two reachable depths");
+});
+
+// ── Dedupe / fan-in ──────────────────────────────────────────────────────────
+test("dedupe/fan-in: a node reachable from 6 parents appears ONCE with dependents.length === 6", () => {
+  const parents = Array.from({ length: 6 }, (_, i) => `parent-${i}`);
+  const edgesOf = edgesFrom({
+    root: parents.map((p) => ({ slug: p })),
+    ...Object.fromEntries(parents.map((p) => [p, [{ slug: "foundation" }]])),
+  });
+
+  const graph = layerTemplateGraph({ roots: ["root"], edgesOf });
+  const foundationNodes = [...graph.nodes.values()].filter((n) => n.slug === "foundation");
+  assert.equal(foundationNodes.length, 1, "foundation must appear exactly once in the node map");
+  assert.equal(foundationNodes[0]!.dependents.length, 6, "foundation must carry TRUE fan-in from all 6 parents");
+});
+
+// ── Multi-root ───────────────────────────────────────────────────────────────
+test("multi-root: two roots both reaching a shared node → roots lists both", () => {
+  const edgesOf = edgesFrom({
+    "root-a": [{ slug: "shared" }],
+    "root-b": [{ slug: "shared" }],
+  });
+
+  const graph = layerTemplateGraph({ roots: ["root-a", "root-b"], edgesOf });
+  const shared = graph.nodes.get("shared")!;
+  assert.deepEqual(shared.roots, ["root-a", "root-b"]);
+});
+
+// ── Compose overlays ─────────────────────────────────────────────────────────
+test("compose: a relation:compose dep appears in the base's overlays[] and NOT in layers", () => {
+  // `grants` composes onto `operations` — mirrors the real grants.yaml/operations.yaml pair.
+  const edgesOf = edgesFrom({
+    grants: [{ slug: "operations", relation: "compose", reason: "overlay" }],
+  });
+
+  const graph = layerTemplateGraph({ roots: ["grants"], edgesOf });
+
+  const operations = graph.nodes.get("operations")!;
+  assert.ok(operations, "operations (the base) must be a real node");
+  assert.deepEqual(
+    operations.overlays.map((o) => o.slug),
+    ["grants"],
+    "the compose source must be attached as an overlay on the base"
+  );
+
+  assert.equal(graph.nodes.has("grants"), false, "the compose SOURCE must never be its own node");
+  assert.ok(!flat(graph).includes("grants"), "the compose source must never appear in layers[][]");
+
+  const composeEdge = graph.edges.find((e) => e.from === "grants" && e.to === "operations");
+  assert.ok(composeEdge, "the compose edge must still be recorded in edges[]");
+  assert.equal(composeEdge!.relation, "compose");
+});
+
+// ── Ghost nodes ──────────────────────────────────────────────────────────────
+test("ghost: an uninstalled dep is present with installed:false", () => {
+  const edgesOf = edgesFrom({
+    root: [{ slug: "not-installed-yet" }],
+  });
+
+  const graph = layerTemplateGraph({ roots: ["root"], edgesOf, installed: [] });
+  const ghost = graph.nodes.get("not-installed-yet")!;
+  assert.equal(ghost.installed, false);
+  assert.deepEqual(ghost.workspaceIds, []);
+  // The gap IS the information: it still occupies its layer.
+  assert.equal(graph.layers[ghost.layer]!.some((n) => n.slug === "not-installed-yet"), true);
+});
+
+// ── Cycles ───────────────────────────────────────────────────────────────────
+test("cycle: A→B→A terminates and reports the broken edge in cycles[]", () => {
+  const edgesOf = edgesFrom({
+    A: [{ slug: "B" }],
+    B: [{ slug: "A" }],
+  });
+
+  const graph = layerTemplateGraph({ roots: ["A"], edgesOf });
+
+  assert.equal(graph.cycles.length, 1);
+  assert.deepEqual(graph.cycles[0], ["B", "A"]);
+
+  // Still terminates and produces a usable graph.
+  assert.ok(graph.nodes.has("A"));
+  assert.ok(graph.nodes.has("B"));
+  assert.equal(graph.nodes.get("A")!.layer, 0);
+});
+
+// ── edgesOf injection ─────────────────────────────────────────────────────────
+test("edgesOf injection: deps supplied for a slug NOT in the bundled map are still walked", () => {
+  // "private-remote-pkg" does not exist in the bundled WORKSPACE_TEMPLATES map
+  // at all — this is the live bug rule 5 fixes: a caller-supplied edgesOf must
+  // still be able to walk it.
+  const edgesOf = edgesFrom({
+    "private-remote-pkg": [{ slug: "some-base", relation: "require" }],
+  });
+
+  const graph = layerTemplateGraph({ roots: ["private-remote-pkg"], edgesOf });
+  assert.ok(graph.nodes.has("some-base"), "a dependency declared only by the injected edgesOf must still be walked");
+  assert.equal(graph.nodes.get("some-base")!.layer, 1);
+});

package/src/composition-graph.ts

@@ -0,0 +1,298 @@
+/**
+ * layerTemplateGraph — the KEYSTONE composition-graph engine.
+ * ============================================================
+ *
+ * Today the CLI (`synap-cli/src/commands/market.ts` `buildCompositionTrees`)
+ * renders template composition as a nested TREE: `buildDependencyNode`
+ * rebuilds a fresh `TreeNode` for every OCCURRENCE of a slug on every path, so
+ * a widely-required base (e.g. `foundation`) prints once per branch that
+ * reaches it (6× under a suite like `enterprise-os`). Its "shared" tag is only
+ * top-level-package granularity — there is no true fan-in count.
+ *
+ * This module replaces that with a LAYERED DAG: every node appears EXACTLY
+ * ONCE, positioned at its longest-path depth, with edges converging on it —
+ * so `foundation` sinks to the bedrock row with N inbound edges instead of
+ * being redrawn N times. It is the single source of truth for template
+ * composition; the CLI, browser dialogs, backend boot-ordering, and (later)
+ * the Atlas all consume it.
+ *
+ * PURE + TRANSPORT-AGNOSTIC (same discipline as `catalog.ts`): this is the
+ * ONLY module `synap-cli`, `browser`, `synap-control-plane-api`, and
+ * `synap-backend` can all resolve. No React, no dagre/d3, no fetch, no
+ * Node-only APIs. Pixel layout lives elsewhere (browser-only) — this module
+ * only computes topology (layers + edges + memoized nodes), never coordinates.
+ *
+ * CONSUMES drift, never recomputes it: `installed` / `updates` are read
+ * straight off `catalog.ts`'s `InstalledTemplate`-shaped rows and
+ * `computeTemplateUpdates()` output — this module does no semver comparison
+ * of its own.
+ */
+
+import type { TemplateDependency } from "./types.js";
+import { getWorkspaceTemplate } from "./templates.js";
+import type { TemplateUpdateCheck } from "./catalog.js";
+
+// ============================================================================
+// Inputs
+// ============================================================================
+
+/**
+ * An installed template row, keyed by slug — the shape this engine needs to
+ * mark a node `installed` and populate `workspaceIds`.
+ *
+ * NOTE ON NAMING: `catalog.ts`'s `InstalledTemplate` is `{ slug, version }`
+ * only — it was built for `computeTemplateUpdates`'s narrower need (a version
+ * to diff) and carries no `workspaceId`. `CompositionNode.workspaceIds` is
+ * part of the ratified API and cannot be populated from that shape, so this
+ * is a REAL conflict, not a preference: this module declares its own,
+ * slightly richer row instead of importing `catalog.ts`'s `InstalledTemplate`
+ * under that name. Every field of `catalog.ts`'s `InstalledTemplate` is a
+ * subset of this one, so a caller building `InstalledTemplate[]` for
+ * `computeTemplateUpdates` can build ONE array of `CompositionInstalledEntry`
+ * and pass it to both doors.
+ */
+export interface CompositionInstalledEntry {
+  slug: string;
+  workspaceId: string;
+  workspaceName?: string;
+  /** `settings.packageVersion`, when the pod stamped one. Omit when unknown. */
+  version?: string;
+}
+
+/** One compose-relation dependency, attached to the BASE node it overlays onto. */
+export interface CompositionOverlay {
+  slug: string;
+  name: string;
+  installed: boolean;
+}
+
+/** One edge in the raw dependency graph, exactly as declared (kept even when broken by a cycle). */
+export interface CompositionEdge {
+  from: string;
+  to: string;
+  relation: "compose" | "require";
+  depKind?: string;
+}
+
+export interface CompositionNode {
+  slug: string;
+  name: string;
+  /** Longest-path depth: `1 + max(layer of every node that depends on this one)`. Roots = 0, bedrock = max. */
+  layer: number;
+  /** TRUE fan-in — every slug (node or compose-only overlay source) that declares a dependency on this one. */
+  dependents: string[];
+  /** Which of the input `roots` transitively reach this node (self-inclusive for a root). */
+  roots: string[];
+  installed: boolean;
+  workspaceIds: string[];
+  installedVersion?: string;
+  latestVersion?: string | null;
+  updateAvailable: boolean;
+  noVersionInfo: boolean;
+  /** `compose`-relation deps that overlay onto THIS node (see rule 2 — the overlay source itself is never a layer node). */
+  overlays: CompositionOverlay[];
+}
+
+export interface CompositionGraph {
+  nodes: Map<string, CompositionNode>;
+  edges: CompositionEdge[];
+  /** `layers[0]` = roots … `layers[n]` = bedrock. Compose-overlay SOURCES never appear here (rule 2). */
+  layers: CompositionNode[][];
+  /** Broken back-edges `[from, to]` — surfaced, never silently swallowed (rule 4). */
+  cycles: string[][];
+}
+
+export interface LayerTemplateGraphInput {
+  /** Top-level slugs to walk from. Always land at `layer: 0`. */
+  roots: string[];
+  /** INJECTED edge source (rule 5) — never hardcoded to the bundled map. See `bundledEdgesOf`. */
+  edgesOf: (slug: string) => readonly TemplateDependency[];
+  nameOf?: (slug: string) => string | undefined;
+  installed?: CompositionInstalledEntry[];
+  updates?: TemplateUpdateCheck[];
+}
+
+/**
+ * Default `edgesOf` — reads `dependencies[]` off the BUNDLED template map
+ * only. This is what the current CLI walker is hardcoded to, which is
+ * precisely the live bug rule 5 fixes: a remote/private CP-only package's
+ * `definition.dependencies` are invisible to it, so its subtree silently
+ * renders empty. Callers with a remote catalog entry available should pass
+ * their OWN `edgesOf` that falls back to `entry.remote.definition.dependencies`
+ * (or similar) for slugs this default can't see.
+ */
+export function bundledEdgesOf(slug: string): readonly TemplateDependency[] {
+  return getWorkspaceTemplate(slug)?.dependencies ?? [];
+}
+
+// ============================================================================
+// The engine
+// ============================================================================
+
+export function layerTemplateGraph(input: LayerTemplateGraphInput): CompositionGraph {
+  const { roots, edgesOf } = input;
+  const nameOf = input.nameOf ?? (() => undefined);
+  const rootSet = new Set(roots);
+
+  const installedBySlug = new Map<string, CompositionInstalledEntry[]>();
+  for (const entry of input.installed ?? []) {
+    const list = installedBySlug.get(entry.slug);
+    if (list) list.push(entry);
+    else installedBySlug.set(entry.slug, [entry]);
+  }
+  const updatesBySlug = new Map((input.updates ?? []).map((u) => [u.slug, u]));
+
+  // ── Phase 1: discovery — walk every root, global memo (rule 1) ───────────
+  const edges: CompositionEdge[] = [];
+  const cycles: string[][] = [];
+  /** Every edge target/source touched, whether or not it ends up a layer node. */
+  const touched = new Set<string>(roots);
+  /** dependent -> Set(dependency) for EVERY edge (both relations) — reachability adjacency. */
+  const adjacency = new Map<string, Set<string>>();
+  /** dependency -> Set(dependent) for every NON-broken edge (both relations) — true fan-in + layering DP. */
+  const dependentsMap = new Map<string, Set<string>>();
+  /** Compose-relation edges, kept separately to build overlays + the node-exclusion set. */
+  const composeEdges: Array<{ from: string; to: string; depKind?: string }> = [];
+  /** A slug's `edgesOf` has already been walked — prevents re-expanding a shared node's children (rule 1). */
+  const discovered = new Set<string>();
+
+  function addAdjacency(from: string, to: string): void {
+    const set = adjacency.get(from);
+    if (set) set.add(to);
+    else adjacency.set(from, new Set([to]));
+  }
+
+  function addDependent(dependency: string, dependent: string): void {
+    const set = dependentsMap.get(dependency);
+    if (set) set.add(dependent);
+    else dependentsMap.set(dependency, new Set([dependent]));
+  }
+
+  function walk(slug: string, ancestors: Set<string>): void {
+    const deps = edgesOf(slug) ?? [];
+    for (const dep of deps) {
+      const relation: "compose" | "require" = dep.relation ?? "require";
+      touched.add(dep.slug);
+
+      if (ancestors.has(dep.slug)) {
+        // Broken back-edge — surfaced, not swallowed (rule 4). Still recorded
+        // in `edges` (the honest picture of what was declared), but excluded
+        // from `dependentsMap`/`adjacency` so it can't loop the DP/BFS below.
+        cycles.push([slug, dep.slug]);
+        edges.push({ from: slug, to: dep.slug, relation, depKind: dep.kind });
+        continue;
+      }
+
+      edges.push({ from: slug, to: dep.slug, relation, depKind: dep.kind });
+      addAdjacency(slug, dep.slug);
+      addDependent(dep.slug, slug);
+      if (relation === "compose") {
+        composeEdges.push({ from: slug, to: dep.slug, depKind: dep.kind });
+      }
+
+      if (!discovered.has(dep.slug)) {
+        discovered.add(dep.slug);
+        const nextAncestors = new Set(ancestors);
+        nextAncestors.add(slug);
+        walk(dep.slug, nextAncestors);
+      }
+    }
+  }
+
+  for (const root of roots) {
+    if (discovered.has(root)) continue;
+    discovered.add(root);
+    walk(root, new Set([root]));
+  }
+
+  // ── Phase 2: compose-relation sources are never layer nodes (rule 2) ─────
+  const composeSources = new Set(composeEdges.map((e) => e.from));
+  const overlaysByBase = new Map<string, CompositionOverlay[]>();
+  for (const e of composeEdges) {
+    const isInstalled = installedBySlug.has(e.from);
+    const overlay: CompositionOverlay = { slug: e.from, name: nameOf(e.from) ?? e.from, installed: isInstalled };
+    const list = overlaysByBase.get(e.to);
+    if (list) list.push(overlay);
+    else overlaysByBase.set(e.to, [overlay]);
+  }
+
+  // ── Phase 3: which touched slugs are real layer nodes ────────────────────
+  const nodeSlugs = [...touched].filter((s) => !composeSources.has(s)).sort();
+
+  // ── Phase 4: reachability — which input roots reach each slug ────────────
+  const rootsReaching = new Map<string, Set<string>>();
+  for (const root of roots) {
+    const visited = new Set<string>([root]);
+    const queue: string[] = [root];
+    const addReach = (s: string) => {
+      const set = rootsReaching.get(s);
+      if (set) set.add(root);
+      else rootsReaching.set(s, new Set([root]));
+    };
+    addReach(root);
+    while (queue.length) {
+      const cur = queue.shift()!;
+      for (const next of adjacency.get(cur) ?? []) {
+        if (visited.has(next)) continue;
+        visited.add(next);
+        addReach(next);
+        queue.push(next);
+      }
+    }
+  }
+
+  // ── Phase 5: longest-path layering (rule 1) ───────────────────────────────
+  // layer(n) = 1 + max(layer of every node that depends on n); roots = 0.
+  // Works for ANY slug (node or compose-only overlay source) so a compose
+  // source's OWN layer still feeds the DP for the base it composes onto —
+  // e.g. `grants` (excluded from `nodes`) still positions `operations` one
+  // layer below wherever `grants` itself sits.
+  const layerMemo = new Map<string, number>();
+  function layerOf(slug: string, stack: Set<string>): number {
+    if (rootSet.has(slug)) return 0;
+    const memoized = layerMemo.get(slug);
+    if (memoized !== undefined) return memoized;
+    if (stack.has(slug)) return 0; // defensive — cycle edges are already excluded from dependentsMap
+    stack.add(slug);
+    const dependents = dependentsMap.get(slug);
+    const layer = !dependents || dependents.size === 0
+      ? 0
+      : 1 + Math.max(...[...dependents].map((d) => layerOf(d, stack)));
+    stack.delete(slug);
+    layerMemo.set(slug, layer);
+    return layer;
+  }
+
+  // ── Phase 6: build nodes ──────────────────────────────────────────────────
+  const nodes = new Map<string, CompositionNode>();
+  for (const slug of nodeSlugs) {
+    const installedEntries = installedBySlug.get(slug) ?? [];
+    const workspaceIds = installedEntries.map((e) => e.workspaceId).filter(Boolean);
+    const installed = workspaceIds.length > 0;
+    const update = updatesBySlug.get(slug);
+    const installedVersion = update?.installedVersion || installedEntries[0]?.version;
+    const noVersionInfo = installed && (update === undefined || update.latestVersion === undefined);
+
+    nodes.set(slug, {
+      slug,
+      name: nameOf(slug) ?? slug,
+      layer: layerOf(slug, new Set()),
+      dependents: [...(dependentsMap.get(slug) ?? [])].sort(),
+      roots: [...(rootsReaching.get(slug) ?? [])].sort(),
+      installed,
+      workspaceIds,
+      installedVersion,
+      latestVersion: update?.latestVersion ?? null,
+      updateAvailable: update?.updateAvailable ?? false,
+      noVersionInfo,
+      overlays: overlaysByBase.get(slug) ?? [],
+    });
+  }
+
+  const maxLayer = Math.max(0, ...[...nodes.values()].map((n) => n.layer));
+  const layers: CompositionNode[][] = Array.from({ length: maxLayer + 1 }, () => []);
+  for (const node of nodes.values()) layers[node.layer].push(node);
+  for (const bucket of layers) bucket.sort((a, b) => a.slug.localeCompare(b.slug));
+
+  return { nodes, edges, layers, cycles };
+}

package/src/index.ts

@@ -85,6 +85,19 @@ export type {
   TemplateUpdateCheck,
 } from "./catalog.js";
 
+export {
+  layerTemplateGraph,
+  bundledEdgesOf,
+} from "./composition-graph.js";
+export type {
+  CompositionInstalledEntry,
+  CompositionOverlay,
+  CompositionEdge,
+  CompositionNode,
+  CompositionGraph,
+  LayerTemplateGraphInput,
+} from "./composition-graph.js";
+
 export {
   toWorkspaceDefinition,
   toPackageDefinition,