openapi.js

/*
 * Reconstruct OpenAPI operation docs from a Mintlify RSC payload.
 *
 * Mintlify flattens its OpenAPI spec and embeds it in the page payload as a map
 * of `"<uuid>": <value>` definitions plus operation objects whose
 * parameters/requestBody/responses/schema fields are UUID *references* into
 * that map (content-hash dedup). We:
 *   1. Build the uuid -> raw-JSON map by balanced-span scanning the payload.
 *   2. Find operation objects (those carrying "operationId" + "method").
 *   3. Deep-resolve their UUID refs against the map (cycle-guarded).
 *   4. Render each to Markdown (method/path, description, params, body,
 *      responses, curl sample).
 */
const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/;
const UUID_ONLY = new RegExp('^' + UUID.source + '$');

/* Match a balanced JSON value starting at index i (on { [ " or a scalar).
 * Returns [rawString, endIndex] or null. Respects string escapes. */
function matchValue(s, i) {
  while (i < s.length && /\s/.test(s[i])) i++;
  const c = s[i];
  if (c === '"') {
    let j = i + 1;
    while (j < s.length) {
      if (s[j] === '\\') { j += 2; continue; }
      if (s[j] === '"') { j++; break; }
      j++;
    }
    return [s.slice(i, j), j];
  }
  if (c === '{' || c === '[') {
    const open = c, close = c === '{' ? '}' : ']';
    let depth = 0, j = i, inStr = false;
    for (; j < s.length; j++) {
      const ch = s[j];
      if (inStr) {
        if (ch === '\\') { j++; continue; }
        if (ch === '"') inStr = false;
        continue;
      }
      if (ch === '"') inStr = true;
      else if (ch === open) depth++;
      else if (ch === close) { depth--; if (depth === 0) { j++; break; } }
    }
    return [s.slice(i, j), j];
  }
  // scalar: number / true / false / null
  let j = i;
  while (j < s.length && !',}]'.includes(s[j])) j++;
  return [s.slice(i, j).trim(), j];
}

/* Build uuid -> parsed-value map from every `"<uuid>": <value>` in the text. */
function buildRefMap(text) {
  const map = new Map();
  const keyRe = /"([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})"\s*:/g;
  let m;
  while ((m = keyRe.exec(text))) {
    const id = m[1];
    if (map.has(id)) continue;
    const colon = text.indexOf(':', m.index + m[0].length - 1);
    const got = matchValue(text, colon + 1);
    if (!got) continue;
    try { map.set(id, JSON.parse(got[0])); } catch { /* skip non-JSON */ }
  }
  return map;
}

/* Recursively replace UUID string refs with their resolved values. */
function resolve(node, map, seen = new Set(), depth = 0) {
  if (depth > 40) return node;
  if (typeof node === 'string') {
    if (UUID_ONLY.test(node) && map.has(node) && !seen.has(node)) {
      return resolve(map.get(node), map, new Set(seen).add(node), depth + 1);
    }
    return node;
  }
  if (Array.isArray(node)) return node.map((x) => resolve(x, map, seen, depth + 1));
  if (node && typeof node === 'object') {
    const out = {};
    for (const k of Object.keys(node)) out[k] = resolve(node[k], map, seen, depth + 1);
    return out;
  }
  return node;
}

/* Find operation objects in the payload and return them resolved. */
function extractOperations(text) {
  const map = buildRefMap(text);
  const ops = [];
  const seen = new Set();
  // Anchor on "summary": it appears early in every operation object (before the
  // code samples, whose literal {} in curl bodies would corrupt the backward
  // brace scan) and unlike "operationId" it is always present. We brace-match
  // backward to the object start, then forward-match (string-aware) the value.
  const re = /"summary"\s*:\s*"/g;
  let m;
  while ((m = re.exec(text))) {
    let depth = 0, start = -1;
    for (let j = m.index; j >= 0; j--) {
      const ch = text[j];
      if (ch === '}') depth++;
      else if (ch === '{') { if (depth === 0) { start = j; break; } depth--; }
    }
    if (start < 0) continue;
    const got = matchValue(text, start);
    if (!got) continue;
    let op;
    try { op = JSON.parse(got[0]); } catch { continue; }
    if (!op || !op.method || !op.path) continue; // not an operation object
    const key = `${op.method} ${op.path}`;
    if (seen.has(key)) continue;
    seen.add(key);
    ops.push(resolve(op, map));
  }
  return ops;
}

