@wpkernel/pipeline 0.12.3-beta.0 → 0.12.5-beta.0

package/README.md

@@ -1,20 +1,23 @@
 # @wpkernel/pipeline
 
-> Framework-agnostic orchestration primitives for building dependency-aware execution pipelines with atomic rollback.
+> A type-safe, dependency-aware workflow engine for orchestrating complex generation tasks.
 
 ## Overview
 
-`@wpkernel/pipeline` powers every generation flow inside WPKernel. It was extracted from
-`@wpkernel/core` so CLI builders, PHP bridges, and external projects can compose helpers,
-validate dependencies, and execute deterministic plans. The runtime enforces a three-phase
-model (fragments → builders → extensions) and provides rich diagnostics when helpers clash or
-dependencies are missing.
+`@wpkernel/pipeline` is a generic orchestration engine that turns sets of decoupled "helpers" into deterministic, topologically sorted execution plans.
 
-## Quick links
+While it powers WPKernel's code generation (assembling fragments into artifacts), the core is completely agnostic. You can use it to build:
 
-- [Package guide](../../docs/packages/pipeline.md)
-- [API reference](../../docs/api/@wpkernel/pipeline/README.md)
-- [PHP codemod roadmap](../../docs/internal/php-json-ast-codemod-plan.md)
+- **ETL Pipelines**: Extract, Transform, and Load stages with shared state.
+- **Build Systems**: Compile, Bundle, and Minify steps with precise ordering.
+- **Code Generators**: The standard "Fragment → Builder" pattern.
+
+It guarantees:
+
+- **Deterministic Ordering**: Topologically sorts helpers based on `dependsOn`.
+- **Cycle Detection**: Fails fast if dependencies form a loop.
+- **Atomic Rollbacks**: Extensions provide transactional `commit` and `rollback` hooks.
+- **Type Safety**: Full TypeScript support for custom contexts, options, and artifacts.
 
 ## Installation
 
@@ -24,101 +27,81 @@ pnpm add @wpkernel/pipeline
 
 The package ships pure TypeScript and has no runtime dependencies.
 
-## Quick start
+## Usage
+
+### 1. Define Your World
+
+The pipeline is generic. You define the "Stages" and "State" relevant to your domain.
 
 ```ts
-import { createPipeline, createHelper } from '@wpkernel/pipeline';
-
-const pipeline = createPipeline({
-	fragmentKind: 'fragment',
-	builderKind: 'builder',
-	createBuildOptions: (options) => options,
-	createContext: (options) => ({ reporter: options.reporter }),
-	createFragmentState: () => ({ items: [] }),
-	createFragmentArgs: ({ context, draft }) => ({
-		context,
-		input: undefined,
-		output: draft,
-		reporter: context.reporter,
-	}),
-	finalizeFragmentState: ({ draft }) => draft,
-	createBuilderArgs: ({ context, artifact }) => ({
-		context,
-		input: artifact,
-		output: { result: '' },
-		reporter: context.reporter,
-	}),
+import { makePipeline } from '@wpkernel/pipeline';
+
+const pipeline = makePipeline({
+	// Define the "Stages" of your pipeline
+	stages: (deps) => [
+		deps.makeLifecycleStage('extract'),
+		deps.makeLifecycleStage('transform'),
+		deps.makeLifecycleStage('load'),
+		deps.commitStage,
+		deps.finalizeResult,
+	],
+	// Define how to create your context and state
+	createContext: (ops) => ({ db: ops.db }),
+	// ... logic for resolving args for your helpers ...
 });
+```
+
+### 2. Register Helpers
+
+Helpers are the atomic units of work. They can be anything - functions, objects, or complex services.
 
