@opalesce/core 0.0.1 → 0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+`@opalesce/core` is the in-memory AsyncAPI generation engine for Opalesce. It parses input once, runs each configured plugin in declared order, 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.
 
@@ -14,11 +14,13 @@ 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`,
-    });
+  generate(context) {
+    return [
+      {
+        path: "metadata/version.txt",
+        contents: `AsyncAPI ${context.document.version()}\n`,
+      },
+    ];
   },
 }));
 
@@ -54,11 +56,13 @@ const input = {
 
 const versionFile = definePlugin((options: { readonly path: string }) => ({
   name: "version-file",
-  build(context) {
-    context.emit({
-      path: options.path,
-      contents: `AsyncAPI ${context.document.version()}\n`,
-    });
+  generate(context) {
+    return [
+      {
+        path: options.path,
+        contents: `AsyncAPI ${context.document.version()}\n`,
+      },
+    ];
   },
 }));
 
@@ -72,12 +76,13 @@ 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:
+The result contains the official parsed AsyncAPI document, parser diagnostics, artifacts in return order, and the configured plugin order:
 
 ```ts
 interface PipelineResult {
   readonly document: AsyncAPIDocumentInterface;
   readonly diagnostics: readonly Diagnostic[];
+  readonly source?: AsyncAPISource;
   readonly artifacts: readonly GeneratedArtifact[];
   readonly pluginNames: readonly string[];
 }
@@ -107,14 +112,13 @@ The scoped package is not a normal consumer dependency; prefer the `opalesce` fa
 
 `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.
+1. Snapshot `config.plugins` in declared order.
+2. Parse `config.input` once.
+3. Create one frozen plugin context with a lazy interaction contract.
+4. Run and await each plugin `generate` in declared order.
+5. 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.
+Core parse failures pass through unchanged. A generation failure stops the pipeline immediately, so later plugins do not run.
 
 ## Pipeline Configuration
 
@@ -130,7 +134,7 @@ interface PipelineConfig {
 | --------- | -------- | ------------------------------------------------------------------------------------------------------------ |
 | `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.                                      |
+| `plugins` | No       | Plugins to execute sequentially in declared order. Defaults to an empty pipeline.                            |
 
 `defineConfig` is an identity helper. It preserves the concrete config type and improves TypeScript inference:
 
