# 在你的项目根目录执行
mkdir -p .claude/skills/complexity-scan/scripts
mkdir -p .claude/skills/complexity-scan/references

.claude/skills/complexity-scan/
├── SKILL.md                 # 入口：元数据 + 指令正文
├── scripts/
│   └── scan.py              # 真正干活的度量脚本
└── references/
    └── metrics.md           # 指标定义与阈值（按需加载）

---
name: complexity-scan
description: 扫描代码复杂度热点。度量函数行数、嵌套深度、圈复杂度，按重构优先级排序输出 Top 函数清单。当用户想找出最该重构的函数、做代码评审、评估技术债优先级、或提到"圈复杂度/嵌套太深/函数太长/重构哪些函数"时使用。
---

# 代码复杂度热点扫描

## 何时使用
用户需要定位"最该重构的函数"，或代码评审/技术债盘点时。

## 执行步骤
1. 确认目标目录与语言。默认扫描当前工作目录的 `src/`，语言自动识别。
2. 运行度量脚本：
   `python3 scripts/scan.py <目录> [--top N] [--format json|md]`
3. 读取脚本输出的 Markdown 清单，对 Top 函数逐条给出"为何复杂 + 一句话重构建议"。
4. 若用户追问指标定义，再读取 `references/metrics.md` 解释。

## 输出格式
先给一张 Top N 表（函数、文件:行、loc/depth/ccn、score），再给 2-4 条优先重构建议。

## 注意
- 启发式度量有误差，对宏/模板/字符串里的关键字会高估，结论需结合人工判断。
- 默认只读，不修改任何源码。

#!/usr/bin/env python3
# complexity-scan/scripts/scan.py
import os, re, sys, json, argparse

# 决策关键字 -> 圈复杂度贡献
DECISIONS = re.compile(
    r'\b(if|else if|elif|for|while|case|catch|except|and|or)\b'
    r'|\&\&|\|\||\?'
)
# 函数签名启发式（覆盖 C/Java/JS/TS/Go 风格 + Python def）
FUNC_SIG = re.compile(
    r'^\s*'
    r'(?:public|private|protected|static|async|export|export default|func|def|fun)\s+'
    r'.*?\(.*?\)\s*(?:{|:)'
    r'|^\s*def\s+\w+\s*\(.*?\)\s*'
)

def parse_file(path):
    """返回该文件中的函数列表，每项含指标字典。"""
    try:
        with open(path, encoding='utf-8', errors='ignore') as f:
            lines = f.readlines()
    except OSError:
        return []

    funcs, i, n = [], 0, len(lines)
    while i < n:
        if FUNC_SIG.match(lines[i]):
            start = i
            depth, peak, ccn, body = 0, 0, 0, 0
            # 定位函数体起始大括号（或 Python 的缩进块）
            while i < n and '{' not in lines[i] and lines[i].strip() != '':
                i += 1
            j = i
            while j < n:
                ln = lines[j]
                body += 1
                depth += ln.count('{') - ln.count('}')
                peak = max(peak, depth)
                ccn += len(DECISIONS.findall(ln))
                j += 1
                # 大括号回到 0 或以下表示函数结束
                if depth <= 0 and j > start + 1:
                    break
            # Python 无大括号：用后续缩进收尾的简单兜底
            if body <= 1:
                j = start + 1
                while j < n and (lines[j].startswith('    ') or lines[j].startswith('\t') or lines[j].strip() == ''):
                    body += 1; ccn += len(DECISIONS.findall(lines[j]))
                    j += 1
            loc = max(body, 1)
            depth_v = max(peak, 1)
            ccn_v = ccn + 1  # 基线为 1
            score = loc/50 + depth_v/4 + ccn_v/10
            funcs.append({
                'file': path, 'line': start + 1,
                'loc': loc, 'depth': depth_v, 'ccn': ccn_v,
                'score': round(score, 2),
            })
            i = max(j, i + 1)
        else:
            i += 1
    return funcs

def collect(root, exts):
    out = []
    for dp, _, files in os.walk(root):
        if 'node_modules' in dp or '.git' in dp or 'vendor' in dp:
            continue
        for fn in files:
            if any(fn.endswith(e) for e in exts):
                out += parse_file(os.path.join(dp, fn))
    return out

