@volter/twin-standard 1.0.0

package/src/published.ts

@@ -0,0 +1,37 @@
+// A published version graded as the catalog grades a submission (docs/contributing/architecture.md, "The catalog: where
+// twins come from"): its tarball fetched from the registry, unpacked under its vendor's name (so its lanes are read as
+// the vendor's), and every unit in it — the pack and each lane — put through the gate.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { p3Gate } from './gate.ts';
+
+export type PublishedGate = { spec: string; failures: Array<{ unit: string; failures: string[] }> };
+
+/** The vendor a package twins: its name without its scope and the `twin-` prefix (`@volter/twin-supabase` is supabase). */
+export const vendorOfPackage = (name: string): string => name.replace(/^@[^/]+\//, '').replace(/^twin-/, '');
+
+/** The gate over `spec` (`<name>@<version>`) as the registry serves it; throws when it cannot be fetched or unpacked. */
+export async function gatePublished(spec: string, opts: { registry?: string } = {}): Promise<PublishedGate> {
+  const tmp = mkdtempSync(join(tmpdir(), 'twin-standard-'));
+  try {
+    const pack = spawnSync('npm', ['pack', spec, '--pack-destination', tmp, '--silent', ...(opts.registry ? ['--registry', opts.registry] : [])], { encoding: 'utf8' });
+    const tarball = readdirSync(tmp).find((f) => f.endsWith('.tgz'));
+    if (pack.status !== 0 || !tarball) throw new Error(`${spec}: the registry gave no tarball (${String(pack.stderr).trim().split('\n').at(-1) ?? ''})`);
+    const untar = spawnSync('tar', ['-xzf', join(tmp, tarball), '-C', tmp], { encoding: 'utf8' });
+    if (untar.status !== 0) throw new Error(`${spec}: the tarball does not unpack (${String(untar.stderr).trim()})`);
+    const name = (JSON.parse(readFileSync(join(tmp, 'package', 'package.json'), 'utf8')) as { name: string }).name;
+    const dir = join(tmp, vendorOfPackage(name));
+    renameSync(join(tmp, 'package'), dir);
+    const lanes = readdirSync(dir).filter((l) => existsSync(join(dir, l, 'src', 'manifest.ts')) && !existsSync(join(dir, l, 'package.json'))).map((l) => join(dir, l));
+    const results = await p3Gate([dir, ...lanes]);
+    const unit = (u: string): string => u.slice(tmp.length + 1);
+    return {
+      spec,
+      failures: results.filter((r) => r.failures.length).map((r) => ({ unit: unit(r.unit), failures: r.failures })),
+    };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/src/spec-documents.ts

@@ -0,0 +1,58 @@
+// One API published as several OpenAPI documents (Upstash publishes QStash's and Workflow's, both served on
+// qstash-{region}.upstash.io with one key set, and sharing endpoints): the pack vendors each as published under
+// `spec/openapi/<name>.{json,yaml}[.gz]`, patches address a document as `/documents/<name>/...`, and the documents are
+// read as their union. A path and method, or a component, that two documents both give must be the same (their words,
+// description and summary, aside); where they contradict each other, neither page is evidence against the other, and a
+// patch rules which holds (citing what shows it: the vendor's own client, a recording), so the union is never a guess.
+
+import { parse as parseYaml } from 'yaml';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+
+type Json = any;
+export type SpecDocuments = { documents: Record<string, Json> };
+
+/** The documents of `spec/openapi/`, by name, or undefined when the pack vendors one spec file. */
+export function readSpecDocuments(specDir: string): SpecDocuments | undefined {
+  const dir = join(specDir, 'openapi');
+  if (!existsSync(dir)) return undefined;
+  const documents: Record<string, Json> = {};
+  for (const f of readdirSync(dir).filter((f) => /\.(json|ya?ml)(\.gz)?$/.test(f)).sort()) {
+    const bytes = readFileSync(join(dir, f));
+    const text = (f.endsWith('.gz') ? gunzipSync(bytes) : bytes).toString('utf8');
+    documents[f.replace(/\.(json|ya?ml)(\.gz)?$/, '')] = /\.ya?ml(\.gz)?$/.test(f) ? parseYaml(text) : JSON.parse(text);
+  }
+  if (Object.keys(documents).length < 2) throw new Error(`${dir}: one API in several documents needs at least two; a single document is spec/openapi.{json,yaml}`);
+  return { documents };
+}
+
+/** A node without its words (description, summary, examples, and the tags a document files it under): what two
+ *  documents must agree on. */
+const substance = (n: Json): string => JSON.stringify(n, (k, v) => (['description', 'summary', 'example', 'examples', 'x-mint', 'tags'].includes(k) ? undefined : v && typeof v === 'object' && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b))) : v));
+
+/** The union of the documents as one OpenAPI document; each contradiction left unpatched is named, by pointer. */
+export function mergeDocuments(docs: SpecDocuments): { doc: Json; contradictions: string[] } {
+  const names = Object.keys(docs.documents);
+  const first = docs.documents[names[0]!];
+  const doc: Json = { ...structuredClone(first), paths: {}, components: {} };
+  const from: Record<string, string> = {};
+  const contradictions: string[] = [];
+  const take = (target: Json, key: string, value: Json, pointer: string, name: string): void => {
+    if (target[key] === undefined) { target[key] = structuredClone(value); from[pointer] = name; return; }
+    if (substance(target[key]) !== substance(value)) contradictions.push(`/documents/${from[pointer]}${pointer} and /documents/${name}${pointer} differ`);
+  };
+  for (const name of names) {
+    const d = docs.documents[name];
+    if (substance(d.servers) !== substance(first.servers)) contradictions.push(`/documents/${name}/servers differs from /documents/${names[0]}/servers: not one API`);
+    for (const [path, item] of Object.entries((d.paths ?? {}) as Record<string, Json>)) {
+      const target = (doc.paths[path] ??= {});
+      for (const [k, v] of Object.entries(item)) take(target, k, v, `/paths/${path.replace(/~/g, '~0').replace(/\//g, '~1')}/${k}`, name);
+    }
+    for (const [part, entries] of Object.entries((d.components ?? {}) as Record<string, Record<string, Json>>)) {
+      const target = (doc.components[part] ??= {});
+      for (const [k, v] of Object.entries(entries)) take(target, k, v, `/components/${part}/${k}`, name);
+    }
+  }
+  return { doc, contradictions };
+}

