x-openapi-flow 1.1.1 → 1.1.3

package/README.md

@@ -1,6 +1,6 @@
 # x-openapi-flow
 
-CLI and specification for validating the `x-flow` extension field in OpenAPI documents.
+CLI and specification for validating the `x-openapi-flow` extension field in OpenAPI documents.
 
 ## Installation
 
@@ -20,11 +20,25 @@ x-openapi-flow doctor
 
 ```bash
 x-openapi-flow validate <openapi-file> [--format pretty|json] [--profile core|relaxed|strict] [--strict-quality] [--config path]
-x-openapi-flow init [output-file] [--title "My API"]
+x-openapi-flow init [openapi-file] [--flows path]
+x-openapi-flow apply [openapi-file] [--flows path] [--out path]
 x-openapi-flow graph <openapi-file> [--format mermaid|json]
 x-openapi-flow doctor [--config path]
 ```
 
+`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.
+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
+
+```bash
+x-openapi-flow init openapi.yaml
+# edit x-openapi-flow.flows.yaml
+x-openapi-flow apply openapi.yaml
+```
+
 ## Optional Configuration
 
 Create `x-openapi-flow.config.json` in your project directory:
@@ -40,7 +54,24 @@ Create `x-openapi-flow.config.json` in your project directory:
 ## File Compatibility
 
 - OpenAPI input in `.yaml`, `.yml`, and `.json`
-- Validation processes OAS content with the `x-flow` extension
+- 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
 

package/bin/x-openapi-flow.js

@@ -3,14 +3,15 @@
 
 const fs = require("fs");
 const path = require("path");
+const yaml = require("js-yaml");
 const {
   run,
   loadApi,
   extractFlows,
-  buildStateGraph,
 } = require("../lib/validator");
 
 const DEFAULT_CONFIG_NAME = "x-openapi-flow.config.json";
+const DEFAULT_FLOWS_FILE = "x-openapi-flow.flows.yaml";
 
 function resolveConfigPath(configPathArg) {
   return configPathArg
@@ -42,7 +43,8 @@ function printHelp() {
 
 Usage:
   x-openapi-flow validate <openapi-file> [--format pretty|json] [--profile core|relaxed|strict] [--strict-quality] [--config path]
-  x-openapi-flow init [output-file] [--title "My API"]
+  x-openapi-flow init [openapi-file] [--flows path]
+  x-openapi-flow apply [openapi-file] [--flows path] [--out path]
   x-openapi-flow graph <openapi-file> [--format mermaid|json]
   x-openapi-flow doctor [--config path]
   x-openapi-flow --help
@@ -51,7 +53,10 @@ 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 my-api.yaml --title "Orders API"
+  x-openapi-flow init openapi.yaml --flows x-openapi-flow.flows.yaml
+  x-openapi-flow init
+  x-openapi-flow apply openapi.yaml
+  x-openapi-flow apply openapi.yaml --out openapi.flow.yaml
   x-openapi-flow graph examples/order-api.yaml
   x-openapi-flow doctor
 `);
