x-openapi-flow 1.4.3 → 1.5.0

package/lib/error-codes.js

@@ -0,0 +1,289 @@
+"use strict";
+
+// ---------------------------------------------------------------------------
+// x-openapi-flow Stable Error & Warning Code Registry
+//
+// Codes are organized by category:
+//   XFLOW_E0xx  – Schema validation errors
+//   XFLOW_E1xx  – Graph validation errors
+//   XFLOW_W2xx  – Quality check warnings
+//   XFLOW_L3xx  – Lint rule violations
+//   XFLOW_RT4xx – Runtime guard errors
+//   XFLOW_CLI5xx – CLI / argument errors
+//
+// All codes are stable across releases. New codes are only appended.
+// ---------------------------------------------------------------------------
+
+const CODES = {
+  // ── Schema ──────────────────────────────────────────────────────────────
+  /** x-openapi-flow payload failed JSON Schema validation. */
+  SCHEMA_VALIDATION_FAILED: {
+    code: "XFLOW_E001",
+    category: "schema",
+    severity: "error",
+    title: "Schema validation failed",
+  },
+  /** Required field is missing from the x-openapi-flow object. */
+  SCHEMA_MISSING_REQUIRED: {
+    code: "XFLOW_E002",
+    category: "schema",
+    severity: "error",
+    title: "Missing required field",
+  },
+  /** Unknown property found in x-openapi-flow payload. */
+  SCHEMA_ADDITIONAL_PROPERTY: {
+    code: "XFLOW_E003",
+    category: "schema",
+    severity: "error",
+    title: "Additional property not allowed",
+  },
+  /** Field value is not in the allowed enum set. */
+  SCHEMA_INVALID_ENUM: {
+    code: "XFLOW_E004",
+    category: "schema",
+    severity: "error",
+    title: "Invalid enum value",
+  },
+
+  // ── Graph ────────────────────────────────────────────────────────────────
+  /** No initial state (indegree = 0) detected in the flow graph. */
+  GRAPH_NO_INITIAL_STATE: {
+    code: "XFLOW_E101",
+    category: "graph",
+    severity: "error",
+    title: "No initial state detected",
+  },
+  /** No terminal state (outdegree = 0) detected in the flow graph. */
+  GRAPH_NO_TERMINAL_STATE: {
+    code: "XFLOW_E102",
+    category: "graph",
+    severity: "error",
+    title: "No terminal state detected",
+  },
+  /** One or more states are unreachable from any initial state. */
+  GRAPH_UNREACHABLE_STATES: {
+    code: "XFLOW_E103",
+    category: "graph",
+    severity: "error",
+    title: "Unreachable state(s) detected",
+  },
+  /** A cycle was detected in the flow graph (strict profile fails on cycles). */
+  GRAPH_CYCLE_DETECTED: {
+    code: "XFLOW_E104",
+    category: "graph",
+    severity: "error",
+    title: "Cycle detected in flow graph",
+  },
+  /** States referenced in transitions but not defined as current_state ancestors. */
+  GRAPH_ORPHAN_STATES: {
+    code: "XFLOW_E105",
+    category: "graph",
+    severity: "error",
+    title: "Orphan states detected",
+  },
+
+  // ── Quality ──────────────────────────────────────────────────────────────
+  /** More than one flow has no incoming transitions (multiple starting points). */
+  QUALITY_MULTIPLE_INITIAL_STATES: {
+    code: "XFLOW_W201",
+    category: "quality",
+    severity: "warning",
+    title: "Multiple initial states",
+  },
+  /** Two or more transitions from the same state to the same target are identical. */
+  QUALITY_DUPLICATE_TRANSITIONS: {
+    code: "XFLOW_W202",
+    category: "quality",
+    severity: "warning",
+    title: "Duplicate transitions",
+  },
+  /** A state exists that has no outgoing path to any terminal state. */
+  QUALITY_NON_TERMINATING_STATES: {
+    code: "XFLOW_W203",
+    category: "quality",
+    severity: "warning",
+    title: "Non-terminating states",
+  },
+  /** A transition references an operationId that is not defined in the API spec. */
+  QUALITY_INVALID_OPERATION_REF: {
+    code: "XFLOW_W204",
+    category: "quality",
+    severity: "warning",
+    title: "Invalid operation reference in transition",
+  },
+  /** A field reference in a transition cannot be resolved against the API schema. */
+  QUALITY_INVALID_FIELD_REF: {
+    code: "XFLOW_W205",
+    category: "quality",
+    severity: "warning",
+    title: "Invalid field reference in transition",
+  },
+  /** State names use inconsistent naming conventions (e.g. mix of snake_case and camelCase). */
+  QUALITY_SEMANTIC_INCONSISTENT_NAMING: {
+    code: "XFLOW_W206",
+    category: "quality",
+    severity: "warning",
+    title: "Inconsistent state naming style",
+  },
+  /** Different capitalisation variants resolve to the same canonical state name. */
+  QUALITY_SEMANTIC_AMBIGUOUS_VARIANTS: {
+    code: "XFLOW_W207",
+    category: "quality",
+    severity: "warning",
+    title: "Ambiguous state name variants",
+  },
+
+  // ── Lint ─────────────────────────────────────────────────────────────────
+  /** next_operation_id references an operationId that does not exist. */
+  LINT_NEXT_OPERATION_ID_EXISTS: {
+    code: "XFLOW_L301",
+    category: "lint",
+    severity: "error",
+    title: "next_operation_id references unknown operation",
+  },
+  /** prerequisite_operation_ids references one or more operationIds that do not exist. */
+  LINT_PREREQUISITE_OPERATION_IDS_EXIST: {
+    code: "XFLOW_L302",
+    category: "lint",
+    severity: "error",
+    title: "prerequisite_operation_ids references unknown operation",
+  },
+  /** Duplicate transitions violate lint rule. */
+  LINT_DUPLICATE_TRANSITIONS: {
+    code: "XFLOW_L303",
+    category: "lint",
+    severity: "error",
+    title: "Duplicate transitions (lint)",
+  },
+  /** State(s) cannot reach any terminal state, violating the terminal_path lint rule. */
+  LINT_TERMINAL_PATH: {
+    code: "XFLOW_L304",
+    category: "lint",
+    severity: "error",
+    title: "No terminal path from state",
+  },
+  /** Semantic naming consistency issues detected in flow state names. */
+  LINT_SEMANTIC_CONSISTENCY: {
+    code: "XFLOW_L305",
+    category: "lint",
+    severity: "error",
+    title: "Semantic modeling inconsistency",
+  },
+
+  // ── Runtime ──────────────────────────────────────────────────────────────
+  /** Request blocked because the resource is not in a state that allows this operation. */
+  RUNTIME_INVALID_STATE_TRANSITION: {
+    code: "XFLOW_RT401",
+    category: "runtime",
+    severity: "error",
+    title: "Invalid state transition blocked",
+    httpStatus: 409,
+    legacyCode: "INVALID_STATE_TRANSITION",
+  },
+  /** Runtime guard cannot resolve an operation for the incoming request. */
+  RUNTIME_UNKNOWN_OPERATION: {
+    code: "XFLOW_RT402",
+    category: "runtime",
+    severity: "error",
+    title: "Unknown operation",
+    httpStatus: 500,
+    legacyCode: "UNKNOWN_OPERATION",
+  },
+  /** Runtime guard is configured without a getCurrentState callback. */
+  RUNTIME_MISSING_STATE_RESOLVER: {
+    code: "XFLOW_RT403",
+    category: "runtime",
+    severity: "error",
+    title: "Missing state resolver",
+    httpStatus: 500,
+    legacyCode: "MISSING_STATE_RESOLVER",
+  },
+  /** Runtime guard cannot determine the resource id for the incoming request. */
+  RUNTIME_MISSING_RESOURCE_ID: {
+    code: "XFLOW_RT404",
+    category: "runtime",
+    severity: "error",
+    title: "Missing resource id",
+    httpStatus: 400,
+    legacyCode: "MISSING_RESOURCE_ID",
+  },
+
+  // ── CLI ──────────────────────────────────────────────────────────────────
+  /** OpenAPI or sidecar file could not be found at the specified path. */
+  CLI_FILE_NOT_FOUND: {
+    code: "XFLOW_CLI501",
+    category: "cli",
+    severity: "error",
+    title: "File not found",
+  },
+  /** OpenAPI or sidecar file could not be parsed (invalid YAML/JSON). */
+  CLI_PARSE_ERROR: {
+    code: "XFLOW_CLI502",
+    category: "cli",
+    severity: "error",
+    title: "File parse error",
+  },
+  /** Invalid or missing CLI argument. */
+  CLI_INVALID_ARGS: {
+    code: "XFLOW_CLI503",
+    category: "cli",
+    severity: "error",
+    title: "Invalid arguments",
+  },
+};
+
+/**
+ * Build a structured diagnostic issue object suitable for JSON output.
+ *
+ * @param {object} def  - A CODES entry.
+ * @param {string} [message] - Human-readable detail message.
+ * @param {object} [opts]
+ * @param {string} [opts.location] - Operation endpoint or state label.
+ * @param {string} [opts.suggestion] - Actionable fix text.
+ * @param {object} [opts.details] - Extra machine-readable fields.
+ * @returns {{ code: string, category: string, severity: string, title: string, message: string, location?: string, suggestion?: string }}
+ */
+function buildIssue(def, message, { location, suggestion, details } = {}) {
+  const issue = {
+    code: def.code,
+    category: def.category,
+    severity: def.severity,
+    title: def.title,
+    message: message || def.title,
+  };
+
+  if (location != null) {
+    issue.location = location;
+  }
+
+  if (suggestion != null) {
+    issue.suggestion = suggestion;
+  }
+
+  if (details && typeof details === "object") {
+    Object.assign(issue, details);
+  }
+
+  return issue;
+}
+
+/**
+ * Look up a CODES entry by its short key (e.g. "SCHEMA_VALIDATION_FAILED") or
+ * by stable code string (e.g. "XFLOW_E001").
+ *
+ * @param {string} keyOrCode
+ * @returns {object|null}
+ */
+function lookup(keyOrCode) {
+  if (CODES[keyOrCode]) {
+    return CODES[keyOrCode];
+  }
+
+  return Object.values(CODES).find((entry) => entry.code === keyOrCode) || null;
+}
+
+module.exports = {
+  CODES,
+  buildIssue,
+  lookup,
+};

