build(types): ENG-04 add strict projects and legacy compiler checks

2026-10-19 03:11:20 -08:00 · 2026-09-10 21:21:39 +08:00
1 parent 09902b8b8c
commit 771482426f
@@ -41,6 +41,7 @@
 | [风险维护说明](risk-guide.md) | 证据等级、关闭条件、第三方边界和校验命令 |
 | [第三方来源清单](third-party.json) | 依赖解析、vendor 文件指纹、SDK/CDN 与许可来源缺口 |
 | [消费者与真实环境矩阵](environment-matrix.md) | 22 包的版本依据、能力/设备/样本、现有证据、验证任务及发布影响 |
+| [类型检查与迁移入口](typechecking.md) | 根/分包配置、当前/旧编译器、严格正反例和历史声明错误 |

 ## 维护规则

@@ -0,0 +1,13 @@
+# ENG-04：类型检查基础落地
+
+日期 2026-09-10；起点 09902b8b；分支 codex/compatible-modernization。
+
+新增根/核心/chapter tsconfig、浏览器资源声明、yarn typecheck 与 CI 接入。脚本自动发现分包配置，禁止严格检查退化为跳过声明或生成产物，并拒绝新 TS 包缺少配置。实现检查和消费者解析模式分开，当前核心/chapter 的生产 TS 文件数诚实输出为零；本任务没有改写生产源码或公开声明。
+
+固定 TypeScript 5.9.3；新增根开发 alias typescript-compat=typescript 4.3.5，支持精确 alias 的 Yarn 工具检查与拒绝浮动 alias 的回归。4.1.6 试探无法解析现有类型内 getter，最终依赖已移除；4.3.5 是当前已测旧版本点，不是对全部历史消费者下限的新声明。
+
+3 个严格配置通过；现代 TS 的 Node10+CJS、NodeNext+CJS、Bundler+ESM，以及 4.3.5 Node10+CJS 消费通过。NodeNext ESM 的 7 个既有诊断逐条保存并关联 BASE-TYPE-01，不当作候选通过。原发布包四模式/16 场景仍由基线测试执行；新增实际错误 URL、无效错误断言和源码类型错误的回归，不用跳过/any 消除历史差异。
+
+验证：完整 ci:check 通过工具链、计划、只读 lint、类型入口、21 项 Node 和 19 项基线测试，共 40 项；特定类型文件 lint 通过。冻结安装核对新依赖；原 1335 个 lock selector 的版本/integrity 全同，只增加一个 alias。Yarn 合并了 esbuild/p-map 同版本 selector；esbuild 的已存在 selector resolved 合并到相同内容的 Yarn registry 地址，未升级生产依赖。
+
+实际文件职责、运行命令、JS/TS 边界、旧编译器范围与后续工作见 [维护说明](../typechecking.md)。独立提交 ENG-04，撤销本提交可恢复原检查和依赖，不影响生产产物。下一项 ENG-06 让正常构建支持 TS 和非交互选包，随后接续单元/浏览器测试服务与 chapter 试点。
@@ -8,10 +8,11 @@
 | --- | --- |
 | `yarn lint` | 只读 ESLint，覆盖包源码/声明、JS/MJS 工具、测试和编辑器声明 |
 | `yarn lint:fix` | 显式自动修复相同范围 |
+| `yarn typecheck` | 根/迁移包严格检查、当前与兼容 TS 消费；历史 NodeNext ESM 错误单独核对，见 typechecking.md |
 | `yarn test:node` | 显式执行 4 个有行为断言的 Node 测试文件，保留原 test:playback/test:dash-control 入口 |
 | `yarn test:imports` | 3 个既有包导入 smoke，构建后执行以使用新产物；不把 console 示例视为完整行为断言 |
 | `yarn test:baseline` | 固定发布包完整性及本地 HTTP 基线测试；首次可能下载已固定归档到缓存 |
-| `yarn ci:check` | 严格 Node/Yarn/锁检查、计划、只读 lint、Node 和基线测试；允许写忽略缓存，不修改源码 |
+| `yarn ci:check` | 严格 Node/Yarn/锁检查、计划、只读 lint、类型、Node 和基线测试；允许写忽略缓存，不修改源码 |
 | `yarn ci:build` | 21 库包、i18n、编辑器声明和文档站构建，以及构建后包导入 smoke；会生成 dist 和 docs 内容 |
 | `yarn build:all` | 保留旧入口，执行 ci:build 后只读 lint |

