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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the 'Software'), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# @lorion-org/composition-graph
+
+Framework-free descriptor catalogs, relation graphs, and composition selection logic.
+
+This package models flat named descriptors, their declared relations, optional base descriptors, and deterministic composition flows.
+
+## Install
+
+```shell
+pnpm add @lorion-org/composition-graph
+```
+
+## What it is
+
+- a typed descriptor model for flat descriptors
+- a graph builder for declared relations
+- a catalog for querying profiles and relation paths
+- a selection layer for resolving selected and base descriptors into a final set
+
+## What it is not
+
+- not a package manager
+- not a filesystem discovery tool
+- not a framework adapter
+- not a runtime-config loader
+
+## Basic example
+
+```ts
+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: 'web-shell',
+      version: '1.0.0',
+      dependencies: { router: '*' },
+    },
+    {
+      id: 'router',
+      version: '1.0.0',
+    },
+  ],
+});
+
+const selection = catalog.resolveSelection({
+  selected: ['billing'],
+  baseDescriptors: ['web-shell'],
+});
+
+console.log(selection.getResolved());
+console.log(selection.getProvenance());
+```
+
+## Example: explicit base descriptors
+
+Use `baseDescriptors` for descriptors that always participate in the
+resolution for a given runtime, deployment, or application shell.
+
+```ts
+import { createDescriptorCatalog } from '@lorion-org/composition-graph';
+
+const catalog = createDescriptorCatalog({
+  descriptors: [
+    {
+      id: 'billing',
+      version: '1.0.0',
+      dependencies: { storage: '*' },
+    },
+    {
+      id: 'storage',
+      version: '1.0.0',
+    },
+    {
+      id: 'web-shell',
+      version: '1.0.0',
+      dependencies: { router: '*' },
+    },
+    {
+      id: 'router',
+      version: '1.0.0',
+    },
+  ],
+});
+
+const selection = catalog.resolveSelection({
+  selected: ['billing'],
+  baseDescriptors: ['web-shell'],
+});
+
+selection.getResolved();
+// => ['billing', 'router', 'storage', 'web-shell']
+```
+
+## Example: explain why something is present
+
+The catalog and selection APIs expose path explanation helpers for diagnostics,
+admin UIs, and composition debugging.
+
+```ts
+import { createDescriptorCatalog } from '@lorion-org/composition-graph';
+
+const catalog = createDescriptorCatalog({
+  descriptors: [
+    {
+      id: 'billing',
+      version: '1.0.0',
+      dependencies: { storage: '*' },
+    },
+    {
+      id: 'storage',
+      version: '1.0.0',
+      dependencies: { queue: '*' },
+    },
+    {
+      id: 'queue',
+      version: '1.0.0',
+    },
+  ],
+});
+
+catalog.explain({
+  from: 'billing',
+  to: 'queue',
+  relationIds: ['dependencies'],
+});
+// => [
+//   { from: 'billing', to: 'storage', relation: 'dependencies' },
+//   { from: 'storage', to: 'queue', relation: 'dependencies' },
+// ]
+```
+
+## Example: combine with descriptor discovery
+
+`@lorion-org/composition-graph` expects flat descriptors. If your authoring format
+allows nested descriptor documents, flatten them before building the catalog.
+
+```ts
+import { createDescriptorCatalog } from '@lorion-org/composition-graph';
+import { discoverDescriptors } from '@lorion-org/descriptor-discovery';
+
+const discovered = discoverDescriptors({
+  roots: ['./descriptors'],
+  descriptorFileName: 'descriptor.json',
+  idField: 'name',
+  nestedField: 'bundles',
+});
+
+const catalog = createDescriptorCatalog({
+  descriptors: discovered.map((entry) => entry.descriptor),
+});
+```
+
+## Relations
+
+- `dependencies` is the only built-in relation
+- every additional relation must be registered via `relationDescriptors`
+- unconfigured descriptor fields are ignored by the graph
+- string parsing for user-facing selection input belongs in a higher adapter layer
+- nested descriptor authoring belongs in a discovery or normalization layer, not in this package
+
+`relationDescriptors` are intentionally small:
+
+- `id` identifies the relation in graph queries and policies
+- `field` optionally maps the relation to a descriptor field name
+
+The core graph does not prescribe directional interpretation, hinting, or
+weighting. Those concerns belong in higher layers.
+
+Dependency-specific projections are also intentionally outside the core. If a
+consumer needs a "what pulled this in?" view, derive that from
+`getProvenance()` in its own adapter or UI layer.
+
+## Local commands
+
+```shell
+cd packages/composition-graph
+pnpm build
+pnpm test
+pnpm coverage
+pnpm typecheck
+pnpm package:check
+```

package/dist/index.cjs

@@ -0,0 +1,442 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  assertKnownDescriptorIds: () => assertKnownDescriptorIds,
+  buildDescriptorGraph: () => buildDescriptorGraph,
+  buildDescriptorMap: () => buildDescriptorMap,
+  createCompositionSelection: () => createCompositionSelection,
+  createDescriptorCatalog: () => createDescriptorCatalog,
+  defaultCompositionPolicy: () => defaultCompositionPolicy,
+  defaultRelationDescriptors: () => defaultRelationDescriptors,
+  explainPath: () => explainPath,
+  explainPathsBatch: () => explainPathsBatch,
+  getCompositionProvenance: () => getCompositionProvenance,
+  getDependents: () => getDependents,
+  getIncomingRelationMap: () => getIncomingRelationMap,
+  getTransitiveTargets: () => getTransitiveTargets,
+  parseDescriptorIds: () => parseDescriptorIds
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertKnownDescriptorIds,
+  buildDescriptorGraph,
+  buildDescriptorMap,
+  createCompositionSelection,
+  createDescriptorCatalog,
+  defaultCompositionPolicy,
+  defaultRelationDescriptors,
+  explainPath,
+  explainPathsBatch,
+  getCompositionProvenance,
+  getDependents,
+  getIncomingRelationMap,
+  getTransitiveTargets,
+  parseDescriptorIds
+});