blume 1.4.2 → 1.5.0

package/src/search/orama-index.ts

@@ -1,5 +1,10 @@
 import { create, insertMultiple, search } from "@orama/orama";
-import type { AnyOrama, Tokenizer } from "@orama/orama";
+import type {
+  AnyOrama,
+  EnumArrComparisonOperator,
+  EnumComparisonOperator,
+  Tokenizer,
+} from "@orama/orama";
 
 /**
  * The minimal document shape both the client-side search dialog and the
@@ -13,6 +18,11 @@ export interface OramaDoc {
   title: string;
   /** Locale code; indexed as an enum so queries can filter to one language. */
   locale?: string;
+  /**
+   * Docs version; indexed as an enum so queries can filter to one version.
+   * The current docs carry `""`, which the enum stores and matches exactly.
+   */
+  version?: string;
   /** Resolved page `type`; indexed as an enum so queries can filter by type. */
   contentType?: string;
   /** Declared facet values (`content.types.<type>.facets`), key → value. */
@@ -35,6 +45,7 @@ const SCHEMA = {
   locale: "enum",
   route: "string",
   title: "string",
+  version: "enum",
 } as const;
 
 /** Flatten a facet map to the `key:value` terms the `facetTerms` enum holds. */
@@ -79,6 +90,23 @@ const BIGRAM_LANGUAGES = new Set(["ja", "zh"]);
 const BIGRAM_SCRIPTS =
   /^[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}々〆〇ーﾞﾟ]+$/u;
 
