blume 0.0.0 → 0.1.0

package/src/core/graph.ts

@@ -0,0 +1,128 @@
+import { localizeRoute, resolveFallbackLocale } from "./i18n.ts";
+import { buildNavigation } from "./navigation.ts";
+import type {
+  FolderMeta,
+  ResolvedConfig,
+  ResolvedI18nConfig,
+} from "./schema.ts";
+import type {
+  ContentGraph,
+  Diagnostic,
+  Navigation,
+  PageRecord,
+} from "./types.ts";
+
+/** Assemble the content graph: routes map, nav, and duplicate diagnostics. */
+export const buildContentGraph = (
+  pages: PageRecord[],
+  options: {
+    folderMeta: Map<string, FolderMeta>;
+    sharedFolderMeta?: Map<string, FolderMeta>;
+    navigation: ResolvedConfig["navigation"];
+    i18n?: ResolvedI18nConfig;
+  }
+): ContentGraph => {
+  const routes = new Map<string, string>();
+  const diagnostics: Diagnostic[] = [];
+
+  for (const page of pages) {
+    const existing = routes.get(page.route);
+    if (existing) {
+      diagnostics.push({
+        code: "BLUME_DUPLICATE_ROUTE",
+        file: page.sourcePath ?? page.id,
+        message: `Two files resolve to ${page.route}: ${existing} and ${page.id}`,
+        severity: "error",
+        suggestion: "Rename or move one of the files so each route is unique.",
+      });
+      continue;
+    }
+    routes.set(page.route, page.id);
+  }
+
+  const { i18n } = options;
+  const navigationByLocale: Record<string, Navigation> = {};
+  let navigation: Navigation;
+
+  if (i18n) {
+    // Pages of the fallback locale, by translation key — used to fill in a
+    // locale's sidebar for pages it hasn't translated yet, so navigation mirrors
+    // the default structure instead of showing an empty (or partial) tree.
+    const fallback = resolveFallbackLocale(i18n);
+    const fallbackByKey = new Map<string, PageRecord>();
+    if (fallback) {
+      for (const page of pages) {
+        if (page.locale === fallback) {
+          fallbackByKey.set(page.translationKey, page);
+        }
+      }
+    }
+
+    // Each locale gets an independent tree from its own pages and folder meta,
+    // so navigation may diverge per language (Mintlify-style).
+    for (const { code } of i18n.locales) {
+      // Localize internal tab paths so a header tab points to its in-locale
+      // route (e.g. `/docs` -> `/fr/docs`); external paths pass through.
+      const tabs = options.navigation.tabs?.map((tab) => ({
+        ...tab,
+        path: tab.path.startsWith("/")
+          ? localizeRoute(tab.path, code, i18n)
+          : tab.path,
+      }));
+
+      const real = pages.filter((page) => page.locale === code);
+      let localePages = real;
+      if (fallback && code !== fallback) {
+        const present = new Set(real.map((page) => page.translationKey));
+        const filled: PageRecord[] = [];
+        for (const [key, source] of fallbackByKey) {
+          if (!present.has(key)) {
+            filled.push({
+              ...source,
+              locale: code,
+              route: localizeRoute(key, code, i18n),
+            });
+          }
+        }
+        localePages = [...real, ...filled];
+      }
+
+      navigationByLocale[code] = buildNavigation(localePages, {
+        chromeVariants: options.navigation.chromeVariants,
+        folderMeta: options.folderMeta,
+        metaPrefix: code === i18n.defaultLocale ? "" : code,
+        refByLogical: true,
+        selectors: options.navigation.selectors,
+        sharedFolderMeta: options.sharedFolderMeta,
+        sidebar: options.navigation.sidebar,
+        sidebarVariants: options.navigation.sidebarVariants,
+        tabs,
+      });
+    }
+    navigation = navigationByLocale[i18n.defaultLocale] ?? {
+      chromeVariants: [],
+      selectors: [],
+      sidebar: [],
+      sidebarVariants: [],
+      tabs: [],
+    };
+  } else {
+    navigation = buildNavigation(pages, {
+      chromeVariants: options.navigation.chromeVariants,
+      folderMeta: options.folderMeta,
+      selectors: options.navigation.selectors,
+      sharedFolderMeta: options.sharedFolderMeta,
+      sidebar: options.navigation.sidebar,
+      sidebarVariants: options.navigation.sidebarVariants,
+      tabs: options.navigation.tabs,
+    });
+  }
+
+  return {
+    diagnostics,
+    navigation,
+    navigationByLocale,
+    pages,
+    routes,
+  };
+};

