查看: 582|回复: 3

ArkTS 移植 fast-diff:严格模式编译与差分验

[复制链接]
发表于 8 小时前 | 显示全部楼层 |阅读模式
把纯 JS/TS 的 npm 库搬到 OpenHarmony/HarmonyOS,最后通常要产出一个能在 ArkTS 严格模式下编译的 HAR。真正容易出问题的不是语法改写,而是移植顺序和验证链:先查重、先让上游测试跑起来、编译报错逐条处理、差分对照分清哪些结论可信。下面以 fast-diff 为例,复盘 harmony-js-lib-port 这份 Skill 在实操中暴露的问题和修正。

一、先钉死移植目标:语义一致优先

harmony-js-lib-port 是一份写给 AI 编程助手的操作手册,但它约束的其实是人的流程。目标只有一句话:ArkTS 严格模式编得过,行为和上游一模一样;性能优化、新 API、示范界面都放到移植之后。这个顺序来自 jsonrepair 那次的教训:一边移植一边做优化,差分测试要同时兜住语义和性能,出问题很难定位。

Skill 把流程拆成六步:查重,固定上游版本,搭工程,先搭差分测试再改代码,逐个文件移植,最后过验证闸门。闸门就是每一步结束时必须通过的检查,过不了不往下走。HAR 是鸿蒙的静态库包;codelinter 是命令行代码检查工具;hdc 用来连接设备。

二、查重和工程准备

fast-diff 是在 ohpm 中心仓查重后选定的。ohpm 是鸿蒙三方库中心仓,类似 npm。check-ohpm.sh 会按精确包名和关键词同时搜索。compare-versions 和 ms 已经有人移植,fast-diff 和 diff-match-patch 搜不到;按 text diff 搜到的 diff 7.0.0 是另一个库 jsdiff 的移植,算法和 API 都不同,不算重复。

fast-diff 适合做验证样本:纯 JS 实现,Apache-2.0 许可证,自带测试,不依赖浏览器 DOM 和 Node 内置模块,整个库只有一个 1138 行文件。它按字符比对两段文本差异,Quill 编辑器的 delta 依赖它,算法来自 google-diff-match-patch。

工程脚手架也暴露过问题。scaffold.sh 负责一键生成工程骨架,但它先替换占位符、后复制差分测试模板,导致 prepare.mjs 里的 __HAR__ 没有被替换。问题不大,却说明脚本必须自己完整跑一遍,不能只写进 Skill 就算完成。

三、先让上游测试跑在移植代码上

Skill 要求先打通测试管道,再改语法。v1 默认上游测试用 vitest 或 jest 这类框架,改 import 就能接上;fast-diff 不是。它的测试是一个 398 行的 Node 脚本,用 CommonJS 的 require('./diff.js') 引入库,依赖 lodash 和 seedrandom,出错就 throw,全部通过时打印 Success!。它还会读取 diff.INSERT 这种挂在函数对象上的属性,并且每次运行都换随机种子。

接法只替换 require 那一行,测试文件其余部分不动;再用 DIFF_TARGET=upstream 让同一份测试先跑 npm 原包,证明管道本身没问题。diff-shim.cts 把移植版包一层,把 INSERT、DELETE、EQUAL 三个常量挂回去。这样后面差分再出红灯,就只可能是移植代码的问题。

四、编译策略:先直译,再按报错改

v1 的规则表要求把 var 改成 let、补类型、把正则字面量换成 new RegExp,还要求把嵌套函数改成私有类。实际操作中,两个内层函数没有使用任何外层变量,助手直接把它们挪到了模块顶层。第一次编译只报 4 条:三条 arkts-no-any-unknown 出在 new Array(v_length) 上,改成 new Array<number>(v_length) 即可;剩下一条是可空类型收窄,上游靠逻辑保证不会为空,但 TypeScript 推断不出来。
  1. // 改写后:分支一一对应,不用 as 和 !
  2. if (hm1 !== null && hm2 !== null) {
  3.   hm = hm1[4].length > hm2[4].length ? hm1 : hm2;
  4. } else if (hm1 !== null) {
  5.   hm = hm1;
  6. } else if (hm2 !== null) {
  7.   hm = hm2;
  8. } else {
  9.   return null;
  10. }
复制代码

