cts-dev

# CTS开发修复技能 本技能提供ArkTS前端编译器(ets2panda)CTS测试用例修复的完整开发流程，涵盖问题定位、代码修改、测试验证和上库标准。 ## 前置技能：Spec分析 **当处理CTS用例失败时，必须先使用 `spec-test-analyzer` 技能**，对失败用例进行spec规则召回和差异分析，生成「CTS缺陷Spec分析报告」。 本技能的修复工作基于该报告进行： 1. 报告中的「责任模块判定」→ 确定修改哪个模块 2. 报告中的「Spec与编译器行为差异分析」→ 理解根因 3. 报告中的「补充测试场景」→ 确保修复覆盖边界条件 4. 报告中的「Spec原文」→ 修复依据（spec-first原则） 如果尚未生成Spec分析报告，请先触发 `spec-test-analyzer` 技能。 ## 重要约定 - **项目根目录**: 包含`runtime_core/`和`ets_frontend/`的目录（脚本自动检测，也可通过`ARK_ROOT_DIR`环境变量指定） - **编译器代码路径**: `ets_frontend/ets2panda`（不是`ets_frontend/es2panda`） - **涉及仓库**: `ets_frontend` 和 `runtime_core` - **编译命令执行路径**: `runtime_core/static_core/` - **构建目标**: `es2panda` - **构建目录**: 自动检测（优先级：`ARK_BUILD_DIR`环境变量 > `build_release` > `out`） - **脚本位置**: 所有脚本使用绝对路径，通过`common.sh`自动检测项目根目录，**可在任意目录执行** ### 环境变量 | 变量 | 说明 | 示例 | |------|------|------| | `ARK_ROOT_DIR` | 项目根目录（含runtime_core/和ets_frontend/） | `/home/user/arkcompile` | | `ARK_BUILD_DIR` | 构建输出目录（绝对路径） | `/home/user/arkcompile/runtime_core/static_core/out` | ### 编译模式 所有编译命令在 `runtime_core/static_core/` 目录下执行： ```bash # Release模式 cmake -B out -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=./cmake/toolchain/host_clang_default.cmake -GNinja . && cmake --build out # Debug模式 cmake -B out -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=./cmake/toolchain/host_clang_default.cmake -GNinja . && cmake --build out # Debug-ASAN模式 cmake -B cmake-build-debug -DPANDA_ENABLE_ADDRESS_SANITIZER=true -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=./cmake/toolchain/host_clang_default.cmake -GNinja . ``` ## 关键目录 | 路径 | 说明 | |------|------| | `ets_frontend/ets2panda` | 编译器实现代码 | | `ets_frontend/ets2panda/test/` | 编译器测试用例（ast/compiler/ets/） | | `runtime_core/static_core/` | 测试命令执行根目录、编译根目录 | | `runtime_core/static_core/plugins/ets/tests/ets-templates/` | CTS测试用例模板 | | `runtime_core/static_core/plugins/ets/doc/spec/` | ArkTS语言规范文档 | | `runtime_core/static_core/tests/tests-u-runner/` | 测试运行器 | | `mktemp` 生成的临时目录 | 当前运行渲染后的CTS用例代码目录（由 `runtime.sh` 自动创建和清理） | ## 开发流程 ### 阶段零：准备基线（异步后台） 后台异步执行CTS全量测试保存基线结果，后续回归验证时对比： ```bash SCRIPTS_DIR="...scripts目录绝对路径..." $SCRIPTS_DIR/cts2.sh > baseline.txt 2>&1 & ``` ### 阶段一：Spec分析（前置，由spec-test-analyzer执行） > 本步骤由 `spec-test-analyzer` 技能完成，不在此技能内执行。 > 如果用户直接提供了失败用例但未附带Spec分析报告，应先触发 `spec-test-analyzer` 生成报告。 输入：失败的CTS用例 + 错误信息 输出：**CTS缺陷Spec分析报告**（包含spec规则召回、行为差异分析、责任模块判定） ### 阶段二：问题定位与修复 1. **阅读Spec分析报告**: 获取 `spec-test-analyzer` 输出的CTS缺陷Spec分析报告，重点关注： - 「责任模块判定」→ 确定是parser/checker/lowering中的哪个模块 - 「Spec与编译器行为差异分析」→ 理解期望行为vs实际行为的gap - 「建议修复方向」→ 获取修复思路 2. **复现问题**: 使用对应测试脚本运行失败用例，确认问题可复现 ```bash SCRIPTS_DIR="...scripts目录绝对路径..." # CTS测试用例（支持 --test-file 或 --filter） $SCRIPTS_DIR/cts2.sh --test-file <用例路径> $SCRIPTS_DIR/cts2.sh --filter "*17.experimental_features/13.adding_functionality_to_existing_types*" # astchecker测试 $SCRIPTS_DIR/astcheck.sh --test-file <用例路径> # recheck测试 $SCRIPTS_DIR/recheck.sh --test-file <用例路径> # 单元测试 $SCRIPTS_DIR/ut.sh --test-file <用例路径> ``` 3. **结合Spec报告定位根因**: 将Spec报告中的差异点映射到具体代码位置 - Parser差异 → 查看 `parser/ETSParser*.cpp` - Checker差异 → 查看 `checker/ETSAnalyzer*.cpp` 和 `checker/ets/*.cpp` - Lowering差异 → 查看 `compiler/lowering/ets/*Lowering.cpp` 4. **确定修改范围**: 明确需要修改的文件和函数，参考 `reference/architecture.md` 5. **修改代码**: 根据根因分析修改对应模块代码，严格遵循代码规范 6. **增量编译**: ```bash $SCRIPTS_DIR/build_diff.sh ``` 7. **确认目标用例通过**: 反复修改+编译+测试，直到所有目标用例通过 ### 阶段三：定向回归验证 确保修复的特定CTS子类用例全部通过（每步通过后才继续下一步）： ```bash SCRIPTS_DIR="...scripts目录绝对路径..." # 1. 目标CTS子类测试（如：adding_functionality_to_existing_types） $SCRIPTS_DIR/cts2.sh --filter "*17.experimental_features/13.adding_functionality_to_existing_types*" # 2. ets-runtime测试（约8分钟） $SCRIPTS_DIR/runtime.sh # 3. astchecker测试（约10分钟） $SCRIPTS_DIR/astcheck.sh ``` ### 阶段四：全量回归验证 按顺序执行全量回归测试： ```bash SCRIPTS_DIR="...scripts目录绝对路径..." # 1. CTS全量测试（约136分钟） $SCRIPTS_DIR/cts2.sh # 2. ets-func-tests（约30分钟） # 直接在 static_core 下执行 cd $ARK_ROOT_DIR/runtime_core/static_core tests/tests-u-runner/runner.sh --ets-func-tests --show-progress --build-dir out --processes=all # 3. parser测试（约8分钟） $SCRIPTS_DIR/parser.sh ``` ### 阶段五：代码格式检查 在项目根目录（`runtime_core/`和`ets_frontend/`同级目录）执行格式检查： ```bash SCRIPTS_DIR="...scripts目录绝对路径..." # 检查所有仓库的修改文件格式（默认检查ets_frontend和runtime_core） $SCRIPTS_DIR/format.sh # 只检查ets_frontend $SCRIPTS_DIR/format.sh --repo ets_frontend # 只检查runtime_core $SCRIPTS_DIR/format.sh --repo runtime_core # 检查最后一次提交的文件 $SCRIPTS_DIR/format.sh log # 检查最后一次提交，仅ets_frontend $SCRIPTS_DIR/format.sh --repo ets_frontend log ``` 根据检查结果修改代码，反复执行直到格式检查通过。 ### 阶段六：生成代码修改报告 所有测试通过后，生成代码修改报告（模板见下方）。 ## 测试脚本速查 所有脚本位于 `scripts/` 目录，**使用绝对路径，可在任意目录执行**。 所有脚本通过 `common.sh` 自动检测项目根目录（向上查找含`runtime_core/`和`ets_frontend/`的目录）。 | 脚本 | 用途 | 参数 | |------|------|------| | `build_diff.sh` | 增量编译es2panda | 无 | | `build.sh` | 全量编译 | 无 | | `install_build.sh` | 首次安装构建 | 无 | | `cts2.sh` | CTS测试 | `--test-file <路径>` 或 `--filter <模式>` | | `astcheck.sh` | astchecker测试 | `--test-file <路径>` | | `parser.sh` | parser测试 | `--test-file <路径>` | | `recheck.sh` | recheck测试 | `--test-file <路径>` | | `runtime.sh` | ets-runtime测试 | 无 | | `ut.sh` | 单元测试 | `--test-file <路径>` | | `declgen.sh` | 声明生成测试 | `--test-file <路径>` | | `runets.sh` | 编译运行单个ets文件 | `<文件路径>` | | `style.sh` | ninja clang-force-format | 无 | | `format.sh` | 代码格式检查（clang-format+clang-tidy） | `--repo <仓库>` `log` | | `all_with_build.sh` | 构建后运行全部测试 | 无 | | `test.sh` | 旧版全套测试（含format） | 无 | | `common.sh` | 共享函数（自动检测路径） | （被其他脚本source） | ## 代码规范 ### 命名规范 - 新增函数命名不能过长 - 函数首个单词首字母大写，首个单词为动词（如`GetTypeFor...`、`Check...`、`Resolve...`） - 不能有魔术数字、魔术字符串，必须定义为命名常量 ### 复杂度规范 - 函数圈复杂度不超过10 - 代码缩进层级不超过5 - 单个函数不能超过49行 - 函数参数个数不超过5个 - 新增代码存在重复代码时要提取为函数 ### 模块约束 - **Checker**: 不改AST形状、不新建AST节点，仅修改语义元数据 - **Parser**: 仅做语法解析（token→AST），不报告语义错误 - **Lowering**: AST→AST变换，新建节点后必须re-bind/re-check - 详细模块约束见 `reference/architecture.md` ### 类型系统规则 - 使用`TypeRelation` API（`IsSupertypeOf`、`IsIdenticalTo`）进行类型逻辑判断 - 不硬编码类型名（如`"escompat.Record"`），不用指针比较类型 - 不引入新的状态标志（`CheckerStatus`、`AstNodeFlags`等） - 不依赖`ToString()`稳定性做语义判断，应使用类型结构/TypeRelation ### 通用工程规范 - 不使用显式`new`/`delete`管理内存 - 优先使用文件级`static`/私有辅助函数，不膨胀公共接口 - 使用arena allocation管理编译器对象 - Linux和Windows文本文件编码格式可能不同，注意换行符差异导致的crash ## 验收标准 ### 必须通过项 - [ ] 修复命令中指定的所有失败用例均通过 - [ ] parser测试套无新增失败 - [ ] astchecker测试套无新增失败 - [ ] recheck测试套无新增失败 - [ ] ets-runtime测试套无新增失败 - [ ] CTS全量测试无回归（与基线对比无新增失败） - [ ] 编译构建无error无warning - [ ] 代码格式检查通过（format.sh） ### 代码质量项 - [ ] 圈复杂度 ≤ 10 - [ ] 函数行数 ≤ 49行 - [ ] 缩进层级 ≤ 5 - [ ] 无魔术数字/字符串 - [ ] 无冗余/重复代码 - [ ] 符合命名规范 ### Spec一致性项 - [ ] 行为符合最新技术预览规范（spec-first） - [ ] 不引入spec之外的行为 - [ ] 不移除现有assertion ## 上库标准 ### Commit Message格式 ``` [CTS] 简短描述（首行不超过50字符） Issue: https://gitcode.com/openharmony/arkcompiler_runtime_core/issues/<编号> Co-Authored-By: Agent Signed-off-by: <姓名> <邮箱> ``` - 首行和正文之间有空行 - 首行字符数不超过50 - 关联Issue链接 ### 必须包含 - 修复行为的对应测试用例 - spec规范依据（如涉及） - 代码修改报告 ## 代码修改报告 每次修复完成后，必须生成代码修改报告。报告中"Spec依据"部分应引用 `spec-test-analyzer` 输出的CTS缺陷Spec分析报告中的具体spec章节和规则。 模板如下： ```markdown # 代码修改报告 ## 一、问题根因分析 ### 1.1 问题描述 <!-- 描述CTS测试失败的现象：哪个用例、什么错误信息 --> ### 1.2 根因定位 <!-- 定位到具体模块（parser/checker/lowering）和具体函数/文件 --> - **涉及模块**: - **根因文件**: - **根因函数**: - **根因类型**: （逻辑错误 / 缺失功能 / 边界条件未处理 / spec实现不一致） ### 1.3 根因详细分析 <!-- 解释为什么会产生这个问题，从spec或编译器架构角度分析 --> ## 二、架构设计 ### 2.1 修改方案 <!-- 描述修复方案的设计思路 --> ### 2.2 修改文件列表 | 文件路径 | 修改类型 | 说明 | |----------|----------|------| | | 新增/修改/删除 | | ### 2.3 模块影响分析 - **Parser影响**: - **Checker影响**: - **Lowering影响**: - **其他模块影响**: ### 2.4 新增函数说明 | 函数签名 | 所在文件 | 职责 | |----------|----------|------| | | | | ## 三、影响范围 ### 3.1 功能影响 <!-- 本次修改影响哪些语言特性/语法规则 --> ### 3.2 测试影响 - **新增测试用例**: - **修改测试用例**: - **预期影响的CTS章节**: ### 3.3 兼容性影响 <!-- 是否影响已有代码的编译行为 --> ### 3.4 回归测试结果 | 测试套 | 修复前结果 | 修复后结果 | 是否有回归 | |--------|-----------|-----------|-----------| | parser | | | | | astchecker | | | | | recheck | | | | | ets-runtime | | | | | CTS全量 | | | | ## 四、Spec依据 <!-- 引用spec-test-analyzer输出的CTS缺陷Spec分析报告中的具体spec章节和规则 --> <!-- 包括：Spec章节编号、规则描述、原文引用 --> <!-- 来源报告路径：{spec-test-analyzer输出的报告路径} --> ``` ## 参考资源 - **前置技能**: [`../spec-test-analyzer/SKILL.md`](../spec-test-analyzer/SKILL.md) — Spec规则召回和分析，CTS修复的必经前置步骤 - **模块架构**: `reference/architecture.md` — checker/parser/lowering三大模块的详细架构知识 - **测试脚本**: `scripts/` — 所有可执行的测试和构建脚本（绝对路径，自动检测项目根目录）