@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/src/approvals.ts

@@ -0,0 +1,157 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { z } from "zod";
+import { type ApprovalRequest, type ApprovalResult, type ApprovalState, notApprover, Principal } from "./define.ts";
+import { RejectedError } from "./errors.ts";
+import { entry, write } from "./ledger.ts";
+import { warn } from "./log.ts";
+import type { Placed } from "./call.ts";
+import type { Run } from "./run.ts";
+import { approverLabel, mayDecide } from "./shared.ts";
+
+// The wire contract between a run waiting on approvals and whoever decides them. The client
+// imports this file and never the worker's.
+
+/** The DBOS event a run publishes its approvals on, as `ApprovalState[]`. */
+export const APPROVALS_EVENT = "approvals";
+/** The `recv` topic a decision on an approval is sent to. */
+export const topicOf = (approvalId: string) => approvalId;
+/** The DBOS event an approval's decision is published on, as its decided `ApprovalState`, once made. */
+export const decisionEventOf = (approvalId: string) => `approval:${approvalId}`;
+/**
+ * The idempotency key a decision message is sent with, so a retried send queues it once. DBOS
+ * scopes the key per run, not per topic, so it names the approval too: one message id reused
+ * for two approvals of a run would otherwise drop the second send.
+ */
+export const messageKeyOf = (approvalId: string, messageId: string) => `${approvalId}:${messageId}`;
+
+/**
+ * A decision, as sent to a run. `id` names the message, so whoever sent it can tell whether
+ * the run decided with it or with another; `SanomaClient.decide` sets one.
+ */
+export const ApprovalMessage = z.object({
+  id: z.string().optional(),
+  decision: z.enum(["approve", "reject"]),
+  by: Principal,
+  note: z.string().optional(),
+});
+export type ApprovalMessage = z.infer<typeof ApprovalMessage>;
+
+const statusOf = (decision: ApprovalMessage["decision"]) => (decision === "approve" ? "approved" : "rejected");
+
+/** The sender's id, from a message that may not be a valid decision. */
+function senderOf(raw: unknown): string | undefined {
+  const by = typeof raw === "object" && raw !== null ? (raw as { by?: unknown }).by : undefined;
+  const id = typeof by === "object" && by !== null ? (by as { id?: unknown }).id : undefined;
+  return typeof id === "string" && id ? id : undefined;
+}
+
+/** An approval request as checked: who may decide it, and the operations it covers, by id. */
+export interface CheckedApproval extends Omit<ApprovalRequest, "covers"> {
+  covers: string[];
+}
+
+/** A policy's hold: the call held, and the ledger `seq` its `op.called` record takes. */
+export interface HeldCall {
+  op: string;
+  seq: number;
+  input: unknown;
+}
+
+/**
+ * Waits, durably, for a decision from someone who may make it. Throws `RejectedError` on a
+ * rejection. Without `held`, the workflow asked (`ctx.approval`); with it, the policy did, and
+ * `place` is the held call's outline node and name.
+ */
+export async function awaitApproval(
+  run: Run,
+  title: string,
+  req: CheckedApproval,
+  place: Placed,
+  held?: HeldCall,
+): Promise<ApprovalResult> {
+  const { covers } = req;
+  const all = run.approvals;
+  const state: ApprovalState = {
+    id: `approval-${all.length + 1}`,
+    title,
+    approver: req.approver,
+    ...(req.links === undefined ? {} : { links: req.links }),
+    ...(req.details === undefined ? {} : { details: req.details }),
+    requestedBy: held ? "policy" : "workflow",
+    covers,
+    ...(held ? { op: held.op, opSeq: held.seq, input: held.input } : {}),
+    status: "pending",
+    requestedAt: 0,
+    refused: [],
+  };
+  all.push(state);
+  state.requestedAt = await DBOS.now();
+  await DBOS.setEvent(APPROVALS_EVENT, all);
+  await write(
+    run,
+    entry(
+      run,
+      {
+        type: "approval.requested",
+        approval: state.id,
+        ...place,
+        title,
+        approver: state.approver,
+        requestedBy: state.requestedBy,
+        covers,
+        ...(held ? { op: held.op, opSeq: held.seq } : {}),
+      },
+      { key: state.id, at: state.requestedAt },
+    ),
+  );
+  for (;;) {
+    const raw = await DBOS.recv<unknown>(topicOf(state.id), { timeoutSeconds: 24 * 60 * 60 });
+    if (raw === null || raw === undefined) {
+      warn(`run ${run.id}: approval ${state.id} ("${title}") is still waiting for ${approverLabel(state.approver)}`);
+      continue;
+    }
+    const at = await DBOS.now();
+    const parsed = ApprovalMessage.safeParse(raw);
+    const msg = parsed.success ? parsed.data : undefined;
+    if (!msg || !mayDecide(state, msg.by)) {
+      const by = msg?.by.id ?? senderOf(raw);
+      const reason = msg ? notApprover(state, msg.by) : "not a valid decision message";
+      state.refused.push({
+        ...(by === undefined ? {} : { by }),
+        ...(msg?.id === undefined ? {} : { id: msg.id }),
+        at,
+        reason,
+      });
+      await DBOS.setEvent(APPROVALS_EVENT, all);
+      await write(
+        run,
+        entry(
+          run,
+          { type: "approval.refused", approval: state.id, ...(by === undefined ? {} : { by }), reason },
+          { key: `${state.id}:refused:${state.refused.length}`, at },
+        ),
+      );
+      continue;
+    }
+    Object.assign(state, {
+      status: statusOf(msg.decision),
+      decidedBy: msg.by.id,
+      decidedAt: at,
+      note: msg.note,
+      decidedWith: msg.id,
+    });
+    // The list first, then the ledger, then the decision event: whoever sees the event sees both.
+    await DBOS.setEvent(APPROVALS_EVENT, all);
+    await write(
+      run,
+      entry(
+        run,
+        { type: "approval.decided", approval: state.id, decision: msg.decision, by: msg.by.id, note: msg.note },
+        { key: state.id, at },
+      ),
+    );
+    await DBOS.setEvent(decisionEventOf(state.id), state);
+    if (msg.decision === "reject") throw new RejectedError(title, msg.by, msg.note, state.id);
+    return { approvedBy: msg.by.id, at, note: msg.note };
+  }
+}

