x-openapi-flow 1.2.0 → 1.2.2

package/README.md

@@ -1,6 +1,16 @@
 # x-openapi-flow
 
-CLI and specification for validating the `x-openapi-flow` extension field in OpenAPI documents.
+CLI and extension contract for documenting and validating resource lifecycle workflows in OpenAPI using `x-openapi-flow`.
+
+## Overview
+
+`x-openapi-flow` validates:
+
+- Extension schema correctness
+- Lifecycle graph consistency
+- Optional quality checks for transitions and references
+
+It also supports a sidecar workflow (`init` + `apply`) to preserve lifecycle metadata when OpenAPI files are regenerated.
 
 ## Installation
 
@@ -23,15 +33,21 @@ If authentication is required, include this in your `.npmrc`:
 
 Use a GitHub PAT with `read:packages` (install) and `write:packages` (publish).
 
-## Quick Usage
+## Quick Start
+
+```bash
+npx x-openapi-flow init openapi.yaml
+npx x-openapi-flow apply openapi.yaml
+```
+
+Optional checks:
 
 ```bash
-x-openapi-flow validate openapi.yaml
-x-openapi-flow graph openapi.yaml
-x-openapi-flow doctor
+npx x-openapi-flow validate openapi.yaml --profile strict
+npx x-openapi-flow graph openapi.yaml
 ```
 
-## Commands
+## CLI Commands
 
 ```bash
 x-openapi-flow validate <openapi-file> [--format pretty|json] [--profile core|relaxed|strict] [--strict-quality] [--config path]
@@ -41,20 +57,22 @@ x-openapi-flow graph <openapi-file> [--format mermaid|json]
 x-openapi-flow doctor [--config path]
 ```
 
+## Sidecar Workflow
+
 `init` always works on an existing OpenAPI file in your repository.
-`init` creates/synchronizes `x-openapi-flow.flows.yaml` as a persistent sidecar for your `x-openapi-flow` data.
+`init` creates/synchronizes `{context}-openapi-flow.(json|yaml)` as a persistent sidecar for your `x-openapi-flow` data.
 Use `apply` to inject sidecar flows back into regenerated OpenAPI files.
 If no OpenAPI/Swagger file exists yet, generate one first with your framework's official OpenAPI/Swagger tooling.
 
-## Recommended Workflow
+### Recommended Sequence
 
 ```bash
 x-openapi-flow init openapi.yaml
-# edit x-openapi-flow.flows.yaml
+# edit {context}-openapi-flow.(json|yaml)
 x-openapi-flow apply openapi.yaml
 ```
 
-## Optional Configuration
+## Configuration
 
 Create `x-openapi-flow.config.json` in your project directory:
 
@@ -66,12 +84,12 @@ Create `x-openapi-flow.config.json` in your project directory:
 }
 ```
 
-## File Compatibility
+## Compatibility
 
 - OpenAPI input in `.yaml`, `.yml`, and `.json`
 - Validation processes OAS content with the `x-openapi-flow` extension
 
-### Optional Transition Guidance Fields
+## Transition Guidance Fields
 
 - `next_operation_id`: operationId usually called for the next state transition
 - `prerequisite_operation_ids`: operationIds expected before a transition
@@ -83,21 +101,25 @@ Field reference format:
 - `operationId:request.body.field`
 - `operationId:response.<status>.body.field`
 
-## Swagger UI
+## Visualization
+
+### 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`.
 - 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.
 
 ![Swagger UI integration result](../docs/assets/swagger-ui-integration-result-v2.svg)
 
-## Graph Output Example
+### Graph Output Example
 
 `x-openapi-flow graph` includes transition guidance labels in Mermaid output when present (`next_operation_id`, `prerequisite_operation_ids`).
+The `graph` command accepts both full OpenAPI files and sidecar files (`{context}-openapi-flow.(json|yaml)`).
 
 ![Guided graph example](../docs/assets/graph-order-guided.svg)
 
-## Repository and Full Documentation
+## Repository and Documentation
 
 - Repository: https://github.com/tiago-marques/x-openapi-flow
 - Full guide and changelog are available in the root repository.

