@alexgorbatchev/typescript-ai-policy (英语)

共享 氧化剂 财务报告和审定财务报表 氧化剂 配置希望AI协助的TypeScript保持严格,可预见,以及 可审查.

这个包裹是故意的 它不尝试是一个灵活的样式预设. 它编码仓库合同 就像林特规则 生成和修改的代码 土地形状,你可以信任.

这是给谁的

如果您想要使用此软件包 :

• 在 AI 生成或 AI 修改后的类型Script 上执行更严格的结构
• 用机器可检查规则取代手瓦编码指导
• 保持反应、测试、定着和类型边界
• 一份共用政策包 横跨仓库

如果您想要一个松散的可选样式规则集合,这个软件包是错误的工具.

你得到的东西

• 共享 Oxfmt 配置
• 共享 Oxlint 配置
• 自定义 @alexgorbatchev/* 用于常见 LLM 失败模式的规则
• 直接修复说明书
• 页:1 typescript-ai-policy 带 CLI 的 fix-semantic 财务报告和审定财务报表 guidance 命令

上游Oxlint, TypeScript, 和Jest规则作为基线正确性护栏继续启用.

安装

bun add -d @alexgorbatchev/typescript-ai-policy oxfmt oxlint

如果你想用这个 typescript-ai-policy fix-semantic 命令,安装其可选的对等依赖 :

bun add -d typescript@npm:@typescript/typescript6@latest @typescript/native@npm:typescript@latest

这个 typescript 化名提供语义修正所使用的TypeScript 6编译器API. 这个 @typescript/native 别名提供TypeScript 7编译器和LSP后端. 帮帮我, check,以及 guidance 工作时没有编译器.

出版的邮包船编译 .js 运行时间文件加 .d.ts 声明。 安装 typescript-ai-policy CLI通过 Bun 运行,所以 Bun 需要执行套件安装的 bin. 这个 fix-semantic 命令不变 期望在消费项目中安装其可选对等依赖,同时 guidance 只读 已公布的政策元数据.

快开始

oxfmt.config.ts

import createOxfmtConfig from "@alexgorbatchev/typescript-ai-policy/oxfmt-config";

export default createOxfmtConfig(() => ({
  ignorePatterns: ["vendor/**"],
}));

oxlint.config.ts

import createOxlintConfig from "@alexgorbatchev/typescript-ai-policy/oxlint-config";

export default createOxlintConfig({
  ignorePatterns: ["coverage"],
  rules: {
    "no-var": "error",
  },
});

两个配置入口都具有出口工厂的功能. createOxlintConfig(...) 接受配置对象或 召回那个返回一个。 返回的用户配置已深入 在此之前 共享默认,所以共享 政策仍在相互冲突的密钥上取胜.

对奥克林特来说,消费配置是仅限扩展的. 如果提供的配置试图重新定义一个共享规则, 而不是让仓库静静地削弱下游的政策.

createOxlintConfig 还出口 FilenameStyle 作为从 @alexgorbatchev/typescript-ai-policy/oxlint-config。 。 。 . createOxlintConfig 保留 filenameStyle 此密钥 软件包的共享文件名策略。 默认为 FilenameStyle.PascalCase,执行 ComponentName.tsx 财务报告和审定财务报表 useThing.ts{,x} 所有权文件。 设定 filenameStyle: FilenameStyle.DashCase 执行 component-name.tsx 财务报告和审定财务报表 use-thing.ts{,x} 相反:

import createOxlintConfig, { FilenameStyle } from "@alexgorbatchev/typescript-ai-policy/oxlint-config";

export default createOxlintConfig({
  filenameStyle: FilenameStyle.DashCase,
  ignorePatterns: ["coverage"],
});

当您手动运行 Oxlint 时, 使用 Bun 启动 CLI :

bun --bun oxlint .

处理 bun --bun oxlint ... 作为本套装以及使用 这些类型脚本配置入口.

执行什么

从一个角度看,共同政策执行:

• 基线护栏,如严格平等,无 any,并填写完整的反钩依赖清单(react/exhaustive-deps 作为错误)
• 组件所有权文件,可以导出一个主要组件或一个多部分组件家族,外加只类型二级API,并生活在条形体下 components/, (中文(简体) ), templates/,或 layouts/ 使用目录 ComponentName.tsx 默认或 component-name.tsx 何时 filenameStyle: FilenameStyle.DashCase 已配置
• 完全导出主要文件的钩形所有文件 use* 钩子,加上唯一型的二级API, 并且作为直生子生活 hooks/useThing.ts[x] 默认文件或 hooks/use-thing.ts[x] 何时 filenameStyle: FilenameStyle.DashCase 已配置
• 钩自有 .tsx 文件使用钩子合同和匹配测试,而不是组件命名、测试标识或故事书所有权要求;共享原始JSX和直接样式边界仍然适用
• 仅JSX 反应组件代码而非 React.createElement(...)
• 在兄弟关系下匹配组件所有权文件的故事簿文件 stories/ 目录, 故事支持文件仅限于 helpers.ts[x], (中文(简体) ), fixtures.ts[x],或 fixtures/
• 故事书项目支助 .tsx 直接或嵌入的文件 .storybook/ 路径而不将其作为组件所有权文件处理
• 在兄弟关系下匹配钩子所有权文件的测试文件 __tests__/ 目录, 保存源底名和扩展名( e).ts 钩子需要 .test.ts· ; .tsx 钩子需要 .test.tsx),测试支持文件仅限于 helpers.ts[x], (中文(简体) ), fixtures.ts[x],或 fixtures/
• 已键入故事本元件, 带有相干标题, 已键入故事导出, 并需要 play 函数
• 确定性成分测试标识,例如: ComponentName 财务报告和审定财务报表 ComponentName--child,加上出口所有权部件所需的根试码
• canonical 组件所有权目录 (components/, (中文(简体) ), templates/, (中文(简体) ), layouts/作为唯一的产品 .tsx 表面允许生化 JSX 或直接通过 className 编号 : style 道具,包含用于故事/测试支持的文件角色和故事本 .storybook/ 支持文件
• 运行时代码、测试代码、故事代码和固定代码之间的严格界限,包括不从 __tests__/ 进入运行时代码,没有从 constants.ts; 擦去专用的指定进口 typeof 允许查询值
• 测试文件纪律:没有跳过或聚焦测试,没有条件逻辑,没有 throw,没有模块嘲笑,没有测试文件导出,也没有内置固定绑定
• fixture 纪律: 犬类定位,单一入站,限制出口命名和出口类型,没有本地类型声明,以及犬类固定进口路径
• 明确文件的类型/价值所有者规则,例如 index.ts, (中文(简体) ), constants.ts,以及 types.ts
• 严格的类型和职能合同规则: I* 只有接口,没有 I* 类型别名,没有直接接口到类型通过别名,没有小的属性选择器转发包,其名称仅重复所选属性,没有内线类型导入或内线结构类型表达式,以及缩进多行模板文字
• 一种政策立场,即内在的不可否认的评论不能成为纠正违法行为的可以接受的逃生口

Lint- disable 评论不是一个有效的修复策略

代理商和开发商要直接满足共享政策,而不是在当地通过评论压制共享政策,例如 // oxlint-disable-next-line 或者说 /* oxlint-disable */。 。 。 .

