codeabc 0.1.0__py3-none-any.whl

backend/services/long_functions.py

@@ -0,0 +1,101 @@
+"""Flag over-long functions — functions whose body runs on for many lines.
+
+Length is a readability signal that :mod:`complexity` and :mod:`deep_nesting` both
+miss. A function can have very few branches (low cyclomatic complexity) and shallow
+nesting, yet still be hundreds of lines of straight-line code — reading it means
+scrolling and holding a long story in your head with no natural place to pause. For
+a beginner these are the functions that feel exhausting even though no single line
+is hard, and they are usually the clearest candidates for splitting into a few
+named helper functions, each doing one thing.
+
+This is deliberately a *physical line span* (``def`` line through the last line of
+the body), which is the same yardstick common linters use, rather than a token or
+statement count: it is the number a reader actually scrolls past, and it needs no
+language-specific tuning to be meaningful to a newcomer.
+"""
+
+from __future__ import annotations
+
+import ast
+
+# Functions at least this many lines long are surfaced.
+_LENGTH_THRESHOLD = 60
+
+
+def _function_length(node: ast.FunctionDef | ast.AsyncFunctionDef) -> int:
+    """Line span of a function, from its ``def`` line through the end of its body.
+
+    Decorators are excluded (``node.lineno`` points at ``def``, not at the first
+    decorator), so a function is not penalised for the decorators stacked above it.
+    Falls back to a single line when ``end_lineno`` is unavailable.
+    """
+    end = getattr(node, "end_lineno", None)
+    if end is None:
+        return 1
+    return end - node.lineno + 1
+
+
+def scan_long_functions(
+    file_contents: dict[str, str], *, threshold: int = _LENGTH_THRESHOLD, limit: int = 15
+) -> dict:
+    """Find functions whose body spans ``threshold`` lines or more.
+
+    Args:
+        file_contents: mapping of path to file text (as CodeABC already read it).
+        threshold: minimum line span to flag a function.
+        limit: how many of the longest functions to return.
+
+    Returns ``{"total", "max_length", "threshold", "files"}`` where ``files`` lists
+    the longest functions (descending), each ``{"path", "function", "length"}``.
+    Test files and non-Python files are skipped. A nested helper is measured on its
+    own, so both an over-long outer function and an over-long inner one can surface.
+    """
+    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)):
+                length = _function_length(node)
+                overall_max = max(overall_max, length)
+                if length >= threshold:
+                    flagged.append({"path": path, "function": node.name, "length": length})
+
+    flagged.sort(key=lambda f: (-f["length"], f["path"], f["function"]))
+    return {
+        "total": len(flagged),
+        "max_length": overall_max,
+        "threshold": threshold,
+        "files": flagged[:limit],
+    }
+
+
+def render_long_functions_markdown(project_name: str, data: dict | None) -> str:
+    """Render the long-functions section, or an empty string when nothing is flagged."""
+    if not data or not data.get("files"):
+        return ""
+
+    threshold = data.get("threshold", _LENGTH_THRESHOLD)
+    lines = [
+        f"## 过长的函数（{project_name}）",
+        "",
+        "下面这些函数一口气写了很多行。哪怕里面没有复杂的分支、也没有很深的嵌套，"
+        "光是「长」本身就难读——你得一直往下滚，脑子里还要记着开头发生了什么，中间"
+        f"却没有一个自然的停顿点。这里列出**{threshold} 行或更长**的函数，它们通常"
+        "最值得拆成几个各司其职、名字取好的小函数：一个函数只做一件事，读的人就能"
+        "一段一段看懂，而不用一次消化一整篇。",
+        "",
+        "| 文件 | 函数 | 行数 |",
+        "| --- | --- | --- |",
+    ]
+    for f in data["files"]:
+        lines.append(f"| `{f['path']}` | `{f['function']}` | {f['length']} |")
+    return "\n".join(lines)

backend/services/ownership.py

