Skip to content

t1k:cocos:base:tsc-validate

FieldValue
Modulebase
Version4.51.9
Effortmedium
Tools—

Keywords: gate, tsc, type-check

/t1k:cocos:base:tsc-validate

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

StepAgent
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 firststays 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.

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)

Section titled “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.

Ngoại lệ TSRS: yêu cầu typecheck TSRS toàn studio (cho TypeScript web/none) KHÔNG áp dụng cho dự án Cocos Creator. TSRS nhắm TypeScript 7.1 nên không tái hiện được compiler mà editor đóng gói; một checker “bare” sẽ cho kết quả xanh giả. Giữ nguyên gate này (tsc-validate; trong module playable: tsc-gate.sh, tsc-baseline.cjs, tsconfig.typecheck.json), không thay bằng tsrs.

Skill này sinh ra cho 2.4.x (TS 4.1.3, .cv.ts, Client/tsconfig.json). Với Cocos Creator 3.x:

  • Layout: không có .cv.ts/Client/; tsconfig.json nằm ở root project. Script tự nhận layout này (không có Client/tsconfig.json + không có .claude/cocos-migrate.json, có ./tsconfig.json) → project=tsconfig.json, script-root=assets, target .ts; in dòng layout Cocos 3.x tự nhận. Hoặc truyền tường minh: --project tsconfig.json --script-root assets --post-cutover.
  • Compiler: editor 3.8.7 bundle hai TypeScript — 4.9.5 (resources/resources/3d/engine/node_modules/typescript) và 5.8.2 (resources/app.asar.unpacked/node_modules/typescript). Kit chưa xác định cái nào compile assets/ (cần kiểm trên editor thật) nên KHÔNG pin giá trị cho 3.x. Cách làm: trỏ gate vào từng bản bằng --typescript <thư-mục-package-typescript> (header in TS x.y.z để xác nhận) và so kết quả; đường dẫn bundle lấy từ thư mục cài editor của bạn.
  • Gate vẫn NÔNG: pass ≠ editor compile — xác nhận bằng editor (library entry), như dưới.

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

Section titled “⚠️ Đâ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”.

Terminal window
# (lần đầu) cài TS đúng version pin:
cd .claude/skills/t1k-cocos-base-tsc-validate/scripts && bun install && cd -
# Validate TẤT CẢ .cv.ts:
bun .claude/skills/t1k-cocos-base-tsc-validate/scripts/tsc-validate.cjs
# Validate file cụ thể (closure import tự kéo qua type-resolve):
bun .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> · --typescript <dir> · --post-cutover.

Đườ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.

Luôn chạy script pin, KHÔNG DÙNG bunx tsc thay thế. Script in header TS ${ts.version} xác nhận compiler ĐÚNG version (pin 4.1.3) đã chạy. Bare bunx tsc không in version line và trong project không có typescript dependency có thể báo “0 errors” mà không chạy gì (#509) — một kết quả 0-error chỉ đáng tin khi bạn thấy version line.

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.
  • 2 = UNVERIFIABLE khi 0 target, hoặc có target KHÔNG nằm trong program của tsconfig (include/files bỏ sót, gõ sai path): file đó không được compile nên không có diag nào để lọc — trước đây đọc thành PASS (#1903). Sửa tsconfig hoặc path.
  • 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.
  • 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).
  1. Chạy bun install 1 lần trong scripts/ để có typescript đúng version. Thiếu → script throw Cannot find module typescript.

  2. 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.

  3. Gate NÔNG — pass ≠ editor compile. BẮT BUỘC cặp editor-compile-verify. Xem ## ⚠️ trên.

  4. 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ả.

  5. Báo 0 lỗi từ bunx tsc là KHÔNG đáng tin khi project không có typescript dependency (#509). Khi agent bỏ qua script pin và chạy bunx tsc thay thế, npx shim có thể in “0 errors” mà không chạy compiler nào cả — false PASS kết thúc investigation sớm. Script của skill đã an toàn (require typescript từ scripts/node_modules, throw nếu thiếu), nhưng khi thấy kết quả 0 lỗi, luôn xác nhận compiler THỰC SỰ chạy — script in TS ${ts.version} ở header; bare bunx tsc không có equivalent. Nếu dùng bunx tsc và không thấy version line, kết quả là evidence của không gì cả.

  6. Cocos 3.x typecheck: npx tsc + types: ["node"] có thể cho false 0-error. npx tsc có thể chạy một package KHÔNG phải compiler (không phải typescript). Ngoài ra nếu tsconfig khai "types": ["node"] mà project không cài @types/node, tsc báo TS2688 (Cannot find type definition file) và bỏ qua semantic check — kết quả “0 error” là xanh giả. Cách làm: chạy tsc của editor-bundled TypeScript (xem § Cocos 3.x, --typescript <dir>) với override --types "" (hoặc "types": []), và chỉ tin kết quả khi thấy header TS x.y.z cùng ít nhất một diagnostic semantic (TS2xxx) có thể tái hiện được trên file cố ý lỗi.

  • t1k-cocos-base-js2ts — sinh .cv.ts (chạy trước).
  • t1k-cocos-base-uuid-verify — attach + verify (gồm editor-compile-verify, chạy sau).
  • plans/reports/2026-05-29-js-to-ts-migration-brainstorm.md §6 — định nghĩa gate tsc-validate.