-pipeline.ir.use(
-	createHelper({
-		key: 'collect-items',
-		kind: 'fragment',
-		apply: ({ output }) => {
-			output.items.push('item1', 'item2');
-		},
-	})
-);
-
-pipeline.builders.use(
-	createHelper({
-		key: 'format-result',
-		kind: 'builder',
-		dependsOn: ['collect-items'],
-		apply: ({ input, output }) => {
-			output.result = input.items.join(', ');
-		},
-	})
-);
-
-const result = await pipeline.run({ reporter: console });
-console.log(result.artifact.result); // "item1, item2"
+```ts
+// "Extract" helper
+pipeline.use({
+	kind: 'extract',
+	key: 'users',
+	apply: async ({ context }) => {
+		return context.db.query('SELECT * FROM users');
+	},
+});
+
+// "Transform" helper (depends on generic extract logic)
+pipeline.use({
+	kind: 'transform',
+	key: 'clean-users',
+	dependsOn: ['users'],
+	apply: ({ input }) => {
+		return input.map((u) => ({ ...u, name: u.name.trim() }));
+	},
+});
 ```
 
-## Core concepts
+### 3. Run It
 
-- **Three-phase execution** – fragment helpers assemble intermediate representations, builder
-  helpers produce artefacts, and extension hooks commit or roll back side-effects.
-- **Deterministic ordering** – helpers declare `dependsOn` relationships; the runtime performs
-  topological sorting, cycle detection, and unused-helper diagnostics.
-- **Extension system** – register hooks via `createPipelineExtension()` to manage commits,
-  rollbacks, and shared setup/teardown logic.
-- **Typed contracts** – helper descriptors, execution metadata, and diagnostics surfaces are
-  fully typed for TypeScript consumers.
+The pipeline resolves the graph, executes the content, and manages the lifecycle.
 
-## Official extension incubator
+```ts
+const result = await pipeline.run({ db: myDatabase });
+```
 
-The package owns an `src/extensions/` workspace where internal extensions are designed before
-being promoted to standalone packages. The directory ships a README that documents authoring
-guidelines and an [`official.ts`](./src/extensions/official.ts) catalogue describing the
-blueprints for:
+## Concepts
 
-- a live runner extension that streams reporter events to interactive renderers;
-- a deterministic concurrency scheduler;
-- additional integration blueprints for telemetry and runtime adapters.
+### Agnostic Helper Kinds
 
-Consumers can import the catalogue through `@wpkernel/pipeline/extensions` to understand the
-contracts and helper annotations each extension expects while we finalise their
-implementations.
+You are not limited to fixed roles. Define any `kind` of helper (e.g., `'validator'`, `'compiler'`, `'notifier'`) and map them to execution stages.
 
-## Consumers
+### Dependency Graph
 
