x-openapi-flow 1.1.3 → 1.2.1

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
 
@@ -8,7 +18,22 @@ CLI and specification for validating the `x-openapi-flow` extension field in Ope
 npm install x-openapi-flow
 ```
 
-## Quick Usage
+Optional mirror on GitHub Packages (default usage remains unscoped on npm):
+
+```bash
+npm config set @tiago-marques:registry https://npm.pkg.github.com
+npm install @tiago-marques/x-openapi-flow
+```
+
+If authentication is required, include this in your `.npmrc`:
+
+```ini
+//npm.pkg.github.com/:_authToken=${GH_PACKAGES_TOKEN}
+```
+
+Use a GitHub PAT with `read:packages` (install) and `write:packages` (publish).
+
+## Quick Start
 
 ```bash
 x-openapi-flow validate openapi.yaml
@@ -16,7 +41,7 @@ x-openapi-flow graph openapi.yaml
 x-openapi-flow doctor
 ```
 
-## Commands
+## CLI Commands
 
 ```bash
 x-openapi-flow validate <openapi-file> [--format pretty|json] [--profile core|relaxed|strict] [--strict-quality] [--config path]
@@ -26,20 +51,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:
 
@@ -51,29 +78,42 @@ 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
+- `prerequisite_field_refs`: required field refs before transition
+- `propagated_field_refs`: field refs used by downstream flows
 
-## Swagger UI
+Field reference format:
+
+- `operationId:request.body.field`
+- `operationId:response.<status>.body.field`
+
+## 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/payment-api.yaml

@@ -22,6 +22,12 @@ paths:
           - target_state: CAPTURED
             condition: Merchant explicitly requests capture.
             trigger_type: synchronous
+            next_operation_id: capturePayment
+            prerequisite_field_refs:
+              - createPayment:response.201.body.id
+            propagated_field_refs:
+              - createPayment:request.body.amount
+              - createPayment:request.body.currency
       requestBody:
         required: true
         content:

package/examples/swagger-ui/index.html

@@ -15,6 +15,9 @@
 
     <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
     <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
