typescript-check

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript Type Check Skill

TypeScript类型检查技能

Operator Context

操作场景

This skill operates as an operator for TypeScript type validation, configuring Claude's behavior for running

tsc --noEmit

and parsing output into structured, actionable error reports. It implements a Linear Validation pattern -- locate config, execute compiler, parse output, present results.

本技能用于TypeScript类型验证，配置Claude执行

tsc --noEmit

并将输出解析为结构化的、可执行的错误报告。它采用线性验证模式——定位配置文件、执行编译器、解析输出、展示结果。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before running checks
Read-Only Validation: Report errors only; never modify source code unless explicitly requested
Complete Output: Always show full tsc output with file paths, line numbers, and error codes
Verify tsconfig.json First: Confirm tsconfig.json exists before running tsc
No Dependency Installation: Never run npm install, yarn add, or pnpm add

CLAUDE.md合规性: 运行检查前需阅读并遵循仓库中的CLAUDE.md
只读验证: 仅报告错误；除非明确请求，否则绝不修改源代码
完整输出: 始终显示包含文件路径、行号和错误代码的完整tsc输出
优先验证tsconfig.json: 运行tsc前需确认tsconfig.json存在
不安装依赖: 绝不运行npm install、yarn add或pnpm add命令

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

Parse Errors: Convert raw tsc output into structured, file-grouped format
Absolute Paths: Display absolute file paths for direct navigation
Group by File: Organize errors by source file, sorted by line number
Exit Code Reporting: Report PASS (exit 0) or FAIL (exit 1+) with error count
Error Code Inclusion: Include TS#### codes for each error

错误解析: 将原始tsc输出转换为结构化的、按文件分组的格式
绝对路径: 显示绝对文件路径以支持直接导航
按文件分组: 按源文件组织错误，并按行号排序
退出码报告: 报告PASS（退出码0）或FAIL（退出码1+）及错误数量
包含错误代码: 为每个错误添加TS####格式的错误代码

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，可开启）

--strict mode: Run with additional strict flags beyond tsconfig settings
--project path: Use a specific tsconfig.json when multiple exist
--skipLibCheck: Add --skipLibCheck to speed up checking on large projects
Specific files: Check only named files instead of entire project

--strict模式: 除tsconfig设置外，额外启用严格检查标志
--project路径: 当存在多个配置时，使用指定的tsconfig.json
--skipLibCheck: 添加该标志以加速大型项目的检查速度
指定文件: 仅检查指定文件而非整个项目

What This Skill CAN Do

本技能可实现的功能

Run TypeScript type checking on any project with tsconfig.json
Parse and format tsc error output into actionable, file-grouped reports
Detect missing type dependencies, bad imports, and configuration issues
Check specific files or the entire project
Report pass/fail status with structured error summaries

对任何包含tsconfig.json的项目运行TypeScript类型检查
将tsc错误输出解析并格式化为可执行的、按文件分组的报告
检测缺失的类型依赖、错误的导入及配置问题
检查指定文件或整个项目
以结构化错误摘要的形式报告通过/失败状态

What This Skill CANNOT Do

本技能无法实现的功能

Auto-fix type errors (this is read-only validation)
Install dependencies or modify package.json
Modify tsconfig.json or any project configuration
Run on projects without tsconfig.json
Execute tests or perform linting

自动修复类型错误（本技能为只读验证工具）
安装依赖或修改package.json
修改tsconfig.json或任何项目配置
在无tsconfig.json的项目中运行
执行测试或代码linting

Instructions

操作步骤

Step 1: Verify TypeScript Project

步骤1：验证TypeScript项目

Locate tsconfig.json in the project:

bash

ls tsconfig.json 2>/dev/null || ls */tsconfig.json 2>/dev/null

If no tsconfig.json exists, stop and inform the user. Do not proceed without configuration.

在项目中定位tsconfig.json：

bash

ls tsconfig.json 2>/dev/null || ls */tsconfig.json 2>/dev/null

若未找到tsconfig.json，需停止操作并告知用户。无配置文件时请勿继续。

Step 2: Run Type Check

步骤2：运行类型检查

Execute the TypeScript compiler in type-check-only mode:

bash

npx tsc --noEmit 2>&1

Capture the exit code:

Exit 0: No type errors found
Exit 1+: Type errors detected

以仅类型检查模式执行TypeScript编译器：

bash

npx tsc --noEmit 2>&1

捕获退出码：

退出码0: 未发现类型错误
退出码1+: 检测到类型错误

Step 3: Parse Output

步骤3：解析输出

For each error line in the tsc output, extract:

File path: The .ts/.tsx file containing the error
Line:Column: Exact location in the file
Error code: TS#### identifier (e.g., TS2322, TS7006)
Message: Human-readable error description

针对tsc输出中的每一行错误，提取以下信息：

文件路径: 包含错误的.ts/.tsx文件
行号:列号: 错误在文件中的精确位置
错误代码: TS####格式的标识符（如TS2322、TS7006）
错误信息: 易于理解的错误描述

Step 4: Present Results

步骤4：展示结果

Format output using this structure:

=== TypeScript Type Check ===

Status: PASS / FAIL (N errors)

Errors by File:
---------------

src/components/Button.tsx
  Line 15:3  TS2322  Type 'string' is not assignable to type 'number'
  Line 28:10 TS2339  Property 'foo' does not exist on type 'Props'

src/utils/helpers.ts
  Line 5:1   TS7006  Parameter 'x' implicitly has an 'any' type

Summary: N files, M errors

使用以下结构格式化输出：

=== TypeScript类型检查结果 ===

