x-openapi-flow 1.1.2 → 1.1.3

package/README.md

@@ -56,12 +56,23 @@ Create `x-openapi-flow.config.json` in your project directory:
 - OpenAPI input in `.yaml`, `.yml`, and `.json`
 - Validation processes OAS content with the `x-openapi-flow` extension
 
+### Optional Transition Guidance Fields
+
+- `next_operation_id`: operationId usually called for the next state transition
+- `prerequisite_operation_ids`: operationIds expected before a transition
+
 ## 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`.
 
+## Graph Output Example
+
+`x-openapi-flow graph` includes transition guidance labels in Mermaid output when present (`next_operation_id`, `prerequisite_operation_ids`).
+
+![Guided graph example](../docs/assets/graph-order-guided.svg)
+
 ## Repository and Full Documentation
 
 - Repository: https://github.com/tiago-marques/x-openapi-flow

package/bin/x-openapi-flow.js

@@ -8,7 +8,6 @@ const {
   run,
   loadApi,
   extractFlows,
-  buildStateGraph,
 } = require("../lib/validator");
 
 const DEFAULT_CONFIG_NAME = "x-openapi-flow.config.json";
@@ -702,25 +701,61 @@ function runDoctor(parsed) {
 function buildMermaidGraph(filePath) {
   const api = loadApi(filePath);
   const flows = extractFlows(api);
-  const graph = buildStateGraph(flows);
   const lines = ["stateDiagram-v2"];
+  const nodes = new Set();
+  const edges = [];
+  const edgeSeen = new Set();
+
+  for (const { flow } of flows) {
+    nodes.add(flow.current_state);
+
+    const transitions = flow.transitions || [];
+    for (const transition of transitions) {
+      const from = flow.current_state;
+      const to = transition.target_state;
+      if (!to) {
+        continue;
+      }
 
-  for (const state of graph.nodes) {
-    lines.push(`  state ${state}`);
-  }
+      nodes.add(to);
 
-  for (const [from, targets] of graph.adjacency.entries()) {
-    for (const to of targets) {
-      lines.push(`  ${from} --> ${to}`);
+      const labelParts = [];
+      if (transition.next_operation_id) {
+        labelParts.push(`next:${transition.next_operation_id}`);
+      }
+      if (
+        Array.isArray(transition.prerequisite_operation_ids) &&
+        transition.prerequisite_operation_ids.length > 0
+      ) {
+        labelParts.push(`requires:${transition.prerequisite_operation_ids.join(",")}`);
+      }
+
+      const label = labelParts.join(" | ");
+      const edgeKey = `${from}::${to}::${label}`;
+      if (edgeSeen.has(edgeKey)) {
+        continue;
+      }
+
+      edgeSeen.add(edgeKey);
+      edges.push({
+        from,
+        to,
+        next_operation_id: transition.next_operation_id,
+        prerequisite_operation_ids: transition.prerequisite_operation_ids || [],
+      });
+
+      lines.push(`  ${from} --> ${to}${label ? `: ${label}` : ""}`);
     }
   }
 
+  for (const state of nodes) {
+    lines.splice(1, 0, `  state ${state}`);
+  }
+
   return {
     flowCount: flows.length,
-    nodes: [...graph.nodes],
-    edges: [...graph.adjacency.entries()].flatMap(([from, targets]) =>
-      [...targets].map((to) => ({ from, to }))
-    ),
+    nodes: [...nodes],
+    edges,
     mermaid: lines.join("\n"),
   };
 }

package/examples/order-api.yaml

@@ -19,9 +19,11 @@ paths:
           - target_state: CONFIRMED
             condition: Stock and payment checks pass.
             trigger_type: synchronous
+            next_operation_id: confirmOrder
           - target_state: CANCELLED
             condition: Validation fails before confirmation.
             trigger_type: synchronous
+            next_operation_id: cancelOrder
       responses:
         "201":
           description: Order created successfully.
@@ -39,6 +41,9 @@ paths:
           - target_state: SHIPPED
             condition: Warehouse dispatches package.
             trigger_type: webhook
+            next_operation_id: shipOrder
+            prerequisite_operation_ids:
+              - createOrder
       parameters:
         - name: id
           in: path
@@ -62,6 +67,9 @@ paths:
           - target_state: DELIVERED
             condition: Carrier confirms delivery.
             trigger_type: webhook
+            next_operation_id: deliverOrder
+            prerequisite_operation_ids:
+              - confirmOrder
       parameters:
         - name: id
           in: path

package/lib/validator.js

@@ -40,7 +40,7 @@ function loadApi(filePath) {
 /**
  * Extract every x-openapi-flow object found in the `paths` section of an OAS document.
  * @param {object} api - Parsed OAS document.
- * @returns {{ endpoint: string, flow: object }[]}
+ * @returns {{ endpoint: string, operation_id?: string, flow: object }[]}
  */
 function extractFlows(api) {
   const entries = [];
@@ -62,6 +62,7 @@ function extractFlows(api) {
       if (operation && operation["x-openapi-flow"]) {
         entries.push({
           endpoint: `${method.toUpperCase()} ${pathKey}`,
+          operation_id: operation.operationId,
           flow: operation["x-openapi-flow"],
         });
       }
@@ -147,11 +148,55 @@ function defaultResult(pathValue, ok = true) {
       multiple_initial_states: [],
       duplicate_transitions: [],
       non_terminating_states: [],
+      invalid_operation_references: [],
       warnings: [],
     },
   };
 }
 
+/**
+ * Detect invalid operationId references declared in transitions.
+ * @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)
+  );
+
+  const invalidReferences = [];
+
+  for (const { endpoint, flow } of flows) {
+    const transitions = flow.transitions || [];
+
+    for (const transition of transitions) {
+      if (transition.next_operation_id && !knownOperationIds.has(transition.next_operation_id)) {
+        invalidReferences.push({
+          type: "next_operation_id",
+          operation_id: transition.next_operation_id,
+          declared_in: endpoint,
+        });
+      }
+
+      const prerequisites = Array.isArray(transition.prerequisite_operation_ids)
+        ? transition.prerequisite_operation_ids
+        : [];
+
+      for (const prerequisiteOperationId of prerequisites) {
+        if (!knownOperationIds.has(prerequisiteOperationId)) {
+          invalidReferences.push({
+            type: "prerequisite_operation_ids",
+            operation_id: prerequisiteOperationId,
+            declared_in: endpoint,
+          });
+        }
+      }
+    }
+  }
+
+  return invalidReferences;
+}
+
 /**
  * Verify that every target_state referenced in transitions corresponds to a
  * current_state defined in at least one endpoint of the same API.
@@ -554,6 +599,7 @@ function run(apiPath, options = {}) {
   const cycle = detectCycle(graph);
   const duplicateTransitions = detectDuplicateTransitions(flows);
   const terminalCoverage = detectTerminalCoverage(graph);
+  const invalidOperationReferences = detectInvalidOperationReferences(flows);
   const multipleInitialStates = initialStates.length > 1 ? initialStates : [];
 
   if (profileConfig.runAdvanced) {
@@ -590,6 +636,15 @@ function run(apiPath, options = {}) {
     );
   }
 
+  if (profileConfig.runQuality && invalidOperationReferences.length > 0) {
+    const invalidOperationIds = [
+      ...new Set(invalidOperationReferences.map((item) => item.operation_id)),
+    ];
+    qualityWarnings.push(
+      `Transition operation references not found: ${invalidOperationIds.join(", ")}`
+    );
+  }
+
   if (strictQuality && qualityWarnings.length > 0) {
     hasErrors = true;
   }
@@ -678,6 +733,7 @@ function run(apiPath, options = {}) {
       multiple_initial_states: multipleInitialStates,
       duplicate_transitions: duplicateTransitions,
       non_terminating_states: terminalCoverage.non_terminating_states,
+      invalid_operation_references: invalidOperationReferences,
       warnings: qualityWarnings,
     },
   };

package/package.json

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

package/schema/flow-schema.json

@@ -58,6 +58,17 @@
             "type": "string",
             "enum": ["synchronous", "webhook", "polling"],
             "description": "Mechanism that triggers the state transition."
+          },
+          "next_operation_id": {
+            "type": "string",
+            "description": "operationId usually called to apply the next state transition."
+          },
+          "prerequisite_operation_ids": {
+            "type": "array",
+            "description": "operationIds that are expected to have happened before this transition.",
+            "items": {
+              "type": "string"
+            }
           }
         },
         "additionalProperties": false