@cratis/ 组件. migrator

A 第3部分编码库更新为第4部分公共合同。 它会将根命名空间移动到明确的子路径导入,取代已贬值的按钮外观道具,并将遗留的事件-收发回调改为语义值回调. CLI在内部使用语法感知码器,但每个指令都因其所执行的迁移而取名,可以独立运行,并具有同位素. 部件4只将包式供应商设置放在根上;每个部件都是从其明显的子路径导入的(@cratis/components/Canvas(例如,第1行) 伴侣 @cratis/eslint-plugin-components 软件包 no-root-barrel-import 规定一旦消费者迁移就执行.

软件包在 npm 上发布,并以与 @cratis/components (4.0.0 继续). 运行它 npx, (中文(简体) ), pnpm dlx,或 yarn dlx 如下所示 应用程序运行时间依赖 。 此寄存器的撰稿人可以运行工作空间脚本 直接换成.

已发布的软件包是 仅限CLI 工具。 它的公开表面是记录 cratis-components-* 可执行名称(+) ./package.json 用于工具元数据; lib/, (中文(简体) ), scripts/,单个变换是执行细节,被包输出图所屏蔽. 不要从应用程序代码导入它们, 或在其上构建自定义的迁移 API .

remove-root-namespace-imports

一个以TypeScript编译器API上所建的以AST为主的同能编码器. 出版的CLI 带来自己的 typescript 运行时间依赖,所以它的解析器不依赖于消费者 应用程序的 TypeScript 版本。 它重写静态 import 声明和名称 export … from 只有再出口;它永远不会猜测,并报告它不会触及的每一个案件.

重写什么

一个名字 export … from '@cratis/components' 再出口遵循的规则与 输入,因为两个方向的转换同样明确:出口 名称识别一个特定的命名空间(或经批准的设置符号),因此代码可以 重写而无猜想. 仅a 通配符 整个包裹再出口—— export * from '@cratis/components' 或者说 export * as X from '@cratis/components' 留下来 不支持, 出于同样原因, 全包命名空间导入仍然不支持 : 见 它拒绝猜测什么。 。 。 .

历史 CommandStepper 根命名空间是一个特殊的情况: 它别名了完整 CommandDialog 模块。 因此,代码模块将其映射到 @cratis/components/CommandDialog,保留第4部分保留成员的模块身份。 它不能恢复一个已删除的模块导出, 如意外 CommandStepperContent 表面。 只需要独立组件的新代码 import { CommandStepper } from '@cratis/components/CommandStepper' (或等同再出口).

一个导入或再导出的多命名空间成为每个命名空间的子路径声明 :

// Before
import { Canvas, Common } from '@cratis/components';

// After
import * as Canvas from '@cratis/components/Canvas';
import * as Common from '@cratis/components/Common';

混合进口或再出口既命名一个经批准的设置符号,又命名空间被分割—— 设置符号保留在根上,命名空间移动到它的子路径:

// Before
import { CratisComponentsProvider, Canvas } from '@cratis/components';

// After
import { CratisComponentsProvider } from '@cratis/components';
import * as Canvas from '@cratis/components/Canvas';

重新运行自输出的编码器是无操作的——它只匹配导入或 命名后再导出其模块指定符是准确的 @cratis/components (或 --package ),因此,已经迁移的子路径导入或再出口永远不会被重审.

完整的命名空间 ~ 子路径图, 已知已删除的组件 3 相容导出, 以及经批准的- root- symbol 允许列表 lib/namespaceMap.js,反射为 ESLint/lib/rootNamespaceMap.js。当一个命名空间子路径、去除边界或设置符号改变时,贡献者必须一起更新两个软件包。 套件共享寄存器发布版本;等分谱防止了他们的迁移合同漂移.

它拒绝猜测什么

每一个都完全没有受到影响,而是报告为诊断:

• 整个软件包的命名空间导入—— import * as Components from '@cratis/components';。 。 。 . 稍后的子路径 Components.X 无法从 导入.
• 默认导入.. import Components from '@cratis/components';。软件包没有 默认导出 .
• 仅附带效果的导入 import '@cratis/components';。没有义务推断 子路径从.
• 既非经批准的设置符号, 也非已知名称空间的符号的命名导入 (例如成员喜欢: Button 仅存在 内部 一个命名空间, 不在 词根). 整个导入语句没有被触及,而不是部分迁移.
• 构成部分3.6 Compatibility 名称空间及其直接通过输出。 他们 4组件没有兼容性 子路径,所以变换使语句未受影响,并指示消费者 键入 Cratis 部件.
• TypeScript 导入任务 - import Components = require('@cratis/components');。 。 。 . 这就是整个软件包命名空间,所以后来的成员访问像 import * as。 。 。 .
• 一个动态 import('@cratis/components') 或一个普通JS require('@cratis/components'), (中文(简体) ), 档案里的任何地方.
• 整个包的通配符再出口—— export * from '@cratis/components'; - 或一个 整个软件包的命名空间再导出 - export * as Components from '@cratis/components';。两者都与整包命名空间导入完全一样模糊: 单靠再出口无法确定后期的每一个准入需求。 A 类 名称 再出口(export { Canvas } from '@cratis/components';)不在这份清单中—— 见 重写什么。 。 。 .

现有的子路径进口和再出口@cratis/components/Canvas,.)从不被触动—— 狭义的子路径消费者 被保留在原样.

