codeabc 0.1.0__py3-none-any.whl

backend/services/dependencies.py

@@ -0,0 +1,270 @@
+"""External dependencies: the third-party libraries a project pulls in.
+
+The reading map and entry points tell a newcomer what to read and how to run the
+code; this answers another practical first question — "what does this project
+depend on, and what would I need to install?". It reads the dependency manifests
+CodeABC already loaded (``requirements*.txt``, ``pyproject.toml``, ``setup.cfg``,
+``Pipfile``, ``package.json``) and lists the declared third-party packages,
+marking each as runtime, development, or optional and noting which manifest it
+came from.
+
+This is deliberately distinct from the internal import/package graph: it is about
+the *external* libraries the project installs, not how its own modules reference
+each other. :func:`scan_dependencies` is pure over the file contents, so it is
+unit-testable with plain strings and needs no repository or network.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from backend.services import package_purposes
+
+_RUNTIME = "runtime"
+_DEV = "dev"
+_OPTIONAL = "optional"
+
+# Lower rank wins when the same package shows up in more than one role.
+_KIND_RANK = {_RUNTIME: 0, _DEV: 1, _OPTIONAL: 2}
+_KIND_LABEL = {_RUNTIME: "运行依赖", _DEV: "开发依赖", _OPTIONAL: "可选依赖"}
+
+# A quoted string inside a TOML/JSON array.
+_QUOTED_RE = re.compile(r"""['"]([^'"]+)['"]""")
+# A `name = <value>` table entry (poetry / Pipfile style), one per line.
+_TABLE_ENTRY_RE = re.compile(r"""(?m)^\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*=\s*(.+?)\s*$""")
+# A requirements filename: requirements.txt, requirements-dev.txt, ...
+_REQUIREMENTS_RE = re.compile(r"requirements.*\.txt", re.I)
+
+
+def _section(content: str, header: str) -> str:
+    """Text of a TOML/INI ``[header]`` section, until the next top-level header."""
+    start = content.find(f"[{header}]")
+    if start == -1:
+        return ""
+    rest = content[start + len(header) + 2 :]
+    end = re.search(r"(?m)^\s*\[", rest)
+    return rest[: end.start()] if end else rest
+
+
+def _array_body(text: str, key: str) -> str:
+    """Raw body of a TOML ``key = [ ... ]`` array.
+
+    Walks to the matching ``]`` while tracking nesting and ignoring any brackets
+    that appear *inside* quoted strings — so an extras marker like
+    ``"requests[security]>=2"`` does not terminate the array early.
+    """
+    m = re.search(rf"(?m)^\s*{re.escape(key)}\s*=\s*\[", text)
+    if not m:
+        return ""
+    depth, quote, out, i = 1, "", [], m.end()
+    while i < len(text) and depth > 0:
+        c = text[i]
+        if quote:
+            if c == quote:
+                quote = ""
+            out.append(c)
+        elif c in "'\"":
+            quote = c
+            out.append(c)
+        elif c == "[":
+            depth += 1
+            out.append(c)
+        elif c == "]":
+            depth -= 1
+            if depth:
+                out.append(c)
+        else:
+            out.append(c)
+        i += 1
+    return "".join(out)
+
+
+def _req_name_version(spec: str) -> tuple[str, str] | None:
+    """Parse a requirement string into ``(name, version_spec)``.
+
+    Returns ``None`` for anything that is not a package: blanks, comments, pip
+    options (``-r``, ``--index-url``), or a bare VCS/URL requirement with no
+    resolvable name.
+    """
+    spec = spec.split("#", 1)[0].strip()
+    if not spec or spec.startswith("-"):
+        return None
+    spec = spec.split(";", 1)[0].strip()  # drop environment markers
+    m = re.match(r"[A-Za-z0-9][A-Za-z0-9._-]*", spec)
+    if not m:
+        return None
+    name = m.group(0)
+    rest = re.sub(r"^\s*\[[^\]]*\]", "", spec[m.end() :]).strip()  # drop extras
+    if " @ " in rest or "://" in rest:  # "pkg @ git+https://..." has no clean version
+        rest = ""
+    return name, rest
+
+
+def _from_requirements(content: str, kind: str) -> list[tuple[str, str, str]]:
+    deps = []
+    for line in content.splitlines():
+        parsed = _req_name_version(line)
+        if parsed:
+            deps.append((parsed[0], parsed[1], kind))
+    return deps
+
+
+def _from_pyproject(content: str) -> list[tuple[str, str, str]]:
+    deps: list[tuple[str, str, str]] = []
+    # PEP 621: [project] dependencies = [...] and [project.optional-dependencies].
+    for spec in _QUOTED_RE.findall(_array_body(content, "dependencies")):
+        parsed = _req_name_version(spec)
+        if parsed:
+            deps.append((parsed[0], parsed[1], _RUNTIME))
+    for spec in _QUOTED_RE.findall(_section(content, "project.optional-dependencies")):
+        parsed = _req_name_version(spec)
+        if parsed:
+            deps.append((parsed[0], parsed[1], _OPTIONAL))
+    # Poetry: [tool.poetry.dependencies] uses `name = "^1.0"` table entries.
+    for header, kind in (
+        ("tool.poetry.dependencies", _RUNTIME),
+        ("tool.poetry.dev-dependencies", _DEV),
+        ("tool.poetry.group.dev.dependencies", _DEV),
+    ):
+        for name, raw in _TABLE_ENTRY_RE.findall(_section(content, header)):
+            if name == "python":  # the interpreter constraint, not a dependency
+                continue
+            version = next(iter(_QUOTED_RE.findall(raw)), "")
+            deps.append((name, "" if version == "*" else version, kind))
+    return deps
+
+
+def _from_setup_cfg(content: str) -> list[tuple[str, str, str]]:
+    block = _section(content, "options")
+    m = re.search(r"(?m)^install_requires\s*=(.*)$", block)
+    if not m:
+        return []
+    lines = block[m.start() :].splitlines()
+    items = [lines[0].split("=", 1)[1].strip()]
+    for line in lines[1:]:
+        if not line.strip():
+            continue
+        if line[0] in " \t":  # indented continuation line
+            items.append(line.strip())
+        else:  # a new dedented key ends the install_requires block
+            break
+    deps = []
+    for item in items:
+        parsed = _req_name_version(item)
+        if parsed:
+            deps.append((parsed[0], parsed[1], _RUNTIME))
+    return deps
+
+
+def _from_pipfile(content: str) -> list[tuple[str, str, str]]:
+    deps = []
+    for header, kind in (("packages", _RUNTIME), ("dev-packages", _DEV)):
+        for name, raw in _TABLE_ENTRY_RE.findall(_section(content, header)):
+            version = next(iter(_QUOTED_RE.findall(raw)), "")
+            deps.append((name, "" if version == "*" else version, kind))
+    return deps
+
+
+def _from_package_json(content: str) -> list[tuple[str, str, str]]:
+    try:
+        data = json.loads(content)
+    except (json.JSONDecodeError, ValueError):
+        return []
+    deps = []
+    for field, kind in (
+        ("dependencies", _RUNTIME),
+        ("devDependencies", _DEV),
+        ("optionalDependencies", _OPTIONAL),
+        ("peerDependencies", _OPTIONAL),
+    ):
+        block = data.get(field)
+        if isinstance(block, dict):
+            deps.extend((str(name), str(ver), kind) for name, ver in block.items())
+    return deps
+
+
+def scan_dependencies(file_contents: dict[str, str], *, limit: int = 200) -> dict:
+    """Collect the project's declared third-party dependencies from its manifests.
+
+    Args:
+        file_contents: mapping of path to file text (as CodeABC already read it).
+        limit: how many dependencies to return in the ranked list.
+
+    Returns ``{"total", "dependencies", "manifests"}`` where each dependency is
+    ``{"name", "version", "kind", "manifest", "purpose"}`` and ``kind`` is one of
+    ``runtime``, ``dev`` or ``optional``. ``purpose`` is a plain-language note for
+    well-known packages (``None`` otherwise). A package seen in several roles is
+    kept once at its strongest role (runtime over dev over optional).
+    """
+    best: dict[str, dict] = {}
+    manifests: list[str] = []
+
+    def _add(name: str, version: str, kind: str, manifest: str) -> None:
+        key = name.lower()
+        existing = best.get(key)
+        if existing is None or _KIND_RANK[kind] < _KIND_RANK[existing["kind"]]:
+            best[key] = {
+                "name": name,
+                "version": version.strip(),
+                "kind": kind,
+                "manifest": manifest,
+                "purpose": package_purposes.explain_package(name),
+            }
+
+    for path, content in file_contents.items():
+        if not content:
+            continue
+        name = path.replace("\\", "/").rsplit("/", 1)[-1]
+        if _REQUIREMENTS_RE.fullmatch(name):
+            kind = _DEV if re.search(r"dev|test", name, re.I) else _RUNTIME
+            collected = _from_requirements(content, kind)
+        elif name == "pyproject.toml":
+            collected = _from_pyproject(content)
+        elif name == "setup.cfg":
+            collected = _from_setup_cfg(content)
+        elif name == "Pipfile":
+            collected = _from_pipfile(content)
+        elif name == "package.json":
+            collected = _from_package_json(content)
+        else:
+            continue
+        if collected:
+            manifests.append(name)
+            for dep_name, version, kind in collected:
+                _add(dep_name, version, kind, name)
+
+    deps = sorted(best.values(), key=lambda d: (_KIND_RANK[d["kind"]], d["name"].lower()))
+    return {
+        "total": len(deps),
+        "dependencies": deps[:limit],
+        "manifests": sorted(set(manifests)),
+    }
+
+
+def render_dependencies_markdown(project_name: str, data: dict | None) -> str:
+    """Render the external dependencies as Markdown, or ``""`` if none were found."""
+    deps = (data or {}).get("dependencies") or []
+    if not deps:
+        return ""
+    manifests = (data or {}).get("manifests") or []
+    source = "、".join(f"`{m}`" for m in manifests)
+    lines = [
+        f"# {project_name} — 外部依赖清单（第三方库）",
+        "",
+        "> 这个项目要装哪些第三方库才能跑。运行依赖是跑起来必须的，开发依赖只在改代码/跑测试时用，"
+        f"可选依赖按需安装。来源：{source}。",
+        "",
+    ]
+    for kind in (_RUNTIME, _DEV, _OPTIONAL):
+        group = [d for d in deps if d["kind"] == kind]
+        if not group:
+            continue
+        lines.append(f"## {_KIND_LABEL[kind]}（{len(group)}）")
+        lines.append("")
+        for d in group:
+            version = f" `{d['version']}`" if d["version"] else ""
+            lines.append(f"- **{d['name']}**{version} — 来自 `{d['manifest']}`")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"

backend/services/docs.py

@@ -0,0 +1,255 @@
+"""Documentation coverage: which source files are written down, and which aren't.
+
+Tests answer "is this code verified?"; this answers the sibling question a
+non-programmer asks when inheriting a codebase: "is this code *explained*?".
+A large source file with almost no comments or docstrings is the hardest to
+read and the riskiest to change blind — and it's exactly the kind of thing that
+doesn't show up in a test-coverage or churn report.
+
+:func:`assess_doc_coverage` walks the already-read file contents, counts code
+lines vs. comment/docstring lines per source file, and flags the ones that
+carry real logic yet are effectively undocumented. The bigger a bare file is,
+the higher it ranks: a 300-line module with no comments hurts more than a
+10-line helper.
+
+Pure functions over the file-content map — no repo or git history needed, so it
+is unit-testable with plain strings. The comment detection is a deterministic
+heuristic (line-comment prefixes, C-style block comments, Python docstrings),
+not a full parser; it aims to be honest about density, not byte-perfect.
+"""
+
+from __future__ import annotations
+
+# Extension -> (line-comment prefix, has C-style /* */ blocks).
+# Python is handled specially because triple-quoted docstrings count as docs.
+_LINE_COMMENT: dict[str, str] = {
+    "py": "#",
+    "pyi": "#",
+    "js": "//",
+    "jsx": "//",
+    "ts": "//",
+    "tsx": "//",
+    "go": "//",
+    "java": "//",
+    "rs": "//",
+    "c": "//",
+    "h": "//",
+    "cpp": "//",
+    "hpp": "//",
+    "cc": "//",
+    "cs": "//",
+    "kt": "//",
+    "swift": "//",
+    "scala": "//",
+}
+_C_STYLE = {
+    "js",
+    "jsx",
+    "ts",
+    "tsx",
+    "go",
+    "java",
+    "rs",
+    "c",
+    "h",
+    "cpp",
+    "hpp",
+    "cc",
+    "cs",
+    "kt",
+    "swift",
+    "scala",
+}
+_PY = {"py", "pyi"}
+
+# A file needs at least this many code lines before "no docs" is worth flagging;
+# tiny files don't need a comment to be understood.
+_MIN_CODE_LINES = 15
+# At or below this comment-to-code ratio a file counts as "under-documented".
+_UNDER_DOCUMENTED_RATIO = 0.05
+
+_TEST_SEGMENTS = {"test", "tests", "__tests__", "spec", "specs"}
+_SKIP_NAMES = {"__init__.py", "conftest.py", "setup.py"}
+
+
+def _ext(path: str) -> str:
+    name = path.rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+    return name.rsplit(".", 1)[-1].lower() if "." in name else ""
+
+
+def _is_test_or_skip(path: str) -> bool:
+    norm = path.replace("\\", "/")
+    segments = [s for s in norm.split("/") if s]
+    if any(s in _TEST_SEGMENTS for s in segments):
+        return True
+    name = segments[-1] if segments else ""
+    if name in _SKIP_NAMES:
+        return True
+    stem = name.rsplit(".", 1)[0] if "." in name else name
+    # test_x.py / x_test.go / x.test.ts / x.spec.ts naming conventions
+    return stem.startswith("test_") or stem.endswith("_test") or ".test" in name or ".spec" in name
+
+
+def _count_lines(content: str, ext: str) -> tuple[int, int]:
+    """Return (code_lines, comment_lines) for one source file."""
+    line_token = _LINE_COMMENT.get(ext, "")
+    c_style = ext in _C_STYLE
+    py = ext in _PY
+
+    code = 0
+    comment = 0
+    in_block = False  # C-style /* */
+    in_doc = False  # Python triple-quote docstring
+    doc_delim = ""
+
+    for raw in content.splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+
+        if in_block:
+            comment += 1
+            if "*/" in line:
+                in_block = False
+            continue
+
+        if in_doc:
+            comment += 1
+            if doc_delim in line:
+                in_doc = False
+            continue
+
+        # Python docstring / triple-quoted block.
+        if py and (line.startswith('"""') or line.startswith("'''")):
+            doc_delim = line[:3]
+            comment += 1
+            # A one-line """doc""" opens and closes on the same line.
+            if line.count(doc_delim) < 2:
+                in_doc = True
+            continue
+
+        # C-style block comment start.
+        if c_style and line.startswith("/*"):
+            comment += 1
+            if "*/" not in line:
+                in_block = True
+            continue
+
+        # Whole-line // or # comment.
+        if line_token and line.startswith(line_token):
+            comment += 1
+            continue
+
+        code += 1
+
+    return code, comment
+
+
+def _reason(code: int, ratio: int) -> str:
+    if ratio == 0:
+        return f"{code} 行代码、几乎没有注释或文档，读懂全靠猜，改动前最该补一句说明它在做什么。"
+    return f"{code} 行代码只有约 {ratio}% 的注释/文档，核心逻辑缺解释，新人上手成本高。"
+
+
+def assess_doc_coverage(file_contents: dict[str, str], *, limit: int = 12) -> dict:
+    """Assess documentation density across source files.
+
+    Args:
+        file_contents: mapping of path to file text (as CodeABC already read it).
+        limit: how many under-documented files to return in the ranked list.
+
+    Returns::
+
+        {
+          "total_source_files": int,
+          "documented_files": int,
+          "undocumented_files": int,
+          "doc_percent": int,           # 0-100, documented / total source files
+          "under_documented": [         # ranked by code size (biggest first)
+            {"path", "code_lines", "comment_lines", "ratio", "reason"}, ...
+          ],
+          "notes": [str, ...],
+        }
+    """
+    total = 0
+    documented = 0
+    under: list[dict] = []
+
+    for path, content in file_contents.items():
+        if not content:
+            continue
+        ext = _ext(path)
+        if ext not in _LINE_COMMENT or _is_test_or_skip(path):
+            continue
+
+        code, comment = _count_lines(content, ext)
+        if code == 0:
+            continue
+        total += 1
+        ratio = comment / (code + comment) if (code + comment) else 0.0
+        if ratio > _UNDER_DOCUMENTED_RATIO:
+            documented += 1
+        if code >= _MIN_CODE_LINES and ratio <= _UNDER_DOCUMENTED_RATIO:
+            pct = int(round(ratio * 100))
+            under.append(
+                {
+                    "path": path,
+                    "code_lines": code,
+                    "comment_lines": comment,
+                    "ratio": pct,
+                    "reason": _reason(code, pct),
+                }
+            )
+
+    under.sort(key=lambda f: (-f["code_lines"], f["path"]))
+    undocumented = total - documented
+    doc_percent = int(round(documented / total * 100)) if total else 0
+
+    notes: list[str] = []
+    if total == 0:
+        notes.append("没有发现可统计的源代码文件。")
+    elif not under:
+        notes.append("核心源文件都带了一定注释/文档，文档基线不错。")
+
+    return {
+        "total_source_files": total,
+        "documented_files": documented,
+        "undocumented_files": undocumented,
+        "doc_percent": doc_percent,
+        "under_documented": under[:limit],
+        "notes": notes,
+    }
+
+
+def render_doc_coverage_markdown(project_name: str, data: dict | None) -> str:
+    """Render the documentation-coverage map as a Markdown section, or ``""``."""
+    d = data or {}
+    total = d.get("total_source_files", 0)
+    if not total:
+        return ""
+
+    lines = [
+        f"# {project_name} — 文档覆盖",
+        "",
+        f"> {total} 个源文件里约 {d.get('doc_percent', 0)}% 带有注释/文档。"
+        "下面这些是「代码不少、却几乎没解释」的文件，对刚接手的人最难读、改起来最容易踩坑。",
+        "",
+    ]
+
+    under = d.get("under_documented") or []
+    if not under:
+        lines.append("核心源文件都带了一定注释，没有明显「裸奔」的大文件。")
+        return "\n".join(lines).rstrip() + "\n"
+
+    lines.append("## 最该补文档的文件")
+    lines.append("")
+    for entry in under:
+        lines.append(f"- `{entry['path']}` — {entry['reason']}")
+
+    notes = d.get("notes") or []
+    if notes:
+        lines += ["", "## 注意事项", ""]
+        for n in notes:
+            lines.append(f"- {n}")
+
+    return "\n".join(lines).rstrip() + "\n"