@@ -161,131 +165,88 @@ interface ManifestPluginOptions {
 
 export const manifestPlugin = definePlugin((options: ManifestPluginOptions) => ({
   name: "manifest",
-  build(context) {
-    context.emit({
-      path: options.path,
-      contents: JSON.stringify(
-        {
-          asyncapi: context.document.version(),
-        },
-        null,
-        2,
-      ),
-    });
+  generate(context) {
+    return [
+      {
+        path: options.path,
+        contents: JSON.stringify(
+          {
+            asyncapi: context.document.version(),
+          },
+          null,
+          2,
+        ),
+      },
+    ];
   },
 }));
 ```
 
-A plugin can implement either or both lifecycle hooks:
+A plugin has one required execution hook:
 
 ```ts
 interface OrchestrationPlugin {
   readonly name: string;
-  readonly dependsOn?: readonly string[];
-  setup?(context: PluginSetupContext): void | Promise<void>;
-  build?(context: PluginBuildContext): void | Promise<void>;
+  generate(
+    context: PluginContext,
+  ): readonly GeneratedArtifact[] | Promise<readonly GeneratedArtifact[]>;
 }
 ```
 
-- `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:
+The context separates the complete parser model from shared generation semantics:
 
 ```ts
-const provider = definePlugin(() => ({
-  name: "provider",
-  setup() {},
-}));
-
-const consumer = definePlugin(() => ({
-  name: "consumer",
-  dependsOn: ["provider"],
-  build() {},
-}));
-
-const config = defineConfig({
-  input,
-  plugins: [consumer(), provider()],
-});
+interface PluginContext {
+  readonly document: AsyncAPIDocumentInterface;
+  readonly interaction: InteractionContract;
+  readonly diagnostics: readonly Diagnostic[];
+  readonly source?: AsyncAPISource;
+}
 ```
 
-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.
+- `document` is the complete official parser model, including bindings, servers, security, and extensions.
+- `interaction` is the target-neutral schema, message, channel, parameter, operation, reply, and dependency contract shared by TypeScript, Zod, and other output plugins.
+- `diagnostics` contains parser diagnostics.
+- `source` is the optional unresolved source snapshot.
+- `generate` returns text artifacts.
+- Plugin generations run sequentially in the exact order declared in `plugins`.
+- Core awaits asynchronous generation before starting the next plugin.
+- Core lazily builds `interaction` on first access and returns the same immutable contract identity to every plugin in the run.
+- Plugins own target-specific projection, naming, rendering, and files.
+- Plugins do not receive services or artifacts from other plugins.
 
-The runner rejects:
+Contract normalization supports AsyncAPI 2.6, 3.0, and 3.1. A plugin that never reads `interaction` does not trigger normalization, so document-only plugins retain parser-level version support. Contract construction never reads files, accesses the network, or invokes another parser.
 
-- Empty plugin names.
-- Duplicate plugin names.
-- Missing dependencies.
-- Self dependencies.
-- Dependency cycles.
+For raw text and object inputs, `context.source.data` is an Opalesce-owned recursively frozen snapshot captured before parser reference resolution. It preserves authored `$ref` strings and boolean schemas instead of exposing the resolved, potentially cyclic parser model. `context.source.uri` contains `parse.source` when supplied. The same source identity is shared by every plugin and the pipeline result.
 
-These failures use `PluginConfigurationError` and occur before Core parses the input.
+When `input` is an existing `AsyncAPIDocumentInterface`, `source` is `undefined`. Core does not reconstruct purported authored input from `document.json()` because that model has already been resolved.
 
-## Sharing Typed Services
+The name identifies a plugin in results and execution errors. Repeated entries and repeated names are executed rather than deduplicated.
 
-Service tokens allow one plugin to provide a typed in-memory capability to another plugin without adding untyped fields to a global context.
+## Linear Plugin Order
 
-```ts
-import { createServiceToken, defineConfig, definePlugin, run } from "@opalesce/core";
+The config array is the complete execution plan:
 
-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(
-  defineConfig({
-    input,
-    plugins: [documentInfoFile(), documentInfoProvider()],
-  }),
-);
+```ts
+const config = defineConfig({
+  input,
+  plugins: [typescriptPlugin(), documentationPlugin(), metadataPlugin()],
+});
 ```
 
-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.
+Core does not reorder plugins. If the same plugin instance appears twice, its `generate` runs twice at those positions. Generation contexts cannot observe earlier artifacts, so config order controls execution without creating a plugin dependency API.
 
-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.
+## Returning Artifacts
 
-A future `@opalesce/schema` package can use this boundary to export a shared `ServiceToken<SchemaGraph>`.
-
-## Emitting Artifacts
-
-Only build contexts expose `emit`:
+`generate` returns artifact descriptions:
 
 ```ts
-context.emit({
-  path: "types/UserCreated.ts",
-  contents: "export interface UserCreated {}\n",
-});
+return [
+  {
+    path: "types/UserCreated.ts",
+    contents: "export interface UserCreated {}\n",
+  },
+];
 ```
 
 Artifact paths must:
@@ -296,59 +257,33 @@ Artifact paths must:
 - 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`,
-    });
-  },
-}));
-```
+Artifacts are stored as defensive frozen copies and become visible in `PipelineResult` after the complete run succeeds. A plugin cannot inspect artifacts returned by another plugin. Outputs that must be coordinated, such as modules and their barrel file, belong to one plugin.
 
 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 {
-  AsyncAPIParseError,
-  PluginConfigurationError,
-  PluginExecutionError,
-  run,
-} from "@opalesce/core";
+import { AsyncAPIParseError, PluginExecutionError, run } from "@opalesce/core";
 
 try {
   await run(config);
 } catch (error) {
-  if (error instanceof PluginConfigurationError) {
-    console.error(error.code, error.pluginNames);
-  } else if (error instanceof AsyncAPIParseError) {
+  if (error instanceof AsyncAPIParseError) {
     console.error(error.diagnostics);
   } else if (error instanceof PluginExecutionError) {
-    console.error(error.pluginName, error.phase, error.cause);
+    console.error(error.pluginName, 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`.           |
+| Error                  | When it is raised                                                                             |
+| ---------------------- | --------------------------------------------------------------------------------------------- |
+| `AsyncAPIParseError`   | Core cannot produce a valid AsyncAPI document. This error passes through unchanged.           |
+| `PluginExecutionError` | Plugin generation fails. It contains `pluginName` and the original `cause`.                   |
+| `ArtifactError`        | A plugin returns an invalid or colliding artifact path. It is a `PluginExecutionError.cause`. |
 
 The pipeline is fail-fast and returns no partial result after an error.
 