这个软件包明文禁止对ESLint和Oxlint进行线性 lint-disable 注释. 把这当作一个 硬政策信号而不是作为绕道的障碍。 执行策略假设你将解决 潜在的违反合同 而不是压制警告.

重要的合同很简单:

• 不使用内置的 lint- disable 注释来绕过共享策略
• 修补代码,使其符合规则
• 如果政策本身是错误的,则故意改变共享软件包,而不是绕过本地

故事书是反应组件合同

对于反应组件,这一政策是故意的 第一个故事。 。 。 .

每个组件所有权文件必须有一个匹配的故事书文件,每个故事元必须被打入并使用一个 软件包相对 title,每个导出的故事必须输入并包含 play 函数,除非 !test 删除 内置的故事书 test 那个故事的标签。 在实际操作中,这让"故事书"成为了犬科文物 组件行为 :

• 同一故事层可以回溯 CI 交互覆盖
• 同样的故事 也作为人类的视觉参考
• 组件结构和组件核查停留在一个地方,而不是漂移到单独的特设测试文件之间

A 类 main.tsx 外部组件所有权目录是当客户端没有输出或本地端时的 React 客户端入口 通过进口直接申报JSX react-dom/client createRoot 调用( 链条 或指定给本地根). 这种靴子不需要组件导出、所有权目录或故事. 所有其他政策检查仍然适用;仅文件名并不能将文件作为切入点.

这个软件包是 没有 为您连接您的 CI , 但是它确实执行 Storybook 驱动所需的寄存器形状 构成部分核查.

预期布局形状

该政策在您的特征树内执行 Canonical 角色目录 .

这意味着寄存器可以选择它们的特性边界,但是组件,故事,钩子,和测试文件仍然有 固定所有权地点:

