ts-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript Audit

TypeScript 审计

Audit TypeScript code against 9 expert-level references covering type safety, generics, advanced patterns, React integration, type transformations, and testing. The goal is to surface concrete improvements the author may not have considered — not to nitpick style, but to catch real type-safety gaps, missed narrowing opportunities, and patterns that would make the code more robust.

依据 9 个专家级参考资料对 TypeScript 代码进行审计，涵盖 type safety、generics、advanced patterns、React integration、type transformations 和 testing。目标是发现代码作者可能未曾考虑的具体改进空间——不为样式细节吹毛求疵，而是找出真实的 type-safety 缺口、错失的 narrowing 机会，以及能让代码更健壮的模式。

Invocation

调用方式

The user provides a target: a file path, directory, or glob pattern. Examples:

```
/ts-audit src/db/queries.ts
```
```
/ts-audit src/pipeline/
```
```
/ts-audit src/**/*.tsx
```

用户需提供目标：文件路径、目录或 glob 模式。示例：

```
/ts-audit src/db/queries.ts
```
```
/ts-audit src/pipeline/
```
```
/ts-audit src/**/*.tsx
```

Invocation Position

调用定位

This is a side-route skill for TypeScript code quality auditing, not a default pipeline step.

Use

/ts-audit

when you want to audit TypeScript or React code against expert-level patterns from the bundled TypeScript library references — whether on a single file, a directory, or a glob of changed files.

Do not use it as a substitute for

/pre-merge

architectural review (which checks structural principles) or

/tdd

(which enforces red-green-refactor). It complements both by focusing specifically on type-safety gaps and TypeScript idiom improvements.

For TypeScript projects,

/ts-audit

pairs naturally with

/pre-merge

Phase 3 (Architectural Review) — running it on changed files provides type-safety analysis that complements the structural review dimensions defined in

pre-merge/review-checklist.md

这是用于 TypeScript 代码质量审计的旁路 Skill，而不是默认 pipeline 步骤。

当你想依据随附的 TypeScript 库参考资料，对单个文件、目录或变更文件 glob 中的 TypeScript 或 React 代码进行审计时，使用

/ts-audit

。

不要将其用作

/pre-merge

architectural review（检查结构原则）或

/tdd

（强制 red-green-refactor）的替代品。它专注于 type-safety 缺口和 TypeScript idiom 改进，从而补充二者。

对于 TypeScript 项目，

/ts-audit

可自然搭配

/pre-merge

Phase 3（Architectural Review）——在变更文件上运行它，可提供 type-safety 分析，补充

pre-merge/review-checklist.md

中定义的结构性审查维度。

Step 1: Read the target code

Step 1：读取目标代码

Single file: read it directly
Directory: glob for
```
**/*.ts
```
and
```
**/*.tsx
```
files within it
Glob pattern: expand the glob