backend/services/docstrings.py

@@ -0,0 +1,163 @@
+"""API documentation coverage: which public functions and classes have no docstring.
+
+``docs`` measures comment *density* — how many comment/docstring lines a file
+carries relative to its code. This asks a different, sharper question: of the
+things a reader actually calls — the public functions, classes and methods that
+make up a module's surface — how many explain themselves with a docstring?
+
+For someone learning a codebase, an undocumented public API is the wall they hit
+first: they can see ``def parse_manifest(path)`` but not what it expects or
+returns. This ranks the files whose public surface is least documented, so the
+gaps a newcomer will trip over are visible at a glance. It approximates the
+``interrogate`` metric from the Python AST: a symbol is "documented" when
+``ast.get_docstring`` finds a string, and only public names (no leading
+underscore) count, since dunders and private helpers are rarely self-documented
+by contract. ``scan_docstring_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 undocumented 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:
+    """Docstrings 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 _scan_module(tree: ast.Module) -> tuple[int, int, list[str]]:
+    """Return (documentable, documented, undocumented_names) for a parsed module.
+
+    Counts public top-level functions and classes plus public methods of public
+    classes. Walks only the module and class bodies rather than ``ast.walk`` so
+    nested/local helpers — which are not part of the callable surface — are not
+    counted.
+    """
+    documentable = 0
+    documented = 0
+    missing: list[str] = []
+
+    def _record(has_doc: bool, label: str) -> None:
+        nonlocal documentable, documented
+        documentable += 1
+        if has_doc:
+            documented += 1
+        else:
+            missing.append(label)
+
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef) and _is_public(node.name):
+            _record(ast.get_docstring(node) is not None, node.name)
+        elif isinstance(node, ast.ClassDef) and _is_public(node.name):
+            _record(ast.get_docstring(node) is not None, node.name)
+            for sub in node.body:
+                if isinstance(sub, ast.FunctionDef | ast.AsyncFunctionDef) and _is_public(sub.name):
+                    _record(ast.get_docstring(sub) is not None, f"{node.name}.{sub.name}")
+
+    return documentable, documented, missing
+
+
+def scan_docstring_coverage(file_contents: dict[str, str], *, limit: int = 15) -> dict:
+    """Rank the project's Python files by how much of their public API lacks docstrings.
+
+    Args:
+        file_contents: mapping of path to file text (as CodeABC already read it).
+        limit: how many of the least-documented files to return.
+
+    Returns ``{"total_symbols", "documented", "coverage", "files"}`` where
+    ``coverage`` is the repo-wide documented fraction (0.0-1.0, and 1.0 when there
+    is no public API to document) and ``files`` are the files with the most
+    undocumented public symbols (descending), each ``{"path", "symbols",
+    "documented", "coverage", "missing"}``.
+    """
+    total_symbols = 0
+    total_documented = 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
+
+        documentable, documented, missing = _scan_module(tree)
+        if documentable == 0:
+            continue  # no public surface to document
+
+        total_symbols += documentable
+        total_documented += documented
+        if documented >= documentable:
+            continue  # fully documented, nothing to flag
+
+        scored.append(
+            {
+                "path": path,
+                "symbols": documentable,
+                "documented": documented,
+                "coverage": round(documented / documentable, 3),
+                "missing": missing[:_MISSING_SAMPLE],
+            }
+        )
+
+    coverage = round(total_documented / total_symbols, 3) if total_symbols else 1.0
+    # Worst first: most undocumented symbols, then lowest coverage, then path.
+    scored.sort(key=lambda f: (-(f["symbols"] - f["documented"]), f["coverage"], f["path"]))
+    return {
+        "total_symbols": total_symbols,
+        "documented": total_documented,
+        "coverage": coverage,
+        "files": scored[:limit],
+    }
+
+
+def render_docstring_coverage_markdown(project_name: str, data: dict | None) -> str:
+    """Render the docstring-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)
+    documented = data.get("documented") or 0
+    files = data.get("files") or []
+
+    lines = [
+        f"# {project_name} — API 文档覆盖率（哪些公开接口没写文档字符串）",
+        "",
+        "> 统计每个文件里「别人会调用」的公开函数、类、方法中有多少写了 docstring。"
+        "这和「注释密度」不同——密度看整体注释多少，这里只看**对外接口**是否自解释，"
+        "没文档的公开接口正是新人最先撞墙的地方。私有成员和 dunder（下划线开头）不计。",
+        "",
+        f"**整体覆盖率：{coverage_pct}%**（{documented}/{total} 个公开接口有文档字符串）。",
+        "",
+    ]
+    if files:
+        lines.append("公开接口文档最缺的文件：")
+        lines.append("")
+        for f in files:
+            missing = "、".join(f["missing"])
+            more = "…" if f["symbols"] - f["documented"] > len(f["missing"]) else ""
+            lines.append(
+                f"- `{f['path']}` — {f['documented']}/{f['symbols']} 有文档"
+                f"（{round(f['coverage'] * 100)}%），缺：{missing}{more}"
+            )
+    return "\n".join(lines).rstrip() + "\n"