@lorion-org/react 1.0.0-beta.1 → 1.0.0-beta.2

package/dist/vite.js

@@ -1,14 +1,25 @@
+import {
+  createCapabilityCompositionPolicy,
+  defaultCapabilityRelationDescriptors
+} from "./chunk-5FUI4JPB.js";
+
 // src/vite.ts
 import { existsSync, readFileSync } from "fs";
 import { dirname, join, relative, resolve, sep } from "path";
+import process from "process";
 import {
   createCompositionSelection,
-  createDescriptorCatalog
+  createDescriptorCatalog,
+  resolveDescriptorSelectionSeed
 } from "@lorion-org/composition-graph";
 import {
   descriptorSchema,
   discoverDescriptors
 } from "@lorion-org/descriptor-discovery";
+import {
+  collectSelectedProviderPreferences,
+  resolveSelectedProviderRelationPreferences
+} from "@lorion-org/provider-selection";
 var virtualModuleId = "virtual:capabilities";
 var resolvedVirtualModuleId = `\0${virtualModuleId}`;
 function capabilityLoader(options = {}) {
@@ -30,7 +41,7 @@ function capabilityLoader(options = {}) {
     },
     load(id) {
       if (id !== resolvedVirtualModuleId) return null;
-      return renderCapabilityModule(capabilities);
+      return renderCapabilityModule(capabilities, resolveSelectionSeed(options));
     }
   };
 }
