多格式代码格式化ZhijiangTang/dsh-fmt

dsh-fmt

DSH 插件：格式化 / 校验文本，支持 JSON / YAML / TOML / SQL 四种格式。纯 ESM、无构建、无原生依赖。

安装

dsh plugin --profile  add file:./plugins/dsh-fmt

（发布到 npm 后：dsh plugin --profile  add dsh-fmt）

工具

- format_text —— 输入文本与目标格式，返回规范值 { format, ok, output, error? }。

参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| text | string | 是 | - | 要格式化 / 校验的文本 |
| format | enum | 是 | - | json / yaml / toml / sql |
| indent | number | 否 | 2 | 缩进宽度（JSON/YAML 美化；SQL 的 tab 宽度） |
| sqlDialect | enum | 否 | standard | standard / postgresql / mysql / sqlite，仅 SQL 使用 |
| keywordCase | enum | 否 | upper | upper / lower / preserve，仅 SQL 使用 |

返回值

规范 JSON 值：

{
"format": "json",       // 本次使用的格式
"ok": true,             // 解析/格式化是否成功
"output": "…",          // 格式化结果（ok=true）
"error": {              // 仅 ok=false 时存在
"message": "…",
"line": 1,            // 可选
"column": 2           // 可选
}
}

解析失败不算工具失败：错误以 ok:false + error（尽力带 line/column 位置）返回，而不是抛出工具异常。

各格式示例

JSON

输入 {"b":1,"a":[1,2]}，format=json，indent=2：

{
"b": 1,
"a": [
1,
2
]
}

非法输入 {bad 返回 ok:false，error.message 含 Node 报错原文，line/column 从报错中的 position … (line L column C) 正则提取。

YAML

输入：

a:
b: 1
c: [x, y]

format=yaml 先 parse 校验，再 stringify 美化（流式数组会展开为块式）。解析失败捕获 YAMLParseError，取 linePos[0] 作为位置。

TOML

输入：

title="demo"
[owner]
name="t"

format=toml 先 parse 校验再 stringify 规范化；解析失败取 TomlError 的 line / column。

SQL

输入 select a,b from t where x=1 order by b，format=sql、keywordCase=upper：

SELECT
a,
b
FROM
t
WHERE
x = 1
ORDER BY
b

sqlDialect 映射到 sql-formatter 的 language：standard→sql、postgresql→postgresql、mysql→mysql、sqlite→sqlite。

SQL 不做语法校验的说明

format_text 的 SQL 分支本身不做主动语法校验：不先解析再格式化，直接把文本交给 sql-formatter 的 format()，多数可读 SQL 都能得到规范化输出。但 sql-formatter 底层是一个完整的 SQL 解析器，遇到根本无法解析的片段会抛错——此时同样遵循「解析失败不算工具失败」的约定，返回 ok:false + error.message，而不会让工具调用失败。

License

MIT