@lorion-org/composition-graph 1.0.0-beta.0

package/dist/index.js

@@ -0,0 +1,402 @@
+// src/descriptorMap.ts
+function buildDescriptorMap(descriptors) {
+  const descriptorMap = /* @__PURE__ */ new Map();
+  for (const descriptor of descriptors) {
+    descriptorMap.set(descriptor.id, descriptor);
+  }
+  return descriptorMap;
+}
+function parseDescriptorIds(input) {
+  if (!input) return [];
+  const items = Array.isArray(input) ? input : input.split(/[,\s]+/).map((item) => item.trim());
+  return Array.from(new Set(items.map((item) => item.trim()).filter(Boolean))).sort();
+}
+function assertKnownDescriptorIds(descriptorMap, ids, label) {
+  const missing = [...new Set(ids)].filter((id) => id && !descriptorMap.has(id)).sort();
+  if (!missing.length) return;
+  throw new Error(`Unknown ${label}: ${missing.join(", ")}`);
+}
+
+// src/descriptorGraph.ts
+var createEmptyAdjacency = (descriptorMap) => {
+  return new Map(
+    Array.from(descriptorMap.keys()).sort().map((id) => [id, []])
+  );
+};
+var sortEdges = (edges) => {
+  return [...edges].sort(
+    (left, right) => left.from.localeCompare(right.from) || left.to.localeCompare(right.to) || left.relation.localeCompare(right.relation)
+  );
+};
+var defaultRelationDescriptors = [
+  {
+    id: "dependencies",
+    field: "dependencies"
+  }
+];
+function isVersionConstraintMap(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getRelationTargets(descriptor, relationDescriptor) {
+  const field = relationDescriptor.field ?? relationDescriptor.id;
+  const relationValue = descriptor[field];
+  if (!isVersionConstraintMap(relationValue)) return [];
+  return Object.keys(relationValue).sort();
+}
+function createOriginType(path) {
+  return path.length ? "resolved" : "selected";
+}
+function compareOrigins(left, right) {
+  const leftPath = JSON.stringify(left.path);
+  const rightPath = JSON.stringify(right.path);
+  return left.originType.localeCompare(right.originType) || leftPath.localeCompare(rightPath);
+}
+function buildDescriptorGraph(input) {
+  const relationDescriptors = input.relationDescriptors ?? defaultRelationDescriptors;
+  const descriptorRegistry = new Map(
+    [...relationDescriptors].sort((left, right) => left.id.localeCompare(right.id)).map((descriptor) => [descriptor.id, descriptor])
+  );
+  const edges = [];
+  const outgoing = createEmptyAdjacency(input.descriptorMap);
+  const incoming = createEmptyAdjacency(input.descriptorMap);
+  for (const descriptor of Array.from(input.descriptorMap.values()).sort(
+    (left, right) => left.id.localeCompare(right.id)
+  )) {
+    for (const relationDescriptor of descriptorRegistry.values()) {
+      for (const target of getRelationTargets(descriptor, relationDescriptor)) {
+        if (!input.descriptorMap.has(target)) continue;
+        const edge = {
+          from: descriptor.id,
+          to: target,
+          relation: relationDescriptor.id,
+          source: "descriptor"
+        };
+        edges.push(edge);
+        outgoing.get(descriptor.id)?.push(edge);
+        incoming.get(target)?.push(edge);
+      }
+    }
+  }
+  for (const [id, nodeEdges] of outgoing) outgoing.set(id, sortEdges(nodeEdges));
+  for (const [id, nodeEdges] of incoming) incoming.set(id, sortEdges(nodeEdges));
+  return {
+    descriptorMap: input.descriptorMap,
+    edges: sortEdges(edges),
+    outgoing,
+    incoming,
+    relationDescriptors: descriptorRegistry
+  };
+}
+function getTransitiveTargets(input) {
+  const allowedRelations = new Set(input.relationIds);
+  const visited = /* @__PURE__ */ new Set();
+  const stack = [...input.start].sort().reverse();
+  while (stack.length) {
+    const current = stack.pop();
+    if (!current || visited.has(current)) continue;
+    visited.add(current);
+    for (const edge of input.graph.outgoing.get(current) ?? []) {
+      if (!allowedRelations.has(edge.relation) || visited.has(edge.to)) continue;
+      stack.push(edge.to);
+    }
+  }
+  return Array.from(visited).filter((id) => input.graph.descriptorMap.has(id)).sort();
+}
+function getIncomingRelationMap(input) {
+  const entries = Array.from(input.graph.incoming.entries()).map(([target, edges]) => {
+    const sources = edges.filter((edge) => edge.relation === input.relationId).map((edge) => edge.from).sort();
+    return [target, sources];
+  }).filter(([, sources]) => sources.length > 0).sort(([left], [right]) => left.localeCompare(right));
+  return new Map(entries);
+}
+function getDependents(input) {
+  if (!input.graph.descriptorMap.has(input.target)) return [];
+  const allowedRelations = new Set(input.relationIds);
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [input.target];
+  while (queue.length) {
+    const current = queue.shift();
+    if (!current || visited.has(current)) continue;
+    visited.add(current);
+    if (input.transitive === false && current !== input.target) continue;
+    for (const edge of input.graph.incoming.get(current) ?? []) {
+      if (!allowedRelations.has(edge.relation) || visited.has(edge.from)) continue;
+      queue.push(edge.from);
+    }
+  }
+  visited.delete(input.target);
+  return Array.from(visited).sort();
+}
+function explainPath(input) {
+  if (!input.graph.descriptorMap.has(input.from) || !input.graph.descriptorMap.has(input.to))
+    return [];
+  if (input.from === input.to) return [];
+  const allowedRelations = new Set(input.relationIds);
+  const visited = /* @__PURE__ */ new Set([input.from]);
+  const queue = [
+    { node: input.from, path: [] }
+  ];
+  while (queue.length) {
+    const current = queue.shift();
+    if (!current) continue;
+    for (const edge of input.graph.outgoing.get(current.node) ?? []) {
+      if (!allowedRelations.has(edge.relation) || visited.has(edge.to)) continue;
+      const nextPath = [
+        ...current.path,
+        {
+          from: edge.from,
+          to: edge.to,
+          relation: edge.relation
+        }
+      ];
+      if (edge.to === input.to) return nextPath;
+      visited.add(edge.to);
+      queue.push({
+        node: edge.to,
+        path: nextPath
+      });
+    }
+  }
+  return [];
+}
+function explainPathsBatch(input) {
+  return [...input.pairs].sort((left, right) => left.from.localeCompare(right.from) || left.to.localeCompare(right.to)).map(({ from, to }) => ({
+    from,
+    to,
+    path: explainPath({
+      graph: input.graph,
+      from,
+      to,
+      relationIds: input.relationIds
+    })
+  }));
+}
+function getCompositionProvenance(input) {
+  const selected = [...new Set(input.selected)].filter((descriptorId) => input.graph.descriptorMap.has(descriptorId)).sort();
+  const baseDescriptors = [...new Set(input.baseDescriptors ?? [])].filter((descriptorId) => input.graph.descriptorMap.has(descriptorId)).sort();
+  const descriptorIds = [...new Set(input.descriptorIds)].filter((descriptorId) => input.graph.descriptorMap.has(descriptorId)).sort();
+  return descriptorIds.map((descriptorId) => {
+    const origins = [];
+    if (selected.includes(descriptorId)) {
+      origins.push({
+        originType: "selected",
+        path: []
+      });
+    }
+    if (baseDescriptors.includes(descriptorId)) {
+      origins.push({
+        originType: "base",
+        path: []
+      });
+    }
+    for (const source of [...selected, ...baseDescriptors]) {
+      if (source === descriptorId) continue;
+      const path = explainPath({
+        graph: input.graph,
+        from: source,
+        to: descriptorId,
+        relationIds: input.relationIds
+      });
+      if (!path.length) continue;
+      origins.push({
+        originType: createOriginType(path),
+        path
+      });
+    }
+    return {
+      descriptorId,
+      origins: origins.sort(compareOrigins)
+    };
+  });
+}
+
+// src/compositionSelection.ts
+var defaultCompositionPolicy = {
+  resolutionRelationIds: ["dependencies"],
+  provenanceRelationIds: ["dependencies"],
+  inspectionRelationIds: ["dependencies"]
+};
+function resolvePolicy(policy) {
+  return {
+    ...defaultCompositionPolicy,
+    ...policy,
+    resolutionRelationIds: policy?.resolutionRelationIds ?? defaultCompositionPolicy.resolutionRelationIds,
+    provenanceRelationIds: policy?.provenanceRelationIds ?? defaultCompositionPolicy.provenanceRelationIds,
+    inspectionRelationIds: policy?.inspectionRelationIds ?? defaultCompositionPolicy.inspectionRelationIds
+  };
+}
+function createCompositionSelection(input) {
+  const catalog = input.catalog;
+  const descriptorMap = catalog.getDescriptorMap();
+  const selected = [...new Set(input.selected ?? [])].filter(Boolean).sort();
+  const baseDescriptors = [...new Set(input.baseDescriptors ?? [])].filter(Boolean).sort();
+  assertKnownDescriptorIds(descriptorMap, selected, "selected descriptors");
+  assertKnownDescriptorIds(descriptorMap, baseDescriptors, "base descriptors");
+  const policy = resolvePolicy(input.policy);
+  const resolved = catalog.getTransitiveTargets({
+    start: [...selected, ...baseDescriptors],
+    relationIds: policy.resolutionRelationIds
+  });
+  let resolvedDescriptorsCache;
+  let provenanceCache;
+  const getResolvedDescriptors = () => {
+    if (!resolvedDescriptorsCache) {
+      resolvedDescriptorsCache = resolved.map((descriptorId) => descriptorMap.get(descriptorId)).filter((descriptor) => Boolean(descriptor));
+    }
+    return resolvedDescriptorsCache;
+  };
+  const getProvenance = () => {
+    if (!provenanceCache) {
+      provenanceCache = getCompositionProvenance({
+        graph: catalog.getGraph(),
+        descriptorIds: resolved,
+        selected,
+        baseDescriptors,
+        relationIds: policy.provenanceRelationIds
+      });
+    }
+    return provenanceCache;
+  };
+  return {
+    getCatalog: () => catalog,
+    getGraph: () => catalog.getGraph(),
+    getSelected: () => [...selected],
+    getBaseDescriptors: () => [...baseDescriptors],
+    getResolved: () => [...resolved],
+    getResolvedDescriptors,
+    getProvenance,
+    getDependentsFor: (target, dependentsInput = {}) => {
+      return catalog.getDependents({
+        target,
+        relationIds: dependentsInput.relationIds ?? policy.resolutionRelationIds,
+        ...dependentsInput.transitive !== void 0 ? { transitive: dependentsInput.transitive } : {}
+      });
+    },
+    explain: (explainInput) => {
+      return catalog.explain({
+        from: explainInput.from,
+        to: explainInput.to,
+        relationIds: explainInput.relationIds ?? policy.inspectionRelationIds
+      });
+    },
+    explainPathsBatch: (batchInput) => {
+      return catalog.explainPathsBatch({
+        pairs: batchInput.pairs,
+        relationIds: batchInput.relationIds ?? policy.inspectionRelationIds
+      });
+    }
+  };
+}
+
+// src/descriptorCatalog.ts
+function createRelationRecord(relationIds, values) {
+  return Object.fromEntries(
+    relationIds.map((relationId) => {
+      const entry = values.find(([relation]) => relation === relationId);
+      return [relationId, entry?.[1] ?? []];
+    })
+  );
+}
+function resolveRelationDescriptors(relationDescriptors) {
+  const registry = /* @__PURE__ */ new Map();
+  for (const relationDescriptor of defaultRelationDescriptors) {
+    registry.set(relationDescriptor.id, relationDescriptor);
+  }
+  for (const relationDescriptor of relationDescriptors ?? []) {
+    registry.set(relationDescriptor.id, relationDescriptor);
+  }
+  return Array.from(registry.values()).sort((left, right) => left.id.localeCompare(right.id));
+}
+function buildDescriptorProfile(descriptor, relationIds, graph) {
+  const outgoing = createRelationRecord(
+    relationIds,
+    relationIds.map((relationId) => {
+      const targets = (graph.outgoing.get(descriptor.id) ?? []).filter((edge) => edge.relation === relationId).map((edge) => edge.to).sort();
+      return [relationId, targets];
+    })
+  );
+  const incoming = createRelationRecord(
+    relationIds,
+    relationIds.map((relationId) => {
+      const sources = (graph.incoming.get(descriptor.id) ?? []).filter((edge) => edge.relation === relationId).map((edge) => edge.from).sort();
+      return [relationId, sources];
+    })
+  );
+  return {
+    id: descriptor.id,
+    disabled: descriptor.disabled === true,
+    capabilities: [...descriptor.capabilities ?? []].sort(),
+    ...descriptor.location ? { location: descriptor.location } : {},
+    ...typeof descriptor.providesFor === "string" ? { providesFor: descriptor.providesFor } : {},
+    outgoing,
+    incoming
+  };
+}
+function createDescriptorCatalog(input) {
+  const descriptorMap = input.descriptorMap ?? buildDescriptorMap(input.descriptors ?? []);
+  const relationDescriptors = resolveRelationDescriptors(input.relationDescriptors);
+  const graph = buildDescriptorGraph({
+    descriptorMap,
+    relationDescriptors
+  });
+  const catalog = {
+    getDescriptorMap: () => descriptorMap,
+    getAllDescriptors: () => Array.from(descriptorMap.values()),
+    getDescriptor: (id) => descriptorMap.get(id),
+    getGraph: () => graph,
+    getRelationDescriptors: () => Array.from(graph.relationDescriptors.values()),
+    getProfiles: (profileInput = {}) => {
+      const ids = [...new Set(profileInput.ids ?? [])].filter(Boolean).sort();
+      const descriptors = ids.length ? ids.map((id) => descriptorMap.get(id)).filter((descriptor) => Boolean(descriptor)) : Array.from(descriptorMap.values()).filter(
+        (descriptor) => profileInput.includeDisabled === true || descriptor.disabled !== true
+      ).sort((left, right) => left.id.localeCompare(right.id));
+      return descriptors.map(
+        (descriptor) => buildDescriptorProfile(descriptor, Array.from(graph.relationDescriptors.keys()), graph)
+      );
+    },
+    getIncomingRelationMap: (relationId) => getIncomingRelationMap({ graph, relationId }),
+    getTransitiveTargets: (transitiveInput) => getTransitiveTargets({
+      graph,
+      start: transitiveInput.start,
+      relationIds: transitiveInput.relationIds
+    }),
+    getDependents: (dependentsInput) => getDependents({
+      graph,
+      target: dependentsInput.target,
+      relationIds: dependentsInput.relationIds,
+      ...dependentsInput.transitive !== void 0 ? { transitive: dependentsInput.transitive } : {}
+    }),
+    explain: (explainInput) => explainPath({
+      graph,
+      from: explainInput.from,
+      to: explainInput.to,
+      relationIds: explainInput.relationIds
+    }),
+    explainPathsBatch: (batchInput) => explainPathsBatch({
+      graph,
+      pairs: batchInput.pairs,
+      relationIds: batchInput.relationIds
+    }),
+    resolveSelection: (selectionInput) => createCompositionSelection({
+      catalog,
+      ...selectionInput
+    })
+  };
+  return catalog;
+}
+export {
+  assertKnownDescriptorIds,
+  buildDescriptorGraph,
+  buildDescriptorMap,
+  createCompositionSelection,
+  createDescriptorCatalog,
+  defaultCompositionPolicy,
+  defaultRelationDescriptors,
+  explainPath,
+  explainPathsBatch,
+  getCompositionProvenance,
+  getDependents,
+  getIncomingRelationMap,
+  getTransitiveTargets,
+  parseDescriptorIds
+};

package/examples/deployment-composition.js

@@ -0,0 +1,43 @@
+/* eslint-env node */
+import { createDescriptorCatalog } from '../dist/index.js';
+
+const catalog = createDescriptorCatalog({
+  relationDescriptors: [
+    {
+      id: 'integrations',
+      field: 'integrations',
+    },
+  ],
+  descriptors: [
+    {
+      id: 'billing',
+      version: '1.0.0',
+      dependencies: { storage: '*' },
+      integrations: { analytics: '*' },
+    },
+    {
+      id: 'storage',
+      version: '1.0.0',
+    },
+    {
+      id: 'analytics',
+      version: '1.0.0',
+    },
+    {
+      id: 'ui-shell',
+      version: '1.0.0',
+      dependencies: { router: '*' },
+    },
+    {
+      id: 'router',
+      version: '1.0.0',
+    },
+  ],
+});
+
+const selection = catalog.resolveSelection({
+  selected: ['billing'],
+  baseDescriptors: ['ui-shell'],
+});
+
+process.stdout.write(`${selection.getResolved().join(', ')}\n`);

package/examples/deployment-composition.ts

@@ -0,0 +1,52 @@
+import { createDescriptorCatalog } from '@lorion-org/composition-graph';
+
+const catalog = createDescriptorCatalog({
+  relationDescriptors: [
+    {
+      id: 'integrations',
+      field: 'integrations',
+    },
+  ],
+  descriptors: [
+    {
+      id: 'billing',
+      version: '1.0.0',
+      dependencies: { storage: '*' },
+      integrations: { analytics: '*' },
+    },
+    {
+      id: 'storage',
+      version: '1.0.0',
+    },
+    {
+      id: 'analytics',
+      version: '1.0.0',
+    },
+    {
+      id: 'ui-shell',
+      version: '1.0.0',
+      dependencies: { router: '*' },
+    },
+    {
+      id: 'router',
+      version: '1.0.0',
+    },
+  ],
+});
+
+const selection = catalog.resolveSelection({
+  selected: ['billing'],
+  baseDescriptors: ['ui-shell'],
+});
+
+console.log(selection.getResolved());
+// ['analytics', 'billing', 'router', 'storage', 'ui-shell']
+
+console.log(selection.getProvenance());
+// [
+//   { descriptorId: 'analytics', origins: ['resolved'] },
+//   { descriptorId: 'billing', origins: ['selected'] },
+//   { descriptorId: 'router', origins: ['resolved'] },
+//   { descriptorId: 'storage', origins: ['resolved'] },
+//   { descriptorId: 'ui-shell', origins: ['base'] }
+// ]

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@lorion-org/composition-graph",
+  "version": "1.0.0-beta.0",
+  "description": "Framework-free descriptor catalogs, relation graphs, and composition selection logic.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lorion-org/lorion.git",
+    "directory": "packages/composition-graph"
+  },
+  "homepage": "https://github.com/lorion-org/lorion/tree/main/packages/composition-graph#readme",
+  "bugs": {
+    "url": "https://github.com/lorion-org/lorion/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "examples",
+    "LICENSE"
+  ],
+  "keywords": [
+    "composition",
+    "graph",
+    "descriptor",
+    "catalog"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "clean": "rimraf coverage dist tsconfig.tsbuildinfo",
+    "example:composition": "node ./examples/deployment-composition.js",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run --root ../.. --config vitest.config.mts packages/composition-graph/src/index.spec.ts",
+    "coverage": "node -e \"require('node:fs').mkdirSync('../../coverage/.tmp', { recursive: true })\" && vitest run --coverage --coverage.include=packages/composition-graph/src/**/*.ts --root ../.. --config vitest.config.mts packages/composition-graph/src/index.spec.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "package:check": "pnpm build && pnpm pack --dry-run && publint"
+  }
+}