blume 0.0.0 → 0.1.0

package/src/components/layout/toc-element.ts

@@ -0,0 +1,108 @@
+/**
+ * Client behaviour for the `<blume-toc>` custom element wrapping each "On this
+ * page" list. As the reader scrolls, it marks the link for the section currently
+ * in view with `aria-current="location"` — styled via Tailwind `aria-[current]`
+ * variants in RootLayout — giving the table of contents a live scrollspy.
+ *
+ * The active heading is chosen by rect (the last heading at or above a trigger
+ * line just below the sticky header), so it stays correct for sections taller
+ * than the viewport and at the bottom of the page. An IntersectionObserver is the
+ * cheap primary trigger — it only fires as headings cross the band near the top —
+ * and a passive, rAF-throttled scroll listener covers the one case it can't: a
+ * final section too short to push its heading past the trigger line.
+ *
+ * Imported for its side effect (registers the element) from RootLayout's script.
+ */
+
+interface TocEntry {
+  heading: HTMLElement;
+  link: HTMLAnchorElement;
+}
+
+// Matches the theme's `scroll-padding-top: 4.5rem`, so the highlighted heading
+// agrees with where a clicked anchor lands beneath the sticky header.
+const TRIGGER_OFFSET = 72;
+
+class BlumeToc extends HTMLElement {
+  #entries: TocEntry[] = [];
+  #observer: IntersectionObserver | null = null;
+  #current: HTMLAnchorElement | null = null;
+  #ticking = false;
+
+  connectedCallback() {
+    for (const link of this.querySelectorAll<HTMLAnchorElement>(
+      'a[href^="#"]'
+    )) {
+      const id = decodeURIComponent(link.hash.slice(1));
+      const heading = id
+        ? document.querySelector<HTMLElement>(`#${CSS.escape(id)}`)
+        : null;
+      if (heading) {
+        this.#entries.push({ heading, link });
+      }
+    }
+    if (this.#entries.length === 0) {
+      return;
+    }
+
+    this.#observer = new IntersectionObserver(() => this.#update(), {
+      rootMargin: `-${TRIGGER_OFFSET}px 0px -70% 0px`,
+      threshold: 0,
+    });
+    for (const { heading } of this.#entries) {
+      this.#observer.observe(heading);
+    }
+    window.addEventListener("scroll", this.#onScroll, { passive: true });
+    this.#update();
+  }
+
+  disconnectedCallback() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    window.removeEventListener("scroll", this.#onScroll);
+  }
+
+  #onScroll = () => {
+    if (this.#ticking) {
+      return;
+    }
+    this.#ticking = true;
+    requestAnimationFrame(() => {
+      this.#ticking = false;
+      this.#update();
+    });
+  };
+
+  #update() {
+    const active = this.#activeLink();
+    if (active === this.#current) {
+      return;
+    }
+    this.#current?.removeAttribute("aria-current");
+    active?.setAttribute("aria-current", "location");
+    this.#current = active;
+  }
+
+  #activeLink(): HTMLAnchorElement | null {
+    const scrolledToBottom =
+      window.innerHeight + window.scrollY >=
+      document.documentElement.scrollHeight - 2;
+    if (scrolledToBottom) {
+      return this.#entries.at(-1)?.link ?? null;
+    }
+
+    // Headings are in document order, so the last one whose top has reached the
+    // trigger line is the section currently being read; default to the first.
+    let active = this.#entries[0]?.link ?? null;
+    for (const { heading, link } of this.#entries) {
+      if (heading.getBoundingClientRect().top <= TRIGGER_OFFSET) {
+        active = link;
+      }
+    }
+    return active;
+  }
+}
+
+if (!customElements.get("blume-toc")) {
+  customElements.define("blume-toc", BlumeToc);
+}

package/src/core/bridge.ts

