@wpkernel/pipeline 0.12.1-beta.0

package/dist/createPipeline.d.ts

@@ -0,0 +1,205 @@
+import { CreatePipelineOptions, Helper, HelperKind, Pipeline, PipelineDiagnostic, PipelineReporter, PipelineRunState } from './types';
+/**
+ * Creates a pipeline orchestrator-the execution engine that powers WPKernel's entire code generation infrastructure.
+ *
+ * ## Why Pipelines Matter
+ *
+ * The pipeline system is the **single most critical component** of the framework:
+ *
+ * - **CLI package**: Every generator (`wpk generate resource`, `wpk generate action`, etc.) runs on pipeline
+ * - **PHP Driver**: All PHP AST transformations flow through pipeline helpers
+ * - **Core package**: Resource definitions, action middleware, and capability proxies leverage pipeline
+ * - **Future-proof**: Designed to extract into standalone `@wpkernel/pipeline` package
+ *
+ * Pipelines provide:
+ * 1. **Dependency resolution**: Topologically sorts helpers based on `dependsOn` declarations
+ * 2. **Priority ordering**: Executes helpers in deterministic order via priority values
+ * 3. **Error recovery**: Automatic rollback on failure via commit/rollback protocol
+ * 4. **Diagnostics**: Built-in error tracking with reporter integration
+ * 5. **Extensibility**: Plugin-style extensions via hooks (pre-run, post-build, etc.)
+ *
+ * ## Architecture
+ *
+ * A pipeline consists of three phases:
+ *
+ * ### 1. Registration Phase
+ * ```
+ * pipeline.registerFragment(helper1)
+ * pipeline.registerBuilder(helper2)
+ * ```
+ * Helpers are collected but not executed. Dependency graph is constructed.
+ *
+ * ### 2. Execution Phase
+ * ```
+ * const result = await pipeline.run(options)
+ * ```
+ * - Validates dependency graph (detects missing deps, cycles)
+ * - Sorts helpers topologically
+ * - Runs fragment helpers to transform AST
+ * - Runs builder helpers to produce artifacts
+ * - Commits successful results
+ *
+ * ### 3. Rollback Phase (on error)
+ * ```
+ * // Automatic on failure
+ * ```
+ * - Walks back through executed helpers in reverse order
+ * - Invokes rollback functions to undo side effects
+ * - Aggregates diagnostics for debugging
+ *
+ * ## Extension System
+ *
+ * Pipelines support hooks that intercept execution at key points:
+ *
+ * - `pre-run`: Before any helpers execute (validation, setup)
+ * - `post-fragment`: After fragment helpers complete (AST inspection)
+ * - `post-builder`: After builder helpers complete (artifact transformation)
+ * - `pre-commit`: Before committing results (final validation)
+ *
+ * Extensions enable:
+ * - Custom validation logic
+ * - Third-party integrations (ESLint, Prettier, type checkers)
+ * - Conditional execution (feature flags, environment checks)
+ * - Artifact post-processing (minification, bundling)
+ *
+ * ## Type Safety
+ *
+ * The pipeline is fully generic across 16 type parameters, enabling:
+ * - Type-safe context sharing between helpers
+ * - Strongly-typed input/output contracts
+ * - Custom reporter integration (LogLayer, console, etc.)
+ * - Flexible artifact types (strings, AST nodes, binary data)
+ *
+ * ## Performance
+ *
+ * - **Lazy execution**: Helpers only run when `pipeline.run()` is called
+ * - **Incremental registration**: Add helpers at any time before execution
+ * - **Async support**: Mix sync and async helpers seamlessly
+ * - **Memory efficiency**: Helpers are immutable descriptors (no closures)
+ *
+ * @param    options
+ * @category Pipeline
+ *
+ * @example Basic pipeline setup
+ * ```typescript
+ * import { createPipeline, createHelper } from '@wpkernel/core/pipeline';
+ * import { createReporter } from '@wpkernel/core';
+ *
+ * interface MyContext {
+ *   reporter: ReturnType<typeof createReporter>;
+ *   namespace: string;
+ * }
+ *
+ * const pipeline = createPipeline({
+ *   fragmentKind: 'fragment',
+ *   builderKind: 'builder',
+ *
+ *   createContext: (reporter) => ({
+ *     reporter,
+ *     namespace: 'MyPlugin',
+ *   }),
+ *
+ *   buildFragment: (ctx, opts) => {
+ *     // Transform AST node
+ *     const fragment = opts.input;
+ *     fragment.namespace = ctx.namespace;
+ *     return { fragment };
+ *   },
+ *
+ *   buildArtifact: (ctx, opts) => {
+ *     // Generate final PHP code
+ *     const code = opts.draft.toString();
+ *     return { artifact: code };
+ *   },
+ * });
+ *
+ * // Register helpers
+ * pipeline.registerFragment(addPHPTagHelper);
+ * pipeline.registerFragment(addNamespaceHelper);
+ * pipeline.registerBuilder(writeFileHelper);
+ *
+ * // Execute
+ * const result = await pipeline.run({ input: myAST });
+ * console.log(result.artifact); // Generated PHP code
+ * ```
+ *
+ * @example Pipeline with extensions
+ * ```typescript
+ * const pipeline = createPipeline({
+ *   // ... base config ...
+ *
+ *   extensions: [
+ *     {
+ *       key: 'eslint-validation',
+ *       hooks: {
+ *         'post-builder': async ({ artifact, context }) => {
+ *           const lintResult = await eslint.lintText(artifact);
+ *           if (lintResult.errorCount > 0) {
+ *             throw new Error('Linting failed');
+ *           }
+ *           return { artifact };
+ *         },
+ *       },
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Error handling with rollback
+ * ```typescript
+ * const result = await pipeline.run({ input: myAST });
+ *
+ * if (!result.success) {
+ *   console.error('Pipeline failed:', result.diagnostics);
+ *   // Rollback already executed automatically
+ *   // Files restored, temp resources cleaned up
+ * } else {
+ *   console.log('Success:', result.artifact);
+ *   // All commit functions executed
+ * }
+ * ```
+ *
+ * @example Real-world CLI usage
+ * ```typescript
+ * // This is how `wpk generate resource` works internally:
+ *
+ * const resourcePipeline = createPipeline({
+ *   fragmentKind: 'fragment',
+ *   builderKind: 'builder',
+ *   createContext: (reporter) => ({
+ *     reporter,
+ *     config: loadKernelConfig(),
+ *   }),
+ *   buildFragment: (ctx, opts) => {
+ *     // Build PHP AST for resource class
+ *     return buildResourceClass(opts.input, ctx.config);
+ *   },
+ *   buildArtifact: async (ctx, opts) => {
+ *     // Convert AST to PHP code
+ *     const code = await printPhpAst(opts.draft);
+ *     return { artifact: code };
+ *   },
+ * });
+ *
+ * // Register standard helpers
+ * resourcePipeline.registerFragment(phpOpeningTagHelper);
+ * resourcePipeline.registerFragment(namespaceHelper);
+ * resourcePipeline.registerFragment(useStatementsHelper);
+ * resourcePipeline.registerFragment(classDefinitionHelper);
+ * resourcePipeline.registerBuilder(writeFileHelper);
+ * resourcePipeline.registerBuilder(formatCodeHelper);
+ *
+ * // User can inject custom helpers via config
+ * const userHelpers = loadUserHelpers();
+ * userHelpers.forEach(h => resourcePipeline.registerFragment(h));
+ *
+ * // Execute generation
+ * const result = await resourcePipeline.run({
+ *   input: { name: 'Post', endpoint: '/posts' }
+ * });
+ * ```
+ */
+export declare function createPipeline<TRunOptions, TBuildOptions, TContext extends {
+    reporter: TReporter;
+}, TReporter extends PipelineReporter = PipelineReporter, TDraft = unknown, TArtifact = unknown, TDiagnostic extends PipelineDiagnostic = PipelineDiagnostic, TRunResult = PipelineRunState<TArtifact, TDiagnostic>, TFragmentInput = unknown, TFragmentOutput = unknown, TBuilderInput = unknown, TBuilderOutput = unknown, TFragmentKind extends HelperKind = 'fragment', TBuilderKind extends HelperKind = 'builder', TFragmentHelper extends Helper<TContext, TFragmentInput, TFragmentOutput, TReporter, TFragmentKind> = Helper<TContext, TFragmentInput, TFragmentOutput, TReporter, TFragmentKind>, TBuilderHelper extends Helper<TContext, TBuilderInput, TBuilderOutput, TReporter, TBuilderKind> = Helper<TContext, TBuilderInput, TBuilderOutput, TReporter, TBuilderKind>>(options: CreatePipelineOptions<TRunOptions, TBuildOptions, TContext, TReporter, TDraft, TArtifact, TDiagnostic, TRunResult, TFragmentInput, TFragmentOutput, TBuilderInput, TBuilderOutput, TFragmentKind, TBuilderKind, TFragmentHelper, TBuilderHelper>): Pipeline<TRunOptions, TRunResult, TContext, TReporter, TBuildOptions, TArtifact, TFragmentInput, TFragmentOutput, TBuilderInput, TBuilderOutput, TDiagnostic, TFragmentKind, TBuilderKind, TFragmentHelper, TBuilderHelper>;
+//# sourceMappingURL=createPipeline.d.ts.map