改完再编译就过了。但带标签的代码块、往函数上挂属性的写法、把对象当布尔值用的写法,编译器都没有报错。于是又写了一个探针文件,把上游常见写法逐个放进去编译。被拒的有嵌套函数、var、索引签名、没声明类型的对象字面量、函数表达式、解构赋值,以及给函数挂函数类型的属性;正则字面量不在其中。v1 要求改正则字面量,是照旧资料写的,在现在的工具链上并不需要改。

所以第 4 步改成先直译、后按报错改。编译器没报的写法不要为了“看起来像 ArkTS”去改,每多改一处,就多一处要靠差分测试兜底。

codelinter 也不能替代编译。探针文件里明明有 11 处 ArkTS 语法错误,codelinter 却报 Errors:0,只提示 ForEach 缺 keyGenerator、启动图标太大。它不检查 ArkTS 语法,只能作为补充闸门。

五、差分对照要比较结果或异常

第一版差分测试写成 expect(port(a, b)).toEqual(upstream(a, b)),emoji 那一组当场栈溢出。调用栈全在移植版里,看起来像递归被改坏了。换成 run() 包住两边调用后才发现,npm 原包在同样输入上也栈溢出。
  1. type Outcome = { ok: true; out: unknown } | { ok: false; err: string }
  2. function run(f: () => unknown): Outcome {
  3.   try { return { ok: true, out: f() } } catch (e) { return { ok: false, err: (e as Error).name + ': ' + (e as Error).message } }
  4. }
  5. // const want = run(() => upstream(a, b, c, cleanup))
  6. // expect(run(() => port(a, b, c, cleanup)), `case ${n}`).toEqual(want)
复制代码

根因在随机输入生成器。一个 emoji 在 JS 字符串里占两个 UTF-16 码元,生成器按码元切字符串,把 emoji 从中间切开,留下孤立代理项。fast-diff 假定输入是合法 Unicode 字符串,所以这不是移植 bug,而是上游遇到非法输入时的原有行为。Skill 里有一条规矩:不要顺手修上游的怪行为。移植版保持和上游一致,这个行为写进 README 的已知限制。

之后差分拆成两组。合法输入按完整字符切,要求输出完全一致,且原包一次都不能抛异常;专门按码元切的那组,只要求两边失败方式相同。5000 次调用里原包失败了 126 次,移植版在同样输入上也失败。

上游 test.js 换了 6 个随机种子各跑一次,都通过。它覆盖 7 组回归用例、两轮各 10000 次随机模糊测试、72 条光标用例,每条光标用例再派生 6 种变体,另外还有 emoji 用例和语义整理。原包差分用了 DNA 序列、带换行英文、emoji、中英混排四种字母表,每种 2500 对输入,cleanup 开关各跑一次,共 20000 次调用,结果逐项一致。

测试全绿还不够,还要确认它们真能抓到错。突变测试故意改坏两处:把语义整理里的 score >= bestScore 改成 >,以及删掉计算公共前缀时防止把 emoji 切成两半的那一步。两处都被测试抓到,改回去恢复全绿。这一步后来成为闸门 G4b。

六、调用方验证和设备边界

HAR 自己能编译,只能说明库内部合法;别的 ArkTS 模块按正常写法调用它行不行,是另一回事。编译生成的类型声明文件里,diff.INSERT 会变成 declare namespace diff { var INSERT: number };CursorInfo 这种联合类型参数,调用方传对象字面量时必须用导出的 interface 标注类型。因此又加了一个最小 entry 模块,把每个导出都调用一遍,diff.INSERT 也读一次。这一步成为闸门 G1b。

设备验证没做成。本机 HarmonyOS 7.0 模拟器一开始因 /dev/kvm 权限问题起不来;处理完能启动后,两次冷启动都在 72 秒左右出事:系统核心服务 foundation 崩溃,系统 panic 重启,hdc list targets 一直查不到设备。entry 里已经写好方舟上的自检:先在电脑上用 npm 原包对 400 条固定输入算好结果,打包进应用后逐条比对,再按上游 test.js 的规则校验 3000 次随机 diff。这段代码编译过了,但没在方舟运行时上跑过。所以文章里的“通过”,只限于电脑上的测试和编译层面,不能等同于 ArkTS 运行时验证。

