x-openapi-flow 1.2.1 → 1.2.3

package/README.md

@@ -36,9 +36,15 @@ Use a GitHub PAT with `read:packages` (install) and `write:packages` (publish).
 ## Quick Start
 
 ```bash
-x-openapi-flow validate openapi.yaml
-x-openapi-flow graph openapi.yaml
-x-openapi-flow doctor
+npx x-openapi-flow init openapi.yaml
+npx x-openapi-flow apply openapi.yaml
+```
+
+Optional checks:
+
+```bash
+npx x-openapi-flow validate openapi.yaml --profile strict
+npx x-openapi-flow graph openapi.yaml
 ```
 
 ## CLI Commands
@@ -100,7 +106,7 @@ Field reference format:
 ### Swagger UI
 
 - There is no Swagger UI-based automated test in this repo today (tests are CLI-only).
-- For UI interpretation of `x-openapi-flow`, use `showExtensions: true` plus the example plugin at `examples/swagger-ui/x-openapi-flow-plugin.js`.
+- For UI interpretation of `x-openapi-flow`, use `showExtensions: true` plus the plugin at `lib/swagger-ui/x-openapi-flow-plugin.js`.
 - A ready HTML example is available at `examples/swagger-ui/index.html`.
 - The plugin renders a global **Flow Overview** (Mermaid image) near the top of the docs, plus operation-level flow cards.
 

package/bin/x-openapi-flow.js