package/src/core/i18n-ui.ts

@@ -0,0 +1,171 @@
+import { z } from "zod";
+
+import { UI_PACKS } from "./ui-packs/index.ts";
+
+/**
+ * Translatable UI chrome strings.
+ *
+ * The schema is the single source of truth: each field's `.default()` is the
+ * English baseline, so `EN_UI = uiStringsSchema.parse({})`. Shipped packs and
+ * user overrides merge on top (see {@link resolveUIStrings}). Grouped by surface
+ * to keep the runtime payload and component props readable.
+ */
+const uiStringsObject = z.object({
+  actions: z
+    .object({
+      addToCursor: z.string().default("Add to Cursor"),
+      addToVscode: z.string().default("Add to VS Code"),
+      askAI: z.string().default("Ask AI about this page"),
+      connectMcp: z.string().default("Connect to MCP"),
+      copied: z.string().default("Copied!"),
+      copyClaudeCode: z.string().default("Copy Claude Code command"),
+      copyMarkdown: z.string().default("Copy as Markdown"),
+      copyServerUrl: z.string().default("Copy server URL"),
+      edit: z.string().default("Edit on GitHub"),
+      openInChat: z.string().default("Open in chat"),
+      scrollToTop: z.string().default("Scroll to top"),
+    })
+    .default({}),
+  ask: z
+    .object({
+      empty: z.string().default("Ask a question about the docs."),
+      error: z.string().default("Sorry, something went wrong."),
+      label: z.string().default("Ask a question"),
+      placeholder: z.string().default("Ask a question…"),
+      send: z.string().default("Send"),
+      title: z.string().default("Ask AI"),
+    })
+    .default({}),
+  feedback: z
+    .object({
+      no: z.string().default("No"),
+      question: z.string().default("Was this page helpful?"),
+      thanks: z.string().default("Thanks for your feedback!"),
+      yes: z.string().default("Yes"),
+    })
+    .default({}),
+  languageSwitcher: z
+    .object({
+      label: z.string().default("Language"),
+      untranslated: z.string().default("Not translated"),
+    })
+    .default({}),
+  page: z
+    .object({
+      lastUpdated: z.string().default("Last updated on"),
+      next: z.string().default("Next"),
+      previous: z.string().default("Previous"),
+      skipToContent: z.string().default("Skip to content"),
+    })
+    .default({}),
+  search: z
+    .object({
+      allLanguages: z.string().default("All languages"),
+      button: z.string().default("Search"),
+      devOnly: z
+        .string()
+        .default("Search is available in the production build."),
+      label: z.string().default("Search docs"),
+      noResults: z.string().default("No results found."),
+      placeholder: z.string().default("Search documentation…"),
+    })
+    .default({}),
+  toc: z
+    .object({
+      title: z.string().default("On this page"),
+    })
+    .default({}),
+});
+
+export const uiStringsSchema = uiStringsObject.default({});
+
+/** A fully-resolved dictionary; every key present. */
+export type UIStrings = z.infer<typeof uiStringsObject>;
+
+/** The English baseline, derived from the schema defaults. */
+export const EN_UI: UIStrings = uiStringsObject.parse({});
+
+/**
+ * A partial override: `{ group: { key: "translation" } }`. Validated loosely
+ * (object of objects of strings) so packs and user config can supply only the
+ * keys they translate. Unknown groups/keys merge harmlessly.
+ */
+export const uiStringsOverrideSchema = z.record(
+  z.string(),
+  z.record(z.string(), z.string())
+);
+
+export type UIStringsOverride = z.infer<typeof uiStringsOverrideSchema>;
+
+/** Per-locale UI overrides supplied in `i18n.ui`. */
+export const uiLocaleOverridesSchema = z.record(
+  z.string(),
+  uiStringsOverrideSchema
+);
+
+/** Merge an override's string leaves onto a base dictionary (two levels deep). */
+const mergeUI = (base: UIStrings, override?: UIStringsOverride): UIStrings => {
+  if (!override) {
+    return base;
+  }
+  const out: UIStrings = structuredClone(base);
+  for (const [group, values] of Object.entries(override)) {
+    const target = (out as Record<string, Record<string, string>>)[group];
+    if (target && values) {
+      Object.assign(target, values);
+    }
+  }
+  return out;
+};
+
+/**
+ * Built-in translation packs, one module per locale under {@link ./ui-packs}.
+ * English is the schema baseline (no pack); every other locale ships a starter
+ * pack so adopters get translated chrome out of the box. Re-exported here so the
+ * resolver and existing imports keep a single entry point.
+ */
+export { UI_PACKS };
+
+/** Case-insensitive index for region-variant lookup (`pt-br` -> `pt-BR`). */
+const PACKS_BY_LOWER: Record<string, UIStringsOverride> = Object.fromEntries(
+  Object.entries(UI_PACKS).map(([code, pack]) => [code.toLowerCase(), pack])
+);
+
+/**
+ * Find the built-in pack for a locale code, tolerating case and region subtags:
+ * an exact match wins, then a case-insensitive match (`pt-br` -> `pt-BR`), then
+ * the base language (`fr-CA` -> `fr`). So any reasonable code gets sensible
+ * chrome without the project having to match our exact casing.
+ */
+const packFor = (code: string): UIStringsOverride | undefined => {
+  const lower = code.toLowerCase();
+  return (
+    UI_PACKS[code] ??
+    PACKS_BY_LOWER[lower] ??
+    PACKS_BY_LOWER[lower.split(/[-_]/u)[0] ?? lower]
+  );
+};
+
+/**
+ * Resolve the active dictionary for a locale. Layers, in order:
+ * English baseline ← default-locale pack ← default-locale override ←
+ * locale pack ← locale override. So a missing key falls back to the default
+ * locale's translation, then to English.
+ */
+export const resolveUIStrings = (
+  locale: string,
+  options: {
+    defaultLocale: string;
+    overrides?: Record<string, UIStringsOverride>;
+  }
+): UIStrings => {
+  const { defaultLocale, overrides } = options;
+  let dict = EN_UI;
+  dict = mergeUI(dict, packFor(defaultLocale));
+  dict = mergeUI(dict, overrides?.[defaultLocale]);
+  if (locale !== defaultLocale) {
+    dict = mergeUI(dict, packFor(locale));
+    dict = mergeUI(dict, overrides?.[locale]);
+  }
+  return dict;
+};

