gemstack 0.2.5 → 0.3.0

data/lib/gemstack/contract/builder.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Contract
+    # Turns the route table into a language-neutral contract (IR):
+    #
+    #   {
+    #     api_path: "/api",
+    #     types: { "Product" => { fields: [{ name:, type:, nullable:, optional: }] }, ... },
+    #     resources: [{ name: "products", endpoints: [{ name: "list", verb: "GET", path: "/products",
+    #                   params: [], body: nil, query: nil, response: { array: { ref: "Product" } } }] }],
+    #     warnings: [...]
+    #   }
+    #
+    # A type reference is { scalar: :string }, { ref: "Product" }, { array: ref },
+    # { object: [fields] } (anonymous nested object) or { unknown: true }.
+    #
+    # Response conventions (overridable with `returns` in the controller):
+    #   index → [<Resource>Serializer], show/create/update → <Resource>Serializer,
+    #   destroy → no body, anything else → unknown (with a warning).
+    class Builder
+      # Names the generated TypeScript defines itself.
+      RESERVED_TYPES = %w[Paginated PaginationMeta PaginationQuery RequestOptions].freeze
+
+      METHOD_NAMES = { "index" => "list", "show" => "get", "create" => "create", "update" => "update",
+                       "destroy" => "delete" }.freeze
+      VERB_PREFERENCE = %w[GET POST PATCH PUT DELETE].freeze
+
+      def initialize(routes:, api_path:)
+        @routes = routes
+        @api_path = api_path.to_s
+        @types = {}
+        @warnings = []
+      end
+
+      def build
+        result = build_contract
+        clash = result[:types].keys & RESERVED_TYPES
+        unless clash.empty?
+          raise ConfigurationError, "API type name(s) #{clash.join(", ")} are reserved by the generated TypeScript; " \
+                                    "rename the serializer/schema or set its type_name"
+        end
+        result
+      end
+
+      def build_contract
+        resources = @routes.select(&:controller).group_by(&:controller).sort.filter_map do |controller_name, routes|
+          controller = resolve(controller_name) or next
+          endpoints = routes.group_by(&:action).map do |action, action_routes|
+            endpoint(controller, action, action_routes)
+          end
+          { name: controller_name, endpoints: endpoints.compact.sort_by { |e| [e[:path], e[:name]] } }
+        end
+        { api_path: @api_path, types: @types.sort.to_h, resources: resources, warnings: @warnings }
+      end
+
+      private
+
+      def resolve(controller_name)
+        const = "#{Inflector.camelize(controller_name)}Controller"
+        Object.const_get(const)
+      rescue NameError
+        @warnings << "#{const} is not defined; its routes are left out of the contract"
+        nil
+      end
+
+      def endpoint(controller, action, routes)
+        route = routes.min_by { |r| VERB_PREFERENCE.index(r.verb) || 99 }
+        path = route.path.delete_prefix(@api_path)
+        path = "/" if path.empty?
+        schema = controller.input_schemas[action]
+        input = schema && schema_ref(schema, "#{resource_name(controller)}#{Inflector.camelize(action)}Input")
+        get = %w[GET HEAD].include?(route.verb)
+        response = response_ref(controller, action)
+        {
+          name: METHOD_NAMES.fetch(action) { lower_camel(action) }, action: action, verb: route.verb, path: path,
+          params: route.param_names.dup, body: get ? nil : input, query: get ? input : nil,
+          response: response, paginated: response.is_a?(Hash) && response.key?(:page)
+        }
+      end
+
+      def response_ref(controller, action)
+        if controller.response_types.key?(action)
+          type = controller.response_types[action]
+          return type.nil? ? nil : type_ref(type)
+        end
+
+        serializer = conventional_serializer(controller)
+        case action
+        when "index" then serializer ? { array: serializer_ref(serializer) } : unknown(controller, action)
+        when "show", "create", "update" then serializer ? serializer_ref(serializer) : unknown(controller, action)
+        when "destroy" then nil
+        else unknown(controller, action)
+        end
+      end
+
+      def unknown(controller, action)
+        @warnings << "#{controller.name}##{action}: response type unknown (add `returns :#{action}, SomeSerializer`)"
+        { unknown: true }
+      end
+
+      # ProductsController → ProductSerializer (Admin::ProductsController tries Admin::ProductSerializer first).
+      def conventional_serializer(controller)
+        parts = controller.name.delete_suffix("Controller").split("::")
+        singular = Inflector.singularize(parts.last)
+        candidates = ["#{(parts[0...-1] + [singular]).join("::")}Serializer", "#{singular}Serializer"].uniq
+        candidates.each do |name|
+          klass = Object.const_get(name) if Object.const_defined?(name)
+          return klass if klass.is_a?(Class) && klass <= Serializer
+        rescue NameError
+          next
+        end
+        nil
+      end
+
+      def resource_name(controller)
+        Inflector.singularize(controller.name.delete_suffix("Controller").split("::").join)
+      end
+
+      def type_ref(type)
+        case type
+        when HTTP::Page::Type then { page: type_ref(type.item) }
+        when Array then { array: type_ref(type.first) }
+        when Class
+          return serializer_ref(type) if type <= Serializer
+          return schema_ref(type, type.name.to_s.split("::").join) if type <= Schema
+
+          { scalar: Types.fetch(type).name }
+        else { scalar: Types.fetch(type).name }
+        end
+      end
+
+      def serializer_ref(serializer)
+        name = serializer.type_name
+        unless @types.key?(name)
+          @types[name] = :pending # guards against recursive serializers
+          fields = serializer.resolved_attributes.map do |attr|
+            if attr[:type] == :json && !serializer.attributes_list[attr[:name]].type
+              @warnings << "#{serializer.name}##{attr[:name]}: type unknown, emitted as unknown"
+            end
+            { name: attr[:name].to_s, type: type_ref(attr[:type]), nullable: attr[:nullable], optional: false }
+          end
+          @types[name] = { fields: fields }
+        end
+        { ref: name }
+      end
+
+      def schema_ref(schema, fallback_name)
+        name = schema.type_name || fallback_name
+        @types[name] ||= { fields: schema_fields(schema) }
+        { ref: name }
+      end
+
+      def schema_fields(schema)
+        schema.fields.values.map do |field|
+          type = field.schema ? { object: schema_fields(field.schema) } : { scalar: field.type }
+          type = { array: type } if field.array
+          { name: field.name.to_s, type: type, nullable: field.nullable, optional: field.ts_optional? }
+        end
+      end
+
+      def lower_camel(name)
+        camel = Inflector.camelize(name)
+        camel[0].downcase + camel[1..]
+      end
+    end
+  end
+end

