blume 1.7.3 → 2.0.1

package/src/sources/registry.ts

@@ -0,0 +1,182 @@
+import { z } from "zod";
+
+import { contentful, contentfulAdapterSchema } from "./contentful.ts";
+import type { ContentfulAdapter } from "./contentful.ts";
+import { custom, customAdapterSchema } from "./custom.ts";
+import type { CustomAdapter } from "./custom.ts";
+import { filesystem, filesystemAdapterSchema } from "./filesystem.ts";
+import type { FilesystemAdapter } from "./filesystem.ts";
+import {
+  githubReleases,
+  githubReleasesAdapterSchema,
+} from "./github-releases.ts";
+import type { GithubReleasesAdapter } from "./github-releases.ts";
+import { mdxRemote, mdxRemoteAdapterSchema } from "./mdx-remote.ts";
+import type { MdxRemoteAdapter } from "./mdx-remote.ts";
+import { notion, notionAdapterSchema } from "./notion.ts";
+import type { NotionAdapter } from "./notion.ts";
+import { obsidian, obsidianAdapterSchema } from "./obsidian.ts";
+import type { ObsidianAdapter } from "./obsidian.ts";
+import { payload, payloadAdapterSchema } from "./payload.ts";
+import type { PayloadAdapter } from "./payload.ts";
+import { sanity, sanityAdapterSchema } from "./sanity.ts";
+import type { SanityAdapter } from "./sanity.ts";
+import { strapi, strapiAdapterSchema } from "./strapi.ts";
+import type { StrapiAdapter } from "./strapi.ts";
+
+/** Every descriptor a `blume/sources` factory can return. */
+export type AnySourceAdapter =
+  | FilesystemAdapter
+  | MdxRemoteAdapter
+  | GithubReleasesAdapter
+  | SanityAdapter
+  | NotionAdapter
+  | ContentfulAdapter
+  | PayloadAdapter
+  | StrapiAdapter
+  | ObsidianAdapter
+  | CustomAdapter;
+
+/** Every adapter identity. */
+export type SourceAdapterKind = AnySourceAdapter["kind"];
+
+/** One variant per public adapter factory. */
+const adapterVariants = [
+  filesystemAdapterSchema,
+  mdxRemoteAdapterSchema,
+  githubReleasesAdapterSchema,
+  sanityAdapterSchema,
+  notionAdapterSchema,
+  contentfulAdapterSchema,
+  payloadAdapterSchema,
+  strapiAdapterSchema,
+  obsidianAdapterSchema,
+  customAdapterSchema,
+] as const;
+
+const sourceAdapterUnion = z.discriminatedUnion("kind", adapterVariants);
+
+/** What a public factory returns, as the config schema accepts it. */
+export type SourceAdapterInput = z.input<typeof sourceAdapterUnion>;
+
+/**
+ * A validated descriptor: the adapter's options with their defaults applied
+ * (a `filesystem()` entry always carries `root`/`include`/`exclude`), and the
+ * metadata lists re-derived from the factory so every consumer reads the
+ * `runtimeDeps` and `requiredSecrets` this version of Blume ships.
+ */
+export type ContentSourceAdapter = z.output<typeof sourceAdapterUnion>;
+
+/** The factory name the 1.x `type` discriminator maps to, for the hint below. */
+const FACTORY_FOR_TYPE = new Map([
+  ["custom", "custom"],
+  ["filesystem", "filesystem"],
+  ["github-releases", "githubReleases"],
+  ["mdx-remote", "mdxRemote"],
+  ["notion", "notion"],
+  ["obsidian", "obsidian"],
+  ["sanity", "sanity"],
+]);
+
+const FACTORIES_HINT =
+  'content.sources takes adapters imported from "blume/sources" — filesystem({ root }), mdxRemote({ github }), githubReleases({ owner, repo }), sanity({ projectId, dataset, query }), notion({ database }), contentful({ space, contentType }), payload({ url, collection }), strapi({ url, contentType }), obsidian({ vault }), or custom(source).';
+
+const ARRAY_HINT = `content.sources is a list of adapters — e.g. \`sources: [filesystem({ root: "docs" }), githubReleases({ owner, repo, prefix: "changelog" })]\`, imported from "blume/sources".`;
+
+const isObjectLike = (value: unknown): value is object =>
+  typeof value === "object" && value !== null;
+
+/** The 1.x object form's discriminator, when an entry carries one. */
+const legacyEntrySchema = z.looseObject({ type: z.string() });
+
+/**
+ * The message for an entry that is not a descriptor. A 1.x `{ type: "…" }`
+ * object names the factory that replaces it, so the fix is a rename plus
+ * moving the remaining fields into the call.
+ */
+const entryHint = (type: string | undefined): string => {
+  if (type === undefined) {
+    return FACTORIES_HINT;
+  }
+  const factory = FACTORY_FOR_TYPE.get(type);
+  if (!factory) {
+    return `${FACTORIES_HINT} The 1.x { type: "${type}" } object form was removed.`;
+  }
+  const call =
+    type === "custom"
+      ? "custom(source) with the source you passed as `source`"
+      : `${factory}({ … }) with the other fields as its options`;
+  return `${FACTORIES_HINT} The 1.x { type: "${type}", … } object was removed: replace it with ${call}.`;
+};
+
+/**
+ * Validates a descriptor a factory returned and resolves it to the canonical
+ * form, so a descriptor that went through JSON (or was edited by hand)
+ * resolves to the same metadata Blume ships.
+ */
+export const resolvedSourceAdapterSchema = sourceAdapterUnion.transform(
+  (value): ContentSourceAdapter => {
+    switch (value.kind) {
+      case "filesystem": {
+        return { ...filesystem(value.options), options: value.options };
+      }
+      case "github-releases": {
+        return { ...githubReleases(value.options), options: value.options };
+      }
+      case "mdx-remote": {
+        return { ...mdxRemote(value.options), options: value.options };
+      }
+      case "notion": {
+        return { ...notion(value.options), options: value.options };
+      }
+      case "contentful": {
+        return { ...contentful(value.options), options: value.options };
+      }
+      case "payload": {
+        return { ...payload(value.options), options: value.options };
+      }
+      case "strapi": {
+        return { ...strapi(value.options), options: value.options };
+      }
+      case "obsidian": {
+        return { ...obsidian(value.options), options: value.options };
+      }
+      case "sanity": {
+        return { ...sanity(value.options), options: value.options };
+      }
+      default: {
+        // Only `custom` is left, and TypeScript has narrowed `value` to it.
+        // It returns after the switch rather than from a last case block:
+        // Bun 1.4.0's line coverage never credits the closing brace of a
+        // switch's final block, which would fail the 100% gate in CI.
+        break;
+      }
+    }
+    return custom(value.options);
+  }
+);
+
+/**
+ * One `content.sources` entry. Anything without a `kind` — the 1.x `{ type }`
+ * object, a string, `null` — fails here with the factory hint instead of the
+ * union's opaque "invalid discriminator" message.
+ */
+const sourceEntrySchema = z
+  .custom<SourceAdapterInput>(
+    (value) => isObjectLike(value) && "kind" in value,
+    {
+      error: (issue) => {
+        const legacy = legacyEntrySchema.safeParse(issue.input);
+        return entryHint(legacy.success ? legacy.data.type : undefined);
+      },
+    }
+  )
+  .pipe(resolvedSourceAdapterSchema);
+
+/**
+ * `content.sources`: the adapters to read, in order. A non-array (the 1.x
+ * object form, say) fails with the list hint; entry errors keep their own.
+ */
+export const contentSourcesSchema = z.array(sourceEntrySchema, {
+  error: (issue) => (issue.code === "invalid_type" ? ARRAY_HINT : undefined),
+});

