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

package/examples/deployment-composition.ts

@@ -1,52 +1,60 @@
 import { createDescriptorCatalog } from '@lorion-org/composition-graph';
 
 const catalog = createDescriptorCatalog({
-  relationDescriptors: [
+  descriptors: [
     {
-      id: 'integrations',
-      field: 'integrations',
+      id: 'web',
+      version: '1.0.0',
+      dependencies: {
+        checkout: '^1.0.0',
+        payments: '^1.0.0',
+        'payment-provider-invoice': '^1.0.0',
+        'payment-provider-stripe': '^1.0.0',
+        shops: '^1.0.0',
+      },
     },
-  ],
-  descriptors: [
     {
-      id: 'billing',
+      id: 'checkout',
       version: '1.0.0',
-      dependencies: { storage: '*' },
-      integrations: { analytics: '*' },
+      dependencies: { payments: '^1.0.0' },
     },
     {
-      id: 'storage',
+      id: 'payments',
       version: '1.0.0',
     },
     {
-      id: 'analytics',
+      id: 'shops',
       version: '1.0.0',
     },
     {
-      id: 'ui-shell',
+      id: 'payment-provider-invoice',
       version: '1.0.0',
-      dependencies: { router: '*' },
+      providesFor: 'payment-checkout',
+      dependencies: { payments: '^1.0.0' },
     },
     {
-      id: 'router',
+      id: 'payment-provider-stripe',
       version: '1.0.0',
+      defaultFor: 'payment-checkout',
+      providesFor: 'payment-checkout',
+      dependencies: { payments: '^1.0.0' },
     },
   ],
 });
 
 const selection = catalog.resolveSelection({
-  selected: ['billing'],
-  baseDescriptors: ['ui-shell'],
+  selected: ['web'],
 });
 
 console.log(selection.getResolved());
-// ['analytics', 'billing', 'router', 'storage', 'ui-shell']
+// ['checkout', 'payment-provider-invoice', 'payment-provider-stripe', 'payments', 'shops', 'web']
 
 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'] }
+//   { descriptorId: 'checkout', origins: ['resolved'] },
+//   { descriptorId: 'payment-provider-invoice', origins: ['resolved'] },
+//   { descriptorId: 'payment-provider-stripe', origins: ['resolved'] },
+//   { descriptorId: 'payments', origins: ['resolved'] },
+//   { descriptorId: 'shops', origins: ['resolved'] },
+//   { descriptorId: 'web', origins: ['selected'] }
 // ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorion-org/composition-graph",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.2",
   "description": "Framework-free descriptor catalogs, relation graphs, and composition selection logic.",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,10 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "lorion-source": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
@@ -35,7 +39,9 @@
   "files": [
     "dist",
     "examples",
-    "LICENSE"
+    "LICENSE",
+    "src/**/*.ts",
+    "!src/**/*.spec.ts"
   ],
   "keywords": [
     "composition",

package/src/compositionSelection.ts

@@ -0,0 +1,109 @@
+import { getCompositionProvenance } from './descriptorGraph';
+import { assertKnownDescriptorIds } from './descriptorMap';
+import type {
+  CompositionPolicy,
+  CompositionProvenance,
+  CompositionSelection,
+  Descriptor,
+  DescriptorCatalog,
+  DescriptorId,
+} from './types';
+
+export const defaultCompositionPolicy: CompositionPolicy = {
+  resolutionRelationIds: ['dependencies'],
+  provenanceRelationIds: ['dependencies'],
+  inspectionRelationIds: ['dependencies'],
+};
+
+function resolvePolicy(policy?: Partial<CompositionPolicy>): CompositionPolicy {
+  return {
+    ...defaultCompositionPolicy,
+    ...policy,
+    resolutionRelationIds:
+      policy?.resolutionRelationIds ?? defaultCompositionPolicy.resolutionRelationIds,
+    provenanceRelationIds:
+      policy?.provenanceRelationIds ?? defaultCompositionPolicy.provenanceRelationIds,
+    inspectionRelationIds:
+      policy?.inspectionRelationIds ?? defaultCompositionPolicy.inspectionRelationIds,
+  };
+}
+
+export function createCompositionSelection(input: {
+  catalog: DescriptorCatalog;
+  selected?: DescriptorId[];
+  baseDescriptors?: DescriptorId[];
+  policy?: Partial<CompositionPolicy>;
+}): CompositionSelection {
+  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: Descriptor[] | undefined;
+  let provenanceCache: CompositionProvenance[] | undefined;
+
+  const getResolvedDescriptors = (): Descriptor[] => {
+    if (!resolvedDescriptorsCache) {
+      resolvedDescriptorsCache = resolved
+        .map((descriptorId) => descriptorMap.get(descriptorId))
+        .filter((descriptor): descriptor is Descriptor => Boolean(descriptor));
+    }
+
+    return resolvedDescriptorsCache;
+  };
+
+  const getProvenance = (): CompositionProvenance[] => {
+    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 !== undefined
+          ? { 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,
+      });
+    },
+  };
+}

