blume 0.0.0 → 0.1.0

package/src/core/navigation.ts

@@ -0,0 +1,392 @@
+import { extname } from "pathe";
+
+import type {
+  FolderMeta,
+  SidebarDisplay,
+  SidebarItemConfig,
+} from "./schema.ts";
+import type {
+  NavChromeVariant,
+  NavNode,
+  NavSidebarVariant,
+  Navigation,
+  NavSelector,
+  NavTab,
+  PageRecord,
+} from "./types.ts";
+
+const NUMERIC_PREFIX = /^(?<order>\d+)[-_.]/u;
+const GROUP_FOLDER = /^\((?<label>.+)\)$/u;
+const WORD_SPLIT = /[-_]/u;
+
+const humanize = (segment: string): string =>
+  segment
+    .replace(NUMERIC_PREFIX, "")
+    .split(WORD_SPLIT)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+
+const numericOrder = (segment: string): number => {
+  const value = segment.match(NUMERIC_PREFIX)?.groups?.order;
+  return value ? Number.parseInt(value, 10) : Number.POSITIVE_INFINITY;
+};
+
+/** The nav key of a raw path segment: group label or numeric-stripped name. */
+const segmentKey = (raw: string): string => {
+  const group = raw.match(GROUP_FOLDER)?.groups?.label;
+  return (group ?? raw).replace(NUMERIC_PREFIX, "");
+};
+
+interface MutablePage {
+  kind: "page";
+  key: string;
+  label: string;
+  route: string;
+  description?: string;
+  icon?: string;
+  badge?: string;
+  deprecated?: boolean;
+  pageId: string;
+  order: number;
+}
+
+interface MutableGroup {
+  kind: "group";
+  key: string;
+  path: string;
+  label: string;
+  icon?: string;
+  collapsed?: boolean;
+  display?: SidebarDisplay;
+  order: number;
+  children: MutableNode[];
+  index: Map<string, MutableGroup>;
+}
+
+type MutableNode = MutablePage | MutableGroup;
+
+const createGroup = (
+  key: string,
+  path: string,
+  label: string,
+  order: number
+): MutableGroup => ({
+  children: [],
+  index: new Map(),
+  key,
+  kind: "group",
+  label,
+  order,
+  path,
+});
+
+const ensureGroup = (
+  parent: MutableGroup,
+  rawSegment: string
+): MutableGroup => {
+  const existing = parent.index.get(rawSegment);
+  if (existing) {
+    return existing;
+  }
+  const path = parent.path ? `${parent.path}/${rawSegment}` : rawSegment;
+  const group = createGroup(
+    segmentKey(rawSegment),
+    path,
+    humanize(rawSegment.match(GROUP_FOLDER)?.groups?.label ?? rawSegment),
+    numericOrder(rawSegment)
+  );
+  parent.index.set(rawSegment, group);
+  parent.children.push(group);
+  return group;
+};
+
+const pageOrder = (page: PageRecord, filename: string): number => {
+  if (page.meta.sidebar.order !== undefined) {
+    return page.meta.sidebar.order;
+  }
+  if (filename.replace(extname(filename), "") === "index") {
+    return Number.NEGATIVE_INFINITY;
+  }
+  return numericOrder(filename);
+};
+
+/**
+ * Folder-meta lookup key for a group path. Under i18n the meta files live in
+ * the locale directory (`fr/guides/meta.ts` -> key `fr/guides`) while the
+ * nav group path is locale-stripped (`guides`), so prepend the locale prefix.
+ */
+const metaKey = (path: string, metaPrefix: string): string => {
+  if (!metaPrefix) {
+    return path;
+  }
+  return path ? `${metaPrefix}/${path}` : metaPrefix;
+};
+
+/** Apply folder meta (title/order/icon/collapsed and explicit page order). */
+const applyFolderMeta = (
+  group: MutableGroup,
+  folderMeta: Map<string, FolderMeta>,
+  sharedMeta: Map<string, FolderMeta>,
+  metaPrefix: string
+): void => {
+  // Locale-specific meta wins; a shared `meta.$.*` (keyed by the locale-stripped
+  // group path) applies to every locale otherwise.
+  const meta =
+    folderMeta.get(metaKey(group.path, metaPrefix)) ??
+    sharedMeta.get(group.path);
+  if (meta) {
+    group.label = meta.title ?? group.label;
+    group.icon = meta.icon ?? group.icon;
+    group.order = meta.order ?? group.order;
+    group.collapsed = meta.collapsed ?? group.collapsed;
+    group.display = meta.display ?? group.display;
+
+    if (meta.pages) {
+      const rank = new Map(meta.pages.map((key, i) => [key, i]));
+      for (const child of group.children) {
+        const position = rank.get(child.key);
+        if (position !== undefined) {
+          child.order = position;
+        }
+      }
+    }
+  }
+
+  for (const child of group.children) {
+    if (child.kind === "group") {
+      applyFolderMeta(child, folderMeta, sharedMeta, metaPrefix);
+    }
+  }
+};
+
+const sortNodes = (nodes: MutableNode[]): void => {
+  nodes.sort((a, b) => {
+    if (a.order !== b.order) {
+      return a.order - b.order;
+    }
+    return a.label.localeCompare(b.label);
+  });
+  for (const node of nodes) {
+    if (node.kind === "group") {
+      sortNodes(node.children);
+    }
+  }
+};
+
+const toNavNode = (node: MutableNode): NavNode => {
+  if (node.kind === "page") {
+    return {
+      badge: node.badge,
+      deprecated: node.deprecated || undefined,
+      description: node.description,
+      icon: node.icon,
+      kind: "page",
+      label: node.label,
+      pageId: node.pageId,
+      route: node.route,
+    };
+  }
+  return {
+    children: node.children.map(toNavNode),
+    collapsed: node.collapsed,
+    display: node.display,
+    icon: node.icon,
+    kind: "group",
+    label: node.label,
+  };
+};
+
+/** Build the sidebar tree from the file system and folder meta. */
+const buildFileSystemSidebar = (
+  pages: PageRecord[],
+  folderMeta: Map<string, FolderMeta>,
+  sharedMeta: Map<string, FolderMeta>,
+  metaPrefix: string
+): NavNode[] => {
+  const root = createGroup("", "", "", 0);
+
+  for (const page of pages) {
+    if (page.meta.sidebar.hidden) {
+      continue;
+    }
+    // Group by the locale-stripped path so the locale dir is not a nav group.
+    const parts = page.navPath.split("/");
+    const filename = parts.at(-1) ?? page.navPath;
+    const dirs = parts.slice(0, -1);
+
+    let parent = root;
+    for (const dir of dirs) {
+      parent = ensureGroup(parent, dir);
+    }
+
+    parent.children.push({
+      badge: page.meta.sidebar.badge,
+      deprecated: page.meta.deprecated || undefined,
+      description: page.description,
+      icon: page.meta.sidebar.icon,
+      key: segmentKey(filename.replace(extname(filename), "")),
+      kind: "page",
+      label: page.meta.sidebar.label ?? page.title,
+      order: pageOrder(page, filename),
+      pageId: page.id,
+      route: page.route,
+    });
+  }
+
+  applyFolderMeta(root, folderMeta, sharedMeta, metaPrefix);
+  sortNodes(root.children);
+  return root.children.map(toNavNode);
+};
+
+const normalizeRef = (ref: string): string => {
+  if (ref === "index") {
+    return "/";
+  }
+  const withSlash = ref.startsWith("/") ? ref : `/${ref}`;
+  return withSlash.endsWith("/index") ? withSlash.slice(0, -6) : withSlash;
+};
+
+const routeForRef = (
+  ref: string | undefined,
+  byRoute: Map<string, PageRecord>
+): string | undefined => {
+  if (!ref) {
+    return undefined;
+  }
+  const normalized = normalizeRef(ref);
+  return byRoute.get(normalized)?.route ?? normalized;
+};
+
+/** Build the sidebar tree from an explicit config spec. */
+const buildConfigSidebar = (
+  items: SidebarItemConfig[],
+  byRoute: Map<string, PageRecord>
+): NavNode[] => {
+  const nodes: NavNode[] = [];
+
+  for (const item of items) {
+    if (typeof item === "string") {
+      const page = byRoute.get(normalizeRef(item));
+      if (page) {
+        nodes.push({
+          badge: page.meta.sidebar.badge,
+          deprecated: page.meta.deprecated || undefined,
+          description: page.description,
+          icon: page.meta.sidebar.icon,
+          kind: "page",
+          label: page.meta.sidebar.label ?? page.title,
+          pageId: page.id,
+          route: page.route,
+        });
+      }
+      continue;
+    }
+
+    if (item.items) {
+      nodes.push({
+        badge: item.badge,
+        children: buildConfigSidebar(item.items, byRoute),
+        collapsed: item.collapsed,
+        directory: item.directory,
+        display: item.display,
+        icon: item.icon,
+        kind: "group",
+        label: item.label,
+        route: routeForRef(item.root, byRoute),
+      });
+      continue;
+    }
+
+    if (item.root) {
+      const page = byRoute.get(normalizeRef(item.root));
+      nodes.push({
+        badge: item.badge,
+        deprecated: page?.meta.deprecated || undefined,
+        icon: item.icon,
+        kind: "page",
+        label: item.label,
+        pageId: page?.id ?? "",
+        route: page?.route ?? normalizeRef(item.root),
+      });
+      continue;
+    }
+
+    if (item.href) {
+      nodes.push({
+        badge: item.badge,
+        icon: item.icon,
+        kind: "page",
+        label: item.label,
+        pageId: "",
+        route: item.href,
+      });
+    }
+  }
+
+  return nodes;
+};
+
+/** Build the complete navigation model from pages, meta, and config. */
+export const buildNavigation = (
+  pages: PageRecord[],
+  options: {
+    chromeVariants?: NavChromeVariant[];
+    folderMeta: Map<string, FolderMeta>;
+    selectors?: NavSelector[];
+    tabs?: NavTab[];
+    sidebar?: SidebarItemConfig[];
+    sidebarVariants?: { path: string; items: SidebarItemConfig[] }[];
+    /** Locale dir prefix for folder-meta lookup (`""` for the default locale). */
+    metaPrefix?: string;
+    /**
+     * Resolve explicit-sidebar references against each page's locale-agnostic
+     * `translationKey` instead of its localized `route`. Used under i18n so a
+     * single authored sidebar maps onto every locale's pages.
+     */
+    refByLogical?: boolean;
+    /** Shared `meta.$.*` meta, keyed by locale-stripped dir path. */
+    sharedFolderMeta?: Map<string, FolderMeta>;
+  }
+): Navigation => {
+  const chromeVariants = options.chromeVariants ?? [];
+  const selectors = options.selectors ?? [];
+  const tabs = options.tabs ?? [];
+  const metaPrefix = options.metaPrefix ?? "";
+  const sharedFolderMeta = options.sharedFolderMeta ?? new Map();
+  const byRoute = new Map(
+    pages.map((page) => [
+      options.refByLogical ? page.translationKey : page.route,
+      page,
+    ])
+  );
+  const sidebarVariants: NavSidebarVariant[] = (
+    options.sidebarVariants ?? []
+  ).map((variant) => ({
+    path: variant.path,
+    sidebar: buildConfigSidebar(variant.items, byRoute),
+  }));
+
+  if (options.sidebar) {
+    return {
+      chromeVariants,
+      selectors,
+      sidebar: buildConfigSidebar(options.sidebar, byRoute),
+      sidebarVariants,
+      tabs,
+    };
+  }
+
+  return {
+    chromeVariants,
+    selectors,
+    sidebar: buildFileSystemSidebar(
+      pages,
+      options.folderMeta,
+      sharedFolderMeta,
+      metaPrefix
+    ),
+    sidebarVariants,
+    tabs,
+  };
+};

