t1k:cocos:base:tsc-validate

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

Keywords: gate, tsc, type-check

How to invoke

/t1k:cocos:base:tsc-validate

Executed by

Running the gate and classifying its output is mechanical; only the follow-up judgment stays on a reasoning tier (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”):

Step	Agent
Run `tsc-validate.cjs` and classify each reported diagnostic by its stated rule (`TS1xxx` → BLOCKING exit 2, `TS2xxx`/other → non-blocking residual)	`t1k-list-classifier`
Diagnose WHY a specific `TS2xxx` residual exists, or why a file that passes tsc still fails editor compile (the § “gate NÔNG” trap)	`t1k-debugger` — reasoning tier, not cheap
Decide whether to proceed to `uuid-verify attach` given the residual set, or fix first	stays with the orchestrating skill/user — a judgment call, not a rubric

The rule is closed-form (two TS-code prefixes, two outcomes), so applying it to a diagnostic list needs no reasoning tier. The moment the question becomes “is this specific residual safe to ship” or “why does the editor disagree with tsc”, that is causal reasoning about one file’s semantics, not rubric application, and belongs on t1k-debugger instead.

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 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: 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 đúng version pin:
cd .claude/skills/t1k-cocos-base-tsc-validate/scripts && 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 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-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ả.