blodemd 0.0.13 → 0.0.15

package/packages/@repo/previewing/src/config-loader.ts

@@ -0,0 +1,316 @@
+import path from "node:path";
+
+import { normalizePath } from "@repo/common";
+import type { DocsConfig, SiteConfig } from "@repo/models";
+import { validateDocsConfig, validateSiteConfig } from "@repo/validation";
+
+import { LEGACY_PROJECT_NAME_FALLBACK_WARNING } from "./constants.js";
+import type { ContentSource } from "./content-source.js";
+import type { SiteConfigResult } from "./types.js";
+
+const DOCS_CONFIG_FILE = "docs.json";
+
+const defaultLinkLabel = (input: {
+  href: string;
+  label?: string;
+  type?: "discord" | "github";
+}) => {
+  if (input.label) {
+    return input.label;
+  }
+  if (input.type === "github") {
+    return "GitHub";
+  }
+  if (input.type === "discord") {
+    return "Discord";
+  }
+  try {
+    return new URL(input.href).hostname;
+  } catch {
+    return input.href;
+  }
+};
+
+// oxlint-disable-next-line eslint/complexity
+const mapDocsConfig = (docs: DocsConfig): SiteConfig => {
+  const navigation = {
+    global:
+      docs.navbar?.links?.length || docs.navigation.global?.anchors?.length
+        ? {
+            anchors: docs.navigation.global?.anchors?.map((anchor) => ({
+              href: anchor.href,
+              label: anchor.anchor,
+            })),
+            links: docs.navbar?.links?.map((link) => ({
+              href: link.href,
+              label: defaultLinkLabel(link),
+            })),
+          }
+        : undefined,
+    groups: docs.navigation.groups?.map((group) => ({
+      expanded: group.expanded,
+      group: group.group,
+      hidden: group.hidden,
+      pages: group.root
+        ? [
+            group.root,
+            ...(group.pages ?? []).filter((page) => page !== group.root),
+          ]
+        : group.pages,
+    })),
+    languages: docs.navigation.languages?.map((language) => ({
+      label: language.language,
+      locale: language.language,
+      url: language.href,
+    })),
+    pages: docs.navigation.pages,
+    tabs: docs.navigation.tabs?.map((tab) => ({
+      groups: tab.groups?.map((group) => ({
+        expanded: group.expanded,
+        group: group.group,
+        hidden: group.hidden,
+        pages: group.root
+          ? [
+              group.root,
+              ...(group.pages ?? []).filter((page) => page !== group.root),
+            ]
+          : group.pages,
+      })),
+      href: tab.href,
+      icon: tab.icon,
+      label: tab.tab,
+      pages: tab.pages,
+    })),
+    versions: docs.navigation.versions?.map((version) => ({
+      label: version.version,
+      url: version.href,
+    })),
+  } satisfies SiteConfig["navigation"];
+
+  return {
+    collections: [
+      {
+        id: "docs",
+        navigation,
+        openapi: docs.api?.openapi,
+        root: "",
+        type: "docs",
+      },
+    ],
+    contextual: docs.contextual,
+    description: docs.description,
+    favicon:
+      typeof docs.favicon === "string" ? docs.favicon : docs.favicon?.light,
+    features: {
+      rightToc: true,
+      search: true,
+      themeToggle: docs.appearance?.strict !== true,
+      toc: true,
+    },
+    logo: docs.logo
+      ? {
+          dark: typeof docs.logo === "string" ? docs.logo : docs.logo.dark,
+          href: typeof docs.logo === "string" ? undefined : docs.logo.href,
+          light: typeof docs.logo === "string" ? docs.logo : docs.logo.light,
+        }
+      : undefined,
+    name: docs.name,
+    navigation,
+    openapiProxy: {
+      enabled:
+        docs.api?.playground?.proxy !== false &&
+        Boolean(docs.api?.openapi || docs.api?.asyncapi),
+    },
+    seo: docs.seo,
+    slug: docs.slug,
+  };
+};
+
+const getProjectWarnings = (config: { slug?: string }): string[] =>
+  config.slug ? [] : [LEGACY_PROJECT_NAME_FALLBACK_WARNING];
+
+const readJsonConfig = async (source: ContentSource, relativePath: string) =>
+  JSON.parse(await source.readFile(relativePath)) as unknown;
+
+const normalizeRefPath = (baseDirectory: string, reference: string) => {
+  if (
+    reference.startsWith("/") ||
+    reference.startsWith("\\") ||
+    reference.startsWith("http://") ||
+    reference.startsWith("https://")
+  ) {
+    throw new Error(
+      `Invalid $ref "${reference}". Only relative JSON files are supported.`
+    );
+  }
+
+  const normalized = normalizePath(path.posix.join(baseDirectory, reference));
+  if (
+    !normalized ||
+    normalized === "." ||
+    normalized.startsWith("../") ||
+    normalized.includes("/../")
+  ) {
+    throw new Error(`Invalid $ref "${reference}".`);
+  }
+  return normalized;
+};
+
+const resolveJsonRefs = async (
+  source: ContentSource,
+  value: unknown,
+  baseDirectory: string,
+  seen: Set<string>
+): Promise<unknown> => {
+  if (Array.isArray(value)) {
+    return await Promise.all(
+      value.map((item) => resolveJsonRefs(source, item, baseDirectory, seen))
+    );
+  }
+
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+
+  const record = value as Record<string, unknown>;
+  const reference = record.$ref;
+  if (typeof reference === "string") {
+    const resolvedPath = normalizeRefPath(baseDirectory, reference);
+    if (seen.has(resolvedPath)) {
+      throw new Error(`Circular $ref detected for "${resolvedPath}".`);
+    }
+
+    const nextSeen = new Set(seen);
+    // oxlint-disable-next-line eslint-plugin-unicorn/no-immediate-mutation
+    nextSeen.add(resolvedPath);
+    const referenced = await readJsonConfig(source, resolvedPath);
+    const referencedValue = await resolveJsonRefs(
+      source,
+      referenced,
+      path.posix.dirname(resolvedPath) === "."
+        ? ""
+        : normalizePath(path.posix.dirname(resolvedPath)),
+      nextSeen
+    );
+
+    const siblingEntries = Object.entries(record).filter(
+      ([key]) => key !== "$ref"
+    );
+    if (
+      !siblingEntries.length ||
+      !referencedValue ||
+      typeof referencedValue !== "object" ||
+      Array.isArray(referencedValue)
+    ) {
+      return referencedValue;
+    }
+
+    const siblingValue = await resolveJsonRefs(
+      source,
+      Object.fromEntries(siblingEntries),
+      baseDirectory,
+      seen
+    );
+    return {
+      ...(referencedValue as Record<string, unknown>),
+      ...(siblingValue as Record<string, unknown>),
+    };
+  }
+
+  const resolvedEntries = await Promise.all(
+    Object.entries(record).map(async ([key, entryValue]) => [
+      key,
+      await resolveJsonRefs(source, entryValue, baseDirectory, seen),
+    ])
+  );
+  return Object.fromEntries(resolvedEntries);
+};
+
+const readResolvedJsonConfig = async (
+  source: ContentSource,
+  relativePath: string
+) =>
+  await resolveJsonRefs(
+    source,
+    await readJsonConfig(source, relativePath),
+    path.posix.dirname(relativePath) === "."
+      ? ""
+      : normalizePath(path.posix.dirname(relativePath)),
+    new Set([relativePath])
+  );
+
+const loadDocsConfig = async (
+  source: ContentSource
+): Promise<SiteConfigResult | null> => {
+  if (!(await source.exists(DOCS_CONFIG_FILE))) {
+    return null;
+  }
+
+  try {
+    const parsed = await readResolvedJsonConfig(source, DOCS_CONFIG_FILE);
+
+    // Try SiteConfig format first (has collections, theme, colors, etc.)
+    const siteResult = validateSiteConfig(parsed);
+    if (siteResult.success) {
+      return {
+        config: siteResult.data,
+        ok: true,
+        warnings: getProjectWarnings(siteResult.data),
+      };
+    }
+
+    // Fall back to DocsConfig format (Mintlify-compatible) and map to SiteConfig
+    const docsResult = validateDocsConfig(parsed);
+    if (docsResult.success) {
+      return {
+        config: mapDocsConfig(docsResult.data),
+        ok: true,
+        warnings: getProjectWarnings(docsResult.data),
+      };
+    }
+
+    return { errors: docsResult.errors, ok: false };
+  } catch (error) {
+    return {
+      errors: [
+        error instanceof Error
+          ? error.message
+          : `Failed to load ${DOCS_CONFIG_FILE}`,
+      ],
+      ok: false,
+    };
+  }
+};
+
+export const loadSiteConfig = async (
+  source: ContentSource
+): Promise<SiteConfigResult> => {
+  const docsConfig = await loadDocsConfig(source);
+  if (docsConfig) {
+    return docsConfig;
+  }
+
+  return {
+    errors: [`${DOCS_CONFIG_FILE} not found.`],
+    ok: false,
+  };
+};
+
+export const getDocsCollection = (config: SiteConfig) =>
+  config.collections.find((collection) => collection.type === "docs");
+
+export const getDocsNavigation = (config: SiteConfig) =>
+  getDocsCollection(config)?.navigation ?? config.navigation;
+
+export const getDocsCollectionWithNavigation = (
+  config: SiteConfig
+): SiteConfig["collections"][number] | undefined => {
+  const docsCollection = getDocsCollection(config);
+  const docsNavigation = getDocsNavigation(config);
+
+  return docsCollection &&
+    docsNavigation &&
+    docsCollection.navigation !== docsNavigation
+    ? { ...docsCollection, navigation: docsNavigation }
+    : docsCollection;
+};