package/src/core/package-root.ts

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+
+import { dirname, join } from "pathe";
+
+/**
+ * Walk up from `start` until a directory containing a `package.json` is found.
+ *
+ * Exported for testing; call sites should use {@link packageRoot}.
+ */
+export const findPackageRoot = (start: string): string => {
+  let dir = start;
+  while (!existsSync(join(dir, "package.json"))) {
+    const parent = dirname(dir);
+    if (parent === dir) {
+      throw new Error("blume: unable to locate the package root");
+    }
+    dir = parent;
+  }
+  return dir;
+};
+
+let cached: string | undefined;
+
+/**
+ * Absolute path to the installed Blume package root (the directory holding its
+ * `package.json`), found by walking up from this module.
+ *
+ * Anchoring here — rather than at a fixed offset from `import.meta` — keeps the
+ * package's own `src/`, assets, and `node_modules` locatable whether the code
+ * runs from source under Bun (`src/...`) or from the published, bundled CLI
+ * (`dist/cli/index.js`). The two layouts sit at different depths, so a relative
+ * `../..` resolves to different places; locating `package.json` does not.
+ */
+export const packageRoot = (): string => {
+  cached ??= findPackageRoot(import.meta.dirname);
+  return cached;
+};

package/src/core/project-graph.ts