package/src/sources/sanity.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { SharedSourceOptions } from "./shared.ts";
+import { sharedSourceOptionsSchema } from "./shared.ts";
+
+/** Options for {@link sanity}. */
+export interface SanityOptions extends SharedSourceOptions {
+  /** Sanity API version (a date). Defaults to `2024-01-01`. */
+  apiVersion?: string;
+  /** Dataset name to query. */
+  dataset: string;
+  /** Field paths mapping a document onto Blume meta + body. */
+  fields?: {
+    /** Field holding the renderable body (Portable Text or Markdown). */
+    body?: string;
+    /** Field holding the page description. */
+    description?: string;
+    /** Field holding the last-modified date. */
+    lastModified?: string;
+    /** Field holding the page slug. */
+    slug?: string;
+    /** Field holding the page title. */
+    title?: string;
+  };
+  /** Sanity project id. */
+  projectId: string;
+  /** GROQ query selecting the documents to import. */
+  query: string;
+}
+
+export const sanityOptionsSchema = sharedSourceOptionsSchema.extend({
+  apiVersion: z.string().optional(),
+  dataset: z.string(),
+  fields: z
+    .strictObject({
+      body: z.string().optional(),
+      description: z.string().optional(),
+      lastModified: z.string().optional(),
+      slug: z.string().optional(),
+      title: z.string().optional(),
+    })
+    .optional(),
+  projectId: z.string(),
+  query: z.string(),
+});
+
+export type SanityAdapter = AdapterDescriptor<"sanity", SanityOptions>;
+
+export const sanityAdapterSchema = adapterDescriptorSchema(
+  "sanity",
+  sanityOptionsSchema
+);
+
+/**
+ * A Sanity dataset queried with GROQ; Portable Text bodies become Markdown.
+ * `@sanity/client` is the declared runtime dependency, and a private dataset's
+ * read token comes from `SANITY_TOKEN`.
+ */
+export const sanity = (options: SanityOptions): SanityAdapter => ({
+  kind: "sanity",
+  options,
+  requiredSecrets: ["SANITY_TOKEN"],
+  runtimeDeps: ["@sanity/client"],
+});

