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

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';

package/src/types.ts

@@ -0,0 +1,133 @@
+export type DescriptorId = string;
+
+export type DescriptorIds = DescriptorId[];
+
+export type VersionConstraintMap = Record<DescriptorId, string>;
+
+export type RelationId = string;
+
+export type Descriptor = {
+  id: DescriptorId;
+  version: string;
+  providesFor?: DescriptorId | DescriptorId[];
+  defaultFor?: DescriptorId | DescriptorId[];
+  capabilities?: string[];
+  dependencies?: VersionConstraintMap;
+  disabled?: boolean;
+  location?: string;
+  [key: string]: unknown;
+};
+
+export type DescriptorMap = Map<DescriptorId, Descriptor>;
+
+export type RelationDescriptor = {
+  direction?: 'outgoing' | 'incoming';
+  id: RelationId;
+  field?: string;
+  targetMode?: 'keys' | 'values';
+};
+
+export type DescriptorEdge = {
+  from: DescriptorId;
+  to: DescriptorId;
+  relation: RelationId;
+  source: 'descriptor' | 'derived';
+};
+
+export type ResolutionStep = {
+  from: DescriptorId;
+  to: DescriptorId;
+  relation: RelationId;
+};
+
+export type CompositionOriginType = 'selected' | 'base' | 'resolved';
+
+export type CompositionProvenanceOrigin = {
+  originType: CompositionOriginType;
+  path: ResolutionStep[];
+};
+
+export type CompositionProvenance = {
+  descriptorId: DescriptorId;
+  origins: CompositionProvenanceOrigin[];
+};
+
+export type DescriptorGraph = {
+  descriptorMap: DescriptorMap;
+  edges: DescriptorEdge[];
+  outgoing: Map<DescriptorId, DescriptorEdge[]>;
+  incoming: Map<DescriptorId, DescriptorEdge[]>;
+  relationDescriptors: Map<RelationId, RelationDescriptor>;
+};
+
+export type DescriptorProfile = {
+  id: DescriptorId;
+  location?: string;
+  disabled: boolean;
+  providesFor?: DescriptorId | DescriptorId[];
+  capabilities: string[];
+  outgoing: Record<RelationId, string[]>;
+  incoming: Record<RelationId, string[]>;
+};
+
+export type CompositionPolicy = {
+  resolutionRelationIds: RelationId[];
+  provenanceRelationIds: RelationId[];
+  inspectionRelationIds: RelationId[];
+};
+
+export type DescriptorCatalog = {
+  getDescriptorMap: () => DescriptorMap;
+  getAllDescriptors: () => Descriptor[];
+  getDescriptor: (id: DescriptorId) => Descriptor | undefined;
+  getGraph: () => DescriptorGraph;
+  getRelationDescriptors: () => RelationDescriptor[];
+  getProfiles: (input?: { ids?: DescriptorId[]; includeDisabled?: boolean }) => DescriptorProfile[];
+  getIncomingRelationMap: (relationId: RelationId) => Map<DescriptorId, DescriptorId[]>;
+  getTransitiveTargets: (input: {
+    start: DescriptorId[];
+    relationIds: RelationId[];
+  }) => DescriptorIds;
+  getDependents: (input: {
+    target: DescriptorId;
+    relationIds: RelationId[];
+    transitive?: boolean;
+  }) => DescriptorIds;
+  explain: (input: {
+    from: DescriptorId;
+    to: DescriptorId;
+    relationIds: RelationId[];
+  }) => ResolutionStep[];
+  explainPathsBatch: (input: {
+    pairs: Array<{ from: DescriptorId; to: DescriptorId }>;
+    relationIds: RelationId[];
+  }) => Array<{ from: DescriptorId; to: DescriptorId; path: ResolutionStep[] }>;
+  resolveSelection: (input: {
+    selected?: DescriptorId[];
+    baseDescriptors?: DescriptorId[];
+    policy?: Partial<CompositionPolicy>;
+  }) => CompositionSelection;
+};
+
+export type CompositionSelection = {
+  getCatalog: () => DescriptorCatalog;
+  getGraph: () => DescriptorGraph;
+  getSelected: () => DescriptorIds;
+  getBaseDescriptors: () => DescriptorIds;
+  getResolved: () => DescriptorIds;
+  getResolvedDescriptors: () => Descriptor[];
+  getProvenance: () => CompositionProvenance[];
+  getDependentsFor: (
+    target: DescriptorId,
+    input?: { transitive?: boolean; relationIds?: RelationId[] },
+  ) => DescriptorIds;
+  explain: (input: {
+    from: DescriptorId;
+    to: DescriptorId;
+    relationIds?: RelationId[];
+  }) => ResolutionStep[];
+  explainPathsBatch: (input: {
+    pairs: Array<{ from: DescriptorId; to: DescriptorId }>;
+    relationIds?: RelationId[];
+  }) => Array<{ from: DescriptorId; to: DescriptorId; path: ResolutionStep[] }>;
+};