For large targets (>15 files), focus on files with the richest type-level code — interfaces, generics, service layers, component props. Skip auto-generated files (

*.gen.ts

*.d.ts

单文件：直接读取
目录：在目录内对
```
**/*.ts
```
和
```
**/*.tsx
```
文件进行 glob 匹配
Glob 模式：展开 glob

对于大型目标（超过 15 个文件），重点检查类型层级代码最丰富的文件——包括 interfaces、generics、service layers 和 component props。跳过自动生成的文件（

*.gen.ts

、

*.d.ts

）。

Step 2: Load the relevant library references

Step 2：加载相关库参考资料

Resolve the library path:

bash

echo "${CLAUDE_LIBRARY_DIR:-$([ -f "$HOME/.claude/library/index.json" ] && echo "$HOME/.claude/library" || echo "NOT_FOUND")}"

Select which books to load based on what's in the target. This keeps context lean — only pay for what you need.

Always load (core):

Book	What it covers
`total-typescript-book`	Core type system — inference, narrowing, unions, `satisfies` , `as const`
`ts-essentials`	Essential patterns — annotations, type guards, discriminated unions
`ts-generics`	Generic scope, constraints, inference, overloads
`ts-type-transforms`	Mapped types, conditional types, template literals, `infer`
`advanced-ts-patterns`	Branded types, assertion functions, identity functions, `const T`

Load if target contains
.tsx
files or files that import React:

Book	What it covers
`react-ts-patterns`	React props typing, hooks, `ComponentProps` , discriminated union props

Load if target contains test files (
*.test.ts
,
*.test.tsx
,
*.spec.ts
):

Book	What it covers
`testing-fundamentals`	Test structure, assertions, async testing
`advanced-vitest-patterns`	Fixtures, custom assertions, performance testing
`mocking-techniques`	MSW, dependency injection, fake timers, typed mocks

Read each selected SKILL.md (path:

{LIB}/books/<name>/SKILL.md

) into context. These contain lookup tables, decision matrices, and anti-pattern catalogs that form the audit criteria.

Also consult these companion skills when the target uses Zod (these live in

~/.claude/skills/

, not the library):

Skill	Load when
`/zod`	Any source file in target imports `zod` — covers schema design, `safeParse` , `z.infer` , refinements, transforms, codecs, branded types, and v3→v4 migration concerns
`/zod-testing`	Test files in target import `zod` or reference zod schemas — covers schema correctness, error assertion patterns, `z.toJSONSchema()` snapshots, and mock-data generation

Read each companion skill's

SKILL.md

(path:

~/.claude/skills/<name>/SKILL.md

) and any rule files it points at. Treat them as authoritative for Zod-specific findings the same way Total TypeScript books are authoritative for general type-system findings.

解析库路径：

bash

echo "${CLAUDE_LIBRARY_DIR:-$([ -f "$HOME/.claude/library/index.json" ] && echo "$HOME/.claude/library" || echo "NOT_FOUND")}"

根据目标内容选择要加载的书籍。这样可以保持 context 精简——只按需加载。

始终加载（核心）：

资料	涵盖内容
`total-typescript-book`	核心类型系统——inference、narrowing、unions、 `satisfies` 、 `as const`
`ts-essentials`	基础模式——annotations、type guards、discriminated unions
`ts-generics`	Generic scope、constraints、inference、overloads
`ts-type-transforms`	Mapped types、conditional types、template literals、 `infer`
`advanced-ts-patterns`	Branded types、assertion functions、identity functions、 `const T`

如果目标包含
.tsx
文件或导入 React 的文件，则加载：

资料	涵盖内容
`react-ts-patterns`	React props typing、hooks、 `ComponentProps` 、discriminated union props

如果目标包含测试文件（
*.test.ts
、
*.test.tsx
、
*.spec.ts
），则加载：

资料	涵盖内容
`testing-fundamentals`	Test structure、assertions、async testing
`advanced-vitest-patterns`	Fixtures、custom assertions、performance testing
`mocking-techniques`	MSW、dependency injection、fake timers、typed mocks

将每个选中的 SKILL.md（路径：

{LIB}/books/<name>/SKILL.md

）读入 context。这些文件包含 lookup tables、decision matrices 和 anti-pattern catalogs，共同构成审计标准。

当目标使用 Zod 时，还需查阅以下 companion skills（这些文件位于

~/.claude/skills/

，而不是 library 中）：

Skill	加载条件
`/zod`	目标中的任何源文件导入 `zod` ——涵盖 schema design、 `safeParse` 、 `z.infer` 、refinements、transforms、codecs、branded types，以及 v3→v4 migration concerns
`/zod-testing`	测试文件导入 `zod` 或引用 zod schemas——涵盖 schema correctness、error assertion patterns、 `z.toJSONSchema()` snapshots 和 mock-data generation

读取每个 companion skill 的 SKILL.md（路径：

~/.claude/skills/<name>/SKILL.md

）及其指向的任何 rule 文件。对于 Zod 专项发现，应将这些文件视为 authoritative，就像将 Total TypeScript 书籍视为 general type-system findings 的依据一样。

Step 3: Analyze the code

Step 3：分析代码

Work through each file and check against the loaded references. The categories below describe what to look for — the specific rules come from the library references you just loaded.

逐个检查文件，并对照已加载的参考资料。以下类别说明检查方向——具体规则来自刚刚加载的库参考资料。

Type Safety (total-typescript-book, ts-essentials)

类型安全（total-typescript-book、ts-essentials）

Widened types where narrower literals exist (e.g.,
```
status: string
```
when only
```
"approved" | "denied" | "tabled"
```
are valid)
```
any
```
where
```
unknown
```
would be safer
```
as
```
type assertions that bypass narrowing — could the code use a type guard or discriminated union instead?
Missing return type annotations on exported/public functions
Loose
```
string
```
or
```
number
```
where branded types would prevent value confusion
Library-callback return wrapper types without
satisfies
. A local type that wraps a library-provided callback's return (agent hooks, middleware, proxy, tool handlers, render props, lifecycle methods) and gets returned from the callback as a typed variable. TS excess-property check does not run on returns of typed values — fields not declared by the library's signature are silently dropped at runtime. Remedy: end the returned object expression with
```
satisfies LibraryReturnType
```
, return a fresh object literal, or derive the local type via
```
ReturnType<…>
```
/
```
Parameters<…>
```
. Cite: ts-essentials Rule 31, "Use
```
satisfies
```
for type validation without losing inference precision."

存在更窄 literal type 时却使用了 widened type（例如，只有
```
"approved" | "denied" | "tabled"
```
有效，却写成
```
status: string
```
）
使用
```
any
```
，而
```
unknown
```
会更安全
使用
```
as
```
type assertion 绕过 narrowing——能否改用 type guard 或 discriminated union？
exported/public functions 缺少 return type annotations
使用宽松的
```
string
```
或
```
number
```
，而 branded types 可以防止值混淆
包装 library-provided callback 返回值的 local type 缺少
satisfies
。某个 local type 包装 library-provided callback 的返回值（Agent hooks、middleware、proxy、tool handlers、render props、lifecycle methods），并作为 typed variable 从 callback 返回。TS excess-property check 不会在 typed value 的 return 上运行——library 签名未声明的字段会在运行时被静默丢弃。修复方式：让返回的对象表达式以
```
satisfies LibraryReturnType
```
结尾、返回新的 object literal，或通过
```
ReturnType<…>
```
/
```
Parameters<…>
```
推导 local type。引用：ts-essentials Rule 31，“使用
```
satisfies
```
在不损失 inference 精度的前提下进行类型验证。”

Generics (ts-generics)

Generics（ts-generics）

Generics declared at too broad a scope (class-level when function-level suffices)
Missing or overly loose constraints (
```
T
```
with no
```
extends
```
)
Redundant generic parameters the compiler could infer
Cases where function overloads would clarify input-dependent return types

Generics 声明的 scope 过于宽泛（class-level 足以覆盖的场景却使用了 function-level 之外的 scope）
Constraints 缺失或过于宽松（
```
T
```
没有
```
extends
```
）
存在 compiler 本可自行 infer 的冗余 generic parameters
某些场景可使用 function overloads 更清晰地表达依赖于输入的 return types

Discriminated Unions & Narrowing (total-typescript-book, ts-essentials)

Discriminated Unions 与 Narrowing（total-typescript-book、ts-essentials）

Boolean props/flags where a discriminated union would be clearer and safer
Destructured discriminated union parameters (breaks narrowing)
Switch/if chains on union types missing exhaustive checks
Filtering arrays of unions without type predicates (result stays wide)

使用 Boolean props/flags，而 discriminated union 会更清晰、更安全
对 discriminated union parameters 进行解构，导致 narrowing 失效
针对 union types 的 switch/if chains 缺少 exhaustive checks
过滤 union arrays 时未使用 type predicates，导致结果类型仍然过宽

Advanced Patterns (advanced-ts-patterns)

Advanced Patterns（advanced-ts-patterns）

Assertion functions using arrow syntax (must use
```
function
```
declarations)
Opportunities for
```
const T
```
parameter to preserve literal types
Places where branded types would prevent mixing semantically distinct values (e.g.,
```
userId
```
vs
```
orderId
```
)
Builder/accumulator patterns that could leverage generic intersection

使用 arrow syntax 编写 assertion functions（必须使用
```
function
```
declarations）
可以利用
```
const T
```
parameter 保留 literal types 的机会
可以使用 branded types 防止语义不同的值混用（例如
```
userId
```
与
```
orderId
```
）
Builder/accumulator patterns 可以利用 generic intersection 的机会

Type Transformations (ts-type-transforms)

Type Transformations（ts-type-transforms）

Manual type duplication where
```
typeof
```
, mapped types, or conditional types would derive from a single source of truth
```
ReturnType<fn>
```
instead of
```
ReturnType<typeof fn>
```
Opportunities for template literal types

手动重复类型定义，而本可通过
```
typeof
```
、mapped types 或 conditional types 从单一 source of truth 推导
使用
```
ReturnType<fn>
```
，而不是
```
ReturnType<typeof fn>
```
可以利用 template literal types 的机会

React Patterns (react-ts-patterns) —

.tsx

files or files importing React

React Patterns（react-ts-patterns）——适用于

.tsx

文件或导入 React 的文件

HTML wrapper components not using
```
ComponentProps<"element">
```
Missing generic parameters on
```
useState
```
,
```
useRef
```
Mutually exclusive props modeled as optional booleans instead of discriminated unions
Event handlers manually typed instead of derived from React types

HTML wrapper components 未使用
```
ComponentProps<"element">
```
```
useState
```
、
```
useRef
```
缺少 generic parameters
将 mutually exclusive props 建模为 optional booleans，而不是 discriminated unions
手动定义 event handlers 类型，而不是从 React types 推导

Zod Schema Validation (

/zod

) — files importing

zod

Zod Schema Validation（

/zod

）——适用于导入

zod

的文件

```
parse()
```
at trust boundaries where
```
safeParse()
```
would let the caller branch on validation failure without exceptions
Hand-maintained TypeScript types alongside a Zod schema where
```
z.infer<typeof Schema>
```
would derive them from a single source of truth
```
z.nativeEnum()
```
in code targeting Zod v4 (removed — use
```
z.enum()
```
over the values, or
```
z.literal
```
unions)
String formats expressed as
```
.refine(...)
```
regex when Zod v4's first-class formats (
```
z.email()
```
,
```
z.url()
```
,
```
z.uuid()
```
,
```
z.iso.datetime()
```
, etc.) apply
```
.refine()
```
chains that mask which check failed — splitting into multiple
```
.refine()
```
calls with distinct messages, or moving to
```
.superRefine()
```
with
```
ctx.addIssue
```
, surfaces clearer error paths
Reading
```
.error.format()
```
for programmatic handling where
```
.error.issues
```
(the flat array) is the v4-preferred shape
Untyped
```
try/catch
```
around
```
parse()
```
— the thrown value is
```
ZodError
```
, not generic;
```
safeParse
```
+ discriminant check preserves the typed error channel
Schemas defined inside hot paths (request handlers, render bodies) that should be hoisted to module scope so they aren't reconstructed per call