@@ -0,0 +1,153 @@
+import { loadConfig } from "./config.ts";
+import type { ConfigBridge } from "./config.ts";
+import { buildContentGraph } from "./graph.ts";
+import { i18nDiagnostics } from "./i18n.ts";
+import {
+  gitLastModifiedTimes,
+  resolveLastModifiedConfig,
+} from "./last-modified.ts";
+import { buildManifest } from "./manifest.ts";
+import { discoverFolderMeta } from "./meta.ts";
+import { resolveProjectContext } from "./project.ts";
+import type { ResolvedConfig } from "./schema.ts";
+import { normalizeEntry } from "./sources/normalize.ts";
+import { resolveSources } from "./sources/resolve.ts";
+import type { ContentSource } from "./sources/types.ts";
+import type {
+  BlumeManifest,
+  ContentGraph,
+  Diagnostic,
+  PageRecord,
+  ProjectContext,
+} from "./types.ts";
+
+/** Build mode: drafts are kept in `dev` and dropped in `build`. */
+export type BuildMode = "dev" | "build";
+
+/** Everything Blume knows about a project after a full scan. */
+export interface BlumeProject {
+  mode: BuildMode;
+  context: ProjectContext;
+  config: ResolvedConfig;
+  graph: ContentGraph;
+  manifest: BlumeManifest;
+  diagnostics: Diagnostic[];
+  /** The instantiated content sources, for lazy entry reads (search/AI/raw). */
+  sources: ContentSource[];
+  /** Set when serving a foreign docs config (e.g. Mintlify) without migrating. */
+  bridge: ConfigBridge | null;
+}
+
+/**
+ * Run the full core pipeline for a project root: load config, resolve paths,
+ * discover content and folder meta, build the graph, and assemble the manifest.
+ * Collects all diagnostics without throwing on content-level problems so
+ * callers can decide how strict to be.
+ */
+export const scanProject = async (
+  root: string,
+  options: {
+    devServerUrl?: string;
+    mode?: BuildMode;
+    preview?: boolean;
+    refresh?: boolean;
+  } = {}
+): Promise<BlumeProject> => {
+  const mode = options.mode ?? "dev";
+  const preview = options.preview ?? false;
+  const { bridge, config } = await loadConfig(root, {
+    devServerUrl: options.devServerUrl,
+  });
+  const context = resolveProjectContext(root, config);
+
+  // Each source validates itself (e.g. the filesystem source checks its root
+  // exists), replacing the single hard `contentRoot` check.
+  const sources = resolveSources(config, context, {
+    mode,
+    preview,
+    refresh: options.refresh,
+  });
+  for (const source of sources) {
+    source.validate?.();
+  }
+
+  // Run every source's `load()` in parallel, then funnel each entry through the
+  // shared `normalizeEntry` so route mapping is identical regardless of origin.
+  const [loaded, folderMeta] = await Promise.all([
+    Promise.all(
+      sources.map(async (source) => ({ source, ...(await source.load()) }))
+    ),
+    discoverFolderMeta(context.contentRoot),
+  ]);
+
+  const allPages: PageRecord[] = [];
+  const contentDiagnostics: Diagnostic[] = [];
+  for (const { source, entries, diagnostics } of loaded) {
+    contentDiagnostics.push(...diagnostics);
+    for (const entry of entries) {
+      const normalized = normalizeEntry(entry, {
+        defaultType: config.content.defaultType,
+        i18n: config.i18n,
+        source: {
+          name: source.name,
+          prefix: source.prefix,
+          staged: source.staged,
+        },
+      });
+      allPages.push(...normalized.pages);
+      contentDiagnostics.push(...normalized.diagnostics);
+    }
+  }
+
+  // Drafts render in dev and in preview, but are excluded from production builds.
+  const pages =
+    mode === "build" && !preview
+      ? allPages.filter((page) => !page.meta.draft)
+      : allPages;
+
+  // Resolve "last updated" dates before the graph is built so the manifest
+  // (which shares these page objects) picks them up. Frontmatter always wins;
+  // git applies to filesystem entries, other sources supply dates on the entry.
+  const lastModified = resolveLastModifiedConfig(config.lastModified);
+  if (lastModified.enabled && lastModified.source === "git") {
+    const fsPaths = pages
+      .map((page) => page.sourcePath)
+      .filter((path): path is string => path !== undefined);
+    const gitTimes = gitLastModifiedTimes(
+      context.root,
+      context.contentRoot,
+      fsPaths
+    );
+    for (const page of pages) {
+      if (!page.lastModified && page.sourcePath) {
+        page.lastModified = gitTimes.get(page.sourcePath);
+      }
+    }
+  }
+
+  const graph = buildContentGraph(pages, {
+    folderMeta: folderMeta.meta,
+    i18n: config.i18n,
+    navigation: config.navigation,
+    sharedFolderMeta: folderMeta.shared,
+  });
+  const manifest = buildManifest({ config, context, graph });
+
+  const i18nWarnings = config.i18n ? i18nDiagnostics(pages, config.i18n) : [];
+
+  return {
+    bridge,
+    config,
+    context,
+    diagnostics: [
+      ...contentDiagnostics,
+      ...folderMeta.diagnostics,
+      ...graph.diagnostics,
+      ...i18nWarnings,
+    ],
+    graph,
+    manifest,
+    mode,
+    sources,
+  };
+};

