@sanoma-ai/workflows 0.4.0 → 0.4.2

package/src/plugin.ts

@@ -1,15 +1,67 @@
 import { readDataFile } from "./datafile.ts";
 
-// An oxlint JS plugin with one rule, `sanoma/data-file`: the data-file subset `readResources`
-// reads, the same check as `lintResources`, on the tree oxlint has already parsed. The
-// package's `oxlint.json` turns it on for `resources/**`. Typed here by the little it uses, so
-// the package needs no oxlint types.
+// An oxlint JS plugin with two rules, on the trees oxlint has already parsed, which the package's
+// `oxlint.json` turns on: `sanoma/data-file` for `resources/**`, the data-file subset
+// `readResources` reads, the same check as `lintResources`; and `sanoma/date` for `workflows/**`,
+// `Date` reading the clock. Typed here by the little they use, so the package needs no oxlint types.
 
 interface Context {
   filename: string;
+  sourceCode: { isGlobalReference(node: Node): boolean };
   report(diagnostic: { message: string; node: { range: [number, number] } }): void;
 }
 
+/** A node of oxlint's ESTree, by the little the `date` rule reads. */
+interface Node {
+  type: string;
+  range: [number, number];
+  parent?: Node;
+  name?: string;
+  callee?: Node;
+  object?: Node;
+  property?: Node;
+  computed?: boolean;
+  arguments?: Node[];
+  operator?: string;
+  right?: Node;
+}
+
+const DATE_MESSAGE =
+  "Workflows are replayed, so a workflow reads the clock with `await ctx.now()`, never `Date`: `new Date(await ctx.now())` for a date, `new Date(value)`, `Date.parse` or `Date.UTC` for one it has, and `ctx.sleep({ until })` to wait for a date.";
+
+/** Where `Date` names the type, which the build erases: `d: Date`, `typeof Date`, `implements Date`. */
+const TYPE_PARENTS = new Set([
+  "TSTypeReference",
+  "TSTypeQuery",
+  "TSQualifiedName",
+  "TSClassImplements",
+  "TSInterfaceHeritage",
+]);
+
+/** `Date`'s functions that read no clock. */
+const PURE = new Set(["parse", "UTC"]);
+
+/**
+ * Whether `Date` (`node`) reads no clock where it is: `new Date(value)`, `Date.parse(…)`,
+ * `Date.UTC(…)`, `x instanceof Date`, or a type. A node without its parent is reported.
+ */
+function readsNoClock(node: Node): boolean {
+  const { parent } = node;
+  if (!parent) return false;
+  if (TYPE_PARENTS.has(parent.type)) return true;
+  if (parent.type === "BinaryExpression") return parent.operator === "instanceof" && parent.right === node;
+  if (parent.type === "NewExpression" && parent.callee === node) {
+    const [first] = parent.arguments ?? [];
+    return first !== undefined && first.type !== "SpreadElement";
+  }
+  return (
+    parent.type === "MemberExpression" &&
+    parent.object === node &&
+    !parent.computed &&
+    PURE.has(parent.property?.name ?? "")
+  );
+}
+
 const plugin = {
   meta: { name: "sanoma" },
   rules: {
@@ -31,6 +83,23 @@ const plugin = {
         };
       },
     },
+    // `Date` reads the clock in `Date.now()`, `new Date()` and `Date()`, which a replay would read
+    // again; a workflow reads it with `ctx.now()`, recorded. Every other use of `Date` is pure:
+    // `new Date(value)` (of `await ctx.now()`, or of a date the workflow has), `Date.parse`, `Date.UTC`.
+    date: {
+      meta: {
+        type: "problem",
+        docs: { description: "A workflow reads the clock with `await ctx.now()`, never `Date`" },
+      },
+      create(context: Context) {
+        return {
+          Identifier(node: Node) {
+            if (node.name !== "Date" || readsNoClock(node)) return;
+            if (context.sourceCode.isGlobalReference(node)) context.report({ message: DATE_MESSAGE, node });
+          },
+        };
+      },
+    },
   },
 };
 