package/lib/openapi-state-machine-adapter.js

@@ -0,0 +1,151 @@
+"use strict";
+
+const path = require("path");
+const { loadApi } = require("./validator");
+
+const HTTP_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+];
+
+function normalizePathTemplate(inputPath) {
+  if (!inputPath) {
+    return "/";
+  }
+
+  const withSlashes = String(inputPath).startsWith("/")
+    ? String(inputPath)
+    : `/${String(inputPath)}`;
+
+  return withSlashes
+    .replace(/:([A-Za-z0-9_]+)/g, "{$1}")
+    .replace(/\/+/g, "/")
+    .replace(/\/$/, "") || "/";
+}
+
+function buildPathRegex(pathTemplate) {
+  const escaped = normalizePathTemplate(pathTemplate)
+    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+    .replace(/\\\{[^}]+\\\}/g, "[^/]+");
+
+  return new RegExp(`^${escaped}$`);
+}
+
+function routeKey(method, pathTemplate) {
+  return `${String(method || "").toUpperCase()} ${normalizePathTemplate(pathTemplate)}`;
+}
+
+function extractFlowOperationsFromOpenApi(api, options = {}) {
+  const methods = Array.isArray(options.httpMethods) && options.httpMethods.length > 0
+    ? options.httpMethods
+    : HTTP_METHODS;
+
+  const operations = [];
+  const paths = (api && api.paths) || {};
+
+  for (const [pathKey, pathItem] of Object.entries(paths)) {
+    for (const method of methods) {
+      const operation = pathItem[method];
+      if (!operation || !operation["x-openapi-flow"]) {
+        continue;
+      }
+
+      const flow = operation["x-openapi-flow"];
+      const operationId = operation.operationId || `${method}_${pathKey}`;
+
+      operations.push({
+        operationId,
+        method: method.toUpperCase(),
+        pathTemplate: normalizePathTemplate(pathKey),
+        routeKey: routeKey(method, pathKey),
+        routeRegex: buildPathRegex(pathKey),
+        currentState: flow.current_state,
+        transitions: Array.isArray(flow.transitions) ? flow.transitions : [],
+      });
+    }
+  }
+
+  return operations;
+}
+
+function buildStateMachineDefinitionFromOperations(operations) {
+  const byOperationId = new Map(operations.map((operation) => [operation.operationId, operation]));
+  const transitions = [];
+
+  for (const source of operations) {
+    for (const transition of source.transitions) {
+      if (transition.next_operation_id && byOperationId.has(transition.next_operation_id)) {
+        const target = byOperationId.get(transition.next_operation_id);
+        transitions.push({
+          from: source.currentState,
+          action: transition.next_operation_id,
+          to: target.currentState,
+        });
+        continue;
+      }
+
+      if (!transition.target_state) {
+        continue;
+      }
+
+      for (const target of operations) {
+        if (target.currentState === transition.target_state) {
+          transitions.push({
+            from: source.currentState,
+            action: target.operationId,
+            to: target.currentState,
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    transitions,
+  };
+}
+
+function buildStateMachineDefinitionFromOpenApi(api, options = {}) {
+  const operations = extractFlowOperationsFromOpenApi(api, options);
+  return buildStateMachineDefinitionFromOperations(operations);
+}
+
+function buildStateMachineDefinitionFromOpenApiFile(openapiPath, options = {}) {
+  const api = loadApi(path.resolve(openapiPath));
+  return buildStateMachineDefinitionFromOpenApi(api, options);
+}
+
+function createStateMachineAdapterModel(options = {}) {
+  if (!options.openapi && !options.openapiPath) {
+    throw new Error("State machine adapter requires 'openapi' object or 'openapiPath'.");
+  }
+
+  const api = options.openapiPath
+    ? loadApi(path.resolve(options.openapiPath))
+    : options.openapi;
+
+  const operations = extractFlowOperationsFromOpenApi(api, options);
+  const definition = buildStateMachineDefinitionFromOperations(operations);
+
+  return {
+    api,
+    operations,
+    definition,
+  };
+}
+
+module.exports = {
+  normalizePathTemplate,
+  routeKey,
+  extractFlowOperationsFromOpenApi,
+  buildStateMachineDefinitionFromOperations,
+  buildStateMachineDefinitionFromOpenApi,
+  buildStateMachineDefinitionFromOpenApiFile,
+  createStateMachineAdapterModel,
+};

package/lib/runtime-guard/core.js

@@ -0,0 +1,176 @@
+"use strict";
+
+const {
+  FlowGuardError,
+  invalidTransitionError,
+  unknownOperationError,
+  missingStateResolverError,
+  missingResourceIdError,
+} = require("./errors");
+const { loadRuntimeModel, normalizePathTemplate, routeKey } = require("./model");
+
+function defaultResolveResourceId(context) {
+  const params = context && context.params;
+  if (!params || typeof params !== "object") {
+    return null;
+  }
+
+  if (params.id != null) {
+    return String(params.id);
+  }
+
+  if (params.resourceId != null) {
+    return String(params.resourceId);
+  }
+
+  return null;
+}
+
+class RuntimeFlowGuard {
+  constructor(options = {}) {
+    const runtimeModel = loadRuntimeModel(options);
+
+    this.operations = runtimeModel.operations;
+    this.byOperationId = runtimeModel.byOperationId;
+    this.byRouteKey = runtimeModel.byRouteKey;
+    this.stateMachine = runtimeModel.stateMachine;
+
+    this.getCurrentState = options.getCurrentState;
+    this.resolveResourceId = options.resolveResourceId || defaultResolveResourceId;
+    this.resolveOperationId = options.resolveOperationId || null;
+
+    this.allowUnknownOperations = options.allowUnknownOperations === true;
+    this.allowIdempotentState = options.allowIdempotentState !== false;
+    this.allowMissingStateForInitial = options.allowMissingStateForInitial !== false;
+    this.requireResourceIdForTransitions = options.requireResourceIdForTransitions !== false;
+  }
+
+  resolveOperation({ operationId, method, path }) {
+    if (operationId && this.byOperationId.has(operationId)) {
+      return this.byOperationId.get(operationId);
+    }
+
+    const normalizedPath = normalizePathTemplate(path || "/");
+    const byKey = this.byRouteKey.get(routeKey(method, normalizedPath));
+    if (byKey) {
+      return byKey;
+    }
+
+    const methodUpper = String(method || "").toUpperCase();
+    for (const operation of this.operations) {
+      if (operation.method !== methodUpper) {
+        continue;
+      }
+
+      if (operation.routeRegex.test(normalizedPath)) {
+        return operation;
+      }
+    }
+
+    return null;
+  }
+
+  async enforce(context = {}) {
+    if (typeof this.getCurrentState !== "function") {
+      throw missingStateResolverError();
+    }
+
+    const operationFromResolver = this.resolveOperationId
+      ? await this.resolveOperationId(context)
+      : null;
+
+    const operation = this.resolveOperation({
+      operationId: context.operationId || operationFromResolver,
+      method: context.method,
+      path: context.path,
+    });
+
+    if (!operation) {
+      if (this.allowUnknownOperations) {
+        return { ok: true, skipped: true, reason: "unknown_operation" };
+      }
+
+      throw unknownOperationError({
+        operationId: context.operationId || operationFromResolver,
+        method: context.method,
+        path: context.path,
+      });
+    }
+
+    const resourceId = this.resolveResourceId(context);
+    if (!resourceId && operation.incomingFromStates.size > 0 && this.requireResourceIdForTransitions) {
+      throw missingResourceIdError({
+        operationId: operation.operationId,
+        method: context.method,
+        path: context.path,
+      });
+    }
+
+    const currentState = await this.getCurrentState({
+      operation,
+      operationId: operation.operationId,
+      resourceId,
+      context,
+    });
+
+    if (currentState == null) {
+      if (operation.incomingFromStates.size === 0 && this.allowMissingStateForInitial) {
+        return {
+          ok: true,
+          operationId: operation.operationId,
+          resourceId,
+          currentState: null,
+        };
+      }
+
+      throw invalidTransitionError({
+        operationId: operation.operationId,
+        currentState: null,
+        allowedFromStates: operation.incomingFromStates,
+        resourceId,
+      });
+    }
+
+    const normalizedState = String(currentState);
+    const isAllowedFrom = this.stateMachine.canTransition(normalizedState, operation.operationId);
+    const isSameState = this.allowIdempotentState && normalizedState === String(operation.currentState);
+
+    if (!isAllowedFrom && !isSameState) {
+      throw invalidTransitionError({
+        operationId: operation.operationId,
+        currentState: normalizedState,
+        allowedFromStates: operation.incomingFromStates,
+        resourceId,
+      });
+    }
+
+    return {
+      ok: true,
+      operationId: operation.operationId,
+      resourceId,
+      currentState: normalizedState,
+      nextState: this.stateMachine.getNextState(normalizedState, operation.operationId),
+    };
+  }
+}
+
+function createRuntimeFlowGuard(options) {
+  return new RuntimeFlowGuard(options);
+}
+
+function toErrorPayload(error) {
+  if (error instanceof FlowGuardError) {
+    return error.toJSON();
+  }
+
+  return {
+    code: "INTERNAL_RUNTIME_GUARD_ERROR",
+    message: error && error.message ? error.message : "Unknown runtime guard error.",
+  };
+}
+
+module.exports = {
+  RuntimeFlowGuard,
+  createRuntimeFlowGuard,
+  toErrorPayload,
+};

package/lib/runtime-guard/errors.js

@@ -0,0 +1,85 @@
+"use strict";
+
+class FlowGuardError extends Error {
+  constructor(message, details = {}, statusCode = 409) {
+    super(message);
+    this.name = "FlowGuardError";
+    this.code = details.code || "FLOW_GUARD_ERROR";
+    this.statusCode = statusCode;
+    this.details = details;
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...this.details,
+    };
+  }
+}
+
+function invalidTransitionError({
+  operationId,
+  currentState,
+  allowedFromStates,
+  resourceId,
+}) {
+  const allowed = [...allowedFromStates].sort();
+  const current = currentState == null ? null : String(currentState);
+
+  return new FlowGuardError(
+    `Blocked invalid transition for operation '${operationId}'. Current state '${current}' cannot transition to this operation.`,
+    {
+      code: "INVALID_STATE_TRANSITION",
+      operation_id: operationId,
+      current_state: current,
+      allowed_from_states: allowed,
+      resource_id: resourceId || null,
+    },
+    409
+  );
+}
+
+function unknownOperationError({ operationId, method, path }) {
+  return new FlowGuardError(
+    `Runtime guard could not resolve operation for '${method} ${path}'.`,
+    {
+      code: "UNKNOWN_OPERATION",
+      operation_id: operationId || null,
+      method: method || null,
+      path: path || null,
+    },
+    500
+  );
+}
+
+function missingStateResolverError() {
+  return new FlowGuardError(
+    "Runtime guard requires 'getCurrentState' callback to enforce transitions.",
+    {
+      code: "MISSING_STATE_RESOLVER",
+    },
+    500
+  );
+}
+
+function missingResourceIdError({ operationId, method, path }) {
+  return new FlowGuardError(
+    `Runtime guard requires a resource id to enforce operation '${operationId}'.`,
+    {
+      code: "MISSING_RESOURCE_ID",
+      operation_id: operationId || null,
+      method: method || null,
+      path: path || null,
+    },
+    400
+  );
+}
+
+module.exports = {
+  FlowGuardError,
+  invalidTransitionError,
+  unknownOperationError,
+  missingStateResolverError,
+  missingResourceIdError,
+};