@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.2

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/scanner/CHANGELOG.md

@@ -0,0 +1,506 @@
+# 变更日志
+
+## 4.0.0 - 2026-10-29
+
+### 变更
+
+- upgrade主CSV固定为9列，deprecated主CSV固定为8列；内部完整字段、findingId计算、扫描JSON schema4和交付布局4保持。
+- 索引移除历史路径及别名映射，缺少官方ID时按当前章节路径生成规则身份，188条行为来源的policyId路径哈希同步更新。
+
+### 修复
+
+- 精简后仍逐条输出同位置调用与显示相同的记录，详细符号、列号、废弃时间、检测来源和替代证据保留在扫描JSON。
+
+### 验证
+
+- 补充双模式表头、空表和重复记录回归，复制目录无需evals即可运行CLI、结构校验及adapter测试。
+
+## 3.0.0 - 2026-10-28
+
+### 变更
+
+- 扫描入口迁入scripts/scanner/bin，按core、behavior、deprecated、native分组，共享基础与维护回归统一位于scripts/shared和scripts/maintenance，不保留旧路径包装。
+- 删除未接入的src/index汇总导出和旧批次读取/诊断回退，批次模块仅保留布局4创建、ID分配与发布边界保护，扫描字段、算法及当前交付命名不变。
+- 版本与文件工具使用共享实现，保留真实SDK、发布通道、范围、物理身份和超时行为；运行指纹按新目录枚举并排除测试代码。
+
+### 验证
+
+- 保留扫描回归104项通过，复制目录中的CLI、资源和选定后端夹具通过；真实Windows、Node20、HarmonyOS工程和设备未新增验收。
+
+## 2.1.0 - 2026-10-27
+
+### 新增
+
+- 两类新批次统一使用outputLayout.schemaVersion=4，按mode提供deliveryDirectory、rawCsv及adaptedCsv；原始CSV直接位于upgrade或deprecated目录，适配表目标路径统一为adapted-results-<批次ID>.csv，scanner不生成模型结果。
+- 布局读取保留旧版本1/2/3及原文件位置，batchArtifactPaths保留历史默认参数，新扫描显式选择布局4；扫描CSV字段、完整扫描JSON数据schema及内部证据位置不变。
+
+### 修复
+
+- 读取功能目录CSV时先校验父批次，防止越界链接借外部合法旧元数据绕过检查；发布前再次校验功能目录与扫描证据目录。
+
+### 测试
+
+- 更新两类CLI、早期IDE失败与扫描输出回归，新增发布前替换功能目录链接的保护场景；scanner本机99项测试通过，平台与模型验收限制见skill验证记录。
+
+## 2.0.1 - 2026-10-27
+
+### 修复
+
+- 默认变更资料切换至 references/changelogs，索引和来源文件使用英文名称，保留精确路径映射、官方链接与稳定规则标识。
+- 内置行为策略仅保留 API13 起的 188 条记录；API12 行为基线在正文解析前排除，from=12 仍可覆盖 API13，废弃 API 继续基于真实 SDK 识别。
+- 策略生成过滤 API12、拒绝索引中未登记的来源，并正确解析 Windows 分隔符，避免维护时重新引入已删除资料。
+
+### 文档
+
+- 更新资料范围及中文金标记录，保留历史数值与结论，补充来源迁移、基线过滤和跨平台回归。
+
+## 2.0.0 - 2026-10-27
+
+### 变更
+
+- 将模式 deprecated-only 重命名为 deprecated，scan、inspect-rules 和内部入口不接受旧名称别名。
+- 批次、扫描 JSON、诊断与功能身份统一使用 deprecated，保持 schema 3、CSV 字段和命名不变。
+
+### 修复
+
+- 在 SDK 发现、后端启动或输出写入前拒绝旧名称，保留废弃 SDK 判断、替代声明、原生扫描及 upgrade 行为。
+
+## 1.0.0 - 2026-10-27
+
+### 变更
+
+- 删除 full 及默认模式，scan/inspect-rules 和内部入口仅接受显式 upgrade/deprecated-only，非法模式提前返回 SCAN_MODE_INVALID。
+- 移除 API 差异表引擎、兼容性分类、full 行为自动分类及项目级运行验证分组，规则按模式提前筛选。
+- 强制新扫描使用有效批次，保持两种模式的 CSV、schema 2/3 与命中身份，保留旧诊断读取。
+
+### 修复
+
+- 保留 SDK 废弃识别、替代声明审计、C/C++ 超时与范围处理，废弃结果逐位置分组输出与原行为一致。
+- 官方来源目录生成不再推断动作，旧新路径标识一致，换行哈希跨平台稳定，并正确解析 API 26 的目录版本。
+- 废弃维护验收显式选择模式并读取真实返回路径，对比时排除批次 ID 差异。
+
+## 0.20.0 - 2026-10-23
+
+### 变更
+
+- deprecated-only 新批次采用 schemaVersion=3，根目录保留时间戳扫描 CSV，扫描 JSON、验证 CSV、coverage 和 diagnostics 收纳到 .internal/scanner。
+- 批次记录模式与扫描时间戳，CSV 命名沿用目录的同秒冲突后缀，继续保留全部命中和内部批次身份。
+
+### 修复
+
+- 诊断返回、失败读取和内部目录校验兼容新版废弃 API 布局，full 及行为变更沿用现有路径。
+- 补充非空扫描、失败诊断、批次身份及旧布局回归，更新提前拒绝不兼容 IDE 的产物位置断言。
+
+## 0.19.1 - 2026-10-20
+
+### 修复
+
+- 统一源码类型白名单，禁止将二进制依赖、包 main、非源码 overlay 或解析回退结果标记为 TypeScript 源码。
+- 保留已有源码与声明入口解析、未解析依赖诊断及原生源码扫描；补充多种二进制、目录别名和编译上下文回归。
+
+## 0.19.0 - 2026-10-19
+
+### 变更
+
+- upgrade 新批次采用 schemaVersion=2，扫描 JSON、coverage 和 diagnostics 收纳到 .internal/scanner/，根目录保留批次扫描总表。
+- upgrade 停止生成空验证 CSV，validationCsv 返回 null；full 和 deprecated-only 保留原协议。
+
+### 修复
+
+- 返回与失败诊断使用实际内部路径，诊断读取兼容旧布局，拒绝损坏元数据回退及内部目录链接越界。
+- 增加零行与非空扫描产物、返回路径和旧模式验证 CSV 回归，同步精简布局文档。
+
+## 0.18.2 - 2026-10-17
+
+### 修复
+
+- C++ 超时测试夹具使用 `path.join` 和安全字符串序列化，避免 Windows 路径嵌入 JavaScript 后丢失反斜杠而被来源检查过滤。
+- 普通路径及中文、空格、单引号路径均验证 ArkTS/C++ 已完成结果在返回值、CSV 和扫描 JSON 中保留，继续检查超时状态与人工复核警告。
+
+## 0.18.1 - 2026-10-16
+
+### 修复
+
+- 模块解析与规范文件匹配的物理路径统一使用 `realpathSync.native`，Windows 8.3 短路径别名与扫描器物理根保持同一身份，合法绝对扫描目录不再被误判越界。
+
+## 0.18.0 - 2026-10-16
+
+### 新增
+
+- upgrade CLI 为扫描分配一次生成的 12 位随机批次 ID，独占预留并重试冲突，保留原时间戳目录及同秒目录后缀。
+- 扫描总表与伴随 JSON 使用同一批次命名并记录 batchId，返回统一 outputLayout，保留其他扫描模式的原文件名。
+
+## 0.17.4 - 2026-10-16
+
+### 修复
+
+- 与 Adapter 共用 SDK 根目录解析，接受 default 输入并向后端传递规范 SDK 根目录，诊断保留原始输入和元数据位置。
+- 对同一后端复用有界帮助探测，避免契约识别与文件过滤能力检查重复启动进程，保持能力证明与超时约束。
+- 新增 SDK 目录规范化和帮助探测次数回归，保留精确扫描区间及实际 SDK 上限校验。
+
+## 0.17.3 - 2026-10-15
+
+### 修复
+
+- 使用带来源和校验的精确版本目录解析 from/to，起点与终点采用不同优先级，显式通道及实际 SDK 上限不被静默改写。
+- 区分 index 家族与文件过滤能力，CLI 帮助优先于源码偶然出现的参数字符串，支持完整模块范围且拒绝不支持的窄目录。
+- 扫描元数据记录精确区间、实际 SDK 和能力依据，保留既有废弃状态扫描的无区间测试兼容性。
+- 新增严格参数契约夹具，目标 SDK 声明的构建覆盖校验不再混用发布通道排序。
+
+## 0.17.2 - 2026-10-15
+
+### 修复
+
+- 回归脚本复用公共进程执行器及 PATH 合并，使用已探测 OHPM，保留流式日志并正确判定启动失败和超时。
+- 统一日志导入及两类金标比较的 Windows 路径身份，兼容盘符、目录大小写和分隔符差异。
+- 扫描临时目录清理有限重试，失败仅附加结构化诊断，不覆盖扫描结果或原始错误。
+- 修复假扫描后端对 POSIX 路径的依赖，补充 Windows 路径和占用清理回归。
+
+## 0.17.1 - 2026-10-15
+
+### 修复
+
+- 以真实规则来源和条目锚点验证超链接，拒绝后端 scan-* ID 和其他规则链接覆盖官方来源。
+- 统一 harmonyos-releases 与 doccenter-release-notes 文档别名，输出规范化的真实条目链接。
+
+## 0.17.0 - 2026-10-15
+
+### 新增
+
+- 新增加载规则、命中规则、CSV 记录和源码位置独立统计，并向 Adapter 透传官方覆盖缺口与规则包版本。
+
+### 修复
+
+- 补齐缺少插件 URL 的规则所对应的唯一官方条目链接，保留后端已有 HYPERLINK，记录链接来源及缺失诊断。
+- 覆盖警告列明缺失变更的标题、版本及官方来源，不再仅报告缺口总数。
+
+## 0.16.0 - 2026-10-14
+
+### 新增
+
+- 新增 scan-module 模块选择及模块、目录交集，支持工程外已注册模块与 HAR 范围校验。
+- 按所选模块或文件集合调用 integrated 与 index 后端，文件列表按模块和长度分批，保留精确范围能力诊断。
+- 扫描元数据记录范围指纹和实际源文件集合，新增两类后端的真实调用参数回归。
+
+### 修复
+
+- 统一模块名、目录名与物理路径解析，保留源码范围及排除目录校验，避免物理路径别名误过滤。
+
+## 0.15.1 - 2026-10-14
+
+### 修复
+
+- 所有扫描及规则检查模式接受编译 SDK ≥ target，拒绝低于目标的 SDK，并保留真实声明来源和快照。
+- 分别报告 compileSdk 与 targetSdk，SDK26 声明不冒充历史 SDK20，废弃条目仍按目标 API 上限过滤。
+
+## 0.15.0 - 2026-10-13
+
+### 新增
+
+- 新增 upgrade 模式，保留 DevEco 插件四类非废弃逐位置结果，排除额外 API 差异规则及旧行为分类过滤。
+- 新增官方规则覆盖差异及工程相关性报告，允许使用高于目标 target 的真实编译 SDK 声明。
+
+### 修复
+
+- 保留 upgrade 插件调用列信息，原子分配时间戳目录，避免并发扫描覆盖证据。
+
+本文档记录 HarmonyOS API 兼容性扫描器及其 skill 集成的重要功能新增、行为调整和缺陷修复。
+
+## 未发布
+
+### 配套 Adapter 2.9.0
+
+- SDK 类型程序增加可选内存 Builder，供适配器调用所选 SDK 的 ArkTS Linter；不改变扫描、规则和 CSV 语义，保留 0.14.0 版本锁定。
+
+## 0.14.0 - 2026-10-06
+
+### 新增
+
+- 与 Adapter 共用 DevEco 版本校验，按目标 SDK 平台版本确定 IDE 门槛，保留实际版本、最低要求和目标诊断证据。
+
+### 修复
+
+- 两种扫描模式及规则检查在扫描后端启动前拒绝过低或无法识别的 DevEco 版本，环境预检同步禁止不合格后端的帮助探测。
+
+### 文档
+
+- 补充随目标变化的 IDE 要求和环境修复提示，保留目标 SDK 精确快照与扫描组件覆盖校验。
+
+## 0.13.0 - 2026-10-01
+
+### 新增
+
+- 与 Adapter 共用精确版本入口，支持 API Level 简写、Beta 序号和通道比较。
+- SDK 未解析导入增加使用声明／公开导出影响证据，无关缺失导出仅告警，相关缺失仍阻断完整扫描。
+- 类型程序支持不落盘的拟议源码覆盖层，用于准确替代符号、重载、接收者及参数验证。
+
+### 修复
+
+- SDK 声明证据保存参数及返回类型，缺失 SourceFile 的合成节点安全返回；运行产物记录 Adapter/Scanner 版本与实现来源。
+
+## 0.12.0 - 2026-09-29
+
+### 新增
+
+- `scan` 与 `inspect-rules` 省略 `--to` 时使用所选 SDK 的精确版本；版本解析完整区分 Canary、Beta、Beta1、Beta2 与 Release。
+- 失败 JSON 与 `diagnostics.json` 增加 command、stack、cause 和 artifactPaths，并保留最多 50 层堆栈。
+
+### 修复
+
+- 目标版本和规则选择不再丢失 Beta 序号，Beta1 与 Beta2 不会被视为同一 SDK 快照。
+
+## 0.11.0 - 2026-09-29
+
+### 新增
+
+- 扫描输出改为时间戳目录：默认输出根目录改为工程 `.api-change-output/`，每次运行新建 `YYYYMMDDHHmmss` 子目录（同秒冲突追加 `-2` 递增），`apiChange_<时间戳>.csv`、`apiChange_<时间戳>.validation.csv`、`apiChange_<时间戳>.scan.json` 携带相同时间戳。
+- 新增 `--mode deprecated-only` 专项扫描模式：行为／UX／定义变更规则不进入扫描后端，主 CSV 中 `Change Type` 只存在 `Deprecated API`；C/C++ 废弃规则仍通过 DevEco 后端检测。
+- 主 CSV 与验证 CSV 的 `Title` 列改为 `=HYPERLINK()` 公式：行为变更行链接官方变更文档，废弃行优先链接关联变更文档 URL、公开 `@ohos.<module>` 模块回退官方 API 参考页，验证清单行链接本地 changelog 来源文档；无法可靠构造链接时保持纯文字。
+- 原生模块构建前置自动执行 `ohpm install`（10 分钟超时）；失败以 `OHPM_INSTALL_FAILED` 报错，`ohpm` 不可用时以 `OHPM_UNAVAILABLE` 提示。
+
+## 0.10.13 - 2026-09-29
+
+### 修复
+
+- SDK catalog 同时保留原始 `file + start` 索引和平台规范化位置索引，`catalogEntry` 在原始键未命中时使用规范键回退。
+- 零宽度 ArkTS 节点的父容器及同文件声明匹配也统一使用平台路径身份。
+
+## 0.10.12 - 2026-09-29
+
+### 修复
+
+- `catalogEntry` 现在从原始 SDK AST 节点获取文件名和起始位置，修复克隆声明节点的文件名格式与目录索引不同导致的映射失败。
+- 增加 Windows 克隆节点使用反斜杠、原始节点使用正斜杠的精确回归用例。
+
+## 0.10.11 - 2026-09-29
+
+### 修复
+
+- ArkTS compiler host 的 `getCanonicalFileName`、源文件缓存和 SDK 声明缓存共用跨平台路径身份，修复 Windows 正反斜杠导致的 SDK `api/` 类型解析不一致。
+- SDK 内部文件的未解析导入也使用相同身份判定，避免将系统声明问题误归为普通第三方警告。
+
+## 0.10.10 - 2026-09-29
+
+### 修复
+
+- DevEco 规则加载结果保留“规范语义版本 → 实际规则文件基名”映射，并在 integrated 后端启动时透传。
+- 新命名传入 `HarmonyOS_26.0.0_Release`，旧布局继续传入 `HarmonyOS_26.0.0(26)_Release`；无映射时保留原有规范命名回退。
+
+## 0.10.9 - 2026-09-28
+
+### 修复
+
+- 规则覆盖判定不再比较固定文件名，改为解析文件名后与目标语义版本比较，接受 API 26 省略 `(26)` 的新命名。
+- 展开目录和 JAR 使用语义版本 key 去重，目录文件优先级保持不变。
+
+## 0.10.8 - 2026-09-28
+
+### 修复
+
+- 无论展开规则目录是否存在，都检查 project API change JAR 的规则条目；加载时以目录文件优先，只从 JAR 解压缺失的版本文件。
+- 覆盖“目录有 Beta1、JAR 有 Beta1 和 Release”的混合布局，并验证同名时不读取 JAR 重复项。
+
+## 0.10.7 - 2026-09-28
+
+### 修复
+
+- 废弃 API 位置归属改为按当前平台路径语义判断文件是否位于模块根目录，兼容 Windows parser 将反斜杠转为正斜杠。
+
+### 文档
+
+- 补充跨平台金标的 `sourceSnapshot`、目标 SDK 版本和 `sdkSnapshot` 一致性前置条件。
+
+## 0.10.6 - 2026-09-28
+
+### 修复
+
+- 对 Windows DevEco `index.js` 的 worker 文件名打包不一致增加子进程内兼容层；仅在 `ApiScan.worker.ts` 缺失且同目录存在 `worker.js` 时重定向。
+
+## 0.10.5 - 2026-09-28
+
+### 修复
+
+- `index` 后端使用原生模块扫描和内部分批，避免 `--scanFilePaths` 随工程文件数增长并超出 Windows 命令行限制。
+- 新增 10,000 个源文件路径的回归用例，同时保留扫描目录和源文件范围过滤。
+
+## 0.10.4 - 2026-09-28
+
+### 修复
+
+- 废弃规则审计按 parser 规范化后的文件名查找 SDK 源文件，解决 Windows 反斜杠 map key 与正斜杠 `SourceFile.fileName` 不一致导致的 `undefined.text`。
+- 无法找到声明源时返回结构化的 `SDK_DECLARATION_SOURCE_MISSING` 错误。
+
+## 0.10.3 - 2026-09-28
+
+### 修复
+
+- SDK 废弃声明索引忽略无法解释的无名 JSDoc 节点，并继续提取有效的 `@useinstead` 和 `@throws` 标签。
+- `scan` 失败输出和诊断文件新增 `stage`，Adapter 同步透传 `scannerStage`。
+
+## 0.10.2 - 2026-09-28
+
+### 修复
+
+- 行为策略来源哈希在计算前统一换行符，避免 Windows CRLF checkout 误报 `BEHAVIOR_POLICY_STALE`。
+- 校验错误现在区分 `SOURCE_NOT_FOUND` 与 `SOURCE_HASH_CHANGED`，内容变更时返回期望与实际哈希。
+
+## 0.10.1 - 2026-09-28
+
+### 修复
+
+- 支持直接读取 JAR 中 Deflate/Store 压缩的 `apiChange/*.json`，覆盖 Windows 未展开规则资源目录的安装布局。
+- project API change JAR 改为普通目录缺失时的规则源，并在诊断中记录 JAR 路径、条目和读取错误。
+
+## 0.10.0 - 2026-09-26
+
+### 新增
+
+- 按 webpack 入口和 CLI 参数契约区分综合 `ApiChangeMain` 与 ArkTS `MainSrc/index` 后端，不依赖固定脚本文件名。
+- `index` 后端支持生成 SDK 配置、扫描工程 ArkTS 文件并将原始 CSV 转换到统一结果模型。
+- 诊断记录 DevEco product-info、扫描器候选、规则资源、parser、SDK family 和 C API 后端路径。
+
+### 修复
+
+- SDK 与 DevEco Studio 分离安装时不再把 SDK 父目录误判为 IDE 根目录。
+- project API change JAR 不再作为未使用的启动依赖；C/C++ 与 Native 组件改为使用时校验并返回明确错误码。
+
+## 0.9.0 - 2026-09-24
+
+### 新增
+
+- 支持将 DevEco Studio 根目录与 SDK 根目录分开传入，覆盖 Windows 自定义 SDK 布局。
+- 接入共享平台进程、文件与路径层，支持 Windows `.bat/.cmd`、进程树超时清理和大小写不敏感路径身份。
+
+### 变更
+
+- Native 预构建和 DevEco 扫描统一使用跨平台进程执行器；C++ 超时在 Windows 上终止完整子进程树。
+- Windows 集成扫描在真实 DevEco 金标验证完成前标记为实验能力。
+
+## 0.8.0 - 2026-09-24
+
+### 新增
+
+- 内置覆盖 320 条官方行为变更的策略目录，保存文档哈希、生效条件、处置类型和静态检查。
+- 新增按规则聚合的 `apiChange.validation.csv`，项目级变更不需 API 命中也可生成验证任务。
+
+### 变更
+
+- 行为变更主 CSV 按规则、API 和文件聚合，只保留代码／配置整改及代码复核项。
+- 完整扫描 JSON 升级为 schema v4，保留全部调用点、整改分组、验证分组和静态证据。
+
+## 0.7.0 - 2026-09-22
+
+### 新增
+
+- 将 API 12 固定为行为／UX 变更的已适配基线，排除规则不进入 DevEco 扫描后端，`coverage.json` 记录 `BEHAVIOR_BASELINE_ALREADY_ADAPTED` 及规则数。
+- 官方明确无需适配的行为变更新增结构化原文证据，完整 JSON 保留来源字段和结论。
+
+### 变更
+
+- 条件性无需适配、混合章节和只有可选建议但没有明确结论的条目仍保留人工评估；API 定义变更和废弃 API 扫描语义不变。
+
+## 0.6.0 - 2026-09-22
+
+### 变更
+
+- 本目录成为 `harmonyos-api-upgrade-adapter` 仓库内的 scanner 唯一开发源码，不再与外部 tools 仓库同步。
+- 新增 `src/index.mjs` 稳定内部入口，供 adapter 使用 SDK 目录、ArkTS 程序、语义扫描和 CSV 能力。
+- 保留独立 CLI 和扫描器测试，发布及版本变更统一由 Skill 仓库管理。
+
+### 修复
+
+- 排除 Hvigor 在模块根目录生成的 `BuildProfile.ets`，避免非增量构建前后源码快照被误判为变化。
+
+## 0.5.0 - 2026-09-16
+
+### 新增
+
+- 使用目标 SDK 自带 ArkTS 解析器和配置建立完整废弃声明目录，支持命名空间、继承、重载、Kit 别名和组件字段。
+- 独立 SDK 语义废弃检测覆盖起始版本之前的历史废弃，不再依赖 DevEco 文档增量规则。
+- CSV 增加声明 ID、列号、废弃 API Level、检测来源和源码归属；完整 JSON 升级为 schema v3。
+- 支持可信编译日志导入依赖告警，验证日志、SDK、源码及配置快照；第三方代码禁止自动修改。
+- 增加通用金标位置比较器及隔离构建／双次扫描回归脚本。
+
+### 修复
+
+- 修复所属容器被误当成废弃类，以及成员缺少完整命名空间导致漏扫的问题。
+- 修复废弃重载被同名兼容扩参规则覆盖并过滤的问题。
+- 修复 SDK 子串查找将 format、同名成员或其他重载的替代方案串用的问题。
+- 修复语句首行定位和文件／行去重丢失多个调用的问题。
+- 在遍历入口排除依赖、构建和 `.hvigor` 缓存，并以选中文件集合约束输出。
+- 发布报告前验证源码、配置、已分析依赖和 SDK／解析器哈希，拒绝未解析系统 API 的完整扫描声明。
+- 修复大小写不敏感文件系统中 Index.ets 导入别名与实际 index.ets 输出位置不一致的问题；恢复 SDK ArkUI 组件的隐式继承类型。
+- C++ 语义批次增加外层 240 秒进程组超时保护，中断结果显式提示，已完成 ArkTS 结果继续生成。
+
+## 0.4.0 - 2026-09-09
+
+### 新增
+
+- 增加工程适用性证明：扫描器从 `module.json5` 确认 Stage 模型后，自动过滤仅约束 FA 模型的 ArkUI Stage 模型规则。
+- 增加保守的 API 声明兼容分析，支持证明 `ResourceStr` 已知别名扩展、`Optional<T>` 包装、联合类型扩大和新增尾部可选参数仍接受旧调用。
+- `apiChange.scan.json` 为上述过滤结果保留结构化 `applicabilityProof`，包含工程模型或新旧 API 声明证据。
+- Skill 的 `NO_ADAPTATION` 决策增加高置信度结构化证明校验，要求证明类型、直接证据和源码或文档引用。
+
+### 变更
+
+- 条件性行为变更、纯参数改名和无法安全展开的命名类型仍保留在主 CSV，交由 skill 根据调用实参和源码上下文判断。
+- 扫描器版本升级至 `0.4.0`，适配 skill 版本升级至 `1.4.0`。
+
+### 修复
+
+- 修复在扫描器包目录执行 `npm test` 时，金标比较测试错误拼接脚本路径的问题。
+
+## 0.3.0 - 2026-09-09
+
+### 新增
+
+- 从精确关联的行为变更文档章节识别明确“无需适配”或“不涉及应用适配”的扫描结果。
+- 从目标 SDK 的 `@deprecated` 声明提取 `@useinstead` 替代 API、声明文件和行号，并写入 CSV 与完整扫描 JSON。
+- 金标比较器支持通过 `--scan-json` 将已按文档过滤的金标条目计入完整覆盖率。
+
+### 变更
+
+- 文档明确无需适配的命中不再进入 `apiChange.csv`，但仍保留在 `apiChange.scan.json`，过滤原因为 `DOCUMENTED_NO_ADAPTATION`。
+- Skill 最终生成的适配 CSV 也会移除已确认 `NO_ADAPTATION` 的条目，并在最终报告记录过滤数量。
+- 扫描器版本升级至 `0.3.0`，适配 skill 版本升级至 `1.3.0`。
+
+### 修复
+
+- 修复 skill 无法从扫描结果获得废弃 API 替代方案，导致 SDK 已声明 `@useinstead` 时仍被标记为无替代方案的问题。
+- 修复模拟器前台启动进程被 20 秒命令超时终止，以及 HDC 未就绪或应用启动失败时仍在 `finally` 阶段关闭模拟器的问题。
+- 模拟器改为独立进程启动，优先复用一台已运行的匹配实例，并同时验证 HDC shell、应用进程和 UI 布局。
+- 修复 `-screenshotPath` 被错误传入文件路径的问题；现在传入目录并等待非零 PNG 写入完成。
+- 支持有界处理连续出现的“同意”和“允许”首次启动页面，确认进入应用首屏并截图后才判定冒烟通过。
+
+## 0.2.0 - 2026-09-08
+
+### 新增
+
+- 为扫描结果增加确定性分类：需要修改或人工确认的结果进入 `apiChange.csv`，全部命中保留在 `apiChange.scan.json`。
+- 为完整扫描结果增加 `includedInCsv`、`disposition` 和 `filterReason`，并输出总命中数、主报告数、过滤数及过滤原因汇总。
+- 增加参数类型范围扩大、成员迁移到父类、能力新增、删除错误码、可选权限新增和区间内无净变化等兼容性过滤规则。
+- 增加兼容性过滤、区间状态变化和 CSV/JSON 分层输出的自动化测试。
+
+### 变更
+
+- `apiChange.csv` 只保留需要代码修改或无法静态证明兼容、需要人工确认的结果。
+- Skill 升级适配流程只处理主 CSV；完整扫描命中和过滤依据通过 `apiChange.scan.json` 审计。
+- 扫描器版本升级至 `0.2.0`，适配 skill 版本升级至 `1.2.0`。
+
+### 修复
+
+- 修复扫描区间内能力状态多次变化时，成对抵消算法可能错误过滤最终不兼容变更的问题。
+- 修复扫描器同步或 skill 安装时复制 `.git`、`.DS_Store`、`node_modules` 等仓库或依赖元数据的问题。
+
+## 0.1.0 - 2026-09-07
+
+### 新增
+
+- 提供独立的 ArkTS 和 C/C++ API 语义扫描能力。
+- 支持指定工程、SDK、扫描目录、起始版本和目标版本，并校验版本区间 `(from, to]`。
+- 基于 DevEco Studio 内置扫描组件和本地 HarmonyOS 变更文档编译确定性规则。
+- 输出 `apiChange.csv`、`apiChange.scan.json`、`coverage.json` 和 `diagnostics.json`。
+- 明确扫描并标识废弃 API，补充 DevEco 金标未覆盖的废弃规则。
+- 支持缺失或过期原生构建产物时自动调用 Hvigor `compileNative`。
+- C++ 扫描超时时显式告警并继续生成报告；CDT 不可用或退化到 grep 时停止扫描。
+- 提供四个测试工程的金标对比工具和重复扫描一致性验证。

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/scanner/GOLDEN_VALIDATION.md

