From 5ae52629f7ba063e4590688cd6a501efea6c4ed7 Mon Sep 17 00:00:00 2001 From: jxxghp Date: Sat, 17 Oct 2026 03:02:49 +0800 Subject: [PATCH] chore(types): read FastAPI and Click contracts in strict checks --- docs/code-quality.md | 15 +++-- docs/refactor/optimization-checklist.md | 4 +- mypy.ini | 5 ++ .../fixtures/architecture/mypy-baseline.json | 56 ++++--------------- 4 files changed, 27 insertions(+), 53 deletions(-) diff --git a/docs/code-quality.md b/docs/code-quality.md index 2747a17f4..409f2f532 100644 --- a/docs/code-quality.md +++ b/docs/code-quality.md @@ -71,16 +71,21 @@ uv run --locked --no-sync python scripts/architecture/complexity.py 三个文件及完整严格清单实测通过，不增加忽略规则或类型债务。全宿主 mypy ratchet 继续保留。 严格清单对项目内部的 `app.*` 统一采用 `follow_imports = silent`，并将此策略应用于 -内部 `.pyi`，读取真实接口；外部依赖仍沿用 `follow_imports = skip` 和 -`ignore_missing_imports = True`。`silent` 只影响导入的非目标文件，`files` 中的目标仍然 +内部 `.pyi`，读取真实接口；FastAPI 和 Click 同样读取供应方已声明的类型， +其它外部依赖沿用 `follow_imports = skip`，保留 `ignore_missing_imports = True`。`silent` 只影响导入的非目标文件，`files` 中的目标仍然 严格检查；全宿主 Linux 分析显式扫描整个 `app`，继续报告未清零文件的全部历史债务。 -本次将已有完整分析零错误的文件统一纳入严格清单，保留之前的全部目标，新增 551 个 +此前将已有完整分析零错误的文件统一纳入严格清单，保留之前的全部目标，新增 551 个 受保护文件。扩围前后对完整宿主逐文件、逐错误码核对，导入策略没有隐藏任何既有错误； 订阅请求仓储补齐真实查询接口、API 移除恒等 cast 后，另消除 8 项原有类型错误。 -门禁扩围表示已清零代码受到保护，不表示本次修复了这些文件的业务实现。 +门禁扩围表示已清零代码受到保护，不表示同时修复了这些文件的业务实现。 + +FastAPI/Click 合同治理移除了 107 条已失效的类型忽略，修正 OpenAPI 状态码键和 +真实协程返回类型，并从定义方导入 FastAPI 的同一对象。全宿主诊断下降 417 项， +逐文件、逐错误码没有增长；新增清零的 `app/factory.py` 进入严格清单。仍有历史 +债务的文件继续受完整分析的低水位约束，不因装饰器类型恢复而宣称整文件已清零。 2026-10-16 开始逐文件清理类型债务，`app/domain/title.py` 通过局部可空类型声明保留 -既有搜索解析行为，并纳入严格清单；当前清单共 763 个文件（762 个生产文件和 1 个脚本）。 +既有搜索解析行为，并纳入严格清单；当前清单共 764 个文件（763 个生产文件和 1 个脚本）。 每个生产文件完成针对性测试后独立提交，并纳入严格门禁。每批集中同步真实下降的 类型基线和指标文档，运行完整本地单测与适用门禁后统一推送；不逐文件等待远端 CI。 验收同时检查完整严格清单与全宿主 Linux 分析，保证导入接口和全量历史债务都受检查； diff --git a/docs/refactor/optimization-checklist.md b/docs/refactor/optimization-checklist.md index 7b68e9899..003fd641d 100644 --- a/docs/refactor/optimization-checklist.md +++ b/docs/refactor/optimization-checklist.md @@ -106,9 +106,9 @@ ARCH-201 至 ARCH-204 均达到实现、验证、提交、推送和远端门禁 | Model/Oper 事务债务 | 0 | 自建 Session、自动事务装饰器、直接 commit/rollback 等基线均为零 | | Module Contract | 215 specs / 211 methods / 263 calls | 动态方法名为 0；分类事实富化通过显式合同进入插件调度，旧 YAML 分类方法已移除；download 新增 custom_words 可选参数，旧 provider 签名通过显式合同兼容 | | Event Contract | 53 | 均已有 payload model，但当前全部是 diagnostic enforcement | -| Python 源码量 | 373,141 行 | 本次重新扫描物理行数，排除 `app/plugins/**`；74 个文件超过 1,000 行，12 个超过 2,000 行；源码尺寸仅作观察 | +| Python 源码量 | 373,207 行 | 本次重新扫描物理行数，排除 `app/plugins/**`；74 个文件超过 1,000 行，12 个超过 2,000 行；源码尺寸仅作观察 | | 长方法 | 309 个超过 80 行 | 本次 AST 扫描排除 `app/plugins/**`；61 个超过 150 行，17 个超过 250 行；新增函数仍受 C901/嵌套深度门禁约束 | -| 全量 mypy 历史债务 | 7,140 / 361 文件 | 通知排版补齐 Slack 消息块类型，历史债务减少 2 项；工作流资源过滤改用领域对象调用过滤链，恢复的节点输出在消费前归一化，并收紧可空资源列表的类型低水位；消息媒体交互类型债务已清零，canonical Facade 与 endpoint 类型边界已补齐，低水位只允许继续下降；微信 ClawBot 入站 item_list 媒体解析改为按子项键名分派后，类型错误减少 4 项；站点解析器分享率改用浮点初值，类型错误减少 20 项；本次下载与文件安全修复再减少 3 项；Transmission 进度回退值归一化再减少 2 项，逐文件逐错误码无增长 | +| 全量 mypy 历史债务 | 6,723 / 360 文件 | 通知排版补齐 Slack 消息块类型，历史债务减少 2 项；工作流资源过滤改用领域对象调用过滤链，恢复的节点输出在消费前归一化，并收紧可空资源列表的类型低水位；消息媒体交互类型债务已清零，canonical Facade 与 endpoint 类型边界已补齐，低水位只允许继续下降；微信 ClawBot 入站 item_list 媒体解析改为按子项键名分派后，类型错误减少 4 项；站点解析器分享率改用浮点初值，类型错误减少 20 项；本次下载与文件安全修复再减少 3 项；Transmission 进度回退值归一化再减少 2 项，逐文件逐错误码无增长 | | Ruff 历史诊断 | 98 | 低水位门禁通过，但规则集只覆盖 `E4/E7/E9/F/I` | | 覆盖率固定基线 | Application 80.00%，Domain 80.00% | Chain、Runtime、Agent、Adapter、Startup 未进入包级覆盖率门禁 | diff --git a/mypy.ini b/mypy.ini index 0920b83a0..edf38a369 100644 --- a/mypy.ini +++ b/mypy.ini @@ -7,6 +7,7 @@ follow_imports = skip show_error_codes = True pretty = True files = + app/factory.py, app/__init__.py, app/adapters/__init__.py, app/adapters/cache/__init__.py, @@ -776,3 +777,7 @@ files = [mypy-app.*] follow_imports = silent follow_imports_for_stubs = True + +# 读取已安装供应方的真实装饰器与路由签名，避免把已声明类型的接口视为 Any。 +[mypy-click.*,fastapi.*] +follow_imports = silent diff --git a/tests/fixtures/architecture/mypy-baseline.json b/tests/fixtures/architecture/mypy-baseline.json index b3332b880..d259731d6 100644 --- a/tests/fixtures/architecture/mypy-baseline.json +++ b/tests/fixtures/architecture/mypy-baseline.json @@ -310,16 +310,13 @@ "redundant-cast": 2 }, "app/api/endpoints/agent.py": { - "misc": 13, "type-arg": 11 }, "app/api/endpoints/anilist.py": { "attr-defined": 1, - "misc": 8, "no-untyped-call": 2 }, "app/api/endpoints/anthropic.py": { - "misc": 1, "no-untyped-call": 1, "no-untyped-def": 3, "type-arg": 1, @@ -327,64 +324,55 @@ }, "app/api/endpoints/auth.py": { "arg-type": 1, - "misc": 3 + "misc": 1 }, "app/api/endpoints/bangumi.py": { "attr-defined": 1, - "misc": 5, "no-untyped-call": 3, "operator": 12 }, "app/api/endpoints/dashboard.py": { "arg-type": 2, - "misc": 19, "no-untyped-call": 2, "operator": 12 }, "app/api/endpoints/discover.py": { "arg-type": 20, "attr-defined": 1, - "misc": 6, "no-redef": 1, "no-untyped-call": 5, "operator": 2 }, "app/api/endpoints/douban.py": { "attr-defined": 1, - "misc": 5, "no-untyped-call": 2 }, "app/api/endpoints/download.py": { "arg-type": 6, "assignment": 5, "attr-defined": 4, - "misc": 10, + "misc": 1, "type-arg": 2 }, "app/api/endpoints/history.py": { "arg-type": 4, - "misc": 7, "no-untyped-call": 2, "no-untyped-def": 2 }, "app/api/endpoints/llm.py": { - "misc": 2, "no-untyped-def": 2 }, "app/api/endpoints/login.py": { - "misc": 3, "union-attr": 33 }, "app/api/endpoints/mcp.py": { "assignment": 3, - "index": 1, - "misc": 6 + "index": 1 }, "app/api/endpoints/media.py": { "arg-type": 2, "assignment": 7, "attr-defined": 3, - "misc": 13, "no-untyped-call": 5, "no-untyped-def": 1 }, @@ -392,14 +380,12 @@ "arg-type": 4, "assignment": 1, "attr-defined": 1, - "misc": 8, "type-arg": 2, "union-attr": 1 }, "app/api/endpoints/message.py": { "arg-type": 4, "assignment": 1, - "misc": 8, "no-untyped-def": 8, "union-attr": 4 }, @@ -407,24 +393,22 @@ "attr-defined": 4, "call-overload": 1, "index": 2, - "misc": 16, + "misc": 7, "operator": 1, "type-arg": 2 }, "app/api/endpoints/music.py": { "arg-type": 6, "attr-defined": 1, - "misc": 10, "type-arg": 3 }, "app/api/endpoints/notification.py": { - "misc": 2, "no-untyped-def": 2 }, "app/api/endpoints/openai.py": { "attr-defined": 1, "has-type": 1, - "misc": 5, + "misc": 2, "no-any-return": 1, "no-untyped-call": 1, "no-untyped-def": 15, @@ -434,21 +418,18 @@ "app/api/endpoints/plugin.py": { "assignment": 1, "import-untyped": 1, - "misc": 28, - "no-any-return": 5, + "no-any-return": 4, "no-untyped-call": 1, "no-untyped-def": 2, "type-arg": 9 }, "app/api/endpoints/recommend.py": { "attr-defined": 2, - "misc": 16, "no-redef": 1 }, "app/api/endpoints/search.py": { "arg-type": 2, "attr-defined": 3, - "misc": 11, "no-untyped-call": 3, "no-untyped-def": 4, "type-arg": 14 @@ -457,21 +438,18 @@ "arg-type": 6, "assignment": 2, "attr-defined": 2, - "misc": 26, "no-untyped-def": 2, "return-value": 1, "type-arg": 5 }, "app/api/endpoints/storage.py": { "assignment": 1, - "attr-defined": 1, - "misc": 7 + "attr-defined": 1 }, "app/api/endpoints/subscribe.py": { "arg-type": 11, "assignment": 3, "attr-defined": 2, - "misc": 23, "no-any-return": 1, "no-untyped-call": 1, "no-untyped-def": 1, @@ -480,47 +458,38 @@ "app/api/endpoints/system.py": { "arg-type": 1, "attr-defined": 4, - "misc": 30, "no-untyped-call": 6, "no-untyped-def": 24, "type-arg": 6 }, "app/api/endpoints/tmdb.py": { "attr-defined": 1, - "misc": 11, "no-untyped-call": 2, "operator": 4, "type-arg": 3 }, "app/api/endpoints/torrent.py": { - "misc": 5, "no-untyped-call": 1, "no-untyped-def": 5 }, "app/api/endpoints/transfer.py": { "arg-type": 9, "attr-defined": 2, - "misc": 8, "operator": 3, "type-arg": 3 }, "app/api/endpoints/user.py": { - "misc": 10, "no-untyped-def": 2, "str-bytes-safe": 1, "type-arg": 3 }, "app/api/endpoints/webhook.py": { - "misc": 2, "no-untyped-def": 1 }, "app/api/endpoints/workflow.py": { - "assignment": 1, - "misc": 16 + "assignment": 1 }, "app/api/response.py": { - "arg-type": 1, - "misc": 2, "valid-type": 1 }, "app/api/servarr.py": { @@ -528,14 +497,13 @@ "assignment": 1, "attr-defined": 1, "index": 3, - "misc": 16, - "no-any-return": 2, + "no-any-return": 1, "type-arg": 1, "union-attr": 1 }, "app/api/servcookie.py": { "import-untyped": 1, - "misc": 7, + "misc": 1, "no-any-return": 5, "return": 1, "type-arg": 1 @@ -931,7 +899,6 @@ }, "app/cli.py": { "attr-defined": 2, - "misc": 57, "no-any-return": 4, "type-arg": 3, "union-attr": 2 @@ -1004,9 +971,6 @@ "no-untyped-def": 1, "type-arg": 10 }, - "app/factory.py": { - "misc": 1 - }, "app/foundation/temporal.py": { "import-untyped": 3, "no-any-return": 1,