ty 中 unused-type-ignore-comment 规则：检测并清理失效的 `type: ignore` 注释

本文以 Ruff 仓库内置类型检查器 ty 的规则文档为骨架，深入讲解 unused-type-ignore-comment 规则的用途、判定逻辑、配置方式与自动修复行为。通过本文，你将掌握如何在 ty 项目中定位不再生效的 type: ignore 注释，理解它与 ty: ignore 规则的差异，并学会通过 respect-type-ignore-comments 配置项控制该规则的行为。

规则概述：检测不再适用的 type: ignore 指令

unused-type-ignore-comment 是 ty 类型检查器内置的一条 lint 规则，其职责是检查那些已经无法匹配任何诊断违规的 type: ignore 注释。

在源码中，该规则通过 declare_lint! 宏声明于 crates/ty_python_semantic/src/suppression.rs：

declare_lint! {
    #[doc = include_str!("../resources/lint_docs/unused-type-ignore-comment.md")]
    pub(crate) static UNUSED_TYPE_IGNORE_COMMENT = {
        summary: "detects unused `type: ignore` comments",
        status: LintStatus::stable("0.0.14"),
        default_level: Level::Warn,
    }
}

从中可以确认三条关键事实：

• 规则 ID：unused-type-ignore-comment，其文档正文直接由 include_str! 从本篇文章对应的文档文件 crates/ty_python_semantic/resources/lint_docs/unused-type-ignore-comment.md 注入；
• 默认级别：warn，即默认启用且以警告级别输出；
• 稳定版本：自 0.0.14 起标记为稳定（stable）。

与之配套的还有一条面向 ty: ignore 的姊妹规则 unused-ignore-comment（声明于同一文件的 L29-L36），默认级别同样是 warn。两条规则共享同一套"未使用抑制"检测流程，只是分别针对 type: ignore 与 ty: ignore 两种注释形式，这一点在 crates/ty/docs/rules.md 中有完整的规则索引说明。

为什么这是问题

type: ignore 注释的作用是显式告诉类型检查器"这一行我已经检查过，请忽略这里的类型错误"。当代码演化后，原本被抑制的错误已经消失（例如修好了类型问题、重构了表达式、依赖升级后类型更精确），这条注释就成了悬空的抑制指令：

• 它不再承担任何实际功能，会误导后续阅读代码的人，让人以为"这里曾经有（或仍然有）一个被刻意忽略的错误"；
• 它会掩盖真实的代码状态——读者无法判断这行代码是"有意忽略错误"还是"忘记删除旧注释"；
• 积少成多后，代码库中的无效抑制注释会稀释真正需要 type: ignore 的位置的可读性。

因此规则文档给出的结论是：这类注释很可能是被误加的，应当删除以避免混淆。

触发示例与修复

规则文档给出了最典型的触发场景——type: ignore 被加在了一条根本不会产生类型错误的代码行上：

# error
a = 20 / 2  # type: ignore

20 / 2 是合法的整数除法，ty 不会在此报告任何类型错误，因此这条 type: ignore 永远不会被用到。正确写法是直接删除注释：

a = 20 / 2

更多真实场景：来自 mdtest 的快照证据

在 ty 的 mdtest 测试语料中，可以找到该规则的丰富实证。例如 crates/ty_python_semantic/resources/mdtest/suppressions/type_ignore.md 中的"Unused ignore comment"一节，展示了带 ty: 前缀代码的未使用抑制及其完整修复快照：

# snapshot
a = 10 / 2  # type: ignore[ty:division-by-zero]

对应的快照输出：

warning[unused-type-ignore-comment]: Unused `type: ignore` directive
 --> src/mdtest_snippet.py:2:13
  |
2 | a = 10 / 2  # type: ignore[ty:division-by-zero]
  |             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
help: Remove the unused suppression comment
  |
1 | # snapshot
  - a = 10 / 2  # type: ignore[ty:division-by-zero]
2 + a = 10 / 2
  |

可以看到，诊断会精确高亮整条抑制注释，并给出 Remove the unused suppression comment 的修复提示与对应的删除编辑。

部分代码未使用时只删除失效部分

当一条 type: ignore[...] 中只有部分代码失效时，ty 不会删除整条注释，而是只移除未使用的代码。同一份 mdtest 文件中的"Unused ignore comment mixed with mypy comments"一节（L307-L326）演示了该行为：

# snapshot
a = 10 / 2  # type: ignore[mypy-code, ty:division-by-zero]

快照输出：

warning[unused-type-ignore-comment]: Unused `type: ignore` directive: 'division-by-zero'
 --> src/mdtest_snippet.py:2:39
  |
2 | a = 10 / 2  # type: ignore[mypy-code, ty:division-by-zero]
  |                                       ^^^^^^^^^^^^^^^^^^^
help: Remove the unused suppression code
  |
1 | # snapshot
  - a = 10 / 2  # type: ignore[mypy-code, ty:division-by-zero]
2 + a = 10 / 2  # type: ignore[mypy-code]
  |

