@lorion-org/descriptor-discovery 1.0.0-beta.0 → 1.0.0-beta.2

package/LICENSE

@@ -1,21 +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.
+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

@@ -31,11 +31,11 @@ pnpm add @lorion-org/descriptor-discovery @lorion-org/composition-graph
 ## Directory shape
 
 ```text
-descriptors/
-  billing/
-    descriptor.json
-  dashboard/
-    descriptor.json
+layer-extensions/
+  checkout/
+    extension.json
+  shops/
+    extension.json
 ```
 
 ## Basic example
@@ -44,7 +44,8 @@ descriptors/
 import { discoverDescriptors } from '@lorion-org/descriptor-discovery';
 
 const discovered = discoverDescriptors({
-  roots: ['./descriptors'],
+  cwd: './playground',
+  descriptorPaths: ['layer-extensions/*/extension.json'],
 });
 
 const descriptors = discovered.map((entry) => entry.descriptor);
@@ -60,9 +61,8 @@ id when the descriptor does not define one.
 import { discoverDescriptors } from '@lorion-org/descriptor-discovery';
 
 const discovered = discoverDescriptors({
-  roots: ['./modules'],
-  descriptorFileName: 'module.json',
-  idField: 'name',
+  cwd: './playground',
+  descriptorPaths: ['layer-extensions/*/extension.json'],
   nestedField: 'bundles',
 });
 
