MDX-Compiler 编译器

// 签名 1：基本用法，返回纯字符串
function mdxToMd(
  content: string,
  options?: MdxToMdOptions & { extractMetadata?: false }
): Promise<string>
 
// 签名 2：带元数据提取，返回结构化结果
function mdxToMd(
  content: string,
  options: MdxToMdOptions & { extractMetadata: true }
): Promise<MdxToMdResult>

interface MdxToMdResult {
  /** 编译后的 Markdown 内容 */
  content: string
  /** 从 export 语句和 YAML frontmatter 中提取的元数据 */
  metadata: ExportMetadata
}
 
interface ExportMetadata {
  /** 提取的字段键值对 */
  fields: Record<string, unknown>
  /** 元数据来源类型 */
  source: 'export' | 'yaml' | 'mixed'
}

function buildPromptTomlArtifact(
  options: BuildPromptTomlArtifactOptions
): string

function buildTomlDocument(
  value: Readonly<Record<string, unknown>>,
  options?: BuildTomlDocumentOptions
): string
 
interface BuildTomlDocumentOptions {
  readonly fieldOrder?: readonly string[]
}

// 解析器插件链
const processor = unified()
  .use(remarkParse)        // 标准 Markdown 解析
  .use(remarkGfm)          // GFM 扩展（表格、任务列表、删除线）
  .use(remarkFrontmatter, ['yaml'])  // YAML frontmatter 支持
  .use(remarkMdx)          // MDX 扩展（JSX、表达式、ESM）

// 简单引用：直接属性查找
const SIMPLE_REFERENCE_PATTERN = /^[a-z_$][\w$]*(?:\.[a-z_$][\w$]*)*$/iu
 
// 复杂表达式：Function 构造器
const fn = new Function(...scopeKeys, `return (${expression})`)
const result = fn(...scopeValues)

type ComponentHandler = (
  element: MdxJsxFlowElement | MdxJsxTextElement,
  ctx: ProcessingContext,
  processChildren: (children: RootContent[], ctx: ProcessingContext) => Promise<RootContent[]>
) => Promise<RootContent[]>

<Md when={someCondition}>
  仅当条件为真时渲染的内容
</Md>
 
<Md.Line when={isVisible}>
  行内条件文本
</Md.Line>

// 模式 1: 单个命名导出
export const title = "My Document"
 
// 模式 2: 对象展开导出（metadata 特殊键）
export const metadata = { name: "test", enabled: true }
 
// 模式 3: default 导出（对象会被展开）
export default { title: "Default Title", version: 2 }

interface MdxGlobalScope {
  profile: UserProfile       // 用户档案信息
  codeStyles: CodeStylePreferences  // 代码风格偏好
  tool: ToolReferences       // AI 工具名称引用
  env: EnvironmentContext     // 环境变量上下文
  os: OsInfo                 // 操作系统信息
  Md: MdComponent            // 条件渲染组件
}

import { ToolPresets } from '@truenine/memory-sync-sdk/globals'
 
// 默认预设 (snake_case)
ToolPresets.default
// → { websearch: 'web_search', readFile: 'read_file', ... }
 
// Claude Code CLI 预设 (PascalCase)
ToolPresets.claudeCode
// → { readFile: 'Read', writeFile: 'Write', executeCommand: 'Execute', ... }
 
// Kiro 预设 (camelCase)
ToolPresets.kiro
// → { readFile: 'readFile', websearch: 'remote_web_search', ... }

import { mdxToMd } from '@truenine/memory-sync-sdk'
 
const mdxSource = `
# Hello MDX
 
Welcome to **MDX-Compiler**!
 
This is a {typeof mdx === 'undefined' ? 'compiled' : 'raw'} document.
 
- Item 1
- Item 2
- Item 3
`.trim()
 
const markdown = await mdxToMd(mdxSource)
 
console.log(markdown)
// 输出:
// # Hello MDX
//
// Welcome to **MDX-Compiler**!
//
// This is a compiled document.
//
// - Item 1
// - Item 2
// - Item 3

import { mdxToMd, MdxToMdOptions } from '@truenine/memory-sync-sdk'
 
const mdxSource = `
# Profile Page
 
Hello, {profile.name}!
 
Your OS is {os.platform} ({os.arch}).
 
Environment: {env.NODE_ENV ?? 'development'}
 
<Md when={profile.role === 'admin'}>
  > Admin-only content visible here.
</Md>
 
Tools available: {tool.readFile}, {tool.writeFile}
`.trim()
 
