tsconfig-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

tsconfig Audit

tsconfig 审计

Purpose

目的

Report what a

tsconfig.json

should look like on TypeScript 7:

Options and values TS7 rejects outright, with a migration for each
Options that are redundant — locked to one value, implied by another option, or equal to a default
Options that became load-bearing because a default changed, and must now be written explicitly
Options that look droppable but should be kept

报告

tsconfig.json

在TypeScript 7环境下的理想配置状态：

TypeScript 7直接拒绝的选项及对应值，并提供每个选项的迁移方案
冗余选项——被锁定为单一值、由其他选项隐含、或与默认值一致
因默认值变更而变为必需的选项，现在必须显式声明
看似可删除但应保留的选项

When to Use This Skill

使用场景

"Audit my tsconfig"
"What can I drop from tsconfig for TypeScript 7?"

"Is

baseUrl

esModuleInterop

downlevelIteration

still needed?"

"Prepare this config for the TS7 upgrade"
Before or during a TypeScript 6 → 7 upgrade

Trigger phrases: "tsconfig audit", "tsconfig cleanup", "TypeScript 7 migration", "compilerOptions", "drop tsconfig options".

"审计我的tsconfig"
"为了适配TypeScript 7，我可以从tsconfig中删除哪些内容？"

baseUrl

esModuleInterop

downlevelIteration

仍然需要吗？"

"为TS7升级准备此配置"
在TypeScript 6 → 7升级之前或期间

触发短语："tsconfig audit"、"tsconfig cleanup"、"TypeScript 7 migration"、"compilerOptions"、"drop tsconfig options"。

Scope

范围

This audits

compilerOptions

only.

include

exclude

files

are read to reason about

rootDir

, not audited. It does not touch dependency hygiene, lint config, or build scripts.

The target is always TypeScript 7. Advice for staying on 5.x or 6.x is out of scope — those configs are audited against what 7 will require of them.

仅审计

compilerOptions

。

include

exclude

files

仅用于推导

rootDir

，不进行审计。不涉及依赖卫生、lint配置或构建脚本。

目标始终是TypeScript 7。关于停留在5.x或6.x版本的建议不在范围内——这些配置会按照TS7的要求进行审计。

How It Works

工作原理

The compiler is the authority wherever it can answer, so the audit stays correct as TypeScript releases move:

Source	Answers
`tsc --noEmit` diagnostics	Removals ( `TS5102` / `TS5108` ), unknown options ( `TS5023` ), invalid values ( `TS6046` ), illegal combinations ( `TS5095` )
`tsc --showConfig`	Options implied by another option, and the fully resolved `extends` chain
`references/ts7-options.json`	Defaults, locked values, which unknown options are legacy removals rather than typos, keep-list

Two things the compiler will not tell you, which the script handles itself:

--showConfig
swallows config errors. It prints a config containing a removed option and exits 0. It is never used as a diagnostics source.
Diagnostics anchor to the leaf config, even when the option was inherited from a base inside
```
node_modules
```
. The script walks the
```
extends
```
chain itself to attribute each option to the file that really set it.

编译器是权威来源，因此审计结果会随TypeScript版本更新保持准确：

来源	可解答的问题
`tsc --noEmit` 诊断信息	需要移除的选项（ `TS5102` / `TS5108` ）、未知选项（ `TS5023` ）、无效值（ `TS6046` ）、非法组合（ `TS5095` ）
`tsc --showConfig`	由其他选项隐含的选项，以及完整解析的 `extends` 链
`references/ts7-options.json`	默认值、锁定值、哪些未知选项是已移除的旧选项而非拼写错误、保留列表

编译器无法告知的两件事，由脚本自行处理：

--showConfig
会忽略配置错误。它会打印包含已移除选项的配置并以0状态码退出。它永远不会作为诊断来源使用。
诊断信息锚定在叶子配置，即使选项是从
```
node_modules
```
中的基础配置继承而来。脚本会自行遍历
```
extends
```
链，将每个选项归因于实际设置它的文件。

Asking the User

询问用户

Every question in this skill is written as

AskUserQuestion

options. Use that tool where the host offers it, or the host's nearest structured-choice equivalent. Where the host has neither, ask the same question in normal chat as a numbered list of 2–5 options — recommended first, one short line of description each — and wait for the user to reply with a number.

本技能中的所有问题均以

AskUserQuestion

选项形式编写。如果宿主提供该工具，请使用它；或使用宿主最接近的结构化选择等效工具。如果宿主都不提供，则以普通聊天形式提出相同问题，列出2–5个选项的编号列表——推荐选项放在首位，每个选项配一行简短描述——然后等待用户回复编号。

Workflow

工作流程

