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/ 目录下执行：

# 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全量测试保存基线结果，后续回归验证时对比：

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. 复现问题: 使用对应测试脚本运行失败用例，确认问题可复现

   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. 增量编译:

   $SCRIPTS_DIR/build_diff.sh
   

7. 确认目标用例通过: 反复修改+编译+测试，直到所有目标用例通过

阶段三：定向回归验证

确保修复的特定CTS子类用例全部通过（每步通过后才继续下一步）：

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

阶段四：全量回归验证

按顺序执行全量回归测试：

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/同级目录）执行格式检查：

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章节和规则。

模板如下：

# 代码修改报告

## 一、问题根因分析

### 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规则召回和分析，CTS修复的必经前置步骤
• 模块架构: reference/architecture.md — checker/parser/lowering三大模块的详细架构知识
• 测试脚本: scripts/ — 所有可执行的测试和构建脚本（绝对路径，自动检测项目根目录）
• 共享函数: scripts/common.sh — 路径自动检测逻辑（detect_root_dir、detect_build_dir）
• Spec规范: runtime_core/static_core/plugins/ets/doc/spec/ — ArkTS语言规范