@@ -0,0 +1,92 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+import { join } from "pathe";
+
+import { loadMintlifyConfig } from "../migrate/mintlify/config.ts";
+import { mintlifyI18n } from "../migrate/mintlify/i18n.ts";
+import type { BlumeConfig } from "./schema.ts";
+
+/** A detected docs-tool config that Blume can serve without a migration. */
+export interface BridgeDetection {
+  /** Which foreign docs tool was detected. */
+  tool: "mintlify";
+  /** Absolute path of the detected config file (`docs.json`/`mint.json`). */
+  configFile: string;
+  /** A Blume config synthesized from the foreign config, ready to validate. */
+  raw: BlumeConfig;
+}
+
+const MINTLIFY_CONFIG_FILES = ["docs.json", "mint.json"];
+
+/**
+ * Detect a Mintlify project at `root` and synthesize an equivalent Blume config.
+ *
+ * "Bridge mode" lets a team swap `mintlify dev` for `blume dev` with no file
+ * changes: `docs.json` is translated to Blume config (`loadMintlifyConfig`) and
+ * its content block is rewired to a single `mintlify` content source, which
+ * transforms each MDX page to Blume idiom at scan time. The original
+ * `content.root`/`exclude` and `variables` move onto the source (Blume has no
+ * runtime variable substitution, so globals are inlined into content there).
+ *
+ * Returns `null` when no Mintlify config is present. Only called when no
+ * `blume.config.*` exists, so an explicit Blume config always takes precedence.
+ */
+export const detectMintlifyBridge = async (
+  root: string
+): Promise<BridgeDetection | null> => {
+  const configFile = MINTLIFY_CONFIG_FILES.map((name) => join(root, name)).find(
+    (candidate) => existsSync(candidate)
+  );
+  if (!configFile) {
+    return null;
+  }
+
+  const config = await loadMintlifyConfig(root, configFile);
+
+  // i18n is derived from the raw spec (language dirs), mirroring the migrator.
+  const spec = JSON.parse(await readFile(configFile, "utf-8")) as Record<
+    string,
+    unknown
+  >;
+  const i18n = mintlifyI18n(spec);
+  if (i18n) {
+    config.i18n = i18n;
+    // Language switching is handled by Blume i18n, not a nav selector.
+    if (config.navigation?.selectors) {
+      config.navigation.selectors = config.navigation.selectors.filter(
+        (selector) => selector.kind !== "language"
+      );
+    }
+  }
+
+  const variables = (config.variables as Record<string, string>) ?? {};
+  const root_ = config.content?.root ?? ".";
+  const exclude = config.content?.exclude ?? [];
+
+  return {
+    configFile,
+    raw: {
+      ...config,
+      content: {
+        // Mirror the excludes onto `content.exclude` too: the generated Astro
+        // `docs` collection globs `content.root` (here the project root) and
+        // must skip node_modules/snippets just like the source does.
+        exclude,
+        root: root_,
+        sources: [
+          {
+            configFile,
+            exclude,
+            root: root_,
+            type: "mintlify",
+            variables,
+          },
+        ],
+      },
+      // Globals are inlined into content by the source; drop the top-level copy.
+      variables: undefined,
+    },
+    tool: "mintlify",
+  };
+};

package/src/core/config.ts

