codeabc 0.1.0__py3-none-any.whl

backend/services/glossary.py

@@ -0,0 +1,96 @@
+"""Terminology dictionary: plain-language definitions for jargon in code.
+
+A reader new to a codebase trips over vocabulary as much as logic. This is a
+curated dictionary of common programming terms with everyday, jargon-free
+explanations (the same voice as the line annotations), plus a scanner that
+reports which of those terms actually appear in a given file so the UI can
+offer "hover a keyword, see what it means".
+
+Deterministic — no LLM call — so it's instant, free, and unit-testable.
+"""
+
+from __future__ import annotations
+
+import re
+
+# term (lowercase canonical) -> plain-language explanation.
+# Definitions deliberately avoid jargon and lean on everyday analogies.
+GLOSSARY: dict[str, str] = {
+    "api": "一套约定好的「对外接口」，别的程序按这套约定就能调用你的功能，像餐厅菜单：照着点就行，不用进厨房。",
+    "async": "异步：发起一件耗时的事后不干等着，先去做别的，等它好了再回来处理，像点了外卖继续干活而不是站在门口等。",
+    "await": "等一件异步的事真正完成再往下走，相当于「这一步必须拿到结果才能继续」。",
+    "cache": "缓存：把算过/取过的结果先存起来，下次直接拿，省得重复跑，像把常用调料放灶台边而不是每次去仓库。",
+    "callback": "回调：把一个函数交给别人，让对方在某件事发生时替你调用它，像留个电话「好了打给我」。",
+    "closure": "闭包：一个函数把它出生时周围的变量一起「打包带走」，之后还能用到那些变量，像便当带上了家里的菜。",
+    "concurrency": "并发：让多件事在时间上交错推进，看起来同时在做，像一个人左右手轮流照看几口锅。",
+    "coroutine": "协程：能中途暂停、之后从原地接着跑的函数，配合异步用来高效处理大量等待。",
+    "decorator": "装饰器：在不改原函数的前提下给它套一层额外行为，像给手机套个壳，功能多了但手机没变。",
+    "dependency": "依赖：这段代码要正常工作所必须用到的别的库或模块，缺了就跑不起来。",
+    "deserialize": "反序列化：把存成文本/字节的数据还原成程序里能用的对象，是序列化的逆操作。",
+    "endpoint": "端点：服务对外暴露的一个具体网址入口，访问它就能触发某个功能。",
+    "enum": "枚举：把一组固定的可选值起好名字管起来，比如「红/黄/绿」，避免到处写魔法数字。",
+    "generator": "生成器：需要时才一个一个「现产」数据而不是一次全做好，省内存，像点一份做一份。",
+    "hash": "哈希：把任意数据压成一个固定长度的「指纹」，常用来快速比对或定位。",
+    "idempotent": "幂等：同样的操作做一次和做多次效果一样，像电梯按钮多按几下也只来一趟。",
+    "inheritance": "继承：新类直接沿用并扩展已有类的能力，像孩子继承父母的部分特征再加自己的。",
+    "iterator": "迭代器：负责「逐个往下取」集合里元素的东西，for 循环背后就靠它。",
+    "lambda": "匿名函数：临时用、不取名字的小函数，写在用它的地方，用完即弃。",
+    "lazy": "惰性：能拖到真正需要时再算/再加载，不提前浪费力气。",
+    "lock": "锁：同一时刻只让一个人动共享数据，防止大家一起改乱套，像洗手间的门闩。",
+    "memoize": "记忆化：把函数对某组输入算出的结果缓存下来，下次同样输入直接返回。",
+    "middleware": "中间件：夹在请求和真正处理之间的一层，统一做鉴权、日志等杂活，像进场前的安检。",
+    "mutex": "互斥锁：保证同一份资源同一时间只被一个线程使用的开关。",
+    "orm": "对象关系映射：让你用操作对象的方式读写数据库，不必手写 SQL，像翻译官帮你和数据库对话。",
+    "polymorphism": "多态：同一个调用，不同对象给出各自的实现，像「叫一声」猫和狗反应不同。",
+    "promise": "承诺对象：代表一件「将来才会有结果」的事，先拿到凭据，结果到了再兑现。",
+    "recursion": "递归：函数自己调用自己来把大问题拆成同样的小问题，像两面镜子互照。",
+    "refactor": "重构：在不改变外部行为的前提下整理代码结构，让它更清晰好维护。",
+    "regex": "正则表达式：用一串符号描述「什么样的文本算匹配」，用来查找或校验字符串，像高级版的查找替换。",
+    "serialize": "序列化：把程序里的对象转成可保存或可传输的文本/字节，方便存盘或发送。",
+    "singleton": "单例：整个程序里某个东西只允许存在一个实例，大家共用它。",
+    "stub": "桩：测试时用来顶替真实依赖的简化假货，让测试不碰外部系统。",
+    "thread": "线程：程序里一条独立执行的「流水线」，多条线程可以并行干活。",
+    "throttle": "节流：限制某操作的触发频率，太频繁就先压一压，避免把系统压垮。",
+    "token": "令牌：一小段代表身份或权限的凭证，带着它就能证明「我是谁、能干啥」。",
+    "tuple": "元组：一串按顺序排好、且不可修改的值，像一张定好的座位表。",
+    "yield": "把当前结果先「吐」出去并暂停，等下次再要时从这里继续，是生成器的核心动作。",
+    "race condition": "竞态：多个执行流同时改一份数据、谁先谁后没定准，导致结果飘忽的 bug。",
+    "dependency injection": "依赖注入：一个组件需要的零件由外部传进来，而不是自己 new，方便替换和测试。",
+    "garbage collection": "垃圾回收：运行时自动把不再用到的内存清掉，省得你手动释放。",
+}
+
+# Pre-build one matcher per term so we can map matches back to the canonical
+# key. Phrases allow flexible whitespace; all matching is whole-word and
+# case-insensitive so "in" never lights up inside "string".
+_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    (
+        term,
+        re.compile(
+            r"\b" + r"\s+".join(re.escape(part) for part in term.split()) + r"\b",
+            re.IGNORECASE,
+        ),
+    )
+    for term in GLOSSARY
+]
+
+
+def lookup(term: str) -> str | None:
+    """Return the definition for *term* (case-insensitive), or ``None``."""
+    return GLOSSARY.get(term.strip().lower())
+
+
+def scan_terms(text: str) -> list[dict]:
+    """Return the glossary terms that appear in *text*, with definitions.
+
+    Each entry is ``{"term", "definition"}``. Results are de-duplicated and
+    sorted alphabetically so the panel order is stable.
+    """
+    if not text:
+        return []
+    found = [
+        {"term": term, "definition": GLOSSARY[term]}
+        for term, pattern in _PATTERNS
+        if pattern.search(text)
+    ]
+    found.sort(key=lambda e: e["term"])
+    return found