package/src/sources/shared.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+
+/** The glob every content-reading adapter defaults `include` to. */
+export const DEFAULT_CONTENT_GLOB = "**/*.{md,mdx}";
+
+/**
+ * Options every built-in content source shares. They ride on the descriptor
+ * beside the adapter's own options, so an adapter declares only what is
+ * specific to it.
+ */
+export interface SharedSourceOptions {
+  /**
+   * Opt-in dev polling interval (seconds) for a remote source; omit to fetch
+   * once and freeze for the session. Local sources (`filesystem()`,
+   * `obsidian()`) watch the filesystem instead and ignore it.
+   */
+  pollInterval?: number;
+  /** Namespaces the source's routes under `/<prefix>/`. */
+  prefix?: string;
+}
+
+/** The schema for {@link SharedSourceOptions}; each adapter extends it. */
+export const sharedSourceOptionsSchema = z.strictObject({
+  pollInterval: z.number().positive().optional(),
+  prefix: z.string().optional(),
+});
+
+/** Field paths mapping a CMS document onto Blume meta + body. */
+export interface SourceFieldMap {
+  /** Field holding the renderable body (rich text, or a Markdown string). */
+  body?: string;
+  /** Field holding the page description. */
+  description?: string;
+  /** Field holding the last-modified date. */
+  lastModified?: string;
+  /** Field holding the page slug. */
+  slug?: string;
+  /** Field holding the page title. */
+  title?: string;
+}
+
+/** The schema for {@link SourceFieldMap}. */
+export const sourceFieldMapSchema = z.strictObject({
+  body: z.string().optional(),
+  description: z.string().optional(),
+  lastModified: z.string().optional(),
+  slug: z.string().optional(),
+  title: z.string().optional(),
+});
+
+/** Extra query parameters a REST-backed adapter appends to its request. */
+export const queryParamsSchema = z.record(z.string(), z.string());

