codeabc 0.1.0__py3-none-any.whl

backend/services/techdebt.py

@@ -0,0 +1,124 @@
+"""Tech-debt markers: surface the codebase's own TODO/FIXME notes.
+
+A codebase usually documents its own rough edges inline — ``TODO`` for things
+left unfinished, ``FIXME`` for known-broken spots, ``HACK`` for deliberate
+shortcuts, ``XXX`` for "look here, this is suspicious". Collecting them gives a
+newcomer a fast, honest map of where the authors themselves flagged debt,
+without having to read every file.
+
+This is a *self-declared* signal (what the authors wrote down), complementary to
+the churn/ownership history and the static import graph. :func:`scan_tech_debt`
+is pure — it operates on the already-read file contents, so it is unit-testable
+with plain strings and needs no repository.
+
+Markers are matched as whole, upper-case words (the near-universal convention),
+which keeps prose like "todo list" or "debugging" from being mistaken for a
+marker.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+
+# Whole-word, upper-case markers only. Leading comment punctuation and the
+# usual separators after the marker are dropped so the captured note is clean.
+_MARKER_RE = re.compile(r"\b(TODO|FIXME|HACK|XXX)\b[:\s)\-]*(.*)")
+
+# A note longer than this is almost certainly a run-on line; keep the map terse.
+_MAX_NOTE_LEN = 160
+
+
+def _kind_reason(kind: str, count: int) -> str:
+    if kind == "FIXME":
+        return f"{count} 处 FIXME：作者标了“这里是坏的/要修”，读到相关代码时别当它是对的。"
+    if kind == "HACK":
+        return f"{count} 处 HACK：作者承认是临时绕过/取巧，改动前先确认有没有更干净的做法。"
+    if kind == "XXX":
+        return f"{count} 处 XXX：作者标了“可疑、看这里”，往往藏着隐患或待定决策。"
+    return f"{count} 处 TODO：作者留的未完成事项，是了解“还差什么”的最快线索。"
+
+
+def scan_tech_debt(
+    file_contents: dict[str, str],
+    *,
+    limit: int = 15,
+    per_file_limit: int = 5,
+) -> dict:
+    """Collect ``TODO``/``FIXME``/``HACK``/``XXX`` markers from file contents.
+
+    Args:
+        file_contents: mapping of path to file text (as CodeABC already read it).
+        limit: how many files to return in the ranked list.
+        per_file_limit: how many individual markers to keep per file.
+
+    Returns ``{"total", "by_kind", "files"}`` where ``files`` is ranked by how
+    many markers each file carries (most first), and ``by_kind`` counts each
+    marker type across the whole project.
+    """
+    by_file: dict[str, list[dict]] = {}
+    kind_counts: Counter[str] = Counter()
+    total = 0
+
+    for path, content in file_contents.items():
+        if not content:
+            continue
+        for line_no, line in enumerate(content.splitlines(), start=1):
+            match = _MARKER_RE.search(line)
+            if not match:
+                continue
+            kind = match.group(1)
+            note = match.group(2).strip()[:_MAX_NOTE_LEN]
+            by_file.setdefault(path, []).append({"line": line_no, "kind": kind, "note": note})
+            kind_counts[kind] += 1
+            total += 1
+
+    files = [
+        {"path": path, "count": len(markers), "markers": markers[:per_file_limit]}
+        for path, markers in by_file.items()
+    ]
+    files.sort(key=lambda f: (-f["count"], f["path"]))
+
+    return {
+        "total": total,
+        "by_kind": dict(kind_counts),
+        "files": files[:limit],
+    }
+
+
+def render_techdebt_markdown(project_name: str, techdebt_data: dict | None) -> str:
+    """Render the tech-debt markers as a Markdown section, or ``""`` if none."""
+    data = techdebt_data or {}
+    files = data.get("files") or []
+    if not files:
+        return ""
+
+    total = data.get("total", 0)
+    by_kind = data.get("by_kind") or {}
+    lines = [
+        f"# {project_name} — 待办与技术债",
+        "",
+        f"> 扫描代码里作者自己留的 TODO / FIXME / HACK / XXX 标记，共 {total} 处，"
+        "是了解“作者知道哪里还没做好”的最快线索。",
+        "",
+    ]
+
+    if by_kind:
+        lines.append("## 按类型")
+        lines.append("")
+        for kind in ("FIXME", "HACK", "XXX", "TODO"):
+            count = by_kind.get(kind)
+            if count:
+                lines.append(f"- {_kind_reason(kind, count)}")
+        lines.append("")
+
+    lines.append("## 标记最多的文件")
+    lines.append("")
+    for entry in files:
+        lines.append(f"- `{entry['path']}` — {entry['count']} 处")
+        for marker in entry["markers"]:
+            note = f"：{marker['note']}" if marker["note"] else ""
+            lines.append(f"  - L{marker['line']} `{marker['kind']}`{note}")
+    lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"

backend/services/too_many_params.py

@@ -0,0 +1,102 @@
+"""Flag functions that take too many parameters.
+
+A long parameter list is a readability and design signal that is orthogonal to
+:mod:`complexity` (branch count), :mod:`deep_nesting` (indentation depth), and
+:mod:`long_functions` (line span): a short, flat function can still be painful to
+call and read if it asks for eight separate arguments. The caller has to remember
+what each positional slot means and keep the order straight, and the reader has to
+hold the whole list in mind to understand what the function needs. These are the
+functions most worth refactoring by grouping related arguments into an object (or
+dataclass), or by splitting the work into smaller, single-purpose helpers.
+
+A leading ``self`` / ``cls`` receiver is not counted, and ``*args`` / ``**kwargs``
+are ignored on purpose: they collapse a variable number of arguments rather than
+adding named ones, so they do not carry the same "remember every slot" cost.
+"""
+
+from __future__ import annotations
+
+import ast
+
+# Functions with at least this many named parameters are surfaced.
+_PARAM_THRESHOLD = 6
+
+
+def _param_count(node: ast.FunctionDef | ast.AsyncFunctionDef) -> int:
+    """Number of named parameters, excluding a ``self`` / ``cls`` receiver.
+
+    Positional-only, regular, and keyword-only parameters are all counted;
+    ``*args`` / ``**kwargs`` are not, since they aggregate arguments rather than
+    naming individual ones.
+    """
+    args = node.args
+    count = len(args.posonlyargs) + len(args.args) + len(args.kwonlyargs)
+    leading = args.posonlyargs or args.args
+    if leading and leading[0].arg in ("self", "cls"):
+        count -= 1
+    return count
+
+
+def scan_too_many_params(
+    file_contents: dict[str, str], *, threshold: int = _PARAM_THRESHOLD, limit: int = 15
+) -> dict:
+    """Find functions that declare ``threshold`` named parameters or more.
+
+    Args:
+        file_contents: mapping of path to file text (as CodeABC already read it).
+        threshold: minimum named-parameter count to flag a function.
+        limit: how many of the widest functions to return.
+
+    Returns ``{"total", "max_params", "threshold", "files"}`` where ``files`` lists
+    the widest functions (descending), each ``{"path", "function", "params"}``.
+    Test files and non-Python files are skipped.
+    """
+    flagged: list[dict] = []
+    overall_max = 0
+    for path, content in file_contents.items():
+        if not content or not path.endswith(".py"):
+            continue
+        base = path.rsplit("/", 1)[-1]
+        if base.startswith("test_") or base.endswith("_test.py") or "/tests/" in path:
+            continue
+        try:
+            tree = ast.parse(content)
+        except (SyntaxError, ValueError):
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                params = _param_count(node)
+                overall_max = max(overall_max, params)
+                if params >= threshold:
+                    flagged.append({"path": path, "function": node.name, "params": params})
+
+    flagged.sort(key=lambda f: (-f["params"], f["path"], f["function"]))
+    return {
+        "total": len(flagged),
+        "max_params": overall_max,
+        "threshold": threshold,
+        "files": flagged[:limit],
+    }
+
+
+def render_too_many_params_markdown(project_name: str, data: dict | None) -> str:
+    """Render the too-many-parameters section, or an empty string when nothing is flagged."""
+    if not data or not data.get("files"):
+        return ""
+
+    threshold = data.get("threshold", _PARAM_THRESHOLD)
+    lines = [
+        f"## 参数过多的函数（{project_name}）",
+        "",
+        "下面这些函数一次要接收很多个参数。参数一多，调用它的时候就得记住每个位置该"
+        "传什么、顺序还不能错，很容易传错或漏传；读代码的人也要同时盯着一长串参数才"
+        f"能明白这个函数到底需要什么。这里列出参数达到 **{threshold} 个或更多**的函数，"
+        "它们通常值得把关系紧密的几个参数打包成一个对象（或 dataclass）一起传，或者"
+        "干脆拆成职责更单一的小函数。",
+        "",
+        "| 文件 | 函数 | 参数个数 |",
+        "| --- | --- | --- |",
+    ]
+    for f in data["files"]:
+        lines.append(f"| `{f['path']}` | `{f['function']}` | {f['params']} |")
+    return "\n".join(lines)

backend/services/typing_coverage.py

@@ -0,0 +1,184 @@
+"""Type-annotation coverage: which public functions leave their types unstated.
+
+``docstrings`` asks whether a module's public surface *explains* itself; this
+asks whether it *types* itself. A function is "typed" when it declares a return
+annotation and every parameter (other than a leading ``self``/``cls``) carries
+one — the same bar mypy's ``disallow-untyped-defs`` enforces. Fully typed code
+says what goes in and what comes out without being run, and it is the difference
+between an editor that can autocomplete and catch mistakes and one that guesses.
+
+For someone modifying an unfamiliar codebase, an un-typed public function is a
+quiet trap: ``def merge(a, b)`` gives no hint whether ``a`` is a dict, a path, or
+a dataframe. This ranks the files whose public API is least annotated so the
+riskiest places to change surface at a glance. ``scan_typing_coverage`` is pure
+over the file contents and parses with the standard library, so it needs no
+repository; non-Python files, test files, and files that don't parse are skipped.
+"""
+
+from __future__ import annotations
+
+import ast
+
+_MISSING_SAMPLE = 5  # how many un-typed symbol names to surface per file
+
+
+def _is_public(name: str) -> bool:
+    """Public API names carry no leading underscore (skips dunders and privates)."""
+    return not name.startswith("_")
+
+
+def _is_test_path(path: str) -> bool:
+    """Type hints on test functions are noise, so tests are left out of the metric."""
+    lower = path.lower()
+    base = lower.rsplit("/", 1)[-1]
+    return (
+        "/tests/" in lower
+        or "/test/" in lower
+        or base.startswith("test_")
+        or base.endswith("_test.py")
+        or base == "conftest.py"
+    )
+
+
+def _is_typed(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    """True when the function declares a return type and every parameter is annotated.
+
+    A leading ``self``/``cls`` is exempt (methods conventionally leave it bare),
+    as are the ``*args``/``**kwargs`` only when the codebase omits them; both the
+    variadic forms are required to be annotated when present. This matches mypy's
+    ``disallow-untyped-defs`` "typed def" bar.
+    """
+    if node.returns is None:
+        return False
+    args = node.args
+    positional = [*args.posonlyargs, *args.args]
+    if positional and positional[0].arg in ("self", "cls"):
+        positional = positional[1:]
+    for arg in (*positional, *args.kwonlyargs):
+        if arg.annotation is None:
+            return False
+    if args.vararg is not None and args.vararg.annotation is None:
+        return False
+    if args.kwarg is not None and args.kwarg.annotation is None:
+        return False
+    return True
+
+
+def _scan_module(tree: ast.Module) -> tuple[int, int, list[str]]:
+    """Return (typeable, typed, untyped_names) for a parsed module.
+
+    Counts public top-level functions plus public methods of public classes. A
+    class itself has no call signature to annotate, so only its methods count.
+    Walks the module and class bodies rather than ``ast.walk`` so nested/local
+    helpers — which are not part of the callable surface — are left out.
+    """
+    typeable = 0
+    typed = 0
+    missing: list[str] = []
+
+    def _record(is_typed: bool, label: str) -> None:
+        nonlocal typeable, typed
+        typeable += 1
+        if is_typed:
+            typed += 1
+        else:
+            missing.append(label)
+
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef) and _is_public(node.name):
+            _record(_is_typed(node), node.name)
+        elif isinstance(node, ast.ClassDef) and _is_public(node.name):
+            for sub in node.body:
+                if isinstance(sub, ast.FunctionDef | ast.AsyncFunctionDef) and _is_public(sub.name):
+                    _record(_is_typed(sub), f"{node.name}.{sub.name}")
+
+    return typeable, typed, missing
+
+
+def scan_typing_coverage(file_contents: dict[str, str], *, limit: int = 15) -> dict:
+    """Rank the project's Python files by how much of their public API lacks type hints.
+
+    Args:
+        file_contents: mapping of path to file text (as CodeABC already read it).
+        limit: how many of the least-annotated files to return.
+
+    Returns ``{"total_symbols", "typed", "coverage", "files"}`` where ``coverage``
+    is the repo-wide typed fraction (0.0-1.0, and 1.0 when there is no public API
+    to type) and ``files`` are the files with the most un-typed public functions
+    (descending), each ``{"path", "symbols", "typed", "coverage", "missing"}``.
+    """
+    total_symbols = 0
+    total_typed = 0
+    scored: list[dict] = []
+
+    for path, content in file_contents.items():
+        if not content or not path.endswith(".py") or _is_test_path(path):
+            continue
+        try:
+            tree = ast.parse(content)
+        except (SyntaxError, ValueError):
+            continue
+
+        typeable, typed, missing = _scan_module(tree)
+        if typeable == 0:
+            continue  # no public functions to type
+
+        total_symbols += typeable
+        total_typed += typed
+        if typed >= typeable:
+            continue  # fully typed, nothing to flag
+
+        scored.append(
+            {
+                "path": path,
+                "symbols": typeable,
+                "typed": typed,
+                "coverage": round(typed / typeable, 3),
+                "missing": missing[:_MISSING_SAMPLE],
+            }
+        )
+
+    coverage = round(total_typed / total_symbols, 3) if total_symbols else 1.0
+    # Worst first: most un-typed functions, then lowest coverage, then path.
+    scored.sort(key=lambda f: (-(f["symbols"] - f["typed"]), f["coverage"], f["path"]))
+    return {
+        "total_symbols": total_symbols,
+        "typed": total_typed,
+        "coverage": coverage,
+        "files": scored[:limit],
+    }
+
+
+def render_typing_coverage_markdown(project_name: str, data: dict | None) -> str:
+    """Render the type-annotation coverage ranking as Markdown, or ``""`` if nothing to report."""
+    data = data or {}
+    total = data.get("total_symbols") or 0
+    if not total:
+        return ""
+
+    coverage_pct = round((data.get("coverage") or 0.0) * 100)
+    typed = data.get("typed") or 0
+    files = data.get("files") or []
+
+    lines = [
+        f"# {project_name} — 类型注解覆盖率（哪些公开函数没写全类型标注）",
+        "",
+        "> 统计每个文件里「别人会调用」的公开函数、方法中有多少写全了类型标注"
+        "（参数和返回值都标了）。写全类型的代码不用运行就能看出「传什么、返回什么」，"
+        "编辑器也能自动补全并提前报错；没标类型的公开函数正是改起来最容易踩坑的地方。"
+        "开头的 `self`/`cls` 不计，私有成员和 dunder（下划线开头）也不计。",
+        "",
+        f"**整体覆盖率：{coverage_pct}%**（{typed}/{total} 个公开函数写全了类型标注）。",
+        "",
+    ]
+    if files:
+        lines.append("类型标注最缺的文件：")
+        lines.append("")
+        for f in files:
+            missing = "、".join(f["missing"])
+            more = "…" if f["symbols"] - f["typed"] > len(f["missing"]) else ""
+            lines.append(
+                f"- `{f['path']}` — {f['typed']}/{f['symbols']} 标了类型"
+                f"（{round(f['coverage'] * 100)}%），缺：{missing}{more}"
+            )
+    return "\n".join(lines).rstrip() + "\n"