@moheng-design/ui-skill 1.0.0 → 2.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/cli.js +0 -0
- 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 +8 -2
- package/generated/SKILL.md +258 -63
- package/generated/contracts.json +650 -119
- package/generated/plugin-data.js +403 -32
- package/generated/reference.md +788 -314
- package/generated/rules.json +436 -33
- 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 +31 -10
- package/generated/skills/moheng-ui-review/SKILL.md +8 -5
- package/generated/skills/moheng-ui-upgrade/SKILL.md +1 -1
- package/generated/unenforced.json +20 -5
- package/handwritten/anti-patterns.md +40 -22
- package/handwritten/canvas-model.md +175 -10
- package/handwritten/conventions.md +198 -136
- 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 +30 -9
- package/handwritten/unenforced.md +6 -3
- package/package.json +11 -11
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` | 四份测试共 176 条:生成器负向 25 条 + lint 行为 135 条 + 命令行为 16 条 |
|
|
188
195
|
|
|
189
196
|
### 生成器必须能失败
|
|
190
197
|
|
package/bin/cli.js
CHANGED
|
File without changes
|
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
|
@@ -58,7 +58,13 @@ export async function run(argv) {
|
|
|
58
58
|
const prevProps = new Map(prev.props.map((p) => [p.name, p]))
|
|
59
59
|
const nextProps = new Map(next.props.map((p) => [p.name, p]))
|
|
60
60
|
for (const p of prevProps.keys()) if (!nextProps.has(p)) removedProps.push(`\`${name}.${p}\``)
|
|
61
|
-
|
|
61
|
+
/* 新增且必填的 prop 与「变为必填」同样会让旧代码编译不过,归入破坏性的那一组;
|
|
62
|
+
* 混在「新增的 prop」里,读报告的人会把最该先改的一处当成可选增强跳过 */
|
|
63
|
+
for (const [p, np] of nextProps) {
|
|
64
|
+
if (prevProps.has(p)) continue
|
|
65
|
+
if (np.required) requiredFlips.push(`\`${name}.${p}\` 为新增的必填 prop`)
|
|
66
|
+
else addedProps.push(`\`${name}.${p}\``)
|
|
67
|
+
}
|
|
62
68
|
for (const [pname, np] of nextProps) {
|
|
63
69
|
const pp = prevProps.get(pname)
|
|
64
70
|
if (!pp) continue
|
|
@@ -71,7 +77,7 @@ export async function run(argv) {
|
|
|
71
77
|
}
|
|
72
78
|
|
|
73
79
|
section('删除的 prop(props-whitelist 会报)', removedProps)
|
|
74
|
-
section('变为必填的 prop', requiredFlips)
|
|
80
|
+
section('变为必填的 prop(引用处必须补)', requiredFlips)
|
|
75
81
|
section('删除的枚举值(prop-enum 会报)', removedValues)
|
|
76
82
|
section('新增的 prop', addedProps)
|
|
77
83
|
section('新增的枚举值', addedValues)
|