@opalesce/core 0.0.0

package/README.md

@@ -0,0 +1,424 @@
+# @opalesce/core
+
+`@opalesce/core` is the in-memory AsyncAPI generation engine for Opalesce. It parses input once, resolves plugin dependencies, runs plugin lifecycle hooks, shares typed services, and collects generated text artifacts without writing files.
+
+The package is released as a focused building block for advanced integrations. Normal consumers use the `opalesce` facade, while `@opalesce/config` and `@opalesce/cli` remain the focused config, filesystem, and command layers.
+
+## Project Workflow
+
+Most projects describe generation without calling the pipeline directly:
+
+```ts
+// opalesce.config.ts
+import { defineConfig, definePlugin } from "opalesce";
+
+const versionFile = definePlugin(() => ({
+  name: "version-file",
+  build(context) {
+    context.emit({
+      path: "metadata/version.txt",
+      contents: `AsyncAPI ${context.document.version()}\n`,
+    });
+  },
+}));
+
+export default defineConfig({
+  input: "./asyncapi.yaml",
+  output: {
+    path: "./generated",
+  },
+  plugins: [versionFile()],
+});
+```
+
+```sh
+opalesce generate
+```
+
+The CLI discovers the config, reads the input, calls `run` once, and writes successful artifacts. The config remains side-effect free.
+
+## Programmatic Usage
+
+Call `run` explicitly when another program already owns input loading and artifact persistence:
+
+```ts
+import { definePipelineConfig, definePlugin, run, type Input } from "opalesce";
+
+const input = {
+  asyncapi: "3.1.0",
+  info: {
+    title: "Events",
+    version: "1.0.0",
+  },
+} satisfies Input;
+
+const versionFile = definePlugin((options: { readonly path: string }) => ({
+  name: "version-file",
+  build(context) {
+    context.emit({
+      path: options.path,
+      contents: `AsyncAPI ${context.document.version()}\n`,
+    });
+  },
+}));
+
+const config = definePipelineConfig({
+  input,
+  plugins: [versionFile({ path: "metadata/version.txt" })],
+});
+
+const result = await run(config);
+
+console.log(result.artifacts);
+```
+
+The result contains the official parsed AsyncAPI document, parser diagnostics, artifacts in emission order, and the resolved plugin order:
+
+```ts
+interface PipelineResult {
+  readonly document: AsyncAPIDocumentInterface;
+  readonly diagnostics: readonly Diagnostic[];
+  readonly artifacts: readonly GeneratedArtifact[];
+  readonly pluginNames: readonly string[];
+}
+```
+
+## Internal Workspace Usage
+
+Internal packages can depend on Core directly:
+
+```json
+{
+  "dependencies": {
+    "@opalesce/core": "workspace:*"
+  }
+}
+```
+
+Then refresh workspace links:
+
+```sh
+pnpm install
+```
+
+The scoped package is not a normal consumer dependency; prefer the `opalesce` facade unless direct access to the engine is required.
+
+## Pipeline Lifecycle
+
+`run` executes one deterministic pipeline:
+
+1. Validate plugin names and dependency relationships.
+2. Resolve a stable topological plugin order.
+3. Parse `config.input` once.
+4. Run every plugin `setup` hook in resolved order.
+5. Run every plugin `build` hook in the same order.
+6. Return a frozen result with all in-memory artifacts.
+
+Plugin configuration failures happen before parsing. Core parse failures pass through unchanged. A setup or build failure stops the pipeline immediately.
+
+## Pipeline Configuration
+
+```ts
+interface PipelineConfig {
+  readonly input: Input;
+  readonly parser?: ParseAsyncAPIOptions;
+  readonly plugins?: readonly OrchestrationPlugin[];
+}
+```
+
+| Field     | Required | Purpose                                                                                                      |
+| --------- | -------- | ------------------------------------------------------------------------------------------------------------ |
+| `input`   | Yes      | YAML or JSON text, a JavaScript AsyncAPI object, or an existing official AsyncAPI document accepted by Core. |
+| `parser`  | No       | Core parser-constructor and parse options forwarded unchanged to `parseAsyncAPI`.                            |
+| `plugins` | No       | Plugins to validate, order, and execute. Defaults to an empty pipeline.                                      |
+
+`defineConfig` is an identity helper. It preserves the concrete config type and improves TypeScript inference:
+
+```ts
+const config = defineConfig({
+  input,
+  parser: {
+    parse: {
+      source: "memory://events/asyncapi.yaml",
+    },
+  },
+  plugins: [],
+});
+```
+
+An input string is treated as AsyncAPI document content, not as a filesystem path.
+
+## Defining Plugins
+
+`definePlugin` preserves the arguments and concrete return type of a plugin factory:
+
+```ts
+import { definePlugin } from "opalesce";
+
+interface ManifestPluginOptions {
+  readonly path: string;
+}
+
+export const manifestPlugin = definePlugin((options: ManifestPluginOptions) => ({
+  name: "manifest",
+  build(context) {
+    context.emit({
+      path: options.path,
+      contents: JSON.stringify(
+        {
+          asyncapi: context.document.version(),
+        },
+        null,
+        2,
+      ),
+    });
+  },
+}));
+```
+
+A plugin can implement either or both lifecycle hooks:
+
+```ts
+interface OrchestrationPlugin {
+  readonly name: string;
+  readonly dependsOn?: readonly string[];
+  setup?(context: PluginSetupContext): void | Promise<void>;
+  build?(context: PluginBuildContext): void | Promise<void>;
+}
+```
+
+- `setup` registers or consumes shared in-memory services.
+- `build` consumes services, inspects previously emitted artifacts, and emits new artifacts.
+- All setup hooks finish before the first build hook starts.
+- Hooks run sequentially. A hook can be synchronous or asynchronous.
+
+Plugin names must be non-empty and unique in one pipeline.
+
+## Plugin Dependencies
+
+Use `dependsOn` when a plugin requires another configured plugin:
+
+```ts
+const provider = definePlugin(() => ({
+  name: "provider",
+  setup() {},
+}));
+
+const consumer = definePlugin(() => ({
+  name: "consumer",
+  dependsOn: ["provider"],
+  build() {},
+}));
+
+const config = defineConfig({
+  input,
+  plugins: [consumer(), provider()],
+});
+```
+
+The resolved order is `provider`, then `consumer`, even though the consumer appears first in the config. Config order breaks ties between plugins that are currently eligible to run.
+
+The runner rejects:
+
+- Empty plugin names.
+- Duplicate plugin names.
+- Missing dependencies.
+- Self dependencies.
+- Dependency cycles.
+
+These failures use `PluginConfigurationError` and occur before Core parses the input.
+
+## Sharing Typed Services
+
+Service tokens allow one plugin to provide a typed in-memory capability to another plugin without adding untyped fields to a global context.
+
+```ts
+import { createServiceToken, definePipelineConfig, definePlugin, run } from "opalesce";
+
+interface DocumentInfo {
+  readonly asyncapiVersion: string;
+}
+
+const documentInfoService = createServiceToken<DocumentInfo>("document-info");
+
+const documentInfoProvider = definePlugin(() => ({
+  name: "document-info-provider",
+  setup(context) {
+    context.provide(documentInfoService, {
+      asyncapiVersion: context.document.version(),
+    });
+  },
+}));
+
+const documentInfoFile = definePlugin(() => ({
+  name: "document-info-file",
+  dependsOn: ["document-info-provider"],
+  build(context) {
+    const documentInfo = context.get(documentInfoService);
+
+    context.emit({
+      path: "metadata/document.txt",
+      contents: `${documentInfo.asyncapiVersion}\n`,
+    });
+  },
+}));
+
+const result = await run(
+  definePipelineConfig({
+    input,
+    plugins: [documentInfoFile(), documentInfoProvider()],
+  }),
+);
+```
+
+The generic token type controls both `provide` and `get`. Token identity, not the diagnostic name, selects the value, so two tokens with the same name remain independent.
+
+A token can be provided only once per pipeline. Retrieving an unavailable token or providing the same token twice raises `ServiceRegistryError` inside the active plugin hook.
+
+A future `@opalesce/schema` package can use this boundary to export a shared `ServiceToken<SchemaGraph>`.
+
+## Emitting Artifacts
+
+Only build contexts expose `emit`:
+
+```ts
+context.emit({
+  path: "types/UserCreated.ts",
+  contents: "export interface UserCreated {}\n",
+});
+```
+
+Artifact paths must:
+
+- Be non-empty and relative.
+- Use forward slashes.
+- Contain no empty, `.` or `..` segments.
+- Not be POSIX or Windows absolute paths.
+- Be unique across the complete pipeline.
+
+Artifacts are stored as defensive frozen copies. `context.artifacts` is a frozen snapshot of artifacts emitted so far, allowing a later plugin such as a barrel generator to inspect earlier output:
+
+```ts
+const barrelPlugin = definePlugin(() => ({
+  name: "barrel",
+  build(context) {
+    const modules = context.artifacts
+      .filter((artifact) => artifact.path.endsWith(".ts"))
+      .map((artifact) => `export * from "./${artifact.path}";`)
+      .join("\n");
+
+    context.emit({
+      path: "index.ts",
+      contents: `${modules}\n`,
+    });
+  },
+}));
+```
+
+Core returns artifacts but does not write them. A facade or storage layer owns output-directory resolution, atomic writes, cleanup, and rollback.
+
+## Error Handling
+
+```ts
+import { PluginConfigurationError, PluginExecutionError, run } from "opalesce";
+import { AsyncAPIParseError } from "@opalesce/core";
+
+try {
+  await run(config);
+} catch (error) {
+  if (error instanceof PluginConfigurationError) {
+    console.error(error.code, error.pluginNames);
+  } else if (error instanceof AsyncAPIParseError) {
+    console.error(error.diagnostics);
+  } else if (error instanceof PluginExecutionError) {
+    console.error(error.pluginName, error.phase, error.cause);
+  } else {
+    throw error;
+  }
+}
+```
+
+| Error                      | When it is raised                                                                                              |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `PluginConfigurationError` | Plugin names or dependency relationships are invalid. This error is not wrapped.                               |
+| `AsyncAPIParseError`       | Core cannot produce a valid AsyncAPI document. This error passes through unchanged.                            |
+| `PluginExecutionError`     | A setup or build hook fails. It contains `pluginName`, `phase`, and the original `cause`.                      |
+| `ServiceRegistryError`     | A hook retrieves a missing service or provides a token twice. It is available as `PluginExecutionError.cause`. |
+| `ArtifactError`            | A hook emits an invalid or colliding artifact path. It is available as `PluginExecutionError.cause`.           |
+
+The pipeline is fail-fast and returns no partial result after an error.
+
+## Public API
+
+Runtime exports:
+
+- `parseAsyncAPI`
+- `AsyncAPIParseError`
+- `defineConfig`
+- `definePlugin`
+- `run`
+- `createServiceToken`
+- `PluginConfigurationError`
+- `PluginExecutionError`
+- `ServiceRegistryError`
+- `ArtifactError`
+
+The root entry point also exports the parser, pipeline, plugin, context, service, artifact, and error-code types:
+
+- `Input`
+- `ParseAsyncAPIOptions`
+- `AsyncAPIDocumentInterface`
+- `Diagnostic`
+
+## Current Boundaries
+
+`@opalesce/core` intentionally does not:
+
+- Discover or execute `opalesce.config.*`.
+- Provide an `opalesce` bin or CLI arguments.
+- Read an AsyncAPI source file.
+- Write or clean output directories.
+- Generate schemas, TypeScript, Zod, JSON Schema, or barrel files by itself.
+- Support binary artifacts.
+
+Those behaviors belong to config-loader, CLI, storage, schema, and output-plugin packages built on top of this API.
+
+## Prerequisites
+
+Workspace development uses Node.js 24 as declared by the repository Nix environment. The package does not yet declare a public runtime support range.
+
+Recommended:
+
+```sh
+nix develop
+pnpm install
+```
+
+The workspace pins pnpm through the root `packageManager` field. For manual setup, install Node.js 24, enable the pinned pnpm version, and run `pnpm install` from the repository root.
+
+## Stack
+
+| Area                                      | Version source files                       |
+| ----------------------------------------- | ------------------------------------------ |
+| Runtime dependencies and package metadata | [`package.json`](./package.json)           |
+| Development environment                   | [`../../flake.nix`](../../flake.nix)       |
+| Workspace command aliases                 | [`../../justfile`](../../justfile)         |
+
+## Development Commands
+
+Run commands from the repository root:
+
+| Command                                  | Purpose                                                     |
+| ---------------------------------------- | ----------------------------------------------------------- |
+| `just nx build @opalesce/core`           | Build ESM JavaScript and TypeScript declarations.           |
+| `pnpm --dir packages/core run typecheck` | Type-check package source and tests without emitting files. |
+| `pnpm --dir packages/core run test`      | Run focused parser and orchestration runtime tests.         |
+| `just nx run @opalesce/core:check`       | Run package type-checking and tests.                        |
+| `just nx run-many -t build`              | Build every Nx package project.                             |
+| `just nx run-many -t check --parallel=1` | Run package checks across the Nx workspace.                 |
+
+The package tests cover parser option forwarding, lifecycle ordering, dependency validation, typed services, artifact validation, immutable results, package exports, and error propagation.
+
+## License
+
+No license has been declared yet.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { ArtifactError, PluginConfigurationError, PluginExecutionError, ServiceRegistryError, } from "./orchestrator/errors.js";
+export type { ArtifactErrorCode, PluginConfigurationErrorCode, ServiceRegistryErrorCode, } from "./orchestrator/errors.js";
+export { defineConfig, definePlugin } from "./orchestrator/helpers.js";
+export { run } from "./orchestrator/run.js";
+export { createServiceToken } from "./orchestrator/services.js";
+export type { ServiceToken } from "./orchestrator/services.js";
+export type { GeneratedArtifact, OrchestrationPlugin, PipelineConfig, PipelineResult, PluginBuildContext, PluginContext, PluginExecutionPhase, PluginSetupContext, } from "./orchestrator/types.js";
+export { AsyncAPIParseError, parseAsyncAPI } from "./parseAsyncAPI.js";
+export type { AsyncAPIDocumentInterface, AsyncAPIParserOptions, Diagnostic, Input, ParseAsyncAPIOptions, ParseOptions, ParsedAsyncAPI, } from "./parseAsyncAPI.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,iBAAiB,EACjB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EACV,yBAAyB,EACzB,qBAAqB,EACrB,UAAU,EACV,KAAK,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,GACf,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { ArtifactError, PluginConfigurationError, PluginExecutionError, ServiceRegistryError, } from "./orchestrator/errors.js";
+export { defineConfig, definePlugin } from "./orchestrator/helpers.js";
+export { run } from "./orchestrator/run.js";
+export { createServiceToken } from "./orchestrator/services.js";
+export { AsyncAPIParseError, parseAsyncAPI } from "./parseAsyncAPI.js";

