@lorion-org/descriptor-discovery 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,102 @@
+# @lorion-org/descriptor-discovery
+
+Disk-based discovery and normalization helpers for descriptor files.
+
+This package is the Node-side companion to `@lorion-org/composition-graph`.
+It is responsible for reading descriptor documents from disk and flattening
+optional nested descriptor authoring into the flat `Descriptor[]` shape that
+the graph core expects.
+
+## Install
+
+```shell
+pnpm add @lorion-org/descriptor-discovery @lorion-org/composition-graph
+```
+
+## What it is
+
+- a Node-side descriptor file discovery helper
+- a normalization layer for descriptor ids and versions
+- a small flattening helper for one level of nested descriptor authoring
+- a bridge from files on disk to `@lorion-org/composition-graph`
+
+## What it is not
+
+- not a graph builder
+- not a package manager
+- not a framework adapter
+- not a recursive schema language
+- not a watcher or live reload system
+
+## Directory shape
+
+```text
+descriptors/
+  billing/
+    descriptor.json
+  dashboard/
+    descriptor.json
+```
+
+## Basic example
+
+```ts
+import { discoverDescriptors } from '@lorion-org/descriptor-discovery';
+
+const discovered = discoverDescriptors({
+  roots: ['./descriptors'],
+});
+
+const descriptors = discovered.map((entry) => entry.descriptor);
+```
+
+`discoverDescriptors()` scans each direct child directory below every root and
+loads a descriptor file when it exists. The directory name is used as a fallback
+id when the descriptor does not define one.
+
+## Example: custom descriptor fields
+
+```ts
+import { discoverDescriptors } from '@lorion-org/descriptor-discovery';
+
+const discovered = discoverDescriptors({
+  roots: ['./modules'],
+  descriptorFileName: 'module.json',
+  idField: 'name',
+  nestedField: 'bundles',
+});
+
+discovered.map((entry) => entry.id);
+```
+
+Nested descriptors are flattened into the same output list as their parent.
+Only one nesting level is supported so the resulting graph input stays explicit.
+
+## Example: use with composition graph
+
+```ts
+import { createDescriptorCatalog } from '@lorion-org/composition-graph';
+import { discoverDescriptors } from '@lorion-org/descriptor-discovery';
+
+const discovered = discoverDescriptors({
+  roots: ['./descriptors'],
+});
+
+const catalog = createDescriptorCatalog({
+  descriptors: discovered.map((entry) => entry.descriptor),
+});
+
+catalog.resolveSelection({
+  selected: ['billing'],
+});
+```
+
+## Local commands
+
+```shell
+cd packages/descriptor-discovery
+pnpm build
+pnpm test
+pnpm typecheck
+pnpm package:check
+```

package/dist/chunk-PIMQRGRQ.js

@@ -0,0 +1,49 @@
+// src/descriptor.schema.json
+var descriptor_schema_default = {
+  $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: {
+          type: "string",
+          minLength: 1
+        },
+        capabilities: {
+          type: "array",
+          items: {
+            type: "string",
+            minLength: 1
+          }
+        },
+        dependencies: { $ref: "#/$defs/dependencyMap" },
+        disabled: { type: "boolean" },
+        location: { type: "string" }
+      },
+      required: ["id", "version"],
+      additionalProperties: true
+    }
+  }
+};
+
+// src/schema.ts
+var descriptorSchema = descriptor_schema_default;
+
+export {
+  descriptorSchema
+};

package/dist/index.cjs

