fix(build): [ENG-12] exclude declaration sources from library artifacts

2026-10-11 05:26:15 -08:00 · 2026-09-13 13:37:00 +08:00
1 parent 38355ae4cf
commit 4a299eb2d4
@@ -0,0 +1,97 @@
+{
+  "schemaVersion": 1,
+  "task": "ENG-12",
+  "date": "2026-09-13",
+  "baseCommit": "38355ae4cf058053d050a69625808af0b18290ff",
+  "worktreeScope": "CORE-25 default fix and tests were also present; their runtime acceptance belongs to CORE-25",
+  "before": {
+    "archiveSha256": "e742d78759a036df6a745973e053b272447e879f139f3641d909fa261f9360b3",
+    "copiedSources": [
+      "package/dist/artplayer.cts",
+      "package/dist/artplayer.mts",
+      "package/dist/artplayer.ts",
+      "package/dist/component.ts",
+      "package/dist/config.ts",
+      "package/dist/cssVar.ts",
+      "package/dist/emitter.ts",
+      "package/dist/events.ts",
+      "package/dist/i18n.ts",
+      "package/dist/icons.ts",
+      "package/dist/language.cts",
+      "package/dist/language.mts",
+      "package/dist/legacy/language.ts",
+      "package/dist/option.ts",
+      "package/dist/playback.ts",
+      "package/dist/player.ts",
+      "package/dist/plugin.ts",
+      "package/dist/quality.ts",
+      "package/dist/runtime.cts",
+      "package/dist/runtime.mts",
+      "package/dist/runtime.ts",
+      "package/dist/runtime/component.ts",
+      "package/dist/runtime/construction.ts",
+      "package/dist/runtime/events.ts",
+      "package/dist/runtime/media.ts",
+      "package/dist/runtime/option.ts",
+      "package/dist/runtime/player.ts",
+      "package/dist/runtime/plugin.ts",
+      "package/dist/runtime/services.ts",
+      "package/dist/runtime/setting.ts",
+      "package/dist/runtime/subtitle.ts",
+      "package/dist/runtime/template.ts",
+      "package/dist/runtime/utils.ts",
+      "package/dist/setting.ts",
+      "package/dist/subtitle.ts",
+      "package/dist/template.ts",
+      "package/dist/utils.ts"
+    ]
+  },
+  "after": {
+    "archiveSha256": "9e2fcf57f3ad0c9eba9e50aea4118b053c36616a905ffe14a1c0a69cfcb47f2b",
+    "remainingFiles": 68,
+    "allRemainingMemberBytesIdentical": true
+  },
+  "fixture": {
+    "before": "Private declaration source was copied",
+    "after": "all 3 real Vite formats omit private .ts and unrelated .txt",
+    "focusedTests": 3
+  },
+  "build": {
+    "command": "yarn ci:build",
+    "libraries": 21,
+    "imports": 3,
+    "seconds": 72.79,
+    "declarationsChanged": 0,
+    "exitCode": 0
+  },
+  "packageCheck": {
+    "command": "yarn test:package:release",
+    "exitCode": 0,
+    "includesUncommittedCore25": true
+  },
+  "incidentalGeneratedFilesRestored": 58,
+  "newGeneratedDocsArchived": 13,
+  "logs": [
+    {
+      "file": "refactor/.cache/eng12-build-before.log",
+      "sha256": "547c7cbba4362e1f191c7b6da96219a08c1a8a5e410e170f1d19276629cbf9c9"
+    },
+    {
+      "file": "refactor/.cache/eng12-focused.log",
+      "sha256": "809b43ea894b0e1eb7d30663667f04befbc964c540f455edbcb0fe84cffc3f72"
+    },
+    {
+      "file": "refactor/.cache/eng12-build.log",
+      "sha256": "cbdf8ebacd81a12a97ea27be151e4ac355fa8c86bc4dd1bc4556b0e7c95c8717"
+    },
+    {
+      "file": "refactor/.cache/eng12-package.log",
+      "sha256": "e01db4a932d5f596b5c223641ec860e3d1ce10ff289102b451842da2f880bde2"
+    },
+    {
+      "file": "refactor/.cache/eng12-lint.log",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    }
+  ],
+  "remoteRun": null
+}
@@ -2,6 +2,12 @@

 ENG-06 保留原来的 Vite 7.3.6、Terser、三种库产物及路径，增加选包参数和 TS 入口；未切换 bundler 或运行时依赖。固定工具链仍为 Node 24.21.0 / Yarn 1.22.22。

