blume 1.7.3 → 2.0.1

package/src/core/sources/resolve.ts

@@ -1,18 +1,29 @@
-import { isAbsolute, join, resolve } from "pathe";
+import { join } from "pathe";
 
 import { blumeReferences } from "../../openapi/references.ts";
 import { openApiSource } from "../../openapi/source.ts";
-import type { ContentSourceConfig, ResolvedConfig } from "../schema.ts";
+import type { ContentSourceAdapter } from "../../sources/registry.ts";
+import type { ResolvedConfig } from "../schema.ts";
 import type { ProjectContext } from "../types.ts";
+import { contentfulSource } from "./contentful.ts";
 import { filesystemSource } from "./filesystem.ts";
 import { githubReleasesSource } from "./github-releases.ts";
 import { mdxRemoteSource } from "./mdx-remote.ts";
 import { notionSource } from "./notion.ts";
 import { obsidianSource } from "./obsidian.ts";
+import { payloadSource } from "./payload.ts";
 import { sanitySource } from "./sanity.ts";
+import { strapiSource } from "./strapi.ts";
 import type { ContentSource, SourceContext } from "./types.ts";
 
-/** Allocate a unique, stable source name from a base (prefix or type). */
+export {
+  resolveDocsCollection,
+  resolveSourceRoot,
+  sourcesOfKind,
+} from "./collection.ts";
+export type { DocsCollection } from "./collection.ts";
+
+/** Allocate a unique, stable source name from a base (prefix or kind). */
 const uniqueNamer = (): ((base: string) => string) => {
   const used = new Set<string>();
   return (base) => {
@@ -63,191 +74,118 @@ const typeFrontmatterKeys = (
     ])
   );
 