@@ -4,7 +4,7 @@

 基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 214 项，范围 22 个包及工作区/示例。

-状态：todo 189 / doing 0 / blocked 0 / done 25 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 188 / doing 0 / blocked 0 / done 26 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

 前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。

@@ -77,7 +77,7 @@
 | ENG-PM-01 | workspace<br>按用户选择切换固定 Yarn 包管理器 | ENG-01 | Yarn 固定版本、唯一 yarn.lock、工具检查与安装维护文档 | 干净冻结安装、Node 测试和全部构建通过；记录解析差异和依赖用途，独立提交 | M | done |
 | ENG-02 | workspace<br>拆分只读检查并建立 PR CI | ENG-01, ENG-PM-01 | lint/lint:fix、PR 与主线检查、独立部署任务；遵循 github-ci-cd.md，PR/重构分支触发、最小权限及 workflow 静态检查 | 仓库内检查可执行且不改源码、不发布；required checks 的外部设置状态列入发布台账，不阻塞本地框架建设 | M | done |
 | ENG-03 | workspace<br>建立公共行为与单元测试入口 | ENG-02, BASE-03 | 保留现有 node:test，测试目录/夹具/统一入口 | 已有 19 项回归保留，旧版与候选可用同一夹具运行 | M | todo |
-| ENG-04 | workspace<br>建立类型测试基础 | ENG-02, BASE-05 | 根与分包 tsconfig、显式 TS 依赖、正反例测试 | 核心/试点与迁移模块严格检查，未迁移第三方/包历史问题独立台账；明确最低/当前 TS 和各环境类型；复用 BASE-05 的四种消费模式，不以 skipLibCheck 掩盖 BASE-TYPE-01/03 | M | todo |
+| ENG-04 | workspace<br>建立类型测试基础 | ENG-02, BASE-05 | 根与分包 tsconfig、显式 TS 依赖、正反例测试 | 核心/试点与迁移模块严格检查，未迁移第三方/包历史问题独立台账；明确最低/当前 TS 和各环境类型；复用 BASE-05 的四种消费模式，不以 skipLibCheck 掩盖 BASE-TYPE-01/03 | M | done |
 | ENG-05 | workspace<br>建立真实浏览器测试服务 | ENG-03, BASE-04, BASE-08 | Playwright projects、本地 Range/失败媒体服务；复用 docs 页面/样本的状态隔离、错误采集与候选资源映射 | Chromium/Firefox/WebKit 的基础播放 smoke 和报告可执行；以媒体状态断言判定通过，区分轻量用例与真实编辑器交互 | M | todo |
 | ENG-06 | workspace<br>支持按包非交互与 JS/TS 构建 | ENG-02, BASE-05 | build/dev 入口解析、指定包参数、原交互保留 | 三种产物、Less/SVG/worker 和本地 8082 demo 正常；保持 BASE-05 的 AMD 同时写入全局行为及 i18n/legacy 入口 | H | todo |
 | ENG-07 | workspace<br>建立 tarball 消费与产物检查 | ENG-04, ENG-06 | 隔离 npm 消费 fixtures、API/声明/入口差分 | 不借 workspace 源码通过，能识别缺文件与默认导出变化 | H | todo |
@@ -428,3 +428,4 @@
 - ENG-01: [记录](changes/2026-09-10-ENG-01-reproducible-toolchain.md) [记录](baselines/toolchain-validation.json)
 - ENG-PM-01: [记录](changes/2026-09-10-ENG-PM-01-yarn-toolchain.md) [记录](baselines/yarn-validation.json)
 - ENG-02: [记录](changes/2026-09-10-ENG-02-readonly-ci.md) [记录](baselines/ci-validation.json)
+- ENG-04: [记录](changes/2026-09-10-ENG-04-typechecking.md) [记录](typechecking.md)
@@ -1,5 +1,9 @@
 # 进度与证据

