@huicai/cli 2026.804.0 → 2026.1019.0

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

@@ -0,0 +1,1079 @@
+# 代码体检的「一把尺」：把任意语言的源码量成同一套结构化事实，供 code_check / code_fix 共用。
+#
+# 与 pptx_layout / docx_layout / xlsx_layout 同构——建版与体检必须共用一把尺，
+# 否则「检查器说的」和「生成器做的」是两回事，体检通过不代表东西是对的。
+#
+# ── 为什么第一件事是掩码，而不是解析 ──
+# 体检规则几乎全是在代码文本上找模式：SQL 拼接、硬编码密钥、== 误用、空 catch。
+# 如果直接在原文上跑正则，第一个撞上的就是**字符串和注释**：
+#
+#     log.info("用户表 SELECT * FROM users WHERE id = " + id)   ← 日志文案里的 SQL，不是拼接漏洞
+#     // 这里以前用 == 比较，改成 === 了                          ← 注释里的 ==，不是误用
+#     msg = "请勿把 password = 'xxx' 写进代码"                    ← 安全提示文案，不是硬编码密钥
+#
+# 一个会在这三处报警的体检器，比没有体检器更糟：人会学会无视它。
+# 所以 mask_code() 先把所有字符串字面量与注释替换成等长空格（保留换行与列位置），
+# 之后**所有**规则只在掩码后的「纯代码视图」上跑，需要原文时再按行列回查。
+#
+# 一把尺量出来的东西（Lens）：
+#   lang / lines / code(掩码后全文) / units(函数·方法·类) / comments / imports /
+#   strings(字符串字面量，安全类规则要看它) / parse_ok(解析是否成功)
+#
+# parse_ok=False 时**必须如实上报**「这个文件没能解析，只做了降级检查」——
+# 静默降级会让人以为查过了，这是比漏检更严重的欺骗。
+
+import ast
+import io
+import os
+import re
+import tokenize
+
+# ── 语言识别 ────────────────────────────────────────────────────────────────
+EXT_LANG = {
+    '.js': 'js', '.mjs': 'js', '.cjs': 'js', '.jsx': 'js',
+    '.ts': 'ts', '.tsx': 'ts', '.mts': 'ts', '.cts': 'ts',
+    '.py': 'py', '.pyi': 'py',
+    '.java': 'java',
+    '.vue': 'vue',
+    '.go': 'go', '.rs': 'rust', '.cs': 'csharp', '.php': 'php',
+    '.c': 'c', '.h': 'c', '.cc': 'cpp', '.cpp': 'cpp', '.hpp': 'cpp',
+    '.rb': 'ruby', '.kt': 'kotlin', '.swift': 'swift', '.scala': 'scala',
+    '.sh': 'shell', '.bash': 'shell', '.zsh': 'shell',
+    '.sql': 'sql',
+}
+
+# 大括号系语言：共用一套括号配对解析（JS/TS/Java 深覆盖，其余按通用规则降级）
+BRACE_LANGS = {'js', 'ts', 'java', 'go', 'rust', 'csharp', 'php', 'c', 'cpp', 'kotlin', 'swift', 'scala'}
+DEEP_LANGS = {'js', 'ts', 'py', 'java', 'vue'}     # 有专门解析器、规则集最全的语言
+
+# 不体检的目录（依赖、产物、缓存）——扫描整仓时靠它避免几十万行噪声
+SKIP_DIRS = {
+    'node_modules', '.git', 'dist', 'build', 'out', 'target', '__pycache__',
+    '.venv', 'venv', 'vendor', '.idea', '.gradle', 'coverage', '.next', '.nuxt',
+    'release', '.cache', 'site-packages', '.pytest_cache', '.mypy_cache',
+}
+# 产物/压缩文件：体检它们没有意义，且会拖垮扫描
+SKIP_FILE_RE = re.compile(r'(\.min\.(js|css)|\.bundle\.js|-lock\.json|\.d\.ts)$', re.I)
+
+
+def lang_of(path):
+    """按扩展名判语言；不认识的返回 'generic'（仍能跑语言无关规则）。"""
+    return EXT_LANG.get(os.path.splitext(str(path))[1].lower(), 'generic')
+
+
+def is_test_path(path):
+    """是否测试文件。体检对测试代码要放宽（长函数、魔法数字在测试里是常态），
+    但测试自身的质量另有一组规则（断言强度、自证循环）。"""
+    p = str(path).replace('\\', '/').lower()
+    base = os.path.basename(p)
+    return bool(
+        re.search(r'(^|/)(tests?|__tests__|spec|specs)(/|$)', p)
+        or re.match(r'^test_.*\.(py|js|ts)$', base)
+        or re.search(r'\.(test|spec)\.[cm]?[jt]sx?$', base)
+        or re.search(r'_test\.(py|go|java)$', base)
+        or re.search(r'Tests?\.(java|cs)$', os.path.basename(str(path)))
+        # C# 的测试约定：xxxTests.cs / xxxTest.cs、以及 Foo.Tests / Foo.UnitTests 项目目录。
+        # 不认它的话，C# 项目的测试代码会被按生产标准检查（长度、缺文档、覆盖率），
+        # 而测试专用规则（async void 测试）反而不生效。
+        or re.search(r'(^|/)[\w.]+\.(Tests?|UnitTests|IntegrationTests)/', p, re.I)
+        # 压测台与夹具文件里**故意**放着坏代码样本（SQL 拼接、空捕获、硬编码密钥）。
+        # 不把它们算作测试代码，体检就会把这些样本当成真缺陷报出来，
+        # 而人每次跑体检都要重新判断一遍「哦这是样本」——噪声会盖掉真问题。
+        or re.search(r'(_battery|_fixtures?|conftest|fixtures?)\.(py|js|ts|mjs|cjs)$', base)
+        or re.search(r'(^|/)fixtures?/', p)
+    )
+
+
+# ── 掩码：把字符串与注释抹成空格 ────────────────────────────────────────────
+class _Masker:
+    """逐字符扫描，维护「当前在代码 / 在字符串 / 在注释」状态机。
+
+    比正则可靠：正则处理不了嵌套引号、转义、模板串里的 ${} 插值、以及
+    「注释符号出现在字符串里」这种互相包含的情况——而这些在真实代码里遍地都是。
+    """
+
+    def __init__(self, text, lang):
+        self.src = text
+        self.lang = lang
+        self.out = []          # 掩码后的字符（与原文等长）
+        self.strings = []      # [(start_off, end_off, quote, raw)]
+        self.comments = []     # [(start_off, end_off, kind)]  kind: line|block|doc
+
+    def run(self):
+        s = self.src
+        n = len(s)
+        i = 0
+        lang = self.lang
+        # 行注释与块注释的记号按语言不同
+        if lang == 'py':
+            line_marks, block_pairs = ['#'], []
+        elif lang == 'shell':
+            line_marks, block_pairs = ['#'], []
+        elif lang == 'sql':
+            line_marks, block_pairs = ['--'], [('/*', '*/')]
+        elif lang == 'vue':
+            line_marks, block_pairs = ['//'], [('/*', '*/'), ('<!--', '-->')]
+        else:
+            line_marks, block_pairs = ['//'], [('/*', '*/')]
+        out = self.out
+        while i < n:
+            ch = s[i]
+            # 1) 块注释
+            hit = None
+            for op, cl in block_pairs:
+                if s.startswith(op, i):
+                    hit = (op, cl)
+                    break
+            if hit:
+                op, cl = hit
+                j = s.find(cl, i + len(op))
+                j = n if j < 0 else j + len(cl)
+                kind = 'doc' if s.startswith('/**', i) else 'block'
+                self.comments.append((i, j, kind))
+                out.append(self._blank(s[i:j]))
+                i = j
+                continue
+            # 2) 行注释
+            mark = next((m for m in line_marks if s.startswith(m, i)), None)
+            if mark:
+                j = s.find('\n', i)
+                j = n if j < 0 else j
+                self.comments.append((i, j, 'line'))
+                out.append(self._blank(s[i:j]))
+                i = j
+                continue
+            # 3) 字符串 / 模板串
+            if ch in '"\'`':
+                j, quote = self._scan_string(s, i, n)
+                self.strings.append((i, j, quote, s[i:j]))
+                out.append(self._blank(s[i:j]))
+                i = j
+                continue
+            # 4) 正则字面量（JS）：/pattern/flags。必须与除号区分，否则 a / b / c 会被吞掉
+            if ch == '/' and self.lang in ('js', 'ts', 'vue') and self._regex_allowed(out):
+                j = self._scan_regex(s, i, n)
+                if j > i + 1:
+                    out.append(self._blank(s[i:j]))
+                    i = j
+                    continue
+            out.append(ch)
+            i += 1
+        return ''.join(out)
+
+    @staticmethod
+    def _blank(chunk):
+        """抹成等长空白，但**保留换行**——行号与列号必须与原文严格对齐，
+        否则体检报出来的位置会指到别处，人一核对就不信这个工具了。"""
+        return ''.join('\n' if c == '\n' else ' ' for c in chunk)
+
+    def _scan_string(self, s, i, n):
+        q = s[i]
+        # Python 三引号
+        if self.lang == 'py' and s.startswith(q * 3, i):
+            j = s.find(q * 3, i + 3)
+            return (n if j < 0 else j + 3), q * 3
+        j = i + 1
+        while j < n:
+            c = s[j]
+            if c == '\\':
+                j += 2
+                continue
+            if c == q:
+                return j + 1, q
+            # 普通字符串不跨行（模板串可以）：遇换行即收，避免一个漏引号吃掉整个文件
+            if c == '\n' and q != '`':
+                return j, q
+            j += 1
+        return n, q
+
+    @staticmethod
+    def _regex_allowed(out):
+        """看前一个有效字符判断 / 是正则开头还是除号。
+        正则只能出现在「运算符/开括号/关键字」之后，不能跟在标识符或 ) ] 之后。"""
+        k = len(out) - 1
+        while k >= 0 and out[k] in ' \t\n':
+            k -= 1
+        if k < 0:
+            return True
+        prev = out[k]
+        if prev in '=(,:[!&|?{};+-*%<>~^':
+            return True
+        # return / typeof / case 等关键字之后也允许
+        tail = ''.join(out[max(0, k - 9):k + 1])
+        return bool(re.search(r'\b(return|typeof|case|in|of|delete|void|instanceof|new|do|else|yield|await)$', tail))
+
+    @staticmethod
+    def _scan_regex(s, i, n):
+        j = i + 1
+        in_class = False
+        while j < n:
+            c = s[j]
+            if c == '\\':
+                j += 2
+                continue
+            if c == '\n':
+                return i + 1          # 正则不跨行：判定失败，当普通除号
+            if c == '[':
+                in_class = True
+            elif c == ']':
+                in_class = False
+            elif c == '/' and not in_class:
+                j += 1
+                while j < n and s[j].isalpha():
+                    j += 1
+                return j
+            j += 1
+        return i + 1
+
+
+def mask_code(text, lang):
+    """返回 (code, strings, comments)：code 是字符串/注释被抹空的「纯代码视图」。
+
+    所有模式类规则都必须在 code 上跑；要看字面量内容时用 strings（已带原文）。
+    """
+    m = _Masker(text, lang)
+    code = m.run()
+    return code, m.strings, m.comments
+
+
+# ── 统一的量度单位 ──────────────────────────────────────────────────────────
+class Unit:
+    """一个可体检的代码单元：函数 / 方法 / 类。
+
+    三种语言解析出来的东西必须落到同一个形状上，规则层才不用写三遍。
+    """
+
+    __slots__ = ('kind', 'name', 'start', 'end', 'header_line', 'params', 'doc',
+                 'body', 'depth', 'complexity', 'returns', 'is_public', 'is_async',
+                 'owner', 'lang', 'decorators', 'destructured', 'ret_type', 'throws', 'modifiers',
+                 'body_line')
+
+    def __init__(self, kind, name, start, end, **kw):
+        self.kind = kind                       # function | method | class
+        self.name = name
+        self.start = start                     # 1 基：声明行
+        self.end = end                         # 1 基：结束行（含）
+        self.header_line = kw.get('header_line', start)
+        self.params = kw.get('params', [])
+        self.doc = kw.get('doc')               # 紧邻上方的文档注释原文
+        self.body = kw.get('body', '')         # 掩码后的函数体（规则在它上面跑）
+        self.depth = kw.get('depth', 0)        # 最大嵌套深度
+        self.complexity = kw.get('complexity', 1)
+        self.returns = kw.get('returns', [])
+        self.is_public = kw.get('is_public', True)
+        self.is_async = kw.get('is_async', False)
+        self.owner = kw.get('owner')           # 所属类名（方法才有）
+        self.lang = kw.get('lang', 'generic')
+        self.decorators = kw.get('decorators', [])
+        # 解构参数 `function f({ a, b })` 里的字段名。
+        # 它们不是形参，但 JSDoc 惯例正是用 `@param {object} p` + `@param p.a` 来记录它们；
+        # 不把这些字段收进来，每一份写得规范的解构文档都会被判成「写了不存在的形参」。
+        self.destructured = kw.get('destructured', [])
+        # 下面三个是 Java 规则的前提：
+        #   ret_type  —— 判「声明了返回值却只 return null」「整数除法赋给 double」
+        #   throws    —— 判「@throws 写了但方法根本不声明抛」
+        #   modifiers —— 判 @Transactional 落在 private/final 上（那样 AOP 代理根本不生效）
+        self.ret_type = kw.get('ret_type', '')
+        self.throws = kw.get('throws', [])
+        self.modifiers = kw.get('modifiers', [])
+        # 函数体（`{`）所在的行号。规则拿 body 里的偏移换算绝对行号时必须用它，
+        # 不能用 start——C# 的 Allman 风格把 `{` 放在下一行，用 start 会整体差 1。
+        self.body_line = kw.get('body_line', kw.get('start', start))
+
+    def has_annotation(self, *names):
+        """带没带某个注解（不区分是否写了参数：@Transactional 与 @Transactional(rollbackFor=…) 同等）。"""
+        for ann in self.decorators:
+            head = re.split(r'[(\s]', str(ann).lstrip('@'), 1)[0]
+            if head in names or str(ann).lstrip('@') in names:
+                return True
+        return False
+
+    @property
+    def lines(self):
+        return max(1, self.end - self.start + 1)
+
+    def line_at(self, body_offset):
+        """把「函数体内的字符偏移」换算成文件里的绝对行号。
+
+        规则里到处都要做这件事，各写各的就会各错各的——
+        尤其是 C# 这类把 `{` 放在下一行的风格，用 start 推算会整体差 1。
+        """
+        return self.body_line + str(self.body)[:max(0, body_offset)].count('\n')
+
+    @property
+    def label(self):
+        return f'{self.owner}.{self.name}' if self.owner else self.name
+
+    def __repr__(self):
+        return f'<Unit {self.kind} {self.label} L{self.start}-{self.end}>'
+
+
+class Lens:
+    """一个文件量完之后的全部事实。规则层只认它，不再碰原始文本。"""
+
+    def __init__(self, path, text, lang):
+        self.path = path
+        self.text = text
+        self.lang = lang
+        self.lines = text.split('\n')
+        self.code, self.strings, self.comments = mask_code(text, lang)
+        self.code_lines = self.code.split('\n')
+        self.units = []
+        self.imports = []
+        # 类字段：Java 侧「@Autowired 字段注入」「static SimpleDateFormat」
+        # 「单例 bean 里的可变实例字段」三条规则都建立在它上面。
+        self.fields = []
+        # Vue 单文件组件的 <template> 段（原文 + 起始行号）。
+        # script 已经被转成 js/ts 走正常解析，template 是纯标记，只能按文本查。
+        self.vue_template = None
+        self.vue_template_line = 0
+        # .vue 的 script 段会被当成 js/ts 解析，lang 因此不再是 'vue'。
+        # 规则层要判「这是不是 Vue 组件」就得靠这个标记——
+        # 用 lang 判会把所有 .vue 漏掉，用 vue_template 判会漏掉只有 script 的那些。
+        self.is_vue = lang_of(path) == 'vue'
+        self.parse_ok = True
+        self.parse_error = None
+        self.is_test = is_test_path(path)
+
+    # 行号取文本：1 基，越界返回空串（规则层不必到处判边界）
+    def line(self, no):
+        return self.lines[no - 1] if 1 <= no <= len(self.lines) else ''
+
+    def code_line(self, no):
+        return self.code_lines[no - 1] if 1 <= no <= len(self.code_lines) else ''
+
+    @property
+    def loc(self):
+        """有效代码行数（非空、非纯注释）。"""
+        return sum(1 for ln in self.code_lines if ln.strip())
+
+    def comment_lines(self):
+        """注释占用的行号集合。"""
+        s = set()
+        for a, b, _ in self.comments:
+            s.update(range(self._line_of(a), self._line_of(b) + 1))
+        return s
+
+    def _line_of(self, off):
+        return self.text.count('\n', 0, off) + 1
+
+    def functions(self):
+        return [u for u in self.units if u.kind in ('function', 'method')]
+
+    def classes(self):
+        return [u for u in self.units if u.kind == 'class']
+
+    def in_literal(self, off):
+        """这个偏移量是否落在某个字符串字面量内部。
+
+        凡是「必须在原文上定位」的规则（模式里带引号，掩码视图已把引号抹掉）
+        都要再用它过一道：否则代码生成器、文档示例、压测样本里写在字符串中的代码
+        会被当成真代码检查——报出来的每一条都是噪声。
+        """
+        for a, b, _q, _raw in self.strings:
+            if a <= off < b:
+                return True
+            if a > off:
+                break                       # strings 按偏移递增，越过就不必再找
+        return False
+
+    def unit_at(self, lineno):
+        """某一行落在哪个函数里（取最内层）。诊断要指出「在哪个函数」才有用。"""
+        best = None
+        for u in self.functions():
+            if u.start <= lineno <= u.end and (best is None or u.start > best.start):
+                best = u
+        return best
+
+
+def _doc_above(lines, start_line, lang):
+    """取声明行正上方紧邻的注释块原文（中间只许有空行）。
+
+    这是「注释优化」类规则的输入：有没有文档、文档说的和代码做的是否一致。
+    """
+    i = start_line - 2                       # 0 基，声明行的上一行
+    while i >= 0 and not lines[i].strip():
+        i -= 1
+    # C# 把文档注释写在 `[Attribute]` 上方，跳过注解行才找得到它；
+    # 不跳的话，凡是带注解的成员都会被判成「没有文档」。
+    while i >= 0 and _RE_CS_ATTRIBUTE.match(lines[i]):
+        i -= 1
+        while i >= 0 and not lines[i].strip():
+            i -= 1
+    if i < 0:
+        return None
+    buf = []
+    if lang == 'py':
+        return None                          # Python 的 docstring 在函数体内，由 ast 直接取
+    tail = lines[i].strip()
+    if tail.endswith('*/'):
+        j = i
+        while j >= 0 and '/*' not in lines[j]:
+            buf.append(lines[j])
+            j -= 1
+        if j >= 0:
+            buf.append(lines[j])
+        return '\n'.join(reversed(buf)).strip() or None
+    if tail.startswith('//'):
+        j = i
+        while j >= 0 and lines[j].strip().startswith('//'):
+            buf.append(lines[j].strip())
+            j -= 1
+        return '\n'.join(reversed(buf)).strip() or None
+    return None
+
+
+# ── Python：走标准库 ast，事实最准 ─────────────────────────────────────────
+# 判定分支的节点类型。圈复杂度 = 1 + 分支数，衡量「这个函数有多少条路要测」。
+_PY_BRANCH = (ast.If, ast.For, ast.AsyncFor, ast.While, ast.ExceptHandler,
+              ast.With, ast.AsyncWith, ast.Assert, ast.IfExp, ast.comprehension)
+_PY_NEST = (ast.If, ast.For, ast.AsyncFor, ast.While, ast.With, ast.AsyncWith, ast.Try)
+
+
+def _py_complexity(node):
+    n = 1
+    for sub in ast.walk(node):
+        if isinstance(sub, _PY_BRANCH):
+            n += 1
+        elif isinstance(sub, ast.BoolOp):
+            n += len(sub.values) - 1          # a and b and c = 两个额外分支
+    return n
+
+
+def _py_depth(node, cur=0):
+    best = cur
+    for child in ast.iter_child_nodes(node):
+        step = 1 if isinstance(child, _PY_NEST) else 0
+        best = max(best, _py_depth(child, cur + step))
+    return best
+
+
+def parse_python(lens):
+    try:
+        tree = ast.parse(lens.text)
+    except SyntaxError as e:
+        lens.parse_ok = False
+        lens.parse_error = f'第 {e.lineno} 行语法错误：{e.msg}'
+        return
+    stack = []                                 # 当前所处的类名栈
+
+    def end_of(node):
+        return getattr(node, 'end_lineno', None) or node.lineno
+
+    def visit(node, owner=None, in_func=False):
+        """递归登记类与函数。
+
+        in_func 标记「当前是否已经在某个函数体内」——嵌套函数（闭包、局部 helper）
+        外部根本拿不到，把它们判成「对外可见」会凭空要求一堆文档注释，
+        而误报的文档要求最终会让人把整条 missing-doc 规则关掉。
+        """
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, ast.ClassDef):
+                lens.units.append(Unit(
+                    'class', child.name, child.lineno, end_of(child),
+                    doc=ast.get_docstring(child), lang='py', owner=owner,
+                    is_public=not child.name.startswith('_') and not in_func,
+                    decorators=[ast.unparse(d) for d in child.decorator_list],
+                    body=_slice(lens.code, child.lineno, end_of(child)),
+                ))
+                stack.append(child.name)
+                visit(child, child.name, in_func)
+                stack.pop()
+            elif isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                args = child.args
+                params = [a.arg for a in (args.posonlyargs + args.args + args.kwonlyargs)]
+                if args.vararg:
+                    params.append('*' + args.vararg.arg)
+                if args.kwarg:
+                    params.append('**' + args.kwarg.arg)
+                rets = [s.lineno for s in ast.walk(child) if isinstance(s, ast.Return)]
+                lens.units.append(Unit(
+                    'method' if owner else 'function', child.name, child.lineno, end_of(child),
+                    params=params, doc=ast.get_docstring(child), lang='py', owner=owner,
+                    complexity=_py_complexity(child), depth=_py_depth(child),
+                    returns=rets, is_async=isinstance(child, ast.AsyncFunctionDef),
+                    # 私有类的方法、以及嵌套在函数里的局部函数，外部都够不着
+                    is_public=(not child.name.startswith('_') and not in_func
+                               and not (owner or '').startswith('_')),
+                    decorators=[ast.unparse(d) for d in child.decorator_list],
+                    body=_slice(lens.code, child.lineno, end_of(child)),
+                    header_line=child.lineno, body_line=child.lineno,
+                ))
+                visit(child, owner, True)      # 嵌套函数也要量，但它们不对外
+            elif isinstance(child, (ast.Import, ast.ImportFrom)):
+                mod = getattr(child, 'module', None) or ''
+                for a in child.names:
+                    lens.imports.append({'name': a.name, 'module': mod, 'line': child.lineno,
+                                         'alias': a.asname})
+            else:
+                visit(child, owner, in_func)
+
+    visit(tree)
+    lens.units.sort(key=lambda u: (u.start, u.end))
+    lens._ast = tree                            # 深度规则（可变默认参、空 except）直接复用
+
+
+def _slice(code, start, end):
+    """按 1 基行号取掩码视图的片段。"""
+    return '\n'.join(code.split('\n')[start - 1:end])
+
+
+# ── 大括号语言：JS / TS / Java 共用一套括号配对 ────────────────────────────
+# 声明式函数：function f() / async function f() / export default function f()
+_RE_JS_FUNC = re.compile(
+    r'(?:^|[\s;{}()])(?:export\s+)?(?:default\s+)?(async\s+)?function\s*(\*\s*)?([A-Za-z_$][\w$]*)?\s*\(')
+# 赋值式函数：const f = (...) => / let f = async function(...)
+_RE_JS_ASSIGN = re.compile(
+    r'(?:^|[\s;{}])(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*'
+    r'(async\s+)?(?:function\s*(?:\*\s*)?[\w$]*\s*)?\(')
+# 类方法 / 对象方法：  name(a, b) {   |  async name() {  |  get name() {
+_RE_JS_METHOD = re.compile(
+    r'^[ \t]*(?:(?:public|private|protected|readonly|static|abstract|override)\s+)*'
+    r'(async\s+)?(?:(get|set)\s+)?(?:\*\s*)?([A-Za-z_$#][\w$]*)\s*(?:<[^>(]*>)?\s*\(', re.M)
+_RE_JS_CLASS = re.compile(r'(?:^|\s)(?:export\s+)?(?:default\s+)?(?:abstract\s+)?(class|interface)\s+([A-Za-z_$][\w$]*)')
+# Java 方法：修饰符 + 返回类型 + 名字(  —— 必须排掉 if/for/while/catch/switch 这些「长得像调用」的关键字
+_RE_JAVA_METHOD = re.compile(
+    r'^[ \t]*((?:(?:public|private|protected|static|final|synchronized|abstract|native|default|strictfp)\s+)*)'
+    r'(?:<[^>]+>\s*)?'
+    r'([A-Za-z_$][\w$<>\[\],.\s?]*?)\s+'
+    r'([A-Za-z_$][\w$]*)\s*\(', re.M)
+_RE_JAVA_TYPE = re.compile(
+    r'(?:^|\s)((?:public|private|protected|static|final|abstract|sealed)\s+)*'
+    r'(class|interface|enum|record)\s+([A-Za-z_$][\w$]*)')
+# C# 与 Java 形态相近，但修饰符更多、类型种类更多（record/struct），
+# 且注解写成 `[Attribute]` 而不是 `@Attribute`。
+# 改造前 C# 落在 parse_braces 的 js/java 两个分支之间的空隙里——
+# 只认得出 class，**方法一个都解析不到**，而 parse_ok 仍然是 True。
+# 于是所有基于函数的规则（长度、复杂度、缺文档、无测试覆盖）在 C# 上静默失效，
+# 报告却照样说「未发现问题」——规则不响和代码干净，看起来一模一样。
+_CS_MODIFIERS = (r'public|private|protected|internal|static|async|override|virtual|abstract'
+                 r'|sealed|partial|extern|unsafe|new|readonly|required|volatile|const|file')
+_RE_CS_METHOD = re.compile(
+    r'^[ \t]*((?:(?:' + _CS_MODIFIERS + r')\s+)*)'
+    r'(?:<[^>]+>\s*)?'
+    r'([A-Za-z_@][\w<>\[\],.\s?]*?)\s+'
+    r'([A-Za-z_@][\w]*)\s*(?:<[^>(]*>)?\s*\(', re.M)
+_RE_CS_TYPE = re.compile(
+    r'(?:^|\s)(?:(?:' + _CS_MODIFIERS + r')\s+)*'
+    r'(class|interface|struct|record|enum)\s+([A-Za-z_@][\w]*)')
+# `[Serializable]` / `[HttpGet("/x")]` / `[Obsolete("理由")]`
+_RE_CS_ATTRIBUTE = re.compile(r'^\s*\[([A-Za-z_][\w.]*)\s*(\([^\n]*\))?\s*\]\s*$')
+
+_KEYWORD_CALL = {'if', 'for', 'while', 'switch', 'catch', 'return', 'do', 'else', 'try',
+                 'synchronized', 'new', 'super', 'this', 'throw', 'case', 'with', 'yield', 'await'}
+# 分支关键字：圈复杂度按它数（&&/||/?: 也算——每一个都是一条独立的路）
+_RE_BRANCH = re.compile(r'\b(if|for|while|case|catch|elif|else\s+if)\b|\?\.?\s*[^.:]|&&|\|\||\?\?')
+
+
+def _match_brace(code, open_idx):
+    """从 open_idx 处的 '{' 找到配对 '}'，返回其下标；找不到返回 -1。
+
+    在**掩码后**的视图上配对——原文里字符串中的 { } 会把配对带偏，
+    而那正是「函数体范围算错 → 整份体检指错位置」的经典来源。
+    """
+    depth = 0
+    for i in range(open_idx, len(code)):
+        c = code[i]
+        if c == '{':
+            depth += 1
+        elif c == '}':
+            depth -= 1
+            if depth == 0:
+                return i
+    return -1
+
+
+def _line_at(code, off):
+    return code.count('\n', 0, off) + 1
+
+
+def _skip_lead(code, off):
+    """跳过声明正则吃进来的前导分隔符。
+
+    `(?:^|[\\s;{}()])function` 这类写法会把上一行的换行符算进匹配，
+    起始行就整体偏到上一行——报出来的位置差一行，人一核对就不信这份报告了。
+    """
+    while off < len(code) and code[off] in ' \t\n;{}()':
+        off += 1
+    return off
+
+
+def _params_of(code, lparen):
+    """从 '(' 处取形参，返回 (形参名列表, ')' 下标, 解构字段名列表)。
+
+    解构参数按**一个**形参计（`f({a,b,c,d,e,f,g})` 是「一个选项对象」这种好写法，
+    不该被判成「七个参数太多」），但里面的字段名要单独收着——JSDoc 用 `p.a` 记录它们。
+    """
+    depth = 0
+    for i in range(lparen, len(code)):
+        if code[i] == '(':
+            depth += 1
+        elif code[i] == ')':
+            depth -= 1
+            if depth == 0:
+                raw = code[lparen + 1:i]
+                out, fields = [], []
+                for seg in _split_top(raw, ','):
+                    seg = seg.strip()
+                    if not seg:
+                        continue
+                    if seg.startswith('{') or seg.startswith('['):
+                        inner = seg[1:seg.rfind('}')] if '}' in seg else seg[1:]
+                        for f in _split_top(inner, ','):
+                            mm = re.match(r'\s*(?:\.\.\.)?([A-Za-z_$][\w$]*)', f)
+                            if mm:
+                                fields.append(mm.group(1))
+                        out.append('{}')
+                        continue
+                    seg = re.sub(r'=.*$', '', seg).strip()          # 默认值
+                    seg = re.sub(r':\s*[\w<>\[\]|&.,\s?]+$', '', seg).strip()  # TS 类型标注
+                    m = re.search(r'([A-Za-z_$][\w$]*)\s*$', seg)
+                    out.append(m.group(1) if m else seg[:24])
+                return out, i, fields
+    return [], lparen, []
+
+
+def _split_top(s, sep):
+    """只在顶层切分（跳过 () [] {} <> 内的分隔符）。"""
+    out, buf, depth = [], [], 0
+    for ch in s:
+        if ch in '([{<':
+            depth += 1
+        elif ch in ')]}>':
+            depth -= 1
+        if ch == sep and depth <= 0:
+            out.append(''.join(buf))
+            buf = []
+        else:
+            buf.append(ch)
+    out.append(''.join(buf))
+    return out
+
+
+def _depth_of(body):
+    """函数体的最大花括号嵌套深度（body 已是掩码视图，字符串里的括号不会干扰）。"""
+    depth = best = 0
+    for c in body:
+        if c == '{':
+            depth += 1
+            best = max(best, depth)
+        elif c == '}':
+            depth -= 1
+    return max(0, best - 1)          # 减掉函数体自身那一层
+
+
+def _complexity_of(body):
+    return 1 + len(_RE_BRANCH.findall(body))
+
+
+def parse_braces(lens):
+    """JS / TS / Java 的统一解析：扫掩码视图找声明，再靠括号配对定边界。
+
+    没有用真 AST，是权衡后的选择：托管 Python 里没有可靠的 JS/Java 解析器，
+    引入外部依赖会让「首次体检要装包」——那等于让体检在最需要它的时候不可用。
+    括号配对 + 掩码视图对「函数从哪到哪、有多深、多复杂」这几件事足够准，
+    而这正是体检要量的东西。真正需要类型信息的规则一律不做，不猜。
+    """
+    code = lens.code
+    lang = lens.lang
+    seen = set()                                # 同一个 '(' 只认一次，避免多条正则重复命中
+
+    def add(kind, name, hdr_off, lparen, is_async=False, owner=None, strict=False, extra=None):
+        hdr_off = _skip_lead(code, hdr_off)
+        params, rparen, fields = _params_of(code, lparen)
+        brace = code.find('{', rparen)
+        arrow = code.find('=>', rparen)
+        # 箭头函数可能没有花括号体：const f = (a) => a + 1
+        if 0 <= arrow < (brace if brace >= 0 else len(code)) and lang in ('js', 'ts', 'vue'):
+            nxt = code.find('{', arrow)
+            semi = code.find('\n', arrow)
+            if nxt < 0 or (0 <= semi < nxt and code[arrow + 2:nxt].strip()):
+                start = _line_at(code, hdr_off)
+                end = _line_at(code, semi if semi > 0 else len(code) - 1)
+                body = _slice(code, start, end)
+                lens.units.append(Unit(
+                    kind, name, start, end, params=params, lang=lang, owner=owner,
+                    destructured=fields,
+                    is_async=is_async, body=body, depth=0, complexity=_complexity_of(body),
+                    doc=_doc_above(lens.lines, start, lang),
+                    is_public=_is_public(lens.lines[start - 1] if start <= len(lens.lines) else '', name, lang, owner),
+                ))
+                return end
+        if brace < 0:
+            return None
+        # `)` 与 `{` 之间只允许返回类型标注(TS)/throws(Java)/修饰符。
+        # 这一关是防「行首的普通函数调用被当成函数声明」的闸：
+        #     doSomething(arg);\n    if (x) {     ← 中间夹着 ; 就不是函数头
+        between = code[rparen + 1:brace]
+        if strict or lang == 'java':
+            if ';' in between or '=' in between.replace('=>', '') or len(between) > 160:
+                return None
+        elif code.count('\n', rparen, brace) > 3:
+            return None
+        close = _match_brace(code, brace)
+        if close < 0:
+            return None
+        start = _line_at(code, hdr_off)
+        end = _line_at(code, close)
+        body = code[brace:close + 1]
+        header = lens.lines[start - 1] if start <= len(lens.lines) else ''
+        java_extra = extra or {}
+        if lang in ('java', 'csharp'):
+            # throws 只可能出现在 `)` 与 `{` 之间；注解只可能在声明行上方
+            thrown = re.search(r'\bthrows\s+([\w$.,<>\s]+)$', between.strip())
+            java_extra.setdefault('throws',
+                                  [x.strip() for x in thrown.group(1).split(',')] if thrown else [])
+            # C# 的注解已在调用处取好（写法是 `[Attr]` 而不是 `@Attr`），这里只给 Java 兜底
+            if lang == 'java':
+                java_extra.setdefault('decorators', _annotations_above(lens.lines, start))
+        lens.units.append(Unit(
+            kind, name, start, end, params=params, lang=lang, owner=owner,
+            destructured=fields, body_line=_line_at(code, brace),
+            ret_type=java_extra.get('ret_type', ''), throws=java_extra.get('throws', []),
+            modifiers=java_extra.get('modifiers', []),
+            decorators=java_extra.get('decorators', []),
+            is_async=is_async, body=body, depth=_depth_of(body),
+            complexity=_complexity_of(body),
+            returns=[start + i for i, ln in enumerate(body.split('\n')) if re.search(r'\breturn\b', ln)],
+            doc=_doc_above(lens.lines, start, lang),
+            is_public=_is_public(header, name, lang, owner),
+            header_line=start,
+        ))
+        return end
+
+    # 1) 类型声明（class / interface / enum / record）——先登记，方法才知道自己的 owner
+    class_ranges = []
+    pat = {'java': _RE_JAVA_TYPE, 'csharp': _RE_CS_TYPE}.get(lang, _RE_JS_CLASS)
+    for m in pat.finditer(code):
+        name = m.group(3) if lang == 'java' else m.group(2)
+        kind_word = m.group(2) if lang == 'java' else m.group(1)
+        if lang == 'csharp':
+            kind_word, name = m.group(1), m.group(2)
+        brace = code.find('{', m.end())
+        semi = code.find(';', m.end())
+        # positional record：`public record Order(long Id, decimal Amount);` 没有花括号体。
+        # 不认它的话，这一整类声明在 C# 项目里都不会被登记成类型。
+        if lang == 'csharp' and 0 <= semi < (brace if brace >= 0 else len(code)):
+            start = _line_at(code, _skip_lead(code, m.start()))
+            lens.units.append(Unit('class', name, start, start, lang=lang,
+                                   doc=_doc_above(lens.lines, start, lang),
+                                   body='', decorators=[kind_word]))
+            continue
+        if brace < 0:
+            continue
+        close = _match_brace(code, brace)
+        if close < 0:
+            continue
+        start, end = _line_at(code, _skip_lead(code, m.start())), _line_at(code, close)
+        lens.units.append(Unit('class', name, start, end, lang=lang,
+                               doc=_doc_above(lens.lines, start, lang),
+                               body=code[brace:close + 1],
+                               decorators=([kind_word] + _annotations_above(lens.lines, start)
+                                           if lang == 'java' else [kind_word])))
+        class_ranges.append((brace, close, name))
+
+    def owner_of(off):
+        best = None
+        for a, b, nm in class_ranges:
+            if a <= off <= b and (best is None or a > best[0]):
+                best = (a, nm)
+        return best[1] if best else None
+
+    # 2) 函数与方法
+    if lang in ('js', 'ts', 'vue'):
+        for m in _RE_JS_FUNC.finditer(code):
+            lp = code.index('(', m.end() - 1)
+            if lp in seen:
+                continue
+            seen.add(lp)
+            add('function' if not owner_of(m.start()) else 'method',
+                m.group(3) or '(匿名)', m.start(), lp, bool(m.group(1)), owner_of(m.start()))
+        for m in _RE_JS_ASSIGN.finditer(code):
+            lp = code.index('(', m.end() - 1)
+            if lp in seen:
+                continue
+            seen.add(lp)
+            add('function', m.group(1), m.start(), lp, bool(m.group(2)), owner_of(m.start()))
+        for m in _RE_JS_METHOD.finditer(code):
+            name = m.group(3)
+            if name in _KEYWORD_CALL:
+                continue
+            lp = m.end() - 1
+            if lp in seen:
+                continue
+            own = owner_of(m.start())
+            seen.add(lp)
+            add('method' if own else 'function', name, m.start(), lp, bool(m.group(1)), own, strict=True)
+    elif lang == 'csharp':
+        # record 的主构造函数 `public record Order(long Id);` 长得像方法，先把类型所在行排除掉
+        type_starts = {_line_at(code, a) for a, _b, _n in class_ranges}
+        for m in _RE_CS_METHOD.finditer(code):
+            name, rtype = m.group(3), (m.group(2) or '').strip()
+            if name in _KEYWORD_CALL or rtype in ('return', 'throw', 'else', 'new', 'await', 'yield'):
+                continue
+            if _line_at(code, m.start()) in type_starts:
+                continue                      # 这一行是 record/class 声明，不是方法
+            lp = m.end() - 1
+            if lp in seen:
+                continue
+            seen.add(lp)
+            # 构造函数没有返回类型，正则会把修饰符当成返回类型（`public Foo(` → rtype='public'）
+            is_ctor = rtype in _CS_MODIFIERS.split('|')
+            add('method', name, m.start(), lp, 'async' in (m.group(1) or ''),
+                owner_of(m.start()), strict=True,
+                extra={'ret_type': '' if is_ctor else rtype,
+                       'modifiers': (m.group(1) or '').split(),
+                       'decorators': _cs_attributes_above(lens.lines, _line_at(code, m.start()))})
+    elif lang == 'java':
+        for m in _RE_JAVA_METHOD.finditer(code):
+            name, rtype = m.group(3), (m.group(2) or '').strip()
+            if name in _KEYWORD_CALL or rtype.split()[-1:] == ['new']:
+                continue
+            if rtype in ('return', 'throw', 'else', 'new'):
+                continue
+            lp = m.end() - 1
+            if lp in seen:
+                continue
+            seen.add(lp)
+            add('method', name, m.start(), lp, False, owner_of(m.start()), strict=True,
+                extra={'ret_type': rtype, 'modifiers': (m.group(1) or '').split()})
+    # 3) import
+    imp = (re.compile(r'^\s*import\s+(?:type\s+)?(?:(.+?)\s+from\s+)?[\'"]([^\'"]+)[\'"]', re.M)
+           if lang != 'java' else re.compile(r'^\s*import\s+(?:static\s+)?([\w.$*]+)\s*;', re.M))
+    for m in imp.finditer(lens.text):
+        lens.imports.append({'name': (m.group(1) or '').strip(), 'module': m.group(len(m.groups())),
+                             'line': lens.text.count('\n', 0, m.start()) + 1, 'alias': None})
+    if lang in ('java', 'csharp'):
+        # 字段要在方法登记完之后收——它靠「不在任何方法范围内」把字段和局部变量分开。
+        # C# 的字段声明形态与 Java 足够接近（修饰符 类型 名字 [= 初值];），共用同一套。
+        _collect_java_fields(lens, class_ranges)
+    # 去重（同一 '(' 被两条正则捞到时留范围大的那条）与排序
+    uniq = {}
+    for u in lens.units:
+        key = (u.kind, u.name, u.start)
+        if key not in uniq or u.end > uniq[key].end:
+            uniq[key] = u
+    lens.units = sorted(uniq.values(), key=lambda u: (u.start, u.end))
+
+
+# 注解可以连着写好几行，也可以带很长的参数：@RequestMapping(value = "/x", method = POST)
+_RE_ANNOTATION_LINE = re.compile(r'^\s*@([A-Za-z_$][\w$.]*)\s*(\([^\n]*\))?\s*$')
+
+
+def _cs_attributes_above(lines, start_line):
+    """取声明行上方连续的 `[Attribute]`（C# 的注解写法）。
+
+    与 Java 的 `@Xxx` 是同一个角色：`[HttpGet]`、`[Obsolete]`、`[Fact]` 决定了
+    这个成员在框架里怎么被使用，几条 C# 规则都要看它。
+    """
+    out = []
+    i = start_line - 2
+    while i >= 0:
+        raw = lines[i].strip()
+        if not raw:
+            i -= 1
+            continue
+        m = _RE_CS_ATTRIBUTE.match(lines[i])
+        if not m:
+            break
+        out.append('[' + m.group(1) + (m.group(2) or '') + ']')
+        i -= 1
+    return out
+
+
+def _annotations_above(lines, start_line):
+    """取声明行正上方连续的注解（允许夹空行与注解自身的换行参数）。
+
+    注解是 Java 规则的主要抓手：@Transactional 落在哪、@Test 有没有断言、
+    @Autowired 是不是字段注入——全靠它。往上扫而不是正则整块匹配，
+    是因为注解参数里可以带花括号与逗号，正则一旦贪心就会吃掉上一个方法。
+    """
+    out = []
+    i = start_line - 2                       # 0 基，声明行的上一行
+    while i >= 0:
+        raw = lines[i].strip()
+        if not raw:
+            i -= 1
+            continue
+        m = _RE_ANNOTATION_LINE.match(lines[i])
+        if m:
+            out.append('@' + m.group(1) + (m.group(2) or ''))
+            i -= 1
+            continue
+        # 注解参数换行的情形：`)` 收尾，往上找到 `@Xxx(` 那一行
+        if raw.endswith(')') and not raw.endswith(';'):
+            j = i
+            buf = []
+            while j >= 0 and not re.match(r'^\s*@[A-Za-z_$]', lines[j]):
+                buf.append(lines[j].strip())
+                j -= 1
+                if start_line - j > 12:      # 别无限往上找
+                    return out
+            if j >= 0:
+                head = re.match(r'^\s*@([A-Za-z_$][\w$.]*)', lines[j])
+                if head:
+                    out.append('@' + head.group(1) + '(…)')
+                    i = j - 1
+                    continue
+        break
+    return out
+
+
+# 字段声明：`private final OrderRepo repo;` / `private static SimpleDateFormat FMT = new …;`
+_RE_JAVA_FIELD = re.compile(
+    r'^[ \t]*((?:(?:public|private|protected|internal|static|final|transient|volatile'
+    r'|readonly|const|required|new|abstract|override|sealed)\s+)*)'
+    r'([A-Za-z_$][\w$<>\[\],.\s?]*?)\s+'
+    r'([A-Za-z_$][\w$]*)\s*(=[^;]*)?;\s*$', re.M)
+
+
+def _collect_java_fields(lens, class_ranges):
+    """收集类字段。只认「类体内、方法体外」的声明——方法里的局部变量长得一模一样。"""
+    code = lens.code
+    method_spans = [(u.start, u.end) for u in lens.units if u.kind == 'method']
+    for m in _RE_JAVA_FIELD.finditer(code):
+        ln = _line_at(code, m.start())
+        if any(a <= ln <= b for a, b in method_spans):
+            continue                          # 方法体内 = 局部变量，不是字段
+        owner = None
+        for a, b, nm in class_ranges:
+            if _line_at(code, a) <= ln <= _line_at(code, b):
+                owner = nm
+        if owner is None:
+            continue
+        mods = (m.group(1) or '').split()
+        lens.fields.append({
+            'name': m.group(3), 'type': (m.group(2) or '').strip(), 'line': ln,
+            'modifiers': mods, 'owner': owner, 'init': (m.group(4) or '').strip(),
+            'annotations': _annotations_above(lens.lines, ln),
+        })
+
+
+def _is_public(header, name, lang, owner=None):
+    if lang == 'java':
+        return 'public' in header or not re.search(r'\b(private|protected)\b', header)
+    if name.startswith('_') or name.startswith('#'):
+        return False
+    if re.search(r'\b(private|protected)\b', header):
+        return False
+    # 类方法默认对外可见——它不写 export，但外部拿到实例就能调
+    return 'export' in header or owner is not None
+
+
+def parse_generic(lens):
+    """降级解析：靠缩进与「看起来像函数头」的行做粗切分。
+
+    覆盖不到的语言仍能跑语言无关规则（函数过长、注释密度、TODO、行宽、硬编码密钥），
+    但**不会**去猜它做不到的事——报告里会写明这是降级模式。
+    """
+    pat = re.compile(
+        r'^[ \t]*(?:(?:pub|public|private|protected|static|final|func|fn|def|sub|function|proc)\s+)+'
+        r'[\w<>\[\]:*&,\s]*?([A-Za-z_][\w]*)\s*\(')
+    hits = [(m.start(), m.group(1)) for m in pat.finditer(lens.code)]
+    for i, (off, name) in enumerate(hits):
+        start = _line_at(lens.code, off)
+        end = (_line_at(lens.code, hits[i + 1][0]) - 1) if i + 1 < len(hits) else len(lens.lines)
+        body = _slice(lens.code, start, end)
+        lens.units.append(Unit('function', name, start, max(start, end), lang=lens.lang,
+                               body=body, complexity=_complexity_of(body), depth=_depth_of(body),
+                               doc=_doc_above(lens.lines, start, lens.lang)))
+
+
+def _vue_script(text):
+    """从 .vue 单文件组件里抠出 <script> 段，连同它的起始行偏移。"""
+    m = re.search(r'<script[^>]*>(.*?)</script>', text, re.S | re.I)
+    if not m:
+        return None, 0
+    return m.group(1), text.count('\n', 0, m.start(1))
+
+
+def _vue_template(text):
+    """抠出顶层 <template> 段，返回 (原文, 起始行号)；没有则 (None, 0)。
+
+    Vue 的一半问题在 template 里——`v-for` 少了 `:key`、`v-if` 与 `v-for` 写在同一个元素上、
+    `v-html` 塞用户输入。改造前这一段被整个丢弃（只抠 script），
+    于是这些最常见的问题一条也查不到，而报告照样显示「已体检」。
+
+    只认**行首**的 `<template`：组件内部的具名插槽 `<template #header>` 是缩进的，
+    不该被当成顶层模板；结束位置取最后一个 `</template>`，因为插槽会造成嵌套。
+    """
+    m = re.search(r'^[ \t]*<template[^>]*>', text, re.M | re.I)
+    if not m:
+        return None, 0
+    end = text.rfind('</template>')
+    if end <= m.end():
+        return None, 0
+    return text[m.end():end], text.count('\n', 0, m.end()) + 1
+
+
+def read_lens(path, text=None, lang=None):
+    """量一个文件。text 可直接传入（压测与内存中的内容用），否则从磁盘读。"""
+    if text is None:
+        with open(path, 'r', encoding='utf-8', errors='replace') as f:
+            text = f.read()
+    lang = lang or lang_of(path)
+    offset = 0
+    vue_template, vue_template_line = None, 0
+    raw_text = None
+    if lang == 'vue':
+        vue_template, vue_template_line = _vue_template(text)
+        raw_text = text
+        script, offset = _vue_script(text)
+        if script is None:
+            lang = 'generic'
+        else:
+            text = '\n' * offset + script          # 补回行偏移，行号仍对得上原文件
+            lang = 'ts' if re.search(r'<script[^>]+lang=["\']ts', text) else 'js'
+    lens = Lens(path, text, lang)
+    if vue_template is not None:
+        lens.vue_template = vue_template
+        lens.vue_template_line = vue_template_line
+    if raw_text is not None:
+        # .vue 的解析用的是「补齐换行的 script 段」，行号与原文对齐但内容不是原文：
+        # template 所在的那些行在解析文本里是空的。
+        # 而 lens.line() 是**呈现与豁免**的入口（报告里的源码摘录、就地 ignore 注释都走它），
+        # 所以它必须看原文——否则 template 里的问题报出来只有行号、没有内容，
+        # 写在 template 上的豁免注释也永远读不到。
+        # code_lines（掩码视图）仍是 script，规则照旧只在真代码上跑。
+        lens.lines = raw_text.split('\n')
+    try:
+        if lang == 'py':
+            parse_python(lens)
+        elif lang in BRACE_LANGS:
+            parse_braces(lens)
+        else:
+            parse_generic(lens)
+    except Exception as e:                          # 解析器自身出错：降级但**如实记录**
+        lens.parse_ok = False
+        lens.parse_error = f'{type(e).__name__}: {e}'
+        lens.units = []
+        try:
+            parse_generic(lens)
+        except Exception as e2:
+            # 连降级解析都失败：把两次失败都记进 parse_error。
+            # 这里若 pass 掉，报告只会说「解析失败」而说不出降级也没成，
+            # 人就无从判断这个文件到底被检查了多少——静默降级比漏检更糟。
+            lens.parse_error += f'；降级解析同样失败：{type(e2).__name__}: {e2}'
+    return lens
+
+
+def walk_files(root, exts=None, limit=4000):
+    """遍历待体检的源文件（跳过依赖/产物/压缩文件）。"""
+    out = []
+    root = os.path.abspath(root)
+    if os.path.isfile(root):
+        return [root]
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith('.')]
+        for fn in filenames:
+            ext = os.path.splitext(fn)[1].lower()
+            if ext not in EXT_LANG:
+                continue
+            if SKIP_FILE_RE.search(fn):
+                continue
+            if exts and ext not in exts:
+                continue
+            out.append(os.path.join(dirpath, fn))
+            if len(out) >= limit:
+                return out
+    return out