+/**
+ * One index term inside a word-like segment. Being word-like does not make a
+ * segment all letters: UAX #29 keeps connector punctuation, format characters
+ * and mid-number punctuation *within* a word, so `Intl.Segmenter` reports
+ * スネーク_ケース and robots.txt as one segment each. A term is a run of
+ * letters, combining marks and digits. Marks are spelling, not punctuation —
+ * Thai writes vowels and tones as combining marks, so dropping them leaves
+ * consonant skeletons that collapse distinct words (เสื้อ, shirt, and เสือ,
+ * tiger, differ by one mark). Two separators stay where the surrounding text
+ * makes them part of the word: an apostrophe followed by a letter (don't),
+ * and a decimal point or thousands separator flanked by digits (1.0.3,
+ * 1,000) — split, either would leave one-letter and one-digit fragments that
+ * co-occur on unrelated pages.
+ */
+const TERM =
+  /[\p{L}\p{M}\p{N}]+(?:(?:['’](?=\p{L})|(?<=\p{N})[.,](?=\p{N}))[\p{L}\p{M}\p{N}]+)*/gu;
+
 /**
  * Emit every overlapping 2-character window of `run`, or the lone character.
  * Windows are cut by code point: an ideograph outside the basic plane is a
@@ -109,8 +137,10 @@ const addBigrams = (run: string, tokens: Set<string>): void => {
 /**
  * A word-segmenting tokenizer for languages the default splitter can't handle,
  * built on `Intl.Segmenter` (the same engine `@orama/tokenizers` wraps).
- * Input is lowercased before segmenting — unlike the upstream tokenizers —
- * so Latin terms ("GDPR", English pages on a mixed-locale site) still match
+ * Input is NFC-normalized and lowercased before segmenting — unlike the
+ * upstream tokenizers — so decomposed text (macOS filenames, some CMS
+ * pipelines) indexes the same terms a composed query produces, and Latin
+ * terms ("GDPR", English pages on a mixed-locale site) still match
  * case-insensitively. Returns `undefined` for languages the default tokenizer
  * already serves, and on runtimes without `Intl.Segmenter`, where the caller
  * falls back to Orama's default.
@@ -118,16 +148,24 @@ const addBigrams = (run: string, tokens: Set<string>): void => {
  * On a {@link BIGRAM_LANGUAGES} index, runs of adjacent
  * {@link BIGRAM_SCRIPTS} segments are joined and re-cut into character
  * bigrams; everything else (Latin, digits, and every segment on a Korean or
- * Thai index) is emitted as the segmenter produced it. Punctuation and spaces
- * are not word-like, so they end a run — 「クーリング・オフ」 bigrams either
- * side of the interpunct rather than across it.
+ * Thai index) is emitted one {@link TERM} at a time. Separators end a run
+ * either way — whether they stand between segments, as 「クーリング・オフ」
+ * does, or inside one.
+ */
+/**
+ * `Intl.Segmenter` is missing on some runtimes even though the lib type
+ * declares it, so the constructor's presence is probed before use.
  */
+const hasSegmenter = (
+  segmenter: typeof Intl.Segmenter | undefined
+): segmenter is typeof Intl.Segmenter => typeof segmenter === "function";
+
 const segmentingTokenizer = (locale?: string): Tokenizer | undefined => {
   const language = locale?.toLowerCase().split(/[-_]/u)[0] ?? "";
   if (!SEGMENTED_LANGUAGES.has(language)) {
     return;
   }
-  if (typeof Intl.Segmenter !== "function") {
+  if (!hasSegmenter(Intl.Segmenter)) {
     return;
   }
   const segmenter = new Intl.Segmenter(language, { granularity: "word" });
@@ -146,17 +184,35 @@ const segmentingTokenizer = (locale?: string): Tokenizer | undefined => {
           run = "";
         }
       };
-      for (const segment of segmenter.segment(raw.toLowerCase())) {
+      const take = (term: string): void => {
+        if (bigram && BIGRAM_SCRIPTS.test(term)) {
+          run += term;
+          return;
+        }
+        flush();
+        tokens.add(term);
+      };
+      for (const segment of segmenter.segment(
+        raw.normalize("NFC").toLowerCase()
+      )) {
         if (!segment.isWordLike) {
           flush();
           continue;
         }
-        if (bigram && BIGRAM_SCRIPTS.test(segment.segment)) {
-          run += segment.segment;
-          continue;
+        let end = 0;
+        for (const match of segment.segment.matchAll(TERM)) {
+          // A gap means punctuation stood there, which ends the run as surely
+          // as a non-word-like segment would: スネーク_ケース pairs either side
+          // of the connector, never across it.
+          if (match.index > end) {
+            flush();
+          }
+          take(match[0]);
+          end = match.index + match[0].length;
+        }
+        if (end < segment.segment.length) {
+          flush();
         }
-        flush();
-        tokens.add(segment.segment);
       }
       flush();
       return [...tokens];
@@ -171,17 +227,18 @@ const segmentingTokenizer = (locale?: string): Tokenizer | undefined => {
  * `i18n.defaultLocale` — swaps in a word-segmenting tokenizer for languages
  * written without spaces (Japanese, Chinese, Korean, Thai); the tokenizer
  * belongs to the database, so on a mixed-locale site it applies to every
- * document, which is safe because Latin words survive segmentation intact.
+ * document, which is safe because words in other scripts — Latin, and
+ * mark-bearing scripts like Hebrew or Devanagari — survive segmentation
+ * intact.
  */
 export const buildOramaIndex = async (
   documents: OramaDoc[],
   locale?: string
 ): Promise<AnyOrama> => {
   const tokenizer = segmentingTokenizer(locale);
-  const db = create({
-    schema: SCHEMA,
-    ...(tokenizer ? { components: { tokenizer } } : {}),
-  });
+  const db = tokenizer
+    ? create({ components: { tokenizer }, schema: SCHEMA })
+    : create({ schema: SCHEMA });
   await insertMultiple(
     db,
     documents.map((doc) =>
@@ -205,6 +262,23 @@ export interface OramaQueryFilters {
   facets?: Record<string, string>;
   /** Keep only documents in this locale. */
   locale?: string;
+  /**
+   * Keep only documents of this docs version (`""` is the current docs — a
+   * meaningful filter value, so absence alone disables version filtering).
+   */
+  version?: string;
+}
+
+/**
+ * The exact-match `where` clause the filters compile to. Orama types `where`
+ * openly (any schema property to an operator), mirrored here by the index
+ * signature; this module only ever emits the two enum operators.
+ */
+interface OramaWhereClause {
+  [property: string]:
+    | EnumArrComparisonOperator
+    | EnumComparisonOperator
+    | undefined;
 }
 
 /**
@@ -226,27 +300,38 @@ export const queryOramaIndex = async (
   filters?: OramaQueryFilters
 ): Promise<OramaDoc[]> => {
   const facetTerms = filters?.facets ? toFacetTerms(filters.facets) : [];
-  const where = {
-    ...(filters?.locale ? { locale: { eq: filters.locale } } : {}),
-    ...(filters?.contentTypes && filters.contentTypes.length > 0
-      ? { contentType: { in: filters.contentTypes } }
-      : {}),
-    ...(facetTerms.length > 0
-      ? { facetTerms: { containsAll: facetTerms } }
-      : {}),
-  };
-  const params = {
+  const where: OramaWhereClause = {};
+  if (filters?.locale) {
+    where.locale = { eq: filters.locale };
+  }
+  // `""` (the current docs) is a real filter value, so test for presence.
+  if (filters?.version !== undefined) {
+    where.version = { eq: filters.version };
+  }
+  if (filters?.contentTypes && filters.contentTypes.length > 0) {
+    where.contentType = { in: filters.contentTypes };
+  }
+  if (facetTerms.length > 0) {
+    where.facetTerms = { containsAll: facetTerms };
+  }
+  const unfiltered = {
     boost: BOOST,
     limit,
     properties: ["title", "description", "content"],
     term,
-    ...(Object.keys(where).length > 0 ? { where } : {}),
   };
+  const params =
+    Object.keys(where).length > 0 ? { ...unfiltered, where } : unfiltered;
   const bigrammed = BIGRAM_LANGUAGES.has(db.tokenizer?.language ?? "");
+  // The result-document generic is OramaDoc because `buildOramaIndex` is the
+  // only writer to this database and inserts OramaDoc records (plus the
+  // derived `facetTerms`).
   const strict = bigrammed
-    ? await search(db, { ...params, threshold: ALL_TOKENS })
+    ? await search<AnyOrama, OramaDoc>(db, { ...params, threshold: ALL_TOKENS })
     : undefined;
   const found =
-    strict && strict.hits.length > 0 ? strict : await search(db, params);
-  return found.hits.map((hit) => hit.document as unknown as OramaDoc);
+    strict && strict.hits.length > 0
+      ? strict
+      : await search<AnyOrama, OramaDoc>(db, params);
+  return found.hits.map((hit) => hit.document);
 };

package/src/search/popular.ts

@@ -26,8 +26,13 @@ export const resolveSearchPopular = (
   popular: { href: string; icon?: string; label: string }[],
   basePath: string
 ): SearchPopularPage[] =>
-  popular.map(({ href, icon, label }) => ({
-    ...(icon ? { icon } : {}),
-    label,
-    route: withBasePath(basePath, href),
-  }));
+  popular.map(({ href, icon, label }) => {
+    const page: SearchPopularPage = {
+      label,
+      route: withBasePath(basePath, href),
+    };
+    if (icon) {
+      page.icon = icon;
+    }
+    return page;
+  });

package/src/search/providers.ts

@@ -29,7 +29,7 @@ export interface SearchProviderMeta {
   syncs: boolean;
 }
 
-export const SEARCH_PROVIDERS: Record<SearchProvider, SearchProviderMeta> = {
+export const SEARCH_PROVIDERS = {
   algolia: {
     kind: "hosted",
     requiresServer: false,
@@ -80,7 +80,7 @@ export const SEARCH_PROVIDERS: Record<SearchProvider, SearchProviderMeta> = {
     runtimeDeps: ["typesense"],
     syncs: true,
   },
-};
+} satisfies Record<SearchProvider, SearchProviderMeta>;
 
 export const searchProviderMeta = (
   provider: SearchProvider

package/src/search/sync/index.ts

@@ -45,6 +45,8 @@ export const syncSearchProvider = async (
       `Synced ${records.length} record(s) to ${search.provider}`
     );
   } catch (error) {
+    // SAFETY: the three sync clients surface network/auth failures as Error
+    // instances; the message is read only to annotate the skip warning.
     reporter.warn(`Search sync skipped: ${(error as Error).message}`);
   }
 };

package/src/search/sync/typesense.ts

@@ -56,9 +56,10 @@ export const syncTypesense = async (
       { name: "content", type: "string" },
       { name: "url", type: "string" },
       { facet: true, name: "tag", optional: true, type: "string" },
-      // Carried as a facet so an i18n site can filter hosted results per
-      // language (the SearchRecord contract).
+      // Carried as facets so hosted results can filter per language and per
+      // docs version (the SearchRecord contract; current docs = "current").
       { facet: true, name: "locale", optional: true, type: "string" },
+      { facet: true, name: "version", optional: true, type: "string" },
     ],
     name: config.collection,
   });
@@ -71,6 +72,7 @@ export const syncTypesense = async (
     tag: record.tag,
     title: record.title,
     url: record.url,
+    version: record.version,
   }));
   await client
     .collections(config.collection)

package/src/seo/jsonld.ts

@@ -27,10 +27,25 @@ export interface StructuredDataInput {
 }
 
 /** schema.org `@type` for each content type; defaults to TechArticle. */
-const ARTICLE_TYPES: Record<string, string> = {
+const ARTICLE_TYPES = {
   blog: "BlogPosting",
   changelog: "TechArticle",
-};
+} as const;
+
+/**
+ * `hasOwn` (not a bare index) so a content type named like an
+ * `Object.prototype` member can't resolve a function up the prototype chain.
+ */
+const isArticleType = (value: string): value is keyof typeof ARTICLE_TYPES =>
+  Object.hasOwn(ARTICLE_TYPES, value);
+
+/** A value a schema.org node property can hold. */
+type JsonLdValue = string | number | JsonLdValue[] | JsonLdNode;
+
+/** A schema.org node: JSON-LD keys to concrete JSON values. */
+export interface JsonLdNode {
+  [key: string]: JsonLdValue;
+}
 
 const trimSlash = (value: string): string => value.replace(/\/$/u, "");
 
@@ -59,14 +74,14 @@ export const toIso = (value: DateInput | undefined): string | undefined => {
  */
 export const buildStructuredData = (
   input: StructuredDataInput
-): Record<string, unknown> | null => {
+): JsonLdNode | null => {
   const base = input.siteUrl ? trimSlash(input.siteUrl) : null;
   // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top
   // so JSON-LD URLs match the served location.
   const deployBase = normalizeBasePath(input.base);
   const pageUrl = absolute(base, withBasePath(deployBase, input.route));
   const rootUrl = absolute(base, deployBase);
-  const graph: Record<string, unknown>[] = [];
+  const graph: JsonLdNode[] = [];
 
   if (base) {
     graph.push({
@@ -80,9 +95,12 @@ export const buildStructuredData = (
   // The homepage is fully described by the WebSite node; deeper pages get an
   // article node plus a breadcrumb trail.
   if (input.route !== "/") {
-    const node: Record<string, unknown> = {
+    const pageType = input.pageType ?? "";
+    const node: JsonLdNode = {
       "@id": `${pageUrl}#page`,
-      "@type": ARTICLE_TYPES[input.pageType ?? ""] ?? "TechArticle",
+      "@type": isArticleType(pageType)
+        ? ARTICLE_TYPES[pageType]
+        : "TechArticle",
       headline: input.title,
       inLanguage: input.locale || "en",
       name: input.title,

package/src/seo/x-handle.ts

@@ -1,3 +1,7 @@
+/** Frontmatter defense in depth: only a real string can carry a handle. */
+const isString = <Value>(value: Value): value is Value & string =>
+  typeof value === "string";
+
 /**
  * Normalize an X account to the leading `@` that `twitter:site`/`twitter:creator`
  * require, so `acme`, `@acme`, and `  @acme ` all land on `@acme`. Empty or
@@ -7,10 +11,11 @@
  * Astro's collections carry no schema here, so a page's `seo.x.creator` reaches
  * them as raw frontmatter, and the schema's own transform never runs on it.
  * (Blume's page pipeline does reject a non-string `creator` before the page is
- * built, so `unknown` is defense in depth rather than the expected path.)
+ * built, so the string guard is defense in depth rather than the expected
+ * path.)
  */
-export const normalizeXHandle = (value: unknown): string | undefined => {
-  if (typeof value !== "string") {
+export const normalizeXHandle = <Value>(value: Value): string | undefined => {
+  if (!isString(value)) {
     return;
   }
   const handle = value.trim().replace(/^@+/u, "");

package/src/theme/chrome-icons.ts

@@ -12,11 +12,16 @@
  * Values are Lucide inner-SVG markup; the client `svg()` helpers wrap them in an
  * `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" …>`.
  */
-export const chromeIcons: Record<string, string> = {
+/** Inner-SVG markup keyed by the icon name a client script requests. */
+interface ChromeIconSet {
+  [name: string]: string;
+}
+
+export const chromeIcons: ChromeIconSet = {
   check: '<path d="M20 6 9 17l-5-5"/>',
   copy: '<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>',
   file: '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/>',
   search: '<circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/>',
   sparkles:
-    '<path d="m12 3-1.9 5.8a2 2 0 0 1-1.3 1.3L3 12l5.8 1.9a2 2 0 0 1 1.3 1.3L12 21l1.9-5.8a2 2 0 0 1 1.3-1.3L21 12l-5.8-1.9a2 2 0 0 1-1.3-1.3Z"/><path d="M5 3v4"/><path d="M3 5h4"/><path d="M19 17v4"/><path d="M17 19h4"/>',
+    '<path d="m12 3-1.9 5.8a2 2 0 0 1-1.3 1.3L3 12l5.8 1.9a2 2 0 0 1 1.3 1.3L12 21l1.9-5.8a2 2 0 0 1-1.3-1.3L21 12l-5.8-1.9a2 2 0 0 1-1.3-1.3Z"/><path d="M5 3v4"/><path d="M3 5h4"/><path d="M19 17v4"/><path d="M17 19h4"/>',
 };

package/src/theme/fonts.ts

@@ -82,11 +82,11 @@ export type FontEntry =
       variants: LocalFontVariant[];
     };
 
-const FALLBACKS: Record<FontCategory, string[]> = {
+const FALLBACKS = {
   mono: ["ui-monospace", "SF Mono", "Menlo", "monospace"],
   sans: ["ui-sans-serif", "system-ui", "sans-serif"],
   serif: ["ui-serif", "Georgia", "serif"],
-};
+} satisfies Record<FontCategory, string[]>;
 
 /** Slug -> Google family + weights + fallback category. Keep keys alphabetical. */
 export const GOOGLE_FONTS = {
@@ -223,12 +223,16 @@ const SLOTS: FontSlot[] = ["display", "body", "mono"];
 const slotCategory = (slot: FontSlot): FontCategory =>
   slot === "mono" ? "mono" : "sans";
 
+/** Whether a slot value is the slug-string form (vs a custom font object). */
+const isSlugValue = (value: FontValue): value is string =>
+  typeof value === "string";
+
 /** A slot value normalized into an entry, or null for an unknown slug string. */
 const resolveFontValue = (
   slot: FontSlot,
   value: FontValue
 ): FontEntry | null => {
-  if (typeof value === "string") {
+  if (isSlugValue(value)) {
     if (!isFontSlug(value)) {
       return null;
     }
@@ -320,7 +324,7 @@ export const buildFontEntries = (fonts: FontsConfig): FontEntry[] => {
 
 /** The slug backing a slot's CSS variable, or null for an unknown slug string. */
 const slotSlug = (value: FontValue): string | null => {
-  if (typeof value === "string") {
+  if (isSlugValue(value)) {
     return isFontSlug(value) ? value : null;
   }
   return slugifyFontName(value.name);

package/src/theme/icons.ts

@@ -17,9 +17,11 @@ import { getIconData, iconToSVG } from "@iconify/utils";
 // strips it when externalizing) and then rejects the module, whereas `require`
 // of a JSON file needs no attribute and works under both Node and Bun.
 const requireJson = createRequire(import.meta.url);
+// SAFETY: the required file is the Iconify-published icon-set JSON, whose
+// shape is exactly `IconifyJSON`.
 const loadSet = (pkg: string): IconifyJSON => requireJson(pkg) as IconifyJSON;
 
-const SETS: Record<string, IconifyJSON> = {
+const SETS = {
   lucide: loadSet("@iconify-json/lucide/icons.json"),
 };
 
@@ -27,7 +29,7 @@ const SETS: Record<string, IconifyJSON> = {
 const DEFAULT_SET = "lucide";
 
 /** Explicit `prefix:name` prefixes. Lucide is the only bundled set. */
-const PREFIX_SETS: Record<string, string> = {
+const PREFIX_SETS = {
   lucide: "lucide",
 };
 

package/src/theme/palette.ts

@@ -2,8 +2,12 @@ import type { ResolvedConfig } from "../core/schema.ts";
 
 const FALLBACK_ACCENT = "oklch(0.62 0.16 250)";
 
-/** Named accent presets mapped to OKLCH values. */
-const ACCENTS: Record<string, string> = {
+/**
+ * Named accent presets mapped to OKLCH values. The single source of truth for
+ * preset colors: the theme CSS and the OG card (og/card.ts) both resolve from
+ * this table, so a site and its social cards can't disagree about "blue".
+ */
+export const ACCENTS = {
   blue: FALLBACK_ACCENT,
   green: "oklch(0.6 0.16 150)",
   orange: "oklch(0.68 0.17 50)",
@@ -11,7 +15,16 @@ const ACCENTS: Record<string, string> = {
   purple: "oklch(0.58 0.2 290)",
   red: "oklch(0.58 0.22 25)",
   teal: "oklch(0.6 0.12 195)",
-};
+} satisfies Record<string, string>;
+
+/**
+ * Whether a raw config value names an accent preset. `hasOwn` keeps a value
+ * like "constructor" from resolving an Object.prototype member — which would
+ * stringify a function into the generated CSS, breaking the rule (the exact
+ * breakout {@link safeColor} exists to prevent).
+ */
+export const isAccentPreset = (value: string): value is keyof typeof ACCENTS =>
+  Object.hasOwn(ACCENTS, value);
 
 // Characters valid in a CSS color value (hex, rgb/hsl/oklch functions, named
 // colors). Anything else — notably `;`, `{`, `}` — could break out of the
@@ -22,27 +35,20 @@ const CSS_COLOR = /^[\w\s#%.,()/+-]+$/u;
 const safeColor = (value: string, fallback: string): string =>
   CSS_COLOR.test(value.trim()) ? value.trim() : fallback;
 
-/**
- * Resolve a named preset or fall back to {@link safeColor}. `hasOwn` keeps a
- * value like "constructor" from resolving an Object.prototype member — which
- * would stringify a function into the generated CSS, breaking the rule (the
- * exact breakout safeColor exists to prevent).
- */
+/** Resolve a named preset or fall back to {@link safeColor}. */
 const presetOrColor = (value: string): string =>
-  Object.hasOwn(ACCENTS, value)
-    ? (ACCENTS[value] as string)
-    : safeColor(value, FALLBACK_ACCENT);
+  isAccentPreset(value) ? ACCENTS[value] : safeColor(value, FALLBACK_ACCENT);
 
 /** Like {@link safeColor} but drops an unsafe/absent value to `null`. */
 const safeColorOrNull = (value: string | undefined): string | null =>
   value && CSS_COLOR.test(value.trim()) ? value.trim() : null;
 
-const RADII: Record<ResolvedConfig["theme"]["radius"], string> = {
+const RADII = {
   lg: "0.75rem",
   md: "0.5rem",
   none: "0",
   sm: "0.25rem",
-};
+} satisfies Record<ResolvedConfig["theme"]["radius"], string>;
 
 const cssString = (value: string): string => JSON.stringify(value);
 
@@ -112,6 +118,12 @@ ${tokens.join("\n")}
 `;
 };
 
+/** Per-mode accent CSS colors. */
+export interface AccentColors {
+  dark: string;
+  light: string;
+}
+
 /**
  * Resolve the configured accent to per-mode CSS colors. A named accent
  * resolves to its preset; any other value is treated as a raw CSS color so
@@ -121,7 +133,7 @@ ${tokens.join("\n")}
  */
 export const resolveAccent = (
   theme: ResolvedConfig["theme"]
-): { dark: string; light: string } => ({
+): AccentColors => ({
   dark: presetOrColor(theme.accent.dark),
   light: presetOrColor(theme.accent.light),
 });

package/src/translate/ledger.ts

@@ -36,8 +36,10 @@ export const emptyLedger = (): TranslationLedger => ({
 
 /**
  * Hash the raw source text (frontmatter included), so any edit invalidates
- * every locale's stamp. sha256-16 like the audit snapshot's content hash —
- * never `hashText` (djb2), which is an ephemeral-cache-only hash.
+ * every locale's stamp. sha256-16 like the audit snapshot's content hash.
+ * Kept as its own function rather than sharing core's `hashText`: ledger
+ * stamps persist in user repos, so this hash must never change shape when an
+ * ephemeral cache hash does.
  */
 export const hashSource = (text: string): string =>
   createHash("sha256").update(text).digest("hex").slice(0, 16);

package/src/translate/meta.ts

@@ -39,6 +39,15 @@ export interface TranslatableMeta {
 
 const META_FILES = ["**/meta.ts", "**/meta.js", "**/meta.mjs"];
 
+/**
+ * Whether a loaded meta module default-exports a factory function. Generic so
+ * it can decode the loader's untyped module value at this boundary.
+ */
+const isFactoryModule = <T>(
+  value: T
+): value is T & ((...args: never[]) => FolderMeta) =>
+  typeof value === "function";
+
 /** Where a locale's generated meta module lives (always written as `meta.ts`). */
 export const metaTargetPath = (
   meta: TranslatableMeta,
@@ -92,7 +101,7 @@ export const discoverTranslatableMeta = async (
         readFile(file, "utf-8"),
         load(file),
       ]);
-      if (typeof mod === "function") {
+      if (isFactoryModule(mod)) {
         diagnostics.push({
           code: "BLUME_TRANSLATE_META_FACTORY",
           file,
@@ -130,14 +139,14 @@ export const generateMetaModule = (
   meta: FolderMeta,
   translatedTitle: string
 ): string => {
-  const data: Record<string, unknown> = {
+  const data = {
     ...meta,
     title: translatedTitle,
   };
-  const lines = Object.keys(data)
-    .toSorted()
-    .filter((key) => data[key] !== undefined)
-    .map((key) => `  ${key}: ${JSON.stringify(data[key])},`);
+  const lines = Object.entries(data)
+    .toSorted(([a], [b]) => (a < b ? -1 : 1))
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => `  ${key}: ${JSON.stringify(value)},`);
   return [
     "// Generated by `blume translate` — edit the default locale's meta file",
     "// and rerun the translation instead of editing this copy.",