在 trust boundaries 使用
```
parse()
```
；此处改用
```
safeParse()
```
可让调用方根据 validation failure 分支处理，而无需抛出异常
在 Zod schema 旁手动维护 TypeScript types；应使用
```
z.infer<typeof Schema>
```
从单一 source of truth 推导类型
面向 Zod v4 的代码中使用
```
z.nativeEnum()
```
（已移除——应对 values 使用
```
z.enum()
```
，或使用
```
z.literal
```
unions）
当 Zod v4 的 first-class formats（
```
z.email()
```
、
```
z.url()
```
、
```
z.uuid()
```
、
```
z.iso.datetime()
```
等）适用时，字符串格式却通过
```
.refine(...)
```
regex 表达
```
.refine()
```
chains 掩盖了具体失败的检查——可拆分为多个带有不同 messages 的
```
.refine()
```
calls，或使用
```
ctx.addIssue
```
将逻辑移至
```
.superRefine()
```
，以呈现更清晰的 error paths
在需要 programmatic handling 的场景中读取
```
.error.format()
```
；v4 更推荐使用扁平数组形式
```
.error.issues
```
在
```
parse()
```
周围使用未类型化的
```
try/catch
```
——抛出的值是
```
ZodError
```
，而非 generic；使用
```
safeParse
```
+ discriminant check 可以保留 typed error channel
在 hot paths（request handlers、render bodies）中定义 schemas；应将其提升至 module scope，避免每次调用时重新创建

