#mbt-typeset

$ mbt-typeset --markdown 文档.md
文档.md:3:5: warning [cjk-latin-space] 中文与英文或数字之间应插入一个空格 (可自动修复)
文档.md:3:14: warning [fullwidth-punct] 中文语境中应使用全角标点「，」 (可自动修复)
文档.md:3:24: warning [ellipsis] 省略号应使用中文省略号「……」 (可自动修复)

$ mbt-typeset --markdown --fix 文档.md
文档.md: 已应用 34 处修复，剩余 0 处问题

修复前：本文使用MoonBit编写,演示常见的排版问题... 修复后：本文使用 MoonBit 编写，演示常见的排版问题……

#为什么做这个项目

#特性

• 30 条排版规则，覆盖间距、标点、引号、术语、Markdown 结构五大类
• 一键自动修复，满足幂等性：修完再修不会产生新改动
• Markdown 感知：自动跳过代码围栏、行内代码、链接地址、URL、前置元数据（front matter）
• 三种输出格式：text（人读）、json（机器读）、github（Actions 注解）
• 可配置：JSON 配置文件 + 命令行覆盖，规则可逐条开关
• 零外部依赖：纯 MoonBit 实现，只依赖标准库与 moonbitlang/x 的文件 API

#规则一览

#安装与构建

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm https://cli.moonbitlang.cn/install/powershell.ps1 | iex

curl -fsSL https://cli.moonbitlang.cn/install/unix.sh | bash

git clone <this-repo>
cd mbt-typeset
moon check        # 类型检查
moon build        # 构建

#命令行用法

用法:
  mbt-typeset [选项] <文件...>

选项:
  --fix                        就地修复可自动修复的问题
  --format <text|json|github>  输出格式（默认 text）
  --config <路径>              读取 JSON 配置
  --markdown                   按 Markdown 文档处理
  --max-line-length <n>        行宽上限（0 表示不检查）
  --rule <id=on|off>           启用/关闭某条规则（可重复）
  --terminology <源=标准>      追加术语（可重复）
  --list-rules                 列出全部规则
  -v, --version                显示版本
  -h, --help                   显示帮助

退出码:
  0  未发现问题
  1  发现 warning 及以上问题
  2  用法错误或读写失败

moon run cmd/main -- --markdown examples/before.md            # 检查
moon run cmd/main -- --markdown --fix examples/after.md        # 修复
moon run cmd/main -- --format json examples/before.md          # JSON 输出
moon run cmd/main -- --list-rules                              # 规则表

#只检查某几条规则

# 关闭术语规则，并开启「英文语境用半角标点」
moon run cmd/main -- --markdown \
  --rule terminology=off \
  --rule halfwidth-punct-in-latin=on \
  examples/before.md

#配置文件

{
  "markdown": true,
  "maxLineLength": 120,
  "rules": {
    "halfwidth-punct-in-latin": true,
    "consecutive-spaces": false
  },
  "terminology": {
    "moonbit": "MoonBit",
    "javascript": "JavaScript"
  }
}

#作为库使用

// 1. 检查：返回按位置排序的诊断列表
let diags = @lib.lint(source, @lib.Config::markdown())

// 2. 修复：返回修复结果、应用的编辑数与剩余问题
let outcome = @lib.fix(source, @lib.Config::markdown())
println(outcome.output)     // 修复后的文本
println(outcome.applied)    // 应用了多少处修复
println(outcome.remaining)  // 仍然存在、但无法自动修复的问题

// 3. 渲染：text / json / github 三种输出
let report = @lib.render_text(diags, "文档.md")

#诊断结构

pub struct Diagnostic {
  rule : String          // 规则 id
  severity : Severity    // Error | Warning | Info
  message : String       // 说明
  line : Int             // 1 起始行号
  column : Int           // 1 起始列号（按字符计）
  start : Int            // 全文字符偏移（闭端，用于修复）
  end : Int              // 全文字符偏移（开端）
  replacement : String?  // 可自动修复时的替换文本
}

#测试与验收

#1. 标准单元测试

moon test

• 一致性语料（conformance.mbt）：69 条「输入 → 期望输出」用例，是全部规则的单一事实来源； 每条用例都会校验 lint 报告了期望的规则、fix 的结果等于期望文本、并对结果再跑一次 fix 确认幂等。
• 黑盒单元测试（mbt-typeset_test.mbt）：只通过公开 API 覆盖位置计算、保护掩码、渲染输出、规则表、配置等细节。

#2. 自检程序（无需 moon test 也能跑）

moon run cmd/verify
# mbt-typeset 自检：共 69 条用例，失败 0 条
# 全部通过

#设计要点

mbt-typeset/
├── charclass.mbt      # Unicode 字符分类：CJK 文字 / CJK 标点 / 全角 / ASCII
├── types.mbt          # Diagnostic、Severity、RuleInfo、FixOutcome
├── config.mbt         # 运行配置与内置术语表
├── segment.mbt        # 扫描：切行、识别代码区域、构造逐字符「保护掩码」
├── blocks.mbt         # 块级分析：标题 / 列表 / 表格 / 缩进代码块
├── quotes.mbt         # 引号配对状态机与中文弯引号转换
├── rules.mbt          # 30 条规则 + 规则注册表
├── engine.mbt         # lint / fix（迭代到不动点）+ 位置计算
├── render.mbt         # text / json / github 渲染 + 规则表
├── conformance.mbt    # 一致性语料 + 自检入口
├── mbt-typeset_test.mbt # 黑盒测试（只走公开 API）
├── cmd/main           # 命令行工具
├── cmd/verify         # 自检程序
├── examples/          # 前后对比示例、配置示例
└── PROJECT_PROPOSAL.md # 大赛项目申报书

#为什么修复是幂等的

• 规则之间即使相互影响（例如先把半角逗号改成全角，再去掉标点旁的空格），最终也会收敛到稳定结果；
• 对同一份输入重复调用 fix，第二次不会再产生任何改动，这一点由一致性语料对每条用例强制校验。

#如何避免误伤代码

#已知边界

• 只做「确定性强」的排版规则：不做标点语义判断、不做语法检查、不做引号弯直转换（避免误伤）。
• 数字与单位规则采用保守的单位白名单（不包含单字母单位，避免把 5G 误判为 5 G）。
• halfwidth-punct-in-latin、consecutive-spaces、line-length 默认关闭，因为它们依赖具体写作约定。

#许可证