package/src/core/i18n.ts

@@ -0,0 +1,169 @@
+import type { ResolvedConfig, ResolvedI18nConfig } from "./schema.ts";
+import type { Diagnostic, PageRecord } from "./types.ts";
+import { UI_PACKS } from "./ui-packs/index.ts";
+
+/**
+ * Locale logic, centralized. Every seam that needs to reason about locales
+ * (content discovery, navigation, manifest, runtime generation, the catch-all)
+ * goes through these helpers so the routing rules live in exactly one place.
+ */
+
+/** Locale codes Blume recognizes (those it ships a UI pack for, plus English). */
+const KNOWN_LOCALES = new Set(
+  [...Object.keys(UI_PACKS), "en"].map((code) => code.toLowerCase())
+);
+
+/** True when the project opts into i18n. */
+export const i18nEnabled = (
+  config: ResolvedConfig
+): config is ResolvedConfig & { i18n: ResolvedI18nConfig } =>
+  config.i18n !== undefined;
+
+/** All configured locale codes, default first as authored. */
+export const localeCodes = (i18n: ResolvedI18nConfig): string[] =>
+  i18n.locales.map((locale) => locale.code);
+
+/** Text direction for a locale (`ltr` when unknown). */
+export const localeDir = (
+  code: string,
+  i18n: ResolvedI18nConfig
+): "ltr" | "rtl" =>
+  i18n.locales.find((locale) => locale.code === code)?.dir ?? "ltr";
+
+/**
+ * The locale a missing translation falls back to: `fallbackLocale` when set,
+ * the default locale when `fallbackLocale` is omitted, or `null` (disabled)
+ * when explicitly set to `null`.
+ */
+export const resolveFallbackLocale = (
+  i18n: ResolvedI18nConfig
+): string | null => {
+  if (i18n.fallbackLocale === null) {
+    return null;
+  }
+  return i18n.fallbackLocale ?? i18n.defaultLocale;
+};
+
+/** URL prefix for a locale: `""` for the hidden default, else `/<code>`. */
+export const localePrefix = (code: string, i18n: ResolvedI18nConfig): string =>
+  code === i18n.defaultLocale && i18n.hideDefaultLocalePrefix ? "" : `/${code}`;
+
+/**
+ * Prefix a locale-agnostic route (e.g. `/guides/x` or `/`) with its locale.
+ * `/` becomes `/fr` (or stays `/` for the hidden default).
+ */
+export const localizeRoute = (
+  logicalRoute: string,
+  code: string,
+  i18n: ResolvedI18nConfig
+): string => {
+  const prefix = localePrefix(code, i18n);
+  if (!prefix) {
+    return logicalRoute;
+  }
+  return logicalRoute === "/" ? prefix : `${prefix}${logicalRoute}`;
+};
+
+/**
+ * Detect a leading non-default locale directory in a path's segments. The
+ * default locale lives at the content root, so only non-default codes are
+ * matched as a leading segment. Returns the resolved locale and the remaining
+ * (locale-stripped) segments.
+ */
+export const detectLocale = (
+  parts: string[],
+  i18n: ResolvedI18nConfig
+): { locale: string; rest: string[] } => {
+  const [first] = parts;
+  const isNonDefault = i18n.locales.some(
+    (locale) => locale.code !== i18n.defaultLocale && locale.code === first
+  );
+  if (first !== undefined && isNonDefault) {
+    return { locale: first, rest: parts.slice(1) };
+  }
+  return { locale: i18n.defaultLocale, rest: parts };
+};
+
+/**
+ * Resolve where a content file lives across locales, by parser:
+ * - `dir`: a leading locale directory (`fr/page.mdx`)
+ * - `dot`: a filename suffix (`page.fr.mdx`)
+ *
+ * A `.$.` infix (e.g. `changelog.$.mdx`) marks a shared, locale-agnostic file
+ * that is materialized into every configured locale. Returns the locale-stripped
+ * path (used for nav grouping) and the locale codes the file maps to (one for a
+ * normal file, all locales for a shared one).
+ */
+export const localePlacement = (
+  rel: string,
+  ext: string,
+  i18n: ResolvedI18nConfig
+): { navPath: string; locales: string[] } => {
+  const base = rel.slice(0, rel.length - ext.length);
+
+  // Shared `$` file: the same content in every locale.
+  if (base.endsWith(".$")) {
+    return {
+      locales: i18n.locales.map((locale) => locale.code),
+      navPath: `${base.slice(0, -2)}${ext}`,
+    };
+  }
+
+  if (i18n.parser === "dot") {
+    const lastDot = base.lastIndexOf(".");
+    // Only a dot inside the filename (not a directory) is a locale suffix.
+    if (lastDot > base.lastIndexOf("/")) {
+      const suffix = base.slice(lastDot + 1);
+      const isNonDefault = i18n.locales.some(
+        (locale) => locale.code !== i18n.defaultLocale && locale.code === suffix
+      );
+      if (isNonDefault) {
+        return {
+          locales: [suffix],
+          navPath: `${base.slice(0, lastDot)}${ext}`,
+        };
+      }
+    }
+    return { locales: [i18n.defaultLocale], navPath: rel };
+  }
+
+  const { locale, rest } = detectLocale(rel.split("/"), i18n);
+  return { locales: [locale], navPath: rest.join("/") };
+};
+
+/**
+ * Warn about top-level content folders that look like a locale (a code Blume
+ * recognizes) but aren't declared in `i18n.locales`. Without this they're
+ * silently treated as default-locale content under a `/<code>/…` route, which
+ * is almost never intended — usually a translation that wasn't registered.
+ */
+export const i18nDiagnostics = (
+  pages: PageRecord[],
+  i18n: ResolvedI18nConfig
+): Diagnostic[] => {
+  const configured = new Set(
+    i18n.locales.map((locale) => locale.code.toLowerCase())
+  );
+  const seen = new Set<string>();
+  const diagnostics: Diagnostic[] = [];
+  for (const page of pages) {
+    // The locale-looking folder is the first segment of the source-local ref
+    // (e.g. `fr/guide.md`), not the namespaced id (`filesystem:fr/guide.md`).
+    const first = page.source.ref.split("/")[0]?.toLowerCase();
+    if (
+      first &&
+      !seen.has(first) &&
+      KNOWN_LOCALES.has(first) &&
+      !configured.has(first)
+    ) {
+      seen.add(first);
+      diagnostics.push({
+        code: "BLUME_I18N_UNCONFIGURED_LOCALE",
+        message: `Folder "${first}/" looks like a locale, but "${first}" is not in i18n.locales — its pages are treated as "${i18n.defaultLocale}" content at /${first}/….`,
+        severity: "warning",
+        suggestion: `Add { code: "${first}", label: "…" } to i18n.locales, or rename the folder if it isn't a translation.`,
+      });
+    }
+  }
+  return diagnostics;
+};

