@ultimat3/cli 29.4.0 → 30.1.0

package/src/openapi-compile-schema.ts

@@ -0,0 +1,284 @@
+// One JSON Schema (OpenAPI 3.0 or 3.1) to a `ClientType`: `$ref`, objects, arrays, enums, `const`,
+// `oneOf`/`anyOf`, `allOf`, nullable. A keyword that would change a value's shape and is not one of
+// those is refused with its pointer; a keyword that only narrows a value is not a shape and is read
+// past. Named components are compiled on first reach, so a recursive `$ref` is a name, not a loop.
+
+import type { ClientField, ClientObject, ClientType } from './openapi-compile-ir';
+import { objectAt, own, pointerJoin, unsupported } from './openapi-refuse';
+
+const SHAPE_KEYS = new Set([
+  'type',
+  'properties',
+  'required',
+  'additionalProperties',
+  'items',
+  'enum',
+  'const',
+  'oneOf',
+  'anyOf',
+  'allOf',
+  '$ref',
+  'nullable',
+]);
+
+/** Annotations and value narrowings: true of a value, never a different shape for it. */
+const NARROWING_KEYS = new Set([
+  '$schema',
+  '$id',
+  '$comment',
+  '$defs',
+  'title',
+  'description',
+  'default',
+  'example',
+  'examples',
+  'deprecated',
+  'readOnly',
+  'writeOnly',
+  'format',
+  'minLength',
+  'maxLength',
+  'pattern',
+  'minimum',
+  'maximum',
+  'exclusiveMinimum',
+  'exclusiveMaximum',
+  'multipleOf',
+  'minItems',
+  'maxItems',
+  'uniqueItems',
+  'minProperties',
+  'maxProperties',
+  'propertyNames',
+  'discriminator',
+  'externalDocs',
+  'xml',
+  'contentMediaType',
+  'contentEncoding',
+]);
+
+const COMPONENT_REF = '#/components/schemas/';
+const UNKNOWN: ClientType = { kind: 'unknown' };
+const NULL: ClientType = { kind: 'null' };
+
+/** The component table the compiler fills as operations reach it. */
+export interface SchemaScope {
+  readonly components: Readonly<Record<string, unknown>>;
+  /** Component name → its compiled type; `null` while that component is being compiled. */
+  readonly compiled: Map<string, ClientType | null>;
+}
+
+/** `review-draft.input` → `ReviewDraftInput`: a TypeScript identifier, case kept inside a word. */
+export function typeName(name: string): string {
+  const words = name.split(/[^A-Za-z0-9]+/).filter((word) => word.length > 0);
+  const joined = words.map((word) => `${word[0]?.toUpperCase() ?? ''}${word.slice(1)}`).join('');
+  return /^[0-9]/.test(joined) || joined === '' ? `T${joined}` : joined;
+}
+
+/** A union with nested unions flattened and duplicates dropped; one member is that member. */
+export function unionOf(members: readonly ClientType[]): ClientType {
+  const seen = new Map<string, ClientType>();
+  for (const member of members.flatMap((m) => (m.kind === 'union' ? m.members : [m]))) {
+    seen.set(JSON.stringify(member), member);
+  }
+  const unique = [...seen.values()];
+  if (unique.some((member) => member.kind === 'unknown')) return UNKNOWN;
+  return unique.length === 1 ? (unique[0] as ClientType) : { kind: 'union', members: unique };
+}
+
+function reachComponent(scope: SchemaScope, ref: string, pointer: string): ClientType {
+  if (!ref.startsWith(COMPONENT_REF)) return refuse(pointer, `the $ref ${ref}`);
+  const name = ref.slice(COMPONENT_REF.length).replace(/~1/g, '/').replace(/~0/g, '~');
+  const target = own(scope.components, name);
+  if (target === undefined) return refuse(pointer, `a $ref to a missing component (${ref})`);
+  if (!scope.compiled.has(name)) {
+    scope.compiled.set(name, null);
+    scope.compiled.set(name, compileSchema(scope, target, `${COMPONENT_REF}${name}`));
+  }
+  return { kind: 'ref', name };
+}
+
+function refuse(pointer: string, construct: string): never {
+  throw unsupported(pointer, construct);
+}
+
+/** A type as an object to merge into, a `$ref` followed; anything else is refused. */
+function asObject(scope: SchemaScope, type: ClientType, pointer: string): ClientObject {
+  if (type.kind === 'object') return type;
+  if (type.kind === 'ref') {
+    const target = scope.compiled.get(type.name);
+    if (target === null) return refuse(pointer, 'an allOf through a recursive $ref');
+    if (target !== undefined) return asObject(scope, target, pointer);
+  }
+  return refuse(pointer, `an allOf or oneOf member that is not an object (${type.kind})`);
+}
+
+/** Field by field, the later declaration winning: an `allOf` narrows what it extends. */
+function mergeObjects(objects: readonly ClientObject[]): ClientObject {
+  const fields = new Map<string, ClientField>();
+  for (const object of objects) {
+    for (const field of object.fields) {
+      const before = fields.get(field.name);
+      fields.set(field.name, { ...field, required: field.required || before?.required === true });
+    }
+  }
+  return { kind: 'object', fields: [...fields.values()] };
+}
+
+function objectOf(
+  scope: SchemaScope,
+  schema: Readonly<Record<string, unknown>>,
+  pointer: string,
+): ClientType {
+  const properties = objectAt(schema['properties']) ?? {};
+  const required = new Set(Array.isArray(schema['required']) ? schema['required'].map(String) : []);
+  const names = [...new Set([...Object.keys(properties), ...required])];
+  const fields = names.map((name) => ({
+    name,
+    required: required.has(name),
+    type: Object.hasOwn(properties, name)
+      ? compileSchema(
+          scope,
+          properties[name],
+          pointerJoin(pointerJoin(pointer, 'properties'), name),
+        )
+      : UNKNOWN,
+  }));
+  const extra = schema['additionalProperties'];
+  if (extra !== undefined && typeof extra !== 'boolean') {
+    if (fields.length > 0) return refuse(pointer, 'properties beside a typed additionalProperties');
+    return {
+      kind: 'record',
+      values: compileSchema(scope, extra, pointerJoin(pointer, 'additionalProperties')),
+    };
+  }
+  if (fields.length === 0 && extra !== false) return { kind: 'record', values: UNKNOWN };
+  return { kind: 'object', fields };
+}
+
+function typed(
+  scope: SchemaScope,
+  schema: Readonly<Record<string, unknown>>,
+  type: unknown,
+  pointer: string,
+): ClientType {
+  switch (type) {
+    case 'string':
+      return { kind: 'string' };
+    case 'integer':
+    case 'number':
+      return { kind: 'number', integer: type === 'integer' };
+    case 'boolean':
+      return { kind: 'boolean' };
+    case 'null':
+      return NULL;
+    case 'array':
+      return {
+        kind: 'array',
+        items:
+          schema['items'] === undefined
+            ? UNKNOWN
+            : compileSchema(scope, schema['items'], pointerJoin(pointer, 'items')),
+      };
+    case 'object':
+      return objectOf(scope, schema, pointer);
+    default:
+      return refuse(pointerJoin(pointer, 'type'), `the type ${JSON.stringify(type)}`);
+  }
+}
+
+function literalOf(value: unknown, pointer: string): ClientType {
+  if (value === null) return NULL;
+  if (typeof value === 'string' || typeof value === 'boolean') return { kind: 'literal', value };
+  if (typeof value === 'number' && Number.isFinite(value)) return { kind: 'literal', value };
+  return refuse(pointer, 'an enum or const value that is not a string, number, boolean or null');
+}
+
+/** What a schema with no combinator says: its `type` (or the type its keywords imply). */
+function shapeOf(
+  scope: SchemaScope,
+  schema: Readonly<Record<string, unknown>>,
+  pointer: string,
+): ClientType {
+  if (Array.isArray(schema['enum'])) {
+    return unionOf(schema['enum'].map((value, i) => literalOf(value, pointerJoin(pointer, i))));
+  }
+  if (Object.hasOwn(schema, 'const'))
+    return literalOf(schema['const'], pointerJoin(pointer, 'const'));
+  if (Array.isArray(schema['type'])) {
+    return unionOf(schema['type'].map((type) => typed(scope, schema, type, pointer)));
+  }
+  if (schema['type'] !== undefined) return typed(scope, schema, schema['type'], pointer);
+  if (schema['properties'] !== undefined || schema['additionalProperties'] !== undefined) {
+    return objectOf(scope, schema, pointer);
+  }
+  if (schema['required'] !== undefined) return objectOf(scope, schema, pointer);
+  if (schema['items'] !== undefined) return typed(scope, schema, 'array', pointer);
+  return UNKNOWN;
+}
+
+const hasShape = (schema: Readonly<Record<string, unknown>>): boolean =>
+  ['type', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'const'].some((key) =>
+    Object.hasOwn(schema, key),
+  );
+
+const without = (
+  schema: Readonly<Record<string, unknown>>,
+  keys: readonly string[],
+): Readonly<Record<string, unknown>> =>
+  Object.fromEntries(Object.entries(schema).filter(([key]) => !keys.includes(key)));
+
+function combined(
+  scope: SchemaScope,
+  schema: Readonly<Record<string, unknown>>,
+  pointer: string,
+): ClientType {
+  if (typeof schema['$ref'] === 'string') {
+    const target = reachComponent(scope, schema['$ref'], pointerJoin(pointer, '$ref'));
+    const rest = without(schema, ['$ref']);
+    if (!hasShape(rest) && rest['allOf'] === undefined) return target;
+    const merged = mergeObjects([
+      asObject(scope, target, pointer),
+      asObject(scope, compileSchema(scope, rest, pointer), pointer),
+    ]);
+    return merged;
+  }
+  if (Array.isArray(schema['allOf'])) {
+    const members = schema['allOf'].map((member, i) =>
+      compileSchema(scope, member, pointerJoin(pointerJoin(pointer, 'allOf'), i)),
+    );
+    const rest = without(schema, ['allOf']);
+    const all = hasShape(rest) ? [...members, compileSchema(scope, rest, pointer)] : members;
+    if (all.length === 1) return all[0] as ClientType;
+    return mergeObjects(all.map((member) => asObject(scope, member, pointer)));
+  }
+  const key = Array.isArray(schema['oneOf'])
+    ? 'oneOf'
+    : Array.isArray(schema['anyOf'])
+      ? 'anyOf'
+      : '';
+  if (key !== '') {
+    const list = schema[key] as readonly unknown[];
+    const members = list.map((member, i) =>
+      compileSchema(scope, member, pointerJoin(pointerJoin(pointer, key), i)),
+    );
+    const rest = without(schema, ['oneOf', 'anyOf']);
+    if (!hasShape(rest)) return unionOf(members);
+    const base = asObject(scope, shapeOf(scope, rest, pointer), pointer);
+    return unionOf(members.map((member) => mergeObjects([base, asObject(scope, member, pointer)])));
+  }
+  return shapeOf(scope, schema, pointer);
+}
+
+/** The one entry point: a schema at `pointer` to its `ClientType`, or a refusal naming where. */
+export function compileSchema(scope: SchemaScope, schema: unknown, pointer: string): ClientType {
+  if (schema === true) return UNKNOWN;
+  const node = objectAt(schema);
+  if (node === undefined) return refuse(pointer, 'a schema that is not an object');
+  for (const key of Object.keys(node)) {
+    if (SHAPE_KEYS.has(key) || NARROWING_KEYS.has(key) || key.startsWith('x-')) continue;
+    refuse(pointerJoin(pointer, key), `the keyword ${key}`);
+  }
+  const type = combined(scope, node, pointer);
+  return node['nullable'] === true ? unionOf([type, NULL]) : type;
+}