@@ -163,21 +168,21 @@ function parseValidateArgs(args) {
 }
 
 function parseInitArgs(args) {
-  const unknown = findUnknownOptions(args, ["--title"], []);
+  const unknown = findUnknownOptions(args, ["--flows"], []);
   if (unknown) {
     return { error: `Unknown option: ${unknown}` };
   }
 
-  const titleOpt = getOptionValue(args, "--title");
-  if (titleOpt.error) {
-    return { error: titleOpt.error };
+  const flowsOpt = getOptionValue(args, "--flows");
+  if (flowsOpt.error) {
+    return { error: flowsOpt.error };
   }
 
   const positional = args.filter((token, index) => {
-    if (token === "--title") {
+    if (token === "--flows") {
       return false;
     }
-    if (index > 0 && args[index - 1] === "--title") {
+    if (index > 0 && args[index - 1] === "--flows") {
       return false;
     }
     return !token.startsWith("--");
@@ -188,8 +193,45 @@ function parseInitArgs(args) {
   }
 
   return {
-    outputFile: path.resolve(positional[0] || "x-flow-api.yaml"),
-    title: titleOpt.found ? titleOpt.value : "Sample API",
+    openApiFile: positional[0] ? path.resolve(positional[0]) : undefined,
+    flowsPath: flowsOpt.found ? path.resolve(flowsOpt.value) : undefined,
+  };
+}
+
+function parseApplyArgs(args) {
+  const unknown = findUnknownOptions(args, ["--flows", "--out"], []);
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
+  }
+
+  const flowsOpt = getOptionValue(args, "--flows");
+  if (flowsOpt.error) {
+    return { error: flowsOpt.error };
+  }
+
+  const outOpt = getOptionValue(args, "--out");
+  if (outOpt.error) {
+    return { error: outOpt.error };
+  }
+
+  const positional = args.filter((token, index) => {
+    if (token === "--flows" || token === "--out") {
+      return false;
+    }
+    if (index > 0 && (args[index - 1] === "--flows" || args[index - 1] === "--out")) {
+      return false;
+    }
+    return !token.startsWith("--");
+  });
+
+  if (positional.length > 1) {
+    return { error: `Unexpected argument: ${positional[1]}` };
+  }
+
+  return {
+    openApiFile: positional[0] ? path.resolve(positional[0]) : undefined,
+    flowsPath: flowsOpt.found ? path.resolve(flowsOpt.value) : undefined,
+    outPath: outOpt.found ? path.resolve(outOpt.value) : undefined,
   };
 }
 
@@ -274,6 +316,11 @@ function parseArgs(argv) {
     return parsed.error ? parsed : { command, ...parsed };
   }
 
+  if (command === "apply") {
+    const parsed = parseApplyArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
   if (command === "doctor") {
     const parsed = parseDoctorArgs(commandArgs);
     return parsed.error ? parsed : { command, ...parsed };
@@ -282,51 +329,330 @@ function parseArgs(argv) {
   return { error: `Unknown command: ${command}` };
 }
 
-function buildTemplate(title) {
-  return `openapi: "3.0.3"
-info:
-  title: ${title}
-  version: "1.0.0"
-paths:
-  /resources:
-    post:
-      summary: Create resource
-      operationId: createResource
-      x-flow:
-        version: "1.0"
-        id: create-resource-flow
-        current_state: CREATED
-        transitions:
-          - target_state: COMPLETED
-            condition: Resource reaches terminal condition.
-            trigger_type: synchronous
-      responses:
-        "201":
-          description: Resource created.
-
-  /resources/{id}/complete:
-    post:
-      summary: Complete resource
-      operationId: completeResource
-      x-flow:
-        version: "1.0"
-        id: complete-resource-flow
-        current_state: COMPLETED
-      responses:
-        "200":
-          description: Resource completed.
-`;
+function findOpenApiFile(startDirectory) {
+  const preferredNames = [
+    "openapi.yaml",
+    "openapi.yml",
+    "openapi.json",
+    "swagger.yaml",
+    "swagger.yml",
+    "swagger.json",
+  ];
+
+  for (const fileName of preferredNames) {
+    const candidate = path.join(startDirectory, fileName);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  const ignoredDirs = new Set(["node_modules", ".git", "dist", "build"]);
+
+  function walk(directory) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch (_err) {
+      return null;
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(directory, entry.name);
+
+      if (entry.isDirectory()) {
+        if (!ignoredDirs.has(entry.name)) {
+          const nested = walk(fullPath);
+          if (nested) {
+            return nested;
+          }
+        }
+        continue;
+      }
+
+      if (preferredNames.includes(entry.name)) {
+        return fullPath;
+      }
+    }
+
+    return null;
+  }
+
+  return walk(startDirectory);
+}
+
+function resolveFlowsPath(openApiFile, customFlowsPath) {
+  if (customFlowsPath) {
+    return customFlowsPath;
+  }
+
+  if (openApiFile) {
+    return path.join(path.dirname(openApiFile), DEFAULT_FLOWS_FILE);
+  }
+
+  return path.resolve(process.cwd(), DEFAULT_FLOWS_FILE);
+}
+
+function getOpenApiFormat(filePath) {
+  return filePath.endsWith(".json") ? "json" : "yaml";
+}
+
+function saveOpenApi(filePath, api) {
+  const format = getOpenApiFormat(filePath);
+  const content = format === "json"
+    ? JSON.stringify(api, null, 2) + "\n"
+    : yaml.dump(api, { noRefs: true, lineWidth: -1 });
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+function extractOperationEntries(api) {
+  const entries = [];
+  const paths = (api && api.paths) || {};
+  const httpMethods = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+
+  for (const [pathKey, pathItem] of Object.entries(paths)) {
+    for (const method of httpMethods) {
+      const operation = pathItem[method];
+      if (!operation) {
+        continue;
+      }
+
+      const operationId = operation.operationId;
+      const key = operationId ? `operationId:${operationId}` : `${method.toUpperCase()} ${pathKey}`;
+
+      entries.push({
+        key,
+        operationId,
+        method,
+        path: pathKey,
+      });
+    }
+  }
+
+  return entries;
+}
+
+function readFlowsFile(flowsPath) {
+  if (!fs.existsSync(flowsPath)) {
+    return {
+      version: "1.0",
+      operations: [],
+    };
+  }
+
+  const content = fs.readFileSync(flowsPath, "utf8");
+  const parsed = yaml.load(content);
+
+  if (!parsed || typeof parsed !== "object") {
+    return { version: "1.0", operations: [] };
+  }
+
+  return {
+    version: parsed.version || "1.0",
+    operations: Array.isArray(parsed.operations) ? parsed.operations : [],
+  };
+}
+
+function writeFlowsFile(flowsPath, flowsDoc) {
+  fs.mkdirSync(path.dirname(flowsPath), { recursive: true });
+  const content = yaml.dump(flowsDoc, { noRefs: true, lineWidth: -1 });
+  fs.writeFileSync(flowsPath, content, "utf8");
+}
+
+function buildOperationLookup(api) {
+  const lookupByKey = new Map();
+  const lookupByOperationId = new Map();
+  const entries = extractOperationEntries(api);
+
+  for (const entry of entries) {
+    lookupByKey.set(entry.key, entry);
+    if (entry.operationId) {
+      lookupByOperationId.set(entry.operationId, entry);
+    }
+  }
+
+  return { entries, lookupByKey, lookupByOperationId };
+}
+
+function mergeFlowsWithOpenApi(api, flowsDoc) {
+  const { entries, lookupByKey, lookupByOperationId } = buildOperationLookup(api);
+
+  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);
+    }
+  }
+
+  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,
+      });
+    }
+  }
+
+  for (const existing of flowsDoc.operations) {
+    const existingKey = existing.key || (existing.operationId ? `operationId:${existing.operationId}` : null);
+    const found = existingKey && lookupByKey.has(existingKey);
+
+    if (!found) {
+      mergedOperations.push({
+        ...existing,
+        missing_in_openapi: true,
+      });
+    }
+  }
+
+  return {
+    version: "1.0",
+    operations: mergedOperations,
+  };
+}
+
+function applyFlowsToOpenApi(api, flowsDoc) {
+  const paths = (api && api.paths) || {};
+  let appliedCount = 0;
+  const { lookupByKey, lookupByOperationId } = buildOperationLookup(api);
+
+  for (const flowEntry of flowsDoc.operations || []) {
+    if (!flowEntry || flowEntry.missing_in_openapi === true) {
+      continue;
+    }
+
+    const flowValue = flowEntry["x-openapi-flow"];
+    if (!flowValue || typeof flowValue !== "object") {
+      continue;
+    }
+
+    let target = null;
+    if (flowEntry.operationId && lookupByOperationId.has(flowEntry.operationId)) {
+      target = lookupByOperationId.get(flowEntry.operationId);
+    } else if (flowEntry.key && lookupByKey.has(flowEntry.key)) {
+      target = lookupByKey.get(flowEntry.key);
+    }
+
+    if (!target) {
+      continue;
+    }
+
+    const pathItem = paths[target.path];
+    if (pathItem && pathItem[target.method]) {
+      pathItem[target.method]["x-openapi-flow"] = flowValue;
+      appliedCount += 1;
+    }
+  }
+
+  return appliedCount;
 }
 
 function runInit(parsed) {
-  if (fs.existsSync(parsed.outputFile)) {
-    console.error(`ERROR: File already exists: ${parsed.outputFile}`);
+  const targetOpenApiFile = parsed.openApiFile || findOpenApiFile(process.cwd());
+
+  if (!targetOpenApiFile) {
+    console.error("ERROR: Could not find an existing OpenAPI file in this repository.");
+    console.error("Expected one of: openapi.yaml|yml|json, swagger.yaml|yml|json");
+    console.error("Create your OpenAPI/Swagger spec first (using your framework's official generator), then run init again.");
+    return 1;
+  }
+
+  const flowsPath = resolveFlowsPath(targetOpenApiFile, parsed.flowsPath);
+
+  let api;
+  try {
+    api = loadApi(targetOpenApiFile);
+  } catch (err) {
+    console.error(`ERROR: Could not parse OpenAPI file — ${err.message}`);
+    return 1;
+  }
+
+  let flowsDoc;
+  try {
+    flowsDoc = readFlowsFile(flowsPath);
+  } catch (err) {
+    console.error(`ERROR: Could not parse flows file — ${err.message}`);
     return 1;
   }
 
-  fs.writeFileSync(parsed.outputFile, buildTemplate(parsed.title), "utf8");
-  console.log(`Template created: ${parsed.outputFile}`);
-  console.log(`Next step: x-openapi-flow validate ${parsed.outputFile}`);
+  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;
+
+  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(`Validate now: x-openapi-flow validate ${targetOpenApiFile}`);
+  return 0;
+}
+
+function runApply(parsed) {
+  const targetOpenApiFile = parsed.openApiFile || findOpenApiFile(process.cwd());
+
+  if (!targetOpenApiFile) {
+    console.error("ERROR: Could not find an existing OpenAPI file in this repository.");
+    console.error("Expected one of: openapi.yaml|yml|json, swagger.yaml|yml|json");
+    return 1;
+  }
+
+  const flowsPath = resolveFlowsPath(targetOpenApiFile, parsed.flowsPath);
+  if (!fs.existsSync(flowsPath)) {
+    console.error(`ERROR: Flows sidecar not found: ${flowsPath}`);
+    console.error("Run `x-openapi-flow init` first to create and sync the sidecar.");
+    return 1;
+  }
+
+  let api;
+  let flowsDoc;
+  try {
+    api = loadApi(targetOpenApiFile);
+  } catch (err) {
+    console.error(`ERROR: Could not parse OpenAPI file — ${err.message}`);
+    return 1;
+  }
+
+  try {
+    flowsDoc = readFlowsFile(flowsPath);
+  } catch (err) {
+    console.error(`ERROR: Could not parse flows file — ${err.message}`);
+    return 1;
+  }
+
+  const appliedCount = applyFlowsToOpenApi(api, flowsDoc);
+  const outputPath = parsed.outPath || targetOpenApiFile;
+  saveOpenApi(outputPath, api);
+
+  console.log(`OpenAPI source: ${targetOpenApiFile}`);
+  console.log(`Flows sidecar: ${flowsPath}`);
+  console.log(`Applied x-openapi-flow entries: ${appliedCount}`);
+  console.log(`Output written to: ${outputPath}`);
   return 0;
 }
 
@@ -375,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"];
-
-  for (const state of graph.nodes) {
-    lines.push(`  state ${state}`);
+  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;
+      }
+
+      nodes.add(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 [from, targets] of graph.adjacency.entries()) {
-    for (const to of targets) {
-      lines.push(`  ${from} --> ${to}`);
-    }
+  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"),
   };
 }
@@ -440,6 +802,10 @@ function main() {
     process.exit(runGraph(parsed));
   }
 
+  if (parsed.command === "apply") {
+    process.exit(runApply(parsed));
+  }
+
   const config = loadConfig(parsed.configPath);
   if (config.error) {
     console.error(`ERROR: ${config.error}`);

package/examples/non-terminating-api.yaml

@@ -10,7 +10,7 @@ paths:
     post:
       summary: Start flow
       operationId: startFlow
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: start-flow
         current_state: START
@@ -29,7 +29,7 @@ paths:
     post:
       summary: Loop A
       operationId: loopA
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: loop-a-flow
         current_state: LOOP_A
@@ -45,7 +45,7 @@ paths:
     post:
       summary: Loop B
       operationId: loopB
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: loop-b-flow
         current_state: LOOP_B
@@ -61,7 +61,7 @@ paths:
     post:
       summary: Done
       operationId: doneFlow
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: done-flow
         current_state: DONE

package/examples/order-api.yaml

@@ -3,14 +3,14 @@ info:
   title: Order API
   version: "1.0.0"
   description: >
-    Example API demonstrating x-flow for order lifecycle orchestration.
+    Example API demonstrating x-openapi-flow for order lifecycle orchestration.
 
 paths:
   /orders:
     post:
       summary: Create a new order
       operationId: createOrder
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: create-order-flow
         current_state: CREATED
@@ -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.
@@ -30,7 +32,7 @@ paths:
     post:
       summary: Confirm an order
       operationId: confirmOrder
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: confirm-order-flow
         current_state: CONFIRMED
@@ -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
@@ -53,7 +58,7 @@ paths:
     post:
       summary: Mark order as shipped
       operationId: shipOrder
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: ship-order-flow
         current_state: SHIPPED
@@ -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
@@ -76,7 +84,7 @@ paths:
     post:
       summary: Mark order as delivered
       operationId: deliverOrder
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: deliver-order-flow
         current_state: DELIVERED
@@ -95,7 +103,7 @@ paths:
     post:
       summary: Cancel an order
       operationId: cancelOrder
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: cancel-order-flow
         current_state: CANCELLED

package/examples/payment-api.yaml

@@ -3,14 +3,14 @@ info:
   title: Payment API
   version: "1.0.0"
   description: >
-    Simple payment API demonstrating the x-flow extension for OpenAPI Spec.
+    Simple payment API demonstrating the x-openapi-flow extension for OpenAPI Spec.
 
 paths:
   /payments:
     post:
       summary: Create and authorize a payment
       operationId: createPayment
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: create-payment-flow
         current_state: AUTHORIZED
@@ -44,7 +44,7 @@ paths:
     post:
       summary: Capture an authorized payment
       operationId: capturePayment
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: capture-payment-flow
         current_state: CAPTURED

package/examples/quality-warning-api.yaml

@@ -10,7 +10,7 @@ paths:
     post:
       summary: Start flow A
       operationId: startA
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: start-a-flow
         current_state: A_START
@@ -29,7 +29,7 @@ paths:
     post:
       summary: Complete flow A
       operationId: doneA
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: done-a-flow
         current_state: A_DONE
@@ -41,7 +41,7 @@ paths:
     post:
       summary: Start flow B
       operationId: startB
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: start-b-flow
         current_state: B_START
@@ -57,7 +57,7 @@ paths:
     post:
       summary: Complete flow B
       operationId: doneB
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: done-b-flow
         current_state: B_DONE

package/examples/swagger-ui/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>x-openapi-flow + Swagger UI</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+    <style>
+      body { margin: 0; }
+      #swagger-ui { max-width: 1200px; margin: 0 auto; }
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+
+    <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 src="./x-openapi-flow-plugin.js"></script>
+    <script>
+      window.ui = SwaggerUIBundle({
+        url: "../payment-api.yaml",
+        dom_id: "#swagger-ui",
+        deepLinking: true,
+        presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+        plugins: [window.XOpenApiFlowPlugin],
+        showExtensions: true,
+      });
+    </script>
+  </body>
+</html>

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

@@ -0,0 +1,46 @@
+window.XOpenApiFlowPlugin = function () {
+  return {
+    wrapComponents: {
+      OperationSummary: (Original, system) => (props) => {
+        const operation = props.operation;
+        const flow = operation && operation.get && operation.get("x-openapi-flow");
+
+        if (!flow) {
+          return React.createElement(Original, props);
+        }
+
+        const flowObject = flow && flow.toJS ? flow.toJS() : flow;
+        const currentState = flowObject.current_state || "-";
+        const version = flowObject.version || "-";
+
+        return React.createElement(
+          "div",
+          null,
+          React.createElement(Original, props),
+          React.createElement(
+            "div",
+            {
+              style: {
+                marginTop: "8px",
+                padding: "8px 10px",
+                border: "1px solid #d9d9d9",
+                borderRadius: "6px",
+                background: "#fafafa",
+                fontSize: "12px",
+              },
+            },
+            React.createElement("strong", null, "x-openapi-flow"),
+            React.createElement(
+              "div",
+              { style: { marginTop: "4px" } },
+              "version: ",
+              version,
+              " | current_state: ",
+              currentState
+            )
+          )
+        );
+      },
+    },
+  };
+};

package/examples/ticket-api.yaml

@@ -3,14 +3,14 @@ info:
   title: Support Ticket API
   version: "1.0.0"
   description: >
-    Example API demonstrating x-flow for support ticket lifecycle.
+    Example API demonstrating x-openapi-flow for support ticket lifecycle.
 
 paths:
   /tickets:
     post:
       summary: Open a support ticket
       operationId: openTicket
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: open-ticket-flow
         current_state: OPEN
@@ -27,7 +27,7 @@ paths:
     post:
       summary: Start ticket handling
       operationId: startTicket
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: start-ticket-flow
         current_state: IN_PROGRESS
@@ -53,7 +53,7 @@ paths:
     post:
       summary: Wait for customer response
       operationId: waitCustomer
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: wait-customer-flow
         current_state: WAITING_CUSTOMER
@@ -76,7 +76,7 @@ paths:
     post:
       summary: Resolve ticket
       operationId: resolveTicket
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: resolve-ticket-flow
         current_state: RESOLVED
@@ -99,7 +99,7 @@ paths:
     post:
       summary: Close ticket
       operationId: closeTicket
-      x-flow:
+      x-openapi-flow:
         version: "1.0"
         id: close-ticket-flow
         current_state: CLOSED

package/lib/validator.js

@@ -38,9 +38,9 @@ function loadApi(filePath) {
 }
 
 /**
- * Extract every x-flow object found in the `paths` section of an OAS document.
+ * 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 = [];
@@ -59,10 +59,11 @@ function extractFlows(api) {
     ];
     for (const method of HTTP_METHODS) {
       const operation = pathItem[method];
-      if (operation && operation["x-flow"]) {
+      if (operation && operation["x-openapi-flow"]) {
         entries.push({
           endpoint: `${method.toUpperCase()} ${pathKey}`,
-          flow: operation["x-flow"],
+          operation_id: operation.operationId,
+          flow: operation["x-openapi-flow"],
         });
       }
     }
@@ -76,7 +77,7 @@ function extractFlows(api) {
 // ---------------------------------------------------------------------------
 
 /**
- * Validate all x-flow objects against the JSON Schema.
+ * Validate all x-openapi-flow objects against the JSON Schema.
  * @param {{ endpoint: string, flow: object }[]} flows
  * @returns {{ endpoint: string, errors: object[] }[]} Array of validation failures.
  */
@@ -105,23 +106,23 @@ function suggestFixes(errors = []) {
     if (err.keyword === "required" && err.params && err.params.missingProperty) {
       const missing = err.params.missingProperty;
       if (missing === "version") {
-        suggestions.add("Add `version: \"1.0\"` to the x-flow object.");
+        suggestions.add("Add `version: \"1.0\"` to the x-openapi-flow object.");
       } else if (missing === "id") {
-        suggestions.add("Add a unique `id` to the x-flow object.");
+        suggestions.add("Add a unique `id` to the x-openapi-flow object.");
       } else if (missing === "current_state") {
         suggestions.add("Add `current_state` to describe the operation state.");
       } else {
-        suggestions.add(`Add required property \`${missing}\` in x-flow.`);
+        suggestions.add(`Add required property \`${missing}\` in x-openapi-flow.`);
       }
     }
 
     if (err.keyword === "enum" && err.instancePath.endsWith("/version")) {
-      suggestions.add("Use supported x-flow version: `\"1.0\"`.");
+      suggestions.add("Use supported x-openapi-flow version: `\"1.0\"`.");
     }
 
     if (err.keyword === "additionalProperties" && err.params && err.params.additionalProperty) {
       suggestions.add(
-        `Remove unsupported property \`${err.params.additionalProperty}\` from x-flow payload.`
+        `Remove unsupported property \`${err.params.additionalProperty}\` from x-openapi-flow payload.`
       );
     }
   }
@@ -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.
@@ -474,7 +519,7 @@ function run(apiPath, options = {}) {
     return result;
   }
 
-  // 2. Extract x-flow objects
+  // 2. Extract x-openapi-flow objects
   const flows = extractFlows(api);
 
   if (flows.length === 0) {
@@ -484,14 +529,14 @@ function run(apiPath, options = {}) {
     if (output === "json") {
       console.log(JSON.stringify(result, null, 2));
     } else {
-      console.warn("WARNING: No x-flow extensions found in the API paths.");
+      console.warn("WARNING: No x-openapi-flow extensions found in the API paths.");
     }
 
     return result;
   }
 
   if (output === "pretty") {
-    console.log(`Found ${flows.length} x-flow definition(s).\n`);
+    console.log(`Found ${flows.length} x-openapi-flow definition(s).\n`);
   }
 
   let hasErrors = false;
@@ -504,7 +549,7 @@ function run(apiPath, options = {}) {
 
   if (output === "pretty") {
     if (schemaFailures.length === 0) {
-      console.log("✔  Schema validation passed for all x-flow definitions.");
+      console.log("✔  Schema validation passed for all x-openapi-flow definitions.");
     } else {
       console.error("✘  Schema validation FAILED:");
       for (const { endpoint, errors } of schemaFailures) {
@@ -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.1",
+  "version": "1.1.3",
   "description": "OpenAPI extension for resource workflow and lifecycle management",
   "main": "lib/validator.js",
   "repository": {
@@ -39,7 +39,7 @@
     "openapi-flow",
     "workflow",
     "lifecycle",
-    "x-flow"
+    "x-openapi-flow"
   ],
   "license": "MIT",
   "dependencies": {

package/schema/flow-schema.json

@@ -1,15 +1,15 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://x-flow.dev/schema/flow-schema.json",
-  "title": "x-flow",
-  "description": "JSON Schema for the x-flow OpenAPI extension, defining resource lifecycle states and transitions.",
+  "$id": "https://x-openapi-flow.dev/schema/flow-schema.json",
+  "title": "x-openapi-flow",
+  "description": "JSON Schema for the x-openapi-flow OpenAPI extension, defining resource lifecycle states and transitions.",
   "type": "object",
   "required": ["version", "id", "current_state"],
   "properties": {
     "version": {
       "type": "string",
       "enum": ["1.0"],
-      "description": "Version of the x-flow schema contract used by this definition."
+      "description": "Version of the x-openapi-flow schema contract used by this definition."
     },
     "id": {
       "type": "string",
@@ -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