blume 0.5.2 → 0.5.4

package/src/migrate/starlight/config.ts

@@ -1,455 +0,0 @@
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-
-import { join } from "pathe";
-
-import type { BlumeConfig, SidebarItemConfig } from "../../core/schema.ts";
-import type { LiteralValue } from "../shared.ts";
-import {
-  asLiteralArray as asArray,
-  asLiteralString as asString,
-  isLiteralObject as isObject,
-  parseLiteral,
-  scanObject,
-  stripJsComments,
-} from "../shared.ts";
-
-/**
- * Translate a Starlight `astro.config.*` into a `BlumeConfig`. The
- * `starlight({...})` options object is read statically out of the source text —
- * never executed — mirroring the Nextra `_meta` reader. Values that aren't pure
- * literals are skipped and reported, so a config that references imported assets
- * or plugins still yields a usable result instead of failing wholesale.
- */
-
-const CONFIG_FILES = [
-  "astro.config.mjs",
-  "astro.config.mts",
-  "astro.config.ts",
-  "astro.config.js",
-  "astro.config.cjs",
-];
-
-const STARLIGHT_IMPORT =
-  /import\s+(?<name>\w+)\s+from\s+["']@astrojs\/starlight["']/u;
-
-type StarlightOptions = Record<string, LiteralValue>;
-
-/** Extract the object literal passed to `starlight(…)` from config source. */
-const extractStarlightOptions = (
-  source: string
-): StarlightOptions | "unparseable" | "missing" => {
-  const clean = stripJsComments(source);
-  const importName = STARLIGHT_IMPORT.exec(clean)?.groups?.name ?? "starlight";
-  const call = new RegExp(`\\b${importName}\\s*\\(`, "u").exec(clean);
-  if (!call) {
-    return "missing";
-  }
-  let index = call.index + call[0].length;
-  while (index < clean.length && /\s/u.test(clean[index] ?? "")) {
-    index += 1;
-  }
-  if (clean[index] !== "{") {
-    // `starlight()` with no/non-literal options — nothing to translate.
-    return clean[index] === ")" ? {} : "unparseable";
-  }
-  const scan = scanObject(clean, index);
-  if (!scan) {
-    return "unparseable";
-  }
-  const parsed = parseLiteral(clean.slice(index, scan.end + 1));
-  return isObject(parsed) ? parsed : "unparseable";
-};
-
-export interface LoadedStarlightConfig {
-  options: StarlightOptions;
-  warnings: string[];
-}
-
-/** Locate and read the Starlight options out of the project's astro config. */
-export const loadStarlightConfig = async (
-  root: string
-): Promise<LoadedStarlightConfig> => {
-  const file = CONFIG_FILES.map((name) => join(root, name)).find((path) =>
-    existsSync(path)
-  );
-  if (!file) {
-    return {
-      options: {},
-      warnings: [
-        "No astro.config.* found; wrote a default config — port your Starlight options by hand.",
-      ],
-    };
-  }
-
-  const source = await readFile(file, "utf-8");
-  const result = extractStarlightOptions(source);
-  if (result === "missing") {
-    return {
-      options: {},
-      warnings: [
-        "Could not find a starlight() call in astro.config.*; port your options by hand.",
-      ],
-    };
-  }
-  if (result === "unparseable") {
-    return {
-      options: {},
-      warnings: [
-        "Could not statically read the starlight() options; port your config by hand.",
-      ],
-    };
-  }
-  return { options: result, warnings: [] };
-};
-
-// ---------------------------------------------------------------------------
-// Field mappers
-// ---------------------------------------------------------------------------
-
-type LogoConfig = string | { alt?: string; dark?: string; light?: string };
-
-const mapLogo = (
-  value: LiteralValue | undefined,
-  warnings: string[]
-): LogoConfig | undefined => {
-  const logo = isObject(value) ? value : undefined;
-  if (!logo) {
-    return undefined;
-  }
-  const alt = asString(logo.alt);
-  const src = asString(logo.src);
-  const light = asString(logo.light);
-  const dark = asString(logo.dark);
-
-  let result: LogoConfig | undefined;
-  if (src) {
-    result = alt ? { alt, dark: src, light: src } : src;
-  } else if (light || dark) {
-    result = {
-      ...(alt ? { alt } : {}),
-      ...(dark ? { dark } : {}),
-      ...(light ? { light } : {}),
-    };
-  }
-  if (result) {
-    warnings.push(
-      "Mapped the Starlight logo; move the referenced file under public/ (Blume serves static assets from there)."
-    );
-  }
-  return result;
-};
-
-const GITHUB_REPO = /github\.com\/(?<owner>[^/]+)\/(?<repo>[^/?#]+)/u;
-const EDIT_LINK =
-  /github\.com\/(?<owner>[^/]+)\/(?<repo>[^/]+)\/edit\/(?<branch>[^/?#]+)/u;
-
-interface GithubConfig {
-  branch?: string;
-  owner: string;
-  repo: string;
-}
-
-const githubFromUrl = (url: string): GithubConfig | undefined => {
-  const groups = GITHUB_REPO.exec(url)?.groups;
-  if (!groups?.owner || !groups.repo) {
-    return undefined;
-  }
-  return { owner: groups.owner, repo: groups.repo.replace(/\.git$/u, "") };
-};
-
-interface SocialMapping {
-  github?: GithubConfig;
-  socials: Record<string, string>;
-}
-
-/** Normalize a Starlight social icon key into a Blume `footer.socials` key. */
-const socialKey = (icon: string): string =>
-  icon.toLowerCase().replace(/\.com$/u, "");
-
-const mapSocial = (value: LiteralValue | undefined): SocialMapping => {
-  const result: SocialMapping = { socials: {} };
-  const record = (icon: string, href: string): void => {
-    const key = socialKey(icon);
-    result.socials[key] = href;
-    if (key === "github" && !result.github) {
-      result.github = githubFromUrl(href);
-    }
-  };
-
-  const array = asArray(value);
-  if (array) {
-    for (const entry of array) {
-      if (!isObject(entry)) {
-        continue;
-      }
-      const icon = asString(entry.icon);
-      const href = asString(entry.href);
-      if (icon && href) {
-        record(icon, href);
-      }
-    }
-    return result;
-  }
-  // Older Starlight: `social: { github: "https://…", discord: "https://…" }`.
-  if (isObject(value)) {
-    for (const [icon, href] of Object.entries(value)) {
-      const url = asString(href);
-      if (url) {
-        record(icon, url);
-      }
-    }
-  }
-  return result;
-};
-
-const mapEditLink = (
-  value: LiteralValue | undefined
-): GithubConfig | undefined => {
-  const editLink = isObject(value) ? value : undefined;
-  const baseUrl = asString(editLink?.baseUrl);
-  if (!baseUrl) {
-    return undefined;
-  }
-  const groups = EDIT_LINK.exec(baseUrl)?.groups;
-  if (!groups?.owner || !groups.repo || !groups.branch) {
-    return undefined;
-  }
-  return {
-    branch: groups.branch,
-    owner: groups.owner,
-    repo: groups.repo.replace(/\.git$/u, ""),
-  };
-};
-
-/** Flatten a Starlight badge (`string` or `{ text, variant }`) to a string. */
-const badgeText = (value: LiteralValue | undefined): string | undefined =>
-  asString(value) ?? asString(isObject(value) ? value.text : undefined);
-
-const mapSidebarItem = (
-  value: LiteralValue,
-  warnings: string[]
-): SidebarItemConfig | null => {
-  if (typeof value === "string") {
-    return `/${value.replace(/^\/+/u, "")}`;
-  }
-  if (!isObject(value)) {
-    return null;
-  }
-  const label = asString(value.label);
-  const badge = badgeText(value.badge);
-  const collapsed =
-    typeof value.collapsed === "boolean" ? value.collapsed : undefined;
-
-  const autogenerate = isObject(value.autogenerate)
-    ? asString(value.autogenerate.directory)
-    : undefined;
-  if (autogenerate && label) {
-    return {
-      label,
-      ...(badge ? { badge } : {}),
-      ...(collapsed === undefined ? {} : { collapsed }),
-      root: autogenerate,
-    };
-  }
-
-  const items = asArray(value.items);
-  if (items && label) {
-    const mapped = items
-      .map((item) => mapSidebarItem(item, warnings))
-      .filter((item): item is SidebarItemConfig => item !== null);
-    return {
-      ...(badge ? { badge } : {}),
-      ...(collapsed === undefined ? {} : { collapsed }),
-      items: mapped,
-      label,
-    };
-  }
-
-  const link = asString(value.link);
-  if (link) {
-    return label
-      ? { ...(badge ? { badge } : {}), href: link, label }
-      : { href: link, label: link };
-  }
-
-  const slug = asString(value.slug);
-  if (slug) {
-    const href = `/${slug.replace(/^\/+/u, "")}`;
-    return label ? { ...(badge ? { badge } : {}), href, label } : href;
-  }
-
-  warnings.push("Skipped a sidebar entry that uses an unsupported shape.");
-  return null;
-};
-
-const mapSidebar = (
-  value: LiteralValue | undefined,
-  warnings: string[]
-): SidebarItemConfig[] | undefined => {
-  const array = asArray(value);
-  if (!array) {
-    return undefined;
-  }
-  const items = array
-    .map((item) => mapSidebarItem(item, warnings))
-    .filter((item): item is SidebarItemConfig => item !== null);
-  return items.length > 0 ? items : undefined;
-};
-
-const mapCodeTheme = (
-  value: LiteralValue | undefined,
-  warnings: string[]
-): { dark: string; light: string } | undefined => {
-  const expressive = isObject(value) ? value : undefined;
-  if (value === false) {
-    warnings.push(
-      "expressiveCode is disabled in Starlight; Blume always renders code blocks."
-    );
-    return undefined;
-  }
-  if (!expressive) {
-    return undefined;
-  }
-  if (expressive.styleOverrides !== undefined) {
-    warnings.push(
-      "Dropped expressiveCode.styleOverrides; restyle code blocks via theme.css."
-    );
-  }
-  const themes = asArray(expressive.themes)?.filter(
-    (theme): theme is string => typeof theme === "string"
-  );
-  const [first, second] = themes ?? [];
-  if (!first) {
-    return undefined;
-  }
-  const dark = themes?.find((theme) => /dark/u.test(theme)) ?? first;
-  const light =
-    themes?.find((theme) => /light/u.test(theme)) ?? second ?? first;
-  return { dark, light };
-};
-
-const mapHead = (
-  value: LiteralValue | undefined,
-  warnings: string[]
-): Record<string, string> | undefined => {
-  const array = asArray(value);
-  if (!array) {
-    return undefined;
-  }
-  const metatags: Record<string, string> = {};
-  for (const entry of array) {
-    if (!isObject(entry)) {
-      continue;
-    }
-    const tag = asString(entry.tag);
-    const attrs = isObject(entry.attrs) ? entry.attrs : undefined;
-    const content = asString(attrs?.content);
-    const key = asString(attrs?.name) ?? asString(attrs?.property);
-    if (tag === "meta" && key && content) {
-      metatags[key] = content;
-    } else {
-      warnings.push(
-        `Dropped a <${tag ?? "?"}> head entry; re-add scripts/links via a custom layout.`
-      );
-    }
-  }
-  return Object.keys(metatags).length > 0 ? metatags : undefined;
-};
-
-/** Warn about Starlight options that carry over to Blume only by hand. */
-const warnDroppedOptions = (
-  options: StarlightOptions,
-  warnings: string[]
-): void => {
-  if (options.customCss !== undefined) {
-    warnings.push(
-      "Dropped customCss; move your custom styles into a top-level theme.css."
-    );
-  }
-  if (isObject(options.components)) {
-    warnings.push(
-      "Dropped Starlight component overrides; re-implement them via `blume eject`."
-    );
-  }
-  if (asArray(options.plugins)?.length) {
-    warnings.push(
-      "Dropped Starlight plugins; they have no Blume equivalent and need manual review."
-    );
-  }
-  if (options.routeMiddleware !== undefined) {
-    warnings.push(
-      "Dropped routeMiddleware; re-implement any route data in Blume directly."
-    );
-  }
-};
-
-/**
- * Map the statically-read Starlight options onto a `BlumeConfig`. Content stays
- * under `src/content/docs`, so the content root is pinned there. Unsupported or
- * non-literal options are dropped with a warning rather than failing.
- */
-export const mapStarlightConfig = (
-  options: StarlightOptions,
-  warnings: string[]
-): BlumeConfig => {
-  const config: BlumeConfig = {
-    content: { root: "src/content/docs" },
-    title: asString(options.title) ?? "Documentation",
-  };
-  if (options.title !== undefined && asString(options.title) === undefined) {
-    warnings.push(
-      "Starlight title is per-locale or computed; set config.title manually."
-    );
-  }
-
-  const description =
-    asString(options.description) ?? asString(options.tagline);
-  if (description) {
-    config.description = description;
-  }
-
-  const logo = mapLogo(options.logo, warnings);
-  if (logo) {
-    config.logo = logo;
-  }
-
-  const favicon = asString(options.favicon);
-  if (favicon) {
-    config.favicon = favicon;
-    if (!favicon.startsWith("/") && !/^https?:/u.test(favicon)) {
-      warnings.push(
-        `favicon "${favicon}" should live under public/ and be referenced from the site root.`
-      );
-    }
-  }
-
-  const social = mapSocial(options.social);
-  const github = mapEditLink(options.editLink) ?? social.github;
-  if (github) {
-    config.github = github;
-  }
-
-  const sidebar = mapSidebar(options.sidebar, warnings);
-  if (sidebar) {
-    config.navigation = { sidebar };
-  }
-
-  const theme = mapCodeTheme(options.expressiveCode, warnings);
-  if (theme) {
-    config.markdown = { codeBlocks: { theme } };
-  }
-
-  const metatags = mapHead(options.head, warnings);
-  if (metatags) {
-    config.seo = { metatags };
-  }
-
-  if (options.lastUpdated === true) {
-    config.lastModified = true;
-  }
-
-  warnDroppedOptions(options, warnings);
-
-  return config;
-};

package/src/migrate/starlight/content.ts

@@ -1,78 +0,0 @@
-import { renameTag, rewriteCallouts } from "../shared.ts";
-
-/**
- * Source-to-source rewrites that turn Starlight-only MDX into idiomatic Blume
- * markup. Runs once at migration time — no Starlight-aware plugins remain in the
- * Blume runtime.
- */
-
-const STARLIGHT_IMPORT =
-  /^import\s+[\s\S]*?\s+from\s+["']@astrojs\/starlight(?:\/[^"']*)?["'];?[ \t]*\n?/gmu;
-
-/**
- * Drop `import … from "@astrojs/starlight/components"` (and other subpaths).
- * Blume injects its components globally, so these imports would fail to resolve
- * once the Starlight packages are gone.
- */
-export const stripStarlightImports = (source: string): string => {
-  const stripped = source.replace(STARLIGHT_IMPORT, "");
-  // Collapse the blank gap a removed import block leaves behind.
-  return stripped === source ? source : stripped.replaceAll(/\n{3,}/gu, "\n\n");
-};
-
-/** Starlight `<Aside type="X">` values mapped to Blume directive names. */
-const ASIDE_TYPE_DIRECTIVES: Record<string, string> = {
-  caution: "caution",
-  danger: "danger",
-  note: "note",
-  tip: "tip",
-};
-
-/**
- * Convert Starlight `<Aside type="note|tip|caution|danger" title="…">`
- * components into Blume `:::` directives. A bare `<Aside>` becomes `:::note`.
- * (Plain `:::`-syntax asides already pass through unchanged — Blume's directive
- * set covers all four types, with `caution` aliased to `warning`.)
- */
-export const rewriteStarlightAsides = (source: string): string =>
-  rewriteCallouts(source, {
-    defaultDirective: "note",
-    tagDirectives: {},
-    tags: ["Aside"],
-    typeDirectives: ASIDE_TYPE_DIRECTIVES,
-  });
-
-/**
- * Rename Starlight container components to their Blume equivalents, then move
- * each `<Tab>`'s `label` onto the `title` prop Blume reads. `LinkCard` folds into
- * `Card` (which renders an `href`); its `description` has no Card prop and is
- * dropped. `CardGrid`'s `stagger` layout flag has no equivalent and is left on
- * the tag harmlessly (Blume ignores unknown attributes).
- */
-export const rewriteStarlightComponents = (source: string): string => {
-  let out = renameTag(source, "CardGrid", "CardGroup");
-  out = renameTag(out, "LinkCard", "Card");
-  out = renameTag(out, "TabItem", "Tab");
-  // Starlight selects a tab label with `label=`; Blume's `<Tab>` uses `title=`.
-  out = out.replaceAll(
-    /(?<tab><Tab\b[^>]*?)\blabel(?<eq>\s*=)/gu,
-    "$<tab>title$<eq>"
-  );
-  return out;
-};
-
-/** Starlight components with no drop-in Blume equivalent — flagged for review. */
-const UNSUPPORTED_COMPONENTS = ["Code", "FileTree", "LinkButton", "Steps"];
-
-/** Names of Starlight components in `source` that need manual attention. */
-export const unsupportedStarlightComponents = (source: string): string[] =>
-  UNSUPPORTED_COMPONENTS.filter((name) =>
-    new RegExp(`<${name}\\b`, "u").test(source)
-  );
-
-const ASSET_ALIAS =
-  /(?:!\[[^\]]*\]\(|\bsrc\s*=\s*["'])(?<path>[~@]\/[^"')\s]+)/u;
-
-/** True when the source references images via Starlight's `~/`/`@/` aliases. */
-export const hasAliasedAssets = (source: string): boolean =>
-  ASSET_ALIAS.test(source);

package/src/migrate/starlight/frontmatter.ts

@@ -1,111 +0,0 @@
-import { z } from "zod";
-
-import { stripUnknownPageMeta } from "../shared.ts";
-
-/**
- * One-time translation of Starlight page frontmatter into Blume's shape. Runs at
- * migration time only — Blume's runtime page schema stays Starlight-free and
- * strict. `sidebar.badge` flattens to a string, `pagefind:false` becomes
- * `search.exclude`, `lastUpdated` (a date) becomes `lastModified`, and
- * `prev`/`next:false` become `hideFooterPagination`. Starlight-only keys
- * (`template`, `hero`, `banner`, `tableOfContents`, `editUrl`, `head`) are then
- * dropped by the strict-schema pass and reported.
- */
-
-const starlightBadgeSchema = z.union([
-  z.string(),
-  z.object({ text: z.string() }).passthrough(),
-]);
-
-const starlightSidebarSchema = z
-  .object({
-    badge: starlightBadgeSchema.optional(),
-    hidden: z.boolean().optional(),
-    label: z.string().optional(),
-    order: z.number().optional(),
-  })
-  .passthrough();
-
-const starlightPageMetaInputSchema = z
-  .object({
-    lastUpdated: z.union([z.date(), z.string(), z.boolean()]).optional(),
-    next: z.unknown().optional(),
-    pagefind: z.boolean().optional(),
-    prev: z.unknown().optional(),
-    sidebar: starlightSidebarSchema.optional(),
-  })
-  .passthrough();
-
-type StarlightPageMeta = z.infer<typeof starlightPageMetaInputSchema>;
-
-const normalizedSidebar = (
-  sidebar: NonNullable<StarlightPageMeta["sidebar"]>
-): Record<string, unknown> => {
-  const out: Record<string, unknown> = {};
-  if (sidebar.label !== undefined) {
-    out.label = sidebar.label;
-  }
-  if (sidebar.order !== undefined) {
-    out.order = sidebar.order;
-  }
-  if (sidebar.hidden !== undefined) {
-    out.hidden = sidebar.hidden;
-  }
-  const badge =
-    typeof sidebar.badge === "string" ? sidebar.badge : sidebar.badge?.text;
-  if (badge !== undefined) {
-    out.badge = badge;
-  }
-  return out;
-};
-
-/**
- * Map Starlight page frontmatter onto Blume's frontmatter shape, returning the
- * cleaned data plus any unknown keys dropped to satisfy the strict page schema.
- */
-export const normalizeStarlightPageMeta = (
-  value: unknown
-): { data: Record<string, unknown>; removed: string[] } => {
-  const parsed = starlightPageMetaInputSchema.safeParse(value);
-  if (!parsed.success || typeof value !== "object" || value === null) {
-    return stripUnknownPageMeta((value ?? {}) as Record<string, unknown>);
-  }
-
-  const meta = parsed.data;
-  const data: Record<string, unknown> = {
-    ...(value as Record<string, unknown>),
-  };
-
-  if (meta.sidebar) {
-    const sidebar = normalizedSidebar(meta.sidebar);
-    if (Object.keys(sidebar).length > 0) {
-      data.sidebar = sidebar;
-    } else {
-      delete data.sidebar;
-    }
-  }
-
-  if (meta.pagefind === false) {
-    const existing =
-      typeof data.search === "object" && data.search !== null
-        ? (data.search as Record<string, unknown>)
-        : {};
-    data.search = { ...existing, exclude: true };
-  }
-  delete data.pagefind;
-
-  if (meta.lastUpdated instanceof Date) {
-    data.lastModified = meta.lastUpdated.toISOString();
-  } else if (typeof meta.lastUpdated === "string") {
-    data.lastModified = meta.lastUpdated;
-  }
-  delete data.lastUpdated;
-
-  if (meta.prev === false || meta.next === false) {
-    data.hideFooterPagination = true;
-  }
-  delete data.prev;
-  delete data.next;
-
-  return stripUnknownPageMeta(data);
-};

package/src/migrate/starlight/i18n.ts

@@ -1,54 +0,0 @@
-import type { BlumeConfig } from "../../core/schema.ts";
-import type { LiteralValue } from "../shared.ts";
-import { asLiteralString, isLiteralObject } from "../shared.ts";
-
-/**
- * Map Starlight's `defaultLocale` + `locales` onto Blume's `i18n` config.
- * Starlight keys locales by URL segment (`root` for the un-prefixed default) and
- * carries the BCP-47 tag in `lang`; Blume keys by `code`. The `root` locale maps
- * to the default with `hideDefaultLocalePrefix`, and locale directories under
- * `src/content/docs` line up with Blume's `"dir"` parser.
- */
-
-type I18nConfig = NonNullable<BlumeConfig["i18n"]>;
-
-export const starlightI18n = (
-  options: Record<string, LiteralValue>
-): I18nConfig | undefined => {
-  const locales = isLiteralObject(options.locales)
-    ? options.locales
-    : undefined;
-  if (!locales) {
-    return undefined;
-  }
-
-  const entries: { code: string; label: string }[] = [];
-  let rootCode: string | undefined;
-  for (const [key, value] of Object.entries(locales)) {
-    const entry = isLiteralObject(value) ? value : undefined;
-    const lang = asLiteralString(entry?.lang);
-    const label = asLiteralString(entry?.label) ?? key;
-    const code = key === "root" ? (lang ?? "en") : (lang ?? key);
-    if (key === "root") {
-      rootCode = code;
-    }
-    entries.push({ code, label });
-  }
-  if (entries.length === 0) {
-    return undefined;
-  }
-
-  const requested = asLiteralString(options.defaultLocale);
-  const fallback = rootCode ?? entries[0]?.code ?? "en";
-  const preferred =
-    requested === undefined || requested === "root" ? fallback : requested;
-  const codes = new Set(entries.map((locale) => locale.code));
-  const defaultLocale = codes.has(preferred) ? preferred : fallback;
-
-  return {
-    defaultLocale,
-    hideDefaultLocalePrefix: true,
-    locales: entries,
-    parser: "dir",
-  };
-};