package/src/scenario.ts

@@ -29,10 +29,11 @@ import {
 import { errorCode, errorInfo, SanomaError } from "./errors.ts";
 import { type CallRecord, contains, type CoreExpectation, detailOf, isCall } from "./expectations.ts";
 import type { Fake } from "./fake.ts";
-import { fill, isBug, seedFrom, shapeOf } from "./fill.ts";
+import { fill, isBug, objectUnder, restOf, seedFrom, shapeOf } from "./fill.ts";
 import type { LedgerRecord } from "./ledger.ts";
 import type { Driver, Op } from "./op.ts";
 import { type OutlineNode, outlineWorkflow } from "./outline.ts";
+import { isObject } from "./resource.ts";
 import { admit, type DeclaredPeople, readPeople } from "./resources.ts";
 import { memorySecrets } from "./secret.ts";
 import {
@@ -229,22 +230,50 @@ const FAULTS = {
   "loses its reply once": "loseReply",
 } as const;
 
-/** The schema of the field `name` of an object schema (`owner`, for the error); throws naming the fields it has. */
+/**
+ * The schema of the field `name` of an object schema (`owner`, for the error), or of the fields it
+ * takes besides its own (`restOf`); throws naming the fields it has.
+ */
 function fieldOf(schema: z.ZodType, name: string, owner: string): z.ZodType {
   const shape = shapeOf(schema);
-  if (!Object.hasOwn(shape, name)) {
-    throw new Error(`no field "${name}" in ${owner}; it has ${Object.keys(shape).join(", ") || "none"}`);
-  }
-  return shape[name]!;
+  if (Object.hasOwn(shape, name)) return shape[name]!;
+  const rest = restOf(schema);
+  if (rest) return rest;
+  throw new Error(`no field "${name}" in ${owner}; it has ${Object.keys(shape).join(", ") || "none"}`);
 }
 
 const issues = (error: z.ZodError) => error.issues.map((i) => i.message).join("; ");
 
+/**
+ * Why `field` refuses `value`, or undefined when it takes it. `partial`, for what a `Then` expects
+ * at least: an object may leave fields out at any depth, and only the fields it has are checked.
+ */
+function refusal(field: z.ZodType, value: unknown, what: string, partial: boolean): string | undefined {
+  const object = partial && isObject(value) ? objectUnder(field) : undefined;
+  if (object) return fieldsRefusal(object, value as Record<string, unknown>, what, true);
+  const parsed = field.safeParse(value);
+  return parsed.success ? undefined : `${what} cannot be ${JSON.stringify(value)}: ${issues(parsed.error)}`;
+}
+
+/** Why the object schema refuses the first of `fields` it refuses (`refusal`), `owner` its owner in errors. */
+function fieldsRefusal(
+  schema: z.ZodType,
+  fields: Record<string, unknown>,
+  owner: string,
+  partial: boolean,
+): string | undefined {
+  for (const [name, v] of Object.entries(fields)) {
+    const why = refusal(fieldOf(schema, name, owner), v, `${name} in ${owner}`, partial);
+    if (why) return why;
+  }
+  return undefined;
+}
+
 /**
  * The value text from a table cell or a phrase gives a field: the text itself when the field
  * takes it, else the text read as JSON (a number, `true`, a list) when the field takes that.
  */
-function valueFor(field: z.ZodType, text: string, what: string): unknown {
+function valueFor(field: z.ZodType, text: string, what: string, partial = false): unknown {
   const asText = field.safeParse(text);
   if (asText.success) return text;
   let json: unknown;
@@ -253,17 +282,18 @@ function valueFor(field: z.ZodType, text: string, what: string): unknown {
   } catch {
     throw new Error(`${what} cannot be ${JSON.stringify(text)}: ${issues(asText.error)}`);
   }
-  const asJson = field.safeParse(json);
-  if (!asJson.success) throw new Error(`${what} cannot be ${text}: ${issues(asJson.error)}`);
+  const why = refusal(field, json, what, partial);
+  if (why) throw new Error(why);
   return json;
 }
 
 /**
  * The fields the step's doc string (a JSON object) or two-column table gives `owner` (an
  * operation's input, or a resource), each checked against its field in `schema`: a field it
- * lacks, or a value it refuses, is an error.
+ * lacks, or a value it refuses, is an error. `partial` (a `Then`'s "at least these fields"):
+ * an object value may leave fields out, at any depth.
  */
-function fieldsFrom(pickle: PickleStep, schema: z.ZodType, owner: string): Record<string, unknown> {
+function fieldsFrom(pickle: PickleStep, schema: z.ZodType, owner: string, partial = false): Record<string, unknown> {
   const { docString, dataTable } = pickle.argument ?? {};
   const what = (name: string) => `${name} in ${owner}`;
   if (dataTable) {
@@ -271,7 +301,7 @@ function fieldsFrom(pickle: PickleStep, schema: z.ZodType, owner: string): Recor
       dataTable.rows.map(({ cells }) => {
         if (cells.length !== 2) throw new Error(`the table after "${pickle.text}" needs two columns: name | value`);
         const [name, text] = cells.map((c) => c.value) as [string, string];
-        return [name, valueFor(fieldOf(schema, name, owner), text, what(name))];
+        return [name, valueFor(fieldOf(schema, name, owner), text, what(name), partial)];
       }),
     );
   }
@@ -282,14 +312,10 @@ function fieldsFrom(pickle: PickleStep, schema: z.ZodType, owner: string): Recor
   } catch (err) {
     throw new Error(`the doc string after "${pickle.text}" is not JSON: ${errorMessage(err)}`, { cause: err });
   }
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new Error(`"${pickle.text}" needs a JSON object`);
-  }
-  for (const [name, v] of Object.entries(value)) {
-    const parsed = fieldOf(schema, name, owner).safeParse(v);
-    if (!parsed.success) throw new Error(`${what(name)} cannot be ${JSON.stringify(v)}: ${issues(parsed.error)}`);
-  }
-  return value as Record<string, unknown>;
+  if (!isObject(value)) throw new Error(`"${pickle.text}" needs a JSON object`);
+  const why = fieldsRefusal(schema, value, owner, partial);
+  if (why) throw new Error(why);
+  return value;
 }
 
 /** A parameter's transform: the name, when `ids` has it. */
@@ -504,7 +530,7 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
       source: "{op} was called with",
       takes: TAKES_OBJECT,
       read: ([op], pickle) =>
-        expecting({ op: op as string, input: fieldsFrom(pickle, opOf(op).input, inputOf(op)), called: true }),
+        expecting({ op: op as string, input: fieldsFrom(pickle, opOf(op).input, inputOf(op), true), called: true }),
     },
     ...[true, false].map((called): Rule => ({
       kind: "then",
@@ -545,7 +571,11 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
         // An unnamed call with a computed segment is named by the operation it calls.
         const op = scope.ops.get(node.id) ?? (node.name === undefined ? scope.ops.get(name as string) : undefined);
         if (!op) throw new Error(`${step} calls ${node.id}, whose input cannot be read: name its operation in full`);
-        return expecting({ name: name as string, input: fieldsFrom(pickle, op.input, inputOf(op.id)), called: true });
+        return expecting({
+          name: name as string,
+          input: fieldsFrom(pickle, op.input, inputOf(op.id), true),
+          called: true,
+        });
       },
     },
     ...[true, false].map((called): Rule => ({
@@ -603,7 +633,7 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
           const last = lastCall(records);
           if (typeof last === "string") return last;
           if (last.error) return `it failed: ${last.error.code ?? last.error.name}: ${last.error.message}`;
-          const expected = fieldsFrom(pickle, opOf(last.op).output, `${last.op}'s output`);
+          const expected = fieldsFrom(pickle, opOf(last.op).output, `${last.op}'s output`, true);
           return contains(last.output, expected) ? undefined : `it returned ${JSON.stringify(last.output)}`;
         },
       }),
@@ -707,9 +737,13 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
           transformer: (...g) => field(g),
         });
       }