data/lib/gemstack/contract/docs/index.html

@@ -0,0 +1,264 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>__TITLE__ API · GemStack</title>
+<style>
+  :root { color-scheme: light dark; --bg: #fff; --fg: #16181d; --muted: #5b6170; --panel: #f4f5f8; --line: #e3e5ea;
+    --get: #1f7a4d; --post: #2b59c3; --patch: #9a6700; --put: #7a3fb0; --delete: #c53030; --focus: #2b59c3; }
+  @media (prefers-color-scheme: dark) { :root { --bg: #0f1115; --fg: #e6e8ee; --muted: #9aa0ad; --panel: #181c26;
+    --line: #262b38; --get: #4cc38a; --post: #7ea2ff; --patch: #e0b44c; --put: #c49bf0; --delete: #ff7b7b; --focus: #7ea2ff; } }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 15px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+  header { position: sticky; top: 0; z-index: 2; display: flex; gap: 1rem; align-items: center; padding: .7rem 1rem;
+    background: var(--bg); border-bottom: 1px solid var(--line); flex-wrap: wrap; }
+  header h1 { font-size: 1.05rem; margin: 0; } header .muted { font-size: .85rem; }
+  header input { flex: 1; min-width: 10rem; max-width: 24rem; }
+  .layout { display: grid; grid-template-columns: 15rem minmax(0, 1fr); }
+  nav { position: sticky; top: 3.3rem; align-self: start; max-height: calc(100vh - 3.3rem); overflow-y: auto; padding: 1rem;
+    border-right: 1px solid var(--line); font-size: .9rem; }
+  nav h2 { font-size: .75rem; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); margin: 1rem 0 .3rem; }
+  nav a { display: flex; gap: .4rem; padding: .15rem 0; color: inherit; text-decoration: none; overflow-wrap: anywhere; }
+  nav a:hover { text-decoration: underline; }
+  main { padding: 1rem 1.5rem 4rem; min-width: 0; }
+  section.op { border: 1px solid var(--line); border-radius: 10px; margin: 0 0 1rem; overflow: hidden; }
+  section.op > summary { list-style: none; } details > summary::-webkit-details-marker { display: none; }
+  summary { display: flex; gap: .7rem; align-items: center; padding: .6rem .9rem; cursor: pointer; flex-wrap: wrap; }
+  summary code { font-size: .95rem; overflow-wrap: anywhere; }
+  .body { padding: .2rem 1rem 1rem; border-top: 1px solid var(--line); }
+  .verb { font: 700 .72rem/1 ui-monospace, Menlo, monospace; padding: .3rem .45rem; border-radius: 5px; color: #fff; min-width: 3.9rem; text-align: center; }
+  .GET { background: var(--get); } .POST { background: var(--post); } .PATCH { background: var(--patch); }
+  .PUT { background: var(--put); } .DELETE { background: var(--delete); }
+  nav .verb { min-width: 3.2rem; font-size: .62rem; padding: .22rem .3rem; }
+  h3 { font-size: .8rem; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); margin: 1rem 0 .35rem; }
+  pre, textarea, input, select, button { font: 13px/1.5 ui-monospace, Menlo, monospace; }
+  pre { background: var(--panel); border-radius: 8px; padding: .7rem .9rem; margin: 0; overflow-x: auto; white-space: pre; }
+  table { border-collapse: collapse; width: 100%; font-size: .9rem; } td, th { text-align: left; padding: .3rem .5rem; border-bottom: 1px solid var(--line); vertical-align: top; }
+  th { color: var(--muted); font-weight: 600; }
+  input, textarea, select { width: 100%; padding: .4rem .5rem; border: 1px solid var(--line); border-radius: 6px; background: var(--bg); color: var(--fg); }
+  input:focus, textarea:focus, button:focus-visible { outline: 2px solid var(--focus); outline-offset: 1px; }
+  textarea { min-height: 7rem; resize: vertical; }
+  button { padding: .45rem .9rem; border-radius: 6px; border: 1px solid var(--fg); background: var(--fg); color: var(--bg); cursor: pointer; }
+  button:disabled { opacity: .6; cursor: default; }
+  .row { display: flex; gap: .6rem; align-items: center; margin-top: .6rem; flex-wrap: wrap; }
+  .muted { color: var(--muted); } .warn { border-left: 3px solid var(--patch); padding: .4rem .8rem; background: var(--panel); border-radius: 4px; margin: 0 0 1rem; font-size: .9rem; }
+  a.ref { color: var(--focus); }
+  .status { font-weight: 700; } .ok { color: var(--get); } .bad { color: var(--delete); }
+  @media (max-width: 760px) { .layout { grid-template-columns: 1fr; } nav { position: static; max-height: none; border-right: 0; border-bottom: 1px solid var(--line); } main { padding: 1rem; } }
+</style>
+</head>
+<body>
+<header>
+  <h1>__TITLE__ API</h1>
+  <input id="filter" type="search" placeholder="Filter endpoints…" aria-label="Filter endpoints">
+  <span class="muted">Development only · <a class="ref" href="__OPENAPI_URL__">openapi.json</a></span>
+</header>
+<div class="layout">
+  <nav id="nav" aria-label="Endpoints"></nav>
+  <main id="main"><p class="muted">Loading…</p></main>
+</div>
+<script>
+"use strict";
+const OPENAPI_URL = "__OPENAPI_URL__";
+const VERBS = ["get", "post", "put", "patch", "delete"];
+let doc;
+
+function el(tag, attrs, ...children) {
+  const node = document.createElement(tag);
+  for (const [key, value] of Object.entries(attrs || {})) {
+    if (value === undefined || value === null || value === false) continue;
+    if (key === "class") node.className = value;
+    else if (key.startsWith("on")) node.addEventListener(key.slice(2), value);
+    else node.setAttribute(key, value === true ? "" : value);
+  }
+  for (const child of children.flat(Infinity)) {
+    if (child === null || child === undefined || child === false) continue;
+    node.append(child instanceof Node ? child : String(child));
+  }
+  return node;
+}
+
+const refName = (ref) => ref.split("/").pop();
+const resolve = (schema) => (schema && schema.$ref ? doc.components.schemas[refName(schema.$ref)] : schema);
+
+// JSON Schema → a TypeScript-like description (matches the generated client types).
+function typeText(schema, indent = "") {
+  if (!schema) return "unknown";
+  if (schema.$ref) return refName(schema.$ref);
+  const variants = schema.anyOf || schema.oneOf;
+  if (variants) return variants.map((s) => typeText(s, indent)).join(" | ");
+  if (schema.enum) return schema.enum.map((v) => JSON.stringify(v)).join(" | ");
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+  const nullable = types.includes("null");
+  const type = types.find((t) => t !== "null");
+  let text;
+  if (type === "array") text = `${wrap(typeText(schema.items, indent))}[]`;
+  else if (type === "object" && schema.properties) {
+    const required = new Set(schema.required || []);
+    const inner = indent + "  ";
+    const lines = Object.entries(schema.properties).map(
+      ([name, prop]) => `${inner}${name}${required.has(name) ? "" : "?"}: ${typeText(prop, inner)};`,
+    );
+    text = `{\n${lines.join("\n")}\n${indent}}`;
+  } else if (type === "object") text = schema.additionalProperties ? `Record<string, ${typeText(schema.additionalProperties, indent)}>` : "Record<string, unknown>";
+  else if (type === "integer" || type === "number") text = "number";
+  else if (type === "string") text = schema.format ? `string /* ${schema.format} */` : "string";
+  else text = type || "unknown";
+  return nullable ? `${text} | null` : text;
+}
+const wrap = (t) => (t.includes("|") ? `(${t})` : t);
+
+function example(schema, depth = 0) {
+  schema = resolve(schema);
+  if (!schema || depth > 4) return null;
+  if (schema.example !== undefined) return schema.example;
+  if (schema.enum) return schema.enum[0];
+  if (schema.anyOf || schema.oneOf) return example((schema.anyOf || schema.oneOf)[0], depth + 1);
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+  const type = types.find((t) => t !== "null");
+  if (type === "object") {
+    const out = {};
+    for (const [name, prop] of Object.entries(schema.properties || {})) out[name] = example(prop, depth + 1);
+    return out;
+  }
+  if (type === "array") return [example(schema.items, depth + 1)];
+  if (type === "integer" || type === "number") return 0;
+  if (type === "boolean") return false;
+  if (type === "string") return { "date-time": new Date().toISOString(), date: new Date().toISOString().slice(0, 10), uuid: crypto.randomUUID() }[schema.format] || "";
+  return null;
+}
+
+// Types mentioned by a schema, linked below the signature.
+function refsIn(schema, found = new Set()) {
+  if (!schema || typeof schema !== "object") return found;
+  if (schema.$ref) {
+    const name = refName(schema.$ref);
+    if (!found.has(name)) { found.add(name); refsIn(doc.components.schemas[name], found); }
+    return found;
+  }
+  for (const value of Object.values(schema)) if (typeof value === "object") refsIn(value, found);
+  return found;
+}
+
+function schemaBlock(schema) {
+  const refs = [...refsIn(schema)].filter((name) => name !== "Error");
+  return [
+    el("pre", {}, typeText(schema)),
+    refs.length ? el("p", { class: "muted" }, "Types: ", refs.flatMap((name, i) => [i ? ", " : "", el("a", { class: "ref", href: `#type-${name}` }, name)])) : null,
+  ];
+}
+
+function operationSection(path, verb, op) {
+  const method = verb.toUpperCase();
+  const id = `op-${op.operationId || method + path}`.replace(/[^\w.-]/g, "-");
+  const params = op.parameters || [];
+  const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+  const [status, response] = Object.entries(op.responses || {}).find(([code]) => code !== "default") || [];
+  const responseSchema = response?.content?.["application/json"]?.schema;
+
+  const inputs = {};
+  const paramRows = params.map((p) => {
+    inputs[p.name] = el("input", { name: p.name, placeholder: p.required ? "required" : "optional", "aria-label": p.name });
+    return el("tr", {}, el("td", {}, el("code", {}, p.name)), el("td", {}, p.in), el("td", {}, typeText(p.schema)), el("td", {}, inputs[p.name]));
+  });
+  const bodyInput = bodySchema ? el("textarea", { "aria-label": "Request body (JSON)", spellcheck: "false" }, JSON.stringify(example(bodySchema), null, 2)) : null;
+  const output = el("div");
+  const send = el("button", { type: "button" }, "Send request");
+  send.addEventListener("click", async () => {
+    send.disabled = true;
+    output.replaceChildren(el("p", { class: "muted" }, "Sending…"));
+    try {
+      let url = path;
+      const query = new URLSearchParams();
+      for (const p of params) {
+        const value = inputs[p.name].value;
+        if (p.in === "path") url = url.replace(`{${p.name}}`, encodeURIComponent(value));
+        else if (p.in === "query" && value !== "") query.append(p.name, value);
+      }
+      if (query.toString()) url += `?${query}`;
+      const init = { method, headers: { accept: "application/json" }, credentials: "same-origin" };
+      if (bodyInput) {
+        JSON.parse(bodyInput.value || "null"); // fail early on invalid JSON
+        init.body = bodyInput.value;
+        init.headers["content-type"] = "application/json";
+      }
+      const started = performance.now();
+      const res = await fetch(url, init);
+      const ms = Math.round(performance.now() - started);
+      const text = await res.text();
+      let shown = text;
+      try { shown = JSON.stringify(JSON.parse(text), null, 2); } catch { /* not JSON */ }
+      output.replaceChildren(
+        el("p", {}, el("span", { class: `status ${res.ok ? "ok" : "bad"}` }, `${res.status} ${res.statusText}`), el("span", { class: "muted" }, ` · ${ms} ms · ${method} ${url}`)),
+        text ? el("pre", {}, shown) : el("p", { class: "muted" }, "(no body)"),
+      );
+    } catch (error) {
+      output.replaceChildren(el("p", { class: "bad" }, String(error.message || error)));
+    } finally {
+      send.disabled = false;
+    }
+  });
+
+  return el("details", { class: "op", id, "data-search": `${method} ${path} ${op.operationId || ""}`.toLowerCase() },
+    el("summary", {}, el("span", { class: `verb ${method}` }, method), el("code", {}, path), el("span", { class: "muted" }, op.operationId || "")),
+    el("div", { class: "body" },
+      params.length ? [el("h3", {}, "Parameters"), el("table", {}, el("tr", {}, el("th", {}, "Name"), el("th", {}, "In"), el("th", {}, "Type"), el("th", {}, "Value")), paramRows)] : null,
+      bodySchema ? [el("h3", {}, "Request body"), schemaBlock(bodySchema)] : null,
+      el("h3", {}, `Response ${status || ""}`), responseSchema ? schemaBlock(responseSchema) : el("p", { class: "muted" }, "No body"),
+      el("h3", {}, "Try it"),
+      el("p", { class: "muted" }, "Sent from this page with your session cookie (sign in through the app first for protected endpoints)."),
+      bodyInput, el("div", { class: "row" }, send), output,
+    ),
+  );
+}
+
+function render() {
+  const main = document.getElementById("main");
+  const nav = document.getElementById("nav");
+  const groups = new Map();
+  for (const [path, item] of Object.entries(doc.paths || {})) {
+    for (const verb of VERBS) {
+      const op = item[verb];
+      if (!op) continue;
+      const tag = (op.tags && op.tags[0]) || "other";
+      if (!groups.has(tag)) groups.set(tag, []);
+      groups.get(tag).push({ path, verb, op });
+    }
+  }
+  const content = [];
+  const warnings = doc["x-gemstack-warnings"] || [];
+  if (warnings.length) content.push(el("div", { class: "warn" }, el("strong", {}, "Contract warnings"), el("ul", {}, warnings.map((w) => el("li", {}, w)))));
+  const navItems = [];
+  for (const [tag, ops] of [...groups.entries()].sort()) {
+    content.push(el("h2", { id: `tag-${tag}` }, tag));
+    navItems.push(el("h2", {}, tag));
+    for (const { path, verb, op } of ops) {
+      const section = operationSection(path, verb, op);
+      content.push(section);
+      navItems.push(el("a", { href: `#${section.id}`, "data-search": section.dataset.search, onclick: () => (section.open = true) },
+        el("span", { class: `verb ${verb.toUpperCase()}` }, verb.toUpperCase()), path));
+    }
+  }
+  const schemas = Object.entries(doc.components?.schemas || {}).sort(([a], [b]) => a.localeCompare(b));
+  content.push(el("h2", { id: "types" }, "Types"));
+  for (const [name, schema] of schemas) content.push(el("div", { id: `type-${name}` }, el("h3", {}, name), el("pre", {}, typeText(schema))));
+  if (!groups.size) content.unshift(el("p", { class: "muted" }, "No routes yet. Add some in config/routes.rb — this page rebuilds on every load."));
+  main.replaceChildren(...content);
+  nav.replaceChildren(...navItems, el("h2", {}, el("a", { href: "#types" }, "Types")));
+  const hash = decodeURIComponent(location.hash.slice(1));
+  if (hash) { const target = document.getElementById(hash); if (target) { if (target.tagName === "DETAILS") target.open = true; target.scrollIntoView(); } }
+}
+
+document.getElementById("filter").addEventListener("input", (event) => {
+  const q = event.target.value.trim().toLowerCase();
+  for (const node of document.querySelectorAll("[data-search]")) node.hidden = q !== "" && !node.dataset.search.includes(q);
+});
+
+fetch(OPENAPI_URL, { headers: { accept: "application/json" } })
+  .then((res) => (res.ok ? res.json() : Promise.reject(new Error(`HTTP ${res.status} loading ${OPENAPI_URL}`))))
+  .then((json) => { doc = json; render(); })
+  .catch((error) => document.getElementById("main").replaceChildren(el("p", { class: "bad" }, String(error.message || error))));
+</script>
+</body>
+</html>

data/lib/gemstack/contract/docs.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Contract
+    # Development API docs:
+    #   GET <api_path>/docs               interactive page (self-contained, no CDN)
+    #   GET <api_path>/docs/openapi.json  OpenAPI 3.1 built from the current routes
+    # Rebuilt on every request, so it always matches the code after a reload.
+    class Docs
+      PAGE = File.read(File.join(__dir__, "docs", "index.html")).freeze
+      CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; " \
+            "img-src data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+
+      def initialize(app, application)
+        @app = app
+        @application = application
+      end
+
+      def call(env)
+        path = env[Rack::PATH_INFO]
+        base = "#{@application.config.http.api_path}/docs"
+        return @app.call(env) unless env[Rack::REQUEST_METHOD] == "GET" && [base, "#{base}/",
+                                                                            "#{base}/openapi.json"].include?(path)
+
+        path.end_with?(".json") ? openapi : page(base)
+      end
+
+      private
+
+      def openapi
+        contract = Builder.new(routes: @application.routes, api_path: @application.config.http.api_path).build
+        body = JSON.generate(OpenAPI.new(contract).document.merge("x-gemstack-warnings" => contract[:warnings]))
+        [200, { "content-type" => "application/json; charset=utf-8", "cache-control" => "no-store" }, [body]]
+      end
+
+      def page(base)
+        title = Rack::Utils.escape_html(GemStack.config.name.to_s)
+        html = PAGE.gsub("__OPENAPI_URL__", "#{base}/openapi.json").gsub("__TITLE__", title)
+        headers = { "content-type" => "text/html; charset=utf-8", "cache-control" => "no-store",
+                    "content-security-policy" => CSP }
+        [200, headers, [html]]
+      end
+    end
+  end
+end

data/lib/gemstack/contract/openapi.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Contract
+    # OpenAPI 3.1 document from the contract IR.
+    class OpenAPI
+      ERROR_SCHEMA = {
+        type: "object",
+        required: ["error"],
+        properties: {
+          error: {
+            type: "object", required: %w[code message],
+            properties: { code: { type: "string" }, message: { type: "string" }, request_id: { type: "string" } }
+          },
+          errors: { type: "object", additionalProperties: { type: "array", items: { type: "string" } } }
+        }
+      }.freeze
+
+      def initialize(contract, title: GemStack.config.name, version: GemStack::VERSION)
+        @contract = contract
+        @title = title
+        @version = version
+      end
+
+      def document
+        {
+          openapi: "3.1.0",
+          info: { title: @title, version: @version },
+          paths: paths,
+          components: { schemas: schemas.merge("Error" => ERROR_SCHEMA) }
+        }
+      end
+
+      PAGE_PARAMETERS = %w[page per_page].map do |name|
+        { name: name, in: "query", required: false, schema: { type: "integer", minimum: 1 } }
+      end.freeze
+
+      private
+
+      def paths
+        @contract[:resources].flat_map { |resource| resource[:endpoints].map { |e| [resource, e] } }
+                             .group_by { |_, e| openapi_path(e[:path]) }
+                             .transform_values do |pairs|
+          pairs.to_h do |resource, e|
+            [e[:verb].downcase, operation(resource, e)]
+          end
+        end
+      end
+
+      def operation(resource, endpoint)
+        op = {
+          operationId: "#{resource[:name].tr("/", "_")}.#{endpoint[:name]}",
+          tags: [resource[:name]],
+          parameters: endpoint[:params].map { |p| { name: p, in: "path", required: true, schema: { type: "string" } } },
+          responses: responses(endpoint)
+        }
+        op[:parameters].concat(query_parameters(endpoint[:query])) if endpoint[:query]
+        op[:parameters].concat(PAGE_PARAMETERS) if endpoint[:paginated]
+        if endpoint[:body]
+          op[:requestBody] =
+            { required: true, content: { "application/json" => { schema: schema_for(endpoint[:body]) } } }
+        end
+        op
+      end
+
+      def responses(endpoint)
+        success = endpoint[:verb] == "POST" ? "201" : "200"
+        ok = if endpoint[:response]
+               { success => { description: "OK",
+                              content: { "application/json" => { schema: schema_for(endpoint[:response]) } } } }
+             else
+               { "204" => { description: "No Content" } }
+             end
+        error = { description: "Error",
+                  content: { "application/json" => { schema: { "$ref": "#/components/schemas/Error" } } } }
+        ok.merge("default" => error)
+      end
+
+      def query_parameters(ref)
+        fields = ref[:ref] ? @contract[:types].dig(ref[:ref], :fields) : []
+        Array(fields).map do |field|
+          { name: field[:name], in: "query", required: !field[:optional], schema: schema_for(field[:type]) }
+        end
+      end
+
+      def schemas
+        @contract[:types].transform_values { |type| object_schema(type[:fields]) }
+      end
+
+      def object_schema(fields)
+        properties = fields.to_h do |field|
+          schema = schema_for(field[:type])
+          schema = { oneOf: [schema, { type: "null" }] } if field[:nullable]
+          [field[:name], schema]
+        end
+        { type: "object", properties: properties, required: fields.reject { |f| f[:optional] }.map { |f| f[:name] } }
+      end
+
+      def schema_for(ref)
+        if ref[:scalar] then Types.fetch(ref[:scalar]).openapi.dup
+        elsif ref[:ref] then { "$ref": "#/components/schemas/#{ref[:ref]}" }
+        elsif ref[:array] then { type: "array", items: schema_for(ref[:array]) }
+        elsif ref[:page] then page_schema(ref[:page])
+        elsif ref[:object] then object_schema(ref[:object])
+        else {}
+        end
+      end
+
+      def page_schema(item)
+        meta = %w[page per_page total total_pages].to_h { |key| [key, { type: "integer" }] }
+        {
+          type: "object", required: %w[data meta],
+          properties: {
+            data: { type: "array", items: schema_for(item) },
+            meta: { type: "object", required: meta.keys, properties: meta }
+          }
+        }
+      end
+
+      def openapi_path(path) = "#{@contract[:api_path]}#{path.gsub(/[:*](\w+)/, '{\1}')}"
+    end
+  end
+end