package/src/descriptorCatalog.ts

@@ -0,0 +1,163 @@
+import {
+  buildDescriptorGraph,
+  defaultRelationDescriptors,
+  explainPath,
+  explainPathsBatch,
+  getDependents,
+  getIncomingRelationMap,
+  getTransitiveTargets,
+} from './descriptorGraph';
+import { buildDescriptorMap } from './descriptorMap';
+import { createCompositionSelection } from './compositionSelection';
+import type {
+  Descriptor,
+  DescriptorCatalog,
+  DescriptorGraph,
+  DescriptorMap,
+  DescriptorProfile,
+  RelationDescriptor,
+  RelationId,
+} from './types';
+
+function createRelationRecord(
+  relationIds: RelationId[],
+  values: Array<[RelationId, string[]]>,
+): Record<RelationId, string[]> {
+  return Object.fromEntries(
+    relationIds.map((relationId) => {
+      const entry = values.find(([relation]) => relation === relationId);
+
+      return [relationId, entry?.[1] ?? []];
+    }),
+  );
+}
+
+function resolveRelationDescriptors(
+  relationDescriptors?: RelationDescriptor[],
+): RelationDescriptor[] {
+  const registry = new Map<string, RelationDescriptor>();
+
+  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: Descriptor,
+  relationIds: RelationId[],
+  graph: DescriptorGraph,
+): DescriptorProfile {
+  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' || Array.isArray(descriptor.providesFor)
+      ? { providesFor: descriptor.providesFor }
+      : {}),
+    outgoing,
+    incoming,
+  };
+}
+
+export function createDescriptorCatalog(input: {
+  descriptorMap?: DescriptorMap;
+  descriptors?: Descriptor[];
+  relationDescriptors?: RelationDescriptor[];
+}): DescriptorCatalog {
+  const descriptorMap = input.descriptorMap ?? buildDescriptorMap(input.descriptors ?? []);
+  const relationDescriptors = resolveRelationDescriptors(input.relationDescriptors);
+  const graph = buildDescriptorGraph({
+    descriptorMap,
+    relationDescriptors,
+  });
+
+  const catalog: DescriptorCatalog = {
+    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): descriptor is 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 !== undefined
+          ? { 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;
+}

package/src/descriptorGraph.ts

@@ -0,0 +1,327 @@
+import type {
+  CompositionOriginType,
+  CompositionProvenance,
+  CompositionProvenanceOrigin,
+  Descriptor,
+  DescriptorEdge,
+  DescriptorGraph,
+  DescriptorId,
+  DescriptorIds,
+  DescriptorMap,
+  RelationDescriptor,
+  RelationId,
+  ResolutionStep,
+} from './types';
+
+const createEmptyAdjacency = (
+  descriptorMap: DescriptorMap,
+): Map<DescriptorId, DescriptorEdge[]> => {
+  return new Map(
+    Array.from(descriptorMap.keys())
+      .sort()
+      .map((id) => [id, []]),
+  );
+};
+
+const sortEdges = (edges: DescriptorEdge[]): DescriptorEdge[] => {
+  return [...edges].sort(
+    (left, right) =>
+      left.from.localeCompare(right.from) ||
+      left.to.localeCompare(right.to) ||
+      left.relation.localeCompare(right.relation),
+  );
+};
+
+export const defaultRelationDescriptors: RelationDescriptor[] = [
+  {
+    id: 'dependencies',
+    field: 'dependencies',
+  },
+];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function getRelationTargets(
+  descriptor: Descriptor,
+  relationDescriptor: RelationDescriptor,
+): DescriptorId[] {
+  const field = relationDescriptor.field ?? relationDescriptor.id;
+  const relationValue = descriptor[field];
+
+  const targets = Array.isArray(relationValue)
+    ? relationValue
+    : typeof relationValue === 'string'
+      ? [relationValue]
+      : isRecord(relationValue)
+        ? relationDescriptor.targetMode === 'values'
+          ? Object.values(relationValue)
+          : Object.keys(relationValue)
+        : [];
+
+  return targets
+    .filter((target): target is string => typeof target === 'string' && target.length > 0)
+    .sort();
+}
+
+function createOriginType(path: ResolutionStep[]): CompositionOriginType {
+  return path.length ? 'resolved' : 'selected';
+}
+
+function compareOrigins(
+  left: CompositionProvenanceOrigin,
+  right: CompositionProvenanceOrigin,
+): number {
+  const leftPath = JSON.stringify(left.path);
+  const rightPath = JSON.stringify(right.path);
+
+  return left.originType.localeCompare(right.originType) || leftPath.localeCompare(rightPath);
+}
+
+export function buildDescriptorGraph(input: {
+  descriptorMap: DescriptorMap;
+  relationDescriptors?: RelationDescriptor[];
+}): DescriptorGraph {
+  const relationDescriptors = input.relationDescriptors ?? defaultRelationDescriptors;
+  const descriptorRegistry = new Map<RelationId, RelationDescriptor>(
+    [...relationDescriptors]
+      .sort((left, right) => left.id.localeCompare(right.id))
+      .map((descriptor) => [descriptor.id, descriptor]),
+  );
+  const edges: DescriptorEdge[] = [];
+  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 isIncoming = relationDescriptor.direction === 'incoming';
+        const edge: DescriptorEdge = {
+          from: isIncoming ? target : descriptor.id,
+          to: isIncoming ? descriptor.id : target,
+          relation: relationDescriptor.id,
+          source: 'descriptor',
+        };
+
+        edges.push(edge);
+        outgoing.get(edge.from)?.push(edge);
+        incoming.get(edge.to)?.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,
+  };
+}
+
+export function getTransitiveTargets(input: {
+  graph: DescriptorGraph;
+  start: DescriptorId[];
+  relationIds: RelationId[];
+}): DescriptorIds {
+  const allowedRelations = new Set(input.relationIds);
+  const visited = new Set<DescriptorId>();
+  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();
+}
+
+export function getIncomingRelationMap(input: {
+  graph: DescriptorGraph;
+  relationId: RelationId;
+}): Map<DescriptorId, DescriptorId[]> {
+  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] as const;
+    })
+    .filter(([, sources]) => sources.length > 0)
+    .sort(([left], [right]) => left.localeCompare(right));
+
+  return new Map(entries);
+}
+
+export function getDependents(input: {
+  graph: DescriptorGraph;
+  target: DescriptorId;
+  relationIds: RelationId[];
+  transitive?: boolean;
+}): DescriptorIds {
+  if (!input.graph.descriptorMap.has(input.target)) return [];
+
+  const allowedRelations = new Set(input.relationIds);
+  const visited = new Set<DescriptorId>();
+  const queue: DescriptorId[] = [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();
+}
+
+export function explainPath(input: {
+  graph: DescriptorGraph;
+  from: DescriptorId;
+  to: DescriptorId;
+  relationIds: RelationId[];
+}): ResolutionStep[] {
+  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 = new Set<DescriptorId>([input.from]);
+  const queue: Array<{ node: DescriptorId; path: ResolutionStep[] }> = [
+    { 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: ResolutionStep[] = [
+        ...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 [];
+}
+
+export function explainPathsBatch(input: {
+  graph: DescriptorGraph;
+  pairs: Array<{ from: DescriptorId; to: DescriptorId }>;
+  relationIds: RelationId[];
+}): Array<{ from: DescriptorId; to: DescriptorId; path: ResolutionStep[] }> {
+  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,
+      }),
+    }));
+}
+
+export function getCompositionProvenance(input: {
+  graph: DescriptorGraph;
+  descriptorIds: DescriptorId[];
+  selected: DescriptorId[];
+  baseDescriptors?: DescriptorId[];
+  relationIds: RelationId[];
+}): CompositionProvenance[] {
+  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): CompositionProvenance => {
+    const origins: CompositionProvenanceOrigin[] = [];
+
+    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),
+    };
+  });
+}