@syntax-syllogism/flow-delta 0.3.0 → 0.4.3

package/README.md

@@ -5,10 +5,12 @@ A semantic, visual diff for Salesforce Flows: parse two versions of a
 interactive HTML artifact (plus `diff.json`) that shows added / deleted /
 modified / unchanged nodes and edges with per-property deltas.
 
-Inspired by Google's [Flow Lens](https://github.com/google/flow-lens), with
-a focus on making it work with GitLab's pipelines. We also opted for our own HTML output over plantuml, graphviz, or mermaid.
+Inspired by Google's [Flow Lens](https://github.com/google/flow-lens), with a
+focus on CI review workflows for GitLab merge requests and GitHub pull requests.
+We also opted for our own HTML output over plantuml, graphviz, or mermaid.
 
-[Sample Gitlab Project with artifacts](https://gitlab.com/j.p.richter/flow-delta-example/-/merge_requests/1)
+- [Sample GitLab project with artifacts](https://gitlab.com/j.p.richter/flow-delta-example/-/merge_requests/)
+- [Sample GitHub project with artifacts](https://github.com/Syntax-Syllogism/flow-delta-example/pulls)
 
 ## Usage
 
@@ -19,6 +21,19 @@ for full file-mode and git-mode options.
 npx tsx src/cli.ts --old before.flow-meta.xml --new after.flow-meta.xml --out ./flow-delta-out --json
 ```
 
+CI reporters read the generated `flow-delta-out/*.diff.json` files and post a
+sticky review comment:
+
+```bash
+flow-delta-gitlab --in flow-delta-out
+flow-delta-github --in flow-delta-out
+```
+
+The GitHub reporter can also consume `--artifact-urls <manifest.json>` for
+user-owned live-render links, such as R2 presigned URLs or Cloudflare
+Worker-backed URLs. See [docs/ci.md](docs/ci.md) for GitLab/GitHub workflow
+recipes, private-repo artifact viewing, and smoke harnesses.
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -628,6 +628,38 @@ function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+// src/model/flow-header.ts
+import { Parser as Parser2 } from "xml2js";
+var FLOW_HEADER_KEYS = [
+  "status",
+  "processType",
+  "runInMode",
+  "apiVersion",
+  "triggerOrder",
+  "description",
+  "interviewLabel",
+  "isTemplate"
+];
+async function extractFlowHeader(xml) {
+  try {
+    const parsed = await new Parser2({ explicitArray: false }).parseStringPromise(xml);
+    const flow = parsed.Flow;
+    if (!flow) {
+      return {};
+    }
+    const header = {};
+    for (const key of FLOW_HEADER_KEYS) {
+      const value = flow[key];
+      if (value !== void 0 && (value === null || typeof value !== "object")) {
+        header[key] = String(value);
+      }
+    }
+    return header;
+  } catch {
+    return {};
+  }
+}
+
 // src/diff/deep-diff.ts
 function deepDiff(before, after, path = "") {
   if (Object.is(before, after)) {
@@ -685,21 +717,32 @@ function diffModel(oldModel, newModel) {
   const edgeIds = [.../* @__PURE__ */ new Set([...oldEdges.keys(), ...newEdges.keys()])].sort();
   const nodes = nodeIds.map((id) => classifyNode(oldNodes.get(id), newNodes.get(id)));
   const edges = edgeIds.map((id) => classifyEdge(oldEdges.get(id), newEdges.get(id)));
+  const flowChanges = diffFlowHeaders(oldModel, newModel);
   const summary = {
     addedNodes: nodes.filter((node) => node.status === "added").length,
     removedNodes: nodes.filter((node) => node.status === "deleted").length,
     modifiedNodes: nodes.filter((node) => node.status === "modified").length,
     unchangedNodes: nodes.filter((node) => node.status === "unchanged").length,
     addedEdges: edges.filter((edge) => edge.status === "added").length,
-    removedEdges: edges.filter((edge) => edge.status === "deleted").length
+    removedEdges: edges.filter((edge) => edge.status === "deleted").length,
+    changedFlowAttributes: flowChanges.length
   };
   return {
     flowName: selectFlowName(oldModel, newModel),
     summary,
+    ...flowChanges.length > 0 ? { flowChanges } : {},
     nodes,
     edges
   };
 }
+function diffFlowHeaders(oldModel, newModel) {
+  if (!oldModel.header || !newModel.header) {
+    return [];
+  }
+  const changes = deepDiff(oldModel.header, newModel.header);
+  const order = new Map(FLOW_HEADER_KEYS.map((key, index) => [key, index]));
+  return changes.sort((left, right) => (order.get(left.path) ?? 999) - (order.get(right.path) ?? 999));
+}
 function selectFlowName(oldModel, newModel) {
   if (newModel.nodes.length > 0 || newModel.edges.length > 0) {
     return newModel.flowName;
@@ -1532,6 +1575,7 @@ function renderHtml(layout) {
   const edgeStat = s.addedEdges + s.removedEdges > 0 ? `<span class="sep">\xB7</span><span class="stat edges">+${s.addedEdges}/\u2212${s.removedEdges} edges</span>` : "";
   const metaHtml = `${stat(s.addedNodes, "added", "added")}<span class="sep">\xB7</span>${stat(s.removedNodes, "deleted", "deleted")}<span class="sep">\xB7</span>${stat(s.modifiedNodes, "modified", "modified")}${edgeStat}`;
   const viewBox = fitViewBox(layout.width, layout.height);
+  const flowBannerHtml = renderFlowBanner(layout.diff.flowChanges);
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -1678,6 +1722,15 @@ function renderHtml(layout) {
     .group-head { display: flex; align-items: center; gap: 7px; margin-bottom: 8px; }
     .group-label { font-weight: 700; font-size: 12.5px; }
     .outcome-group .changes { margin-bottom: 8px; }
+    .flow-banner { border-bottom: 1px solid var(--border); background: #fffaf0; padding: 12px 20px; }
+    .flow-banner-callout { margin-bottom: 8px; font-weight: 750; }
+    .flow-banner-callout.deactivated { color: var(--deleted); }
+    .flow-banner-callout.activated { color: var(--added); }
+    .flow-banner-callout.neutral { color: var(--modified); }
+    .flow-banner-list { display: grid; gap: 7px; max-width: 960px; }
+    .flow-change-row { display: grid; grid-template-columns: minmax(120px, 190px) minmax(0, 1fr); align-items: start; gap: 10px; }
+    .flow-change-label { color: var(--muted); font-size: 12px; font-weight: 700; }
+    .flow-change-value { min-width: 0; max-height: 180px; overflow: auto; }
     .edge { fill: none; }
     .edge.unchanged { stroke-width: 1.4; opacity: 0.55; }
     .edge.normal.unchanged { stroke: var(--edge); marker-end: url(#arrow-normal); }
@@ -1734,6 +1787,7 @@ function renderHtml(layout) {
       </div>
     </div>
   </header>
+  ${flowBannerHtml}
   <main>
     <div class="canvas">
       <svg id="flow-svg" viewBox="${viewBox}" preserveAspectRatio="xMidYMid meet" role="img" aria-label="Flow diff">
@@ -2073,6 +2127,48 @@ function renderHtml(layout) {
 </body>
 </html>`;
 }
+function renderFlowBanner(changes) {
+  if (!changes || changes.length === 0) {
+    return "";
+  }
+  const statusChange = changes.find((change) => change.path === "status");
+  const callout = statusChange ? renderStatusCallout(statusChange.before, statusChange.after) : "";
+  return `<section class="flow-banner" aria-label="Flow-level changes">
+    ${callout}
+    <div class="flow-banner-list">
+      ${changes.map((change) => `<div class="flow-change-row">
+        <div class="flow-change-label">${escapeHtml2(humanizePath(change.path))}</div>
+        <div class="flow-change-value">${renderValueDelta(change.before, change.after)}</div>
+      </div>`).join("")}
+    </div>
+  </section>`;
+}
+function renderStatusCallout(before, after) {
+  const beforeText = String(before);
+  const afterText = String(after);
+  if (beforeText === "Active" && afterText !== "Active") {
+    return `<div class="flow-banner-callout deactivated">Deactivated (${escapeHtml2(beforeText)} -> ${escapeHtml2(afterText)})</div>`;
+  }
+  if (beforeText !== "Active" && afterText === "Active") {
+    return `<div class="flow-banner-callout activated">Activated (${escapeHtml2(beforeText)} -> ${escapeHtml2(afterText)})</div>`;
+  }
+  return `<div class="flow-banner-callout neutral">Status: ${escapeHtml2(beforeText)} -> ${escapeHtml2(afterText)}</div>`;
+}
+function renderValueDelta(before, after) {
+  if (before === void 0) {
+    return `<span class="val ins">${escapeHtml2(formatValue(after))}</span>`;
+  }
+  if (after === void 0) {
+    return `<span class="val del">${escapeHtml2(formatValue(before))}</span>`;
+  }
+  return `<span class="val del">${escapeHtml2(formatValue(before))}</span><span class="arrow">-></span><span class="val ins">${escapeHtml2(formatValue(after))}</span>`;
+}
+function formatValue(value) {
+  if (value === void 0) {
+    return "(missing)";
+  }
+  return String(value);
+}
 function fitViewBox(contentWidth, contentHeight) {
   const minWidth = 720;
   const minHeight = 540;
@@ -2236,8 +2332,10 @@ async function main(argv = process.argv.slice(2)) {
   }
 }
 async function runFileMode(oldPath, newPath, outDir, writeJson) {
-  const oldModel = buildModel(await parseXml(readFlowFromFile(oldPath)));
-  const newModel = buildModel(await parseXml(readFlowFromFile(newPath)));
+  const oldXml = readFlowFromFile(oldPath);
+  const newXml = readFlowFromFile(newPath);
+  const oldModel = await buildModelWithHeader(oldXml);
+  const newModel = await buildModelWithHeader(newXml);
   await writeArtifacts(oldModel, newModel, outDir, writeJson);
 }
 async function runGitMode(repo, from, to, pattern, outDir, writeJson, changedOnly) {
@@ -2247,8 +2345,8 @@ async function runGitMode(repo, from, to, pattern, outDir, writeJson, changedOnl
     try {
       const oldXml = readFlowFromGit(repo, from, filePath);
       const newXml = readFlowFromGit(repo, to, filePath);
-      const oldModel = oldXml ? buildModel(await parseXml(oldXml)) : buildEmptyModel();
-      const newModel = newXml ? buildModel(await parseXml(newXml)) : buildEmptyModel();
+      const oldModel = oldXml ? await buildModelWithHeader(oldXml) : buildEmptyModel();
+      const newModel = newXml ? await buildModelWithHeader(newXml) : buildEmptyModel();
       await writeArtifacts(oldModel, newModel, outDir, writeJson, filePath);
     } catch (error) {
       hadFailure = true;
@@ -2263,6 +2361,11 @@ async function parseXml(xml) {
   const parser = new FlowParser(xml);
   return parser.generateFlowDefinition();
 }
+async function buildModelWithHeader(xml) {
+  const model = buildModel(await parseXml(xml));
+  model.header = await extractFlowHeader(xml);
+  return model;
+}
 function buildEmptyModel() {
   return {
     flowName: "(unknown)",
@@ -2281,9 +2384,15 @@ async function writeArtifacts(oldModel, newModel, outDir, writeJson, sourcePath)
     writeFileSync(join(outDir, `${fileStem}.diff.json`), JSON.stringify(diff, null, 2), "utf8");
   }
   console.log(
-    `${diff.flowName}: nodes ${diff.summary.addedNodes} added, ${diff.summary.removedNodes} deleted, ${diff.summary.modifiedNodes} modified; edges ${diff.summary.addedEdges} added, ${diff.summary.removedEdges} deleted`
+    `${diff.flowName}: nodes ${diff.summary.addedNodes} added, ${diff.summary.removedNodes} deleted, ${diff.summary.modifiedNodes} modified; edges ${diff.summary.addedEdges} added, ${diff.summary.removedEdges} deleted${formatFlowAttributeSummary(diff.flowChanges)}`
   );
 }
+function formatFlowAttributeSummary(flowChanges) {
+  if (!flowChanges || flowChanges.length === 0) {
+    return "";
+  }
+  return `; flow attributes: ${flowChanges.length} changed (${flowChanges.map((change) => change.path).join(", ")})`;
+}
 function discoverGitFiles(repo, from, to, pattern, changedOnly) {
   const matcher = createPathMatcher(pattern);
   if (!changedOnly) {

package/dist/github-report.js

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+
+// src/ci/github-report.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { parseArgs } from "node:util";
+
+// src/util/is-main-module.ts
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+function isMainModule(metaUrl, argvPath = process.argv[1]) {
+  if (!argvPath) {
+    return false;
+  }
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(argvPath);
+  } catch {
+    return false;
+  }
+}
+
+// src/ci/report-core.ts
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+// src/render/snapshot-panel.ts
+var COLLECTION_KEY_NAMES = [
+  "assignmentItems",
+  "choiceReferences",
+  "choices",
+  "conditions",
+  "customErrorMessages",
+  "dataTypeMappings",
+  "fields",
+  "filters",
+  "inputAssignments",
+  "inputParameters",
+  "outputParameters",
+  "outputAssignments",
+  "processMetadataValues",
+  "rules",
+  "scheduledPaths",
+  "sortOptions",
+  "stageSteps",
+  "steps",
+  "storeOutputParameters",
+  "transformValues",
+  "valueMappings",
+  "waitEvents"
+];
+var COLLECTION_KEYS = new Set(COLLECTION_KEY_NAMES);
+function humanizePath(path) {
+  const names = {
+    assignmentItems: "Assignment item",
+    choiceReferences: "Choice reference",
+    choices: "Choice",
+    conditions: "Condition",
+    customErrorMessages: "Custom error message",
+    dataTypeMappings: "Data type mapping",
+    fields: "Field",
+    filters: "Filter",
+    inputAssignments: "Input assignment",
+    inputParameters: "Input parameter",
+    outputParameters: "Output parameter",
+    processMetadataValues: "Process metadata value",
+    rules: "Rule",
+    scheduledPaths: "Scheduled path",
+    storeOutputParameters: "Store output parameter",
+    transformValues: "Transform value",
+    valueMappings: "Value mapping",
+    waitEvents: "Wait event"
+  };
+  return path.split(".").map((segment) => {
+    const match = segment.match(/^([^[]+)(?:\[(\d+)\])?$/);
+    if (!match) return segment;
+    const name = names[match[1]] || match[1].replace(/([a-z])([A-Z])/g, "$1 $2").replace(/^./, (char) => char.toUpperCase());
+    return match[2] === void 0 ? name : name + " " + (Number(match[2]) + 1);
+  }).join(" > ");
+}
+
+// src/util/file-name.ts
+function safeFileName(value) {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "_");
+}
+
+// src/ci/report-core.ts
+var DEFAULT_MARKER = "<!-- FlowDelta:report -->";
+function buildComment(results, opts = {}) {
+  const marker = opts.marker ?? DEFAULT_MARKER;
+  const sorted = [...results].sort((left, right) => left.flowName.localeCompare(right.flowName));
+  const lines = [marker, "", `## \u{1F50D} FlowDelta \u2014 ${sorted.length} flow(s) changed`, ""];
+  if (sorted.length === 0) {
+    lines.push("_No Flow changes in this MR._");
+  } else {
+    lines.push("| Flow | +nodes | -nodes | ~nodes | +/-edges | Flow | Diff |");
+    lines.push("| --- | ---: | ---: | ---: | ---: | --- | --- |");
+    for (const result of sorted) {
+      const flowSummary = escapeTableCell(formatFlowChanges(result.flowChanges));
+      lines.push(
+        `| ${escapeTableCell(result.flowName)} | ${result.summary.addedNodes} | ${result.summary.removedNodes} | ${result.summary.modifiedNodes} | ${result.summary.addedEdges} / ${result.summary.removedEdges} | ${flowSummary} | [Open interactive diff](${result.artifactUrl}) |`
+      );
+    }
+  }
+  if (opts.commitSha) {
+    lines.push("", `Commit: \`${opts.commitSha.slice(0, 7)}\``);
+  }
+  return lines.join("\n");
+}
+function readResults(inputDir) {
+  return readdirSync(inputDir).filter((file) => file.endsWith(".diff.json")).map((file) => {
+    const diff = JSON.parse(readFileSync(join(inputDir, file), "utf8"));
+    if (isZeroSummary(diff.summary)) {
+      return null;
+    }
+    return {
+      flowName: diff.flowName,
+      summary: diff.summary,
+      flowChanges: diff.flowChanges,
+      stem: safeFileName(diff.flowName)
+    };
+  }).filter((value) => value !== null);
+}
+function loadArtifactUrls(path) {
+  if (!path || !existsSync(path)) {
+    return {};
+  }
+  const raw = readFileSync(path, "utf8").trim();
+  if (!raw) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    return Object.fromEntries(
+      Object.entries(parsed).filter(
+        (entry) => typeof entry[1] === "string" && (entry[1].startsWith("https://") || entry[1].startsWith("http://"))
+      )
+    );
+  } catch {
+    return {};
+  }
+}
+function resolveArtifactUrl(stem, urls, fallback) {
+  return urls[`${stem}.html`] ?? fallback;
+}
+function isZeroSummary(summary) {
+  return summary.addedNodes === 0 && summary.removedNodes === 0 && summary.modifiedNodes === 0 && summary.addedEdges === 0 && summary.removedEdges === 0 && summary.changedFlowAttributes === 0;
+}
+function findStickyNote(notes, marker, authorId) {
+  return notes.find((note) => note.body.includes(marker) && (authorId === void 0 || note.author?.id === authorId));
+}
+function escapeTableCell(value) {
+  return value.replaceAll("|", "\\|").replaceAll("`", "\\`").replace(/\r?\n/g, "<br>");
+}
+function formatFlowChanges(flowChanges) {
+  if (!flowChanges || flowChanges.length === 0) {
+    return "";
+  }
+  const status = flowChanges.find((change) => change.path === "status");
+  if (status) {
+    return formatStatusChange(status.before, status.after);
+  }
+  return flowChanges.map((change) => humanizePath(change.path)).join(", ");
+}
+function formatStatusChange(before, after) {
+  if (before === "Active" && after !== "Active") {
+    return `Deactivated (${String(before)} -> ${String(after)})`;
+  }
+  if (before !== "Active" && after === "Active") {
+    return `Activated (${String(before)} -> ${String(after)})`;
+  }
+  return `Status: ${String(before)} -> ${String(after)}`;
+}
+
+// src/ci/github-report.ts
+var REPORTER_USAGE = `Usage:
+  flow-delta-github --in <flow-delta-out> [--api-url <url>] [--repo <owner/repo>] [--pr <number>]
+                    [--server-url <url>] [--run-id <id>] [--token <token>] [--commit-sha <sha>]
+                    [--artifact-urls <manifest.json>]
+`;
+function artifactUrl(env) {
+  const base = env.serverUrl.replace(/\/+$/, "");
+  return `${base}/${env.owner}/${env.repo}/actions/runs/${env.runId}`;
+}
+async function upsertComment(env, body, fetchImpl = fetch) {
+  const headers = {
+    Authorization: `Bearer ${env.token}`,
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+    "Content-Type": "application/json"
+  };
+  const marker = env.marker ?? DEFAULT_MARKER;
+  const comments = await listComments(fetchImpl, env, headers);
+  const sticky = findStickyNote(
+    comments.map((comment) => ({ id: comment.id, body: comment.body })),
+    marker
+  );
+  if (sticky) {
+    await requestJson(fetchImpl, `${env.apiUrl}/repos/${env.owner}/${env.repo}/issues/comments/${sticky.id}`, {
+      method: "PATCH",
+      headers,
+      body: JSON.stringify({ body })
+    });
+  } else {
+    await requestJson(fetchImpl, `${env.apiUrl}/repos/${env.owner}/${env.repo}/issues/${env.prNumber}/comments`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ body })
+    });
+  }
+}
+async function main(argv = process.argv.slice(2)) {
+  try {
+    const parsed = parseArgs({
+      args: argv,
+      options: {
+        in: { type: "string" },
+        "api-url": { type: "string" },
+        repo: { type: "string" },
+        pr: { type: "string" },
+        "server-url": { type: "string" },
+        "run-id": { type: "string" },
+        token: { type: "string" },
+        "commit-sha": { type: "string" },
+        "artifact-urls": { type: "string" },
+        marker: { type: "string" },
+        help: { type: "boolean", short: "h" }
+      },
+      allowPositionals: false
+    });
+    if (parsed.values.help) {
+      console.log(REPORTER_USAGE.trimEnd());
+      return;
+    }
+    const inputDir = parsed.values.in ?? process.env.FLOW_LENS_OUT_DIR ?? "./flow-delta-out";
+    const records = readResults(inputDir);
+    if (records.length === 0) {
+      return;
+    }
+    const prNumber = resolvePrNumber(parsed.values);
+    if (prNumber === void 0) {
+      console.error("No pull request number resolved (not a pull_request event); skipping GitHub comment.");
+      return;
+    }
+    const env = resolveEnv(parsed.values, prNumber);
+    const urls = loadArtifactUrls(stringValueOptional(parsed.values["artifact-urls"]));
+    const fallbackUrl = artifactUrl(env);
+    const results = records.map((record) => ({
+      flowName: record.flowName,
+      summary: record.summary,
+      flowChanges: record.flowChanges,
+      artifactUrl: resolveArtifactUrl(record.stem, urls, fallbackUrl)
+    }));
+    const body = buildComment(results, {
+      marker: env.marker,
+      commitSha: env.commitSha
+    });
+    await upsertComment(env, body);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+function resolvePrNumber(values) {
+  const fromFlag = stringValueOptional(values.pr);
+  if (fromFlag) {
+    return fromFlag;
+  }
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+  if (!eventPath) {
+    return void 0;
+  }
+  try {
+    const event = JSON.parse(readFileSync2(eventPath, "utf8"));
+    const number = event.pull_request?.number;
+    return typeof number === "number" ? String(number) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolveEnv(values, prNumber) {
+  const apiUrl = stringValueOptional(values["api-url"] ?? process.env.GITHUB_API_URL) ?? "https://api.github.com";
+  const repoFull = stringValue(values.repo ?? process.env.GITHUB_REPOSITORY, "GITHUB_REPOSITORY");
+  const [owner, repo] = repoFull.split("/");
+  if (!owner || !repo) {
+    throw new Error(`Invalid repo (expected owner/repo): ${repoFull}`);
+  }
+  const serverUrl = stringValueOptional(values["server-url"] ?? process.env.GITHUB_SERVER_URL) ?? "https://github.com";
+  const runId = stringValue(values["run-id"] ?? process.env.GITHUB_RUN_ID, "GITHUB_RUN_ID");
+  const token = stringValue(values.token ?? process.env.GITHUB_TOKEN, "GITHUB_TOKEN");
+  const commitSha = stringValueOptional(values["commit-sha"] ?? process.env.GITHUB_SHA);
+  const marker = stringValueOptional(values.marker) ?? DEFAULT_MARKER;
+  return { apiUrl, owner, repo, prNumber, serverUrl, runId, token, commitSha, marker };
+}
+function stringValue(value, name) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Missing required value: ${name}`);
+  }
+  return value;
+}
+function stringValueOptional(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+async function listComments(fetchImpl, env, headers) {
+  const comments = [];
+  let page = 1;
+  while (true) {
+    const response = await fetchImpl(
+      `${env.apiUrl}/repos/${env.owner}/${env.repo}/issues/${env.prNumber}/comments?per_page=100&page=${page}`,
+      { headers }
+    );
+    const pageComments = await parseResponse(response, "list PR comments");
+    comments.push(...pageComments);
+    if (pageComments.length < 100) {
+      return comments;
+    }
+    page += 1;
+  }
+}
+async function requestJson(fetchImpl, url, init, label = url) {
+  const response = await fetchImpl(url, init);
+  return parseResponse(response, label);
+}
+async function parseResponse(response, label) {
+  const body = await response.text();
+  if (!response.ok) {
+    throw new Error(`${label} failed: ${response.status} ${body}`);
+  }
+  return body.length > 0 ? JSON.parse(body) : void 0;
+}
+if (isMainModule(import.meta.url)) {
+  void main();
+}
+export {
+  artifactUrl,
+  buildComment,
+  findStickyNote,
+  isZeroSummary,
+  main,
+  upsertComment
+};

package/dist/gitlab-report.js

@@ -1,15 +1,8 @@
 #!/usr/bin/env node
 
 // src/ci/gitlab-report.ts
-import { readFileSync, readdirSync } from "node:fs";
-import { join } from "node:path";
 import { parseArgs } from "node:util";
 
-// src/util/file-name.ts
-function safeFileName(value) {
-  return value.replace(/[^a-zA-Z0-9._-]+/g, "_");
-}
-
 // src/util/is-main-module.ts
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -24,12 +17,72 @@ function isMainModule(metaUrl, argvPath = process.argv[1]) {
   }
 }
 
-// src/ci/gitlab-report.ts
+// src/ci/report-core.ts
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+// src/render/snapshot-panel.ts
+var COLLECTION_KEY_NAMES = [
+  "assignmentItems",
+  "choiceReferences",
+  "choices",
+  "conditions",
+  "customErrorMessages",
+  "dataTypeMappings",
+  "fields",
+  "filters",
+  "inputAssignments",
+  "inputParameters",
+  "outputParameters",
+  "outputAssignments",
+  "processMetadataValues",
+  "rules",
+  "scheduledPaths",
+  "sortOptions",
+  "stageSteps",
+  "steps",
+  "storeOutputParameters",
+  "transformValues",
+  "valueMappings",
+  "waitEvents"
+];
+var COLLECTION_KEYS = new Set(COLLECTION_KEY_NAMES);
+function humanizePath(path) {
+  const names = {
+    assignmentItems: "Assignment item",
+    choiceReferences: "Choice reference",
+    choices: "Choice",
+    conditions: "Condition",
+    customErrorMessages: "Custom error message",
+    dataTypeMappings: "Data type mapping",
+    fields: "Field",
+    filters: "Filter",
+    inputAssignments: "Input assignment",
+    inputParameters: "Input parameter",
+    outputParameters: "Output parameter",
+    processMetadataValues: "Process metadata value",
+    rules: "Rule",
+    scheduledPaths: "Scheduled path",
+    storeOutputParameters: "Store output parameter",
+    transformValues: "Transform value",
+    valueMappings: "Value mapping",
+    waitEvents: "Wait event"
+  };
+  return path.split(".").map((segment) => {
+    const match = segment.match(/^([^[]+)(?:\[(\d+)\])?$/);
+    if (!match) return segment;
+    const name = names[match[1]] || match[1].replace(/([a-z])([A-Z])/g, "$1 $2").replace(/^./, (char) => char.toUpperCase());
+    return match[2] === void 0 ? name : name + " " + (Number(match[2]) + 1);
+  }).join(" > ");
+}
+
+// src/util/file-name.ts
+function safeFileName(value) {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "_");
+}
+
+// src/ci/report-core.ts
 var DEFAULT_MARKER = "<!-- FlowDelta:report -->";
-var REPORTER_USAGE = `Usage:
-  flow-delta-gitlab --in <flow-delta-out> [--api-url <url>] [--project-id <id>] [--mr-iid <iid>]
-                    [--project-url <url>] [--job-id <id>] [--token <token>] [--commit-sha <sha>]
-`;
 function buildComment(results, opts = {}) {
   const marker = opts.marker ?? DEFAULT_MARKER;
   const sorted = [...results].sort((left, right) => left.flowName.localeCompare(right.flowName));
@@ -37,11 +90,12 @@ function buildComment(results, opts = {}) {
   if (sorted.length === 0) {
     lines.push("_No Flow changes in this MR._");
   } else {
-    lines.push("| Flow | +nodes | -nodes | ~nodes | +/-edges | Diff |");
-    lines.push("| --- | ---: | ---: | ---: | ---: | --- |");
+    lines.push("| Flow | +nodes | -nodes | ~nodes | +/-edges | Flow | Diff |");
+    lines.push("| --- | ---: | ---: | ---: | ---: | --- | --- |");
     for (const result of sorted) {
+      const flowSummary = escapeTableCell(formatFlowChanges(result.flowChanges));
       lines.push(
-        `| ${escapeTableCell(result.flowName)} | ${result.summary.addedNodes} | ${result.summary.removedNodes} | ${result.summary.modifiedNodes} | ${result.summary.addedEdges} / ${result.summary.removedEdges} | [Open interactive diff \u25B8](${result.artifactUrl}) |`
+        `| ${escapeTableCell(result.flowName)} | ${result.summary.addedNodes} | ${result.summary.removedNodes} | ${result.summary.modifiedNodes} | ${result.summary.addedEdges} / ${result.summary.removedEdges} | ${flowSummary} | [Open interactive diff](${result.artifactUrl}) |`
       );
     }
   }
@@ -50,15 +104,63 @@ function buildComment(results, opts = {}) {
   }
   return lines.join("\n");
 }
+function readResults(inputDir) {
+  return readdirSync(inputDir).filter((file) => file.endsWith(".diff.json")).map((file) => {
+    const diff = JSON.parse(readFileSync(join(inputDir, file), "utf8"));
+    if (isZeroSummary(diff.summary)) {
+      return null;
+    }
+    return {
+      flowName: diff.flowName,
+      summary: diff.summary,
+      flowChanges: diff.flowChanges,
+      stem: safeFileName(diff.flowName)
+    };
+  }).filter((value) => value !== null);
+}
+function isZeroSummary(summary) {
+  return summary.addedNodes === 0 && summary.removedNodes === 0 && summary.modifiedNodes === 0 && summary.addedEdges === 0 && summary.removedEdges === 0 && summary.changedFlowAttributes === 0;
+}
+function findStickyNote(notes, marker, authorId) {
+  return notes.find((note) => note.body.includes(marker) && (authorId === void 0 || note.author?.id === authorId));
+}
+function normalizePath(value) {
+  return value.replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function escapeTableCell(value) {
+  return value.replaceAll("|", "\\|").replaceAll("`", "\\`").replace(/\r?\n/g, "<br>");
+}
+function formatFlowChanges(flowChanges) {
+  if (!flowChanges || flowChanges.length === 0) {
+    return "";
+  }
+  const status = flowChanges.find((change) => change.path === "status");
+  if (status) {
+    return formatStatusChange(status.before, status.after);
+  }
+  return flowChanges.map((change) => humanizePath(change.path)).join(", ");
+}
+function formatStatusChange(before, after) {
+  if (before === "Active" && after !== "Active") {
+    return `Deactivated (${String(before)} -> ${String(after)})`;
+  }
+  if (before !== "Active" && after === "Active") {
+    return `Activated (${String(before)} -> ${String(after)})`;
+  }
+  return `Status: ${String(before)} -> ${String(after)}`;
+}
+
+// src/ci/gitlab-report.ts
+var REPORTER_USAGE = `Usage:
+  flow-delta-gitlab --in <flow-delta-out> [--api-url <url>] [--project-id <id>] [--mr-iid <iid>]
+                    [--project-url <url>] [--job-id <id>] [--token <token>] [--commit-sha <sha>]
+`;
 function artifactUrl(env, relPath, stem) {
   const base = env.projectUrl.replace(/\/+$/, "");
   const relativePath = normalizePath(relPath);
   const encodedPath = [relativePath, `${stem}.html`].filter(Boolean).flatMap((segment) => segment.split("/").filter(Boolean)).map(encodeURIComponent).join("/");
   return `${base}/-/jobs/${env.jobId}/artifacts/file/${encodedPath}`;
 }
-function findStickyNote(notes, marker, authorId) {
-  return notes.find((note) => note.body.includes(marker) && (authorId === void 0 || note.author?.id === authorId));
-}
 async function upsertComment(env, body, fetchImpl = fetch) {
   const headers = {
     "PRIVATE-TOKEN": env.token,
@@ -109,6 +211,7 @@ async function main(argv = process.argv.slice(2)) {
     const results = records.map((record) => ({
       flowName: record.flowName,
       summary: record.summary,
+      flowChanges: record.flowChanges,
       artifactUrl: artifactUrl(env, inputDir, record.stem)
     }));
     const body = buildComment(results, {
@@ -121,22 +224,6 @@ async function main(argv = process.argv.slice(2)) {
     process.exitCode = 1;
   }
 }
-function readResults(inputDir) {
-  return readdirSync(inputDir).filter((file) => file.endsWith(".diff.json")).map((file) => {
-    const diff = JSON.parse(readFileSync(join(inputDir, file), "utf8"));
-    if (isZeroSummary(diff.summary)) {
-      return null;
-    }
-    return {
-      flowName: diff.flowName,
-      summary: diff.summary,
-      stem: safeFileName(diff.flowName)
-    };
-  }).filter((value) => value !== null);
-}
-function isZeroSummary(summary) {
-  return summary.addedNodes === 0 && summary.removedNodes === 0 && summary.modifiedNodes === 0 && summary.addedEdges === 0 && summary.removedEdges === 0;
-}
 function resolveEnv(values) {
   const apiUrl = stringValue(values["api-url"] ?? process.env.CI_API_V4_URL, "CI_API_V4_URL");
   const projectId = stringValue(values["project-id"] ?? process.env.CI_PROJECT_ID, "CI_PROJECT_ID");
@@ -184,12 +271,6 @@ async function parseResponse(response, label) {
   }
   return body.length > 0 ? JSON.parse(body) : void 0;
 }
-function normalizePath(value) {
-  return value.replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/^\/+/, "").replace(/\/+$/, "");
-}
-function escapeTableCell(value) {
-  return value.replaceAll("|", "\\|").replaceAll("`", "\\`").replace(/\r?\n/g, "<br>");
-}
 if (isMainModule(import.meta.url)) {
   void main();
 }
@@ -197,6 +278,7 @@ export {
   artifactUrl,
   buildComment,
   findStickyNote,
+  isZeroSummary,
   main,
   upsertComment
 };

package/examples/cloudflare-worker/src/index.ts

@@ -0,0 +1,63 @@
+export interface Env {
+  BUCKET: R2Bucket;
+  ARTIFACT_HMAC_KEY?: string;
+}
+
+const worker = {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    const url = new URL(req.url);
+    const key = decodeURIComponent(url.pathname.replace(/^\/+/, ""));
+    if (!key || key.includes("..")) {
+      return new Response("Not found", { status: 404 });
+    }
+
+    if (env.ARTIFACT_HMAC_KEY) {
+      const exp = Number(url.searchParams.get("exp"));
+      const sig = url.searchParams.get("sig") ?? "";
+      if (!exp || Math.floor(Date.now() / 1000) > exp) {
+        return new Response("Link expired", { status: 403 });
+      }
+      const expected = await hmacHex(env.ARTIFACT_HMAC_KEY, `${key}:${exp}`);
+      if (!timingSafeEqual(expected, sig)) {
+        return new Response("Bad signature", { status: 403 });
+      }
+    }
+
+    const obj = await env.BUCKET.get(key);
+    if (!obj) {
+      return new Response("Not found", { status: 404 });
+    }
+
+    const headers = new Headers();
+    obj.writeHttpMetadata(headers);
+    headers.set("content-type", "text/html; charset=utf-8");
+    headers.set("cache-control", "private, max-age=300");
+    return new Response(obj.body, { headers });
+  },
+};
+
+export default worker;
+
+async function hmacHex(secret: string, message: string): Promise<string> {
+  const enc = new TextEncoder();
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", cryptoKey, enc.encode(message));
+  return [...new Uint8Array(sig)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let out = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    out |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return out === 0;
+}

package/examples/cloudflare-worker/wrangler.toml

@@ -0,0 +1,8 @@
+name = "flowdelta-artifacts"
+main = "src/index.ts"
+compatibility_date = "2025-01-01"
+
+[[r2_buckets]]
+binding = "BUCKET"
+bucket_name = "flow-delta-sample"
+

package/examples/github-actions.yml

@@ -0,0 +1,56 @@
+name: FlowDelta
+
+on: pull_request
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  flowdelta:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: npm install --no-save @syntax-syllogism/flow-delta@^0.3
+      - run: |
+          ./node_modules/.bin/flow-delta \
+            --repo . \
+            --from "${{ github.event.pull_request.base.sha }}" \
+            --to   "${{ github.sha }}" \
+            --path 'force-app/**/*.flow-meta.xml' \
+            --changed-only \
+            --out flow-delta-out --json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: flow-delta-out
+          path: flow-delta-out
+      # Optional live-render path for private repos using your own R2 bucket and Worker.
+      # See docs/ci.md for the required secrets, Worker template, and presigned alternative.
+      - name: Publish to R2 + sign
+        if: ${{ vars.ARTIFACT_BASE_URL != '' }}
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+          R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
+          R2_BUCKET: ${{ secrets.R2_BUCKET }}
+          ARTIFACT_BASE_URL: ${{ vars.ARTIFACT_BASE_URL }}
+          ARTIFACT_HMAC_KEY: ${{ secrets.ARTIFACT_HMAC_KEY }}
+        run: node ./node_modules/@syntax-syllogism/flow-delta/scripts/r2-publish.mjs flow-delta-out "$GITHUB_REPOSITORY/${{ github.event.number }}/$GITHUB_SHA" > flow-delta-out/urls.json
+        continue-on-error: true
+      - name: Report with live-render links
+        if: ${{ vars.ARTIFACT_BASE_URL != '' }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: ./node_modules/.bin/flow-delta-github --in flow-delta-out --artifact-urls flow-delta-out/urls.json
+        continue-on-error: true
+      - name: Report with baseline artifact link
+        if: ${{ vars.ARTIFACT_BASE_URL == '' }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: ./node_modules/.bin/flow-delta-github --in flow-delta-out
+        continue-on-error: true

package/examples/gitlab-ci.yml

@@ -0,0 +1,23 @@
+FlowDelta:
+  image: node:24-alpine
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  variables:
+    GIT_DEPTH: 0
+  before_script:
+    - apk add --no-cache git
+  script:
+    - |
+      # see /docs/ci.md for details on how this works
+      npx --yes -p @syntax-syllogism/flow-delta@latest flow-delta \
+        --repo . \
+        --from "$CI_MERGE_REQUEST_DIFF_BASE_SHA" \
+        --to   "${CI_MERGE_REQUEST_SOURCE_BRANCH_SHA:-$CI_COMMIT_SHA}" \
+        --path 'force-app/**/*.flow-meta.xml' \
+        --changed-only \
+        --out flow-delta-out --json
+    - npx --yes -p @syntax-syllogism/flow-delta@latest flow-delta-gitlab --in flow-delta-out
+  artifacts:
+    paths: [flow-delta-out]
+    expire_in: 30 days
+  allow_failure: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntax-syllogism/flow-delta",
-  "version": "0.3.0",
+  "version": "0.4.3",
   "type": "module",
   "description": "Semantic visual diff for Salesforce Flows",
   "license": "MIT",
@@ -27,14 +27,15 @@
   "scripts": {
     "build": "node scripts/build.mjs",
     "smoke:gitlab": "node --import tsx scripts/smoke-gitlab.ts",
-    "test": "node --import tsx --test test/parser.test.ts test/semantic-diff.test.ts test/gitlab-report.test.ts test/smoke-gitlab.test.ts",
+    "smoke:github": "node --import tsx scripts/smoke-github.ts",
+    "test": "node --import tsx --test test/parser.test.ts test/semantic-diff.test.ts test/report-core.test.ts test/gitlab-report.test.ts test/github-report.test.ts test/smoke-gitlab.test.ts test/r2-publish.test.ts test/cloudflare-worker.test.ts",
     "test:parser": "node --import tsx --test test/parser.test.ts",
     "prepublishOnly": "npm run build && npm test",
     "render:fixtures": "bash bin/render-fixtures.sh"
   },
   "devDependencies": {
     "esbuild": "^0.28.0",
-    "@types/node": "^25.9.2",
+    "@types/node": "^26.1.0",
     "@types/xml2js": "^0.4.14",
     "tsx": "^4.19.0"
   },
@@ -44,10 +45,13 @@
   },
   "bin": {
     "flow-delta": "dist/cli.js",
-    "flow-delta-gitlab": "dist/gitlab-report.js"
+    "flow-delta-gitlab": "dist/gitlab-report.js",
+    "flow-delta-github": "dist/github-report.js"
   },
   "files": [
     "dist",
+    "examples",
+    "scripts/r2-publish.mjs",
     "NOTICE",
     "LICENSE",
     "LICENSE-APACHE",

package/scripts/r2-publish.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { createHmac } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const [outDir = "flow-delta-out", keyPrefix = defaultKeyPrefix()] = process.argv.slice(2);
+
+  try {
+    const urls = publishDirectory(outDir, keyPrefix);
+    process.stdout.write(`${JSON.stringify(urls, null, 2)}\n`);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}
+
+export function publishDirectory(outDir, keyPrefix, env = process.env) {
+  const bucket = required(env.R2_BUCKET, "R2_BUCKET");
+  const endpoint = r2Endpoint(env);
+  const htmlFiles = readdirSync(outDir).filter((file) => file.endsWith(".html")).sort();
+  const urls = {};
+
+  for (const file of htmlFiles) {
+    const key = joinKey(keyPrefix, file);
+    uploadHtml(join(outDir, file), bucket, key, endpoint);
+    urls[file] = resolveUrl(bucket, key, endpoint, env);
+  }
+
+  return urls;
+}
+
+export function signedWorkerUrl(baseUrl, key, secret, exp) {
+  const base = baseUrl.replace(/\/+$/, "");
+  const encodedKey = key.split("/").map(encodeURIComponent).join("/");
+  const sig = hmacHex(secret, `${key}:${exp}`);
+  return `${base}/${encodedKey}?exp=${exp}&sig=${sig}`;
+}
+
+export function hmacHex(secret, message) {
+  return createHmac("sha256", secret).update(message).digest("hex");
+}
+
+function resolveUrl(bucket, key, endpoint, env) {
+  if (env.ARTIFACT_BASE_URL) {
+    const secret = required(env.ARTIFACT_HMAC_KEY, "ARTIFACT_HMAC_KEY");
+    const exp = String(Math.floor(Date.now() / 1000) + expirySeconds(env));
+    return signedWorkerUrl(env.ARTIFACT_BASE_URL, key, secret, exp);
+  }
+
+  return presignUrl(bucket, key, endpoint, expirySeconds(env));
+}
+
+function uploadHtml(path, bucket, key, endpoint) {
+  runAws([
+    "s3",
+    "cp",
+    path,
+    `s3://${bucket}/${key}`,
+    "--endpoint-url",
+    endpoint,
+    "--content-type",
+    "text/html",
+  ]);
+}
+
+function presignUrl(bucket, key, endpoint, expiresIn) {
+  return runAws([
+    "s3",
+    "presign",
+    `s3://${bucket}/${key}`,
+    "--endpoint-url",
+    endpoint,
+    "--expires-in",
+    String(expiresIn),
+  ]);
+}
+
+function runAws(args) {
+  const result = spawnSync("aws", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || `aws ${args.join(" ")} failed`);
+  }
+  return result.stdout.trim();
+}
+
+function r2Endpoint(env) {
+  const accountId = required(env.R2_ACCOUNT_ID, "R2_ACCOUNT_ID");
+  return `https://${accountId}.r2.cloudflarestorage.com`;
+}
+
+function expirySeconds(env) {
+  const raw = env.ARTIFACT_EXPIRES_IN_SECONDS ?? "86400";
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error("ARTIFACT_EXPIRES_IN_SECONDS must be a positive integer");
+  }
+  return Math.min(value, 604800);
+}
+
+function joinKey(prefix, file) {
+  return [prefix.replace(/^\/+|\/+$/g, ""), basename(file)].filter(Boolean).join("/");
+}
+
+function defaultKeyPrefix() {
+  const repo = required(process.env.GITHUB_REPOSITORY, "GITHUB_REPOSITORY");
+  const sha = required(process.env.GITHUB_SHA, "GITHUB_SHA");
+  const pr = process.env.GITHUB_PR_NUMBER ?? process.env.PR_NUMBER ?? readGitHubEventPrNumber() ?? "unknown-pr";
+  return `${repo}/${pr}/${sha}`;
+}
+
+function readGitHubEventPrNumber() {
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+  if (!eventPath) {
+    return undefined;
+  }
+  try {
+    const event = JSON.parse(readFileSync(eventPath, "utf8"));
+    return typeof event?.number === "number" ? String(event.number) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function required(value, name) {
+  if (!value) {
+    throw new Error(`Missing required value: ${name}`);
+  }
+  return value;
+}