Step 1: Find the configs

步骤1：查找配置文件

Unless the user named one, list the candidates before auditing anything:

bash

undefined

除非用户指定了某个配置文件，否则在审计前先列出候选文件：

bash

undefined

Glob: **/tsconfig*.json, excluding node_modules

全局匹配：**/tsconfig*.json，排除node_modules


A repo commonly has several — a root config plus build, site, test and benchmark variants, each
extending the root. Audit the one the user meant, and say which others exist rather than silently
auditing only the root. A config reached through `extends` is covered automatically as part of the
chain; a sibling config is not.


一个仓库通常有多个配置文件——根配置加上构建、站点、测试和基准测试变体，每个变体都继承根配置。审计用户指定的配置文件，并告知存在哪些其他配置文件，而非仅静默审计根配置。通过`extends`链关联的配置会自动被覆盖；同级配置则不会。

Step 2: Run the checker

步骤2：运行检查器

bash

node <skill-dir>/scripts/tsconfig-check.mjs [path/to/tsconfig.json]

Add

--json

for structured findings when you need to post-process them. Use

--tsc <path>

to point at a specific compiler.

The script needs a TypeScript compiler. It looks for

node_modules/.bin/tsc

upward from the config, then

tsgo

, then

tsc

PATH

. If none is found it stops rather than guessing — do not work around this by hand-reasoning about the config.

If the compiler found is older than 7.x, the script still runs and says so. Findings from the data file stay TS7-accurate, but removal and unknown-option findings come from the older compiler and will understate what TS7 rejects. Say this plainly in the report rather than presenting partial results as complete.

bash

node <skill-dir>/scripts/tsconfig-check.mjs [path/to/tsconfig.json]

当需要对结果进行后处理时，添加

--json

参数以获取结构化结果。使用

--tsc <path>

指向特定的编译器。

脚本需要TypeScript编译器。它会从配置文件向上查找

node_modules/.bin/tsc

，然后是

tsgo

，最后是

PATH

中的

tsc

。如果未找到任何编译器，脚本会停止运行，而非猜测——请勿手动推导配置来解决此问题。

如果找到的编译器版本早于7.x，脚本仍会运行并告知用户。数据文件中的结果仍保持TS7的准确性，但移除和未知选项的结果来自旧版本编译器，会低估TS7拒绝的内容。在报告中明确说明这一点，而非将部分结果呈现为完整结果。

Step 3: Read the findings

步骤3：读取检查结果

Each finding carries

option

action

reason

severity

confidence

sourceFile

and

editable

. With

--json

they arrive as a flat list — group them yourself; the grouping is a presentation choice, not part of the data:

json

{
  "option": "baseUrl",
  "value": "./src",
  "action": "remove",
  "reason": "removed-in-ts7",
  "severity": "error",
  "confidence": "high",
  "sourceFile": "tsconfig.json",
  "editable": true,
  "suggestion": "\"paths\": {\"*\": [\"./src/*\"]}"
}

Group them for the user by severity:

Blocking —
```
severity: error
```
. The build fails on TS7 until these are fixed.
Must add —
```
reason: conditional-add
```
. Nothing errors; the output silently moves or globals silently vanish. Explain the concrete consequence, not just the flag.
Safe to drop —
```
locked-value
```
,
```
implied-by
```
,
```
matches-default
```
.
Keep —
```
keep-list
```
,
```
external-consumer
```
.

Two flags change what you can offer:

```
editable: false
```
means the option lives outside the project (typically an
```
@tsconfig/*
```
base in
```
node_modules
```
). Never edit it. Offer a local override instead, and say which package owns it.
```
needsResearch: true
```
means TS7 reported an unknown option that is not a known legacy removal. Go to Step 4.

每个结果包含

option

、

action

、

reason

、

severity

、

confidence

、

sourceFile

和

editable

。使用

--json

参数时，结果会以扁平列表形式返回——自行分组；分组是展示选择，而非数据的一部分：

json

{
  "option": "baseUrl",
  "value": "./src",
  "action": "remove",
  "reason": "removed-in-ts7",
  "severity": "error",
  "confidence": "high",
  "sourceFile": "tsconfig.json",
  "editable": true,
  "suggestion": "\"paths\": {\"*\": [\"./src/*\"]}"
}

按严重程度为用户分组：

阻塞项 —
```
severity: error
```
。在修复这些问题之前，TS7环境下的构建会失败。
必须添加项 —
```
reason: conditional-add
```
。不会报错，但输出会静默变更或全局变量会消失。解释具体后果，而非仅说明标志。
可安全删除项 —
```
locked-value
```
、
```
implied-by
```
、
```
matches-default
```
。
需保留项 —
```
keep-list
```
、
```
external-consumer
```
。