七、这套方法能复用什么

v2 一共改了 11 处,完整清单在仓库的 references/changelog.md。最管用的是顺序:查重放在挑库阶段,差分管道放在第一次编译之前,编译一过马上知道行为对不对;不要顺手修上游,否则移植版和原包输出对不上,差分反而变红。

需要人判断的地方也不少:挑哪个库、栈溢出到底是生成器问题还是移植问题、diff.INSERT 留不留。这里选择保留 diff.INSERT 以保持 API 一致,同时另外导出 DIFF_INSERT 常量。包名定成 @lwcwam/fast-diff,还没发布到 ohpm,当前只能按本地路径引用。Skill 也只在两个纯算法库上用过,碰到依赖 Buffer、正则后行断言或大量动态属性的库,估计还要再改一轮。

仓库在 https://atomgit.com/lwcwam/fast-diff-arkts,Skill 位于 skills/harmony-js-lib-port 目录,每道闸门的命令和结果记录在 docs/VERIFY.md。
回复

使用道具 举报

发表于 8 小时前 | 显示全部楼层

Re: ArkTS 移植 fast-diff:严格模式编译与差分验

这篇复盘很有参考价值,尤其是“先直译、再按报错改”和“差分测试要比较结果或异常”这两点,把移植里容易凭感觉改代码的问题讲透了。探针文件发现 codelinter 不能替代编译、emoji 那组栈溢出其实是上游对非法输入的原行为,这两个细节很关键,也说明差分测试本身要先保证输入合法。感觉“每多改一处就多一处要靠差分兜底”很实在。想请教后续会不会把探针文件和随机输入合法性检查固化进 Skill,作为固定闸门?感谢分享。
回复 支持 反对

使用道具 举报

发表于 8 小时前 | 显示全部楼层

Re: ArkTS 移植 fast-diff:严格模式编译与差分验

这个复盘很实用。我觉得最有价值的是把“编译通过”和“语义一致”拆开:先用上游测试证明测试管道本身没问题,再用差分测试兜底移植代码。探针文件那段提醒也很关键,编译器没报的写法不要为了“看起来像 ArkTS”去改,codelinter 也不能当 ArkTS 语法闸门。 关于 emoji 孤立代理项那组,建议在差分用例里把输入合法性单独标记,异常也按 run() 的结果比对,并在报告里注明这是上游遇到非法输入时的既有行为,避免后来人误以为是移植回归。脚手架先替换占位符、后复制模板这种顺序问题,确实只有完整跑一遍才会暴露。想问一下,第 4 步改成先直译、后按报错改之后,探针文件是保留为回归检查,还是每次移植都重新生成?
回复 支持 反对

使用道具 举报

发表于 8 小时前 | 显示全部楼层

Re: ArkTS 移植 fast-diff:严格模式编译与差分验

这套复盘很有价值,尤其把“语义一致优先”和“先直译、按报错改”讲得很清楚。我比较认同 codelinter 只能作补充闸门这一点,编译器和探针文件才是硬约束。差分测试用 run 包住两边、比较结果或异常也很关键,否则容易把上游原有的栈溢出误判成移植问题。 有个小疑问:既然 emoji 那组是随机生成器按 UTF-16 码元切出孤立代理项触发的,后面会不会把生成器改成按码点生成合法字符串,同时单独保留一组非法输入用例?这样正常路径和异常路径都能覆盖。另外探针文件如果固定下来当回归用例,后续工具链升级时应该挺有用。 整体流程闸门的思路很实用,感谢分享。
回复 支持 反对

使用道具 举报

您需要登录后才可以回帖 登录 | 注册

本版积分规则

指导单位

江苏省公安厅

江苏省通信管理局

浙江省台州刑侦支队

DEFCON GROUP 86025

Hacking Group 021A

旗下站点

态势感知中心

应急响应中心

红盟安全

联系我们

官方QQ群:112851260

官方邮箱:security#ihonker.org(#改成@)

官方核心成员

关注微信公众号

Archiver|手机版|小黑屋| ( 沪ICP备2021026908号 )

GMT+8, 2026-11-17 08:49 , Processed in 0.028209 second(s), 18 queries , Gzip On, Redis On.

Powered by ihonker.com

Copyright © 2015-现在.

  • 返回顶部