@huicai/cli 2026.804.0 → 2026.1019.0

package/skills/code-quality/scripts/code_jsts.py

@@ -0,0 +1,313 @@
+# JS / TS / Vue 专属体检：异步陷阱 + 类型逃逸 + Vue 响应式与模板。
+#
+# ── 这一份为什么要比 Python 那份保守 ──
+# Python 有标准库 ast，能判类型层级、作用域、名字绑定，所以敢做很细的推断。
+# JS/TS 这边只有「掩码视图 + 括号配对」——托管 Python 里没有可靠的 JS 解析器，
+# 而为了体检去装一个解析器，等于让体检在最需要它的时候先卡几分钟。
+#
+# 权衡的结果是：**判据必须是确定信号，拿不准就不报**。
+#   `.forEach(async (x) => …)`   —— 形态唯一，forEach 不会等 Promise，报；
+#   `a?.b.c`                     —— 前半段保护了、后半段没保护，报；
+#   `x === NaN`                  —— 永远为 false，报；
+#   「这个变量是不是数组」        —— 猜不准，只在有声明依据时才报。
+#
+# ── 分组 ──
+#   logic.js-*    异步与经典陷阱（浮空 Promise、forEach async、for-in 数组、sort、NaN）
+#   logic.ts-*    类型逃逸（as any、@ts-ignore、返回 any）
+#   framework.vue-*  Vue 3（模板的 v-for/v-if/v-html，脚本的 props 与响应式）
+#
+# Vue 的一半问题在 <template> 里，而 template 一度被整个丢弃（只抠 script）——
+# 那时 `v-for` 少了 `:key` 这类最常见的问题一条也查不到，报告却照样显示「已体检」。
+
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# ── 异步 ────────────────────────────────────────────────────────────────────
+_RE_ASYNC_ITER = re.compile(
+    r'\.\s*(forEach|map|filter|some|every|find|findIndex|sort|reduce)\s*\(\s*async\b')
+_RE_THEN_NO_CATCH = re.compile(r'\.\s*then\s*\(')
+# `a?.b.c`：前半段做了可选链保护，后半段又直接点出去——a 为空时前半段返回 undefined，后半段照样崩
+_RE_OPTIONAL_THEN_DOT = re.compile(r'\?\.\s*([A-Za-z_$][\w$]*)\s*\.\s*([A-Za-z_$][\w$]*)')
+_RE_NAN_CMP = re.compile(r'(===|!==|==|!=)\s*NaN\b|\bNaN\s*(===|!==|==|!=)')
+_RE_PARSE_INT = re.compile(r'\bparseInt\s*\(([^,()]*(?:\([^()]*\))?[^,()]*)\)')
+_RE_SORT_BARE = re.compile(r'\.\s*sort\s*\(\s*\)')
+_RE_DELETE_INDEX = re.compile(r'\bdelete\s+([A-Za-z_$][\w$]*)\s*\[')
+_RE_JSON_PARSE = re.compile(r'\bJSON\s*\.\s*parse\s*\(')
+_RE_FOR_IN = re.compile(r'\bfor\s*\(\s*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s+in\s+([A-Za-z_$][\w$.]*)\s*\)')
+
+
+def _line_of(lens, off):
+    return lens.text.count('\n', 0, off) + 1
+
+
+def _unit_of(lens, line):
+    u = lens.unit_at(line)
+    return u.label if u else None
+
+
+def _enclosing_try(code, off, limit=3000):
+    """这个偏移量是否落在某个 try 块里（粗判：往前找 try{ 且括号未闭合）。"""
+    head = code.rfind('try', max(0, off - limit), off)
+    if head < 0:
+        return False
+    brace = code.find('{', head)
+    if brace < 0 or brace > off:
+        return False
+    depth = 0
+    for i in range(brace, min(len(code), off + 1)):
+        if code[i] == '{':
+            depth += 1
+        elif code[i] == '}':
+            depth -= 1
+            if depth == 0:
+                return False              # try 块在 off 之前就结束了
+    return depth > 0
+
+
+def check_js_traps(lens, ctx, out, add):
+    """JS 的异步与经典陷阱。判据一律取确定形态，拿不准不报。"""
+    code = lens.code
+
+    # ── 数组方法里传 async 回调：forEach 根本不等 Promise，循环瞬间跑完 ──
+    for m in _RE_ASYNC_ITER.finditer(code):
+        ln = _line_of(lens, m.start())
+        method = m.group(1)
+        if method in ('map', 'filter', 'some', 'every', 'find', 'findIndex'):
+            hint = (f'`{method}` 会得到一个 Promise 数组：用 `await Promise.all(arr.map(async …))`；'
+                    f'{method} 需要布尔结果的（filter/some/every）要先 await 再过滤')
+        else:
+            hint = ('`forEach` 不返回也不等待 Promise —— 改成 `for (const x of arr) { await … }` 顺序执行，'
+                    '或 `await Promise.all(arr.map(async x => …))` 并发执行')
+        add(out, ctx, 'logic.js-async-in-array-method', 'error', lens, ln,
+            f'`.{method}(async …)` —— 回调返回的是 Promise，而 `{method}` 不会等它。'
+            '结果是循环"瞬间跑完"，后面的代码在数据还没就绪时就执行了',
+            hint, _unit_of(lens, ln))
+
+    # ── a?.b.c：前半段防了空，后半段没防，等于白防 ──
+    for m in _RE_OPTIONAL_THEN_DOT.finditer(code):
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.js-optional-chain-broken', 'warn', lens, ln,
+            f'`?.{m.group(1)}.{m.group(2)}` —— 可选链只保护了第一层：'
+            f'前面为空时 `?.{m.group(1)}` 得到 undefined，紧接着的 `.{m.group(2)}` 照样抛 TypeError',
+            f'整条链都要带上：`?.{m.group(1)}?.{m.group(2)}`。'
+            '只在第一个点上写 `?.` 是最常见的误用——它给人"已经防过空"的错觉',
+            _unit_of(lens, ln))
+
+    # ── 与 NaN 比较：NaN 不等于任何值，包括它自己 ──
+    for m in _RE_NAN_CMP.finditer(code):
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.js-nan-compare', 'error', lens, ln,
+            '和 `NaN` 做比较 —— NaN 不等于任何值**包括它自己**，这个判断永远为 false',
+            '用 `Number.isNaN(x)`（不要用全局 `isNaN`，它会先把参数转成数字，'
+            '`isNaN("abc")` 也是 true）', _unit_of(lens, ln))
+
+    # ── for...in 遍历数组：拿到的是字符串下标，还会带出原型链上的属性 ──
+    for m in _RE_FOR_IN.finditer(code):
+        target = m.group(2)
+        ln = _line_of(lens, m.start())
+        # 只在有声明依据时才报——猜"这个变量是不是数组"会误伤大量对象遍历
+        decl = re.search(rf'\b(?:const|let|var)\s+{re.escape(target)}\s*=\s*(\[|Array|new Array|[\w.]+\.(?:map|filter|split|concat|slice)\s*\()',
+                         code[:m.start()])
+        # 只认声明依据，**不靠名字猜**。
+        # `prevFiles` 是 `{ rel: {...} }` 这样的映射对象，却因为以 files 结尾被当成数组报了出来——
+        # 这已经是第二次栽在「按命名推断类型」上（Java 那轮是 `code == getCode()` 两边都是 int）。
+        if not decl:
+            continue
+        add(out, ctx, 'logic.js-for-in-array', 'error', lens, ln,
+            f'`for...in` 遍历数组 `{target}` —— 得到的是**字符串下标**（"0"、"1"），'
+            '还会把原型链上的可枚举属性一起带出来，顺序也不保证',
+            f'数组用 `for (const x of {target})`（要下标就 `{target}.entries()`）；'
+            '`for...in` 只给对象用', _unit_of(lens, ln))
+
+    # ── sort() 不带比较函数 ──
+    # 只报**排数字**的情况：默认 sort 把元素转成字符串再比，对字符串数组来说这正是想要的，
+    # `Object.keys(v).sort()` / `[...set].sort()` 都是完全正确的写法。
+    # 一开始没做这个区分，在真实代码上报出 20 条、无一为真。
+    for m in _RE_SORT_BARE.finditer(code):
+        ln = _line_of(lens, m.start())
+        recv = re.search(r'([A-Za-z_$][\w$.\]]*)\s*\.\s*sort\s*\(\s*\)$', code[:m.end()])
+        name = recv.group(1).split('.')[-1] if recv else ''
+        line_txt = lens.line(ln)
+        numeric = bool(re.search(r'(ids|nums?|counts?|sizes?|ages?|prices?|amounts?|scores?|ports?|years?|lens?)$',
+                                 name, re.I))
+        if not numeric:
+            # 声明处是数字字面量数组，或经过 map(Number) 的，也算数字数组
+            decl = re.search(rf'\b(?:const|let|var)\s+{re.escape(name)}\s*=\s*\[\s*-?\d', code) if name else None
+            numeric = bool(decl) or bool(re.search(r'\.map\s*\(\s*Number\s*\)|\.map\s*\(\s*\w+\s*=>\s*\+', line_txt))
+        if not numeric:
+            continue
+        add(out, ctx, 'logic.js-sort-no-comparator', 'warn', lens, ln,
+            '`sort()` 没有传比较函数 —— 它会把元素**转成字符串**再排，'
+            '`[10, 9, 100].sort()` 得到的是 `[10, 100, 9]`',
+            '数字用 `sort((a, b) => a - b)`；中文用 `sort((a, b) => a.localeCompare(b, "zh"))`',
+            _unit_of(lens, ln))
+
+    # ── parseInt 不带基数 ──
+    for m in _RE_PARSE_INT.finditer(code):
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.js-parseint-radix', 'info', lens, ln,
+            '`parseInt()` 没有指定基数 —— 解析行为依赖输入的前缀（`0x` 会被当十六进制）',
+            '明确写成 `parseInt(x, 10)`；只是想转数字用 `Number(x)`，'
+            '它对 "12abc" 会给 NaN 而不是 12', _unit_of(lens, ln))
+
+    # ── delete 数组元素：留下一个空洞，length 不变 ──
+    for m in _RE_DELETE_INDEX.finditer(code):
+        ln = _line_of(lens, m.start())
+        line_txt = lens.line(ln)
+        if not re.search(r'\[\s*\d|\[\s*i\b|\[\s*idx|\[\s*index', line_txt):
+            continue                      # 删对象的键是正常用法，只管按下标删的
+        add(out, ctx, 'logic.js-delete-array-index', 'error', lens, ln,
+            f'`delete {m.group(1)}[...]` 删数组元素 —— 它只是把那一格置空，'
+            '**length 不变**，留下一个 empty 洞，后面遍历会拿到 undefined',
+            f'用 `{m.group(1)}.splice(下标, 1)`；按条件删整批用 `filter` 重建', _unit_of(lens, ln))
+
+    # ── JSON.parse 没有防护：输入一旦不是合法 JSON 就直接抛 ──
+    for m in _RE_JSON_PARSE.finditer(code):
+        ln = _line_of(lens, m.start())
+        seg = lens.line(ln)
+        if 'JSON.stringify' in seg:
+            continue                      # JSON.parse(JSON.stringify(x)) 是深拷贝惯用法
+        if _enclosing_try(code, m.start()):
+            continue
+        u = lens.unit_at(ln)
+        if u and re.search(r'\btry\b', u.body):
+            continue                      # 函数体里有 try，粗判已被兜住
+        add(out, ctx, 'logic.js-json-parse-unguarded', 'warn', lens, ln,
+            '`JSON.parse()` 没有放在 try 里 —— 输入不是合法 JSON 时直接抛异常，'
+            '而"输入不合法"恰恰是要处理的正常情况（半截响应、空串、被截断的缓存）',
+            '包一层 try/catch 并给出降级值；或者写个 `safeParse(text, fallback)` 统一处理',
+            _unit_of(lens, ln))
+
+
+# ── TypeScript 类型逃逸 ─────────────────────────────────────────────────────
+_RE_AS_ANY = re.compile(r'\bas\s+any\b|<any>')
+_RE_TS_IGNORE = re.compile(r'@ts-(ignore|expect-error|nocheck)\b')
+_RE_ANY_RETURN = re.compile(r'\)\s*:\s*(any|any\[\]|Promise\s*<\s*any\s*>)\s*[{;=]')
+_RE_ANY_PARAM = re.compile(r'[(,]\s*\w+\s*:\s*any\b')
+
+
+def check_ts_escapes(lens, ctx, out, add):
+    """TypeScript 的类型逃逸：写了 TS 却把类型系统关掉的那几种写法。"""
+    if lens.lang not in ('ts', 'js') and not lens.is_vue:
+        return
+    code = lens.code
+    is_ts = lens.lang == 'ts' or re.search(r'lang=["\']ts', lens.text or '')
+    if not is_ts:
+        return
+
+    for m in _RE_AS_ANY.finditer(code):
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.ts-as-any', 'warn', lens, ln,
+            '`as any` 断言 —— 这一行之后所有的类型检查都失效了，'
+            '写错属性名、传错参数都不会报错',
+            '断言到**具体类型**（`as UserDto`）；类型确实拿不准就用 `unknown` + 类型守卫，'
+            '它会强制你在用之前先判一次', _unit_of(lens, ln))
+
+    for m in _RE_TS_IGNORE.finditer(lens.text):
+        ln = _line_of(lens, m.start())
+        tail = lens.line(ln)[m.start() - lens.text.rfind('\n', 0, m.start()) - 1:]
+        if len(tail.strip()) > 24:
+            continue                      # 后面跟了说明，算有理由
+        add(out, ctx, 'logic.ts-ignore-no-reason', 'warn', lens, ln,
+            f'`@ts-{m.group(1)}` 没写理由 —— 它会把下一行的类型错误整个静音，'
+            '而没人知道当初为什么要静音、现在还需不需要',
+            '在同一行补一句为什么（`@ts-expect-error 第三方类型声明缺 xxx，已提 issue #123`）。'
+            '`@ts-expect-error` 优于 `@ts-ignore`：问题修好后它会主动报"这里已经不需要了"',
+            _unit_of(lens, ln))
+
+    for m in _RE_ANY_RETURN.finditer(code):
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.ts-any-return', 'warn', lens, ln,
+            '函数返回类型标成了 `any` —— 调用方从这里开始失去全部类型信息，'
+            '一处 any 会顺着调用链扩散出去',
+            '写出真实的返回类型；结构复杂就先定义 interface。'
+            '实在不确定用 `unknown`，它至少强制调用方先收窄', _unit_of(lens, ln))
+
+
+# ── Vue 3 ──────────────────────────────────────────────────────────────────
+# 一个开始标签连同它的全部属性。属性里可能带引号包着的表达式（含 `>`），
+# 所以不能简单地一路吃到第一个 `>`——先把引号段整体跳过。
+_RE_TAG = re.compile(r'<([a-zA-Z][\w.-]*)((?:"[^"]*"|\'[^\']*\'|[^<>"\'])*)>', re.S)
+_RE_HAS_KEY = re.compile(r'(?:^|\s)(?::key|v-bind:key|key)\s*=')
+_RE_KEY_INDEX = re.compile(r'(?::key|v-bind:key)\s*=\s*["\'](?:\s*)(index|idx|i)\s*["\']')
+_RE_V_FOR = re.compile(r'(?:^|\s)v-for\s*=')
+_RE_V_IF = re.compile(r'(?:^|\s)v-(?:if|else-if)\s*=')
+_RE_V_HTML = re.compile(r'(?:^|\s)v-html\s*=')
+
+
+def check_vue(lens, ctx, out, add):
+    """Vue 3 单文件组件：模板里的指令用法 + 脚本里的响应式陷阱。"""
+    if not lens.is_vue:
+        return
+    tmpl = lens.vue_template
+    base = lens.vue_template_line
+
+    if tmpl:
+        for m in _RE_TAG.finditer(tmpl):
+            tag, attrs = m.group(1), m.group(2) or ''
+            ln = base + tmpl.count('\n', 0, m.start())
+            has_for = bool(_RE_V_FOR.search(attrs))
+
+            # ── v-for 没有 :key：Vue 只能按位置复用节点，列表一变动状态就串到别的行上 ──
+            if has_for and not _RE_HAS_KEY.search(attrs):
+                add(out, ctx, 'framework.vue-vfor-no-key', 'error', lens, ln,
+                    f'`<{tag}>` 上有 v-for 却没有 `:key` —— Vue 只能按位置复用 DOM 节点，'
+                    '列表一旦插入/删除/重排，输入框里的内容、勾选状态就会串到别的行上',
+                    '补 `:key="item.id"`（要用**数据本身的稳定标识**）', None)
+
+            # ── :key 用下标：等于没给 key，重排时照样串 ──
+            if has_for and _RE_KEY_INDEX.search(attrs):
+                add(out, ctx, 'framework.vue-key-is-index', 'warn', lens, ln,
+                    f'`<{tag}>` 的 `:key` 用的是下标 —— 下标跟着位置走，'
+                    '插入或删除一行之后所有后续项的 key 都变了，等于没给 key',
+                    '用数据里的稳定 id；确实没有 id 就在数据入口处生成一个并保存下来', None)
+
+            # ── v-if 与 v-for 写在同一个元素上 ──
+            if has_for and _RE_V_IF.search(attrs):
+                add(out, ctx, 'framework.vue-vif-with-vfor', 'error', lens, ln,
+                    f'`<{tag}>` 上 v-if 与 v-for 写在同一个元素 —— Vue 3 里 **v-if 优先级更高**，'
+                    '它先执行，此时 v-for 的循环变量还不存在，会直接报未定义',
+                    '把 v-if 移到外层 `<template v-for>` 上，'
+                    '或者先在 computed 里把数据过滤好再渲染（后者顺带避免每次渲染都重算）', None)
+
+            # ── v-html：内容会被当 HTML 解析 ──
+            if _RE_V_HTML.search(attrs):
+                add(out, ctx, 'framework.vue-v-html', 'warn', lens, ln,
+                    f'`<{tag}>` 用了 `v-html` —— 内容会被当成 HTML 解析执行，'
+                    '一旦其中混入用户输入就是 XSS',
+                    '能用 `{{ }}` 插值就别用 v-html（插值会转义）；'
+                    '确实要渲染富文本，先过一遍白名单净化（DOMPurify 之类）', None)
+
+    # ── 脚本侧：直接改 props / reactive 解构 ──
+    code = lens.code
+    props_names = set()
+    for m in re.finditer(r'\b(?:const|let)\s+(\w+)\s*=\s*defineProps\b', code):
+        props_names.add(m.group(1))
+    for m in re.finditer(r'\bdefineProps\s*<\s*\{([^}]*)\}', code):
+        props_names.add('props')
+    if 'defineProps' in code and not props_names:
+        props_names.add('props')
+
+    for name in props_names:
+        for m in re.finditer(rf'\b{re.escape(name)}\.(\w+)\s*(?:=(?!=)|\+\+|--|\+=|-=)', code):
+            ln = _line_of(lens, m.start())
+            add(out, ctx, 'framework.vue-mutate-props', 'error', lens, ln,
+                f'直接修改了 props：`{name}.{m.group(1)} = …` —— props 是**单向数据流**，'
+                '子组件改它不会同步回父组件，父组件下次重渲染还会把值覆盖回去',
+                '把值 emit 给父组件让它改（`emit("update:xxx", 新值)` + 父侧 v-model），'
+                '或在子组件里用 ref 存一份本地副本', _unit_of(lens, ln))
+
+    # ── reactive 解构：解出来的是普通值，响应性当场断掉 ──
+    for m in re.finditer(r'(?:const|let)\s*\{([^}]+)\}\s*=\s*(\w+)\b', code):
+        var = m.group(2)
+        if not re.search(rf'\b(?:const|let)\s+{re.escape(var)}\s*=\s*reactive\s*\(', code):
+            continue
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'framework.vue-reactive-destructure', 'error', lens, ln,
+            f'解构了 `reactive` 对象 `{var}` —— 解出来的是**当时的普通值**，'
+            '响应性就此断掉：后面改它，视图不会更新',
+            f'用 `toRefs({var})` 解构（拿到的是 ref，保持响应），'
+            '或者干脆整个对象用，不解构', _unit_of(lens, ln))