backend/services/health_score.py

@@ -0,0 +1,381 @@
+"""Project health score — aggregate signal from multiple analyses into a single 0-100 rating.
+
+When a non-programmer receives a code review, a vendor codebase, or an inherited project,
+they need a fast answer to the question: "is this code in good shape?" Before this module,
+CodeABC produced several independent analyses (security, test coverage, activity, complexity,
+tech debt, architecture) but left it to the viewer to mentally weigh them.
+
+This module synthesises those signals into one score and grade.
+
+Scoring dimensions and weights:
+  Security         25 %   hardcoded secrets / dangerous calls cost heavily
+  Test coverage    20 %   ratio of source files covered by tests
+  Activity         20 %   recent commit cadence from the activity pulse
+  Complexity       15 %   average cyclomatic complexity of source files
+  Tech debt        10 %   density of TODO/FIXME/HACK markers
+  Architecture     10 %   import-cycle count; orphan modules contribute to noise
+
+Grade mapping:
+  A   90–100   excellent
+  B   75–89    good
+  C   60–74    fair — consider targeted improvements
+  D   40–59    needs work
+  F     0–39   critical issues present
+
+Pure function over already-computed analysis dicts — no repo access required.
+"""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+_ACTIVITY_LABEL_SCORE: dict[str, int] = {
+    "active": 100,
+    "slowing": 72,
+    "quiet": 48,
+    "stale": 22,
+    "abandoned": 0,
+    "unknown": 50,
+    "": 50,
+}
+
+_GRADE_THRESHOLDS: list[tuple[int, str]] = [
+    (90, "A"),
+    (75, "B"),
+    (60, "C"),
+    (40, "D"),
+]
+
+
+def _grade(score: int) -> str:
+    for threshold, letter in _GRADE_THRESHOLDS:
+        if score >= threshold:
+            return letter
+    return "F"
+
+
+def _security_score(security: dict | None) -> int:
+    """100 = no issues; subtract for critical and non-critical findings."""
+    if not security or not security.get("total"):
+        return 100
+    critical = security.get("critical", 0)
+    total = security.get("total", 0)
+    non_critical = total - critical
+    s = 100 - critical * 25 - non_critical * 8
+    return max(0, s)
+
+
+def _coverage_score(test_coverage: dict | None) -> int:
+    if not test_coverage:
+        return 50  # unknown: neutral
+    pct = test_coverage.get("coverage_percent", 0)
+    # Reward coverage non-linearly: 0%→0, 50%→55, 80%→80, 100%→100
+    if pct >= 80:
+        return pct
+    if pct >= 50:
+        # scale 50-80 → 55-80
+        return int(55 + (pct - 50) * (80 - 55) / (80 - 50))
+    if pct > 0:
+        # scale 1-49 → 5-54
+        return max(5, int(pct * 54 / 49))
+    return 0
+
+
+def _activity_score(activity: dict | None) -> int:
+    if not activity or not activity.get("available", True):
+        # uploaded project without git — neutral
+        return 50
+    label = activity.get("label", "unknown")
+    return _ACTIVITY_LABEL_SCORE.get(label, 50)
+
+
+def _complexity_score(
+    complexity_files: list[dict] | None,
+    total_files: int,
+    deep_nesting_files: list[dict] | None = None,
+) -> int:
+    """Higher complexity → lower score.
+
+    Complexity files are already the most complex ones in the project. We
+    penalise for having highly complex files relative to project size, using two
+    distinct signals: cyclomatic complexity (how many branches) and nesting depth
+    (how deeply those branches are stacked) — a function can be hard to follow on
+    either axis independently.
+    """
+    if (not complexity_files and not deep_nesting_files) or total_files == 0:
+        return 100
+    # Complexity threshold: cyclomatic complexity > 20 is considered "high"
+    HIGH_THRESHOLD = 20
+    VERY_HIGH_THRESHOLD = 50
+    high_count = sum(1 for f in (complexity_files or []) if f.get("complexity", 0) > HIGH_THRESHOLD)
+    very_high_count = sum(
+        1 for f in (complexity_files or []) if f.get("complexity", 0) > VERY_HIGH_THRESHOLD
+    )
+    # Fraction of project that is "high complexity"
+    high_frac = high_count / max(total_files, 1)
+    very_high_frac = very_high_count / max(total_files, 1)
+    s = 100 - int(high_frac * 60) - int(very_high_frac * 20)
+    # Deep nesting is a separate readability cost from branch count: penalise
+    # functions nested very deep (>= 6 levels) relative to project size.
+    if deep_nesting_files:
+        deep_count = sum(1 for f in deep_nesting_files if f.get("depth", 0) >= 6)
+        s -= int((deep_count / max(total_files, 1)) * 30)
+    return max(0, s)
+
+
+def _tech_debt_score(tech_debt_files: list[dict] | None, total_files: int) -> int:
+    """Score based on density of TODO/FIXME/HACK markers across the project."""
+    if not tech_debt_files or total_files == 0:
+        return 100
+    total_markers = sum(f.get("count", 0) for f in tech_debt_files)
+    markers_per_file = total_markers / max(total_files, 1)
+    # 0 markers/file → 100; 1/file → ~80; 3/file → ~55; 10+/file → ~20
+    if markers_per_file == 0:
+        return 100
+    if markers_per_file < 0.5:
+        return 90
+    if markers_per_file < 1:
+        return 80
+    if markers_per_file < 2:
+        return 68
+    if markers_per_file < 5:
+        return int(68 - (markers_per_file - 2) * 9)
+    return max(15, int(50 - markers_per_file * 3))
+
+
+def _architecture_score(
+    import_cycles: list[dict] | None,
+    orphan_modules: list[dict] | None,
+    total_files: int,
+) -> int:
+    """Score based on import cycles and orphan modules."""
+    cycles = len(import_cycles) if import_cycles else 0
+    orphans = len(orphan_modules) if orphan_modules else 0
+    if cycles == 0 and orphans == 0:
+        return 100
+    orphan_frac = orphans / max(total_files, 1)
+    s = 100 - min(cycles * 20, 60) - int(min(orphan_frac * 30, 30))
+    return max(0, s)
+
+
+# ---------------------------------------------------------------------------
+# Strengths / weaknesses narrative
+# ---------------------------------------------------------------------------
+
+
+def _build_strengths_weaknesses(
+    cat_scores: dict[str, int],
+    security: dict | None,
+    test_coverage: dict | None,
+    complexity_files: list[dict] | None,
+    tech_debt_files: list[dict] | None,
+    import_cycles: list[dict] | None,
+) -> tuple[list[str], list[str]]:
+    strengths: list[str] = []
+    weaknesses: list[str] = []
+
+    # Security
+    if cat_scores["security"] == 100:
+        strengths.append("未发现硬编码密钥或高危调用，安全基线良好。")
+    elif cat_scores["security"] < 60:
+        crit = (security or {}).get("critical", 0)
+        weaknesses.append(f"发现 {crit} 处高危安全问题（硬编码密钥或危险调用），应优先处理。")
+    elif cat_scores["security"] < 80:
+        weaknesses.append("存在轻度安全隐患，建议排查 security 报告中的 findings。")
+
+    # Test coverage
+    pct = (test_coverage or {}).get("coverage_percent", -1)
+    if pct >= 75:
+        strengths.append(f"测试覆盖率 {pct}%，源文件覆盖充分。")
+    elif pct >= 0:
+        weaknesses.append(f"测试覆盖率仅 {pct}%，核心文件建议补充单元测试。")
+    else:
+        weaknesses.append("缺少测试文件，无法评估测试覆盖率。")
+
+    # Activity
+    if cat_scores["activity"] >= 90:
+        strengths.append("项目处于活跃维护期，近期提交频繁。")
+    elif cat_scores["activity"] == 0:
+        weaknesses.append("项目超过一年无新提交，疑似停摆，使用前请评估维护风险。")
+    elif cat_scores["activity"] < 50:
+        weaknesses.append("项目活跃度较低，近 3 个月内提交稀少。")
+
+    # Complexity
+    if cat_scores["complexity"] >= 90:
+        strengths.append("代码复杂度在可控范围内，没有明显的「上帝函数」。")
+    elif cat_scores["complexity"] < 60:
+        high = [f for f in (complexity_files or []) if f.get("complexity", 0) > 20]
+        weaknesses.append(f"{len(high)} 个文件复杂度偏高（圈复杂度 >20），阅读和维护成本大。")
+
+    # Tech debt
+    if cat_scores["tech_debt"] >= 90:
+        strengths.append("技术债标记（TODO/FIXME/HACK）极少，代码整洁。")
+    elif cat_scores["tech_debt"] < 55:
+        total_m = sum(f.get("count", 0) for f in (tech_debt_files or []))
+        weaknesses.append(f"技术债标记共 {total_m} 处，建议择期清理。")
+
+    # Architecture
+    if cat_scores["architecture"] >= 90:
+        strengths.append("无循环依赖，模块边界清晰。")
+    elif import_cycles:
+        weaknesses.append(f"存在 {len(import_cycles)} 个循环依赖组，可能导致难以理解的耦合。")
+
+    return strengths, weaknesses
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+_WEIGHTS: dict[str, float] = {
+    "security": 0.25,
+    "test_coverage": 0.20,
+    "activity": 0.20,
+    "complexity": 0.15,
+    "tech_debt": 0.10,
+    "architecture": 0.10,
+}
+
+
+def compute_health_score(
+    *,
+    security: dict | None = None,
+    test_coverage: dict | None = None,
+    activity: dict | None = None,
+    complexity_files: list[dict] | None = None,
+    tech_debt_files: list[dict] | None = None,
+    import_cycles: list[dict] | None = None,
+    orphan_modules: list[dict] | None = None,
+    deep_nesting_files: list[dict] | None = None,
+    total_files: int = 0,
+) -> dict:
+    """Compute an aggregate health score from existing analysis results.
+
+    All arguments are optional and keyword-only; callers pass whichever
+    analyses are available — missing dimensions default to a neutral 50.
+
+    Returns::
+
+        {
+          "score": int,             # 0-100
+          "grade": str,             # "A" | "B" | "C" | "D" | "F"
+          "category_scores": {
+            "security": int,
+            "test_coverage": int,
+            "activity": int,
+            "complexity": int,
+            "tech_debt": int,
+            "architecture": int,
+          },
+          "weights": {str: float},  # applied weights for transparency
+          "strengths": [str, ...],  # things going well
+          "weaknesses": [str, ...], # things to address
+          "notes": [str, ...],
+        }
+    """
+    cat = {
+        "security": _security_score(security),
+        "test_coverage": _coverage_score(test_coverage),
+        "activity": _activity_score(activity),
+        "complexity": _complexity_score(complexity_files, total_files, deep_nesting_files),
+        "tech_debt": _tech_debt_score(tech_debt_files, total_files),
+        "architecture": _architecture_score(import_cycles, orphan_modules, total_files),
+    }
+
+    weighted = sum(cat[k] * _WEIGHTS[k] for k in _WEIGHTS)
+    score = max(0, min(100, round(weighted)))
+    grade = _grade(score)
+
+    strengths, weaknesses = _build_strengths_weaknesses(
+        cat,
+        security=security,
+        test_coverage=test_coverage,
+        complexity_files=complexity_files,
+        tech_debt_files=tech_debt_files,
+        import_cycles=import_cycles,
+    )
+
+    notes: list[str] = []
+    if total_files == 0:
+        notes.append("未扫描到代码文件，部分维度评分使用默认值。")
+    if not import_cycles and not orphan_modules:
+        notes.append("架构维度基于 import 图分析；上传项目（无 .git）同样支持。")
+
+    return {
+        "score": score,
+        "grade": grade,
+        "category_scores": cat,
+        "weights": _WEIGHTS,
+        "strengths": strengths,
+        "weaknesses": weaknesses,
+        "notes": notes,
+    }
+
+
+def render_health_score_markdown(project_name: str, data: dict | None) -> str:
+    """Render the health score as a Markdown section."""
+    if not data:
+        return ""
+    score = data.get("score", 0)
+    grade = data.get("grade", "?")
+    cat = data.get("category_scores", {})
+
+    _GRADE_EMOJI = {"A": "🟢", "B": "🟡", "C": "🟠", "D": "🔴", "F": "🔴"}
+    emoji = _GRADE_EMOJI.get(grade, "⚪")
+
+    lines = [
+        f"# 健康评分（{project_name}）",
+        "",
+        f"> **{score} / 100** — 等级 **{grade}** {emoji}",
+        "",
+        "## 各维度得分",
+        "",
+        "| 维度 | 得分 | 权重 |",
+        "|------|------|------|",
+    ]
+    _DIM_LABELS = {
+        "security": "安全性",
+        "test_coverage": "测试覆盖",
+        "activity": "活跃度",
+        "complexity": "代码复杂度",
+        "tech_debt": "技术债",
+        "architecture": "架构健康",
+    }
+    weights = data.get("weights", _WEIGHTS)
+    for key, label in _DIM_LABELS.items():
+        s = cat.get(key, 50)
+        w = int(weights.get(key, 0) * 100)
+        lines.append(f"| {label} | {s} | {w}% |")
+
+    lines += [
+        "",
+        "> 维度说明（每项满分 100，越高越好）："
+        "**安全性**＝有没有把密码写死在代码里、用了危险写法等隐患；"
+        "**测试覆盖**＝有多少代码配了自动测试兜底，改动后能第一时间发现问题；"
+        "**活跃度**＝最近还有没有人在维护更新；"
+        "**代码复杂度**＝逻辑绕不绕、新人好不好读懂；"
+        "**技术债**＝代码里堆了多少迟早要还的「烂账」（TODO、临时凑合的写法）；"
+        "**架构健康**＝文件之间的依赖关系清不清爽、乱不乱。",
+    ]
+
+    strengths = data.get("strengths", [])
+    if strengths:
+        lines += ["", "## 做得好的地方", ""]
+        for s in strengths:
+            lines.append(f"- {s}")
+
+    weaknesses = data.get("weaknesses", [])
+    if weaknesses:
+        lines += ["", "## 建议改进", ""]
+        for w in weaknesses:
+            lines.append(f"- {w}")
+
+    notes = data.get("notes", [])
+    if notes:
+        lines += ["", "## 注意事项", ""]
+        for n in notes:
+            lines.append(f"- {n}")
+
+    return "\n".join(lines).rstrip() + "\n"