注意这里的细节：mypy-code 不属于 ty 认识的代码（见下文"代码白名单"），因此被保留，只有 ty:division-by-zero 被判定为未使用并删除。

工作原理：从源码看"未使用"如何判定

规则的判定并不是简单的字符串匹配，而是建立在 ty 完整的抑制注释（suppression）基础设施之上，核心逻辑位于 crates/ty_python_semantic/src/suppression/unused.rs 的 check_unused_suppressions 函数。

整体流程如下：

1. 收集抑制：ty 对每个文件调用 suppressions()（见 suppression.rs 的 L78-L139），遍历 token 流，用 SuppressionParser 解析出所有的 type: ignore / ty: ignore 注释，构建 Suppressions 索引（含文件级抑制 file 与行内抑制 inline 两个集合）。
2. 类型检查：在类型检查过程中，每当一个诊断被某个抑制注释"吸收"（即命中），该抑制的 ID 会被标记为 used。
3. 兜底比对：类型检查结束后，遍历全部抑制注释，凡是没有被标记为 used 的，即为未使用抑制，进入 unused-type-ignore-comment（或 unused-ignore-comment）的报告流程。

关键代码片段（suppression.rs L36-L57）：

// Collect all suppressions that are unused after type-checking.
for suppression in all.iter() {
    if diagnostics.is_used(suppression.id()) {
        continue;
    }
    ...
    unused.push(suppression);
}

报告时还会按抑制目标区分不同消息（unused.rs L80-L198）：

抑制形态	诊断消息
type: ignore（无代码，抑制全部）	Unused blanket \type: ignore` directive`
type: ignore[ty:xxx] 且全部代码未使用	Unused \type: ignore` directive`
type: ignore[ty:xxx] 且部分代码未使用	Unused \type: ignore` directive: 'xxx'`
type: ignore[]（空代码列表）	Unused \type: ignore` without a code`

所有相关诊断都会被加上 DiagnosticTag::Unnecessary 标签（表示"非必要代码"），便于下游工具（如 IDE 的灰色提示）识别。

自动修复的精细处理

remove_comment_fix 函数（unused.rs L209-L250）负责生成删除编辑，它需要处理多种文本布局：

• 注释后还有其他内容（如 # ty: ignore # fmt: off）：只删除 type: ignore 注释本身；若删除后会把后续注释提升为行首主注释，则退化为 unsafe 修复，否则为 safe；
• 行内注释独占一行且有缩进：删除整个物理行；
• 行尾普通注释：连同注释前的空白一起删除，避免产生行尾多余空格。

这些细节保证了自动修复在任何情况下都不会破坏 # fmt: off / # fmt: skip 等相邻格式化指令。

type: ignore 与 ty: ignore 的语义差异

理解本规则，必须分清 ty 支持的两类抑制注释。从 SuppressionKind 枚举 可以看出，ty 内部将它们建模为 TypeIgnore 与 Ty 两种类型。

关键差异在于独立成行的 type: ignore 语义。mdtest 文档（type_ignore.md L266-L277）明确说明：

Unlike ty: ignore, an own-line type: ignore does not suppress the following line (unless it appears before any Python statements in the file, in which case it suppresses the entire file). This preserves the standardized semantics of type: ignore comments.

即：

• 行尾的 type: ignore：只抑制同一行的诊断（多行表达式可抑制起点或终点所在行）；
• 独立成行的 type: ignore：不抑制下一行，除非它位于文件顶部、任何非 trivia token（含模块 docstring）之前——此时它成为文件级抑制，作用于整个文件；
• ty: ignore 的独立成行形式则更宽松，可以覆盖后续的逻辑行。

因此，一个独立成行的 type: ignore 若没有处于文件头部，就会立刻触发 unused-type-ignore-comment（因为按标准语义它什么都抑制不了）。mdtest 中有专门用例（L270-L277）：

seen_code = True

# error: [unused-type-ignore-comment]
# type: ignore
# error: [unresolved-reference]
value = missing

同时，文件级 type: ignore 必须位于所有非 trivia 内容之前（L251-L264），否则同样会被判定为未使用：

"""
File level suppressions must come before any non-trivia token,
including module docstrings.
"""

# error: [unused-type-ignore-comment] "Unused blanket `type: ignore` directive"
# type: ignore

a = 10 / 0  # error: [division-by-zero]

代码白名单：只认 ty: 前缀

与 mypy 类似，ty 也支持 type: ignore[codes] 形式，但有一个刻意设计：ty 只认可以 ty: 开头的代码，其余一律视为其他类型检查器的注释而不予处理，从而避免与 mypy 等工具的抑制代码产生歧义。

这一点在 suppression.rs 的 add_comment 逻辑 L663-L672 中实现：

// For `type:ignore`, ignore codes that don't start with `ty:`.
let code = if comment.kind().is_type_ignore() {
    if let Some(prefix) = code.strip_prefix("ty:") {
        prefix
    } else {
        continue;
    }
} else {
    code
};

实际效果（mdtest L133-L140）：

a = test  # type: ignore[name-defined, ty:unresolved-reference]

