@manohub/kit 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CONTRACT.md +86 -24
  2. package/bin/kit.mjs +12 -3
  3. package/package.json +1 -1
  4. package/skills/kit-migrate/references/migration-map.md +294 -294
  5. package/skills/kit-migrate/references/migration-playbook.md +188 -188
  6. package/skills/lint.mjs +500 -0
package/skills/kit-migrate/references/migration-playbook.md CHANGED
@@ -1,188 +1,188 @@
1
- # 迁移剧本
2
-
3
- `SKILL.md` 是流程骨架，本文件是**阶段细则 + 可直接抄的登记模板**。
4
- 替换对照表见 `migration-map.md`；契约条款见 `node_modules/@manohub/kit/CONTRACT.md`。
5
-
6
- > **0.6.0 起没有自动扫描了**：`kit lint` 与三条护栏已下线。本文件里原先「装护栏 → 跑出基线 →
7
- > 逐文件归零 → 撤销豁免」的机械流程，改为**按契约条款人工盘点与收口** —— 判据仍是闭集，
8
- > 但执行从「跑命令」变成「过清单」，成果必须落在应用文档上。
9
-
10
- ---
11
-
12
- ## 一、阶段 0 · 记录表（抄进应用文档，后面验收要用）
13
-
14
- ```markdown
15
- ## 改造前基线（YYYY-MM-DD）
16
-
17
- - 应用：<app 目录>；入口：<src/main.ts 或等价>
18
- - 依赖：@manohub/kit <版本> / @manohub/ui <版本> / 是否仍有 @farris/ui-vue
19
- - 页面数：路由页 <n> 个；页面内 components/ 子件 <m> 个
20
- - 用量（搜索计数）：
21
- - `App` 前缀组件名：<n> 处
22
- - `.ak-` 样式：<n> 处
23
- - `@farris/ui-vue` import：<n> 处
24
- - 命令式服务（notify / messageBox / loading / modalService）：<n> 处
25
- - 构建：`pnpm build` 产物 <大小>；构建耗时 <秒>
26
- ```
27
-
28
- **存量源判定**（决定后面按哪条路走）：
29
-
30
- | 现状 | 走法 |
31
- |---|---|
32
- | 旧版 kit（`App*` 名 + `.ak-*` 样式） | 主路径：按 `migration-map.md` 逐件替换 |
33
- | 直连底层组件库（farris）自绘页面 | 先按契约 §5 重建页面骨架，再替换组件 |
34
- | 其它 UI 库 / 全自绘 | 同上：映射表查不到的按契约重建，不要照搬旧库词汇 |
35
-
36
- ## 二、阶段 1 · 命名空间表与条款级盘点
37
-
38
- ### 命名空间表（取代旧配置里的 `prefixes`）
39
-
40
- `docs/kit-namespaces.md`：
41
-
42
- ```markdown
43
- # 类名命名空间表
44
-
45
- > 本表只回答「这个类名前缀归谁」。样式属性本身合不合规由契约 §3 L1-5 判，与本表无关。
46
- > 库锚 `[data-manohub-ui]` 恒允许、不必登记；类名 `.app-container` 是 kit 内部命名，不是跨包契约。
47
-
48
- | 应用 | 目录 | 类名前缀 | 说明 |
49
- |---|---|---|---|
50
- | <app 名> | <apps/xxx> | `<前缀>-` | <这一层是干嘛的> |
51
- ```
52
-
53
- ### 条款级盘点（取代旧「护栏基线」）
54
-
55
- 打开契约，**逐层逐条**对着代码盘，把命中记成表。条款号就用契约里的 `L0-n / L1-n / L1.5-n / L2-n / L3-n`：
56
-
57
- ```markdown
58
- ## 违规盘点（YYYY-MM-DD 迁移前）
59
-
60
- | 层 | 条款 | 命中 | 说明 |
61
- |---|---|---|---|
62
- | L0 | L0-2 容器必须有 `data-manohub-ui` | <n> | 自建容器缺锚 |
63
- | L1 | L1-5 属性白名单 | <n> | 视觉属性，翻成主题令牌后清零 |
64
- | L2 | L2-1 路由页必须用 `Page` 承载 | <n> | 路由页未用骨架 |
65
- | L3 | L3-1 import 源白名单 | <n> | 直连底层组件库 |
66
- | … | … | … | … |
67
-
68
- **合计**：<n> 条｜本批承诺收口的层：<[L2]>｜其余层待第 <N> 批
69
- ```
70
-
71
- - 盘点的是「改造前的事实」，不是「要修掉的清单」——数量本身没有对错，写清日期。
72
- - **没有配置文件要改**：承诺层与未承诺层都写在应用文档里（旧版的 `pending` / `waivedRules` 机制已退场）。
73
-
74
- ## 三、阶段 2 · 层级与批次
75
-
76
- **层序（L0 → L1 → L1.5 → L2 → L3）是收口顺序**，但**施工顺序**按「先结构、后组件、最后样式」：
77
-
78
- | 批次 | 做什么 | 本批承诺收口的层 | 未承诺（下一批起点） |
79
- |---|---|---|---|
80
- | ① 页面骨架 | `AppShell.*` → `Page.*` | **L2** | L1、L1.5、L3 |
81
- | ② 组件逐件 | 按 `migration-map.md` 换名换 prop | 加上 **L3** | L1、L1.5 |
82
- | ③ 图标 | 自绘 svg / 文字符号 → `<Icon>` | 加上 **L1.5** | L1 |
83
- | ④ 样式收口 | 删 `.ak-*`，视觉意图翻成主题令牌 | 全部（含 **L1**） | — |
84
-
85
- 只做 ① 时，就是「只迁骨架（Shell-only）」变体（见第九节）。
86
-
87
- ## 四、阶段 3 · 单文件循环
88
-
89
- ```text
90
- 读文件 → 按对照表替换 → 对照契约对应层逐条改 → 类型检查
91
- ```
92
-
93
- - 契约该层的条款与「正误对照」段是改法的直接依据；**不要自创等价写法**。
94
- - **样式违规的处理原则：能删就删**。旧 `.ak-*` 覆写多半是「当年为了补组件缺失的形态」，
95
- 新组件自带那些形态 —— 直接删；删掉后视觉不对的，才按契约 §3「局部换肤」翻成主题令牌。
96
- - 一次只改一个语义单元（一个页面 / 一个子件），改动面越小，逐层收口越好核对。
97
-
98
- ## 五、阶段 4 · 逐层收口口径
99
-
100
- | 检查 | 通过标准 |
101
- |---|---|
102
- | 已承诺的层 | 该层条款**逐条**对照代码过一遍、无命中（证据：清单里该层打勾 + 涉及文件清单） |
103
- | 未承诺的层 | 照常记录、命中数不高于阶段 1 的盘点 |
104
- | 类型 | `pnpm exec vue-tsc --noEmit` 0 错 |
105
- | 构建 | `pnpm build` 成功；产物大小与阶段 0 记录值量级一致（差异要能解释） |
106
-
107
- **「无命中」要能举证**：说某层已收口，就得说得出「哪几（十）个文件里没有它」。
108
- 说不出就说明没真过一遍 —— 0.6.0 没有退出码帮你确认。
109
-
110
- 定版例外（**不是通行证**，登记也只放行契约 §11 允许的范围）：
111
-
112
- ```markdown
113
- ## 定版文件清单（按设计稿逐像素还原，改动需人工确认）
114
-
115
- | 文件 | 设计节点 | 说明 |
116
- |---|---|---|
117
- | src/views/skill/components/skill-card.css | 0:2128 | 卡片间距与描边按设计稿还原；色值字面量只减不增 |
118
-
119
- > 注意：契约 §11 列了**登记也不放行**的几类（导入越界 / 自绘页头 / 原生控件 /
120
- > `!important` / `.mh-*` 覆写 / `:root`）—— 先读契约 §11 再登记。
121
- ```
122
-
123
- ## 六、阶段 5 · 验收清单
124
-
125
- ```markdown
126
- ## 二、验收（YYYY-MM-DD）
127
-
128
- - [ ] 契约 §7 自检清单五层逐条过完（留痕：每层勾选 + 备注）
129
- - [ ] 已承诺层的条款逐条举得出「没有它的文件清单」
130
- - [ ] `pnpm exec vue-tsc --noEmit` 0 错
131
- - [ ] `pnpm build` 成功（产物大小与阶段 0 对比：<差异及原因>）
132
- - [ ] 浏览器逐个过页面：渲染 / 交互 / 样式 / 弹层落点
133
- - [ ] 命令式提示落在应用容器内（`toast('success','ok')` 后 `[data-manohub-ui]` 内有 `.mh-toast`）
134
- - [ ] `showLoading()` → 关闭句柄能收掉（引用计数配平）
135
- - [ ] `index.html?xxx=1` 类入口已登记 `rootPathAliases`
136
- - [ ] 语言切换一处生效
137
- ```
138
-
139
- **已知缺口**（本包侧，不算漏改）：
140
-
141
- - **没有任何工具替你检查结构** —— SFC 与 TSX 一律人工过契约 §7 自检清单，并按 §5 骨架条款核对。
142
- - 组件库暂无 `DatePicker` / `Number`（契约 §8）：按替代口径顶住并记录，不得自绘。
143
-
144
- ## 七、阶段 6 · 收尾登记
145
-
146
- ```markdown
147
- ## 迁移完成（YYYY-MM-DD）
148
-
149
- - 已承诺层：<L2 / L3 / …> 逐条收口（见清单）
150
- - 未承诺层：<L1、L1.5…> 剩余 <n> 条，作为下一批起点
151
- - 定版例外：<n> 条（见定版文件清单）；无则写「无」
152
- - 命名空间表：docs/kit-namespaces.md（已建 / 无变化）
153
- - 遗留项：<列出来，并说明为什么不在本次范围>
154
- ```
155
-
156
- ## 八、已知缺口与边界
157
-
158
- | 缺口 | 影响 | 处理 |
159
- |---|---|---|
160
- | 无自动扫描 | 结构 / 样式 / 图标三层都没有机械保障 | 人工过契约 §7 清单 + 评审查各层「正误对照」 |
161
- | 组件库暂无 `DatePicker` / `Number` | 日期、数字输入要自己拼 | 契约 §8：用 `Input` 顶住 + 记录；或提缺件 |
162
- | `class` 载荷可以写任意类 | 样式纪律只兜住 CSS 侧 | 评审把关（契约 §6 L3-2：外观走语义 prop） |
163
- | 桥接层已随 farris 退场 | 不再有 `--ibp-popup-shift-*` 之类的弹层原点补偿 | 浮层一律用组件库的（`Dialog` / `Drawer` / 服务层），它们自带落点处理 |
164
-
165
- ## 九、变体路径：只迁骨架（Shell-only）
166
-
167
- 适用：本次只想把**页面结构**收口（承诺 L2），组件与样式留待下一批。
168
-
169
- ### 步骤
170
-
171
- 1. 阶段 1 的盘点里把 L1 / L1.5 / L3 的命中数单独留出来（那就是下一批的起点），
172
- 应用文档里写明「本批只承诺 L2」。
173
- 2. 阶段 2 只做批次 ①（`AppShell.*` → `Page.*`），不动组件与样式。
174
- 3. 阶段 4 按分层口径验收（不要求其余层归零，但要求 **L2 逐条收口、举得出证据**）。
175
-
176
- ### 里程碑 A 验收
177
-
178
- | 检查 | 通过标准 |
179
- |---|---|
180
- | L2（20 条） | 逐条对照代码过一遍、无命中；涉及文件清单留痕 |
181
- | 其它层 | 照常记录、命中数不高于阶段 1 的盘点 |
182
- | 运行 | 页面能打开，视觉与改造前一致（这一批只动结构，视觉不该变） |
183
-
184
- ### 下一批次怎么收
185
-
186
- 1. 重新盘一次 L1 / L1.5 / L3 的命中数 —— 那是本批的起点；
187
- 2. 按 `migration-map.md` 分批替换组件（先表格 / 分页 / 表单，它们的 prop 差异最大）；
188
- 3. 每收口一层就复跑一次 §7 自检清单，能全绿再动下一层。
1
+ # 迁移剧本
2
+
3
+ `SKILL.md` 是流程骨架，本文件是**阶段细则 + 可直接抄的登记模板**。
4
+ 替换对照表见 `migration-map.md`；契约条款见 `node_modules/@manohub/kit/CONTRACT.md`。
5
+
6
+ > **0.6.0 起没有自动扫描了**：`kit lint` 与三条护栏已下线。本文件里原先「装护栏 → 跑出基线 →
7
+ > 逐文件归零 → 撤销豁免」的机械流程，改为**按契约条款人工盘点与收口** —— 判据仍是闭集，
8
+ > 但执行从「跑命令」变成「过清单」，成果必须落在应用文档上。
9
+
10
+ ---
11
+
12
+ ## 一、阶段 0 · 记录表（抄进应用文档，后面验收要用）
13
+
14
+ ```markdown
15
+ ## 改造前基线（YYYY-MM-DD）
16
+
17
+ - 应用：<app 目录>；入口：<src/main.ts 或等价>
18
+ - 依赖：@manohub/kit <版本> / @manohub/ui <版本> / 是否仍有 @farris/ui-vue
19
+ - 页面数：路由页 <n> 个；页面内 components/ 子件 <m> 个
20
+ - 用量（搜索计数）：
21
+ - `App` 前缀组件名：<n> 处
22
+ - `.ak-` 样式：<n> 处
23
+ - `@farris/ui-vue` import：<n> 处
24
+ - 命令式服务（notify / messageBox / loading / modalService）：<n> 处
25
+ - 构建：`pnpm build` 产物 <大小>；构建耗时 <秒>
26
+ ```
27
+
28
+ **存量源判定**（决定后面按哪条路走）：
29
+
30
+ | 现状 | 走法 |
31
+ |---|---|
32
+ | 旧版 kit（`App*` 名 + `.ak-*` 样式） | 主路径：按 `migration-map.md` 逐件替换 |
33
+ | 直连底层组件库（farris）自绘页面 | 先按契约 §5 重建页面骨架，再替换组件 |
34
+ | 其它 UI 库 / 全自绘 | 同上：映射表查不到的按契约重建，不要照搬旧库词汇 |
35
+
36
+ ## 二、阶段 1 · 命名空间表与条款级盘点
37
+
38
+ ### 命名空间表（取代旧配置里的 `prefixes`）
39
+
40
+ `docs/kit-namespaces.md`：
41
+
42
+ ```markdown
43
+ # 类名命名空间表
44
+
45
+ > 本表只回答「这个类名前缀归谁」。样式属性本身合不合规由契约 §3 L1-5 判，与本表无关。
46
+ > 库锚 `[data-manohub-ui]` 恒允许、不必登记；类名 `.app-container` 是 kit 内部命名，不是跨包契约。
47
+
48
+ | 应用 | 目录 | 类名前缀 | 说明 |
49
+ |---|---|---|---|
50
+ | <app 名> | <apps/xxx> | `<前缀>-` | <这一层是干嘛的> |
51
+ ```
52
+
53
+ ### 条款级盘点（取代旧「护栏基线」）
54
+
55
+ 打开契约，**逐层逐条**对着代码盘，把命中记成表。条款号就用契约里的 `L0-n / L1-n / L1.5-n / L2-n / L3-n`：
56
+
57
+ ```markdown
58
+ ## 违规盘点（YYYY-MM-DD 迁移前）
59
+
60
+ | 层 | 条款 | 命中 | 说明 |
61
+ |---|---|---|---|
62
+ | L0 | L0-2 容器必须有 `data-manohub-ui` | <n> | 自建容器缺锚 |
63
+ | L1 | L1-5 属性白名单 | <n> | 视觉属性，翻成主题令牌后清零 |
64
+ | L2 | L2-1 路由页必须用 `Page` 承载 | <n> | 路由页未用骨架 |
65
+ | L3 | L3-3 外观来源白名单 | <n> | 直连底层组件库 |
66
+ | … | … | … | … |
67
+
68
+ **合计**：<n> 条｜本批承诺收口的层：<[L2]>｜其余层待第 <N> 批
69
+ ```
70
+
71
+ - 盘点的是「改造前的事实」，不是「要修掉的清单」——数量本身没有对错，写清日期。
72
+ - **没有配置文件要改**：承诺层与未承诺层都写在应用文档里（旧版的 `pending` / `waivedRules` 机制已退场）。
73
+
74
+ ## 三、阶段 2 · 层级与批次
75
+
76
+ **层序（L0 → L1 → L1.5 → L2 → L3）是收口顺序**，但**施工顺序**按「先结构、后组件、最后样式」：
77
+
78
+ | 批次 | 做什么 | 本批承诺收口的层 | 未承诺（下一批起点） |
79
+ |---|---|---|---|
80
+ | ① 页面骨架 | `AppShell.*` → `Page.*` | **L2** | L1、L1.5、L3 |
81
+ | ② 组件逐件 | 按 `migration-map.md` 换名换 prop | 加上 **L3** | L1、L1.5 |
82
+ | ③ 图标 | 自绘 svg / 文字符号 → `<Icon>` | 加上 **L1.5** | L1 |
83
+ | ④ 样式收口 | 删 `.ak-*`，视觉意图翻成主题令牌 | 全部（含 **L1**） | — |
84
+
85
+ 只做 ① 时，就是「只迁骨架（Shell-only）」变体（见第九节）。
86
+
87
+ ## 四、阶段 3 · 单文件循环
88
+
89
+ ```text
90
+ 读文件 → 按对照表替换 → 对照契约对应层逐条改 → 类型检查
91
+ ```
92
+
93
+ - 契约该层的条款与「正误对照」段是改法的直接依据；**不要自创等价写法**。
94
+ - **样式违规的处理原则：能删就删**。旧 `.ak-*` 覆写多半是「当年为了补组件缺失的形态」，
95
+ 新组件自带那些形态 —— 直接删；删掉后视觉不对的，才按契约 §3「局部换肤」翻成主题令牌。
96
+ - 一次只改一个语义单元（一个页面 / 一个子件），改动面越小，逐层收口越好核对。
97
+
98
+ ## 五、阶段 4 · 逐层收口口径
99
+
100
+ | 检查 | 通过标准 |
101
+ |---|---|
102
+ | 已承诺的层 | 该层条款**逐条**对照代码过一遍、无命中（证据：清单里该层打勾 + 涉及文件清单） |
103
+ | 未承诺的层 | 照常记录、命中数不高于阶段 1 的盘点 |
104
+ | 类型 | `pnpm exec vue-tsc --noEmit` 0 错 |
105
+ | 构建 | `pnpm build` 成功；产物大小与阶段 0 记录值量级一致（差异要能解释） |
106
+
107
+ **「无命中」要能举证**：说某层已收口，就得说得出「哪几（十）个文件里没有它」。
108
+ 说不出就说明没真过一遍 —— 0.6.0 没有退出码帮你确认。
109
+
110
+ 定版例外（**不是通行证**，登记也只放行契约 §11 允许的范围）：
111
+
112
+ ```markdown
113
+ ## 定版文件清单（按设计稿逐像素还原，改动需人工确认）
114
+
115
+ | 文件 | 设计节点 | 说明 |
116
+ |---|---|---|
117
+ | src/views/skill/components/skill-card.css | 0:2128 | 卡片间距与描边按设计稿还原；色值字面量只减不增 |
118
+
119
+ > 注意：契约 §11 列了**登记也不放行**的几类（导入越界 / 自绘页头 / 原生控件 /
120
+ > `!important` / `.mh-*` 覆写 / 令牌名拼错）—— 先读契约 §11 再登记。
121
+ ```
122
+
123
+ ## 六、阶段 5 · 验收清单
124
+
125
+ ```markdown
126
+ ## 二、验收（YYYY-MM-DD）
127
+
128
+ - [ ] 契约 §7 自检清单五层逐条过完（留痕：每层勾选 + 备注）
129
+ - [ ] 已承诺层的条款逐条举得出「没有它的文件清单」
130
+ - [ ] `pnpm exec vue-tsc --noEmit` 0 错
131
+ - [ ] `pnpm build` 成功（产物大小与阶段 0 对比：<差异及原因>）
132
+ - [ ] 浏览器逐个过页面：渲染 / 交互 / 样式 / 弹层落点
133
+ - [ ] 命令式提示落在应用容器内（`toast('success','ok')` 后 `[data-manohub-ui]` 内有 `.mh-toast`）
134
+ - [ ] `showLoading()` → 关闭句柄能收掉（引用计数配平）
135
+ - [ ] `index.html?xxx=1` 类入口已登记 `rootPathAliases`
136
+ - [ ] 语言切换一处生效
137
+ ```
138
+
139
+ **已知缺口**（本包侧，不算漏改）：
140
+
141
+ - **没有任何工具替你检查结构** —— SFC 与 TSX 一律人工过契约 §7 自检清单，并按 §5 骨架条款核对。
142
+ - 组件库暂无 `DatePicker` / `Number`（契约 §8）：按替代口径顶住并记录，不得自绘。
143
+
144
+ ## 七、阶段 6 · 收尾登记
145
+
146
+ ```markdown
147
+ ## 迁移完成（YYYY-MM-DD）
148
+
149
+ - 已承诺层：<L2 / L3 / …> 逐条收口（见清单）
150
+ - 未承诺层：<L1、L1.5…> 剩余 <n> 条，作为下一批起点
151
+ - 定版例外：<n> 条（见定版文件清单）；无则写「无」
152
+ - 命名空间表：docs/kit-namespaces.md（已建 / 无变化）
153
+ - 遗留项：<列出来，并说明为什么不在本次范围>
154
+ ```
155
+
156
+ ## 八、已知缺口与边界
157
+
158
+ | 缺口 | 影响 | 处理 |
159
+ |---|---|---|
160
+ | 无自动扫描 | 结构 / 样式 / 图标三层都没有机械保障 | 人工过契约 §7 清单 + 评审查各层「正误对照」 |
161
+ | 组件库暂无 `DatePicker` / `Number` | 日期、数字输入要自己拼 | 契约 §8：用 `Input` 顶住 + 记录；或提缺件 |
162
+ | `class` 载荷可以写任意类 | 样式纪律只兜住 CSS 侧 | 评审把关（契约 §6 L3-2：外观走语义 prop） |
163
+ | 桥接层已随 farris 退场 | 不再有 `--ibp-popup-shift-*` 之类的弹层原点补偿 | 浮层一律用组件库的（`Dialog` / `Drawer` / 服务层），它们自带落点处理 |
164
+
165
+ ## 九、变体路径：只迁骨架（Shell-only）
166
+
167
+ 适用：本次只想把**页面结构**收口（承诺 L2），组件与样式留待下一批。
168
+
169
+ ### 步骤
170
+
171
+ 1. 阶段 1 的盘点里把 L1 / L1.5 / L3 的命中数单独留出来（那就是下一批的起点），
172
+ 应用文档里写明「本批只承诺 L2」。
173
+ 2. 阶段 2 只做批次 ①（`AppShell.*` → `Page.*`），不动组件与样式。
174
+ 3. 阶段 4 按分层口径验收（不要求其余层归零，但要求 **L2 逐条收口、举得出证据**）。
175
+
176
+ ### 里程碑 A 验收
177
+
178
+ | 检查 | 通过标准 |
179
+ |---|---|
180
+ | L2（20 条） | 逐条对照代码过一遍、无命中；涉及文件清单留痕 |
181
+ | 其它层 | 照常记录、命中数不高于阶段 1 的盘点 |
182
+ | 运行 | 页面能打开，视觉与改造前一致（这一批只动结构，视觉不该变） |
183
+
184
+ ### 下一批次怎么收
185
+
186
+ 1. 重新盘一次 L1 / L1.5 / L3 的命中数 —— 那是本批的起点；
187
+ 2. 按 `migration-map.md` 分批替换组件（先表格 / 分页 / 表单，它们的 prop 差异最大）；
188
+ 3. 每收口一层就复跑一次 §7 自检清单，能全绿再动下一层。