@xoong/cli 0.0.0-stage → 0.0.35

package/src/openapi.js

@@ -0,0 +1,474 @@
+// @ts-check
+import { swagger2ToOpenApi3 } from './swagger2.js';
+import { bodySchemaOf } from './body-schema.js';
+/**
+ * OpenAPI 3.x (JSON) -> xoong tables.
+ * Produces:
+ *   operations.json : { operations, entities }   (consumed by @xoong/data at runtime)
+ *   api.d.ts        : TypeScript types for schemas and operations
+ *   problems        : findings for `xoong doctor`
+ */
+
+const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+const MAX_DEPTH = 60; // schemas nest far less than this; deeper means a cycle
+const refName = (ref) => {
+  const seg = ref.slice(ref.lastIndexOf('/') + 1);
+  try { return decodeURIComponent(seg).replace(/~1/g, '/').replace(/~0/g, '~'); } catch { return seg; }
+};
+
+/** Resolve a local "#/a/b" pointer in `doc`; undefined when it does not exist. */
+function resolvePointer(doc, ref) {
+  let node = doc;
+  for (const raw of ref.slice(2).split('/')) {
+    let seg = raw;
+    try { seg = decodeURIComponent(raw); } catch { /* keep raw */ }
+    seg = seg.replace(/~1/g, '/').replace(/~0/g, '~');
+    if (node == null || typeof node !== 'object' || !Object.hasOwn(node, seg)) return undefined;
+    node = node[seg];
+  }
+  return node;
+}
+
+/** Every distinct `$ref` string in the document (iterative: specs can be deeply nested). */
+function collectRefs(doc) {
+  const refs = new Set();
+  const seen = new Set(); // YAML anchors make shared (even cyclic) objects: visit each once
+  const stack = [doc];
+  while (stack.length) {
+    const n = stack.pop();
+    if (seen.has(n)) continue;
+    seen.add(n);
+    if (Array.isArray(n)) { for (const x of n) if (x && typeof x === 'object') stack.push(x); continue; }
+    for (const [k, v] of Object.entries(n)) {
+      if (k === '$ref' && typeof v === 'string') refs.add(v);
+      else if (v && typeof v === 'object') stack.push(v);
+    }
+  }
+  return refs;
+}
+
+/**
+ * @param {any} doc
+ * @param {{ hints?: { idNames?: string[], schemas?: Record<string, { id?: string, entity?: string }>, unwrap?: string, idempotencyKeys?: Record<string, string>, fields?: Record<string, any> } }} [options]
+ *   `hints` lets the frontend declare identity without editing the backend's document:
+ *   { "idNames": ["id", "gid"],                     // any schema with one of these properties is an entity
+ *     "schemas": { "SessionResponse": { "entity": "Session", "id": "session_id" } },
+ *     "unwrap": "data",                              // responses shaped { code, message, data } are read as `data`
+ *     "idempotencyKeys": { "sendMessage": "client_message_id" } }   // a fresh UUID is filled in per call
+ */
+export function analyze(doc, { hints } = {}) {
+  if (doc && typeof doc === 'object' && String(doc.swagger ?? '').startsWith('2')) doc = swagger2ToOpenApi3(doc); // Swagger 2.0 is converted first
+  if (!doc || typeof doc !== 'object' || !String(doc.openapi ?? '').startsWith('3')) {
+    throw new Error('xoong: expected an OpenAPI 3.x document (field "openapi" starting with "3")');
+  }
+  const schemas = { ...(doc.components?.schemas ?? {}) }; // a copy: hints must not modify the caller's document
+  for (const [name, h] of Object.entries(hints?.schemas ?? {})) {
+    if (!schemas[name]) throw new Error(`xoong: hints refer to unknown schema "${name}"`);
+    schemas[name] = { ...schemas[name], ...(h.id ? { 'x-xoong-id': h.id } : {}), ...(h.entity ? { 'x-xoong-entity': h.entity } : {}) };
+  }
+  /** @type {{level:'error'|'warn', code:string, where:string, message:string, fix:string}[]} */
+  const problems = [];
+  if (!doc.paths && !doc.webhooks) {
+    problems.push({ level: 'error', code: 'XO100', where: '#/paths', message: 'the document has no "paths"', fix: 'Add a paths object (OpenAPI requires it unless the document only declares webhooks/components)' });
+  }
+  const missing = [];
+  for (const ref of collectRefs(doc)) {
+    if (!ref.startsWith('#/')) problems.push({ level: 'warn', code: 'XO151', where: ref, message: 'external $ref is not resolved by xoong', fix: 'Bundle the document so all references are local (for example with redocly bundle)' });
+    else if (resolvePointer(doc, ref) === undefined) missing.push(ref);
+  }
+  for (const ref of missing) problems.push({ level: 'error', code: 'XO150', where: ref, message: `$ref points to something that does not exist`, fix: 'Define the target or remove the reference' });
+  const resolve = (s) => (s?.$ref ? schemas[refName(s.$ref)] : s);
+
+  // --- entity detection: component schemas with an identity property
+  /** schema name -> id property; schema name -> entity name (several schemas may be one entity) */
+  /** @type {Record<string, string>} */
+  const idKeys = {};
+  /** @type {Record<string, string>} */
+  const entityOf = {};
+  for (const [name, schema] of Object.entries(schemas)) {
+    const props = collectProps(schema, schemas);
+    const explicit = schema['x-xoong-id'];
+    if (explicit) {
+      // One property, or several for a composite identity (Kubernetes: ["namespace", "name"]).
+      const absent = [].concat(explicit).filter((k) => !props[k]);
+      if (!absent.length) { idKeys[name] = explicit; entityOf[name] = schema['x-xoong-entity'] ?? name; }
+      else problems.push({ level: 'error', code: 'XO101', where: `#/components/schemas/${name}`, message: `x-xoong-id "${absent[0]}" is not a property of ${name}`, fix: 'Name existing properties or remove x-xoong-id' });
+    } else {
+      // Conventional identity: `id`, or the first property named in hints.idNames (for example "gid" or "pk").
+      const key = ['id', ...(hints?.idNames ?? [])].find((k) => props[k]);
+      if (key) { idKeys[name] = key; entityOf[name] = schema['x-xoong-entity'] ?? name; }
+    }
+  }
+
+  const isScalarSchema = (s) => !!s && !s.$ref && !s.properties && !s.allOf && !s.oneOf && !s.anyOf && (['string', 'integer', 'number', 'boolean', 'null'].includes(s.type) || (Array.isArray(s.type) && s.type.every((t) => ['string', 'integer', 'number', 'boolean', 'null'].includes(t))));
+  const single = (p) => (p && 'const' in p ? p.const : p?.enum?.length === 1 ? p.enum[0] : undefined);
+  /**
+   * How to tell the members of a oneOf/anyOf apart: the OpenAPI `discriminator`, or a property that
+   * every member declares with one fixed value (`type: "file"`, Stripe's `object: "customer"`).
+   * Returns { key, values[] } aligned with `members`, or null.
+   */
+  const unionTag = (schema, members) => {
+    const d = schema.discriminator;
+    if (d?.propertyName) {
+      const values = members.map((m) => {
+        if (!m.$ref) return undefined;
+        const mapped = Object.entries(d.mapping ?? {}).find(([, target]) => target === m.$ref || String(target).endsWith('/' + refName(m.$ref)));
+        return mapped ? mapped[0] : refName(m.$ref);
+      });
+      return values.every((v) => v !== undefined) ? { key: d.propertyName, values } : null;
+    }
+    const propsOf = members.map((m) => collectProps(m, schemas));
+    const fixed = (p, key) => single(p[key] && (p[key].$ref ? schemas[refName(p[key].$ref)] : p[key]));
+    // 1) a property every member fixes to a different value
+    for (const key of Object.keys(propsOf[0] ?? {})) {
+      const values = propsOf.map((p) => fixed(p, key));
+      if (values.every((v) => v !== undefined) && new Set(values).size === values.length) return { key, values };
+    }
+    // 2) a property that all but one member fixes (Stripe: `deleted: true` marks deleted_customer; plain customer lacks it)
+    const keys = new Set(propsOf.flatMap((p) => Object.keys(p)));
+    for (const key of keys) {
+      const values = propsOf.map((p) => fixed(p, key));
+      const untagged = values.map((v, i) => (v === undefined ? i : -1)).filter((i) => i >= 0);
+      const tagged = values.filter((v) => v !== undefined);
+      if (untagged.length === 1 && new Set(tagged).size === tagged.length) return { key, values, fallback: untagged[0] };
+    }
+    return null;
+  };
+
+  /** Names of the members of the first oneOf/anyOf of 2+ entities found in a response that xoong cannot tell apart (looking through refs, arrays and properties). */
+  const unresolvedUnion = (schema, seen = new Set(), depth = 0) => {
+    if (!schema || depth > 5) return undefined;
+    if (schema.$ref) {
+      const n = refName(schema.$ref);
+      if (seen.has(n)) return undefined;
+      return unresolvedUnion(schemas[n], new Set(seen).add(n), depth + 1);
+    }
+    const alt = (schema.oneOf ?? schema.anyOf)?.filter((s) => !isScalarSchema(s));
+    const entities = alt?.filter((s) => s.$ref && idKeys[refName(s.$ref)]) ?? [];
+    if (entities.length > 1 && !describe(schema)) return entities.map((s) => refName(s.$ref));
+    for (const child of [schema.items, ...(schema.allOf ?? []), ...Object.values(schema.properties ?? {})]) {
+      const found = unresolvedUnion(child, seen, depth + 1);
+      if (found) return found;
+    }
+    return undefined;
+  };
+
+  /** Schema -> runtime descriptor (null when it contains no entities). */
+  const describe = (schema, seen = new Set(), depth = 0) => {
+    if (!schema || depth > MAX_DEPTH) return null; // depth cap: YAML aliases can make a schema contain itself
+    if (schema.$ref) {
+      const name = refName(schema.$ref);
+      // `replace`: this schema is the entity's own full schema, so a response replaces the stored record (fields the
+      // server stopped sending disappear). Schemas that share an entity through hints, or are marked x-xoong-partial, merge.
+      if (idKeys[name]) return { t: 'entity', name: entityOf[name], ...(entityOf[name] === name && !schemas[name]['x-xoong-partial'] ? { replace: true } : {}) };
+      if (seen.has(name)) return null;
+      return describe(schemas[name], new Set(seen).add(name), depth + 1);
+    }
+    const alternatives = schema.oneOf ?? schema.anyOf;
+    if (alternatives) {
+      // Plain values (`string`, `null`) are ignored: Stripe-style "id or expanded object" is just the object.
+      const real = alternatives.filter((s) => !isScalarSchema(s));
+      if (real.length === 0) return null;
+      if (real.length === 1) return describe(real[0], seen, depth + 1);
+      // Several object shapes: usable when a tag property tells them apart, or each has a required property no other has.
+      const tag = unionTag(schema, real);
+      if (!tag) {
+        const sets = real.map((s) => {
+          const resolved = s.$ref ? schemas[refName(s.$ref)] : s;
+          return { props: new Set(Object.keys(collectProps(s, schemas))), required: [...new Set([...(resolved?.required ?? []), ...(resolved?.allOf ?? []).flatMap((p) => (p.$ref ? schemas[refName(p.$ref)] : p)?.required ?? [])])] };
+        });
+        const has = [];
+        for (let i = 0; i < real.length; i++) {
+          const prop = sets[i].required.find((k) => sets.every((o, j) => j === i || !o.props.has(k)));
+          const d = prop && describe(real[i], seen, depth + 1);
+          if (!prop || !d) return null; // one member cannot be recognised: leave the union alone (doctor reports XO160)
+          has.push([prop, d]);
+        }
+        return { t: 'union', has };
+      }
+      const map = {};
+      real.forEach((s, i) => {
+        const d = describe(s, seen, depth + 1);
+        if (d && tag.values[i] !== undefined) map[tag.values[i]] = d;
+      });
+      const fallback = tag.fallback !== undefined ? describe(real[tag.fallback], seen, depth + 1) : null;
+      if (!Object.keys(map).length && !fallback) return null;
+      return { t: 'union', key: tag.key, map, ...(fallback ? { default: fallback } : {}) };
+    }
+    if (schema.allOf) {
+      const props = {};
+      for (const part of schema.allOf) {
+        const d = describe(part, seen, depth + 1);
+        if (d?.t === 'object') Object.assign(props, d.props);
+        else if (d?.t === 'entity') return d;
+      }
+      return Object.keys(props).length ? { t: 'object', props } : null;
+    }
+    if (schema.type === 'array') {
+      const items = describe(schema.items, seen, depth + 1);
+      return items ? { t: 'array', items } : null;
+    }
+    if (schema.properties) {
+      const props = {};
+      for (const [k, v] of Object.entries(schema.properties)) {
+        const d = describe(v, seen, depth + 1);
+        if (d) props[k] = d;
+      }
+      return Object.keys(props).length ? { t: 'object', props } : null;
+    }
+    return null;
+  };
+
+  const entities = {};
+  for (const name of Object.keys(idKeys)) {
+    const entity = entityOf[name];
+    const props = { ...(entities[entity]?.props ?? {}) };
+    for (const [k, v] of Object.entries(collectProps(schemas[name], schemas))) {
+      const d = describe(v);
+      if (d) props[k] = d;
+    }
+    if (entities[entity] && JSON.stringify(entities[entity].id) !== JSON.stringify(idKeys[name])) {
+      problems.push({ level: 'error', code: 'XO102', where: `#/components/schemas/${name}`, message: `entity "${entity}" has conflicting id properties ("${entities[entity].id}" and "${idKeys[name]}")`, fix: 'Use the same id property for every schema mapped to one entity' });
+      continue;
+    }
+    entities[entity] = { id: idKeys[name], ...(Object.keys(props).length ? { props } : {}) };
+  }
+
+  // --- operations
+  const operations = {};
+  const used = new Set();
+  for (const [path, item] of Object.entries(doc.paths ?? {})) {
+    for (const method of METHODS) {
+      const o = item[method];
+      if (!o) continue;
+      let id = o.operationId;
+      if (!id) {
+        id = `${method}${path.replace(/[{}]/g, '').split(/[/\-_]+/).filter(Boolean).map((p) => p[0].toUpperCase() + p.slice(1)).join('')}`;
+        problems.push({ level: 'warn', code: 'XO110', where: `${method.toUpperCase()} ${path}`, message: 'operation has no operationId', fix: `Add operationId (xoong would use "${id}")` });
+      }
+      if (used.has(id)) {
+        problems.push({ level: 'error', code: 'XO111', where: `${method.toUpperCase()} ${path}`, message: `duplicate operationId "${id}"`, fix: 'Make operationIds unique' });
+        continue;
+      }
+      used.add(id);
+      const merged = new Map();
+      for (const raw of [...(item.parameters ?? []), ...(o.parameters ?? [])]) {
+        const p = raw?.$ref ? resolvePointer(doc, raw.$ref) : raw;
+        if (p?.name && p.in) merged.set(`${p.in}:${p.name}`, p); // operation-level overrides path-level
+      }
+      const params = [...merged.values()];
+      const pathParams = params.filter((p) => p.in === 'path');
+      const declared = [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+      for (const name of declared) if (!pathParams.some((p) => p.name === name)) {
+        problems.push({ level: 'warn', code: 'XO112', where: `${method.toUpperCase()} ${path}`, message: `path parameter "${name}" is not documented`, fix: 'Declare it under parameters with in: path' });
+      }
+      const okCode = Object.keys(o.responses ?? {}).find((c) => /^2\d\d$/.test(c));
+      const okContent = okCode ? resolve(o.responses[okCode])?.content : undefined;
+      const stream = !!okContent?.['text/event-stream'] && !okContent['application/json'];
+      let okSchema = okContent?.['application/json']?.schema;
+      let unwrap;
+      if (hints?.unwrap && okSchema && collectProps(resolve(okSchema), schemas)[hints.unwrap]) {
+        unwrap = hints.unwrap; // { code, message, data } envelopes: the screen sees `data`
+        okSchema = collectProps(resolve(okSchema), schemas)[unwrap];
+      }
+      const reqContent = o.requestBody?.content ?? {};
+      const multipart = !reqContent['application/json'] && !!reqContent['multipart/form-data'];
+      const bodySchema = (reqContent['application/json'] ?? (multipart ? reqContent['multipart/form-data'] : undefined))?.schema;
+      const uuid = hints?.idempotencyKeys?.[id];
+      if (uuid && !(bodySchema && collectProps(resolve(bodySchema), schemas)[uuid])) {
+        problems.push({ level: 'error', code: 'XO170', where: `${method.toUpperCase()} ${path}`, message: `hint idempotencyKeys.${id} names "${uuid}", which is not a field of the request body`, fix: 'Name an existing body property or remove the hint' });
+      }
+      const hasBody = !!o.requestBody;
+      const response = describe(okSchema);
+      if (method === 'get' && okCode && !okSchema && okCode !== '204' && !stream) {
+        problems.push({ level: 'warn', code: 'XO120', where: `GET ${path}`, message: 'success response has no application/json schema', fix: 'Describe the response schema so types and caching can be generated' });
+      }
+      const union = unresolvedUnion(okSchema);
+      if (union) {
+        const names = union.slice(0, 4).join(' | ') + (union.length > 4 ? ' | ...' : '');
+        problems.push({ level: 'warn', code: 'XO160', where: `${method.toUpperCase()} ${path}`, message: `the response contains a union of entities (${names}) with no way to tell them apart, so they are not stored in the shared entity store`, fix: 'Give the members a property with one fixed value each (for example type: "file") or an OpenAPI discriminator' });
+      }
+      const hasError = Object.keys(o.responses ?? {}).some((c) => /^[45]/.test(c) || c === 'default');
+      if (!hasError) problems.push({ level: 'warn', code: 'XO130', where: `${method.toUpperCase()} ${path}`, message: 'no error responses documented', fix: 'Document 4xx/5xx or default with application/problem+json' });
+      const lost = [];
+      const builtBodyNode = bodySchema && !multipart ? bodySchemaOf(bodySchema, schemas, hints, lost) : undefined;
+      const builtBody = () => builtBodyNode;
+      for (const where of new Set(lost)) problems.push({ level: 'warn', code: 'XO161', where: `${method.toUpperCase()} ${path}`, message: `a union in ${where} cannot be told apart, so a generated form draws it as free-form`, fix: 'Add a discriminator (propertyName) or give each member a property with one fixed value (const or a one-value enum)' });
+      operations[id] = {
+        id, method: method.toUpperCase(), path,
+        ...(params.some((p) => p.in === 'query') ? { query: params.filter((p) => p.in === 'query').map((p) => p.name) } : {}),
+        ...(hasBody ? { body: true } : {}),
+        ...(multipart ? { multipart: true } : {}),
+        ...(uuid ? { uuid: [uuid] } : {}),
+        ...(unwrap ? { unwrap } : {}),
+        ...(stream ? { stream: true } : {}),
+        ...(bodyFieldsOf(bodySchema, schemas) ? { bodyFields: bodyFieldsOf(bodySchema, schemas) } : {}),
+        ...(bodySkippedOf(bodySchema, schemas) ? { bodySkipped: bodySkippedOf(bodySchema, schemas) } : {}),
+        ...(bodySchema && !multipart && builtBody(bodySchema) ? { bodySchema: builtBody(bodySchema) } : {}),
+        ...(response ? { response } : {}),
+      };
+      operations[id]._types = { params, okSchema, bodySchema };
+    }
+  }
+
+  for (const [name, schema] of Object.entries(schemas)) {
+    const candidate = !idKeys[name] && schema.type === 'object' && !/Request$/.test(name) ? identityCandidate(name, schema, schemas, hints?.idNames ?? []) : undefined;
+    if (candidate) {
+      problems.push({ level: 'warn', code: 'XO140', where: `#/components/schemas/${name}`, message: `${name} has "${candidate}" but is not treated as an entity, so it is stored inline and not shared between screens`, fix: `If instances repeat across responses, add a hint { "schemas": { "${name}": { "id": "${candidate}" } } } (or "x-xoong-id" in the document); otherwise ignore` });
+    }
+  }
+  return { operations, entities, schemas, problems };
+}
+
+/**
+ * The flat, primitive fields of a request body, for generated forms (`<xo-form>`) and typed form values.
+ * Nested objects and arrays are left out: a form for them is hand-written.
+ * @returns {{ name: string, type: string, required?: true, format?: string, enum?: any[], maxLength?: number, title?: string }[] | undefined}
+ */
+function bodyFieldsOf(schema, schemas) {
+  const root = schema?.$ref ? schemas[refName(schema.$ref)] : schema;
+  if (!root || root.type !== 'object' && !root.properties && !root.allOf) return undefined;
+  const required = new Set([...(root.required ?? []), ...(root.allOf ?? []).flatMap((p) => (p.$ref ? schemas[refName(p.$ref)] : p)?.required ?? [])]);
+  const out = [];
+  for (const [name, raw] of Object.entries(collectProps(root, schemas))) {
+    const prop = raw?.$ref ? schemas[refName(raw.$ref)] : raw;
+    if (!prop || !['string', 'integer', 'number', 'boolean'].includes(prop.type) || prop.readOnly) continue;
+    const file = prop.type === 'string' && prop.format === 'binary';
+    out.push({
+      name, type: file ? 'file' : prop.type,
+      ...(required.has(name) ? { required: true } : {}),
+      ...(prop.format && !file ? { format: prop.format } : {}),
+      ...(prop.enum ? { enum: prop.enum } : {}),
+      ...(prop.maxLength ? { maxLength: prop.maxLength } : {}),
+      ...(prop.title ? { title: prop.title } : {}),
+    });
+  }
+  return out.length ? out : undefined;
+}
+/**
+ * Request body properties that `bodyFieldsOf` leaves out (nested objects, arrays, unions), so tools can warn when a *required*
+ * one is missing from a generated form: that form can never succeed.
+ * @returns {{ name: string, type: string, required?: true }[] | undefined}
+ */
+function bodySkippedOf(schema, schemas) {
+  const root = schema?.$ref ? schemas[refName(schema.$ref)] : schema;
+  if (!root || root.type !== 'object' && !root.properties && !root.allOf) return undefined;
+  const required = new Set([...(root.required ?? []), ...(root.allOf ?? []).flatMap((p) => (p.$ref ? schemas[refName(p.$ref)] : p)?.required ?? [])]);
+  const out = [];
+  for (const [name, raw] of Object.entries(collectProps(root, schemas))) {
+    const prop = raw?.$ref ? schemas[refName(raw.$ref)] : raw;
+    if (!prop || prop.readOnly || ['string', 'integer', 'number', 'boolean'].includes(prop.type)) continue;
+    out.push({ name, type: prop.type ?? (prop.oneOf || prop.anyOf ? 'union' : 'object'), ...(required.has(name) ? { required: true } : {}) });
+  }
+  return out.length ? out : undefined;
+}
+function collectProps(schema, schemas, seen = new Set()) {
+  if (!schema) return {};
+  if (schema.$ref) {
+    const name = refName(schema.$ref);
+    if (seen.has(name)) return {}; // circular allOf
+    return collectProps(schemas[name], schemas, new Set(seen).add(name));
+  }
+  let props = { ...(schema.properties ?? {}) };
+  for (const part of schema.allOf ?? []) props = { ...collectProps(part, schemas, seen), ...props };
+  return props;
+}
+/**
+ * A property that looks like the schema's own identity, excluding plain `id` (handled elsewhere):
+ * a conventional name (uuid, guid, gid, uid, pk) or `<stem>_id` / `<stem>Id` where the stem occurs in
+ * the schema name (session_id in SessionResponse). Foreign keys to other things (task_id in PendingAction) are ignored.
+ */
+function identityCandidate(name, schema, schemas, taken = []) {
+  const flat = name.toLowerCase().replace(/[^a-z0-9]/g, '');
+  return Object.keys(collectProps(schema, schemas)).find((k) => {
+    if (k === 'id' || taken.includes(k)) return false;
+    if (/^(uuid|guid|gid|uid|pk)$/i.test(k)) return true;
+    const m = /^(.+?)(?:_id|Id)$/.exec(k);
+    return !!m && flat.includes(m[1].toLowerCase().replace(/[^a-z0-9]/g, ''));
+  });
+}
+
+// ---------------------------------------------------------------- TypeScript
+
+const ident = (s) => (/^[A-Za-z_$][\w$]*$/.test(s) ? s : JSON.stringify(s));
+
+/** Words that cannot (or must not) be used as a generated type name. */
+const RESERVED = new Set(('break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await async type any unknown never object string number boolean symbol bigint undefined Record Array Operations Partial Readonly Promise').split(' '));
+
+/** A schema name as a valid TypeScript type name (Dto.User -> Dto_User, import -> import_). */
+export function typeName(name) {
+  let t = name.replace(/[^A-Za-z0-9_$]/g, '_');
+  if (/^[0-9]/.test(t)) t = '_' + t;
+  return RESERVED.has(t) ? t + '_' : t;
+}
+
+/** Unique TypeScript names for every schema (two schemas never share a name). */
+export function typeNames(schemas) {
+  const used = new Set();
+  const map = new Map();
+  for (const name of Object.keys(schemas)) {
+    let t = typeName(name);
+    while (used.has(t)) t += '_';
+    used.add(t);
+    map.set(name, t);
+  }
+  return map;
+}
+
+/** JSON-Schema-ish -> TypeScript type text. `names` maps schema names to type names (refs to unknown schemas become `unknown`). */
+export function tsType(schema, depth = 0, names = null, hops = 0) {
+  if (!schema || hops > MAX_DEPTH) return 'unknown'; // hops counts every nesting step (arrays and unions too), so a cycle ends
+  if (schema.$ref) {
+    const n = refName(schema.$ref);
+    if (names) return names.get(n) ?? 'unknown';
+    return typeName(n);
+  }
+  const nullable = schema.nullable ? ' | null' : '';
+  if ('const' in schema) return JSON.stringify(schema.const) + nullable;
+  if (schema.enum) return (schema.enum.length ? schema.enum.map((v) => JSON.stringify(v)).join(' | ') : 'never') + nullable;
+  if (schema.allOf) return schema.allOf.map((s) => tsType(s, depth, names, hops + 1)).join(' & ') + nullable;
+  if (schema.oneOf || schema.anyOf) return (schema.oneOf ?? schema.anyOf).map((s) => tsType(s, depth, names, hops + 1)).join(' | ') + nullable;
+  const type = Array.isArray(schema.type) ? schema.type : [schema.type];
+  const parts = type.map((t) => {
+    switch (t) {
+      case 'string': return 'string';
+      case 'integer': case 'number': return 'number';
+      case 'boolean': return 'boolean';
+      case 'null': return 'null';
+      case 'array': return `Array<${tsType(schema.items, depth, names, hops + 1)}>`;
+      case 'object': case undefined: {
+        const props = Object.entries(schema.properties ?? {});
+        if (!props.length) return schema.additionalProperties && schema.additionalProperties !== true ? `Record<string, ${tsType(schema.additionalProperties, depth, names, hops + 1)}>` : t === 'object' ? 'Record<string, unknown>' : 'unknown';
+        const pad = '  '.repeat(depth + 1);
+        const req = new Set(schema.required ?? []);
+        return `{\n${props.map(([k, v]) => `${pad}${ident(k)}${req.has(k) ? '' : '?'}: ${tsType(v, depth + 1, names, hops + 1)};`).join('\n')}\n${'  '.repeat(depth)}}`;
+      }
+      default: return 'unknown';
+    }
+  });
+  return parts.join(' | ') + nullable;
+}
+
+/** @param {ReturnType<typeof analyze>} a */
+export function generateDts(a) {
+  const out = ['// Generated by `xoong sync`. Do not edit.\n'];
+  const names = typeNames(a.schemas);
+  for (const [name, schema] of Object.entries(a.schemas)) out.push(`export type ${names.get(name)} = ${tsType(schema, 0, names)};\n`);
+  out.push('export interface Operations {');
+  for (const o of Object.values(a.operations)) {
+    const t = o._types;
+    const seen = new Set();
+    const params = t.params.filter((p) => (p.in === 'path' || p.in === 'query') && !seen.has(p.name) && seen.add(p.name));
+    const paramsT = params.length ? `{ ${params.map((p) => `${ident(p.name)}${p.in === 'path' || p.required ? '' : '?'}: ${tsType(p.schema, 0, names)}`).join('; ')} }` : 'Record<string, never>';
+    out.push(`  ${ident(o.id)}: { method: ${JSON.stringify(o.method)}; path: ${JSON.stringify(o.path)}; params: ${paramsT}; body: ${t.bodySchema ? tsType(t.bodySchema, 2, names) : 'never'}; response: ${t.okSchema ? tsType(t.okSchema, 2, names) : 'void'} };`);
+  }
+  out.push('}\n');
+  return out.join('\n');
+}
+
+/** Strip build-only data before writing operations.json. */
+export function runtimeTable(a) {
+  const operations = {};
+  for (const [id, { _types, ...rest }] of Object.entries(a.operations)) operations[id] = rest;
+  return { version: 1, operations, entities: a.entities };
+}

package/src/scaffold.js

@@ -0,0 +1,159 @@
+// @ts-check
+import { mkdir, writeFile, copyFile, access } from 'node:fs/promises';
+import { join, basename, resolve } from 'node:path';
+import { analyze, runtimeTable, generateDts } from './openapi.js';
+import { load } from './commands.js';
+
+const SCALAR = new Set(['string', 'integer', 'number', 'boolean']);
+const refName = (r) => r.slice(r.lastIndexOf('/') + 1);
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
+
+/**
+ * Pick a first screen: a GET operation without path parameters whose response is (or contains) a list of objects.
+ * Returns { operation, listPath, columns } or null.
+ */
+export function pickListScreen(a) {
+  const deref = (s) => (s?.$ref ? a.schemas[refName(s.$ref)] : s);
+  const columnsOf = (item) => {
+    const schema = deref(item);
+    const props = { ...(schema?.properties ?? {}) };
+    for (const part of schema?.allOf ?? []) Object.assign(props, deref(part)?.properties ?? {});
+    return Object.entries(props).filter(([, v]) => SCALAR.has(deref(v)?.type)).map(([k]) => k).slice(0, 4);
+  };
+  for (const op of Object.values(a.operations)) {
+    if (op.method !== 'GET' || /\{/.test(op.path)) continue;
+    const root = deref(op._types.okSchema);
+    if (!root) continue;
+    if (root.type === 'array') { const columns = columnsOf(root.items); if (columns.length) return { operation: op, listPath: '.', columns }; }
+    for (const [key, v] of Object.entries(root.properties ?? {})) {
+      const prop = deref(v);
+      if (prop?.type === 'array') { const columns = columnsOf(prop.items); if (columns.length) return { operation: op, listPath: key, columns }; }
+    }
+  }
+  return null;
+}
+
+/** HTML for the first screen. */
+export function listScreenHtml(pick, title) {
+  let view = '    <p>No list operation found in the API; add a screen by hand.</p>';
+  if (pick) {
+    const heading = pick.columns.map((c) => `<th>${esc(c)}</th>`).join('');
+    const cells = pick.columns.map((c) => `<td>{${c}}</td>`).join('');
+    const op = pick.operation;
+    view = `    <xo-view get="${esc(op.method + ' ' + op.path)}">
+      <p xo-if="$loading">Loading…</p>
+      <p xo-if="$error" class="error">{$error.code} {$error.detail}</p>
+      <table>
+        <thead><tr>${heading}</tr></thead>
+        <tbody><tr xo-each="${pick.listPath}">${cells}</tr></tbody>
+      </table>
+    </xo-view>`;
+  }
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${esc(title)}</title>
+  <link rel="icon" href="data:,">
+  <link rel="stylesheet" href="/src/app.css">
+  <script type="module" src="/src/main.ts"></script>
+</head>
+<body>
+  <main>
+    <h1>${esc(title)}</h1>
+${view}
+  </main>
+</body>
+</html>
+`;
+}
+
+/**
+ * Create a project folder from an OpenAPI document.
+ * @param {string} dir  target folder (created; must not contain files we would overwrite)
+ * @param {{ spec: string, title?: string, link?: string }} options  `link`: path to a checkout of xoong; the project then depends on its packages by path (they are not published yet)
+ */
+export async function scaffold(dir, { spec, title, link }) {
+  const target = resolve(dir);
+  try { await access(join(target, 'package.json')); throw new Error(`xoong: ${target} already contains a project (package.json exists)`); } catch (error) {
+    if (!/ENOENT/.test(String(/** @type {any} */ (error)?.code))) throw error;
+  }
+  const doc = await load(spec);
+  const a = analyze(doc);
+  const name = basename(target).toLowerCase().replace(/[^a-z0-9-]/g, '-') || 'xoong-app';
+  const pick = pickListScreen(a);
+  const heading = title ?? doc.info?.title ?? name;
+  const pkg = (n) => (link ? `file:${resolve(link, 'packages', n)}` : '*');
+
+  await mkdir(join(target, 'src'), { recursive: true });
+  await mkdir(join(target, 'test'), { recursive: true });
+  await mkdir(join(target, '.xoong'), { recursive: true });
+  const files = {
+    'package.json': JSON.stringify({
+      name, version: '0.0.0', private: true, type: 'module',
+      scripts: { dev: 'xoong dev', sync: 'xoong sync openapi.json --hints xoong.hints.json', check: 'xoong check index.html', test: 'vitest run' },
+      dependencies: { '@xoong/core': pkg('core'), '@xoong/data': pkg('data'), '@xoong/ui': pkg('ui') },
+      devDependencies: { '@xoong/cli': pkg('cli'), '@xoong/test': pkg('test'), vitest: '*', 'happy-dom': '*' },
+      // The packages depend on each other by name: point those names at the checkout too.
+      ...(link ? { overrides: Object.fromEntries(['core', 'data', 'forms', 'ui', 'cli', 'test', 'server'].map((n) => [`@xoong/${n}`, pkg(n)])) } : {}),
+    }, null, 2) + '\n',
+    'xoong.config.json': JSON.stringify({ port: 5173, proxy: { '/api': 'http://localhost:8080' } }, null, 2) + '\n',
+    'xoong.hints.json': JSON.stringify({ idNames: ['id'] }, null, 2) + '\n',
+    'index.html': listScreenHtml(pick, heading),
+    'src/main.ts': `import { configure } from '@xoong/data';
+import '@xoong/data/view';
+import operations from '/.xoong/operations.json' with { type: 'json' };
+
+// The generated table describes every operation; requests go through the dev proxy (see xoong.config.json).
+configure({ api: operations, baseUrl: '/api' });
+
+// Mutation failures arrive as bubbling events; show them however you like.
+document.addEventListener('xo-error', (event) => console.warn((event as CustomEvent).detail));
+`,
+    'src/app.css': `:root { --space: 1rem; --border: #d0d7de; --accent: #0b5fff; }
+body { font: 16px/1.5 system-ui, sans-serif; margin: 0; }
+main { max-width: 60rem; margin: 0 auto; padding: var(--space); }
+table { width: 100%; border-collapse: collapse; }
+th, td { text-align: left; padding: .5rem; border-bottom: 1px solid var(--border); }
+.error { color: #b42318; }
+`,
+    'vitest.config.mjs': `import { defineConfig } from 'vitest/config';
+export default defineConfig({ test: { environment: 'happy-dom', include: ['test/**/*.spec.{mjs,js,ts}'] } });
+`,
+    'test/index.spec.mjs': pick ? `import { it, expect, afterEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { mount, mockApi } from '@xoong/test';
+import operations from '../.xoong/operations.json';
+
+let screen;
+afterEach(() => screen?.unmount());
+
+it('shows the ${esc(pick.operation.path)} list', async () => {
+  const api = mockApi(operations, { ${JSON.stringify(pick.operation.id)}: () => ${pick.listPath === '.' ? '[]' : `({ ${pick.listPath}: [] })`} });
+  const html = readFileSync('index.html', 'utf8').match(/<xo-view[\\s\\S]*<\\/xo-view>/)[0];
+  screen = await mount(html, { api });
+  expect(api.unhandled).toEqual([]);
+  expect(screen.errors).toEqual([]);
+});
+` : '',
+    'README.md': `# ${heading}
+
+Generated by \`xoong new\` from \`openapi.json\`.
+
+\`\`\`bash
+npm install
+npm run sync     # regenerate .xoong/ after the API changes
+npm run check    # check the HTML screens against the API
+npm run dev      # http://localhost:5173 (proxies /api to xoong.config.json)
+npm test
+\`\`\`
+`,
+  };
+  for (const [file, content] of Object.entries(files)) if (content) await writeFile(join(target, file), content);
+  await writeFile(join(target, 'openapi.json'), JSON.stringify(doc, null, 2) + '\n');
+  // Same output as `xoong sync` (kept in step by sharing the functions).
+  await writeFile(join(target, '.xoong', 'operations.json'), JSON.stringify(runtimeTable(a), null, 2) + '\n');
+  await writeFile(join(target, '.xoong', 'api.d.ts'), generateDts(a));
+  return { dir: target, screen: pick ? `${pick.operation.method} ${pick.operation.path}` : null, files: Object.keys(files).filter((f) => files[f]).concat('openapi.json', '.xoong/operations.json', '.xoong/api.d.ts') };
+}