@@ -0,0 +1,42 @@
+# 金标验证记录
+
+跨平台金标只在工程 `sourceSnapshot`、目标 SDK 版本与 `deprecationCatalog.sdkSnapshot` 相同时比较。Beta 与 Release SDK 的声明和废弃标记可以不同，不将其行数差异视为平台差异。输入快照一致后，废弃 API 使用 `API Symbol ID + Code Location + Column` 对齐，并归一化主机绝对路径。
+
+## Scanner 0.5.0 废弃 API 验收 - 2026-09-16
+
+目标 SDK：HarmonyOS 26.0.0 Release（26.0.0.105）。四工程在隔离副本中执行非增量 `assembleApp`，保持 Git 基线业务源码，采用原工程当前构建配置以匹配已安装依赖；补齐现有缺失 rawfile 资源，不复制构建缓存。原工程和业务代码不修改，不启动模拟器。
+
+每次构建日志关联 SDK、源码、配置和日志哈希，使用 `compare-deprecated.mjs` 按真实文件名、行、列及 SDK 符号对齐。第三方 `oh_modules` 不扫描，也不计入自有代码漏扫。
+
+| 工程 | 自有代码编译金标 | 漏扫 | SDK 废弃引用 | 仅扫描器发现 | 两次 CSV / 完整 JSON |
+| --- | ---: | ---: | ---: | ---: | --- |
+| ComprehensiveNews1.0.2 | 208 | 0 | 217 | 9 | 完全一致 |
+| ComprehensiveTool1.0.7 | 301 | 0 | 319 | 18 | 完全一致 |
+| ComprehensiveMall1.0.4 | 86 | 0 | 94 | 8 | 完全一致 |
+| Recipes | 53 | 0 | 57 | 4 | 完全一致 |
+| 合计 | 648 | 0 | 687 | 39 | 通过 |
+
+仅扫描器发现的引用均保留准确 SDK 声明证据，不能仅因构建未引用源码或编译没有告警而删除。编译金标只提供正例，不是全部扫描目录的负例。C/C++ 沿用现有后端；本表不宣称 C++ 编译金标覆盖已验证。C++ 卡死的外层超时和非阻断报告流程另有通用测试覆盖。
+
+业务源码基线：News `5f686d1`、Tool `1234fa7`、Mall `3fdbcd1`、Recipes `f791656`。回归脚本、配置来源和完整结果见本机 `/tmp/harmony-scanner-050-regression-20260915/regression.json`，各子目录包含 `build.log`、`build-evidence.json`、`comparison.json` 和两轮报告。临时目录不提交。
+
+## Scanner 0.4.0 历史文档 CSV 验证
+
+验证日期：2026-09-09
+
+全部比较使用 `scripts/compare-golden.mjs` 并传入 `--scan-json`。比较器结合主 CSV 与包含过滤记录的扫描 JSON 核对 DevEco 完整覆盖，再单独报告来自变更文档的待评估项。因兼容、工程不适用或文档明确无需适配而从主 CSV 排除的记录，仍保留在 `apiChange.scan.json`，并附过滤原因与适用性证明。
+
+| 工程 | 版本区间 | 金标行数 | 匹配 | 缺失 | 额外 | 主 CSV 行数 | 已报告 DevEco 行数 | 已过滤金标行数 | 已报告文档行数 | 全部过滤行数 | 废弃行数 | 耗时 |
+| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| ComprehensiveMall1.0.4 | API 12 至 API 26 Beta2 | 3,134 | 3,134 | 0 | 0 | 1,133 | 916 | 2,218 | 217 | 3,570 | 91 | 67.5 s |
+| ComprehensiveNews1.0.2 | API 12 至 API 26 Release | 3,561 | 3,561 | 0 | 0 | 1,276 | 968 | 2,593 | 308 | 4,397 | 205 | 71.6 s |
+| ComprehensiveTool1.0.7 | API 12 至 API 26 Release | 8,361 | 8,361 | 0 | 0 | 3,925 | 2,727 | 5,634 | 1,198 | 8,958 | 284 | 114.6 s |
+| Recipes | API 12 至 API 26 Beta2 | 1,424 | 1,424 | 0 | 0 | 633 | 518 | 906 | 115 | 1,423 | 53 | 66.3 s |
+
+Tool 金标 CSV 包含 38 个模块，不包含 `ar_measure`；比较采用相同模块范围。生成的报告包含一条 C 记录，执行完成且未超时。扩大范围的扫描可能包含有效的 `ar_measure` 记录，但这些记录不属于金标范围。
+
+提供的金标 CSV 不包含完整废弃 API 数据集。生成的 CSV 通过 `Change Type = Deprecated API` 和 `Change Operation = API_DEPRECATED` 明确标识此类记录；目标 SDK 声明了 `@useinstead` 时，该行还包含 `Replacement API` 和 `Replacement Source`。兼容、工程不适用及文档明确无需适配的记录仅从主 CSV 省略；扫描 JSON 保留全部记录，以及 `includedInCsv`、`disposition`、`filterReason` 和可取得的 `applicabilityProof`。
+
+## 可重复性与性能
+
+`ComprehensiveNews1.0.2` 在 API 12 至 API 26 Release 区间执行两次扫描，分别使用独立包与 Skill 内置包。两次均从 5,673 条记录中报告 1,276 行，并过滤相同的 4,397 条，其中包括 2,396 条 Stage 模型约束和 132 条源码兼容的签名变更。输出字节完全一致：CSV SHA-256 为 `d151d89f69e7c6e1093eca63bd8cd6ba1e5fba2ba72d36a48ea02886a815e64c`，扫描 JSON SHA-256 为 `e3baf7784edfdd8d49f7ca0dfcc9a698db7d83e7b99e11de4f1d827657feb2b5`。两次耗时分别为 71.6 秒与 73.6 秒。