@huicai/cli 2026.804.0 → 2026.1019.0

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

@@ -0,0 +1,1269 @@
+# 代码体检：把「生成完代码之后人该做的那遍排查」做成机器能重复做的事。
+#
+# 与 docx_check / xlsx_check 同构，纪律也一样：
+#   ① 只在 code_lens 的掩码视图上找模式——字符串和注释里的 `==`、SQL、password 不是缺陷；
+#   ② 每加一条规则，code_battery 里必须配一个**故意做坏的样本**断言它会响，
+#      再配一个合规样本断言它**不响**（只会说「未发现问题」的体检器比没有更糟）；
+#   ③ 标了 fixable 的规则，code_fix 必须真的能修——门槛与 check 对齐，
+#      靠 FIXABLE 这一个集合两边共用来保证，不靠两处各写一遍的自觉；
+#   ④ 解析失败要如实上报「这个文件只做了降级检查」，不许静默跳过。
+#
+# 七类规则，对应「代码写完要排查什么」：
+#   logic       逻辑对不对      —— 空捕获、恒真条件、可变默认参、死代码、循环内 await…
+#   comment     注释可不可信    —— 文档与实现不符、@param 对不上、注释掉的代码、空洞注释
+#   readability 读不读得懂      —— 函数过长、嵌套过深、圈复杂度、参数过多、命名
+#   structure   结构清不清楚    —— 重复代码块、硬编码路径、调试残留
+#   test        测试作不作数    —— 无断言、弱断言、only/skip 残留、公共函数无覆盖
+#   security    安不安全        —— 硬编码密钥、SQL 拼接、命令注入、eval
+#   consistency 前后一不一致    —— 同名函数签名漂移、导出与实现不符
+#
+# 严重度：error=必修（会出事/会骗人）· warn=建议（该改但不拦交付）· info=提示（风格与偏好）
+
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import code_lens as L  # noqa: E402
+import code_java as J  # noqa: E402
+import code_python as PY  # noqa: E402
+import code_jsts as JT  # noqa: E402
+import code_csharp as CS  # noqa: E402
+
+LEVELS = ('error', 'warn', 'info')
+
+# 可自动修复的规则（code_fix 从这里读，两边永远对齐）。
+# 只收「改法唯一、不改变行为、不需要理解业务」的：加个 === 、删个 it.only。
+# 「函数太长」这种没有唯一改法的**绝不**列进来——工具不能标它做不到的自动修。
+# 门槛：改完之后行为要么完全不变，要么是**恢复本该有的行为**。
+# 刻意不收的两条，理由写在这里免得以后有人「顺手补上」：
+#   logic.loose-eq   `==`→`===` 会改变行为（"1" == 1 真，"1" === 1 假），代码若正依赖它，一键修完当场出故障；
+#   logic.self-assign `x = x` 删掉看似无害，但它多半是「漏写了 this.」的现场证据，删了等于抹掉线索、bug 还在。
+# 这两条报给人判断。工具绝不标它做不到的「可自动修」——
+# 一个会自动改坏代码的修复器，比没有修复器危险，因为人会停止复核它的改动。
+FIXABLE = {
+    'test.only-left',                # 删 .only：恢复「跑全部用例」
+    'readability.trailing-space',    # 去行尾空白（字符串内部的不动）
+    'comment.commented-code',        # 删被注释掉的死代码：注释不参与执行
+    'structure.debug-left',          # 删调试输出：仅限单行、参数里没有函数调用的
+    'logic.empty-finally',           # 删空 finally：空块本就没有任何作用
+}
+
+
+class Issue:
+    __slots__ = ('rule', 'level', 'path', 'line', 'msg', 'hint', 'unit', 'excerpt')
+
+    def __init__(self, rule, level, path, line, msg, hint='', unit=None, excerpt=''):
+        self.rule = rule
+        self.level = level
+        self.path = path
+        self.line = line
+        self.msg = msg
+        self.hint = hint
+        self.unit = unit
+        self.excerpt = excerpt
+
+    @property
+    def fixable(self):
+        return self.rule in FIXABLE
+
+    def to_dict(self):
+        return {'rule': self.rule, 'level': self.level, 'path': self.path, 'line': self.line,
+                'msg': self.msg, 'hint': self.hint, 'unit': self.unit, 'fixable': self.fixable,
+                'excerpt': self.excerpt}
+
+
+class Ctx:
+    """一次体检的上下文：阈值、已知的测试文件、跨文件索引。"""
+
+    def __init__(self, **kw):
+        self.max_lines = kw.get('max_lines', 80)          # 函数行数上限
+        self.max_depth = kw.get('max_depth', 4)           # 嵌套深度上限
+        self.max_cx = kw.get('max_cx', 15)                # 圈复杂度上限
+        self.max_params = kw.get('max_params', 6)
+        self.max_file_lines = kw.get('max_file_lines', 1200)
+        self.max_line_len = kw.get('max_line_len', 160)
+        self.strict = kw.get('strict', False)             # 严格模式：warn 提到 error
+        self.tested_names = kw.get('tested_names', set())  # 测试里出现过的标识符
+        self.has_tests = kw.get('has_tests', False)
+        self.only = set(kw.get('only') or [])             # 只跑这些类
+        self.skip = set(kw.get('skip') or [])
+
+
+_RE_IGNORE = re.compile(r'(?:code-inspect|inspect)-ignore(?:\s*:\s*|\s+)([\w.,\- ]*)')
+
+
+def _ignored(lens, line, rule):
+    """人是否在这一行（或上一行）就地豁免了这条规则。
+
+    写法：`// code-inspect-ignore: logic.empty-catch 这里的失败不影响主流程`
+    不写规则名则豁免该行全部规则。豁免要求写在紧邻处，且鼓励顺手写下理由——
+    一个没有豁免出口的检查器，遇到第一条「确实误报但改不动」的规则就会被整个关掉。
+    """
+    for probe in (lens.line(line), lens.line(line - 1)):
+        m = _RE_IGNORE.search(probe or '')
+        if not m:
+            continue
+        names = [x.strip() for x in (m.group(1) or '').replace(' ', ',').split(',') if x.strip()]
+        if not names or rule in names or rule.split('.')[0] in names:
+            return True
+    return False
+
+
+def _add(out, ctx, rule, level, lens, line, msg, hint='', unit=None):
+    cat = rule.split('.')[0]
+    if _ignored(lens, line, rule):
+        return
+    # 同一条规则在同一行只报一次。
+    # 多条正则命中同一处是常态（`expect(true).toBe(true)` 同时符合两种弱断言形态），
+    # 重复的条目会让人以为问题比实际更多，也让「必修 N 条」这个数字失去意义。
+    for prev in out:
+        if prev.rule == rule and prev.line == line and prev.path == lens.path:
+            return
+    if ctx.only and cat not in ctx.only:
+        return
+    if cat in ctx.skip:
+        return
+    if ctx.strict and level == 'warn':
+        level = 'error'
+    out.append(Issue(rule, level, lens.path, line, msg, hint, unit,
+                     excerpt=lens.line(line).strip()[:160]))
+
+
+def _unit_of(lens, line):
+    u = lens.unit_at(line)
+    return u.label if u else None
+
+
+# ══ 逻辑类 ══════════════════════════════════════════════════════════════════
+# 空捕获：JS `catch (e) {}` · Java `catch (E e) { }` · Python `except: pass`
+_RE_EMPTY_CATCH_JS = re.compile(r'\bcatch\s*(?:\([^)]*\))?\s*\{\s*\}')
+_RE_EMPTY_FINALLY = re.compile(r'\bfinally\s*\{\s*\}')
+# 恒真/恒假：if (true) · while(1) · if (1 == 1) · if (x == x)
+_RE_ALWAYS = re.compile(r'\b(?:if|while)\s*\(\s*(true|false|1|0)\s*\)')
+# 两侧必须是**完整**表达式：前不粘 `.`（否则 `i.level == level` 会从 level 起匹配上），
+# 后不粘 `.` `(` `[`（否则 `ln != ln.rstrip()` 会被当成自我比较）。
+_RE_SELF_CMP = re.compile(
+    r'(?<![\w$.])([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*(===|==|!==|!=)\s*\1(?![\w$.(\[])')
+_RE_SELF_ASSIGN = re.compile(r'^\s*([A-Za-z_$][\w$.]*)\s*=\s*\1\s*;?\s*$', re.M)
+# 松散比较（排除与 null/undefined 的惯用写法 x == null）
+_RE_LOOSE_EQ = re.compile(r'(?<![=!<>])(==|!=)(?!=)')
+_RE_ASSIGN_IN_COND = re.compile(r'\b(?:if|while)\s*\(\s*[^=()]*[^=!<>+\-*/%&|^]=(?!=)[^=]')
+_RE_FLOAT_EQ = re.compile(r'(?:===|==)\s*-?\d+\.\d+|-?\d+\.\d+\s*(?:===|==)')
+_RE_AWAIT_IN_LOOP = re.compile(r'\b(?:for|while)\s*\([^)]*\)\s*\{[^{}]*\bawait\b', re.S)
+# ⚠ 这一条必须在**原文**上跑：掩码视图把字符串连引号一起抹成了空格，
+# 而「一边是字符串字面量」正是这条规则最可靠的判据。在掩码上跑的话，
+# `emp.getStatus() == "ACTIVE"` 这种最典型的写法一条也抓不到。
+# 最强信号：`表达式 == "字面量"`（或反过来）——不管左边是变量还是方法调用，
+# 只要另一边是字符串字面量，比的就一定是引用而不是内容。
+# 只认两种**确定**的形态，不猜：
+#   ① 一边是字符串字面量 —— 那另一边不管是变量还是方法调用，比的都是引用；
+#   ② 两边都是本文件里声明成 String 的变量。
+# 曾经有过第三种「名字里带 Code/Name/Str 就算字符串」的猜测分支，
+# 结果 `this.code == ResultCode.SUCCESS.getCode()`（两边都是 int）被报成错误——
+# 靠命名猜类型，猜错的代价是让人不再相信这条规则。
+_RE_JAVA_STR_LITERAL_EQ = re.compile(
+    r'([\w$.]+(?:\s*\([^()]*\))?)\s*(==|!=)\s*"[^"]*"'
+    r'|"[^"]*"\s*(==|!=)\s*([\w$.]+(?:\s*\([^()]*\))?)')
+_RE_JAVA_STR_VAR_EQ = re.compile(r'\b(\w+)\s*(==|!=)\s*(\w+)\b')
+
+
+def _logic_swallowed_errors(lens, ctx, out):
+    """异常被吞掉的几种形态：空 catch、空 finally、裸 except、except-pass。
+
+    单列一组是因为它们共享同一条判据——「块里有没有写下为什么」。
+    """
+    code, lang = lens.code, lens.lang
+    is_js = lang in ('js', 'ts', 'vue')
+
+    # ── 空捕获：错误被吞掉，故障现场当场消失 ──
+    if is_js or lang == 'java':
+        for m in _RE_EMPTY_CATCH_JS.finditer(code):
+            ln = code.count('\n', 0, m.start()) + 1
+            # 掩码把注释抹成了空格，所以 `catch { /* 说明 */ }` 在纯代码视图里看着是空的。
+            # 回原文同一段偏移上看：块里写了注释，就是「我知道这里忽略了什么」的证据。
+            # 原先要求注释里出现「忽略/ignore」等特定词——写注释的人不会照着谁的词表写，
+            # 那条判据在真实项目上一口气刷出上百条假必修。
+            if re.search(r'/\*|//', lens.text[m.start():m.end()]):
+                continue
+            if re.search(r'(忽略|ignore|intentional|no-?op|不处理|故意)', lens.line(ln) + lens.line(ln + 1), re.I):
+                continue
+            _add(out, ctx, 'logic.empty-catch', 'error', lens, ln,
+                 '捕获了异常却什么都不做，故障会被静默吞掉',
+                 '至少记一条日志（含原始异常），或注释写明为什么可以忽略；真不需要就别 try',
+                 _unit_of(lens, ln))
+        for m in _RE_EMPTY_FINALLY.finditer(code):
+            ln = code.count('\n', 0, m.start()) + 1
+            _add(out, ctx, 'logic.empty-finally', 'warn', lens, ln, '空的 finally 块没有任何作用', '删掉它',
+                 _unit_of(lens, ln))
+    if lang == 'py':
+        for i, ln in enumerate(lens.code_lines, 1):
+            if re.match(r'^\s*except\s*:\s*$', ln):
+                _add(out, ctx, 'logic.bare-except', 'warn', lens, i,
+                     '裸 except 会连 KeyboardInterrupt / SystemExit 一起吞掉',
+                     '写明要捕获的异常类型，至少用 except Exception', _unit_of(lens, i))
+            m_exc = re.match(r'^\s*except\s*([\w.,() ]*)\s*(?:as\s+\w+)?\s*:\s*$', ln)
+            if m_exc:
+                nxt = lens.code_line(i + 1).strip()
+                has_note = '#' in (lens.line(i + 1) or '') or '#' in (lens.line(i) or '')
+                if nxt != 'pass' or has_note:
+                    continue
+                # 按「吞掉了多大范围」分级：
+                #   except Exception: pass  —— 连编程错误（NameError、TypeError）一起吞，是真危险；
+                #   except KeyError: pass   —— 捕的是一个具体的、可预期的情况，意图基本写在类型名上了。
+                # 不分级的话，一个成熟 Python 仓库会报出几十条必修，而其中大半是「取不到就用默认」
+                # 这种合理降级——必修项一多，人就不再逐条看了。
+                caught = (m_exc.group(1) or '').strip()
+                broad = (not caught) or bool(re.search(r'\b(Exception|BaseException)\b', caught))
+                if broad:
+                    _add(out, ctx, 'logic.empty-catch', 'error', lens, i,
+                         f'`except {caught or "（裸 except）"}` 捕获范围很宽却直接 pass —— '
+                         '连 NameError、TypeError 这类编程错误也一起吞了，改坏了都不会有人知道',
+                         '至少 log 一条（含异常内容）；真要忽略就把异常类型缩窄到具体那一个，'
+                         '并注释写明为什么可以忽略', _unit_of(lens, i))
+                else:
+                    _add(out, ctx, 'logic.empty-catch-narrow', 'warn', lens, i,
+                         f'`except {caught}` 之后直接 pass，没有说明为什么可以忽略',
+                         '补一句注释说明这个异常在什么情况下出现、忽略它为什么是安全的——'
+                         '异常类型说明了「捕什么」，注释要说明「为什么不用管」', _unit_of(lens, i))
+
+
+def _logic_constant_conditions(lens, ctx, out):
+    """分支其实是常量：恒真/恒假条件、自己和自己比、自己赋值给自己、条件里写了赋值。
+
+    共同点是「这段代码的走向与运行时数据无关」，而作者显然不是这个意思。
+    """
+    code = lens.code
+
+    # ── 恒真/恒假条件：分支永远只走一边，另一边是死的 ──
+    for m in _RE_ALWAYS.finditer(code):
+        ln = code.count('\n', 0, m.start()) + 1
+        word = m.group(1)
+        if re.match(r'\bwhile', m.group(0)) and word in ('true', '1'):
+            continue                       # while(true) 是合法的事件循环写法
+        _add(out, ctx, 'logic.constant-condition', 'error', lens, ln,
+             f'条件恒为 {word}，分支永远只走一边', '把真实条件写进去，或删掉这层判断', _unit_of(lens, ln))
+    for m in _RE_SELF_CMP.finditer(code):
+        ln = code.count('\n', 0, m.start()) + 1
+        _add(out, ctx, 'logic.self-compare', 'error', lens, ln,
+             f'`{m.group(1)}` 在和自己比较，结果是常量',
+             '多半是写错了变量名——对照上下文确认该比的是谁', _unit_of(lens, ln))
+    for m in _RE_SELF_ASSIGN.finditer(code):
+        ln = code.count('\n', 0, m.start()) + 1
+        _add(out, ctx, 'logic.self-assign', 'warn', lens, ln,
+             f'`{m.group(1)}` 赋值给自己，这一行没有效果', '删掉，或确认是不是漏写了 this./参数名',
+             _unit_of(lens, ln))
+
+    # ── 条件里做赋值：`if (x = 1)` 恒真，且悄悄改了 x ──
+    for m in _RE_ASSIGN_IN_COND.finditer(code):
+        ln = code.count('\n', 0, m.start()) + 1
+        _add(out, ctx, 'logic.assign-in-condition', 'error', lens, ln,
+             '条件表达式里出现了赋值 `=`（不是比较 `==`）',
+             '要比较就写 === / ==；确实要在条件里赋值，用额外括号写明意图', _unit_of(lens, ln))
+
+
+def _logic_language_traps(lens, ctx, out):
+    """各语言特有的坑：JS 松散比较、Python 可变默认参、循环内 await、
+    Java 用 == 比字符串、浮点直接比相等。
+
+    它们不靠通用模式识别，全都依赖「这是什么语言」，所以单独一组。
+    """
+    code, lang = lens.code, lens.lang
+    is_js = lang in ('js', 'ts', 'vue')
+
+    # ── JS 松散比较：== 会做类型转换，'' == 0 为真 ──
+    if is_js:
+        for i, ln in enumerate(lens.code_lines, 1):
+            for m in _RE_LOOSE_EQ.finditer(ln):
+                seg = ln[max(0, m.start() - 24):m.end() + 24]
+                if re.search(r'[!=]=\s*null|null\s*[!=]=|[!=]=\s*undefined|undefined\s*[!=]=', seg):
+                    continue               # x == null 同时判 null 与 undefined，是公认惯用法
+                _add(out, ctx, 'logic.loose-eq', 'warn', lens, i,
+                     f'用了松散比较 `{m.group(1)}`，会发生隐式类型转换（`"" == 0` 为真）',
+                     f'改成 `{m.group(1)[0]}==`（严格比较）', _unit_of(lens, i))
+                break
+
+    # ── Python 可变默认参数：默认值在定义时求值一次，会跨调用累积 ──
+    if lang == 'py' and getattr(lens, '_ast', None) is not None:
+        import ast
+        for node in ast.walk(lens._ast):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                for d in list(node.args.defaults) + [x for x in node.args.kw_defaults if x]:
+                    if isinstance(d, (ast.List, ast.Dict, ast.Set)) or (
+                            isinstance(d, ast.Call) and getattr(d.func, 'id', '') in ('list', 'dict', 'set')):
+                        _add(out, ctx, 'logic.mutable-default', 'error', lens, d.lineno,
+                             f'函数 `{node.name}` 用可变对象做默认参数，它在定义时只求值一次、会跨调用累积',
+                             '改成 `=None`，进函数体后再 `x = x or []`', node.name)
+
+    # ── 循环里 await：把本可并发的请求排成了队 ──
+    if is_js:
+        for m in _RE_AWAIT_IN_LOOP.finditer(code):
+            ln = code.count('\n', 0, m.start()) + 1
+            body = m.group(0)
+            if re.search(r'\b(sleep|delay|wait|retry|poll|排队|顺序)\b', body, re.I):
+                continue                   # 明确要顺序执行的（重试、轮询、限速）
+            _add(out, ctx, 'logic.await-in-loop', 'warn', lens, ln,
+                 '循环体里 await：N 个请求会串行等待，总耗时是各次之和',
+                 '互相独立就收集成数组交给 Promise.all 并发；确实要顺序执行，注释说明原因',
+                 _unit_of(lens, ln))
+
+    # ── Java 用 == 比字符串：比的是引用地址，不是内容 ──
+    if lang == 'java':
+        # 本文件里明确声明成 String 的名字（字段、局部变量、形参都在内）
+        str_vars = {f['name'] for f in lens.fields if f['type'].strip() == 'String'}
+        str_vars |= set(re.findall(r'\bString\s+(\w+)', code))
+        for i, ln in enumerate(lens.lines, 1):          # 原文，不是掩码视图（理由见正则上方）
+            if 'null' in ln:
+                continue
+            hit = bool(_RE_JAVA_STR_LITERAL_EQ.search(ln))
+            if not hit:
+                m = _RE_JAVA_STR_VAR_EQ.search(lens.code_line(i))
+                hit = bool(m and m.group(1) in str_vars and m.group(3) in str_vars)
+            if hit:
+                _add(out, ctx, 'logic.java-string-eq', 'error', lens, i,
+                     '用 `==` 比较字符串，比的是对象引用而不是内容',
+                     '改用 `equals()`；防空指针写成 `Objects.equals(a, b)`', _unit_of(lens, i))
+
+    # ── 浮点数直接比相等：0.1+0.2 !== 0.3 ──
+    for m in _RE_FLOAT_EQ.finditer(code):
+        ln = code.count('\n', 0, m.start()) + 1
+        _add(out, ctx, 'logic.float-eq', 'warn', lens, ln,
+             '浮点数直接比相等，二进制表示误差会让它在该相等时不等',
+             '改成比较差的绝对值小于容差；金额一律用整数分或定点小数', _unit_of(lens, ln))
+
+
+def _logic_dead_code(lens, ctx, out):
+    """return / throw / break 之后还写了语句——那些语句永远执行不到。
+
+    难点全在**排除跨行表达式**（括号未闭合、行尾是运算符、下一行是续行、
+    多行模板串被掩码抹空），排除不干净这条规则会在成熟项目上刷出几十条假必修。
+    """
+    # ── return / throw 之后的死代码 ──
+    for u in lens.functions():
+        body_lines = u.body.split('\n')
+        for i, ln in enumerate(body_lines[:-1]):
+            s = ln.strip()
+            if not re.match(r'^(return\b|throw\b|break\b|continue\b|raise\b)', s):
+                continue
+            if s.endswith('{') or s.endswith('\\'):
+                continue
+            # 跨行表达式的三种形态，都不是死代码：
+            #   ① 括号没闭合：`return bool(\n  ...\n)`（掩码抹空了字符串，括号计数可靠）
+            #   ② 本行以运算符结尾：`return a +`
+            #   ③ 下一行以运算符/点/逗号开头：`return a\n  || b`
+            # 只查①会漏掉②③——而 `|| xxx` 这种续行在真实代码里遍地都是，
+            # 漏查的后果是整个 dead-code 规则在成熟项目上刷出几十条假必修。
+            if (s.count('(') != s.count(')') or s.count('[') != s.count(']')
+                    or s.count('{') != s.count('}')):
+                continue
+            if re.search(r'([|&+\-*/%?:.,=]|\b(and|or|not|in|is)\b)\s*$', s):
+                continue
+            # 跨行字面量：`return \`…几十行模板…\`` 掩码后只剩 `return`，
+            # 而真正的返回值还在下面几十行里。拿原文比一下就知道这一行被抹掉过东西。
+            raw_here = lens.line(u.start + i)
+            if raw_here.strip() and len(raw_here.strip()) > len(s) + 1:
+                continue
+            nxt = ''
+            for j in range(i + 1, len(body_lines)):
+                if body_lines[j].strip():
+                    nxt = body_lines[j].strip()
+                    break
+            if not nxt or nxt.startswith(('}', ')', ']', 'else', 'catch', 'finally', 'case', 'default:', 'elif', 'except')):
+                continue
+            if re.match(r'^\s*(\?\?|\|\||&&|=>|[|&+\-*/%?:.,])', nxt):
+                continue                         # 下一行是续行，不是新语句
+            cur_indent = len(ln) - len(ln.lstrip())
+            nxt_indent = len(body_lines[j]) - len(body_lines[j].lstrip())
+            if nxt_indent < cur_indent:
+                continue                   # 同级块结束，不是死代码
+            _add(out, ctx, 'logic.dead-code', 'error', lens, u.start + i + 1,
+                 f'`{s.split()[0]}` 之后还有语句，它永远执行不到',
+                 '删掉死代码，或检查是不是把它放错了位置', u.label)
+            break
+
+
+def check_logic(lens, ctx, out):
+    """逻辑类体检：会出事的那些写法，不是风格问题。
+
+    按子类分成四组而不是写成一个长函数——加新规则时知道该放进哪一组，
+    而一个一百多行的 check_logic 只会让人在末尾继续追加。
+    Java 的语言陷阱另在 code_java 里（拆箱、精度、并发、资源、集合那一大类，
+    通用规则一条也看不见，混在一起只会让两边都难读）。
+    """
+    for rule_group in (_logic_swallowed_errors, _logic_constant_conditions,
+                       _logic_language_traps, _logic_dead_code):
+        rule_group(lens, ctx, out)
+    if lens.lang == 'py':
+        # Python 有标准库 ast，事实最准——能判类型层级、作用域、名字绑定，
+        # 而这几样恰恰是 Python 最难查的那批坑（共享可变、闭包延迟绑定、except 顺序）。
+        PY.check_python_traps(lens, ctx, out, _add)
+        PY.check_python_data_and_security(lens, ctx, out, _add)
+        PY.check_python_pitfalls(lens, ctx, out, _add)
+    if lens.lang in ('js', 'ts', 'vue') or lens.is_vue:
+        # JS/TS 没有可用的本地解析器，判据一律取确定形态；
+        # Vue 的 <template> 是纯标记，另走一套按标签的检查。
+        JT.check_js_traps(lens, ctx, out, _add)
+        JT.check_ts_escapes(lens, ctx, out, _add)
+        JT.check_vue(lens, ctx, out, _add)
+    if lens.lang == 'csharp':
+        # C# 与 Java 同走「掩码 + 括号配对」，但坑不一样：
+        # async void 无法捕获异常、.Result 死锁、throw ex 重置堆栈，都是 C# 独有的形态。
+        CS.check_csharp_traps(lens, ctx, out, _add)
+        CS.check_csharp_linq_and_ef(lens, ctx, out, _add)
+        CS.check_csharp_pitfalls(lens, ctx, out, _add)
+    if lens.lang == 'java':
+        J.check_java_traps(lens, ctx, out, _add)
+        J.check_java_framework(lens, ctx, out, _add)
+        J.check_java_doc_and_test(lens, ctx, out, _add, _doc_text)
+        J.check_java_pitfalls(lens, ctx, out, _add)
+
+
+# ══ 注释类 ══════════════════════════════════════════════════════════════════
+# 这一类是「注释优化」的机器部分。最要紧的不是「注释够不够多」，
+# 而是**注释说的和代码做的是不是一回事**——
+# 一条过期的注释比没有注释危害大得多：它会让下一个读者（和下一次的模型）
+# 基于错误的前提去改代码，而错误前提是看不见的。
+_RE_JSDOC_PARAM = re.compile(r'@param\s*(?:\{[^}]*\}\s*)?\[?([A-Za-z_$][\w$.]*)')
+_RE_PY_PARAM = re.compile(r'^\s*:param\s+(?:\w+\s+)?([A-Za-z_]\w*)\s*:', re.M)
+_RE_RETURN_TAG = re.compile(r'@returns?\b|^\s*:returns?:|^\s*Returns?:\s*$', re.M)
+_RE_TODO = re.compile(r'^[\s*#/─\-—·]*(TODO|FIXME|待办|待定|待补)\b', re.I | re.M)
+_RE_TODO_CASED = re.compile(r'^[\s*#/─\-—·]*(XXX|HACK)\b', re.M)
+# 「看起来像被注释掉的代码」：注释内容里有赋值/调用/结束分号/控制结构
+_RE_LOOKS_CODE = re.compile(
+    r'(^\s*(if|for|while|return|const|let|var|def|class|function|public|private|import|await)\b'
+    r'|[;{}]\s*$|^\s*[\w.$\[\]]+\s*=[^=]|\w+\([^)]*\)\s*;?\s*$)')
+_DOC_START = re.compile(r'^\s*(/\*\*?|\*|//|#|"""|\'\'\')\s?')
+
+
+def _doc_text(raw):
+    """把注释块剥成纯文本（去掉 /** * // # 这些记号）。"""
+    if not raw:
+        return ''
+    lines = []
+    for ln in str(raw).split('\n'):
+        ln = _DOC_START.sub('', ln)
+        lines.append(re.sub(r'\*/\s*$', '', ln).rstrip())
+    return '\n'.join(lines).strip()
+
+
+def _params_declared(doc, lang):
+    """从文档注释里读出它声称的形参名。"""
+    if lang == 'py':
+        names = set(_RE_PY_PARAM.findall(doc))
+        m = re.search(r'^\s*(?:Args|参数)\s*:\s*$', doc, re.M)
+        if m:                                    # Google 风格：Args: 下面每行 `name: 说明`
+            for ln in doc[m.end():].split('\n'):
+                if re.match(r'^\s*(Returns?|Raises?|Yields?|返回|异常)\s*:', ln):
+                    break
+                mm = re.match(r'^\s{2,}\*?\s*([A-Za-z_]\w*)\s*(?:\([^)]*\))?\s*:', ln)
+                if mm:
+                    names.add(mm.group(1))
+        return names
+    return set(_RE_JSDOC_PARAM.findall(doc))
+
+
+def _comment_doc_vs_code(lens, ctx, out):
+    """文档说的和代码做的是不是一回事：形参对不对得上、有没有返回值、
+    名字是不是从别的函数抄来的、该写文档的有没有写、长函数里有没有一句解释。
+
+    这是整套体检里最有价值的一组——**过期的注释比没有注释危害大**：
+    它让下一个读者（和下一次的模型）基于错误的前提去改代码，而错误前提是看不见的。
+    """
+    comment_lines = lens.comment_lines()
+    lang = lens.lang
+
+    for u in lens.functions():
+        doc = _doc_text(u.doc)
+        # ── C05 文档形参与真实形参对不上 ──
+        if doc and ('@param' in doc or ':param' in doc or re.search(r'^\s*(Args|参数)\s*:', doc, re.M)):
+            declared = _params_declared(doc, lang)
+            fields = set(u.destructured)
+            has_destructure = '{}' in u.params
+            actual = {p.lstrip('*') for p in u.params} | {'self', 'cls'} | fields
+            # JSDoc 记录解构参数的惯例是 `@param {object} p` + `@param p.command`：
+            #   · 带点的取末段，对照解构字段；
+            #   · 不带点的那个根名（这里的 p）在签名里根本不存在，是惯例的一部分，放过。
+            # 不认这套惯例，每一份写得规范的解构文档都会被判成「写了不存在的形参」——
+            # 而这恰恰是最认真写注释的那批代码。
+            ghost = []
+            for d in declared:
+                if '.' in d:
+                    root, leaf = d.split('.')[0], d.split('.')[-1]
+                    if root in actual:
+                        continue      # `p` 是真实形参，文档在描述它的字段——签名验证不了，不猜
+                    if has_destructure and fields and leaf not in fields:
+                        ghost.append(d)
+                    elif not has_destructure:
+                        ghost.append(d)
+                    continue
+                if d in actual:
+                    continue
+                if has_destructure and any(x.startswith(d + '.') for x in declared):
+                    continue          # 它是解构对象的根名，下面用 d.xxx 记录了字段
+                ghost.append(d)
+            ghost = sorted(set(ghost))
+            if ghost:
+                _add(out, ctx, 'comment.param-mismatch', 'error', lens, u.start,
+                     f'`{u.label}` 的文档写了形参 {"、".join(ghost)}，但函数签名里没有',
+                     '形参改过名/删过，注释没跟着改——按现在的签名更新文档，别留一份骗人的说明',
+                     u.label)
+            leafs = {d.split('.')[-1] for d in declared}
+            real_params = [p for p in u.params if p != '{}']
+            missing = sorted(p for p in real_params
+                             if p not in ('self', 'cls') and not p.startswith('*')
+                             and p not in declared and p not in leafs)
+            if declared and missing and len(real_params) > 1:
+                _add(out, ctx, 'comment.param-missing', 'warn', lens, u.start,
+                     f'`{u.label}` 的文档漏了形参 {"、".join(missing)}（其它形参都写了）',
+                     '补上，或者都不写——只写一半会让读者以为漏掉的那个不重要', u.label)
+        # ── C05b 文档声称有返回值，函数却从不返回 ──
+        if doc and _RE_RETURN_TAG.search(doc) and u.kind != 'class':
+            has_ret = any(re.search(r'\breturn\s+\S', ln) for ln in u.body.split('\n'))
+            if not has_ret and not u.is_async and 'yield' not in u.body:
+                _add(out, ctx, 'comment.return-mismatch', 'error', lens, u.start,
+                     f'`{u.label}` 的文档写了返回值，但函数体里没有任何 `return 值`',
+                     '要么补上返回，要么把文档里的返回值说明删掉', u.label)
+        # ── C07 文档里写的函数名和实际函数名不一样（复制粘贴没改） ──
+        if doc:
+            m = re.search(r'^\s*(?:函数\s*)?([A-Za-z_$][\w$]{3,})\s*(?:\(\)|：|:)\s', doc)
+            if m and m.group(1) != u.name and m.group(1).lower() not in ('param', 'return', 'returns',
+                                                                        'example', 'note', 'todo', 'see'):
+                other = next((x for x in lens.units if x.name == m.group(1)), None)
+                if other is not None:            # 确实是本文件里**另一个**函数的名字 → 复制粘贴残留
+                    _add(out, ctx, 'comment.name-mismatch', 'error', lens, u.start,
+                         f'`{u.label}` 的文档开头写的是 `{m.group(1)}`，多半是从那个函数复制过来忘了改',
+                         '把文档改成描述这个函数自己在做什么', u.label)
+        # ── C01 对外可见的函数没有文档 ──
+        if not doc and u.is_public and not lens.is_test and u.lines >= 8:
+            _add(out, ctx, 'comment.missing-doc', 'warn', lens, u.start,
+                 f'`{u.label}` 对外可见却没有文档注释（{u.lines} 行）',
+                 '写清楚三件事：做什么、参数含义与约束、返回值/异常；「怎么做」看代码就行，不必写',
+                 u.label)
+        # ── C06 长函数里一条注释都没有 ──
+        if u.lines >= 40:
+            inner = sum(1 for n in range(u.start, u.end + 1) if n in comment_lines)
+            if inner == 0:
+                _add(out, ctx, 'comment.no-inline', 'warn', lens, u.start,
+                     f'`{u.label}` 有 {u.lines} 行却没有一条注释',
+                     '不必逐行注释——在每个「为什么这么做」的转折处写一句：'
+                     '选了这个方案而不是那个的原因、绕开了哪个坑、这段的前提是什么', u.label)
+
+
+def _comment_commented_out(lens, ctx, out):
+    """被注释掉的代码：版本库记得住旧代码，留着只会让人不敢动周围的逻辑。"""
+    # ── C03 被注释掉的代码 ──
+    run_start, run = None, []
+    for a, b, kind in sorted(lens.comments):
+        ln = lens.text.count('\n', 0, a) + 1
+        raw = _doc_text(lens.text[a:b])
+        if not raw:
+            continue
+        first = raw.split('\n')[0].strip()
+        # 含中文=这是在讲解，不是被注释掉的代码。真注释掉的死代码不会夹着说明文字。
+        looks = bool(_RE_LOOKS_CODE.search(first)) and not re.search(r'[\u4e00-\u9fff]', first)
+        if looks:
+            if run_start is None:
+                run_start = ln
+            run.append(ln)
+        else:
+            if len(run) >= 3:
+                _add(out, ctx, 'comment.commented-code', 'warn', lens, run_start,
+                     f'第 {run_start}–{run[-1]} 行是被注释掉的代码（{len(run)} 处）',
+                     '删掉它——版本库记得住旧代码，注释掉的死代码只会让人不敢动周围的逻辑', None)
+            run_start, run = None, []
+    if len(run) >= 3:
+        _add(out, ctx, 'comment.commented-code', 'warn', lens, run_start,
+             f'第 {run_start}–{run[-1]} 行是被注释掉的代码（{len(run)} 处）',
+             '删掉它——版本库记得住旧代码，注释掉的死代码只会让人不敢动周围的逻辑', None)
+
+
+def _comment_echo(lens, ctx, out):
+    """把下一行代码念了一遍的注释——没有新增信息，纯噪声。"""
+    # ── C02 空洞注释：注释内容≈它下面那行代码，等于把代码念了一遍 ──
+    for a, b, kind in lens.comments:
+        if kind == 'doc':
+            continue
+        ln = lens.text.count('\n', 0, a) + 1
+        txt = _doc_text(lens.text[a:b])
+        if not txt or len(txt) > 40 or '\n' in txt:
+            continue
+        nxt = lens.code_line(ln + 1).strip() or lens.code_line(ln).strip()
+        if not nxt:
+            continue
+        toks = set(re.findall(r'[A-Za-z_$][\w$]{2,}', txt.lower()))
+        code_toks = set(re.findall(r'[A-Za-z_$][\w$]{2,}', nxt.lower()))
+        if toks and toks <= code_toks and len(toks) >= 1 and len(txt) < 30:
+            _add(out, ctx, 'comment.echo', 'info', lens, ln,
+                 '这条注释只是把下一行代码念了一遍，没有新增信息',
+                 '删掉，或改写成「为什么」——代码写了做什么，注释该写为什么这么做', _unit_of(lens, ln))
+
+
+def _comment_todo(lens, ctx, out):
+    """没有主、没有期限的 TODO：等于永远不会有人做。"""
+    # ── C04 TODO 没有主和期限，等于永远不会有人做 ──
+    for a, b, kind in lens.comments:
+        raw = lens.text[a:b]
+        m = _RE_TODO.search(_doc_text(raw)) or _RE_TODO_CASED.search(_doc_text(raw))
+        if not m:
+            continue
+        ln = lens.text.count('\n', 0, a) + 1
+        tail = raw[m.end():m.end() + 120]
+        if re.search(r'[(（]\s*[\w.@一-龥-]+\s*[)）]|@\w+|\d{4}-\d{2}|#\d+', tail):
+            continue                             # 有责任人或单号或日期，算合格
+        _add(out, ctx, 'comment.todo-orphan', 'info', lens, ln,
+             f'`{m.group(1)}` 没有写清楚谁来做、什么时候做',
+             '补成 `TODO(姓名, 2026-10-01): 具体要做什么`，或直接建个单号；无主 TODO 会永久沉底',
+             _unit_of(lens, ln))
+
+
+def check_comment(lens, ctx, out):
+    """注释类体检：注释可不可信，而不是注释够不够多。"""
+    for rule_group in (_comment_doc_vs_code, _comment_commented_out,
+                       _comment_echo, _comment_todo):
+        rule_group(lens, ctx, out)
+
+
+# ══ 可读性 ══════════════════════════════════════════════════════════════════
+# 阈值是「该停下来看一眼」的信号，不是「必须拆」的判决。所以除了超得离谱的，
+# 一律 warn/info：把风格偏好判成必修，人就会开始整体无视这个工具。
+_LOOP_VARS = {'i', 'j', 'k', 'n', 'm', 'x', 'y', 'z', '_', 'e', 'f', 'a', 'b', 'c', 'd', 't', 'v', 'q'}
+# 参数名的白名单要比循环变量窄得多：`for (i…)` 里的 i 一望而知，
+# 但一个叫 `q` 的参数在四十行之后没人记得它是 query 还是 queue。
+_OK_SHORT_PARAMS = {'i', 'j', 'k', 'n', 'x', 'y', 'z', '_', 'e'}
+_RE_MAGIC = re.compile(r'(?<![\w.$])(?<!\d)(\d{3,})(?![\w.])')
+_SAFE_MAGIC = {'100', '200', '201', '204', '301', '302', '304', '400', '401', '403', '404',
+               '409', '422', '429', '500', '502', '503', '504', '1000', '1024', '360', '255',
+               '2026', '3600', '8080'}
+
+
+def check_readability(lens, ctx, out):
+    limit = ctx.max_lines * 2 if lens.is_test else ctx.max_lines
+    for u in lens.functions():
+        if u.lines > limit:
+            _add(out, ctx, 'readability.long-function', 'warn', lens, u.start,
+                 f'`{u.label}` 有 {u.lines} 行（建议 ≤{limit}）',
+                 '找函数里的「小节」——每一段开头你想写注释的地方，通常就是该抽成独立函数的地方', u.label)
+        if u.depth > ctx.max_depth:
+            _add(out, ctx, 'readability.deep-nesting', 'warn', lens, u.start,
+                 f'`{u.label}` 嵌套深达 {u.depth} 层（建议 ≤{ctx.max_depth}）',
+                 '用卫语句提前 return 把异常分支甩掉，主流程回到最外层；或把内层整块抽成函数', u.label)
+        if u.complexity > ctx.max_cx:
+            _add(out, ctx, 'readability.high-complexity', 'warn', lens, u.start,
+                 f'`{u.label}` 圈复杂度 {u.complexity}（建议 ≤{ctx.max_cx}），'
+                 f'要覆盖它至少需要 {u.complexity} 个测试用例',
+                 '按职责拆分；一长串 if-else 分派可以换成查表/多态', u.label)
+        real = [p for p in u.params if p not in ('self', 'cls')]
+        if len(real) > ctx.max_params:
+            _add(out, ctx, 'readability.too-many-params', 'warn', lens, u.start,
+                 f'`{u.label}` 有 {len(real)} 个参数（建议 ≤{ctx.max_params}）',
+                 '把同进同出的几个打包成一个选项对象/结构体，调用处也更好读', u.label)
+        short = [p for p in real if len(p) == 1 and p not in _OK_SHORT_PARAMS]
+        if short and u.lines > 15:
+            _add(out, ctx, 'readability.cryptic-param', 'info', lens, u.start,
+                 f'`{u.label}` 的参数名 {"、".join(short)} 只有一个字母，函数却有 {u.lines} 行',
+                 '起个说得出含义的名字——读的人不必再往回翻', u.label)
+
+    if len(lens.lines) > ctx.max_file_lines:
+        _add(out, ctx, 'readability.long-file', 'info', lens, 1,
+             f'文件 {len(lens.lines)} 行（建议 ≤{ctx.max_file_lines}）',
+             '按职责拆分模块；先看有没有一组函数只服务于同一件事，它们通常能整体搬走', None)
+
+    for i, ln in enumerate(lens.lines, 1):
+        if len(ln) > ctx.max_line_len:
+            _add(out, ctx, 'readability.long-line', 'info', lens, i,
+                 f'第 {i} 行长 {len(ln)} 字符（建议 ≤{ctx.max_line_len}）', '折行或抽出中间变量',
+                 _unit_of(lens, i))
+            break                                # 一个文件报一次就够，不刷屏
+    for i, ln in enumerate(lens.lines, 1):
+        if ln != ln.rstrip():
+            _add(out, ctx, 'readability.trailing-space', 'info', lens, i, '行尾有多余空白',
+                 '删掉（编辑器一般可配置保存时自动清理）', None)
+            break
+
+    if not lens.is_test:
+        seen_lines = set()
+        for i, ln in enumerate(lens.code_lines, 1):
+            if len(seen_lines) > 60:
+                break
+            for m in _RE_MAGIC.finditer(ln):
+                num = m.group(1)
+                if num in _SAFE_MAGIC or i in seen_lines:
+                    continue
+                if re.search(r'(version|port|timeout|ms|width|height|size|len|max|min)', ln, re.I):
+                    continue                     # 上下文自带含义的不算魔法数字
+                seen_lines.add(i)
+                _add(out, ctx, 'readability.magic-number', 'info', lens, i,
+                     f'字面量 `{num}` 没有名字，读的人不知道它代表什么',
+                     '提成有名字的常量，名字本身就是注释', _unit_of(lens, i))
+                break
+
+
+# ══ 结构 ════════════════════════════════════════════════════════════════════
+# 两道后顾断言都是治误报的：盘符前面不能紧挨字母（否则每个 http:// / https:// 的「p:/」「s:/」都像 Windows 盘符），
+# /home 这类目录前面不能紧挨主机名（否则 https://site.com/home/x 也像本机路径）。
+# 实测修之前：内联 SVG 的 xmlns、data:image/svg+xml、fetch('https://…') 全被报成「写死了本机绝对路径」。
+_RE_HARD_PATH = re.compile(r'(?:(?<![\w.-])/(?:Users|home|var|opt|etc|tmp)/[\w./-]{4,}|(?<![A-Za-z0-9])[A-Za-z]:[\\/]{1,2}[\w\\/.-]{4,})')
+_RE_DEBUG_JS = re.compile(r'\bconsole\.(log|debug|dir|trace)\s*\(')
+_RE_DEBUG_PY = re.compile(r'^\s*print\s*\(')
+_RE_DEBUG_JAVA = re.compile(r'\bSystem\.(out|err)\.print')
+
+
+def check_structure(lens, ctx, out):
+    lang = lens.lang
+    # ── 硬编码的本机绝对路径：换台机器就崩 ──
+    for a, b, q, raw in lens.strings:
+        if _RE_HARD_PATH.search(raw):
+            ln = lens.text.count('\n', 0, a) + 1
+            if lens.is_test or re.search(r'(示例|example|e\.g\.|比如|如 )', lens.line(ln)):
+                continue
+            _add(out, ctx, 'structure.hardcoded-path', 'warn', lens, ln,
+                 '写死了本机绝对路径，换一台机器/换一个用户就找不到',
+                 '改成配置项、环境变量，或基于项目根目录拼相对路径', _unit_of(lens, ln))
+
+    # ── 调试输出残留 ──
+    path_s = str(lens.path).replace('\\', '/')
+    if not lens.is_test and not re.search(r'(bin|cli|scripts?|tools?)/', path_s):
+        pat = {'py': _RE_DEBUG_PY, 'java': _RE_DEBUG_JAVA}.get(lang, _RE_DEBUG_JS)
+        hits = [i for i, ln in enumerate(lens.code_lines, 1) if pat.search(ln)]
+        if hits:
+            _add(out, ctx, 'structure.debug-left', 'info', lens, hits[0],
+                 f'有 {len(hits)} 处调试输出残留（第 {"、".join(map(str, hits[:6]))} 行）',
+                 '删掉，或换成项目的日志组件并给合适的级别', _unit_of(lens, hits[0]))
+
+    # ── 重复代码块：连续 ≥6 行完全相同（忽略缩进差异） ──
+    norm = [re.sub(r'\s+', ' ', ln.strip()) for ln in lens.code_lines]
+    window = 6
+    seen = {}
+    reported = 0
+    for i in range(len(norm) - window + 1):
+        chunk = norm[i:i + window]
+        if sum(1 for c in chunk if c) < window or sum(len(c) for c in chunk) < 90:
+            continue
+        key = ''.join(chunk)
+        if key in seen:
+            if i - seen[key] < window:
+                continue
+            reported += 1
+            if reported <= 3:
+                _add(out, ctx, 'structure.duplicate-block', 'warn', lens, i + 1,
+                     f'第 {i + 1} 行起的 {window} 行与第 {seen[key] + 1} 行起的完全相同',
+                     '抽成一个函数——重复的代码意味着改的时候要记得改两处，而人总会忘一处', None)
+        else:
+            seen[key] = i
+
+
+# ══ 测试 ════════════════════════════════════════════════════════════════════
+_RE_ASSERT = re.compile(
+    r'\b(assert\w*|expect|should|verify|toBe\w*|toEqual|toThrow|toHaveBeen\w*|'
+    r'deepStrictEqual|strictEqual|notStrictEqual|ok|fail|match)\b')
+# 拆成一组独立正则，不拼成一个大 alternation：
+# 合并写法里的反向引用编号会随着前面加了几个组而整体漂移，
+# 改一条就可能悄悄改坏另一条——这种错编译期不报，跑起来才发现规则从来没响过。
+_WEAK_ASSERTS = [
+    re.compile(r'\bassert\s*\(\s*(?:true|True|1)\s*[,)]'),
+    re.compile(r'\bassertTrue\s*\(\s*true\s*\)'),
+    re.compile(r'\bself\.assertTrue\s*\(\s*True\s*\)'),
+    re.compile(r'\bexpect\s*\(\s*(true|1)\s*\)\s*\.\s*to\w*\s*\(\s*\1\s*\)'),
+    re.compile(r'\bassertEquals\s*\(\s*(\d+)\s*,\s*\1\s*\)'),
+    re.compile(r'\bexpect\s*\(\s*([\w.]+)\s*\)\s*\.\s*toBe\s*\(\s*\1\s*\)'),
+]
+# 两个形态各有用处：BLOCK 在**原文**上定位带标题的测试块（要求引号），
+# CALL 在**掩码视图**上判断块里还有没有嵌套的测试块（引号已被抹掉，不能要求它）。
+_RE_TEST_BLOCK = re.compile(r'(?<![\w.$])(?:it|test)\s*(?:\.\s*\w+\s*)?\(\s*[\'"`]')
+_RE_TEST_CALL = re.compile(r'(?<![\w.$])(?:it|test)\s*(?:\.\s*\w+\s*)?\(')
+
+
+def _match_paren(code, lparen):
+    """从 lparen 处的 '(' 找到配对的 ')'；找不到返回 -1。
+
+    在掩码视图上配对——测试标题里带括号（'读到 (空) 时返回默认值'）是常事，
+    在原文上数括号会把块的边界算错，块内容一错，「有没有断言」就判反了。
+    """
+    depth = 0
+    for i in range(lparen, len(code)):
+        if code[i] == '(':
+            depth += 1
+        elif code[i] == ')':
+            depth -= 1
+            if depth == 0:
+                return i
+    return -1
+
+
+_RE_ONLY = re.compile(r'\b(?:it|test|describe|context)\s*\.\s*only\s*\(|\bfdescribe\s*\(|\bfit\s*\(')
+_RE_SKIP = re.compile(r'\b(?:it|test|describe)\s*\.\s*skip\s*\(|@(?:Disabled|Ignore)\b|@pytest\.mark\.skip')
+
+
+def check_test(lens, ctx, out):
+    if not lens.is_test:
+        return
+    code = lens.code
+    # ── .only 残留：CI 会只跑这一个用例，其余全部静默跳过 ──
+    for m in _RE_ONLY.finditer(code):
+        ln = code.count('\n', 0, m.start()) + 1
+        _add(out, ctx, 'test.only-left', 'error', lens, ln,
+             '`.only` 残留：整个文件会**只跑这一个用例**，其余全部被跳过且不报错',
+             '删掉 `.only`——本地调试用完必须清掉，否则 CI 绿得毫无意义', _unit_of(lens, ln))
+    for m in _RE_SKIP.finditer(code):
+        ln = code.count('\n', 0, m.start()) + 1
+        if re.search(r'(理由|because|reason|待|#\d+)', lens.line(ln) + lens.line(ln - 1), re.I):
+            continue
+        _add(out, ctx, 'test.skip-no-reason', 'warn', lens, ln,
+             '跳过了测试但没有写原因', '注明为什么跳过、什么条件下恢复，或建个单号跟踪', _unit_of(lens, ln))
+    # ── 弱断言：断言恒成立，等于没测 ──
+    for pat in _WEAK_ASSERTS:
+      for m in pat.finditer(code):
+        ln = code.count('\n', 0, m.start()) + 1
+        _add(out, ctx, 'test.weak-assert', 'error', lens, ln,
+             '这个断言恒为真，无论被测代码对错它都会通过',
+             '断言真实的输出值/状态变化；断不出东西说明这个用例还没想清楚要验证什么', _unit_of(lens, ln))
+    # ── JS 主流写法 it('…', () => {…}) 不是「函数声明」，解析器不会把它当 unit，
+    #    但它恰恰是 JS/TS 项目里绝大多数测试的形状。只靠 lens.functions() 遍历，
+    #    这条规则在真实的 JS 测试文件上永远不会响——而报告照样显示「已体检」。
+    # ⚠ 定位必须在**原文**上做：掩码视图把字符串连同引号一起抹成了空格，
+    #   所以 `it\s*\(\s*['"]` 这种依赖引号的模式在 code 上永远匹配不到——
+    #   规则加了等于没加，而报告照样显示「已体检」。
+    #   掩码与原文等长，偏移量通用：定位用 text，配对与内容判断用 code。
+    for m in _RE_TEST_BLOCK.finditer(lens.text):
+        if lens.in_literal(m.start()):
+            continue                              # 写在字符串里的测试代码样本，不是本文件的测试
+        lparen = lens.text.index('(', m.start())
+        close = _match_paren(code, lparen)
+        if close < 0:
+            continue
+        block = code[lparen:close]
+        inner = block[block.find(',') + 1:] if ',' in block else ''
+        if not inner.strip():
+            continue
+        if _RE_TEST_CALL.search(inner):
+            continue                              # 外层 describe/嵌套块，断言在内层各 it 里
+        if not _RE_ASSERT.search(inner):
+            ln = lens.text.count('\n', 0, m.start()) + 1
+            named = re.search(r'[\'"`]([^\'"`]*)', lens.text[m.start():m.start() + 200])
+            title = (named.group(1).strip() if named else '') or '(未命名)'
+            _add(out, ctx, 'test.no-assert', 'error', lens, ln,
+                 f'测试「{title}」里没有任何断言——它只要不抛异常就算通过',
+                 '补上对返回值/状态/副作用的断言；只想确认「不抛异常」也要显式写出来', None)
+
+    # ── 没有断言的测试：跑过了就算过，其实什么都没验证 ──
+    for u in lens.functions():
+        head = lens.line(u.start) + ' ' + lens.line(u.start - 1)
+        looks_test = (u.name or '').startswith('test') or '@Test' in head
+        if not looks_test:
+            continue
+        if not _RE_ASSERT.search(u.body):
+            _add(out, ctx, 'test.no-assert', 'error', lens, u.start,
+                 f'测试 `{u.label}` 里没有任何断言——它只要不抛异常就算通过',
+                 '补上对返回值/状态/副作用的断言；只想确认「不抛异常」也要显式写出来', u.label)
+        if re.match(r'^(test_?\d+|测试\d*|tmp|foo|bar)$', u.name or ''):
+            _add(out, ctx, 'test.vague-name', 'info', lens, u.start,
+                 f'测试名 `{u.name}` 说不出它在验证什么',
+                 '用「条件_预期」命名，如 `空输入时返回默认值`——失败时光看名字就知道坏了什么', u.label)
+
+
+def check_coverage(lens, ctx, out):
+    """公共函数有没有被测试提到过。
+
+    口径是「测试文件里有没有出现这个名字」——这是覆盖的**下界**，不是真覆盖率。
+    所以只报 warn，且报告里必须写明口径；装成精确覆盖率会骗人。
+    """
+    if lens.is_test or not ctx.has_tests:
+        return
+    for u in lens.functions():
+        if not u.is_public or u.lines < 6 or u.name in ('(匿名)', 'constructor', '__init__'):
+            continue
+        if u.name in ctx.tested_names:
+            continue
+        _add(out, ctx, 'test.uncovered', 'warn', lens, u.start,
+             f'`{u.label}` 对外可见（{u.lines} 行，圈复杂度 {u.complexity}）但测试里从没出现过这个名字',
+             f'至少补一个正常路径 + 一个边界用例；圈复杂度 {u.complexity} 说明它有 {u.complexity} 条路要走',
+             u.label)
+
+
+# ══ 安全 ════════════════════════════════════════════════════════════════════
+# 这一类误报代价特别高：安全告警一旦被判定为「又在乱叫」，人会连真的那条一起无视。
+# 所以每条规则都带一组排除：占位符、示例、从环境变量取值、纯提示文案。
+# 词表刻意不收裸 `pass` 和裸 `auth`：前者会撞上 Python 的 pass 关键字，
+# 后者会撞上 authState / authorize / authorized 这类遍地都是的普通标识符。
+# 密钥告警一旦被当成噪声，人会连真的那条一起无视——宁可漏一点，不可吵。
+_SECRET_NAME = re.compile(
+    r'\b(pass(?:wd|word)|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key'
+    r'|credential|auth[_-]?(?:token|key|secret)|appkey|app[_-]?secret|signature)\b', re.I)
+# 明显不是真密钥的值：占位、模板、从配置读、太短
+_PLACEHOLDER = re.compile(
+    r'^\s*$|^(x{3,}|\*{3,}|\.{3,}|-{3,})$|your|example|sample|placeholder|dummy|test|demo|fake'
+    r'|change[_-]?me|<[^>]+>|\$\{|\{\{|%[sd]|\bnull\b|\bnone\b|请填写|填入|示例|占位',
+    re.I)
+_RE_ENV_READ = re.compile(r'(process\.env|os\.getenv|os\.environ|System\.getenv|getProperty|'
+                          r'@Value|config\.|settings\.|\.env\b)', re.I)
+# SQL 语句特征（掩码后看不到字符串，所以这条必须在**字符串原文**上跑）
+_RE_SQL = re.compile(r'\b(SELECT\s+.+\s+FROM|INSERT\s+INTO|UPDATE\s+\w+\s+SET|DELETE\s+FROM|WHERE\s+\w+\s*=)\b', re.I)
+_RE_EXEC = re.compile(r'\b(exec|execSync|spawn|spawnSync|system|popen|Runtime\.getRuntime\(\)\.exec'
+                      r'|ProcessBuilder|os\.system|subprocess\.(?:call|run|Popen|check_output))\s*\(')
+# 右边界同样要卡死：只管左边界的话，`evalService` / `EvalService` 里的 eval 全中招
+# （实测在一个 Spring 后端上一口气刷出 31 条假告警，而 Java 根本没有 eval 语法）。
+_RE_EVAL = re.compile(r'(?<![\w.$])(?:window\.)?(eval)\s*\(|(?<![\w.$])(new\s+Function)\s*\('
+                      r'|(?<![\w.$])(setTimeout|setInterval)\s*\(\s*[\'"`]')
+# Java 的动态执行是另一套入口
+_RE_EVAL_JAVA = re.compile(r'\b(ScriptEngine|GroovyShell|GroovyClassLoader|Nashorn|'
+                           r'javax\.script|Class\.forName|MethodHandles\.lookup)\b')
+
+
+def _line_of(lens, off):
+    return lens.text.count('\n', 0, off) + 1
+
+
+def _sec_level(lens):
+    """安全问题在测试代码里降一级。
+
+    测试代码不上生产，把它判成「必修」会让必修项列表里混进一堆不影响线上的东西，
+    真正该先改的那条就被埋了。但仍然要报——测试里的注入一样能把 CI 环境打穿。
+    """
+    return 'warn' if lens.is_test else 'error'
+
+
+def check_security(lens, ctx, out):
+    lang = lens.lang
+    # ── 硬编码密钥 ──
+    for a, b, q, raw in lens.strings:
+        val = raw.strip('\'"`')
+        if len(val) < 8 or _PLACEHOLDER.search(val):
+            continue
+        ln = _line_of(lens, a)
+        line_txt = lens.line(ln)
+        if _RE_ENV_READ.search(line_txt):
+            continue                            # 值是从环境/配置来的，字面量只是键名或兜底
+        # 必须是**紧邻的赋值**：`apiKey: "…"` / `password = "…"` / `"token": "…"`。
+        # 放宽成「本行里出现过密钥词」的话，`{ ...authHeaders(apiKey), 'content-type': ct }`
+        # 这种一行里提到 apiKey 的正常代码，后面每个字符串都会被报成硬编码密钥。
+        col = a - lens.text.rfind('\n', 0, a) - 1
+        before = line_txt[:col].rstrip()
+        if not re.search(r'[\'"`]?\s*[:=]\s*$', before):
+            continue
+        name_part = re.sub(r'[\'"`]?\s*[:=]\s*$', '', before)
+        owner = re.search(r'([\w$\-]+)[\'"`]?\s*$', name_part)
+        if not owner or not _SECRET_NAME.fullmatch(owner.group(1)):
+            continue
+        if re.search(r'(提示|说明|错误|message|msg|label|title|描述|请|不要|禁止)', before, re.I):
+            continue                            # 这是在讲密钥，不是在存密钥
+        _add(out, ctx, 'security.hardcoded-secret', _sec_level(lens), lens, ln,
+             '疑似把密钥/口令直接写进了代码',
+             '挪到环境变量或密钥管理服务；已经提交过的必须视同泄露，去后台轮换一次', _unit_of(lens, ln))
+
+    # ── SQL 拼接：参数拼进语句就是注入 ──
+    for a, b, q, raw in lens.strings:
+        if not _RE_SQL.search(raw):
+            continue
+        ln = _line_of(lens, a)
+        line_txt = lens.line(ln)
+        joined = False
+        if lang in ('js', 'ts', 'vue'):
+            joined = bool(re.search(r'\$\{', raw)) or bool(re.search(r'[\'"]\s*\+|\+\s*[\'"]', line_txt))
+        elif lang == 'py':
+            joined = bool(re.search(r'^\s*f[\'"]', raw.lstrip()) or re.search(r'\{[\w.\[\]]+\}', raw)) or \
+                bool(re.search(r'%\s*[\(\w]|\.format\s*\(|[\'"]\s*\+', line_txt))
+        elif lang == 'java':
+            joined = bool(re.search(r'[\'"]\s*\+|\+\s*[\'"]', line_txt)) or 'String.format' in line_txt
+        if not joined:
+            continue
+        if re.search(r'\?|:\w+|#\{|%s.*(execute|prepare)', line_txt):
+            continue                            # 用了占位符的参数化写法
+        _add(out, ctx, 'security.sql-concat', _sec_level(lens), lens, ln,
+             'SQL 语句里拼接了变量——这是 SQL 注入的标准入口',
+             '改用参数化查询（? / :name / #{}）把值作为参数传入；表名等确实不能参数化的，用白名单校验',
+             _unit_of(lens, ln))
+
+    # ── 命令注入：拼接出来的命令字符串 ──
+    for m in _RE_EXEC.finditer(lens.code):
+        ln = _line_of(lens, m.start())
+        seg = lens.line(ln)
+        if not re.search(r'[\'"`]\s*\+|\+\s*[\'"`]|\$\{|%s|\.format\s*\(|f[\'"]', seg):
+            continue
+        if re.search(r'shell\s*=\s*False|\[\s*[\'"]', seg):
+            continue                            # 数组参数形式不经 shell，没有注入面
+        _add(out, ctx, 'security.command-injection', _sec_level(lens), lens, ln,
+             '把变量拼进了要执行的命令字符串',
+             '改成数组/列表形式传参（不经 shell 解析）；必须走 shell 时对参数做转义', _unit_of(lens, ln))
+
+    # ── 动态执行：把字符串当代码跑 ──
+    pat = _RE_EVAL_JAVA if lang == 'java' else _RE_EVAL
+    for m in pat.finditer(lens.code):
+        ln = _line_of(lens, m.start())
+        what = next((g for g in m.groups() if g), m.group(0)).strip()
+        _add(out, ctx, 'security.eval', 'warn', lens, ln,
+             f'用了 `{what}`，它会把字符串当代码/类名执行',
+             ('反射与脚本引擎的入参若来自外部，等同于任意代码执行——'
+              '入参必须走白名单，且不要让调用方决定类名/方法名') if lang == 'java'
+             else '几乎总有替代：查表分派、JSON.parse、显式的函数引用', _unit_of(lens, ln))
+
+    # ── 用不安全随机数生成令牌 ──
+    for i, ln in enumerate(lens.code_lines, 1):
+        if re.search(r'(Math\.random|random\.random|new Random\(\)|rand\(\))', ln) and \
+                _SECRET_NAME.search(ln):
+            _add(out, ctx, 'security.weak-random', 'warn', lens, i,
+                 '用普通随机数生成令牌/密钥，它是可预测的',
+                 'JS 用 crypto.randomUUID/randomBytes，Python 用 secrets，Java 用 SecureRandom',
+                 _unit_of(lens, i))
+
+
+# ══ 一致性 ══════════════════════════════════════════════════════════════════
+def check_consistency(lenses, ctx, out):
+    """跨文件的一致性。单文件体检看不见这些——它们只有把多个文件放在一起才成立。"""
+    by_name = {}
+    for lens in lenses:
+        # Java 跳过：同名不同参在 Java 里是**方法重载**，是语言特性不是缺陷；
+        # 而 Controller 从上下文取 userId 再转调 Service 的分层写法，天然就是「同名多一个参」。
+        # 实测在一个 Spring 后端上这条规则报出 151 条，无一为真。
+        if lens.lang == 'java':
+            continue
+        for u in lens.functions():
+            if u.name in ('(匿名)', 'constructor', '__init__') or not u.is_public:
+                continue
+            by_name.setdefault(u.name, []).append((lens, u))
+    for name, items in by_name.items():
+        if len(items) < 2:
+            continue
+        sigs = {len([p for p in u.params if p not in ('self', 'cls')]) for _, u in items}
+        if len(sigs) > 1 and len(items) <= 4:
+            where = '、'.join(f'{os.path.basename(str(l.path))}:{u.start}({len(u.params)}参)'
+                             for l, u in items)
+            lens0, u0 = items[0]
+            _add(out, ctx, 'consistency.signature-drift', 'info', lens0, u0.start,
+                 f'`{name}` 在多处定义但参数个数不一致：{where}',
+                 '确认是两件不同的事（那就改名），还是改了一处忘了另一处', name)
+
+
+# ══ 编排与报告 ══════════════════════════════════════════════════════════════
+CATEGORY_CN = {
+    'logic': '逻辑', 'comment': '注释', 'readability': '可读性', 'structure': '结构',
+    'test': '测试', 'security': '安全', 'consistency': '一致性', 'framework': '框架用法',
+}
+LEVEL_CN = {'error': '必修', 'warn': '建议', 'info': '提示'}
+
+
+def _collect_tested_names(paths):
+    """把测试文件里出现过的标识符收成一个集合，用于判「有没有被测到」。
+
+    口径故意放得很宽（只要名字在测试里出现过就算），因为这条规则宁可漏报也不能误报：
+    对着一个其实测过的函数说「没测」，人只会关掉这条规则。
+    """
+    names = set()
+    found = False
+    for p in paths:
+        if not L.is_test_path(p):
+            continue
+        found = True
+        try:
+            with open(p, 'r', encoding='utf-8', errors='replace') as f:
+                txt = f.read()
+        except OSError:
+            continue
+        names.update(re.findall(r'[A-Za-z_$][\w$]{2,}', txt))
+    return names, found
+
+
+def check_files(paths, **opts):
+    """体检一组文件，返回 (issues, lenses, stats)。"""
+    paths = [p for p in paths if os.path.isfile(p)]
+    tested, has_tests = _collect_tested_names(paths)
+    ctx = Ctx(tested_names=tested, has_tests=has_tests, **opts)
+    issues, lenses = [], []
+    degraded = []
+    for p in paths:
+        try:
+            lens = L.read_lens(p)
+        except OSError as e:
+            degraded.append((p, f'读不到：{e}'))
+            continue
+        lenses.append(lens)
+        if not lens.parse_ok:
+            degraded.append((p, lens.parse_error or '解析失败'))
+        check_logic(lens, ctx, issues)
+        check_comment(lens, ctx, issues)
+        check_readability(lens, ctx, issues)
+        check_structure(lens, ctx, issues)
+        check_test(lens, ctx, issues)
+        check_coverage(lens, ctx, issues)
+        check_security(lens, ctx, issues)
+    check_consistency(lenses, ctx, issues)
+    stats = {
+        'files': len(lenses),
+        'loc': sum(l.loc for l in lenses),
+        'units': sum(len(l.functions()) for l in lenses),
+        'langs': sorted({l.lang for l in lenses}),
+        'degraded': degraded,
+        'has_tests': has_tests,
+        'test_files': sum(1 for l in lenses if l.is_test),
+    }
+    issues.sort(key=lambda x: (LEVELS.index(x.level), str(x.path), x.line))
+    return issues, lenses, stats
+
+
+def counts_of(issues):
+    c = {k: 0 for k in LEVELS}
+    for i in issues:
+        c[i.level] += 1
+    return c
+
+
+def render_report(issues, stats, root='.', max_show=60, title='代码体检'):
+    """渲染成给模型和人都能直接读的文本报告。
+
+    刻意不做成「一堆告警的罗列」：先给结论与必修项，再按类别归并，
+    最后才是明细。一份看完不知道该先改哪一条的报告，等于没出。
+    """
+    c = counts_of(issues)
+    lines = []
+    head = (f'【{title}】{stats["files"]} 个文件 / {stats["loc"]} 行有效代码 / '
+            f'{stats["units"]} 个函数 · 语言 {"、".join(stats["langs"]) or "—"}')
+    lines.append(head)
+    if c['error'] == 0 and c['warn'] == 0 and c['info'] == 0:
+        scope = '逻辑/注释/可读性/结构/测试/安全/一致性'
+        frameworks = []
+        if 'java' in stats['langs']:
+            frameworks.append('Spring·MyBatis')
+        if 'py' in stats['langs']:
+            frameworks.append('pandas')
+        if frameworks:
+            scope += f'/框架用法({"·".join(frameworks)})'
+        lines.append(f'结论：未发现问题（本体检覆盖 {scope}）。')
+    else:
+        lines.append(f'结论：必修 {c["error"]} · 建议 {c["warn"]} · 提示 {c["info"]}'
+                     + ('　← 必修项清零前不要说「已完成」' if c['error'] else ''))
+    if stats['degraded']:
+        lines.append(f'⚠ 有 {len(stats["degraded"])} 个文件只做了降级检查（解析未成功），这些文件的逻辑类规则没有跑：')
+        for p, why in stats['degraded'][:5]:
+            lines.append(f'   · {os.path.relpath(p, root)}：{why}')
+    if not stats['has_tests']:
+        lines.append('ℹ 这批文件里没有测试文件，因此「测试覆盖」一类未参与体检。')
+
+    by_cat = {}
+    for i in issues:
+        by_cat.setdefault(i.rule.split('.')[0], []).append(i)
+    if by_cat:
+        seg = []
+        for cat in ('logic', 'framework', 'security', 'test', 'comment',
+                    'readability', 'structure', 'consistency'):
+            if cat in by_cat:
+                n = len(by_cat[cat])
+                e = sum(1 for x in by_cat[cat] if x.level == 'error')
+                seg.append(f'{CATEGORY_CN[cat]} {n}' + (f'(必修{e})' if e else ''))
+        lines.append('分类：' + ' · '.join(seg))
+
+    shown = 0
+    for level in LEVELS:
+        group = [i for i in issues if i.level == level]
+        if not group:
+            continue
+        lines.append('')
+        lines.append(f'── {LEVEL_CN[level]}（{len(group)}）' + ('─' * 40))
+        for i in group:
+            if shown >= max_show:
+                lines.append(f'   …… 还有 {len(issues) - shown} 条未展开'
+                             f'（用 --json 取全量，或按 --only 分类逐类处理）')
+                return '\n'.join(lines)
+            rel = os.path.relpath(str(i.path), root)
+            where = f'{rel}:{i.line}' + (f'  〔{i.unit}〕' if i.unit else '')
+            lines.append(f'  [{i.rule}] {where}')
+            if i.excerpt:
+                lines.append(f'     │ {i.excerpt}')
+            lines.append(f'     问题：{i.msg}')
+            if i.hint:
+                lines.append(f'     改法：{i.hint}')
+            shown += 1
+    return '\n'.join(lines)
+
+
+def list_rules():
+    """从本文件源码里现取规则清单，按类分组。
+
+    刻意不维护一张手写的规则表：手写的那张迟早和实现对不上，
+    而一份「说有 47 条、实际 46 条」的清单会让人怀疑整个工具的其它数字。
+    """
+    here = os.path.dirname(os.path.abspath(__file__))
+    found = {}
+    # **动态发现**所有规则文件，不写死文件名。
+    # 这个清单被写死过两次，每次加一门语言（code_java.py、code_python.py）就漏一次，
+    # 症状是「--rules 说 46 条、压测台说 78 条」这类自相矛盾——
+    # 同一个错误重复出现，说明问题不在忘了改，而在这个清单本来就不该由人维护。
+    # 压测台的 declared_rules() 也直接调用本函数，全程只有这一处实现。
+    for name in sorted(os.listdir(here)):
+        if not (name.startswith('code_') and name.endswith('.py')):
+            continue
+        if name in ('code_battery.py', 'code_lens.py'):
+            continue                     # 压测台与一把尺不声明规则
+        path = os.path.join(here, name)
+        if not os.path.exists(path):
+            continue
+        with open(path, encoding='utf-8') as f:
+            text = f.read()
+        for m in re.finditer(
+                r"\b(?:_add|add)\(out, ctx, '([a-z]+\.[a-z-]+)',\s*([_a-z'()\w]+)", text):
+            rule, level = m.group(1), m.group(2).strip("'")
+            found.setdefault(rule, level.replace('_sec_level(lens)', 'error/warn'))
+    out = {}
+    for rule, level in sorted(found.items()):
+        out.setdefault(rule.split('.')[0], []).append((rule, level))
+    return out
+
+
+def main(argv):
+    import json
+    args = [a for a in argv if not a.startswith('--')]
+    flags = {a.split('=')[0]: (a.split('=', 1)[1] if '=' in a else True) for a in argv if a.startswith('--')}
+    # 收多个目标：回合收尾自检会把本回合改过的文件一次性传进来，
+    # 一次进程跑完全部，比每个文件起一次 Python 快一个数量级（也才谈得上「顺手查一遍」）。
+    if flags.get('--rules'):
+        groups = list_rules()
+        total = sum(len(v) for v in groups.values())
+        print(f'代码体检规则清单（共 {total} 条，从实现里现取）\n')
+        for cat in ('logic', 'comment', 'readability', 'structure', 'test', 'security', 'consistency'):
+            if cat not in groups:
+                continue
+            print(f'── {CATEGORY_CN[cat]} {cat}（{len(groups[cat])}）')
+            for rule, level in groups[cat]:
+                mark = {'error': '必修', 'warn': '建议', 'info': '提示'}.get(level, level)
+                print(f'   [{mark}] {rule}' + ('  ← 可自动修' if rule in FIXABLE else ''))
+            print()
+        print('可自动修的只有：' + '、'.join(sorted(FIXABLE)))
+        return 0
+    targets = args or ['.']
+    paths = []
+    for t in targets:
+        paths.extend(L.walk_files(t) if os.path.isdir(t) else [t])
+    seen = set()
+    paths = [p for p in paths if not (p in seen or seen.add(p))]
+    first = targets[0]
+    root = first if os.path.isdir(first) else (os.path.dirname(os.path.abspath(first)) or '.')
+    if not paths:
+        out = {'error': f'{first} 下没有找到可体检的源文件'}
+        print(json.dumps(out, ensure_ascii=False))
+        return 2
+    opts = {}
+    if flags.get('--strict'):
+        opts['strict'] = True
+    if isinstance(flags.get('--only'), str):
+        opts['only'] = flags['--only'].split(',')
+    if isinstance(flags.get('--skip'), str):
+        opts['skip'] = flags['--skip'].split(',')
+    for key, name in (('--max-lines', 'max_lines'), ('--max-depth', 'max_depth'),
+                      ('--max-cx', 'max_cx'), ('--max-params', 'max_params')):
+        if isinstance(flags.get(key), str):
+            opts[name] = int(flags[key])
+    issues, lenses, stats = check_files(paths, **opts)
+    if flags.get('--json'):
+        print(json.dumps({
+            'counts': counts_of(issues),
+            'stats': {k: v for k, v in stats.items() if k != 'degraded'},
+            'degraded': [{'path': p, 'why': w} for p, w in stats['degraded']],
+            'issues': [i.to_dict() for i in issues],
+            'report': render_report(issues, stats, root),
+        }, ensure_ascii=False))
+    else:
+        print(render_report(issues, stats, root,
+                            max_show=int(flags['--max']) if isinstance(flags.get('--max'), str) else 60))
+    return 1 if counts_of(issues)['error'] else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))