package/src/core/last-modified.ts

@@ -0,0 +1,88 @@
+import { execFileSync } from "node:child_process";
+
+import { relative } from "pathe";
+
+/** Normalized form of the `lastModified` config. */
+export interface ResolvedLastModified {
+  enabled: boolean;
+  source: "git" | "frontmatter";
+}
+
+/** Normalize the `lastModified` config union into `{ enabled, source }`. */
+export const resolveLastModifiedConfig = (
+  value: boolean | { type: "git" | "frontmatter" }
+): ResolvedLastModified => {
+  if (value === false) {
+    return { enabled: false, source: "git" };
+  }
+  if (value === true) {
+    return { enabled: true, source: "git" };
+  }
+  return { enabled: true, source: value.type };
+};
+
+/**
+ * Parse `git log --format=%x00%cI --name-only` output into a map of
+ * repo-root-relative path → most recent committer ISO date. Each commit emits a
+ * NUL-prefixed date line followed by the paths it touched; since git logs
+ * newest-first, the first date seen for a path wins. Blank lines are ignored.
+ */
+export const parseGitLog = (output: string): Map<string, string> => {
+  const times = new Map<string, string>();
+  let current: string | null = null;
+  for (const line of output.split("\n")) {
+    if (line.startsWith("\0")) {
+      current = line.slice(1);
+    } else if (line && current && !times.has(line)) {
+      times.set(line, current);
+    }
+  }
+  return times;
+};
+
+/**
+ * Resolve each source file's last-modified date from git history, keyed by
+ * absolute source path. Runs a single `git log` over the content tree and maps
+ * repo-root-relative paths back to the given absolute paths (monorepo-safe via
+ * `rev-parse --show-toplevel`). Returns an empty map if git is unavailable or
+ * the project isn't a repo — the feature then simply shows no dates.
+ */
+export const gitLastModifiedTimes = (
+  root: string,
+  contentRoot: string,
+  sourcePaths: string[]
+): Map<string, string> => {
+  try {
+    const gitRoot = execFileSync(
+      "git",
+      ["-C", root, "rev-parse", "--show-toplevel"],
+      { encoding: "utf-8" }
+    ).trim();
+    const output = execFileSync(
+      "git",
+      [
+        "-C",
+        root,
+        "-c",
+        "core.quotePath=false",
+        "log",
+        "--format=%x00%cI",
+        "--name-only",
+        "--",
+        contentRoot,
+      ],
+      { encoding: "utf-8", maxBuffer: 256 * 1024 * 1024 }
+    );
+    const byRepoPath = parseGitLog(output);
+    const result = new Map<string, string>();
+    for (const sourcePath of sourcePaths) {
+      const iso = byRepoPath.get(relative(gitRoot, sourcePath));
+      if (iso) {
+        result.set(sourcePath, iso);
+      }
+    }
+    return result;
+  } catch {
+    return new Map();
+  }
+};