blume 2.0.3 → 2.1.0

package/src/openapi/model.ts

@@ -46,6 +46,9 @@ export type HttpMethod = (typeof HTTP_METHODS)[number];
 /** Group used for operations that declare no tag. */
 const UNTAGGED = "Operations";
 
+/** Group used for webhooks that declare no tag. */
+const UNTAGGED_WEBHOOKS = "Webhooks";
+
 /** A lower-case letter or digit followed by a capital: `addPet`, `v2List`. */
 const CASE_BOUNDARY = /(?<before>[\p{Ll}\p{N}])(?<capital>\p{Lu})/gu;
 /** The last capital of an acronym before a capitalized word: `HTTPResponse`. */
@@ -101,6 +104,12 @@ export interface ApiOperationRef {
   deprecated: boolean;
   /** The channel the operation acts on (AsyncAPI only). */
   channelId?: string;
+  /**
+   * An OpenAPI 3.1 webhook: a request the API sends to the reader's endpoint
+   * rather than one it serves. `path` then holds the webhook's name, the key
+   * it has under the document's `webhooks`.
+   */
+  webhook?: true;
 }
 
 /**
@@ -134,8 +143,8 @@ export interface ApiSpecData {
   /** Operations keyed by {@link ApiOperationRef.key}. */
   operations: Record<string, ApiOperationRef>;
   tags: ApiTagRef[];
-  /** Code-sample languages to render per operation. */
-  codeSamples: string[];
+  /** Code-sample languages to render per operation; `false` for none. */
+  codeSamples: string[] | false;
   /** Whether nested schema rows start expanded. */
   expandSchemas: boolean;
   /**
@@ -301,6 +310,11 @@ export const tagSlugger = (): ((name: string) => string) => {
   };
 };
 
+/** One entry of a document's `paths` or `webhooks` map. */
+type PathItemEntry =
+  | NonNullable<ApiDocument["paths"]>[string]
+  | NonNullable<ApiDocument["webhooks"]>[string];
+
 /** An operation before the collector assigns its unique key and route. */
 type CollectedOperation = Omit<ApiOperationRef, "route" | "tagSlug">;
 
