blume 1.7.3 → 2.0.0

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 --claude` (or `--codex`) 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,