blume 1.4.3 → 1.5.0

package/src/core/sources/normalize.ts

@@ -9,6 +9,7 @@ import { localePlacement, localizeRoute } from "../i18n.ts";
 import { pageMetaSchema } from "../schema.ts";
 import type { FrontmatterExtend, PageMeta } from "../schema.ts";
 import type { Diagnostic, Heading, PageLink, PageRecord } from "../types.ts";
+import { detectVersionRef, versionizeRoute } from "../versions.ts";
 import type { NormalizeContext, SourceEntry } from "./types.ts";
 
 const NUMERIC_PREFIX = /^\d+[-_.]/u;
@@ -102,10 +103,15 @@ const addRouteSegment = (
   segments.push(safe);
 };
 
+/** URL + nav metadata mapped from one content-root-relative path. */
+interface MappedRoute {
+  segments: string[];
+  groups: string[];
+  route: string;
+}
+
 /** Convert a content-root-relative path into URL + nav metadata. */
-const mapRoute = (
-  relativePath: string
-): { segments: string[]; groups: string[]; route: string } => {
+const mapRoute = (relativePath: string): MappedRoute => {
   const withoutExt = relativePath.slice(
     0,
     relativePath.length - extname(relativePath).length
@@ -138,10 +144,10 @@ export type FenceState = "```" | "~~~" | null;
  */
 export const nextFenceState = (line: string, fence: FenceState): FenceState => {
   const trimmed = line.trimStart();
-  const delimiter = trimmed.match(CODE_FENCE)?.groups?.delimiter as
-    | Exclude<FenceState, null>
-    | undefined;
-  if (delimiter === undefined) {
+  const delimiter = trimmed.match(CODE_FENCE)?.groups?.delimiter;
+  // The `delimiter` group matches exactly ``` or ~~~; comparing against both
+  // narrows it without a cast.
+  if (delimiter !== "```" && delimiter !== "~~~") {
     return fence;
   }
   if (fence === null) {
@@ -519,6 +525,10 @@ const deriveTitle = (
 const trimSlashes = (value: string): string =>
   value.replaceAll(/^\/+|\/+$/gu, "");
 
+/** Whether a raw frontmatter value is a string (e.g. the `type` override). */
+const isStringValue = (value: SourceEntry["data"][string]): value is string =>
+  typeof value === "string";
+
 const withPrefix = (prefix: string | undefined, path: string): string => {
   const clean = prefix ? trimSlashes(prefix) : "";
   return clean ? `${clean}/${path}` : path;
@@ -530,13 +540,27 @@ interface CustomKeyIssue {
   path: (string | number)[];
 }
 
+/** The validated custom keys (if any survived) plus every failure found. */
+interface CustomKeyValidation {
+  custom?: PageRecord["custom"];
+  issues: CustomKeyIssue[];
+}
+
+/** Whether a Standard Schema path segment is the wrapped `{ key }` form. */
+const isKeyCarrier = (
+  segment: PropertyKey | { readonly key: PropertyKey }
+): segment is { readonly key: PropertyKey } =>
+  typeof segment === "object" && segment !== null;
+
+const isSymbolKey = (key: PropertyKey): key is symbol =>
+  typeof key === "symbol";
+
 /** Lower a Standard Schema path segment (`key` or `{ key }`) for joining. */
 const segmentKey = (
   segment: PropertyKey | { readonly key: PropertyKey }
 ): string | number => {
-  const key =
-    typeof segment === "object" && segment !== null ? segment.key : segment;
-  return typeof key === "symbol" ? String(key) : key;
+  const key = isKeyCarrier(segment) ? segment.key : segment;
+  return isSymbolKey(key) ? String(key) : key;
 };
 
 /**
@@ -549,10 +573,10 @@ const segmentKey = (
  * synchronous, and frontmatter validation has no business awaiting I/O.
  */
 const validateCustomKeys = (
-  data: Record<string, unknown>,
+  data: SourceEntry["data"],
   extend: FrontmatterExtend
-): { custom?: Record<string, unknown>; issues: CustomKeyIssue[] } => {
-  const custom: Record<string, unknown> = {};
+): CustomKeyValidation => {
+  const custom: NonNullable<PageRecord["custom"]> = {};
   const issues: CustomKeyIssue[] = [];
   for (const [key, schema] of Object.entries(extend)) {
     const outcome = schema["~standard"].validate(data[key]);
@@ -597,13 +621,14 @@ const parseEntryMeta = (
   entry: SourceEntry,
   ctx: NormalizeContext
 ):
-  | { meta: PageMeta; custom?: Record<string, unknown>; diagnostics?: never }
+  | { meta: PageMeta; custom?: PageRecord["custom"]; diagnostics?: never }
   | { meta?: never; diagnostics: Diagnostic[] } => {
   // Resolved the same way `contentType` is after parsing (`meta.type` falling
   // back to `defaultType`); a non-string `type` fails the strict parse below,
   // so which per-type map was merged for that entry never matters.
-  const entryType =
-    typeof entry.data.type === "string" ? entry.data.type : ctx.defaultType;
+  const entryType = isStringValue(entry.data.type)
+    ? entry.data.type
+    : ctx.defaultType;
   const typeExtend = ctx.typeFrontmatter?.[entryType];
   // Config validation rejects a key declared both site-wide and per-type, so
   // this merge never has to pick a winner.
@@ -649,6 +674,12 @@ const parseEntryMeta = (
   };
 };
 
+/** The per-locale page records and diagnostics from one source entry. */
+export interface NormalizedEntry {
+  pages: PageRecord[];
+  diagnostics: Diagnostic[];
+}
+
 /**
  * Normalize one source entry into per-locale `PageRecord`s. This is the single
  * funnel every adapter's entries pass through, so route mapping, heading/link
@@ -657,7 +688,7 @@ const parseEntryMeta = (
 export const normalizeEntry = (
   entry: SourceEntry,
   ctx: NormalizeContext
-): { pages: PageRecord[]; diagnostics: Diagnostic[] } => {
+): NormalizedEntry => {
   const { format } = entry.body;
   const ext = format === "mdx" ? ".mdx" : ".md";
 
@@ -678,14 +709,22 @@ export const normalizeEntry = (
     meta.seo.noindex = true;
   }
 
+  // The version is detected first: a snapshot directory is outermost on disk
+  // (`v1.0/fr/page.mdx`), so the locale parser and route mapping must see a
+  // version-stripped ref. The current version is `""` and lives at the root.
+  const { versions } = ctx;
+  const { version, rest: versionlessRef } = versions
+    ? detectVersionRef(entry.ref, versions)
+    : { rest: entry.ref, version: "" };
+
   // Locale and the locale-stripped nav path come from the entry's ref (a leading
   // dir, or a filename suffix under the `dot` parser), not the slug — the slug is
   // the logical, locale-agnostic path within a locale. A shared `$` file maps to
   // every locale. Remote/CMS sources without i18n placement map to one locale.
   const { i18n } = ctx;
   const { navPath: rawNavPath, locales } = i18n
-    ? localePlacement(entry.ref, ext, i18n)
-    : { locales: [""], navPath: entry.ref };
+    ? localePlacement(versionlessRef, ext, i18n)
+    : { locales: [""], navPath: versionlessRef };
 
   const navPath = withPrefix(ctx.source.prefix, rawNavPath);
   // Frontmatter `slug` wins, then the adapter-supplied `entry.slug` (the typed
@@ -699,7 +738,13 @@ export const normalizeEntry = (
     slug ? `${slug}${ext}` : rawNavPath
   );
 
-  const { segments, groups, route: logicalRoute } = mapRoute(routeInput);
+  // The version prefixes the mapped route *after* `mapRoute` runs: the mapped
+  // route is the version-agnostic key, the config id is prepended verbatim
+  // (never numeric-prefix-stripped), a frontmatter `slug` gets versionized so
+  // snapshots can't collide with the live page, and `translationKey` becomes
+  // version-specific for free.
+  const { segments, groups, route: versionKey } = mapRoute(routeInput);
+  const logicalRoute = versionizeRoute(versionKey, version);
   const headings = extractHeadings(entry.body.text);
   const { staged } = ctx.source;
 
@@ -729,6 +774,8 @@ export const normalizeEntry = (
     sourcePath: entry.sourcePath,
     title: deriveTitle(meta, headings, navPath),
     translationKey: logicalRoute,
+    version,
+    versionKey,
   } satisfies Omit<PageRecord, "locale" | "route">;
 
   // One record per locale this entry maps to (one normally; every locale for a

package/src/core/sources/notion.ts

@@ -47,11 +47,21 @@ interface NotionPage {
   last_edited_time?: string;
 }
 
+/** The per-type payload a block carries under the key matching its `type`. */
+interface NotionBlockPayload {
+  caption?: NotionRichText[];
+  checked?: boolean;
+  external?: { url: string };
+  file?: { url: string };
+  language?: string;
+  rich_text?: NotionRichText[];
+}
+
 interface NotionBlock {
   id: string;
   type: string;
   has_children?: boolean;
-  [key: string]: unknown;
+  [key: string]: NotionBlockPayload | boolean | string | undefined;
 }
 
 interface NotionList<T> {
@@ -120,6 +130,17 @@ export interface NotionSourceOptions {
   fetchImpl?: typeof fetch;
 }
 
+/** The frontmatter Blume derives from a Notion page's properties. */
+interface NotionFrontmatter {
+  description?: string;
+  draft?: boolean;
+  sidebar?: { order: number };
+  title?: string;
+  // Frontmatter stays an open bag downstream (`SourceEntry.data`), so admit
+  // the value shapes this source writes under any future key.
+  [key: string]: boolean | string | { order: number } | undefined;
+}
+
 const richToMarkdown = (rich: NotionRichText[] = []): string =>
   rich
     .map((node) => {
@@ -140,9 +161,18 @@ const richToMarkdown = (rich: NotionRichText[] = []): string =>
     })
     .join("");
 
+const isBlockPayload = (
+  value: NotionBlockPayload | boolean | string | undefined
+): value is NotionBlockPayload => typeof value === "object";
+
+/** The payload object stored under a block's own `type` key, if present. */
+const payloadOf = (block: NotionBlock): NotionBlockPayload | undefined => {
+  const value = block[block.type];
+  return isBlockPayload(value) ? value : undefined;
+};
+
 const blockField = (block: NotionBlock): NotionRichText[] =>
-  ((block[block.type] as { rich_text?: NotionRichText[] })?.rich_text ??
-    []) as NotionRichText[];
+  payloadOf(block)?.rich_text ?? [];
 
 const RATE_LIMITED = 429;
 const MAX_RETRIES = 4;
@@ -165,10 +195,16 @@ const withNotionRetry = async <T>(
   try {
     return await call();
   } catch (error) {
+    // SAFETY: Notion SDK failures are APIResponseError-shaped, carrying the
+    // failed request's HTTP status; anything else reads `undefined` and is
+    // rethrown below.
     const { status } = error as { status?: number };
     if (status !== RATE_LIMITED || attempt === MAX_RETRIES) {
       throw error;
     }
+    // SAFETY: same APIResponseError shape — `headers` maps lower-cased HTTP
+    // header names to their values; a missing header yields `NaN` and falls
+    // back to exponential backoff.
     const retryAfter = Number(
       (error as { headers?: Record<string, string> }).headers?.["retry-after"]
     );
@@ -206,7 +242,7 @@ const isListItem = (block: NotionBlock | undefined): boolean =>
 
 /** Render a leaf (non-container) block to Markdown, or null for containers. */
 const renderLeaf = (block: NotionBlock): string | null => {
-  const data = (block[block.type] ?? {}) as Record<string, unknown>;
+  const data = payloadOf(block) ?? {};
   const text = richToMarkdown(blockField(block));
   switch (block.type) {
     case "paragraph": {
@@ -237,16 +273,11 @@ const renderLeaf = (block: NotionBlock): string | null => {
       return "---";
     }
     case "code": {
-      return `\`\`\`${(data.language as string) ?? ""}\n${text}\n\`\`\``;
+      return `\`\`\`${data.language ?? ""}\n${text}\n\`\`\``;
     }
     case "image": {
-      const media = data as {
-        external?: { url: string };
-        file?: { url: string };
-        caption?: NotionRichText[];
-      };
-      const url = media.external?.url ?? media.file?.url;
-      return url ? `![${richToMarkdown(media.caption)}](${url})` : "";
+      const url = data.external?.url ?? data.file?.url;
+      return url ? `![${richToMarkdown(data.caption)}](${url})` : "";
     }
     default: {
       return null;
@@ -288,6 +319,9 @@ export const notionSource = (
     }
     let Client: new (config: { auth?: string }) => NotionClientLike;
     try {
+      // SAFETY: `@notionhq/client` exports a `Client` class constructable with
+      // an `auth` token whose instances cover the NotionClientLike slice; the
+      // local type keeps the SDK mockable without importing its types.
       ({ Client } = (await import("@notionhq/client")) as {
         Client: new (config: { auth?: string }) => NotionClientLike;
       });
@@ -421,13 +455,11 @@ export const notionSource = (
 
   const orderOf = (page: NotionPage): number | undefined => {
     const order = page.properties[props.order ?? "Order"]?.number;
-    return typeof order === "number" ? order : undefined;
+    return order === null ? undefined : order;
   };
 
-  const frontmatter = (
-    page: NotionPage
-  ): { data: Record<string, unknown>; slug: string } => {
-    const data: Record<string, unknown> = {};
+  const frontmatter = (page: NotionPage) => {
+    const data: NotionFrontmatter = {};
     const title = richToMarkdown(titleProperty(page)?.title);
     if (title) {
       data.title = title;

package/src/core/sources/portable-text.ts

@@ -5,6 +5,23 @@
  * Markdown text that flows through Blume's normal pipeline.
  */
 
+/**
+ * A field value on a Portable Text node: the arbitrary JSON the CMS query
+ * returned (custom blocks carry whatever fields the studio schema defines).
+ * Spans and mark defs appear as members so the block's typed fields conform
+ * to its index signature.
+ */
+export type PortableTextValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | PortableTextSpan
+  | PortableTextMarkDef
+  | PortableTextValue[]
+  | { [key: string]: PortableTextValue };
+
 /** A single Portable Text node (block, image, or a custom type). */
 export interface PortableTextBlock {
   _type: string;
@@ -14,7 +31,7 @@ export interface PortableTextBlock {
   level?: number;
   children?: PortableTextSpan[];
   markDefs?: PortableTextMarkDef[];
-  [key: string]: unknown;
+  [key: string]: PortableTextValue;
 }
 
 interface PortableTextSpan {
@@ -36,14 +53,14 @@ export interface PortableTextOptions {
   serializers?: Record<string, (block: PortableTextBlock) => string>;
 }
 
-const HEADING_STYLES: Record<string, string> = {
-  h1: "# ",
-  h2: "## ",
-  h3: "### ",
-  h4: "#### ",
-  h5: "##### ",
-  h6: "###### ",
-};
+const HEADING_STYLES = new Map([
+  ["h1", "# "],
+  ["h2", "## "],
+  ["h3", "### "],
+  ["h4", "#### "],
+  ["h5", "##### "],
+  ["h6", "###### "],
+]);
 
 // Markdown/raw-HTML structure characters. Portable Text spans are *plain
 // text* — formatting arrives as marks, never as syntax in the text — so a
@@ -108,6 +125,10 @@ const renderChildren = (block: PortableTextBlock): string => {
   return (block.children ?? []).map((span) => renderSpan(span, defs)).join("");
 };
 
+/** Whether an image block's `alt` field is usable alt text (CMS JSON may hold anything). */
+const isAltText = (value: PortableTextValue): value is string =>
+  typeof value === "string";
+
 const renderBlock = (
   block: PortableTextBlock,
   options: PortableTextOptions
@@ -118,7 +139,7 @@ const renderBlock = (
   }
   if (block._type === "image") {
     const url = options.imageUrl?.(block);
-    const alt = typeof block.alt === "string" ? block.alt : "";
+    const alt = isAltText(block.alt) ? block.alt : "";
     return url ? `![${alt}](${url})` : "";
   }
   if (block._type !== "block") {
@@ -134,7 +155,7 @@ const renderBlock = (
   if (block.style === "blockquote") {
     return `> ${inline}`;
   }
-  return `${HEADING_STYLES[block.style ?? "normal"] ?? ""}${inline}`;
+  return `${HEADING_STYLES.get(block.style ?? "normal") ?? ""}${inline}`;
 };
 
 /** Serialize a Portable Text array into a Markdown string. */

package/src/core/sources/sanity.ts

@@ -59,12 +59,44 @@ export interface SanitySourceOptions {
 
 const IMAGE_REF = /^image-(?<id>[a-f0-9]+)-(?<dims>\d+x\d+)-(?<ext>\w+)$/u;
 
+/** A value in a fetched document: arbitrary JSON the GROQ query returned. */
+type SanityValue =
+  | string
+  | number
+  | boolean
+  | null
+  | SanityValue[]
+  | { [key: string]: SanityValue };
+
+/** A document as the GROQ query returns it. */
+interface SanityDocument {
+  [key: string]: SanityValue;
+}
+
+/** The frontmatter fields this adapter maps from a document. */
+interface SanityFrontmatter {
+  description?: string;
+  title?: string;
+}
+
+/**
+ * A node a dot path can descend into. Arrays pass too (matching their runtime
+ * string-key indexing, e.g. `items.0`), so the predicate types them as the
+ * keyed form both traverse through.
+ */
+const isTraversable = (
+  value: SanityValue | undefined
+): value is SanityDocument => typeof value === "object" && value !== null;
+
 /** Resolve a dot path (`slug.current`) against a document. */
-const getPath = (doc: Record<string, unknown>, path: string): unknown => {
-  let current: unknown = doc;
+const getPath = (
+  doc: SanityDocument,
+  path: string
+): SanityValue | undefined => {
+  let current: SanityValue | undefined = doc;
   for (const key of path.split(".")) {
-    if (current && typeof current === "object") {
-      current = (current as Record<string, unknown>)[key];
+    if (isTraversable(current)) {
+      current = current[key];
     } else {
       return;
     }
@@ -72,8 +104,11 @@ const getPath = (doc: Record<string, unknown>, path: string): unknown => {
   return current;
 };
 
-const asString = (value: unknown): string | undefined =>
-  typeof value === "string" ? value : undefined;
+const isStringValue = (value: SanityValue | undefined): value is string =>
+  typeof value === "string";
+
+const asString = (value: SanityValue | undefined): string | undefined =>
+  isStringValue(value) ? value : undefined;
 
 /** Build a Sanity CDN URL from an image asset `_ref`. */
 const imageUrlFromRef = (
@@ -89,6 +124,16 @@ const imageUrlFromRef = (
   return `https://cdn.sanity.io/images/${projectId}/${dataset}/${id}-${dims}.${ext}`;
 };
 
+/** The `createClient` config slice this adapter passes. */
+interface SanityClientConfig {
+  apiVersion: string;
+  dataset: string;
+  perspective: "previewDrafts" | "published";
+  projectId: string;
+  token: string | undefined;
+  useCdn: boolean;
+}
+
 const resolveClient = async (
   options: SanitySourceOptions,
   preview: boolean
@@ -96,10 +141,13 @@ const resolveClient = async (
   if (options.client) {
     return options.client;
   }
-  let createClient: (config: Record<string, unknown>) => SanityClientLike;
+  let createClient: (config: SanityClientConfig) => SanityClientLike;
   try {
+    // SAFETY: `@sanity/client` is an optional dependency; its `createClient`
+    // accepts a superset of this config slice and returns a client exposing
+    // the `fetch` method this adapter uses.
     ({ createClient } = (await import("@sanity/client")) as {
-      createClient: (config: Record<string, unknown>) => SanityClientLike;
+      createClient: (config: SanityClientConfig) => SanityClientLike;
     });
   } catch {
     throw new BlumeError({
@@ -135,7 +183,7 @@ export const sanitySource = (
   );
   let snapshot = new Map<string, SourceEntry>();
 
-  const toEntry = (doc: Record<string, unknown>): SourceEntry => {
+  const toEntry = (doc: SanityDocument): SourceEntry => {
     const slugValue =
       asString(getPath(doc, fields.slug ?? "slug.current")) ??
       asString(doc._id) ??
@@ -148,7 +196,7 @@ export const sanitySource = (
     const slug =
       slugifyPath(slugValue) || slugify(asString(doc._id) ?? "") || "untitled";
 
-    const data: Record<string, unknown> = {};
+    const data: SanityFrontmatter = {};
     const title = asString(getPath(doc, fields.title ?? "title"));
     const description = asString(
       getPath(doc, fields.description ?? "description")
@@ -160,11 +208,17 @@ export const sanitySource = (
       data.description = description;
     }
 
+    // SAFETY: the configured body field holds Portable Text blocks; a value of
+    // any other shape fails the `Array.isArray` check below and yields an
+    // empty body, and the serializer tolerates malformed blocks.
     const blocks = (getPath(doc, fields.body ?? "body") ??
       []) as PortableTextBlock[];
     const markdown = Array.isArray(blocks)
       ? portableTextToMarkdown(blocks, {
           imageUrl: (block) => {
+            // SAFETY: `asset` on an image block is Sanity's asset reference
+            // object; any other shape yields no `_ref` and the image is
+            // skipped.
             const ref = (block.asset as { _ref?: string } | undefined)?._ref;
             return ref
               ? imageUrlFromRef(ref, options.projectId, options.dataset)
@@ -177,7 +231,9 @@ export const sanitySource = (
     const raw = matter.stringify(markdown, data);
     return {
       body: { format: "md", text: markdown },
-      data,
+      // Spread into a fresh literal: `SourceEntry.data` wants an
+      // index-signature type, which the named interface lacks.
+      data: { ...data },
       hash: hashText(raw),
       lastModified: asString(getPath(doc, fields.lastModified ?? "_updatedAt")),
       raw,
@@ -193,9 +249,7 @@ export const sanitySource = (
       cache,
       async () => {
         const client = await resolveClient(options, ctx?.preview ?? false);
-        const docs = await client.fetch<Record<string, unknown>[]>(
-          options.query
-        );
+        const docs = await client.fetch<SanityDocument[]>(options.query);
         return docs.map(toEntry);
       },
       refresh

package/src/core/sources/types.ts

@@ -2,6 +2,7 @@ import type {
   FolderMeta,
   FrontmatterExtend,
   ResolvedI18nConfig,
+  ResolvedVersionsConfig,
 } from "../schema.ts";
 import type { Diagnostic } from "../types.ts";
 
@@ -16,6 +17,7 @@ export interface SourceEntry {
   /** Logical route input; defaults to `ref` if omitted. May include slashes. */
   slug?: string;
   /** Frontmatter-equivalent metadata, validated against the Blume meta schema. */
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- pre-validation frontmatter from YAML/CMS payloads; the meta schema parses it downstream
   data: Record<string, unknown>;
   /** The renderable body as Markdown/MDX source text (frontmatter stripped). */
   body: { format: "md" | "mdx"; text: string };
@@ -129,4 +131,6 @@ export interface NormalizeContext {
    * applied to a page only when its resolved `type` matches.
    */
   typeFrontmatter?: Record<string, FrontmatterExtend>;
+  /** Docs versioning config; a leading archived-version dir becomes the page's version. */
+  versions?: ResolvedVersionsConfig;
 }

package/src/core/sources/watch.ts

@@ -71,7 +71,7 @@ export const ignoringWatchListener = (
   const ignore = new Set(ignoreDirs);
   return (_event, filename) => {
     if (
-      typeof filename === "string" &&
+      filename !== null &&
       filename.split(/[/\\]/u).some((segment) => ignore.has(segment))
     ) {
       return;

package/src/core/standard-schema.ts

@@ -38,7 +38,7 @@ export interface StandardSchema<Input = unknown, Output = Input> {
     readonly version: 1;
     readonly vendor: string;
     readonly validate: (
-      value: unknown
+      value: Input
     ) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
     readonly types?:
       | { readonly input: Input; readonly output: Output }
@@ -46,9 +46,15 @@ export interface StandardSchema<Input = unknown, Output = Input> {
   };
 }
 
-/** Whether a config-supplied value implements the `~standard` contract. */
-export const isStandardSchema = (value: unknown): value is StandardSchema =>
+/**
+ * Whether a config-supplied value implements the `~standard` contract. Generic
+ * so it can decode any input at the config boundary (`z.custom` hands it the
+ * raw config value) while narrowing whatever type the caller holds.
+ */
+export const isStandardSchema = <T>(value: T): value is T & StandardSchema =>
   typeof value === "object" &&
   value !== null &&
+  // SAFETY: the assertion only widens the checked object for property probing;
+  // the trailing typeof check is what verifies `~standard.validate` exists.
   typeof (value as { "~standard"?: { validate?: unknown } })["~standard"]
     ?.validate === "function";

package/src/core/text-width.ts

@@ -0,0 +1,26 @@
+import stringWidth from "string-width";
+
+/**
+ * The longest prefix of `text` that renders within `max` display columns
+ * without cutting inside a grapheme cluster. Columns are `string-width`'s: a
+ * fullwidth or wide character counts 2, a combining mark 0, everything else 1
+ * — the same measure `blume audit` grades titles and meta descriptions with,
+ * so text cut here stays inside the audit's thresholds for every script, not
+ * just Latin. Grapheme segmentation is rule-based (UAX #29), so unlike word
+ * segmentation it does not drift across ICU builds, and it can never split a
+ * surrogate pair or halve an emoji sequence.
+ */
+export const columnsPrefix = (text: string, max: number): string => {
+  let end = 0;
+  let used = 0;
+  const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+  for (const { index, segment } of graphemes.segment(text)) {
+    const width = stringWidth(segment);
+    if (used + width > max) {
+      break;
+    }
+    used += width;
+    end = index + segment.length;
+  }
+  return text.slice(0, end);
+};

package/src/core/tsconfig-aliases.ts

@@ -30,16 +30,20 @@ const substituteConfigDir = (value: string, configDir: string): string =>
     ? join(configDir, value.slice(CONFIG_DIR_TEMPLATE.length))
     : value;
 
+/** Whether a `paths` fallback entry is a usable target (raw JSONC may lie). */
+const isPathTarget = (target: string | undefined): target is string =>
+  typeof target === "string";
+
 /** Convert one tsconfig `paths` mapping to a Vite alias, or null to skip. */
 const toAlias = (
   key: string,
-  value: unknown,
+  value: string | string[],
   baseDir: string,
   configDir: string
 ): { find: string; replacement: string } | null => {
   // tsconfig allows a fallback array; Vite aliases are 1:1, so take the first.
   const first = Array.isArray(value) ? value[0] : value;
-  if (typeof first !== "string") {
+  if (!isPathTarget(first)) {
     return null;
   }
   const find = key.endsWith("/*") ? key.slice(0, -2) : key;
@@ -86,12 +90,12 @@ export const resolveTsconfigAliases = (
     configDir,
     substituteConfigDir(options?.baseUrl ?? ".", configDir)
   );
-  const aliases: Record<string, string> = {};
+  const entries: [string, string][] = [];
   for (const [key, value] of Object.entries(paths)) {
     const alias = toAlias(key, value, baseDir, configDir);
     if (alias) {
-      aliases[alias.find] = alias.replacement;
+      entries.push([alias.find, alias.replacement]);
     }
   }
-  return aliases;
+  return Object.fromEntries(entries);
 };