Zod Schema Testing (

/zod-testing

) — test files referencing zod schemas

Zod Schema Testing（

/zod-testing

）——适用于引用 zod schemas 的测试文件

Schemas without tests covering both the valid-input accept path and the invalid-input reject path
Error assertions that check only
```
expect(result.success).toBe(false)
```
without asserting on
```
result.error.issues[i].code
```
or
```
path
```
— the test passes for any rejection reason, not the intended one
Mock data hand-rolled inline when
```
zod-schema-faker
```
(or equivalent) would generate conforming fixtures from the schema itself
Missing boundary-value tests for
```
.min()
```
/
```
.max()
```
constraints (off-by-one edges)
Snapshot tests of API response shapes that could use
```
z.toJSONSchema(Schema)
```
as a structural assertion instead of brittle object snapshots
Integration tests that hit handlers with raw objects when the same handler accepts schema-parsed input — the test bypasses the validation it's meant to exercise

Schemas 缺少同时覆盖 valid-input accept 路径和 invalid-input reject 路径的测试
Error assertions 仅检查
```
expect(result.success).toBe(false)
```
，却未断言
```
result.error.issues[i].code
```
或
```
path
```
——测试会因任何 rejection reason 而通过，并非仅验证预期原因
Inline 手动编写 mock data，而
```
zod-schema-faker
```
（或同类工具）可以根据 schema 本身生成符合约束的 fixtures
缺少针对
```
.min()
```
/
```
.max()
```
constraints 的 boundary-value tests（off-by-one edges）
API response shapes 的 snapshot tests 可以使用
```
z.toJSONSchema(Schema)
```
作为 structural assertion，从而避免脆弱的 object snapshots
Integration tests 使用 raw objects 调用 handlers，而同一 handler 可以接受 schema-parsed input——这会绕过测试本应验证的 validation

