blume 1.4.3 → 1.5.0

package/src/og/card.ts

@@ -6,7 +6,7 @@ import type { RenderOptions } from "takumi-js";
 import { container, googleFonts, image, text } from "takumi-js/helpers";
 import type { FontSubset, GoogleFontFamily, Node } from "takumi-js/helpers";
 
-import { ACCENTS } from "../theme/palette.ts";
+import { ACCENTS, isAccentPreset } from "../theme/palette.ts";
 import { OG_IMAGE_HEIGHT, OG_IMAGE_WIDTH } from "./dimensions.ts";
 
 /** A local font file registered with the OG card renderer, read at build. */
@@ -61,10 +61,10 @@ export interface OgFontFamilies {
 // shows (a separate hand-synced hex palette used to drift: the card's "blue"
 // was Tailwind's, not Blume's). Anything else is handed to Takumi as-is, and
 // a genuinely malformed value fails the build with a parse error naming it.
-// `hasOwn` keeps a preset name like "constructor" from resolving up the
-// prototype chain.
+// `isAccentPreset` keeps a preset name like "constructor" from resolving up
+// the prototype chain.
 const resolveAccent = (accent: string): string =>
-  Object.hasOwn(ACCENTS, accent) ? (ACCENTS[accent] as string) : accent;
+  isAccentPreset(accent) ? ACCENTS[accent] : accent;
 
 export interface OgCardPalette {
   accent?: string;
@@ -153,6 +153,9 @@ const loadFonts = (
   const key = JSON.stringify(fonts);
   let pending = fontSubsetCache.get(key);
   if (!pending) {
+    // SAFETY: OgFont's weight strings are documented as variable ranges like
+    // "100..900" (GoogleFontFamily's WeightRange); Takumi validates the value
+    // at fetch time and fails the build naming a malformed one.
     pending = googleFonts(fonts as GoogleFontFamily[]);
     fontSubsetCache.set(key, pending);
   }
@@ -165,13 +168,29 @@ const loadFonts = (
  * registers each file once across a build's per-page renders; a missing file
  * rejects at first use, failing the build with the path in the cause.
  */
-const localFontLoader = (font: OgLocalFont) => ({
-  data: () => readFile(font.src),
-  key: font.src,
-  name: font.name,
-  ...(font.weight === undefined ? {} : { weight: font.weight }),
-  ...(font.style === undefined ? {} : { style: font.style }),
-});
+/** A lazily-read local font file, in the shape `render` accepts for `fonts`. */
+interface LocalFontSource {
+  data: () => Promise<Buffer>;
+  key: string;
+  name: string;
+  weight?: number;
+  style?: "normal" | "italic";
+}
+
+const localFontLoader = (font: OgLocalFont): LocalFontSource => {
+  const loader: LocalFontSource = {
+    data: () => readFile(font.src),
+    key: font.src,
+    name: font.name,
+  };
+  if (font.weight !== undefined) {
+    loader.weight = font.weight;
+  }
+  if (font.style !== undefined) {
+    loader.style = font.style;
+  }
+  return loader;
+};
 
 // Light neutral scale mirrored from the docs homepage theme tokens:
 // FOREGROUND = --foreground, MUTED = --muted-foreground, FAINT = that lighter,

package/src/og/derive.ts

@@ -13,7 +13,6 @@ import type {
   FontsConfig,
   FontValue,
   LocalFontConfig,
-  RemoteFontConfig,
 } from "../theme/fonts.ts";
 import { GOOGLE_FONTS, isFontSlug } from "../theme/fonts.ts";
 import type { OgFont, OgFontFamilies, OgLocalFont } from "./card.ts";
@@ -31,6 +30,23 @@ const CARD_WEIGHTS = [400, 600];
 const absoluteSrc = (root: string, src: string): string =>
   isAbsolute(src) ? src : join(root, src);
 
+/** A concrete numeric face weight (as opposed to a variable-range string). */
+const isNumericWeight = (
+  weight: number | string | undefined
+): weight is number => typeof weight === "number";
+
+/** A variable-range weight spec string, e.g. `"100..900"`. */
+const isRangeWeight = (weight: number | string | undefined): weight is string =>
+  typeof weight === "string";
+
+/** A theme role configured as a font slug / family-name string. */
+const isFontName = (value: FontValue): value is string =>
+  typeof value === "string";
+
+/** An OG font entry that reads a local file (as opposed to a Google family). */
+const isLocalOgFont = (font: OgFont): font is OgLocalFont =>
+  typeof font !== "string" && "src" in font;
+
 /**
  * The weight spec to fetch for a derived Google family: the declared weights
  * the card uses, the declared numeric weights otherwise, a lone variable
@@ -39,9 +55,7 @@ const absoluteSrc = (root: string, src: string): string =>
 const googleWeights = (
   weights: (number | string)[]
 ): number[] | string | undefined => {
-  const numbers = weights.filter(
-    (weight): weight is number => typeof weight === "number"
-  );
+  const numbers = weights.filter(isNumericWeight);
   const used = numbers.filter((weight) => CARD_WEIGHTS.includes(weight));
   if (used.length > 0) {
     return used;
@@ -50,7 +64,7 @@ const googleWeights = (
     return numbers;
   }
   const [first] = weights;
-  return weights.length === 1 && typeof first === "string" ? first : undefined;
+  return weights.length === 1 && isRangeWeight(first) ? first : undefined;
 };
 
 const googleOgFont = (name: string, weights: (number | string)[]): OgFont => {
@@ -60,15 +74,19 @@ const googleOgFont = (name: string, weights: (number | string)[]): OgFont => {
 
 /** Per-variant local entries for the renderer (paths made absolute). */
 const localOgFonts = (font: LocalFontConfig, root: string): OgLocalFont[] =>
-  font.variants.map((variant) => ({
-    name: font.name,
-    src: absoluteSrc(root, variant.src),
-    ...(typeof variant.weight === "number" ? { weight: variant.weight } : {}),
+  font.variants.map((variant) => {
+    const entry: OgLocalFont = {
+      name: font.name,
+      src: absoluteSrc(root, variant.src),
+    };
+    const withWeight: OgLocalFont = isNumericWeight(variant.weight)
+      ? { ...entry, weight: variant.weight }
+      : entry;
     // Takumi's per-face style is normal/italic; oblique falls back to the file.
-    ...(variant.style === "normal" || variant.style === "italic"
-      ? { style: variant.style }
-      : {}),
-  }));
+    return variant.style === "normal" || variant.style === "italic"
+      ? { ...withWeight, style: variant.style }
+      : withWeight;
+  });
 
 /**
  * The card fonts for one theme role, or null when the role can't flow into
@@ -76,7 +94,7 @@ const localOgFonts = (font: LocalFontConfig, root: string): OgLocalFont[] =>
  * `googleFonts` only speaks Google's css2 endpoint).
  */
 const roleFonts = (value: FontValue, root: string): OgFont[] | null => {
-  if (typeof value === "string") {
+  if (isFontName(value)) {
     if (!isFontSlug(value)) {
       return null;
     }
@@ -86,16 +104,15 @@ const roleFonts = (value: FontValue, root: string): OgFont[] | null => {
   if ("variants" in value) {
     return localOgFonts(value, root);
   }
-  const remote = value as RemoteFontConfig;
-  if ((remote.provider ?? "google") !== "google") {
+  if ((value.provider ?? "google") !== "google") {
     return null;
   }
-  return [googleOgFont(remote.name, remote.weights ?? CARD_WEIGHTS)];
+  return [googleOgFont(value.name, value.weights ?? CARD_WEIGHTS)];
 };
 
 /** The family name a theme role registers under. */
 const roleFamily = (value: FontValue): string | null => {
-  if (typeof value === "string") {
+  if (isFontName(value)) {
     return isFontSlug(value) ? GOOGLE_FONTS[value].family : null;
   }
   return value.name;
@@ -136,18 +153,17 @@ export const deriveOgFonts = (
     }
   }
 
-  return {
-    fonts: derived,
-    ...(families.title || families.body ? { families } : {}),
-  };
+  const result: DerivedOgFonts = { fonts: derived };
+  if (families.title || families.body) {
+    result.families = families;
+  }
+  return result;
 };
 
 /** Explicit `seo.og.fonts` with local `src` paths resolved to absolute. */
 export const resolveOgFontSources = (fonts: OgFont[], root: string): OgFont[] =>
   fonts.map((font) =>
-    typeof font !== "string" && "src" in font
-      ? { ...font, src: absoluteSrc(root, font.src) }
-      : font
+    isLocalOgFont(font) ? { ...font, src: absoluteSrc(root, font.src) } : font
   );
 
 /**
@@ -185,14 +201,14 @@ export const missingFontFiles = (
 ): string[] => {
   const sources: string[] = [];
   for (const value of Object.values(options.themeFonts ?? {})) {
-    if (typeof value !== "string" && "variants" in value) {
+    if (!isFontName(value) && "variants" in value) {
       sources.push(
         ...value.variants.map((variant) => absoluteSrc(root, variant.src))
       );
     }
   }
   for (const font of options.ogFonts) {
-    if (typeof font !== "string" && "src" in font) {
+    if (isLocalOgFont(font)) {
       sources.push(absoluteSrc(root, font.src));
     }
   }

package/src/openapi/asyncapi.ts

@@ -0,0 +1,366 @@
+import type { ApiOperationRef, ApiTagRef } from "./model.ts";
+import { operationCollector, operationKey } from "./model.ts";
+
+/**
+ * Blume's own AsyncAPI model — the second front-end of the API reference
+ * pipeline. Specs are normalized to AsyncAPI 3.x at parse time (see
+ * `parseAsyncApiSpec` in `parse.ts`), so this module only handles one shape:
+ * top-level `operations` with `action: send | receive` pointing at `channels`.
+ * Internal `$ref`s are deliberately left in place, mirroring `model.ts` — the
+ * components resolve them lazily, which keeps circular schemas serializable
+ * and lets type labels keep their `#/components/schemas/<name>` names.
+ * Browser-safe: no Node imports (the components import from here).
+ */
+
+/** The two AsyncAPI 3.x operation actions, from the application's perspective. */
+export const ASYNCAPI_ACTIONS = ["send", "receive"] as const;
+
+export type AsyncApiAction = (typeof ASYNCAPI_ACTIONS)[number];
+
+/**
+ * A value carried by a parsed spec document: JSON-compatible data whose exact
+ * position in the document is not modeled (extension fields, bindings,
+ * protocol-specific extras). `undefined` covers absent optional members.
+ */
+export type AsyncApiSpecValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | AsyncApiSpecValue[]
+  | { [key: string]: AsyncApiSpecValue };
+
+/** A permissive view of an AsyncAPI reference object. */
+export interface AsyncApiRefLike {
+  $ref?: string;
+  [key: string]: AsyncApiSpecValue;
+}
+
+/** A permissive view of an AsyncAPI 3.x channel — only the fields we render. */
+export interface AsyncApiChannelObject {
+  address?: string | null;
+  title?: string;
+  summary?: string;
+  description?: string;
+  messages?: Record<string, AsyncApiRefLike>;
+  parameters?: Record<string, AsyncApiRefLike>;
+  servers?: AsyncApiRefLike[];
+  bindings?: Record<string, Record<string, AsyncApiSpecValue>>;
+  [key: string]: AsyncApiSpecValue;
+}
+
+/** A permissive view of an AsyncAPI 3.x operation — only the fields we render. */
+export interface AsyncApiOperationObject {
+  action?: string;
+  channel?: AsyncApiRefLike;
+  title?: string;
+  summary?: string;
+  description?: string;
+  deprecated?: boolean;
+  tags?: { name?: string; description?: string }[];
+  security?: AsyncApiRefLike[];
+  messages?: AsyncApiRefLike[];
+  bindings?: Record<string, Record<string, AsyncApiSpecValue>>;
+  [key: string]: AsyncApiSpecValue;
+}
+
+/** A permissive view of an AsyncAPI 3.x server object. */
+export interface AsyncApiServerObject {
+  host?: string;
+  protocol?: string;
+  pathname?: string;
+  description?: string;
+  security?: AsyncApiRefLike[];
+  [key: string]: AsyncApiSpecValue;
+}
+
+/** A normalized AsyncAPI 3.x document, internal `$ref`s intact. */
+export interface AsyncApiDocument {
+  asyncapi?: string;
+  info?: {
+    title?: string;
+    version?: string;
+    description?: string;
+    tags?: { name?: string; description?: string }[];
+    [key: string]: AsyncApiSpecValue;
+  };
+  defaultContentType?: string;
+  servers?: Record<string, AsyncApiServerObject>;
+  channels?: Record<string, AsyncApiChannelObject>;
+  operations?: Record<string, AsyncApiOperationObject>;
+  components?: Record<string, Record<string, AsyncApiSpecValue>>;
+  [key: string]: AsyncApiSpecValue;
+}
+
+/** Decode a JSON-pointer token: `user~1signedup` -> `user/signedup`. */
+const unescapePointer = (token: string): string =>
+  token.replaceAll("~1", "/").replaceAll("~0", "~");
+
+const CHANNEL_REF = /^#\/channels\/(?<id>.+)$/u;
+
+const isString = (value: AsyncApiSpecValue): value is string =>
+  typeof value === "string";
+
+/** The channel id an operation's `channel.$ref` points at, if resolvable. */
+export const channelIdOf = (channel?: AsyncApiRefLike): string | undefined => {
+  const id = CHANNEL_REF.exec(channel?.$ref ?? "")?.groups?.id;
+  return id === undefined ? undefined : unescapePointer(id);
+};
+
+/**
+ * A channel's display address. AsyncAPI 3.x allows `address: null` (unknown at
+ * design time) — fall back to the channel id so the operation still shows
+ * where it lives.
+ */
+export const channelAddress = (
+  channelId: string,
+  channel?: AsyncApiChannelObject
+): string => {
+  const address = channel?.address;
+  return isString(address) && address !== "" ? address : channelId;
+};
+
+const isObject = (
+  value: AsyncApiSpecValue
+): value is Record<string, AsyncApiSpecValue> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const COMPONENT_SECTION_REF =
+  /^#\/components\/(?<section>channels|operations)\/(?<name>[^/]+)$/u;
+
+/**
+ * Inline top-level `channels`/`operations` entries declared as Reference
+ * Objects (`{ $ref: "#/components/channels/…" }` — the spec's reuse pattern)
+ * by replacing them with their components target. Runs before trait merging
+ * so an inlined operation's traits merge exactly like an inline one's.
+ * Unresolvable refs stay in place; the extractor reports them.
+ */
+const inlineComponentRefs = (document: AsyncApiDocument): void => {
+  const maps: [Record<string, AsyncApiSpecValue> | undefined, string][] = [
+    [document.channels, "channels"],
+    [document.operations, "operations"],
+  ];
+  for (const [map, section] of maps) {
+    if (!isObject(map)) {
+      continue;
+    }
+    const table = document.components?.[section];
+    for (const [id, entry] of Object.entries(map)) {
+      if (!isObject(entry) || !isString(entry.$ref)) {
+        continue;
+      }
+      const groups = COMPONENT_SECTION_REF.exec(entry.$ref)?.groups;
+      if (groups?.section !== section) {
+        continue;
+      }
+      const resolved = isObject(table)
+        ? table[unescapePointer(groups.name ?? "")]
+        : undefined;
+      if (isObject(resolved) && !isString(resolved.$ref)) {
+        map[id] = resolved;
+      }
+    }
+  }
+};
+
+const TRAIT_REF =
+  /^#\/components\/(?<section>operationTraits|messageTraits)\/(?<name>[^/]+)$/u;
+
+/**
+ * Merge `traits` into their operation/message objects, in declaration order,
+ * with the object's own properties taking precedence (the spec's merge rule;
+ * applied shallowly, which covers the fields traits carry in practice —
+ * bindings, security, tags, headers). Runs once at parse time so the
+ * serialized document and every downstream consumer are trait-free; the
+ * `traits` key itself is dropped. Unresolvable trait `$ref`s are skipped.
+ */
+export const applyAsyncApiTraits = (
+  document: AsyncApiDocument
+): AsyncApiDocument => {
+  const resolveTrait = (
+    trait: AsyncApiSpecValue
+  ): Record<string, AsyncApiSpecValue> | undefined => {
+    if (!isObject(trait)) {
+      return undefined;
+    }
+    if (!isString(trait.$ref)) {
+      return trait;
+    }
+    const groups = TRAIT_REF.exec(trait.$ref)?.groups;
+    const section = groups?.section
+      ? document.components?.[groups.section]
+      : undefined;
+    const resolved = section?.[groups?.name ?? ""];
+    return isObject(resolved) ? resolved : undefined;
+  };
+
+  const mergeTraits = (node: Record<string, AsyncApiSpecValue>): void => {
+    const { traits } = node;
+    if (!Array.isArray(traits)) {
+      return;
+    }
+    delete node.traits;
+    const merged: Record<string, AsyncApiSpecValue> = {};
+    for (const trait of traits) {
+      Object.assign(merged, resolveTrait(trait));
+    }
+    for (const [key, value] of Object.entries(merged)) {
+      if (!(key in node)) {
+        node[key] = value;
+      }
+    }
+  };
+
+  for (const operation of Object.values(document.operations ?? {})) {
+    if (isObject(operation)) {
+      mergeTraits(operation);
+    }
+  }
+  const channelMaps = [
+    ...Object.values(document.channels ?? {}),
+    // Reusable channels under components carry messages too; their traits
+    // must merge the same way so a resolved component channel renders alike.
+    ...Object.values(document.components?.channels ?? {}),
+  ];
+  const messageMaps = [
+    ...channelMaps.map((channel) =>
+      isObject(channel) ? channel.messages : undefined
+    ),
+    document.components?.messages,
+  ];
+  for (const messages of messageMaps) {
+    if (!isObject(messages)) {
+      continue;
+    }
+    for (const message of Object.values(messages)) {
+      // A channel message that is itself a `$ref` resolves to a components
+      // message, which this loop also visits — don't merge through the ref.
+      if (isObject(message) && !isString(message.$ref)) {
+        mergeTraits(message);
+      }
+    }
+  }
+  return document;
+};
+
+/**
+ * The parse-time normalization pass: component channel/operation refs inlined,
+ * then traits merged. The serialized document and every downstream consumer
+ * see plain channel/operation objects, trait-free.
+ */
+export const normalizeAsyncApiDocument = (
+  document: AsyncApiDocument
+): AsyncApiDocument => {
+  inlineComponentRefs(document);
+  return applyAsyncApiTraits(document);
+};
+
+/**
+ * Resolve where one operation renders from: its action and its declared
+ * channel. A string return is the warning explaining why the operation can't
+ * appear in the reference.
+ */
+const operationSite = (
+  id: string,
+  operation: AsyncApiOperationObject,
+  channels: Record<string, AsyncApiChannelObject>
+): { action: AsyncApiAction; channelId: string; address: string } | string => {
+  const action = ASYNCAPI_ACTIONS.find((a) => a === operation.action);
+  if (!action) {
+    return `Operation "${id}" declares no send/receive action; it is missing from the reference.`;
+  }
+  const channelId = channelIdOf(operation.channel);
+  const channel = channelId === undefined ? undefined : channels[channelId];
+  // A channel entry that is still a bare `$ref` survived normalization — its
+  // components target doesn't exist — so it renders nothing useful either.
+  if (channelId === undefined || !isObject(channel) || isString(channel.$ref)) {
+    return `Operation "${id}" references a channel that isn't declared under "channels"; it is missing from the reference.`;
+  }
+  return { action, address: channelAddress(channelId, channel), channelId };
+};
+
+/** The route-mapped operations, ordered tags, and skip warnings of one document. */
+export interface AsyncApiOperationCatalog {
+  operations: ApiOperationRef[];
+  tags: ApiTagRef[];
+  warnings: string[];
+}
+
+/**
+ * Flatten a normalized AsyncAPI 3.x document into a route-mapped operation
+ * list and its ordered tags — the AsyncAPI counterpart of `extractOperations`
+ * in `model.ts`, built on the same `operationCollector`. Operations group by
+ * their first tag; untagged operations fall back to their channel address, so
+ * a spec with no tags still gets one sidebar group per channel. Keys come from
+ * the operation id (the `operations` map key), which the official 2.x
+ * converter synthesizes deterministically (`<channel>.publish` /
+ * `<channel>.subscribe`) — so a 2.x spec and its converter-upgraded 3.x form
+ * yield identical URLs. An id that slugifies to nothing falls back to
+ * action + address, the same scheme `operationKey` uses for method + path.
+ */
+export const extractAsyncApiOperations = (
+  document: AsyncApiDocument,
+  baseRoute: string
+): AsyncApiOperationCatalog => {
+  const warnings: string[] = [];
+  const tagMeta = new Map(
+    (document.info?.tags ?? [])
+      .filter(
+        (tag): tag is { name: string; description?: string } =>
+          typeof tag?.name === "string"
+      )
+      .map((tag): [string, string] => [tag.name, tag.description ?? ""])
+  );
+  const collector = operationCollector(baseRoute, tagMeta);
+  const channels = document.channels ?? {};
+
+  for (const [id, operation] of Object.entries(document.operations ?? {})) {
+    if (!isObject(operation)) {
+      continue;
+    }
+    // An operation entry still carrying a `$ref` is one normalization could
+    // not inline; name the real problem instead of the missing-action one.
+    if (isString(operation.$ref)) {
+      warnings.push(
+        `Operation "${id}" is a reference that doesn't resolve to a components operation; it is missing from the reference.`
+      );
+      continue;
+    }
+    const site = operationSite(id, operation, channels);
+    if (isString(site)) {
+      warnings.push(site);
+      continue;
+    }
+    const { action, address, channelId } = site;
+    const tag = operation.tags?.find(
+      (candidate): candidate is { name: string; description?: string } =>
+        typeof candidate?.name === "string"
+    )?.name;
+    collector.add({
+      channelId,
+      deprecated: operation.deprecated === true,
+      description: operation.description ?? "",
+      key: operationKey(action, address, id),
+      method: action,
+      operationId: id,
+      path: address,
+      summary: operation.title ?? operation.summary ?? "",
+      tag: tag ?? address,
+    });
+  }
+
+  return { ...collector.finish(), warnings };
+};
+
+/** Resolve the operation object for a ref out of its (AsyncAPI) document. */
+export const asyncApiOperationObject = (
+  document: AsyncApiDocument,
+  ref: ApiOperationRef
+): AsyncApiOperationObject | undefined => {
+  const operation =
+    ref.operationId === undefined
+      ? undefined
+      : document.operations?.[ref.operationId];
+  return isObject(operation) ? operation : undefined;
+};