两个标志会影响可提供的建议：

```
editable: false
```
表示选项位于项目外部（通常是
```
node_modules
```
中的
```
@tsconfig/*
```
基础配置）。请勿编辑它。建议使用本地覆盖，并说明哪个包拥有该配置。
```
needsResearch: true
```
表示TS7报告了一个未知选项，且该选项不是已知的已移除旧选项。进入步骤4。

Step 4: Research unknown options

步骤4：研究未知选项

An unrecognised option is one of three things, and they have opposite fixes:

a typo — suggest the nearest real option from
```
knownOptions
```
in the data file
a third-party extension (
```
ts-node
```
,
```
tsc-alias
```
,
```
@vue/tsconfig
```
) — a sibling key like
```
ts-node
```
is legal and must be left alone; only
```
compilerOptions
```
entries are audited
newer than the data file — a genuine option added after
```
tsVersion
```

Grep the repo for the option name and for any tool that would own it — a

ts-node

tsc-alias

dependency in

package.json

settles the second case without a web lookup. Otherwise check the current TypeScript release notes and the option reference for the name before advising. Then report it to the user as a gap: name the option, say which case it was, and propose the concrete

references/ts7-options.json

change that would let the checker classify it next time. Do not silently recommend deleting an option you could not identify.

未识别的选项属于以下三种情况之一，且修复方式完全相反：

拼写错误 — 建议从数据文件的
```
knownOptions
```
中选择最接近的真实选项
第三方扩展（
```
ts-node
```
、
```
tsc-alias
```
、
```
@vue/tsconfig
```
）—— 类似
```
ts-node
```
的同级键是合法的，必须保留；仅审计
```
compilerOptions
```
中的条目
比数据文件更新 — 是在
```
tsVersion
```
之后添加的真实选项

在仓库中搜索该选项名称以及可能拥有它的工具——

package.json

中的

ts-node

或

tsc-alias

依赖可直接确定第二种情况，无需网页查询。否则，检查当前TypeScript版本说明和选项参考中的名称，然后再提供建议。然后向用户报告此空白：说明选项名称、属于哪种情况，并提议修改

references/ts7-options.json

的具体内容，以便检查器下次能对其进行分类。请勿静默建议删除无法识别的选项。

Step 5: Report

步骤5：生成报告

Lead with the blocking findings and the concrete failure each one causes. Then the must-add findings, then the safe drops as a single grouped list, then anything to keep and why.

State the compiler and data-file versions the audit ran against. If they differ, say so.

If the config has project

references

, the audit covered only the config it was pointed at. List the referenced configs and offer to audit each one — do not imply the whole solution was checked.

首先列出阻塞项以及每个项导致的具体失败。然后是必须添加项，接着是可安全删除项的分组列表，最后是需保留项及其原因。

说明审计所使用的编译器和数据文件版本。如果两者不同，需明确指出。

如果配置包含项目

references

，审计仅覆盖指向的配置文件。列出引用的配置文件并提议审计每个文件——不要暗示已检查整个解决方案。

Step 6: Offer to apply

步骤6：提议应用修改

Ask before writing, per Asking the User:

Apply blocking fixes and safe drops — everything except the keep findings
Apply blocking fixes only — the minimum to build on TS7
Report only — change nothing

When applying:

Edit surgically. Remove or change the specific lines.
```
tsconfig.json
```
is JSONC and is routinely commented — never reserialize the file, which would strip every comment.
Only edit files inside the project. For
```
editable: false
```
findings, add a local override.
Capture a baseline first:
```
tsc -p <config> --noEmit --locale en
```
before any edit.
Verify after: rerun it and compare the set of diagnostics, not the count — an equal count can hide a different failure.
When the config emits, also compare emitted paths before and after (
```
tsc -p <config> --listFilesOnly
```
plus the resolved
```
outDir
```
layout). This is the only check that catches a
```
rootDir
```
regression, which
```
--noEmit
```
structurally cannot see.
If verification regresses, revert your own edits and report what happened. Do not leave the config half-migrated.

根据询问用户的要求，在修改前先询问：

应用阻塞修复和安全删除项 — 除需保留项外的所有内容
仅应用阻塞修复 — 使配置能在TS7下构建的最小修改
仅生成报告 — 不做任何修改

应用修改时：

