跳转到内容
contextlint

CTX-002 术语一致性

概述

Section titled “概述”

验证 glossary(术语表)文件中定义的别名(alias)是否在正文中被使用。当将 Database 设为正式表记,把 DB / database 注册为别名时,正文中出现 DB 会报告为 warning。这是项目作用域规则,会跨越 include 加载的所有文档进行评估。

判定不区分大小写。glossary 文件本身不在验证对象中。

为什么需要

Section titled “为什么需要”

「写 Database 还是 DB」这类表记不一致难以在评审中指出,放任不管会降低整个文档的可搜索性。尤其是用 AI 生成草稿时,同一概念容易混入多种表记。以 glossary 为单一事实源,机械化检测是否混入别名,可以保持术语一致。

选项

Section titled “选项”
字段 类型 必填 说明
glossary string ✓ 视为 glossary 的文件 glob
termColumn string ✓ 存放正式表记的列名
aliasColumn string — 存放别名的列名(可用逗号分隔指定多个)。未指定则不会检测任何内容
section string — 将 glossary 内引用的表格限定为指定章节
files string — 应用此规则的文件 glob(glossary 本身始终被排除)

aliasColumn 在形式上是 optional,但未指定时不会从 glossary 抽取别名,本规则也不会检测任何内容,实际上接近必需。

违例

Section titled “违例”
docs/glossary.md:


| Term     | Aliases       |
| -------- | ------------- |
| Database | DB, database  |


docs/design.md:


# Design


We use a DB for storage.

docs/design.md 中使用了别名 DB,因此判定为违例。

docs/design.md
  line 3  warning  "DB" should be "Database" (defined in glossary)  CTX-002

修正后

Section titled “修正后”
docs/design.md:


# Design


We use a Database for storage.

配置示例

Section titled “配置示例”
{
  "rule": "ctx002",
  "options": {
    "glossary": "docs/glossary.md",
    "termColumn": "Term",
    "aliasColumn": "Aliases",
    "files": "docs/**/*.md"
  }
}

glossary 文件预期具有如下结构。

## 术语


| Term     | Aliases       |
| -------- | ------------- |
| Database | DB, database  |
| API      | Api, api      |

Aliases 列以逗号分隔,可在单个单元格中列出多个别名。

相关规则

Section titled “相关规则”