blume 2.1.0 → 2.1.2

package/src/narration/provider.ts

@@ -1,29 +1,109 @@
 import { z } from "zod";
 
-import { GATEWAY_API_KEY_ENV, sharedOptions } from "../ai/ask.ts";
+import {
+  GATEWAY_API_KEY_ENV,
+  OPENAI_API_KEY_ENV,
+  sharedOptions,
+} from "../ai/ask.ts";
 import { adapterDescriptorSchema } from "../core/adapter.ts";
 
 /** The speech model narration uses when `gateway()` names none. */
 export const DEFAULT_NARRATION_MODEL = "openai/tts-1-hd";
 
-/** The voice narration uses when `gateway()` names none. */
+/** The voice narration uses when the provider names none. */
 export const DEFAULT_NARRATION_VOICE = "alloy";
 
 /**
- * `narration.provider`: the `gateway()` descriptor from `blume/ai`, read with
- * speech defaults. `reasoning` is an assistant option and is rejected here;
- * `voice` and `instructions` are narration options and are rejected by the
- * assistant.
+ * The AI SDK provider `openai()` narration speaks through, with or without a
+ * `baseUrl`: `@ai-sdk/openai-compatible` has no speech models.
  */
-export const narrationProviderSchema = adapterDescriptorSchema(
+export const OPENAI_SPEECH_DEP = "@ai-sdk/openai";
+
+/**
+ * Whether `url` carries a username or password, which `fetch` refuses to
+ * send and whose error message would print them. A URL that doesn't parse
+ * has none.
+ */
+export const hasCredentials = (url: string): boolean => {
+  const parsed = URL.parse(url);
+  return Boolean(parsed?.username || parsed?.password);
+};
+
+/** The narration options both providers take on top of the shared ones. */
+const speechOptions = {
+  instructions: z.string().min(1).optional(),
+  voice: z.string().min(1).default(DEFAULT_NARRATION_VOICE),
+};
+
+const gatewayNarrationSchema = adapterDescriptorSchema(
   "gateway",
   z.strictObject({
     ...sharedOptions(GATEWAY_API_KEY_ENV),
-    instructions: z.string().min(1).optional(),
+    ...speechOptions,
     model: z.string().min(1).default(DEFAULT_NARRATION_MODEL),
-    voice: z.string().min(1).default(DEFAULT_NARRATION_VOICE),
   })
 );
 
+const openaiNarrationSchema = adapterDescriptorSchema(
+  "openai",
+  z.strictObject({
+    ...sharedOptions(OPENAI_API_KEY_ENV),
+    ...speechOptions,
+    // Replaces the shared default: whether it's OPENAI_API_KEY depends on
+    // the `baseUrl` (see below).
+    apiKeyEnv: z.string().min(1).optional(),
+    // An unparsable URL is left to `z.url()`.
+    baseUrl: z
+      .url()
+      .refine((url) => !hasCredentials(url), {
+        message:
+          "Credentials don't go in the baseUrl: name the env var holding the key in apiKeyEnv.",
+      })
+      .optional(),
+    model: z.string().min(1),
+  })
+);
+
+/**
+ * `narration.provider`: the `gateway()` or `openai()` descriptor from
+ * `blume/ai`, read with speech defaults. `reasoning` (and `openai()`'s
+ * `name`, which speech models don't read) are assistant options and are
+ * rejected here; `voice` and `instructions` are narration options and are
+ * rejected by the assistant.
+ *
+ * `openai()` is read for what narration needs, not what the assistant does:
+ * it speaks through `@ai-sdk/openai` whatever the `baseUrl`, and a custom
+ * endpoint gets only the key `apiKeyEnv` names, never `OPENAI_API_KEY` by
+ * default, so it may take none at all. A key that is named is required.
+ */
+export const narrationProviderSchema = z
+  .discriminatedUnion("kind", [gatewayNarrationSchema, openaiNarrationSchema])
+  .transform((provider) => {
+    if (provider.kind !== "openai") {
+      return provider;
+    }
+    const { options } = provider;
+    const apiKeyEnv =
+      options.apiKeyEnv ?? (options.baseUrl ? undefined : OPENAI_API_KEY_ENV);
+    return {
+      ...provider,
+      options: apiKeyEnv ? { ...options, apiKeyEnv } : options,
+      requiredSecrets: apiKeyEnv ? [apiKeyEnv] : [],
+      runtimeDeps: [OPENAI_SPEECH_DEP],
+    };
+  });
+
 /** A validated narration provider, defaults filled in. */
 export type NarrationProvider = z.output<typeof narrationProviderSchema>;
+
+/** A validated `gateway()` narration provider. */
+export type GatewayNarrationProvider = Extract<
+  NarrationProvider,
+  { kind: "gateway" }
+>;
+
+/** A validated `openai()` narration provider. */
+export type OpenAINarrationProvider = Extract<
+  NarrationProvider,
+  { kind: "openai" }
+>;

package/src/openapi/checks.ts

@@ -0,0 +1,273 @@
+import type { OperationObject } from "@scalar/openapi-types/3.2";
+
+import type { ApiDocument } from "./model.ts";
+import { HTTP_METHODS } from "./model.ts";
+
+/**
+ * Targeted checks for spec mistakes that would otherwise render silently
+ * wrong. This is not a validator — a linter such as Spectral or oasdiff owns
+ * that — and a spec that fails one of these still renders. Each check names
+ * one mistake whose symptom on the page is quiet: a path placeholder sent
+ * as literal text, a Try it input whose value goes nowhere, an Authorization
+ * section with no scheme to describe. Each reports a warning with its own
+ * code, so a build says what's wrong instead of shipping it.
+ */
+
+/** One mistake a check found, before the source names the spec it's in. */
+export interface SpecIssue {
+  code: string;
+  message: string;
+  suggestion: string;
+}
+
+/** A `{name}` placeholder in a path template. */
+const PATH_TEMPLATE = /\{(?<name>[^{}]+)\}/gu;
+
+/** A reference to a parameter declared under `components.parameters`. */
+const PARAMETER_REF = /^#\/components\/parameters\/(?<name>[^/]+)$/u;
+
+/** How many operations a security-scheme warning names before counting the rest. */
+const NAMED_OPERATIONS = 3;
+
+/** One entry of a document's `paths` or `webhooks` map. */
+type PathItem = NonNullable<ApiDocument["paths"]>[string];
+
+/**
+ * How a warning names an operation: `GET /pets`, or a webhook by its name
+ * (`Webhook "newPet" (POST)`), since a webhook has no path.
+ */
+export const operationLabel = (
+  name: string,
+  method: string,
+  webhook: boolean
+): string =>
+  webhook
+    ? `Webhook "${name}" (${method.toUpperCase()})`
+    : `${method.toUpperCase()} ${name}`;
+
+/** One entry of a `parameters` list: a parameter, or a `$ref` to one. */
+type ParameterEntry = NonNullable<OperationObject["parameters"]>[number];
+
+// The runtime object checks stand guard because the document was parsed from
+// arbitrary YAML/JSON: a spec can put a scalar or null where the type
+// promises an object.
+const isObject = <Value>(value: Value): value is NonNullable<Value> =>
+  typeof value === "object" && value !== null;
+
+/** A parameter's `name`, which a hand-written spec may have left out or mistyped. */
+const isName = <Value>(value: Value): value is Value & string =>
+  typeof value === "string";
+
+/** A declared list, or none when a hand-written spec put something else there. */
+const listOf = <Item>(value: Item[] | undefined): NonNullable<Item>[] =>
+  Array.isArray(value) ? value.filter(isObject) : [];
+
+/** A resolved parameter: one that isn't a `$ref`. */
+type Parameter = Extract<ParameterEntry, { in: string }>;
+
+/**
+ * The parameters an operation declares, its path item's and its own, `$ref`s
+ * resolved through `components.parameters`. One that doesn't resolve is left
+ * out, as the page leaves it out.
+ */
+const parametersOf = (
+  document: ApiDocument,
+  item: PathItem,
+  operation: OperationObject
+): Parameter[] => {
+  const components = document.components?.parameters ?? {};
+  return [
+    ...listOf<ParameterEntry>(item.parameters),
+    ...listOf<ParameterEntry>(operation.parameters),
+  ].flatMap((entry) => {
+    const refName =
+      "$ref" in entry
+        ? PARAMETER_REF.exec(entry.$ref)?.groups?.name
+        : undefined;
+    const parameter = (refName ? components[refName] : undefined) ?? entry;
+    return "in" in parameter ? [parameter] : [];
+  });
+};
+
+/**
+ * A path whose template and declared path parameters disagree. A placeholder
+ * with no parameter gets no input in Try it and no row in the table, so
+ * requests send it as literal text; a parameter with no placeholder gets an
+ * input whose value never reaches the URL.
+ */
+const pathParameterIssues = (
+  signature: string,
+  path: string,
+  declared: Set<string>
+): SpecIssue[] => {
+  const used = new Set(
+    [...path.matchAll(PATH_TEMPLATE)].map((match) => match.groups?.name ?? "")
+  );
+  const issues: SpecIssue[] = [];
+  for (const name of used) {
+    if (!declared.has(name)) {
+      issues.push({
+        code: "BLUME_OPENAPI_PATH_PARAMETER_MISSING",
+        message: `${signature} has {${name}} in its path but declares no "${name}" path parameter, so Try it and the code samples send "{${name}}" as literal text.`,
+        suggestion: `Declare "${name}" in the operation's or the path's \`parameters\`, with \`in: path\` and \`required: true\`.`,
+      });
+    }
+  }
+  for (const name of declared) {
+    if (!used.has(name)) {
+      issues.push({
+        code: "BLUME_OPENAPI_PATH_PARAMETER_UNUSED",
+        message: `${signature} declares a "${name}" path parameter, but its path has no {${name}}, so the value Try it asks for never reaches the URL.`,
+        suggestion: `Add {${name}} to the path, or remove the parameter.`,
+      });
+    }
+  }
+  return issues;
+};
+
+/** The scheme names a `security` list requires. */
+const requiredSchemes = (
+  security: ApiDocument["security"] | OperationObject["security"]
+): string[] =>
+  listOf(security).flatMap((requirement) => Object.keys(requirement));
+
+/**
+ * Security schemes a requirement names that `components.securitySchemes`
+ * doesn't define: the Authorization section has nothing to describe, and
+ * Try it and the code samples send no credential for them. One warning per
+ * scheme, naming where it's required: the root `security`, or the first few
+ * operations that list it.
+ */
+const securitySchemeIssues = (
+  document: ApiDocument,
+  requirers: Map<string, string[]>
+): SpecIssue[] => {
+  const defined = document.components?.securitySchemes ?? {};
+  const root = new Set(requiredSchemes(document.security));
+  const issues: SpecIssue[] = [];
+  for (const scheme of new Set([...root, ...requirers.keys()])) {
+    if (Object.hasOwn(defined, scheme)) {
+      continue;
+    }
+    const operations = requirers.get(scheme) ?? [];
+    const more = operations.length - NAMED_OPERATIONS;
+    const where = root.has(scheme)
+      ? "The spec's root `security` requires"
+      : `${operations.slice(0, NAMED_OPERATIONS).join(", ")}${more > 0 ? ` and ${more} more` : ""} ${operations.length === 1 ? "requires" : "require"}`;
+    issues.push({
+      code: "BLUME_OPENAPI_UNKNOWN_SECURITY_SCHEME",
+      message: `${where} the "${scheme}" security scheme, which \`components.securitySchemes\` doesn't define, so the Authorization section can't describe it and requests send no credential for it.`,
+      suggestion: `Define "${scheme}" in \`components.securitySchemes\`, or fix the name in \`security\`.`,
+    });
+  }
+  return issues;
+};
+
+/**
+ * An operation's `in: querystring` parameter (OpenAPI 3.2: the whole query
+ * string as one value), which the parameter table, Try it, and the code
+ * samples don't handle yet, so it would drop out of all three without a sign.
+ */
+const querystringIssue = (signature: string): SpecIssue => ({
+  code: "BLUME_OPENAPI_UNSUPPORTED",
+  message: `${signature} declares an \`in: querystring\` parameter, which OpenAPI 3.2 added and Blume doesn't render yet, so the page has no row or Try it input for it and the code samples leave the query string out.`,
+  suggestion:
+    "Describe the query string in the operation's `description` until Blume renders `querystring` parameters.",
+});
+
+/**
+ * A path item's `additionalOperations` (OpenAPI 3.2: methods beyond the ones
+ * a path item names directly, like `COPY`), which the extractor doesn't
+ * collect yet, so those operations would be missing without a sign.
+ */
+const additionalOperationsIssue = (
+  label: string,
+  methods: string[]
+): SpecIssue => ({
+  code: "BLUME_OPENAPI_UNSUPPORTED",
+  message: `${label} declares \`additionalOperations\` (${methods.join(", ")}), which OpenAPI 3.2 added and Blume doesn't render yet, so those operations are missing from the reference.`,
+  suggestion:
+    "Document those operations on a page of their own until Blume renders `additionalOperations`.",
+});
+
+/**
+ * A root `x-webhooks` and no `webhooks`. It's the extension OpenAPI 3.0 tools
+ * read for webhooks, and upgrading a 3.0 spec renames it to `webhooks`; a spec
+ * already at 3.1 or later isn't upgraded, so it stays an extension and its
+ * webhooks would be missing without a sign.
+ */
+const xWebhooksIssues = (document: ApiDocument): SpecIssue[] =>
+  "x-webhooks" in document && document.webhooks === undefined
+    ? [
+        {
+          code: "BLUME_OPENAPI_X_WEBHOOKS",
+          message:
+            "The spec declares its webhooks under `x-webhooks`, the extension OpenAPI 3.0 tools read. Blume reads it only from a 3.0 spec, which it upgrades, so these webhooks are missing from the reference.",
+          suggestion:
+            "Rename `x-webhooks` to `webhooks`, the field OpenAPI 3.1 added for them.",
+        },
+      ]
+    : [];
+
+/**
+ * Check a parsed document for the mistakes above, and for the OpenAPI 3.2
+ * features Blume doesn't render yet. `$ref` path items are skipped: the
+ * extractor already reports them as missing from the reference.
+ */
+export const specIssues = (document: ApiDocument): SpecIssue[] => {
+  const issues: SpecIssue[] = [...xWebhooksIssues(document)];
+  // Scheme name -> the operations whose own `security` lists it.
+  const requirers = new Map<string, string[]>();
+  const visit = (name: string, item: PathItem, webhook: boolean): void => {
+    if (!isObject(item) || "$ref" in item) {
+      return;
+    }
+    const additional = isObject(item.additionalOperations)
+      ? Object.keys(item.additionalOperations)
+      : [];
+    if (additional.length > 0) {
+      issues.push(
+        additionalOperationsIssue(
+          webhook ? `Webhook "${name}"` : `Path "${name}"`,
+          additional
+        )
+      );
+    }
+    for (const method of HTTP_METHODS) {
+      const operation = item[method];
+      if (!isObject(operation)) {
+        continue;
+      }
+      const signature = operationLabel(name, method, webhook);
+      for (const scheme of requiredSchemes(operation.security)) {
+        requirers.set(scheme, [...(requirers.get(scheme) ?? []), signature]);
+      }
+      const parameters = parametersOf(document, item, operation);
+      // A webhook is keyed by its name, not a path: it has no template.
+      if (!webhook) {
+        issues.push(
+          ...pathParameterIssues(
+            signature,
+            name,
+            new Set(
+              parameters
+                .filter((parameter) => parameter.in === "path")
+                .map((parameter) => parameter.name)
+                .filter(isName)
+            )
+          )
+        );
+      }
+      if (parameters.some((parameter) => parameter.in === "querystring")) {
+        issues.push(querystringIssue(signature));
+      }
+    }
+  };
+  for (const [path, item] of Object.entries(document.paths ?? {})) {
+    visit(path, item, false);
+  }
+  for (const [name, item] of Object.entries(document.webhooks ?? {})) {
+    visit(name, item, true);
+  }
+  return [...issues, ...securitySchemeIssues(document, requirers)];
+};

package/src/openapi/graphql-build.ts

@@ -26,6 +26,7 @@ import {
   parse,
   print,
   specifiedDirectives,
+  valueFromASTUntyped,
   visit,
 } from "graphql";
 
@@ -34,6 +35,7 @@ import type {
   GraphqlEnumValue,
   GraphqlField as ModelField,
   GraphqlInputValue,
+  GraphqlJsonValue,
   GraphqlTypeDef,
   GraphqlTypeRef,
 } from "./graphql.ts";
@@ -68,6 +70,21 @@ const defaultLiteral = (
   return literal ? print(literal) : undefined;
 };
 
+/**
+ * The same default as the JSON a client sends in `variables`, which the
+ * example variables start from.
+ */
+const defaultJson = (
+  input: GraphQLArgument | GraphQLInputField
+): GraphqlJsonValue | undefined => {
+  const literal = input.default?.literal;
+  // SAFETY: a const literal has no variables, so it lowers to JSON values
+  // only: numbers, strings, booleans, null, enum names, lists and objects.
+  return literal
+    ? (valueFromASTUntyped(literal) as GraphqlJsonValue)
+    : undefined;
+};
+
 const inputValue = (
   input: GraphQLArgument | GraphQLInputField
 ): GraphqlInputValue => {
@@ -80,6 +97,10 @@ const inputValue = (
   if (printed !== undefined) {
     value.default = printed;
   }
+  const json = defaultJson(input);
+  if (json !== undefined) {
+    value.defaultValue = json;
+  }
   // `deprecationReason` is null on non-deprecated members in some builds;
   // absent means "not deprecated" downstream, so both collapse to absent.
   if (

package/src/openapi/graphql.ts

@@ -58,6 +58,15 @@ export interface GraphqlTypeRef {
   name: string;
 }
 
+/** A GraphQL input value as JSON carries it in `variables` (enums by name). */
+export type GraphqlJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | GraphqlJsonValue[]
+  | { [key: string]: GraphqlJsonValue };
+
 /** An argument or input-object field. */
 export interface GraphqlInputValue {
   name: string;
@@ -65,6 +74,8 @@ export interface GraphqlInputValue {
   type: GraphqlTypeRef;
   /** Default value printed as a GraphQL literal (`10`, `"asc"`, `[1, 2]`). */
   default?: string;
+  /** The same default as JSON, for the example variables. */
+  defaultValue?: GraphqlJsonValue;
   deprecationReason?: string;
 }
 

package/src/openapi/model.ts

@@ -1,5 +1,6 @@
-import type { Document, OperationObject } from "@scalar/openapi-types/3.1";
+import type { Document, OperationObject } from "@scalar/openapi-types/3.2";
 
+import type { GraphqlAuthOptions } from "../reference/options.ts";
 import type {
   AsyncApiAction,
   AsyncApiDocument,
@@ -26,10 +27,18 @@ export { slugify } from "./references.ts";
  * per-operation route so it becomes a first-class Blume page.
  */
 
-/** A normalized OpenAPI 3.1 document, internal `$ref`s intact. */
+/**
+ * A normalized OpenAPI document, internal `$ref`s intact. Typed as 3.2, which
+ * is backward compatible with 3.1, so one type covers both the upgraded 3.1
+ * documents and the 3.2 ones read as written.
+ */
 export type ApiDocument = Document;
 
-/** The HTTP methods an OpenAPI path item may declare, in spec order. */
+/**
+ * The HTTP methods an OpenAPI path item may declare, in spec order. `query`
+ * is OpenAPI 3.2's (the QUERY method: a safe request that carries a body); a
+ * 3.1 path item can't declare it, so listing it changes nothing there.
+ */
 export const HTTP_METHODS = [
   "get",
   "put",
@@ -39,6 +48,7 @@ export const HTTP_METHODS = [
   "head",
   "patch",
   "trace",
+  "query",
 ] as const;
 
 export type HttpMethod = (typeof HTTP_METHODS)[number];
@@ -140,6 +150,8 @@ export interface ApiSpecData {
    * (GraphQL only; OpenAPI documents carry their servers in the document).
    */
   endpoint?: string;
+  /** How the GraphQL endpoint authenticates (GraphQL only). */
+  auth?: GraphqlAuthOptions;
   /** Operations keyed by {@link ApiOperationRef.key}. */
   operations: Record<string, ApiOperationRef>;
   tags: ApiTagRef[];

package/src/openapi/parse.ts

@@ -4,7 +4,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 import type * as ConverterModule from "@asyncapi/converter";
 import { normalize, upgrade } from "@scalar/openapi-parser";
 import pRetry, { AbortError } from "p-retry";
-import { isAbsolute, join } from "pathe";
+import { dirname, isAbsolute, join, resolve } from "pathe";
 import type * as UndiciModule from "undici";
 
 import {
@@ -15,8 +15,11 @@ import { nodeRequire } from "../core/node-require.ts";
 import { hashText } from "../core/sources/cache.ts";
 import type { AsyncApiDocument } from "./asyncapi.ts";
 import { normalizeAsyncApiDocument } from "./asyncapi.ts";
+import { operationLabel } from "./checks.ts";
+import type { SpecIssue } from "./checks.ts";
 import { buildGraphqlDocument } from "./graphql-build.ts";
 import type { GraphqlDocument } from "./graphql.ts";
+import { HTTP_METHODS } from "./model.ts";
 import type { ApiDocument } from "./model.ts";
 import { applyOverlay, isJsonObject, overlayDocument } from "./overlay.ts";
 import { SpecDependencyError } from "./spec-dependency-error.ts";
@@ -25,6 +28,8 @@ import { SpecDependencyError } from "./spec-dependency-error.ts";
  * Spec loading and normalization. Blume reuses Scalar's parser
  * (`@scalar/openapi-parser`) to read a spec (YAML or JSON), then upgrade Swagger
  * 2.0 / OpenAPI 3.0 documents to 3.1 so the renderer only handles one shape.
+ * OpenAPI 3.2 is backward compatible with 3.1, so a 3.2 document is read as
+ * written.
  * Internal `$ref`s are deliberately left in place (see `model.ts`).
  *
  * Remote (`http(s)`) specs are fetched defensively — bounded per attempt, retried
@@ -58,6 +63,8 @@ const PROXY_ENV_VARS = [
 
 export interface ParsedSpec {
   document: ApiDocument;
+  /** `x-codeSamples` entries whose `$ref` couldn't be inlined. */
+  issues: SpecIssue[];
   warnings: string[];
 }
 
@@ -360,6 +367,123 @@ export const readOverlaidSpec = async (
   return { text: JSON.stringify(document), warnings };
 };
 
+/** A `$ref` in place of an `x-codeSamples` entry's `source`. */
+interface SampleRef {
+  $ref: string;
+}
+
+/** An `x-codeSamples` entry whose `source` is a `$ref` rather than the code. */
+const isRefSample = (value: unknown): value is { source: SampleRef } =>
+  isJsonObject(value) &&
+  isJsonObject(value.source) &&
+  typeof value.source.$ref === "string";
+
+/**
+ * Where a code sample's `$ref` points, in the form `readSpecText` reads: a
+ * URL, or a path resolved against the spec's own location. `undefined` for
+ * a JSON pointer (`#/…`, or a file with a fragment), which names a spot
+ * inside a document rather than a file of code.
+ */
+const sampleTarget = (
+  ref: string,
+  spec: string,
+  root: string
+): string | undefined => {
+  if (ref.includes("#")) {
+    return undefined;
+  }
+  if (URL_SPEC.test(ref)) {
+    return ref;
+  }
+  if (URL_SPEC.test(spec)) {
+    return new URL(ref, spec).href;
+  }
+  return resolve(dirname(isAbsolute(spec) ? spec : join(root, spec)), ref);
+};
+
+/**
+ * Inline each `x-codeSamples` entry whose `source` is a `$ref` to a file of
+ * its own, as Redocly's docs describe (`source: { $ref: ../code_samples/… }`):
+ * `redocly bundle` inlines those, and a spec read as written doesn't. Each
+ * file is read relative to the spec,
+ * the way the spec itself was (local, or fetched and cached), so the sample
+ * renders like a written-out one. An entry that can't be read is left out of
+ * the page, with a warning, rather than dropped without a sign.
+ */
+const inlineSampleRefs = async (
+  document: ApiDocument,
+  spec: string,
+  root: string,
+  options: SpecFetchOptions
+): Promise<SpecIssue[]> => {
+  const reads: Promise<SpecIssue | undefined>[] = [];
+  const inline = async (
+    entry: { source: SampleRef | string },
+    ref: string,
+    label: string
+  ): Promise<SpecIssue | undefined> => {
+    const target = sampleTarget(ref, spec, root);
+    if (target === undefined) {
+      return {
+        code: "BLUME_OPENAPI_CODE_SAMPLE_REF",
+        message: `${label} has an \`x-codeSamples\` entry whose \`source\` is a $ref to "${ref}", a spot inside a document, which Blume doesn't resolve, so the sample is left out.`,
+        suggestion:
+          "Point the `$ref` at a file that holds only the sample's code, or write the code out in `source`.",
+      };
+    }
+    try {
+      const { text } = await readSpecText(target, root, options);
+      entry.source = text;
+      return undefined;
+    } catch (error) {
+      // SAFETY: a failed read throws a Node error, and a failed fetch an
+      // Error (`attemptFetch` wraps anything else); only the message is shown.
+      const { message } = error as Error;
+      return {
+        code: "BLUME_OPENAPI_CODE_SAMPLE_REF",
+        message: `${label} has an \`x-codeSamples\` entry whose \`source\` is a $ref to "${ref}", which couldn't be read (${message}), so the sample is left out.`,
+        suggestion:
+          "Check the path, which is relative to the spec, or write the code out in `source`.",
+      };
+    }
+  };
+  const visit = (
+    name: string,
+    item: NonNullable<ApiDocument["paths"]>[string] | undefined,
+    webhook: boolean
+  ): void => {
+    if (!isJsonObject(item) || "$ref" in item) {
+      return;
+    }
+    for (const method of HTTP_METHODS) {
+      const operation = item[method];
+      // The spelling `customCodeSamples` renders: the current one wins.
+      const samples = isJsonObject(operation)
+        ? (operation["x-codeSamples"] ?? operation["x-code-samples"])
+        : undefined;
+      for (const entry of Array.isArray(samples) ? samples : []) {
+        if (isRefSample(entry)) {
+          reads.push(
+            inline(
+              entry,
+              entry.source.$ref,
+              operationLabel(name, method, webhook)
+            )
+          );
+        }
+      }
+    }
+  };
+  for (const [path, item] of Object.entries(document.paths ?? {})) {
+    visit(path, item, false);
+  }
+  for (const [name, item] of Object.entries(document.webhooks ?? {})) {
+    visit(name, item, true);
+  }
+  const issues = await Promise.all(reads);
+  return issues.filter((issue) => issue !== undefined);
+};
+
 export const parseSpec = async (
   spec: string,
   root: string,
@@ -377,7 +501,8 @@ export const parseSpec = async (
       `${spec} is not a valid OpenAPI document (expected a YAML or JSON object).`
     );
   }
-  return { document: specification, warnings };
+  const issues = await inlineSampleRefs(specification, spec, root, options);
+  return { document: specification, issues, warnings };
 };
 
 export interface ParsedAsyncApiSpec {