package/dist/createPipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createPipeline.d.ts","sourceRoot":"","sources":["../src/createPipeline.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACX,qBAAqB,EACrB,MAAM,EAEN,UAAU,EAGV,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAMhB,gBAAgB,EAEhB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuMG;AACH,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,CAywBA"}

package/dist/createPipeline.js

@@ -0,0 +1,447 @@
+import { maybeThen as M, maybeTry as Q } from "./async-utils.js";
+import { createDependencyGraph as X } from "./dependency-graph.js";
+import { runExtensionHooks as ie, rollbackExtensionResults as ce, commitExtensionResults as ae, createRollbackErrorMetadata as Y } from "./extensions.js";
+import { executeHelpers as Z } from "./executor.js";
+import { registerHelper as _, handleExtensionRegisterResult as ue } from "./registration.js";
+/**
+ * @wpkernel/pipeline
+ * @license EUPL-1.2
+ */
+function ye(c) {
+  const b = c.fragmentKind ?? "fragment", m = c.builderKind ?? "builder", h = c.createError ?? ((e, n) => new Error(`[${e}] ${n}`)), E = [], y = [], S = [], G = /* @__PURE__ */ new WeakMap();
+  let H;
+  const v = [], l = b, p = m;
+  function C(e, n) {
+    return e === l ? `Fragment helper "${n.key}"` : e === p ? `Builder helper "${n.key}"` : `Helper "${n.key}"`;
+  }
+  function P(e, n, t, r) {
+    const a = c.createConflictDiagnostic?.({
+      helper: e,
+      existing: n,
+      message: r
+    }) ?? {
+      type: "conflict",
+      key: e.key,
+      mode: e.mode,
+      helpers: [
+        n.origin ?? n.key,
+        e.origin ?? e.key
+      ],
+      message: r,
+      kind: t
+    };
+    O(a);
+  }
+  function q(e, n, t) {
+    const r = `${C(t, e)} depends on unknown helper "${n}".`, a = c.createMissingDependencyDiagnostic?.({
+      helper: e,
+      dependency: n,
+      message: r
+    }) ?? {
+      type: "missing-dependency",
+      key: e.key,
+      dependency: n,
+      message: r,
+      kind: t,
+      helper: e.origin ?? e.key
+    };
+    O(a);
+  }
+  function D(e, n, t, r) {
+    const a = `${C(n, e)} ${t}.`, u = c.createUnusedHelperDiagnostic?.({
+      helper: e,
+      message: a
+    }) ?? {
+      type: "unused-helper",
+      key: e.key,
+      message: a,
+      kind: n,
+      helper: e.origin ?? e.key,
+      dependsOn: r
+    };
+    O(u);
+  }
+  function T(e) {
+    if (!H || !c.onDiagnostic)
+      return;
+    const n = G.get(H);
+    if (n?.has(e))
+      return;
+    const t = n ?? /* @__PURE__ */ new Set();
+    c.onDiagnostic({
+      reporter: H,
+      diagnostic: e
+    }), t.add(e), n || G.set(H, t);
+  }
+  function O(e) {
+    S.push(e), T(e);
+  }
+  function W(e, n, t) {
+    for (const r of e)
+      n.has(r.id) || D(
+        r.helper,
+        t,
+        "was registered but never executed",
+        r.helper.dependsOn
+      );
+  }
+  function A(e, n, t) {
+    const r = [], a = [], u = [];
+    for (const k of e) {
+      const f = k.helper.key;
+      r.push(f), n.has(k.id) ? a.push(f) : u.push(f);
+    }
+    return {
+      kind: t,
+      registered: r,
+      executed: a,
+      missing: u
+    };
+  }
+  function j(e, n, t) {
+    if (n.missing.length === 0)
+      return;
+    const r = e.filter(
+      (u) => n.missing.includes(u.helper.key) && !u.helper.optional
+    );
+    if (r.length === 0)
+      return;
+    const a = r.map(
+      (u) => C(t, u.helper)
+    );
+    throw h(
+      "ValidationError",
+      `Pipeline finalisation aborted because ${a.join(", ")} did not execute.`
+    );
+  }
+  const N = (e) => _(
+    e,
+    b,
+    E,
+    l,
+    (n, t, r) => P(
+      n,
+      t,
+      l,
+      r
+    ),
+    h
+  ), I = (e) => _(
+    e,
+    m,
+    y,
+    p,
+    (n, t, r) => P(
+      n,
+      t,
+      p,
+      r
+    ),
+    h
+  ), J = (e, n) => ue(e, n, v);
+  function ee(e) {
+    const n = c.createBuildOptions(e), t = c.createContext(e);
+    H = t.reporter;
+    for (const o of S)
+      T(o);
+    const r = c.createFragmentState({
+      options: e,
+      context: t,
+      buildOptions: n
+    }), a = X(
+      E,
+      {
+        onMissingDependency: ({ dependant: o, dependencyKey: i }) => {
+          const s = o.helper;
+          q(
+            s,
+            i,
+            l
+          ), D(
+            s,
+            l,
+            `could not execute because dependency "${i}" was not found`,
+            s.dependsOn
+          );
+        },
+        onUnresolvedHelpers: ({ unresolved: o }) => {
+          for (const i of o) {
+            const s = i.helper;
+            D(
+              s,
+              l,
+              "could not execute because its dependencies never resolved",
+              s.dependsOn
+            );
+          }
+        }
+      },
+      h
+    ).order, u = [], k = (o) => {
+      const i = o.helper;
+      u.push({
+        id: o.id,
+        index: u.length,
+        key: i.key,
+        kind: i.kind,
+        mode: i.mode,
+        priority: i.priority,
+        dependsOn: i.dependsOn,
+        origin: i.origin
+      });
+    }, f = {
+      onMissingDependency: ({ dependant: o, dependencyKey: i }) => {
+        const s = o.helper;
+        q(
+          s,
+          i,
+          p
+        ), D(
+          s,
+          p,
+          `could not execute because dependency "${i}" was not found`,
+          s.dependsOn
+        );
+      },
+      onUnresolvedHelpers: ({ unresolved: o }) => {
+        for (const i of o) {
+          const s = i.helper;
+          D(
+            s,
+            p,
+            "could not execute because its dependencies never resolved",
+            s.dependsOn
+          );
+        }
+      }
+    }, K = c.createExtensionHookOptions ?? ((o) => ({
+      context: o.context,
+      options: o.options,
+      artifact: o.artifact
+    })), U = (o) => K({
+      context: t,
+      options: e,
+      buildOptions: n,
+      artifact: o
+    }), $ = c.onExtensionRollbackError ?? ((o) => {
+      const { reporter: i } = o.context, s = i.warn;
+      typeof s == "function" && s.call(i, "Pipeline extension rollback failed.", {
+        error: o.error,
+        errorName: o.errorMetadata.name,
+        errorMessage: o.errorMetadata.message,
+        errorStack: o.errorMetadata.stack,
+        errorCause: o.errorMetadata.cause,
+        extensions: o.extensionKeys,
+        hookKeys: o.hookSequence
+      });
+    });
+    return {
+      runOptions: e,
+      buildOptions: n,
+      context: t,
+      draft: r,
+      fragmentOrder: a,
+      steps: u,
+      pushStep: k,
+      builderGraphOptions: f,
+      createHookOptions: U,
+      handleRollbackError: $
+    };
+  }
+  const ne = c.createRunResult ?? ((e) => ({
+    artifact: e.artifact,
+    diagnostics: e.diagnostics,
+    steps: e.steps
+  }));
+  function te(e) {
+    const {
+      runOptions: n,
+      buildOptions: t,
+      context: r,
+      draft: a,
+      fragmentOrder: u,
+      steps: k,
+      pushStep: f,
+      builderGraphOptions: K,
+      createHookOptions: U,
+      handleRollbackError: $
+    } = e;
+    let o = A(
+      y,
+      /* @__PURE__ */ new Set(),
+      m
+    );
+    const i = Z(
+      u,
+      (s) => c.createFragmentArgs({
+        helper: s.helper,
+        options: n,
+        context: r,
+        buildOptions: t,
+        draft: a
+      }),
+      (s, F, x) => s.apply(F, x),
+      (s) => f(s)
+    );
+    return M(i, (s) => {
+      W(
+        E,
+        s,
+        l
+      );
+      const F = A(
+        E,
+        s,
+        b
+      );
+      j(
+        E,
+        F,
+        l
+      );
+      let x = c.finalizeFragmentState({
+        draft: a,
+        options: n,
+        context: r,
+        buildOptions: t,
+        helpers: { fragments: F }
+      });
+      const re = X(
+        y,
+        K,
+        h
+      ).order, oe = ie(
+        v,
+        U(x),
+        ({ error: R, extensionKeys: B, hookSequence: z }) => $({
+          error: R,
+          extensionKeys: B,
+          hookSequence: z,
+          errorMetadata: Y(R),
+          context: r
+        })
+      );
+      return M(oe, (R) => {
+        x = R.artifact;
+        const B = () => (d) => M(
+          ce(
+            R.results,
+            v,
+            ({
+              error: g,
+              extensionKeys: w,
+              hookSequence: V
+            }) => $({
+              error: g,
+              extensionKeys: w,
+              hookSequence: V,
+              errorMetadata: Y(
+                g
+              ),
+              context: r
+            })
+          ),
+          () => {
+            throw d;
+          }
+        ), z = B(), se = (d) => {
+          W(
+            y,
+            d,
+            p
+          );
+          const g = A(
+            y,
+            d,
+            m
+          );
+          j(
+            y,
+            g,
+            p
+          ), o = g;
+          const w = () => ne({
+            artifact: x,
+            diagnostics: S.slice(),
+            steps: k,
+            context: r,
+            buildOptions: t,
+            options: n,
+            helpers: {
+              fragments: F,
+              builders: o
+            }
+          }), V = B();
+          return M(
+            Q(
+              () => ae(
+                R.results
+              ),
+              V
+            ),
+            w
+          );
+        };
+        return Q(() => M(
+          Z(
+            re,
+            (d) => c.createBuilderArgs({
+              helper: d.helper,
+              options: n,
+              context: r,
+              buildOptions: t,
+              artifact: x
+            }),
+            (d, g, w) => d.apply(g, w),
+            (d) => f(d)
+          ),
+          se
+        ), z);
+      });
+    });
+  }
+  const L = {
+    fragmentKind: b,
+    builderKind: m,
+    ir: {
+      use(e) {
+        N(e);
+      }
+    },
+    builders: {
+      use(e) {
+        I(e);
+      }
+    },
+    extensions: {
+      use(e) {
+        const n = e.register(L);
+        return n && typeof n?.then == "function" ? n.then(
+          (t) => J(e.key, t)
+        ) : J(e.key, n);
+      }
+    },
+    use(e) {
+      if (e.kind === b) {
+        N(e);
+        return;
+      }
+      if (e.kind === m) {
+        I(e);
+        return;
+      }
+      throw h(
+        "ValidationError",
+        `Unsupported helper kind "${e.kind}".`
+      );
+    },
+    run(e) {
+      const n = ee(e);
+      return te(n);
+    }
+  };
+  return L;
+}
+export {
+  ye as createPipeline
+};