开发工具静态分析Lint代码质量【免费下载链接】typescript-eslint:sparkles: Monorepo for all the tooling which enables ESLint to support TypeScript项目地址https://gitcode.com/GitHub_Trending/ty/typescript-eslint点击查看免费下载typescript-eslint/rule-schema-to-typescript-types是 typescript-eslint 仓库中的一个内部工具包它读取规则在meta.schema中声明的 JSON Schemav4并输出与之等价的 TypeScript 类型字符串形如type Options [...]。这些生成结果既用于文档展示也作为规则类型定义的权威来源。读完本文你将理解该包的输入/输出约定、类型映射规则、$ref/$defs处理方式、错误边界与优化策略并能独立复现其核心能力。一、包定位内部工具服务于文档与类型生成在 typescript-eslint 这个 monorepo 中packages/rule-schema-to-typescript-types/README.md 明确声明这是一个Internal Package内部包面向 typescript-eslint 仓库自身的工具链而非面向最终用户的独立产品。官方文档页 docs/packages/RuleSchemaToTypeScriptTypes.mdx 对它的描述是一句话Converts ESLint rule schemas to equivalent TypeScript type strings ✨包的package.jsonpackages/rule-schema-to-typescript-types/package.json中 version 为8.71.1依赖了同仓库的typescript-eslint/type-utils与typescript-eslint/utils另外依赖natural-compare用于排序保证输出确定性Node 版本要求^18.18.0 || ^20.9.0 || 21.1.0。该包在整个仓库中的核心消费方是 eslint-plugin 的类型生成测试 packages/eslint-plugin/tests/schemas.test.ts它遍历所有规则的ruleDef.meta.schema调用schemaToTypes生成类型字符串再用 Prettier 格式化后写入schema-snapshots/*.shot快照文件。也就是说每一个规则的可读类型签名都来自这个包。对应的快照产物可见 packages/eslint-plugin/tests/schema-snapshots/例如no-unused-vars.shot其中# SCHEMA:段是原始 JSON Schema# TYPES:段是生成的类型定义。二、入口函数schemaToTypes输入与输出约定对外唯一入口是schemaToTypes实现在 src/index.tsexport function schemaToTypes( schema: JSONSchema4 | readonly JSONSchema4[], ): string关键行为输入可以是单个 JSON Schema v4 对象也可以是 schema 数组。JSONSchema4类型定义在 packages/utils/src/json-schema.ts对应 JSON Schema draft v4 的各个子类型JSONSchema4ObjectSchema、JSONSchema4ArraySchema、JSONSchema4RefSchema等。数组输入 → 元组类型数组被当作规则 options 的元组输出type Options [T0, T1, ...]对象输入 → 单一类型输出type Options T空数组输入返回固定的/** No options declared */type Options [];对应测试 tests/index.test.ts 的第一条用例$defs/definitions展开仅支持顶层的$defs或definitions源码注释we only support defs at the top level for simplicity每个定义键会被转换为 PascalCase 类型名toPascalCase首字母大写并同时注册#/$defs/{key}与#/items/{index}/$defs/{key}两个引用路径随后以引用类型在前、Options 类型在后、块间空行分隔的顺序拼接输出。官方文档页 docs/packages/RuleSchemaToTypeScriptTypes.mdx 给出的最小示例import { schemaToTypes } from typescript-eslint/rule-schema-to-typescript-types; schemaToTypes({ description: My great option!, items: { type: string }, type: array, }); // 输出 // type Options [ // /** My great option! */ // string[] // ];三、类型生成规则JSON Schema → TS 类型的映射核心递归逻辑在 src/generateType.ts处理顺序如下$ref优先命中refMap则生成TypeReferenceAST引用类型名enum把枚举值生成联合类型见第四节anyOf/oneOf均生成联合类型。源码注释特别说明anyOf在 JSON Schema 语义上其实是组合T、U、V 的任意交集组合但实践中大多被用来模拟oneOf因此本工具直接按联合类型处理type关键字按类型分发——any→unknown不生成any避免污染类型安全null→nullnumber/string→ 直接输出对应关键字boolean→booleaninteger→numberTS 无integer类型array→ 走generateArrayType第五节object→ 走generateObjectType第六节未声明type且不含$ref/enum/oneOf的 schema→ 抛出NotSupportedErroruntyped schemas without one of [$ref, enum, oneOf]type为数组多类型 schema→ 同样抛出NotSupportedError。显式不支持的关键字src/generateType.ts 定义了一组可能应该支持但当前不支持的关键字命中即抛NotSupportedErrorallOf, dependencies, extends, maxProperties, minProperties, multipleOf, not, patternProperties错误信息会带上完整 JSON 序列化的目标 schema方便定位问题。四、枚举与联合类型generateUnionTypesrc/generateUnionType.ts 负责把枚举成员转为联合类型成员字符串转成单引号字面量内部单引号会被转义为\数字 / 布尔值原样转成字面量对象递归走generateType不支持的成员null或数组出现在 enum 中会抛NotSupportedError。联合成员在输出时会被排序以保证确定性依赖natural-compare排序逻辑见 src/printAST.ts 的compareElements不同节点类型先按代码文本自然比较同为 tuple 时先按元素数量升序避免 natural-compare 把长元组排前面再按代码比较。五、数组与元组generateArrayType的启发式策略src/generateArrayType.ts 是策略最复杂的一环核心规则items缺失抛UnexpectedError{type: array}理论上可映射为any[]但过于宽松工具拒绝生成单类型数组items不是数组直接生成T[]即使声明了minItems/maxItems也不生成元组源码注释[T, ...T[]]形式虽然可行但为了文档可读性放弃参见 issue #11117items为数组 → 按元组处理并引入三个关键约束MAX_ITEMS_TO_TUPLIZE 20元组元素超过 20 个就不再元组化直接退化为数组类型以保证简洁maxItems语义只有当maxItems 20时才考虑若maxItems items.length且存在additionalItems对象形式则生成展开元素打印为...T[]maxItems小于 items 个数、或大于 items 个数却没有additionalItems都会抛UnexpectedErrorminItems语义当 items 个数多于minItems时不采用可选元素运算符[T, T?, T?]因为它允许[a, undefined, c]这种中间空洞而是生成元组的联合[T] | [T, T] | [T, T, T]保证每个位置类型更精确源码注释给出了这一类型安全论证且只有联合的最后一个元组带展开参数。例如测试中的用例[{ items: [{type:string}], type: array }]输出为type Options [ | [] | [string]]六、对象类型必填/可选属性与索引签名src/generateObjectType.ts 处理type: object的 schema属性必填性根据required数组判定不在required中的属性输出为可选?:。required非数组时按空集合处理属性名转义通过typescript-eslint/type-utils的requiresQuoting判断属性名是否需要加引号必要时输出prop-name形式索引签名additionalProperties true或未声明时索引签名类型为unknownadditionalProperties为对象时递归生成其类型。输出形式为[k: string]: T属性排序在打印阶段src/printAST.ts用naturalCompare对属性名排序保证无论声明顺序如何输出一致并强制把对象打印为多行。七、注释生成description → JSDocsrc/getCommentLines.ts 将 schema 的description作为注释行src/printAST.ts 的printComment负责排版单行描述 →/** description */多行 → 逐行加*前缀的多行 JSDoc描述中的任意换行符CRLF、CR、LF、行分隔符 U2028、段落分隔符 U2029都会被ASTUtils.LINEBREAK_MATCHER拆分为独立注释行——测试 tests/index.test.ts 对五种换行符分别断言了多行注释输出。八、AST 优化联合展开与去重src/optimizeAST.ts 在生成后对中间 AST 做一轮优化主要是针对联合类型递归优化所有子节点unwrapUnions展平嵌套联合并把外层联合的注释行前置到第一个元素上避免注释丢失按JSON.stringify去重联合成员注释注明这是hacky way to deduplicate union members。九、打印输出把 AST 渲染为类型字符串src/printAST.ts 定义了完整的打印器printTypeAlias输出/** 注释 */\ntype 别名 类型数组T[]若元素是联合则加括号(T | U)[]printAndMaybeParenthesize对象{\nprop: T;\n[k: string]: T}属性间用分号连接并强制换行注释说明这样能让 Prettier 稳定地按多行输出元组[T0,T1,...T[]]元素逐个打印含各自注释展开元素打印为...T[]联合每个成员前加/** 注释 */ |成员排序后按\n连接整行以空格开头因此快照中出现| a的样式。十、错误边界两种明确的异常src/errors.ts 定义了两种错误均携带完整的目标 schema JSON 以便排查NotSupportedError遇到当前不支持的特性如allOf、patternProperties、无类型且无$ref/enum的 schema、多类型数组、单类型数组配additionalItems、enum 中的null/数组UnexpectedError遇到不应发生的内部不一致如缺失items、maxItems与 items 数量矛盾、$ref找不到对应定义错误信息会列出所有已注册的 ref 路径。十一、在仓库中的真实应用schema-snapshots 工作流eslint-plugin 的 schemas.test.ts 展示了完整的落地用法遍历../src/rules/index.js导出的全部规则将ruleDef.meta.schema用 Prettier 格式化后写入快照的# SCHEMA:段对 enum 数组与对象属性做排序以保证跨平台稳定调用schemaToTypes(ruleDef.meta.schema)同样用 Prettier 格式化后写入# TYPES:段用toMatchFileSnapshot与 schema-snapshots/ 下的.shot文件比对从而在 CI 中保证schema 变更必须同步更新类型快照。以no-unused-vars.shotpackages/eslint-plugin/tests/schema-snapshots/no-unused-vars.shot为例其生成的类型节选type Options [ | local | { /** Whether to check all, some, or no arguments. */ args?: | all | none | after-used; argsIgnorePattern?: string; /** Whether to check catch block arguments. */ caughtErrors?: | none | all; caughtErrorsIgnorePattern?: string; // ... 其余属性 } | all, ];可以看到oneOf成员被展开为联合、enum 成员被排序、description被转成内联 JSDoc、非必填属性带?。这些快照同时是规则文档展示的素材来源因此该包保证了文档里看到的类型与规则实际校验的 schema 永远一致。十二、小结何时使用与边界提醒使用场景当你需要把 ESLint 规则的 options schema 转换为可读、可文档化的 TypeScript 类型时schemaToTypes是开箱即用的工具它也是 typescript-eslint 内部保证规则 schema 与类型文档一致性的基础设施。适用前提输入必须是 JSON Schema draft v4JSONSchema4且避免使用本工具明确不支持的allOf、dependencies、patternProperties等关键字。已知取舍anyOf按联合而非严格组合语义生成maxItems 20时不再元组化单类型数组忽略minItems/maxItems$defs/definitions仅支持顶层声明——这些都是为了文档可读性与实现简洁性做出的有意设计使用前应了解这些边界。赞分享开发工具静态分析Lint代码质量【免费下载链接】typescript-eslint:sparkles: Monorepo for all the tooling which enables ESLint to support TypeScript项目地址https://gitcode.com/GitHub_Trending/ty/typescript-eslint点击查看免费下载相关推荐ESET-KeyGen与GitHub Actions集成自动化生成ESET密钥的高效方法ESET KeyGen与GitHub Actions集成自动化生成ESET密钥的高效方法 ESET KeyGen是一款功能强大的ESET杀毒软件试用密钥与账号CLIArkType代码生成如何从JSON Schema自动生成TypeScript类型定义ArkType代码生成如何从JSON Schema自动生成TypeScript类型定义 ArkType是一个强大的TypeScript运行时验证库它能够从J后端OpenAPI TypeScript自定义类型映射终极指南从JSON Schema到TypeScript类型OpenAPI TypeScript自定义类型映射终极指南从JSON Schema到TypeScript类型 openapi typescript是一个强大的开发工具代码生成后端上一篇unlazy深度解析AI智能体完成度纪律神器用可运行门控杜绝半截活下一篇codex-lb配额管理深度解析搞懂5小时与周双窗口榨干账号每一滴配额创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考