package/dist/orchestrator/artifacts.d.ts

@@ -0,0 +1,8 @@
+import type { GeneratedArtifact } from "./types.js";
+export declare class ArtifactStore {
+    private readonly artifacts;
+    private readonly paths;
+    emit(artifact: GeneratedArtifact): void;
+    snapshot(): readonly GeneratedArtifact[];
+}
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/orchestrator/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/orchestrator/artifacts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAkBpD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;IACrD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAE3C,IAAI,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAkBvC,QAAQ,IAAI,SAAS,iBAAiB,EAAE;CAGzC"}

package/dist/orchestrator/artifacts.js

@@ -0,0 +1,34 @@
+import { ArtifactError } from "./errors.js";
+function isCanonicalArtifactPath(path) {
+    if (path.length === 0 ||
+        path.includes("\\") ||
+        path.includes("\0") ||
+        path.startsWith("/") ||
+        /^[A-Za-z]:\//u.test(path)) {
+        return false;
+    }
+    return path
+        .split("/")
+        .every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
+export class ArtifactStore {
+    artifacts = [];
+    paths = new Set();
+    emit(artifact) {
+        if (!isCanonicalArtifactPath(artifact.path)) {
+            throw new ArtifactError("invalid-path", artifact.path);
+        }
+        if (this.paths.has(artifact.path)) {
+            throw new ArtifactError("path-collision", artifact.path);
+        }
+        const storedArtifact = Object.freeze({
+            path: artifact.path,
+            contents: artifact.contents,
+        });
+        this.paths.add(storedArtifact.path);
+        this.artifacts.push(storedArtifact);
+    }
+    snapshot() {
+        return Object.freeze([...this.artifacts]);
+    }
+}

package/dist/orchestrator/errors.d.ts

@@ -0,0 +1,29 @@
+import type { PluginExecutionPhase } from "./types.js";
+export type PluginConfigurationErrorCode = "empty-name" | "duplicate-name" | "missing-dependency" | "dependency-cycle";
+export declare class PluginConfigurationError extends Error {
+    readonly name = "PluginConfigurationError";
+    readonly code: PluginConfigurationErrorCode;
+    readonly pluginNames: readonly string[];
+    constructor(code: PluginConfigurationErrorCode, message: string, pluginNames?: readonly string[]);
+}
+export type ServiceRegistryErrorCode = "duplicate-service" | "missing-service";
+export declare class ServiceRegistryError extends Error {
+    readonly name = "ServiceRegistryError";
+    readonly code: ServiceRegistryErrorCode;
+    readonly serviceName: string;
+    constructor(code: ServiceRegistryErrorCode, serviceName: string);
+}
+export type ArtifactErrorCode = "invalid-path" | "path-collision";
+export declare class ArtifactError extends Error {
+    readonly name = "ArtifactError";
+    readonly code: ArtifactErrorCode;
+    readonly path: string;
+    constructor(code: ArtifactErrorCode, path: string);
+}
+export declare class PluginExecutionError extends Error {
+    readonly name = "PluginExecutionError";
+    readonly pluginName: string;
+    readonly phase: PluginExecutionPhase;
+    constructor(pluginName: string, phase: PluginExecutionPhase, cause: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/orchestrator/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/orchestrator/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,MAAM,MAAM,4BAA4B,GACpC,YAAY,GACZ,gBAAgB,GAChB,oBAAoB,GACpB,kBAAkB,CAAC;AAEvB,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,SAAkB,IAAI,8BAA8B;IACpD,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;gBAGtC,IAAI,EAAE,4BAA4B,EAClC,OAAO,EAAE,MAAM,EACf,WAAW,GAAE,SAAS,MAAM,EAAO;CAMtC;AAED,MAAM,MAAM,wBAAwB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAE/E,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,0BAA0B;IAChD,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,IAAI,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM;CAShE;AAED,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAElE,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAkB,IAAI,mBAAmB;IACzC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM;CASlD;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,0BAA0B;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;gBAEzB,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,EAAE,KAAK,EAAE,OAAO;CAK5E"}

package/dist/orchestrator/errors.js

@@ -0,0 +1,44 @@
+export class PluginConfigurationError extends Error {
+    name = "PluginConfigurationError";
+    code;
+    pluginNames;
+    constructor(code, message, pluginNames = []) {
+        super(message);
+        this.code = code;
+        this.pluginNames = Object.freeze([...pluginNames]);
+    }
+}
+export class ServiceRegistryError extends Error {
+    name = "ServiceRegistryError";
+    code;
+    serviceName;
+    constructor(code, serviceName) {
+        super(code === "duplicate-service"
+            ? `Service "${serviceName}" has already been provided.`
+            : `Service "${serviceName}" has not been provided.`);
+        this.code = code;
+        this.serviceName = serviceName;
+    }
+}
+export class ArtifactError extends Error {
+    name = "ArtifactError";
+    code;
+    path;
+    constructor(code, path) {
+        super(code === "invalid-path"
+            ? `Artifact path "${path}" must be a canonical relative path using forward slashes.`
+            : `Artifact path "${path}" has already been emitted.`);
+        this.code = code;
+        this.path = path;
+    }
+}
+export class PluginExecutionError extends Error {
+    name = "PluginExecutionError";
+    pluginName;
+    phase;
+    constructor(pluginName, phase, cause) {
+        super(`Plugin "${pluginName}" failed during ${phase}.`, { cause });
+        this.pluginName = pluginName;
+        this.phase = phase;
+    }
+}

package/dist/orchestrator/helpers.d.ts

@@ -0,0 +1,4 @@
+import type { OrchestrationPlugin, PipelineConfig } from "./types.js";
+export declare function defineConfig<const TConfig extends PipelineConfig>(config: TConfig): TConfig;
+export declare function definePlugin<TFactory extends (...arguments_: never[]) => OrchestrationPlugin>(factory: TFactory): TFactory;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/orchestrator/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/orchestrator/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEtE,wBAAgB,YAAY,CAAC,KAAK,CAAC,OAAO,SAAS,cAAc,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAE3F;AAED,wBAAgB,YAAY,CAAC,QAAQ,SAAS,CAAC,GAAG,UAAU,EAAE,KAAK,EAAE,KAAK,mBAAmB,EAC3F,OAAO,EAAE,QAAQ,GAChB,QAAQ,CAEV"}

package/dist/orchestrator/helpers.js

@@ -0,0 +1,6 @@
+export function defineConfig(config) {
+    return config;
+}
+export function definePlugin(factory) {
+    return factory;
+}

package/dist/orchestrator/orderPlugins.d.ts

@@ -0,0 +1,3 @@
+import type { OrchestrationPlugin } from "./types.js";
+export declare function orderPlugins(configuredPlugins: readonly OrchestrationPlugin[]): readonly OrchestrationPlugin[];
+//# sourceMappingURL=orderPlugins.d.ts.map

package/dist/orchestrator/orderPlugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderPlugins.d.ts","sourceRoot":"","sources":["../../src/orchestrator/orderPlugins.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAOtD,wBAAgB,YAAY,CAC1B,iBAAiB,EAAE,SAAS,mBAAmB,EAAE,GAChD,SAAS,mBAAmB,EAAE,CAwEhC"}

package/dist/orchestrator/orderPlugins.js

@@ -0,0 +1,41 @@
+import { PluginConfigurationError } from "./errors.js";
+export function orderPlugins(configuredPlugins) {
+    const records = [];
+    const pluginsByName = new Map();
+    for (const plugin of configuredPlugins) {
+        if (typeof plugin.name !== "string" || plugin.name.trim().length === 0) {
+            throw new PluginConfigurationError("empty-name", "Plugin names must contain at least one non-whitespace character.");
+        }
+        if (pluginsByName.has(plugin.name)) {
+            throw new PluginConfigurationError("duplicate-name", `Plugin name "${plugin.name}" is configured more than once.`, [plugin.name]);
+        }
+        pluginsByName.set(plugin.name, plugin);
+        records.push({
+            plugin,
+            dependencies: Object.freeze([...new Set(plugin.dependsOn ?? [])]),
+        });
+    }
+    for (const record of records) {
+        if (record.dependencies.includes(record.plugin.name)) {
+            throw new PluginConfigurationError("dependency-cycle", `Plugin "${record.plugin.name}" cannot depend on itself.`, [record.plugin.name]);
+        }
+        const missing = record.dependencies.filter((name) => !pluginsByName.has(name));
+        if (missing.length > 0) {
+            throw new PluginConfigurationError("missing-dependency", `Plugin "${record.plugin.name}" requires missing dependencies: ${missing.join(", ")}.`, [record.plugin.name, ...missing]);
+        }
+    }
+    const pending = [...records];
+    const resolvedNames = new Set();
+    const ordered = [];
+    while (pending.length > 0) {
+        const ready = pending.find((record) => record.dependencies.every((name) => resolvedNames.has(name)));
+        if (ready === undefined) {
+            const cyclicNames = pending.map((record) => record.plugin.name);
+            throw new PluginConfigurationError("dependency-cycle", `Plugin dependency cycle detected: ${cyclicNames.join(", ")}.`, cyclicNames);
+        }
+        pending.splice(pending.indexOf(ready), 1);
+        ordered.push(ready.plugin);
+        resolvedNames.add(ready.plugin.name);
+    }
+    return Object.freeze(ordered);
+}

package/dist/orchestrator/run.d.ts

@@ -0,0 +1,3 @@
+import type { PipelineConfig, PipelineResult } from "./types.js";
+export declare function run(config: PipelineConfig): Promise<PipelineResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/orchestrator/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/orchestrator/run.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAEV,cAAc,EACd,cAAc,EAIf,MAAM,YAAY,CAAC;AAcpB,wBAAsB,GAAG,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAiDzE"}

package/dist/orchestrator/run.js

@@ -0,0 +1,57 @@
+import { parseAsyncAPI } from "../parseAsyncAPI.js";
+import { ArtifactStore } from "./artifacts.js";
+import { PluginExecutionError } from "./errors.js";
+import { orderPlugins } from "./orderPlugins.js";
+import { ServiceRegistry } from "./services.js";
+async function runHook(pluginName, phase, hook) {
+    try {
+        await hook();
+    }
+    catch (cause) {
+        throw new PluginExecutionError(pluginName, phase, cause);
+    }
+}
+export async function run(config) {
+    const plugins = orderPlugins(config.plugins ?? []);
+    const parsed = await parseAsyncAPI(config.input, config.parser);
+    const services = new ServiceRegistry();
+    const artifacts = new ArtifactStore();
+    function get(token) {
+        return services.get(token);
+    }
+    const setupContext = Object.freeze({
+        document: parsed.document,
+        diagnostics: parsed.diagnostics,
+        get,
+        provide(token, value) {
+            services.provide(token, value);
+        },
+    });
+    const buildContext = Object.freeze({
+        document: parsed.document,
+        diagnostics: parsed.diagnostics,
+        get,
+        get artifacts() {
+            return artifacts.snapshot();
+        },
+        emit(artifact) {
+            artifacts.emit(artifact);
+        },
+    });
+    for (const plugin of plugins) {
+        if (plugin.setup !== undefined) {
+            await runHook(plugin.name, "setup", () => plugin.setup?.(setupContext));
+        }
+    }
+    for (const plugin of plugins) {
+        if (plugin.build !== undefined) {
+            await runHook(plugin.name, "build", () => plugin.build?.(buildContext));
+        }
+    }
+    return Object.freeze({
+        document: parsed.document,
+        diagnostics: parsed.diagnostics,
+        artifacts: artifacts.snapshot(),
+        pluginNames: Object.freeze(plugins.map((plugin) => plugin.name)),
+    });
+}

package/dist/orchestrator/services.d.ts

@@ -0,0 +1,26 @@
+declare const serviceAccess: unique symbol;
+interface MissingService {
+    readonly found: false;
+}
+interface AvailableService<T> {
+    readonly found: true;
+    readonly value: T;
+}
+type ServiceLookup<T> = MissingService | AvailableService<T>;
+interface ServiceAccess<T> {
+    read(scope: object): ServiceLookup<T>;
+    write(scope: object, value: T): boolean;
+}
+export interface ServiceToken<T> {
+    readonly name: string;
+    readonly key: symbol;
+    readonly [serviceAccess]: ServiceAccess<T>;
+}
+export declare function createServiceToken<T>(name: string): ServiceToken<T>;
+export declare class ServiceRegistry {
+    private readonly scope;
+    provide<T>(token: ServiceToken<T>, value: T): void;
+    get<T>(token: ServiceToken<T>): T;
+}
+export {};
+//# sourceMappingURL=services.d.ts.map

package/dist/orchestrator/services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../src/orchestrator/services.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,aAAa,eAAoC,CAAC;AAExD,UAAU,cAAc;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED,UAAU,gBAAgB,CAAC,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,KAAK,aAAa,CAAC,CAAC,IAAI,cAAc,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;AAE7D,UAAU,aAAa,CAAC,CAAC;IACvB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IACtC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;CAC5C;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CA2BnE;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAM;IAE5B,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAMlD,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC;CASlC"}

package/dist/orchestrator/services.js

@@ -0,0 +1,42 @@
+import { ServiceRegistryError } from "./errors.js";
+const serviceAccess = Symbol("opalesce.service-access");
+export function createServiceToken(name) {
+    const values = new WeakMap();
+    return Object.freeze({
+        name,
+        key: Symbol(name),
+        [serviceAccess]: {
+            read(scope) {
+                const entry = values.get(scope);
+                return entry === undefined
+                    ? { found: false }
+                    : {
+                        found: true,
+                        value: entry.value,
+                    };
+            },
+            write(scope, value) {
+                if (values.has(scope)) {
+                    return false;
+                }
+                values.set(scope, { value });
+                return true;
+            },
+        },
+    });
+}
+export class ServiceRegistry {
+    scope = {};
+    provide(token, value) {
+        if (!token[serviceAccess].write(this.scope, value)) {
+            throw new ServiceRegistryError("duplicate-service", token.name);
+        }
+    }
+    get(token) {
+        const lookup = token[serviceAccess].read(this.scope);
+        if (!lookup.found) {
+            throw new ServiceRegistryError("missing-service", token.name);
+        }
+        return lookup.value;
+    }
+}

package/dist/orchestrator/types.d.ts

@@ -0,0 +1,37 @@
+import type { AsyncAPIDocumentInterface, Diagnostic, Input, ParseAsyncAPIOptions } from "../parseAsyncAPI.js";
+import type { ServiceToken } from "./services.js";
+export interface GeneratedArtifact {
+    readonly path: string;
+    readonly contents: string;
+}
+export interface PluginContext {
+    readonly document: AsyncAPIDocumentInterface;
+    readonly diagnostics: readonly Diagnostic[];
+    get<T>(token: ServiceToken<T>): T;
+}
+export interface PluginSetupContext extends PluginContext {
+    provide<T>(token: ServiceToken<T>, value: T): void;
+}
+export interface PluginBuildContext extends PluginContext {
+    readonly artifacts: readonly GeneratedArtifact[];
+    emit(artifact: GeneratedArtifact): void;
+}
+export interface OrchestrationPlugin<TName extends string = string> {
+    readonly name: TName;
+    readonly dependsOn?: readonly string[];
+    setup?(context: PluginSetupContext): void | Promise<void>;
+    build?(context: PluginBuildContext): void | Promise<void>;
+}
+export interface PipelineConfig {
+    readonly input: Input;
+    readonly parser?: ParseAsyncAPIOptions;
+    readonly plugins?: readonly OrchestrationPlugin[];
+}
+export interface PipelineResult {
+    readonly document: AsyncAPIDocumentInterface;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly artifacts: readonly GeneratedArtifact[];
+    readonly pluginNames: readonly string[];
+}
+export type PluginExecutionPhase = "setup" | "build";
+//# sourceMappingURL=types.d.ts.map

package/dist/orchestrator/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/orchestrator/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EACzB,UAAU,EACV,KAAK,EACL,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;IAC5C,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACpD;AAED,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,IAAI,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,mBAAmB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IAChE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,KAAK,CAAC,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,KAAK,CAAC,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,OAAO,CAAC"}

package/dist/orchestrator/types.js

@@ -0,0 +1 @@
+export {};

package/dist/parseAsyncAPI.d.ts

@@ -0,0 +1,17 @@
+import { Parser, type AsyncAPIDocumentInterface, type Diagnostic, type Input, type ParseOptions } from "@asyncapi/parser";
+export type { AsyncAPIDocumentInterface, Diagnostic, Input, ParseOptions } from "@asyncapi/parser";
+export interface ParsedAsyncAPI {
+    readonly document: AsyncAPIDocumentInterface;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export type AsyncAPIParserOptions = NonNullable<ConstructorParameters<typeof Parser>[0]>;
+export interface ParseAsyncAPIOptions {
+    readonly parser?: AsyncAPIParserOptions;
+    readonly parse?: ParseOptions;
+}
+export declare class AsyncAPIParseError extends Error {
+    readonly diagnostics: readonly Diagnostic[];
+    constructor(diagnostics: readonly Diagnostic[]);
+}
+export declare function parseAsyncAPI(input: Input, options?: ParseAsyncAPIOptions): Promise<ParsedAsyncAPI>;
+//# sourceMappingURL=parseAsyncAPI.d.ts.map

package/dist/parseAsyncAPI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseAsyncAPI.d.ts","sourceRoot":"","sources":["../src/parseAsyncAPI.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,MAAM,EACN,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,yBAAyB,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEnG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;CAC7C;AAED,MAAM,MAAM,qBAAqB,GAAG,WAAW,CAAC,qBAAqB,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CAC/B;AAMD,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;gBAEhC,WAAW,EAAE,SAAS,UAAU,EAAE;CAK/C;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,KAAK,EACZ,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,cAAc,CAAC,CAezB"}

package/dist/parseAsyncAPI.js

@@ -0,0 +1,24 @@
+import { DiagnosticSeverity, Parser, } from "@asyncapi/parser";
+function freezeDiagnostics(diagnostics) {
+    return Object.freeze([...diagnostics]);
+}
+export class AsyncAPIParseError extends Error {
+    diagnostics;
+    constructor(diagnostics) {
+        super("Failed to parse the AsyncAPI document.");
+        this.name = "AsyncAPIParseError";
+        this.diagnostics = freezeDiagnostics(diagnostics);
+    }
+}
+export async function parseAsyncAPI(input, options) {
+    const parser = new Parser(options?.parser);
+    const output = await parser.parse(input, options?.parse);
+    if (!output.document ||
+        output.diagnostics.some((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error)) {
+        throw new AsyncAPIParseError(output.diagnostics);
+    }
+    return {
+        document: output.document,
+        diagnostics: freezeDiagnostics(output.diagnostics),
+    };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@opalesce/core",
+  "version": "0.0.0",
+  "description": "AsyncAPI parsing and plugin orchestration engine for Opalesce",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ravecat/opalesce.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@asyncapi/parser": "^3.6.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.check.json",
+    "test": "vitest run --config vitest.config.ts",
+    "check": "pnpm run typecheck && pnpm run test"
+  }
+}