跳转到内容
contextlint

CTX-002 术语一致性

概述

Section titled “概述”

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

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

为什么需要

Section titled “为什么需要”

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

选项

Section titled “选项”
字段类型必填说明
glossarystring✓视为 glossary 的文件 glob
termColumnstring✓存放正式表记的列名
aliasColumnstring—存放别名的列名(可用逗号分隔指定多个)。未指定则不会检测任何内容
sectionstring—将 glossary 内引用的表格限定为指定章节
filesstring—应用此规则的文件 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 “相关规则”