feat: #206 add configurable SQL formatting with formatSQL API

[Cythia828]

Feat

#226

---

概述

关联 #206。新增可选、可配置的 SQL 格式化能力，基于 sql-formatter。只做补全/诊断的接入方不必安装该依赖。

双入口设计

入口	作用
主入口 monaco-sql-languages	运行时不解析 sql-formatter，仅通过 setupLanguageFeatures + formatBridge 协作
子路径 monaco-sql-languages/format	副作用注册内置 Format 动作；导出 formatSQL / formatEditorSQL 等；格式化时再 import('sql-formatter')

import 'monaco-sql-languages/format'          // ① 必须先执行一次
setupLanguageFeatures(lang, { format: { enable: true } })  // ②
        ↓
formatBridge 注册器 → registerFormatAction
        ↓
formatEditorSQL → formatSQL → import('sql-formatter')

• package.json 的 exports：. · ./format · ./esm/*
• 可选 peer：sql-formatter >= 10.7.2（optional: true）
• Chrome 75 请固定 sql-formatter@10.7.2；现代浏览器可用 15+

如何开启（两步，缺一不可）

import { KeyCode, KeyMod } from 'monaco-editor';
import 'monaco-sql-languages/format'; // 必须在 enable 之前
import { LanguageIdEnum, setupLanguageFeatures } from 'monaco-sql-languages';

setupLanguageFeatures(LanguageIdEnum.MYSQL, {
  format: {
    enable: true, // 注册右键菜单 / 快捷键所必需
    tabWidth: 4,
    fallback: (code, languageId) => myLegacyFormat(code, languageId),
    keybindings: [KeyMod.CtrlCmd | KeyMod.Shift | KeyCode.KeyF] // 可选
  }
});

工具栏或其它调用（构建期需要已安装 peer）：

import { formatEditorSQL, formatSQL } from 'monaco-sql-languages/format';

await formatEditorSQL(editor, { tabWidth: 4, fallback: myLegacyFormat });
const text = await formatSQL(code, LanguageIdEnum.MYSQL, { tabWidth: 4 });

行为说明

• 默认关闭（format.enable 默认为 false）
• 优先级： sql-formatter → fallback（不可用或抛错）→ 原文
• 未 import /format 却 enable: true： console.error + 抛错
• 稍后才 import /format： 对已加载且开启 format 的语言做补偿注册（异步 setupMode 带序号，避免竞态覆盖）
• 选区： 有选区则只格式化选区，否则整篇；结果与原文相同则不写 edits
• tabWidth： 默认 4；小于 1 或非有限值回退为 4；小数向下取整
• 方言： MySQL / PG / Spark / Hive / Trino 有专用映射；Flink / Impala / Generic 走标准 SQL
• 快捷键： 默认 Ctrl/Cmd+Alt+F（右键 Format），可用 keybindings 覆盖

文档 / 演示 / Website

• 中英文 README：安装规则、两步开启、抛错与补偿、版本说明
• Website：import '…/esm/format.entry'、共享 formatFallback、工具栏调用 formatEditorSQL
• Website 构建：统一 monaco-editor@0.54.0（tsconfig / vite 别名 + pnpm overrides），避免双份 monaco 类型冲突

测试

• format.test.ts：方言、fallback、加载失败、tabWidth 钳制、选区切片、空操作
• formatBridge.test.ts：缺失入口断言、registrar ready 回调 / 立即回放

迁移注意

1. 仅在需要格式化时安装可选 peer
2. 先 import 'monaco-sql-languages/format'，再 setupLanguageFeatures(..., { format: { enable: true } })
3. 格式化运行时 API 不在主入口，请从 monaco-sql-languages/format 引入