@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 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 [moheng.recommended]
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` | 91 |
126
- | 生成(契约) | `prop-enum` | 37 |
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` | 三份测试共 160 条:生成器负向 25 条 + lint 行为 135 条 |
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
- parser
65
- ? { files: ['**/*.{ts,tsx,mts,cts}'], languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } } }
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
- if (rule.kind === 'forbid-import') report.structural.deepImports.push(`${file}:${m.line}`)
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}`)
@@ -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 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' })
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({ type: '待分类', where, note: m[1].trim(), via: 'TODO(moheng)' })
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}`, '')
@@ -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 [moheng.recommended]')
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(' 存量项目先跑 npx @moheng-design/ui-skill audit,再用 moheng.migration 接入。')
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
  }
@@ -6,8 +6,8 @@
6
6
  * --from <旧版 contracts.json> 必填,升级前从 node_modules 拷出来的那份
7
7
  * --to <新版 contracts.json> 可选,默认本包 generated/contracts.json
8
8
  *
9
- * 只比三层:组件增删、prop 增删与必填翻转、枚举值增删。契约是唯一事实来源(§6.2),
10
- * 差异从它算,不从 CHANGELOG 抄。
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
- for (const p of nextProps.keys()) if (!prevProps.has(p)) addedProps.push(`\`${name}.${p}\``)
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
- const pv = new Set(pp.values ?? [])
67
- const nv = new Set(np.values ?? [])
68
- for (const v of pv) if (!nv.has(v)) removedValues.push(`\`${name}.${pname}\` 不再接受 \`${v}\``)
69
- for (const v of nv) if (!pv.has(v)) addedValues.push(`\`${name}.${pname}\` 新增 \`${v}\``)
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