Testing Patterns (testing-fundamentals, advanced-vitest-patterns, mocking-techniques) — test files only

Testing Patterns（testing-fundamentals、advanced-vitest-patterns、mocking-techniques）——仅适用于测试文件

Mocking that could use dependency injection
Untyped mocks
Tests not following arrange/act/assert structure
API mocking that should use MSW

Mocking 可以改用 dependency injection
未类型化的 mocks
Tests 未遵循 arrange/act/assert 结构
API mocking 应使用 MSW

Step 3b: Go deeper — surface what the library knows that general knowledge doesn't

Step 3b：深入分析——发现 library 中超出一般知识的模式

After catching the obvious issues above, make a second pass specifically looking for opportunities to apply the non-obvious patterns from each loaded reference. These are the findings that differentiate this audit from what any TypeScript developer would notice:

From advanced-ts-patterns: Look for functions that accept

string

number

parameters where the values are semantically distinct (e.g., a

userId

and an

orderId

both typed as

string

). Suggest branded types at the boundaries. Look for assertion functions written as arrow functions — they must use

function

declarations. Check if any generic function would benefit from

const T

to preserve literal types from callers.

From ts-type-transforms: Look for manually duplicated type shapes across files (write-side vs read-side types, DTO vs entity). Suggest

Pick

Omit

, intersection types, or mapped types to derive from a single source of truth. Check for

ReturnType<fn>

that should be

ReturnType<typeof fn>

From ts-generics: Look for generics placed at class or module scope that could be narrowed to function scope. Look for functions returning different types based on input where overloads would make the contract clearer. Check for unconstrained

parameters that should have

extends

bounds.

From react-ts-patterns (if loaded): Look for components wrapping HTML elements that don't use

ComponentProps<"element">

to forward props. Check for mutually exclusive prop combinations modeled as separate optional props instead of a discriminated union. Look for manual event handler types that could be derived from React's event types.

From testing books (if loaded): Look for

test.extend()

fixture opportunities where multiple tests share the same setup. Check for typed mock patterns — are mocks losing type information? Look for API calls being mocked inline that should use MSW for more realistic testing. Check if Effect-based code is being tested via

runPromise

rejects.toThrow()

instead of

runPromiseExit

which preserves the typed error channel.

From
/zod
,
/zod-testing
(if loaded): Look for places where a Zod schema and a manually-declared TS type describe the same shape —

z.infer<typeof Schema>

collapses the drift surface. Look for

parse()

calls at system boundaries (HTTP handlers, form submissions, env var parsing) where

safeParse()

would let the caller respond gracefully instead of throwing. Check for v3-isms in v4 code (

nativeEnum

, custom regex for emails/URLs,

.error.format()

for programmatic flow). In test files, check that error assertions inspect

issues[i].code

path

— not just

success === false

— so the test actually pins down which validation failed. Watch for schemas reconstructed inside hot paths (request handlers, render bodies) that should be hoisted to module scope, and for handler/integration tests that bypass the schema layer they exist to verify.

The goal of this second pass is to surface at least 1-2 findings per loaded library that go beyond what a developer would catch from general TypeScript knowledge alone. If a library's patterns genuinely don't apply to the target code, that's fine — skip it. But look carefully before deciding nothing applies.