@@ -44,7 +44,7 @@ function printHelp() {
 Usage:
   x-openapi-flow validate <openapi-file> [--format pretty|json] [--profile core|relaxed|strict] [--strict-quality] [--config path]
   x-openapi-flow init [openapi-file] [--flows path]
-  x-openapi-flow apply [openapi-file] [--flows path] [--out path]
+  x-openapi-flow apply [openapi-file] [--flows path] [--out path] [--in-place]
   x-openapi-flow graph <openapi-file> [--format mermaid|json]
   x-openapi-flow doctor [--config path]
   x-openapi-flow --help
@@ -56,12 +56,19 @@ Examples:
   x-openapi-flow init openapi.yaml --flows openapi-openapi-flow.yaml
   x-openapi-flow init
   x-openapi-flow apply openapi.yaml
+  x-openapi-flow apply openapi.yaml --in-place
   x-openapi-flow apply openapi.yaml --out openapi.flow.yaml
   x-openapi-flow graph examples/order-api.yaml
   x-openapi-flow doctor
 `);
 }
 
+function deriveFlowOutputPath(openApiFile) {
+  const parsed = path.parse(openApiFile);
+  const extension = parsed.ext || ".yaml";
+  return path.join(parsed.dir, `${parsed.name}.flow${extension}`);
+}
+
 function getOptionValue(args, optionName) {
   const index = args.indexOf(optionName);
   if (index === -1) {
@@ -199,7 +206,7 @@ function parseInitArgs(args) {
 }
 
 function parseApplyArgs(args) {
-  const unknown = findUnknownOptions(args, ["--flows", "--out"], []);
+  const unknown = findUnknownOptions(args, ["--flows", "--out"], ["--in-place"]);
   if (unknown) {
     return { error: `Unknown option: ${unknown}` };
   }
@@ -214,8 +221,13 @@ function parseApplyArgs(args) {
     return { error: outOpt.error };
   }
 
+  const inPlace = args.includes("--in-place");
+  if (inPlace && outOpt.found) {
+    return { error: "Options --in-place and --out cannot be used together." };
+  }
+
   const positional = args.filter((token, index) => {
-    if (token === "--flows" || token === "--out") {
+    if (token === "--flows" || token === "--out" || token === "--in-place") {
       return false;
     }
     if (index > 0 && (args[index - 1] === "--flows" || args[index - 1] === "--out")) {
@@ -232,6 +244,7 @@ function parseApplyArgs(args) {
     openApiFile: positional[0] ? path.resolve(positional[0]) : undefined,
     flowsPath: flowsOpt.found ? path.resolve(flowsOpt.value) : undefined,
     outPath: outOpt.found ? path.resolve(outOpt.value) : undefined,
+    inPlace,
   };
 }
 
@@ -656,7 +669,9 @@ function runApply(parsed) {
   }
 
   const appliedCount = applyFlowsToOpenApi(api, flowsDoc);
-  const outputPath = parsed.outPath || targetOpenApiFile;
+  const outputPath = parsed.inPlace
+    ? targetOpenApiFile
+    : (parsed.outPath || deriveFlowOutputPath(targetOpenApiFile));
   saveOpenApi(outputPath, api);
 
   console.log(`OpenAPI source: ${targetOpenApiFile}`);

package/examples/swagger-ui/index.html

@@ -18,7 +18,7 @@
     <script>
       window.XOpenApiFlowGraphImageUrl = "https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/graph-order-guided.svg";
     </script>
-    <script src="./x-openapi-flow-plugin.js"></script>
+    <script src="../../lib/swagger-ui/x-openapi-flow-plugin.js"></script>
     <script>
       window.ui = SwaggerUIBundle({
         url: "../payment-api.yaml",

package/{examples → lib}/swagger-ui/x-openapi-flow-plugin.js

@@ -256,6 +256,10 @@ window.XOpenApiFlowPlugin = function () {
     return result;
   }
 
+  function hasFlowData(spec) {
+    return extractFlowsFromSpec(spec).length > 0;
+  }
+
   function buildOverviewMermaid(flows) {
     const lines = ['stateDiagram-v2'];
     const states = new Set();
@@ -331,6 +335,8 @@ window.XOpenApiFlowPlugin = function () {
   }
 
   let overviewRenderedHash = null;
+  let overviewRenderInProgress = false;
+  let overviewPendingHash = null;
   async function renderOverview() {
     const spec = getSpecFromUi();
     const flows = extractFlowsFromSpec(spec);
@@ -339,6 +345,7 @@ window.XOpenApiFlowPlugin = function () {
     const mermaid = buildOverviewMermaid(flows);
     const currentHash = `${flows.length}:${mermaid}`;
     if (overviewRenderedHash === currentHash) return;
+    if (overviewRenderInProgress && overviewPendingHash === currentHash) return;
 
     const infoContainer = document.querySelector('.swagger-ui .information-container');
     if (!infoContainer) return;
@@ -352,6 +359,8 @@ window.XOpenApiFlowPlugin = function () {
     }
 
     holder.innerHTML = '<div class="xof-title">x-openapi-flow — Flow Overview</div><div class="xof-empty">Rendering Mermaid graph...</div>';
+    overviewRenderInProgress = true;
+    overviewPendingHash = currentHash;
 
     try {
       const mermaidLib = await ensureMermaid();
@@ -374,6 +383,8 @@ window.XOpenApiFlowPlugin = function () {
         <div class="xof-empty">Could not render Mermaid image in this environment.</div>
         <div class="xof-overview-code">${mermaid.replace(/</g, '&lt;').replace(/>/g, '&gt;')}</div>
       `;
+    } finally {
+      overviewRenderInProgress = false;
     }
 
     overviewRenderedHash = currentHash;
@@ -410,18 +421,35 @@ window.XOpenApiFlowPlugin = function () {
   }
 
   function enhanceAll() {
+    const spec = getSpecFromUi();
+    if (!hasFlowData(spec)) {
+      return;
+    }
+
     injectStyles();
     const opblocks = document.querySelectorAll('.opblock');
     opblocks.forEach((opblock) => enhanceOperation(opblock));
-    renderOverview();
+    renderOverview().catch(() => {
+      // keep plugin resilient in environments where async rendering fails
+    });
+  }
+
+  let enhanceScheduled = false;
+  function scheduleEnhance() {
+    if (enhanceScheduled) return;
+    enhanceScheduled = true;
+    window.requestAnimationFrame(() => {
+      enhanceScheduled = false;
+      enhanceAll();
+    });
   }
 
   const observer = new MutationObserver(() => {
-    enhanceAll();
+    scheduleEnhance();
   });
 
   window.addEventListener('load', () => {
-    enhanceAll();
+    scheduleEnhance();
     observer.observe(document.body, { childList: true, subtree: true });
   });
 })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x-openapi-flow",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "OpenAPI extension for resource workflow and lifecycle management",
   "main": "lib/validator.js",
   "repository": {