package/src/ast.ts

@@ -0,0 +1,115 @@
+import { readFileSync } from "node:fs";
+import { parseSync, visitorKeys } from "oxc-parser";
+import { errorMessage } from "./shared.ts";
+
+// What the lints, the outline and the data-file reader share: one way to parse a file, walk it
+// and say where in it a problem is.
+
+/** oxc-parser's ESTree nodes, read by shape. */
+export type Node = any;
+
+/** Parses TypeScript, which covers the JavaScript a built package holds, as a module; a `.tsx` or `.jsx` file with its JSX. */
+export const parse = (filename: string, source: string) =>
+  parseSync(filename, source, {
+    lang: /\.[jt]sx$/.test(filename) ? "tsx" : "ts",
+    sourceType: "module",
+    preserveParens: false,
+  });
+
+// The keys that hold types, not code: nothing the lint or the outline looks for is in them.
+const TYPE_KEYS = new Set([
+  "typeAnnotation",
+  "typeParameters",
+  "returnType",
+  "typeArguments",
+  "superTypeArguments",
+  "implements",
+]);
+
+const CODE_KEYS = new Map(
+  Object.entries(visitorKeys).map(([type, keys]) => [type, keys.filter((key) => !TYPE_KEYS.has(key))]),
+);
+
+/** A node's children in source order, by oxc-parser's `visitorKeys`, without its types. A hole in a list is `null`. */
+export const childrenOf = (node: Node): Node[] => (CODE_KEYS.get(node.type) ?? []).flatMap((key) => node[key] ?? []);
+
+/**
+ * The offset each line of `source` starts at, from line 1, and one past the end of the text as
+ * the start of the line after the last: where each line ends is the next start, less its `\n`.
+ */
+export const lineStartsOf = (source: string): number[] => {
+  const lineStarts = [0];
+  for (let i = 0; i < source.length; i++) if (source[i] === "\n") lineStarts.push(i + 1);
+  lineStarts.push(source.length + 1);
+  return lineStarts;
+};
+
+/** Where an offset into `source` is, as a line and a column, both from 1. */
+export function locator(source: string): (offset: number) => { line: number; column: number } {
+  const lineStarts = lineStartsOf(source);
+  return (offset) => {
+    let line = 0;
+    while (line + 1 < lineStarts.length && lineStarts[line + 1]! <= offset) line++;
+    return { line: line + 1, column: offset - lineStarts[line]! + 1 };
+  };
+}
+
+/**
+ * The offset into a text of a line and column, both from 1, as a stack frame gives them, from
+ * the text's `lineStartsOf`; or undefined when the text has no such line, or the line no such
+ * column (a frame mapped wrong must not land in the next line). The column is taken as a UTF-16
+ * unit index, as V8 counts it.
+ */
+export function offsetOf(lineStarts: readonly number[], line: number, column: number): number | undefined {
+  const start = lineStarts[line - 1];
+  const next = lineStarts[line];
+  if (line < 1 || column < 1 || start === undefined || next === undefined) return undefined;
+  const offset = start + column - 1;
+  return offset < next - 1 ? offset : undefined;
+}
+
+/** Something wrong in a file, at a line and column from 1. */
+export interface LintProblem {
+  line: number;
+  column: number;
+  message: string;
+}
+
+/** A file parsed, its syntax errors as problems, and offsets as lines and columns from 1. */
+export function parsed(source: string, filename: string) {
+  const { program, errors } = parse(filename, source);
+  const at = locator(source);
+  const problems: LintProblem[] = errors.map((e) => ({
+    ...at(e.labels?.[0]?.start ?? 0),
+    message: `syntax: ${e.message}`,
+  }));
+  return { program: program as Node, problems, at };
+}
+
+/**
+ * A file read and parsed once, for the outline and the lint alike: its text with `\n` line
+ * endings (CodeMirror counts a line break as one unit, oxc counts `\r\n` as two, and spans need
+ * `\n` alone), its program, offsets as lines and columns, and its syntax problems.
+ */
+export interface SourceFile {
+  file: string;
+  source: string;
+  program: Node;
+  at: (offset: number) => { line: number; column: number };
+  problems: LintProblem[];
+}
+
+/** Reads and parses `file`; or why it could not be read, as a message naming it. */
+export function readSource(file: string): SourceFile | string {
+  let source: string;
+  try {
+    source = readFileSync(file, "utf8").replaceAll("\r\n", "\n");
+  } catch (err) {
+    return `${file} could not be read: ${errorMessage(err)}`;
+  }
+  return { file, source, ...parsed(source, file) };
+}
+
+/** Problems in the order of their place in the file. */
+export const byPosition = <P extends Omit<LintProblem, "message">>(problems: P[]): P[] =>
+  problems.toSorted((a, b) => a.line - b.line || a.column - b.column);