@@ -0,0 +1,112 @@
+import { detectMintlifyBridge } from "./bridge.ts";
+import type { BridgeDetection } from "./bridge.ts";
+import { applyDeploymentEnv } from "./deployment-env.ts";
+import { BlumeError, diagnosticsFromZod } from "./diagnostics.ts";
+import { createModuleLoader } from "./load-module.ts";
+import { findConfigFile } from "./project.ts";
+import { blumeConfigSchema } from "./schema.ts";
+import type { BlumeConfig, ResolvedConfig } from "./schema.ts";
+import type { Diagnostic } from "./types.ts";
+
+/**
+ * Identity helper for authoring `blume.config.ts`. Exists for type inference
+ * and a stable future home for plugin hooks; it does not transform input.
+ */
+export const defineConfig = (config: BlumeConfig): BlumeConfig => config;
+
+/** Bridge mode info: a foreign docs tool Blume is serving without migrating. */
+export interface ConfigBridge {
+  tool: "mintlify";
+  /** Absolute path of the foreign config file (`docs.json`/`mint.json`). */
+  configFile: string;
+}
+
+/** Result of loading + validating a project config. */
+export interface ConfigLoadResult {
+  config: ResolvedConfig;
+  /** Absolute path of the config file used, or null when defaults were used. */
+  configFile: string | null;
+  /** Set when a foreign docs config (e.g. Mintlify) is being bridged. */
+  bridge: ConfigBridge | null;
+  diagnostics: Diagnostic[];
+}
+
+const importConfigModule = createModuleLoader();
+
+/**
+ * Load and validate the project config. When no config file exists, schema
+ * defaults produce a fully resolved config so the zero-boilerplate path works.
+ */
+export const loadConfig = async (
+  root: string,
+  /**
+   * Supplied only by `blume dev`: the local dev server URL, used as the
+   * `deployment.site` fallback when none is configured or detected. Builds
+   * never pass it, so production output can't end up pointing at localhost.
+   */
+  options: { devServerUrl?: string } = {}
+): Promise<ConfigLoadResult> => {
+  const configFile = findConfigFile(root);
+
+  // With no Blume config, a Mintlify `docs.json` activates bridge mode: serve
+  // the unconverted project by synthesizing config + a `mintlify` content source.
+  let bridge: BridgeDetection | null = null;
+  let raw: unknown = {};
+  if (configFile) {
+    try {
+      raw = await importConfigModule(configFile);
+    } catch (error) {
+      throw new BlumeError({
+        code: "BLUME_CONFIG_LOAD_FAILED",
+        file: configFile,
+        message: `Failed to load config: ${(error as Error).message}`,
+        severity: "error",
+      });
+    }
+  } else {
+    bridge = await detectMintlifyBridge(root);
+    if (bridge) {
+      ({ raw } = bridge);
+    }
+  }
+
+  const sourceFile = bridge?.configFile ?? configFile;
+  const parsed = blumeConfigSchema.safeParse(raw ?? {});
+  if (!parsed.success) {
+    const diagnostics = diagnosticsFromZod(parsed.error, {
+      code: "BLUME_CONFIG_INVALID",
+      file: sourceFile ?? undefined,
+    });
+    throw new BlumeError(
+      diagnostics[0] ?? {
+        code: "BLUME_CONFIG_INVALID",
+        file: sourceFile ?? undefined,
+        message: "Invalid Blume config.",
+        severity: "error",
+      }
+    );
+  }
+
+  // Resolve the canonical site URL, then SEO defaults that depend on it.
+  // Precedence: explicit config > platform env (Vercel/Netlify/Cloudflare, via
+  // applyDeploymentEnv) > the local dev server URL (dev only).
+  const config = applyDeploymentEnv(parsed.data);
+  const site = config.deployment.site ?? options.devServerUrl;
+
+  // OG images need an absolute `og:image`, so they default on once a site URL
+  // is known and off otherwise. An explicit `seo.og.enabled` always wins.
+  const ogEnabled = config.seo.og.enabled ?? Boolean(site);
+
+  return {
+    bridge: bridge
+      ? { configFile: bridge.configFile, tool: bridge.tool }
+      : null,
+    config: {
+      ...config,
+      deployment: { ...config.deployment, site },
+      seo: { ...config.seo, og: { ...config.seo.og, enabled: ogEnabled } },
+    },
+    configFile: sourceFile,
+    diagnostics: [],
+  };
+};

package/src/core/content.ts

@@ -0,0 +1,50 @@
+import type { ResolvedI18nConfig } from "./schema.ts";
+import { filesystemSource } from "./sources/filesystem.ts";
+import { normalizeEntry } from "./sources/normalize.ts";
+import type { Diagnostic, PageRecord } from "./types.ts";
+
+// Re-export the shared parsing helpers from their new home so existing importers
+// (and tests) keep resolving them from `core/content.ts`.
+export {
+  extractHeadings,
+  extractLinks,
+  normalizeEntry,
+  slugify,
+} from "./sources/normalize.ts";
+
+/**
+ * Discover and normalize all content pages under a content root. Thin wrapper
+ * around the filesystem `ContentSource` + `normalizeEntry`, kept for callers and
+ * tests that scan a single directory directly.
+ */
+export const discoverContent = async (options: {
+  contentRoot: string;
+  include: string[];
+  exclude: string[];
+  defaultType: string;
+  i18n?: ResolvedI18nConfig;
+}): Promise<{ pages: PageRecord[]; diagnostics: Diagnostic[] }> => {
+  const source = filesystemSource({
+    exclude: options.exclude,
+    include: options.include,
+    name: "filesystem",
+    projectRoot: options.contentRoot,
+    root: options.contentRoot,
+  });
+
+  const { entries, diagnostics: loadDiagnostics } = await source.load();
+  const pages: PageRecord[] = [];
+  const diagnostics: Diagnostic[] = [...loadDiagnostics];
+
+  for (const entry of entries) {
+    const normalized = normalizeEntry(entry, {
+      defaultType: options.defaultType,
+      i18n: options.i18n,
+      source: { name: source.name, prefix: source.prefix, staged: false },
+    });
+    pages.push(...normalized.pages);
+    diagnostics.push(...normalized.diagnostics);
+  }
+
+  return { diagnostics, pages };
+};