-- `@wpkernel/cli` (code generation pipeline, codemod entry points)
-- `@wpkernel/core` (resource/action orchestration)
-- `@wpkernel/php-json-ast` (codemod and builder stacks)
-- External tooling that requires deterministic job orchestration
+Pipeline creates a dependency graph for _each_ kind of helper. If `Helper B` depends on `Helper A`, the runner ensures `A` executes before `B` (and passes `A`'s output to `B` if configured).
 
-## Diagnostics & error handling
+### Extensions & Lifecycles
 
-Use the built-in factories (`createDefaultError`, `PipelineDiagnostic`) to capture conflicts,
-missing dependencies, and rollback metadata. Execution snapshots describe which helpers ran,
-which were skipped, and what extensions committed.
+Extensions wrap the execution with hooks like `prepare`, `onSuccess`, and `rollback`. They are crucial for ensuring atomic operations - if any stage fails, the pipeline automatically triggers the rollback chain for all executed extensions.
 
-## Contributing
+## Documentation
 
-Keep helpers exported through `src/index.ts` and accompany new primitives with examples in the
-API reference. When expanding the extension system or diagnostics, update the codemod roadmap to
-reflect new capabilities that PHP bridges or the CLI can adopt.
+- [Architecture Guide](../../docs/packages/pipeline/architecture.md): Deep dive into the runner's internals and DAG resolution.
+- [API Reference](../../docs/api/@wpkernel/pipeline/README.md): Generated TSDoc for all interfaces.
 
 ## License
 

package/dist/async-utils.d.ts

@@ -48,4 +48,18 @@ export declare function maybeTry<T>(run: () => MaybePromise<T>, onError: (error:
  * @internal
  */
 export declare function processSequentially<T>(items: readonly T[], handler: (item: T, index: number) => MaybePromise<void>, direction?: 'forward' | 'reverse'): MaybePromise<void>;
+/**
+ * A small abstraction representing a state transformer that may be async.
+ *
+ * @internal
+ */
+export type Program<S> = (state: S) => MaybePromise<S>;
+/**
+ * Right-to-left composition for {@link Program} functions that short-circuits
+ * on promises while preserving synchronous execution when possible.
+ *
+ * @param {...any} fns
+ * @internal
+ */
+export declare const composeK: <S>(...fns: Program<S>[]) => Program<S>;
 //# sourceMappingURL=async-utils.d.ts.map

package/dist/async-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async-utils.d.ts","sourceRoot":"","sources":["../src/async-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAAC,OAAO,CAAC,CAS3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EACnC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EACtB,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,YAAY,CAAC,OAAO,CAAC,GAC9C,YAAY,CAAC,OAAO,CAAC,CAMvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACzB,GAAG,EAAE,MAAM,YAAY,CAAC,CAAC,CAAC,EAC1B,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,YAAY,CAAC,CAAC,CAAC,GAC1C,YAAY,CAAC,CAAC,CAAC,CAYjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACpC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC,IAAI,CAAC,EACvD,SAAS,GAAE,SAAS,GAAG,SAAqB,GAC1C,YAAY,CAAC,IAAI,CAAC,CAgCpB"}
+{"version":3,"file":"async-utils.d.ts","sourceRoot":"","sources":["../src/async-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAAC,OAAO,CAAC,CAS3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EACnC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EACtB,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,YAAY,CAAC,OAAO,CAAC,GAC9C,YAAY,CAAC,OAAO,CAAC,CAMvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACzB,GAAG,EAAE,MAAM,YAAY,CAAC,CAAC,CAAC,EAC1B,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,YAAY,CAAC,CAAC,CAAC,GAC1C,YAAY,CAAC,CAAC,CAAC,CAYjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACpC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC,IAAI,CAAC,EACvD,SAAS,GAAE,SAAS,GAAG,SAAqB,GAC1C,YAAY,CAAC,IAAI,CAAC,CAgCpB;AAED;;;;GAIG;AAEH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC;AACvD;;;;;;GAMG;AAEH,eAAO,MAAM,QAAQ,GACnB,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,KAAG,OAAO,CAAC,CAAC,CAKlC,CAAC"}

package/dist/async-utils.js

@@ -1,35 +1,40 @@
 function c(t) {
   return (typeof t != "object" || t === null) && typeof t != "function" ? !1 : typeof t.then == "function";
 }
-function l(t, e) {
+function m(t, e) {
   return c(t) ? Promise.resolve(t).then(e) : e(t);
 }
-function m(t, e) {
+function l(t, e) {
   try {
     const r = t();
-    return c(r) ? Promise.resolve(r).catch((s) => e(s)) : r;
+    return c(r) ? Promise.resolve(r).catch((n) => e(n)) : r;
   } catch (r) {
     return e(r);
   }
 }
 function p(t, e, r = "forward") {
-  const s = t.length;
-  if (s === 0)
+  const n = t.length;
+  if (n === 0)
     return;
-  const a = (n) => r === "forward" ? n < s : n >= 0, f = (n) => r === "forward" ? n + 1 : n - 1, u = (n) => {
-    for (let o = n; a(o); o = f(o)) {
-      const y = t[o], i = e(y, o);
+  const h = (o) => r === "forward" ? o < n : o >= 0, f = (o) => r === "forward" ? o + 1 : o - 1, u = (o) => {
+    for (let s = o; h(s); s = f(s)) {
+      const y = t[s], i = e(y, s);
       if (c(i))
         return Promise.resolve(i).then(
-          () => u(f(o))
+          () => u(f(s))
         );
     }
-  }, h = r === "forward" ? 0 : s - 1;
-  return u(h);
+  }, a = r === "forward" ? 0 : n - 1;
+  return u(a);
 }
+const w = (...t) => (e) => t.reduceRight(
+  (r, n) => m(r, n),
+  e
+);
 export {
+  w as composeK,
   c as isPromiseLike,
-  l as maybeThen,
-  m as maybeTry,
+  m as maybeThen,
+  l as maybeTry,
   p as processSequentially
 };

package/dist/createExtension.d.ts

@@ -2,7 +2,13 @@ import { MaybePromise, PipelineExtension, PipelineExtensionHook, PipelineExtensi
 interface CreatePipelineExtensionBaseOptions {
     readonly key?: string;
 }
-interface CreatePipelineExtensionWithRegister<TPipeline, TContext, TOptions, TArtifact> extends CreatePipelineExtensionBaseOptions {
+/**
+ * Options for creating a pipeline extension using the dynamic register pattern.
+ *
+ * @category Pipeline
+ * @public
+ */
+export interface CreatePipelineExtensionWithRegister<TPipeline, TContext, TOptions, TArtifact> extends CreatePipelineExtensionBaseOptions {
     readonly register: (pipeline: TPipeline) => MaybePromise<void | PipelineExtensionHook<TContext, TOptions, TArtifact> | PipelineExtensionHookRegistration<TContext, TOptions, TArtifact>>;
 }
 interface CreatePipelineExtensionWithSetup<TPipeline, TContext, TOptions, TArtifact> extends CreatePipelineExtensionBaseOptions {

package/dist/createExtension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createExtension.d.ts","sourceRoot":"","sources":["../src/createExtension.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,iCAAiC,EACjC,0BAA0B,EAC1B,MAAM,YAAY,CAAC;AAEpB,UAAU,kCAAkC;IAC3C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,mCAAmC,CAC5C,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,SAAQ,kCAAkC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,CAClB,QAAQ,EAAE,SAAS,KACf,YAAY,CACd,IAAI,GACJ,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,GACpD,iCAAiC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAClE,CAAC;CACF;AAED,UAAU,gCAAgC,CACzC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,SAAQ,kCAAkC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7D,QAAQ,CAAC,IAAI,CAAC,EACX,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,GACpD,iCAAiC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,0BAA0B,CAAC;CAChD;AAED,MAAM,MAAM,8BAA8B,CACzC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,IAEP,mCAAmC,CACnC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,GACD,gCAAgC,CAChC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,CAAC;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoJG;AACH,wBAAgB,uBAAuB,CACtC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,EAET,OAAO,EAAE,8BAA8B,CACtC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACT,GACC,iBAAiB,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAoD7D"}
+{"version":3,"file":"createExtension.d.ts","sourceRoot":"","sources":["../src/createExtension.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,iCAAiC,EACjC,0BAA0B,EAC1B,MAAM,YAAY,CAAC;AAEpB,UAAU,kCAAkC;IAC3C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mCAAmC,CACnD,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,SAAQ,kCAAkC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,CAClB,QAAQ,EAAE,SAAS,KACf,YAAY,CACd,IAAI,GACJ,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,GACpD,iCAAiC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAClE,CAAC;CACF;AAED,UAAU,gCAAgC,CACzC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,SAAQ,kCAAkC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7D,QAAQ,CAAC,IAAI,CAAC,EACX,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,GACpD,iCAAiC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,0BAA0B,CAAC;CAChD;AAED,MAAM,MAAM,8BAA8B,CACzC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,IAEP,mCAAmC,CACnC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,GACD,gCAAgC,CAChC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,CAAC;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoJG;AACH,wBAAgB,uBAAuB,CACtC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,EAET,OAAO,EAAE,8BAA8B,CACtC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACT,GACC,iBAAiB,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAoD7D"}

package/dist/createPipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createPipeline.d.ts","sourceRoot":"","sources":["../src/createPipeline.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACX,qBAAqB,EACrB,MAAM,EAEN,UAAU,EAEV,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAEhB,gBAAgB,EAEhB,MAAM,SAAS,CAAC;AAIjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,wBAAgB,cAAc,CAC7B,WAAW,EACX,aAAa,EACb,QAAQ,SAAS;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,EACxC,SAAS,SAAS,gBAAgB,GAAG,gBAAgB,EACrD,MAAM,GAAG,OAAO,EAChB,SAAS,GAAG,OAAO,EACnB,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,UAAU,GAAG,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,EACrD,cAAc,GAAG,OAAO,EACxB,eAAe,GAAG,OAAO,EACzB,aAAa,GAAG,OAAO,EACvB,cAAc,GAAG,OAAO,EACxB,aAAa,SAAS,UAAU,GAAG,UAAU,EAC7C,YAAY,SAAS,UAAU,GAAG,SAAS,EAC3C,eAAe,SAAS,MAAM,CAC7B,QAAQ,EACR,cAAc,EACd,eAAe,EACf,SAAS,EACT,aAAa,CACb,GAAG,MAAM,CACT,QAAQ,EACR,cAAc,EACd,eAAe,EACf,SAAS,EACT,aAAa,CACb,EACD,cAAc,SAAS,MAAM,CAC5B,QAAQ,EACR,aAAa,EACb,cAAc,EACd,SAAS,EACT,YAAY,CACZ,GAAG,MAAM,CACT,QAAQ,EACR,aAAa,EACb,cAAc,EACd,SAAS,EACT,YAAY,CACZ,EAED,OAAO,EAAE,qBAAqB,CAC7B,WAAW,EACX,aAAa,EACb,QAAQ,EACR,SAAS,EACT,MAAM,EACN,SAAS,EACT,WAAW,EACX,UAAU,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,CACd,GACC,QAAQ,CACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,SAAS,EACT,aAAa,EACb,SAAS,EACT,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,WAAW,EACX,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,CACd,CAwNA"}
+{"version":3,"file":"createPipeline.d.ts","sourceRoot":"","sources":["../src/createPipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,qBAAqB,EACrB,MAAM,EACN,UAAU,EACV,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,MAAM,SAAS,CAAC;AAGjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,wBAAgB,cAAc,CAC7B,WAAW,EACX,aAAa,EACb,QAAQ,SAAS;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,EACxC,SAAS,SAAS,gBAAgB,GAAG,gBAAgB,EACrD,MAAM,GAAG,OAAO,EAChB,SAAS,GAAG,OAAO,EACnB,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,UAAU,GAAG,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,EACrD,cAAc,GAAG,OAAO,EACxB,eAAe,GAAG,OAAO,EACzB,aAAa,GAAG,OAAO,EACvB,cAAc,GAAG,OAAO,EACxB,aAAa,SAAS,UAAU,GAAG,UAAU,EAC7C,YAAY,SAAS,UAAU,GAAG,SAAS,EAC3C,eAAe,SAAS,MAAM,CAC7B,QAAQ,EACR,cAAc,EACd,eAAe,EACf,SAAS,EACT,aAAa,CACb,GAAG,MAAM,CACT,QAAQ,EACR,cAAc,EACd,eAAe,EACf,SAAS,EACT,aAAa,CACb,EACD,cAAc,SAAS,MAAM,CAC5B,QAAQ,EACR,aAAa,EACb,cAAc,EACd,SAAS,EACT,YAAY,CACZ,GAAG,MAAM,CACT,QAAQ,EACR,aAAa,EACb,cAAc,EACd,SAAS,EACT,YAAY,CACZ,EAED,OAAO,EAAE,qBAAqB,CAC7B,WAAW,EACX,aAAa,EACb,QAAQ,EACR,SAAS,EACT,MAAM,EACN,SAAS,EACT,WAAW,EACX,UAAU,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,CACd,GACC,QAAQ,CACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,SAAS,EACT,aAAa,EACb,SAAS,EACT,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,WAAW,EACX,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,CACd,CAsCA"}

package/dist/createPipeline.js

@@ -1,122 +1,9 @@
-import { maybeThen as E, isPromiseLike as h } from "./async-utils.js";
-import { registerHelper as v, handleExtensionRegisterResult as w } from "./registration.js";
-import { initDiagnosticManager as V } from "./internal/diagnostic-manager.js";
-import { initPipelineRunner as $ } from "./internal/pipeline-runner.js";
-function L(r) {
-  const i = r.fragmentKind ?? "fragment", s = r.builderKind ?? "builder", a = r.createError ?? ((e, n) => new Error(`[${e}] ${n}`)), l = [], d = [], f = [], o = [], u = V({
-    options: r,
-    fragmentKind: i,
-    builderKind: s
-  }), k = r.createRunResult ?? ((e) => ({
-    artifact: e.artifact,
-    diagnostics: e.diagnostics,
-    steps: e.steps
-  })), { prepareContext: K, executeRun: P } = $({
-    options: r,
-    fragmentEntries: l,
-    builderEntries: d,
-    fragmentKind: i,
-    builderKind: s,
-    diagnosticManager: u,
-    createError: a,
-    resolveRunResult: k,
-    extensionHooks: f
-  }), g = i, m = s, p = (e) => v(
-    e,
-    i,
-    l,
-    g,
-    (n, t, c) => u.flagConflict(
-      n,
-      t,
-      g,
-      c
-    ),
-    a
-  ), R = (e) => v(
-    e,
-    s,
-    d,
-    m,
-    (n, t, c) => u.flagConflict(
-      n,
-      t,
-      m,
-      c
-    ),
-    a
-  ), C = (e, n) => w(e, n, f), H = (e) => {
-    if (e && h(e)) {
-      Promise.resolve(e).catch(() => {
-      });
-      const n = Promise.resolve(e).then(() => {
-      });
-      n.catch(() => {
-      }), o.push(n), n.finally(() => {
-        const t = o.indexOf(n);
-        t !== -1 && o.splice(t, 1);
-      }).catch(() => {
-      });
-    }
-    return e;
-  }, b = () => {
-    if (o.length !== 0)
-      return Promise.all([...o]).then(
-        () => {
-        }
-      );
-  }, x = {
-    fragmentKind: i,
-    builderKind: s,
-    ir: {
-      use(e) {
-        p(e);
-      }
-    },
-    builders: {
-      use(e) {
-        R(e);
-      }
-    },
-    extensions: {
-      use(e) {
-        const n = e.register(x);
-        n && h(n) && Promise.resolve(n).catch(() => {
-        });
-        const t = E(
-          n,
-          (c) => C(e.key, c)
-        );
-        return H(t);
-      }
-    },
-    use(e) {
-      if (e.kind === i) {
-        p(e);
-        return;
-      }
-      if (e.kind === s) {
-        R(e);
-        return;
-      }
-      throw a(
-        "ValidationError",
-        `Unsupported helper kind "${e.kind}".`
-      );
-    },
-    run(e) {
-      const n = () => {
-        const t = K(e);
-        return P(t);
-      };
-      return E(
-        b(),
-        () => n()
-      );
-    }
-  };
-  return x;
+import { makePipeline as i } from "./makePipeline.js";
+function n(e) {
+  return i(
+    e
+  );
 }
 export {
-  L as createPipeline
+  n as createPipeline
 };

package/dist/dependency-graph.d.ts

@@ -28,6 +28,12 @@ export interface CreateDependencyGraphOptions<THelper> {
     readonly onUnresolvedHelpers?: (options: {
         readonly unresolved: RegisteredHelper<THelper>[];
     }) => void;
+    /**
+     * Optional set of helper keys that are considered “already satisfied”.
+     * Useful when a pipeline run intentionally omits certain helpers (e.g. IR
+     * fragments) but builders still declare them as dependencies.
+     */
+    readonly providedKeys?: readonly string[];
 }
 /**
  * Creates a unique identifier for a registered helper.

package/dist/dependency-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO;IACxC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAaD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB,CAAC,OAAO;IAC9C,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B,CAAC,OAAO;IACpD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAC9B,KAAK,EAAE,sBAAsB,CAAC,OAAO,CAAC,KAClC,IAAI,CAAC;IACV,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE;QACxC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;KACjD,KAAK,IAAI,CAAC;CACX;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EACzC,KAAK,EAAE,MAAM,GACX,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,SAAS,gBAAgB,EAC9D,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAC5B,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAC1B,MAAM,CAUR;AA2KD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,SAAS,gBAAgB,EACrE,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,EACpC,OAAO,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAAG,SAAS,EAC1D,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,KAAK,GACnD;IACF,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;IACnC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACpC,CA4CA"}
+{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO;IACxC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAaD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB,CAAC,OAAO;IAC9C,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B,CAAC,OAAO;IACpD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAC9B,KAAK,EAAE,sBAAsB,CAAC,OAAO,CAAC,KAClC,IAAI,CAAC;IACV,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE;QACxC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;KACjD,KAAK,IAAI,CAAC;IACX;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EACzC,KAAK,EAAE,MAAM,GACX,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,SAAS,gBAAgB,EAC9D,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAC5B,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAC1B,MAAM,CAUR;AAoPD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,SAAS,gBAAgB,EACrE,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,EACpC,OAAO,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAAG,SAAS,EAC1D,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,KAAK,GACnD;IACF,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;IACnC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACpC,CAgBA"}

package/dist/dependency-graph.js

@@ -1,101 +1,109 @@
-function k(n, e) {
+function M(n, e) {
   return `${n.kind}:${n.key}#${e}`;
 }
-function f(n, e) {
+function u(n, e) {
   return n.helper.priority !== e.helper.priority ? e.helper.priority - n.helper.priority : n.helper.key !== e.helper.key ? n.helper.key.localeCompare(e.helper.key) : n.index - e.index;
 }
 function y(n) {
-  const e = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map();
-  for (const t of n)
-    e.set(t.id, /* @__PURE__ */ new Set()), o.set(t.id, 0), r.set(t.id, t);
-  return { adjacency: e, indegree: o, entryById: r };
+  const e = /* @__PURE__ */ new Map(), t = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map();
+  for (const o of n)
+    e.set(o.id, /* @__PURE__ */ new Set()), t.set(o.id, 0), r.set(o.id, o);
+  return { adjacency: e, indegree: t, entryById: r };
 }
 function a(n, e) {
-  const o = [];
+  const t = [];
   for (const r of n)
-    for (const t of r.helper.dependsOn)
+    for (const o of r.helper.dependsOn)
       h(
         n,
         e,
-        t,
+        o,
         r.id
-      ) || o.push({
+      ) || t.push({
         dependant: r,
-        dependencyKey: t
+        dependencyKey: o
       });
-  return o;
+  return t;
 }
-function h(n, e, o, r) {
-  const t = n.filter(
-    ({ helper: c }) => c.key === o
+function h(n, e, t, r) {
+  const o = n.filter(
+    ({ helper: s }) => s.key === t
   );
-  if (t.length === 0)
+  if (o.length === 0)
     return !1;
-  for (const c of t) {
-    const d = e.adjacency.get(c.id);
-    if (!d)
+  for (const s of o) {
+    const c = e.adjacency.get(s.id);
+    if (!c)
       continue;
-    d.add(r);
+    c.add(r);
     const i = e.indegree.get(r) ?? 0;
     e.indegree.set(r, i + 1);
   }
   return !0;
 }
 function g(n, e) {
-  const o = n.filter(
+  const t = n.filter(
     (i) => (e.indegree.get(i.id) ?? 0) === 0
   );
-  o.sort(f);
-  const r = [], t = new Map(e.indegree), c = /* @__PURE__ */ new Set();
-  for (; o.length > 0; ) {
-    const i = o.shift();
+  t.sort(u);
+  const r = [], o = new Map(e.indegree), s = /* @__PURE__ */ new Set();
+  for (; t.length > 0; ) {
+    const i = t.shift();
     if (!i)
       break;
-    r.push(i), c.add(i.id);
-    const u = e.adjacency.get(i.id);
-    if (u)
-      for (const s of u) {
-        const p = (t.get(s) ?? 0) - 1;
-        if (t.set(s, p), p !== 0)
+    r.push(i), s.add(i.id);
+    const p = e.adjacency.get(i.id);
+    if (p)
+      for (const d of p) {
+        const l = (o.get(d) ?? 0) - 1;
+        if (o.set(d, l), l !== 0)
           continue;
-        const l = e.entryById.get(s);
-        l && (o.push(l), o.sort(f));
+        const f = e.entryById.get(d);
+        f && (t.push(f), t.sort(u));
       }
   }
-  const d = n.filter((i) => !c.has(i.id));
-  return { ordered: r, unresolved: d };
+  const c = n.filter((i) => !s.has(i.id));
+  return { ordered: r, unresolved: c };
 }
-function w(n, e, o) {
-  const r = y(n), t = a(n, r);
-  if (t.length > 0) {
-    for (const s of t)
-      e?.onMissingDependency?.(s);
-    const i = /* @__PURE__ */ new Map();
-    for (const s of t) {
-      const p = s.dependant.helper.key, l = i.get(p) ?? [];
-      l.push(s.dependencyKey), i.set(p, l);
-    }
-    const u = Array.from(i.entries()).map(
-      ([s, p]) => `"${s}" → [${p.map((l) => `"${l}"`).join(", ")}]`
-    ).join(", ");
-    throw o(
-      "ValidationError",
-      `Helpers depend on unknown helpers: ${u}.`
-    );
-  }
-  const { ordered: c, unresolved: d } = g(n, r);
-  if (d.length > 0) {
-    e?.onUnresolvedHelpers?.({ unresolved: d });
-    const i = d.map((u) => u.helper.key);
-    throw o(
-      "ValidationError",
-      `Detected unresolved pipeline helpers: ${i.join(", ")}.`
-    );
+function k(n, e, t) {
+  if (n.length === 0)
+    return;
+  if (e?.onMissingDependency)
+    for (const s of n)
+      e.onMissingDependency(s);
+  const r = /* @__PURE__ */ new Map();
+  for (const s of n) {
+    const c = s.dependant.helper.key, i = r.get(c) ?? [];
+    i.push(s.dependencyKey), r.set(c, i);
   }
-  return { order: c, adjacency: r.adjacency };
+  const o = Array.from(r.entries()).map(
+    ([s, c]) => `"${s}" → [${c.map((i) => `"${i}"`).join(", ")}]`
+  ).join(", ");
+  throw t(
+    "ValidationError",
+    `Helpers depend on unknown helpers: ${o}.`
+  );
+}
+function w(n, e, t) {
+  if (n.length === 0)
+    return;
+  e?.onUnresolvedHelpers && e.onUnresolvedHelpers({ unresolved: n });
+  const r = n.map((o) => o.helper.key);
+  throw t(
+    "ValidationError",
+    `Detected unresolved pipeline helpers: ${r.join(", ")}.`
+  );
+}
+function j(n, e, t) {
+  const r = y(n), o = a(n, r), s = new Set(e?.providedKeys ?? []), c = o.filter(
+    (d) => !s.has(d.dependencyKey)
+  );
+  k(c, e, t);
+  const { ordered: i, unresolved: p } = g(n, r);
+  return w(p, e, t), { order: i, adjacency: r.adjacency };
 }
 export {
-  f as compareHelpers,
-  w as createDependencyGraph,
-  k as createHelperId
+  u as compareHelpers,
+  j as createDependencyGraph,
+  M as createHelperId
 };

package/dist/error-factory.d.ts

@@ -24,7 +24,7 @@ export declare function createDefaultError(code: string, message: string): Error
 /**
  * Creates an error factory that wraps a custom error class.
  *
- * @param ErrorClass - Custom error class constructor
+ * @param create - A function that creates an Error instance based on a code and message.
  * @param create
  * @returns An error factory function
  *