def main():
    ap = argparse.ArgumentParser(description='代码复杂度热点扫描')
    ap.add_argument('dir', help='目标目录')
    ap.add_argument('--top', type=int, default=15)
    ap.add_argument('--format', choices=['md', 'json'], default='md')
    ap.add_argument('--ext', default='.py,.js,.ts,.java,.go,.c,.cpp,.cs,.rb')
    a = ap.parse_args()

    funcs = collect(a.dir, tuple(a.ext.split(',')))
    funcs.sort(key=lambda x: x['score'], reverse=True)
    top = funcs[:a.top]

    if a.format == 'json':
        print(json.dumps({'total': len(funcs), 'top': top}, ensure_ascii=False, indent=2))
        return

    print(f'## 复杂度热点 Top {len(top)}（共扫描 {len(funcs)} 个函数）\n')
    print('| 函数定位 | 行数 | 嵌套深度 | 圈复杂度 | 优先级 |')
    print('|---|---:|---:|---:|---:|')
    for f in top:
        loc_f = '⚠️' if f['loc'] > 50 else ''
        print(f"| {f['file']}:{f['line']} | {f['loc']}{loc_f} | {f['depth']} | {f['ccn']} | {f['score']} |")
    print('\n> 阈值：行数>50 / 嵌套>4 / 圈复杂度>10 视为预警。优先级=三者归一化之和。')

if __name__ == '__main__':
    main()

# 复杂度指标定义（complexity-scan 参考文档）

## 圈复杂度（Cyclomatic Complexity）
衡量程序独立路径数，公式 CCN = E - N + 2P。本 Skill 用启发式：
CCN ≈ 1 + 决策关键字出现次数（if/for/while/case/catch/&&/||/?: 等）。
- 1–10：简单，低风险
- 11–20：可接受，需测试覆盖
- 21–50：高风险，建议拆分
- >50：极难维护，必须重构

## 嵌套深度
从函数体起算的 `{` 入栈峰值。每多一层，人脑理解成本指数上升。
>4 层即应考虑用早返回（guard clause）或提取子函数压平。

## 行数
纯启发式：签名行到匹配结束大括号。注释/空行也计入，属已知偏差。

sequenceDiagram
    participant U as 用户
    participant C as Claude Code
    participant SK as SKILL.md(元数据+正文)
    participant S as scripts/scan.py
    participant R as references/metrics.md

    Note over C,SK: 启动阶段：只读所有 Skill 的 name+description
    U->>C: "帮我看看哪些函数最该重构"
    C->>C: 语义匹配 -> 命中 complexity-scan
    C->>SK: 加载正文（步骤指令）
    C->>S: 运行 scan.py src/ --top 15
    S-->>C: Markdown 热点表
    C->>U: 表格 + 重构建议
    U->>C: "圈复杂度怎么算的？"
    C->>R: 此时才读取 metrics.md
    R-->>C: 指标定义
    C->>U: 解释阈值与算法

// demo/src/cart.js —— 故意写复杂的函数
function calculateTotal(items, coupons, user, region) {
  let total = 0;
  for (let i = 0; i < items.length; i++) {
    if (items[i].active) {
      if (items[i].type === 'digital') {
        if (region === 'EU') { total += items[i].price * 1.2; }
        else { total += items[i].price; }
      } else {
        if (items[i].weight > 10) {
          if (region === 'EU') { total += items[i].price * 1.2 + 15; }
          else { total += items[i].price + 10; }
        } else { total += items[i].price + 5; }
      }
    }
  }
  for (let c = 0; c < coupons.length; c++) {
    if (coupons[c].valid && user.tier === 'vip') {
      if (coupons[c].type === 'percent') { total -= total * coupons[c].value; }
      else { total -= coupons[c].value; }
    }
  }
  return total;
}

## 复杂度热点 Top 5（共扫描 12 个函数）

| 函数定位 | 行数 | 嵌套深度 | 圈复杂度 | 优先级 |
|---|---:|---:|---:|---:|
| demo/src/cart.js:2 | 26 ⚠️ | 6 ⚠️ | 12 ⚠️ | 4.32 |
| demo/src/checkout.js:14 | 41 ⚠️ | 4 | 9 | 2.62 |
| ... | ... | ... | ... | ... |

flowchart TD
    A[需求:找出最该重构的函数] --> B[设计指标: loc/depth/ccn + score]
    B --> C[创建 .claude/skills/complexity-scan/]
    C --> D[写 SKILL.md: 元数据触发 + 步骤正文]
    D --> E[写 scripts/scan.py: 只读、纯文本输出]
    E --> F[写 references/metrics.md: 按需加载]
    F --> G[/skills 确认注册]
    G --> H[多话术测触发, 调优 description]
    H --> I[真实项目跑 Top N]
    I --> J[Claude 结合语义给重构建议]
    J --> K{结论达标?}
    K -- 否 --> H
    K -- 是 --> L[Skill 上线可复用]