x-openapi-flow 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @metiagomarques
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# x-openapi-flow
+
+CLI and specification for validating the `x-flow` extension field in OpenAPI documents.
+
+## Installation
+
+```bash
+npm install x-openapi-flow
+```
+
+## Quick Usage
+
+```bash
+x-openapi-flow validate openapi.yaml
+x-openapi-flow graph openapi.yaml
+x-openapi-flow doctor
+```
+
+## Commands
+
+```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 graph <openapi-file> [--format mermaid|json]
+x-openapi-flow doctor [--config path]
+```
+
+## Optional Configuration
+
+Create `x-openapi-flow.config.json` in your project directory:
+
+```json
+{
+  "profile": "strict",
+  "format": "pretty",
+  "strictQuality": false
+}
+```
+
+## File Compatibility
+
+- OpenAPI input in `.yaml`, `.yml`, and `.json`
+- Validation processes OAS content with the `x-flow` extension
+
+## Repository and Full 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

@@ -0,0 +1,461 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  run,
+  loadApi,
+  extractFlows,
+  buildStateGraph,
+} = require("../lib/validator");
+
+const DEFAULT_CONFIG_NAME = "x-openapi-flow.config.json";
+
+function resolveConfigPath(configPathArg) {
+  return configPathArg
+    ? path.resolve(configPathArg)
+    : path.resolve(process.cwd(), DEFAULT_CONFIG_NAME);
+}
+
+function loadConfig(configPathArg) {
+  const configPath = resolveConfigPath(configPathArg);
+  if (!fs.existsSync(configPath)) {
+    return { path: configPath, exists: false, data: {} };
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    return { path: configPath, exists: true, data: parsed };
+  } catch (err) {
+    return {
+      path: configPath,
+      exists: true,
+      error: `Could not parse config file: ${err.message}`,
+      data: {},
+    };
+  }
+}
+
+function printHelp() {
+  console.log(`x-openapi-flow CLI
+
+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 graph <openapi-file> [--format mermaid|json]
+  x-openapi-flow doctor [--config path]
+  x-openapi-flow --help
+
+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 graph examples/order-api.yaml
+  x-openapi-flow doctor
+`);
+}
+
+function getOptionValue(args, optionName) {
+  const index = args.indexOf(optionName);
+  if (index === -1) {
+    return { found: false };
+  }
+
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) {
+    return { found: true, error: `Missing value for ${optionName}.` };
+  }
+
+  return { found: true, value, index };
+}
+
+function findUnknownOptions(args, knownOptionsWithValue, knownFlags) {
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token.startsWith("--")) {
+      continue;
+    }
+
+    if (knownFlags.includes(token)) {
+      continue;
+    }
+
+    if (knownOptionsWithValue.includes(token)) {
+      index += 1;
+      continue;
+    }
+
+    return token;
+  }
+
+  return null;
+}
+
+function parseValidateArgs(args) {
+  const unknown = findUnknownOptions(
+    args,
+    ["--format", "--profile", "--config"],
+    ["--strict-quality"]
+  );
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
+  }
+
+  const formatOpt = getOptionValue(args, "--format");
+  if (formatOpt.error) {
+    return { error: `${formatOpt.error} Use 'pretty' or 'json'.` };
+  }
+
+  const profileOpt = getOptionValue(args, "--profile");
+  if (profileOpt.error) {
+    return { error: `${profileOpt.error} Use 'core', 'relaxed', or 'strict'.` };
+  }
+
+  const configOpt = getOptionValue(args, "--config");
+  if (configOpt.error) {
+    return { error: configOpt.error };
+  }
+
+  const strictQuality = args.includes("--strict-quality");
+  const format = formatOpt.found ? formatOpt.value : undefined;
+  const profile = profileOpt.found ? profileOpt.value : undefined;
+
+  if (format && !["pretty", "json"].includes(format)) {
+    return { error: `Invalid --format '${format}'. Use 'pretty' or 'json'.` };
+  }
+
+  if (profile && !["core", "relaxed", "strict"].includes(profile)) {
+    return { error: `Invalid --profile '${profile}'. Use 'core', 'relaxed', or 'strict'.` };
+  }
+
+  const positional = args.filter((token, index) => {
+    if (["--format", "--profile", "--config"].includes(token)) {
+      return false;
+    }
+
+    if (
+      index > 0 &&
+      ["--format", "--profile", "--config"].includes(args[index - 1])
+    ) {
+      return false;
+    }
+
+    return !token.startsWith("--") || token === "-";
+  });
+
+  if (positional.length === 0) {
+    return { error: "Missing OpenAPI file path. Usage: x-openapi-flow validate <openapi-file>" };
+  }
+
+  if (positional.length > 1) {
+    return { error: `Unexpected argument: ${positional[1]}` };
+  }
+
+  return {
+    filePath: path.resolve(positional[0]),
+    strictQuality,
+    format,
+    profile,
+    configPath: configOpt.found ? configOpt.value : undefined,
+  };
+}
+
+function parseInitArgs(args) {
+  const unknown = findUnknownOptions(args, ["--title"], []);
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
+  }
+
+  const titleOpt = getOptionValue(args, "--title");
+  if (titleOpt.error) {
+    return { error: titleOpt.error };
+  }
+
+  const positional = args.filter((token, index) => {
+    if (token === "--title") {
+      return false;
+    }
+    if (index > 0 && args[index - 1] === "--title") {
+      return false;
+    }
+    return !token.startsWith("--");
+  });
+
+  if (positional.length > 1) {
+    return { error: `Unexpected argument: ${positional[1]}` };
+  }
+
+  return {
+    outputFile: path.resolve(positional[0] || "x-flow-api.yaml"),
+    title: titleOpt.found ? titleOpt.value : "Sample API",
+  };
+}
+
+function parseGraphArgs(args) {
+  const unknown = findUnknownOptions(args, ["--format"], []);
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
+  }
+
+  const formatOpt = getOptionValue(args, "--format");
+  if (formatOpt.error) {
+    return { error: `${formatOpt.error} Use 'mermaid' or 'json'.` };
+  }
+
+  const format = formatOpt.found ? formatOpt.value : "mermaid";
+  if (!["mermaid", "json"].includes(format)) {
+    return { error: `Invalid --format '${format}'. Use 'mermaid' or 'json'.` };
+  }
+
+  const positional = args.filter((token, index) => {
+    if (token === "--format") {
+      return false;
+    }
+    if (index > 0 && args[index - 1] === "--format") {
+      return false;
+    }
+    return !token.startsWith("--");
+  });
+
+  if (positional.length === 0) {
+    return { error: "Missing OpenAPI file path. Usage: x-openapi-flow graph <openapi-file>" };
+  }
+
+  if (positional.length > 1) {
+    return { error: `Unexpected argument: ${positional[1]}` };
+  }
+
+  return { filePath: path.resolve(positional[0]), format };
+}
+
+function parseDoctorArgs(args) {
+  const unknown = findUnknownOptions(args, ["--config"], []);
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
+  }
+
+  const configOpt = getOptionValue(args, "--config");
+  if (configOpt.error) {
+    return { error: configOpt.error };
+  }
+
+  return {
+    configPath: configOpt.found ? configOpt.value : undefined,
+  };
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === "--help" || command === "-h") {
+    return { help: true };
+  }
+
+  const commandArgs = args.slice(1);
+  if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
+    return { help: true, command };
+  }
+
+  if (command === "validate") {
+    const parsed = parseValidateArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "init") {
+    const parsed = parseInitArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "graph") {
+    const parsed = parseGraphArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "doctor") {
+    const parsed = parseDoctorArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  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 runInit(parsed) {
+  if (fs.existsSync(parsed.outputFile)) {
+    console.error(`ERROR: File already exists: ${parsed.outputFile}`);
+    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}`);
+  return 0;
+}
+
+function runDoctor(parsed) {
+  const config = loadConfig(parsed.configPath);
+  let hasErrors = false;
+
+  console.log("x-openapi-flow doctor");
+  console.log(`- Node.js: ${process.version}`);
+
+  if (config.exists) {
+    if (config.error) {
+      console.error(`- Config: FAIL (${config.path})`);
+      console.error(`  ${config.error}`);
+      hasErrors = true;
+    } else {
+      console.log(`- Config: OK (${config.path})`);
+    }
+  } else {
+    console.log(`- Config: not found (${config.path})`);
+  }
+
+  const defaultApi = path.resolve(process.cwd(), "examples", "payment-api.yaml");
+  if (fs.existsSync(defaultApi)) {
+    console.log(`- Example API: found (${defaultApi})`);
+  } else {
+    console.log("- Example API: not found in current directory (this is optional)");
+  }
+
+  try {
+    if (fs.existsSync(defaultApi)) {
+      const api = loadApi(defaultApi);
+      extractFlows(api);
+      console.log("- Validator engine: OK");
+    } else {
+      console.log("- Validator engine: OK");
+    }
+  } catch (_err) {
+    console.error("- Validator engine: FAIL");
+    hasErrors = true;
+  }
+
+  return hasErrors ? 1 : 0;
+}
+
+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}`);
+  }
+
+  for (const [from, targets] of graph.adjacency.entries()) {
+    for (const to of targets) {
+      lines.push(`  ${from} --> ${to}`);
+    }
+  }
+
+  return {
+    flowCount: flows.length,
+    nodes: [...graph.nodes],
+    edges: [...graph.adjacency.entries()].flatMap(([from, targets]) =>
+      [...targets].map((to) => ({ from, to }))
+    ),
+    mermaid: lines.join("\n"),
+  };
+}
+
+function runGraph(parsed) {
+  try {
+    const graphResult = buildMermaidGraph(parsed.filePath);
+    if (parsed.format === "json") {
+      console.log(JSON.stringify(graphResult, null, 2));
+    } else {
+      console.log(graphResult.mermaid);
+    }
+    return 0;
+  } catch (err) {
+    console.error(`ERROR: Could not build graph — ${err.message}`);
+    return 1;
+  }
+}
+
+function main() {
+  const parsed = parseArgs(process.argv);
+
+  if (parsed.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (parsed.error) {
+    console.error(`ERROR: ${parsed.error}`);
+    console.log("");
+    printHelp();
+    process.exit(1);
+  }
+
+  if (parsed.command === "init") {
+    process.exit(runInit(parsed));
+  }
+
+  if (parsed.command === "doctor") {
+    process.exit(runDoctor(parsed));
+  }
+
+  if (parsed.command === "graph") {
+    process.exit(runGraph(parsed));
+  }
+
+  const config = loadConfig(parsed.configPath);
+  if (config.error) {
+    console.error(`ERROR: ${config.error}`);
+    process.exit(1);
+  }
+
+  const options = {
+    output: parsed.format || config.data.format || "pretty",
+    strictQuality:
+      parsed.strictQuality ||
+      config.data.strictQuality === true,
+    profile: parsed.profile || config.data.profile || "strict",
+  };
+
+  const result = run(parsed.filePath, options);
+  process.exit(result.ok ? 0 : 1);
+}
+
+main();

package/examples/non-terminating-api.yaml

@@ -0,0 +1,70 @@
+openapi: "3.0.3"
+info:
+  title: Non-Terminating States API
+  version: "1.0.0"
+  description: >
+    Example API crafted to demonstrate non_terminating_states detection.
+
+paths:
+  /flows/start:
+    post:
+      summary: Start flow
+      operationId: startFlow
+      x-flow:
+        version: "1.0"
+        id: start-flow
+        current_state: START
+        transitions:
+          - target_state: LOOP_A
+            condition: Branch goes to cyclic subflow.
+            trigger_type: synchronous
+          - target_state: DONE
+            condition: Happy path reaches terminal state.
+            trigger_type: synchronous
+      responses:
+        "200":
+          description: Flow started.
+
+  /flows/loop-a:
+    post:
+      summary: Loop A
+      operationId: loopA
+      x-flow:
+        version: "1.0"
+        id: loop-a-flow
+        current_state: LOOP_A
+        transitions:
+          - target_state: LOOP_B
+            condition: Internal loop transition.
+            trigger_type: webhook
+      responses:
+        "200":
+          description: Loop A handled.
+
+  /flows/loop-b:
+    post:
+      summary: Loop B
+      operationId: loopB
+      x-flow:
+        version: "1.0"
+        id: loop-b-flow
+        current_state: LOOP_B
+        transitions:
+          - target_state: LOOP_A
+            condition: Cycles back to Loop A.
+            trigger_type: polling
+      responses:
+        "200":
+          description: Loop B handled.
+
+  /flows/done:
+    post:
+      summary: Done
+      operationId: doneFlow
+      x-flow:
+        version: "1.0"
+        id: done-flow
+        current_state: DONE
+      responses:
+        "200":
+          description: Terminal state.

package/examples/order-api.yaml

@@ -0,0 +1,111 @@
+openapi: "3.0.3"
+info:
+  title: Order API
+  version: "1.0.0"
+  description: >
+    Example API demonstrating x-flow for order lifecycle orchestration.
+
+paths:
+  /orders:
+    post:
+      summary: Create a new order
+      operationId: createOrder
+      x-flow:
+        version: "1.0"
+        id: create-order-flow
+        current_state: CREATED
+        description: A new order is accepted and created.
+        transitions:
+          - target_state: CONFIRMED
+            condition: Stock and payment checks pass.
+            trigger_type: synchronous
+          - target_state: CANCELLED
+            condition: Validation fails before confirmation.
+            trigger_type: synchronous
+      responses:
+        "201":
+          description: Order created successfully.
+
+  /orders/{id}/confirm:
+    post:
+      summary: Confirm an order
+      operationId: confirmOrder
+      x-flow:
+        version: "1.0"
+        id: confirm-order-flow
+        current_state: CONFIRMED
+        description: Order was confirmed and handed to fulfillment.
+        transitions:
+          - target_state: SHIPPED
+            condition: Warehouse dispatches package.
+            trigger_type: webhook
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Order confirmed.
+
+  /orders/{id}/ship:
+    post:
+      summary: Mark order as shipped
+      operationId: shipOrder
+      x-flow:
+        version: "1.0"
+        id: ship-order-flow
+        current_state: SHIPPED
+        description: Package leaves warehouse.
+        transitions:
+          - target_state: DELIVERED
+            condition: Carrier confirms delivery.
+            trigger_type: webhook
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Order shipped.
+
+  /orders/{id}/deliver:
+    post:
+      summary: Mark order as delivered
+      operationId: deliverOrder
+      x-flow:
+        version: "1.0"
+        id: deliver-order-flow
+        current_state: DELIVERED
+        description: Final state after customer receives package.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Order delivered.
+
+  /orders/{id}/cancel:
+    post:
+      summary: Cancel an order
+      operationId: cancelOrder
+      x-flow:
+        version: "1.0"
+        id: cancel-order-flow
+        current_state: CANCELLED
+        description: Terminal cancellation state.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Order canceled.