@sanity/workflow-engine 0.9.0 → 0.11.0

package/dist/define.js

@@ -1,5 +1,5 @@
 import * as v from "valibot";
-import { andConditions, expandRequiredRoles, GROQ_IDENTIFIER, formatValidationError, issuesFromValibot, AuthoringWorkflowSchema, AuthoringStageSchema, AuthoringTaskSchema, AuthoringActionSchema, AuthoringTransitionSchema, AuthoringStateEntrySchema, AuthoringOpSchema, GuardSchema, EffectSchema } from "./_chunks-es/schema.js";
+import { andConditions, expandRequiredRoles, GROQ_IDENTIFIER, formatValidationError, issuesFromValibot, AuthoringWorkflowSchema, AuthoringStageSchema, AuthoringTaskSchema, AuthoringActionSchema, AuthoringTransitionSchema, AuthoringFieldEntrySchema, AuthoringOpSchema, GuardSchema, EffectSchema } from "./_chunks-es/schema.js";
 function groq(strings, ...values) {
   return strings.reduce((out, part, i) => i === 0 ? part : `${out}${serializeGroqValue(values[i - 1])}${part}`, "");
 }
@@ -14,13 +14,13 @@ function serializeGroqValue(value) {
 function desugarWorkflow(authoring) {
   const ctx = {
     issues: [],
-    claimStates: /* @__PURE__ */ new Map(),
-    claimedStates: /* @__PURE__ */ new Set(),
+    claimFields: /* @__PURE__ */ new Map(),
+    claimedFields: /* @__PURE__ */ new Set(),
     roleAliases: authoring.roleAliases
-  }, workflowState = desugarStateEntries(authoring.state, ["state"], ctx), workflowLayer = layerOf(workflowState), stages = authoring.stages.map((stage, i) => {
-    const path = ["stages", i], stageState = desugarStateEntries(stage.state, [...path, "state"], ctx), stageEnv = {
+  }, workflowFields = desugarFieldEntries(authoring.fields, ["fields"], ctx), workflowLayer = layerOf(workflowFields), stages = authoring.stages.map((stage, i) => {
+    const path = ["stages", i], stageFields = desugarFieldEntries(stage.fields, [...path, "fields"], ctx), stageEnv = {
       layers: [
-        { scope: "stage", entries: layerOf(stageState) },
+        { scope: "stage", entries: layerOf(stageFields) },
         { scope: "workflow", entries: workflowLayer }
       ]
     }, tasks = (stage.tasks ?? []).map(
@@ -29,7 +29,7 @@ function desugarWorkflow(authoring) {
       (transition, k) => desugarTransition(transition, [...path, "transitions", k], stageEnv, ctx)
     ), editable = desugarStageEditable(
       stage.editable,
-      editableSlotNames(workflowState, stageState, tasks),
+      editableSlotNames(workflowFields, stageFields, tasks),
       [...path, "editable"],
       ctx
     );
@@ -40,13 +40,13 @@ function desugarWorkflow(authoring) {
         description: stage.description,
         guards: stage.guards
       }),
-      ...stageState ? { state: stageState } : {},
+      ...stageFields ? { fields: stageFields } : {},
       ...tasks.length > 0 ? { tasks } : {},
       ...transitions.length > 0 ? { transitions } : {},
       ...editable ? { editable } : {}
     };
   });
-  return checkUnclaimedClaimStates(ctx), { definition: {
+  return checkUnclaimedClaimFields(ctx), { definition: {
     ...stripUndefined({
       name: authoring.name,
       version: authoring.version,
@@ -57,11 +57,11 @@ function desugarWorkflow(authoring) {
       predicates: authoring.predicates,
       roleAliases: authoring.roleAliases
     }),
-    ...workflowState ? { state: workflowState } : {},
+    ...workflowFields ? { fields: workflowFields } : {},
     stages
   }, issues: ctx.issues };
 }
-function desugarStateEntries(entries, path, ctx) {
+function desugarFieldEntries(entries, path, ctx) {
   return !entries || entries.length === 0 ? entries === void 0 ? void 0 : [] : entries.map((entry, i) => {
     if (entry.type === "claim") {
       const desugared = {
@@ -69,7 +69,7 @@ function desugarStateEntries(entries, path, ctx) {
         type: "value.actor",
         source: { type: "write" }
       };
-      return ctx.claimStates.set(desugared, { name: entry.name, path: [...path, i] }), desugared;
+      return ctx.claimFields.set(desugared, { name: entry.name, path: [...path, i] }), desugared;
     }
     const editable = normalizeEditable(entry.editable, [...path, i, "editable"], ctx);
     return {
@@ -100,12 +100,12 @@ function normalizeEditable(editable, path, ctx) {
   }
   return editable;
 }
-function editableSlotNames(workflowState, stageState, tasks) {
+function editableSlotNames(workflowFields, stageFields, tasks) {
   const names = /* @__PURE__ */ new Set(), collect = (entries) => {
     for (const entry of entries ?? []) entry.editable !== void 0 && names.add(entry.name);
   };
-  collect(workflowState), collect(stageState);
-  for (const task of tasks) collect(task.state);
+  collect(workflowFields), collect(stageFields);
+  for (const task of tasks) collect(task.fields);
   return names;
 }
 function desugarStageEditable(overrides, inScope, path, ctx) {
@@ -128,16 +128,17 @@ function layerOf(entries) {
   return new Map((entries ?? []).map((entry) => [entry.name, entry]));
 }
 function desugarTask(task, path, stageEnv, ctx) {
-  const taskState = desugarStateEntries(task.state, [...path, "state"], ctx), env = {
-    layers: [{ scope: "task", entries: layerOf(taskState) }, ...stageEnv.layers]
+  const taskFields = desugarFieldEntries(task.fields, [...path, "fields"], ctx), env = {
+    layers: [{ scope: "task", entries: layerOf(taskFields) }, ...stageEnv.layers]
   }, ops = desugarOps(task.ops, [...path, "ops"], env, task.name, ctx), actions = (task.actions ?? []).map(
     (action, a) => desugarAction(action, [...path, "actions", a], env, task.name, ctx)
-  );
+  ), target = desugarTarget(task.target, env, [...path, "target"], ctx);
   return {
     ...stripUndefined({
       name: task.name,
       title: task.title,
       description: task.description,
+      kind: task.kind,
       filter: task.filter,
       requirements: task.requirements,
       completeWhen: task.completeWhen,
@@ -146,11 +147,21 @@ function desugarTask(task, path, stageEnv, ctx) {
       subworkflows: task.subworkflows
     }),
     activation: task.activation ?? "manual",
-    ...taskState ? { state: taskState } : {},
+    ...target ? { target } : {},
+    ...taskFields ? { fields: taskFields } : {},
     ...ops ? { ops } : {},
     ...actions.length > 0 ? { actions } : {}
   };
 }
+const TARGET_DOC_KINDS = ["doc.ref", "doc.refs", "release.ref"];
+function desugarTarget(target, env, path, ctx) {
+  if (target === void 0 || target.type === "url") return target;
+  const ref = typeof target.field == "string" ? { field: target.field } : target.field, field = resolveRef(ref, env, [...path, "field"], ctx) ?? fallbackRef(ref), entry = entryAt(env, field);
+  return entry && !TARGET_DOC_KINDS.includes(entry.type) && ctx.issues.push({
+    path: [...path, "field"],
+    message: `manual task target references "${field.field}" of kind "${entry.type}" \u2014 a deep-link target needs a document-valued entry (${TARGET_DOC_KINDS.join(", ")})`
+  }), { type: "field", field };
+}
 function desugarAction(action, path, env, taskName, ctx) {
   if ("type" in action)
     return desugarClaimAction(action, path, env, ctx);
@@ -168,19 +179,19 @@ function desugarAction(action, path, env, taskName, ctx) {
   };
 }
 function desugarClaimAction(action, path, env, ctx) {
-  const ref = typeof action.state == "string" ? { state: action.state } : action.state, resolved = resolveRef(ref, env, [...path, "state"], ctx);
+  const ref = typeof action.field == "string" ? { field: action.field } : action.field, resolved = resolveRef(ref, env, [...path, "field"], ctx);
   if (resolved) {
     const entry = entryAt(env, resolved);
     entry && entry.type !== "value.actor" && ctx.issues.push({
-      path: [...path, "state"],
-      message: `claim action "${action.name}" references "${resolved.state}" of kind "${entry.type}" \u2014 a claim pair needs an actor-valued entry (a "claim" or "value.actor" state declaration)`
-    }), checkShadowedClaimTarget(action.name, ref.state, resolved, env, [...path, "state"], ctx), entry && ctx.claimedStates.add(entry);
+      path: [...path, "field"],
+      message: `claim action "${action.name}" references "${resolved.field}" of kind "${entry.type}" \u2014 a claim pair needs an actor-valued entry (a "claim" or "value.actor" field declaration)`
+    }), checkShadowedClaimTarget(action.name, ref.field, resolved, env, [...path, "field"], ctx), entry && ctx.claimedFields.add(entry);
   }
-  const noSteal = `!defined($state.${ref.state})`, filter = andConditions([
+  const noSteal = `!defined($fields.${ref.field})`, filter = andConditions([
     noSteal,
     rolesCondition(action.roles, ctx.roleAliases),
     action.filter
-  ]), ops = resolved ? [{ type: "state.set", target: resolved, value: { type: "actor" } }] : [];
+  ]), ops = resolved ? [{ type: "field.set", target: resolved, value: { type: "actor" } }] : [];
   return {
     ...stripUndefined({
       name: action.name,
@@ -193,18 +204,18 @@ function desugarClaimAction(action, path, env, ctx) {
     ...ops.length > 0 ? { ops } : {}
   };
 }
-function checkShadowedClaimTarget(actionName, state, resolved, env, path, ctx) {
-  const nearest = env.layers.find((l) => l.entries.has(state));
+function checkShadowedClaimTarget(actionName, field, resolved, env, path, ctx) {
+  const nearest = env.layers.find((l) => l.entries.has(field));
   nearest === void 0 || nearest.scope === resolved.scope || ctx.issues.push({
     path,
-    message: `claim action "${actionName}" targets "${state}" at scope "${resolved.scope}", but a nearer ${nearest.scope}-scope entry of the same name shadows it in $state \u2014 the no-steal filter would read the shadowing entry while the claim writes the "${resolved.scope}" one. Rename one of the entries or claim the nearer one`
+    message: `claim action "${actionName}" targets "${field}" at scope "${resolved.scope}", but a nearer ${nearest.scope}-scope entry of the same name shadows it in $fields \u2014 the no-steal filter would read the shadowing entry while the claim writes the "${resolved.scope}" one. Rename one of the entries or claim the nearer one`
   });
 }
-function checkUnclaimedClaimStates(ctx) {
-  for (const [entry, { name, path }] of ctx.claimStates)
-    ctx.claimedStates.has(entry) || ctx.issues.push({
+function checkUnclaimedClaimFields(ctx) {
+  for (const [entry, { name, path }] of ctx.claimFields)
+    ctx.claimedFields.has(entry) || ctx.issues.push({
       path,
-      message: `claim state "${name}" is never referenced by a claim action \u2014 you announced the pattern and wrote half of it. Declare a defineAction({ type: "claim", state: "${name}" }) or use a raw value.actor entry`
+      message: `claim field "${name}" is never referenced by a claim action \u2014 you announced the pattern and wrote half of it. Declare a defineAction({ type: "claim", field: "${name}" }) or use a raw value.actor entry`
     });
 }
 function desugarTransition(transition, path, stageEnv, ctx) {
@@ -244,7 +255,7 @@ function desugarAuditOp(op, path, env, ctx) {
     return ctx.issues.push({
       path: [...path, "value"],
       message: `audit value must be an object source carrying the domain fields (got "${op.value.type}")`
-    }), { type: "state.append", target, value: op.value };
+    }), { type: "field.append", target, value: op.value };
   const actorField = op.stampFields?.actor ?? "actor", atField = op.stampFields?.at ?? "at", fields = { ...op.value.fields };
   for (const [stamp, source] of [
     [actorField, AUDIT_STAMPS.actor],
@@ -259,23 +270,23 @@ function desugarAuditOp(op, path, env, ctx) {
     }
     fields[stamp] = source;
   }
-  return { type: "state.append", target, value: { type: "object", fields } };
+  return { type: "field.append", target, value: { type: "object", fields } };
 }
 function resolveRef(ref, env, path, ctx) {
   const layers = ref.scope === void 0 ? env.layers : env.layers.filter((l) => l.scope === ref.scope);
   for (const layer of layers)
-    if (layer.entries.has(ref.state)) return { scope: layer.scope, state: ref.state };
+    if (layer.entries.has(ref.field)) return { scope: layer.scope, field: ref.field };
   const reachable = env.layers.flatMap((l) => [...l.entries.keys()].map((n) => `${l.scope}:${n}`));
   ctx.issues.push({
     path,
-    message: `state reference "${ref.state}"${ref.scope ? ` (scope "${ref.scope}")` : ""} does not resolve to a declared entry. Reachable: ${reachable.join(", ") || "(none)"}`
+    message: `field reference "${ref.field}"${ref.scope ? ` (scope "${ref.scope}")` : ""} does not resolve to a declared entry. Reachable: ${reachable.join(", ") || "(none)"}`
   });
 }
 function entryAt(env, ref) {
-  return env.layers.find((l) => l.scope === ref.scope)?.entries.get(ref.state);
+  return env.layers.find((l) => l.scope === ref.scope)?.entries.get(ref.field);
 }
 function fallbackRef(ref) {
-  return { scope: ref.scope ?? "workflow", state: ref.state };
+  return { scope: ref.scope ?? "workflow", field: ref.field };
 }
 function rolesCondition(roles, aliases) {
   if (!(!roles || roles.length === 0))
@@ -288,7 +299,7 @@ function stripUndefined(obj) {
   return out;
 }
 const RESERVED_CONDITION_VARS = [
-  "state",
+  "fields",
   "actor",
   "assigned",
   "can",
@@ -409,43 +420,43 @@ function checkGuardNames(def, issues) {
     issues
   );
 }
-function stateScopes(def) {
+function fieldScopes(def) {
   const scopes = [
-    { entries: def.state, scope: "workflow", path: ["state"], label: "workflow state" }
+    { entries: def.fields, scope: "workflow", path: ["fields"], label: "workflow fields" }
   ];
   for (const [i, stage] of def.stages.entries()) {
     scopes.push({
-      entries: stage.state,
+      entries: stage.fields,
       scope: "stage",
-      path: ["stages", i, "state"],
-      label: `stage "${stage.name}" state`
+      path: ["stages", i, "fields"],
+      label: `stage "${stage.name}" fields`
     });
     for (const [j, task] of (stage.tasks ?? []).entries())
       scopes.push({
-        entries: task.state,
+        entries: task.fields,
         scope: "task",
-        path: ["stages", i, "tasks", j, "state"],
-        label: `task "${task.name}" state`
+        path: ["stages", i, "tasks", j, "fields"],
+        label: `task "${task.name}" fields`
       });
   }
   return scopes;
 }
-function checkRequiredState(def, issues) {
-  for (const { entries, scope, path, label } of stateScopes(def))
+function checkRequiredField(def, issues) {
+  for (const { entries, scope, path, label } of fieldScopes(def))
     for (const [n, entry] of (entries ?? []).entries())
       entry.required === !0 && (scope !== "workflow" ? issues.push({
         path: [...path, n, "required"],
         message: `${label} entry "${entry.name}" is \`required\`, but \`required\` applies only to workflow-scope \`init\` entries \u2014 only those are caller-supplied at start/spawn`
       }) : entry.source.type !== "init" && issues.push({
         path: [...path, n, "required"],
-        message: `state entry "${entry.name}" is \`required\` but its source is "${entry.source.type}" \u2014 \`required\` applies only to \`init\`-sourced entries (the caller fills them at start/spawn)`
+        message: `field entry "${entry.name}" is \`required\` but its source is "${entry.source.type}" \u2014 \`required\` applies only to \`init\`-sourced entries (the caller fills them at start/spawn)`
       }));
 }
-function checkStateEntryNames(def, issues) {
-  for (const { entries, path, label } of stateScopes(def))
+function checkFieldEntryNames(def, issues) {
+  for (const { entries, path, label } of fieldScopes(def))
     checkDuplicates(
       (entries ?? []).map((entry, n) => ({ name: entry.name, path: [...path, n, "name"] })),
-      `state entry name in ${label}`,
+      `field entry name in ${label}`,
       issues
     );
 }
@@ -545,15 +556,55 @@ function collectBindingSites(effects, path, label, sites) {
       });
 }
 function checkAssigneesEntries(def, issues) {
-  for (const { entries, path } of stateScopes(def))
+  for (const { entries, path } of fieldScopes(def))
     (entries ?? []).filter((e) => e.type === "assignees").length <= 1 || issues.push({
       path,
-      message: "at most one assignees-kind state entry per scope \u2014 the inbox reads it by kind"
+      message: "at most one assignees-kind field entry per scope \u2014 the inbox reads it by kind"
     });
 }
+function taskShape(task) {
+  return {
+    hasActions: (task.actions ?? []).length > 0,
+    hasEffects: (task.effects ?? []).length > 0,
+    hasCompleteWhen: task.completeWhen !== void 0,
+    hasSubworkflows: task.subworkflows !== void 0
+  };
+}
+const KIND_SHAPE_RULES = {
+  user: (s) => s.hasActions ? [] : ["needs at least one action for a person to fire"],
+  service: (s) => s.hasEffects ? [] : ["needs at least one effect \u2014 the automated work it performs"],
+  manual: (s) => [
+    s.hasActions || s.hasCompleteWhen ? void 0 : "needs a way to complete \u2014 an action to acknowledge it, or a `completeWhen` predicate to verify it (otherwise it auto-resolves on activation)",
+    s.hasSubworkflows ? "is off-system work, not a fan-out \u2014 drop `subworkflows` or move it to its own task" : void 0
+  ].filter((m) => m !== void 0),
+  receive: (s) => [
+    s.hasCompleteWhen || s.hasSubworkflows ? void 0 : "needs a `completeWhen` (or `subworkflows`) condition to wait on",
+    s.hasActions ? "has no actor, so it cannot carry actions" : void 0
+  ].filter((m) => m !== void 0),
+  script: (s) => [
+    s.hasActions ? "runs inline with no actor, so it cannot carry actions" : void 0,
+    s.hasCompleteWhen ? "resolves on activation, so it cannot carry a `completeWhen` (that is a `receive`/`service` wait)" : void 0,
+    s.hasSubworkflows ? "resolves on activation, so it cannot fan out with `subworkflows`" : void 0
+  ].filter((m) => m !== void 0)
+};
+function checkTaskKinds(def, issues) {
+  for (const [i, stage] of def.stages.entries())
+    for (const [j, task] of (stage.tasks ?? []).entries()) {
+      const path = ["stages", i, "tasks", j];
+      if (task.target !== void 0 && task.kind !== "manual" && issues.push({
+        path: [...path, "target"],
+        message: `task "${task.name}" has a \`target\` but is not \`kind: "manual"\` \u2014 a target is the deep-link for off-system manual work`
+      }), task.kind !== void 0)
+        for (const fault of KIND_SHAPE_RULES[task.kind](taskShape(task)))
+          issues.push({
+            path: [...path, "kind"],
+            message: `task "${task.name}" declares kind "${task.kind}" but ${fault}`
+          });
+    }
+}
 function checkWorkflowInvariants(def) {
   const issues = [], stageNames = checkStages(def, issues);
-  return checkInitialStage(def, stageNames, issues), checkTransitionTargets(def, stageNames, issues), checkEffectNames(def, issues), checkGuardNames(def, issues), checkStateEntryNames(def, issues), checkRequiredState(def, issues), checkPredicates(def, issues), checkCanOutsideActionFilters(def, issues), checkAssigneesEntries(def, issues), issues;
+  return checkInitialStage(def, stageNames, issues), checkTransitionTargets(def, stageNames, issues), checkEffectNames(def, issues), checkGuardNames(def, issues), checkFieldEntryNames(def, issues), checkRequiredField(def, issues), checkPredicates(def, issues), checkCanOutsideActionFilters(def, issues), checkAssigneesEntries(def, issues), checkTaskKinds(def, issues), issues;
 }
 function defineWorkflow(definition) {
   const label = labelFor("defineWorkflow", definition), parsed = parseOrThrow(AuthoringWorkflowSchema, definition, label), { definition: stored, issues: desugarIssues } = desugarWorkflow(parsed), issues = [...desugarIssues, ...checkWorkflowInvariants(stored)];
@@ -572,8 +623,8 @@ function defineAction(action) {
 function defineTransition(transition) {
   return parseOrThrow(AuthoringTransitionSchema, transition, transitionLabel(transition));
 }
-function defineState(entry) {
-  return parseOrThrow(AuthoringStateEntrySchema, entry, labelFor("defineState", entry));
+function defineField(entry) {
+  return parseOrThrow(AuthoringFieldEntrySchema, entry, labelFor("defineField", entry));
 }
 function defineOp(op) {
   return parseOrThrow(AuthoringOpSchema, op, "defineOp");
@@ -609,10 +660,10 @@ export {
   defineAction,
   defineEffect,
   defineEffectDescriptor,
+  defineField,
   defineGuard,
   defineOp,
   defineStage,
-  defineState,
   defineTask,
   defineTransition,
   defineWorkflow,