package/bin/x-openapi-flow.js

@@ -53,7 +53,7 @@ Examples:
   x-openapi-flow validate examples/order-api.yaml
   x-openapi-flow validate examples/order-api.yaml --profile relaxed
   x-openapi-flow validate examples/order-api.yaml --strict-quality
-  x-openapi-flow init openapi.yaml --flows x-openapi-flow.flows.yaml
+  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 --out openapi.flow.yaml
@@ -386,7 +386,10 @@ function resolveFlowsPath(openApiFile, customFlowsPath) {
   }
 
   if (openApiFile) {
-    return path.join(path.dirname(openApiFile), DEFAULT_FLOWS_FILE);
+    const parsed = path.parse(openApiFile);
+    const extension = parsed.ext.toLowerCase() === ".json" ? ".json" : ".yaml";
+    const fileName = `${parsed.name}-openapi-flow${extension}`;
+    return path.join(path.dirname(openApiFile), fileName);
   }
 
   return path.resolve(process.cwd(), DEFAULT_FLOWS_FILE);
@@ -406,6 +409,15 @@ function saveOpenApi(filePath, api) {
   fs.writeFileSync(filePath, content, "utf8");
 }
 
+function buildFallbackOperationId(method, pathKey) {
+  const raw = `${method}_${pathKey}`.toLowerCase();
+  const sanitized = raw
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+
+  return sanitized || "operation";
+}
+
 function extractOperationEntries(api) {
   const entries = [];
   const paths = (api && api.paths) || {};
@@ -419,13 +431,16 @@ function extractOperationEntries(api) {
       }
 
       const operationId = operation.operationId;
+      const resolvedOperationId = operationId || buildFallbackOperationId(method, pathKey);
       const key = operationId ? `operationId:${operationId}` : `${method.toUpperCase()} ${pathKey}`;
 
       entries.push({
         key,
         operationId,
+        resolvedOperationId,
         method,
         path: pathKey,
+        operation,
       });
     }
   }