在发现上述显而易见的问题后，再进行第二轮检查，专门寻找每个已加载参考资料中那些不容易察觉的模式。这些发现正是本次审计区别于普通 TypeScript 开发者所能发现问题的关键：

来自 advanced-ts-patterns： 查找接受

string

或

number

parameters、但值在语义上彼此不同的 functions（例如

userId

和

orderId

都使用

string

类型）。建议在 boundaries 使用 branded types。查找以 arrow functions 编写的 assertion functions——它们必须使用

function

declarations。检查是否有 generic function 可以通过

const T

保留 callers 传入的 literal types。

来自 ts-type-transforms： 查找跨文件手动重复的 type shapes（write-side 与 read-side types、DTO 与 entity）。建议使用

Pick

、

Omit

、intersection types 或 mapped types，从单一 source of truth 推导。检查

ReturnType<fn>

是否应改为

ReturnType<typeof fn>

。

来自 ts-generics： 查找位于 class 或 module scope、但可以缩小至 function scope 的 generics。查找根据 input 返回不同 types、且通过 overloads 能够更清晰表达 contract 的 functions。检查未受约束、但应设置

extends

bounds 的

parameters。

来自 react-ts-patterns（如果已加载）： 查找未使用

ComponentProps<"element">

转发 props 的 HTML element wrapper components。检查 mutually exclusive prop combinations 是否被建模为多个 separate optional props，而不是 discriminated union。检查是否可以从 React event types 推导 manual event handler types。

来自 testing books（如果已加载）： 查找多个 tests 共享相同 setup、且可以使用

test.extend()

fixtures 的机会。检查 typed mock patterns——mocks 是否丢失了 type information？检查 inline mocked API calls 是否应使用 MSW，以获得更真实的 testing。检查 Effect-based code 是否使用

runPromise

rejects.toThrow()

进行测试，而不是使用能够保留 typed error channel 的

runPromiseExit

。

来自
/zod
、
/zod-testing
（如果已加载）：查找同一个 shape 同时由 Zod schema 和 manually-declared TS type 描述的位置——使用

z.infer<typeof Schema>

可以消除 drift surface。查找 system boundaries（HTTP handlers、form submissions、env var parsing）中的

parse()

calls；改用

safeParse()

可让调用方优雅处理失败，而不是抛出异常。检查 v4 代码中是否存在 v3-isms（

nativeEnum

、用于 emails/URLs 的 custom regex、programmatic flow 中的

.error.format()

）。在 test files 中，检查 error assertions 是否查看

issues[i].code

path

，而不是只检查

success === false

，以确保测试真正固定了具体失败的 validation。留意在 hot paths（request handlers、render bodies）中重新创建、而本应提升至 module scope 的 schemas，以及绕过 schema layer 的 handler/integration tests。

本轮目标是每个已加载 library 至少找出 1–2 个超出一般 TypeScript 知识范围的发现。如果某个 library 的 patterns 确实不适用于目标代码，可以跳过；但在认定其不适用之前，务必仔细检查。

Step 4: Generate the report

Step 4：生成报告

Redact secrets before writing the report

撰写报告前遮蔽 secrets

The report quotes source code verbatim, and it is a portable artifact — users paste it into a PR, drop it in chat, or hand it to another agent. Source files routinely carry secrets, so masking is not optional and not best-effort: run this pass on every snippet before it goes into the report.

Mask the value of any line matching a high-signal secret shape —
```
*_KEY
```
,
```
*_SECRET
```
,
```
*_TOKEN
```
,
```
*_PASSWORD
```
,
```
AKIA…
```
,
```
sk-…
```
,
```
ghp_…
```
,
```
xox[baprs]-…
```
, bearer tokens,
```
postgres://user:pass@…
```
and other credentialed URIs, PEM blocks.
Keep the key, mask the value —
```
STRIPE_SECRET_KEY=sk_live_••••••••
```
keeps the finding legible without leaking the credential. The type pattern is what the finding is about; the secret is not.
When in doubt, redact. A masked line the reader can ask about is recoverable; a leaked one in a copied report is not.
If you masked anything, say so once near the top of the report ("N value(s) masked") so the reader knows the artifact is sanitized, not incomplete.

Structure the report as markdown:

markdown

undefined