package/src/spec-ir-client.ts

@@ -0,0 +1,86 @@
+// A vendor that publishes no spec of its API but ships its own client: the API as that client calls it. Tinybird
+// publishes no OpenAPI of its platform API (its reference pages omit endpoints its own CLI calls: /v0/tags,
+// /v0/sql_tables), and its Python client (`tinybird/client.py`, class TinyB, in tinybird-cli on PyPI) makes every
+// request through `_req(url, method=..., data=...)`. Each such call, read from the client's syntax tree (the pack's
+// `spec/extract-client-ops.py`), is vendored as data in `spec/client-ops.json`: its method, its URL as the client
+// builds it (a label is the Python expression the client interpolates), the query keys it sends (literal, or the keys
+// of the dict it urlencodes) and its body's keys, each typed by the client's own annotation of the value (`null`
+// where the client does not say). A spec patch corrects the table as it corrects a JSON spec (derive-pack): what the
+// client builds as a raw string (a token's scopes) comes from the vendor's reference page that way.
+//
+// The calls at one method and path are one operation, their query and body keys together. The client says nothing
+// of what an answer holds, so an operation answers no resource here: its answers are the vendor's pages' examples.
+
+import type { IrOperation, IrParam, SpecIR } from './spec-ir.ts';
+
+export type ClientCall = {
+  /** the client method that makes the call, and its line */
+  client: string;
+  line: number;
+  method: string;
+  url: string;
+  query?: Record<string, string | null>;
+  body?: { encoding: 'json' | 'form' | 'raw'; fields?: Record<string, string | null>; passes?: string };
+};
+export type ClientOpsSpec = { format: 'client'; version: string; calls: ClientCall[] };
+
+/** A label's name from the expression the client interpolates: `quote(datasource_name, safe='')` is
+ *  `datasource_name`, `workspace['id']` is `workspace_id`. */
+function labelOf(expr: string): string {
+  const inner = /^\w+\(\s*([\w[\]'"]+)/.exec(expr)?.[1] ?? expr;
+  return inner.replace(/\[['"](\w+)['"]\]/g, '_$1').replace(/\W+/g, '_');
+}
+
+/** The URL's path with each label named, no trailing slash (the client writes `/v0/user/workspaces/`). */
+function pathOf(url: string): { path: string; labels: string[] } {
+  const raw = `/${url.split('?')[0]!.replace(/^\/+/, '')}`.replace(/(.)\/$/, '$1');
+  const labels: string[] = [];
+  const path = raw.replace(/\{([^}]+)\}/g, (_, expr: string) => { const name = labelOf(expr); labels.push(name); return `{${name}}`; });
+  return { path, labels };
+}
+
+const typeOf = (t: string | null | undefined): string => t ?? 'string';
+
+export function fromClientCalls(spec: ClientOpsSpec): SpecIR {
+  const byRoute = new Map<string, { first: ClientCall; path: string; labels: string[]; calls: ClientCall[] }>();
+  for (const call of spec.calls) {
+    const { path, labels } = pathOf(call.url);
+    const key = `${call.method.toUpperCase()} ${path.replace(/\{[^}]+\}/g, '{}')}`;
+    const at = byRoute.get(key);
+    if (at) at.calls.push(call);
+    else byRoute.set(key, { first: call, path, labels, calls: [call] });
+  }
+  const operations: IrOperation[] = [...byRoute.values()].map(({ first, path, labels, calls }) => {
+    const query = new Map<string, IrParam>();
+    const body = new Map<string, IrParam>();
+    const encodings = new Set<string>();
+    for (const c of calls) {
+      for (const [name, t] of Object.entries(c.query ?? {})) if (!query.has(name)) query.set(name, { name, type: typeOf(t), required: false });
+      if (c.body) encodings.add(c.body.encoding);
+      for (const [name, t] of Object.entries(c.body?.fields ?? {})) if (!body.has(name)) body.set(name, { name, type: typeOf(t), required: false });
+    }
+    // a JSON body where any call sends one; a form where the client sends a dict; otherwise the body is the client's own bytes
+    const bodyEncoding: IrOperation['bodyEncoding'] = encodings.has('json') ? 'json' : encodings.has('form') ? 'form' : 'none';
+    return {
+      id: first.client,
+      // the client library that makes the call (`libnpmpublish.publish` is `libnpmpublish`): the operation's family
+      ...(first.client.includes('.') ? { family: first.client.slice(0, first.client.indexOf('.')) } : {}),
+      method: first.method.toLowerCase(),
+      path,
+      pathParams: labels,
+      query: [...query.values()].sort((a, b) => a.name.localeCompare(b.name)),
+      body: [...body.values()].sort((a, b) => a.name.localeCompare(b.name)),
+      bodyEncoding,
+      successStatus: 200,
+      class: 'action',
+    };
+  });
+  // two routes whose first calls share a client method (one method calling twice) keep distinct ids
+  const seen = new Map<string, number>();
+  for (const o of operations.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))) {
+    const n = (seen.get(o.id) ?? 0) + 1;
+    seen.set(o.id, n);
+    if (n > 1) o.id = `${o.id}_${n}`;
+  }
+  return { format: 'client', version: spec.version, resources: [], operations };
+}

package/src/spec-ir-commands.ts

@@ -0,0 +1,50 @@
+// A command language's spec as data: the commands a client names in each request and what each takes and answers,
+// read from the vendor's own command table. Redis publishes one file per command (redis/redis src/commands/<name>.json:
+// its group, the version it arrived in, its arity, its arguments, its flags and its reply's schema); a pack whose wire
+// carries Redis commands (Upstash's REST API: a command and its arguments in the path or the body) vendors the files of
+// the commands its vendor serves and derives its command surface from them, as a line protocol's surface is its RFC's
+// command table (spec-ir-lines.ts). A spec patch corrects the data as it corrects a JSON spec (derive-pack).
+
+export type CommandArgument = { name: string; type: string; optional?: boolean; multiple?: boolean; token?: string; arguments?: CommandArgument[] };
+/** A command: `id` as a client names it (`SET`, `CLIENT GETNAME` for a container's subcommand); `arity` as Redis gives
+ *  it (n: exactly n words with the name; -n: at least n). */
+export type CommandDef = { id: string; group: string; since: string; arity: number; summary: string; flags: string[]; arguments: CommandArgument[]; reply?: unknown };
+export type CommandTableSpec = { format: 'command-table'; version: string; commands: CommandDef[] };
+
+type RedisCommandFile = Record<string, {
+  summary?: string; group?: string; since?: string; arity?: number; container?: string;
+  command_flags?: string[]; arguments?: Array<Record<string, unknown>>; reply_schema?: unknown;
+}>;
+
+function argumentOf(a: Record<string, unknown>): CommandArgument {
+  return {
+    name: String(a.name),
+    type: String(a.type),
+    ...(a.optional === true ? { optional: true } : {}),
+    ...(a.multiple === true ? { multiple: true } : {}),
+    ...(typeof a.token === 'string' ? { token: a.token } : {}),
+    ...(Array.isArray(a.arguments) ? { arguments: (a.arguments as Array<Record<string, unknown>>).map(argumentOf) } : {}),
+  };
+}
+
+/** The command table of the vendored files (file name → its parsed JSON), in command order. */
+export function fromRedisCommands(files: Record<string, RedisCommandFile>, version: string): CommandTableSpec {
+  const commands: CommandDef[] = [];
+  for (const [file, doc] of Object.entries(files)) {
+    for (const [name, c] of Object.entries(doc)) {
+      if (typeof c?.arity !== 'number') throw new Error(`spec-ir-commands: ${file}: ${name} gives no arity`);
+      commands.push({
+        id: c.container ? `${c.container} ${name}` : name,
+        group: String(c.group ?? ''),
+        since: String(c.since ?? ''),
+        arity: c.arity,
+        summary: String(c.summary ?? ''),
+        flags: c.command_flags ?? [],
+        arguments: (c.arguments ?? []).map(argumentOf),
+        ...(c.reply_schema !== undefined ? { reply: c.reply_schema } : {}),
+      });
+    }
+  }
+  commands.sort((a, b) => a.id.localeCompare(b.id));
+  return { format: 'command-table', version, commands };
+}

package/src/spec-ir-discovery.ts

@@ -0,0 +1,104 @@
+// A Google API Discovery document as the IR (spec-ir.ts): the spec every Google REST API publishes at
+// `https://<api>.googleapis.com/$discovery/rest?version=<v>` (https://developers.google.com/discovery/v1/reference/apis),
+// and the one its own generated clients (googleapis, @googleapis/<api>) are built from. Google publishes no OpenAPI
+// document for these APIs, so the Discovery document is the vendor's spec.
+//
+// The document is read into the OpenAPI 3 shape `fromOpenAPI` reads, as a Swagger 2 document is (fromSwagger2), with
+// nothing vendor-specific beyond the Discovery format itself:
+//
+// - every method of every resource (recursively) is one operation: its `id` (`calendar.events.list`) is the
+//   operationId, its `httpMethod` and `path` (relative to `rootUrl` + `servicePath`, which becomes the server) are its
+//   route (a reserved expansion, `{+name}`, is read as a plain parameter: Calendar has none; an API whose path values hold
+//   slashes needs the `spanning` routes and is not yet read by this reader), its `path`-located parameters are path parameters and its `query`-located ones query parameters, a
+//   `repeated` parameter an array;
+// - the document's own `parameters` (Google's standard query parameters: `fields`, `key`, `oauth_token`,
+//   `prettyPrint`, `quotaUser`, `alt`, `userIp`, https://cloud.google.com/apis/docs/system-parameters) are parameters
+//   of every operation, as every method takes them;
+// - `request.$ref` is a JSON request body of that schema, and `response.$ref` the 200 answer; a method with no
+//   `response` answers 204 with no body (Google's REST answer to a delete or a stop);
+// - `scopes` is the operation's security requirement (any one scope lets the call through), under the document's
+//   `auth.oauth2` scheme;
+// - `schemas` are the component schemas, each `$ref: "Name"` rewritten to `#/components/schemas/Name`, and a
+//   Discovery `type: "any"` read as a schema of any type.
+import { fromOpenAPI, type SpecIR } from './spec-ir.ts';
+
+type Json = any;
+
+/** A Discovery schema as an OpenAPI 3 schema. */
+function schemaOf(node: Json): Json {
+  if (Array.isArray(node)) return node.map(schemaOf);
+  if (!node || typeof node !== 'object') return node;
+  const out: Json = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (k === '$ref' && typeof v === 'string') out.$ref = `#/components/schemas/${v}`;
+    else if (k === 'type' && v === 'any') continue;
+    // a schema's own `id` names it in the Discovery format; OpenAPI names it by its key
+    else if (k === 'id' && typeof v === 'string' && typeof node.type === 'string' && !('location' in node)) continue;
+    else if (k === 'properties' && v && typeof v === 'object') out.properties = Object.fromEntries(Object.entries(v).map(([p, s]) => [p, schemaOf(s)]));
+    else if (k === 'items' || k === 'additionalProperties') out[k] = schemaOf(v);
+    else if (k === 'annotations' || k === 'enumDescriptions' || k === 'location' || k === 'repeated') continue;
+    else out[k] = v;
+  }
+  return out;
+}
+
+/** A Discovery parameter as an OpenAPI 3 parameter. */
+function parameterOf(name: string, p: Json): Json {
+  const scalar = schemaOf({ ...p, description: undefined });
+  delete scalar.description;
+  delete scalar.required;
+  const schema = p.repeated ? { type: 'array', items: scalar } : scalar;
+  return { name, in: p.location === 'path' ? 'path' : 'query', ...(p.required || p.location === 'path' ? { required: true } : {}), ...(p.description ? { description: p.description } : {}), schema };
+}
+
+/** Every method of a Discovery resource tree, depth first, in the document's order. */
+export function discoveryMethods(resources: Json): Json[] {
+  const out: Json[] = [];
+  for (const r of Object.values(resources ?? {}) as Json[]) {
+    for (const m of Object.values(r?.methods ?? {}) as Json[]) out.push(m);
+    out.push(...discoveryMethods(r?.resources));
+  }
+  return out;
+}
+
+/** A Google API Discovery document as an OpenAPI 3 document (the shape `fromOpenAPI` reads). */
+export function discoveryToOpenAPI(doc: Json): Json {
+  const global = (doc.parameters ?? {}) as Record<string, Json>;
+  const paths: Record<string, Record<string, Json>> = {};
+  for (const m of discoveryMethods(doc.resources)) {
+    const path = `/${String(m.path).replace(/^\//, '').replace(/\{\+/g, '{')}`;
+    const own = Object.entries((m.parameters ?? {}) as Record<string, Json>);
+    const parameters = [
+      ...own.filter(([, p]) => p.location === 'path').map(([n, p]) => parameterOf(n, p)),
+      ...own.filter(([, p]) => p.location === 'query').map(([n, p]) => parameterOf(n, p)),
+      ...Object.entries(global).filter(([n]) => !own.some(([o]) => o === n)).map(([n, p]) => parameterOf(n, p)),
+    ];
+    const response = m.response?.$ref ? { 200: { description: 'Successful response', content: { 'application/json': { schema: { $ref: `#/components/schemas/${m.response.$ref}` } } } } } : { 204: { description: 'Successful response with no body' } };
+    (paths[path] ??= {})[String(m.httpMethod).toLowerCase()] = {
+      operationId: m.id,
+      ...(m.description ? { description: m.description } : {}),
+      parameters,
+      ...(m.request?.$ref ? { requestBody: { content: { 'application/json': { schema: { $ref: `#/components/schemas/${m.request.$ref}` } } } } } : {}),
+      responses: response,
+      ...(Array.isArray(m.scopes) && m.scopes.length ? { security: [{ Oauth2: m.scopes }] } : {}),
+    };
+  }
+  return {
+    openapi: '3.0.0',
+    info: { title: doc.title ?? doc.name, version: doc.version, description: doc.description, 'x-revision': doc.revision },
+    servers: [{ url: `${String(doc.rootUrl ?? '').replace(/\/+$/, '')}/${String(doc.servicePath ?? '').replace(/^\/+/, '')}`.replace(/\/+$/, '') }],
+    components: {
+      schemas: Object.fromEntries(Object.entries((doc.schemas ?? {}) as Record<string, Json>).map(([n, s]) => [n, schemaOf(s)])),
+      ...(doc.auth?.oauth2 ? { securitySchemes: { Oauth2: { type: 'oauth2', flows: { authorizationCode: { authorizationUrl: 'https://accounts.google.com/o/oauth2/auth', tokenUrl: 'https://oauth2.googleapis.com/token', scopes: Object.fromEntries(Object.entries(doc.auth.oauth2.scopes ?? {}).map(([s, d]: [string, Json]) => [s, d?.description ?? ''])) } } } } } : {}),
+    },
+    paths,
+  };
+}
+
+/** Is this a Google API Discovery document? */
+export const isDiscovery = (doc: Json): boolean => doc?.kind === 'discovery#restDescription';
+
+/** A Google API Discovery document as the IR. */
+export function fromDiscovery(doc: Json): SpecIR {
+  return fromOpenAPI(discoveryToOpenAPI(doc));
+}

package/src/spec-ir-graphql.ts

@@ -0,0 +1,64 @@
+// THE SPEC IR's GraphQL front end: a vendor's published SDL as operations the derived-pack generator
+// reads (docs/contributing/architecture.md, "Protocol 3"). A GraphQL API is one endpoint whose
+// operations are its root fields: each Query field is a read, each Mutation field a write. Resources
+// are the object types a caller can refetch (those implementing `Node`, or carrying an `id: ID!`).
+// Kept apart from spec-ir.ts because it needs the `graphql` protocol library.
+import { buildSchema, getNamedType, isListType, isNonNullType, isObjectType, type GraphQLField, type GraphQLObjectType, type GraphQLOutputType } from 'graphql';
+import type { OperationClass } from './spec-ir.ts';
+
+export type GraphqlOperation = {
+  /** `query.<field>` or `mutation.<field>` */
+  id: string;
+  kind: 'query' | 'mutation';
+  field: string;
+  args: Array<{ name: string; type: string; required: boolean }>;
+  /** the named type the field returns, and whether it is a list or a connection of it */
+  returns: string;
+  class: OperationClass;
+  resource?: string;
+};
+
+export type GraphqlIR = { format: 'graphql'; resources: Array<{ name: string; fields: string[] }>; operations: GraphqlOperation[] };
+
+const unwrap = (t: GraphQLOutputType): GraphQLOutputType => (isNonNullType(t) ? unwrap(t.ofType) : t);
+
+export function fromGraphQL(sdl: string): GraphqlIR {
+  const schema = buildSchema(sdl, { assumeValidSDL: true });
+  const isResource = (t: GraphQLObjectType): boolean => t.getInterfaces().some((i) => i.name === 'Node') || !!t.getFields().id;
+  const resources = Object.values(schema.getTypeMap())
+    .filter((t): t is GraphQLObjectType => isObjectType(t) && !t.name.startsWith('__') && isResource(t))
+    .map((t) => ({ name: t.name, fields: Object.keys(t.getFields()).sort() }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const names = new Set(resources.map((r) => r.name));
+  const connectionOf = (t: GraphQLObjectType): string | undefined => {
+    const nodes = t.getFields().nodes;
+    return t.name.endsWith('Connection') && nodes ? getNamedType(nodes.type).name : undefined;
+  };
+  const operations: GraphqlOperation[] = [];
+  for (const [kind, root] of [['query', schema.getQueryType()], ['mutation', schema.getMutationType()]] as const) {
+    for (const f of Object.values(root?.getFields() ?? {}) as Array<GraphQLField<unknown, unknown>>) {
+      const bare = unwrap(f.type);
+      const named = getNamedType(f.type);
+      const connection = isObjectType(named) ? connectionOf(named) : undefined;
+      const list = isListType(bare) || !!connection;
+      const target = connection ?? named.name;
+      const resource = names.has(target) ? target : undefined;
+      const verb = f.name.toLowerCase();
+      const cls: OperationClass =
+        kind === 'query'
+          ? list ? 'list' : resource ? 'retrieve' : 'computed'
+          : /^(create|add)/.test(verb) ? 'create' : /^(update|edit|set)/.test(verb) ? 'update' : /^(delete|remove)/.test(verb) ? 'delete' : 'action';
+      operations.push({
+        id: `${kind}.${f.name}`,
+        kind,
+        field: f.name,
+        args: f.args.map((a) => ({ name: a.name, type: String(a.type), required: isNonNullType(a.type) })).sort((a, b) => a.name.localeCompare(b.name)),
+        returns: target,
+        class: cls,
+        ...(resource ? { resource } : {}),
+      });
+    }
+  }
+  operations.sort((a, b) => a.id.localeCompare(b.id));
+  return { format: 'graphql', resources, operations };
+}

package/src/spec-ir-lines.ts

@@ -0,0 +1,76 @@
+// A line protocol's spec as data: the commands a client sends and the replies each may be answered,
+// read from the RFC's own table of them. The IR a byte-stream pack derives its surface from, as an HTTP
+// pack derives its from an OpenAPI document; a spec patch corrects it the same way (derive-pack).
+//
+// SMTP's table is RFC 5321 §4.3.2 "Command-Reply Sequences": each command, then its intermediate (I),
+// success (S) and error (E) codes, where `I: 354 -> data -> S: 250` says what answers the lines that
+// follow an intermediate reply. Every command may also answer the section's "any SMTP command" codes.
+
+export type LineReplies = { intermediate: number[]; success: number[]; error: number[] };
+/** A command and its replies; `then`, what answers the lines after an intermediate reply (DATA's payload,
+ *  a SASL exchange). */
+export type LineCommand = LineReplies & { id: string; then?: LineReplies };
+export type LineSpec = { format: 'command-reply'; version: string; anyCommand: number[]; commands: LineCommand[] };
+
+const codes = (text: string): number[] => [...new Set((text.replace(/\([^)]*\)/g, '').match(/\b[2-5]\d\d\b/g) ?? []).map(Number))];
+
+/** The replies in one level of a command's entry: `S: 250 E: 552, 451` and the like. */
+function replies(text: string): LineReplies {
+  const out: LineReplies = { intermediate: [], success: [], error: [] };
+  // `S: 250 E: 552, 451` splits into its letters and what follows each
+  const parts = text.replace(/\([^)]*\)/g, '').split(/\b([ISE]):/);
+  for (let i = 1; i < parts.length; i += 2) {
+    const key = parts[i] === 'I' ? 'intermediate' : parts[i] === 'S' ? 'success' : 'error';
+    out[key] = [...new Set([...out[key], ...codes(parts[i + 1]!)])];
+  }
+  return out;
+}
+
+/** The command-reply table of an RFC in RFC 5321's form, from the RFC's text. */
+export function fromCommandReplies(text: string, section = '4.3.2'): LineSpec {
+  const lines = text.split('\n')
+    // a page's footer and the next page's header are the RFC's pagination, not its words
+    .filter((l) => !/\[Page \d+\]\s*$/.test(l) && !/^RFC \d+\s{2,}/.test(l) && !l.includes('\f'));
+  const start = lines.findIndex((l) => l.startsWith(`${section}.  `));
+  if (start < 0) throw new Error(`spec-ir-lines: the text has no section ${section}`);
+  const end = lines.findIndex((l, i) => i > start && /^\d+(\.\d+)*\.\s{2}/.test(l));
+  const body = lines.slice(start + 1, end < 0 ? undefined : end);
+  const version = /^Request for Comments:\s*(\d+)/m.exec(text)?.[1];
+  // the codes any command may answer: the list the section gives before its specific sequences
+  const specific = body.findIndex((l) => /Specific sequences are:/.test(l));
+  const anyCommand = body.slice(0, specific).filter((l) => /^\s{3}\d{3}\s{2}/.test(l)).map((l) => Number(l.trim().slice(0, 3)));
+  const commands: LineCommand[] = [];
+  let entry: { names: string[]; own: string[]; data: string[] } | undefined;
+  let deep = false;
+  const close = () => {
+    if (!entry) return;
+    const own = replies(entry.own.join(' '));
+    const then = entry.data.length ? replies(`S:${entry.data.join(' ')}`) : undefined;
+    for (const id of entry.names) commands.push({ id, ...own, ...(then ? { then } : {}) });
+  };
+  for (const line of body.slice(specific + 1)) {
+    if (!line.trim()) continue;
+    const indent = line.length - line.trimStart().length;
+    // a command's heading is its name in capitals, one level in ("EHLO or HELO", "CONNECTION ESTABLISHMENT")
+    if (indent <= 6 && /^[A-Z]+(?: (?:or )?[A-Z]+)*$/.test(line.trim())) {
+      close();
+      entry = { names: line.trim().split(' or '), own: [], data: [] };
+      deep = false;
+      continue;
+    }
+    if (!entry) continue;
+    const arrow = line.lastIndexOf('->');
+    if (arrow >= 0) {
+      // `I: 354 -> data -> S: 250`: the first part is the command's own, what follows the last arrow answers the data
+      entry.own.push(line.slice(0, line.indexOf('->')));
+      entry.data.push(line.slice(arrow + 2).replace(/^\s*S:/, ''));
+      deep = true;
+      continue;
+    }
+    // what is indented past the command's own replies continues what answers the data
+    if (deep && indent > 12) entry.data.push(line);
+    else { deep = false; entry.own.push(line); }
+  }
+  close();
+  return { format: 'command-reply', version: version ? `RFC ${version}` : section, anyCommand, commands };
+}