@moheng-design/ui-skill 1.0.0 → 3.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 +11 -4
- package/bin/lib/audit.mjs +21 -5
- package/bin/lib/feedback.mjs +20 -3
- package/bin/lib/install.mjs +6 -2
- package/bin/lib/upgrade.mjs +35 -8
- package/generated/SKILL.md +291 -83
- package/generated/contracts.json +2118 -703
- package/generated/plugin-data.js +512 -47
- package/generated/reference.md +1299 -513
- package/generated/rules.json +525 -48
- package/generated/skills/moheng-ui-audit/SKILL.md +16 -5
- package/generated/skills/moheng-ui-bootstrap/SKILL.md +10 -6
- package/generated/skills/moheng-ui-feedback/SKILL.md +8 -3
- package/generated/skills/moheng-ui-page/SKILL.md +37 -13
- package/generated/skills/moheng-ui-review/SKILL.md +8 -5
- package/generated/skills/moheng-ui-upgrade/SKILL.md +6 -4
- package/generated/unenforced.json +20 -5
- package/handwritten/anti-patterns.md +45 -25
- package/handwritten/canvas-model.md +189 -15
- package/handwritten/conventions.md +330 -194
- package/handwritten/skills/audit.md +9 -1
- package/handwritten/skills/bootstrap.md +8 -4
- package/handwritten/skills/feedback.md +6 -1
- package/handwritten/skills/page.md +33 -9
- package/handwritten/skills/upgrade.md +5 -3
- package/handwritten/unenforced.md +6 -3
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -37,11 +37,18 @@ npx @moheng-design/ui-skill install
|
|
|
37
37
|
|
|
38
38
|
```js
|
|
39
39
|
// eslint.config.js
|
|
40
|
+
import tsParser from '@typescript-eslint/parser'
|
|
40
41
|
import moheng from '@moheng-design/ui-skill/eslint'
|
|
41
42
|
|
|
42
|
-
export default [
|
|
43
|
+
export default [
|
|
44
|
+
// TypeScript 项目必须先配 parser —— 少了这一段,每个 .tsx 都以「Parsing error: Unexpected token <」失败
|
|
45
|
+
{ files: ['**/*.{ts,tsx}'], languageOptions: { parser: tsParser } },
|
|
46
|
+
moheng.recommended, // 新项目直接用 moheng.strict;存量项目从 moheng.migration 起步
|
|
47
|
+
]
|
|
43
48
|
```
|
|
44
49
|
|
|
50
|
+
纯 JavaScript 项目去掉 parser 那一段即可。
|
|
51
|
+
|
|
45
52
|
### 三、stylelint(消费方当前无需接入)
|
|
46
53
|
|
|
47
54
|
ESLint 管 JS / JSX / TS / TSX,stylelint 管 CSS。两个工具,一个来源(§7.2.1)。
|
|
@@ -122,8 +129,8 @@ TypeScript 完全看不见。props 白名单与枚举取值降为 warn,因为
|
|
|
122
129
|
| 手写(`mappings.json`) | `forbid-element` | 17 |
|
|
123
130
|
| 手写(`mappings.json`) | `forbid-import` | 2 |
|
|
124
131
|
| 手写(`mappings.json`) | `forbid-value` | 3 |
|
|
125
|
-
| 生成(契约) | `props-whitelist` |
|
|
126
|
-
| 生成(契约) | `prop-enum` |
|
|
132
|
+
| 生成(契约) | `props-whitelist` | 92 |
|
|
133
|
+
| 生成(契约) | `prop-enum` | 49 |
|
|
127
134
|
|
|
128
135
|
`props-whitelist` 与 `prop-enum` **不得手写**(§5.6)—— 事实来源是契约,手写会被
|
|
129
136
|
`check-mappings` 拒绝。
|
|
@@ -184,7 +191,7 @@ SKILL.md 头部写死了版本号与校验指令,agent 读到版本不一致
|
|
|
184
191
|
| `pnpm generate` | 生成 `generated/` 全部产物 |
|
|
185
192
|
| `pnpm check:generate` | 只校验不落盘,供 CI 用 |
|
|
186
193
|
| `pnpm extract` | 只跑契约提取,供排查用 |
|
|
187
|
-
| `pnpm test` |
|
|
194
|
+
| `pnpm test` | 四份测试共 180 条:生成器负向 25 条 + lint 行为 135 条 + 命令行为 20 条 |
|
|
188
195
|
|
|
189
196
|
### 生成器必须能失败
|
|
190
197
|
|
package/bin/lib/audit.mjs
CHANGED
|
@@ -38,9 +38,12 @@ export async function run() {
|
|
|
38
38
|
files: { scanned: 0, withHits: 0 },
|
|
39
39
|
totalHits: 0,
|
|
40
40
|
byRule: {},
|
|
41
|
+
/* 被 eslint-disable 压掉的命中。存量项目里关掉的规则正是最该看见的那批欠账,
|
|
42
|
+
* 不单列出来,「数字由命令算」算出来的就是一个偏小的数 */
|
|
43
|
+
suppressed: { total: 0, byRule: {} },
|
|
41
44
|
byFile: {},
|
|
42
45
|
buckets: { autofix: 0, manual: 0, generated: 0 },
|
|
43
|
-
structural: { parallelUi: [], stylesImported: false, deepImports: [] },
|
|
46
|
+
structural: { parallelUi: [], parallelImports: [], stylesImported: false, deepImports: [] },
|
|
44
47
|
css: null,
|
|
45
48
|
notes: [],
|
|
46
49
|
}
|
|
@@ -59,17 +62,27 @@ export async function run() {
|
|
|
59
62
|
try { parser = projectRequire('@typescript-eslint/parser') }
|
|
60
63
|
catch { report.notes.push('项目里没装 @typescript-eslint/parser,只统计 .js / .jsx。') }
|
|
61
64
|
|
|
65
|
+
/* .js / .jsx 的 JSX 开关与装没装 TS parser 无关:此前只在没装时才给,装了 TS parser 的项目里
|
|
66
|
+
* 每个 .jsx 都解析失败,而解析失败的消息没有 ruleId、被下面的过滤静默吞掉 —— 那些文件一律记作零命中 */
|
|
62
67
|
const config = [
|
|
63
68
|
{ ...migration, files: parser ? migration.files : ['**/*.{js,jsx,mjs,cjs}'] },
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
: { files: ['**/*.{js,jsx,mjs,cjs}'], languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } } },
|
|
69
|
+
{ files: ['**/*.{js,jsx,mjs,cjs}'], languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } } },
|
|
70
|
+
...(parser ? [{ files: ['**/*.{ts,tsx,mts,cts}'], languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } } }] : []),
|
|
67
71
|
]
|
|
68
72
|
const eslint = new ESLint({ cwd, overrideConfigFile: true, overrideConfig: config })
|
|
69
73
|
const targets = parser ? sources : sources.filter((f) => /\.(js|jsx|mjs|cjs)$/.test(f))
|
|
70
74
|
const results = await eslint.lintFiles(targets)
|
|
71
75
|
|
|
72
76
|
for (const r of results) {
|
|
77
|
+
/* 解析失败的文件一条规则都跑不到,计作零命中等于报了一个假的「干净」 */
|
|
78
|
+
const fatal = r.messages.find((m) => m.fatal)
|
|
79
|
+
if (fatal) report.notes.push(`${rel(r.filePath)} 解析失败,未计入统计:${fatal.message}`)
|
|
80
|
+
for (const m of r.suppressedMessages ?? []) {
|
|
81
|
+
if (!m.ruleId?.startsWith('moheng/')) continue
|
|
82
|
+
const id = m.ruleId.slice('moheng/'.length)
|
|
83
|
+
report.suppressed.byRule[id] = (report.suppressed.byRule[id] ?? 0) + 1
|
|
84
|
+
report.suppressed.total += 1
|
|
85
|
+
}
|
|
73
86
|
const hits = r.messages.filter((m) => m.ruleId?.startsWith('moheng/'))
|
|
74
87
|
if (hits.length === 0) continue
|
|
75
88
|
report.files.withHits += 1
|
|
@@ -84,7 +97,9 @@ export async function run() {
|
|
|
84
97
|
if (rule.generated || rule.kind === 'props-whitelist' || rule.kind === 'prop-enum') report.buckets.generated += 1
|
|
85
98
|
else if (rule.autofix?.enabled) report.buckets.autofix += 1
|
|
86
99
|
else report.buckets.manual += 1
|
|
87
|
-
|
|
100
|
+
/* 两条 forbid-import 性质不同:深引是用错了本库,shadcn 路径是引了一套平行实现 */
|
|
101
|
+
if (id === 'no-deep-import') report.structural.deepImports.push(`${file}:${m.line}`)
|
|
102
|
+
else if (rule.kind === 'forbid-import') report.structural.parallelImports.push(`${file}:${m.line}`)
|
|
88
103
|
}
|
|
89
104
|
}
|
|
90
105
|
}
|
|
@@ -125,6 +140,7 @@ export async function run() {
|
|
|
125
140
|
console.log(`✓ 已写入 moheng-audit.json(@moheng-design/ui ${report.uiVersion ?? '未安装'})`)
|
|
126
141
|
console.log(` 扫描 ${report.files.scanned} 个源文件,${report.files.withHits} 个有命中,共 ${report.totalHits} 处`)
|
|
127
142
|
console.log(` 机械可修 ${report.buckets.autofix} / 人工替换 ${report.buckets.manual} / 生成类 ${report.buckets.generated}`)
|
|
143
|
+
if (report.suppressed.total > 0) console.log(` 另有 ${report.suppressed.total} 处被 eslint-disable 压掉,未计入上面的总数`)
|
|
128
144
|
if (top.length > 0) {
|
|
129
145
|
console.log(' 命中最多的规则:')
|
|
130
146
|
for (const [id, n] of top) console.log(` ${String(n).padStart(5)} ${id}`)
|
package/bin/lib/feedback.mjs
CHANGED
|
@@ -20,6 +20,19 @@ const TYPES = ['missing-component', 'missing-prop', 'missing-token', 'rule-false
|
|
|
20
20
|
const DISABLE = /eslint-disable(?:-next-line|-line)?\s+([^\n]*?moheng\/[^\n]*)/
|
|
21
21
|
const REASON = /--\s*moheng:\s*([a-z-]+)\s*(.*)$/
|
|
22
22
|
const MARKER = /(?:TODO|FIXME)\(moheng\)\s*:?\s*(.*)$/
|
|
23
|
+
const RULE_IDS = /moheng\/[a-z0-9-]+/g
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* TSX 里 JSX 子节点位置的注释只能写成 `{/* … *\/}`,于是同一行的尾部带着注释与花括号的
|
|
27
|
+
* 闭合符。不剥掉它们,条目标题就成了「提交按钮需要原生 form 行为 *\/}」。
|
|
28
|
+
*/
|
|
29
|
+
const stripCommentTail = (text) => text.replace(/\s*\*\/\s*\}?\s*$/, '').trim()
|
|
30
|
+
|
|
31
|
+
/** `TODO(moheng): missing-prop 缺 xxx` —— 首词是已知反馈类型时直接归类,否则待分类 */
|
|
32
|
+
const classify = (note) => {
|
|
33
|
+
const [head, ...rest] = note.split(/\s+/)
|
|
34
|
+
return TYPES.includes(head) ? { type: head, note: rest.join(' ') } : { type: '待分类', note }
|
|
35
|
+
}
|
|
23
36
|
|
|
24
37
|
export async function run() {
|
|
25
38
|
const cwd = process.cwd()
|
|
@@ -32,13 +45,16 @@ export async function run() {
|
|
|
32
45
|
const where = `${rel(file)}:${i + 1}`
|
|
33
46
|
const d = DISABLE.exec(line)
|
|
34
47
|
if (d) {
|
|
35
|
-
const
|
|
36
|
-
|
|
48
|
+
const body = stripCommentTail(d[1])
|
|
49
|
+
const r = REASON.exec(body)
|
|
50
|
+
/* 被关掉的是哪几条规则:维护方据此定位 mappings.json 或契约,丢了它条目就只剩一句话 */
|
|
51
|
+
const rules = (body.split('--')[0].match(RULE_IDS) ?? []).join('、')
|
|
52
|
+
if (r && TYPES.includes(r[1])) entries.push({ type: r[1], where, note: r[2].trim(), rules, via: 'eslint-disable' })
|
|
37
53
|
else unexplained.push({ where, text: line.trim() })
|
|
38
54
|
return
|
|
39
55
|
}
|
|
40
56
|
const m = MARKER.exec(line)
|
|
41
|
-
if (m) entries.push({
|
|
57
|
+
if (m) entries.push({ ...classify(stripCommentTail(m[1])), where, rules: '', via: 'TODO(moheng)' })
|
|
42
58
|
})
|
|
43
59
|
}
|
|
44
60
|
|
|
@@ -62,6 +78,7 @@ export async function run() {
|
|
|
62
78
|
out.push(`### ${type} · ${e.note || '(未写说明)'}`, '')
|
|
63
79
|
out.push(`- 版本:@moheng-design/ui v${version}`)
|
|
64
80
|
out.push(`- 位置:${e.where}`)
|
|
81
|
+
if (e.rules) out.push(`- 规则:${e.rules}`)
|
|
65
82
|
out.push(`- 复现:`)
|
|
66
83
|
out.push(`- 期望:`)
|
|
67
84
|
out.push(`- 当前绕法:${e.via}`, '')
|
package/bin/lib/install.mjs
CHANGED
|
@@ -52,10 +52,14 @@ export async function run(argv) {
|
|
|
52
52
|
console.log(' 下一步 —— 接上 ESLint(Skill 是引导,ESLint 才是强制,见 01 §1.4):')
|
|
53
53
|
console.log('')
|
|
54
54
|
console.log(' // eslint.config.js')
|
|
55
|
+
console.log(" import tsParser from '@typescript-eslint/parser' // TypeScript 项目必需")
|
|
55
56
|
console.log(" import moheng from '@moheng-design/ui-skill/eslint'")
|
|
56
|
-
console.log(' export default [
|
|
57
|
+
console.log(' export default [')
|
|
58
|
+
console.log(" { files: ['**/*.{ts,tsx}'], languageOptions: { parser: tsParser } },")
|
|
59
|
+
console.log(' moheng.strict,')
|
|
60
|
+
console.log(' ]')
|
|
57
61
|
console.log('')
|
|
58
|
-
console.log('
|
|
62
|
+
console.log(' 新项目用 moheng.strict;存量项目先跑 npx @moheng-design/ui-skill audit,再用 moheng.migration 接入。')
|
|
59
63
|
console.log(' 升级 @moheng-design/ui 后重跑本命令,技能会随之更新。')
|
|
60
64
|
return 0
|
|
61
65
|
}
|
package/bin/lib/upgrade.mjs
CHANGED
|
@@ -6,8 +6,8 @@
|
|
|
6
6
|
* --from <旧版 contracts.json> 必填,升级前从 node_modules 拷出来的那份
|
|
7
7
|
* --to <新版 contracts.json> 可选,默认本包 generated/contracts.json
|
|
8
8
|
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
9
|
+
* 比四层:组件增删、prop 增删与必填翻转、枚举值增删、类型与弃用标记的变化。
|
|
10
|
+
* 契约是唯一事实来源(§6.2),差异从它算,不从 CHANGELOG 抄。
|
|
11
11
|
*/
|
|
12
12
|
|
|
13
13
|
import { existsSync, readFileSync, writeFileSync } from 'node:fs'
|
|
@@ -51,6 +51,9 @@ export async function run(argv) {
|
|
|
51
51
|
const requiredFlips = []
|
|
52
52
|
const removedValues = []
|
|
53
53
|
const addedValues = []
|
|
54
|
+
const narrowed = []
|
|
55
|
+
const retyped = []
|
|
56
|
+
const deprecated = []
|
|
54
57
|
|
|
55
58
|
for (const [name, next] of after) {
|
|
56
59
|
const prev = before.get(name)
|
|
@@ -58,21 +61,45 @@ export async function run(argv) {
|
|
|
58
61
|
const prevProps = new Map(prev.props.map((p) => [p.name, p]))
|
|
59
62
|
const nextProps = new Map(next.props.map((p) => [p.name, p]))
|
|
60
63
|
for (const p of prevProps.keys()) if (!nextProps.has(p)) removedProps.push(`\`${name}.${p}\``)
|
|
61
|
-
|
|
64
|
+
/* 新增且必填的 prop 与「变为必填」同样会让旧代码编译不过,归入破坏性的那一组;
|
|
65
|
+
* 混在「新增的 prop」里,读报告的人会把最该先改的一处当成可选增强跳过 */
|
|
66
|
+
for (const [p, np] of nextProps) {
|
|
67
|
+
if (prevProps.has(p)) continue
|
|
68
|
+
if (np.required) requiredFlips.push(`\`${name}.${p}\` 为新增的必填 prop`)
|
|
69
|
+
else addedProps.push(`\`${name}.${p}\``)
|
|
70
|
+
}
|
|
62
71
|
for (const [pname, np] of nextProps) {
|
|
63
72
|
const pp = prevProps.get(pname)
|
|
64
73
|
if (!pp) continue
|
|
65
74
|
if (!pp.required && np.required) requiredFlips.push(`\`${name}.${pname}\` 变为必填`)
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
75
|
+
/* 旧版契约里没有 deprecated 字段(提取器后来才加),缺省按未弃用算 */
|
|
76
|
+
if (pp.deprecated == null && np.deprecated != null) {
|
|
77
|
+
deprecated.push(`\`${name}.${pname}\`${np.deprecated ? `:${np.deprecated.replace(/\s*\n\s*/g, '')}` : ''}`)
|
|
78
|
+
}
|
|
79
|
+
const label = `\`${name}.${pname}\`:\`${pp.type}\` → \`${np.type}\``
|
|
80
|
+
if (pp.values && np.values) {
|
|
81
|
+
const pv = new Set(pp.values)
|
|
82
|
+
const nv = new Set(np.values)
|
|
83
|
+
for (const v of pv) if (!nv.has(v)) removedValues.push(`\`${name}.${pname}\` 不再接受 \`${v}\``)
|
|
84
|
+
for (const v of nv) if (!pv.has(v)) addedValues.push(`\`${name}.${pname}\` 新增 \`${v}\``)
|
|
85
|
+
} else if (np.values) {
|
|
86
|
+
/* 自由类型收窄成固定取值(`string` → `IconName`)是破坏性的:旧代码里任意写的
|
|
87
|
+
* 值此后在 tsc 与 prop-enum 两处被拒。逐值列成「新增的枚举值」会把它排进最后一节,
|
|
88
|
+
* 读起来像可选增强 —— 与「新增且必填」混进「新增的 prop」是同一个错。
|
|
89
|
+
* 类型名不变而旧版没解出取值的(旧提取器解不开 import 进来的别名),不是契约变化,不报 */
|
|
90
|
+
if (pp.type !== np.type) narrowed.push(`${label},只收 ${np.values.length} 个取值,取值表见 reference.md`)
|
|
91
|
+
} else if (pp.type !== np.type) {
|
|
92
|
+
retyped.push(label)
|
|
93
|
+
}
|
|
70
94
|
}
|
|
71
95
|
}
|
|
72
96
|
|
|
73
97
|
section('删除的 prop(props-whitelist 会报)', removedProps)
|
|
74
|
-
section('变为必填的 prop', requiredFlips)
|
|
98
|
+
section('变为必填的 prop(引用处必须补)', requiredFlips)
|
|
75
99
|
section('删除的枚举值(prop-enum 会报)', removedValues)
|
|
100
|
+
section('收窄为固定取值的 prop(tsc 与 prop-enum 会报,引用处必须核对)', narrowed)
|
|
101
|
+
section('类型变化的 prop(引用处须核对)', retyped)
|
|
102
|
+
section('标为弃用的 prop(下一次升级前迁走)', deprecated)
|
|
76
103
|
section('新增的 prop', addedProps)
|
|
77
104
|
section('新增的枚举值', addedValues)
|
|
78
105
|
|