/* ---- Markdown rendering of a resolved operation ---- */
function schemaType(s) {
  if (!s || typeof s !== 'object') return typeof s === 'string' ? s : 'any';
  if (s.type === 'array' && s.items) return `array<${schemaType(s.items)}>`;
  if (s.enum) return `enum(${s.enum.join(', ')})`;
  return s.type || (s.properties ? 'object' : (s.format || 'any'));
}

function renderProps(schema, prefix = '', lines = [], depth = 0) {
  if (!schema || depth > 6) return lines;
  const props = schema.properties || (schema.items && schema.items.properties);
  const req = new Set(schema.required || (schema.items && schema.items.required) || []);
  if (!props) return lines;
  for (const name of Object.keys(props)) {
    const p = props[name];
    const t = schemaType(p);
    const r = req.has(name) ? ' **required**' : '';
    const d = (p.description || '').replace(/\s+/g, ' ').trim();
    lines.push(`| \`${prefix}${name}\` | ${t} |${r ? ' yes' : ' no'} | ${d} |`);
    if (p.properties) renderProps(p, `${prefix}${name}.`, lines, depth + 1);
    else if (p.items && p.items.properties) renderProps(p.items, `${prefix}${name}[].`, lines, depth + 1);
  }
  return lines;
}

function renderOperation(op) {
  const out = [];
  const method = (op.method || '').toUpperCase();
  const path = op.path || '';
  const base = (op.baseUrlOptions && op.baseUrlOptions[0]) || '';
  out.push(`## ${op.summary || op.title || op.operationId || 'Endpoint'}`);
  out.push('');
  out.push('```http');
  out.push(`${method} ${base}${path}`);
  out.push('```');
  if (op.description) out.push('\n' + op.description.replace(/\s+/g, ' ').trim());

  // Parameters (path/query/header).
  const params = Array.isArray(op.parameters) ? op.parameters : [];
  if (params.length) {
    out.push('\n### Parameters\n');
    out.push('| Name | In | Type | Required | Description |');
    out.push('| --- | --- | --- | --- | --- |');
    for (const p of params) {
      if (!p || typeof p !== 'object') continue;
      out.push(`| \`${p.name || ''}\` | ${p.in || ''} | ${schemaType(p.schema)} | ${p.required ? 'yes' : 'no'} | ${(p.description || '').replace(/\s+/g, ' ').trim()} |`);
    }
  }

  // Request body schema.
  const body = op.requestBody;
  const bodySchema = body && body.content &&
    (body.content['application/json'] || Object.values(body.content)[0] || {}).schema;
  if (bodySchema) {
    const rows = renderProps(bodySchema, '', []);
    if (rows.length) {
      out.push('\n### Request body\n');
      out.push('| Field | Type | Required | Description |');
      out.push('| --- | --- | --- | --- |');
      out.push(...rows);
    }
  }

  // Responses.
  if (op.responses && typeof op.responses === 'object') {
    out.push('\n### Responses\n');
    for (const code of Object.keys(op.responses)) {
      const r = op.responses[code] || {};
      out.push(`- **${code}** — ${(r.description || '').replace(/\s+/g, ' ').trim()}`);
    }
  }

  // Code sample (curl).
  const sample = (op.codeSamples && op.codeSamples[0]) ||
    (op['x-code-samples'] && op['x-code-samples'][0]);
  if (sample && sample.source) {
    out.push(`\n### Example (${sample.lang || 'curl'})\n`);
    out.push('```' + (sample.lang || 'bash'));
    out.push(sample.source);
    out.push('```');
  }
  return out.join('\n');
}

function operationsMarkdown(text) {
  const ops = extractOperations(text);
  if (!ops.length) return '';
  return ops.map(renderOperation).join('\n\n').trim();
}

module.exports = { extractOperations, operationsMarkdown, buildRefMap, resolve };