package/src/sources/strapi.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { SharedSourceOptions, SourceFieldMap } from "./shared.ts";
+import {
+  queryParamsSchema,
+  sharedSourceOptionsSchema,
+  sourceFieldMapSchema,
+} from "./shared.ts";
+
+/** Options for {@link strapi}. */
+export interface StrapiOptions extends SharedSourceOptions {
+  /** The content type's plural API id (`articles`). */
+  contentType: string;
+  /**
+   * Field paths mapping an entry onto Blume meta + body. Defaults to
+   * `title` / `description` / `slug` / `content` / `updatedAt`.
+   */
+  fields?: SourceFieldMap;
+  /** Locale code to fetch, for a localized content type. */
+  locale?: string;
+  /** Extra query parameters for the request (`"filters[section][$eq]": "sdk"`). */
+  params?: Record<string, string>;
+  /** The `populate` parameter. Defaults to `*`, which fills media and relations. */
+  populate?: string;
+  /** The Strapi origin (`https://cms.acme.dev`); its REST API is at `/api`. */
+  url: string;
+}
+
+export const strapiOptionsSchema = sharedSourceOptionsSchema.extend({
+  contentType: z.string(),
+  fields: sourceFieldMapSchema.optional(),
+  locale: z.string().optional(),
+  params: queryParamsSchema.optional(),
+  populate: z.string().optional(),
+  url: z.string(),
+});
+
+export type StrapiAdapter = AdapterDescriptor<"strapi", StrapiOptions>;
+
+export const strapiAdapterSchema = adapterDescriptorSchema(
+  "strapi",
+  strapiOptionsSchema
+);
+
+/**
+ * A Strapi content type read through its REST API; Blocks bodies become
+ * Markdown. The API token comes from `STRAPI_API_TOKEN`, and `--preview`
+ * reads drafts. Nothing to install: the adapter speaks the REST API
+ * directly.
+ */
+export const strapi = (options: StrapiOptions): StrapiAdapter => ({
+  kind: "strapi",
+  options,
+  requiredSecrets: ["STRAPI_API_TOKEN"],
+  runtimeDeps: [],
+});

package/src/theme/entry.ts

@@ -8,6 +8,9 @@ import { CODE_PADDING_BLOCK_REM } from "./code-block-padding.ts";
  */
 const CODE_SCROLL_INSET_REM = 0.375;
 
+/** Lucide's arrow-up-right (the featured-link icon) as a `mask` data URI. */
+const EXTERNAL_LINK_MASK = `url("data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#000" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"><path d="M7 7h10v10M7 17L17 7"/></svg>')}")`;
+
 interface TailwindEntryOptions {
   /**
    * Globs to scan for utility classes. Typically the Blume package source and
@@ -274,10 +277,13 @@ ${THEME_MAPPING}
   @apply -my-1 flex flex-1 items-center gap-1.5 rounded py-1 transition-colors aria-[current=page]:text-foreground aria-[current=page]:font-semibold;
 }
 @utility blume-nav-heading {
-  @apply mb-2 flex items-center gap-1.5 px-2.5 font-medium text-foreground text-sm;
+  @apply mb-1 flex items-center gap-1.5 px-2.5 py-1.5 font-medium text-foreground text-sm;
 }
+/* The linked heading fills the heading's own box with negative margins, so
+   its hover/active pill is the page row's exactly (same padding and radius)
+   and an unlinked heading beside it keeps the same text position. */
 @utility blume-nav-heading-link {
-  @apply -ml-1 flex flex-1 items-center gap-1.5 rounded-[0.65rem] px-1 py-0.5 text-foreground transition-colors hover:bg-muted aria-[current=page]:bg-muted;
+  @apply -mx-2.5 -my-1.5 flex flex-1 items-center gap-1.5 rounded-[0.65rem] px-2.5 py-1.5 text-foreground transition-colors hover:bg-muted aria-[current=page]:bg-muted;
 }
 
 /* Theme Tailwind Typography (prose) with Blume tokens. */
@@ -413,6 +419,22 @@ ${THEME_MAPPING}
   text-decoration: none;
 }
 