@@ -79,7 +79,9 @@ import { createDescriptorCatalog } from '@lorion-org/composition-graph';
 import { discoverDescriptors } from '@lorion-org/descriptor-discovery';
 
 const discovered = discoverDescriptors({
-  roots: ['./descriptors'],
+  cwd: './playground',
+  descriptorPaths: ['layer-extensions/*/extension.json'],
+  nestedField: 'bundles',
 });
 
 const catalog = createDescriptorCatalog({
@@ -87,7 +89,7 @@ const catalog = createDescriptorCatalog({
 });
 
 catalog.resolveSelection({
-  selected: ['billing'],
+  selected: ['default'],
 });
 ```
 

package/dist/{chunk-PIMQRGRQ.js → chunk-MUTMPDXM.js}

@@ -21,8 +21,19 @@ var descriptor_schema_default = {
         },
         version: { $ref: "#/$defs/semver" },
         providesFor: {
-          type: "string",
-          minLength: 1
+          oneOf: [
+            {
+              type: "string",
+              minLength: 1
+            },
+            {
+              type: "array",
+              items: {
+                type: "string",
+                minLength: 1
+              }
+            }
+          ]
         },
         capabilities: {
           type: "array",
@@ -33,7 +44,22 @@ var descriptor_schema_default = {
         },
         dependencies: { $ref: "#/$defs/dependencyMap" },
         disabled: { type: "boolean" },
-        location: { type: "string" }
+        location: { type: "string" },
+        defaultFor: {
+          oneOf: [
+            {
+              type: "string",
+              minLength: 1
+            },
+            {
+              type: "array",
+              items: {
+                type: "string",
+                minLength: 1
+              }
+            }
+          ]
+        }
       },
       required: ["id", "version"],
       additionalProperties: true

package/dist/index.cjs

@@ -62,8 +62,19 @@ var descriptor_schema_default = {
         },
         version: { $ref: "#/$defs/semver" },
         providesFor: {
-          type: "string",
-          minLength: 1
+          oneOf: [
+            {
+              type: "string",
+              minLength: 1
+            },
+            {
+              type: "array",
+              items: {
+                type: "string",
+                minLength: 1
+              }
+            }
+          ]
         },
         capabilities: {
           type: "array",
@@ -74,7 +85,22 @@ var descriptor_schema_default = {
         },
         dependencies: { $ref: "#/$defs/dependencyMap" },
         disabled: { type: "boolean" },
-        location: { type: "string" }
+        location: { type: "string" },
+        defaultFor: {
+          oneOf: [
+            {
+              type: "string",
+              minLength: 1
+            },
+            {
+              type: "array",
+              items: {
+                type: "string",
+                minLength: 1
+              }
+            }
+          ]
+        }
       },
       required: ["id", "version"],
       additionalProperties: true

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   descriptorSchema
-} from "./chunk-PIMQRGRQ.js";
+} from "./chunk-MUTMPDXM.js";
 
 // src/index.ts
 import { existsSync, readFileSync, readdirSync } from "fs";

package/dist/schema.cjs

@@ -47,8 +47,19 @@ var descriptor_schema_default = {
         },
         version: { $ref: "#/$defs/semver" },
         providesFor: {
-          type: "string",
-          minLength: 1
+          oneOf: [
+            {
+              type: "string",
+              minLength: 1
+            },
+            {
+              type: "array",
+              items: {
+                type: "string",
+                minLength: 1
+              }
+            }
+          ]
         },
         capabilities: {
           type: "array",
@@ -59,7 +70,22 @@ var descriptor_schema_default = {
         },
         dependencies: { $ref: "#/$defs/dependencyMap" },
         disabled: { type: "boolean" },
-        location: { type: "string" }
+        location: { type: "string" },
+        defaultFor: {
+          oneOf: [
+            {
+              type: "string",
+              minLength: 1
+            },
+            {
+              type: "array",
+              items: {
+                type: "string",
+                minLength: 1
+              }
+            }
+          ]
+        }
       },
       required: ["id", "version"],
       additionalProperties: true

package/dist/schema.js

@@ -1,6 +1,6 @@
 import {
   descriptorSchema
-} from "./chunk-PIMQRGRQ.js";
+} from "./chunk-MUTMPDXM.js";
 export {
   descriptorSchema
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorion-org/descriptor-discovery",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.2",
   "description": "Node-based descriptor discovery and normalization helpers.",
   "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"
@@ -32,6 +36,10 @@
       }
     },
     "./schema": {
+      "lorion-source": {
+        "types": "./src/schema.ts",
+        "default": "./src/schema.ts"
+      },
       "import": {
         "types": "./dist/schema.d.ts",
         "default": "./dist/schema.js"
@@ -44,7 +52,10 @@
   },
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    "src/**/*.ts",
+    "src/**/*.json",
+    "!src/**/*.spec.ts"
   ],
   "keywords": [
     "descriptor",
@@ -56,13 +67,13 @@
     "node": "^20.19.0 || >=22.12.0"
   },
   "peerDependencies": {
-    "@lorion-org/composition-graph": "^1.0.0-beta.0"
+    "@lorion-org/composition-graph": "^1.0.0-beta.2"
   },
   "dependencies": {
     "ajv": "^8.17.1"
   },
   "devDependencies": {
-    "@lorion-org/composition-graph": "1.0.0-beta.0"
+    "@lorion-org/composition-graph": "1.0.0-beta.2"
   },
   "scripts": {
     "build": "tsup src/index.ts src/schema.ts --format esm,cjs --dts",

package/src/descriptor.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lorion.dev/schemas/descriptor.schema.json",
+  "$ref": "#/$defs/descriptor",
+  "$defs": {
+    "semver": {
+      "type": "string",
+      "pattern": "^(\\^|~)?\\d+\\.\\d+\\.\\d+$"
+    },
+    "dependencyMap": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/semver" }
+    },
+    "descriptor": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": { "$ref": "#/$defs/semver" },
+        "providesFor": {
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          ]
+        },
+        "capabilities": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "dependencies": { "$ref": "#/$defs/dependencyMap" },
+        "disabled": { "type": "boolean" },
+        "location": { "type": "string" },
+        "defaultFor": {
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          ]
+        }
+      },
+      "required": ["id", "version"],
+      "additionalProperties": true
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,336 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, dirname, join, resolve as resolvePath } from 'node:path';
+
+import Ajv, { type ErrorObject, type Options as AjvOptions } from 'ajv';
+import type { Descriptor } from '@lorion-org/composition-graph';
+
+export { descriptorSchema, type JsonSchemaObject } from './schema';
+
+export type RawDescriptor = Omit<Descriptor, 'id'> & {
+  id?: string;
+};
+
+export type DiscoveredDescriptor = {
+  id: string;
+  cwd: string;
+  descriptorPath: string;
+  descriptor: Descriptor;
+};
+
+export type DescriptorSchemaValidationTarget = {
+  descriptorPath: string;
+};
+
+export type DescriptorSchemaValidationErrorFormatter = (
+  target: DescriptorSchemaValidationTarget,
+  validationError: ErrorObject,
+) => Error;
+
+export type DescriptorValidationOptions = {
+  ajvOptions?: AjvOptions;
+  formatError?: DescriptorSchemaValidationErrorFormatter;
+  schema: object;
+};
+
+export type ExpandNestedDescriptorsInput = {
+  rawDescriptor: RawDescriptor & Record<string, unknown>;
+  fallbackId: string;
+  idField?: string;
+  nestedField?: string;
+};
+
+export type DiscoverDescriptorsInput = {
+  cwd?: string;
+  descriptorPaths?: string[];
+  roots?: string[];
+  descriptorFileName?: string;
+  idField?: string;
+  maxDepth?: number;
+  nestedField?: string;
+  validation?: false | DescriptorValidationOptions;
+};
+
+function formatDescriptorSchemaValidationError(
+  target: DescriptorSchemaValidationTarget,
+  validationError: ErrorObject,
+): Error {
+  const jsonPath = validationError.instancePath || '/';
+  const ajvError = `${validationError.keyword}${validationError.message ? `: ${validationError.message}` : ''}`;
+
+  return new Error(
+    [
+      'Descriptor schema validation failed.',
+      `File: ${target.descriptorPath}`,
+      `JSON path: ${jsonPath}`,
+      `Schema error: ${ajvError}`,
+    ].join('\n'),
+  );
+}
+
+function createDescriptorValidator(
+  options: false | DescriptorValidationOptions | undefined,
+): ((target: DescriptorSchemaValidationTarget, descriptor: object) => void) | undefined {
+  if (!options) return undefined;
+
+  const ajv = new Ajv({
+    strict: false,
+    allErrors: false,
+    ...options.ajvOptions,
+  });
+  const validate = ajv.compile(options.schema);
+  const formatError = options.formatError ?? formatDescriptorSchemaValidationError;
+
+  return (target, descriptor) => {
+    if (validate(descriptor)) return;
+
+    const validationError = validate.errors?.[0];
+    if (validationError) throw formatError(target, validationError);
+
+    throw new Error(`Descriptor schema validation failed: "${target.descriptorPath}"`);
+  };
+}
+
+function resolveDescriptorId(input: {
+  rawDescriptor: Record<string, unknown>;
+  idField: string;
+  fallbackId?: string;
+  label: string;
+}): string {
+  const configuredId = input.rawDescriptor[input.idField];
+
+  if (typeof configuredId === 'string' && configuredId.trim()) {
+    return configuredId.trim();
+  }
+
+  if (typeof input.fallbackId === 'string' && input.fallbackId.trim()) {
+    return input.fallbackId.trim();
+  }
+
+  throw new Error(`${input.label} is missing a non-empty "${input.idField}" field`);
+}
+
+function getNestedDescriptors(input: {
+  rawDescriptor: Record<string, unknown>;
+  nestedField?: string;
+  parentId: string;
+}): Array<RawDescriptor & Record<string, unknown>> {
+  if (!input.nestedField) return [];
+
+  const nestedValue = input.rawDescriptor[input.nestedField];
+
+  if (nestedValue === undefined) return [];
+  if (!Array.isArray(nestedValue))
+    throw new Error(`Descriptor "${input.parentId}" field "${input.nestedField}" must be an array`);
+
+  return nestedValue.map((entry, index) => {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+      throw new Error(
+        `Descriptor "${input.parentId}" field "${input.nestedField}" contains an invalid entry at index ${index}`,
+      );
+    }
+
+    return entry as RawDescriptor & Record<string, unknown>;
+  });
+}
+
+function normalizeDescriptor(input: {
+  rawDescriptor: RawDescriptor & Record<string, unknown>;
+  id: string;
+  nestedField?: string;
+}): Descriptor {
+  const version =
+    typeof input.rawDescriptor.version === 'string' && input.rawDescriptor.version.trim()
+      ? input.rawDescriptor.version
+      : '0.0.0';
+
+  if (input.nestedField) {
+    const descriptor = { ...input.rawDescriptor };
+
+    delete descriptor[input.nestedField];
+
+    return {
+      ...descriptor,
+      id: input.id,
+      version,
+    };
+  }
+
+  return {
+    ...input.rawDescriptor,
+    id: input.id,
+    version,
+  };
+}
+
+export function expandNestedDescriptors(input: ExpandNestedDescriptorsInput): Descriptor[] {
+  const idField: string = input.idField ?? 'id';
+  const rootId = resolveDescriptorId({
+    rawDescriptor: input.rawDescriptor,
+    idField,
+    fallbackId: input.fallbackId,
+    label: 'Descriptor',
+  });
+  const nestedDescriptors = getNestedDescriptors({
+    rawDescriptor: input.rawDescriptor,
+    parentId: rootId,
+    ...(input.nestedField ? { nestedField: input.nestedField } : {}),
+  });
+  const descriptors: Descriptor[] = [
+    normalizeDescriptor({
+      rawDescriptor: input.rawDescriptor,
+      id: rootId,
+      ...(input.nestedField ? { nestedField: input.nestedField } : {}),
+    }),
+  ];
+
+  for (const nestedDescriptor of nestedDescriptors) {
+    const nestedId = resolveDescriptorId({
+      rawDescriptor: nestedDescriptor,
+      idField,
+      label: `Nested descriptor in "${rootId}"`,
+    });
+    const nestedChildren = getNestedDescriptors({
+      rawDescriptor: nestedDescriptor,
+      parentId: nestedId,
+      ...(input.nestedField ? { nestedField: input.nestedField } : {}),
+    });
+
+    if (nestedChildren.length) {
+      throw new Error(`Nested descriptors are not supported inside descriptor "${nestedId}"`);
+    }
+
+    descriptors.push(
+      normalizeDescriptor({
+        rawDescriptor: nestedDescriptor,
+        id: nestedId,
+        ...(input.nestedField ? { nestedField: input.nestedField } : {}),
+      }),
+    );
+  }
+
+  return descriptors;
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function createGlobSegmentRegex(segment: string): RegExp {
+  return new RegExp(`^${segment.split('*').map(escapeRegex).join('[^/\\\\]*')}$`);
+}
+
+function splitPattern(pattern: string): string[] {
+  return pattern.split(/[\\/]+/).filter(Boolean);
+}
+
+function expandDescriptorPathPattern(input: { cwd: string; pattern: string }): string[] {
+  const segments = splitPattern(input.pattern);
+  const visit = (currentDir: string, index: number): string[] => {
+    const segment = segments[index];
+    if (!segment) return [];
+
+    const isLast = index === segments.length - 1;
+
+    if (!segment.includes('*')) {
+      const nextPath = join(currentDir, segment);
+
+      if (isLast) return existsSync(nextPath) ? [nextPath] : [];
+      if (!existsSync(nextPath)) return [];
+
+      return visit(nextPath, index + 1);
+    }
+
+    if (!existsSync(currentDir)) return [];
+
+    const matcher = createGlobSegmentRegex(segment);
+
+    return readdirSync(currentDir, { withFileTypes: true })
+      .filter((entry) => entry.name !== 'node_modules' && matcher.test(entry.name))
+      .flatMap((entry) => {
+        const nextPath = join(currentDir, entry.name);
+
+        if (isLast) return entry.isFile() ? [nextPath] : [];
+        return entry.isDirectory() ? visit(nextPath, index + 1) : [];
+      });
+  };
+
+  return visit(resolvePath(input.cwd), 0);
+}
+
+function discoverDescriptorFiles(input: { cwd: string; descriptorPaths: string[] }): string[] {
+  return [
+    ...new Set(
+      input.descriptorPaths.flatMap((pattern) =>
+        expandDescriptorPathPattern({
+          cwd: input.cwd,
+          pattern,
+        }),
+      ),
+    ),
+  ].sort();
+}
+
+function discoverDescriptorFilesFromRoots(input: {
+  descriptorFileName: string;
+  maxDepth: number;
+  roots: string[];
+}): string[] {
+  const discovered: string[] = [];
+  const visit = (root: string, depth: number): void => {
+    if (depth > input.maxDepth || !existsSync(root)) return;
+
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name === 'node_modules') continue;
+
+      const cwd: string = join(root, entry.name);
+      const descriptorPath: string = join(cwd, input.descriptorFileName);
+
+      if (existsSync(descriptorPath)) discovered.push(descriptorPath);
+
+      visit(cwd, depth + 1);
+    }
+  };
+
+  for (const root of input.roots) {
+    visit(resolvePath(root), 1);
+  }
+
+  return [...new Set(discovered)].sort();
+}
+
+export function discoverDescriptors(input: DiscoverDescriptorsInput): DiscoveredDescriptor[] {
+  const descriptorFileName: string = input.descriptorFileName ?? 'descriptor.json';
+  const idField: string = input.idField ?? 'id';
+  const maxDepth = input.maxDepth ?? 1;
+  const validateDescriptor = createDescriptorValidator(input.validation);
+  const descriptorPaths = input.descriptorPaths?.length
+    ? discoverDescriptorFiles({
+        cwd: input.cwd ?? '',
+        descriptorPaths: input.descriptorPaths,
+      })
+    : discoverDescriptorFilesFromRoots({
+        descriptorFileName,
+        maxDepth,
+        roots: input.roots ?? [],
+      });
+
+  return descriptorPaths.flatMap((descriptorPath) => {
+    const cwd = dirname(descriptorPath);
+    const rawDescriptor = JSON.parse(readFileSync(descriptorPath, 'utf8')) as RawDescriptor &
+      Record<string, unknown>;
+
+    validateDescriptor?.({ descriptorPath }, rawDescriptor);
+
+    return expandNestedDescriptors({
+      rawDescriptor,
+      fallbackId: basename(cwd),
+      idField,
+      ...(input.nestedField ? { nestedField: input.nestedField } : {}),
+    }).map((descriptor) => ({
+      id: descriptor.id,
+      cwd,
+      descriptorPath,
+      descriptor,
+    }));
+  });
+}

package/src/schema.ts

@@ -0,0 +1,5 @@
+import descriptorSchemaData from './descriptor.schema.json';
+
+export type JsonSchemaObject = Record<string, unknown>;
+
+export const descriptorSchema = descriptorSchemaData as JsonSchemaObject;