package/packages/@repo/previewing/src/constants.ts

@@ -0,0 +1,16 @@
+export const PREBUILT_INDEX_PATH = "_content-index.json";
+export const PREBUILT_OPENAPI_INDEX_PATH = "_openapi-index.json";
+export const PREBUILT_SEARCH_INDEX_PATH = "_search-index.json";
+export const PREBUILT_TOC_INDEX_PATH = "_toc-index.json";
+export const PREBUILT_UTILITY_INDEX_PATH = "_utility-index.json";
+export const PREBUILT_UTILITY_SITEMAP_PATH = "_utility/sitemap.xml";
+export const PREBUILT_UTILITY_LLMS_PATH = "_utility/llms.txt";
+export const PREBUILT_UTILITY_LLMS_FULL_PATH = "_utility/llms-full.txt";
+export const PREBUILT_UTILITY_LLMS_SEGMENT_PREFIX = "_utility/llms/";
+export const PREBUILT_UTILITY_SKILLS_INDEX_PATH = "_utility/skills-index.json";
+export const PREBUILT_UTILITY_SKILLS_MD_PREFIX = "_utility/skills/";
+export const UTILITY_DOCS_ROOT_TOKEN = "__BLODEMD_DOCS_ROOT__";
+export const LEGACY_PROJECT_NAME_FALLBACK_WARNING =
+  "docs.json.slug is recommended. Falling back to docs.json.name as the deployment slug is deprecated.";
+
+export const NEWLINE_REGEX = /\r?\n/;