package/src/core/define-components.ts

@@ -0,0 +1,34 @@
+import type { HydrationMode } from "./schema.ts";
+
+/**
+ * A reference to a component. Either an imported component (preferred, for type
+ * safety) or a string path resolved relative to the project root.
+ */
+export type ComponentReference = unknown | string;
+
+/** An interactive component plus its hydration strategy. */
+export interface IslandDescriptor {
+  component: ComponentReference;
+  client: HydrationMode;
+  /** Required when `client` is `"media"`. */
+  media?: string;
+}
+
+/** A component override: a static component or a hydrated island. */
+export type ComponentOverride = ComponentReference | IslandDescriptor;
+
+/** User-authored component overrides, grouped by surface. */
+export interface ComponentOverrides {
+  /** MDX component map overrides (`Callout`, `Card`, ...). */
+  mdx?: Record<string, ComponentOverride>;
+  /** Layout slot overrides (`Header`, `Sidebar`, `Search`, ...). */
+  layout?: Record<string, ComponentOverride>;
+}
+
+/**
+ * Identity helper for authoring `components.ts`. Provides type inference and a
+ * stable home for future normalization; it does not transform input.
+ */
+export const defineComponents = (
+  overrides: ComponentOverrides
+): ComponentOverrides => overrides;

package/src/core/define-meta.ts

@@ -0,0 +1,20 @@
+import type { FolderMeta } from "./schema.ts";
+
+/** A function that computes folder meta, optionally asynchronously. */
+export type FolderMetaFactory = () => FolderMeta | Promise<FolderMeta>;
+
+/** What a `meta.ts` may default-export: a plain object or a (async) factory. */
+export type FolderMetaDefinition = FolderMeta | FolderMetaFactory;
+
+/**
+ * Identity helper for authoring a folder's `meta.ts`. Provides type inference;
+ * it does not transform input. Pass an object, or a function (sync or async)
+ * that returns one when you need to compute the meta:
+ *
+ * ```ts
+ * export default defineMeta({ title: "Guides", order: 2 });
+ * export default defineMeta(async () => ({ pages: await orderPages() }));
+ * ```
+ */
+export const defineMeta = (meta: FolderMetaDefinition): FolderMetaDefinition =>
+  meta;

package/src/core/deployment-env.ts

@@ -0,0 +1,73 @@
+import type { ResolvedConfig } from "./schema.ts";
+
+/** The deployment platforms Blume can infer from runtime/CI env vars. */
+type DeploymentAdapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
+
+interface Platform {
+  /** Astro adapter to use when building for server output on this platform. */
+  adapter: DeploymentAdapter;
+  /** True when the env indicates the build is running on this platform. */
+  detect: (env: NodeJS.ProcessEnv) => boolean;
+  /** Resolve the canonical site URL from the platform's env vars, or null. */
+  site: (env: NodeJS.ProcessEnv) => string | null;
+}
+
+/** Prefix a bare host with `https://`; pass values that are already absolute. */
+const toUrl = (value: string | undefined): string | null => {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return null;
+  }
+  return /^https?:\/\//u.test(trimmed) ? trimmed : `https://${trimmed}`;
+};
+
+/**
+ * Platforms checked in order; the first whose `detect` matches wins. Site URLs
+ * prefer the stable production domain over per-deployment preview URLs so the
+ * inferred origin (sitemap, OG, RSS) stays put across deploys.
+ */
+const PLATFORMS: Platform[] = [
+  {
+    adapter: "vercel",
+    detect: (env) => Boolean(env.VERCEL),
+    site: (env) => toUrl(env.VERCEL_PROJECT_PRODUCTION_URL ?? env.VERCEL_URL),
+  },
+  {
+    adapter: "netlify",
+    detect: (env) => Boolean(env.NETLIFY),
+    site: (env) => toUrl(env.URL ?? env.DEPLOY_PRIME_URL ?? env.DEPLOY_URL),
+  },
+  {
+    adapter: "cloudflare",
+    detect: (env) => Boolean(env.CF_PAGES),
+    site: (env) => toUrl(env.CF_PAGES_URL),
+  },
+];
+
+/**
+ * Fill in `deployment.adapter` and `deployment.site` from platform env vars
+ * (Vercel, Netlify, Cloudflare Pages) when the user hasn't set them. Explicit
+ * config always wins, and the adapter is only inferred for server output (it
+ * has no effect on static builds). Mirrors Astro's platform auto-detection so a
+ * project deployed to a known host gets a working canonical origin for free.
+ */
+export const applyDeploymentEnv = (
+  config: ResolvedConfig,
+  env: NodeJS.ProcessEnv = process.env
+): ResolvedConfig => {
+  const platform = PLATFORMS.find((candidate) => candidate.detect(env));
+  if (!platform) {
+    return config;
+  }
+
+  const { deployment } = config;
+  const adapter =
+    deployment.adapter ??
+    (deployment.output === "server" ? platform.adapter : null);
+  const site = deployment.site ?? platform.site(env) ?? undefined;
+
+  if (adapter === deployment.adapter && site === deployment.site) {
+    return config;
+  }
+  return { ...config, deployment: { ...deployment, adapter, site } };
+};

