@volter/twin-standard 1.0.0

package/dist/src/spec-ir.js

@@ -0,0 +1,691 @@
+// 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.
+export const CRUD_CLASSES = new Set(['create', 'retrieve', 'list', 'update', 'delete']);
+/** A schema's stated numeric bounds, when it states any. */
+function boundsOf(doc, schema) {
+    const s = deref(doc, schema);
+    return { ...(typeof s?.minimum === 'number' ? { minimum: s.minimum } : {}), ...(typeof s?.maximum === 'number' ? { maximum: s.maximum } : {}) };
+}
+// 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'];
+function deref(doc, node, depth = 0) {
+    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, k) => (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, schema, depth = 0) {
+    const s = deref(doc, schema);
+    if (!s || typeof s !== 'object' || depth > 8)
+        return new Set();
+    const out = new Set(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) => 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, schema, depth = 0) {
+    const s = deref(doc, schema);
+    if (!s || typeof s !== 'object' || depth > 8)
+        return {};
+    const merged = {};
+    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, schema, depth = 0) {
+    const s = deref(doc, schema);
+    if (!s || typeof s !== 'object' || depth > 8)
+        return {};
+    const merged = {};
+    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();
+const refName = (node) => 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) {
+    if (!doc?.paths || JSON.stringify(doc.paths).includes('"$ref"'))
+        return doc;
+    const out = structuredClone(doc);
+    const singular = (key) => (/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) => !!n && typeof n === 'object' && !!n.properties?.id;
+    const chosen = new Map();
+    for (const [path, item] of Object.entries(out.paths)) {
+        for (const [method, op] of Object.entries(item ?? {})) {
+            if (!op || typeof op !== 'object' || !op.responses)
+                continue;
+            const code = Object.keys(op.responses).filter((c) => /^2\d\d$/.test(c)).sort()[0];
+            const schema = code ? op.responses[code]?.content?.['application/json']?.schema : undefined;
+            const props = schema?.properties;
+            if (!props || schema.properties.id)
+                continue;
+            const held = Object.entries(props).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, schema) {
+    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, path) {
+    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, schema, resources) {
+    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']) {
+        if (Array.isArray(s?.[k]))
+            return [...new Set(s[k].flatMap((alt) => resourcesOfSchema(doc, alt, resources)))];
+    }
+    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, node) {
+    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, op, resources) {
+    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, list, key) => ({ 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) => !resourcesOfSchema(doc, part, resources).length).reduce((all, part) => Object.assign(all, propsOf(doc, part)), {})) : [];
+        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, op, pathItem) {
+    const all = [...(pathItem.parameters ?? []), ...(op.parameters ?? [])].map((p) => deref(doc, p));
+    const pathParams = all.filter((p) => p.in === 'path').map((p) => String(p.name));
+    const query = all
+        .filter((p) => p.in === 'query')
+        .map((p) => ({ name: String(p.name), type: typeOf(doc, p.schema), required: p.required === true, ...boundsOf(doc, p.schema) }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return { pathParams, query };
+}
+function bodyOf(doc, op) {
+    const content = deref(doc, op.requestBody)?.content ?? {};
+    const mediaOf = { json: 'application/json', form: 'application/x-www-form-urlencoded', multipart: 'multipart/form-data' };
+    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(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, op, pathItem, encoding) {
+    if (encoding !== 'form')
+        return undefined;
+    const out = {};
+    const visit = (schema, at, depth) => {
+        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) => deref(doc, a));
+        if (alts.length) {
+            const scalar = alts.map((a) => a?.type).find((t) => t === 'integer' || t === 'number' || t === 'boolean');
+            const freeText = alts.some((a) => 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) => 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, discriminator) => (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, answersList) {
+    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, itemGets, listGets, singletons, settingOf = new Map()) {
+    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) {
+    const doc = hoistInline(spec);
+    const schemas = 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(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) => !!d.additionalProperties && typeof d.additionalProperties === 'object' && !d.properties && !d.allOf && !d.anyOf && !d.oneOf;
+        const objectLike = (node) => {
+            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) => {
+            const name = refName(node);
+            if (name && schemas[name] && objectLike(node))
+                return [name];
+            const d = deref(doc, node);
+            for (const k of ['anyOf', 'oneOf'])
+                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) => {
+            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?.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 = [];
+    for (const [key, item] of Object.entries(doc.paths ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+        const [path, query] = key.split('?');
+        const discriminator = query ? Object.fromEntries(new URLSearchParams(query)) : undefined;
+        for (const method of METHODS) {
+            const op = item[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 ?? []);
+            const scopes = [...new Set(security.flatMap((req) => Object.values(req ?? {}).flat()))].sort();
+            const credentials = [...new Set(security.flatMap((req) => { 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.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 } : {}),
+                ...(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();
+    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();
+    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();
+    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();
+    for (const [key, item] of Object.entries(doc.paths ?? {})) {
+        const get = item.get;
+        const [path, query] = key.split('?');
+        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 = 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) => (/^\/[^/]+\.[^/]+$/.test(path) ? path.slice(1, path.lastIndexOf('.')) : undefined);
+    const familyResource = new Map();
+    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 = [...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]) => {
+            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) {
+    const rewrite = (node) => {
+        if (Array.isArray(node))
+            return node.map(rewrite);
+        if (!node || typeof node !== 'object')
+            return node;
+        const out = {};
+        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 = {};
+    for (const [key, item] of Object.entries(doc.paths ?? {})) {
+        const next = {};
+        for (const method of METHODS) {
+            const op = item[method];
+            if (!op)
+                continue;
+            const params = [...(item.parameters ?? []), ...(op.parameters ?? [])];
+            const form = params.filter((p) => p.in === 'formData');
+            const body = params.find((p) => p.in === 'body');
+            const consumes = 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) => p.required).map((p) => p.name), properties: Object.fromEntries(form.map((p) => [p.name, { type: p.type ?? 'string' }])) } } } }
+                    : undefined;
+            next[method] = {
+                ...op,
+                parameters: params.filter((p) => p.in === 'path' || p.in === 'query').map((p) => ({ 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]) => [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) => 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, service) {
+    const shapes = 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) => {
+        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) => {
+        const s = shapes[target];
+        if (!s)
+            return undefined;
+        if (s.type === 'enum')
+            return Object.entries(s.members ?? {}).map(([k, m]) => String(m.traits?.['smithy.api#enumValue'] ?? k));
+        if (Array.isArray(s.traits?.['smithy.api#enum']))
+            return s.traits['smithy.api#enum'].map((e) => String(e.value));
+        return undefined;
+    };
+    const resources = new Map();
+    const xmlWire = Boolean(traits['aws.protocols#restXml']);
+    const resourceOf = (target) => {
+        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]) => !xmlWire || !Object.keys(m.traits ?? {}).some((t) => /^smithy\.api#http(Header|PrefixHeaders|ResponseCode)$/.test(t));
+        const fields = Object.entries(s.members ?? {}).filter(inBody).map(([f, m]) => {
+            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) => {
+        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) => {
+        if (!op.output)
+            return undefined;
+        const payload = Object.values((shapes[op.output.target]?.members ?? {})).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 = (svc.operations ?? []).map((o) => o.target).sort().map((target) => {
+        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 ?? {});
+        const param = ([f, m]) => ({ 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' : 'json',
+            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();
+    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 ?? {}))) {
+                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) => [...String(shapes[o.target]?.traits?.['smithy.api#http']?.uri ?? '').matchAll(/\{([^}+]+)\+\}/g)].map((m) => m[1])))].sort();
+    return { format: 'smithy', version: String(svc.version ?? ''), ...(spanning.length ? { spanning } : {}), resources: [...resources.values()].sort((a, b) => a.name.localeCompare(b.name)), operations };
+}