@@ -0,0 +1,298 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  descriptorSchema: () => descriptorSchema,
+  discoverDescriptors: () => discoverDescriptors,
+  expandNestedDescriptors: () => expandNestedDescriptors
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_ajv = __toESM(require("ajv"), 1);
+
+// src/descriptor.schema.json
+var descriptor_schema_default = {
+  $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: {
+          type: "string",
+          minLength: 1
+        },
+        capabilities: {
+          type: "array",
+          items: {
+            type: "string",
+            minLength: 1
+          }
+        },
+        dependencies: { $ref: "#/$defs/dependencyMap" },
+        disabled: { type: "boolean" },
+        location: { type: "string" }
+      },
+      required: ["id", "version"],
+      additionalProperties: true
+    }
+  }
+};
+
+// src/schema.ts
+var descriptorSchema = descriptor_schema_default;
+
+// src/index.ts
+function formatDescriptorSchemaValidationError(target, validationError) {
+  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) {
+  if (!options) return void 0;
+  const ajv = new import_ajv.default({
+    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) {
+  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) {
+  if (!input.nestedField) return [];
+  const nestedValue = input.rawDescriptor[input.nestedField];
+  if (nestedValue === void 0) 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;
+  });
+}
+function normalizeDescriptor(input) {
+  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
+  };
+}
+function expandNestedDescriptors(input) {
+  const idField = 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 = [
+    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) {
+  return value.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+}
+function createGlobSegmentRegex(segment) {
+  return new RegExp(`^${segment.split("*").map(escapeRegex).join("[^/\\\\]*")}$`);
+}
+function splitPattern(pattern) {
+  return pattern.split(/[\\/]+/).filter(Boolean);
+}
+function expandDescriptorPathPattern(input) {
+  const segments = splitPattern(input.pattern);
+  const visit = (currentDir, index) => {
+    const segment = segments[index];
+    if (!segment) return [];
+    const isLast = index === segments.length - 1;
+    if (!segment.includes("*")) {
+      const nextPath = (0, import_node_path.join)(currentDir, segment);
+      if (isLast) return (0, import_node_fs.existsSync)(nextPath) ? [nextPath] : [];
+      if (!(0, import_node_fs.existsSync)(nextPath)) return [];
+      return visit(nextPath, index + 1);
+    }
+    if (!(0, import_node_fs.existsSync)(currentDir)) return [];
+    const matcher = createGlobSegmentRegex(segment);
+    return (0, import_node_fs.readdirSync)(currentDir, { withFileTypes: true }).filter((entry) => entry.name !== "node_modules" && matcher.test(entry.name)).flatMap((entry) => {
+      const nextPath = (0, import_node_path.join)(currentDir, entry.name);
+      if (isLast) return entry.isFile() ? [nextPath] : [];
+      return entry.isDirectory() ? visit(nextPath, index + 1) : [];
+    });
+  };
+  return visit((0, import_node_path.resolve)(input.cwd), 0);
+}
+function discoverDescriptorFiles(input) {
+  return [
+    ...new Set(
+      input.descriptorPaths.flatMap(
+        (pattern) => expandDescriptorPathPattern({
+          cwd: input.cwd,
+          pattern
+        })
+      )
+    )
+  ].sort();
+}
+function discoverDescriptorFilesFromRoots(input) {
+  const discovered = [];
+  const visit = (root, depth) => {
+    if (depth > input.maxDepth || !(0, import_node_fs.existsSync)(root)) return;
+    for (const entry of (0, import_node_fs.readdirSync)(root, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name === "node_modules") continue;
+      const cwd = (0, import_node_path.join)(root, entry.name);
+      const descriptorPath = (0, import_node_path.join)(cwd, input.descriptorFileName);
+      if ((0, import_node_fs.existsSync)(descriptorPath)) discovered.push(descriptorPath);
+      visit(cwd, depth + 1);
+    }
+  };
+  for (const root of input.roots) {
+    visit((0, import_node_path.resolve)(root), 1);
+  }
+  return [...new Set(discovered)].sort();
+}
+function discoverDescriptors(input) {
+  const descriptorFileName = input.descriptorFileName ?? "descriptor.json";
+  const idField = 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 = (0, import_node_path.dirname)(descriptorPath);
+    const rawDescriptor = JSON.parse((0, import_node_fs.readFileSync)(descriptorPath, "utf8"));
+    validateDescriptor?.({ descriptorPath }, rawDescriptor);
+    return expandNestedDescriptors({
+      rawDescriptor,
+      fallbackId: (0, import_node_path.basename)(cwd),
+      idField,
+      ...input.nestedField ? { nestedField: input.nestedField } : {}
+    }).map((descriptor) => ({
+      id: descriptor.id,
+      cwd,
+      descriptorPath,
+      descriptor
+    }));
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  descriptorSchema,
+  discoverDescriptors,
+  expandNestedDescriptors
+});

package/dist/index.d.cts