package/src/core/diagnostics.ts

@@ -0,0 +1,104 @@
+import { relative } from "pathe";
+import type { ZodError } from "zod";
+
+import type { Diagnostic } from "./types.ts";
+
+/** A recoverable error carrying a structured diagnostic. */
+export class BlumeError extends Error {
+  readonly diagnostic: Diagnostic;
+
+  constructor(diagnostic: Diagnostic) {
+    super(diagnostic.message);
+    this.name = "BlumeError";
+    this.diagnostic = diagnostic;
+  }
+}
+
+export const createDiagnostic = (diagnostic: Diagnostic): Diagnostic =>
+  diagnostic;
+
+/** Convert a ZodError into Blume diagnostics, anchored to a file. */
+export const diagnosticsFromZod = (
+  error: ZodError,
+  options: { code: string; file?: string }
+): Diagnostic[] =>
+  error.issues.map((issue) => {
+    const schemaPath = issue.path.join(".");
+    const received =
+      "received" in issue
+        ? ` (received: ${JSON.stringify(issue.received)})`
+        : "";
+    return {
+      code: options.code,
+      file: options.file,
+      message: schemaPath
+        ? `${schemaPath}: ${issue.message}${received}`
+        : `${issue.message}${received}`,
+      schemaPath: schemaPath || undefined,
+      severity: "error",
+    } satisfies Diagnostic;
+  });
+
+const ESC = String.fromCodePoint(27);
+const COLORS = {
+  blue: `${ESC}[34m`,
+  bold: `${ESC}[1m`,
+  cyan: `${ESC}[36m`,
+  dim: `${ESC}[2m`,
+  red: `${ESC}[31m`,
+  reset: `${ESC}[0m`,
+  yellow: `${ESC}[33m`,
+};
+
+const severityColor = (severity: Diagnostic["severity"]): string => {
+  if (severity === "error") {
+    return COLORS.red;
+  }
+  if (severity === "warning") {
+    return COLORS.yellow;
+  }
+  return COLORS.blue;
+};
+
+/** Format a single diagnostic for terminal output. */
+export const formatDiagnostic = (
+  diagnostic: Diagnostic,
+  root?: string
+): string => {
+  const color = severityColor(diagnostic.severity);
+  const lines: string[] = [
+    `${color}${COLORS.bold}${diagnostic.code}${COLORS.reset} ${diagnostic.message}`,
+  ];
+
+  if (diagnostic.file) {
+    const location = root ? relative(root, diagnostic.file) : diagnostic.file;
+    const column =
+      diagnostic.column === undefined ? "" : `:${diagnostic.column}`;
+    const position =
+      diagnostic.line === undefined ? "" : `:${diagnostic.line}${column}`;
+    lines.push(`  ${COLORS.dim}at ${location}${position}${COLORS.reset}`);
+  }
+
+  if (diagnostic.suggestion) {
+    lines.push(`  ${COLORS.cyan}fix: ${diagnostic.suggestion}${COLORS.reset}`);
+  }
+
+  if (diagnostic.docsUrl) {
+    lines.push(`  ${COLORS.dim}docs: ${diagnostic.docsUrl}${COLORS.reset}`);
+  }
+
+  return lines.join("\n");
+};
+
+export const hasErrors = (diagnostics: Diagnostic[]): boolean =>
+  diagnostics.some((d) => d.severity === "error");
+
+export const countBySeverity = (
+  diagnostics: Diagnostic[]
+): Record<Diagnostic["severity"], number> => {
+  const counts = { error: 0, info: 0, warning: 0 };
+  for (const diagnostic of diagnostics) {
+    counts[diagnostic.severity] += 1;
+  }
+  return counts;
+};