@@ -0,0 +1,194 @@
+"""Code ownership and knowledge-silo analysis from git history.
+
+Churn says *how often* a file changes; ownership says *who* changes it. The
+two are independent dynamic signals: a file can be a quiet corner that only one
+person has ever touched (a knowledge silo — risky if they leave) without being
+a churn hotspot at all.
+
+For each file we derive, from the author of every commit that touched it:
+
+* the primary author and how much of the history they own (a percentage),
+* how many distinct authors have touched it,
+* the *bus factor* — the smallest number of authors who together account for a
+  majority of the commits. A bus factor of 1 means a single person holds the
+  majority of the knowledge for that file.
+
+:func:`analyze_ownership` is pure: it parses the same ``git log --numstat``
+text that :func:`churn.collect_git_log` already produces, so it is unit-testable
+with fixture strings and needs no real repository. We deliberately re-parse that
+text rather than coupling to churn's internals, keeping the two analyses
+independent.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from .churn import _COMMIT_MARKER, _normalize_path
+
+# A file needs at least this many commits before its ownership ratio is worth
+# reporting — one or two commits by one person is not a meaningful "silo".
+_MIN_COMMITS_FOR_SILO = 3
+# A primary author owning at least this share of a file's commits makes it a
+# knowledge-concentration risk worth surfacing.
+_SILO_OWNERSHIP_PCT = 80
+
+
+def _bus_factor(author_commits: dict[str, int], total: int) -> int:
+    """Smallest number of top authors whose commits exceed half the total."""
+    cumulative = 0
+    for rank, commits in enumerate(sorted(author_commits.values(), reverse=True), start=1):
+        cumulative += commits
+        if cumulative * 2 > total:
+            return rank
+    return len(author_commits)
+
+
+def _ownership_reason(primary: str, pct: int, authors: int, bus_factor: int) -> str:
+    if bus_factor == 1 and authors == 1:
+        return f"只有 {primary} 一个人动过，知识完全集中，离职/请假就没人懂，最该补文档和结对。"
+    if bus_factor == 1:
+        return (
+            f"{primary} 掌握了 {pct}% 的改动，是事实上的 owner，有问题先找 ta，"
+            "但也别让知识只压一个人。"
+        )
+    return (
+        f"{authors} 个人共同维护（{primary} 改得最多，占 {pct}%），知识相对分散，改动前可多方对齐。"
+    )
+
+
+def analyze_ownership(
+    git_log_text: str | None,
+    *,
+    scanned_paths: set[str] | list[str] | None = None,
+    limit: int = 8,
+) -> dict:
+    """Parse ``git log --numstat`` text into per-file ownership and silos.
+
+    Args:
+        git_log_text: output of :func:`churn.collect_git_log` (``None`` ⇒ empty).
+        scanned_paths: if given, only these paths are considered, so ownership
+            lines up with the files CodeABC actually scanned.
+        limit: how many entries to return in each list.
+
+    Returns ``{"owners", "silos", "commits_analyzed"}``. ``owners`` ranks the
+    busiest files by commit count with their primary author; ``silos`` is the
+    subset whose knowledge is concentrated in one person (bus factor 1 and a
+    dominant owner), sorted so the riskiest (most commits behind one person)
+    come first.
+    """
+    allowed: set[str] | None = set(scanned_paths) if scanned_paths is not None else None
+
+    # path -> author -> number of commits that author made touching the path
+    author_commits: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
+    commits_analyzed = 0
+
+    current_author = ""
+    touched: set[str] = set()
+
+    def _flush(files: set[str], author: str) -> None:
+        if not files:
+            return
+        nonlocal commits_analyzed
+        commits_analyzed += 1
+        for path in files:
+            author_commits[path][author] += 1
+
+    for line in (git_log_text or "").splitlines():
+        if line.startswith(_COMMIT_MARKER):
+            _flush(touched, current_author)
+            touched = set()
+            parts = line[len(_COMMIT_MARKER) :].split("::")
+            current_author = parts[2] if len(parts) >= 3 else ""
+            continue
+        if not line.strip():
+            continue
+        cols = line.split("\t")
+        if len(cols) != 3:
+            continue
+        _added, _deleted, raw_path = cols
+        path = _normalize_path(raw_path)
+        if not path or (allowed is not None and path not in allowed):
+            continue
+        touched.add(path)
+    _flush(touched, current_author)
+
+    owners = []
+    for path, commits_by_author in author_commits.items():
+        total = sum(commits_by_author.values())
+        if total < 2:
+            continue
+        primary, primary_commits = max(commits_by_author.items(), key=lambda kv: (kv[1], kv[0]))
+        pct = round(primary_commits / total * 100)
+        authors = len(commits_by_author)
+        bus_factor = _bus_factor(commits_by_author, total)
+        owners.append(
+            {
+                "path": path,
+                "primary_author": primary,
+                "ownership": pct,
+                "authors": authors,
+                "commits": total,
+                "bus_factor": bus_factor,
+                "reason": _ownership_reason(primary, pct, authors, bus_factor),
+            }
+        )
+
+    owners.sort(key=lambda o: (-o["commits"], o["bus_factor"], o["path"]))
+
+    silos = [
+        o
+        for o in owners
+        if o["bus_factor"] == 1
+        and o["ownership"] >= _SILO_OWNERSHIP_PCT
+        and o["commits"] >= _MIN_COMMITS_FOR_SILO
+    ]
+    silos.sort(key=lambda o: (-o["commits"], -o["ownership"], o["path"]))
+
+    return {
+        "owners": owners[:limit],
+        "silos": silos[:limit],
+        "commits_analyzed": commits_analyzed,
+    }
+
+
+def render_ownership_markdown(project_name: str, ownership_data: dict | None) -> str:
+    """Render the ownership analysis as a Markdown section, or ``""`` if empty.
+
+    Returns an empty string when there's no usable history (e.g. an uploaded,
+    non-git project) so callers can skip it cleanly.
+    """
+    data = ownership_data or {}
+    owners = data.get("owners") or []
+    silos = data.get("silos") or []
+    if not owners:
+        return ""
+
+    analyzed = data.get("commits_analyzed", 0)
+    lines = [
+        f"# {project_name} — 代码归属",
+        "",
+        f"> 基于最近 {analyzed} 个提交的作者算出，看这块代码该问谁、知识有没有压在一个人身上。",
+        "",
+        "## 谁在维护（按改动次数）",
+        "",
+    ]
+    lines.extend(
+        f"- `{o['path']}` — 主要是 {o['primary_author']}"
+        f"（占 {o['ownership']}%、共 {o['authors']} 人、bus factor {o['bus_factor']}）："
+        f"{o['reason']}"
+        for o in owners
+    )
+    lines.append("")
+
+    if silos:
+        lines.append("## 知识孤岛（只压在一个人身上）")
+        lines.append("")
+        lines.extend(
+            f"- `{s['path']}` — {s['primary_author']} 一个人掌握了 {s['ownership']}%"
+            f"（{s['commits']} 次改动）：建议补文档、结对或 code review 分散知识。"
+            for s in silos
+        )
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"

backend/services/package_purposes.py

@@ -0,0 +1,112 @@
+"""Package purposes: explain what a third-party library is for, in plain words.
+
+:mod:`backend.services.dependencies` lists the packages a project installs, but a
+bare name like ``fastapi``, ``pydantic`` or ``sqlalchemy`` means nothing to a
+non-programmer. This is a curated dictionary (same plain-language voice as
+:mod:`backend.services.glossary` and :mod:`backend.services.filenames`) mapping
+the most common Python and JavaScript packages to a one-line "what it does, and
+why a project would pull it in".
+
+:func:`explain_package` normalises the name (lowercases, strips extras such as
+``uvicorn[standard]``, and resolves a few well-known aliases) before looking it
+up, and returns ``None`` for anything not in the dictionary. Deterministic — no
+network, no LLM — so it is instant and unit-testable.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Canonical lowercase package name -> plain-language purpose.
+_PURPOSES: dict[str, str] = {
+    # --- Python: web / API ---
+    "fastapi": "搭 Web API 的框架，用很少的代码就能对外提供接口，自带数据校验和文档。",
+    "flask": "一个轻量的 Web 框架，用来快速搭网站或接口，小项目常用。",
+    "django": "一个全功能 Web 框架，自带数据库、后台管理、用户系统，适合做完整网站。",
+    "starlette": "FastAPI 底层用的异步 Web 工具库，负责处理请求和路由。",
+    "uvicorn": "把 Python Web 应用真正跑起来的服务器，FastAPI 项目几乎都用它启动。",
+    "gunicorn": "生产环境里跑 Python Web 应用的服务器，能开多个进程扛并发。",
+    "requests": "发 HTTP 请求的库（访问网页、调别人的接口），是 Python 里最常见的之一。",
+    "httpx": "和 requests 类似的发 HTTP 请求的库，但支持异步、更现代。",
+    "aiohttp": "异步地发 HTTP 请求或搭服务器，适合要同时处理很多网络请求的场景。",
+    "websockets": "处理 WebSocket 长连接，用来做实时双向通信（如聊天、推送）。",
+    # --- Python: data / validation ---
+    "pydantic": "定义数据该长什么样并自动校验，传进来的数据不合规矩会直接报错。",
+    "numpy": "数值计算的基础库，处理大批数字和矩阵又快又省，科学计算的地基。",
+    "pandas": "处理表格数据（像代码版的 Excel），做数据清洗和分析的主力工具。",
+    "scipy": "在 numpy 之上的科学计算库，提供统计、优化、信号处理等高级算法。",
+    "matplotlib": "把数据画成图表（折线、柱状、散点等）的画图库。",
+    "polars": "和 pandas 类似的表格数据处理库，主打速度快、省内存。",
+    # --- Python: AI / ML ---
+    "torch": "PyTorch，做深度学习/训练神经网络的主流框架。",
+    "tensorflow": "Google 的深度学习框架，和 PyTorch 并列的两大主流之一。",
+    "transformers": "Hugging Face 的库，几行代码就能加载和使用各种预训练大模型。",
+    "openai": "调用 OpenAI（GPT 等）模型的官方库。",
+    "anthropic": "调用 Anthropic（Claude）模型的官方库。",
+    "langchain": "把大模型和工具、数据、流程串起来做 AI 应用的框架。",
+    "scikit-learn": "经典机器学习库（分类、回归、聚类等），不涉及深度学习时常用。",
+    "datasets": "Hugging Face 的库，方便地下载和处理机器学习数据集。",
+    # --- Python: database / cache ---
+    "sqlalchemy": "用 Python 对象操作数据库，不用手写一堆 SQL。",
+    "psycopg2": "连接 PostgreSQL 数据库的驱动。",
+    "pymysql": "连接 MySQL 数据库的驱动。",
+    "redis": "连接 Redis（内存数据库/缓存）的库，常用来做缓存和队列。",
+    "pymongo": "连接 MongoDB（文档数据库）的库。",
+    "alembic": "管理数据库结构变更的工具，给 SQLAlchemy 配套做迁移。",
+    # --- Python: utilities ---
+    "pyyaml": "读写 YAML 格式的配置文件。",
+    "python-dotenv": "把 .env 文件里的配置加载成环境变量。",
+    "pillow": "处理图片（打开、缩放、裁剪、转格式）的库。",
+    "opencv-python": "做图像和视频处理、计算机视觉的库（OpenCV）。",
+    "beautifulsoup4": "从 HTML 网页里抽取数据（爬虫常用）。",
+    "click": "做命令行工具的库，帮你定义命令、参数和帮助信息。",
+    "rich": "在终端里打印彩色、表格、进度条等漂亮输出。",
+    "tqdm": "给循环加一个进度条，一眼看出跑到哪了。",
+    "celery": "做后台任务队列，把耗时活儿丢到后台异步处理。",
+    "boto3": "操作 AWS 云服务（S3 存储、各种云资源）的官方库。",
+    # --- Python: dev / test ---
+    "pytest": "Python 最常用的测试框架，用来自动检查代码对不对。",
+    "ruff": "又快又全的代码检查+格式化工具，挑出风格和潜在问题。",
+    "mypy": "静态类型检查器，在不运行代码的情况下找出类型用错的地方。",
+    "black": "自动把代码格式化成统一风格，省得手动调缩进和换行。",
+    "flake8": "检查代码风格和明显错误的工具。",
+    # --- JavaScript / TypeScript ---
+    "react": "搭前端界面的主流框架，把页面拆成可复用的组件。",
+    "react-dom": "把 React 组件真正渲染到网页上的配套库。",
+    "vue": "和 React 并列的前端框架，搭交互式网页界面。",
+    "express": "Node.js 上最常用的后端 Web 框架，搭接口和服务器。",
+    "axios": "在浏览器或 Node 里发 HTTP 请求的库。",
+    "lodash": "一堆现成的 JavaScript 工具函数（处理数组、对象等），省得自己写。",
+    "typescript": "给 JavaScript 加类型的语言，写大型项目更稳、更好维护。",
+    "vite": "现代前端构建/开发工具，启动快、热更新快。",
+    "webpack": "把前端代码和资源打包成浏览器能跑的文件的构建工具。",
+    "tailwindcss": "用一串小类名直接写样式的 CSS 框架，不用单独写 CSS 文件。",
+    "next": "基于 React 的全栈框架，自带路由、服务端渲染等。",
+    "eslint": "检查 JavaScript/TypeScript 代码风格和问题的工具。",
+    "zod": "在 TypeScript 里定义并校验数据格式的库（类似 Python 的 pydantic）。",
+    "zustand": "React 里管理共享状态的轻量库。",
+}
+
+# Aliases: the name as it may appear in a manifest -> the canonical key above.
+_ALIASES: dict[str, str] = {
+    "cv2": "opencv-python",
+    "sklearn": "scikit-learn",
+    "pil": "pillow",
+    "bs4": "beautifulsoup4",
+    "yaml": "pyyaml",
+    "dotenv": "python-dotenv",
+    "pytorch": "torch",
+    "react-router-dom": "react",
+}
+
+# Strip an extras suffix like "uvicorn[standard]" -> "uvicorn".
+_EXTRAS_RE = re.compile(r"\[.*\]$")
+
+
+def explain_package(name: str) -> str | None:
+    """Return a plain-language purpose for *name*, or ``None`` if unknown."""
+    if not name:
+        return None
+    key = _EXTRAS_RE.sub("", name.strip().lower())
+    key = _ALIASES.get(key, key)
+    return _PURPOSES.get(key)

