@mingfuyun/star-allinone 0.2.0 → 0.3.1

package/scripts/gen/project.js

@@ -0,0 +1,154 @@
+const fs = require('fs');
+const path = require('path');
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function findProjectRoot(start) {
+  let current = path.resolve(start);
+  while (true) {
+    if (fs.existsSync(path.join(current, '.star-allinone.json'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) {
+      throw new Error('Missing .star-allinone.json. Run this command from a business project root.');
+    }
+    current = parent;
+  }
+}
+
+function loadProject(cwd, options = {}) {
+  const root = findProjectRoot(cwd);
+  const config = readJson(path.join(root, '.star-allinone.json'));
+  const specPath = options.spec || config.openapi
+    ? path.resolve(root, options.spec || config.openapi)
+    : '';
+  if (options.requireSpec !== false && !specPath) {
+    throw new Error('Set openapi in .star-allinone.json or pass --spec <file>.');
+  }
+  if (specPath && !fs.existsSync(specPath)) {
+    throw new Error(`OpenAPI file not found: ${specPath}`);
+  }
+  return {
+    root,
+    config,
+    specPath,
+    spec: specPath ? readJson(specPath) : null,
+    serviceDir: path.resolve(root, config.serviceDir || 'src/services'),
+    dryRun: Boolean(options.dryRun),
+  };
+}
+
+function listDomainDirs(serviceDir) {
+  if (!fs.existsSync(serviceDir)) return [];
+  return fs.readdirSync(serviceDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+}
+
+function existingRequestFile(serviceDir) {
+  for (const name of ['request.tsx', 'request.ts']) {
+    const file = path.join(serviceDir, name);
+    if (fs.existsSync(file)) return name.replace(/\.(tsx|ts)$/, '');
+  }
+  return 'request';
+}
+
+function writeFile(file, content, dryRun) {
+  if (dryRun) {
+    console.log(`[dry-run] write ${file}`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content.endsWith('\n') ? content : `${content}\n`);
+}
+
+function typeExists(content, typeName) {
+  return new RegExp(`\\btype\\s+${typeName}\\b`).test(content);
+}
+
+function insertTypes(content, namespace, blocks) {
+  if (!blocks.length) return content;
+  const nsRe = new RegExp(`declare namespace ${namespace}\\s*\\{`);
+  if (!nsRe.test(content)) {
+    const extra = `declare namespace ${namespace} {\n${blocks.join('\n\n')}\n}\n`;
+    return content.trim() ? `${content.trim()}\n\n${extra}` : extra;
+  }
+  const lastBrace = content.lastIndexOf('}');
+  if (lastBrace === -1) throw new Error(`Cannot insert types into ${namespace}`);
+  return `${content.slice(0, lastBrace).replace(/\s*$/, '\n')}${blocks.join('\n\n')}\n${content.slice(lastBrace)}`;
+}
+
+function insertMethods(content, methods, exportNames, requestImport) {
+  let next = content;
+  if (!next.includes("from '../request'") && !next.includes('from "../request"')) {
+    next = `import MFRequest from '../${requestImport}';\n${next}`;
+  }
+  const exportMatch = next.match(/export default \{[\s\S]*?\};?/);
+  if (!exportMatch) {
+    return `${next.trim()}\n\n${methods.join('\n\n')}\n\nexport default {\n${exportNames.map((name) => `  ${name},`).join('\n')}\n};\n`;
+  }
+  const insertAt = exportMatch.index;
+  const before = next.slice(0, insertAt).replace(/\s*$/, '\n\n');
+  const exportBlock = exportMatch[0];
+  const namesToAdd = exportNames.filter((name) => !new RegExp(`\\b${name}\\b`).test(exportBlock));
+  let updatedExport = exportBlock;
+  if (namesToAdd.length) {
+    updatedExport = exportBlock.replace(
+      /export default \{/,
+      `export default {\n${namesToAdd.map((name) => `  ${name},`).join('\n')}`,
+    );
+  }
+  return `${before}${methods.join('\n\n')}\n\n${updatedExport}${next.slice(insertAt + exportBlock.length)}`;
+}
+
+function patchServiceIndex(indexFile, domain, serviceFile, dryRun) {
+  const importName = `${toCamelSafe(domain)}API`;
+  const importLine = `import ${importName} from './${domain}/${serviceFile}';`;
+  const spread = `...${importName},`;
+  if (!fs.existsSync(indexFile)) {
+    writeFile(
+      indexFile,
+      `${importLine}\n\nexport default {\n  ${spread}\n};\n`,
+      dryRun,
+    );
+    return;
+  }
+  const current = fs.readFileSync(indexFile, 'utf8');
+  if (current.includes(`'./${domain}/${serviceFile}'`) || current.includes(`"./${domain}/${serviceFile}"`)) {
+    return;
+  }
+  let next = `${importLine}\n${current}`;
+  if (/export default \{/.test(next) && !next.includes(spread)) {
+    next = next.replace(/export default \{/, `export default {\n  ${spread}`);
+  }
+  writeFile(indexFile, next, dryRun);
+}
+
+function toCamelSafe(domain) {
+  return domain.charAt(0).toLowerCase() + domain.slice(1);
+}
+
+function patchRootTypings(root, domain, dryRun) {
+  const file = path.join(root, 'typings.d.ts');
+  if (!fs.existsSync(file)) return;
+  const ref = `/// <reference path="./src/services/${domain}/typings.d.ts" />`;
+  const current = fs.readFileSync(file, 'utf8');
+  if (current.includes(`src/services/${domain}/typings.d.ts`)) return;
+  if (!current.includes('/// <reference path=')) return;
+  writeFile(file, `${ref}\n${current}`, dryRun);
+}
+
+module.exports = {
+  readJson,
+  findProjectRoot,
+  loadProject,
+  listDomainDirs,
+  existingRequestFile,
+  writeFile,
+  typeExists,
+  insertTypes,
+  insertMethods,
+  patchServiceIndex,
+  patchRootTypings,
+};

package/scripts/gen/service.js

@@ -0,0 +1,264 @@
+const fs = require('fs');
+const path = require('path');
+const {
+  toPascal,
+  toNamespace,
+  toServiceFile,
+  pathToTemplate,
+  pathParamsFromPath,
+  parseOperationSelector,
+  functionName,
+  requestHelper,
+  domainFromPath,
+  typeName,
+} = require('./names');
+const { findOperation, deref, refName, exampleFromSchema } = require('./spec');
+const { collectRefs, emitNamedType, emitQueryType, paramType } = require('./ts');
+const {
+  loadProject,
+  listDomainDirs,
+  existingRequestFile,
+  writeFile,
+  typeExists,
+  insertTypes,
+  insertMethods,
+  patchServiceIndex,
+  patchRootTypings,
+} = require('./project');
+
+function resolveDomain(operation, project, explicit) {
+  if (explicit) return toPascal(explicit);
+  const dirs = listDomainDirs(project.serviceDir);
+  for (const dir of dirs) {
+    const files = fs.readdirSync(path.join(project.serviceDir, dir));
+    for (const file of files.filter((name) => name.endsWith('.ts') && !name.endsWith('.d.ts'))) {
+      const content = fs.readFileSync(path.join(project.serviceDir, dir, file), 'utf8');
+      if (hasOperation(content, operation.path, operation.method)) {
+        return dir;
+      }
+    }
+  }
+  if (operation.tags?.[0]) return toPascal(operation.tags[0]);
+  return domainFromPath(operation.path);
+}
+
+function useIPrefix(typingsContent) {
+  if (!typingsContent) return false;
+  const prefixed = (typingsContent.match(/\btype I[A-Z]/g) || []).length;
+  const plain = (typingsContent.match(/\btype [A-Z]/g) || []).length;
+  return prefixed > 0 && prefixed >= plain / 2;
+}
+
+function existingNamespace(typingsContent, domain) {
+  const match = typingsContent?.match(/declare namespace (\w+)/);
+  return match?.[1] || toNamespace(domain);
+}
+
+function namedRefMap(spec, schemas, usePrefix, fallback) {
+  const map = new Map();
+  for (const ref of schemas) {
+    const base = refName(ref);
+    map.set(ref, usePrefix ? typeName(base, '', true).replace(/^II/, 'I') : toPascal(base) || fallback);
+  }
+  return map;
+}
+
+function buildArtifacts(project, operation, options) {
+  const fn = functionName(operation);
+  const domain = resolveDomain(operation, project, options.domain);
+  const serviceFile = toServiceFile(domain);
+  const domainDir = path.join(project.serviceDir, domain);
+  const servicePath = path.join(domainDir, `${serviceFile}.ts`);
+  const typingsPath = path.join(domainDir, 'typings.d.ts');
+  const existingService = fs.existsSync(servicePath) ? fs.readFileSync(servicePath, 'utf8') : '';
+  const existingTypings = fs.existsSync(typingsPath) ? fs.readFileSync(typingsPath, 'utf8') : '';
+  const namespace = existingNamespace(existingTypings, domain);
+  const prefix = useIPrefix(existingTypings);
+  const spec = operation.spec;
+  const alreadyHasPath = hasOperation(existingService, operation.path, operation.method);
+  if (!alreadyHasPath && new RegExp(`\\bconst ${fn}\\b`).test(existingService)) {
+    throw new Error(`Conflict: ${fn} already exists in ${path.relative(project.root, servicePath)} but path differs`);
+  }
+
+  const refSet = new Set();
+  [operation.dataSchema, operation.bodySchema, operation.itemSchema, ...operation.queryParams.map((item) => item.schema)]
+    .forEach((schema) => collectRefs(spec, schema, refSet));
+  const namedRefs = namedRefMap(spec, refSet, prefix, 'Entity');
+
+  const typeBlocks = [];
+  for (const [ref, name] of namedRefs.entries()) {
+    if (typeExists(existingTypings, name)) continue;
+    typeBlocks.push(emitNamedType(spec, name, { $ref: ref }, namedRefs));
+  }
+
+  const queryType = typeName(fn, 'Query', prefix);
+  const bodyType = typeName(fn, 'Body', prefix);
+  const dataType = typeName(fn, 'Data', prefix);
+  let responseTypeName;
+
+  const itemType = typeName(fn, 'Item', prefix);
+  if (operation.itemSchema && !operation.itemSchema.$ref && !typeExists(existingTypings, itemType)) {
+    typeBlocks.push(emitNamedType(spec, itemType, deref(spec, operation.itemSchema), namedRefs));
+    namedRefs.set('__item__', itemType);
+  } else if (operation.itemSchema?.$ref) {
+    namedRefs.set('__item__', namedRefs.get(operation.itemSchema.$ref));
+  }
+
+  if (operation.dataSchema?.$ref && namedRefs.get(operation.dataSchema.$ref)) {
+    responseTypeName = namedRefs.get(operation.dataSchema.$ref);
+  } else if (operation.dataSchema) {
+    if (!typeExists(existingTypings, dataType) && !typeBlocks.some((block) => block.includes(`type ${dataType} `))) {
+      typeBlocks.push(emitNamedType(spec, dataType, deref(spec, operation.dataSchema), namedRefs));
+    }
+    responseTypeName = dataType;
+  }
+
+  if (operation.queryParams.length && !typeExists(existingTypings, queryType)) {
+    const emitted = emitQueryType(spec, queryType, operation.queryParams, namedRefs);
+    if (emitted) typeBlocks.push(emitted);
+  }
+  if (operation.bodySchema && !operation.bodySchema.$ref && !typeExists(existingTypings, bodyType)) {
+    typeBlocks.push(emitNamedType(spec, bodyType, deref(spec, operation.bodySchema), namedRefs));
+  } else if (operation.bodySchema?.$ref) {
+    // named ref already emitted
+  }
+
+  const helper = requestHelper(operation);
+  const pathParams = operation.pathParams.length
+    ? operation.pathParams
+    : pathParamsFromPath(operation.path).map((name) => ({ name, required: true, schema: { type: 'string' } }));
+  const args = [];
+  pathParams.forEach((param) => {
+    args.push(`${param.name}: ${paramType(spec, param, namedRefs)}`);
+  });
+  if (operation.queryParams.length) args.push(`params: ${namespace}.${queryType}`);
+  else if (['get', 'delete', 'export'].includes(helper) && !pathParams.length) {
+    args.push(`params?: Record<string, unknown>`);
+  }
+  if (operation.bodySchema) {
+    const bodyName = operation.bodySchema.$ref
+      ? namedRefs.get(operation.bodySchema.$ref) || bodyType
+      : bodyType;
+    args.push(`params: ${namespace}.${bodyName}`);
+  }
+
+  const url = pathToTemplate(operation.path);
+  const generic = responseTypeName ? `<${namespace}.${responseTypeName}>` : '';
+  const callArgs = [];
+  callArgs.push(url);
+  if (operation.bodySchema || operation.queryParams.length) callArgs.push('params');
+  else if (['get', 'delete', 'export'].includes(helper)) callArgs.push(pathParams.length ? '{}' : 'params');
+
+  const summary = (operation.summary || fn).split('\n')[0].trim();
+  const methodSource = `/**\n * ${summary}\n */\nconst ${fn} = (${args.join(', ')}) => {\n  return MFRequest.${helper}${generic}(${callArgs.join(', ')});\n};`;
+
+  const requestImport = existingRequestFile(project.serviceDir);
+  const nextTypings = insertTypes(existingTypings || `declare namespace ${namespace} {\n}\n`, namespace, typeBlocks);
+  const nextService = existingService
+    ? insertMethods(existingService, [methodSource], [fn], requestImport)
+    : `import MFRequest from '../${requestImport}';\n\n${methodSource}\n\nexport default {\n  ${fn},\n};\n`;
+
+  const mock = {
+    code: 0,
+    message: 'success',
+    data: exampleFromSchema(spec, operation.dataSchema) ?? {},
+  };
+
+  return {
+    status: alreadyHasPath ? 'reuse' : 'create',
+    domain,
+    namespace,
+    fn,
+    servicePath,
+    typingsPath,
+    nextService,
+    nextTypings,
+    mock,
+    operation,
+    queryType: operation.queryParams.length ? `${namespace}.${queryType}` : undefined,
+    itemType: itemTypeName(operation, namedRefs, prefix, namespace, itemType),
+    pagination: operation.pagination,
+    message: alreadyHasPath
+      ? `Reused existing ${operation.method.toUpperCase()} ${operation.path}`
+      : undefined,
+  };
+}
+
+function pathVariantsForSearch(apiPath) {
+  return [
+    apiPath,
+    apiPath.replace(/\/$/, ''),
+    apiPath.replace(/\{([^}]+)\}/g, '${$1}'),
+    apiPath.replace(/\{([^}]+)\}/g, '${$1}').replace(/\/$/, ''),
+  ].filter(Boolean);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function hasOperation(content, apiPath, method) {
+  if (!content) return false;
+  const helper = requestHelper({ method, path: apiPath, contentType: '' });
+  return pathVariantsForSearch(apiPath).some((item) => {
+    const pattern = new RegExp(
+      `MFRequest\\.${helper}(?:<[^>]+>)?\\(\\s*[\`'"]${escapeRegExp(item)}`,
+    );
+    return pattern.test(content);
+  });
+}
+
+function itemTypeName(operation, namedRefs, prefix, namespace, fallbackItem) {
+  if (namedRefs.get('__item__')) return `${namespace}.${namedRefs.get('__item__')}`;
+  if (!operation.itemSchema) return undefined;
+  return `${namespace}.${fallbackItem}`;
+}
+
+function writeMock(project, operation, mock, options) {
+  if (!options.mockFile) {
+    return { printed: true, mock };
+  }
+  const relative = `mock${operation.path.replace(/\{[^}]+\}/g, 'id')}${operation.method}.json`
+    .replace(/\/{2,}/g, '/');
+  const file = path.join(project.root, relative);
+  if (fs.existsSync(file) && !options.force) {
+    return { file, status: 'reuse' };
+  }
+  writeFile(file, `${JSON.stringify(mock, null, 2)}\n`, project.dryRun);
+  return { file, status: 'create' };
+}
+
+function generateService(cwd, options) {
+  const project = loadProject(cwd, options);
+  if (!project.spec) throw new Error('OpenAPI spec is required for gen service');
+  const selector = parseOperationSelector(options.operation);
+  const operation = findOperation(project.spec, selector);
+  const artifact = buildArtifacts(project, operation, options);
+  if (artifact.status === 'reuse') {
+    console.log(artifact.message);
+    return artifact;
+  }
+  writeFile(artifact.typingsPath, artifact.nextTypings, project.dryRun);
+  writeFile(artifact.servicePath, artifact.nextService, project.dryRun);
+  patchServiceIndex(
+    path.join(project.serviceDir, 'index.ts'),
+    artifact.domain,
+    toServiceFile(artifact.domain),
+    project.dryRun,
+  );
+  patchRootTypings(project.root, artifact.domain, project.dryRun);
+  const mockResult = writeMock(project, operation, artifact.mock, options);
+  console.log(`${project.dryRun ? '[dry-run] ' : ''}generated ${operation.method.toUpperCase()} ${operation.path} -> ${path.relative(project.root, artifact.servicePath)}#${artifact.fn}`);
+  if (mockResult.file) console.log(`${project.dryRun ? '[dry-run] ' : ''}mock ${path.relative(project.root, mockResult.file)}`);
+  else {
+    console.log(`${operation.method.toUpperCase()} ${operation.path} — success`);
+    console.log(JSON.stringify(artifact.mock, null, 2));
+  }
+  return { ...artifact, mockResult, operation };
+}
+
+module.exports = {
+  generateService,
+  buildArtifacts,
+  resolveDomain,
+};

package/scripts/gen/spec.js

@@ -0,0 +1,220 @@
+const { normalizePath, pathVariants } = require('./names');
+
+function isOAS3(spec) {
+  return Boolean(spec.openapi && String(spec.openapi).startsWith('3'));
+}
+
+function pointerValue(spec, ref) {
+  if (!ref || !ref.startsWith('#/')) return undefined;
+  return ref
+    .slice(2)
+    .split('/')
+    .map((part) => decodeURIComponent(part.replace(/~1/g, '/').replace(/~0/g, '~')))
+    .reduce((value, key) => value?.[key], spec);
+}
+
+function deref(spec, schema, seen = new Set()) {
+  if (!schema) return schema;
+  if (schema.$ref) {
+    if (seen.has(schema.$ref)) return { type: 'object' };
+    const next = new Set(seen);
+    next.add(schema.$ref);
+    const resolved = pointerValue(spec, schema.$ref);
+    if (!resolved) return { type: 'object', description: `unresolved ${schema.$ref}` };
+    return deref(spec, { ...resolved, title: resolved.title || refName(schema.$ref) }, next);
+  }
+  if (Array.isArray(schema.allOf) && schema.allOf.length) {
+    return schema.allOf.reduce(
+      (merged, part) => mergeSchemas(merged, deref(spec, part, seen)),
+      { type: 'object', properties: {}, required: [] },
+    );
+  }
+  return schema;
+}
+
+function refName(ref) {
+  if (!ref) return 'Anonymous';
+  const raw = decodeURIComponent(ref.split('/').pop() || 'Anonymous');
+  return raw.replace(/^transport\./, '').replace(/[^\w]/g, '');
+}
+
+function mergeSchemas(left = {}, right = {}) {
+  return {
+    type: 'object',
+    properties: { ...(left.properties || {}), ...(right.properties || {}) },
+    required: [...new Set([...(left.required || []), ...(right.required || [])])],
+    nullable: left.nullable || right.nullable,
+    description: right.description || left.description,
+  };
+}
+
+function jsonContent(object) {
+  const content = object?.content || {};
+  return (
+    content['application/json'] ||
+    content['application/json; charset=utf-8'] ||
+    content['*/*'] ||
+    Object.values(content)[0]
+  );
+}
+
+function successResponse(operation) {
+  const responses = operation.responses || {};
+  return responses['200'] || responses['201'] || responses['204'] || responses.default;
+}
+
+function collectParameters(spec, pathItem, operation) {
+  const list = [...(pathItem.parameters || []), ...(operation.parameters || [])]
+    .map((item) => (item.$ref ? pointerValue(spec, item.$ref) : item))
+    .filter(Boolean);
+  const pathParams = [];
+  const queryParams = [];
+  let bodySchema;
+  for (const param of list) {
+    const schema = param.schema || param;
+    if (param.in === 'path') pathParams.push({ ...param, schema });
+    else if (param.in === 'query') queryParams.push({ ...param, schema });
+    else if (param.in === 'body') bodySchema = schema;
+  }
+  return { pathParams, queryParams, bodySchema };
+}
+
+function bodyFromOperation(spec, operation, swaggerBody) {
+  if (operation.requestBody) {
+    const media = jsonContent(operation.requestBody);
+    return {
+      schema: media?.schema,
+      contentType: Object.keys(operation.requestBody.content || {})[0] || 'application/json',
+    };
+  }
+  if (swaggerBody) {
+    return { schema: swaggerBody, contentType: 'application/json' };
+  }
+  return { schema: undefined, contentType: undefined };
+}
+
+function successSchema(spec, operation) {
+  const response = successResponse(operation);
+  if (!response) return undefined;
+  if (response.content) return jsonContent(response)?.schema;
+  return response.schema;
+}
+
+function unwrapData(spec, schema) {
+  const resolved = deref(spec, schema);
+  const properties = resolved?.properties || {};
+  if (properties.data && (properties.code || properties.message || properties.msg)) {
+    return properties.data;
+  }
+  return schema;
+}
+
+function listItemSchema(spec, dataSchema) {
+  const resolved = deref(spec, dataSchema);
+  const properties = resolved?.properties || {};
+  if (properties.results?.items) return properties.results.items;
+  if (properties.list?.items) return properties.list.items;
+  if (resolved?.type === 'array' && resolved.items) return resolved.items;
+  return undefined;
+}
+
+function paginationKind(spec, dataSchema) {
+  const resolved = deref(spec, dataSchema);
+  const properties = resolved?.properties || {};
+  if (properties.results && (properties.count || properties.total !== undefined)) {
+    return 'results-count';
+  }
+  if (properties.list && properties.total !== undefined) return 'list-total';
+  return 'unknown';
+}
+
+function findPathKey(spec, apiPath) {
+  const paths = spec.paths || {};
+  const variants = pathVariants(apiPath);
+  return Object.keys(paths).find((key) => variants.includes(normalizePath(key)));
+}
+
+function findOperation(spec, selector) {
+  const paths = spec.paths || {};
+  if (selector.operationId) {
+    for (const [path, pathItem] of Object.entries(paths)) {
+      for (const [method, operation] of Object.entries(pathItem)) {
+        if (['get', 'post', 'put', 'patch', 'delete'].includes(method) && operation.operationId === selector.operationId) {
+          return buildOperation(spec, path, method, pathItem, operation);
+        }
+      }
+    }
+    throw new Error(`operationId not found: ${selector.operationId}`);
+  }
+  if (!selector.path) throw new Error('Operation selector needs a path or operationId');
+  const pathKey = findPathKey(spec, selector.path);
+  if (!pathKey) throw new Error(`Path not found: ${selector.path}`);
+  const pathItem = paths[pathKey];
+  const methods = ['get', 'post', 'put', 'patch', 'delete'].filter((method) => pathItem[method]);
+  const method = (selector.method || (methods.length === 1 ? methods[0] : '')).toLowerCase();
+  if (!method) {
+    throw new Error(`Path ${pathKey} has multiple methods (${methods.join(', ')}). Pass METHOD /path.`);
+  }
+  if (!pathItem[method]) throw new Error(`${method.toUpperCase()} ${pathKey} not found`);
+  return buildOperation(spec, pathKey, method, pathItem, pathItem[method]);
+}
+
+function buildOperation(spec, path, method, pathItem, operation) {
+  const collected = collectParameters(spec, pathItem, operation);
+  const body = bodyFromOperation(spec, operation, collected.bodySchema);
+  const rawSuccess = successSchema(spec, operation);
+  const dataSchema = unwrapData(spec, rawSuccess);
+  return {
+    spec,
+    isOAS3: isOAS3(spec),
+    method,
+    path: normalizePath(path),
+    operationId: operation.operationId,
+    summary: operation.summary || operation.description || '',
+    tags: operation.tags || pathItem.tags || [],
+    pathParams: collected.pathParams,
+    queryParams: collected.queryParams,
+    bodySchema: body.schema,
+    contentType: body.contentType,
+    successSchema: rawSuccess,
+    dataSchema,
+    itemSchema: listItemSchema(spec, dataSchema),
+    pagination: paginationKind(spec, dataSchema),
+  };
+}
+
+function exampleFromSchema(spec, schema, depth = 0) {
+  const resolved = deref(spec, schema);
+  if (!resolved || depth > 6) return null;
+  if (resolved.example !== undefined) return resolved.example;
+  if (resolved.enum?.length) return resolved.enum[0];
+  if (resolved.type === 'array' || resolved.items) {
+    return [exampleFromSchema(spec, resolved.items, depth + 1)];
+  }
+  if (resolved.oneOf?.length) return exampleFromSchema(spec, resolved.oneOf[0], depth + 1);
+  if (resolved.anyOf?.length) return exampleFromSchema(spec, resolved.anyOf[0], depth + 1);
+  const type = resolved.type;
+  if (type === 'integer' || type === 'number') return 1;
+  if (type === 'boolean') return true;
+  if (type === 'string') {
+    if (resolved.format === 'date-time') return '2026-01-01T00:00:00Z';
+    if (resolved.format === 'date') return '2026-01-01';
+    return resolved.title || 'example';
+  }
+  const properties = resolved.properties || {};
+  const object = {};
+  for (const [key, value] of Object.entries(properties)) {
+    object[key] = exampleFromSchema(spec, value, depth + 1);
+  }
+  return object;
+}
+
+module.exports = {
+  isOAS3,
+  pointerValue,
+  deref,
+  refName,
+  findOperation,
+  exampleFromSchema,
+  unwrapData,
+};