package/src/core/project.ts

@@ -0,0 +1,56 @@
+import { existsSync } from "node:fs";
+
+import { isAbsolute, join, resolve } from "pathe";
+
+import type { ResolvedConfig } from "./schema.ts";
+import type { ProjectContext } from "./types.ts";
+
+const CONFIG_FILENAMES = [
+  "blume.config.ts",
+  "blume.config.mjs",
+  "blume.config.js",
+];
+
+const THEME_FILENAMES = ["theme.css"];
+const COMPONENTS_FILENAMES = ["components.tsx", "components.ts"];
+
+const firstExisting = (root: string, names: string[]): string | null => {
+  for (const name of names) {
+    const candidate = join(root, name);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+};
+
+/** Locate the Blume config file for a project root, if any. */
+export const findConfigFile = (root: string): string | null =>
+  firstExisting(root, CONFIG_FILENAMES);
+
+/**
+ * Resolve every path Blume needs from a project root and its resolved config.
+ * Paths are absolute and normalized.
+ */
+export const resolveProjectContext = (
+  root: string,
+  config: ResolvedConfig
+): ProjectContext => {
+  const absoluteRoot = resolve(root);
+  const contentRoot = isAbsolute(config.content.root)
+    ? config.content.root
+    : join(absoluteRoot, config.content.root);
+
+  const pagesPath = join(absoluteRoot, config.content.pages);
+  const pagesRoot = existsSync(pagesPath) ? pagesPath : null;
+
+  return {
+    componentsFile: firstExisting(absoluteRoot, COMPONENTS_FILENAMES),
+    configFile: findConfigFile(absoluteRoot),
+    contentRoot,
+    outDir: join(absoluteRoot, ".blume"),
+    pagesRoot,
+    root: absoluteRoot,
+    themeFile: firstExisting(absoluteRoot, THEME_FILENAMES),
+  };
+};