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

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),
+    };
+  });
+}

package/src/descriptorMap.ts

@@ -0,0 +1,127 @@
+import type { Descriptor, DescriptorId, DescriptorMap } from './types';
+
+export type DescriptorSelectionSeedInput = {
+  argv?: string[];
+  cliKeys?: string[];
+  defaultValue?: DescriptorId[] | string;
+  env?: Record<string, string | undefined>;
+  envKeys?: string[];
+  key?: string;
+};
+
+export function buildDescriptorMap(descriptors: Iterable<Descriptor>): DescriptorMap {
+  const descriptorMap: DescriptorMap = new Map();
+
+  for (const descriptor of descriptors) {
+    descriptorMap.set(descriptor.id, descriptor);
+  }
+
+  return descriptorMap;
+}
+
+export function parseDescriptorIds(input?: unknown): DescriptorId[] {
+  if (typeof input === 'string') {
+    return Array.from(
+      new Set(
+        input
+          .split(/[,\s]+/)
+          .map((item) => item.trim())
+          .filter(Boolean),
+      ),
+    ).sort();
+  }
+
+  if (!Array.isArray(input)) return [];
+
+  const items = input.flatMap((item) => (typeof item === 'string' ? parseDescriptorIds(item) : []));
+
+  return Array.from(new Set(items.map((item) => item.trim()).filter(Boolean))).sort();
+}
+
+function readCliValue(argv: string[], key: string): string | undefined {
+  const arg = argv.find((entry) => entry === key || entry.startsWith(`${key}=`));
+
+  if (!arg) return undefined;
+  if (arg === key) {
+    const value = argv[argv.indexOf(arg) + 1];
+    return value?.startsWith('-') ? undefined : value;
+  }
+
+  return arg.slice(`${key}=`.length);
+}
+
+function firstNonEmptyValue(
+  values: Array<string | string[] | undefined>,
+): string | string[] | undefined {
+  return values.find((value) => {
+    if (typeof value === 'string') return value.trim().length > 0;
+    return Array.isArray(value) && value.some((entry) => typeof entry === 'string' && entry.trim());
+  });
+}
+
+function pluralizeSelectionKeySegment(value: string): string {
+  if (value.endsWith('s')) return value;
+  if (value.endsWith('y')) return `${value.slice(0, -1)}ies`;
+  return `${value}s`;
+}
+
+function normalizeSelectionKey(value: string): string {
+  const segments = value
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[_\s]+/g, '-')
+    .toLowerCase()
+    .split('-')
+    .filter(Boolean);
+
+  if (!segments.length) return '';
+
+  const lastSegment = segments[segments.length - 1] as string;
+  segments[segments.length - 1] = pluralizeSelectionKeySegment(lastSegment);
+
+  return segments.join('-');
+}
+
+function toEnvKey(value: string): string {
+  return value.replaceAll('-', '_').toUpperCase();
+}
+
+function resolveCliKeys(input: DescriptorSelectionSeedInput): string[] {
+  if (input.cliKeys) return input.cliKeys;
+
+  const key = input.key ? normalizeSelectionKey(input.key) : '';
+  return key ? [`--${key}`] : [];
+}
+
+function resolveEnvKeys(input: DescriptorSelectionSeedInput): string[] {
+  if (input.envKeys) return input.envKeys;
+
+  const key = input.key ? normalizeSelectionKey(input.key) : '';
+  return key ? [`npm_config_${key.replaceAll('-', '_')}`, `LORION_${toEnvKey(key)}`] : [];
+}
+
+export function resolveDescriptorSelectionSeed(
+  input: DescriptorSelectionSeedInput = {},
+): DescriptorId[] {
+  return parseDescriptorIds(
+    firstNonEmptyValue([
+      ...resolveCliKeys(input).map((key) => readCliValue(input.argv ?? [], key)),
+      ...resolveEnvKeys(input).map((key) => input.env?.[key]),
+      input.defaultValue,
+    ]),
+  );
+}
+
+export function assertKnownDescriptorIds(
+  descriptorMap: DescriptorMap,
+  ids: DescriptorId[],
+  label: string,
+): void {
+  const missing: DescriptorId[] = [...new Set(ids)]
+    .filter((id) => id && !descriptorMap.has(id))
+    .sort();
+
+  if (!missing.length) return;
+
+  throw new Error(`Unknown ${label}: ${missing.join(', ')}`);
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+export {
+  assertKnownDescriptorIds,
+  buildDescriptorMap,
+  parseDescriptorIds,
+  resolveDescriptorSelectionSeed,
+} from './descriptorMap';
+export {
+  buildDescriptorGraph,
+  defaultRelationDescriptors,
+  explainPath,
+  explainPathsBatch,
+  getCompositionProvenance,
+  getDependents,
+  getIncomingRelationMap,
+  getTransitiveTargets,
+} from './descriptorGraph';
+export { createDescriptorCatalog } from './descriptorCatalog';
+export { createCompositionSelection, defaultCompositionPolicy } from './compositionSelection';
+export type {
+  CompositionOriginType,
+  CompositionPolicy,
+  CompositionProvenance,
+  CompositionProvenanceOrigin,
+  CompositionSelection,
+  Descriptor,
+  DescriptorCatalog,
+  DescriptorEdge,
+  DescriptorGraph,
+  DescriptorId,
+  DescriptorIds,
+  DescriptorMap,
+  DescriptorProfile,
+  RelationDescriptor,
+  RelationId,
+  ResolutionStep,
+  VersionConstraintMap,
+} from './types';
+export type { DescriptorSelectionSeedInput } from './descriptorMap';