@ripplo/testing 0.0.6 → 0.0.8

package/dist/lockfile.js

@@ -0,0 +1,615 @@
+// src/lockfile.ts
+import fs from "fs/promises";
+import path from "path";
+
+// ../spec/src/codec.ts
+import { z } from "zod";
+var envelopeSchema = z.object({
+  __codec: z.string().min(1),
+  data: z.unknown(),
+  version: z.number().int().positive()
+});
+var CodecVersionError = class extends Error {
+  codec;
+  currentVersion;
+  gotVersion;
+  constructor(params) {
+    super(
+      `Unsupported ${params.codec} version ${String(params.gotVersion)} (current ${String(params.currentVersion)}). Upgrade Ripplo or rebuild with a compatible CLI.`
+    );
+    this.name = "CodecVersionError";
+    this.codec = params.codec;
+    this.currentVersion = params.currentVersion;
+    this.gotVersion = params.gotVersion;
+  }
+};
+var CodecMismatchError = class extends Error {
+  constructor(params) {
+    super(`Codec mismatch: expected "${params.expected}", got "${params.got}"`);
+    this.name = "CodecMismatchError";
+  }
+};
+function defineCodec(name) {
+  return makeInitial({ legacy: void 0, migrators: [], name, schemas: [] });
+}
+function decodeJson(codec, raw) {
+  const parsed = JSON.parse(raw);
+  return codec.decode(parsed);
+}
+function makeInitial(state) {
+  return {
+    initial: (schema) => makeBuilder(schema, { ...state, schemas: [schema] }),
+    legacy: (adapter) => makeInitial({ ...state, legacy: adapter })
+  };
+}
+function makeBuilder(latestSchema, state) {
+  return {
+    build: () => buildCodec(latestSchema, state),
+    legacy: (adapter) => makeBuilder(latestSchema, { ...state, legacy: adapter }),
+    upgrade: (schema, up) => {
+      const erased = up;
+      return makeBuilder(schema, {
+        ...state,
+        migrators: [...state.migrators, erased],
+        schemas: [...state.schemas, schema]
+      });
+    }
+  };
+}
+function buildCodec(latestSchema, state) {
+  const currentVersion = state.schemas.length;
+  return {
+    currentVersion,
+    name: state.name,
+    decode: (raw) => decodeWith(latestSchema, state, raw),
+    encode: (value) => ({
+      __codec: state.name,
+      data: value,
+      version: currentVersion
+    })
+  };
+}
+function decodeWith(latestSchema, state, raw) {
+  const { data, version } = unwrapEnvelope(state, raw);
+  const migrated = migrateStep(state, data, version);
+  return latestSchema.parse(migrated);
+}
+function unwrapEnvelope(state, raw) {
+  const envelopeResult = envelopeSchema.safeParse(raw);
+  if (envelopeResult.success) {
+    if (envelopeResult.data.__codec !== state.name) {
+      throw new CodecMismatchError({
+        expected: state.name,
+        got: envelopeResult.data.__codec
+      });
+    }
+    return {
+      data: envelopeResult.data.data,
+      version: envelopeResult.data.version
+    };
+  }
+  if (state.legacy != null && state.legacy.detect(raw)) {
+    return { data: raw, version: state.legacy.assumedVersion };
+  }
+  throw new Error(
+    `Cannot decode "${state.name}": value is not a codec envelope and no legacy detector matched.`
+  );
+}
+function migrateStep(state, data, version) {
+  const currentVersion = state.schemas.length;
+  if (version > currentVersion) {
+    throw new CodecVersionError({
+      codec: state.name,
+      currentVersion,
+      gotVersion: version
+    });
+  }
+  if (version === currentVersion) {
+    return data;
+  }
+  const sourceSchema = state.schemas[version - 1];
+  if (sourceSchema == null) {
+    throw new Error(
+      `Codec "${state.name}" missing schema for v${String(version)}; cannot migrate.`
+    );
+  }
+  const validated = sourceSchema.parse(data);
+  const migrator = state.migrators[version - 1];
+  if (migrator == null) {
+    throw new Error(
+      `Codec "${state.name}" missing migrator v${String(version)} \u2192 v${String(version + 1)}.`
+    );
+  }
+  return migrateStep(state, migrator(validated), version + 1);
+}
+
+// ../spec/src/codecs.ts
+import { z as z11 } from "zod";
+
+// ../spec/src/graph.ts
+import { z as z5 } from "zod";
+
+// ../spec/src/edge.ts
+import { z as z2 } from "zod";
+var edgeSchema = z2.object({
+  from: z2.string().min(1).describe("Key of the source state in the states record"),
+  requiresKeys: z2.record(z2.string(), z2.string()).optional().describe(
+    "Maps workflow variable namespace to precondition name. Used by the runtime to namespace batch precondition data into dot-namespaced variables (e.g. { project: 'data:project' } maps projectId \u2192 project.projectId)."
+  ),
+  to: z2.string().min(1).describe("Key of the target state in the states record"),
+  workflow: z2.string().min(1).describe(
+    "Filename (without .json) of the workflow in .ripplo/workflows/ that executes this edge"
+  )
+}).describe("A directed edge between two states, executed by a workflow");
+
+// ../spec/src/precondition.ts
+import { z as z3 } from "zod";
+var preconditionSchema = z3.object({
+  depends: z3.array(z3.string().min(1)).optional().describe(
+    "Names of other preconditions that must be satisfied first. Resolved via topological sort; cycles are rejected at validation time."
+  ),
+  description: z3.string().min(1).describe("Human-readable description of what this precondition ensures"),
+  returns: z3.array(z3.string().min(1)).optional().describe(
+    "Keys that the execute response's data field will contain. e.g. ['projectId', 'workflowId']. These are used for route param interpolation ({{projectId}}) and workflow variables. Declared here so generated types are strongly typed per precondition."
+  )
+}).describe("A named precondition declared at the graph level. States reference these by name.");
+
+// ../spec/src/state.ts
+import { z as z4 } from "zod";
+var stateNodeSchema = z4.object({
+  preconditions: z4.array(z4.string().min(1)).describe("Ordered list of precondition names to satisfy before entering this state"),
+  route: z4.string().min(1).describe(
+    "URL pattern with {{placeholders}} for dynamic segments, e.g. '/projects/{{projectId}}/settings'"
+  )
+}).describe(
+  "A distinct application state \u2014 a unique combination of location, auth context, and data conditions"
+);
+
+// ../spec/src/graph.ts
+var MAX_STATES = 1e3;
+var MAX_EDGES = 5e3;
+var MAX_PRECONDITIONS = 500;
+var stateGraphSchema = z5.object({
+  edges: z5.array(edgeSchema).max(MAX_EDGES).describe("Directed edges between states, each executed by a workflow"),
+  preconditions: z5.record(z5.string().max(200), preconditionSchema).refine(
+    (obj) => Object.keys(obj).length <= MAX_PRECONDITIONS,
+    `Graph has more than ${String(MAX_PRECONDITIONS)} preconditions`
+  ).describe(
+    "Named preconditions keyed by name (e.g. 'auth:admin', 'data:three-projects'). States reference these by name."
+  ),
+  states: z5.record(z5.string().max(200), stateNodeSchema).refine(
+    (obj) => Object.keys(obj).length <= MAX_STATES,
+    `Graph has more than ${String(MAX_STATES)} states`
+  ).describe("States keyed by stable ID (kebab-case)")
+}).describe("Ripplo State Graph \u2014 models application states, edges, and executable preconditions");
+
+// ../spec/src/schema.ts
+import { z as z10 } from "zod";
+
+// ../spec/src/locators.ts
+import { z as z6 } from "zod";
+var testIdLocator = z6.object({
+  by: z6.literal("testId"),
+  value: z6.string().min(1)
+});
+var roleLocator = z6.object({
+  by: z6.literal("role"),
+  name: z6.string().optional(),
+  role: z6.string().min(1)
+});
+var locatorSchema = z6.discriminatedUnion("by", [testIdLocator, roleLocator]);
+
+// ../spec/src/operators.ts
+import { z as z7 } from "zod";
+var comparisonOperator = z7.enum([
+  "equals",
+  "notEquals",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "matches"
+]);
+var numericOperator = z7.enum([
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual"
+]);
+
+// ../spec/src/value-ref.ts
+import { z as z8 } from "zod";
+var staticValueSchema = z8.object({
+  type: z8.literal("static"),
+  value: z8.union([z8.string(), z8.number(), z8.boolean()])
+});
+var variableRefSchema = z8.object({
+  name: z8.string().min(1),
+  type: z8.literal("variable")
+});
+var valueRefSchema = z8.discriminatedUnion("type", [staticValueSchema, variableRefSchema]);
+var stringValueRefSchema = z8.discriminatedUnion("type", [
+  z8.object({ type: z8.literal("static"), value: z8.string() }),
+  variableRefSchema
+]);
+var numericValueRefSchema = z8.discriminatedUnion("type", [
+  z8.object({ type: z8.literal("static"), value: z8.number().int().nonnegative() }),
+  variableRefSchema
+]);
+
+// ../spec/src/variables.ts
+import { z as z9 } from "zod";
+var variableDefSchema = z9.discriminatedUnion("type", [
+  z9.object({
+    default: z9.string().optional(),
+    type: z9.literal("string")
+  }),
+  z9.object({
+    default: z9.number().optional(),
+    type: z9.literal("number")
+  }),
+  z9.object({
+    default: z9.boolean().optional(),
+    type: z9.literal("boolean")
+  }),
+  z9.object({
+    key: z9.string().min(1),
+    type: z9.literal("env")
+  })
+]);
+
+// ../spec/src/schema.ts
+var nodeBase = {
+  comment: z10.string().max(2e3).optional(),
+  id: z10.string().min(1).max(200),
+  label: z10.string().max(500).optional(),
+  next: z10.string().max(200).optional(),
+  timeout: z10.number().int().positive().optional()
+};
+var MAX_NODES_PER_WORKFLOW = 500;
+var gotoNode = z10.object({
+  ...nodeBase,
+  type: z10.literal("goto"),
+  url: stringValueRefSchema
+});
+var clickNode = z10.object({ ...nodeBase, locator: locatorSchema, type: z10.literal("click") });
+var fillNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("fill"),
+  value: stringValueRefSchema
+});
+var selectNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("select"),
+  value: stringValueRefSchema
+});
+var hoverNode = z10.object({ ...nodeBase, locator: locatorSchema, type: z10.literal("hover") });
+var pressNode = z10.object({
+  ...nodeBase,
+  key: z10.string().min(1),
+  locator: locatorSchema.optional(),
+  type: z10.literal("press")
+});
+var checkNode = z10.object({ ...nodeBase, locator: locatorSchema, type: z10.literal("check") });
+var uncheckNode = z10.object({ ...nodeBase, locator: locatorSchema, type: z10.literal("uncheck") });
+var setViewportNode = z10.object({
+  ...nodeBase,
+  height: z10.number().int().positive(),
+  type: z10.literal("setViewport"),
+  width: z10.number().int().positive()
+});
+var failNode = z10.object({ ...nodeBase, message: z10.string().min(1), type: z10.literal("fail") });
+var setVariableNode = z10.object({
+  ...nodeBase,
+  type: z10.literal("setVariable"),
+  value: valueRefSchema,
+  variable: z10.string().min(1)
+});
+var extractTextNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("extractText"),
+  variable: z10.string().min(1)
+});
+var uploadNode = z10.object({
+  ...nodeBase,
+  files: z10.array(z10.string()).min(1),
+  locator: locatorSchema,
+  type: z10.literal("upload")
+});
+var dblclickNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("dblclick")
+});
+var dragNode = z10.object({
+  ...nodeBase,
+  source: locatorSchema,
+  target: locatorSchema,
+  type: z10.literal("drag")
+});
+var scrollIntoViewNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("scrollIntoView")
+});
+var typeNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("type"),
+  value: stringValueRefSchema
+});
+var focusNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("focus")
+});
+var clearNode = z10.object({ ...nodeBase, locator: locatorSchema, type: z10.literal("clear") });
+var rightClickNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("rightClick")
+});
+var handleDialogNode = z10.object({
+  ...nodeBase,
+  action: z10.enum(["accept", "dismiss"]),
+  promptText: z10.string().optional(),
+  type: z10.literal("handleDialog")
+});
+var clipboardNode = z10.object({
+  ...nodeBase,
+  action: z10.enum(["read", "write"]),
+  type: z10.literal("clipboard"),
+  value: stringValueRefSchema.optional(),
+  variable: z10.string().min(1).optional()
+});
+var setPermissionNode = z10.object({
+  ...nodeBase,
+  permission: z10.string().min(1),
+  state: z10.enum(["granted", "prompt"]),
+  type: z10.literal("setPermission")
+});
+var assertVisibleNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("assertVisible")
+});
+var assertNotVisibleNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("assertNotVisible")
+});
+var assertTextNode = z10.object({
+  ...nodeBase,
+  expected: stringValueRefSchema,
+  locator: locatorSchema,
+  operator: comparisonOperator,
+  type: z10.literal("assertText")
+});
+var assertUrlNode = z10.object({
+  ...nodeBase,
+  expected: stringValueRefSchema,
+  operator: comparisonOperator,
+  type: z10.literal("assertUrl")
+});
+var assertCountNode = z10.object({
+  ...nodeBase,
+  expected: numericValueRefSchema,
+  locator: locatorSchema,
+  operator: numericOperator,
+  type: z10.literal("assertCount")
+});
+var assertValueNode = z10.object({
+  ...nodeBase,
+  expected: stringValueRefSchema,
+  locator: locatorSchema,
+  operator: comparisonOperator,
+  type: z10.literal("assertValue")
+});
+var assertAttributeNode = z10.object({
+  ...nodeBase,
+  attribute: z10.string().min(1),
+  expected: stringValueRefSchema,
+  locator: locatorSchema,
+  operator: comparisonOperator,
+  type: z10.literal("assertAttribute")
+});
+var assertEnabledNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("assertEnabled")
+});
+var assertDisabledNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("assertDisabled")
+});
+var assertTitleNode = z10.object({
+  ...nodeBase,
+  expected: stringValueRefSchema,
+  operator: comparisonOperator,
+  type: z10.literal("assertTitle")
+});
+var assertCheckedNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("assertChecked")
+});
+var assertNotCheckedNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("assertNotChecked")
+});
+var assertFocusedNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("assertFocused")
+});
+var assertNotFocusedNode = z10.object({
+  ...nodeBase,
+  locator: locatorSchema,
+  type: z10.literal("assertNotFocused")
+});
+var specNodeSchema = z10.discriminatedUnion("type", [
+  gotoNode,
+  clickNode,
+  fillNode,
+  selectNode,
+  hoverNode,
+  pressNode,
+  checkNode,
+  uncheckNode,
+  assertVisibleNode,
+  assertNotVisibleNode,
+  assertTextNode,
+  assertUrlNode,
+  assertCountNode,
+  assertValueNode,
+  assertAttributeNode,
+  assertEnabledNode,
+  assertDisabledNode,
+  setViewportNode,
+  failNode,
+  setVariableNode,
+  extractTextNode,
+  uploadNode,
+  dblclickNode,
+  dragNode,
+  scrollIntoViewNode,
+  typeNode,
+  focusNode,
+  clearNode,
+  rightClickNode,
+  handleDialogNode,
+  clipboardNode,
+  setPermissionNode,
+  assertTitleNode,
+  assertCheckedNode,
+  assertNotCheckedNode,
+  assertFocusedNode,
+  assertNotFocusedNode
+]);
+var workflowSpecSchema = z10.object({
+  entryNode: z10.string().min(1).max(200),
+  nodes: z10.record(z10.string().max(200), specNodeSchema).refine(
+    (nodes) => Object.keys(nodes).length <= MAX_NODES_PER_WORKFLOW,
+    `Workflow has more than ${String(MAX_NODES_PER_WORKFLOW)} nodes`
+  ),
+  variableNamespaces: z10.record(z10.string().max(200), z10.string().max(500)).optional(),
+  variables: z10.record(z10.string().max(200), variableDefSchema).optional()
+});
+
+// ../spec/src/codecs.ts
+var preconditionMapSchema = z11.record(z11.string().max(200), preconditionSchema);
+var looksLikeWorkflowSpec = {
+  assumedVersion: 1,
+  detect: (raw) => typeof raw === "object" && raw !== null && "entryNode" in raw && "nodes" in raw
+};
+var looksLikeStateGraph = {
+  assumedVersion: 1,
+  detect: (raw) => typeof raw === "object" && raw !== null && "edges" in raw && "states" in raw && "preconditions" in raw
+};
+var looksLikePreconditionMap = {
+  assumedVersion: 1,
+  detect: (raw) => typeof raw === "object" && raw !== null && !Array.isArray(raw) && !("__codec" in raw)
+};
+var workflowSpecCodec = defineCodec("workflow-spec").legacy(looksLikeWorkflowSpec).initial(workflowSpecSchema).build();
+var stateGraphCodec = defineCodec("state-graph").legacy(looksLikeStateGraph).initial(stateGraphSchema).build();
+var preconditionMapCodec = defineCodec("precondition-map").legacy(looksLikePreconditionMap).initial(preconditionMapSchema).build();
+
+// src/lockfile.ts
+import { z as z12 } from "zod";
+var LOCKFILE_RELATIVE_PATH = ".ripplo/ripplo.lock";
+var MAX_TESTS = 5e3;
+var compiledTestSchema = z12.object({
+  description: z12.string().max(2e3),
+  expectedOutcome: z12.string().max(2e3),
+  implemented: z12.boolean(),
+  name: z12.string().max(200),
+  slug: z12.string().max(200),
+  spec: workflowSpecSchema
+});
+var lockfileBodySchema = z12.object({
+  graph: stateGraphSchema,
+  tests: z12.array(compiledTestSchema).max(MAX_TESTS)
+});
+var lockfileCodec = defineCodec("ripplo-lockfile").initial(lockfileBodySchema).build();
+function compileResultToLockfile(result) {
+  return {
+    graph: result.graph,
+    tests: result.tests.map((test) => ({
+      description: test.description,
+      expectedOutcome: test.expectedOutcome,
+      implemented: test.implemented,
+      name: test.name,
+      slug: test.slug,
+      spec: test.spec
+    }))
+  };
+}
+function serializeLockfile(lockfile) {
+  const envelope = lockfileCodec.encode(lockfile);
+  return `${JSON.stringify(envelope, sortedReplacer(envelope), 2)}
+`;
+}
+async function readLockfile({ cwd }) {
+  const lockfilePath = path.join(cwd, LOCKFILE_RELATIVE_PATH);
+  const raw = await readFileOrNull(lockfilePath);
+  if (raw == null) {
+    return null;
+  }
+  return decodeJson(lockfileCodec, raw);
+}
+async function writeLockfile({ cwd, result }) {
+  const lockfile = compileResultToLockfile(result);
+  const lockfilePath = path.join(cwd, LOCKFILE_RELATIVE_PATH);
+  await fs.mkdir(path.dirname(lockfilePath), { recursive: true });
+  await fs.writeFile(lockfilePath, serializeLockfile(lockfile), "utf8");
+}
+function compareCompileToLockfile({
+  compiled,
+  existing
+}) {
+  if (existing == null) {
+    return "missing";
+  }
+  const fresh = serializeLockfile(compileResultToLockfile(compiled));
+  const current = serializeLockfile(existing);
+  return fresh === current ? "match" : "stale";
+}
+async function readFileOrNull(filePath) {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+function isNodeError(value) {
+  return value instanceof Error && "code" in value;
+}
+function sortedReplacer(root) {
+  return function replacer(_key, value) {
+    if (value === root || !isPlainObject(value)) {
+      return value;
+    }
+    return Object.fromEntries(Object.entries(value).toSorted(([a], [b]) => a.localeCompare(b)));
+  };
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export {
+  LOCKFILE_RELATIVE_PATH,
+  compareCompileToLockfile,
+  compileResultToLockfile,
+  lockfileCodec,
+  readLockfile,
+  serializeLockfile,
+  writeLockfile
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ripplo/testing",
   "description": "TypeScript DSL for defining and running Ripplo e2e workflow tests",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "type": "module",
   "files": [
     "dist"
@@ -37,6 +37,11 @@
       "import": "./dist/compiler.js",
       "default": "./dist/compiler.js"
     },
+    "./lockfile": {
+      "types": "./dist/lockfile.d.ts",
+      "import": "./dist/lockfile.js",
+      "default": "./dist/lockfile.js"
+    },
     "./express": {
       "types": "./dist/express.d.ts",
       "import": "./dist/express.js",
@@ -55,7 +60,7 @@
   },
   "dependencies": {
     "standardwebhooks": "^1.0.0",
-    "zod": "catalog:"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/express": "^5.0.2",