codeabc 0.1.0__py3-none-any.whl

backend/services/coverage.py

@@ -0,0 +1,283 @@
+"""Test-coverage map: which code files have tests, and which don't.
+
+A non-programmer sizing up a codebase — a founder reviewing outsourced work,
+say — wants a blunt answer to "is this code actually tested?" and, more
+usefully, "which important files have *no* test, so changing them is the
+riskiest?". The static reading map and the risk list don't answer that; this
+does.
+
+Deterministic, no LLM. It pairs source files with test files two ways:
+
+* by import — a test that imports a source file genuinely exercises it; this
+  reuses the project import graph, no recomputation, and
+* by name — the near-universal convention that ``test_scanner.py`` /
+  ``scanner.test.ts`` / ``scanner.spec.ts`` cover ``scanner``.
+
+Untested files are then ranked by import fan-in: a file nothing tests but many
+files depend on is exactly where an unnoticed regression spreads furthest.
+
+Pure functions over the scanner's file list — unit-testable with plain dicts,
+no repo or git history needed.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .importgraph import _JS_LANGS, _PY_LANGS, _build_import_graph, _posix
+
+# a file under one of these directories is a test regardless of its name
+_TEST_DIRS = {"test", "tests", "__tests__", "spec", "specs"}
+# packaging / fixtures, not logic that warrants its own test
+_NON_SOURCE_NAMES = {"__init__.py", "conftest.py", "setup.py"}
+
+
+def _segments(path: str) -> list[str]:
+    return [s for s in _posix(path).split("/") if s]
+
+
+def _stem(name: str) -> str:
+    return name.rsplit(".", 1)[0] if "." in name else name
+
+
+def _is_test_file(path: str, lang: str) -> bool:
+    """True if the path looks like a test/spec file."""
+    segs = _segments(path)
+    name = segs[-1] if segs else ""
+    stem = _stem(name)
+    if any(d in _TEST_DIRS for d in segs[:-1]):
+        return True
+    if lang in _PY_LANGS:
+        return stem == "conftest" or stem.startswith("test_") or stem.endswith("_test")
+    if lang in _JS_LANGS:
+        # scanner.test.ts / scanner.spec.ts -> stem ends with .test / .spec
+        return stem.endswith(".test") or stem.endswith(".spec")
+    return False
+
+
+def _tested_stem(path: str, lang: str) -> str | None:
+    """The source stem a test file targets by naming convention, or None."""
+    stem = _stem(_segments(path)[-1])
+    if lang in _PY_LANGS:
+        if stem.startswith("test_"):
+            return stem[len("test_") :] or None
+        if stem.endswith("_test"):
+            return stem[: -len("_test")] or None
+        return None
+    if lang in _JS_LANGS:
+        for suffix in (".test", ".spec"):
+            if stem.endswith(suffix):
+                return stem[: -len(suffix)] or None
+    return None
+
+
+def _untested_reason(fan_in: int) -> str:
+    if fan_in >= 5:
+        return f"没有测试，却有 {fan_in} 个文件依赖它——这里出问题会牵连一大片，补测试的优先级最高。"
+    if fan_in >= 1:
+        return f"没有测试，有 {fan_in} 个文件依赖它：改动缺少自动验证，留意回归。"
+    return "没有测试：相对孤立的文件，改动靠人工确认即可，风险较低。"
+
+
+# config files that pin a Python test runner
+_PYTEST_CONFIG_NAMES = {"pytest.ini", "conftest.py", "tox.ini"}
+# JS/TS config-file stems -> the framework they configure
+_JS_TEST_CONFIG_PREFIXES = {"jest.config": "jest", "vitest.config": "vitest", ".mocharc": "mocha"}
+
+
+def _preview_of(files: list[dict], name_lower: str) -> str | None:
+    """The preview of the first file whose basename matches ``name_lower``."""
+    for f in files:
+        if _segments(f["path"])[-1].lower() == name_lower:
+            return f.get("preview") or ""
+    return None
+
+
+def detect_test_tooling(files: list[dict], test_files: set[str], lang_of: dict[str, str]) -> dict:
+    """Detect the test framework(s) in use and the command to run the tests.
+
+    The coverage map says *which* files are tested; a non-programmer's very next
+    question is "so how do I actually run these tests?". This answers it from
+    config files and the imports inside the test files themselves — deterministic,
+    no LLM, and honest about what it can't see.
+
+    Returns ``{"frameworks": sorted[str], "run_command": str | None}``. When both
+    a Python and a JS/TS runner are present (a monorepo), ``run_command`` is the
+    one whose ecosystem has more test files.
+    """
+    frameworks: set[str] = set()
+    all_names = {_segments(f["path"])[-1].lower() for f in files}
+
+    if _PYTEST_CONFIG_NAMES & all_names:
+        frameworks.add("pytest")
+    for name in all_names:
+        for prefix, fw in _JS_TEST_CONFIG_PREFIXES.items():
+            if name.startswith(prefix):
+                frameworks.add(fw)
+    for cfg in ("pyproject.toml", "setup.cfg"):
+        pv = _preview_of(files, cfg) or ""
+        if "[tool.pytest" in pv or "[pytest]" in pv:
+            frameworks.add("pytest")
+
+    # signals from the test files' own imports (previews carry the head, where imports sit)
+    preview_by_path = {_posix(f["path"]): (f.get("preview") or "") for f in files}
+    py_test = js_test = 0
+    for t in test_files:
+        pv = preview_by_path.get(t, "")
+        lang = lang_of.get(t, "")
+        if lang in _PY_LANGS:
+            py_test += 1
+            if "import pytest" in pv or "from pytest" in pv:
+                frameworks.add("pytest")
+            elif "import unittest" in pv or "from unittest" in pv or "unittest.TestCase" in pv:
+                frameworks.add("unittest")
+        elif lang in _JS_LANGS:
+            js_test += 1
+            if "vitest" in pv:
+                frameworks.add("vitest")
+            if "@jest/globals" in pv or re.search(r"\bjest\.", pv):
+                frameworks.add("jest")
+
+    pkg = _preview_of(files, "package.json") or ""
+    has_npm_test = re.search(r'"test"\s*:', pkg) is not None
+
+    py_cmd = (
+        "pytest"
+        if "pytest" in frameworks
+        else ("python -m unittest" if "unittest" in frameworks else None)
+    )
+    js_fw = next((fw for fw in ("vitest", "jest", "mocha") if fw in frameworks), None)
+    js_cmd = ("npm test" if has_npm_test else f"npx {js_fw}") if js_fw else None
+
+    if py_test >= js_test:
+        run_command = py_cmd or js_cmd
+    else:
+        run_command = js_cmd or py_cmd
+
+    return {"frameworks": sorted(frameworks), "run_command": run_command}
+
+
+def _coverage_notes(
+    total: int, pct: int, test_file_count: int, core_count: int, tooling: dict
+) -> list[str]:
+    if total == 0:
+        return ["没有发现源代码文件。"]
+    if test_file_count == 0:
+        return ["没有发现任何测试文件——这个项目没有自动化测试，每次改动都得靠人工验证。"]
+    notes = []
+    if pct >= 70:
+        notes.append(f"{pct}% 的代码文件有对应测试，改动相对有保障。")
+    elif pct >= 30:
+        notes.append(f"只有 {pct}% 的代码文件有测试，不少改动缺少自动验证、更容易留隐患。")
+    else:
+        notes.append(f"只有 {pct}% 的代码文件有测试，测试覆盖很薄，改动风险偏高。")
+    if core_count:
+        notes.append(
+            f"其中 {core_count} 个被其它文件依赖的核心文件没有测试，改它们风险最高，建议优先补。"
+        )
+    run_command = tooling.get("run_command")
+    if run_command:
+        fw = "、".join(tooling.get("frameworks") or []) or "自动化测试"
+        notes.append(f"用的是 {fw}：在项目根目录运行 `{run_command}` 就能跑测试。")
+    return notes
+
+
+def assess_test_coverage(files: list[dict], *, limit: int = 12) -> dict:
+    """Map source files to whether they have a test, and rank the untested core.
+
+    Args:
+        files: the scanner's file list — dicts with ``path``, ``language`` and
+            ``preview`` (used to resolve imports).
+        limit: how many untested files to surface in ``untested_core``.
+
+    Returns a dict shaped for ``TestCoverageSummary``: file counts, a 0-100
+    ``coverage_percent`` (tested source files / total source files), the
+    untested files ranked by import fan-in, and plain-language ``notes``.
+    """
+    _, imports, fan_in = _build_import_graph(files)
+
+    test_files: set[str] = set()
+    source_files: set[str] = set()
+    lang_of: dict[str, str] = {}
+    for f in files:
+        path = _posix(f["path"])
+        lang = f.get("language", "unknown")
+        if lang not in _PY_LANGS and lang not in _JS_LANGS:
+            continue
+        lang_of[path] = lang
+        if _is_test_file(path, lang):
+            test_files.add(path)
+        elif _segments(path)[-1] not in _NON_SOURCE_NAMES:
+            source_files.add(path)
+
+    covered: set[str] = set()
+    # 1) import-based: a test that imports a source file exercises it
+    for t in test_files:
+        for dep in imports.get(t, ()):
+            if dep in source_files:
+                covered.add(dep)
+    # 2) name-based: test_scanner.py <-> scanner.py, scanner.test.ts <-> scanner.ts
+    tested_stems = {s for t in test_files if (s := _tested_stem(t, lang_of[t])) is not None}
+    tested_stems = {s.lower() for s in tested_stems}
+    if tested_stems:
+        for s in source_files:
+            if _stem(_segments(s)[-1]).lower() in tested_stems:
+                covered.add(s)
+
+    untested = sorted(
+        source_files - covered,
+        key=lambda p: (-len(fan_in.get(p, ())), p),
+    )
+
+    total = len(source_files)
+    tested = len(covered)
+    pct = round(tested / total * 100) if total else 0
+
+    untested_core = [
+        {
+            "path": p,
+            "language": lang_of.get(p, "unknown"),
+            "fan_in": len(fan_in.get(p, ())),
+            "reason": _untested_reason(len(fan_in.get(p, ()))),
+        }
+        for p in untested[:limit]
+    ]
+    core_count = sum(1 for u in untested_core if u["fan_in"] >= 1)
+    tooling = detect_test_tooling(files, test_files, lang_of)
+
+    return {
+        "total_source_files": total,
+        "tested_files": tested,
+        "untested_files": total - tested,
+        "test_files": len(test_files),
+        "coverage_percent": pct,
+        "test_frameworks": tooling["frameworks"],
+        "run_command": tooling["run_command"],
+        "untested_core": untested_core,
+        "notes": _coverage_notes(total, pct, len(test_files), core_count, tooling),
+    }
+
+
+def render_coverage_markdown(name: str, coverage: dict | None) -> str:
+    """Render the test-coverage summary as a Markdown section, or ``""``."""
+    if not coverage or not coverage.get("total_source_files"):
+        return ""
+    pct = coverage.get("coverage_percent", 0)
+    lines = [
+        f"# 测试覆盖（{name}）",
+        "",
+        f"> {coverage.get('tested_files', 0)}/{coverage.get('total_source_files', 0)} "
+        f"个代码文件有测试（{pct}%），共发现 {coverage.get('test_files', 0)} 个测试文件。",
+        "",
+    ]
+    run_command = coverage.get("run_command")
+    if run_command:
+        fw = "、".join(coverage.get("test_frameworks") or []) or "自动化测试"
+        lines.append(f"> 测试框架：{fw}。运行：`{run_command}`")
+        lines.append("")
+    lines.extend(f"- {note}" for note in coverage.get("notes", []))
+    untested = coverage.get("untested_core", [])
+    if untested:
+        lines.extend(["", "## 没有测试、最该补的文件", ""])
+        lines.extend(f"- `{u['path']}` — {u['reason']}" for u in untested)
+    return "\n".join(lines).rstrip() + "\n"

backend/services/datamodels.py

@@ -0,0 +1,190 @@
+"""Data-model map — what shape the data this project moves around actually has.
+
+The symbol index tells you *where* a class named ``User`` is declared. It does
+not tell you what a ``User`` *is*: which fields it carries, and of what type.
+For someone trying to understand an unfamiliar codebase without reading every
+file, that second question is often the important one — "an Order has a total, a
+list of items and a status" says more about the program than any call graph.
+
+This map reads those shapes straight from the source CodeABC already loaded — no
+LLM, nothing to install or run — by recognising the four ways Python code
+declares a data record explicitly:
+
+  dataclass    ``@dataclass class User: id: int; name: str = ""``
+  pydantic     ``class Order(BaseModel): total: float``
+  TypedDict    ``class Movie(TypedDict): title: str``
+  NamedTuple   ``class Coord(NamedTuple): lat: float``
+
+Each model carries its name, which of the four kinds it is, the fields it
+declares (name, type annotation, and whether it has a default), and the file and
+line where it is defined.
+
+:func:`find_data_models` is pure over the file contents, so it is unit-testable
+with plain strings and needs no repository.
+
+Limitations (kept honest on purpose):
+
+  * Only the four class-based declaration styles above. The functional forms
+    (``TypedDict("Movie", {...})``, ``namedtuple("Coord", [...])``) and ORM
+    bases (SQLAlchemy ``Base``, Django ``models.Model``) are out of scope — the
+    latter are too easy to confuse with ordinary classes to flag safely.
+  * Only statically-declared, annotated fields. Attributes assigned in
+    ``__init__`` or built dynamically are not counted.
+  * Inherited fields are not flattened in; each model lists only what it
+    declares itself.
+  * A file that does not parse as Python is skipped, not guessed at.
+"""
+
+from __future__ import annotations
+
+import ast
+
+# Base-class names that mark a class as a typed data record, mapped to the kind
+# label we report for them.
+_BASE_KINDS = {
+    "BaseModel": "pydantic",
+    "TypedDict": "typeddict",
+    "NamedTuple": "namedtuple",
+}
+
+
+def _base_name(node: ast.expr) -> str | None:
+    """Return the right-most attribute name of a base/decorator expression.
+
+    ``BaseModel`` -> ``BaseModel``; ``pydantic.BaseModel`` -> ``BaseModel``.
+    """
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return None
+
+
+def _is_dataclass(cls: ast.ClassDef) -> bool:
+    """True when the class carries a ``@dataclass`` decorator in any form."""
+    for dec in cls.decorator_list:
+        target = dec.func if isinstance(dec, ast.Call) else dec
+        if _base_name(target) == "dataclass":
+            return True
+    return False
+
+
+def _classify(cls: ast.ClassDef) -> str | None:
+    """Resolve which data-model kind a class is, or ``None`` if it is not one."""
+    if _is_dataclass(cls):
+        return "dataclass"
+    for base in cls.bases:
+        name = _base_name(base)
+        if name and name in _BASE_KINDS:
+            return _BASE_KINDS[name]
+    return None
+
+
+def _annotation_str(node: ast.expr | None) -> str:
+    if node is None:
+        return ""
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return ""
+
+
+def _fields(cls: ast.ClassDef) -> list[dict]:
+    """Collect the annotated fields declared directly in the class body."""
+    fields: list[dict] = []
+    for stmt in cls.body:
+        if not isinstance(stmt, ast.AnnAssign) or not isinstance(stmt.target, ast.Name):
+            continue
+        name = stmt.target.id
+        # Skip private (_x) and dunder (__x__) names: ORM table hints like
+        # __tablename__ and internal bookkeeping are not part of the data shape.
+        if name.startswith("_"):
+            continue
+        fields.append(
+            {
+                "name": name,
+                "type": _annotation_str(stmt.annotation),
+                "has_default": stmt.value is not None,
+            }
+        )
+    return fields
+
+
+def find_data_models(file_contents: dict[str, str], *, limit: int = 60) -> dict:
+    """Collect the explicitly-declared data models a project defines.
+
+    Args:
+        file_contents: mapping of path to file text (as CodeABC already read it).
+        limit: how many models to return in the sorted list.
+
+    Returns ``{"total", "kinds", "models"}`` where each model is
+    ``{"name", "kind", "fields", "path", "line"}``, ``kind`` is one of
+    ``dataclass`` / ``pydantic`` / ``typeddict`` / ``namedtuple``, and each field
+    is ``{"name", "type", "has_default"}``.
+    """
+    seen: set[tuple[str, str, int]] = set()
+    models: list[dict] = []
+
+    for path, content in file_contents.items():
+        if not content or not path.endswith(".py"):
+            continue
+        try:
+            tree = ast.parse(content)
+        except (SyntaxError, ValueError):
+            continue
+
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.ClassDef):
+                continue
+            kind = _classify(node)
+            if kind is None:
+                continue
+            key = (path, node.name, node.lineno)
+            if key in seen:
+                continue
+            seen.add(key)
+            models.append(
+                {
+                    "name": node.name,
+                    "kind": kind,
+                    "fields": _fields(node),
+                    "path": path,
+                    "line": node.lineno,
+                }
+            )
+
+    models.sort(key=lambda m: (m["path"], m["line"]))
+    kinds = sorted({m["kind"] for m in models})
+    return {"total": len(models), "kinds": kinds, "models": models[:limit]}
+
+
+def render_data_models_markdown(project_name: str, data: dict | None) -> str:
+    """Render the data-model map as Markdown, or ``""`` if none were found."""
+    models = (data or {}).get("models") or []
+    if not models:
+        return ""
+
+    lines = [
+        f"# {project_name} — 数据长什么样（数据模型）",
+        "",
+        "> 符号索引告诉你一个类“在哪声明”，这里告诉你它“装了什么”——"
+        "项目用 dataclass / pydantic / TypedDict / NamedTuple 显式声明的数据记录，"
+        "以及每条记录有哪些字段、各是什么类型。",
+        "",
+    ]
+    for model in models:
+        lines.append(f"## `{model['name']}`  （{model['kind']}，{model['path']}:{model['line']}）")
+        if not model["fields"]:
+            lines.append("- （未声明带类型标注的字段）")
+            lines.append("")
+            continue
+        for field in model["fields"]:
+            entry = f"- `{field['name']}`"
+            if field["type"]:
+                entry += f"：{field['type']}"
+            if field["has_default"]:
+                entry += "（有默认值）"
+            lines.append(entry)
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"

backend/services/deep_nesting.py

@@ -0,0 +1,110 @@
+"""Flag deeply-nested code — functions whose control flow is indented many levels deep.
+
+Deep nesting (an ``if`` inside a ``for`` inside a ``while`` inside a ``try`` ...) is
+hard to follow even when each individual branch is simple, so it is a different
+signal from :mod:`complexity` (which counts *how many* branches a file has): a
+function can have only a few branches yet bury them several levels deep. For a
+beginner reading unfamiliar code this is exactly the shape that is hard to hold in
+your head, and it points at the functions most worth flattening with early returns,
+guard clauses, or an extracted helper.
+"""
+
+from __future__ import annotations
+
+import ast
+
+# Control-flow blocks that add a level of indentation.
+_NESTING_NODES = (
+    ast.If,
+    ast.For,
+    ast.AsyncFor,
+    ast.While,
+    ast.With,
+    ast.AsyncWith,
+    ast.Try,
+)
+
+# Functions nested this deep or more are surfaced.
+_DEPTH_THRESHOLD = 4
+
+
+def _max_control_depth(node: ast.AST, current: int = 0) -> int:
+    """Deepest chain of nested control-flow blocks under ``node``.
+
+    Nested functions and classes are *not* descended into: they are separate
+    scopes and are measured on their own pass, so a helper defined inside a
+    function does not inflate the outer function's depth.
+    """
+    best = current
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+        if isinstance(child, _NESTING_NODES):
+            best = max(best, _max_control_depth(child, current + 1))
+        else:
+            best = max(best, _max_control_depth(child, current))
+    return best
+
+
+def scan_deep_nesting(
+    file_contents: dict[str, str], *, threshold: int = _DEPTH_THRESHOLD, limit: int = 15
+) -> dict:
+    """Find functions whose control flow nests ``threshold`` levels deep or more.
+
+    Args:
+        file_contents: mapping of path to file text (as CodeABC already read it).
+        threshold: minimum nesting depth to flag a function.
+        limit: how many of the deepest functions to return.
+
+    Returns ``{"total", "max_depth", "threshold", "files"}`` where ``files`` lists
+    the deepest functions (descending), each ``{"path", "function", "depth"}``.
+    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)):
+                depth = _max_control_depth(node)
+                overall_max = max(overall_max, depth)
+                if depth >= threshold:
+                    flagged.append({"path": path, "function": node.name, "depth": depth})
+
+    flagged.sort(key=lambda f: (-f["depth"], f["path"], f["function"]))
+    return {
+        "total": len(flagged),
+        "max_depth": overall_max,
+        "threshold": threshold,
+        "files": flagged[:limit],
+    }
+
+
+def render_deep_nesting_markdown(project_name: str, data: dict | None) -> str:
+    """Render the deep-nesting section, or an empty string when nothing is flagged."""
+    if not data or not data.get("files"):
+        return ""
+
+    threshold = data.get("threshold", _DEPTH_THRESHOLD)
+    lines = [
+        f"## 嵌套过深的函数（{project_name}）",
+        "",
+        "下面这些函数把 `if / for / while / try` 一层套一层，缩进很深。就算每一层"
+        "本身不复杂，层数一多也很难读——你得同时记住「现在在第几层、每一层的条件是"
+        f"什么」。这里列出嵌套达到 **{threshold} 层或更深**的函数，它们通常最值得用"
+        "「提前 return / 卫语句 / 把里层抽成一个小函数」拍平。",
+        "",
+        "| 文件 | 函数 | 最深嵌套层数 |",
+        "| --- | --- | --- |",
+    ]
+    for f in data["files"]:
+        lines.append(f"| `{f['path']}` | `{f['function']}` | {f['depth']} |")
+    return "\n".join(lines)