package/src/openapi-compile.ts

@@ -0,0 +1,273 @@
+// An OpenAPI 3.0/3.1 document to the neutral operation list both client emitters read — the ONLY
+// reader of OpenAPI in the client path. Operations are compiled first and components only as an
+// operation reaches them, so `--only` around a construct the compiler refuses really leaves it out.
+
+import type {
+  ClientBody,
+  ClientMethod,
+  ClientOperation,
+  ClientParameter,
+  ClientType,
+  CompiledDocument,
+} from './openapi-compile-ir';
+import type { SchemaScope } from './openapi-compile-schema';
+import { compileSchema, typeName } from './openapi-compile-schema';
+import { ClientSpecInvalidError, objectAt, own, pointerJoin, unsupported } from './openapi-refuse';
+
+type Json = Readonly<Record<string, unknown>>;
+
+const METHODS: ReadonlyMap<string, ClientMethod> = new Map([
+  ['get', 'GET'],
+  ['put', 'PUT'],
+  ['post', 'POST'],
+  ['delete', 'DELETE'],
+  ['options', 'OPTIONS'],
+  ['head', 'HEAD'],
+  ['patch', 'PATCH'],
+]);
+const PATH_ITEM_KEYS = new Set(['summary', 'description', 'servers', 'parameters']);
+const JSON_MEDIA = /^application\/(?:[\w.-]+\+)?json$/;
+
+export interface CompileOptions {
+  /** Where the document came from, for a refusal's cause. */
+  readonly source: string;
+  /** Keep only operations carrying one of these tags. */
+  readonly only?: readonly string[] | undefined;
+}
+
+/** `invoices.get` → `invoicesGet`: a TypeScript identifier, first letter lower. */
+export function operationName(id: string): string {
+  const pascal = typeName(id);
+  return /^T[0-9]/.test(pascal) ? pascal : `${pascal[0]?.toLowerCase() ?? ''}${pascal.slice(1)}`;
+}
+
+/** No `operationId`: method then path, `{id}` read as `ById` — still a pure function of the doc. */
+const derivedName = (method: string, path: string): string =>
+  operationName(
+    [method, ...path.split('/').map((s) => s.replace(/^\{(.+)\}$/, 'by-$1'))].join('-'),
+  );
+
+/** A `$ref` into `#/components/<section>/` followed once; anything else is the value itself. */
+function deref(document: Json, value: unknown, pointer: string): { node: Json; at: string } {
+  const node = objectAt(value);
+  if (node === undefined) throw unsupported(pointer, 'a value that is not an object');
+  if (typeof node['$ref'] !== 'string') return { node, at: pointer };
+  const segments = node['$ref'].startsWith('#/components/') ? node['$ref'].slice(2).split('/') : [];
+  let target: unknown = document;
+  for (const raw of segments) {
+    const record = objectAt(target);
+    target =
+      record === undefined ? undefined : own(record, raw.replace(/~1/g, '/').replace(/~0/g, '~'));
+  }
+  const resolved = objectAt(target);
+  if (segments.length !== 3 || resolved === undefined) {
+    throw unsupported(pointerJoin(pointer, '$ref'), `the $ref ${node['$ref']}`);
+  }
+  return { node: resolved, at: node['$ref'] };
+}
+
+/** The JSON media entry of a `content` map; `undefined` when there is none at all. */
+function jsonSchemaOf(
+  content: unknown,
+  pointer: string,
+): { schema: unknown; at: string } | undefined {
+  const media = objectAt(content);
+  if (media === undefined || Object.keys(media).length === 0) return undefined;
+  const key = Object.keys(media).find((type) => JSON_MEDIA.test(type));
+  if (key === undefined) {
+    throw unsupported(pointer, `a body that is not JSON (${Object.keys(media).join(', ')})`);
+  }
+  const entry = objectAt(media[key]) ?? {};
+  return { schema: entry['schema'] ?? true, at: pointerJoin(pointerJoin(pointer, key), 'schema') };
+}
+
+function parameterOf(
+  document: Json,
+  scope: SchemaScope,
+  raw: unknown,
+  pointer: string,
+): ClientParameter {
+  const { node, at } = deref(document, raw, pointer);
+  const where = node['in'];
+  if (where !== 'path' && where !== 'query' && where !== 'header') {
+    throw unsupported(pointerJoin(at, 'in'), `a parameter in ${String(where)}`);
+  }
+  if (node['schema'] === undefined)
+    throw unsupported(at, 'a parameter with content instead of schema');
+  const type = compileSchema(scope, node['schema'], pointerJoin(at, 'schema'));
+  if (where === 'query' && (type.kind === 'object' || type.kind === 'record')) {
+    throw unsupported(pointerJoin(at, 'schema'), 'an object-valued query parameter');
+  }
+  return {
+    name: String(node['name']),
+    in: where,
+    required: node['required'] === true || where === 'path',
+    type,
+  };
+}
+
+const isObjectBody = (scope: SchemaScope, type: ClientType): boolean => {
+  if (type.kind === 'object') return true;
+  const target = type.kind === 'ref' ? scope.compiled.get(type.name) : undefined;
+  return target !== undefined && target !== null && target.kind === 'object';
+};
+
+function bodyOf(
+  document: Json,
+  scope: SchemaScope,
+  raw: unknown,
+  pointer: string,
+): ClientBody | undefined {
+  if (raw === undefined) return undefined;
+  const { node, at } = deref(document, raw, pointer);
+  const found = jsonSchemaOf(node['content'], pointerJoin(at, 'content'));
+  if (found === undefined) return undefined;
+  const type = compileSchema(scope, found.schema, found.at);
+  const required = node['required'] === true;
+  return isObjectBody(scope, type)
+    ? { mode: 'fields', type, required }
+    : { mode: 'value', type, required };
+}
+
+function responseOf(
+  document: Json,
+  scope: SchemaScope,
+  responses: Json,
+  pointer: string,
+): ClientType | undefined {
+  const success = Object.keys(responses)
+    .filter((status) => /^2(?:\d\d|XX)$/.test(status))
+    .sort()[0];
+  if (success === undefined) return undefined;
+  const { node, at } = deref(document, responses[success], pointerJoin(pointer, success));
+  const found = jsonSchemaOf(node['content'], pointerJoin(at, 'content'));
+  return found === undefined ? undefined : compileSchema(scope, found.schema, found.at);
+}
+
+function refusalsOf(responses: Json): readonly string[] {
+  const codes = new Set<string>();
+  for (const [status, value] of Object.entries(responses)) {
+    const declared = /^2/.test(status) ? undefined : objectAt(value)?.['x-ultimate-errors'];
+    if (Array.isArray(declared)) for (const code of declared) codes.add(String(code));
+  }
+  return [...codes].sort();
+}
+
+function operationOf(
+  document: Json,
+  scope: SchemaScope,
+  input: {
+    path: string;
+    method: string;
+    op: Json;
+    shared: readonly unknown[];
+    itemPointer: string;
+    pointer: string;
+  },
+): ClientOperation {
+  const { op, pointer } = input;
+  const byKey = new Map<string, ClientParameter>();
+  // Path-item parameters first, so an operation's own parameter of the same name and place wins.
+  const lists: readonly (readonly [readonly unknown[], string])[] = [
+    [input.shared, pointerJoin(input.itemPointer, 'parameters')],
+    [Array.isArray(op['parameters']) ? op['parameters'] : [], pointerJoin(pointer, 'parameters')],
+  ];
+  for (const [list, at] of lists) {
+    list.forEach((raw, i) => {
+      const parameter = parameterOf(document, scope, raw, pointerJoin(at, i));
+      byKey.set(`${parameter.in}:${parameter.name}`, parameter);
+    });
+  }
+  const parameters = [...byKey.values()];
+  const body = bodyOf(document, scope, op['requestBody'], pointerJoin(pointer, 'requestBody'));
+  if (body?.mode === 'value' && parameters.some((p) => p.name === 'body')) {
+    throw unsupported(
+      pointerJoin(pointer, 'parameters'),
+      'a parameter named body beside a non-object body',
+    );
+  }
+  const responses = objectAt(op['responses']) ?? {};
+  return {
+    name:
+      typeof op['operationId'] === 'string'
+        ? operationName(op['operationId'])
+        : derivedName(input.method, input.path),
+    method: METHODS.get(input.method) as ClientMethod,
+    path: input.path,
+    tags: Array.isArray(op['tags']) ? op['tags'].map(String) : [],
+    summary: typeof op['summary'] === 'string' ? op['summary'] : undefined,
+    parameters,
+    body,
+    response: responseOf(document, scope, responses, pointerJoin(pointer, 'responses')),
+    refusals: refusalsOf(responses),
+  };
+}
+
+function checkedDocument(document: unknown, source: string): Json {
+  const root = objectAt(document);
+  if (root === undefined)
+    throw new ClientSpecInvalidError({ source, reason: 'it is not a JSON object' });
+  const version = root['openapi'];
+  if (typeof version !== 'string' || !/^3\.[01]\.\d+/.test(version)) {
+    throw new ClientSpecInvalidError({ source, reason: 'its openapi field is not 3.0.x or 3.1.x' });
+  }
+  if (objectAt(root['paths']) === undefined) {
+    throw new ClientSpecInvalidError({ source, reason: 'it has no paths object' });
+  }
+  return root;
+}
+
+/** The whole document, in a deterministic order: operations by name, types by component name. */
+export function compileOpenApi(document: unknown, options: CompileOptions): CompiledDocument {
+  const root = checkedDocument(document, options.source);
+  const scope: SchemaScope = {
+    components: objectAt(objectAt(root['components'])?.['schemas']) ?? {},
+    compiled: new Map(),
+  };
+  const only = options.only === undefined ? undefined : new Set(options.only);
+  const operations: ClientOperation[] = [];
+  const paths = objectAt(root['paths']) ?? {};
+  for (const path of Object.keys(paths).sort()) {
+    const itemPointer = pointerJoin('#/paths', path);
+    const item = objectAt(paths[path]) ?? {};
+    const shared = Array.isArray(item['parameters']) ? item['parameters'] : [];
+    for (const [key, value] of Object.entries(item)) {
+      if (PATH_ITEM_KEYS.has(key) || key.startsWith('x-')) continue;
+      if (!METHODS.has(key))
+        throw unsupported(pointerJoin(itemPointer, key), `the path item key ${key}`);
+      const op = objectAt(value) ?? {};
+      const tags = Array.isArray(op['tags']) ? op['tags'].map(String) : [];
+      if (only !== undefined && !tags.some((tag) => only.has(tag))) continue;
+      const pointer = pointerJoin(itemPointer, key);
+      const compiled = operationOf(root, scope, {
+        path,
+        method: key,
+        op,
+        shared,
+        itemPointer,
+        pointer,
+      });
+      if (operations.some((other) => other.name === compiled.name)) {
+        throw unsupported(pointer, `a second operation named ${compiled.name}`);
+      }
+      operations.push(compiled);
+    }
+  }
+  const types = new Map<string, ClientType>();
+  const spelled = new Map<string, string>();
+  for (const name of [...scope.compiled.keys()].sort()) {
+    const clash = spelled.get(typeName(name));
+    if (clash !== undefined) {
+      throw unsupported(`#/components/schemas/${name}`, `a component spelled like ${clash}`);
+    }
+    spelled.set(typeName(name), name);
+    types.set(name, scope.compiled.get(name) as ClientType);
+  }
+  const info = objectAt(root['info']) ?? {};
+  return {
+    title: typeof info['title'] === 'string' ? info['title'] : options.source,
+    version: typeof info['version'] === 'string' ? info['version'] : '0.0.0',
+    types,
+    operations: operations.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+  };
+}