backend/services/pr_reading.py

@@ -0,0 +1,181 @@
+"""Pull-request reading mode: turn a PR link into a plain-language diff walkthrough.
+
+Deterministic core, no LLM call: fetch the unified diff, break it into
+per-file changes, classify each file's change type, and propose a reading
+order. An LLM explanation layer can sit on top of this payload later.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import urllib.request
+from dataclasses import dataclass, field
+
+_PR_URL_RE = re.compile(r"^https?://(?:www\.)?github\.com/([^/]+)/([^/]+)/pull/(\d+)(?:/[^\s]*)?$")
+
+
+@dataclass
+class PrRef:
+    owner: str
+    repo: str
+    number: int
+
+
+@dataclass
+class FileChange:
+    path: str
+    added: int
+    deleted: int
+    change_type: str  # code | test | docs | config | other
+    hunks: list[str] = field(default_factory=list)
+
+
+def parse_pr_url(url: str) -> PrRef:
+    """Parse https://github.com/owner/repo/pull/123 (any suffix after the number)."""
+    match = _PR_URL_RE.match(url.strip())
+    if not match:
+        raise ValueError(f"not a GitHub pull request URL: {url}")
+    owner, repo, number = match.group(1), match.group(2), int(match.group(3))
+    return PrRef(owner=owner, repo=repo.removesuffix(".git"), number=number)
+
+
+def fetch_pr_diff(ref: PrRef, timeout: float = 30.0) -> str:
+    """Fetch the PR's unified diff. Try gh first (auth'd), fall back to patch-diff URL."""
+    try:
+        result = subprocess.run(
+            ["gh", "pr", "diff", str(ref.number), "--repo", f"{ref.owner}/{ref.repo}"],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    url = f"https://patch-diff.githubusercontent.com/raw/{ref.owner}/{ref.repo}/pull/{ref.number}.diff"
+    with urllib.request.urlopen(url, timeout=timeout) as resp:  # noqa: S310 (fixed host)
+        return resp.read().decode("utf-8", errors="replace")
+
+
+_FILE_KIND_RULES: tuple[tuple[str, str], ...] = (
+    ("test", "test"),
+    ("docs", "docs"),
+    ("config", "config"),
+)
+
+
+def _file_kind(path: str) -> str:
+    p = path.lower()
+    name = p.rsplit("/", 1)[-1]
+    if any(
+        tok in p for tok in ("/tests/", "/test/", "test_", "_test.", ".test.", ".spec.")
+    ) or name.startswith(("test_", "tests_")):
+        return "test"
+    if name.endswith((".md", ".rst", ".txt")) or p.startswith(("docs/", "doc/")):
+        return "docs"
+    if name.endswith((".json", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".lock")) or name in {
+        "dockerfile",
+        "makefile",
+        "justfile",
+    }:
+        return "config"
+    return "code"
+
+
+def parse_diff_files(diff_text: str) -> list[FileChange]:
+    """Break a unified diff into per-file changes with add/del counts."""
+    files: list[FileChange] = []
+    current: FileChange | None = None
+    for line in diff_text.splitlines():
+        if line.startswith("diff --git "):
+            if current is not None:
+                files.append(current)
+            match = re.match(r"diff --git a/(\S+) b/(\S+)", line)
+            path = match.group(2) if match else "unknown"
+            current = FileChange(path=path, added=0, deleted=0, change_type=_file_kind(path))
+        elif current is not None:
+            if line.startswith("@@"):
+                current.hunks.append(line)
+            elif line.startswith("+") and not line.startswith("+++"):
+                current.added += 1
+            elif line.startswith("-") and not line.startswith("---"):
+                current.deleted += 1
+    if current is not None:
+        files.append(current)
+    return files
+
+
+def reading_order(files: list[FileChange]) -> list[FileChange]:
+    """Suggest a review order: biggest production-code diffs first, then tests, then docs/config."""
+    rank = {"code": 0, "test": 1, "config": 2, "docs": 3, "other": 4}
+    return sorted(
+        files,
+        key=lambda f: (rank.get(f.change_type, 4), -(f.added + f.deleted), f.path),
+    )
+
+
+def summarize_diff(files: list[FileChange]) -> dict:
+    """Plain-language rollup of what the PR touches, no LLM needed."""
+    by_kind: dict[str, int] = {}
+    for f in files:
+        by_kind[f.change_type] = by_kind.get(f.change_type, 0) + 1
+    total_added = sum(f.added for f in files)
+    total_deleted = sum(f.deleted for f in files)
+    biggest = max(files, key=lambda f: f.added + f.deleted) if files else None
+    return {
+        "file_count": len(files),
+        "by_kind": by_kind,
+        "total_added": total_added,
+        "total_deleted": total_deleted,
+        "biggest_file": biggest.path if biggest else None,
+    }
+
+
+def analyze_pr(url: str) -> dict:
+    """Full pipeline: URL -> diff -> per-file breakdown with a suggested reading order."""
+    ref = parse_pr_url(url)
+    diff_text = fetch_pr_diff(ref)
+    files = parse_diff_files(diff_text)
+    ordered = reading_order(files)
+    return {
+        "url": url,
+        "owner": ref.owner,
+        "repo": ref.repo,
+        "number": ref.number,
+        "summary": summarize_diff(files),
+        "files": [
+            {
+                "path": f.path,
+                "added": f.added,
+                "deleted": f.deleted,
+                "change_type": f.change_type,
+                "hunks": f.hunks,
+            }
+            for f in ordered
+        ],
+    }
+
+
+def render_markdown(analysis: dict) -> str:
+    """Human-readable walkthrough of the analysis payload."""
+    summary = analysis["summary"]
+    lines = [
+        f"# PR reading: {analysis['owner']}/{analysis['repo']}#{analysis['number']}",
+        "",
+        (
+            f"{summary['file_count']} files touched "
+            f"(+{summary['total_added']} / -{summary['total_deleted']}). "
+            + ", ".join(f"{kind}: {count}" for kind, count in sorted(summary["by_kind"].items()))
+        ),
+        "",
+        "## Suggested reading order",
+    ]
+    for i, f in enumerate(analysis["files"], start=1):
+        lines.append(f"{i}. `{f['path']}` ({f['change_type']}, +{f['added']} / -{f['deleted']})")
+    return "\n".join(lines) + "\n"
+
+
+def to_json(analysis: dict) -> str:
+    return json.dumps(analysis, ensure_ascii=False, indent=2)