@volter/twin-standard 1.0.0

package/src/spec-ir.ts

@@ -0,0 +1,689 @@
+// THE SPEC IR — one representation of a vendor's published surface, beneath every spec format, that
+// the derived-pack generator reads (docs/contributing/architecture.md, "Protocol 3"). A front end
+// turns a spec into the IR; the generator only ever sees the IR. `fromOpenAPI` is the first front end, and `fromSmithy`
+// reads an AWS Smithy JSON model
+// (OpenAPI 3.x; Stripe's vendor extensions `x-resourceId` and `x-expandableFields` are read where
+// present). Pure and deterministic: the same document always yields the same IR, byte for byte.
+
+type Json = any;
+
+export type OperationClass = 'create' | 'retrieve' | 'list' | 'update' | 'delete' | 'action' | 'computed' | 'non-resource';
+export const CRUD_CLASSES: ReadonlySet<OperationClass> = new Set(['create', 'retrieve', 'list', 'update', 'delete']);
+
+/** A parameter or body field: its name, type and whether it is required, and the numeric bounds the spec states
+ *  (`minimum`, `maximum`), which a strict body (the manifest's `body.strict`, `ctx.fields`) refuses outside of. */
+export type IrParam = { name: string; type: string; required: boolean; minimum?: number; maximum?: number };
+
+/** A schema's stated numeric bounds, when it states any. */
+function boundsOf(doc: Json, schema: Json): { minimum?: number; maximum?: number } {
+  const s = deref(doc, schema);
+  return { ...(typeof s?.minimum === 'number' ? { minimum: s.minimum } : {}), ...(typeof s?.maximum === 'number' ? { maximum: s.maximum } : {}) };
+}
+
+export type IrOperation = {
+  /** The spec's operationId, or the `method_path` slug when the spec has none. */
+  id: string;
+  method: string;
+  path: string;
+  /** Query values that tell this operation from another at the same method and path (a spec key
+   *  such as `/responses?beta=true`); `null`: the key present with any value (S3's UploadPart, `uploadId`). */
+  discriminator?: Record<string, string | null>;
+  /** request headers that name the operation (AWS JSON's X-Amz-Target), for a wire whose operations share a path;
+   *  `null`: the header present with any value (S3's CopyObject, `x-amz-copy-source`) */
+  headers?: Record<string, string | null>;
+  pathParams: string[];
+  /** The spec's own grouping of the operation, where it has one (a client-derived spec: the client library that makes
+   *  the call), which names the family file its handler is written in; absent, the family is the path's (the grade's
+   *  interim rule) */
+  family?: string;
+  /** The path the operation's own server puts before it, when its path item or operation names a server of its own
+   *  (OpenAPI's path-level `servers`: Upstash's /auditlogs at https://api.upstash.com, beside the document's /v2) */
+  basePath?: string;
+  query: IrParam[];
+  /** Top-level body fields; `bodyEncoding` says how the vendor reads them. */
+  body: IrParam[];
+  bodyEncoding: 'json' | 'form' | 'multipart' | 'xml' | 'none';
+  /** A form-encoded operation's number and boolean fields, by bracket path (formScalarsOf). */
+  scalars?: Record<string, 'integer' | 'number' | 'boolean'>;
+  successStatus: number;
+  /** the success is documented with no content at all (a 200 with nothing in it) */
+  emptySuccess?: true;
+  /** The success answer may be a server-sent event stream (`text/event-stream`). */
+  streams?: boolean;
+  /** The resource the success answer is (or lists), when it is one: the first of a union, whose
+   *  other members are `alternatives` (a deleted form, or the kinds of a polymorphic answer); `key`
+   *  when the answer is an envelope holding it under that property (`{ ok, channel: {...} }`). */
+  /** `extends`: fields the answer adds to its resource (GitHub's ruleset-version-with-state: allOf ruleset-version and `state`). */
+  answers?: { resource: string; list: boolean; alternatives?: string[]; key?: string; extends?: string[] };
+  /** The credential scopes any one of which lets a caller make this call, from the spec's security. */
+  scopes?: string[];
+  /** The security schemes any one of which the call is made with (the spec's security, each requirement's scheme
+   *  names); absent when the call takes none. `anonymous` when a requirement is empty (`{}`: the call may also go
+   *  without). */
+  credentials?: string[];
+  /** The resource the operation acts on: the one at its path. */
+  resource?: string;
+  class: OperationClass;
+};
+
+export type IrStateCandidate = { field: string; values: string[] };
+
+export type IrResource = {
+  name: string;
+  /** The component schema that defines it. */
+  schema: string;
+  /** `discriminator`: a union's field each alternative gives one value (which alternative it is). */
+  fields: Array<{ name: string; type: string; nullable: boolean; required?: boolean; enum?: string[]; discriminator?: boolean }>;
+  /** Top-level enum fields with more than one value. The manifest rules on each. */
+  stateCandidates: IrStateCandidate[];
+  /** Fields holding another resource's id that a caller may ask to receive embedded. */
+  expandable: string[];
+};
+
+export type SpecIR = {
+  format: 'openapi' | 'smithy' | 'proto' | 'client';
+  version: string;
+  /** The path the vendor's server URL puts before every operation path (`/v1` for OpenAI), when any. */
+  basePath?: string;
+  /** The path parameters whose values span segments: Smithy's greedy labels (`{Key+}`), which the path keeps as the label. */
+  spanning?: string[];
+  resources: IrResource[];
+  operations: IrOperation[];
+};
+
+// every operation an OpenAPI path item may hold (a HEAD is as published as a GET: Vercel's /v8/artifacts/{hash})
+const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'] as const;
+
+function deref(doc: Json, node: Json, depth = 0): Json {
+  if (!node || typeof node !== 'object' || depth > 8) return node;
+  if (typeof node.$ref === 'string' && node.$ref.startsWith('#/')) {
+    const target = node.$ref.slice(2).split('/').reduce((acc: Json, k: string) => (acc ? acc[k] : undefined), doc);
+    return deref(doc, target, depth + 1);
+  }
+  return node;
+}
+
+/** The fields a schema requires, its `allOf` members' included; a union requires what every alternative does. */
+function requiredOf(doc: Json, schema: Json, depth = 0): Set<string> {
+  const s = deref(doc, schema);
+  if (!s || typeof s !== 'object' || depth > 8) return new Set();
+  const out = new Set<string>(Array.isArray(s.required) ? s.required.map(String) : []);
+  for (const part of Array.isArray(s.allOf) ? s.allOf : []) for (const f of requiredOf(doc, part, depth + 1)) out.add(f);
+  const alts = [...(Array.isArray(s.oneOf) ? s.oneOf : []), ...(Array.isArray(s.anyOf) ? s.anyOf : [])].map((a: Json) => requiredOf(doc, a, depth + 1));
+  if (alts.length) for (const f of alts[0]!) if (alts.every((a) => a.has(f))) out.add(f);
+  return out;
+}
+
+/** A schema's properties, with `allOf` members merged (how composed schemas are written). */
+function propsOf(doc: Json, schema: Json, depth = 0): Record<string, Json> {
+  const s = deref(doc, schema);
+  if (!s || typeof s !== 'object' || depth > 8) return {};
+  const merged: Record<string, Json> = {};
+  for (const part of Array.isArray(s.allOf) ? s.allOf : []) Object.assign(merged, propsOf(doc, part, depth + 1));
+  return { ...merged, ...(s.properties ?? {}) };
+}
+
+const DISCRIMINATOR = 'x-twin-discriminator';
+
+/** The fields a resource can answer: its properties and, for a union (Slack's conversation is a oneOf
+ *  of its kinds), every alternative's, since any of them may be what the vendor sends. */
+function fieldsOf(doc: Json, schema: Json, depth = 0): Record<string, Json> {
+  const s = deref(doc, schema);
+  if (!s || typeof s !== 'object' || depth > 8) return {};
+  const merged: Record<string, Json> = {};
+  for (const alt of [...(Array.isArray(s.oneOf) ? s.oneOf : []), ...(Array.isArray(s.anyOf) ? s.anyOf : [])]) {
+    for (const [k, v] of Object.entries(fieldsOf(doc, alt, depth + 1))) {
+      if (!(k in merged)) { merged[k] = v; continue; }
+      // a field several alternatives list values for (an input message's role, an output message's) takes them all
+      const had = deref(doc, merged[k]);
+      const more = deref(doc, v);
+      // (one value per alternative is the union's discriminator, Stripe's `object` or OpenAI's item `type`: which
+      // alternative this is, never a state)
+      if (Array.isArray(had?.enum) && Array.isArray(more?.enum)) {
+        const discriminates = (had.enum.length === 1 || had[DISCRIMINATOR] === true) && more.enum.length === 1;
+        merged[k] = { ...had, enum: [...new Set([...had.enum, ...more.enum])], ...(discriminates ? { [DISCRIMINATOR]: true } : {}) };
+      }
+    }
+  }
+  for (const part of Array.isArray(s.allOf) ? s.allOf : []) Object.assign(merged, fieldsOf(doc, part, depth + 1));
+  return { ...merged, ...(s.properties ?? {}) };
+}
+
+// An object a spec writes inline where it answers a resource (hoistInline): its name, as a $ref would give one.
+const inlineNames = new WeakMap<object, string>();
+const refName = (node: Json): string | undefined =>
+  typeof node?.$ref === 'string' ? node.$ref.split('/').pop() : node && typeof node === 'object' ? inlineNames.get(node) : undefined;
+
+/** A spec that writes every schema in place (Tremendous: no $ref anywhere under paths, its components unused) names no
+ *  resource. Each object an answer holds under one key (`{ order: {...} }`, `{ orders: [...] }`) with an `id` of its own is
+ *  the resource that key names, singular (`order`): every inline copy of it is read under that name, and the item GET's
+ *  copy (else a list's, else the first seen) is its schema. Each operation keeps its own copy for what it answers. A spec
+ *  that references components anywhere under its paths is read as it always was. */
+function hoistInline(doc: Json): Json {
+  if (!doc?.paths || JSON.stringify(doc.paths).includes('"$ref"')) return doc;
+  const out = structuredClone(doc);
+  const singular = (key: string): string => (/ies$/.test(key) ? `${key.slice(0, -3)}y` : /(ses|xes)$/.test(key) ? key.slice(0, -2) : /s$/.test(key) ? key.slice(0, -1) : key);
+  const idBearing = (n: Json): boolean => !!n && typeof n === 'object' && !!n.properties?.id;
+  const chosen = new Map<string, { node: Json; rank: number }>();
+  for (const [path, item] of Object.entries(out.paths as Record<string, Json>)) {
+    for (const [method, op] of Object.entries(item ?? {})) {
+      if (!op || typeof op !== 'object' || !(op as Json).responses) continue;
+      const code = Object.keys((op as Json).responses).filter((c) => /^2\d\d$/.test(c)).sort()[0];
+      const schema = code ? (op as Json).responses[code]?.content?.['application/json']?.schema : undefined;
+      const props = schema?.properties;
+      if (!props || schema.properties.id) continue;
+      const held = Object.entries(props as Record<string, Json>).flatMap(([key, p]) =>
+        idBearing(p) ? [{ key, node: p, list: false }] : p?.type === 'array' && idBearing(p.items) ? [{ key: singular(key), node: p.items, list: true }] : []);
+      if (held.length !== 1) continue;
+      const { key, node, list } = held[0]!;
+      inlineNames.set(node, key);
+      const rank = method === 'get' && !list && /\}$/.test(path) ? 0 : method === 'get' ? 1 : 2;
+      const had = chosen.get(key);
+      if (!had || rank < had.rank) chosen.set(key, { node, rank });
+    }
+  }
+  if (!chosen.size) return doc;
+  out.components = { ...(out.components ?? {}), schemas: { ...(out.components?.schemas ?? {}) } };
+  for (const [key, { node }] of chosen) out.components.schemas[key] = node;
+  return out;
+}
+
+function typeOf(doc: Json, schema: Json): string {
+  const s = deref(doc, schema);
+  if (!s || typeof s !== 'object') return 'any';
+  if (refName(schema)) return refName(schema)!;
+  if (s.anyOf || s.oneOf) return 'union';
+  return Array.isArray(s.type) ? s.type.join('|') : (s.type ?? (s.properties ? 'object' : 'any'));
+}
+
+export function slug(method: string, path: string): string {
+  return `${method}_${path}`.replace(/[{}]/g, '').replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase();
+}
+
+/** The resources a schema can be: one for a reference to a resource, several for a union of them
+ *  (`anyOf: [customer, deleted_customer]`, `[card, bank_account, source]`), in the spec's order. */
+function resourcesOfSchema(doc: Json, schema: Json, resources: Map<string, string>): string[] {
+  const name = refName(schema);
+  if (name && resources.has(name)) return [resources.get(name)!];
+  const s = deref(doc, schema);
+  for (const k of ['anyOf', 'oneOf', 'allOf'] as const) {
+    if (Array.isArray(s?.[k])) return [...new Set(s[k].flatMap((alt: Json) => resourcesOfSchema(doc, alt, resources)))] as string[];
+  }
+  return [];
+}
+
+/** Whether a property of an envelope is its metadata, not what it holds: a list of messages (Cloudflare's `errors` and
+ *  `messages`: `code`, `message`) or a paging block (`result_info`: `count`, `page`, `per_page`, `total_count`; cursors). */
+const MESSAGE_FIELDS = new Set(['code', 'message', 'documentation_url', 'source', 'pointer']);
+const PAGING_FIELDS = new Set(['count', 'page', 'per_page', 'total_count', 'total_pages', 'cursor', 'cursors', 'next', 'previous', 'next_cursor', 'before', 'after', 'has_more']);
+function envelopeMeta(doc: Json, node: Json): boolean {
+  const d = deref(doc, node);
+  const target = d?.type === 'array' ? d.items : node;
+  const keys = Object.keys(propsOf(doc, target));
+  return keys.length > 0 && (keys.every((k) => MESSAGE_FIELDS.has(k)) || keys.every((k) => PAGING_FIELDS.has(k)));
+}
+
+function successOf(doc: Json, op: Json, resources: Map<string, string>): { status: number; answers?: IrOperation['answers']; empty?: true } {
+  const codes = Object.keys(op.responses ?? {}).filter((c) => /^2\d\d$/.test(c)).sort();
+  if (!codes.length) return { status: 200 };
+  const status = Number(codes[0]);
+  const r = deref(doc, op.responses[codes[0]]);
+  // a success documented with no content at all answers no body, whatever its status (a 200 with nothing in it)
+  if (status !== 204 && (!r?.content || Object.keys(r.content).length === 0)) return { status, empty: true };
+  const schema = r?.content?.['application/json']?.schema;
+  if (!schema) return { status };
+  const answer = (found: string[], list: boolean, key?: string): IrOperation['answers'] => ({ resource: found[0]!, list, ...(found.length > 1 ? { alternatives: found.slice(1) } : {}), ...(key ? { key } : {}) });
+  const direct = resourcesOfSchema(doc, schema, resources);
+  if (direct.length) {
+    // a named schema composed over the resource answers the resource's fields and its own
+    const composed = !resources.has(refName(schema) ?? '') && Array.isArray(deref(doc, schema)?.allOf);
+    const extra = composed ? Object.keys(deref(doc, schema).allOf.filter((part: Json) => !resourcesOfSchema(doc, part, resources).length).reduce((all: Record<string, Json>, part: Json) => Object.assign(all, propsOf(doc, part)), {} as Record<string, Json>)) : [];
+    return { status, answers: { ...answer(direct, false)!, ...(extra.length ? { extends: extra.sort() } : {}) } };
+  }
+  const s = deref(doc, schema);
+  // A list: a bare array of a resource, or an envelope whose `data` is one (Stripe's list object).
+  const items = s?.type === 'array' ? s.items : s?.properties?.data?.type === 'array' ? s.properties.data.items : undefined;
+  const listed = items ? resourcesOfSchema(doc, items, resources) : [];
+  if (listed.length) return { status, answers: answer(listed, true) };
+  // An envelope that holds exactly one resource, or one list of them, under a named property, beside
+  // at most a few scalars (`ok`, a cursor). An object with an `id` of its own, or with other objects
+  // in it, is not an envelope: it is something that embeds another (a Pages site, a branch).
+  const own = propsOf(doc, schema);
+  if (own.id) return { status };
+  // objects and arrays beside the held one: a paging block is fine, a record's own sub-objects are not
+  const objectish = Object.values(own).filter((p) => { const d = deref(doc, p); return d && typeof d === 'object' && (d.type === 'object' || d.type === 'array' || !!d.properties || !!d.allOf) && !envelopeMeta(doc, p); });
+  if (objectish.length > 3 || Object.keys(own).length > 6) return { status };
+  const held = Object.entries(propsOf(doc, schema)).filter(([, p]) => !envelopeMeta(doc, p)).flatMap(([key, p]) => {
+    const one = resourcesOfSchema(doc, p, resources);
+    if (one.length) return [{ key, found: one, list: false, node: p }];
+    const d = deref(doc, p);
+    const many = d?.type === 'array' ? resourcesOfSchema(doc, d.items, resources) : [];
+    return many.length ? [{ key, found: many, list: true, node: d.items }] : [];
+  });
+  if (held.length !== 1) return { status };
+  const h = held[0]!;
+  // an operation's own inline copy of a resource (hoistInline) that answers fields the resource's schema lacks
+  // (Tremendous's generate-reward-link: { id, link }) answers them beside the resource's
+  const name = h.node && typeof h.node === 'object' ? inlineNames.get(h.node) : undefined;
+  const named = name ? doc?.components?.schemas?.[name] : undefined;
+  const extra = named && named !== h.node ? Object.keys(propsOf(doc, h.node)).filter((f) => !(f in propsOf(doc, named))).sort() : [];
+  return { status, answers: { ...answer(h.found, h.list, h.key)!, ...(extra.length ? { extends: extra } : {}) } };
+}
+
+function paramsOf(doc: Json, op: Json, pathItem: Json): { pathParams: string[]; query: IrParam[] } {
+  const all = [...(pathItem.parameters ?? []), ...(op.parameters ?? [])].map((p: Json) => deref(doc, p));
+  const pathParams = all.filter((p: Json) => p.in === 'path').map((p: Json) => String(p.name));
+  const query = all
+    .filter((p: Json) => p.in === 'query')
+    .map((p: Json) => ({ name: String(p.name), type: typeOf(doc, p.schema), required: p.required === true, ...boundsOf(doc, p.schema) }))
+    .sort((a: IrParam, b: IrParam) => a.name.localeCompare(b.name));
+  return { pathParams, query };
+}
+
+function bodyOf(doc: Json, op: Json): { body: IrParam[]; bodyEncoding: IrOperation['bodyEncoding'] } {
+  const content = deref(doc, op.requestBody)?.content ?? {};
+  const mediaOf = { json: 'application/json', form: 'application/x-www-form-urlencoded', multipart: 'multipart/form-data' } as const;
+  const encoding = content[mediaOf.json] ? 'json' : content[mediaOf.form] ? 'form' : content[mediaOf.multipart] ? 'multipart' : 'none';
+  if (encoding === 'none') return { body: [], bodyEncoding: 'none' };
+  const schema = deref(doc, content[mediaOf[encoding]].schema);
+  const required = new Set<string>(schema?.required ?? []);
+  const body = Object.entries(schema?.properties ?? {})
+    .map(([name, p]) => ({ name, type: typeOf(doc, p), required: required.has(name), ...boundsOf(doc, p) }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  return { body, bodyEncoding: encoding };
+}
+
+/** A form-encoded operation's fields whose value is a number or a boolean, by bracket path: a form carries only text, so
+ *  the spec's type is what says `unit_amount=2400` is a number and `metadata[order]=007` or `name=2024` is text. A path
+ *  segment is a property name, `[]` for an array's item, or `*` for a map's key (`additionalProperties`). A field some
+ *  alternative of whose union takes free text is text; `""`, the value Stripe's unsettable fields take, stays text
+ *  wherever it is sent. */
+function formScalarsOf(doc: Json, op: Json, pathItem: Json, encoding: IrOperation['bodyEncoding']): Record<string, 'integer' | 'number' | 'boolean'> | undefined {
+  if (encoding !== 'form') return undefined;
+  const out: Record<string, 'integer' | 'number' | 'boolean'> = {};
+  const visit = (schema: Json, at: string[], depth: number): void => {
+    const s = deref(doc, schema);
+    if (!s || typeof s !== 'object' || depth > 12) return;
+    const alts = [...(Array.isArray(s.anyOf) ? s.anyOf : []), ...(Array.isArray(s.oneOf) ? s.oneOf : [])].map((a: Json) => deref(doc, a));
+    if (alts.length) {
+      const scalar = alts.map((a: Json) => a?.type).find((t: unknown) => t === 'integer' || t === 'number' || t === 'boolean') as 'integer' | 'number' | 'boolean' | undefined;
+      const freeText = alts.some((a: Json) => a?.type === 'string' && !Array.isArray(a.enum));
+      if (scalar && !freeText && at.length) out[at.join('.')] = scalar;
+      for (const a of alts) if (a?.type !== 'integer' && a?.type !== 'number' && a?.type !== 'boolean') visit(a, at, depth + 1);
+      return;
+    }
+    if ((s.type === 'integer' || s.type === 'number' || s.type === 'boolean') && at.length) { out[at.join('.')] = s.type; return; }
+    if (s.type === 'array') { visit(s.items, [...at, '[]'], depth + 1); return; }
+    for (const [name, p] of Object.entries(propsOf(doc, s))) visit(p, [...at, name], depth + 1);
+    if (s.additionalProperties && typeof s.additionalProperties === 'object') visit(s.additionalProperties, [...at, '*'], depth + 1);
+  };
+  for (const p of [...(pathItem.parameters ?? []), ...(op.parameters ?? [])].map((q: Json) => deref(doc, q))) if (p?.in === 'query') visit(p.schema, [String(p.name)], 0);
+  const body = deref(doc, deref(doc, op.requestBody)?.content?.['application/x-www-form-urlencoded']?.schema);
+  for (const [name, p] of Object.entries(propsOf(doc, body))) visit(p, [name], 0);
+  return Object.keys(out).length ? Object.fromEntries(Object.entries(out).sort(([a], [b]) => a.localeCompare(b))) : undefined;
+}
+
+/** The class of one operation, from its method, its path and what it answers. An operation this cannot place is `action`, never CRUD. */
+/** A path and its discriminator as one key: `/responses/{id}` and `/responses/{id}?beta=true` are different reads. */
+// a null value (the key present with any value) keys as the bare name
+const keyOf = (path: string, discriminator?: Record<string, string | null>): string => (discriminator ? `${path}?${new URLSearchParams(Object.entries(discriminator).map(([k, v]) => [k, v ?? '']))}` : path);
+
+/** An RPC method's class from its verb (`conversations.list`, `chat.postMessage`): the conventions
+ *  RPC-style vendors share. An unfamiliar verb is an action. */
+function rpcClass(verb: string, answersList: boolean): OperationClass {
+  const v = verb.toLowerCase();
+  if (answersList || /^(list|history|replies|members)$/.test(v)) return 'list';
+  if (/^(info|get|lookup|read)/.test(v)) return 'retrieve';
+  if (/^(create|add|open|post|schedule|upload)/.test(v)) return 'create';
+  if (/^(update|edit|rename|set)/.test(v)) return 'update';
+  if (/^(delete|remove)/.test(v)) return 'delete';
+  return 'action';
+}
+
+function classify(o: Omit<IrOperation, 'class' | 'resource'>, itemGets: Map<string, string>, listGets: Map<string, string>, singletons: Set<string>, settingOf: Map<string, string> = new Map()): { class: OperationClass; resource?: string } {
+  const segs = o.path.split('/').filter(Boolean);
+  const last = segs[segs.length - 1] ?? '';
+  if (segs.length === 1 && last.includes('.')) {
+    const verb = last.slice(last.lastIndexOf('.') + 1);
+    let cls = rpcClass(verb, o.answers?.list === true);
+    // a method the vendor documents as a GET is a read, whatever its verb (`auth.test`, `search.messages`)
+    if (o.method === 'get' && !['retrieve', 'list'].includes(cls)) cls = o.answers?.list ? 'list' : o.answers ? 'retrieve' : 'computed';
+    return { class: cls, ...(o.answers ? { resource: o.answers.resource } : {}) };
+  }
+  const lastIsParam = last.startsWith('{');
+  const here = itemGets.get(keyOf(o.path, o.discriminator));
+  const parentPath = '/' + segs.slice(0, -1).join('/');
+  const parent = itemGets.get(keyOf(parentPath, o.discriminator));
+  const answered = o.answers?.resource;
+  const setting = settingOf.get(keyOf(o.path, o.discriminator));
+  if (o.method === 'get') {
+    if (setting) return { class: 'retrieve', resource: setting };
+    if (last === 'search') return { class: 'computed', resource: answered };
+    if (o.answers?.list) return { class: 'list', resource: answered };
+    if (answered && lastIsParam) return { class: 'retrieve', resource: answered };
+    if (answered && here === answered) return { class: 'retrieve', resource: answered };
+    return { class: 'computed', resource: answered ?? parent };
+  }
+  if (o.method === 'delete') return lastIsParam || here ? { class: 'delete', resource: here ?? answered } : { class: 'action', resource: parent ?? answered };
+  if (lastIsParam && answered && here === answered) return { class: 'update', resource: answered };
+  if (o.method === 'post' && !lastIsParam && answered && [...itemGets].some(([k, r]) => r === answered && k.startsWith(`${o.path}/{`) && k.split('?')[0]!.split('/').length === segs.length + 2)) {
+    return { class: 'create', resource: answered };
+  }
+  // a POST to a collection answering one of its items creates it, even when the item is read back
+  // elsewhere (GitHub reads an issue comment at /issues/comments/{id}, not under its issue)
+  if (o.method === 'post' && answered && listGets.get(keyOf(o.path, o.discriminator)) === answered) return { class: 'create', resource: answered };
+  // a setting read and written at one path (an id-less object whose identity is its path)
+  if (singletons.has(keyOf(o.path, o.discriminator)) && (o.method === 'put' || o.method === 'patch')) return { class: 'update', ...(setting ?? answered ? { resource: (setting ?? answered)! } : {}) };
+  if (singletons.has(keyOf(o.path, o.discriminator)) && o.method === 'delete') return { class: 'delete', ...(setting ?? answered ? { resource: (setting ?? answered)! } : {}) };
+  if (!answered && !parent) return { class: 'non-resource' };
+  return { class: 'action', resource: parent ?? answered };
+}
+
+export function fromOpenAPI(spec: Json): SpecIR {
+  const doc = hoistInline(spec);
+  const schemas: Record<string, Json> = doc?.components?.schemas ?? {};
+  // A resource is a schema the vendor declares one (`x-resourceId`), or, lacking any declaration,
+  // a schema with an `id` that some GET answers or lists: something a caller can read back.
+  const declared = Object.entries(schemas).filter(([, s]) => typeof s?.['x-resourceId'] === 'string');
+  const resourceBySchema = new Map<string, string>(declared.map(([n, s]) => [n, String(s['x-resourceId'])]));
+  if (!declared.length) {
+    // what a GET reads back: an id-bearing schema it answers directly, the items of a list it
+    // answers, or the one object an envelope it answers holds (`{ ok, channel }`); identity need
+    // not be an `id` (a Slack message is its channel and `ts`)
+    // a map (an object whose keys are the caller's data: `additionalProperties` and no properties of its own, as
+    // currencyapi's `RatesMap` keyed by currency code) is not a thing a caller reads back: its keys are values, not fields
+    const pureMap = (d: Json): boolean => !!d.additionalProperties && typeof d.additionalProperties === 'object' && !d.properties && !d.allOf && !d.anyOf && !d.oneOf;
+    const objectLike = (node: Json): boolean => {
+      const d = deref(doc, node);
+      return !!d && typeof d === 'object' && !pureMap(d) && (d.type === 'object' || !!d.properties || !!d.allOf || !!d.anyOf || !!d.oneOf);
+    };
+    const named = (node: Json): string[] => {
+      const name = refName(node);
+      if (name && schemas[name] && objectLike(node)) return [name];
+      const d = deref(doc, node);
+      for (const k of ['anyOf', 'oneOf'] as const) if (Array.isArray(d?.[k])) return d[k].flatMap(named);
+      // an inline object that is one named schema (`{ type: object, allOf: [$ref] }`: Cloudflare's custom hostname)
+      if (Array.isArray(d?.allOf) && d.allOf.length === 1) return named(d.allOf[0]);
+      return [];
+    };
+    const readBack = (schema: Json): string[] => {
+      const name = refName(schema);
+      if (name && schemas[name] && propsOf(doc, schema).id) return [name];
+      const d = deref(doc, schema);
+      if (d?.type === 'array') return named(d.items);
+      const props = propsOf(doc, schema);
+      if (props.data && deref(doc, props.data)?.type === 'array') return named(deref(doc, props.data).items);
+      const held = Object.values(props).filter((p) => !envelopeMeta(doc, p)).map((p) => (deref(doc, p)?.type === 'array' ? named(deref(doc, p).items) : named(p))).filter((n) => n.length);
+      return held.length === 1 ? held[0]! : [];
+    };
+    for (const item of Object.values(doc.paths ?? {})) {
+      const get = (item as Json)?.get;
+      const code = Object.keys(get?.responses ?? {}).filter((c) => /^2\d\d$/.test(c)).sort()[0];
+      const schema = code ? deref(doc, get.responses[code])?.content?.['application/json']?.schema : undefined;
+      for (const r of schema ? readBack(schema) : []) resourceBySchema.set(r, r);
+    }
+  }
+
+  const server = String(doc?.servers?.[0]?.url ?? '');
+  const docBase = /^https?:\/\//.test(server) ? new URL(server).pathname.replace(/\/+$/, '') : '';
+  const raw: Array<Omit<IrOperation, 'class' | 'resource'>> = [];
+  for (const [key, item] of Object.entries(doc.paths ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+    const [path, query] = key.split('?') as [string, string | undefined];
+    const discriminator = query ? Object.fromEntries(new URLSearchParams(query)) : undefined;
+    for (const method of METHODS) {
+      const op = (item as Json)[method];
+      if (!op) continue;
+      const success = successOf(doc, op, resourceBySchema);
+      const streams = Object.entries(op.responses ?? {}).some(([code, r]) => /^2\d\d$/.test(code) && deref(doc, r)?.content?.['text/event-stream']);
+      const security = (op.security ?? doc.security ?? []) as Json[];
+      const scopes = [...new Set(security.flatMap((req: Json) => Object.values(req ?? {}).flat() as string[]))].sort();
+      const credentials = [...new Set(security.flatMap((req: Json) => { const names = Object.keys(req ?? {}); return names.length ? names : ['anonymous']; }))].sort();
+      const body = bodyOf(doc, op);
+      const scalars = formScalarsOf(doc, op, item, body.bodyEncoding);
+      const ownServer = String((op.servers ?? (item as Json).servers)?.[0]?.url ?? '');
+      const ownBase = /^https?:\/\//.test(ownServer) ? new URL(ownServer).pathname.replace(/\/+$/, '') : undefined;
+      raw.push({
+        id: typeof op.operationId === 'string' && op.operationId ? op.operationId : slug(method, key),
+        method,
+        path,
+        ...(discriminator ? { discriminator } : {}),
+        ...paramsOf(doc, op, item),
+        ...(ownBase !== undefined && ownBase !== docBase ? { basePath: ownBase } : {}),
+        ...body,
+        ...(scalars ? { scalars } : {}),
+        successStatus: success.status,
+        ...(success.empty ? { emptySuccess: true as const } : {}),
+        ...(streams ? { streams: true } : {}),
+        ...(scopes.length ? { scopes } : {}),
+        ...(credentials.length && !(credentials.length === 1 && credentials[0] === 'anonymous') ? { credentials } : {}),
+        ...(success.answers ? { answers: success.answers } : {}),
+      });
+    }
+  }
+  // Paths whose GET retrieves one resource: what a write at that path, or under it, acts on.
+  const itemGets = new Map<string, string>();
+  for (const o of raw) if (o.method === 'get' && o.answers && !o.answers.list) itemGets.set(keyOf(o.path, o.discriminator), o.answers.resource);
+  const listGets = new Map<string, string>();
+  for (const o of raw) if (o.method === 'get' && o.answers?.list) listGets.set(keyOf(o.path, o.discriminator), o.answers.resource);
+  const singletons = new Set<string>();
+  for (const o of raw) if (o.method === 'get' && !o.answers && !o.path.split('/').at(-1)!.startsWith('{') && o.successStatus === 200) singletons.add(keyOf(o.path, o.discriminator));
+  // a setting's resource: the named schema its GET answers (`AuthConfigResponse`), which a pack may declare to have the
+  // core read it (its defaults until first written) and write it (a merge that creates it), keyed by the path's parent
+  const settingOf = new Map<string, string>();
+  for (const [key, item] of Object.entries(doc.paths ?? {})) {
+    const get = (item as Json).get;
+    const [path, query] = key.split('?') as [string, string | undefined];
+    const k = keyOf(path, query ? Object.fromEntries(new URLSearchParams(query)) : undefined);
+    if (!get || !singletons.has(k)) continue;
+    const schema = deref(doc, get.responses?.['200'])?.content?.['application/json']?.schema;
+    const name = schema ? refName(schema) : undefined;
+    if (name && deref(doc, schema)?.type !== 'array') settingOf.set(k, name);
+  }
+  let operations: IrOperation[] = raw.map((o) => {
+    const c = classify(o, itemGets, listGets, singletons, settingOf);
+    return { ...o, class: c.class, ...(c.resource ? { resource: c.resource } : {}) };
+  });
+  // An RPC method that answers no resource acts on its family's: the one the family's retrieve reads
+  // (`conversations.archive` acts on what `conversations.info` answers).
+  const familyOf = (path: string): string | undefined => (/^\/[^/]+\.[^/]+$/.test(path) ? path.slice(1, path.lastIndexOf('.')) : undefined);
+  const familyResource = new Map<string, string>();
+  for (const o of operations) if (o.class === 'retrieve' && o.resource && familyOf(o.path)) familyResource.set(familyOf(o.path)!, o.resource);
+  operations = operations.map((o) => (o.resource || !familyOf(o.path) || !familyResource.has(familyOf(o.path)!) ? o : { ...o, resource: familyResource.get(familyOf(o.path)!)! }));
+
+  const resources: IrResource[] = [...resourceBySchema]
+    .map(([schemaName, name]) => {
+      const s = deref(doc, schemas[schemaName]);
+      const required = requiredOf(doc, schemas[schemaName]);
+      const fields = Object.entries(fieldsOf(doc, schemas[schemaName]))
+        .map(([f, p]: [string, Json]) => {
+          const d = deref(doc, p);
+          return { name: f, type: typeOf(doc, p), nullable: d?.nullable === true, ...(required.has(f) ? { required: true } : {}), ...(Array.isArray(d?.enum) ? { enum: d.enum.map(String) } : {}), ...(d?.[DISCRIMINATOR] ? { discriminator: true } : {}) };
+        })
+        .sort((a, b) => a.name.localeCompare(b.name));
+      return {
+        name,
+        schema: schemaName,
+        fields,
+        // an enum with several values, and the fields a lifecycle usually lives in though the spec types
+        // them plainly (a string `status`, a boolean `merged`): the manifest rules on every one
+        stateCandidates: fields
+          .filter((f) => !f.discriminator)
+          .filter((f) => (f.enum && f.enum.length > 1) || (f.type === 'string' && /^(status|state|conclusion)$/.test(f.name)) || (f.type === 'boolean' && /^(merged|draft|locked|archived|closed|captured|paid|refunded|disabled|active|livemode_off|is_[a-z_]+)$/.test(f.name)))
+          .map((f) => ({ field: f.name, values: f.enum ? [...f.enum].sort() : f.type === 'boolean' ? ['false', 'true'] : [] })),
+        expandable: Array.isArray(s?.['x-expandableFields']) ? [...s['x-expandableFields']].map(String).sort() : [],
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name) || a.schema.localeCompare(b.schema));
+
+  const basePath = docBase;
+  return { format: 'openapi', version: String(doc?.info?.version ?? ''), ...(basePath ? { basePath } : {}), resources, operations };
+}
+
+/** A Swagger 2.0 document as the OpenAPI 3 shape `fromOpenAPI` reads: definitions become component
+ *  schemas, formData and body parameters a request body, response schemas JSON content, and
+ *  host + basePath the server. Nothing vendor-specific. */
+export function fromSwagger2(doc: Json): SpecIR {
+  const rewrite = (node: Json): Json => {
+    if (Array.isArray(node)) return node.map(rewrite);
+    if (!node || typeof node !== 'object') return node;
+    const out: Json = {};
+    for (const [k, v] of Object.entries(node)) out[k] = k === '$ref' && typeof v === 'string' ? v.replace('#/definitions/', '#/components/schemas/') : rewrite(v);
+    return out;
+  };
+  const paths: Json = {};
+  for (const [key, item] of Object.entries(doc.paths ?? {})) {
+    const next: Json = {};
+    for (const method of METHODS) {
+      const op = (item as Json)[method];
+      if (!op) continue;
+      const params = [...((item as Json).parameters ?? []), ...(op.parameters ?? [])];
+      const form = params.filter((p: Json) => p.in === 'formData');
+      const body = params.find((p: Json) => p.in === 'body');
+      const consumes: string[] = op.consumes ?? doc.consumes ?? [];
+      const formType = consumes.includes('multipart/form-data') ? 'multipart/form-data' : 'application/x-www-form-urlencoded';
+      const requestBody = body
+        ? { content: { 'application/json': { schema: body.schema } } }
+        : form.length
+          ? { content: { [formType]: { schema: { type: 'object', required: form.filter((p: Json) => p.required).map((p: Json) => p.name), properties: Object.fromEntries(form.map((p: Json) => [p.name, { type: p.type ?? 'string' }])) } } } }
+          : undefined;
+      next[method] = {
+        ...op,
+        parameters: params.filter((p: Json) => p.in === 'path' || p.in === 'query').map((p: Json) => ({ name: p.name, in: p.in, required: p.required, schema: { type: p.type ?? 'string' } })),
+        ...(requestBody ? { requestBody } : {}),
+        responses: Object.fromEntries(Object.entries(op.responses ?? {}).map(([code, r]: [string, Json]) => [code, { description: r?.description ?? '', ...(r?.schema ? { content: { 'application/json': { schema: r.schema } } } : {}) }])),
+      };
+    }
+    paths[key] = next;
+  }
+  const scheme = (doc.schemes ?? ['https'])[0];
+  return fromOpenAPI(
+    rewrite({
+      openapi: '3.0.0',
+      info: doc.info,
+      ...(doc.host ? { servers: [{ url: `${scheme}://${doc.host}${doc.basePath ?? ''}` }] } : {}),
+      ...(doc.security ? { security: doc.security } : {}),
+      components: { schemas: doc.definitions ?? {} },
+      paths,
+    }),
+  );
+}
+
+// ── Smithy (AWS) ─────────────────────────────────────────────────────────────────────────────
+// An AWS service's Smithy JSON model: its operations, each named on the wire by `X-Amz-Target: <prefix>.<Operation>`
+// (awsJson1_0 / awsJson1_1, every operation a POST to `/`) or by its `smithy.api#http` trait (restJson1, restXml). A model
+// with no resource shapes (Secrets Manager) answers each operation with its output structure, which is the resource
+// that operation answers: its members are the fields, `smithy.api#required` marks the required ones, and an enum
+// shape's values are the field's values. Timestamps are numbers on AWS JSON (epoch seconds).
+
+const short = (id: string): string => id.split('#').pop()!;
+
+/** An AWS service's Smithy JSON model as the IR (`service` names the service shape when the model holds several). */
+export function fromSmithy(model: Json, service?: string): SpecIR {
+  const shapes: Record<string, Json> = model.shapes ?? {};
+  const serviceId = service ?? Object.keys(shapes).find((k) => shapes[k].type === 'service')!;
+  const svc = shapes[serviceId];
+  const traits = svc.traits ?? {};
+  const json = Boolean(traits['aws.protocols#awsJson1_0'] || traits['aws.protocols#awsJson1_1']);
+  // AWS JSON names an operation by the service shape's own name (secretsmanager.CreateSecret, DynamoDB_20120810.PutItem)
+  const targetPrefix = short(serviceId);
+  const typeOfShape = (target: string): string => {
+    const s = shapes[target];
+    if (!s) return short(target).toLowerCase();
+    if (s.type === 'structure' || s.type === 'union') return short(target);
+    if (s.type === 'timestamp') return json ? 'number' : 'string';
+    if (s.type === 'enum' || s.type === 'intEnum') return 'string';
+    return s.type;
+  };
+  const enumOf = (target: string): string[] | undefined => {
+    const s = shapes[target];
+    if (!s) return undefined;
+    if (s.type === 'enum') return Object.entries(s.members ?? {}).map(([k, m]: [string, Json]) => String(m.traits?.['smithy.api#enumValue'] ?? k));
+    if (Array.isArray(s.traits?.['smithy.api#enum'])) return s.traits['smithy.api#enum'].map((e: Json) => String(e.value));
+    return undefined;
+  };
+  const resources = new Map<string, IrResource>();
+  const xmlWire = Boolean(traits['aws.protocols#restXml']);
+  const resourceOf = (target: string): string => {
+    const name = short(target);
+    if (resources.has(name)) return name;
+    const s = shapes[target] ?? {};
+    // on restXml an output's members bound to headers or the status are not in its body, and an element is named by its
+    // xmlName where it has one (what SHAPE sees of the answer)
+    const inBody = ([, m]: [string, Json]): boolean => !xmlWire || !Object.keys(m.traits ?? {}).some((t) => /^smithy\.api#http(Header|PrefixHeaders|ResponseCode)$/.test(t));
+    const fields = (Object.entries(s.members ?? {}) as Array<[string, Json]>).filter(inBody).map(([f, m]: [string, Json]) => {
+      const values = enumOf(m.target);
+      return { name: xmlWire ? String(m.traits?.['smithy.api#xmlName'] ?? f) : f, type: typeOfShape(m.target), nullable: !m.traits?.['smithy.api#required'], ...(m.traits?.['smithy.api#required'] ? { required: true } : {}), ...(values ? { enum: values } : {}) };
+    }).sort((a, b) => a.name.localeCompare(b.name));
+    const stateCandidates = fields.filter((f) => f.enum && f.enum.length > 1).map((f) => ({ field: f.name, values: [...f.enum!].sort() }));
+    resources.set(name, { name, schema: name, fields, stateCandidates, expandable: [] });
+    return name;
+  };
+  const classOf = (name: string): OperationClass => {
+    if (/^Create/.test(name)) return 'create';
+    if (/^(Get|Describe)/.test(name)) return 'retrieve';
+    if (/^List/.test(name)) return 'list';
+    if (/^(Update|Put)/.test(name)) return 'update';
+    if (/^Delete/.test(name)) return 'delete';
+    return 'action';
+  };
+  // an HTTP-bound protocol (restJson1, restXml) binds each input member to the wire by a trait: a path label, a query
+  // key, a header, or the payload (smithy.io/2.0/spec/http-bindings); what no trait binds is the body. The IR carries
+  // the labels, the query and the body; a header-bound member is the handler's to read.
+  // what an operation's success answer is: its output structure, or on restXml the structure its payload member holds
+  // (GetBucketCors answers its CORSConfiguration); a payload of bytes (GetObject's Body) is no resource
+  const answerOf = (op: Json): string | undefined => {
+    if (!op.output) return undefined;
+    const payload = Object.values((shapes[op.output.target]?.members ?? {}) as Record<string, Json>).find((m) => m.traits?.['smithy.api#httpPayload'] !== undefined);
+    if (!xmlWire || !payload) return resourceOf(op.output.target);
+    return shapes[payload.target]?.type === 'structure' ? resourceOf(payload.target) : undefined;
+  };
+  const BOUND = /^smithy\.api#http(Label|Query|QueryParams|Header|PrefixHeaders|ResponseCode)$/;
+  const operations: IrOperation[] = (svc.operations ?? []).map((o: Json) => o.target).sort().map((target: string) => {
+    const op = shapes[target];
+    const name = short(target);
+    const http = op.traits?.['smithy.api#http'];
+    const input = op.input ? shapes[op.input.target] : undefined;
+    const members = Object.entries(input?.members ?? {}) as Array<[string, Json]>;
+    const param = ([f, m]: [string, Json]): IrParam => ({ name: f, type: typeOfShape(m.target), required: Boolean(m.traits?.['smithy.api#required']) });
+    // a uri's query literals (`/{Bucket}?cors`) must be carried by a request to match it, and tell operations at one
+    // path apart; a greedy label (`{Key+}`) is the label, the surface's `spanning` naming it
+    const [uriPath, uriQuery] = String(http?.uri ?? '/').split('?');
+    const discriminator = !json && uriQuery ? Object.fromEntries(uriQuery.split('&').map((kv) => { const [k, v = ''] = kv.split('='); return [k!, v]; })) : undefined;
+    const payload = members.find(([, m]) => m.traits?.['smithy.api#httpPayload'] !== undefined);
+    return {
+      id: name,
+      method: json ? 'post' : String(http?.method ?? 'POST').toLowerCase(),
+      path: json ? '/' : uriPath!.replace(/\{([^}+]+)\+\}/g, '{$1}'),
+      ...(discriminator ? { discriminator } : {}),
+      ...(json ? { headers: { 'x-amz-target': `${targetPrefix}.${name}` } } : {}),
+      pathParams: json ? [] : [...uriPath!.matchAll(/\{([^}+]+)\+?\}/g)].map((m) => m[1]!),
+      query: json ? [] : members.filter(([, m]) => m.traits?.['smithy.api#httpQuery'] !== undefined).map(([f, m]) => ({ ...param([f, m]), name: String(m.traits['smithy.api#httpQuery']) })),
+      body: json ? members.map(param) : payload ? [param(payload)] : members.filter(([, m]) => !Object.keys(m.traits ?? {}).some((t) => BOUND.test(t))).map(param),
+      bodyEncoding: xmlWire ? ('xml' as const) : ('json' as const),
+      successStatus: json ? 200 : Number(http?.code ?? 200),
+      ...(answerOf(op) ? { answers: { resource: answerOf(op)!, list: false } } : {}),
+      class: classOf(name),
+    };
+  });
+  // operations at one method, path and query literals are told apart, as the service tells them, by what each requires
+  // the request to carry: a required query key or header present (S3: CopyObject's `x-amz-copy-source`, UploadPart's
+  // `partNumber` and `uploadId`); an operation that requires none is the one a request carrying none of them reaches
+  const at = new Map<string, IrOperation[]>();
+  for (const o of operations) { const k = `${o.method} ${o.path} ${JSON.stringify(o.discriminator ?? {})}`; at.set(k, [...(at.get(k) ?? []), o]); }
+  for (const group of at.values()) {
+    if (json || group.length < 2) continue;
+    for (const o of group) {
+      const input = shapes[shapes[`${serviceId.split('#')[0]}#${o.id}`]?.input?.target ?? ''];
+      for (const m of Object.values((input?.members ?? {}) as Record<string, Json>)) {
+        if (!m.traits?.['smithy.api#required']) continue;
+        const q = m.traits['smithy.api#httpQuery'];
+        const h = m.traits['smithy.api#httpHeader'];
+        if (q !== undefined) o.discriminator = { ...(o.discriminator ?? {}), [String(q)]: o.discriminator?.[String(q)] ?? null };
+        if (h !== undefined) o.headers = { ...(o.headers ?? {}), [String(h).toLowerCase()]: null };
+      }
+    }
+  }
+  // "a label suffixed with the + qualifier that can be used to match more than one path segment" (smithy.io/2.0/spec/http-bindings.html, Greedy labels)
+  const spanning = [...new Set((svc.operations ?? []).flatMap((o: Json) => [...String(shapes[o.target]?.traits?.['smithy.api#http']?.uri ?? '').matchAll(/\{([^}+]+)\+\}/g)].map((m) => m[1]!)))].sort() as string[];
+  return { format: 'smithy', version: String(svc.version ?? ''), ...(spanning.length ? { spanning } : {}), resources: [...resources.values()].sort((a, b) => a.name.localeCompare(b.name)), operations };
+}