范围外发现,从 #4827(PR #5509,登记 page-header-subtitle-alias)里掉出来,不在那个 PR 里修 —— 那单的范围被 PM 限定为「仅 conversion 登记这一件事」。观察类,今天没有任何用户能碰到。
事实
packages/spec/src/conversions/walk.ts 的存在理由写在它自己的模块注释里:conversion 需要在不可变、不整树克隆的前提下走查深层集合,所以这些 walker 集中一处、只写一遍。mapFlowNodes / mapPages / mapCollection / mapDatasources 都在那里。
但 protocol-15 的 page-component-visibility-to-visibleWhen(conversions/registry.ts)是在条目内部就地展开了 pages[] → regions[] → components[] 这段 copy-on-write 走查的:约 25 行手写的 map + changed 标志 + 逐层 { ...dict, components: next }。
PR #5509 给同一段走查加了共享实现 mapPageComponents(walk.ts),但只让新条目用了它,没有回改那条已发布的条目 —— 于是同一形状的走查在同一个包里有两份。
为什么值得记一笔(以及为什么不急)
不是重复代码的洁癖问题,是漂移问题:这段走查的正确性依赖两件今天成立的事 —— PageComponentSchema 没有 children 键(嵌套组件都躺在别的组件的自由 properties 里),以及 region 级就是 page 组件的全部可达面。哪天这个前提变了(例如 page 组件长出结构化容器槽,像 flow 的 ADR-0031 region 那样),需要改的是两处,而只有一处在 walk.ts 里、会被下一个作者找到。mapFlowNodes 当年就正好走过这一遭:#4347 给它补上区域递归时,受益的是所有共用它的条目。
不急的原因也很实在:两份实现今天行为一致,各自都有 fixture 钉着,没有任何已知输入能让它们分叉。
建议处置
把 page-component-visibility-to-visibleWhen 的内联走查换成 mapPageComponents(stack, mapper)。它的 fixture pair 与 conversions.test.ts 里的专门用例都不用改 —— 行为等价,红了就说明不等价,这本身就是这次改动的验收判据。
关联:#4827 / PR #5509、#4347(mapFlowNodes 的区域递归)、ADR-0087 D2
范围外发现,从 #4827(PR #5509,登记
page-header-subtitle-alias)里掉出来,不在那个 PR 里修 —— 那单的范围被 PM 限定为「仅 conversion 登记这一件事」。观察类,今天没有任何用户能碰到。事实
packages/spec/src/conversions/walk.ts的存在理由写在它自己的模块注释里:conversion 需要在不可变、不整树克隆的前提下走查深层集合,所以这些 walker 集中一处、只写一遍。mapFlowNodes/mapPages/mapCollection/mapDatasources都在那里。但 protocol-15 的
page-component-visibility-to-visibleWhen(conversions/registry.ts)是在条目内部就地展开了pages[] → regions[] → components[]这段 copy-on-write 走查的:约 25 行手写的map+changed标志 + 逐层{ ...dict, components: next }。PR #5509 给同一段走查加了共享实现
mapPageComponents(walk.ts),但只让新条目用了它,没有回改那条已发布的条目 —— 于是同一形状的走查在同一个包里有两份。为什么值得记一笔(以及为什么不急)
不是重复代码的洁癖问题,是漂移问题:这段走查的正确性依赖两件今天成立的事 ——
PageComponentSchema没有 children 键(嵌套组件都躺在别的组件的自由properties里),以及 region 级就是 page 组件的全部可达面。哪天这个前提变了(例如 page 组件长出结构化容器槽,像 flow 的 ADR-0031 region 那样),需要改的是两处,而只有一处在 walk.ts 里、会被下一个作者找到。mapFlowNodes当年就正好走过这一遭:#4347 给它补上区域递归时,受益的是所有共用它的条目。不急的原因也很实在:两份实现今天行为一致,各自都有 fixture 钉着,没有任何已知输入能让它们分叉。
建议处置
把
page-component-visibility-to-visibleWhen的内联走查换成mapPageComponents(stack, mapper)。它的 fixture pair 与conversions.test.ts里的专门用例都不用改 —— 行为等价,红了就说明不等价,这本身就是这次改动的验收判据。关联:#4827 / PR #5509、#4347(
mapFlowNodes的区域递归)、ADR-0087 D2