ClassyGitShadowzzh

index.ts

index.ts

/**
 * MDX 編譯與「可渲染性」檢查的**唯一一份實作**。
 *
 * 抽成套件的理由是這裡本來就已經抄了兩份:`src/lib/mdx/mdx-compile-core.ts` 的檔頭自己寫著
 * 「如果那支腳本自己抄一份選項,日後有人在這裡加 plugin,檢查器會用舊的那組編——
 * 過了也不代表線上過,那種檢查比沒有還糟」,而 `packages/mcp-server/src/validate.ts`
 * 正是又抄了一份。三個使用者:
 *
 *   · `src/lib/mdx/mdx-compile.ts`(createServerFn)→ 前台渲染
 *   · `scripts/check-mdx.ts`(CI 每日)→ 已發布文章
 *   · `packages/mcp-server/src/validate.ts` → agent 送出前的自檢
 *
 * ## 為什麼產出的是 hast 而不是 JS
 *
 * 以前是 `outputFormat: 'function-body'` → 前端 `runSync`(底層 `new Function`)。
 * 那需要 CSP 的 `'unsafe-eval'`,也就是把整個站的 `script-src` 打開。
 *
 * 改成輸出**序列化的 hast 樹**,前端用 `hast-util-to-jsx-runtime` 渲染,沒有任何
 * 字串轉程式碼。實測 15 篇 × 5 語系兩條路徑產出的 HTML **逐字相同**;
 * 傳輸量 gzip 後只差 2%(未壓縮 +53%,但 JSON 壓得比 minify 過的 JS 好)。
 *
 * ## 代價:MDX 只能「叫元件、餵資料」
 *
 * 屬性值必須是字面值(字串/數字/布林/陣列/物件),不能有運算式、import/export
 * 或展開屬性。這不是暫時的限制而是設計:文章內容由 agent 產出、人工 review,
 * 而「在文章裡寫一小段 JS」這個逃生口一旦開著,MDX 就變成沒人 review 得動的程式碼。
 *
 * 元件那一側完全不受限——想要計算機、圖表、股票元件,寫成 React 元件註冊進去即可。
 */
/**
 * 這裡刻意用**最小的結構型別**而不是 `@types/hast`。
 *
 * 理由:這個模組對樹的處理只有兩件事——走訪 children、認幾種 mdx 節點型別。
 * 拉進完整的 hast 型別會讓三個使用者(前端/scripts/MCP)都得裝 @types/hast,
 * 而它們對這棵樹的其餘部分本來就當成不透明的 JSON。
 */
export interface HastNode {
  type: string;
  children?: HastNode[];
  [k: string]: unknown;
}

/** 前端渲染不了的構造。訊息會直接被 agent 與 CI 看到,所以要講「怎麼改」而不只是「錯了」。 */
export class MdxUnsupportedError extends Error {
  readonly line: number | undefined;
  constructor(message: string, line?: number) {
    super(message);
    this.name = 'MdxUnsupportedError';
    this.line = line;
  }
}

/**
 * 抽掉只有編譯期才需要的欄位。**必做**:不抽的話 payload 是 3.8 倍。
 *
 * ⚠ `data.estree` **不能抽掉**。屬性值(`options={[…]}`)是靠它傳到前端的——
 *   `hast-util-to-jsx-runtime` 對 mdxJsx 節點就是讀 `attribute.value.data.estree`
 *   再交給 evaluater。第一版把它一起抽了,結果編譯正常、樹裡也有 `<Poll>`,
 *   但前端渲染出來是空的(屬性全不見)。抽掉的是 estree 裡的**位置資訊**,
 *   那些欄位佔大部分體積而 evaluater 一個都用不到。
 */
const POSITIONAL = new Set(['position', 'loc', 'range', 'start', 'end']);

function slim(node: unknown): unknown {
  if (Array.isArray(node)) return node.map(slim);
  if (!node || typeof node !== 'object') return node;
  const out: Record<string, unknown> = {};
  for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
    if (POSITIONAL.has(k)) continue;
    out[k] = slim(v);
  }
  return out;
}

interface EstreeNode {
  type: string;
  [k: string]: unknown;
}

/**
 * estree 字面值 → JS 值。碰到任何「要算才知道」的東西就丟錯。
 *
 * 這個函式就是那條界線。它決定了前端不需要 `'unsafe-eval'`——不是靠約定,
 * 是靠這裡把所有非字面值擋掉。
 */
export function literalValue(node: EstreeNode, where: string, line?: number): unknown {
  switch (node.type) {
    case 'Literal':
      return (node as unknown as { value: unknown }).value;
    case 'ArrayExpression':
      return (node.elements as EstreeNode[]).map((e) => literalValue(e, where, line));
    case 'ObjectExpression':
      return Object.fromEntries(
        (node.properties as EstreeNode[]).map((p) => {
          if (p.type !== 'Property') {
            throw new MdxUnsupportedError(`${where}:物件裡不支援 ${p.type}(例如展開 ...x)`, line);
          }
          const key = p.key as { type: string; name?: string; value?: unknown };
          const k = key.type === 'Identifier' ? (key.name ?? '') : String(key.value);
          return [k, literalValue(p.value as EstreeNode, where, line)];
        }),
      );
    case 'UnaryExpression': {
      const u = node as unknown as { operator: string; argument: EstreeNode };
      if (u.operator === '-') return -(literalValue(u.argument, where, line) as number);
      throw new MdxUnsupportedError(`${where}:不支援一元運算子 ${u.operator}`, line);
    }
    case 'TemplateLiteral': {
      const t = node as unknown as { expressions: unknown[]; quasis: { value: { cooked: string } }[] };
      if (t.expressions.length === 0) return t.quasis[0].value.cooked;
      throw new MdxUnsupportedError(`${where}:樣板字串裡有運算式。屬性值必須是寫得死的內容,把結果直接寫出來。`, line);
    }
    default:
      throw new MdxUnsupportedError(
        `${where}:屬性值是運算式(${node.type}),前端不會執行它。` +
          `屬性只能放字面值——字串、數字、布林、陣列、物件。要算的東西請放進元件裡。`,
        line,
      );
  }
}

