blume 0.0.0 → 0.1.0

package/src/migrate/shared.ts

@@ -0,0 +1,623 @@
+import { writeFile } from "node:fs/promises";
+
+import { join } from "pathe";
+
+import type { BlumeConfig } from "../core/schema.ts";
+import { pageMetaSchema } from "../core/schema.ts";
+
+/**
+ * Framework-agnostic helpers shared by more than one migrator. Each piece here
+ * was generalized from a migrator-specific implementation so Mintlify, Nextra,
+ * and future migrators converge on a single copy.
+ */
+
+/** Serialize a `BlumeConfig` to a `blume.config.ts` at the project root. */
+export const writeBlumeConfig = async (
+  root: string,
+  config: BlumeConfig
+): Promise<void> => {
+  const body = `import { defineConfig } from "blume";\n\nexport default defineConfig(${JSON.stringify(config, null, 2)});\n`;
+  await writeFile(join(root, "blume.config.ts"), body, "utf-8");
+};
+
+// ---------------------------------------------------------------------------
+// Callout components -> Blume `:::` directives
+// ---------------------------------------------------------------------------
+
+export interface CalloutRewriteOptions {
+  /** Directive for a type-bearing tag with no `type` attribute (e.g. bare `<Callout>`). */
+  defaultDirective: string;
+  /** Tag names whose directive is fixed by the tag itself (e.g. `<Warning>`). */
+  tagDirectives: Record<string, string>;
+  /** Component tag names to convert. */
+  tags: string[];
+  /** `type="…"` values mapped to Blume directive names. */
+  typeDirectives: Record<string, string>;
+}
+
+/** Read a quoted string attribute (`name="…"` or `name='…'`) from a tag. */
+export const attribute = (attrs: string, name: string): string | undefined => {
+  const match = attrs.match(
+    new RegExp(`\\b${name}=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')`, "u")
+  );
+  return match?.groups?.dq ?? match?.groups?.sq;
+};
+
+/** Remove a shared leading indent and surrounding blank lines from a block. */
+const dedent = (value: string): string => {
+  const lines = value
+    .replace(/^\r?\n/u, "")
+    .replace(/\s+$/u, "")
+    .split("\n");
+  const indents = lines
+    .filter((line) => line.trim() !== "")
+    .map((line) => line.match(/^\s*/u)?.[0].length ?? 0);
+  const common = indents.length > 0 ? Math.min(...indents) : 0;
+  return lines.map((line) => line.slice(common)).join("\n");
+};
+
+const directiveBlock = (
+  directive: string,
+  title: string | undefined,
+  inner: string
+): string => {
+  const head = title ? `:::${directive}[${title}]` : `:::${directive}`;
+  const body = dedent(inner);
+  return `${head}\n${body}\n:::`;
+};
+
+/**
+ * Find the `>` that closes an opening JSX tag, honoring quotes and `{…}`
+ * expression attributes (so a `>` inside `icon={"<svg…>"}` is not mistaken for
+ * the tag end). Returns -1 if unterminated.
+ */
+export const findOpenTagEnd = (source: string, from: number): number => {
+  let depth = 0;
+  let quote: '"' | "'" | "`" | null = null;
+  for (let index = from; index < source.length; index += 1) {
+    const char = source[index];
+    if (quote) {
+      if (char === quote && source[index - 1] !== "\\") {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+    } else if (char === "{") {
+      depth += 1;
+    } else if (char === "}") {
+      depth -= 1;
+    } else if (char === ">" && depth === 0) {
+      return index;
+    }
+  }
+  return -1;
+};
+
+const directiveFor = (
+  tag: string,
+  attrs: string,
+  options: CalloutRewriteOptions
+): string | undefined => {
+  if (tag in options.tagDirectives) {
+    return options.tagDirectives[tag];
+  }
+  const type = attribute(attrs, "type")?.toLowerCase();
+  return type ? options.typeDirectives[type] : options.defaultDirective;
+};
+
+/**
+ * Convert callout-style JSX components into Blume `:::` directives. Uses a
+ * quote/brace-aware tag scanner so callouts carrying JSX-expression attributes
+ * (e.g. inline-SVG icons) convert cleanly; non-convertible attributes (icons,
+ * colors, emoji) are dropped. A tag whose resolved directive is unknown is left
+ * untouched.
+ */
+export const rewriteCallouts = (
+  source: string,
+  options: CalloutRewriteOptions
+): string => {
+  const tagPattern = new RegExp(
+    `<(?<tag>${options.tags.join("|")})(?=[\\s/>])`,
+    "u"
+  );
+  let output = "";
+  let cursor = 0;
+
+  while (cursor < source.length) {
+    const match = tagPattern.exec(source.slice(cursor));
+    if (!match?.groups) {
+      output += source.slice(cursor);
+      break;
+    }
+
+    const start = cursor + match.index;
+    const { tag } = match.groups;
+    if (!tag) {
+      output += source.slice(cursor);
+      break;
+    }
+    const openEnd = findOpenTagEnd(source, start + tag.length + 1);
+    if (openEnd === -1) {
+      output += source.slice(cursor, start + 1);
+      cursor = start + 1;
+      continue;
+    }
+
+    const attrs = source.slice(start + tag.length + 1, openEnd);
+    const directive = directiveFor(tag, attrs, options);
+    const closeTag = `</${tag}>`;
+    const selfClosing = attrs.trimEnd().endsWith("/");
+    const closeIndex = selfClosing
+      ? openEnd
+      : source.indexOf(closeTag, openEnd + 1);
+
+    if (!directive || (!selfClosing && closeIndex === -1)) {
+      output += source.slice(cursor, openEnd + 1);
+      cursor = openEnd + 1;
+      continue;
+    }
+
+    output += source.slice(cursor, start);
+    const title = attribute(attrs, "title");
+    if (selfClosing) {
+      output += title
+        ? `:::${directive}[${title}]\n:::`
+        : `:::${directive}\n:::`;
+      cursor = openEnd + 1;
+    } else {
+      output += directiveBlock(
+        directive,
+        title,
+        source.slice(openEnd + 1, closeIndex)
+      );
+      cursor = closeIndex + closeTag.length;
+    }
+  }
+
+  return output;
+};
+
+// ---------------------------------------------------------------------------
+// Page frontmatter
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove frontmatter keys Blume's strict page schema would reject (e.g. stray
+ * `og:*`/`twitter:*` metatags) so the migrated page validates, reporting what
+ * was dropped. Validation errors other than stray keys are left for `blume dev`
+ * to surface.
+ */
+export const stripUnknownPageMeta = (
+  data: Record<string, unknown>
+): { data: Record<string, unknown>; removed: string[] } => {
+  const result = pageMetaSchema.safeParse(data);
+  if (result.success) {
+    return { data, removed: [] };
+  }
+
+  const removed = new Set<string>();
+  for (const issue of result.error.issues) {
+    if (issue.code === "unrecognized_keys" && issue.path.length === 0) {
+      for (const key of issue.keys) {
+        removed.add(key);
+      }
+    }
+  }
+  if (removed.size === 0) {
+    return { data, removed: [] };
+  }
+
+  const next: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (!removed.has(key)) {
+      next[key] = value;
+    }
+  }
+  return { data: next, removed: [...removed] };
+};
+
+// ---------------------------------------------------------------------------
+// JSX tag renaming
+// ---------------------------------------------------------------------------
+
+/**
+ * Rename a JSX tag (open and close) while preserving its attributes. The
+ * trailing lookahead means a longer tag (e.g. `CardGrid`) is never matched by a
+ * rule for its shorter prefix (`Card`), so prefix-sharing renames can be chained
+ * — run the item-level rename before the container rename.
+ */
+export const renameTag = (source: string, from: string, to: string): string =>
+  source.replaceAll(
+    new RegExp(`<(?<close>/?)${from}(?=[\\s/>])`, "gu"),
+    `<$<close>${to}`
+  );
+
+// ---------------------------------------------------------------------------
+// JavaScript literal scanning
+// ---------------------------------------------------------------------------
+
+/**
+ * Static readers for JS/TS config files (Nextra `_meta`, Starlight
+ * `astro.config`). Config is parsed by walking the source as text — quote-,
+ * comment-, and bracket-aware — rather than executing user code, matching the
+ * other migrators (which never eval). Values that aren't pure literals (an
+ * identifier, call, JSX, or interpolated template) are reported as `UNPARSEABLE`
+ * so the caller can drop the field and warn.
+ */
+
+/** Index of a string within a JS source: the close quote matching `s[open]`. */
+export const findStringEnd = (s: string, open: number): number => {
+  const quote = s[open];
+  for (let index = open + 1; index < s.length; index += 1) {
+    if (s[index] === "\\") {
+      index += 1;
+      continue;
+    }
+    if (s[index] === quote) {
+      return index;
+    }
+  }
+  return -1;
+};
+
+export const unescapeString = (inner: string): string =>
+  inner.replaceAll(/\\(?<ch>["'`\\nt])/gu, (_match, ch: string) => {
+    if (ch === "n") {
+      return "\n";
+    }
+    if (ch === "t") {
+      return "\t";
+    }
+    return ch;
+  });
+
+/** Index of the last char of a `//` or block comment at `index`, else `index`. */
+const skipComment = (source: string, index: number): number => {
+  if (source[index + 1] === "/") {
+    const newline = source.indexOf("\n", index + 2);
+    return newline === -1 ? source.length : newline;
+  }
+  if (source[index + 1] === "*") {
+    const close = source.indexOf("*/", index + 2);
+    return close === -1 ? source.length : close + 1;
+  }
+  return index;
+};
+
+const pushSlice = (
+  parts: string[],
+  source: string,
+  start: number,
+  end: number
+): void => {
+  const raw = source.slice(start, end).trim();
+  if (raw) {
+    parts.push(raw);
+  }
+};
+
+export interface ObjectScanResult {
+  end: number;
+  entries: string[];
+}
+
+/**
+ * Walk a `{…}` object literal starting at `openIndex`, returning the matching
+ * close-brace index and the raw `key: value` text of each top-level entry.
+ * Quote-, comment-, and bracket-aware so commas/braces nested in strings,
+ * arrays, or child objects don't split entries. Returns null if unterminated.
+ */
+export const scanObject = (
+  source: string,
+  openIndex: number
+): ObjectScanResult | null => {
+  let depth = 0;
+  const entries: string[] = [];
+  let entryStart = openIndex + 1;
+
+  for (let index = openIndex; index < source.length; index += 1) {
+    const char = source[index];
+
+    if (char === '"' || char === "'" || char === "`") {
+      const end = findStringEnd(source, index);
+      index = end === -1 ? source.length : end;
+      continue;
+    }
+    if (char === "/") {
+      const skipped = skipComment(source, index);
+      if (skipped !== index) {
+        index = skipped;
+        continue;
+      }
+    }
+    if (char === "{" || char === "[" || char === "(") {
+      depth += 1;
+      continue;
+    }
+    if (char === "}" || char === "]" || char === ")") {
+      depth -= 1;
+      if (char === "}" && depth === 0) {
+        pushSlice(entries, source, entryStart, index);
+        return { end: index, entries };
+      }
+      continue;
+    }
+    if (char === "," && depth === 1) {
+      pushSlice(entries, source, entryStart, index);
+      entryStart = index + 1;
+    }
+  }
+
+  return null;
+};
+
+export interface ArrayScanResult {
+  elements: string[];
+  end: number;
+}
+
+/**
+ * Walk a `[…]` array literal starting at `openIndex`, returning the matching
+ * close-bracket index and the raw text of each top-level element. The sibling of
+ * {@link scanObject}; a trailing comma yields no empty element.
+ */
+export const scanArray = (
+  source: string,
+  openIndex: number
+): ArrayScanResult | null => {
+  let depth = 0;
+  const elements: string[] = [];
+  let elementStart = openIndex + 1;
+
+  for (let index = openIndex; index < source.length; index += 1) {
+    const char = source[index];
+
+    if (char === '"' || char === "'" || char === "`") {
+      const end = findStringEnd(source, index);
+      index = end === -1 ? source.length : end;
+      continue;
+    }
+    if (char === "/") {
+      const skipped = skipComment(source, index);
+      if (skipped !== index) {
+        index = skipped;
+        continue;
+      }
+    }
+    if (char === "{" || char === "[" || char === "(") {
+      depth += 1;
+      continue;
+    }
+    if (char === "}" || char === ")") {
+      depth -= 1;
+      continue;
+    }
+    if (char === "]") {
+      depth -= 1;
+      if (depth === 0) {
+        pushSlice(elements, source, elementStart, index);
+        return { elements, end: index };
+      }
+      continue;
+    }
+    if (char === "," && depth === 1) {
+      pushSlice(elements, source, elementStart, index);
+      elementStart = index + 1;
+    }
+  }
+
+  return null;
+};
+
+/**
+ * Strip `//` and block comments so they don't leak into entry text (the scanner
+ * splits on slices, so an inter-entry comment would otherwise attach to the next
+ * entry). String literals are preserved verbatim.
+ */
+export const stripJsComments = (source: string): string => {
+  let out = "";
+  let quote: string | null = null;
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    if (quote) {
+      out += char;
+      if (char === "\\") {
+        out += source[index + 1] ?? "";
+        index += 1;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      out += char;
+      continue;
+    }
+    if (char === "/" && source[index + 1] === "/") {
+      const newline = source.indexOf("\n", index + 2);
+      index = newline === -1 ? source.length - 1 : newline - 1;
+      continue;
+    }
+    if (char === "/" && source[index + 1] === "*") {
+      const close = source.indexOf("*/", index + 2);
+      index = close === -1 ? source.length - 1 : close + 1;
+      out += " ";
+      continue;
+    }
+    out += char;
+  }
+  return out;
+};
+
+export interface KeyValue {
+  key: string;
+  value: string;
+}
+
+/** Split a raw `key: value` entry at its top-level colon. */
+export const splitKeyValue = (entry: string): KeyValue | null => {
+  let index = 0;
+  while (index < entry.length && /\s/u.test(entry[index] ?? "")) {
+    index += 1;
+  }
+  const first = entry[index];
+  if (first === "[") {
+    // Computed key — not something we can resolve statically.
+    return null;
+  }
+
+  let key: string;
+  if (first === '"' || first === "'" || first === "`") {
+    const close = findStringEnd(entry, index);
+    if (close === -1) {
+      return null;
+    }
+    key = entry.slice(index, close + 1);
+    index = close + 1;
+  } else {
+    const start = index;
+    while (index < entry.length && !/[\s:]/u.test(entry[index] ?? "")) {
+      index += 1;
+    }
+    key = entry.slice(start, index);
+  }
+
+  while (index < entry.length && /\s/u.test(entry[index] ?? "")) {
+    index += 1;
+  }
+  if (entry[index] !== ":") {
+    return { key, value: "" };
+  }
+  return { key, value: entry.slice(index + 1).trim() };
+};
+
+/** Read an object key, unquoting it when it is a string literal. */
+export const parseKey = (key: string): string => {
+  const trimmed = key.trim();
+  const [quote] = trimmed;
+  if (quote === '"' || quote === "'" || quote === "`") {
+    const end = findStringEnd(trimmed, 0);
+    if (end !== -1) {
+      return unescapeString(trimmed.slice(1, end));
+    }
+  }
+  return trimmed;
+};
+
+/** Read a clean string literal value, or null if it's an expression. */
+export const readString = (value: string): string | null => {
+  const trimmed = value.trim();
+  const [quote] = trimmed;
+  if (quote !== '"' && quote !== "'" && quote !== "`") {
+    return null;
+  }
+  if (quote === "`" && trimmed.includes("${")) {
+    return null;
+  }
+  const end = findStringEnd(trimmed, 0);
+  if (end === -1 || trimmed.slice(end + 1).trim() !== "") {
+    return null;
+  }
+  return unescapeString(trimmed.slice(1, end));
+};
+
+/** A value that isn't a pure literal (identifier, call, JSX, computed, …). */
+export const UNPARSEABLE = Symbol("unparseable");
+
+export type LiteralValue =
+  | LiteralValue[]
+  | boolean
+  | null
+  | number
+  | string
+  | typeof UNPARSEABLE
+  | { [key: string]: LiteralValue };
+
+const NUMERIC = /^-?\d/u;
+
+const parseScalarLiteral = (trimmed: string): LiteralValue => {
+  if (trimmed === "true") {
+    return true;
+  }
+  if (trimmed === "false") {
+    return false;
+  }
+  if (trimmed === "null") {
+    return null;
+  }
+  if (NUMERIC.test(trimmed)) {
+    const num = Number(trimmed);
+    if (!Number.isNaN(num)) {
+      return num;
+    }
+  }
+  return UNPARSEABLE;
+};
+
+const parseObjectLiteral = (trimmed: string): LiteralValue => {
+  const scan = scanObject(trimmed, 0);
+  if (!scan || trimmed.slice(scan.end + 1).trim() !== "") {
+    return UNPARSEABLE;
+  }
+  const out: Record<string, LiteralValue> = {};
+  for (const entry of scan.entries) {
+    const kv = splitKeyValue(entry);
+    if (kv?.key && kv.value !== "") {
+      // oxlint-disable-next-line no-use-before-define -- mutual recursion
+      out[parseKey(kv.key)] = parseLiteral(kv.value);
+    }
+  }
+  return out;
+};
+
+const parseArrayLiteral = (trimmed: string): LiteralValue => {
+  const scan = scanArray(trimmed, 0);
+  if (!scan || trimmed.slice(scan.end + 1).trim() !== "") {
+    return UNPARSEABLE;
+  }
+  // oxlint-disable-next-line no-use-before-define -- mutual recursion
+  return scan.elements.map((element) => parseLiteral(element));
+};
+
+/**
+ * Evaluate a JS literal expression (string / number / boolean / null / array /
+ * object) into its value without executing it. Anything else resolves to
+ * {@link UNPARSEABLE}; inside arrays the sentinel keeps the element's position,
+ * inside objects it stays as the field's value so the caller can warn and drop.
+ */
+export const parseLiteral = (source: string): LiteralValue => {
+  const trimmed = source.trim();
+  if (trimmed === "") {
+    return UNPARSEABLE;
+  }
+  const [first] = trimmed;
+  if (first === '"' || first === "'" || first === "`") {
+    return readString(trimmed) ?? UNPARSEABLE;
+  }
+  if (first === "{") {
+    return parseObjectLiteral(trimmed);
+  }
+  if (first === "[") {
+    return parseArrayLiteral(trimmed);
+  }
+  return parseScalarLiteral(trimmed);
+};
+
+/** Narrow a parsed literal to a string. */
+export const asLiteralString = (
+  value: LiteralValue | undefined
+): string | undefined => (typeof value === "string" ? value : undefined);
+
+/** Narrow a parsed literal to a plain object (not an array or `UNPARSEABLE`). */
+export const isLiteralObject = (
+  value: LiteralValue | undefined
+): value is Record<string, LiteralValue> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Narrow a parsed literal to an array. */
+export const asLiteralArray = (
+  value: LiteralValue | undefined
+): LiteralValue[] | undefined => (Array.isArray(value) ? value : undefined);