t1k:cocos:base:tsc-validate

Field	Value
Module	`base`
Version	`1.14.0`
Effort	`medium`
Tools	—

Keywords: cocos, gate, js2ts, migration, tsc, type-check, typescript, validate

How to invoke

/t1k:cocos:base:tsc-validate

When to use

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

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

Vì sao pin TS 4.1.3 (không dùng tsc cài sẵn)

Cocos Creator 2.4.15 editor compile .ts bằng TypeScript 4.1.3 bundled (đã xác định: 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 chính xác typescript@4.1.3 để khớp.

⚠️ Đâ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: MapPage.cv.ts 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-base-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 4.1.3:
cd .claude/skills/t1k-cocos-base-tsc-validate && npm install && cd -

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

# Validate file cụ thể (closure import tự kéo qua type-resolve):
node .claude/skills/t1k-cocos-base-tsc-validate/scripts/tsc-validate.cjs Client/assets/script/scripts/MapPage.cv.ts

Flags: --project <tsconfig.json> · --script-root <p>.

Đườ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-base-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 (đã chứng minh: MapPage.cv có library entry dù 35 TS2339). Để type-hardening pass (§12) 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.
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 thư mục skill để có typescript@4.1.3. 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-base-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.
1 lỗi có sẵn HotUpdate.ts (TS1068) nằm ngoài .cv.ts → đã lọc, không ảnh hưởng kết quả.