+    <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>
       window.ui = SwaggerUIBundle({

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

@@ -1,46 +1,427 @@
 window.XOpenApiFlowPlugin = function () {
+  const h = React.createElement;
+
+  function toPlain(value) {
+    if (!value) return value;
+    return value.toJS ? value.toJS() : value;
+  }
+
+  function text(value) {
+    if (value === null || value === undefined || value === "") return "-";
+    if (Array.isArray(value)) return value.length ? value.join(", ") : "-";
+    return String(value);
+  }
+
+  function transitionsList(currentState, transitions) {
+    if (!Array.isArray(transitions) || transitions.length === 0) {
+      return h("div", { style: { opacity: 0.85, fontStyle: "italic" } }, "No transitions (terminal state)");
+    }
+
+    return h(
+      "ul",
+      { style: { margin: "6px 0 0 18px", padding: 0 } },
+      transitions.map((transition, index) =>
+        h(
+          "li",
+          { key: `${currentState}-${index}`, style: { marginBottom: "4px", lineHeight: 1.45 } },
+          h("strong", null, text(transition.trigger_type)),
+          " → ",
+          h("strong", null, text(transition.target_state)),
+          transition.condition ? ` — ${text(transition.condition)}` : "",
+          transition.next_operation_id ? ` (next: ${text(transition.next_operation_id)})` : ""
+        )
+      )
+    );
+  }
+
+  function miniGraph(currentState, transitions) {
+    if (!Array.isArray(transitions) || transitions.length === 0) {
+      return [h("div", { key: "terminal", style: { fontFamily: "monospace" } }, `${text(currentState)} [terminal]`)];
+    }
+
+    return transitions.map((transition, index) =>
+      h(
+        "div",
+        { key: `edge-${index}`, style: { fontFamily: "monospace", lineHeight: 1.45 } },
+        `${text(currentState)} --> ${text(transition.target_state)} [${text(transition.trigger_type)}]`
+      )
+    );
+  }
+
   return {
     wrapComponents: {
-      OperationSummary: (Original, system) => (props) => {
+      OperationSummary: (Original) => (props) => {
         const operation = props.operation;
         const flow = operation && operation.get && operation.get("x-openapi-flow");
 
         if (!flow) {
-          return React.createElement(Original, props);
+          return h(Original, props);
         }
 
-        const flowObject = flow && flow.toJS ? flow.toJS() : flow;
-        const currentState = flowObject.current_state || "-";
-        const version = flowObject.version || "-";
+        const flowObject = toPlain(flow) || {};
+        const currentState = flowObject.current_state;
+        const transitions = Array.isArray(flowObject.transitions) ? flowObject.transitions : [];
+        const graphImageUrl = flowObject.graph_image_url || window.XOpenApiFlowGraphImageUrl;
+
+        const metadataGrid = h(
+          "div",
+          {
+            style: {
+              display: "grid",
+              gridTemplateColumns: "140px 1fr",
+              gap: "4px 10px",
+              fontSize: "12px",
+              marginTop: "6px",
+            },
+          },
+          h("div", { style: { opacity: 0.85 } }, "version"),
+          h("div", null, text(flowObject.version)),
+          h("div", { style: { opacity: 0.85 } }, "id"),
+          h("div", null, text(flowObject.id)),
+          h("div", { style: { opacity: 0.85 } }, "current_state"),
+          h("div", null, text(currentState))
+        );
+
+        const graphImageNode = graphImageUrl
+          ? h(
+              "div",
+              { style: { marginTop: "10px" } },
+              h("div", { style: { fontWeight: 700, marginBottom: "6px" } }, "Flow graph image"),
+              h("img", {
+                src: graphImageUrl,
+                alt: "x-openapi-flow graph",
+                style: {
+                  width: "100%",
+                  maxWidth: "560px",
+                  border: "1px solid rgba(255,255,255,0.3)",
+                  borderRadius: "6px",
+                },
+              })
+            )
+          : null;
 
-        return React.createElement(
+        return h(
           "div",
           null,
-          React.createElement(Original, props),
-          React.createElement(
+          h(Original, props),
+          h(
             "div",
             {
               style: {
                 marginTop: "8px",
-                padding: "8px 10px",
-                border: "1px solid #d9d9d9",
-                borderRadius: "6px",
-                background: "#fafafa",
+                padding: "10px",
+                border: "1px solid rgba(255,255,255,0.28)",
+                borderRadius: "8px",
+                background: "rgba(0,0,0,0.12)",
                 fontSize: "12px",
               },
             },
-            React.createElement("strong", null, "x-openapi-flow"),
-            React.createElement(
+            h("div", { style: { fontWeight: 700 } }, "x-openapi-flow"),
+            metadataGrid,
+            h("div", { style: { marginTop: "10px", fontWeight: 700 } }, "Transitions"),
+            transitionsList(currentState, transitions),
+            h("div", { style: { marginTop: "10px", fontWeight: 700 } }, "Flow graph (operation-level)"),
+            h(
               "div",
-              { style: { marginTop: "4px" } },
-              "version: ",
-              version,
-              " | current_state: ",
-              currentState
-            )
+              {
+                style: {
+                  marginTop: "6px",
+                  border: "1px dashed rgba(255,255,255,0.32)",
+                  borderRadius: "6px",
+                  padding: "8px",
+                },
+              },
+              ...miniGraph(currentState, transitions)
+            ),
+            graphImageNode
           )
         );
       },
     },
   };
 };
+
+(function () {
+  const styleId = 'x-openapi-flow-ui-style';
+
+  function injectStyles() {
+    if (document.getElementById(styleId)) return;
+
+    const style = document.createElement('style');
+    style.id = styleId;
+    style.textContent = `
+      .xof-card { border: 1px solid rgba(255,255,255,0.28); border-radius: 8px; padding: 10px; background: rgba(0,0,0,0.12); }
+      .xof-title { font-weight: 700; margin-bottom: 8px; }
+      .xof-meta { display: grid; grid-template-columns: 140px 1fr; gap: 4px 10px; font-size: 12px; margin-bottom: 10px; }
+      .xof-meta-label { opacity: 0.85; }
+      .xof-list { margin: 0; padding-left: 18px; }
+      .xof-list li { margin: 4px 0; }
+      .xof-graph { margin-top: 10px; padding: 8px; border: 1px dashed rgba(255,255,255,0.32); border-radius: 6px; }
+      .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);
+  }
+
+  function text(value) {
+    if (value === null || value === undefined || value === '') return '-';
+    if (Array.isArray(value)) return value.length ? value.join(', ') : '-';
+    return String(value);
+  }
+
+  function renderTransitions(currentState, transitions) {
+    if (!Array.isArray(transitions) || transitions.length === 0) {
+      return '<div class="xof-empty">No transitions (terminal state)</div>';
+    }
+
+    return `<ul class="xof-list">${transitions
+      .map((transition) => {
+        const condition = transition.condition ? ` — ${text(transition.condition)}` : '';
+        const nextOperation = transition.next_operation_id ? ` (next: ${text(transition.next_operation_id)})` : '';
+        return `<li><strong>${text(transition.trigger_type)}</strong> → <strong>${text(transition.target_state)}</strong>${condition}${nextOperation}</li>`;
+      })
+      .join('')}</ul>`;
+  }
+
+  function renderGraph(currentState, transitions) {
+    if (!Array.isArray(transitions) || transitions.length === 0) {
+      return `<div class="xof-edge">${text(currentState)} [terminal]</div>`;
+    }
+
+    return transitions
+      .map((transition) => `<div class="xof-edge">${text(currentState)} --> ${text(transition.target_state)} [${text(transition.trigger_type)}]</div>`)
+      .join('');
+  }
+
+  function renderCard(flow) {
+    const transitions = Array.isArray(flow.transitions) ? flow.transitions : [];
+    return `
+      <div class="xof-card">
+        <div class="xof-title">x-openapi-flow</div>
+        <div class="xof-meta">
+          <div class="xof-meta-label">version</div><div>${text(flow.version)}</div>
+          <div class="xof-meta-label">id</div><div>${text(flow.id)}</div>
+          <div class="xof-meta-label">current_state</div><div>${text(flow.current_state)}</div>
+        </div>
+        <div><strong>Transitions</strong></div>
+        ${renderTransitions(flow.current_state, transitions)}
+        <div class="xof-graph">
+          <div class="xof-graph-title">Flow graph (operation-level)</div>
+          ${renderGraph(flow.current_state, transitions)}
+        </div>
+      </div>
+    `;
+  }
+
+  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;
+  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;
+
+    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>';
+
+    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>
+      `;
+    }
+
+    overviewRenderedHash = currentHash;
+  }
+
+  function findXOpenApiFlowValueCell(opblock) {
+    const rows = opblock.querySelectorAll('tr');
+    for (const row of rows) {
+      const cells = row.querySelectorAll('td');
+      if (cells.length < 2) continue;
+      if (cells[0].innerText.trim() === 'x-openapi-flow') {
+        return cells[1];
+      }
+    }
+    return null;
+  }
+
+  function enhanceOperation(opblock) {
+    const valueCell = findXOpenApiFlowValueCell(opblock);
+    if (!valueCell || valueCell.dataset.xofEnhanced === '1') return;
+
+    const raw = valueCell.innerText.trim();
+    if (!raw) return;
+
+    let flow;
+    try {
+      flow = JSON.parse(raw);
+    } catch (_error) {
+      return;
+    }
+
+    valueCell.innerHTML = renderCard(flow);
+    valueCell.dataset.xofEnhanced = '1';
+  }
+
+  function enhanceAll() {
+    injectStyles();
+    const opblocks = document.querySelectorAll('.opblock');
+    opblocks.forEach((opblock) => enhanceOperation(opblock));
+    renderOverview();
+  }
+
+  const observer = new MutationObserver(() => {
+    enhanceAll();
+  });
+
+  window.addEventListener('load', () => {
+    enhanceAll();
+    observer.observe(document.body, { childList: true, subtree: true });
+  });
+})();

package/lib/validator.js

@@ -149,20 +149,42 @@ function defaultResult(pathValue, ok = true) {
       duplicate_transitions: [],
       non_terminating_states: [],
       invalid_operation_references: [],
+      invalid_field_references: [],
       warnings: [],
     },
   };
 }
 
+function getOperationsById(api) {
+  const operationsById = new Map();
+  const paths = (api && api.paths) || {};
+  const methods = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+
+  for (const [pathKey, pathItem] of Object.entries(paths)) {
+    for (const method of methods) {
+      const operation = pathItem[method];
+      if (!operation || !operation.operationId) {
+        continue;
+      }
+
+      operationsById.set(operation.operationId, {
+        operation,
+        endpoint: `${method.toUpperCase()} ${pathKey}`,
+      });
+    }
+  }
+
+  return operationsById;
+}
+
 /**
  * Detect invalid operationId references declared in transitions.
+ * @param {Map<string, { operation: object, endpoint: string }>} operationsById
  * @param {{ endpoint: string, operation_id?: string, flow: object }[]} flows
  * @returns {{ type: string, operation_id: string, declared_in: string }[]}
  */
-function detectInvalidOperationReferences(flows) {
-  const knownOperationIds = new Set(
-    flows.map(({ operation_id }) => operation_id).filter(Boolean)
-  );
+function detectInvalidOperationReferences(operationsById, flows) {
+  const knownOperationIds = new Set(operationsById.keys());
 
   const invalidReferences = [];
 
@@ -197,6 +219,196 @@ function detectInvalidOperationReferences(flows) {
   return invalidReferences;
 }
 
+function parseFieldReference(refValue) {
+  if (typeof refValue !== "string") {
+    return null;
+  }
+
+  const match = refValue.match(/^([^:]+):(request\.body|response\.(\d{3}|default)\.body)\.(.+)$/);
+  if (!match) {
+    return null;
+  }
+
+  const operationId = match[1];
+  const scope = match[2];
+  const responseCode = match[3];
+  const fieldPath = match[4];
+
+  return {
+    operation_id: operationId,
+    scope,
+    response_code: responseCode,
+    field_path: fieldPath,
+  };
+}
+
+function resolveSchema(api, schema, depth = 0) {
+  if (!schema || typeof schema !== "object") {
+    return null;
+  }
+
+  if (depth > 10) {
+    return null;
+  }
+
+  if (schema.$ref && typeof schema.$ref === "string") {
+    const ref = schema.$ref;
+    if (!ref.startsWith("#/")) {
+      return null;
+    }
+
+    const tokens = ref.slice(2).split("/");
+    let target = api;
+    for (const token of tokens) {
+      if (!target || typeof target !== "object") {
+        return null;
+      }
+      target = target[token];
+    }
+
+    return resolveSchema(api, target, depth + 1);
+  }
+
+  return schema;
+}
+
+function hasFieldPath(api, schema, pathTokens) {
+  const resolved = resolveSchema(api, schema);
+  if (!resolved) {
+    return false;
+  }
+
+  if (pathTokens.length === 0) {
+    return true;
+  }
+
+  const [currentToken, ...rest] = pathTokens;
+
+  if (Array.isArray(resolved.anyOf)) {
+    return resolved.anyOf.some((item) => hasFieldPath(api, item, pathTokens));
+  }
+  if (Array.isArray(resolved.oneOf)) {
+    return resolved.oneOf.some((item) => hasFieldPath(api, item, pathTokens));
+  }
+  if (Array.isArray(resolved.allOf)) {
+    return resolved.allOf.some((item) => hasFieldPath(api, item, pathTokens));
+  }
+
+  if (resolved.type === "array" && resolved.items) {
+    return hasFieldPath(api, resolved.items, pathTokens);
+  }
+
+  if (resolved.properties && typeof resolved.properties === "object") {
+    if (!(currentToken in resolved.properties)) {
+      return false;
+    }
+    return hasFieldPath(api, resolved.properties[currentToken], rest);
+  }
+
+  if (resolved.additionalProperties && typeof resolved.additionalProperties === "object") {
+    return hasFieldPath(api, resolved.additionalProperties, rest);
+  }
+
+  return false;
+}
+
+function resolveFieldReferenceSchema(api, operationsById, parsedRef) {
+  const operationInfo = operationsById.get(parsedRef.operation_id);
+  if (!operationInfo) {
+    return { error: "operation_not_found" };
+  }
+
+  const operation = operationInfo.operation;
+  if (parsedRef.scope === "request.body") {
+    const requestSchema = operation.requestBody
+      && operation.requestBody.content
+      && operation.requestBody.content["application/json"]
+      && operation.requestBody.content["application/json"].schema;
+
+    if (!requestSchema) {
+      return { error: "request_schema_not_found" };
+    }
+
+    return { schema: requestSchema };
+  }
+
+  const responseCode = parsedRef.response_code;
+  const responseSchema = operation.responses
+    && operation.responses[responseCode]
+    && operation.responses[responseCode].content
+    && operation.responses[responseCode].content["application/json"]
+    && operation.responses[responseCode].content["application/json"].schema;
+
+  if (!responseSchema) {
+    return { error: "response_schema_not_found" };
+  }
+
+  return { schema: responseSchema };
+}
+
+function detectInvalidFieldReferences(api, operationsById, flows) {
+  const invalidFieldReferences = [];
+
+  for (const { endpoint, flow } of flows) {
+    const transitions = flow.transitions || [];
+
+    for (const transition of transitions) {
+      const referenceGroups = [
+        {
+          type: "prerequisite_field_refs",
+          refs: Array.isArray(transition.prerequisite_field_refs)
+            ? transition.prerequisite_field_refs
+            : [],
+        },
+        {
+          type: "propagated_field_refs",
+          refs: Array.isArray(transition.propagated_field_refs)
+            ? transition.propagated_field_refs
+            : [],
+        },
+      ];
+
+      for (const group of referenceGroups) {
+        for (const refValue of group.refs) {
+          const parsedRef = parseFieldReference(refValue);
+          if (!parsedRef) {
+            invalidFieldReferences.push({
+              type: group.type,
+              reference: refValue,
+              reason: "invalid_format",
+              declared_in: endpoint,
+            });
+            continue;
+          }
+
+          const resolvedSchema = resolveFieldReferenceSchema(api, operationsById, parsedRef);
+          if (resolvedSchema.error) {
+            invalidFieldReferences.push({
+              type: group.type,
+              reference: refValue,
+              reason: resolvedSchema.error,
+              declared_in: endpoint,
+            });
+            continue;
+          }
+
+          const pathTokens = parsedRef.field_path.split(".").filter(Boolean);
+          if (!hasFieldPath(api, resolvedSchema.schema, pathTokens)) {
+            invalidFieldReferences.push({
+              type: group.type,
+              reference: refValue,
+              reason: "field_not_found",
+              declared_in: endpoint,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return invalidFieldReferences;
+}
+
 /**
  * Verify that every target_state referenced in transitions corresponds to a
  * current_state defined in at least one endpoint of the same API.
@@ -588,6 +800,7 @@ function run(apiPath, options = {}) {
   }
 
   // 5. Advanced graph checks
+  const operationsById = getOperationsById(api);
   const graph = buildStateGraph(flows);
   const initialStates = [...graph.nodes].filter(
     (state) => graph.indegree.get(state) === 0
@@ -599,7 +812,8 @@ function run(apiPath, options = {}) {
   const cycle = detectCycle(graph);
   const duplicateTransitions = detectDuplicateTransitions(flows);
   const terminalCoverage = detectTerminalCoverage(graph);
-  const invalidOperationReferences = detectInvalidOperationReferences(flows);
+  const invalidOperationReferences = detectInvalidOperationReferences(operationsById, flows);
+  const invalidFieldReferences = detectInvalidFieldReferences(api, operationsById, flows);
   const multipleInitialStates = initialStates.length > 1 ? initialStates : [];
 
   if (profileConfig.runAdvanced) {
@@ -645,6 +859,12 @@ function run(apiPath, options = {}) {
     );
   }
 
+  if (profileConfig.runQuality && invalidFieldReferences.length > 0) {
+    qualityWarnings.push(
+      `Transition field references not found/invalid: ${invalidFieldReferences.length}`
+    );
+  }
+
   if (strictQuality && qualityWarnings.length > 0) {
     hasErrors = true;
   }
@@ -734,6 +954,7 @@ function run(apiPath, options = {}) {
       duplicate_transitions: duplicateTransitions,
       non_terminating_states: terminalCoverage.non_terminating_states,
       invalid_operation_references: invalidOperationReferences,
+      invalid_field_references: invalidFieldReferences,
       warnings: qualityWarnings,
     },
   };

package/package.json

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

package/schema/flow-schema.json

@@ -69,6 +69,20 @@
             "items": {
               "type": "string"
             }
+          },
+          "prerequisite_field_refs": {
+            "type": "array",
+            "description": "Field references required before this transition. Format: operationId:request.body.field or operationId:response.<status>.body.field",
+            "items": {
+              "type": "string"
+            }
+          },
+          "propagated_field_refs": {
+            "type": "array",
+            "description": "Field references produced/propagated for downstream flows. Format: operationId:request.body.field or operationId:response.<status>.body.field",
+            "items": {
+              "type": "string"
+            }
           }
         },
         "additionalProperties": false