const options: MdxToMdOptions = {
  filePath: '/templates/profile.mdx',
  basePath: '/templates',
  globalScope: {
    profile: { name: 'Alice', role: 'admin', username: 'alice' },
    codeStyles: { indent: 'space', tabSize: 2 },
    tool: { readFile: 'read_file', writeFile: 'write_file' },
    env: { NODE_ENV: 'production' },
    os: { platform: 'linux', arch: 'x64', kind: 'linux' as const }
  },
  scope: {
    customVar: 'custom value'
  }
}
 
const result = await mdxToMd(mdxSource, { ...options, extractMetadata: true })
 
console.log(result.content)
console.log(result.metadata)
// metadata:
// {
//   fields: {},
//   source: 'yaml'
// }

import { mdxToMd, buildPromptTomlArtifact } from '@truenine/memory-sync-sdk'
 
const promptContent = `
# System Prompt
 
You are a helpful assistant.
 
## Instructions
 
- Be concise
- Use Markdown formatting
`.trim()
 
const tomlOutput = buildPromptTomlArtifact({
  content: promptContent,
  bodyFieldName: 'prompt_content',
  frontMatter: {
    role: 'system',
    model: 'claude-sonnet-4-20250514',
    temperature: 0.7,
    max_tokens: 4096
  },
  fieldNameMap: {
    role: 'role',
    temperature: 'temperature',
    max_tokens: 'max_tokens'
  },
  excludedKeys: ['internal_note'],
  extraFields: {
    version: '1.0.0',
    generated_at: new Date().toISOString()
  },
  fieldOrder: ['role', 'model', 'temperature', 'max_tokens', 'prompt_content', 'version', 'generated_at']
})
 
console.log(tomlOutput)
// 输出类似:
// role = "system"
// model = "claude-sonnet-4-20250514"
// temperature = 0.7
// max_tokens = 4096
// version = "1.0.0"
// generated_at = "2026-04-12T..."
//
// prompt_content = """
// # System Prompt
//
// You are a helpful assistant.
//
// ## Instructions
//
// - Be concise
// - Use Markdown formatting
// """

import { mdxToMd } from '@truenine/memory-sync-sdk'
 
const mdxWithExports = `
---
author: yaml-author
tags: [from-yaml]
---
 
export const title = "My Document"
export const version = 2
export const enabled = true
export const tags = ["mdx", "compiler"]
export const metadata = { category: "docs", priority: "high" }
export default { description: "A sample document" }
 
# {title}
 
Version: {version}, Enabled: {enabled}
`.trim()
 
const result = await mdxToMd(mdxWithExports, {
  filePath: '/docs/sample.mdx',
  extractMetadata: true,
  scope: {}
})
 
console.log(JSON.stringify(result.metadata, null, 2))
// 输出:
// {
//   "fields": {
//     "author": "yaml-author",
//     "tags": ["mdx", "compiler"],
//     "title": "My Document",
//     "version": 2,
//     "enabled": true,
//     "category": "docs",
//     "priority": "high",
//     "description": "A sample document"
//   },
//   "source": "mixed"
// }
//
// 注意:
// - "tags" 被 export 覆盖了 YAML 中的值 (export 优先)
// - metadata 对象的属性被展开到顶层
// - export default 的对象也被展开
// - author 仅来自 YAML (无同名 export)

import {
  mdxToMd,
  registerComponent,
  clearComponents,
  type ComponentHandler,
  type MdxJsxFlowElement,
  type ProcessingContext,
  type RootContent
} from '@truenine/memory-sync-sdk'
 
// 定义一个 <Alert> 组件
const alertHandler: ComponentHandler = async (
  element: MdxJsxFlowElement,
  ctx: ProcessingContext,
  processChildren
) => {
  const typeAttr = element.attributes.find(
    a => a.type === 'mdxJsxAttribute' && a.name === 'type'
  )
  const alertType = typeof typeAttr?.value === 'string' ? typeAttr.value : 'info'
 
  const children = await processChildren(element.children as RootContent[], ctx)
 
  const prefixMap: Record<string, string> = {
    warning: '> ⚠️ ',
    error: '> ❌ ',
    info: '> ℹ️ ',
    success: '> ✅ '
  }
 
  const prefix = prefixMap[alertType] || '> '
 
  return [{
    type: 'blockquote',
    children: [
      { type: 'paragraph', children: [{ type: 'text', value: prefix }] },
      ...children.map(child =>
        child.type === 'paragraph' ? child : { type: 'paragraph', children: [child] }
      )
    ]
  }]
}
 
// 注册组件
registerComponent('Alert', alertHandler)
 
const mdx = `
# Custom Components
 
<Alert type="warning">
  This is a warning message with **bold** text inside.
</Alert>
 
<Alert type="success">
  Operation completed successfully!
</Alert>
`.trim()
 
const result = await mdxToMd(mdx)
console.log(result)
 
// 清理（通常在测试中使用）
clearComponents()