其中 name-defined 会被忽略，只有 ty:unresolved-reference 生效。若 type: ignore[ty:xxx] 中的 ty:xxx 本身是未知代码，则会触发另一条规则 ignore-comment-unknown-rule（见 L349-L361），并给出"你是否想写 division-by-zero"之类的提示。

配置：analysis.respect-type-ignore-comments

规则文档的 Options 一节指出：当 analysis.respect-type-ignore-comments 被设置为 false 时，本规则将被跳过。该配置项的完整说明位于 crates/ty/docs/configuration.md：

Whether ty should respect type: ignore comments. When set to false, type: ignore comments are treated like any other normal comment and can't be used to suppress ty errors (you have to use ty: ignore instead). Defaults to true.

要点归纳：

• 默认值：true（type: ignore 默认被尊重、可用于抑制错误）；
• 类型：bool；
• 置为 false 的效果：type: ignore 被当作普通注释——既不能抑制任何 ty 错误，ty 也不会报告或删除未使用的 type: ignore（自然也就不会触发 unused-type-ignore-comment），同时无效的 type: ignore 语法也不会被 invalid-ignore-comment 报告；
• 适用场景：与 mypy 等其他类型检查器混用时，或你更倾向统一使用 ty: ignore 时。

配置示例

在 pyproject.toml 中关闭：

[tool.ty.analysis]
# Disable support for `type: ignore` comments
respect-type-ignore-comments = false

在 ty.toml 中关闭：

[analysis]
# Disable support for `type: ignore` comments
respect-type-ignore-comments = false

从源码看，该配置被读取的位置在 suppression.rs L84-L86：

let respect_type_ignore = db
    .analysis_settings(source_file)
    .respect_type_ignore_comments;

读取后有两处直接生效（suppression.rs L103-L105 与 L121-L123）：当 respect_type_ignore 为 false 时，SuppressionParser 解析出的 type: ignore 注释（以及格式非法的同类注释）会直接被 continue 跳过，根本不会进入抑制索引，因此既不会抑制任何错误，也不会出现在"未使用"检查的候选集中。配置字段本身定义于 crates/ty_project/src/metadata/options.rs。

关闭后的行为对照

mdtest 文档（L279-L305）为关闭配置后的三种行为提供了可验证的对照：

场景	关闭 respect-type-ignore-comments 后的行为
a = b + 10 # type: ignore	type: ignore 无法抑制错误，unresolved-reference 照常报告
a = 10 + 5 # type: ignore	ty 不报告也不删除这条未使用的 type: ignore
a = 10 + 4 # type: ignoreee	无效的 type: ignore 语法不再被 invalid-ignore-comment 报告

这也解释了为什么规则文档将其列为唯一关联配置项——它是 unused-type-ignore-comment 的总开关。

与相关规则的协作

unused-type-ignore-comment 并非孤立存在，它属于 ty 的"抑制注释"规则族，全部声明于 crates/ty_python_semantic/src/suppression.rs，并由 check_suppressions 统一驱动（L141-L154）：

规则	职责	默认级别
unused-ignore-comment	检测未使用的 ty: ignore	warn
unused-type-ignore-comment	检测未使用的 type: ignore	warn
ignore-comment-unknown-rule	检测引用了未知规则的抑制注释	warn
invalid-ignore-comment	检测语法无效的抑制注释	warn
blanket-ignore-comment	检测笼统的 ty: ignore（不带代码）	ignore

is_unused_ignore_comment_lint 辅助函数（L74-L76）专门用于识别两条"未使用"规则。实际检查时，unused.rs L18-L23 会先判断两条规则是否同时被禁用，若都禁用则整个未使用检查直接返回。

还有一个值得注意的设计：unused-ignore-comment 诊断只能通过指定代码来抑制，而不能被笼统的 type: ignore 抑制。源码注释（unused.rs L41-L45）解释得很清楚——如果笼统的 type: ignore 也能抑制它自身，那么每条 type: ignore 都会隐式地压掉自己的"未使用"诊断，规则将形同虚设。

小结

unused-type-ignore-comment 是 ty 在抑制注释管理上的关键一环，它与 unused-ignore-comment 一起构成了"无死代码抑制"的保障：

1. 判定本质：在类型检查完成后，凡未被任何诊断引用的 type: ignore 即为未使用，默认以 warn 级别报告，并附带删除注释（或仅删除失效代码）的安全修复；
2. 语义边界：独立成行的 type: ignore 只在其位于文件头部时才是文件级抑制，否则必然触发本规则；代码列表只认可 ty: 前缀，天然兼容 mypy 等其他检查器的抑制注释；
3. 配置总开关：analysis.respect-type-ignore-comments = false 可让 ty 完全无视 type: ignore 并跳过本规则，适合与其他类型检查器混用或希望统一使用 ty: ignore 的团队。

如果你想深入验证本规则在各种边界情况下的行为（多行表达式、多行字符串、行续接、插值字符串、文件级抑制等），建议直接阅读 mdtest 语料 crates/ty_python_semantic/resources/mdtest/suppressions/type_ignore.md，其中的 # snapshot 用例与快照输出就是最直观的"活文档"。