x-openapi-flow 1.2.3 → 1.3.1

package/adapters/docs/doc-adapter.js

@@ -0,0 +1,119 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { loadApi } = require("../../lib/validator");
+const { buildIntermediateModel } = require("../../lib/sdk-generator");
+const { toTitleCase, buildLifecycleSequences } = require("../shared/helpers");
+
+function buildResourceMermaid(resource) {
+  const flowOperations = resource.operations.filter((operation) => operation.hasFlow);
+  const lines = ["stateDiagram-v2", "  direction LR"];
+
+  const states = new Set(flowOperations.map((operation) => operation.currentState).filter(Boolean));
+  for (const state of [...states].sort()) {
+    lines.push(`  state ${state}`);
+  }
+
+  const edgeSet = new Set();
+  for (const operation of flowOperations) {
+    for (const next of operation.nextOperations || []) {
+      const targetOperation = flowOperations.find((candidate) => candidate.operationId === next.nextOperationId);
+      const targetState = next.targetState || (targetOperation && targetOperation.currentState);
+      if (!targetState || !operation.currentState) continue;
+
+      const label = next.nextOperationId
+        ? `${operation.methodName} -> ${next.nextOperationId}`
+        : operation.methodName;
+      const edgeKey = `${operation.currentState}::${targetState}::${label}`;
+      if (edgeSet.has(edgeKey)) continue;
+      edgeSet.add(edgeKey);
+      lines.push(`  ${operation.currentState} --> ${targetState}: ${label}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function buildDocFlowsMarkdown(model, sourcePath) {
+  const lines = [];
+  lines.push("# API Flows");
+  lines.push("");
+  lines.push(`Source: ${sourcePath}`);
+  lines.push("");
+  lines.push("This page is generated from x-openapi-flow metadata.");
+  lines.push("");
+
+  for (const resource of model.resources) {
+    const displayName = toTitleCase(resource.resourcePlural || resource.resource);
+    lines.push(`## ${displayName} Lifecycle`);
+    lines.push("");
+    lines.push("### Flow / Lifecycle");
+    lines.push("");
+    lines.push("```mermaid");
+    lines.push(buildResourceMermaid(resource));
+    lines.push("```");
+    lines.push("");
+
+    const sequences = buildLifecycleSequences(resource);
+    if (sequences.length > 0) {
+      lines.push("### Journeys");
+      lines.push("");
+      sequences.forEach((sequence, index) => {
+        const label = sequence.map((operation) => operation.methodName).join(" -> ");
+        lines.push(`- Journey ${index + 1}: ${label}`);
+      });
+      lines.push("");
+    }
+
+    lines.push("### Operations");
+    lines.push("");
+    for (const operation of resource.operations.filter((item) => item.hasFlow)) {
+      lines.push(`#### ${operation.operationId}`);
+      lines.push(`- Endpoint: ${operation.httpMethod.toUpperCase()} ${operation.path}`);
+      lines.push(`- Current state: ${operation.currentState || "-"}`);
+      const prereqs = operation.prerequisites && operation.prerequisites.length > 0
+        ? operation.prerequisites.join(", ")
+        : "-";
+      lines.push(`- Prerequisites: ${prereqs}`);
+
+      const nextOps = (operation.nextOperations || [])
+        .map((next) => next.nextOperationId)
+        .filter(Boolean);
+      lines.push(`- Next operations: ${nextOps.length > 0 ? nextOps.join(", ") : "-"}`);
+      lines.push("");
+    }
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function exportDocFlows(options) {
+  const apiPath = path.resolve(options.apiPath);
+  const outputPath = path.resolve(options.outputPath || path.join(process.cwd(), "api-flows.md"));
+  const format = options.format || "markdown";
+
+  if (!["markdown", "json"].includes(format)) {
+    throw new Error(`Unsupported doc flow format '${format}'. Use 'markdown' or 'json'.`);
+  }
+
+  const api = loadApi(apiPath);
+  const model = buildIntermediateModel(api);
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+
+  if (format === "json") {
+    fs.writeFileSync(outputPath, `${JSON.stringify(model, null, 2)}\n`, "utf8");
+  } else {
+    fs.writeFileSync(outputPath, buildDocFlowsMarkdown(model, apiPath), "utf8");
+  }
+
+  return {
+    outputPath,
+    format,
+    resources: model.resources.length,
+    flowCount: model.flowCount,
+  };
+}
+
+module.exports = { exportDocFlows };

package/adapters/flow-output-adapters.js

@@ -0,0 +1,15 @@
+"use strict";
+
+// Barrel — re-exports all output adapters from their domain modules.
+// Add new adapters to the relevant domain folder and re-export here.
+const { exportDocFlows } = require("./docs/doc-adapter");
+const { generatePostmanCollection } = require("./collections/postman-adapter");
+const { generateInsomniaWorkspace } = require("./collections/insomnia-adapter");
+const { generateRedocPackage } = require("./ui/redoc-adapter");
+
+module.exports = {
+  exportDocFlows,
+  generatePostmanCollection,
+  generateInsomniaWorkspace,
+  generateRedocPackage,
+};

package/adapters/shared/helpers.js

@@ -0,0 +1,87 @@
+"use strict";
+
+function toTitleCase(value) {
+  return String(value || "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[_-]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((word) => word[0].toUpperCase() + word.slice(1).toLowerCase())
+    .join(" ");
+}
+
+function pathToPostmanUrl(pathTemplate, resourceKey) {
+  const variablePrefix = resourceKey || "resource";
+  return String(pathTemplate || "")
+    .replace(/\{([^}]+)\}/g, (_full, name) => `{{${variablePrefix}${toTitleCase(name).replace(/\s+/g, "")}}}`);
+}
+
+function buildLifecycleSequences(resource) {
+  const flowOperations = resource.operations.filter((operation) => operation.hasFlow);
+  if (flowOperations.length === 0) {
+    return [];
+  }
+
+  const byId = new Map(flowOperations.map((operation) => [operation.operationId, operation]));
+  const indegree = new Map(flowOperations.map((operation) => [operation.operationId, 0]));
+
+  for (const operation of flowOperations) {
+    for (const next of operation.nextOperations || []) {
+      if (next.nextOperationId && indegree.has(next.nextOperationId)) {
+        indegree.set(next.nextOperationId, indegree.get(next.nextOperationId) + 1);
+      }
+    }
+  }
+
+  const starts = flowOperations
+    .filter((operation) => indegree.get(operation.operationId) === 0)
+    .map((operation) => operation.operationId);
+
+  const roots = starts.length > 0 ? starts : [flowOperations[0].operationId];
+  const sequences = [];
+
+  function walk(operationId, trail, seen) {
+    if (!byId.has(operationId) || seen.has(operationId)) {
+      sequences.push(trail.slice());
+      return;
+    }
+
+    const current = byId.get(operationId);
+    trail.push(current);
+
+    const nextIds = (current.nextOperations || [])
+      .map((next) => next.nextOperationId)
+      .filter((nextId) => nextId && byId.has(nextId));
+
+    if (nextIds.length === 0) {
+      sequences.push(trail.slice());
+      trail.pop();
+      return;
+    }
+
+    const nextSeen = new Set(seen);
+    nextSeen.add(operationId);
+    for (const nextId of nextIds) {
+      walk(nextId, trail, nextSeen);
+    }
+    trail.pop();
+  }
+
+  for (const root of roots) {
+    walk(root, [], new Set());
+  }
+
+  const dedup = new Map();
+  for (const sequence of sequences) {
+    if (!sequence || sequence.length === 0) continue;
+    const key = sequence.map((operation) => operation.operationId).join("->");
+    if (!dedup.has(key)) {
+      dedup.set(key, sequence);
+    }
+  }
+
+  return [...dedup.values()];
+}
+
+module.exports = { toTitleCase, pathToPostmanUrl, buildLifecycleSequences };

package/adapters/ui/redoc/x-openapi-flow-redoc-plugin.js

@@ -0,0 +1,127 @@
+(function () {
+  "use strict";
+
+  function createSectionTitle(text) {
+    var title = document.createElement("h3");
+    title.textContent = text;
+    title.style.margin = "16px 0 8px";
+    title.style.fontSize = "14px";
+    title.style.fontWeight = "700";
+    return title;
+  }
+
+  function listItem(text) {
+    var item = document.createElement("li");
+    item.textContent = text;
+    item.style.marginBottom = "6px";
+    return item;
+  }
+
+  function renderMermaidText(resource) {
+    var lines = ["stateDiagram-v2", "  direction LR"];
+
+    var states = Array.from(new Set((resource.states || []).filter(Boolean))).sort();
+    states.forEach(function (state) {
+      lines.push("  state " + state);
+    });
+
+    (resource.operations || []).forEach(function (operation) {
+      (operation.nextOperations || []).forEach(function (next) {
+        if (!operation.currentState || !next.targetState) return;
+        var label = next.nextOperationId || operation.operationId;
+        lines.push("  " + operation.currentState + " --> " + next.targetState + ": " + label);
+      });
+    });
+
+    return lines.join("\n");
+  }
+
+  function renderResourceBlock(resource) {
+    var container = document.createElement("div");
+    container.style.border = "1px solid #e5e7eb";
+    container.style.borderRadius = "8px";
+    container.style.padding = "12px";
+    container.style.marginBottom = "14px";
+
+    var title = document.createElement("h4");
+    title.textContent = (resource.resourcePlural || resource.resource || "Resource") + " Lifecycle";
+    title.style.margin = "0 0 8px";
+    title.style.fontSize = "13px";
+    container.appendChild(title);
+
+    var mermaid = document.createElement("pre");
+    mermaid.textContent = renderMermaidText(resource);
+    mermaid.style.background = "#f8fafc";
+    mermaid.style.border = "1px solid #e2e8f0";
+    mermaid.style.padding = "8px";
+    mermaid.style.borderRadius = "6px";
+    mermaid.style.whiteSpace = "pre-wrap";
+    mermaid.style.fontSize = "11px";
+    container.appendChild(mermaid);
+
+    var operationsTitle = createSectionTitle("Operations");
+    operationsTitle.style.marginTop = "10px";
+    operationsTitle.style.fontSize = "12px";
+    container.appendChild(operationsTitle);
+
+    var opList = document.createElement("ul");
+    opList.style.paddingLeft = "16px";
+
+    (resource.operations || []).forEach(function (operation) {
+      if (!operation.hasFlow) return;
+      var prerequisites = (operation.prerequisites || []).length > 0
+        ? operation.prerequisites.join(", ")
+        : "-";
+      var nextOps = (operation.nextOperations || [])
+        .map(function (next) { return next.nextOperationId; })
+        .filter(Boolean);
+      var nextText = nextOps.length > 0 ? nextOps.join(", ") : "-";
+
+      opList.appendChild(
+        listItem(
+          operation.operationId
+          + " | state=" + (operation.currentState || "-")
+          + " | prerequisites=" + prerequisites
+          + " | next=" + nextText
+        )
+      );
+    });
+
+    container.appendChild(opList);
+    return container;
+  }
+
+  function mount(options) {
+    var model = options && options.model;
+    if (!model || !Array.isArray(model.resources) || model.resources.length === 0) {
+      return;
+    }
+
+    var target = document.querySelector(options.targetSelector || "#x-openapi-flow-panel");
+    if (!target) {
+      return;
+    }
+
+    target.innerHTML = "";
+
+    var heading = document.createElement("h2");
+    heading.textContent = "Flow / Lifecycle";
+    heading.style.margin = "0 0 8px";
+    heading.style.fontSize = "18px";
+    target.appendChild(heading);
+
+    var subtitle = document.createElement("p");
+    subtitle.textContent = "Generated from x-openapi-flow metadata.";
+    subtitle.style.margin = "0 0 12px";
+    subtitle.style.color = "#4b5563";
+    target.appendChild(subtitle);
+
+    model.resources.forEach(function (resource) {
+      target.appendChild(renderResourceBlock(resource));
+    });
+  }
+
+  window.XOpenApiFlowRedocPlugin = {
+    mount: mount,
+  };
+})();

package/adapters/ui/redoc-adapter.js

@@ -0,0 +1,75 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { loadApi } = require("../../lib/validator");
+const { buildIntermediateModel } = require("../../lib/sdk-generator");
+
+function buildRedocHtml(model, specFileName) {
+  const modelPayload = JSON.stringify(model);
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>x-openapi-flow Redoc</title>
+    <style>
+      body { margin: 0; background: #ffffff; color: #111827; font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif; }
+      #x-openapi-flow-panel { max-width: 1200px; margin: 0 auto; padding: 16px; border-bottom: 1px solid #e5e7eb; }
+    </style>
+  </head>
+  <body>
+    <div id="x-openapi-flow-panel"></div>
+    <redoc spec-url="./${specFileName}"></redoc>
+    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
+    <script src="./x-openapi-flow-redoc-plugin.js"></script>
+    <script>
+      window.XOpenApiFlowRedocPlugin.mount({
+        model: ${modelPayload},
+        targetSelector: "#x-openapi-flow-panel"
+      });
+    </script>
+  </body>
+</html>
+`;
+}
+
+function generateRedocPackage(options) {
+  const apiPath = path.resolve(options.apiPath);
+  const outputDir = path.resolve(options.outputDir || path.join(process.cwd(), "redoc-flow"));
+
+  const api = loadApi(apiPath);
+  const model = buildIntermediateModel(api);
+  const specFileName = path.extname(apiPath).toLowerCase() === ".json" ? "openapi.json" : "openapi.yaml";
+
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const sourceSpec = fs.readFileSync(apiPath, "utf8");
+  fs.writeFileSync(path.join(outputDir, specFileName), sourceSpec, "utf8");
+
+  // Plugin lives at adapters/ui/redoc/ — __dirname is adapters/ui
+  const pluginSourcePath = path.join(__dirname, "redoc", "x-openapi-flow-redoc-plugin.js");
+  const pluginTargetPath = path.join(outputDir, "x-openapi-flow-redoc-plugin.js");
+  fs.copyFileSync(pluginSourcePath, pluginTargetPath);
+
+  fs.writeFileSync(
+    path.join(outputDir, "flow-model.json"),
+    `${JSON.stringify(model, null, 2)}\n`,
+    "utf8"
+  );
+
+  fs.writeFileSync(
+    path.join(outputDir, "index.html"),
+    buildRedocHtml(model, specFileName),
+    "utf8"
+  );
+
+  return {
+    outputDir,
+    indexPath: path.join(outputDir, "index.html"),
+    resources: model.resources.length,
+    flowCount: model.flowCount,
+  };
+}
+
+module.exports = { generateRedocPackage };