@moheng-design/ui-skill 1.0.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.
- package/README.md +227 -0
- package/bin/cli.js +35 -0
- package/bin/lib/audit.mjs +138 -0
- package/bin/lib/feedback.mjs +82 -0
- package/bin/lib/install.mjs +61 -0
- package/bin/lib/paths.mjs +47 -0
- package/bin/lib/upgrade.mjs +86 -0
- package/eslint/index.js +94 -0
- package/eslint/lib/factories.js +313 -0
- package/eslint/lib/match.js +188 -0
- package/eslint/lib/tiers.js +27 -0
- package/generated/SKILL.md +696 -0
- package/generated/contracts.json +9270 -0
- package/generated/mappings.schema.json +333 -0
- package/generated/plugin-data.js +6994 -0
- package/generated/reference.md +5651 -0
- package/generated/rules.json +3864 -0
- package/generated/skills/moheng-ui-audit/SKILL.md +66 -0
- package/generated/skills/moheng-ui-bootstrap/SKILL.md +109 -0
- package/generated/skills/moheng-ui-feedback/SKILL.md +65 -0
- package/generated/skills/moheng-ui-page/SKILL.md +75 -0
- package/generated/skills/moheng-ui-review/SKILL.md +55 -0
- package/generated/skills/moheng-ui-upgrade/SKILL.md +40 -0
- package/generated/unenforced.json +57 -0
- package/handwritten/anti-patterns.md +239 -0
- package/handwritten/canvas-model.md +98 -0
- package/handwritten/conventions.md +2082 -0
- package/handwritten/skills/audit.md +54 -0
- package/handwritten/skills/bootstrap.md +99 -0
- package/handwritten/skills/feedback.md +63 -0
- package/handwritten/skills/page.md +44 -0
- package/handwritten/skills/review.md +43 -0
- package/handwritten/skills/upgrade.md +38 -0
- package/handwritten/unenforced.md +27 -0
- package/package.json +66 -0
- package/stylelint/index.js +121 -0
package/README.md
ADDED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
# @moheng-design/ui-skill
|
|
2
|
+
|
|
3
|
+
`@moheng-design/ui` 的 AI agent 支持包:**SKILL.md 负责引导,ESLint 与 stylelint 负责强制。**
|
|
4
|
+
|
|
5
|
+
两者是同一份数据的两种表达。约束若只写进 SKILL.md 而没有 lint 实现,就会造成
|
|
6
|
+
「以为约束住了、实际没有」的假象 —— 那是 [01 §1.4](../../docs/01-实施规范.md) 点名的反模式。
|
|
7
|
+
|
|
8
|
+
## 这个包是怎么来的
|
|
9
|
+
|
|
10
|
+
本包是 `@moheng-design/ui` 的**只读投影**,全部内容由生成器从组件库的两个事实来源产出:
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
@moheng-design/ui 的 contracts/*.ts ─┐
|
|
14
|
+
@moheng-design/ui 的 mappings.json ─┤
|
|
15
|
+
@moheng-design/ui 的 tokens.json ─┼─▶ scripts/generate.mjs ─▶ generated/
|
|
16
|
+
handwritten/*.md ─┘
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
生成关系**单向,永不反向**。改约束请改 `@moheng-design/ui` 的 `mappings.json` 或契约,
|
|
20
|
+
不要改 `generated/` 下的任何文件。
|
|
21
|
+
|
|
22
|
+
## 接入
|
|
23
|
+
|
|
24
|
+
### 一、拷技能进项目
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npx @moheng-design/ui-skill install
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
命令把主技能 `generated/SKILL.md` 写进 `.claude/skills/moheng-ui/`,并把
|
|
31
|
+
`generated/skills/` 下的六个附属技能各写进 `.claude/skills/<name>/`。
|
|
32
|
+
目标已存在时命令拒绝执行,加 `--force` 覆盖 —— 它不做合并。
|
|
33
|
+
|
|
34
|
+
升级 `@moheng-design/ui` 后**必须重跑本命令**。拷出去的那份不会自动更新。
|
|
35
|
+
|
|
36
|
+
### 二、接上 ESLint
|
|
37
|
+
|
|
38
|
+
```js
|
|
39
|
+
// eslint.config.js
|
|
40
|
+
import moheng from '@moheng-design/ui-skill/eslint'
|
|
41
|
+
|
|
42
|
+
export default [moheng.recommended]
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### 三、stylelint(消费方当前无需接入)
|
|
46
|
+
|
|
47
|
+
ESLint 管 JS / JSX / TS / TSX,stylelint 管 CSS。两个工具,一个来源(§7.2.1)。
|
|
48
|
+
但 CSS 侧现有的三条规则 scope 均为 `internal` —— **消费方接上只会得到一个空规则集**,
|
|
49
|
+
详见下方「stylelint 两档」。将来出现面向消费方的 CSS 规则时,接法是:
|
|
50
|
+
|
|
51
|
+
```js
|
|
52
|
+
// stylelint.config.js
|
|
53
|
+
import moheng from '@moheng-design/ui-skill/stylelint'
|
|
54
|
+
|
|
55
|
+
export default { plugins: moheng.plugins, rules: moheng.consumer }
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## 技能族:一个主技能,六个附属技能
|
|
59
|
+
|
|
60
|
+
主技能 `moheng-ui` 只覆盖一个时刻 —— agent 正在写新代码。新项目启动时、存量接入前、审查时、
|
|
61
|
+
接入后、升级时、搭页面时各是一个独立技能,各有各的触发描述。塞进主技能会让它越来越宽,
|
|
62
|
+
触发越来越不准。
|
|
63
|
+
|
|
64
|
+
| 技能 | 时刻 | 配套命令 | 手写稿 |
|
|
65
|
+
|---|---|---|---|
|
|
66
|
+
| `moheng-ui` | 写新代码 | —— | `conventions.md` 等三份 |
|
|
67
|
+
| `moheng-ui-bootstrap` | 新项目启动,定技术栈与搭建顺序 | —— | `skills/bootstrap.md` |
|
|
68
|
+
| `moheng-ui-review` | 审查 diff | —— | `skills/review.md` |
|
|
69
|
+
| `moheng-ui-audit` | 存量项目接入前 | `npx @moheng-design/ui-skill audit` | `skills/audit.md` |
|
|
70
|
+
| `moheng-ui-feedback` | 用库过程中撞到问题 | `npx @moheng-design/ui-skill feedback` | `skills/feedback.md` |
|
|
71
|
+
| `moheng-ui-upgrade` | 升级版本 | `npx @moheng-design/ui-skill upgrade --from <旧契约>` | `skills/upgrade.md` |
|
|
72
|
+
| `moheng-ui-page` | 用 Application Module 层搭页面 | —— | `skills/page.md` |
|
|
73
|
+
|
|
74
|
+
三条命令的分工是同一句话:**数字由命令算,技能只解释。** `audit` 用 `migration` 档跑
|
|
75
|
+
ESLint 并按规则 / 文件聚合,写 `moheng-audit.json`;`feedback` 扫对本库规则的
|
|
76
|
+
`eslint-disable` 与 `TODO(moheng)` 标记,写 `moheng-feedback.md` 草稿;`upgrade` 比对
|
|
77
|
+
新旧两份 `contracts.json`,写 `moheng-upgrade.md`。三者都不改源文件,也不自动提交任何东西。
|
|
78
|
+
|
|
79
|
+
附属技能的手写稿自带 frontmatter,正文用 `<!-- @generated: xxx -->` 占位符引用生成数据
|
|
80
|
+
(版本号、规则数、autofix 规则清单、未强制约束表、五层模型字段、Module 组件清单、
|
|
81
|
+
react / eslint / stylelint 的 peer 范围、audit 判为平行 UI 的依赖清单)。
|
|
82
|
+
规则 id 与组件名一律不许手抄进稿子 —— 抄进去的那份在规则增补时不会跟着变(§6.2)。
|
|
83
|
+
|
|
84
|
+
**当前是路线,不是成品。** 六份稿子各有结构与产出格式,但判据的细度(比如 audit 的
|
|
85
|
+
「升档门槛」怎么算、page 的「字段取值 → 组件组合」决策表)留待真实项目用过再补。
|
|
86
|
+
|
|
87
|
+
## ESLint 四档
|
|
88
|
+
|
|
89
|
+
| 档 | 规则集 | 严重度 | 用途 |
|
|
90
|
+
|---|---|---|---|
|
|
91
|
+
| `recommended` | consumer + both | 核心 error,其余 warn | 默认档 |
|
|
92
|
+
| `strict` | consumer + both | 全部 error | 新项目,或已收敛完毕的项目 |
|
|
93
|
+
| `migration` | consumer + both | 全部 warn | 存量项目接入期 |
|
|
94
|
+
| `internal` | internal + both | 全部 error | 组件库自用,不发给消费方 |
|
|
95
|
+
|
|
96
|
+
**存量项目不得直接上 `strict`。** §7.4:一上来全开 error 会让存量项目红一片,
|
|
97
|
+
团队第一反应是关掉规则,然后就永远关着了。路径是 `migration` → `recommended` → `strict`。
|
|
98
|
+
|
|
99
|
+
`recommended` 的「核心」指原生元素替换与禁止深引这两类 —— 它们覆盖的是「用错组件库」,
|
|
100
|
+
TypeScript 完全看不见。props 白名单与枚举取值降为 warn,因为契约的类型声明已经在
|
|
101
|
+
编译期报同样的错(§7.1),lint 层再报 error 只是双重刷屏。
|
|
102
|
+
|
|
103
|
+
## stylelint 两档
|
|
104
|
+
|
|
105
|
+
| 档 | 规则集 | 说明 |
|
|
106
|
+
|---|---|---|
|
|
107
|
+
| `internal` | 3 条 forbid-value | 组件库自用 |
|
|
108
|
+
| `consumer` | 当前为空 | 见下 |
|
|
109
|
+
|
|
110
|
+
`consumer` 档为空**不是遗漏**,是 §7.3 的直接结果:三条 forbid-value(禁硬编码色值、
|
|
111
|
+
禁硬编码尺寸、禁直接书写字族)的 scope 均为 `internal`,而 schema 强制这类规则只能是
|
|
112
|
+
`internal`。用户业务代码里出现色值与 px 是完全正常的,全量禁止会吵到用户关掉整条规则,
|
|
113
|
+
连带把真正有价值的一起关了。将来若有 scope 为 `consumer` 或 `both` 的 CSS 规则,
|
|
114
|
+
它会自动出现在这一档。
|
|
115
|
+
|
|
116
|
+
## 规则构成
|
|
117
|
+
|
|
118
|
+
共 150 条:
|
|
119
|
+
|
|
120
|
+
| 来源 | 类型 | 条数 |
|
|
121
|
+
|---|---|---:|
|
|
122
|
+
| 手写(`mappings.json`) | `forbid-element` | 17 |
|
|
123
|
+
| 手写(`mappings.json`) | `forbid-import` | 2 |
|
|
124
|
+
| 手写(`mappings.json`) | `forbid-value` | 3 |
|
|
125
|
+
| 生成(契约) | `props-whitelist` | 91 |
|
|
126
|
+
| 生成(契约) | `prop-enum` | 37 |
|
|
127
|
+
|
|
128
|
+
`props-whitelist` 与 `prop-enum` **不得手写**(§5.6)—— 事实来源是契约,手写会被
|
|
129
|
+
`check-mappings` 拒绝。
|
|
130
|
+
|
|
131
|
+
规则的报错文案与 SKILL.md 替换表、`generated/rules.json` **是同一个字符串**。
|
|
132
|
+
同源是「报错文案与 Skill 一致」这条验收标准成立的唯一做法(§1.5)。
|
|
133
|
+
|
|
134
|
+
## 只有引导、没有强制的约束
|
|
135
|
+
|
|
136
|
+
上表之外,SKILL.md 里还有一批「不得 / 必须」**没有任何 lint 规则兜底**。它们逐条列在
|
|
137
|
+
[`handwritten/unenforced.md`](handwritten/unenforced.md) —— 那是唯一来源,本节不再复制:
|
|
138
|
+
`moheng-ui-review` 的审查清单与 `moheng-ui-audit` 的第四桶都从它生成,一张表两处维护,
|
|
139
|
+
缩短时必漏一处。
|
|
140
|
+
|
|
141
|
+
逐条列出来是因为 §1.4 的危害不在「少一条规则」,而在「以为约束住了、实际没有」。
|
|
142
|
+
表里每条都实测过 —— 用全量 js 规则(`error` 档)跑对应的违规语料,报 0 条。
|
|
143
|
+
接入方须自行 review 这些条目,`--fix` 与 CI 都不会替人看住它们。
|
|
144
|
+
|
|
145
|
+
**这张表是会缩短的。** `<Icon size={17}>` 原本也在其中 —— 契约把 `size` 从 `number`
|
|
146
|
+
收成字面量联合 `14 | 16 | 18 | 20 | 24` 之后,`prop-enum` 自动接管了它。**凡是能收进
|
|
147
|
+
类型或收进 mappings 的,就不该留在这张表里。** 表里三条文案约束(mock 占位符、按钮命名、
|
|
148
|
+
Emoji)同源:`forbid-value` 判得了字符串字面量,只是 §7.3 把它的 `scope` 锁在了
|
|
149
|
+
`internal`。放开它要动的是 schema 与 §7.3 的裁决本身,不是补一条规则的事。
|
|
150
|
+
|
|
151
|
+
## 包内路径
|
|
152
|
+
|
|
153
|
+
| 路径 | 来源 | 内容 |
|
|
154
|
+
|---|---|---|
|
|
155
|
+
| `generated/SKILL.md` | 生成 | 拷进用户项目的薄文件,39.4 KB |
|
|
156
|
+
| `generated/skills/<name>/SKILL.md` | 生成 | 六个附属技能,随主技能一起拷进用户项目 |
|
|
157
|
+
| `generated/unenforced.json` | 生成 | 未强制约束表的结构化形态,供工具读 |
|
|
158
|
+
| `generated/reference.md` | 生成 | 完整参考,387.6 KB,留在 `node_modules` |
|
|
159
|
+
| `generated/rules.json` | 生成 | 合并后的规则集,schema 合规 |
|
|
160
|
+
| `generated/plugin-data.js` | 生成 | 两个 lint 插件的运行时数据 |
|
|
161
|
+
| `generated/contracts.json` | 生成 | 契约提取的中间产物,供排查用 |
|
|
162
|
+
| `generated/mappings.schema.json` | 生成 | `@moheng-design/ui` 同名文件的副本,使 `rules.json` 自描述 |
|
|
163
|
+
| `eslint/index.js` | 手写 | 插件与四档配置 |
|
|
164
|
+
| `eslint/lib/` | 手写 | 五类规则的工厂与匹配基元;`tiers.js` 是档位定义,两个插件与文档站的「Lint 规则」页共用 |
|
|
165
|
+
| `stylelint/index.js` | 手写 | 插件与两档配置 |
|
|
166
|
+
| `handwritten/conventions.md` | 手写 | 组合约定,每个组件一个 `## <ComponentName>` 章节 |
|
|
167
|
+
| `handwritten/anti-patterns.md` | 手写 | 成对的 bad / good 反例 |
|
|
168
|
+
| `handwritten/canvas-model.md` | 手写 | 五层 Canvas 模型的使用前提 |
|
|
169
|
+
| `handwritten/unenforced.md` | 手写 | 只有引导、没有强制的约束表,review / audit 两个技能的来源 |
|
|
170
|
+
| `handwritten/skills/*.md` | 手写 | 六个附属技能的稿子,带 frontmatter 与占位符 |
|
|
171
|
+
| `bin/cli.js` + `bin/lib/` | 手写 | `npx @moheng-design/ui-skill install / audit / feedback / upgrade` |
|
|
172
|
+
|
|
173
|
+
本表列的是 `package.json` 的 `files` 字段实际发布的内容,可用 `npm pack --dry-run` 逐行核对。
|
|
174
|
+
`scripts/` 与 `test/` **不随包发布** —— 生成器只在本仓库内运行,产物已在 `generated/` 里。
|
|
175
|
+
|
|
176
|
+
**SKILL.md 薄而 reference.md 厚,是刻意的**(§6.5)。拷进用户项目的那份在升级后会变旧,
|
|
177
|
+
所以它只写核心约束与索引;详细内容留在 `node_modules`,永远跟着包版本走,不可能过期。
|
|
178
|
+
SKILL.md 头部写死了版本号与校验指令,agent 读到版本不一致时会自己去查 reference.md。
|
|
179
|
+
|
|
180
|
+
## 命令
|
|
181
|
+
|
|
182
|
+
| 命令 | 作用 |
|
|
183
|
+
|---|---|
|
|
184
|
+
| `pnpm generate` | 生成 `generated/` 全部产物 |
|
|
185
|
+
| `pnpm check:generate` | 只校验不落盘,供 CI 用 |
|
|
186
|
+
| `pnpm extract` | 只跑契约提取,供排查用 |
|
|
187
|
+
| `pnpm test` | 三份测试共 160 条:生成器负向 25 条 + lint 行为 135 条 |
|
|
188
|
+
|
|
189
|
+
### 生成器必须能失败
|
|
190
|
+
|
|
191
|
+
`generate.mjs` 在下列情况以非零退出码结束,让 CI 变红:
|
|
192
|
+
|
|
193
|
+
1. 组件库新增了组件,但 `handwritten/conventions.md` 中没有对应的使用约定
|
|
194
|
+
2. `mappings.json` 中引用了不存在的组件
|
|
195
|
+
3. 某条规则缺少 `message` 或 `example`
|
|
196
|
+
4. `conventions.md` 中存在组件库里已不存在的章节
|
|
197
|
+
5. 某个组件的约定章节结构不完整(缺五个小节之一,或禁止清单少于 3 条)
|
|
198
|
+
6. 手写文件里出现 Emoji
|
|
199
|
+
7. 手写文件在,但内容为空
|
|
200
|
+
8. `anti-patterns.md` 的成对反例少于 8 组,或 `canvas-model.md` 未写全五层模型的五个字段名
|
|
201
|
+
9. 契约的 JSDoc 里出现 Emoji(组件、prop、辅助类型及其成员四层全查)
|
|
202
|
+
10. 技能族:`unenforced.md` 没有一行完整的表行,或某份技能稿缺 frontmatter、引用未知占位符、与主技能重名
|
|
203
|
+
|
|
204
|
+
第 1 条尤其重要:组件加进去了、类型也导出了、构建也过了,唯独 Skill 不知道它,
|
|
205
|
+
而**没有任何环节会报错** —— agent 就当那个组件不存在。
|
|
206
|
+
|
|
207
|
+
第 9 条与第 6 条是同一条约束的两半:契约 JSDoc 同样整段投影到文档站的「契约注记」
|
|
208
|
+
与 `reference.md`,而 Emoji 判定此前只扫 `handwritten/*.md`。58 个契约里曾有 95 个
|
|
209
|
+
U+FE0F —— 跟在 `⚠` 后构成 emoji 呈现的形态 —— 两份对外产物照单全收而无人发现。
|
|
210
|
+
判定沿用同一个 `EMOJI` 常量,因此箭头块与 dingbats 一并放行:契约里作排版连接号的
|
|
211
|
+
`→` 与决议记录的 `✅` / `★` 状态标记不受影响。
|
|
212
|
+
|
|
213
|
+
第 7、8 条补的是同一个洞的另一半:三份手写文件里此前只有 `conventions.md` 有结构校验,
|
|
214
|
+
另外两份只查文件在不在。实测把它们清空后生成器照样退出 0,SKILL.md 从 39.4 KB 缩到 26.6 KB,
|
|
215
|
+
「五层 Canvas 模型」与「反例」两整节只剩空标题。**文件在而内容没了,与文件不在等价。**
|
|
216
|
+
|
|
217
|
+
`test/generate.negative.mjs` 逐条制造上述违规并断言生成器确实失败,共 25 条(含 1 条正向哨兵)。
|
|
218
|
+
**一个从不失败的校验器等于没有校验,而它失败与否看不出来** —— 正向跑一次永远是绿的。
|
|
219
|
+
|
|
220
|
+
另两份是 lint 行为测试 —— `test/eslint-rules.test.mjs` 88 条、`test/stylelint-rules.test.mjs` 47 条。
|
|
221
|
+
它们用 ESLint 的 `Linter` 与 stylelint 的 Node API 跑内联语料,正反例兼有:违规须报错、
|
|
222
|
+
合规哨兵须零报错、`exceptFiles` 豁免须放行。两份都不改写任何文件。
|
|
223
|
+
|
|
224
|
+
## 版本
|
|
225
|
+
|
|
226
|
+
与 `@moheng-design/ui` 共用同一条版本线(changesets `fixed`,§1.6)。
|
|
227
|
+
**版本号相同即为配套**,两包之间不存在兼容矩阵。
|
package/bin/cli.js
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* npx @moheng-design/ui-skill <命令>
|
|
4
|
+
*
|
|
5
|
+
* install [--force] 把 SKILL.md 与附属技能拷进 .claude/skills/(01 §6.1)
|
|
6
|
+
* audit 存量项目审计,写出 moheng-audit.json
|
|
7
|
+
* feedback 收集绕过与标记,写出 moheng-feedback.md 草稿
|
|
8
|
+
* upgrade --from <旧契约> 契约差异,写出 moheng-upgrade.md
|
|
9
|
+
*
|
|
10
|
+
* 四个命令与 generated/skills/ 下的四个技能一一对应:技能负责解释与排序,命令负责
|
|
11
|
+
* 算数。数字由命令算、agent 只解释 —— 这是 §1.4「Skill 是引导,工具才是事实」在
|
|
12
|
+
* 这几个技能上的落法。
|
|
13
|
+
*
|
|
14
|
+
* 命令本体各在 bin/lib/ 下一个文件。本文件只做分发。
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
const argv = process.argv.slice(2)
|
|
18
|
+
const command = argv.find((a) => !a.startsWith('-')) ?? 'install'
|
|
19
|
+
const rest = argv.filter((a) => a !== command)
|
|
20
|
+
|
|
21
|
+
const COMMANDS = {
|
|
22
|
+
install: () => import('./lib/install.mjs'),
|
|
23
|
+
audit: () => import('./lib/audit.mjs'),
|
|
24
|
+
feedback: () => import('./lib/feedback.mjs'),
|
|
25
|
+
upgrade: () => import('./lib/upgrade.mjs'),
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
if (!COMMANDS[command]) {
|
|
29
|
+
console.error(`未知命令 ${command}。可用命令:${Object.keys(COMMANDS).join(' / ')}`)
|
|
30
|
+
process.exit(1)
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const { run } = await COMMANDS[command]()
|
|
34
|
+
const code = await run(rest)
|
|
35
|
+
process.exit(code ?? 0)
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* audit —— 存量项目审计,写出 moheng-audit.json。
|
|
3
|
+
*
|
|
4
|
+
* 路线(细节留白,见 handwritten/skills/audit.md):
|
|
5
|
+
*
|
|
6
|
+
* 1. 用 migration 档跑一遍 ESLint,按规则 / 文件聚合命中数;
|
|
7
|
+
* 2. 按 rules.json 的 kind 与 autofix 把命中分成「机械可修 / 人工替换 / 生成类」三桶;
|
|
8
|
+
* 3. 扫 package.json 的平行 UI 依赖、源码里有没有引 styles.css;
|
|
9
|
+
* 4. 装了 stylelint 时,以只读模式借 internal 档的三条 forbid-value 统计硬编码值 ——
|
|
10
|
+
* 它们不作为消费方 lint 配置发出(§7.3),但统计不是强制,借来量一下是允许的。
|
|
11
|
+
*
|
|
12
|
+
* 数字由这里算,技能只解释。本命令不改任何文件,只写 moheng-audit.json。
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import { readFileSync, writeFileSync } from 'node:fs'
|
|
16
|
+
import { createRequire } from 'node:module'
|
|
17
|
+
import { join } from 'node:path'
|
|
18
|
+
|
|
19
|
+
import { GENERATED, installedUiVersion, listCssFiles, listSourceFiles, readProjectPackage, rel } from './paths.mjs'
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* 与本库平行的 UI 依赖。出现即为结构性问题:两套组件库必然分岔。
|
|
23
|
+
*
|
|
24
|
+
* 导出是给生成器用的:moheng-ui-bootstrap 技能要告诉新项目「哪些依赖从第一天起就不装」,
|
|
25
|
+
* 那份清单若手抄进技能稿,这里增补时它不会跟着变(§6.2)。
|
|
26
|
+
*/
|
|
27
|
+
export const PARALLEL_UI = ['antd', '@ant-design/pro-components', 'element-plus', '@mui/material', '@chakra-ui/react', '@radix-ui/themes', 'tailwindcss', '@headlessui/react', 'shadcn']
|
|
28
|
+
|
|
29
|
+
export async function run() {
|
|
30
|
+
const cwd = process.cwd()
|
|
31
|
+
const projectRequire = createRequire(join(cwd, 'package.json'))
|
|
32
|
+
const rules = JSON.parse(readFileSync(join(GENERATED, 'rules.json'), 'utf8')).rules
|
|
33
|
+
const byId = new Map(rules.map((r) => [r.id, r]))
|
|
34
|
+
|
|
35
|
+
const report = {
|
|
36
|
+
generatedAt: new Date().toISOString(),
|
|
37
|
+
uiVersion: installedUiVersion(cwd),
|
|
38
|
+
files: { scanned: 0, withHits: 0 },
|
|
39
|
+
totalHits: 0,
|
|
40
|
+
byRule: {},
|
|
41
|
+
byFile: {},
|
|
42
|
+
buckets: { autofix: 0, manual: 0, generated: 0 },
|
|
43
|
+
structural: { parallelUi: [], stylesImported: false, deepImports: [] },
|
|
44
|
+
css: null,
|
|
45
|
+
notes: [],
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/* ── 1 & 2:ESLint migration 档 ─────────────────────────────────────── */
|
|
49
|
+
const sources = listSourceFiles(cwd)
|
|
50
|
+
report.files.scanned = sources.length
|
|
51
|
+
|
|
52
|
+
let ESLint
|
|
53
|
+
try { ({ ESLint } = projectRequire('eslint')) }
|
|
54
|
+
catch { report.notes.push('项目里没装 eslint,跳过规则命中统计。'); ESLint = null }
|
|
55
|
+
|
|
56
|
+
if (ESLint && sources.length > 0) {
|
|
57
|
+
const { migration } = await import('../../eslint/index.js')
|
|
58
|
+
let parser = null
|
|
59
|
+
try { parser = projectRequire('@typescript-eslint/parser') }
|
|
60
|
+
catch { report.notes.push('项目里没装 @typescript-eslint/parser,只统计 .js / .jsx。') }
|
|
61
|
+
|
|
62
|
+
const config = [
|
|
63
|
+
{ ...migration, files: parser ? migration.files : ['**/*.{js,jsx,mjs,cjs}'] },
|
|
64
|
+
parser
|
|
65
|
+
? { files: ['**/*.{ts,tsx,mts,cts}'], languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } } }
|
|
66
|
+
: { files: ['**/*.{js,jsx,mjs,cjs}'], languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } } },
|
|
67
|
+
]
|
|
68
|
+
const eslint = new ESLint({ cwd, overrideConfigFile: true, overrideConfig: config })
|
|
69
|
+
const targets = parser ? sources : sources.filter((f) => /\.(js|jsx|mjs|cjs)$/.test(f))
|
|
70
|
+
const results = await eslint.lintFiles(targets)
|
|
71
|
+
|
|
72
|
+
for (const r of results) {
|
|
73
|
+
const hits = r.messages.filter((m) => m.ruleId?.startsWith('moheng/'))
|
|
74
|
+
if (hits.length === 0) continue
|
|
75
|
+
report.files.withHits += 1
|
|
76
|
+
const file = rel(r.filePath)
|
|
77
|
+
report.byFile[file] = hits.length
|
|
78
|
+
for (const m of hits) {
|
|
79
|
+
const id = m.ruleId.slice('moheng/'.length)
|
|
80
|
+
report.byRule[id] = (report.byRule[id] ?? 0) + 1
|
|
81
|
+
report.totalHits += 1
|
|
82
|
+
const rule = byId.get(id)
|
|
83
|
+
if (!rule) continue
|
|
84
|
+
if (rule.generated || rule.kind === 'props-whitelist' || rule.kind === 'prop-enum') report.buckets.generated += 1
|
|
85
|
+
else if (rule.autofix?.enabled) report.buckets.autofix += 1
|
|
86
|
+
else report.buckets.manual += 1
|
|
87
|
+
if (rule.kind === 'forbid-import') report.structural.deepImports.push(`${file}:${m.line}`)
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/* ── 3:结构性 ────────────────────────────────────────────────────────── */
|
|
93
|
+
const pkg = readProjectPackage(cwd)
|
|
94
|
+
const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }
|
|
95
|
+
report.structural.parallelUi = PARALLEL_UI.filter((d) => d in deps)
|
|
96
|
+
report.structural.stylesImported = sources.some((f) => readFileSync(f, 'utf8').includes('@moheng-design/ui/styles.css'))
|
|
97
|
+
|
|
98
|
+
/* ── 4:CSS 硬编码只读统计 ───────────────────────────────────────────── */
|
|
99
|
+
const cssFiles = listCssFiles(cwd)
|
|
100
|
+
if (cssFiles.length > 0) {
|
|
101
|
+
try {
|
|
102
|
+
const stylelint = projectRequire('stylelint')
|
|
103
|
+
const { plugins, internal } = await import('../../stylelint/index.js')
|
|
104
|
+
const out = await stylelint.lint({ files: cssFiles, config: { plugins, rules: internal } })
|
|
105
|
+
const byRule = {}
|
|
106
|
+
let total = 0
|
|
107
|
+
for (const r of out.results) {
|
|
108
|
+
for (const w of r.warnings) {
|
|
109
|
+
const id = w.rule.replace(/^moheng\//, '')
|
|
110
|
+
byRule[id] = (byRule[id] ?? 0) + 1
|
|
111
|
+
total += 1
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
report.css = { files: cssFiles.length, total, byRule, note: '只读统计,不构成 lint 配置(§7.3)。' }
|
|
115
|
+
} catch {
|
|
116
|
+
report.notes.push('项目里没装 stylelint,跳过 CSS 硬编码统计。')
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/* ── 落盘与摘要 ───────────────────────────────────────────────────────── */
|
|
121
|
+
const outPath = join(cwd, 'moheng-audit.json')
|
|
122
|
+
writeFileSync(outPath, `${JSON.stringify(report, null, 2)}\n`)
|
|
123
|
+
|
|
124
|
+
const top = Object.entries(report.byRule).sort((a, b) => b[1] - a[1]).slice(0, 10)
|
|
125
|
+
console.log(`✓ 已写入 moheng-audit.json(@moheng-design/ui ${report.uiVersion ?? '未安装'})`)
|
|
126
|
+
console.log(` 扫描 ${report.files.scanned} 个源文件,${report.files.withHits} 个有命中,共 ${report.totalHits} 处`)
|
|
127
|
+
console.log(` 机械可修 ${report.buckets.autofix} / 人工替换 ${report.buckets.manual} / 生成类 ${report.buckets.generated}`)
|
|
128
|
+
if (top.length > 0) {
|
|
129
|
+
console.log(' 命中最多的规则:')
|
|
130
|
+
for (const [id, n] of top) console.log(` ${String(n).padStart(5)} ${id}`)
|
|
131
|
+
}
|
|
132
|
+
if (report.structural.parallelUi.length > 0) console.log(` 平行 UI 依赖:${report.structural.parallelUi.join('、')}`)
|
|
133
|
+
if (!report.structural.stylesImported) console.log(' 未发现 @moheng-design/ui/styles.css 的引入')
|
|
134
|
+
if (report.css) console.log(` CSS 硬编码值 ${report.css.total} 处(${report.css.files} 个文件,只读统计)`)
|
|
135
|
+
for (const n of report.notes) console.log(` · ${n}`)
|
|
136
|
+
console.log('\n 下一步:加载 moheng-ui-audit 技能,据此文件写 MIGRATION.md。')
|
|
137
|
+
return 0
|
|
138
|
+
}
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* feedback —— 收集绕过与标记,写出 moheng-feedback.md 草稿。
|
|
3
|
+
*
|
|
4
|
+
* 路线(细节留白,见 handwritten/skills/feedback.md):
|
|
5
|
+
*
|
|
6
|
+
* 1. 扫源码里对本库规则的 eslint-disable,分成「附了 -- moheng: 说明」与「没附」两类;
|
|
7
|
+
* 2. 扫 TODO(moheng) / FIXME(moheng) 标记;
|
|
8
|
+
* 3. 连同 @moheng-design/ui 版本号写成按反馈类型分组的草稿。
|
|
9
|
+
*
|
|
10
|
+
* 草稿由人看过再提交。本命令不发 issue,不改任何源文件。
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { readFileSync, writeFileSync } from 'node:fs'
|
|
14
|
+
import { join } from 'node:path'
|
|
15
|
+
|
|
16
|
+
import { installedUiVersion, listSourceFiles, rel } from './paths.mjs'
|
|
17
|
+
|
|
18
|
+
const TYPES = ['missing-component', 'missing-prop', 'missing-token', 'rule-false-positive', 'unclear-convention', 'doc-mismatch']
|
|
19
|
+
|
|
20
|
+
const DISABLE = /eslint-disable(?:-next-line|-line)?\s+([^\n]*?moheng\/[^\n]*)/
|
|
21
|
+
const REASON = /--\s*moheng:\s*([a-z-]+)\s*(.*)$/
|
|
22
|
+
const MARKER = /(?:TODO|FIXME)\(moheng\)\s*:?\s*(.*)$/
|
|
23
|
+
|
|
24
|
+
export async function run() {
|
|
25
|
+
const cwd = process.cwd()
|
|
26
|
+
const entries = []
|
|
27
|
+
const unexplained = []
|
|
28
|
+
|
|
29
|
+
for (const file of listSourceFiles(cwd)) {
|
|
30
|
+
const lines = readFileSync(file, 'utf8').split('\n')
|
|
31
|
+
lines.forEach((line, i) => {
|
|
32
|
+
const where = `${rel(file)}:${i + 1}`
|
|
33
|
+
const d = DISABLE.exec(line)
|
|
34
|
+
if (d) {
|
|
35
|
+
const r = REASON.exec(d[1])
|
|
36
|
+
if (r && TYPES.includes(r[1])) entries.push({ type: r[1], where, note: r[2].trim(), via: 'eslint-disable' })
|
|
37
|
+
else unexplained.push({ where, text: line.trim() })
|
|
38
|
+
return
|
|
39
|
+
}
|
|
40
|
+
const m = MARKER.exec(line)
|
|
41
|
+
if (m) entries.push({ type: '待分类', where, note: m[1].trim(), via: 'TODO(moheng)' })
|
|
42
|
+
})
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const version = installedUiVersion(cwd) ?? '未安装'
|
|
46
|
+
const out = [
|
|
47
|
+
`# @moheng-design/ui 反馈草稿`,
|
|
48
|
+
'',
|
|
49
|
+
`- 版本:@moheng-design/ui v${version}`,
|
|
50
|
+
`- 生成时间:${new Date().toISOString()}`,
|
|
51
|
+
`- 条目:${entries.length},待补说明的 disable:${unexplained.length}`,
|
|
52
|
+
'',
|
|
53
|
+
'<!-- 由 npx @moheng-design/ui-skill feedback 生成。补齐复现 / 期望 / 当前绕法后再提交。 -->',
|
|
54
|
+
'',
|
|
55
|
+
]
|
|
56
|
+
|
|
57
|
+
for (const type of [...TYPES, '待分类']) {
|
|
58
|
+
const group = entries.filter((e) => e.type === type)
|
|
59
|
+
if (group.length === 0) continue
|
|
60
|
+
out.push(`## ${type}`, '')
|
|
61
|
+
for (const e of group) {
|
|
62
|
+
out.push(`### ${type} · ${e.note || '(未写说明)'}`, '')
|
|
63
|
+
out.push(`- 版本:@moheng-design/ui v${version}`)
|
|
64
|
+
out.push(`- 位置:${e.where}`)
|
|
65
|
+
out.push(`- 复现:`)
|
|
66
|
+
out.push(`- 期望:`)
|
|
67
|
+
out.push(`- 当前绕法:${e.via}`, '')
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
if (unexplained.length > 0) {
|
|
72
|
+
out.push('## 未附说明的 disable(先补齐 `-- moheng: <类型> <一句话>`)', '')
|
|
73
|
+
for (const u of unexplained) out.push(`- ${u.where} —— \`${u.text}\``)
|
|
74
|
+
out.push('')
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const outPath = join(cwd, 'moheng-feedback.md')
|
|
78
|
+
writeFileSync(outPath, `${out.join('\n')}\n`)
|
|
79
|
+
console.log(`✓ 已写入 moheng-feedback.md:${entries.length} 条反馈,${unexplained.length} 条 disable 待补说明`)
|
|
80
|
+
console.log(' 下一步:加载 moheng-ui-feedback 技能补齐条目,人工确认后再提交。')
|
|
81
|
+
return 0
|
|
82
|
+
}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* install —— 把 generated/SKILL.md 与 generated/skills/* 拷进 .claude/skills/。
|
|
3
|
+
*
|
|
4
|
+
* 主技能落在 .claude/skills/moheng-ui/,附属技能各落 .claude/skills/<name>/。
|
|
5
|
+
* §6.5:拷出去的这些在用户升级 npm 包后会变旧,所以它们必须**薄** —— 详细内容留在
|
|
6
|
+
* node_modules 的 reference.md 里,那份永远跟着包版本走。升级后重跑本命令。
|
|
7
|
+
*
|
|
8
|
+
* 目标已存在时拒绝执行,加 --force 覆盖;不做合并。
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs'
|
|
12
|
+
import { join, relative } from 'node:path'
|
|
13
|
+
|
|
14
|
+
import { GENERATED } from './paths.mjs'
|
|
15
|
+
|
|
16
|
+
export async function run(argv) {
|
|
17
|
+
const force = argv.includes('--force') || argv.includes('-f')
|
|
18
|
+
const main = join(GENERATED, 'SKILL.md')
|
|
19
|
+
const familyDir = join(GENERATED, 'skills')
|
|
20
|
+
|
|
21
|
+
if (!existsSync(main)) {
|
|
22
|
+
console.error(
|
|
23
|
+
'✗ 找不到 generated/SKILL.md。\n'
|
|
24
|
+
+ ' 该文件是构建产物。若你是从源码仓库运行,先在 packages/ui-skill 下跑 pnpm generate。',
|
|
25
|
+
)
|
|
26
|
+
return 1
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
const family = existsSync(familyDir) ? readdirSync(familyDir).sort() : []
|
|
30
|
+
const plan = [
|
|
31
|
+
{ name: 'moheng-ui', source: main },
|
|
32
|
+
...family.map((name) => ({ name, source: join(familyDir, name, 'SKILL.md') })),
|
|
33
|
+
]
|
|
34
|
+
|
|
35
|
+
const root = join(process.cwd(), '.claude', 'skills')
|
|
36
|
+
const clashes = plan.filter((p) => existsSync(join(root, p.name, 'SKILL.md')))
|
|
37
|
+
if (clashes.length > 0 && !force) {
|
|
38
|
+
console.error(`✗ 以下技能已存在:${clashes.map((c) => c.name).join('、')}。`)
|
|
39
|
+
console.error(' 加 --force 覆盖。覆盖前请确认其中没有你自己追加的内容 —— 本命令不做合并。')
|
|
40
|
+
return 1
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
for (const p of plan) {
|
|
44
|
+
mkdirSync(join(root, p.name), { recursive: true })
|
|
45
|
+
copyFileSync(p.source, join(root, p.name, 'SKILL.md'))
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
const version = /^适用版本:v(.+)$/m.exec(readFileSync(main, 'utf8'))?.[1] ?? '未知'
|
|
49
|
+
console.log(`✓ 已写入 ${plan.length} 个技能到 ${relative(process.cwd(), root)}/(适用版本 v${version})`)
|
|
50
|
+
for (const p of plan) console.log(` ${p.name}`)
|
|
51
|
+
console.log('')
|
|
52
|
+
console.log(' 下一步 —— 接上 ESLint(Skill 是引导,ESLint 才是强制,见 01 §1.4):')
|
|
53
|
+
console.log('')
|
|
54
|
+
console.log(' // eslint.config.js')
|
|
55
|
+
console.log(" import moheng from '@moheng-design/ui-skill/eslint'")
|
|
56
|
+
console.log(' export default [moheng.recommended]')
|
|
57
|
+
console.log('')
|
|
58
|
+
console.log(' 存量项目先跑 npx @moheng-design/ui-skill audit,再用 moheng.migration 接入。')
|
|
59
|
+
console.log(' 升级 @moheng-design/ui 后重跑本命令,技能会随之更新。')
|
|
60
|
+
return 0
|
|
61
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 四个子命令共用的路径与扫描基元。
|
|
3
|
+
*/
|
|
4
|
+
|
|
5
|
+
import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
|
|
6
|
+
import { dirname, join, relative } from 'node:path'
|
|
7
|
+
import { fileURLToPath } from 'node:url'
|
|
8
|
+
|
|
9
|
+
export const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
|
|
10
|
+
export const GENERATED = join(PKG_ROOT, 'generated')
|
|
11
|
+
|
|
12
|
+
const SKIP_DIRS = new Set(['node_modules', 'dist', 'dist-types', '.next', 'out', 'coverage', '.git', '.turbo', 'generated'])
|
|
13
|
+
const SOURCE_EXT = /\.(js|jsx|mjs|cjs|ts|tsx|mts|cts)$/
|
|
14
|
+
const CSS_EXT = /\.(css|scss)$/
|
|
15
|
+
|
|
16
|
+
/** 递归列出项目源文件,跳过构建产物与依赖目录。 */
|
|
17
|
+
export function listFiles(root, match = SOURCE_EXT) {
|
|
18
|
+
const out = []
|
|
19
|
+
const walk = (dir) => {
|
|
20
|
+
for (const entry of readdirSync(dir)) {
|
|
21
|
+
if (SKIP_DIRS.has(entry)) continue
|
|
22
|
+
const full = join(dir, entry)
|
|
23
|
+
const st = statSync(full)
|
|
24
|
+
if (st.isDirectory()) walk(full)
|
|
25
|
+
else if (match.test(entry)) out.push(full)
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
walk(root)
|
|
29
|
+
return out
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export const listSourceFiles = (root) => listFiles(root, SOURCE_EXT)
|
|
33
|
+
export const listCssFiles = (root) => listFiles(root, CSS_EXT)
|
|
34
|
+
|
|
35
|
+
export const rel = (p) => relative(process.cwd(), p).replace(/\\/g, '/')
|
|
36
|
+
|
|
37
|
+
/** 项目里 @moheng-design/ui 的版本;没装则返回 null。 */
|
|
38
|
+
export function installedUiVersion(root) {
|
|
39
|
+
const p = join(root, 'node_modules', '@moheng-design', 'ui', 'package.json')
|
|
40
|
+
if (!existsSync(p)) return null
|
|
41
|
+
return JSON.parse(readFileSync(p, 'utf8')).version
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
export function readProjectPackage(root) {
|
|
45
|
+
const p = join(root, 'package.json')
|
|
46
|
+
return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : {}
|
|
47
|
+
}
|