AGENTS.md

1. Scope

This file is the repository-level guide for ets_frontend. It is primarily a routing index into the knowledge-base documents under docs/.

This repository implements the frontend compiler toolchain for ARK bytecode generation. Runtime execution semantics also depend on companion runtime repositories.

2. High-Risk Boundaries

• es2panda is the ArkTS-Dyn / JS / TS dynamic compiler route
• ets2panda is the C++-implemented ArkTS-Sta static compiler route
• do not assume a fix, rule, or architecture pattern from one route applies to the other
• in ets2panda, binder and checker must not rewrite AST structure; structural changes belong in lowering
• do not treat runtime behavior as fully defined by this repository alone
• compiler implementation must stay consistent with the language syntax spec; the spec documents generally live in the companion runtime_core repository
• if a change may alter generated bytecode, treat it as high-risk and notify the user before proceeding
• ets2panda/public/, bindings, .abc merge, protobuf layout, arkguard, and legacy_bin are compatibility-sensitive
• do not hand-edit generated files; update templates, schema, IDL inputs, or other source-of-truth files instead

Ask before:

• changing ets2panda/public/ interfaces or binding surfaces
• changing protobuf schema, serialization layout, or .abc compatibility behavior
• adding a new dependency
• deleting compatibility shims or legacy-bin behavior
• running destructive or environment-affecting commands outside the sandbox

3. Knowledge Routing

Before planning or editing:

• determine the compiler route: es2panda, ets2panda, or repo-level
• read the matching knowledge-base document below

In the plan, state: compiler route, task category, documents read, constraints found, and whether additional human guidance is required.

Task routing

Task type	Read
dynamic compiler behavior, JS/TS parsing, transformer, tsc-adjacent work	docs/ES2Panda_Knowledge_Base.md
static compiler behavior, checker, lowering, verifier/runtime-facing compile output, CTS failure	docs/ets2panda/Static_Frontend_Knowledge_Base.md
public API, SDK-facing frontend API, bindings surface	docs/ets2panda/Public_Knowledge_Base.md
obfuscation, rename behavior, source transformation, DevEco integration	docs/ArkGuard_Knowledge_Base.md
.abc, bytecode merge, protobuf, serialization	the route KB most closely related to the changed code; treat compatibility as high-risk

Vocabulary routing

Terms	Read / Action
ArkTS-Dyn, JS/TS, transformer, tsc	docs/ES2Panda_Knowledge_Base.md
ArkTS-Sta, checker, lowering, type relation, CTS, recheck, astcheck	docs/ets2panda/Static_Frontend_Knowledge_Base.md
public API, SDK, bindings, IDL	docs/ets2panda/Public_Knowledge_Base.md
.abc, bytecode, merge, protobuf	the route KB most closely related to the changed area
linter, easytrans, migration helper	docs/Linter_Knowledge_Base.md
obfuscation, rename, source map, name cache	docs/ArkGuard_Knowledge_Base.md
generated, template, .erb, protobuf	edit the source of truth, not generated output

4. Verification

Minimum requirements:

• build the affected area, or explain why you could not
• run focused tests near the changed area, or explain why you could not
• for compatibility-sensitive changes, run the closest regression available or state the gap explicitly

Task-specific expectations:

Change type	Build / tests to run	Read
es2panda parser/lexer/binder/compiler change	build: ./build.sh --product-name rk3568 --build-target ets_frontend_build; run targeted python3 es2panda/test/runner.py --parser <build_dir>, --compiler <build_dir>, --bytecode <build_dir>, --tsc <build_dir>, or --patch <build_dir> as applicable	docs/ES2Panda_Knowledge_Base.md
ets2panda parser change	run parser suite under ets2panda/test/ast/parser/; also run runtime_core/static_core/tests/tests-u-runner-2/runner.sh es2panda-verifier astchecker --extension=ets --load-runtimes=ets --force-generate --processes=all when parser output may affect AST validity	docs/ets2panda/Static_Frontend_Knowledge_Base.md
ets2panda checker change	run runtime_core/static_core/tests/tests-u-runner-2/runner.sh es2panda-verifier astchecker --extension=ets --load-runtimes=ets --force-generate --processes=all; run affected ets2panda/test/runtime/ets/ tests; run cts/ when spec compliance is impacted	docs/ets2panda/Static_Frontend_Knowledge_Base.md
ets2panda lowering change	run ets2panda/test/unit/lowerings/; run affected ets2panda/test/runtime/ets/ tests	docs/ets2panda/Static_Frontend_Knowledge_Base.md
public API or binding change	public API: run test/unit/public/e2p_test_plugin* and ninja gen_api; bindings: run nearest ets2panda/bindings/test; if src/lsp/* or LSP/public interfaces changed, also run ets2panda/test/unit/lsp/	docs/ets2panda/Public_Knowledge_Base.md, docs/ets2panda/Bindings_Knowledge_Base.md, docs/ets2panda/LSP_Knowledge_Base.md
.abc / protobuf / merge behavior change	run the closest route-specific bytecode / merge regression; for es2panda, prefer python3 es2panda/test/runner.py --bytecode <build_dir>; call out compatibility risk explicitly in the final report	the route KB most closely related to the changed area
arkguard change	run npm run test:ut; run the nearest cases from arkguard/test/ut/arkobfuscator/ArkObfuscator.spec.ts, arkguard/test/ut/initialization/ConfigResolver.spec.ts, arkguard/test/ut/initialization/ConfigResolver-hsp.spec.ts, arkguard/test/ut/transformer/RenameIdentifierTransformer.spec.ts, arkguard/test/ut/transformer/RenamePropertiesTransformer.spec.ts, arkguard/test/ut/utils/ApiExtractor.spec.ts, arkguard/test/ut/utils/ApiReader.spec.ts, and arkguard/test/ut/utils/NodeUtils.spec.ts as applicable	docs/ArkGuard_Knowledge_Base.md
test-only change	run the changed test file and at least one nearby related test in the same suite or directory	the KB that routes to the changed test area

5. Done Definition

A task is done only when:

• the requested behavior is implemented
• relevant validation has been run, or the limitation is explicitly stated
• the final response includes summary, files changed, validation result, and remaining risks
• compatibility or runtime/verifier impact is called out when relevant