• 组成部分所有权 .tsx 文件在 components/, (中文(简体) ), templates/,或 layouts/
• 允许在这些组成部分所有权区内设立巢穴子目录,但不需要
• 非故事、非测试 .tsx 文件不得使原始的内在JSX像 <div>, (中文(简体) ), <span>,或 <p> 除非 文件居住于其中之一的犬类成分所有权区
• 直接 className 财务报告和审定财务报表 style 道具只允许在这些犬类组件所有权区域内的文件的原始HTML元素上使用. 自定义/资本化组件不得接受 className 或者说 style 任何文件中的道具.
• 故事书项目支助 .tsx 文件在 .storybook/*.tsx 财务报告和审定财务报表 .storybook/**/*.tsx 非组件所有权 文件,并可能使用本地童话书收尾标记
• 故事文件生活在兄弟关系之下 stories/ 目录,该区域被保留给 *.stories.tsx, (中文(简体) ), helpers.ts[x], (中文(简体) ), fixtures.ts[x],以及 fixtures/
• 导出名称起始的运行时钩 use 生活在直接子女之下 hooks/ 所有权文件
• 测试文件位于兄弟关系下 __tests__/ 目录,该区域被保留给 *.test.ts[x], (中文(简体) ), helpers.ts[x], (中文(简体) ), fixtures.ts[x],以及 fixtures/
• 定期申报 fixtures.ts[x] 下级 stories/ 或者说 __tests__/;目录条目使用纯 fixtures/index.ts 装有无外号出口的桶或自筑的空通卡 fixtures.ts[x] 声明文件
• 无扩展固定管源需要匹配 .ts 或者说 .tsx 声明文件; 目录桶跳不是声明所有权
• 从运行时桶、助手或另一个固定区域直接相对固定再出口,对命名语法和通配符语法都拒绝;检查不解决包别名或中转模块图表
• 组件文件名匹配导出 PascalCase 组件名称 ComponentName.tsx 默认形式,或 component-name.tsx 何时 filenameStyle: FilenameStyle.DashCase 已配置
• 钩头文件名与导出的文件相符 use* 钩形名称 useThing.ts[x] 默认形式,或 use-thing.ts[x] 何时 filenameStyle: FilenameStyle.DashCase 已配置
• index.ts 仅用于纯管再出口
• constants.ts 仅用于运行时间值
• types.ts 仅用于类型导出

示例

feature/
├── components/
│   ├── AccountPanel.tsx
│   └── stories/
│       └── AccountPanel.stories.tsx
└── hooks/
    ├── useAccount.ts
    └── __tests__/
        └── useAccount.test.ts

最小配置 :

import createOxlintConfig from "@alexgorbatchev/typescript-ai-policy/oxlint-config";

export default createOxlintConfig();

有了这个配置,路线,页面,特色视图,以及其他产品 .tsx 文件必须渲染导入的组件 而不是原始的 DOM 标记,它们不能直接通过 className 或者说 style 道具来. 原始内在JSX和直接 风格道具在 Canonial 组件所有区、 故事/ 测试支持文件或故事本中保留原始 HTML 元素 .storybook/ 支持文件。 通过 className 或者说 style 各地禁止自定义组件道具.

在消耗性存储器中,使用 typescript-ai-policy check 通过您的软件包管理器本地二进制运行器 执行共享的物料, 并检查该还款.

当一个消耗的带子支持环境注入时,配置这个带子以运行外壳命令 AGENT=1 这样 typescript-ai-policy check 以代理格式发布 oxlint 自动输出代理工作流程及更多 节能符号输出 .

CLI 工具化

软件包包括 typescript-ai-policy CLI(英语:CLI). 内容 fix-semantic 命令由 tsc --lsp --stdio,以及 联合国 guidance 命令打印 本地权威修复指南 @alexgorbatchev/* 规则作为包裹 以粗体规则名或JSON来标注倒弹列表.

套件安装使用量 :

• bun run typescript-ai-policy -- check 运行软件包,在消耗库中检查。 当消耗带配置为注入时 AGENT=1,则 oxlint step 自动为代理工作流程使用代理格式化,并使用更具有符号效率的输出.
• bun run typescript-ai-policy -- guidance ——将软件包为AI代理披露的已公布规则指南打印为用粗体规则名所包裹的Markdown子弹列表.
• bun run typescript-ai-policy -- guidance --json - 打印与 JSON 对象相同的已公布规则指南 ruleName 并获决 guidance 字段.
• bun run typescript-ai-policy -- fix-semantic <target-directory> ——用这个包的政策配置运行Oxlint,收集支持的诊断,对目标目录应用语义修正.
• bun run typescript-ai-policy -- fix-semantic <target-directory> --dry-run ——在不变异文件的情况下打印计划中的语义固定范围.

发表 guidance 输出是包级修复指导,而不是一个特定存储器的配置垃圾堆. 特工应该 仍然检查 消费存储器的实际 oxlint.config.ts 在另一个文档中应用特定文档指导之前 密码库.

仓库开发命令记录在 一般事务人员(其他职等)。 。 。 .

今天,该框架采用了三个保守的语义修饰:

• @alexgorbatchev/interface-naming-convention ——将寄存器所属接口更名为需要的接口 I* 格式,当现有名称能够安全地正常化时.
• @alexgorbatchev/no-i-prefixed-type-aliases ——重命名寄存器自有类型别名以放弃界面样式 I* 前缀,当诊断解析为混凝土类型别名时.
• @alexgorbatchev/test-file-location-convention - 移动错误 .test.ts 编号 : .test.tsx 将文件输入兄弟会 __tests__/ 目录为 __tests__/basename.test.ts[x] 并重写所移动文件的相对导入.

命令和后端外形仍然有意通用,因此以后可以添加更多有规则支撑的语义操作.

学多点

• src/oxlint/README.md ——规则全目录,原理和实例
• AGENTS.md ——为从事此软件包工作的编码代理提供仓库指导

本地软件包设置

此寄存器也会在根上消耗自己的共享配置 :

• oxfmt.config.ts
• oxlint.config.ts