@@ -361,18 +296,29 @@ Runtime exports:
 - `defineConfig`
 - `definePlugin`
 - `run`
-- `createServiceToken`
-- `PluginConfigurationError`
 - `PluginExecutionError`
-- `ServiceRegistryError`
 - `ArtifactError`
+- `InteractionContractError`
 
-The root entry point also exports the parser, pipeline, plugin, context, service, artifact, and error-code types:
+The root entry point also exports parser, pipeline, plugin, context, artifact, and error-code types, including:
 
 - `Input`
 - `ParseAsyncAPIOptions`
 - `AsyncAPIDocumentInterface`
 - `Diagnostic`
+- `AsyncAPISource`
+- `JsonValue`
+- `OrchestrationPlugin`
+- `PluginContext`
+- `PipelineConfig`
+- `PipelineResult`
+- `GeneratedArtifact`
+- `InteractionContract`
+- `SchemaContract`
+- `MessageContract`
+- `ChannelContract`
+- `OperationContract`
+- `ReplyContract`
 
 ## Current Boundaries
 
@@ -421,7 +367,7 @@ Run commands from the repository root:
 | `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.
+The package tests cover parser option forwarding, declared plugin order, sequential asynchronous generation, artifact validation, immutable results, package exports, and error propagation.
 
 ## License
 

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-export { ArtifactError, PluginConfigurationError, PluginExecutionError, ServiceRegistryError, } from "./orchestrator/errors.js";
-export type { ArtifactErrorCode, PluginConfigurationErrorCode, ServiceRegistryErrorCode, } from "./orchestrator/errors.js";
+export { ArtifactError, PluginExecutionError } from "./orchestrator/errors.js";
+export type { ArtifactErrorCode } 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 type { GeneratedArtifact, OrchestrationPlugin, PipelineConfig, PipelineResult, PluginContext, } from "./orchestrator/types.js";
 export { AsyncAPIParseError, parseAsyncAPI } from "./parseAsyncAPI.js";
 export type { AsyncAPIDocumentInterface, AsyncAPIParserOptions, Diagnostic, Input, ParseAsyncAPIOptions, ParseOptions, ParsedAsyncAPI, } from "./parseAsyncAPI.js";
+export type { AsyncAPISource, JsonArray, JsonObject, JsonPrimitive, JsonValue } from "./source.js";
+export { InteractionContractError } from "./interaction/errors.js";
+export type { InteractionContractErrorCode, InteractionContractErrorOptions, } from "./interaction/errors.js";
+export type { ChannelContract, ChannelParameterContract, InteractionAction, InteractionAsyncAPIVersion, InteractionContract, InteractionRootKind, InteractionRootMetadata, MessageContract, OperationContract, ReplyContract, SchemaContract, SchemaDependencyContract, SchemaRoleContract, } from "./interaction/types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAC5C,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,aAAa,GACd,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;AAC5B,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,YAAY,EACV,4BAA4B,EAC5B,+BAA+B,GAChC,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,eAAe,EACf,wBAAwB,EACxB,iBAAiB,EACjB,0BAA0B,EAC1B,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
-export { ArtifactError, PluginConfigurationError, PluginExecutionError, ServiceRegistryError, } from "./orchestrator/errors.js";
+export { ArtifactError, PluginExecutionError } 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";
+export { InteractionContractError } from "./interaction/errors.js";

package/dist/interaction/build.d.ts

@@ -0,0 +1,5 @@
+import type { AsyncAPIDocumentInterface } from "@asyncapi/parser";
+import type { InteractionContract } from "./types.js";
+import type { AsyncAPISource } from "../source.js";
+export declare function buildInteractionContract(document: AsyncAPIDocumentInterface, source?: AsyncAPISource): InteractionContract;
+//# sourceMappingURL=build.d.ts.map

package/dist/interaction/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/interaction/build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EAM1B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAKV,mBAAmB,EAIpB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AA2NnD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,yBAAyB,EACnC,MAAM,CAAC,EAAE,cAAc,GACtB,mBAAmB,CAqOrB"}