+## 当前实施：ENG-04 类型检查基础完成
+
+根/核心/chapter 配置和 yarn typecheck 已接入 CI。TS 5.9.3 三种消费模式与 TS 4.3.5 旧解析通过，NodeNext ESM 七项历史诊断单独记录；40 项 Node/基线测试通过。见 [ENG-04](changes/2026-09-10-ENG-04-typechecking.md)。当前 214 项，26 完成、188 待办；工具代码已有实施，生产源码 TS 迁移仍为零。BASE-08 提交 09902b8b，本任务独立提交。下一项 ENG-06 构建 TS 与非交互入口，再完成测试服务和 chapter 源码迁移。
+
 ## 当前实施：BASE-08 环境矩阵完成

 22 包的格式/类型/运行环境/codec/SDK/设备与样本缺口已分配任务和发布影响；见 [矩阵](environment-matrix.md)。只引用已有基线，没有新增浏览器通过结论。当前 214 项，25 完成、189 待办；生产源码 TS 迁移仍为零。BASE-07 提交 ed293231；本任务独立提交。下一项直接实施 ENG-04 类型检查配置，再推进构建与 chapter 试点。
@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+import test from 'node:test'
+import ts from 'typescript'
+import compat from 'typescript-compat'
+import { checkConsumer, checkProject } from '../../scripts/typecheck.mjs'
+import { refactorDir } from './releases.mjs'
+
+test('Current and compatibility compilers reject invalid old public calls and unused error assertions', () => {
+  const original = fs.readFileSync(path.join(refactorDir, '../test/types/public.ts'), 'utf8')
+  for (const compiler of [ts, compat]) {
+    assert.deepEqual(checkConsumer(compiler, 'node10-commonjs'), [])
+    const invalid = "import Artplayer from 'artplayer'; new Artplayer({ container: '#player', url: 42 });"
+    assert(checkConsumer(compiler, 'node10-commonjs', invalid).some(d => d.code === 2322))
+    const unused = original.replace('url: 42', "url: 'valid.mp4'")
+    assert(checkConsumer(compiler, 'node10-commonjs', unused).some(d => d.code === 2578))
+  }
+})
+
+test('Browser implementation configuration catches source errors without emitting JavaScript', () => {
+  const parent = path.join(refactorDir, '.cache')
+  fs.mkdirSync(parent, { recursive: true })
+  const directory = fs.mkdtempSync(path.join(parent, 'types-check-'))
+  try {
+    const config = path.join(directory, 'tsconfig.json')
+    fs.writeFileSync(config, JSON.stringify({ extends: path.join(refactorDir, '../tsconfig.base.json'), include: ['source.ts'] }))
+    fs.writeFileSync(path.join(directory, 'source.ts'), 'export const title: string = 42;\n')
+    assert.deepEqual(checkProject(config).diagnostics.map(d => d.code), [2322])
+    assert(!fs.existsSync(path.join(directory, 'source.js')))
+  }
+  finally {
+    const relative = path.relative(parent, directory)
+    assert(relative.startsWith('types-check-') && !relative.includes(path.sep))
+    fs.rmSync(directory, { recursive: true, force: true })
+  }
+})
@@ -509,11 +509,14 @@
        "ENG-02",
        "BASE-05"
      ],
-      "status": "todo",
+      "status": "done",
      "risk": "M",
      "deliverable": "根与分包 tsconfig、显式 TS 依赖、正反例测试",
      "acceptance": "核心/试点与迁移模块严格检查，未迁移第三方/包历史问题独立台账；明确最低/当前 TS 和各环境类型；复用 BASE-05 的四种消费模式，不以 skipLibCheck 掩盖 BASE-TYPE-01/03",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-10-ENG-04-typechecking.md",