package/packages/@repo/previewing/src/content-index.ts

@@ -0,0 +1,384 @@
+import path from "node:path";
+
+import { normalizePath } from "@repo/common";
+import type {
+  CollectionConfig,
+  ContentType,
+  FrontmatterByType,
+  PageMode,
+  SiteConfig,
+} from "@repo/models";
+import { PageModeSchema } from "@repo/models";
+import { validateFrontmatter } from "@repo/validation";
+
+import type { ContentSource } from "./content-source.js";
+import { parseFrontmatter } from "./markdown/format.js";
+import type { ContentEntry, ContentIndex, PageMetadata } from "./types.js";
+
+const validModes = new Set<string>(PageModeSchema.options);
+
+export const buildPageMetadataMap = (
+  index: ContentIndex
+): Map<string, PageMetadata> => {
+  const map = new Map<string, PageMetadata>();
+  for (const entry of index.entries) {
+    if (entry.kind !== "entry") {
+      continue;
+    }
+    const fm = entry.frontmatter as Record<string, unknown>;
+    const meta: PageMetadata = {
+      title: entry.title,
+    };
+    if (typeof fm.sidebarTitle === "string") {
+      meta.sidebarTitle = fm.sidebarTitle;
+    }
+    if (typeof fm.icon === "string") {
+      meta.icon = fm.icon;
+    }
+    if (typeof fm.iconType === "string") {
+      meta.iconType = fm.iconType;
+    }
+    if (typeof fm.tag === "string") {
+      meta.tag = fm.tag;
+    }
+    if (typeof fm.hidden === "boolean") {
+      meta.hidden = fm.hidden;
+    }
+    if (typeof fm.deprecated === "boolean") {
+      meta.deprecated = fm.deprecated;
+    }
+    if (typeof fm.url === "string") {
+      meta.url = fm.url;
+    }
+    if (typeof fm.mode === "string" && validModes.has(fm.mode)) {
+      meta.mode = fm.mode as PageMode;
+    }
+    if (typeof fm.noindex === "boolean") {
+      meta.noindex = fm.noindex;
+    }
+    if (typeof fm.hideFooterPagination === "boolean") {
+      meta.hideFooterPagination = fm.hideFooterPagination;
+    }
+    if (typeof fm.hideApiMarker === "boolean") {
+      meta.hideApiMarker = fm.hideApiMarker;
+    }
+    if (Array.isArray(fm.keywords)) {
+      meta.keywords = fm.keywords as string[];
+    }
+    map.set(entry.slug, meta);
+  }
+  return map;
+};
+
+const DOC_FILE_EXTENSION_REGEX = /\.(mdx|md)$/;
+const INDEX_SUFFIX = "/index";
+
+const titleFromSlug = (slug: string) => {
+  const clean = slug.replaceAll("-", " ").split("/").pop() ?? slug;
+  if (clean === "index") {
+    return "Overview";
+  }
+  return clean.replaceAll(/\b\w/g, (char) => char.toUpperCase());
+};
+
+const slugFromFile = (relativePath: string) => {
+  const clean = normalizePath(relativePath);
+  const withoutExt = clean.replace(DOC_FILE_EXTENSION_REGEX, "");
+  if (withoutExt.endsWith(INDEX_SUFFIX)) {
+    const trimmed = withoutExt.slice(0, -INDEX_SUFFIX.length);
+    return trimmed.length ? trimmed : "index";
+  }
+  return withoutExt.length ? withoutExt : "index";
+};
+
+const listContentFiles = async (source: ContentSource, directory: string) => {
+  const files = await source.listFiles(directory);
+  return files.filter((file: string) => DOC_FILE_EXTENSION_REGEX.test(file));
+};
+
+const sortDefaults: Record<
+  ContentType,
+  { field: "date" | "order" | "title" | "price"; direction: "asc" | "desc" }
+> = {
+  blog: { direction: "desc", field: "date" },
+  courses: { direction: "asc", field: "order" },
+  docs: { direction: "asc", field: "title" },
+  forms: { direction: "asc", field: "title" },
+  notes: { direction: "desc", field: "date" },
+  products: { direction: "asc", field: "title" },
+  sheets: { direction: "asc", field: "title" },
+  site: { direction: "asc", field: "title" },
+  slides: { direction: "asc", field: "title" },
+  todos: { direction: "desc", field: "date" },
+};
+
+const normalizeSortValue = (value: unknown) => {
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "string") {
+    const timestamp = Date.parse(value);
+    if (!Number.isNaN(timestamp)) {
+      return timestamp;
+    }
+    return value.toLowerCase();
+  }
+  return null;
+};
+
+const compareValues = (a: unknown, b: unknown, direction: "asc" | "desc") => {
+  const left = normalizeSortValue(a);
+  const right = normalizeSortValue(b);
+  if (left === null && right === null) {
+    return 0;
+  }
+  if (left === null) {
+    return 1;
+  }
+  if (right === null) {
+    return -1;
+  }
+  const multiplier = direction === "desc" ? -1 : 1;
+  if (typeof left === "number" && typeof right === "number") {
+    return (left - right) * multiplier;
+  }
+  if (left < right) {
+    return -1 * multiplier;
+  }
+  if (left > right) {
+    return 1 * multiplier;
+  }
+  return 0;
+};
+
+const autoIndexTypes = new Set<ContentType>([
+  "blog",
+  "courses",
+  "products",
+  "notes",
+  "forms",
+  "sheets",
+  "slides",
+  "todos",
+]);
+
+const getCollectionIndex = (
+  collection: CollectionConfig,
+  slugPrefix: string
+) => {
+  if (collection.index) {
+    return collection.index;
+  }
+  if (autoIndexTypes.has(collection.type)) {
+    const slug = slugPrefix || collection.id;
+    return {
+      slug,
+      title: titleFromSlug(slug),
+    };
+  }
+  return null;
+};
+
+const addEntry = (
+  entry: ContentEntry,
+  index: ContentIndex,
+  errors: string[]
+) => {
+  if (index.bySlug.has(entry.slug)) {
+    errors.push(`slug "${entry.slug}" is defined more than once`);
+    return;
+  }
+  index.entries.push(entry);
+  index.bySlug.set(entry.slug, entry);
+};
+
+const resolveEntrySlug = (relativeSlug: string, slugPrefix: string) => {
+  if (!slugPrefix) {
+    return relativeSlug;
+  }
+
+  if (relativeSlug === "index") {
+    return slugPrefix;
+  }
+
+  return normalizePath(`${slugPrefix}/${relativeSlug}`);
+};
+
+const buildEntryFromFile = async ({
+  collection,
+  errors,
+  file,
+  root,
+  slugPrefix,
+  source,
+}: {
+  collection: CollectionConfig;
+  errors: string[];
+  file: string;
+  root: string;
+  slugPrefix: string;
+  source: ContentSource;
+}): Promise<Extract<ContentEntry, { kind: "entry" }> | null> => {
+  const sourcePath = root
+    ? normalizePath(path.join(root, file))
+    : normalizePath(file);
+
+  let entrySource = "";
+  try {
+    entrySource = await source.readFile(sourcePath);
+  } catch (error) {
+    errors.push(
+      error instanceof Error ? error.message : `Failed to read ${sourcePath}`
+    );
+    return null;
+  }
+
+  const { frontmatter } = parseFrontmatter(entrySource);
+  const frontmatterResult = validateFrontmatter(collection.type, frontmatter);
+  if (!frontmatterResult.success) {
+    for (const issue of frontmatterResult.errors) {
+      errors.push(`${sourcePath}: ${issue}`);
+    }
+  }
+
+  const resolvedFrontmatter = frontmatterResult.success
+    ? frontmatterResult.data
+    : (frontmatter as FrontmatterByType[ContentType]);
+  const relativeSlug = slugFromFile(file);
+  const slug = resolveEntrySlug(relativeSlug, slugPrefix);
+  const title =
+    typeof resolvedFrontmatter?.title === "string"
+      ? resolvedFrontmatter.title
+      : titleFromSlug(slug);
+  const description =
+    typeof resolvedFrontmatter?.description === "string"
+      ? resolvedFrontmatter.description
+      : undefined;
+
+  const hidden =
+    typeof resolvedFrontmatter?.hidden === "boolean"
+      ? resolvedFrontmatter.hidden
+      : undefined;
+
+  return {
+    collectionId: collection.id,
+    description,
+    frontmatter: resolvedFrontmatter,
+    hidden: hidden || undefined,
+    kind: "entry",
+    relativePath: sourcePath,
+    slug,
+    sourcePath,
+    title,
+    type: collection.type,
+  };
+};
+
+export const buildContentIndex = async (
+  source: ContentSource,
+  config: SiteConfig
+): Promise<ContentIndex> => {
+  const errors: string[] = [];
+  const index: ContentIndex = {
+    byCollection: new Map<string, ContentEntry[]>(),
+    bySlug: new Map<string, ContentEntry>(),
+    entries: [],
+    errors,
+  };
+
+  for (const collection of config.collections) {
+    const root = normalizePath(collection.root ?? "");
+    const slugPrefix = normalizePath(collection.slugPrefix ?? "");
+    let files: string[] = [];
+    try {
+      files = await listContentFiles(source, root);
+    } catch (error) {
+      errors.push(
+        error instanceof Error ? error.message : `Failed to read ${root || "."}`
+      );
+      continue;
+    }
+
+    const collectionEntries: ContentEntry[] = [];
+
+    const resolvedEntries = await Promise.all(
+      files.map(
+        async (file) =>
+          await buildEntryFromFile({
+            collection,
+            errors,
+            file,
+            root,
+            slugPrefix,
+            source,
+          })
+      )
+    );
+
+    for (const entry of resolvedEntries) {
+      if (!entry) {
+        continue;
+      }
+
+      collectionEntries.push(entry);
+      addEntry(entry, index, errors);
+    }
+
+    const sortConfig = {
+      ...sortDefaults[collection.type],
+      ...collection.sort,
+    };
+    const sortField = sortConfig.field ?? "title";
+    const sortDirection = sortConfig.direction ?? "asc";
+    collectionEntries.sort((left, right) => {
+      const leftValue =
+        left.kind === "entry"
+          ? (left.frontmatter as Record<string, unknown>)[sortField]
+          : undefined;
+      const rightValue =
+        right.kind === "entry"
+          ? (right.frontmatter as Record<string, unknown>)[sortField]
+          : undefined;
+      return compareValues(leftValue, rightValue, sortDirection);
+    });
+
+    index.byCollection.set(collection.id, collectionEntries);
+
+    const collectionIndex = getCollectionIndex(collection, slugPrefix);
+    if (collectionIndex) {
+      const indexEntry: ContentEntry = {
+        collectionId: collection.id,
+        description: collectionIndex.description,
+        kind: "index",
+        slug: collectionIndex.slug,
+        title: collectionIndex.title ?? titleFromSlug(collectionIndex.slug),
+        type: collection.type,
+      };
+      addEntry(indexEntry, index, errors);
+    }
+  }
+
+  return index;
+};
+
+export const shouldIncludeSearchEntry = (
+  entry: ContentEntry,
+  pageMetadataMap: Map<string, PageMetadata>,
+  config: SiteConfig
+) => {
+  const pageMeta = pageMetadataMap.get(entry.slug);
+
+  if (pageMeta?.hidden || pageMeta?.noindex) {
+    return false;
+  }
+
+  if (
+    config.seo?.indexing !== "all" &&
+    entry.kind === "entry" &&
+    entry.hidden === true
+  ) {
+    return false;
+  }
+
+  return true;
+};