blume 0.0.0 → 0.1.0

package/src/core/links.ts

@@ -0,0 +1,336 @@
+import { existsSync } from "node:fs";
+
+import { join } from "pathe";
+
+import type {
+  ContentGraph,
+  Diagnostic,
+  PageLink,
+  PageRecord,
+} from "./types.ts";
+
+const HTTP = /^https?:\/\//iu;
+const PROTOCOL_RELATIVE = /^\/\//u;
+const SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
+const DOC_EXT = /\.(?:md|mdx)$/iu;
+const FILE_EXT = /\.[a-z0-9]+$/iu;
+
+const EXTERNAL_CONCURRENCY = 8;
+const EXTERNAL_TIMEOUT_MS = 10_000;
+const STATUS_NOT_FOUND = 404;
+const STATUS_GONE = 410;
+const STATUS_METHOD_NOT_ALLOWED = 405;
+const STATUS_NOT_IMPLEMENTED = 501;
+
+/** Source position shared by every diagnostic raised for a link. */
+interface LinkSite {
+  column: number;
+  file: string;
+  line: number;
+}
+
+/** An external link occurrence queued for a network probe. */
+interface ExternalRef extends LinkSite {
+  url: string;
+}
+
+/** Lookups derived once from the content graph. */
+interface LinkContext {
+  anchors: Map<string, Set<string>>;
+  publicDir: string | null;
+  routes: Set<string>;
+}
+
+/** Outcome of classifying one link target. */
+type LinkResult = Diagnostic | "asset-unchecked" | null;
+
+/** Resolve a relative link target against the directory of a page route. */
+const resolveRelative = (pageRoute: string, target: string): string => {
+  const segments = pageRoute.split("/").filter(Boolean);
+  // Drop the page's own segment so links resolve against its parent directory.
+  segments.pop();
+  for (const part of target.split("/")) {
+    if (part === "" || part === ".") {
+      continue;
+    }
+    if (part === "..") {
+      segments.pop();
+      continue;
+    }
+    segments.push(part);
+  }
+  return `/${segments.join("/")}`;
+};
+
+/** Normalize an internal path to its canonical route form. */
+const toRoute = (path: string): string => {
+  let route = path.replace(DOC_EXT, "");
+  if (route.endsWith("/index")) {
+    route = route.slice(0, -"/index".length);
+  }
+  if (route.length > 1 && route.endsWith("/")) {
+    route = route.slice(0, -1);
+  }
+  return route === "" ? "/" : route;
+};
+
+/** Build a map of route -> set of heading anchor slugs. */
+const buildAnchorIndex = (pages: PageRecord[]): Map<string, Set<string>> => {
+  const anchors = new Map<string, Set<string>>();
+  for (const page of pages) {
+    anchors.set(
+      page.route,
+      new Set(page.headings.map((heading) => heading.slug))
+    );
+  }
+  return anchors;
+};
+
+/** Verify a fragment resolves to a heading on the target route. */
+const checkAnchor = (
+  route: string,
+  fragment: string,
+  site: LinkSite,
+  ctx: LinkContext
+): Diagnostic | null => {
+  if (ctx.anchors.get(route)?.has(fragment.toLowerCase())) {
+    return null;
+  }
+  return {
+    ...site,
+    code: "BLUME_BROKEN_ANCHOR",
+    message: `No heading on ${route} matches anchor #${fragment}.`,
+    severity: "warning",
+  };
+};
+
+/** Validate a resolved internal path: asset, route, then optional anchor. */
+const checkPathLink = (
+  resolved: string,
+  fragment: string,
+  target: string,
+  site: LinkSite,
+  ctx: LinkContext
+): LinkResult => {
+  if (FILE_EXT.test(resolved) && !DOC_EXT.test(resolved)) {
+    if (ctx.publicDir === null) {
+      return "asset-unchecked";
+    }
+    if (existsSync(join(ctx.publicDir, resolved))) {
+      return null;
+    }
+    return {
+      ...site,
+      code: "BLUME_BROKEN_ASSET",
+      message: `Asset ${resolved} was not found in the public directory.`,
+      severity: "warning",
+      suggestion: `Add the file at public${resolved} or fix the link.`,
+    };
+  }
+
+  const route = toRoute(resolved);
+  if (!ctx.routes.has(route)) {
+    return {
+      ...site,
+      code: "BLUME_BROKEN_LINK",
+      message: `Broken link to ${target}: no page resolves to ${route}.`,
+      severity: "error",
+      suggestion: "Check the path, or create the target page.",
+    };
+  }
+  return fragment ? checkAnchor(route, fragment, site, ctx) : null;
+};
+
+/** Probe a URL with the given method, normalizing failures to a result. */
+const request = async (
+  url: string,
+  method: "GET" | "HEAD"
+): Promise<{
+  ok: boolean;
+  status?: number;
+  timedOut?: boolean;
+  error?: string;
+}> => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), EXTERNAL_TIMEOUT_MS);
+  try {
+    const response = await fetch(url, {
+      method,
+      redirect: "follow",
+      signal: controller.signal,
+    });
+    return { ok: response.ok, status: response.status };
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      return { ok: false, timedOut: true };
+    }
+    return {
+      error: error instanceof Error ? error.message : String(error),
+      ok: false,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/** Probe a single URL: HEAD first, falling back to GET when needed. */
+const probe = async (
+  url: string
+): Promise<Awaited<ReturnType<typeof request>>> => {
+  const head = await request(url, "HEAD");
+  const retry =
+    head.status === STATUS_METHOD_NOT_ALLOWED ||
+    head.status === STATUS_NOT_IMPLEMENTED ||
+    (!head.ok && head.status === undefined && !head.timedOut);
+  return retry ? await request(url, "GET") : head;
+};
+
+/** Grade a probe result into a diagnostic severity + detail, or null if OK. */
+const gradeExternal = (
+  result: Awaited<ReturnType<typeof request>>
+): { severity: Diagnostic["severity"]; detail: string } | null => {
+  if (result.ok) {
+    return null;
+  }
+  if (result.timedOut) {
+    return { detail: "request timed out", severity: "warning" };
+  }
+  if (result.status === undefined) {
+    return { detail: result.error ?? "unreachable", severity: "error" };
+  }
+  if (result.status === STATUS_NOT_FOUND || result.status === STATUS_GONE) {
+    return { detail: `HTTP ${result.status}`, severity: "error" };
+  }
+  return { detail: `HTTP ${result.status}`, severity: "warning" };
+};
+
+/** Probe queued external links with bounded concurrency. */
+const checkExternalLinks = async (
+  refs: ExternalRef[]
+): Promise<Diagnostic[]> => {
+  const unique = [...new Set(refs.map((ref) => ref.url))];
+  const results = new Map<string, Awaited<ReturnType<typeof probe>>>();
+
+  let cursor = 0;
+  const worker = async (): Promise<void> => {
+    while (cursor < unique.length) {
+      const url = unique[cursor];
+      cursor += 1;
+      if (url !== undefined) {
+        // oxlint-disable-next-line no-await-in-loop -- bounded-concurrency pool
+        results.set(url, await probe(url));
+      }
+    }
+  };
+  await Promise.all(
+    Array.from(
+      { length: Math.min(EXTERNAL_CONCURRENCY, unique.length) },
+      worker
+    )
+  );
+
+  const diagnostics: Diagnostic[] = [];
+  for (const ref of refs) {
+    const result = results.get(ref.url);
+    const grade = result ? gradeExternal(result) : null;
+    if (grade) {
+      diagnostics.push({
+        code: "BLUME_DEAD_LINK",
+        column: ref.column,
+        file: ref.file,
+        line: ref.line,
+        message: `External link ${ref.url} is unreachable (${grade.detail}).`,
+        severity: grade.severity,
+      });
+    }
+  }
+  return diagnostics;
+};
+
+/** Classify a single link, queueing external refs via `onExternal`. */
+const classifyLink = (
+  page: PageRecord,
+  link: PageLink,
+  ctx: LinkContext,
+  onExternal: (ref: ExternalRef) => void
+): LinkResult => {
+  const { target } = link;
+  const site: LinkSite = {
+    column: link.column,
+    file: page.sourcePath ?? page.id,
+    line: link.line,
+  };
+
+  if (HTTP.test(target) || PROTOCOL_RELATIVE.test(target)) {
+    onExternal({
+      ...site,
+      url: PROTOCOL_RELATIVE.test(target) ? `https:${target}` : target,
+    });
+    return null;
+  }
+  if (SCHEME.test(target)) {
+    // mailto:, tel:, and other non-HTTP schemes are not validated.
+    return null;
+  }
+
+  const hashIndex = target.indexOf("#");
+  const fragment = hashIndex === -1 ? "" : target.slice(hashIndex + 1);
+  let rawPath = hashIndex === -1 ? target : target.slice(0, hashIndex);
+  const queryIndex = rawPath.indexOf("?");
+  if (queryIndex !== -1) {
+    rawPath = rawPath.slice(0, queryIndex);
+  }
+
+  if (rawPath === "") {
+    return fragment ? checkAnchor(page.route, fragment, site, ctx) : null;
+  }
+
+  const resolved = rawPath.startsWith("/")
+    ? rawPath
+    : resolveRelative(page.route, rawPath);
+  return checkPathLink(resolved, fragment, target, site, ctx);
+};
+
+/**
+ * Validate every link discovered in the content graph: internal page links and
+ * anchors against the route map, asset links against the public dir, and
+ * (opt-in) external links over the network.
+ */
+export const validateLinks = async (
+  graph: ContentGraph,
+  options: { publicDir: string | null; checkExternal?: boolean }
+): Promise<Diagnostic[]> => {
+  const ctx: LinkContext = {
+    anchors: buildAnchorIndex(graph.pages),
+    publicDir: options.publicDir,
+    routes: new Set(graph.routes.keys()),
+  };
+  const diagnostics: Diagnostic[] = [];
+  const external: ExternalRef[] = [];
+  let uncheckedAssets = 0;
+
+  for (const page of graph.pages) {
+    for (const link of page.links) {
+      const result = classifyLink(page, link, ctx, (ref) => external.push(ref));
+      if (result === "asset-unchecked") {
+        uncheckedAssets += 1;
+      } else if (result) {
+        diagnostics.push(result);
+      }
+    }
+  }
+
+  if (uncheckedAssets > 0) {
+    diagnostics.push({
+      code: "BLUME_ASSETS_UNCHECKED",
+      message: `${uncheckedAssets} asset link(s) not checked: no public/ directory found.`,
+      severity: "info",
+    });
+  }
+
+  if (options.checkExternal && external.length > 0) {
+    diagnostics.push(...(await checkExternalLinks(external)));
+  }
+
+  return diagnostics;
+};

package/src/core/load-module.ts

@@ -0,0 +1,15 @@
+import { createJiti } from "jiti";
+
+/**
+ * Create a loader for user-authored ESM/TS modules (`blume.config.ts`,
+ * `meta.ts`). One jiti instance is reused across every file the returned loader
+ * is called with. `moduleCache: false` ensures edits are picked up on each load,
+ * which is what makes dev-server regeneration reflect config/meta changes.
+ */
+export const createModuleLoader = (): ((file: string) => Promise<unknown>) => {
+  const jiti = createJiti(import.meta.url, { moduleCache: false });
+  return async (file: string) => {
+    const loaded = await jiti.import<{ default?: unknown }>(file);
+    return loaded?.default ?? loaded;
+  };
+};

package/src/core/manifest.ts

@@ -0,0 +1,126 @@
+import { localizeRoute, resolveFallbackLocale } from "./i18n.ts";
+import type { ResolvedConfig } from "./schema.ts";
+import type {
+  BlumeManifest,
+  ContentGraph,
+  PageRecord,
+  ProjectContext,
+  RouteAlternate,
+  RouteManifestEntry,
+} from "./types.ts";
+import { getBlumeVersion } from "./version.ts";
+
+/** The current manifest schema version. */
+export const MANIFEST_VERSION = 1;
+
+/**
+ * Whether a page may be indexed on its own merits — not author-excluded and not
+ * hidden (unless hidden pages are opted in). This is independent of whether the
+ * site search provider is enabled, so features like the MCP server can index
+ * docs even when on-page search is off.
+ */
+export const contentIndexable = (
+  page: PageRecord,
+  config: ResolvedConfig
+): boolean =>
+  !page.meta.search.exclude &&
+  (!page.meta.sidebar.hidden || config.search.indexing.includeHiddenPages);
+
+/** Build the runtime manifest that bridges core and the generated Astro app. */
+export const buildManifest = (options: {
+  context: ProjectContext;
+  config: ResolvedConfig;
+  graph: ContentGraph;
+}): BlumeManifest => {
+  const { context, config, graph } = options;
+  const searchEnabled = config.search.provider !== "none";
+  const { i18n } = config;
+
+  // Real translations per logical page, for `hreflang` and the switcher. Built
+  // only under i18n; a single-locale page has no alternates.
+  const alternatesByKey = new Map<string, RouteAlternate[]>();
+  if (i18n) {
+    for (const page of graph.pages) {
+      const list = alternatesByKey.get(page.translationKey) ?? [];
+      list.push({ locale: page.locale, path: page.route });
+      alternatesByKey.set(page.translationKey, list);
+    }
+  }
+
+  const routes: RouteManifestEntry[] = graph.pages.map((page) => ({
+    alternates: alternatesByKey.get(page.translationKey) ?? [],
+    collection: page.collection ?? "docs",
+    contentType: page.contentType,
+    draft: page.meta.draft,
+    editUrl: page.editUrl,
+    entryId: page.entryId ?? page.source.ref,
+    hidden: page.meta.sidebar.hidden,
+    id: page.id,
+    indexable: searchEnabled && contentIndexable(page, config),
+    lastModified: page.lastModified,
+    locale: page.locale,
+    path: page.route,
+    source: page.source,
+    sourcePath: page.sourcePath,
+    title: page.title,
+  }));
+
+  // Fallback materialization: render the fallback locale's content at the
+  // localized URL for any translation a non-default locale is missing, so static
+  // output is fully prerendered (render-fallback, no client redirect). Fallback
+  // routes are not indexed and carry no `hreflang` of their own.
+  if (i18n) {
+    const fallback = resolveFallbackLocale(i18n);
+    if (fallback) {
+      const fallbackPages = new Map(
+        graph.pages
+          .filter((page) => page.locale === fallback)
+          .map((page) => [page.translationKey, page] as const)
+      );
+      for (const { code } of i18n.locales) {
+        if (code === fallback) {
+          continue;
+        }
+        const present = new Set(
+          graph.pages
+            .filter((page) => page.locale === code)
+            .map((page) => page.translationKey)
+        );
+        for (const [key, source] of fallbackPages) {
+          if (present.has(key)) {
+            continue;
+          }
+          routes.push({
+            alternates: alternatesByKey.get(key) ?? [],
+            collection: source.collection ?? "docs",
+            contentType: source.contentType,
+            draft: source.meta.draft,
+            editUrl: source.editUrl,
+            entryId: source.entryId ?? source.source.ref,
+            fallback: true,
+            hidden: source.meta.sidebar.hidden,
+            id: source.id,
+            indexable: false,
+            lastModified: source.lastModified,
+            locale: code,
+            path: localizeRoute(key, code, i18n),
+            source: source.source,
+            sourcePath: source.sourcePath,
+            title: source.title,
+          });
+        }
+      }
+    }
+  }
+
+  routes.sort((a, b) => a.path.localeCompare(b.path));
+
+  return {
+    blumeVersion: getBlumeVersion(),
+    contentRoot: context.contentRoot,
+    output: config.deployment.output,
+    projectRoot: context.root,
+    routes,
+    version: MANIFEST_VERSION,
+  };
+};

package/src/core/meta.ts

@@ -0,0 +1,97 @@
+import { basename, dirname, relative } from "pathe";
+import { glob } from "tinyglobby";
+
+import { diagnosticsFromZod } from "./diagnostics.ts";
+import { createModuleLoader } from "./load-module.ts";
+import { folderMetaSchema } from "./schema.ts";
+import type { FolderMeta } from "./schema.ts";
+import type { Diagnostic } from "./types.ts";
+
+const META_FILES = [
+  "**/meta.ts",
+  "**/meta.js",
+  "**/meta.mjs",
+  // Shared, locale-agnostic folder meta (applies to every locale).
+  "**/meta.$.ts",
+  "**/meta.$.js",
+  "**/meta.$.mjs",
+];
+
+/** Resolve a meta module's default export, calling it if it is a factory. */
+const resolveMeta = async (mod: unknown): Promise<unknown> =>
+  typeof mod === "function" ? await (mod as () => unknown)() : mod;
+
+/**
+ * Discover `meta.{ts,js,mjs}` files under the content root. Keys are the
+ * directory path relative to the content root (`""` for the root directory).
+ * `meta.$.*` files are returned in `shared` — folder meta that applies to that
+ * directory in every locale (a locale-specific `meta.*` overrides it). Each file
+ * default-exports an object or a (sync/async) function returning one.
+ */
+export const discoverFolderMeta = async (
+  contentRoot: string
+): Promise<{
+  meta: Map<string, FolderMeta>;
+  shared: Map<string, FolderMeta>;
+  diagnostics: Diagnostic[];
+}> => {
+  const files = await glob(META_FILES, {
+    absolute: true,
+    cwd: contentRoot,
+    // Never descend into dependencies or build output — relevant when the
+    // content root is the project root (e.g. a migrated Mintlify project).
+    ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
+    onlyFiles: true,
+  });
+
+  const load = createModuleLoader();
+  const loaded = await Promise.all(
+    files.map(
+      async (
+        file
+      ): Promise<
+        | { ok: true; file: string; value: unknown }
+        | { ok: false; file: string; error: Error }
+      > => {
+        try {
+          return { file, ok: true, value: await resolveMeta(await load(file)) };
+        } catch (error) {
+          return { error: error as Error, file, ok: false };
+        }
+      }
+    )
+  );
+
+  const meta = new Map<string, FolderMeta>();
+  const shared = new Map<string, FolderMeta>();
+  const diagnostics: Diagnostic[] = [];
+
+  for (const entry of loaded) {
+    const dir = relative(contentRoot, dirname(entry.file));
+
+    if (!entry.ok) {
+      diagnostics.push({
+        code: "BLUME_META_LOAD_FAILED",
+        file: entry.file,
+        message: `Could not load meta file: ${entry.error.message}`,
+        severity: "error",
+      });
+      continue;
+    }
+
+    const result = folderMetaSchema.safeParse(entry.value);
+    if (result.success) {
+      const target = basename(entry.file).startsWith("meta.$.") ? shared : meta;
+      target.set(dir, result.data);
+    } else {
+      diagnostics.push(
+        ...diagnosticsFromZod(result.error, {
+          code: "BLUME_META_INVALID",
+          file: entry.file,
+        })
+      );
+    }
+  }
+
+  return { diagnostics, meta, shared };
+};