@@ -386,10 +400,10 @@ export const operationCollector = (
 
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
- * tags. Operations inherit the first tag they declare; keys are de-duplicated so
- * a repeated `operationId` still yields distinct routes. `warnings` reports
- * anything skipped (a `$ref` path item, webhooks), so missing operations
- * aren't silent.
+ * tags, webhooks included. Operations inherit the first tag they declare; keys
+ * are de-duplicated so a repeated `operationId` still yields distinct routes.
+ * `warnings` reports anything skipped (a `$ref` path item), so missing
+ * operations aren't silent.
  */
 export const extractOperations = (
   document: ApiDocument,
@@ -404,16 +418,24 @@ export const extractOperations = (
   );
   const collector = operationCollector(baseRoute, tagMeta);
 
-  for (const [path, item] of Object.entries(document.paths ?? {})) {
+  // A path item's operations, filed under `name`: a path for `paths`, the
+  // webhook's key for `webhooks`.
+  const addPathItem = (
+    name: string,
+    item: PathItemEntry,
+    webhook: boolean
+  ): void => {
     // A parsed spec can carry a null path item despite the type; skip it.
     if (!item) {
-      continue;
+      return;
     }
     if ("$ref" in item) {
       warnings.push(
-        `Path "${path}" is a $ref to a shared path item; referenced path items are not resolved, so its operations are missing from the reference. Inline the path item under "paths" to render it.`
+        webhook
+          ? `Webhook "${name}" is a $ref to a shared path item; referenced path items are not resolved, so it is missing from the reference. Inline the path item under "webhooks" to render it.`
+          : `Path "${name}" is a $ref to a shared path item; referenced path items are not resolved, so its operations are missing from the reference. Inline the path item under "paths" to render it.`
       );
-      continue;
+      return;
     }
     for (const method of HTTP_METHODS) {
       const operation = item[method];
@@ -421,26 +443,35 @@ export const extractOperations = (
         continue;
       }
       const operationId = specText(operation.operationId);
-      collector.add({
+      const entry: CollectedOperation = {
         deprecated: operation.deprecated ?? false,
         description: specText(operation.description) ?? "",
-        key: operationKey(method, path, operationId),
+        // A webhook without an operationId is keyed by its name, which is
+        // already an identifier (`newPet` -> `new-pet`).
+        key: operationKey(
+          method,
+          name,
+          operationId ?? (webhook ? name : undefined)
+        ),
         method,
         operationId,
-        path,
+        path: name,
         summary: specText(operation.summary) ?? "",
-        tag: specText(operation.tags?.[0]) ?? UNTAGGED,
-      });
+        tag:
+          specText(operation.tags?.[0]) ??
+          (webhook ? UNTAGGED_WEBHOOKS : UNTAGGED),
+      };
+      collector.add(webhook ? { ...entry, webhook: true } : entry);
     }
-  }
+  };
 
-  // OpenAPI 3.1 webhooks (requests the API sends, not ones it serves) have no
-  // page renderer; say so rather than dropping them silently.
-  const webhooks = Object.keys(document.webhooks ?? {});
-  if (webhooks.length > 0) {
-    warnings.push(
-      `The spec declares ${webhooks.length === 1 ? "a webhook" : `${webhooks.length} webhooks`} under "webhooks" (${webhooks.join(", ")}); webhooks aren't rendered, so they are missing from the reference.`
-    );
+  for (const [path, item] of Object.entries(document.paths ?? {})) {
+    addPathItem(path, item, false);
+  }
+  // OpenAPI 3.1 webhooks: requests the API sends rather than serves. They
+  // follow the paths, so an untagged webhook group sits after the endpoints.
+  for (const [name, item] of Object.entries(document.webhooks ?? {})) {
+    addPathItem(name, item, true);
   }
 
   return { ...collector.finish(), warnings };
@@ -458,7 +489,9 @@ export const operationObject = (
   // (AsyncAPI documents go to `asyncApiOperationObject`), so the spec's
   // document is the OpenAPI shape.
   const document = spec.document as ApiDocument;
-  const item = document.paths?.[ref.path];
+  const item = ref.webhook
+    ? document.webhooks?.[ref.path]
+    : document.paths?.[ref.path];
   const operation = method === undefined ? undefined : item?.[method];
   return isOperation(operation) ? operation : undefined;
 };

package/src/openapi/overlay.ts

@@ -0,0 +1,256 @@
+import { exec, query } from "jsonpath-rfc9535";
+import { z } from "zod";
+
+import type { JsonValue } from "../core/adapter.ts";
+
+/**
+ * OpenAPI Overlays: the OpenAPI Initiative's format for changing an API
+ * description without editing it — an ordered list of actions, each an RFC
+ * 9535 JSONPath `target` with an `update` to merge in, a `copy` of another
+ * node to merge in, or `remove`. A spec generated by another tool or owned by
+ * another team can then carry docs-only changes (better descriptions, hidden
+ * internal operations, a public server URL) in a file of its own.
+ *
+ * Implements Overlay Specification 1.0 and 1.1 over `jsonpath-rfc9535`, which
+ * passes the JSONPath compliance suite in full, as the spec requires. The
+ * documents here are already parsed; `parse.ts` reads the files.
+ */
+
+/** An overlay document or action that doesn't follow the spec. */
+export class OverlayError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OverlayError";
+  }
+}
+
+/** An object node, the only kind that holds named properties. */
+interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+/** A node that holds other nodes: where a match's parent can be. */
+type JsonContainer = JsonObject | JsonValue[];
+
+const isObject = (value: JsonValue | undefined): value is JsonObject =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * A parsed YAML or JSON mapping, as the document an overlay acts on: the
+ * parser's own types say nothing of JSON, but what it parses is JSON.
+ */
+export const isJsonObject = <Value>(
+  value: Value
+): value is Value & JsonObject =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isContainer = (value: JsonValue | undefined): value is JsonContainer =>
+  typeof value === "object" && value !== null;
+
+const isIndex = (key: string | number | undefined): key is number =>
+  typeof key === "number";
+
+/** An object, an array, or anything else: what update merging keys on. */
+type MergeKind = "array" | "object" | "primitive";
+
+const mergeKindOf = (value: JsonValue): MergeKind => {
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  return isObject(value) ? "object" : "primitive";
+};
+
+/** A merge kind in a sentence. */
+const MERGE_KIND_PHRASE: Record<MergeKind, string> = {
+  array: "an array",
+  object: "an object",
+  primitive: "a primitive value",
+};
+
+const actionSchema = z.looseObject({
+  /** A JSONPath expression selecting one node to merge into the targets (1.1). */
+  copy: z.string().optional(),
+  description: z.string().optional(),
+  /** Remove every target from the map or array it's in. */
+  remove: z.boolean().default(false),
+  /** An RFC 9535 JSONPath expression selecting the nodes to act on. */
+  target: z.string().min(1),
+  /** A value merged into every target. */
+  update: z.json().optional(),
+});
+
+/** A validated overlay action. */
+type OverlayAction = z.output<typeof actionSchema>;
+
+const overlaySchema = z.looseObject({
+  actions: z.array(actionSchema).min(1),
+  extends: z.string().optional(),
+  info: z.looseObject({ title: z.string(), version: z.string() }),
+  overlay: z.string().regex(/^1\.[01]\.\d+$/u, {
+    message: "must be an Overlay Specification version, 1.0.x or 1.1.x",
+  }),
+});
+
+/** A validated overlay document. */
+export type OverlayDocument = z.output<typeof overlaySchema>;
+
+/** Validate a parsed overlay document, naming the file in any error. */
+export const overlayDocument = <Value>(
+  value: Value,
+  name: string
+): OverlayDocument => {
+  const parsed = overlaySchema.safeParse(value);
+  if (parsed.success) {
+    return parsed.data;
+  }
+  const [issue] = parsed.error.issues;
+  const at = issue?.path.length ? `\`${issue.path.join(".")}\` ` : "";
+  throw new OverlayError(
+    `${name} is not an overlay document: ${at}${issue?.message ?? "invalid"}.`
+  );
+};
+
+/** A matched node, where it sits, and how to reach it. */
+interface Match {
+  key?: string | number;
+  parent?: JsonContainer;
+  value: JsonValue;
+}
+
+/** The nodes `expression` selects, each with its parent (none for the root). */
+const select = (document: JsonValue, expression: string): Match[] => {
+  const matches: Match[] = [];
+  exec(document, expression, (value, path) => {
+    let parent: JsonValue = document;
+    for (const key of path.slice(0, -1)) {
+      // SAFETY: the path is one the query walked, so every step is a key of
+      // the container before it.
+      parent = (parent as Record<string | number, JsonValue>)[key] ?? null;
+    }
+    const key = path.at(-1);
+    matches.push(
+      key === undefined || !isContainer(parent)
+        ? { value }
+        : { key, parent, value }
+    );
+  });
+  return matches;
+};
+
+/**
+ * Merge `patch` into `target` as the spec says: objects recursively, arrays
+ * by concatenation, a primitive replaced by a primitive. Returns the merged
+ * value; any other pairing throws.
+ */
+const merge = (target: JsonValue, patch: JsonValue, at: string): JsonValue => {
+  if (isObject(target) && isObject(patch)) {
+    for (const [key, value] of Object.entries(patch)) {
+      // Only recurse into the target's own keys, so a `__proto__` or
+      // `constructor` key can't reach a prototype.
+      target[key] = Object.hasOwn(target, key)
+        ? merge(target[key] ?? null, value, `${at}.${key}`)
+        : structuredClone(value);
+    }
+    return target;
+  }
+  if (Array.isArray(target) && Array.isArray(patch)) {
+    target.push(...structuredClone(patch));
+    return target;
+  }
+  if (
+    mergeKindOf(target) === "primitive" &&
+    mergeKindOf(patch) === "primitive"
+  ) {
+    return patch;
+  }
+  throw new OverlayError(
+    `can't merge ${MERGE_KIND_PHRASE[mergeKindOf(patch)]} into ${MERGE_KIND_PHRASE[mergeKindOf(target)]} at ${at}`
+  );
+};
+
+/** Remove each match from its container, later siblings first. */
+const removeAll = (matches: Match[]): void => {
+  for (const { key, parent } of matches.toReversed()) {
+    if (Array.isArray(parent) && isIndex(key)) {
+      parent.splice(key, 1);
+    } else if (isObject(parent) && key !== undefined && !isIndex(key)) {
+      // oxlint-disable-next-line typescript/no-dynamic-delete -- an overlay target's key is only known at run time
+      delete parent[key];
+    } else {
+      throw new OverlayError("can't remove the document itself");
+    }
+  }
+};
+
+/**
+ * Merge `patch` into every match, which must all be objects, all arrays, or
+ * all primitives. A primitive match is replaced in its parent.
+ */
+const mergeAll = (matches: Match[], patch: JsonValue, target: string) => {
+  const kinds = new Set(matches.map((match) => mergeKindOf(match.value)));
+  if (kinds.size > 1) {
+    throw new OverlayError(
+      `its target selects a mix of ${[...kinds].toSorted().join(", ")} values, and an update needs all one kind`
+    );
+  }
+  for (const { key, parent, value } of matches) {
+    const merged = merge(value, patch, target);
+    if (merged !== value && parent !== undefined && key !== undefined) {
+      // SAFETY: `key` came from walking `parent`, so it indexes it.
+      (parent as Record<string | number, JsonValue>)[key] = merged;
+    }
+  }
+};
+
+/** The single node a `copy` expression selects, cloned. */
+const copied = (document: JsonValue, expression: string): JsonValue => {
+  const values = query(document, expression);
+  const [value] = values;
+  if (values.length !== 1 || value === undefined) {
+    throw new OverlayError(
+      `its copy expression "${expression}" selects ${values.length} nodes, and copy needs exactly one`
+    );
+  }
+  return structuredClone(value);
+};
+
+const applyAction = (document: JsonValue, action: OverlayAction): void => {
+  const matches = select(document, action.target);
+  if (matches.length === 0) {
+    return;
+  }
+  if (action.remove) {
+    removeAll(matches);
+    return;
+  }
+  const patch =
+    action.update ??
+    (action.copy === undefined ? undefined : copied(document, action.copy));
+  if (patch !== undefined) {
+    mergeAll(matches, patch, action.target);
+  }
+};
+
+/**
+ * Apply an overlay to a parsed document, in place and in action order: each
+ * action sees the result of the one before. A target that matches nothing
+ * changes nothing. Throws an {@link OverlayError} naming the overlay file and
+ * the action that failed.
+ */
+export const applyOverlay = (
+  document: JsonValue,
+  overlay: OverlayDocument,
+  name: string
+): void => {
+  for (const [index, action] of overlay.actions.entries()) {
+    try {
+      applyAction(document, action);
+    } catch (error) {
+      // SAFETY: the JSONPath parser and this module throw Error instances.
+      const { message } = error as Error;
+      throw new OverlayError(
+        `${name} action ${index + 1} (${action.target}): ${message}`
+      );
+    }
+  }
+};

package/src/openapi/parse.ts

@@ -18,6 +18,7 @@ import { normalizeAsyncApiDocument } from "./asyncapi.ts";
 import { buildGraphqlDocument } from "./graphql-build.ts";
 import type { GraphqlDocument } from "./graphql.ts";
 import type { ApiDocument } from "./model.ts";
+import { applyOverlay, isJsonObject, overlayDocument } from "./overlay.ts";
 import { SpecDependencyError } from "./spec-dependency-error.ts";
 
 /**
@@ -75,6 +76,11 @@ export class InvalidSpecError extends Error {
 
 /** Where and whether to cache a remote spec's text between runs. */
 export interface SpecFetchOptions {
+  /**
+   * Overlay documents (local paths or `http(s)` URLs) applied in order to
+   * the parsed spec, before it's upgraded. See `overlay.ts`.
+   */
+  overlays?: readonly string[];
   /** Dir for a last-good on-disk copy of a remote spec (offline fallback). */
   cacheDir?: string;
   /**
@@ -310,13 +316,60 @@ const readSpecText = async (
 const isApiDocument = <Value>(value: Value): value is Value & ApiDocument =>
   typeof value === "object" && value !== null;
 
+/**
+ * Read a spec and apply its overlays, in order, to the parsed document as
+ * written (before any upgrade: an overlay targets its spec's own version).
+ * The overlays are read like the spec, local or remote, cached alike.
+ */
+const readOverlaid = async (
+  spec: string,
+  root: string,
+  options: SpecFetchOptions
+): Promise<{ document: ReturnType<typeof normalize>; warnings: string[] }> => {
+  const [read, ...overlays] = await Promise.all(
+    [spec, ...(options.overlays ?? [])].map((path) =>
+      readSpecText(path, root, options)
+    )
+  );
+  const document = normalize(read?.text ?? "");
+  for (const [index, overlay] of overlays.entries()) {
+    const name = options.overlays?.[index] ?? "";
+    const parsed = overlayDocument(normalize(overlay.text), name);
+    // A spec that isn't a mapping has nothing to overlay; the caller
+    // rejects it as it would without overlays.
+    if (isJsonObject(document)) {
+      applyOverlay(document, parsed, name);
+    }
+  }
+  return {
+    document,
+    warnings: [read, ...overlays].flatMap((entry) => entry?.warnings ?? []),
+  };
+};
+
+/**
+ * A spec with its overlays applied, as JSON text: what the Scalar embed
+ * inlines, since it can't apply overlays itself.
+ */
+export const readOverlaidSpec = async (
+  spec: string,
+  root: string,
+  options: SpecFetchOptions
+): Promise<{ text: string; warnings: string[] }> => {
+  const { document, warnings } = await readOverlaid(spec, root, options);
+  return { text: JSON.stringify(document), warnings };
+};
+
 export const parseSpec = async (
   spec: string,
   root: string,
   options: SpecFetchOptions = {}
 ): Promise<ParsedSpec> => {
-  const { text, warnings } = await readSpecText(spec, root, options);
-  const normalized = normalize(text);
+  const { document: normalized, warnings } = await readOverlaid(
+    spec,
+    root,
+    options
+  );
   const { specification } = upgrade(normalized);
   // Reject a non-mapping here so the renderer never sees a non-document.
   if (!isApiDocument(specification)) {

package/src/openapi/references.ts

@@ -28,8 +28,8 @@ export type BlumeReferenceKind = Exclude<ReferenceKind, "scalar">;
 
 /** Per-adapter display options for the Blume renderer. */
 export interface ReferenceDisplay {
-  /** Code-sample languages shown per operation. */
-  codeSamples: string[];
+  /** Code-sample languages shown per operation; `false` for none. */
+  codeSamples: string[] | false;
   /** Whether nested schema rows start expanded. */
   expandSchemas: boolean;
   /**
@@ -67,6 +67,11 @@ export interface ReferenceSource {
   seoDescriptionSuffix: boolean;
   /** Local path or `http(s)` URL, verbatim from config. */
   spec: string;
+  /**
+   * OpenAPI Overlay documents applied to `spec` in order (`openapi()` and
+   * `scalar()` only).
+   */
+  overlays?: string[];
   /**
    * URL of the live GraphQL endpoint the playground and code samples target
    * (GraphQL only — a schema, unlike an OpenAPI document, names no server).
@@ -184,6 +189,7 @@ interface SourceRow {
   route?: string;
   seoDescriptionSuffix: boolean;
   spec: string;
+  overlays?: string[];
 }
 
 /**
@@ -255,6 +261,9 @@ const referencesFor = (
     if (source.endpoint !== undefined) {
       reference.endpoint = source.endpoint;
     }
+    if (source.overlays !== undefined) {
+      reference.overlays = source.overlays;
+    }
     return reference;
   });
 };
@@ -363,11 +372,18 @@ export const builtinProxyReferences = (
       ref.display.playground.proxy === true
   );
 
+/**
+ * Whether hand-written endpoint pages (`api` frontmatter) send their Try it
+ * requests through the built-in proxy: `api.playground.proxy: true`.
+ */
+export const apiPagesUseBuiltinProxy = (config: ResolvedConfig): boolean =>
+  config.api.playground.enabled && config.api.playground.proxy === true;
+
 /**
  * Whether the built-in playground CORS proxy endpoint (`/_api-proxy`) must be
  * generated: some Blume-rendered reference's playground opted into it with
- * `proxy: true`. Shared by the server feature gate and the generator so the
- * two can never disagree.
+ * `proxy: true`, or the hand-written endpoint pages' did. Shared by the server
+ * feature gate and the generator so the two can never disagree.
  */
 export const needsPlaygroundProxy = (config: ResolvedConfig): boolean =>
-  builtinProxyReferences(config).length > 0;
+  builtinProxyReferences(config).length > 0 || apiPagesUseBuiltinProxy(config);

package/src/openapi/render-mdx.ts

@@ -270,7 +270,8 @@ const operationDescription = (
     // method (see `extractGraphqlOperations`).
     subject = `${operation.path} ${GRAPHQL_MEMBER_PHRASES[operation.method as GraphqlMember]}`;
   } else {
-    subject = `${operation.method.toUpperCase()} ${operation.path} endpoint`;
+    // A webhook is a request the API sends, named rather than pathed.
+    subject = `${operation.method.toUpperCase()} ${operation.path} ${operation.webhook ? "webhook" : "endpoint"}`;
   }
   const suffix = `Reference for the ${subject} in the ${apiPhrase(spec)}.`;
   // Room for the joining space and the period `asSentence` may add, so a
@@ -348,6 +349,9 @@ export const operationMdx = (
     sidebar.badge = method;
   }
   const tags = graphql ? [operation.tag] : [operation.tag, method];
+  if (operation.webhook) {
+    tags.push("Webhook");
+  }
   return {
     body: withDescription(
       description,

package/src/openapi/scalar.ts

@@ -6,6 +6,7 @@ import { scalarReferenceTemplate } from "../astro/templates.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { trimChar } from "../core/trim.ts";
 import { resolveAccent, resolveRadius } from "../theme/palette.ts";
+import { readOverlaidSpec } from "./parse.ts";
 import { resolveReferences } from "./references.ts";
 import type { ReferenceSource } from "./references.ts";
 
@@ -53,14 +54,44 @@ const themeConfiguration = (config: ResolvedConfig, override?: string) => {
   };
 };
 
+/** A source's Scalar spec config, or none when its overlays failed. */
+interface SpecConfiguration {
+  config?: { content: string } | { url: string };
+  warning?: string;
+}
+
+/**
+ * The spec with its overlays applied, inlined: Scalar can't apply overlays
+ * itself. A failed overlay skips the page rather than embed the spec without
+ * it, since an overlay is often what hides the internal operations.
+ */
+const overlaidConfiguration = async (
+  ref: ReferenceSource,
+  root: string
+): Promise<SpecConfiguration> => {
+  try {
+    const { text, warnings } = await readOverlaidSpec(ref.spec, root, {
+      overlays: ref.overlays,
+    });
+    return { config: { content: text }, warning: warnings[0] };
+  } catch (error) {
+    // SAFETY: reading, parsing, and overlaying throw Error instances.
+    const { message } = error as Error;
+    return {
+      warning: `API reference ${ref.route} was skipped: its overlays couldn't be applied to "${ref.spec}" (${message}).`,
+    };
+  }
+};
+
 /** Build the Scalar spec config for a source: inline `content` or remote `url`. */
 const specConfiguration = async (
-  spec: string,
+  ref: ReferenceSource,
   root: string
-): Promise<{
-  config: { content: string } | { url: string };
-  warning?: string;
-}> => {
+): Promise<SpecConfiguration> => {
+  const { spec } = ref;
+  if (ref.overlays?.length) {
+    return await overlaidConfiguration(ref, root);
+  }
   if (URL_SPEC.test(spec)) {
     return { config: { url: spec } };
   }
@@ -133,7 +164,7 @@ export const buildReferenceFiles = async (options: {
   const built = await Promise.all(
     accepted.map(async (ref) => ({
       ref,
-      spec: await specConfiguration(ref.spec, root),
+      spec: await specConfiguration(ref, root),
     }))
   );
 
@@ -142,6 +173,9 @@ export const buildReferenceFiles = async (options: {
     if (spec.warning) {
       warnings.push(spec.warning);
     }
+    if (!spec.config) {
+      continue;
+    }
     const pagePath = referencePagePath(ref.route);
     // `theme` is the one option Blume maps (a named theme replaces the
     // accent/radius layering); every other `scalar()` option is forwarded

package/src/openapi/source.ts

@@ -250,7 +250,7 @@ const parseReference = async (
   const { document, warnings } = await parseSpec(
     reference.spec,
     ctx.projectRoot,
-    options
+    { ...options, overlays: reference.overlays }
   );
   const extracted = extractOperations(document, reference.route);
   return {