状态: PASS / FAIL（共N个错误）

按文件分组的错误:
---------------

src/components/Button.tsx
  第15行第3列  TS2322  类型'string'不能赋值给类型'number'
  第28行第10列 TS2339  类型'Props'上不存在属性'foo'

src/utils/helpers.ts
  第5行第1列   TS7006  参数'x'隐式具有'any'类型

摘要: 涉及N个文件，共M个错误

Error Handling

错误处理

Error: "Cannot find tsconfig.json"

错误："Cannot find tsconfig.json"

Cause: No TypeScript configuration in the project root or specified path. Solution:

Search for tsconfig.json in common locations (src/, app/, packages/)
If found elsewhere, re-run with
```
--project path/to/tsconfig.json
```
If not found anywhere, inform user this requires a TypeScript project

原因：项目根目录或指定路径中无TypeScript配置文件。解决方案：

在常见位置（src/、app/、packages/）搜索tsconfig.json
若在其他位置找到，使用
```
--project path/to/tsconfig.json
```
重新运行
若未找到任何配置文件，告知用户本技能仅适用于TypeScript项目

Error: "Cannot find module 'typescript'"

错误："Cannot find module 'typescript'"

Cause: TypeScript is not installed as a project dependency. Solution:

Inform user that TypeScript must be installed first
Suggest
```
npm install typescript --save-dev
```
Do not install it automatically (read-only skill)

原因：TypeScript未作为项目依赖安装。解决方案：

告知用户需先安装TypeScript
建议执行
```
npm install typescript --save-dev
```
请勿自动安装（本技能为只读工具）

Error: "npx: command not found"

错误："npx: command not found"

Cause: Node.js toolchain is not installed or not in PATH. Solution:

Verify Node.js is installed:
```
node --version
```
If Node.js is present but npx missing, try
```
npm exec tsc -- --noEmit
```
If Node.js is missing, inform user to install Node.js

原因：未安装Node.js工具链或其未加入PATH环境变量。解决方案：

验证Node.js是否安装：
```
node --version
```
若已安装Node.js但缺少npx，尝试
```
npm exec tsc -- --noEmit
```
若未安装Node.js，告知用户需先安装Node.js

Anti-Patterns

反模式

Anti-Pattern 1: Running Without tsconfig.json

反模式1：无tsconfig.json时运行检查

What it looks like: Executing

npx tsc --noEmit

in a directory without tsconfig.json Why wrong: tsc falls back to default settings, missing project-specific configuration like paths, strict mode, and compiler targets Do instead: Always verify tsconfig.json exists in Step 1 before running

表现: 在无tsconfig.json的目录中执行

npx tsc --noEmit

问题: tsc会回退到默认设置，缺失项目特有的配置（如路径、严格模式、编译目标） 正确做法: 始终在步骤1中先验证tsconfig.json存在后再运行检查

Anti-Pattern 2: Suppressing or Summarizing Output

反模式2：抑制或简化输出

What it looks like: Running

npx tsc --noEmit > /dev/null

or reporting only "5 errors found" Why wrong: Users need actual error messages, file paths, and line numbers to fix issues Do instead: Always show complete, structured error output

表现: 执行

npx tsc --noEmit > /dev/null

或仅报告"发现5个错误" 问题: 用户需要具体的错误信息、文件路径和行号才能修复问题 正确做法: 始终显示完整的、结构化的错误输出

Anti-Pattern 3: Auto-Fixing Without Explicit Request

反模式3：未明确请求时自动修复

What it looks like: Seeing a type error and immediately editing the source file Why wrong: Type check is a read-only validation step; user may want to review errors, may disagree with the fix approach, or may have a different solution in mind Do instead: Present errors clearly; only fix if user explicitly asks

表现: 发现类型错误后立即编辑源代码问题: 类型检查是只读验证步骤；用户可能需要先查看错误，或不认可修复方案，或有其他解决思路 正确做法: 清晰展示错误；仅在用户明确请求时进行修复

Anti-Pattern 4: Skipping Exit Code Check

反模式4：跳过退出码检查

What it looks like: Parsing output text without checking the tsc exit code Why wrong: tsc may produce warnings that look like errors, or errors may be incomplete if the process was killed Do instead: Always capture and report the exit code alongside parsed output

表现: 仅解析输出文本而不检查tsc的退出码问题: tsc可能会生成类似错误的警告，或进程被终止导致输出不完整 正确做法: 始终捕获并报告退出码，同时展示解析后的输出

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks

本技能采用以下共享模式：

反合理化 - 避免捷径式的合理化解释
验证清单 - 完成前的检查步骤

Common tsc Flags

常用tsc标志

Flag	Purpose
`--noEmit`	Type check only, do not generate .js files
`--project path`	Use specific tsconfig.json
`--skipLibCheck`	Skip type checking .d.ts files (faster)
`--incremental`	Use incremental compilation (faster for repeat runs)
`--strict`	Enable all strict type checks

标志	用途
`--noEmit`	仅执行类型检查，不生成.js文件
`--project path`	使用指定的tsconfig.json
`--skipLibCheck`	跳过.d.ts文件的类型检查（更快）
`--incremental`	使用增量编译（重复运行时更快）
`--strict`	启用所有严格类型检查

Integration Points

集成场景

Before git-commit-flow: Run type check before committing TypeScript changes
With vitest-runner: Run type check first, then tests
With code-linting: Run lint first, then type check

git-commit-flow之前: 提交TypeScript代码变更前运行类型检查
与vitest-runner配合: 先运行类型检查，再执行测试
与代码linting配合: 先运行lint，再执行类型检查