+      // An `expect` phrase, like `was called with`, may give some of an object's fields.
       const given = (values: unknown[]) =>
         Object.fromEntries(
-          fields.map((name, i) => [name, valueFor(schemas[i]!, values[i] as string, `${name} in ${inputOf(op.id)}`)]),
+          fields.map((name, i) => [
+            name,
+            valueFor(schemas[i]!, values[i] as string, `${name} in ${inputOf(op.id)}`, kind === "then"),
+          ]),
         );
       const common = { source: template, group: op.id, expression: template.replaceAll(/\{([^}]*)\}/g, "{field_$1}") };
       rules.push(

package/src/vendor-info.ts

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import type { VendorInfo } from "./op.ts";
+import { upFrom } from "./paths.ts";
+
+/** A logo file's path in the package: relative, never out of it (`..`), an SVG. */
+const LogoFile = z.string().regex(/^(?!\/)(?!.*\.\.)[\w./-]+\.svg$/, "a relative path to an .svg file in the package");
+
+/**
+ * The `sanoma` field of a connector's package.json: the vendor's name and its logo files, beside
+ * package.json. The app reads the same field from npm to list connectors not installed.
+ */
+export const SanomaPackageField = z.object({
+  title: z.string().min(1),
+  logo: LogoFile.optional(),
+  logoDark: LogoFile.optional(),
+});
+
+/**
+ * A connector's `VendorInfo`, read from its own package.json, the one place it is written: the
+ * package's `name` and `homepage`, and the `sanoma` field's `title` and logo files, such as
+ * `"sanoma": { "title": "Ghost", "logo": "logo.svg", "logoDark": "logo-dark.svg" }`. The app
+ * lists connectors not installed from the same field on npm. `moduleUrl` is any module of the
+ * package, whose nearest package.json is read: `vendorInfo(import.meta.url)`.
+ */
+export function vendorInfo(moduleUrl: string | URL): VendorInfo {
+  const from = dirname(fileURLToPath(moduleUrl));
+  const root = upFrom(from, (dir) => (existsSync(join(dir, "package.json")) ? dir : undefined)) ?? from;
+  const read = (path: string) => readFileSync(join(root, path), "utf8").trim();
+  const pkg = JSON.parse(read("package.json")) as { name: string; homepage?: string; sanoma?: unknown };
+  const field = SanomaPackageField.safeParse(pkg.sanoma);
+  if (!field.success) {
+    throw new Error(
+      `${pkg.name}: package.json needs a "sanoma" field with a title, and logos as .svg paths in the package: ${z.prettifyError(field.error)}`,
+    );
+  }
+  const { title, logo, logoDark } = field.data;
+  const svg = (path: string) => {
+    try {
+      return read(path);
+    } catch {
+      throw new Error(`${pkg.name}: the "sanoma" field's logo ${path} is not in the package`);
+    }
+  };
+  return {
+    title,
+    ...(logo && { logo: { svg: svg(logo), ...(logoDark && { dark: svg(logoDark) }) } }),
+    package: pkg.name,
+    ...(pkg.homepage && { homepage: pkg.homepage }),
+  };
+}

package/src/version.ts

@@ -6,7 +6,7 @@ import { jsonSchemaOf, opIdsOf, type WorkflowDefinition } from "./define.ts";
 import { upFrom } from "./paths.ts";
 
 /** This package's version. A unit test keeps it equal to package.json. */
-export const RUNTIME_VERSION = "0.4.0";
+export const RUNTIME_VERSION = "0.4.2";
 
 /**
  * The sequence of DBOS calls the runtime makes around each `ctx` call: policy step, approval