t1k:cocos:migration:tsc-validate

Field	Value
Module	`migration`
Version	`0.3.0`
Effort	`medium`
Tools	—

Keywords: cocos, gate, migration, tsc, type check, validate

How to invoke

/t1k:cocos:migration:tsc-validate

When to use

Sau t1k-cocos-migration-js2ts (sinh .cv.ts), TRƯỚC t1k-cocos-migration-uuid-verify attach. Bắt lỗi type/syntax sớm.

Pipeline: dep-graph → js2ts → **tsc-validate** → uuid-verify(attach).

Vì sao pin version TS khớp editor bundle (không dùng tsc cài sẵn)

Cocos Creator editor compile .ts bằng TypeScript bundled của chính editor (Cocos 2.4.x = TS 4.1.3; đã xác định qua dấu hiệu output: cc._RF.push/var X = require()/hậu tố _1 = TSC output, không phải Babel — Babel chỉ dùng cho .js). tsc 5.x cài máy có thể pass/fail KHÁC editor → validate sai. Skill pin version qua scripts/package.json (dependencies.typescript) để khớp — đổi giá trị này nếu editor của bạn bundle bản khác. Header output in ts.version thực tế để xác nhận.

⚠️ Đây là gate NÔNG (giới hạn quan trọng)

tsc --noEmit EXIT=0 KHÔNG đảm bảo editor compile được component. Đã chứng minh: một .cv.ts có thể pass tsc sạch nhưng editor vẫn fail (do .meta isPlugin:true → editor bỏ qua, KHÔNG sinh library/imports/<uuid>.js). tsc chỉ thấy type/syntax, KHÔNG thấy flag .meta / registration / library.

→ Luôn cặp với editor-compile-verify (lệnh verify trong t1k-cocos-migration-uuid-verify): sau attach + reload editor, kiểm tra library/imports/<ts-uuid>.js có sinh không. Đó mới là gate đáng tin cho “editor compile được”.

Usage

# (lần đầu) cài TS khớp editor:
cd .claude/skills/t1k-cocos-migration-tsc-validate/scripts && npm install && cd -

# Validate TẤT CẢ .cv.ts:
node .claude/skills/t1k-cocos-migration-tsc-validate/scripts/tsc-validate.cjs

# Validate file cụ thể (closure import tự kéo qua type-resolve):
node .claude/skills/t1k-cocos-migration-tsc-validate/scripts/tsc-validate.cjs <scriptRoot>/<Path>/<Component>.cv.ts

Flags: --project <tsconfig.json> · --script-root <p> · --post-cutover (sau cutover: lọc report về .ts).

Đường dẫn (project=tsconfig, script-root) lấy từ .claude/cocos-migrate.json (key tsconfig + scriptRoot; SSOT dùng chung, KHÔNG hardcode); CLI flag > config > fallback. Xem t1k-cocos-migration-migrate § Config.

Exit + phân loại lỗi:

2 = có SYNTAX error (TS1xxx) — BLOCKING. Editor sẽ “Error on compiling script”. Phải fix trước attach.
0 = PASS gate (0 syntax error). Type residual (TS2xxx: TS2339/2322/2554…) chỉ là checklist any-safe, KHÔNG chặn attach — editor VẪN emit library/imports/<uuid>.js dù có type-error. Để type-hardening pass xử sau.

Cơ chế

File list = các .cv.ts target + toàn bộ ambient .d.ts (types/*.d.ts gồm globals/cc-ext/node-ext/engine-ext + creator.d.ts). Ambient .d.ts PHẢI nằm trong file list mới vào global scope (nếu không → loạt Cannot find name 'user'/cc.* does not exist).
compilerOptions khớp editor: module=commonjs, target=es5, experimentalDecorators, allowJs, skipLibCheck, noEmit, moduleResolution=node (đọc từ project tsconfig).
Chỉ báo lỗi của file .cv.ts target (lọc bỏ lỗi engine/.d.ts/file khác).

Gotchas

Chạy npm install 1 lần trong scripts/ để có typescript đúng version. Thiếu → script throw Cannot find module typescript.
Thiếu ambient .d.ts → bùng nổ Cannot find name/cc.X does not exist (false positive). Skill tự gom types/*.d.ts + creator.d.ts; regenerate .d.ts (qua t1k-cocos-migration-js2ts generators) sau mỗi dep-graph re-run.
Gate NÔNG — pass ≠ editor compile. BẮT BUỘC cặp editor-compile-verify. Xem ## ⚠️ trên.
Lỗi có sẵn trong file .ts ngoài scope (vd TS1068 trong file pre-existing) đã được lọc, không ảnh hưởng kết quả .cv.ts.