+/* External Markdown links (markdown.externalLinks) open in a new tab and trail
+   the same Lucide arrow-up-right the featured sidebar links use, as a mask so it
+   takes the link's color. A link wrapping only an image (a badge, a logo)
+   skips the arrow. */
+.prose :where(a[data-blume-external]:not(:has(img, svg)))::after {
+  background-color: currentColor;
+  content: "";
+  display: inline-block;
+  height: 0.75em;
+  margin-inline-start: 0.125em;
+  -webkit-mask: ${EXTERNAL_LINK_MASK} center / contain no-repeat;
+  mask: ${EXTERNAL_LINK_MASK} center / contain no-repeat;
+  opacity: 0.6;
+  width: 0.75em;
+}
+
 .prose :where(hr) {
   margin: 2.5rem 0;
 }

package/src/translate/report.ts

@@ -137,26 +137,57 @@ export const diagnosticLines = (diagnostics: Diagnostic[]): string[] =>
     (diagnostic) => `  ${colors.yellow("⚠")} ${colors.dim(diagnostic.message)}`
   );
 
+/** One (source, locale) pair a `--check` run flags. */
+interface DriftRow {
+  /** Absolute path of the default-locale source. */
+  file: string;
+  locale: string;
+  sourceRel: string;
+  status: WorkStatus;
+}
+
 /** Every (source, locale, status) drift row in a work list, pages then meta. */
-const driftRows = (
-  workList: TranslateWorkList
-): { locale: string; sourceRel: string; status: WorkStatus }[] =>
+const driftRows = (workList: TranslateWorkList): DriftRow[] =>
   workList.items.flatMap((item) =>
     item.kind === "page"
       ? [
           {
+            file: item.sourcePath,
             locale: item.locale,
             sourceRel: item.sourceRel,
             status: item.status,
           },
         ]
       : item.entries.map((entry: MetaWorkEntry) => ({
+          file: entry.meta.file,
           locale: item.locale,
           sourceRel: entry.meta.sourceRel,
           status: entry.status,
         }))
   );
 
+/**
+ * Each missing or stale translation as an error diagnostic, so the `--check`
+ * JSON's `summary` counts the drift that fails the gate — the exit-code
+ * contract `blume validate/audit/eval --json` keep, where a non-zero exit
+ * always shows as a non-zero `summary.error`.
+ */
+const driftDiagnostics = (workList: TranslateWorkList): Diagnostic[] =>
+  driftRows(workList).map((row) => ({
+    code:
+      row.status === "missing"
+        ? "BLUME_TRANSLATE_MISSING"
+        : "BLUME_TRANSLATE_STALE",
+    file: row.file,
+    message:
+      row.status === "missing"
+        ? `${row.sourceRel} has no "${row.locale}" translation.`
+        : `The "${row.locale}" translation of ${row.sourceRel} is stale: its source changed since it was translated.`,
+    severity: "error",
+    suggestion:
+      "Run `blume translate --codex` (or `--claude`) to bring the translations up to date.",
+  }));
+
 /** One line per missing/stale pair, plus dim lines for untracked adoptions. */
 export const checkLines = (workList: TranslateWorkList): string[] => [
   ...driftRows(workList).map(
@@ -191,10 +222,12 @@ export const hasDrift = (workList: TranslateWorkList): boolean =>
 
 /**
  * The machine-readable `--check` report. The `diagnostics` + `summary` shape
- * matches `blume validate/audit/eval --json` exactly, with the drift report
- * under `translate`.
+ * matches `blume validate/audit/eval --json` exactly — every missing or stale
+ * translation is an error diagnostic there, so `summary.error` agrees with the
+ * exit code — with the drift report grouped by locale under `translate`.
  */
 export const checkReportJson = (workList: TranslateWorkList): string => {
+  const diagnostics = [...workList.diagnostics, ...driftDiagnostics(workList)];
   const locales: Record<
     string,
     { missing: string[]; stale: string[]; untracked: string[] }
@@ -210,8 +243,8 @@ export const checkReportJson = (workList: TranslateWorkList): string => {
   }
   return `${JSON.stringify(
     {
-      diagnostics: workList.diagnostics,
-      summary: countBySeverity(workList.diagnostics),
+      diagnostics,
+      summary: countBySeverity(diagnostics),
       translate: { locales, upToDate: workList.upToDate },
     },
     null,