x-openapi-flow 1.1.3 → 1.2.0

package/README.md

@@ -8,6 +8,21 @@ CLI and specification for validating the `x-openapi-flow` extension field in Ope
 npm install x-openapi-flow
 ```
 
+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 Usage
 
 ```bash
@@ -60,6 +75,13 @@ Create `x-openapi-flow.config.json` in your project directory:
 
 - `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
+
+Field reference format:
+
+- `operationId:request.body.field`
+- `operationId:response.<status>.body.field`
 
 ## Swagger UI
 
@@ -67,6 +89,8 @@ Create `x-openapi-flow.config.json` in your project directory:
 - 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`.
 
+![Swagger UI integration result](../docs/assets/swagger-ui-integration-result-v2.svg)
+
 ## Graph Output Example
 
 `x-openapi-flow graph` includes transition guidance labels in Mermaid output when present (`next_operation_id`, `prerequisite_operation_ids`).

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,262 @@
 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;
 
-        return React.createElement(
+        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 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; }
+    `;
+
+    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 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));
+  }
+
+  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.0",
   "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