@@ -0,0 +1,42 @@
+import { ErrorObject, Options } from 'ajv';
+import { Descriptor } from '@lorion-org/composition-graph';
+export { JsonSchemaObject, descriptorSchema } from './schema.cjs';
+
+type RawDescriptor = Omit<Descriptor, 'id'> & {
+    id?: string;
+};
+type DiscoveredDescriptor = {
+    id: string;
+    cwd: string;
+    descriptorPath: string;
+    descriptor: Descriptor;
+};
+type DescriptorSchemaValidationTarget = {
+    descriptorPath: string;
+};
+type DescriptorSchemaValidationErrorFormatter = (target: DescriptorSchemaValidationTarget, validationError: ErrorObject) => Error;
+type DescriptorValidationOptions = {
+    ajvOptions?: Options;
+    formatError?: DescriptorSchemaValidationErrorFormatter;
+    schema: object;
+};
+type ExpandNestedDescriptorsInput = {
+    rawDescriptor: RawDescriptor & Record<string, unknown>;
+    fallbackId: string;
+    idField?: string;
+    nestedField?: string;
+};
+type DiscoverDescriptorsInput = {
+    cwd?: string;
+    descriptorPaths?: string[];
+    roots?: string[];
+    descriptorFileName?: string;
+    idField?: string;
+    maxDepth?: number;
+    nestedField?: string;
+    validation?: false | DescriptorValidationOptions;
+};
+declare function expandNestedDescriptors(input: ExpandNestedDescriptorsInput): Descriptor[];
+declare function discoverDescriptors(input: DiscoverDescriptorsInput): DiscoveredDescriptor[];
+
+export { type DescriptorSchemaValidationErrorFormatter, type DescriptorSchemaValidationTarget, type DescriptorValidationOptions, type DiscoverDescriptorsInput, type DiscoveredDescriptor, type ExpandNestedDescriptorsInput, type RawDescriptor, discoverDescriptors, expandNestedDescriptors };

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { ErrorObject, Options } from 'ajv';
+import { Descriptor } from '@lorion-org/composition-graph';
+export { JsonSchemaObject, descriptorSchema } from './schema.js';
+
+type RawDescriptor = Omit<Descriptor, 'id'> & {
+    id?: string;
+};
+type DiscoveredDescriptor = {
+    id: string;
+    cwd: string;
+    descriptorPath: string;
+    descriptor: Descriptor;
+};
+type DescriptorSchemaValidationTarget = {
+    descriptorPath: string;
+};
+type DescriptorSchemaValidationErrorFormatter = (target: DescriptorSchemaValidationTarget, validationError: ErrorObject) => Error;
+type DescriptorValidationOptions = {
+    ajvOptions?: Options;
+    formatError?: DescriptorSchemaValidationErrorFormatter;
+    schema: object;
+};
+type ExpandNestedDescriptorsInput = {
+    rawDescriptor: RawDescriptor & Record<string, unknown>;
+    fallbackId: string;
+    idField?: string;
+    nestedField?: string;
+};
+type DiscoverDescriptorsInput = {
+    cwd?: string;
+    descriptorPaths?: string[];
+    roots?: string[];
+    descriptorFileName?: string;
+    idField?: string;
+    maxDepth?: number;
+    nestedField?: string;
+    validation?: false | DescriptorValidationOptions;
+};
+declare function expandNestedDescriptors(input: ExpandNestedDescriptorsInput): Descriptor[];
+declare function discoverDescriptors(input: DiscoverDescriptorsInput): DiscoveredDescriptor[];
+
+export { type DescriptorSchemaValidationErrorFormatter, type DescriptorSchemaValidationTarget, type DescriptorValidationOptions, type DiscoverDescriptorsInput, type DiscoveredDescriptor, type ExpandNestedDescriptorsInput, type RawDescriptor, discoverDescriptors, expandNestedDescriptors };

package/dist/index.js

