codeabc 0.1.2__tar.gz → 0.1.3__tar.gz

{codeabc-0.1.2 → codeabc-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: codeabc
-Version: 0.1.2
+Version: 0.1.3
 Summary: AI-powered code reader for non-programmers
 Author-email: Yufeng He <40085740+he-yufeng@users.noreply.github.com>
 License-Expression: MIT
@@ -22,7 +22,7 @@ Requires-Python: >=3.10
 Requires-Dist: aiofiles>=24.0.0
 Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: fastapi>=0.115.0
-Requires-Dist: litellm>=1.40.0
+Requires-Dist: litellm!=1.100.0,!=1.98.0,!=1.99.0,>=1.40.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: python-multipart>=0.0.9
 Requires-Dist: uvicorn[standard]>=0.30.0
@@ -125,6 +125,10 @@ Before trusting a script you didn't write, you usually want to know what it reac
 
 The most dangerous line in a codebase is often the one that quietly hides a problem: a bare `except:` that catches everything, an empty `catch {}` that throws the error away, a failure that gets logged and then ignored. To a non-coder these are invisible; to a maintainer they are where bugs go to hide. CodeABC flags these silent-failure spots and explains, in everyday terms, why "the program kept going as if nothing happened" can be worse than crashing loudly.
 
+### Which Functions Does Nobody Call?
+
+Orphan modules tell you which files nobody imports; this goes one level finer and asks which functions and classes inside otherwise used files nobody calls. A public helper written for a caller that no longer exists is dead weight every reader still has to load into their head, and it is usually the code that breaks first in a refactor because nothing exercises it. CodeABC flags top-level functions, classes, and exported symbols whose name never appears outside their own file, with the reasoning spelled out. Decorated definitions (routes, fixtures, commands) are skipped on purpose, and the report calls itself a candidate list for human review rather than a verdict, because string references and dynamic imports are invisible to any text scan.
+
 ### Which Files Are Begging for Docs?
 
 Not every file needs a comment, but the ones that other files lean on heavily and that still have almost no explanation are the ones that cost a newcomer the most. CodeABC scores each file on how under-documented it is relative to how central it is, and surfaces the handful that would help the most if someone wrote a few sentences at the top. It is a reading aid as much as a writing one: these are usually the files worth understanding first.

{codeabc-0.1.2 → codeabc-0.1.3}/README.md

@@ -90,6 +90,10 @@ Before trusting a script you didn't write, you usually want to know what it reac
 
 The most dangerous line in a codebase is often the one that quietly hides a problem: a bare `except:` that catches everything, an empty `catch {}` that throws the error away, a failure that gets logged and then ignored. To a non-coder these are invisible; to a maintainer they are where bugs go to hide. CodeABC flags these silent-failure spots and explains, in everyday terms, why "the program kept going as if nothing happened" can be worse than crashing loudly.
 
+### Which Functions Does Nobody Call?
+
+Orphan modules tell you which files nobody imports; this goes one level finer and asks which functions and classes inside otherwise used files nobody calls. A public helper written for a caller that no longer exists is dead weight every reader still has to load into their head, and it is usually the code that breaks first in a refactor because nothing exercises it. CodeABC flags top-level functions, classes, and exported symbols whose name never appears outside their own file, with the reasoning spelled out. Decorated definitions (routes, fixtures, commands) are skipped on purpose, and the report calls itself a candidate list for human review rather than a verdict, because string references and dynamic imports are invisible to any text scan.
+
 ### Which Files Are Begging for Docs?
 
 Not every file needs a comment, but the ones that other files lean on heavily and that still have almost no explanation are the ones that cost a newcomer the most. CodeABC scores each file on how under-documented it is relative to how central it is, and surfaces the handful that would help the most if someone wrote a few sentences at the top. It is a reading aid as much as a writing one: these are usually the files worth understanding first.

{codeabc-0.1.2 → codeabc-0.1.3}/README_CN.md

@@ -98,6 +98,10 @@ Cursor/VS Code 是给程序员用的瑞士军刀，码上懂是给普通人用
 
 一份代码里最危险的一行，往往是悄悄把问题藏起来的那行：一个 `except:` 把所有异常一网打尽、一个空的 `catch {}` 把错误直接扔掉、一个失败被记了个日志然后就当没事发生。对不懂代码的人这些完全看不见，对维护者这些正是 bug 藏身的地方。码上懂会把这些"静默失败"的位置标出来，用大白话讲清楚为什么"程序假装什么都没发生地继续跑"有时比当场报错崩掉更糟。
 
+### 哪些函数根本没有人在用？
+
+"没人 import 的文件"好找，更细一层的问题是：那些正常被用到的文件里，有没有谁写了却没人调用的函数和类？一个当年为某个调用方写的公开函数，调用方没了，函数还在，每个读代码的人都得白白把它装进脑子，重构时又因为它没有测试覆盖而最先坏掉。码上懂会把"名字在项目里其他地方一次都没出现过"的顶层函数、类和导出符号挑出来，并把判断依据写清楚。带装饰器的定义（路由、fixture、命令）会特意跳过，报告也明说自己是"待人工复核的候选"而不是判决书，因为字符串引用和动态 import 是任何文本扫描都看不见的。
+
 ### 哪些文件最该补说明？
 
 不是每个文件都需要注释，但那些被很多别的文件依赖、自己却几乎没有任何说明的文件，是最让新人头疼的。码上懂会按"有多核心"对比"有多缺说明"给每个文件打分，挑出那几个"只要有人在开头写几句话就最能帮到大家"的文件。它既是写文档的提示，也是读代码的向导：这几个文件通常正是最值得先搞懂的。

{codeabc-0.1.2 → codeabc-0.1.3}/backend/models.py

@@ -183,6 +183,21 @@ class ErrorHandling(BaseModel):
     notes: list[str] = []
 
 
+class UnusedExport(BaseModel):
+    path: str
+    name: str
+    kind: str  # "function" | "class"
+    line: int
+    reason: str  # plain-language explanation for a non-programmer
+
+
+class UnusedExports(BaseModel):
+    total: int = 0
+    files_affected: int = 0
+    findings: list[UnusedExport] = []
+    notes: list[str] = []
+
+
 class ExternalService(BaseModel):
     name: str
     category: str  # AI / 大模型 | 云服务 | 数据库 | 支付 | 通讯 | ...
@@ -202,6 +217,7 @@ class EnvVar(BaseModel):
     name: str
     required: bool  # read via os.environ["X"] somewhere, so it must be set
     count: int = 1  # how many places read it
+    documented: bool = True  # mentioned in .env.example / README / docs anywhere
 
 
 class EntryPoint(BaseModel):
@@ -484,6 +500,7 @@ class ProjectMeta(BaseModel):
     action_plan: ActionPlan | None = None
     doc_coverage: DocCoverage | None = None
     error_handling: ErrorHandling | None = None
+    unused_exports: UnusedExports | None = None
     integrations: Integrations | None = None
     release: ReleaseSummary | None = None
     contribution: ContributionGuide | None = None
@@ -614,7 +631,10 @@ class FileOutline(BaseModel):
 
 
 class GitHubRequest(BaseModel):
-    url: str = Field(..., pattern=r"^https?://github\.com/.+/.+")
+    # Shape validation lives in github_clone._parse_github_url, which already
+    # accepts bare github.com/... links, inner-page URLs, git@ SSH and the
+    # owner/repo shorthand; a regex here rejected those before reaching it.
+    url: str = Field(..., min_length=1, description="GitHub URL or owner/repo shorthand")
 
 
 class UploadedFile(BaseModel):

{codeabc-0.1.2 → codeabc-0.1.3}/backend/routers/project.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import uuid
 
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import Response
 
 from backend.models import (
@@ -71,6 +71,8 @@ from backend.models import (
     TechDebtFile,
     TestCoverageSummary,
     TunableSetting,
+    UnusedExport,
+    UnusedExports,
     UploadedFile,
 )
 from backend.services import (
@@ -116,6 +118,7 @@ from backend.services import (
     techdebt,
     too_many_params,
     typing_coverage,
+    unused_exports,
 )
 from backend.services import (
     health_score as health_score_svc,
@@ -252,6 +255,7 @@ def _content_analyses(
     """
     tech_debt = techdebt.scan_tech_debt(file_contents)
     env = envscan.scan_env_vars(file_contents)
+    undocumented_env = set(envscan.find_undocumented_env_vars(env, file_contents))
     entries = entrypoints.find_entry_points(file_contents)
     cli_commands = commands.find_cli_commands(file_contents)
     data_models = datamodels.find_data_models(file_contents)
@@ -266,6 +270,7 @@ def _content_analyses(
     api = apimap.scan_api_routes(file_contents)
     doc = docs.assess_doc_coverage(file_contents)
     silent = error_handling.find_swallowed_errors(file_contents)
+    dead = unused_exports.find_unused_exports(file_contents)
     integ = integrations.detect_external_services(file_contents)
     rel = release_map.find_release_info(file_contents)
     contrib = contributing.find_contribution_guide(file_contents)
@@ -285,7 +290,13 @@ def _content_analyses(
             TechDebtFile(path=f["path"], count=f["count"]) for f in tech_debt["files"]
         ],
         "env_vars": [
-            EnvVar(name=v["name"], required=v["required"], count=v["count"]) for v in env["vars"]
+            EnvVar(
+                name=v["name"],
+                required=v["required"],
+                count=v["count"],
+                documented=v["name"] not in undocumented_env,
+            )
+            for v in env["vars"]
         ],
         "entry_points": [
             EntryPoint(path=e["path"], kind=e["kind"], command=e["command"], reason=e["reason"])
@@ -410,6 +421,12 @@ def _content_analyses(
             findings=[SilentFailure(**f) for f in silent["findings"]],
             notes=silent["notes"],
         ),
+        "unused_exports": UnusedExports(
+            total=dead["total"],
+            files_affected=dead["files_affected"],
+            findings=[UnusedExport(**f) for f in dead["findings"]],
+            notes=dead["notes"],
+        ),
         "integrations": Integrations(
             total=integ["total"],
             services=[ExternalService(**s) for s in integ["services"]],
@@ -796,15 +813,20 @@ async def get_references(project_id: str, name: str):
 
 
 @router.get("/pr-reading")
-async def get_pr_reading(url: str):
+async def get_pr_reading(url: str, request: Request, explain: bool = False):
     """Turn a PR link into a plain-language diff walkthrough.
 
-    Deterministic (no LLM): fetches the PR's unified diff, breaks it into
-    per-file changes with add/del counts, classifies each file as code, test,
-    docs, or config, and proposes a review reading order (biggest production
-    diffs first). An LLM explanation layer can sit on this payload later.
+    The deterministic core (no LLM) fetches the PR's unified diff, breaks it
+    into per-file changes with add/del counts, classifies each file as code,
+    test, docs, or config, and proposes a review reading order (biggest
+    production diffs first). With explain=true the payload also carries
+    per-file plain-language explanations: LLM-written when the caller passes
+    an x-api-key, deterministic diff-derived notes otherwise.
     """
     try:
+        if explain:
+            api_key = request.headers.get("x-api-key")
+            return await pr_reading.analyze_pr_explained(url, explain=True, api_key=api_key)
         return pr_reading.analyze_pr(url)
     except ValueError as exc:
         raise HTTPException(400, str(exc)) from exc

{codeabc-0.1.2 → codeabc-0.1.3}/backend/services/action_plan.py

@@ -198,6 +198,13 @@ def _too_many_params_actions(too_many_params_files: list[dict] | None) -> list[d
     return actions
 
 
+def _missing_count(f: dict) -> int:
+    # typing_coverage emits the sample of unannotated symbol names (a list);
+    # older cached payloads may carry a bare count. Either way compare counts.
+    m = f.get("missing", 0)
+    return len(m) if isinstance(m, list) else m
+
+
 def _typing_actions(typing_files: list[dict] | None) -> list[dict]:
     if not typing_files:
         return []
@@ -205,11 +212,11 @@ def _typing_actions(typing_files: list[dict] | None) -> list[dict]:
     # Files with the most unannotated public symbols and low coverage first;
     # only surface genuinely under-annotated files (not a stray missing hint).
     weak = sorted(
-        (f for f in typing_files if f.get("missing", 0) >= 3 and f.get("coverage", 1) < 0.6),
-        key=lambda f: (-f.get("missing", 0), f.get("coverage", 1)),
+        (f for f in typing_files if _missing_count(f) >= 3 and f.get("coverage", 1) < 0.6),
+        key=lambda f: (-_missing_count(f), f.get("coverage", 1)),
     )
     for f in weak[:_MAX_PER_CATEGORY]:
-        missing = f.get("missing", 0)
+        missing = _missing_count(f)
         pct = round(f.get("coverage", 0) * 100)
         actions.append(
             {

{codeabc-0.1.2 → codeabc-0.1.3}/backend/services/envscan.py

@@ -165,3 +165,47 @@ def render_env_markdown(project_name: str, env_data: dict | None) -> str:
         lines.append("")
 
     return "\n".join(lines).rstrip() + "\n"
+
+
+_DOC_BASENAMES = (
+    ".env.example",
+    ".env.sample",
+    ".env.template",
+    ".env.defaults",
+)
+
+
+def _is_doc_candidate(path: str) -> bool:
+    """Whether a file is a place a newcomer would look for env configuration."""
+    lower = path.lower()
+    base = lower.rsplit("/", 1)[-1]
+    if base in _DOC_BASENAMES or base.startswith("readme"):
+        return True
+    if base.endswith(".md") and (
+        "/" not in lower or lower.startswith(("docs/", "doc/", ".github/"))
+    ):
+        return True
+    return False
+
+
+def find_undocumented_env_vars(scan: dict, file_contents: dict[str, str]) -> list[str]:
+    """Names of env vars that no documentation file mentions.
+
+    ``.env.example`` and the README are where a newcomer learns what to
+    configure; a variable the code reads but nobody writes down is a setup
+    landmine, doubly so when it is required. Matching is a whole-word search
+    over every documentation candidate, so ``HOST`` does not count as
+    documented just because ``DB_HOST`` appears. Pure over the scan result and
+    the file texts, so it is unit-testable with plain dicts.
+    """
+    doc_text = "\n".join(
+        content for path, content in file_contents.items() if _is_doc_candidate(path)
+    )
+    undocumented = []
+    for var in scan.get("vars", []):
+        name = var.get("name")
+        if not name:
+            continue
+        if not re.search(rf"(?<![A-Za-z0-9_]){re.escape(name)}(?![A-Za-z0-9_])", doc_text):
+            undocumented.append(name)
+    return undocumented

{codeabc-0.1.2 → codeabc-0.1.3}/backend/services/pr_reading.py

@@ -7,6 +7,7 @@ order. An LLM explanation layer can sit on top of this payload later.
 
 from __future__ import annotations
 
+import asyncio
 import json
 import re
 import subprocess
@@ -179,3 +180,131 @@ def render_markdown(analysis: dict) -> str:
 
 def to_json(analysis: dict) -> str:
     return json.dumps(analysis, ensure_ascii=False, indent=2)
+
+
+_EXPLAIN_MAX_FILES = 8
+_DIFF_EXCERPT_MAX_LINES = 120
+
+_SYMBOL_RE = re.compile(
+    r"^\+\s*(?:async\s+def|def|class|function|export\s+(?:async\s+)?function|export\s+class)\s+([A-Za-z_][\w]*)"
+)
+
+
+def _diff_sections(diff_text: str) -> dict[str, list[str]]:
+    """Map each file path to its raw diff lines (headers + hunks)."""
+    sections: dict[str, list[str]] = {}
+    current: str | None = None
+    for line in diff_text.splitlines():
+        if line.startswith("diff --git "):
+            match = re.match(r"diff --git a/(\S+) b/(\S+)", line)
+            current = match.group(2) if match else None
+            if current is not None:
+                sections[current] = [line]
+        elif current is not None:
+            sections[current].append(line)
+    return sections
+
+
+def _symbols_from_excerpt(excerpt_lines: list[str]) -> list[str]:
+    names: list[str] = []
+    for line in excerpt_lines:
+        m = _SYMBOL_RE.match(line)
+        if m and m.group(1) not in names:
+            names.append(m.group(1))
+    return names
+
+
+def _deterministic_note(change: FileChange, excerpt_lines: list[str]) -> str:
+    """Plain-language note without any LLM: what kind of file it is, its size, and the
+    functions/classes it adds or updates (from added definition lines in the diff)."""
+    symbols = _symbols_from_excerpt(excerpt_lines)
+    base = {
+        "code": "production code",
+        "test": "test",
+        "docs": "documentation",
+        "config": "configuration",
+    }.get(change.change_type, "other")
+    size = f"+{change.added} / -{change.deleted} lines"
+    if symbols:
+        return f"This {base} file ({size}) adds or updates: {', '.join(symbols[:6])}."
+    return f"This {base} file ({size}) is edited; open it to see the exact changes."
+
+
+def _excerpt(lines: list[str]) -> str:
+    if len(lines) <= _DIFF_EXCERPT_MAX_LINES:
+        return "\n".join(lines)
+    head = "\n".join(lines[:_DIFF_EXCERPT_MAX_LINES])
+    return head + f"\n... ({len(lines) - _DIFF_EXCERPT_MAX_LINES} more diff lines trimmed)"
+
+
+async def explain_files(
+    files: list[FileChange],
+    diff_text: str,
+    *,
+    api_key: str | None = None,
+    model: str | None = None,
+) -> dict[str, str]:
+    """Plain-language note per file. LLM-backed when a key is configured; otherwise a
+    deterministic note built from the diff itself, so the feature works key-free."""
+    from backend.services.llm import call_llm, is_error_text
+
+    sections = _diff_sections(diff_text)
+    out: dict[str, str] = {}
+
+    async def explain_one(change: FileChange) -> tuple[str, str]:
+        excerpt_lines = sections.get(change.path, [])
+        excerpt = _excerpt(excerpt_lines)
+        fallback = _deterministic_note(change, excerpt_lines)
+        if not api_key:
+            return change.path, fallback
+        prompt = (
+            "You are explaining one file's part of a pull request to someone who does not code.\n"
+            f"File: {change.path} ({change.change_type}, +{change.added} / -{change.deleted}).\n"
+            f"Diff excerpt:\n{excerpt}\n\n"
+            "In 2-3 plain sentences: what changed in this file and why it might matter. "
+            "No jargon; say the file name, not the path, when you refer to it."
+        )
+        text = (await call_llm(prompt, api_key=api_key, model=model)).strip()
+        if not text or is_error_text(text):
+            return change.path, fallback
+        return change.path, text
+
+    ordered = files[:_EXPLAIN_MAX_FILES]
+    results = await asyncio.gather(*(explain_one(f) for f in ordered))
+    out.update(results)
+    # Files beyond the cap still get the deterministic note so the UI never shows a gap.
+    for f in files[_EXPLAIN_MAX_FILES:]:
+        out[f.path] = _deterministic_note(f, sections.get(f.path, []))
+    return out
+
+
+async def analyze_pr_explained(
+    url: str, *, explain: bool, api_key: str | None = None, model: str | None = None
+) -> dict:
+    """analyze_pr plus optional per-file explanations (LLM when keyed, deterministic otherwise)."""
+    ref = parse_pr_url(url)
+    diff_text = await asyncio.to_thread(fetch_pr_diff, ref)
+    files = parse_diff_files(diff_text)
+    ordered = reading_order(files)
+    analysis = {
+        "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
+        ],
+    }
+    if explain:
+        analysis["explanations"] = await explain_files(
+            ordered, diff_text, api_key=api_key, model=model
+        )
+    return analysis

codeabc-0.1.3/backend/services/unused_exports.py

@@ -0,0 +1,185 @@
+"""Unused exports: public symbols that nothing else in the project references.
+
+Orphan modules answer "which files does nobody import?". This answers the
+finer question one level down: "which functions and classes inside otherwise
+used files does nobody call?". A public helper that was written for a caller
+that no longer exists is dead weight a new reader still has to load into
+their head, and it tends to be the code that breaks first in a refactor
+because nothing exercises it.
+
+:func:`find_unused_exports` walks the already-read file contents and flags
+top-level ``def`` / ``class`` definitions (Python) and ``export``ed
+``function`` / ``class`` / ``const`` declarations (JS/TS) whose name never
+shows up anywhere outside their own file.
+
+It deliberately stays conservative to keep the signal worth reading:
+
+* Anything decorated is skipped. Decorators are how frameworks register
+  things (FastAPI routes, pytest fixtures, click commands, tasks), and a
+  decorated definition is used by the framework even when no caller is
+  visible in the text.
+* Dunder names, private names (leading ``_``), and definitions inside test
+  files are skipped. Tests are consumers, not candidates.
+* A definition referenced only inside its own module still counts as a
+  candidate: a public symbol used only locally is effectively private and
+  could have been a ``_helper``.
+
+Findings are *candidates for human review, not verdicts*. String references,
+``getattr`` lookups, dynamic imports, and re-export barrels are not tracked,
+so anything here deserves a second look before deletion.
+"""
+
+from __future__ import annotations
+
+import re
+
+_PY = {"py", "pyi"}
+_JSTS = {"js", "jsx", "ts", "tsx", "mjs", "cjs", "mts", "cts"}
+
+_TEST_SEGMENTS = {"test", "tests", "__tests__", "spec", "specs"}
+
+_PY_DEF_RE = re.compile(r"^(async\s+def|def|class)\s+([A-Za-z_][A-Za-z0-9_]*)")
+_JS_EXPORT_RE = re.compile(
+    r"^\s*export\s+(?:async\s+)?(?:function|class|const|let)\s+([A-Za-z_$][A-Za-z0-9_$]*)"
+)
+
+# Names that look dead but are entry points by convention.
+_ENTRY_NAMES = {
+    "main",
+    "app",
+    "application",
+    "handler",
+    "create_app",
+    "run",
+    "cli",
+    "register",
+    "setup",
+    "teardown",
+    "ready",
+    "default",
+}
+
+_MAX_FINDINGS = 200
+
+
+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(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 ""
+    stem = name.rsplit(".", 1)[0] if "." in name else name
+    return stem.startswith("test_") or stem.endswith("_test") or ".test" in name or ".spec" in name
+
+
+def _collect_python_defs(path: str, text: str) -> list[dict]:
+    """Top-level, undecorated def/class definitions in one Python file."""
+    defs: list[dict] = []
+    pending_decorated = False
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        indent = len(line) - len(line.lstrip())
+        if stripped.startswith("@"):
+            if indent == 0:
+                pending_decorated = True
+            continue
+        if indent != 0:
+            pending_decorated = False
+            continue
+        m = _PY_DEF_RE.match(line)
+        if not m:
+            pending_decorated = False
+            continue
+        name = m.group(2)
+        decorated = pending_decorated
+        pending_decorated = False
+        if decorated or name.startswith("_") or name in _ENTRY_NAMES:
+            continue
+        kind = "class" if m.group(1) == "class" else "function"
+        defs.append({"path": path, "name": name, "kind": kind, "line": lineno})
+    return defs
+
+
+def _collect_js_defs(path: str, text: str) -> list[dict]:
+    defs: list[dict] = []
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        m = _JS_EXPORT_RE.match(line)
+        if not m:
+            continue
+        name = m.group(1)
+        if name.startswith("_") or name in _ENTRY_NAMES:
+            continue
+        kind = "class" if "class" in line.split("export", 1)[1].split(name)[0] else "function"
+        defs.append({"path": path, "name": name, "kind": kind, "line": lineno})
+    return defs
+
+
+def _referenced_outside(name: str, home: str, contents: dict[str, str]) -> bool:
+    """True when the name appears anywhere outside its own file.
+
+    Test files count as consumers here: a symbol exercised only by tests is
+    alive, it is just not part of the runtime surface.
+    """
+    word = re.compile(r"\b" + re.escape(name) + r"\b")
+    for path, text in contents.items():
+        if path == home:
+            continue
+        if word.search(text):
+            return True
+    return False
+
+
+def _referenced_locally_only(name: str, home: str, text: str) -> bool:
+    """True when the name is used in its own file beyond the definition line."""
+    return len(re.findall(r"\b" + re.escape(name) + r"\b", text)) > 1
+
+
+def find_unused_exports(file_contents: dict[str, str]) -> dict:
+    """Flag public definitions with no references outside their own file.
+
+    Returns a summary dict with ``total``, ``files_affected``, ``findings``
+    (path/name/kind/line/reason), and ``notes`` explaining the blind spots.
+    """
+    candidates: list[dict] = []
+    for path, text in file_contents.items():
+        ext = _ext(path)
+        if ext not in _PY and ext not in _JSTS:
+            continue
+        if _is_test(path):
+            continue
+        defs = _collect_python_defs(path, text) if ext in _PY else _collect_js_defs(path, text)
+        for d in defs:
+            if _referenced_outside(d["name"], path, file_contents):
+                continue
+            local = _referenced_locally_only(d["name"], path, text)
+            reason = (
+                f"public {d['kind']} used only inside its own module; "
+                "nothing imports it elsewhere (effectively private)"
+                if local
+                else f"public {d['kind']} with no references anywhere else in the project"
+            )
+            candidates.append({**d, "reason": reason})
+
+    candidates.sort(key=lambda c: (c["path"], c["line"]))
+    findings = candidates[:_MAX_FINDINGS]
+    return {
+        "total": len(candidates),
+        "files_affected": len({c["path"] for c in candidates}),
+        "findings": findings,
+        "notes": [
+            "Findings are candidates for human review, not proof of dead code: "
+            "string references, getattr, dynamic imports, and re-export barrels "
+            "are not tracked.",
+            "Decorated definitions are skipped because frameworks (FastAPI, "
+            "pytest, click, task queues) register them without a visible caller.",
+            "A symbol used only inside its own module is flagged as effectively "
+            "private, not necessarily dead.",
+        ],
+    }

{codeabc-0.1.2 → codeabc-0.1.3}/frontend/src/App.tsx

@@ -1,5 +1,6 @@
 import { BrowserRouter, Routes, Route } from "react-router-dom";
 import Home from "./pages/Home";
+import PrView from "./pages/PrView";
 import Overview from "./pages/Overview";
 import FileView from "./pages/FileView";
 import { I18nProvider } from "./lib/i18n";
@@ -10,6 +11,7 @@ function App() {
       <BrowserRouter>
         <Routes>
           <Route path="/" element={<Home />} />
+          <Route path="/pr" element={<PrView />} />
           <Route path="/project/:projectId" element={<Overview />} />
           <Route path="/project/:projectId/file/*" element={<FileView />} />
         </Routes>