+/**
+ * Instantiate the engine-side source for a descriptor. Each adapter's options
+ * spread straight into its engine factory: the descriptor carries exactly the
+ * fields the factory documents, plus the shared `prefix`/`pollInterval`.
+ */
 const buildSource = (
-  def: ContentSourceConfig,
+  adapter: ContentSourceAdapter,
   name: string,
   config: ResolvedConfig,
   context: ProjectContext,
   runtime: SourceRuntime
 ): ContentSource => {
-  if (def.type === "filesystem") {
-    return filesystemSource({
-      exclude: def.exclude,
-      include: def.include,
-      name,
-      prefix: def.prefix,
-      projectRoot: context.root,
-      root: def.root,
-    });
-  }
-  if (def.type === "custom") {
-    // A user-provided instance manages its own context/caching; we only ensure
-    // its name is unique across the project for id namespacing.
-    return def.source.name === name ? def.source : { ...def.source, name };
-  }
-  if (def.type === "sanity") {
-    return sanitySource(
-      {
-        apiVersion: def.apiVersion,
-        dataset: def.dataset,
-        fields: def.fields,
-        name,
-        pollInterval: def.pollInterval,
-        prefix: def.prefix,
-        projectId: def.projectId,
-        query: def.query,
-      },
-      sourceContext(context, name, runtime)
-    );
-  }
-  if (def.type === "notion") {
-    return notionSource(
-      {
-        concurrency: def.concurrency,
-        database: def.database,
-        name,
-        pollInterval: def.pollInterval,
-        prefix: def.prefix,
-        properties: def.properties,
-        publishedValue: def.publishedValue,
-      },
-      sourceContext(context, name, runtime)
-    );
-  }
-  if (def.type === "obsidian") {
-    return obsidianSource(
-      {
-        defaultType: config.content.defaultType,
-        exclude: def.exclude,
-        frontmatterKeys: Object.keys(config.frontmatter.extend),
-        i18n: config.i18n,
-        name,
-        prefix: def.prefix,
-        typeFrontmatterKeys: typeFrontmatterKeys(config),
-        vault: def.vault,
-        versions: config.versions,
-      },
-      sourceContext(context, name, runtime)
-    );
-  }
-  if (def.type === "github-releases") {
-    return githubReleasesSource(
-      {
-        drafts: def.drafts,
-        limit: def.limit,
-        name,
-        owner: def.owner,
-        pollInterval: def.pollInterval,
-        prefix: def.prefix,
-        prereleases: def.prereleases,
-        repo: def.repo,
-      },
-      sourceContext(context, name, runtime)
-    );
+  switch (adapter.kind) {
+    case "filesystem": {
+      const { pollInterval: _ignored, ...options } = adapter.options;
+      return filesystemSource({ ...options, name, projectRoot: context.root });
+    }
+    case "custom": {
+      // A user-provided instance manages its own context/caching; we only ensure
+      // its name is unique across the project for id namespacing.
+      const source = adapter.options;
+      return source.name === name ? source : { ...source, name };
+    }
+    case "sanity": {
+      return sanitySource(
+        { ...adapter.options, name },
+        sourceContext(context, name, runtime)
+      );
+    }
+    case "notion": {
+      return notionSource(
+        { ...adapter.options, name },
+        sourceContext(context, name, runtime)
+      );
+    }
+    case "contentful": {
+      return contentfulSource(
+        { ...adapter.options, name },
+        sourceContext(context, name, runtime)
+      );
+    }
+    case "payload": {
+      return payloadSource(
+        { ...adapter.options, name },
+        sourceContext(context, name, runtime)
+      );
+    }
+    case "strapi": {
+      return strapiSource(
+        { ...adapter.options, name },
+        sourceContext(context, name, runtime)
+      );
+    }
+    case "obsidian": {
+      const { pollInterval: _ignored, ...options } = adapter.options;
+      return obsidianSource(
+        {
+          ...options,
+          defaultType: config.content.defaultType,
+          frontmatterKeys: Object.keys(config.frontmatter.extend),
+          i18n: config.i18n,
+          name,
+          typeFrontmatterKeys: typeFrontmatterKeys(config),
+          versions: config.versions,
+        },
+        sourceContext(context, name, runtime)
+      );
+    }
+    case "github-releases": {
+      return githubReleasesSource(
+        { ...adapter.options, name },
+        sourceContext(context, name, runtime)
+      );
+    }
+    default: {
+      // Only `mdx-remote` is left, and TypeScript has narrowed `adapter` to it.
+      // It returns after the switch rather than from a last case block: Bun
+      // 1.4.0's line coverage never credits the closing brace of a switch's
+      // final block, which would fail the 100% gate in CI.
+      break;
+    }
   }
   return mdxRemoteSource(
-    {
-      files: def.files,
-      github: def.github,
-      include: def.include,
-      name,
-      pollInterval: def.pollInterval,
-      prefix: def.prefix,
-      url: def.url,
-    },
+    { ...adapter.options, name },
     sourceContext(context, name, runtime)
   );
 };
 
-/** Resolve a source `root` against the project root (absolute passes through). */
-const resolveRoot = (projectRoot: string, root: string): string =>
-  isAbsolute(root) ? root : join(resolve(projectRoot), root);
-
-/**
- * The generated `docs` glob collection: its base directory and the include /
- * exclude globs applied under it. Astro's glob loader ids each entry by its path
- * relative to `base`, and a filesystem source ids each entry relative to its own
- * root — so the two only agree when the collection is rooted at that source. A
- * project with exactly one filesystem source therefore roots the collection at
- * *that* source (honoring a non-default `root`), rather than the global
- * `content.root`. With no sources (the implicit source) or several, the base
- * stays `content.root`; a second filesystem source rooted elsewhere can't share
- * one base and is caught by the entry-id guard in `scanProject`.
- */
-export interface DocsCollection {
-  base: string;
-  include: string[];
-  exclude: string[];
-}
-
-export const resolveDocsCollection = (
-  config: ResolvedConfig,
-  context: ProjectContext
-): DocsCollection => {
-  const filesystem = (config.content.sources ?? []).filter(
-    (def) => def.type === "filesystem"
-  );
-  const only = filesystem.length === 1 ? filesystem[0] : undefined;
-  if (only) {
-    return {
-      base: resolveRoot(context.root, only.root),
-      exclude: only.exclude,
-      include: only.include,
-    };
-  }
-  return {
-    base: context.contentRoot,
-    exclude: config.content.exclude,
-    include: config.content.include,
-  };
-};
-
-/** The base name to allocate for a source config (before deduplication). */
-const baseName = (def: ContentSourceConfig): string => {
-  if (def.type === "custom") {
-    return def.source.name;
-  }
-  return def.prefix ?? def.type;
-};
-
-/** The content sources declared by config (implicit filesystem when none). */
-const contentSources = (
-  config: ResolvedConfig,
-  context: ProjectContext,
-  runtime: SourceRuntime
-): ContentSource[] => {
-  const defs = config.content.sources;
-  if (!defs || defs.length === 0) {
-    return [
-      filesystemSource({
-        exclude: config.content.exclude,
-        include: config.content.include,
-        name: "filesystem",
-        projectRoot: context.root,
-        root: config.content.root,
-      }),
-    ];
+/** The base name to allocate for a descriptor (before deduplication). */
+const baseName = (adapter: ContentSourceAdapter): string => {
+  if (adapter.kind === "custom") {
+    return adapter.options.name;
   }
-
-  const nameFor = uniqueNamer();
-  return defs.map((def) =>
-    buildSource(def, nameFor(baseName(def)), config, context, runtime)
-  );
+  return adapter.options.prefix ?? adapter.kind;
 };
 
 /**
- * Build the ordered list of content sources for a project. With no
- * `content.sources` configured, the top-level `root`/`include`/`exclude` desugar
- * to a single implicit filesystem source, so existing projects are untouched.
- * A Blume-rendered OpenAPI reference contributes an internal staged source that
- * lowers each operation into a real content page (routing/nav/search/OG).
+ * Build the ordered list of content sources for a project. The config schema
+ * already desugared the zero-config shorthand into a single `filesystem()`
+ * descriptor, so every project has at least one entry here. A Blume-rendered
+ * OpenAPI reference contributes an internal staged source that lowers each
+ * operation into a real content page (routing/nav/search/OG).
  */
 export const resolveSources = (
   config: ResolvedConfig,
   context: ProjectContext,
   runtime: SourceRuntime
 ): ContentSource[] => {
-  const sources = contentSources(config, context, runtime);
+  const nameFor = uniqueNamer();
+  const sources = config.content.sources.map((adapter) =>
+    buildSource(adapter, nameFor(baseName(adapter)), config, context, runtime)
+  );
 
   const references = blumeReferences(config);
   if (references.length > 0) {

package/src/core/sources/sanity.ts

@@ -2,12 +2,16 @@ import { join } from "pathe";
 
 import { BlumeError } from "../diagnostics.ts";
 import matter from "../frontmatter.ts";
+import { nodeRequire } from "../node-require.ts";
 import {
   hashText,
   loadWithCache,
   pollingWatch,
   snapshotCache,
 } from "./cache.ts";
+import type { JsonObject } from "./json.ts";
+import { asString, getPath } from "./json.ts";
+import { writesMdx } from "./lower.ts";
 import { slugify, slugifyPath } from "./normalize.ts";
 import { portableTextToMarkdown } from "./portable-text.ts";
 import type { PortableTextBlock } from "./portable-text.ts";
@@ -59,19 +63,8 @@ export interface SanitySourceOptions {
 
 const IMAGE_REF = /^image-(?<id>[a-f0-9]+)-(?<dims>\d+x\d+)-(?<ext>\w+)$/u;
 
-/** A value in a fetched document: arbitrary JSON the GROQ query returned. */
-type SanityValue =
-  | string
-  | number
-  | boolean
-  | null
-  | SanityValue[]
-  | { [key: string]: SanityValue };
-
 /** A document as the GROQ query returns it. */
-interface SanityDocument {
-  [key: string]: SanityValue;
-}
+type SanityDocument = JsonObject;
 
 /** The frontmatter fields this adapter maps from a document. */
 interface SanityFrontmatter {
@@ -79,37 +72,6 @@ interface SanityFrontmatter {
   title?: string;
 }
 
-/**
- * A node a dot path can descend into. Arrays pass too (matching their runtime
- * string-key indexing, e.g. `items.0`), so the predicate types them as the
- * keyed form both traverse through.
- */
-const isTraversable = (
-  value: SanityValue | undefined
-): value is SanityDocument => typeof value === "object" && value !== null;
-
-/** Resolve a dot path (`slug.current`) against a document. */
-const getPath = (
-  doc: SanityDocument,
-  path: string
-): SanityValue | undefined => {
-  let current: SanityValue | undefined = doc;
-  for (const key of path.split(".")) {
-    if (isTraversable(current)) {
-      current = current[key];
-    } else {
-      return;
-    }
-  }
-  return current;
-};
-
-const isStringValue = (value: SanityValue | undefined): value is string =>
-  typeof value === "string";
-
-const asString = (value: SanityValue | undefined): string | undefined =>
-  isStringValue(value) ? value : undefined;
-
 /** Build a Sanity CDN URL from an image asset `_ref`. */
 const imageUrlFromRef = (
   ref: string,
@@ -134,19 +96,21 @@ interface SanityClientConfig {
   useCdn: boolean;
 }
 
-const resolveClient = async (
+const resolveClient = (
   options: SanitySourceOptions,
   preview: boolean
-): Promise<SanityClientLike> => {
+): SanityClientLike => {
   if (options.client) {
     return options.client;
   }
   let createClient: (config: SanityClientConfig) => SanityClientLike;
   try {
+    // `require`, not `import()`: an ejected app scans in `astro:build:done`
+    // (see `core/node-require.ts`).
     // SAFETY: `@sanity/client` is an optional dependency; its `createClient`
     // accepts a superset of this config slice and returns a client exposing
     // the `fetch` method this adapter uses.
-    ({ createClient } = (await import("@sanity/client")) as {
+    ({ createClient } = nodeRequire("@sanity/client") as {
       createClient: (config: SanityClientConfig) => SanityClientLike;
     });
   } catch {
@@ -228,16 +192,19 @@ export const sanitySource = (
         })
       : "";
 
+    // Serializer output is MDX (components, directives), so a source with
+    // serializers writes its entries as `.mdx`.
+    const format = writesMdx(options.serializers) ? "mdx" : "md";
     const raw = matter.stringify(markdown, data);
     return {
-      body: { format: "md", text: markdown },
+      body: { format, text: markdown },
       // Spread into a fresh literal: `SourceEntry.data` wants an
       // index-signature type, which the named interface lacks.
       data: { ...data },
       hash: hashText(raw),
       lastModified: asString(getPath(doc, fields.lastModified ?? "_updatedAt")),
       raw,
-      ref: `${slug}.md`,
+      ref: `${slug}.${format}`,
     };
   };
 
@@ -248,7 +215,7 @@ export const sanitySource = (
       options.name,
       cache,
       async () => {
-        const client = await resolveClient(options, ctx?.preview ?? false);
+        const client = resolveClient(options, ctx?.preview ?? false);
         const docs = await client.fetch<SanityDocument[]>(options.query);
         return docs.map(toEntry);
       },

package/src/core/sources/strapi-blocks.ts

@@ -0,0 +1,124 @@
+/**
+ * Strapi's Rich text (Blocks) field → Markdown. Covers every block the
+ * editor emits: paragraphs, headings, lists (nested), quotes, code, images,
+ * and links with the text modifiers.
+ */
+import type { JsonObject, JsonValue } from "./json.ts";
+import { asNumber, asObject, asString, objectsIn } from "./json.ts";
+import {
+  absoluteUrl,
+  blockquote,
+  codeFence,
+  headingPrefix,
+  image,
+  listItem,
+  markdownDocument,
+  renderInline,
+  renderLink,
+  unsupported,
+} from "./lower.ts";
+
+export interface StrapiBlocksOptions {
+  /** The Strapi origin a relative upload URL (`/uploads/x.png`) resolves against. */
+  baseUrl?: string;
+}
+
+const children = (node: JsonObject): JsonObject[] => objectsIn(node.children);
+
+const typeOf = (node: JsonObject): string => asString(node.type) ?? "";
+
+const renderInlines = (nodes: JsonObject[]): string =>
+  nodes
+    // oxlint-disable-next-line no-use-before-define -- mutual recursion: a link's label is itself inline content
+    .map((node) => renderInlineNode(node))
+    .join("");
+
+const renderInlineNode = (node: JsonObject): string => {
+  switch (typeOf(node)) {
+    case "text": {
+      return renderInline(asString(node.text) ?? "", {
+        bold: node.bold === true,
+        code: node.code === true,
+        italic: node.italic === true,
+        strike: node.strikethrough === true,
+      });
+    }
+    case "link": {
+      return renderLink(renderInlines(children(node)), asString(node.url));
+    }
+    default: {
+      return renderInlines(children(node));
+    }
+  }
+};
+
+const renderList = (node: JsonObject): string => {
+  const ordered = asString(node.format) === "ordered";
+  return children(node)
+    .map((item, index) => {
+      const kids = children(item);
+      const line = renderInlines(kids.filter((kid) => typeOf(kid) !== "list"));
+      const sub = kids
+        .filter((kid) => typeOf(kid) === "list")
+        .map((list) => renderList(list))
+        .join("\n");
+      const body = sub ? `${line}\n${sub}` : line;
+      return listItem(ordered ? `${index + 1}.` : "-", body);
+    })
+    .join("\n");
+};
+
+const renderImage = (
+  node: JsonObject,
+  options: StrapiBlocksOptions
+): string => {
+  const file = asObject(node.image);
+  const url = file ? asString(file.url) : undefined;
+  if (!(file && url)) {
+    return "";
+  }
+  return image(
+    asString(file.alternativeText) ?? asString(file.name) ?? "",
+    absoluteUrl(url, options.baseUrl)
+  );
+};
+
+const renderBlock = (
+  node: JsonObject,
+  options: StrapiBlocksOptions
+): string => {
+  switch (typeOf(node)) {
+    case "paragraph": {
+      return renderInlines(children(node));
+    }
+    case "heading": {
+      return `${headingPrefix(asNumber(node.level) ?? 1)}${renderInlines(children(node))}`;
+    }
+    case "quote": {
+      return blockquote(renderInlines(children(node)));
+    }
+    case "list": {
+      return renderList(node);
+    }
+    case "code": {
+      // Code children are plain text nodes; their text is literal.
+      const code = children(node)
+        .map((child) => asString(child.text) ?? "")
+        .join("");
+      return codeFence(code, asString(node.language) ?? "");
+    }
+    case "image": {
+      return renderImage(node, options);
+    }
+    default: {
+      return unsupported(`Strapi block: ${typeOf(node)}`);
+    }
+  }
+};
+
+/** Serialize a Blocks field value (an array of block nodes) to Markdown. */
+export const strapiBlocksToMarkdown = (
+  blocks: JsonValue,
+  options: StrapiBlocksOptions = {}
+): string =>
+  markdownDocument(objectsIn(blocks).map((node) => renderBlock(node, options)));