/**
 * 走一遍樹,把渲染不了的構造挑出來。
 *
 * 在**編譯時**就檢查(而不是等前端渲染失敗)是刻意的:前端的失敗模式是
 * 「靜默退回 markdown、讀者看到裸標籤」,那種錯誤沒有人會發現。
 */
export function assertRenderable(tree: HastNode, knownComponents?: ReadonlySet<string>): void {
  const line = (n: HastNode): number | undefined =>
    (n as { position?: { start?: { line?: number } } }).position?.start?.line;

  const walk = (node: HastNode): void => {
    switch (node.type) {
      case 'mdxjsEsm':
        throw new MdxUnsupportedError(
          'MDX 裡不支援 import / export。要用的元件請註冊到 mdx-blocks-registry。',
          line(node),
        );
      case 'mdxFlowExpression':
      case 'mdxTextExpression': {
        const raw = (node as { value?: unknown }).value;
        const v = (typeof raw === 'string' ? raw : '').slice(0, 40);
        throw new MdxUnsupportedError(
          `內文裡有運算式 {${v}},前端不會執行它。把結果直接寫出來,或做成元件。`,
          line(node),
        );
      }
      case 'mdxJsxFlowElement':
      case 'mdxJsxTextElement': {
        const el = node as unknown as {
          name: string | null;
          attributes: { type: string; name?: string; value?: unknown }[];
        };
        const tag = el.name ?? '<>';
        if (el.name && /^[A-Z]/.test(el.name) && knownComponents && !knownComponents.has(el.name)) {
          throw new MdxUnsupportedError(`<${el.name}> 沒有註冊。可用的元件見 mdx-blocks-registry。`, line(node));
        }
        // mdx-jsx 節點一定有 attributes 陣列(沒屬性就是空陣列),所以不需要 `?? []`。
        for (const a of el.attributes) {
          if (a.type === 'mdxJsxExpressionAttribute') {
            throw new MdxUnsupportedError(`<${tag}>:不支援展開屬性 {...x},請把屬性寫開。`, line(node));
          }
          const v = a.value;
          if (v && typeof v === 'object') {
            const estree = (v as { data?: { estree?: { body?: { expression?: EstreeNode }[] } } }).data?.estree;
            const expr = estree?.body?.[0]?.expression;
            if (!expr) {
              throw new MdxUnsupportedError(`<${tag}> 的 ${a.name}:解不出屬性值`, line(node));
            }
            // 只是要它丟錯;值本身在渲染時才會用到
            literalValue(expr, `<${tag}> 的 ${a.name}`, line(node));
          }
        }
        break;
      }
      default:
        break;
    }
    for (const c of (node as { children?: HastNode[] }).children ?? []) walk(c);
  };
  walk(tree);
}

/**
 * MDX 原始碼 → hast 樹(尚未 slim,帶 position,給診斷用)。
 *
 * plugin 組合與 markdown 管線對齊:GFM(表格/刪除線/腳註)+ GitHub 式彩色 alert。
 */
export async function mdxToHast(source: string): Promise<HastNode> {
  const { createProcessor } = await import('@mdx-js/mdx');
  const remarkGfm = (await import('remark-gfm')).default;
  const { remarkAlert } = await import('remark-github-blockquote-alert');

  // 用物件屬性承載而不是 `let captured`:賦值發生在 plugin 的閉包裡,TS 的流程分析看不到,
  // 會把 `let` 收窄成永遠是 null,於是底下的檢查被判成「永遠為真」。物件屬性不會被收窄
  // (跟 SketchBlock 的 `alive.current` 同一個做法)。
  const out: { tree: HastNode | null } = { tree: null };
  const processor = createProcessor({
    outputFormat: 'function-body',
    development: false,
    remarkPlugins: [remarkGfm, remarkAlert],
    // ⚠ 掛在 rehype 階段的最後一支:`.run()` 會一路跑到 recma(產 estree),
    //   在這裡才攔得到「即將被轉成 JS 之前」的 hast,也就是我們要的那棵樹。
    rehypePlugins: [
      () => (tree: HastNode) => {
        out.tree = tree;
      },
    ],
  });
  // run() 的型別宣告是 Program(管線終點是 recma),但我們在 rehype 階段就攔走了樹
  await processor.run(processor.parse(source) as never);
  if (!out.tree) throw new Error('MDX 管線沒有產出 hast 樹');
  return out.tree;
}

/**
 * MDX 原始碼 → 可直接送到前端的 JSON 字串。
 *
 * 不可渲染的構造會在這裡丟 `MdxUnsupportedError`——呼叫端(blogList)接到之後
 * 退回 markdown 渲染,跟以前編譯失敗的行為一致。
 */
export async function compileMdxToHastJson(source: string, knownComponents?: ReadonlySet<string>): Promise<string> {
  const tree = await mdxToHast(source);
  assertRenderable(tree, knownComponents);
  return JSON.stringify(slim(tree));
}