ArtPlayer/refactor/changes/2026-09-11-ENG-08-quality-reports.md

# ENG-08 覆盖率、资源与性能报告

本任务接在 CORE-23（8ed0a522）之后。目标是让真实覆盖缺口、资源清理失败和性能/体积审查信号可重复检查，不能用工具生成成功代替核心验收。

## 实现与兼容边界

- 新增开发依赖 c8 12.0.0，固定 Yarn 1.22.22；frozen install 已通过。没有新增包运行时依赖、版本变更或公开导出。
- test:coverage 复用 test:unit 的明确用例列表。覆盖率模式生成带完整映射的文件模块，正常测试加载方式保留；按进程隔离临时模块和每次报告，禁用测试构建 tree shaking。原始 V8 收集和归一化映射分别保存，不修改 node_modules。
- sourceInventory 自动纳入未加载源码并明确排除类型文件及已审计第三方文件。关键文件门槛检查实际计数、拒绝零分母、缺失文件、忽略计数与未登记 suppression。类型排除通过 TS 编译后的空模块判断，非简单按文件名猜测。
- 资源适配器四处初始化空 cleanup 和关闭后的空释放统一为无状态内部函数，减少重复闭包分配。实际注册后的闭包和资源所有权仍独立，取消句柄重复调用安全；没有改变公开方法的返回值、事件顺序或 callback this。
- 新增容器预约/失败回滚、直接 scope 释放和聚合清理异常测试。针对新增统计规则，不降低已有门槛，也不执行不可到达回调来增加数字。
- 性能执行、输入/压缩、夹具适配、验证和摘要分离。复用 BASE-06 的同一测量体，仅适配产物 URL 与报告传输；旧冻结 fixture 和既有发布来源验证保留。新旧包相同场景各一次预热、五次正式样本，三组交替配对，资源探针在计时之后独立运行。
- 性能必须使用隔离安装包，校验分发哈希、构建 Node/依赖/脚本、当前包源码和声明来源，拒绝陈旧构建。体积比较三个相同格式入口的实际发布/候选字节，gzip9/Brotli6 沿用原设置。
- Ubuntu/Windows 覆盖率 job 和 macOS 浏览器后顺序配对均写入 Node CI，保留失败证据与摘要，SHA 固定 action、只读权限不变。本次未推送，远端 CI 结果不能由本地结果代替。

## 失败证据与修正

首轮原始 c8 报告声称生命周期行覆盖率 100%，却缺少函数/分支。实际 V8 数据与单独转换均有有效记录；问题在于 Node source-map-cache 中的 file URL 被 c8 本地路径过滤器排除。v8-to-istanbul 默认行计数仍为一，形成虚假高值。保留原始 JSON，独立转换目录归一化路径后，未执行代码和真实分支恢复统计。映射源码还必须匹配本轮源码哈希，拒绝过期/缺失映射。

真实 esbuild/Vite canary 同时验证：完整执行通过、未执行 return 行仍为零、未导入文件留在分母、未执行分支触发门槛。另有空分母、跳过计数和错误百分比检查，不能只检查命令退出码。原失败日志和首轮数据保留在本地缓存。

完整 CI 476 项通过（440 单元、11 工程、25 基线），249 个生产 TS 文件严格检查、37 个公共声明无漂移。覆盖率命令自身还先运行两项真实映射/门槛测试。当前 224 个运行时文件、26 个明确排除，行 60.94%、分支 86.55%、函数 66.71%；四个关键文件的三类指标均为 100%。这是 c8 对 Node 用例的统计，不能等同全部浏览器路径或全生态覆盖率。

## 性能信号与交接

首轮三引擎配对检查全部执行完成，54 次候选资源探针通过；现代核心 gzip 从 35486 增至 58374 字节，核心三个分发格式均超过体积审查阈值。首轮 Firefox/WebKit 个别组构造耗时也出现信号，尚未确认跨组稳定回归。ENG-PERF-01/02 保持 open，交 CORE-22/REVIEW-01 归因、优化及复核。

计时和体积状态 review-required 与资源硬失败分开保存。测试退出零只证明报告有效、配对完整和候选资源要求通过；不能据此发布或关闭风险。没有修改阈值、覆盖历史基线或将旧版定时器残留作为候选允许值。物理设备、屏幕阅读器和浏览器/GPU 原生内存仍有独立发布验收范围。

## 最终验收与提交

| 项目 | 结果 |
| --- | --- |
| 源码和类型 | 原定四个生命周期门槛通过，249 个生产 TS 严格检查，37 个声明无漂移；476 项 CI 通过 |
| 安装包兼容 | run-LF1aXT 的 34 项运行时、5 组旧类型/8 组精确类型通过，零类型阻塞 |
| 生成产物 | 按正式 build/build:i18n 重建；113 个包分发/声明及 docs 编译文件与隔离安装指纹一致；三个导入检查通过 |
| 真实浏览器 | modern 与 legacy 各 114 项资源、实例、字幕生命周期回归通过，三引擎各 38 项，没有失败、重试或跳过 |
| 配对报告 | 最终三引擎各三组配对，54 次候选资源探针通过；Chromium/Firefox 无计时信号，WebKit 第一组 core/chapter 各 +3 ms，其余两组不触发 |
| 性能审查 | 核心三格式体积增长与间歇计时信号保持 review-required；ENG-PERF-01/02 open，不作为发布放行 |
| 工程与文档 | frozen install、actionlint 和 diff 检查通过；源映射、报告规则、运行命令、CI 限制及模块职责已同步 |

[冻结证据](../baselines/quality-validation.json) 保留源码/工具/测试指纹、原始与归一化 V8 哈希、有效覆盖率、配对完整数据、隔离安装类型/运行时检查及两种格式浏览器结果。首轮失败和间歇性能信号的日志指纹单独保留，不覆盖历史。

提交前最后审查为覆盖率 job 明确 bash shell，使 Windows 的多行安装步骤也在中途原生命令失败时停止，避免仅以末条命令状态误判。只调整工作流执行约定，重新通过 actionlint；此前未提交的证据副本保存在本地缓存 quality-before-ci-review.json，最终冻结证据绑定修正后的工作流哈希，生产代码和浏览器产物未变。

ENG-08 done，59 done、155 todo。本任务独立本地 commit 包含实现、测试、文档、任务状态和生成产物；提交核实后开始 CORE-22。没有 push/publish/tag/merge。回退时整体回退本任务实现、开发依赖/锁文件、CI、测试、生成产物和文档，保留前置 CORE-23 的接口与声明成果。