+ENG-12 将库配置的 publicDir 设为 false，防止 core/public 的声明源码被复制到 dist。
+库静态资源须通过已有显式 import/构建入口处理；文档站仍使用独立 VitePress 配置。
+打包检查拒绝非声明形式的 .ts/.cts/.mts，保留 .d.ts/.d.cts/.d.mts；
+实际三格式构建回归见 test/library-build.test.js 和
+[修复记录](changes/2026-09-13-ENG-12-library-public.md)。
+
 ```sh
 yarn build                              # TTY 中原交互选择
 yarn build artplayer                    # 一个包，无交互
@@ -0,0 +1,31 @@
+# ENG-12 隔离库构建的 public 声明源码
+
+CORE-25 生成产物时 Vite 复制 public/artplayer.cts 到 dist 触发 Windows copyfile UNKNOWN。
+进一步检查实际 tarball，确认声明源码目录此前被默认 publicDir 当静态资源复制。
+这是重构新增声明源码目录后的分发污染；真实 npm 基线不包含这些错误复制路径。
+不能只重试 Windows 错误而保留复制行为，也不能把偶发 copyfile 错误断言为确定的锁原因。
+
+scripts/utils.js 的库配置显式设置 publicDir:false。它用于库 build/dev/i18n；文档站
+使用独立 VitePress 构建。根下实际只有 core 的 public 目录，其他库没有依赖该目录
+复制的资源。此选项行为见 [Vite 文档](https://vite.dev/config/shared-options#publicdir)。
+scripts/package-check.mjs 同时拒绝任意路径中非 .d.ts/.d.cts/.d.mts 的 TS 文件，
+防止将来换个目录仍泄漏声明源码；原路径、历史文件和声明存在性检查继续保留。
+
+新增 test/library-build.test.js 实际执行三个格式构建，用 public 内的私有 TS 和无关
+文本作反例。修复前稳定失败，修复后 dist 只包含三个 JS 文件，已接入 test:node。
+test/package-check.test.js 覆盖 .ts/.cts/.mts 拒绝与三种声明后缀允许；真实旧候选
+tarball 同样被拒绝。新 tarball 只移除误复制的文件，其他所有成员字节完全一致。
+
+完整 yarn ci:build（21 库、i18n、编辑器、文档站、3 项导入）通过；声明生成零变化，
+定向三项测试和只读 lint 通过。此时工作区还有 CORE-25 修复和测试，其运行时与浏览器
+验收属于独立 CORE-25；本任务不宣称它已经完成。真实 package:release 也通过，但
+该结果包含 CORE-25 工作区补丁，不代表仅检出 ENG-12 提交就消除了默认选项缺陷。
+计数、成员与日志摘要见 [证据](../baselines/library-public-validation.json)。
+
+完整构建生成的其他包/站点漂移已恢复，新增站点 hash 资源移至忽略缓存留存。
+本提交只包含构建策略、包成员检查、测试/文档以及构建删除的 core 错误复制源码；
+CORE-25 的三个 JS 产物与源码保留到其自己的提交。没有手改生成代码，也没有新依赖。
+
+后续 AI 添加库静态资源时应显式设计资源入口和包成员检查，不重开隐式 public 复制。
+回退需同时恢复配置和检查，但会重新引入已证明的分发污染，不能直接拿来发布。
+独立提交主题：fix(build): [ENG-12] exclude declaration sources from library artifacts。
@@ -2,9 +2,9 @@

 > 由 tasks.json 生成。请修改数据后运行 `node refactor/scripts/plan.mjs --write`，不要手改本表。

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

-状态：todo 87 / doing 16 / blocked 0 / done 121 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 87 / doing 16 / blocked 0 / done 122 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -14,7 +14,7 @@

 | 包 | 基线版本 | 任务 |
 | --- | --- | --- |
-| artplayer | 5.4.1 | CORE-01, CORE-02, CORE-03, CORE-04, CORE-05, CORE-06, CORE-07, CORE-08, CORE-09, CORE-10, CORE-11, CORE-12, CORE-13, CORE-14, CORE-15, CORE-16, CORE-17, CORE-18, CORE-19, CORE-20, CORE-21, CORE-23, CORE-22, CORE-24, CORE-25 |
+| artplayer | 5.4.1 | CORE-01, CORE-02, CORE-03, CORE-04, CORE-05, CORE-06, CORE-07, CORE-08, CORE-09, CORE-10, CORE-11, CORE-12, CORE-13, CORE-14, CORE-15, CORE-16, CORE-17, CORE-18, CORE-19, CORE-20, CORE-21, CORE-23, CORE-22, CORE-24, CORE-25, ENG-12 |
 | artplayer-plugin-ads | 2.1.0 | PKG-ADS-01, PKG-ADS-02, PKG-ADS-03, PKG-ADS-04, PKG-ADS-05, PKG-ADS-06 |
 | artplayer-plugin-ambilight | 1.1.0 | PKG-AMBILIGHT-01, PKG-AMBILIGHT-02, PKG-AMBILIGHT-03, PKG-AMBILIGHT-04, PKG-AMBILIGHT-PROXY-01, PKG-AMBILIGHT-05, PKG-AMBILIGHT-06, PKG-FACTORY-01 |
 | artplayer-plugin-asr | 2.1.0 | PKG-ASR-01, PKG-ASR-02, PKG-ASR-03, PKG-ASR-04, PKG-ASR-05, PKG-ASR-06 |
@@ -132,7 +132,7 @@
 | CORE-23 | artplayer<br>检查并补齐键盘、焦点与可访问名称 | CORE-13, CORE-14, CORE-17, ENG-05, BASE-04 | 主要控件/设置/模式退出的键盘与焦点回归、名称和字幕可用性检查及必要兼容修正 | 保持旧快捷键和 DOM/CSS 钩子；真实浏览器验证，不以静态属性检查代替交互；处理 BASE-DOM-01 的主要控件 Tab 不可达，保留既有名称与快捷键 | H | done |
 | CORE-22 | artplayer<br>核心阶段完整验收 | CORE-21, CORE-23, PILOT-01, ENG-08, ENG-10, ENG-11 | 核心与旧插件的可自动化完整回归、资源/性能及明确外部验证缺口 | 核心自动化和公开差异处置通过；真实环境缺口链接包集成/REL 门槛，阶段完成不代表可公开发布 | H | done |
 | CORE-24 | artplayer<br>修复连续切源的播放意图继承 | CORE-22, PKG-AUDIO-04 | 连续切源保留原播放意图，同时尊重显式暂停与最新来源，回归旧/新 audio | 真实暂停状态的受控测试、重入/取消/失败/销毁、三引擎和 main/legacy 产物验证通过；不恢复过期来源的公开副作用 | H | done |
-| CORE-25 | artplayer<br>修复无 navigator 环境读取默认选项 | CORE-22 | 安全读取默认语言并保留浏览器已有默认值；实际 Node 与发布产物正反例 | 记录旧发布版 ReferenceError；候选在无 navigator 时可读默认选项，浏览器语言和公开类型不回归；不以补全局对象隐藏错误 | M | todo |
+| CORE-25 | artplayer<br>修复无 navigator 环境读取默认选项 | CORE-22, ENG-12 | 安全读取默认语言并保留浏览器已有默认值；实际 Node 与发布产物正反例 | 记录旧发布版 ReferenceError；候选在无 navigator 时可读默认选项，浏览器语言和公开类型不回归；不以补全局对象隐藏错误 | M | todo |

 ## 5 包迁移：artplayer-plugin-chapter

@@ -416,6 +416,12 @@
 | --- | --- | --- | --- | --- | --- | --- |
 | PKG-FACTORY-01 | artplayer-proxy-canvas, artplayer-plugin-ambilight<br>修复已迁移工厂的反向赋值兼容 | PKG-CANVAS-04, PKG-AMBILIGHT-04, PKG-DPIP-04 | 复现两包旧typeof工厂替换与新.default/可选重载冲突，修复公开类型并补安装消费者、产物和文档 | 默认工厂的历史合法反向赋值继续通过；既有类型/运行时导出逐版本核对，不能只验证Parameters或直接调用 | H | doing |

+## 2 测试与工程基础
+
+| ID | 范围 / 步骤 | 前置依赖 | 交付物 | 验收条件 | 风险 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- |
+| ENG-12 | workspace, artplayer<br>隔离库构建的 public 源码与分发内容 | ENG-03, CORE-21 | 禁用库的隐式 public 复制，拒绝误入包内的 TS 源码，清理生成污染并验证真实构建 | 三格式真实构建和严格 tarball 检查通过；已有声明和所有剩余成员字节不变；文档站使用独立构建 | M | done |
+
 ## 完成证据与阻塞

 - DOC-01: [记录](progress.md)
@@ -557,3 +563,4 @@
 - PKG-TOOL-THUMB-04: [记录](changes/2026-09-13-PKG-TOOL-THUMB-04-runtime-types.md) [记录](baselines/thumbnail-runtime-types-validation.json) [记录](changes/2026-09-13-PKG-TOOL-THUMB-04-public-types.md) [记录](baselines/thumbnail-public-types-validation.json) [记录](changes/2026-09-13-PKG-TOOL-THUMB-04-emitter.md) [记录](baselines/thumbnail-emitter-validation.json)
 - PKG-FACTORY-01: [记录](baselines/factory-assignment-gaps.json) [记录](baselines/factory-compatibility-proposals.json) [记录](factory-compatibility-decision.md) [记录](changes/2026-09-12-PKG-FACTORY-01-decision.md)
 - CORE-25: [记录](changes/2026-09-13-CI-01-node-consumers.md)
+- ENG-12: [记录](changes/2026-09-13-ENG-12-library-public.md) [记录](baselines/library-public-validation.json)
@@ -1,5 +1,19 @@
 # 进度与证据

+## ENG-12 库声明源码复制修复完成
+
+CORE-25 构建期间发现 Vite 默认复制 core/public 到 dist；实际候选 tarball 含 37 个
+误复制的声明源码。库配置现在禁用 publicDir，打包检查拒绝任意路径非声明 TS 后缀。
+三个格式真实磁盘构建反例由失败转通过；旧候选被新检查拒绝，新包去掉 37 个文件，
+其余 68 成员字节完全一致。完整 ci:build 的 21 库/i18n/编辑器/文档站/3 导入通过。
+定向 3 项、元数据 9 项和 lint 通过；本任务未另跑完整 ci:check，留给 CORE-25 最终验证。
+见[记录](changes/2026-09-13-ENG-12-library-public.md)和[证据](baselines/library-public-validation.json)。
+恢复 58 个无关生成文件，13 个新增站点 hash 资源移至缓存；保留构建移除的污染文件。
+CORE-25 源码/测试/三个 JS 产物仍在工作区，尚未完成/提交；本提交不包含这些修改。
+225 项：122 done、16 doing、87 todo；202 风险。ENG-DIST-PUBLIC-01 关闭。
+独立本地提交，不推送、不发布；下一步完成 CORE-25 全量验收。
+
+
 ## CI-01 Node 消费者矩阵检查点（doing）

 标准 Node 24.21.0 构建同一 core/chapter tarball，20.19.0/22.12.0/24.21.0 实际
@@ -205,3 +205,4 @@
 | JASSUB-TYPE-01 | open / 已复现 | JASSUB declared required URLs, Promise methods and resize parameter order differ from actual historical behavior | PKG-JASSUB-04 |
 | JASSUB-EXPORT-01 | open / 已复现 | JASSUB historical CommonJS object.default changes to a direct factory in 1.1.0 | PKG-JASSUB-04, PKG-JASSUB-06 |
 | CORE-DEFAULTS-SSR-01 | open / 已复现 | Reading static defaults throws when navigator is absent | CORE-25 |
+| ENG-DIST-PUBLIC-01 | resolved / 已复现 | Vite copied authored declarations into library distribution | ENG-12 |
@@ -4514,6 +4514,28 @@
      "compatibleResolution": "Read navigator through a guarded global lookup while preserving browser language defaults and public declaration shape.",
      "closureCriteria": "Published failure remains explicit; source and actual installed candidate defaults work without navigator on selected Node versions and browser language behavior stays unchanged.",
      "workspaceState": "Node 20.19.0 actual installed probe fails with ReferenceError: navigator is not defined. Published 5.4.0 and candidate 5.4.1 both reproduce under explicitly absent navigator on every selected runtime. CI-01 records this known failure, then compares default values under the same controlled en-US navigator; this is not a production fix."
+    },
+    {
+      "id": "ENG-DIST-PUBLIC-01",
+      "title": "Vite copied authored declarations into library distribution",
+      "confirmation": "reproduced",
+      "status": "resolved",
+      "owners": [
+        "ENG-12"
+      ],
+      "evidence": [
+        "test/library-build.test.js",
+        "refactor/baselines/library-public-validation.json",
+        "refactor/changes/2026-09-13-ENG-12-library-public.md"
+      ],
+      "compatibleResolution": "Disable library publicDir copying and reject non-declaration TypeScript members anywhere in checked tarballs.",
+      "closureCriteria": "Actual format builds omit public source/resources; dirty historical candidate fails the guard; new archive has no copied sources and preserves other bytes.",
+      "workspaceState": "Actual candidate had copied authored public TS files in dist; getViteBuildConfig now disables publicDir. Strict member checking rejects the prior archive, and the replacement differs only by source removals.",
+      "resolutionEvidence": [
+        "refactor/baselines/library-public-validation.json",
+        "refactor/changes/2026-09-13-ENG-12-library-public.md"
+      ],
+      "resolutionRationale": "Three-format disk fixture and actual core archive prove removal; all other package members remain byte-identical. Full 21-library and docs build passed. CORE-25 runtime work was present but is not closed by this task."
    }
  ]
 }
@@ -4490,7 +4490,8 @@
        "artplayer"
      ],
      "dependsOn": [
-        "CORE-22"
+        "CORE-22",
+        "ENG-12"
      ],
      "status": "todo",
      "risk": "M",
@@ -4499,6 +4500,27 @@
      "evidence": [
        "changes/2026-09-13-CI-01-node-consumers.md"
      ]
+    },
+    {
+      "id": "ENG-12",
+      "phase": "2 测试与工程基础",
+      "title": "隔离库构建的 public 源码与分发内容",
+      "scope": [
+        "workspace",
+        "artplayer"
+      ],
+      "dependsOn": [
+        "ENG-03",
+        "CORE-21"
+      ],
+      "status": "done",
+      "risk": "M",
+      "deliverable": "禁用库的隐式 public 复制，拒绝误入包内的 TS 源码，清理生成污染并验证真实构建",
+      "acceptance": "三格式真实构建和严格 tarball 检查通过；已有声明和所有剩余成员字节不变；文档站使用独立构建",
+      "evidence": [
+        "changes/2026-09-13-ENG-12-library-public.md",
+        "baselines/library-public-validation.json"
+      ]
    }
  ]
 }