Textlint 项目中的严重性类型不匹配问题解析

在文本校验工具 Textlint 的最新版本中，开发者发现了一个关于规则严重性级别类型定义不一致的问题。这个问题影响了开发者在使用 TextlintKernel API 时的类型安全性和运行时行为。

问题背景

Textlint 是一个强大的文本校验工具，允许开发者通过规则来检查文本内容。每个规则都可以配置一个严重性级别(severity)，用于指示该规则违反时应如何处理。在 Textlint 的实现中，存在两种不同的严重性级别表示方式：

1. 数字表示法：使用 0、1、2 分别代表不同的严重性级别
2. 字符串表示法：使用 "none"、"info"、"error"、"warn" 等字符串表示

问题表现

开发者在使用 TextlintKernel 的 lintText 方法时遇到了类型不匹配的问题：

• 当使用数字类型(如 severity: 2)时，TypeScript 类型检查通过，但运行时抛出错误
• 当使用字符串类型(如 severity: "error")时，TypeScript 类型检查失败，但运行时却能正常工作

这种类型定义与实际运行时要求的不一致导致了开发者的困惑和使用障碍。

问题根源

经过分析，这个问题源于 Textlint 项目中两处不同的类型定义：

1. 规则定义中使用了数字类型的 SeverityLevel (0|1|2)
2. 内核实现中的 getSeverity 方法却期望字符串类型的严重性级别("none"|"info"|"error"|"warn")

这种不一致导致了类型系统与实际运行时行为的分歧。

解决方案

Textlint 团队在版本 14.0.4 中修复了这个问题。解决方案是统一使用字符串形式的严重性级别表示法，这与.textlinrc.json 配置文件中的选项保持一致，提供了更好的一致性和开发者体验。

对开发者的启示

这个案例提醒我们：

1. 类型系统与实际运行时行为必须保持一致，否则会带来困惑
2. API 设计应当保持一致性，特别是当有多种配置方式时
3. 开源项目的类型定义需要与实际实现仔细对齐

对于使用 Textlint 的开发者来说，现在可以放心地使用字符串形式的严重性级别配置，这既能通过类型检查，也能在运行时正常工作。