@@ -52,28 +63,85 @@ function discoverSelectedCapabilities(workspaceRoot, options = {}) {
 }
 function selectCapabilities(capabilities, options = {}) {
   const enabledCapabilities = capabilities.filter((capability) => capability.disabled !== true);
-  if (!options.selected?.length && !options.baseDescriptors?.length) {
+  const selected = resolveCapabilitySelectionSeed(options);
+  if (!selected.length && !options.baseDescriptors?.length) {
     return [...enabledCapabilities];
   }
+  const selectedProviders = collectSelectedProviderPreferences({
+    items: enabledCapabilities,
+    getCapabilityId: (capability) => capability.manifest.providesFor,
+    getProviderId: (capability) => capability.id,
+    selectedProviderIds: selected
+  });
+  const selectionCapabilities = createProviderSelectionAwareCapabilities(
+    enabledCapabilities,
+    selectedProviders
+  );
   const catalog = createDescriptorCatalog({
-    descriptors: enabledCapabilities.map((capability) => capability.manifest)
+    descriptors: selectionCapabilities.map((capability) => capability.manifest),
+    relationDescriptors: [
+      ...defaultCapabilityRelationDescriptors,
+      ...options.relationDescriptors ?? []
+    ]
   });
   const selection = createCompositionSelection({
     catalog,
-    selected: [...options.selected ?? []],
+    selected: [...selected],
     baseDescriptors: [...options.baseDescriptors ?? []],
-    ...options.policy ? { policy: options.policy } : {}
+    policy: createCapabilityCompositionPolicy(options.policy)
   });
   const selectedIds = new Set(selection.getResolved());
-  return enabledCapabilities.filter((capability) => selectedIds.has(capability.id));
+  return selectionCapabilities.filter((capability) => selectedIds.has(capability.id));
+}
+function createProviderSelectionAwareCapabilities(capabilities, selectedProviders) {
+  if (!Object.keys(selectedProviders).length) return [...capabilities];
+  return capabilities.map((capability) => {
+    const manifest = { ...capability.manifest };
+    const preferences = resolveSelectedProviderRelationPreferences({
+      providerId: capability.id,
+      defaultFor: manifest.defaultFor,
+      providerPreferences: manifest.providerPreferences,
+      selectedProviders
+    });
+    delete manifest.defaultFor;
+    delete manifest.providerPreferences;
+    return {
+      ...capability,
+      manifest: {
+        ...manifest,
+        ...preferences
+      }
+    };
+  });
+}
+function resolveSelectionSeed(options) {
+  return resolveCapabilitySelectionSeed(options);
+}
+function resolveCapabilitySelectionSeed(options) {
+  if (options.selected?.length) return [...options.selected];
+  if (options.selectionSeed === false) return [...options.defaultSelection ?? []];
+  const seedOptions = options.selectionSeed ?? {};
+  const selected = resolveDescriptorSelectionSeed({
+    argv: seedOptions.argv ?? process.argv,
+    env: seedOptions.env ?? process.env,
+    key: seedOptions.key ?? "capability",
+    ...seedOptions.cliKeys ? { cliKeys: seedOptions.cliKeys } : {},
+    ...seedOptions.envKeys ? { envKeys: seedOptions.envKeys } : {}
+  });
+  return selected.length ? selected : [...options.defaultSelection ?? []];
 }
-function renderCapabilityModule(capabilities) {
+function renderCapabilityModule(capabilities, selected = []) {
   const imports = capabilities.map(
     (capability) => `import { capability as ${capability.variableName} } from '${capability.importSpecifier}'`
   ).join("\n");
   const variables = capabilities.map((capability) => `  ${capability.variableName},`).join("\n");
+  const capabilityIds = capabilities.map((capability) => capability.id);
   return `${imports}
 
+export const selectedCapabilityIds = ${JSON.stringify([...selected])}
+
+export const resolvedCapabilityIds = ${JSON.stringify(capabilityIds)}
+
 export const capabilityModules = [
 ${variables}
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorion-org/react",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "React capability runtime and Vite helpers for LORION descriptor-based applications.",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,10 @@
   },
   "exports": {
     ".": {
+      "lorion-source": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
@@ -32,6 +36,10 @@
       }
     },
     "./vite": {
+      "lorion-source": {
+        "types": "./src/vite.ts",
+        "default": "./src/vite.ts"
+      },
       "import": {
         "types": "./dist/vite.d.ts",
         "default": "./dist/vite.js"
@@ -44,12 +52,14 @@
   },
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    "src/**/*.ts",
+    "!src/**/*.spec.ts"
   ],
   "dependencies": {
-    "@lorion-org/composition-graph": "^1.0.0-beta.1",
-    "@lorion-org/provider-selection": "^1.0.0-beta.1",
-    "@lorion-org/descriptor-discovery": "^1.0.0-beta.1"
+    "@lorion-org/composition-graph": "^1.0.0-beta.2",
+    "@lorion-org/descriptor-discovery": "^1.0.0-beta.2",
+    "@lorion-org/provider-selection": "^1.0.0-beta.2"
   },
   "peerDependencies": {
     "react": "^19.0.0"
@@ -80,8 +90,8 @@
     "clean": "rimraf coverage dist tsconfig.tsbuildinfo",
     "lint": "eslint src --ext .ts",
     "package:check": "pnpm build && pnpm pack --dry-run && publint",
-    "build:playground": "vite build --config playground/vite.config.ts",
-    "dev:playground": "vite dev --config playground/vite.config.ts --host 0.0.0.0",
+    "build:playground": "node ../../tools/run-source-condition.mjs vite build --config playground/vite.config.ts --",
+    "dev:playground": "node ../../tools/run-source-condition.mjs vite dev --config playground/vite.config.ts --host 0.0.0.0 --",
     "test": "vitest run --root ../.. --config vitest.config.mts packages/react/src/index.spec.ts packages/react/src/vite.spec.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "typecheck:playground": "tsc -p playground/tsconfig.json --noEmit"

package/src/index.ts

@@ -0,0 +1,222 @@
+import { createContext, createElement, useContext, type ReactElement, type ReactNode } from 'react';
+import {
+  assertKnownDescriptorIds,
+  createDescriptorCatalog,
+  type Descriptor,
+  type DescriptorCatalog,
+} from '@lorion-org/composition-graph';
+import {
+  collectProviderDefaults,
+  collectProviderPreferences,
+  resolveItemProviderSelection,
+  type ProviderPreferenceMap,
+  type ProviderSelectionResolution,
+} from '@lorion-org/provider-selection';
+import { defaultCapabilityRelationDescriptors } from './relations';
+
+export {
+  createCapabilityCompositionPolicy,
+  defaultCapabilityRelationDescriptors,
+  defaultCapabilityResolutionRelations,
+} from './relations';
+
+export type CapabilityManifest = Descriptor & {
+  defaultFor?: string | string[];
+  description?: string;
+  providerPreferences?: ProviderPreferenceMap;
+};
+
+export type ExtensionPoint<T> = {
+  id: string;
+  readonly value?: T;
+};
+
+export type CapabilityContribution<T = unknown> = {
+  extensionPoint: ExtensionPoint<T>;
+  values: readonly T[];
+};
+
+export type RuntimeCapability = {
+  id: string;
+  manifest: CapabilityManifest;
+  contributions?: readonly CapabilityContribution[];
+};
+
+export type CapabilityRuntime = {
+  capabilities: readonly RuntimeCapability[];
+  catalog: DescriptorCatalog;
+  getContributions: <T>(extensionPoint: ExtensionPoint<T>) => T[];
+};
+
+export type ContributionContract<T> = {
+  define: (values: readonly T[]) => CapabilityContribution<T>;
+  extensionPoint: ExtensionPoint<T>;
+  get: (runtime: CapabilityRuntime) => T[];
+  use: () => T[];
+};
+
+export function defineExtensionPoint<T>(id: string): ExtensionPoint<T> {
+  return { id };
+}
+
+export function defineContribution<T>(
+  extensionPoint: ExtensionPoint<T>,
+  values: readonly T[],
+): CapabilityContribution<T> {
+  return { extensionPoint, values };
+}
+
+export function createContributionContract<T>(id: string): ContributionContract<T> {
+  const extensionPoint = defineExtensionPoint<T>(id);
+
+  return {
+    extensionPoint,
+    define: (values) => defineContribution(extensionPoint, values),
+    get: (runtime) => runtime.getContributions(extensionPoint),
+    use: () => useCapabilityRuntime().getContributions(extensionPoint),
+  };
+}
+
+export type CapabilityProviderSelectionOptions = {
+  configuredProviders?: ProviderPreferenceMap;
+  fallbackProviders?: ProviderPreferenceMap;
+  selectedProviders?: ProviderPreferenceMap;
+};
+
+export function getCapabilityProviderSelection(
+  runtime: CapabilityRuntime,
+  options: CapabilityProviderSelectionOptions = {},
+): ProviderSelectionResolution {
+  const descriptors = runtime.catalog.getAllDescriptors();
+  const descriptorPreferences = collectProviderPreferences({
+    items: descriptors,
+    getProviderPreferences: (descriptor) => descriptor.providerPreferences,
+  });
+  const providerDefaults = collectProviderDefaults({
+    items: descriptors,
+    getDefaultFor: (descriptor) => descriptor.defaultFor,
+    getProviderId: (descriptor) => descriptor.id,
+  });
+  const configuredProviders = options.configuredProviders ?? {};
+  const selectedProviders = options.selectedProviders ?? {};
+  const fallbackProviders = {
+    ...providerDefaults,
+    ...descriptorPreferences,
+    ...(options.fallbackProviders ?? {}),
+  };
+  const resolution = resolveItemProviderSelection({
+    items: descriptors,
+    getCapabilityId: (descriptor) => descriptor.providesFor,
+    getProviderId: (descriptor) => descriptor.id,
+    configuredProviders,
+    fallbackProviders,
+    selectedProviders,
+  });
+
+  return {
+    excludedProviderIds: resolution.excludedProviderIds,
+    mismatches: resolution.mismatches,
+    selections: resolution.selections,
+  };
+}
+
+export function defineCapability(capability: RuntimeCapability): RuntimeCapability {
+  if (capability.id !== capability.manifest.id) {
+    throw new Error(
+      `Capability "${capability.id}" must match capability.json id "${capability.manifest.id}".`,
+    );
+  }
+
+  return capability;
+}
+
+export function createCapabilityRuntime(
+  capabilities: readonly RuntimeCapability[],
+): CapabilityRuntime {
+  const enabledCapabilities = capabilities.filter(
+    (capability) => capability.manifest.disabled !== true,
+  );
+  const catalog = createCapabilityCatalog(enabledCapabilities);
+
+  assertUniqueCapabilities(enabledCapabilities);
+  assertKnownCapabilityDependencies(enabledCapabilities, catalog);
+
+  const contributions = collectContributions(enabledCapabilities);
+
+  return {
+    capabilities: Object.freeze([...enabledCapabilities]),
+    catalog,
+    getContributions: <T>(extensionPoint: ExtensionPoint<T>) =>
+      [...(contributions.get(extensionPoint.id) ?? [])] as T[],
+  };
+}
+
+const CapabilityRuntimeContext = createContext<CapabilityRuntime | null>(null);
+
+export type CapabilityRuntimeProviderProps = {
+  children: ReactNode;
+  runtime: CapabilityRuntime;
+};
+
+export function CapabilityRuntimeProvider({
+  children,
+  runtime,
+}: CapabilityRuntimeProviderProps): ReactElement {
+  return createElement(CapabilityRuntimeContext.Provider, { value: runtime }, children);
+}
+
+export function useCapabilityRuntime(): CapabilityRuntime {
+  const runtime = useContext(CapabilityRuntimeContext);
+
+  if (!runtime) {
+    throw new Error('useCapabilityRuntime must be used inside CapabilityRuntimeProvider.');
+  }
+
+  return runtime;
+}
+
+function assertUniqueCapabilities(capabilities: readonly RuntimeCapability[]): void {
+  const seen = new Set<string>();
+
+  for (const capability of capabilities) {
+    if (seen.has(capability.id)) {
+      throw new Error(`Duplicate capability id "${capability.id}".`);
+    }
+
+    seen.add(capability.id);
+  }
+}
+
+function assertKnownCapabilityDependencies(
+  capabilities: readonly RuntimeCapability[],
+  catalog: DescriptorCatalog,
+): void {
+  for (const capability of capabilities) {
+    assertKnownDescriptorIds(
+      catalog.getDescriptorMap(),
+      Object.keys(capability.manifest.dependencies ?? {}),
+      `capability "${capability.id}" dependencies`,
+    );
+  }
+}
+
+function collectContributions(capabilities: readonly RuntimeCapability[]): Map<string, unknown[]> {
+  const contributions = new Map<string, unknown[]>();
+
+  for (const capability of capabilities) {
+    for (const contribution of capability.contributions ?? []) {
+      const bucket = contributions.get(contribution.extensionPoint.id) ?? [];
+      bucket.push(...contribution.values);
+      contributions.set(contribution.extensionPoint.id, bucket);
+    }
+  }
+
+  return contributions;
+}
+
+function createCapabilityCatalog(capabilities: readonly RuntimeCapability[]): DescriptorCatalog {
+  return createDescriptorCatalog({
+    descriptors: capabilities.map((capability) => capability.manifest),
+    relationDescriptors: defaultCapabilityRelationDescriptors,
+  });
+}

package/src/relations.ts

@@ -0,0 +1,37 @@
+import type { CompositionPolicy, RelationDescriptor } from '@lorion-org/composition-graph';
+
+export const defaultCapabilityResolutionRelations = [
+  'dependencies',
+  'defaultProviders',
+  'providerPreferences',
+] as const;
+
+export const defaultCapabilityRelationDescriptors: RelationDescriptor[] = [
+  {
+    direction: 'incoming',
+    field: 'defaultFor',
+    id: 'defaultProviders',
+  },
+  {
+    field: 'providerPreferences',
+    id: 'providerPreferences',
+    targetMode: 'values',
+  },
+];
+
+export function createCapabilityCompositionPolicy(
+  policy?: Partial<CompositionPolicy>,
+): Partial<CompositionPolicy> {
+  return {
+    ...policy,
+    inspectionRelationIds: policy?.inspectionRelationIds ?? [
+      ...defaultCapabilityResolutionRelations,
+    ],
+    provenanceRelationIds: policy?.provenanceRelationIds ?? [
+      ...defaultCapabilityResolutionRelations,
+    ],
+    resolutionRelationIds: policy?.resolutionRelationIds ?? [
+      ...defaultCapabilityResolutionRelations,
+    ],
+  };
+}