+        "typechecking.md"
+      ]
    },
    {
      "id": "ENG-05",
@@ -6,7 +6,7 @@

 1. 切换到 .node-version 指定的 Node，安装 Yarn 1.22.22；例如 `npm install --global yarn@1.22.22`，然后确认 `node --version` 和 `yarn --version`。npm 仅可用于安装 Yarn 工具及消费者兼容检查，不用于维护本仓库依赖锁。
 2. 干净 checkout 执行 `yarn install --frozen-lockfile --non-interactive`，禁止 CI 自动更新锁或忽略安装脚本/engines。参见 [Yarn Classic install](https://classic.yarnpkg.com/en/docs/cli/install/)。
-3. 执行 `yarn check:toolchain --strict`，核对实际 Node/Yarn、19 个固定开发工具和 22 个 workspace 的声明及传递依赖锁条目。普通检查允许满足最低工具要求的 Node，同时打印标准版本。
+3. 执行 `yarn check:toolchain --strict`，核对实际 Node/Yarn、20 个固定开发工具和 22 个 workspace 的声明及传递依赖锁条目。普通检查允许满足最低工具要求的 Node，同时打印标准版本。
 4. 执行 `yarn test:playback`、`yarn test:dash-control`、`yarn build all` 和 `yarn workspace artplayer-vitepress build`。ENG-02 已拆分只读 lint 与 lint:fix；PR/主线入口和独立 Pages 流程见 ci-setup.md。

 私有根包最低 Node 为 ^20.19.0 || >=22.12.0，与原本使用的 Vite 7 一致。本轮验证 Node 24.21.0，其他版本矩阵由 CI-01 接续，不能宣称所有最低环境已经通过。
@@ -14,6 +14,7 @@
 ## 锁文件和依赖维护

 - 根构建工具固定精确版本并放在 devDependencies；发布包的 dependencies/peer 范围保持原样。
+- ENG-04 新增 typescript-compat（npm:typescript@4.3.5）作为旧编译器消费探针；源码继续使用 typescript 5.9.3。精确 npm alias 也由锁检查保护；实际覆盖与命令见 [类型检查说明](typechecking.md)。
 - 添加根开发依赖使用 `yarn add --dev --exact --ignore-workspace-root-check <name>@<version>`，包级依赖使用 `yarn workspace <name> add ...`；运行依赖升级需要独立兼容证据。
 - manifest 和 yarn.lock 同次提交；不提交 package-lock.json、bun.lock 或第二份安装锁。旧 npm 锁及验证报告保留于 ENG-01 Git 历史，原本地 Yarn 锁也已在忽略缓存中备份。
 - 新增 @yarnpkg/lockfile 1.1.0 为显式开发依赖，供检查器使用 Yarn 官方锁解析器；不依赖 Lerna 偶然安装的传递依赖。只验证 registry 依赖图及完整性字段，实际下载完整性由 Yarn 安装验证；peer 兼容仍由消费者测试和安装报告验证。
@@ -0,0 +1,47 @@
+# 已实现的类型检查与迁移入口
+
+ENG-04 使用开发编译器 TypeScript 5.9.3，并将 TypeScript 4.3.5 作为 npm alias typescript-compat 固定在根开发依赖。后者仅用于旧编译器消费回归，不进入播放器运行依赖或产物。Yarn 锁文件校验现在接受精确版本的 npm alias，仍拒绝范围和浮动版本。
+
+## 命令及真实覆盖
+
+```sh
+yarn typecheck
+yarn ci:check
+```
+
+typecheck 读取根及已建立配置的分包项目，以编译器 API 执行，不依赖两个 TS 安装可能影响的全局 tsc 命令。当前根配置检查两个消费/浏览器类型文件，核心检查 14 个声明及共享资源声明，chapter 检查自身声明及共享资源声明。配置实际编译经过的生产 TS 文件数另行输出；本任务完成时为零，不能把声明检查说成生产 JS 已严格检查。
+
+自动检查当前工作区的 TS 5.9.3 Node10+CJS、NodeNext+CJS、Bundler+ESM 及 TS 4.3.5 Node10+CJS。正例包括旧配置、ready 回调 this、插件、play 和 update；反例拒绝错误 URL/章节时间。没有 ts-expect-error 生效时编译也须报错，防止 any 或声明放宽使反例失效。
+
+TS 5.9.3 的 NodeNext ESM 当前有 7 个准确诊断，单独保存在 test/types/known-diagnostics.json，并绑定 BASE-TYPE-01。它们来自原有默认导出声明互操作问题；检查输出明确是历史失败，不能作为候选验收通过。修复由 CORE-07、PKG-CHAPTER-04 和 ENG-07 接续，届时移除对应失败记录、增加成功消费断言，不能一键刷新以容忍新回归。
+
+BASE-05 的四模式、16 场景、真实发布 tarball 隔离验证仍由 test:baseline 执行。本入口补上当前工作区的检查，不代替隔离发布消费；ENG-07 接入候选 tarball。BASE-TYPE-02/03/04 的可选参数、legacy 声明与返回值问题继续由原任务负责，没有在本任务偷偷修改生产声明。
+
+## 配置与文件职责
+
+| 文件 | 职责 |
+| --- | --- |
+| 根 tsconfig.base.json | 浏览器实现基线：ES2020+DOM/DOM.Iterable、strict、noUncheckedIndexedAccess、noImplicitOverride、noEmit、skipLibCheck=false、types=[] |
+| 根 tsconfig.json | 当前公共消费与浏览器环境类型用例；不是无条件将全部遗留包标为已检查 |
+| packages/artplayer/tsconfig.json | 核心自有 TS 及现有公开声明的入口 |
+| packages/artplayer-plugin-chapter/tsconfig.json | 试点 TS 及现有公开声明的入口 |
+| types/assets.d.ts | 当前 Less inline 和 SVG 的 string 导入类型；不提供泛化的任意模块声明 |
+| scripts/typecheck.mjs | 固定编译器检查、分包发现、四种现代消费模式、兼容编译器与历史诊断核对 |
+| test/types/ | 真实旧调用、无 Node 全局污染/数组越界反例、明确历史诊断；无运行时副作用，因为只编译不执行 |
+| refactor/scripts/types.test.mjs | 验证非法旧调用、无效错误断言和生产 TS 错误确实被拒绝，检查不生成 JS |
+
+实现由现有 bundler 构建，所以源码配置采用 Bundler 模块解析；发布声明仍须经过独立 Node 模式验证。[TypeScript 模块解析说明](https://www.typescriptlang.org/tsconfig/moduleResolution) 区分了这些模式，[官方编译器选项指南](https://www.typescriptlang.org/docs/handbook/modules/guides/choosing-compiler-options) 也说明 bundler 成功不保证未打包声明能被 Node 消费。
+
+allowJs=true、checkJs=false 允许渐进迁移时引用旧 JS；只将迁移的 TS 和声明纳入配置根文件，旧 JS 不因被引用就变成已迁移。迁移任务须缩小不明确的 JS 边界，vendored 独立列入第三方台账，不能用 ts-nocheck/any 把自有代码隐藏过去。新增生产 TS 的包若没有 tsconfig，入口会拒绝继续。
+
+不默认启用 exactOptionalPropertyTypes 去收紧旧调用允许的显式 undefined；公开类型接受范围变化需要逐项消费者证据。内部数组/索引检查启用 [noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig/noUncheckedIndexedAccess.html)，防止将不存在的元素当作已存在。浏览器 types=[] 防止依赖树中的 @types/node 自动污染 DOM 代码；worker 和 Node 工具需要自身配置，不把 DOM 与 WebWorker 全局混在一起。
+
+## 编译器版本边界
+
+4.1.6 试探无法解析当前 artplayer.d.ts 的类型内 getter（首个错误在 template.html）；已改用实际通过公共消费样例的 4.3.5，并从最终依赖/锁文件移除 4.1.6。4.3.5 是当前核心/chapter 的已测旧编译器点，不是证明所有历史版本都以它为最低，也不是授权抬高用户已有支持窗口。其他包在自身契约任务核对声明语法和实际旧版本消费者；未查明时保持未知。
+
+源码检查用 5.9.3 不要求用户也使用 5.9.3。生成声明时须保留旧编译器能理解的公开语法，并在版本落实和候选 tarball 后重跑。NodeNext/Bundler 的消费模式由当前编译器验证，不传给不具备这些模式的 4.3.5。
+
+## 后续接入
+
+新迁移包复制分包配置并按实际运行环境调整，加入特有正反例；编译器入口自动发现包配置。TS 构建入口与声明生成由 ENG-06/07 和各包迁移处理；不能只增加一个空 config 就宣布包迁移完成。所有生产变更仍按每任务独立提交和包内架构文档规则交付。