package/src/openapi-refuse.ts

@@ -0,0 +1,45 @@
+// The OpenAPI compiler's refusals: a document that is not OpenAPI 3.0/3.1, and a construct it will
+// not read, each naming the JSON pointer it stopped at. A construct is refused, never typed
+// `unknown` in silence. Codes and titles are registered in `error-codes.ts`.
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
+
+/** RFC 6901: `~` and `/` escaped, so a path key such as `/invoices/{id}` stays one segment. */
+export const pointerJoin = (pointer: string, key: string | number): string =>
+  `${pointer}/${String(key).replace(/~/g, '~0').replace(/\//g, '~1')}`;
+
+/** `#/paths/~1invoices/get` for a reader: the pointer as written in the document. */
+export class ClientSpecUnsupportedError extends UltimateError {
+  constructor(input: { readonly pointer: string; readonly construct: string }) {
+    super({
+      code: 'X_CLIENT_SPEC_UNSUPPORTED',
+      cause: `the document uses ${input.construct} at ${renderCauseValue(input.pointer)}, which the client compiler does not read`,
+      fix: 'x help client --json   # then rerun with --only naming tags that leave that operation out, or pin a corrected source.json',
+      meta: { pointer: input.pointer, construct: input.construct },
+    });
+  }
+}
+
+export class ClientSpecInvalidError extends UltimateError {
+  constructor(input: { readonly source: string; readonly reason: string }) {
+    super({
+      code: 'X_CLIENT_SPEC_INVALID',
+      cause: `${renderCauseValue(input.source)} is not an OpenAPI 3.0 or 3.1 document: ${input.reason}`,
+      fix: 'x help client --json   # then point --from at the OpenAPI 3.0 or 3.1 document itself',
+      meta: { source: input.source },
+    });
+  }
+}
+
+export const unsupported = (pointer: string, construct: string): ClientSpecUnsupportedError =>
+  new ClientSpecUnsupportedError({ pointer, construct });
+
+/** A plain JSON object, or `undefined` — the one narrowing every reader of the document uses. */
+export function objectAt(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Readonly<Record<string, unknown>>)
+    : undefined;
+}
+
+/** `value[key]` for an OWN key only: a component named `constructor` is a name, not a prototype. */
+export const own = (value: Readonly<Record<string, unknown>>, key: string): unknown =>
+  Object.hasOwn(value, key) ? value[key] : undefined;

package/src/otlp-export.ts

@@ -30,7 +30,8 @@ export const METRIC_EXPORT_INTERVAL_MS = 60_000;
  *
  * Both are registered with `onShutdown(..., { phase: 'close' })`: the last spans of a drain are
  * the ones that explain the drain, and a process that exits with a full queue loses exactly the
- * window an operator went looking for.
+ * window an operator went looking for. That phase runs last-registered first, so the boot calls this
+ * BEFORE anything whose teardown should be seen: everything registered after it flushes into it.
  *
  * The release UNINSTALLS what it installed, per signal. `configureTelemetry`/`configureMetrics`
  * merge into process-global state, so stopping the timer and dropping the drain hooks left the