interface CompilerDiagnostic {
  filePath?: string          // 源文件路径
  line?: number              // 起始行号
  column?: number            // 起始列号
  endLine?: number           // 结束行号
  endColumn?: number         // 结束列号
  snippet?: string           // 错误位置代码片段
  sourceLine?: string        // 所在行的完整源码
  codeFrame?: string         // 带指针的代码帧
  expression?: string        // 导致错误的表达式
  exportName?: string        // 相关的导出名
  nodeType?: string          // AST 节点类型
  phase?: string             // 编译阶段标识
  hint?: string              // 修复建议
  cause?: string             // 底层原因
}

import {
  mdxToMd,
  UndefinedVariableError,
  UndefinedNamespaceError,
  ExportParseError,
  MetadataValidationError,
  formatCompilerDiagnostic
} from '@truenine/memory-sync-sdk'
 
try {
  const result = await mdxToMd(mdxSource, { filePath: '/path/to/file.mdx', extractMetadata: true })
  return result
} catch (error) {
  if (error instanceof UndefinedVariableError) {
    console.error(`未定义变量: ${error.variableName}`)
    console.error(`表达式: ${error.diagnostic.expression}`)
    console.error(formatCompilerDiagnostic(error))
  } else if (error instanceof UndefinedNamespaceError) {
    console.error(`未定义命名空间: ${error.namespace}`)
    console.error('可用的作用域键:', Object.keys(scope).join(', '))
  } else if (error instanceof ExportParseError) {
    console.error(`导出解析失败: ${error.exportName ?? 'default'}`)
    console.error(error.diagnostic.hint ?? '请确保导出值为静态可求值的字面量')
  } else if (error instanceof MetadataValidationError) {
    console.error(`缺少必需字段: ${error.missingFields.join(', ')}`)
  } else {
    throw error  // 重新抛出未知错误
  }
}

// ===== 核心类型 (来自 types.ts) =====
 
interface EvaluationScope {
  [key: string]: unknown
}
 
interface MdxToMdOptions {
  scope?: EvaluationScope
  basePath?: string
  filePath?: string
  globalScope?: MdxGlobalScope
  extractMetadata?: boolean
}
 
interface MdxToMdResult {
  content: string
  metadata: ExportMetadata
}
 
interface ProcessingContext {
  scope: EvaluationScope
  components: Map<string, ComponentHandler>
  processingStack: string[]
  basePath?: string
  filePath?: string
  sourceText?: string
}
 
type ComponentHandler = (
  element: MdxJsxFlowElement | MdxJsxTextElement,
  ctx: ProcessingContext,
  processChildren: (children: RootContent[], ctx: ProcessingContext) => Promise<RootContent[]>
) => Promise<RootContent[]>
 
// ===== MDX AST 节点类型 (来自 mdast-util-mdx) =====
 
type MdxFlowExpression      // 块级表达式 {expr}
type MdxTextExpression      // 行内表达式 {expr}
type MdxjsEsm               // ESM import/export 语句
type MdxJsxFlowElement      // 块级 JSX 元素 <Component />
type MdxJsxTextElement      // 行内 JSX 元素 <span />
 
// ===== MDAST 基础类型 (来自 mdast) =====
 
type Root                    // AST 根节点
type RootContent             // 根节点子元素的联合类型
 
// ===== 导出元数据类型 (来自 export-parser.ts) =====
 
type MetadataSource = 'export' | 'yaml' | 'mixed'
 
interface ExportMetadata {
  fields: Record<string, unknown>
  source: MetadataSource
}
 
// ===== TOML 构建类型 (来自 toml.ts) =====
 
interface BuildTomlDocumentOptions {
  fieldOrder?: readonly string[]
}
 
interface BuildPromptTomlArtifactOptions extends BuildTomlDocumentOptions {
  content: string
  bodyFieldName: string
  frontMatter?: Readonly<Record<string, unknown>>
  fieldNameMap?: Readonly<Record<string, string>>
  excludedKeys?: readonly string[]
  extraFields?: Readonly<Record<string, unknown>>
}
 
// ===== 全局作用域类型 (来自 globals/) =====
 
interface UserProfile { name?, username?, gender?, birthday?: string; [key: string]: unknown }
interface CodeStylePreferences { indent?, tabSize?: number; [key: string]: unknown }
interface ToolReferences { [key: string]: string | undefined }
interface EnvironmentContext { [key: string]: unknown }
enum ShellKind { Bash, Zsh, Fish, Sh, PowerShell, Pwsh, Cmd, Unknown }
enum OsKind { Win, Mac, Linux, Unknown }
interface OsInfo { platform?, arch?, hostname?, shellKind?: ShellKind, kind?: OsKind; [key: string]: string | ShellKind | OsKind | undefined }
interface MdGlobalScope { profile, codeStyles, tool, env, os, Md }