@@ -456,10 +471,22 @@ function readFlowsFile(flowsPath) {
 
 function writeFlowsFile(flowsPath, flowsDoc) {
   fs.mkdirSync(path.dirname(flowsPath), { recursive: true });
-  const content = yaml.dump(flowsDoc, { noRefs: true, lineWidth: -1 });
+  const content = flowsPath.endsWith(".json")
+    ? `${JSON.stringify(flowsDoc, null, 2)}\n`
+    : yaml.dump(flowsDoc, { noRefs: true, lineWidth: -1 });
   fs.writeFileSync(flowsPath, content, "utf8");
 }
 
+function buildFlowTemplate(operationId) {
+  const safeOperationId = operationId || "operation";
+  return {
+    version: "1.0",
+    id: `${safeOperationId}_FLOW_ID`,
+    current_state: `${safeOperationId}_STATE`,
+    transitions: [],
+  };
+}
+
 function buildOperationLookup(api) {
   const lookupByKey = new Map();
   const lookupByOperationId = new Map();
@@ -467,8 +494,8 @@ function buildOperationLookup(api) {
 
   for (const entry of entries) {
     lookupByKey.set(entry.key, entry);
-    if (entry.operationId) {
-      lookupByOperationId.set(entry.operationId, entry);
+    if (entry.resolvedOperationId) {
+      lookupByOperationId.set(entry.resolvedOperationId, entry);
     }
   }
 
@@ -476,51 +503,41 @@ function buildOperationLookup(api) {
 }
 
 function mergeFlowsWithOpenApi(api, flowsDoc) {
-  const { entries, lookupByKey, lookupByOperationId } = buildOperationLookup(api);
+  const { entries, lookupByKey } = buildOperationLookup(api);
 
+  const existingByOperationId = new Map();
   const existingByKey = new Map();
   for (const entry of flowsDoc.operations) {
-    const entryKey = entry.key || (entry.operationId ? `operationId:${entry.operationId}` : null);
-    if (entryKey) {
-      existingByKey.set(entryKey, entry);
+    if (entry && entry.operationId) {
+      existingByOperationId.set(entry.operationId, entry);
+    }
+
+    const legacyKey = entry && entry.key ? entry.key : null;
+    if (legacyKey) {
+      existingByKey.set(legacyKey, entry);
     }
   }
 
   const mergedOperations = [];
 
   for (const op of entries) {
-    const existing = existingByKey.get(op.key);
-    if (existing) {
-      mergedOperations.push({
-        ...existing,
-        key: op.key,
-        operationId: op.operationId,
-        method: op.method,
-        path: op.path,
-        missing_in_openapi: false,
-      });
-    } else {
-      mergedOperations.push({
-        key: op.key,
-        operationId: op.operationId,
-        method: op.method,
-        path: op.path,
-        "x-openapi-flow": null,
-        missing_in_openapi: false,
-      });
-    }
-  }
+    const existing = (op.resolvedOperationId && existingByOperationId.get(op.resolvedOperationId))
+      || existingByKey.get(op.key);
 
-  for (const existing of flowsDoc.operations) {
-    const existingKey = existing.key || (existing.operationId ? `operationId:${existing.operationId}` : null);
-    const found = existingKey && lookupByKey.has(existingKey);
+    const openApiFlow =
+      op.operation && typeof op.operation["x-openapi-flow"] === "object"
+        ? op.operation["x-openapi-flow"]
+        : null;
 
-    if (!found) {
-      mergedOperations.push({
-        ...existing,
-        missing_in_openapi: true,
-      });
-    }
+    const sidecarFlow =
+      existing && typeof existing["x-openapi-flow"] === "object"
+        ? existing["x-openapi-flow"]
+        : null;
+
+    mergedOperations.push({
+      operationId: op.resolvedOperationId,
+      "x-openapi-flow": sidecarFlow || openApiFlow || buildFlowTemplate(op.resolvedOperationId),
+    });
   }
 
   return {
@@ -535,12 +552,12 @@ function applyFlowsToOpenApi(api, flowsDoc) {
   const { lookupByKey, lookupByOperationId } = buildOperationLookup(api);
 
   for (const flowEntry of flowsDoc.operations || []) {
-    if (!flowEntry || flowEntry.missing_in_openapi === true) {
+    if (!flowEntry) {
       continue;
     }
 
     const flowValue = flowEntry["x-openapi-flow"];
-    if (!flowValue || typeof flowValue !== "object") {
+    if (!flowValue || typeof flowValue !== "object" || Object.keys(flowValue).length === 0) {
       continue;
     }
 
@@ -595,19 +612,12 @@ function runInit(parsed) {
 
   const mergedFlows = mergeFlowsWithOpenApi(api, flowsDoc);
   writeFlowsFile(flowsPath, mergedFlows);
-  const appliedCount = applyFlowsToOpenApi(api, mergedFlows);
-  saveOpenApi(targetOpenApiFile, api);
-
-  const trackedCount = mergedFlows.operations.filter((entry) => !entry.missing_in_openapi).length;
-  const orphanCount = mergedFlows.operations.filter((entry) => entry.missing_in_openapi).length;
+  const trackedCount = mergedFlows.operations.length;
 
   console.log(`Using existing OpenAPI file: ${targetOpenApiFile}`);
   console.log(`Flows sidecar synced: ${flowsPath}`);
   console.log(`Tracked operations: ${trackedCount}`);
-  if (orphanCount > 0) {
-    console.log(`Orphan flow entries kept in sidecar: ${orphanCount}`);
-  }
-  console.log(`Applied x-openapi-flow entries to OpenAPI: ${appliedCount}`);
+  console.log("OpenAPI source unchanged. Edit the sidecar and run apply to generate the full spec.");
 
   console.log(`Validate now: x-openapi-flow validate ${targetOpenApiFile}`);
   return 0;
@@ -699,8 +709,11 @@ function runDoctor(parsed) {
 }
 
 function buildMermaidGraph(filePath) {
-  const api = loadApi(filePath);
-  const flows = extractFlows(api);
+  const flows = extractFlowsForGraph(filePath);
+  if (flows.length === 0) {
+    throw new Error("No x-openapi-flow definitions found in OpenAPI or sidecar file");
+  }
+
   const lines = ["stateDiagram-v2"];
   const nodes = new Set();
   const edges = [];
@@ -760,6 +773,51 @@ function buildMermaidGraph(filePath) {
   };
 }
 
+function extractFlowsForGraph(filePath) {
+  let flows = [];
+
+  try {
+    const api = loadApi(filePath);
+    flows = extractFlows(api);
+  } catch (_err) {
+    flows = [];
+  }
+
+  if (flows.length > 0) {
+    return flows;
+  }
+
+  const content = fs.readFileSync(filePath, "utf8");
+  const parsed = yaml.load(content);
+
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.operations)) {
+    return [];
+  }
+
+  const sidecarFlows = [];
+  for (const operationEntry of parsed.operations) {
+    if (!operationEntry || typeof operationEntry !== "object") {
+      continue;
+    }
+
+    const flow = operationEntry["x-openapi-flow"];
+    if (!flow || typeof flow !== "object") {
+      continue;
+    }
+
+    if (!flow.current_state) {
+      continue;
+    }
+
+    sidecarFlows.push({
+      endpoint: operationEntry.operationId || operationEntry.key || "sidecar-operation",
+      flow,
+    });
+  }
+
+  return sidecarFlows;
+}
+
 function runGraph(parsed) {
   try {
     const graphResult = buildMermaidGraph(parsed.filePath);

package/examples/swagger-ui/x-openapi-flow-plugin.js

@@ -160,6 +160,9 @@ window.XOpenApiFlowPlugin = function () {
       .xof-graph-title { font-size: 12px; font-weight: 700; margin-bottom: 6px; }
       .xof-edge { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', monospace; font-size: 12px; line-height: 1.45; white-space: pre-wrap; }
       .xof-empty { opacity: 0.85; font-style: italic; }
+      .xof-overview { margin: 10px 0 16px; }
+      .xof-overview img { width: 100%; max-width: 760px; border: 1px solid rgba(255,255,255,0.3); border-radius: 6px; background: #fff; }
+      .xof-overview-code { margin-top: 8px; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', monospace; font-size: 11px; opacity: 0.9; white-space: pre-wrap; }
     `;
 
     document.head.appendChild(style);
@@ -215,6 +218,174 @@ window.XOpenApiFlowPlugin = function () {
     `;
   }
 
+  function getSpecFromUi() {
+    try {
+      if (!window.ui || !window.ui.specSelectors || !window.ui.specSelectors.specJson) {
+        return null;
+      }
+
+      const spec = window.ui.specSelectors.specJson();
+      return spec && spec.toJS ? spec.toJS() : spec;
+    } catch (_error) {
+      return null;
+    }
+  }
+
+  function extractFlowsFromSpec(spec) {
+    const result = [];
+    const paths = (spec && spec.paths) || {};
+    const methods = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+
+    Object.entries(paths).forEach(([pathKey, pathItem]) => {
+      if (!pathItem || typeof pathItem !== 'object') return;
+
+      methods.forEach((method) => {
+        const operation = pathItem[method];
+        if (!operation || typeof operation !== 'object') return;
+
+        const flow = operation['x-openapi-flow'];
+        if (!flow || typeof flow !== 'object' || !flow.current_state) return;
+
+        result.push({
+          operationId: operation.operationId || `${method}_${pathKey}`,
+          flow,
+        });
+      });
+    });
+
+    return result;
+  }
+
+  function buildOverviewMermaid(flows) {
+    const lines = ['stateDiagram-v2'];
+    const states = new Set();
+    const seen = new Set();
+
+    flows.forEach(({ flow }) => {
+      const current = flow.current_state;
+      if (!current) return;
+
+      states.add(current);
+      const transitions = Array.isArray(flow.transitions) ? flow.transitions : [];
+      transitions.forEach((transition) => {
+        const target = transition.target_state;
+        if (!target) return;
+        states.add(target);
+
+        const labelParts = [];
+        if (transition.next_operation_id) {
+          labelParts.push(`next:${text(transition.next_operation_id)}`);
+        }
+        if (Array.isArray(transition.prerequisite_operation_ids) && transition.prerequisite_operation_ids.length) {
+          labelParts.push(`requires:${transition.prerequisite_operation_ids.join(',')}`);
+        }
+        const label = labelParts.join(' | ');
+        const key = `${current}::${target}::${label}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        lines.push(`  ${current} --> ${target}${label ? `: ${label}` : ''}`);
+      });
+    });
+
+    Array.from(states)
+      .sort()
+      .forEach((state) => {
+        lines.splice(1, 0, `  state ${state}`);
+      });
+
+    return lines.join('\n');
+  }
+
+  let mermaidLoaderPromise = null;
+  function ensureMermaid() {
+    if (window.mermaid) {
+      return Promise.resolve(window.mermaid);
+    }
+
+    if (mermaidLoaderPromise) {
+      return mermaidLoaderPromise;
+    }
+
+    mermaidLoaderPromise = new Promise((resolve, reject) => {
+      const script = document.createElement('script');
+      script.src = 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js';
+      script.async = true;
+      script.onload = () => {
+        if (window.mermaid) {
+          window.mermaid.initialize({ startOnLoad: false, securityLevel: 'loose' });
+          resolve(window.mermaid);
+        } else {
+          reject(new Error('Mermaid library not available after load'));
+        }
+      };
+      script.onerror = () => reject(new Error('Could not load Mermaid library'));
+      document.head.appendChild(script);
+    });
+
+    return mermaidLoaderPromise;
+  }
+
+  function svgToDataUri(svg) {
+    const encoded = window.btoa(unescape(encodeURIComponent(svg)));
+    return `data:image/svg+xml;base64,${encoded}`;
+  }
+
+  let overviewRenderedHash = null;
+  let overviewRenderInProgress = false;
+  let overviewPendingHash = null;
+  async function renderOverview() {
+    const spec = getSpecFromUi();
+    const flows = extractFlowsFromSpec(spec);
+    if (!flows.length) return;
+
+    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;
+
+    let holder = document.getElementById('xof-overview-holder');
+    if (!holder) {
+      holder = document.createElement('div');
+      holder.id = 'xof-overview-holder';
+      holder.className = 'xof-overview xof-card';
+      infoContainer.parentNode.insertBefore(holder, infoContainer.nextSibling);
+    }
+
+    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();
+      const renderId = `xof-overview-${Date.now()}`;
+      const renderResult = await mermaidLib.render(renderId, mermaid);
+      const svg = renderResult && renderResult.svg ? renderResult.svg : renderResult;
+      const dataUri = svgToDataUri(svg);
+
+      holder.innerHTML = `
+        <div class="xof-title">x-openapi-flow — Flow Overview</div>
+        <img src="${dataUri}" alt="x-openapi-flow overview graph" />
+        <details style="margin-top:8px;">
+          <summary style="cursor:pointer;">Mermaid source</summary>
+          <div class="xof-overview-code">${mermaid.replace(/</g, '&lt;').replace(/>/g, '&gt;')}</div>
+        </details>
+      `;
+    } catch (_error) {
+      holder.innerHTML = `
+        <div class="xof-title">x-openapi-flow — Flow Overview</div>
+        <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;
+  }
+
   function findXOpenApiFlowValueCell(opblock) {
     const rows = opblock.querySelectorAll('tr');
     for (const row of rows) {
@@ -249,14 +420,27 @@ window.XOpenApiFlowPlugin = function () {
     injectStyles();
     const opblocks = document.querySelectorAll('.opblock');
     opblocks.forEach((opblock) => enhanceOperation(opblock));
+    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.0",
+  "version": "1.2.2",
   "description": "OpenAPI extension for resource workflow and lifecycle management",
   "main": "lib/validator.js",
   "repository": {