使用

被包装的 CLI 需要更新的节点. js 20 或 更新并带来自己的 TypeScript 解析器; 它确实 不依赖于消费者应用程序的TypeScript版本. 它扫描了JavaScript, JSX, TypeScript, 和 TSX 来源, 包括 .mjs, (中文(简体) ), .cjs, (中文(简体) ), .mts,以及 .cts 变相. 构成部分 3没有3.x 迁移包。 4 迁移至 >=4 <5; 从不使用 latest。 。 。 .

在任何扫描或写入之前, CLI 验证其捆绑的相容性表, 检查它自己的 的版本 引用目录,并验证软件包在支持的 3.x 迁移源或 4.x 中 迁移目标窗口。 缺少组件、不支持的版本、陈旧的软件包元数据以及一个 无效的显示失败已关闭 . --help 在未安装组件的情况下仍然可用.

TOOLING_RANGE='^4.0.0' # Shell-safe equivalent of >=4 <5.

# Preview what would change, without writing anything:
npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-remove-root-namespace-imports --check path/to/app/src

# Apply the rewrite:
npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-remove-root-namespace-imports path/to/app/src

# Contributors to this repository can run the workspace source directly:
node Migrator/scripts/remove-root-namespace-imports.js --check Source

Pnpm和Yarn 2+项目中相同的有界限的软件包工作:

pnpm dlx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-remove-root-namespace-imports --check path/to/app/src
yarn dlx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-remove-root-namespace-imports --check path/to/app/src

引用含有空格的任何路径。 可执行示例中故意不使用角括号占位符,因为 <...> 是 shell 输入重定向语法.

当发现不支持的大小写时( 与 --check 或者没有.. 他们总是需要一个人类),和,在 --check 只有模式,当支持的重写有 尚未应用。 运行 --help 用于完整选项列表.

在运行了代码模块后, 运行项目自己的构建/ lint/ test 闸门—— 只运行代码模块 执行机械导入/再出口重写;它不试图修正任何结果 未使用导入, 也不知道您是否使用命名空间成员( q)Canvas.Foo还是 存在于该子路径.

button-variant-tone