@@ -0,0 +1,217 @@
+import {
+  descriptorSchema
+} from "./chunk-PIMQRGRQ.js";
+
+// src/index.ts
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { basename, dirname, join, resolve as resolvePath } from "path";
+import Ajv from "ajv";
+function formatDescriptorSchemaValidationError(target, validationError) {
+  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) {
+  if (!options) return void 0;
+  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) {
+  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) {
+  if (!input.nestedField) return [];
+  const nestedValue = input.rawDescriptor[input.nestedField];
+  if (nestedValue === void 0) 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;
+  });
+}
+function normalizeDescriptor(input) {
+  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
+  };
+}
+function expandNestedDescriptors(input) {
+  const idField = 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 = [
+    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) {
+  return value.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+}
+function createGlobSegmentRegex(segment) {
+  return new RegExp(`^${segment.split("*").map(escapeRegex).join("[^/\\\\]*")}$`);
+}
+function splitPattern(pattern) {
+  return pattern.split(/[\\/]+/).filter(Boolean);
+}
+function expandDescriptorPathPattern(input) {
+  const segments = splitPattern(input.pattern);
+  const visit = (currentDir, index) => {
+    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) {
+  return [
+    ...new Set(
+      input.descriptorPaths.flatMap(
+        (pattern) => expandDescriptorPathPattern({
+          cwd: input.cwd,
+          pattern
+        })
+      )
+    )
+  ].sort();
+}
+function discoverDescriptorFilesFromRoots(input) {
+  const discovered = [];
+  const visit = (root, depth) => {
+    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 = join(root, entry.name);
+      const descriptorPath = 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();
+}
+function discoverDescriptors(input) {
+  const descriptorFileName = input.descriptorFileName ?? "descriptor.json";
+  const idField = 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"));
+    validateDescriptor?.({ descriptorPath }, rawDescriptor);
+    return expandNestedDescriptors({
+      rawDescriptor,
+      fallbackId: basename(cwd),
+      idField,
+      ...input.nestedField ? { nestedField: input.nestedField } : {}
+    }).map((descriptor) => ({
+      id: descriptor.id,
+      cwd,
+      descriptorPath,
+      descriptor
+    }));
+  });
+}
+export {
+  descriptorSchema,
+  discoverDescriptors,
+  expandNestedDescriptors
+};

package/dist/schema.cjs

@@ -0,0 +1,75 @@
+"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/schema.ts
+var schema_exports = {};
+__export(schema_exports, {
+  descriptorSchema: () => descriptorSchema
+});
+module.exports = __toCommonJS(schema_exports);
+
+// src/descriptor.schema.json
+var descriptor_schema_default = {
+  $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: {
+          type: "string",
+          minLength: 1
+        },
+        capabilities: {
+          type: "array",
+          items: {
+            type: "string",
+            minLength: 1
+          }
+        },
+        dependencies: { $ref: "#/$defs/dependencyMap" },
+        disabled: { type: "boolean" },
+        location: { type: "string" }
+      },
+      required: ["id", "version"],
+      additionalProperties: true
+    }
+  }
+};
+
+// src/schema.ts
+var descriptorSchema = descriptor_schema_default;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  descriptorSchema
+});

package/dist/schema.d.cts

@@ -0,0 +1,4 @@
+type JsonSchemaObject = Record<string, unknown>;
+declare const descriptorSchema: JsonSchemaObject;
+
+export { type JsonSchemaObject, descriptorSchema };

package/dist/schema.d.ts

@@ -0,0 +1,4 @@
+type JsonSchemaObject = Record<string, unknown>;
+declare const descriptorSchema: JsonSchemaObject;
+
+export { type JsonSchemaObject, descriptorSchema };

package/dist/schema.js

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

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@lorion-org/descriptor-discovery",
+  "version": "1.0.0-beta.0",
+  "description": "Node-based descriptor discovery and normalization helpers.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lorion-org/lorion.git",
+    "directory": "packages/descriptor-discovery"
+  },
+  "homepage": "https://github.com/lorion-org/lorion/tree/main/packages/descriptor-discovery#readme",
+  "bugs": {
+    "url": "https://github.com/lorion-org/lorion/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./schema": {
+      "import": {
+        "types": "./dist/schema.d.ts",
+        "default": "./dist/schema.js"
+      },
+      "require": {
+        "types": "./dist/schema.d.cts",
+        "default": "./dist/schema.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "keywords": [
+    "descriptor",
+    "discovery",
+    "filesystem",
+    "typescript"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "peerDependencies": {
+    "@lorion-org/composition-graph": "^1.0.0-beta.0"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1"
+  },
+  "devDependencies": {
+    "@lorion-org/composition-graph": "1.0.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/schema.ts --format esm,cjs --dts",
+    "clean": "rimraf coverage dist tsconfig.tsbuildinfo",
+    "lint": "eslint src --ext .ts",
+    "package:check": "pnpm build && pnpm pack --dry-run && publint",
+    "test": "vitest run --root ../.. --config vitest.config.mts packages/descriptor-discovery/src/index.spec.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}