精准编辑。仅移除或修改特定行。
```
tsconfig.json
```
是JSONC格式，通常包含注释——请勿重新序列化文件，否则会丢失所有注释。
仅编辑项目内的文件。对于
```
editable: false
```
的结果，添加本地覆盖。
先捕获基线：修改前运行
```
tsc -p <config> --noEmit --locale en
```
。
修改后验证：重新运行该命令并比较诊断信息的集合，而非数量——相同数量的诊断信息可能隐藏不同的失败。
当配置生成输出时，还要比较修改前后的输出路径（
```
tsc -p <config> --listFilesOnly
```
加上解析后的
```
outDir
```
布局）。这是唯一能发现
```
rootDir
```
回归的检查，而
```
--noEmit
```
在结构上无法检测到这种情况。
如果验证发现回归，撤销自己的修改并报告情况。请勿让配置处于半迁移状态。

Cautions

注意事项

baseUrl
and
paths
are not tsc-only. Bundlers, Vitest/Jest and IDEs resolve them independently. A clean typecheck after dropping them proves nothing about runtime resolution. When
```
baseUrl
```
is removed, every relative
```
paths
```
entry needs its prefix folded in — the checker computes the rewrite.
target
,
module
,
lib
and
strict
are on the keep-list on purpose. The TS7
```
target
```
default floats to the newest stable ECMAScript version, so dropping it makes emit change on a compiler upgrade.
"Matches the default" is a weaker claim than "removed". Defaults can move between releases; a removal will not come back. Present drops as cleanup, not as required work.
Never recommend
```
ignoreDeprecations
```
as a fix. It did nothing in TS7 — removed is removed.

baseUrl
和
paths
并非仅tsc使用。打包工具、Vitest/Jest和IDE会独立解析它们。删除这些选项后通过类型检查并不能证明运行时解析正常。当移除
```
baseUrl
```
时，每个相对的
```
paths
```
条目都需要合并其前缀——检查器会计算重写规则。
target
、
module
、
lib
和
strict
被特意列入保留列表。TS7的
```
target
```
默认值会浮动到最新稳定的ECMAScript版本，因此删除该选项会导致编译器升级时输出变更。
"与默认值匹配"的声明比"已移除"弱。默认值可能在版本间变更；已移除的选项不会再回归。将删除操作表述为清理，而非必需工作。
切勿推荐使用
```
ignoreDeprecations
```
作为修复方案。在TS7中它毫无作用——已移除的就是已移除的。

Keeping the Data File Current

保持数据文件更新

references/ts7-options.json

is generated. Do not hand-edit it.

bash

node <skill-dir>/scripts/refresh-options.mjs [--tag typescript/v7.0.2] [--tsc <path>]

It pulls the compiler's own option declarations from the pinned

microsoft/typescript-go

release tag, then probes an installed

tsc

for removals, enums and implications. Probes win where the two disagree — the declared defaults are help strings and are wrong in places.

rootDir

declares "Computed from the list of input files" but is fixed at

, and the 7.0 release notes claim

stableTypeOrdering

cannot be disabled while the compiler accepts

false

Regenerate when a new TypeScript release ships, or when Step 4 turns up an option the data file does not know.

references/ts7-options.json

是生成的文件。请勿手动编辑。

bash

node <skill-dir>/scripts/refresh-options.mjs [--tag typescript/v7.0.2] [--tsc <path>]

它从固定的

microsoft/typescript-go

版本标签中提取编译器自身的选项声明，然后通过已安装的

tsc

探测已移除的选项、枚举和隐含关系。当两者不一致时，探测结果优先——声明的默认值是帮助字符串，在某些情况下并不准确。例如

rootDir

声明为"从输入文件列表计算"，但实际固定为

；7.0版本说明声称

stableTypeOrdering

无法禁用，但编译器接受

false

值。

当TypeScript发布新版本，或步骤4发现数据文件未收录的选项时，重新生成该文件。

Reference Files

参考文件

```
references/migrations.md
```
— the fix for each removed option and value
```
references/ts7-options.json
```
— generated option data

```
references/migrations.md
```
— 每个已移除选项和值的修复方案
```
references/ts7-options.json
```
— 生成的选项数据

tsconfig-audit

Original

Translation

tsconfig Audit

tsconfig 审计

Purpose

目的

When to Use This Skill

使用场景

Scope

范围

How It Works

工作原理

Asking the User

询问用户

Workflow

工作流程

Step 1: Find the configs

步骤1：查找配置文件

Glob: */tsconfig.json, excluding node_modules

全局匹配：**/tsconfig*.json，排除node_modules

Step 2: Run the checker

步骤2：运行检查器

Step 3: Read the findings

步骤3：读取检查结果

Step 4: Research unknown options

步骤4：研究未知选项

Step 5: Report

步骤5：生成报告

Step 6: Offer to apply

步骤6：提议应用修改

Cautions

注意事项

Keeping the Data File Current

保持数据文件更新

Reference Files

参考文件

Glob: **/tsconfig*.json, excluding node_modules