报告会逐字引用源代码，并且是可移植 artifact——用户会将其粘贴到 PR、发送到聊天或交给另一个 Agent。源文件经常包含 secrets，因此 masking 不是可选项，也不是 best-effort：报告中的每个 snippet 都必须先经过此处理。

对任何匹配高信号 secret shape 的行，遮蔽其 value——包括
```
*_KEY
```
、
```
*_SECRET
```
、
```
*_TOKEN
```
、
```
*_PASSWORD
```
、
```
AKIA…
```
、
```
sk-…
```
、
```
ghp_…
```
、
```
xox[baprs]-…
```
、bearer tokens、
```
postgres://user:pass@…
```
、带凭证的 URIs 和 PEM blocks
保留 key，遮蔽 value——例如
```
STRIPE_SECRET_KEY=sk_live_••••••••
```
，这样仍能清晰表达 finding，而不会泄露 credential
如有疑问，直接遮蔽。被遮蔽的行仍可供读者进一步询问；复制报告时泄露 credential 则无法挽回
如果遮蔽了任何内容，请在报告顶部附近说明一次（“已遮蔽 N 个值”），让读者知道该 artifact 已完成 sanitization，而非内容不完整

将报告组织为 markdown：

markdown

undefined

TypeScript Audit Report

TypeScript 审计报告

Target: <file or directory> Files analyzed: <count> Findings: <count>

目标： <文件或目录> 已分析文件数： <数量> 发现数量： <数量>

<Category Name>

<类别名称>

Source: <library book name(s)>

来源：<library book name(s)

<Short description of the finding>

<finding 的简短说明>

File:

<path>

:<line>

Current code: ```ts // the relevant snippet ```

Suggested change: ```ts // the improved version ```

Why: <1-2 sentences explaining what pattern this violates and why the suggestion is better, grounded in the library reference>


**Grouping:** by category (Type Safety, Generics, etc.), not by file. Within each category, order findings by file path then line number.

**What to include in each finding:**
- The actual code snippet (keep it focused — just the relevant lines), with secret values masked per the redaction step above
- A concrete suggested replacement, not just "consider using X"
- A brief explanation referencing the specific concept from the library

**What to omit:**
- Categories with zero findings — leave them out entirely
- Style preferences (semicolons, quotes, formatting)
- Findings that would break the code's runtime behavior without a broader refactor

End with a summary table:

```markdown

文件：

<path>:<line>

当前代码：

// 相关代码

建议修改：

// 改进后的版本

原因： <用 1–2 句话说明该代码违反了什么模式，以及建议方案为何更好；依据应来自 library reference>


**分组方式：**按类别（Type Safety、Generics 等），而不是按文件。在每个类别内，先按文件路径排序，再按行号排序。

**每个 finding 应包含：**
- 实际代码 snippet（仅保留相关行），并按照 redaction 步骤遮蔽 secret values
- 具体的建议替换方案，而不只是“考虑使用 X”
- 简短说明，并引用 library 中的具体概念

**应省略：**
- 没有 findings 的类别——完全不显示
- Style preferences（分号、引号、格式）
- 如果不进行更广泛的 refactor 就会破坏代码 runtime behavior 的 findings

最后附上 summary table：

```markdown

Summary

汇总

Category	Findings
Type Safety	N
Generics	N
...	...
Total	N


If no findings at all:

> No issues found. The code aligns well with the patterns from the TypeScript library collection.

类别	发现数量
类型安全	N
Generics	N
...	...
总计	N


如果完全没有 findings：

> 未发现问题。代码与 TypeScript 资料库集合中的模式高度一致。

Handoff

交接

Expected input: a file path, directory, or glob pattern pointing to TypeScript or React code to audit
Produces: a structured markdown audit report with findings grouped by category, each grounded in a specific bundled library reference
May feed into:
```
/execute
```
when findings warrant code changes, or
```
/pre-merge
```
when the audit informs the architectural review conversation
What comes next: return to the workflow that invoked the audit — the user decides which findings to act on

**预期输入：**指向 TypeScript 或 React 代码的 file path、directory 或 glob pattern
**产出：**结构化的 markdown audit report，findings 按类别分组，每项均基于具体的 bundled library reference
**可衔接至：**当 findings 需要代码修改时衔接至
```
/execute
```
，或当 audit 为 architectural review 提供依据时衔接至
```
/pre-merge
```
**后续步骤：**返回调用本次 audit 的 workflow——由用户决定处理哪些 findings