@nanobpm/urban 0.17.1 → 0.18.0

package/src/toolkit/models.ts

@@ -0,0 +1,193 @@
+// Model derivation for code-first apps — the toolkit's one *executing* edge.
+//
+// Unlike the pure derivers (migrations, domain, worker I/O), which transform strings, this
+// imports the app's `workflows/*.ts`, turns each `defineFlow` into executable BPMN via
+// `@nanobpm/workflow` (`toBpmn` + `bpmn-auto-layout` DI), and writes `processes/<id>.bpmn`.
+// Executing the app's TypeScript needs a runtime module loader, so this is gated on the
+// optional `GenIO.importModule` (present on Node with type-stripping, and on Deno). When the
+// loader is absent — or the app authors its models directly (model-first) — derivation is a
+// no-op and the rest of `urban gen` proceeds on the authored/derived models unchanged.
+
+import { toDeployableBpmn } from "@nanobpm/workflow";
+import type { Workflow } from "@nanobpm/workflow";
+import type { DerivedArtifact } from "./artifact.ts";
+import type { GenIO } from "./gen.ts";
+import { expandPattern, joinPath } from "./gen.ts";
+import type { ModelSource } from "./derivers/worker-io.ts";
+
+/** Default source glob for code-first flows (matches the code-first scaffold layout). */
+export const DEFAULT_WORKFLOW_PATTERNS = ["workflows/*.ts"];
+
+/** Default output dir for derived models (matches the model-first scaffold, so a derived
+ * model is ejectable to model-first and picked up by `models.processes: ["processes/*.bpmn"]`). */
+export const PROCESSES_DIR = "processes";
+
+/** Marker stamped into every derived `.bpmn` (an XML comment) so re-gen overwrites and the
+ * stale sweep deletes ONLY derived output — never an authored, human-owned model. */
+export const MODEL_PROVENANCE =
+  "Generated by @nanobpm/urban from workflows/*.ts — do not edit; edit the flow and re-run `urban gen`.";
+
+/** Minimal shape a code-first manifest declares for model derivation. */
+export interface ModelsManifest {
+  models?: { processes?: string[]; workflows?: string[] };
+}
+
+/** A `defineFlow` export: has a string `id` and an `imperative`/`declarative` `kind`. */
+export function isWorkflow(v: unknown): v is Workflow {
+  if (!v || typeof v !== "object") return false;
+  const o = v as { id?: unknown; kind?: unknown };
+  return typeof o.id === "string" && (o.kind === "imperative" || o.kind === "declarative");
+}
+
+/** Sanitize a flow id into a safe `.bpmn` filename (mirrors the host generator). */
+export function bpmnFilename(id: string): string {
+  return `${id.replace(/[^A-Za-z0-9._-]/g, "-")}.bpmn`;
+}
+
+/** The directory derived models are written to: the dir of the first `models.processes`
+ * glob if the manifest declares one, else the `processes/` default. */
+export function processesOutDir(manifest: ModelsManifest): string {
+  for (const pat of manifest.models?.processes ?? []) {
+    const star = pat.indexOf("*");
+    const slash = star === -1 ? pat.lastIndexOf("/") : pat.lastIndexOf("/", star);
+    if (slash > 0) return pat.slice(0, slash);
+  }
+  return PROCESSES_DIR;
+}
+
+/** Insert the provenance marker as an XML comment right after the `<?xml … ?>` prolog. */
+function withProvenance(xml: string): string {
+  const comment = `<!-- ${MODEL_PROVENANCE} -->`;
+  const m = xml.match(/^\uFEFF?\s*<\?xml[^>]*\?>/);
+  if (m) return `${m[0]}\n${comment}\n${xml.slice(m[0].length).replace(/^\r?\n/, "")}`;
+  return `${comment}\n${xml}`;
+}
+
+export interface ModelError {
+  path: string;
+  message: string;
+}
+
+export interface DerivedModels {
+  /** `processes/<id>.bpmn` artifacts (path + provenance-stamped content). */
+  artifacts: DerivedArtifact[];
+  /** The same models, in-memory, for feeding the type-contract derivers (worker I/O, meta, messages). */
+  models: ModelSource[];
+  /** Derived flow ids (used for the provenance-scoped stale sweep). */
+  ids: string[];
+  /** Per-flow `{ id, kind, xml }` for the non-writing preview (`urban derive --stdout`). */
+  list: DerivedModelInfo[];
+  /** The output directory the artifacts were written into. */
+  outDir: string;
+  /** True once we attempted derivation (loader present AND at least one workflow file matched). */
+  attempted: boolean;
+  /** True if any workflow module failed to import/derive — suppresses the destructive sweep. */
+  incomplete: boolean;
+  /** Per-file derivation errors (empty on full success). */
+  errors: ModelError[];
+}
+
+export interface DerivedModelInfo {
+  id: string;
+  kind: Workflow["kind"];
+  xml: string;
+}
+
+function emptyDerived(outDir: string): DerivedModels {
+  return {
+    artifacts: [],
+    models: [],
+    ids: [],
+    list: [],
+    outDir,
+    attempted: false,
+    incomplete: false,
+    errors: [],
+  };
+}
+
+function messageOf(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/** Append an actionable hint when a `.ts` import fails because the runtime can't strip types. */
+function importHint(rel: string, e: unknown): string {
+  const base = messageOf(e);
+  const code = (e as { code?: string })?.code ?? "";
+  const looksLikeNoTsLoader =
+    rel.endsWith(".ts") &&
+    (code === "ERR_UNKNOWN_FILE_EXTENSION" || /Unknown file extension "\.ts"/.test(base));
+  if (!looksLikeNoTsLoader) return base;
+  return (
+    `${base}\n    ↳ importing TypeScript workflows needs a runtime that strips types: ` +
+    "Node ≥22.18 (default) or `node --experimental-strip-types`, or run under Deno."
+  );
+}
+
+/**
+ * Derive executable BPMN models from an app's code-first `workflows/*.ts`.
+ *
+ * Returns everything in-memory (artifacts + `ModelSource`s + ids). The caller decides whether
+ * to write the `.bpmn` to disk (`urban gen` / `urban derive`) or keep them in memory to feed
+ * the type-contract derivers only (`urban gen --no-models`) or preview them (`urban derive
+ * --stdout`). Never throws on a bad workflow: a failing module is recorded in `errors`,
+ * `incomplete` is set, and the sweep is suppressed so a partial failure can't delete good models.
+ */
+export async function deriveModels(
+  root: string,
+  io: GenIO,
+  manifest: ModelsManifest,
+): Promise<DerivedModels> {
+  const outDir = processesOutDir(manifest);
+  const importModule = io.importModule;
+  if (!importModule) return emptyDerived(outDir);
+
+  const patterns = manifest.models?.workflows ?? DEFAULT_WORKFLOW_PATTERNS;
+  const files: string[] = [];
+  for (const pat of patterns) {
+    for (const rel of await expandPattern(root, io, pat)) files.push(rel);
+  }
+  if (files.length === 0) return emptyDerived(outDir);
+
+  const out: DerivedModels = { ...emptyDerived(outDir), attempted: true };
+  // id → { source file, workflow ref } — distinguishes a genuine re-export (same
+  // object under two export names) from a true collision (two distinct flows, one id).
+  const byId = new Map<string, { rel: string; ref: unknown }>();
+
+  for (const rel of files.sort()) {
+    let mod: Record<string, unknown>;
+    try {
+      mod = await importModule(joinPath(root, rel));
+    } catch (e) {
+      out.incomplete = true;
+      out.errors.push({ path: rel, message: importHint(rel, e) });
+      continue;
+    }
+    for (const value of Object.values(mod)) {
+      if (!isWorkflow(value)) continue;
+      const id = value.id;
+      const prior = byId.get(id);
+      if (prior) {
+        if (prior.ref === value && prior.rel === rel) continue; // genuine intra-module re-export
+        out.incomplete = true;
+        const where = prior.rel === rel ? "also defined in the same module" : `also defined in ${prior.rel}`;
+        out.errors.push({ path: rel, message: `duplicate flow id "${id}" (${where})` });
+        continue;
+      }
+      byId.set(id, { rel, ref: value });
+      try {
+        const semantic = await toDeployableBpmn(value);
+        const xml = withProvenance(semantic);
+        const path = `${outDir}/${bpmnFilename(id)}`;
+        out.artifacts.push({ path, content: xml });
+        out.models.push({ path, xml });
+        out.list.push({ id, kind: value.kind, xml });
+        out.ids.push(id);
+      } catch (e) {
+        out.incomplete = true;
+        out.errors.push({ path: rel, message: `deriving "${id}": ${messageOf(e)}` });
+      }
+    }
+  }
+  return out;
+}