cratis-components-button-variant-tone 决定 Button 进口的JSX装订品,包括别名和 Common.Button 名称空间访问,来自 @cratis/components/Common它运用了运行时间遗留的优先权(link → text → outlined → solid并替换已贬值的道具:

一个字形 severity='contrast' 还收到 variant='solid' 只有在没有明显的新的变体或更强大的真正遗产变体适用的情况下。 一个字面的新 variant, (中文(简体) ), tone,或 shape 胜出和它多余的后遗症被删除.

// Safe rewrite
<Button outlined rounded severity='warn' />
// becomes
<Button variant='outline' shape='pill' tone='caution' />

变身从不通过JSX来猜测传播,动态后遗症值,重复道具,或与后遗症道具相冲突的未知新道具表达. 它使不确定的道具组保持原状,报告,并增加一个语法安全 TODO(cratis-codemod) 注释。 随后的运行并不重复该注释.

// Refused and reported
<Button text={appearance.text} severity={appearance.severity} />

change-handler

cratis-components-change-handler 解决组件拥有的 JSX 标识符,从 @cratis/components/Dropdown, (中文(简体) ), @cratis/components/CommandForm,以及 @cratis/components/CommandForm/fields。它会将结构上证明的单个转发回调单独改写 Dropdown 和命令表格字段 onValueChange 道具 :

// Before
<Dropdown onChange={(event) => setRole(event.value)} />
// After
<Dropdown onChange={(value) => setRole(value)} />

对于组件 4 命令格式字段, 编码器会离开 onChange 并报告一个可操作的诊断,而不是改变回调。 弧线 asCommandFormField 包装不显示 onChange 作为元件 4 中的字段道具,所以保留属性即使重写回调也会产生TS2322. 将其副作用移动到附件 CommandForm是因为 onFieldChange(command, fieldName, oldValue, newValue, validationInfo?) 调用。 遗产 onValueChange 已证实事件有效载荷的字段回调重写为语义值; 已语义 onValueChange 召回无所动. 这个 第3至4部分 移徙指南 包括这个案子.

多声明、多用途、错误的负载、与默认/撤销的分解、以及依赖本地活动的回调都遭到拒绝、报告和一次附加说明:

// Refused and reported: the host still depends on the old event object
<Dropdown
    onChange={(event) => {
        audit(event.originalEvent);
        setRole(event.value);
    }}
/>

运行迁移序列

对所有3个指令使用有界组件4工具列. 建议的来源/目标顺序是:

1. 包含第3部分>=3 <4)安装,预览和应用了root-import变换. 它的子路径存在于两个大都.
2. 运行组件 3 出入口并检查仅导入的更改 .
3. 核心升级到构成部分4(^4.0.0) (中文(简体) ).
4. 预览并应用按钮外观,然后进行更改-处理器迁移;这些生成组件 4 源.

飞行前还接受组件4目标窗口,这样在升级后可以恢复根变. 它不接受其他核心专业。 在应用前预览每个步骤 :

TOOLING_RANGE='^4.0.0'

npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-remove-root-namespace-imports --check path/to/app/src
npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-remove-root-namespace-imports path/to/app/src

npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-button-variant-tone --check path/to/app/src
npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-button-variant-tone path/to/app/src

npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-change-handler --check path/to/app/src
npx --package "@cratis/components.migrator@$TOOLING_RANGE" \
  cratis-components-change-handler path/to/app/src

永不替换 latest; 继续在内部使用工具 >=4 <5. Tooling包与 Core 共享寄存器的放出版本,被捆绑范围外加被捆绑的显示飞行前执行相容的迁移窗口而无需精确的patch耦合. 两种新的 CLI 都需要 Node.js 20 或更新, 捆绑自己的 TypeScript 编译器依赖性, 扫描 .js, (中文(简体) ), .jsx, (中文(简体) ), .mjs, (中文(简体) ), .cjs, (中文(简体) ), .ts, (中文(简体) ), .tsx, (中文(简体) ), .mts,以及 .cts 递归支持 --package <name>,然后退出非零,用于等待检查模式编辑或任何被拒绝的个案。 审查所有诊断和 TODO(cratis-codemod),然后运行 消耗项目的东西, 油漆,类型检查,测试,和生产建设.

贡献者源指令为:

node Migrator/scripts/button-variant-tone.js --check Source
node Migrator/scripts/change-handler.js --check Source

测试

cd Migrator && yarn test

每个受支持和无支持的根进口案的仓库固定装置均在 Migrator/test/fixtures, (中文(简体) ), 各作为 input.ts编号 :expected.ts 双对 (input.ts 财务报告和审定财务报表 expected.ts 与 不支持的情况,因为没有什么应该改变。 按钮和换接器转换使用 input.tsx编号 :expected.tsx 下对 Migrator/test/button-fixtures 财务报告和审定财务报表 Migrator/test/change-handler-fixtures。 。 。 .