codeabc 0.1.0__py3-none-any.whl

backend/services/codemap_export.py

@@ -0,0 +1,136 @@
+"""Assemble the full deterministic code map as a single Markdown document.
+
+The browser UI renders each analysis (import graph, risk, churn, coverage, ...)
+in its own panel. The ``codemap.md`` export stitches the same analyses into one
+file you can download and read offline or hand to someone else. Every section is
+produced by the service that owns that analysis; this module only decides which
+sections run, in what order, and how they are joined.
+"""
+
+from __future__ import annotations
+
+from backend.services import (
+    action_plan as action_plan_svc,
+)
+from backend.services import (
+    activity,
+    apimap,
+    async_surface,
+    churn,
+    ci_checks,
+    commands,
+    complexity,
+    contributing,
+    coverage,
+    datamodels,
+    deep_nesting,
+    dependencies,
+    docs,
+    docstrings,
+    duplicate_code,
+    entrypoints,
+    envscan,
+    error_handling,
+    importgraph,
+    integrations,
+    licenses,
+    long_functions,
+    ownership,
+    release_map,
+    risk,
+    schedules,
+    security,
+    settings_map,
+    techdebt,
+    too_many_params,
+    typing_coverage,
+)
+from backend.services import (
+    health_score as health_score_svc,
+)
+
+_SECTION_SEPARATOR = "\n\n---\n\n"
+
+
+def _ordered_sections(proj: dict) -> list[str]:
+    """Render every optional code-map section in display order.
+
+    Each service returns an empty string when it has nothing to report (for
+    example, churn/ownership need git history, so an uploaded folder skips them).
+    The import-graph code map is the always-present base and is handled by the
+    caller, so it is not part of this list.
+    """
+    name = proj["name"]
+    files = proj["files"]
+    contents = proj.get("file_contents", {})
+
+    return [
+        risk.render_risk_markdown(
+            risk.rank_risk(
+                importgraph.rank_hotspots(files, limit=500),
+                (proj.get("churn") or {}).get("hotspots", []),
+            )
+        ),
+        churn.render_churn_markdown(name, proj.get("churn")),
+        ownership.render_ownership_markdown(name, proj.get("ownership")),
+        coverage.render_coverage_markdown(name, coverage.assess_test_coverage(files)),
+        techdebt.render_techdebt_markdown(name, techdebt.scan_tech_debt(contents)),
+        envscan.render_env_markdown(name, envscan.scan_env_vars(contents)),
+        entrypoints.render_entrypoints_markdown(name, entrypoints.find_entry_points(contents)),
+        commands.render_commands_markdown(name, commands.find_cli_commands(contents)),
+        datamodels.render_data_models_markdown(name, datamodels.find_data_models(contents)),
+        settings_map.render_settings_markdown(name, settings_map.find_tunable_settings(contents)),
+        schedules.render_schedules_markdown(name, schedules.find_scheduled_tasks(contents)),
+        ci_checks.render_ci_checks_markdown(name, ci_checks.find_ci_checks(contents)),
+        release_map.render_release_markdown(name, release_map.find_release_info(contents)),
+        contributing.render_contributing_markdown(
+            name, contributing.find_contribution_guide(contents)
+        ),
+        licenses.render_licenses_markdown(name, licenses.find_licenses(contents)),
+        complexity.render_complexity_markdown(name, complexity.scan_complexity(contents)),
+        deep_nesting.render_deep_nesting_markdown(name, deep_nesting.scan_deep_nesting(contents)),
+        long_functions.render_long_functions_markdown(
+            name, long_functions.scan_long_functions(contents)
+        ),
+        too_many_params.render_too_many_params_markdown(
+            name, too_many_params.scan_too_many_params(contents)
+        ),
+        duplicate_code.render_duplicate_code_markdown(
+            name, duplicate_code.scan_duplicate_code(contents)
+        ),
+        dependencies.render_dependencies_markdown(name, dependencies.scan_dependencies(contents)),
+        security.render_security_markdown(name, security.scan_security(contents)),
+        apimap.render_apimap_markdown(name, apimap.scan_api_routes(contents)),
+        docs.render_doc_coverage_markdown(name, docs.assess_doc_coverage(contents)),
+        docstrings.render_docstring_coverage_markdown(
+            name, docstrings.scan_docstring_coverage(contents)
+        ),
+        typing_coverage.render_typing_coverage_markdown(
+            name, typing_coverage.scan_typing_coverage(contents)
+        ),
+        async_surface.render_async_surface_markdown(
+            name, async_surface.scan_async_surface(contents)
+        ),
+        error_handling.render_error_handling_markdown(
+            name, error_handling.find_swallowed_errors(contents)
+        ),
+        integrations.render_integrations_markdown(
+            name, integrations.detect_external_services(contents)
+        ),
+        activity.render_activity_markdown(name, proj.get("activity")),
+        health_score_svc.render_health_score_markdown(name, proj.get("health_score")),
+        action_plan_svc.render_action_plan_markdown(name, proj.get("action_plan")),
+    ]
+
+
+def build_codemap_markdown(proj: dict) -> str:
+    """Build the downloadable ``codemap.md`` for a scanned project.
+
+    The import-graph code map always leads; every other analysis is appended only
+    when it has content, separated by a horizontal rule.
+    """
+    markdown = importgraph.render_codemap_markdown(proj["name"], proj["files"])
+    for section in _ordered_sections(proj):
+        if section:
+            markdown = f"{markdown.rstrip()}{_SECTION_SEPARATOR}{section}"
+    return markdown

backend/services/commands.py

@@ -0,0 +1,276 @@
+"""CLI command surface — what you can actually type to drive the tool.
+
+The entry-points map answers "which file or console command starts the program"
+— that you run ``mytool`` or ``python manage.py``. It stops at the front door.
+This map walks through it: once you have a CLI, what *sub-commands* does it
+accept, and what does each one do? For someone evaluating a tool without reading
+the code, that is the real question — ``mytool build``, ``mytool deploy``, the
+list of verbs and the one-line help next to each.
+
+It reads the command surface straight from the source CodeABC already loaded —
+no LLM, and nothing to install or run — by recognising the three CLI frameworks
+that cover the overwhelming majority of Python tools:
+
+  argparse   ``sub = parser.add_subparsers(); sub.add_parser("build", help=...)``
+  click      ``@cli.command("build")`` / ``@click.command`` + ``@click.option``
+  typer      ``@app.command()`` on a ``typer.Typer()`` app
+
+Each command carries its name, the framework it came from, a short help line (the
+``help=`` argument, or the function's docstring first line), the option/argument
+flags it declares, and the file and line where it is defined.
+
+:func:`find_cli_commands` 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 three frameworks above, and only statically-declared commands.
+    Names or help built at runtime, plugin-loaded sub-commands, and groups
+    registered dynamically are out of scope.
+  * A file that does not parse as Python is skipped, not guessed at.
+  * Group nesting is recorded by each command's own name, not rebuilt into a
+    full ``parent child`` path.
+  * argparse option flags need dataflow to tie back to their sub-parser, so
+    argparse commands list their name and help but not their flags.
+"""
+
+from __future__ import annotations
+
+import ast
+
+# Decorator attribute names that register a CLI command or group.
+_COMMAND_ATTRS = ("command", "group")
+# Decorator attribute names that declare a flag/argument on a click/typer command.
+_OPTION_ATTRS = ("option", "argument")
+
+
+def _base_name(node: ast.expr) -> str | None:
+    """Return the left-most name of ``a`` in ``@a.command`` / ``@a.b.command``."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return _base_name(node.value)
+    return None
+
+
+def _first_string_arg(call: ast.Call) -> str | None:
+    for arg in call.args:
+        if isinstance(arg, ast.Constant) and isinstance(arg.value, str):
+            return arg.value
+    return None
+
+
+def _string_kwarg(call: ast.Call, name: str) -> str | None:
+    for kw in call.keywords:
+        if (
+            kw.arg == name
+            and isinstance(kw.value, ast.Constant)
+            and isinstance(kw.value.value, str)
+        ):
+            return kw.value.value
+    return None
+
+
+def _docstring_summary(func: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+    doc = ast.get_docstring(func)
+    if not doc:
+        return ""
+    for line in doc.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped
+    return ""
+
+
+def _command_decorator(dec: ast.expr) -> ast.Attribute | None:
+    """Return the decorator's target if it is a ``.command`` / ``.group`` one."""
+    target = dec.func if isinstance(dec, ast.Call) else dec
+    if isinstance(target, ast.Attribute) and target.attr in _COMMAND_ATTRS:
+        return target
+    return None
+
+
+def _option_flag(dec: ast.expr) -> str | None:
+    if isinstance(dec, ast.Call) and isinstance(dec.func, ast.Attribute):
+        if dec.func.attr in _OPTION_ATTRS:
+            return _first_string_arg(dec)
+    return None
+
+
+def _scan_imports_and_apps(tree: ast.Module) -> tuple[set[str], bool, bool, bool]:
+    """Return (typer_app_vars, click_imported, typer_imported, argparse_imported)."""
+    typer_apps: set[str] = set()
+    click_imported = typer_imported = False
+    argparse_imported = False
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                root = alias.name.split(".")[0]
+                click_imported |= root == "click"
+                typer_imported |= root == "typer"
+                argparse_imported |= root == "argparse"
+        elif isinstance(node, ast.ImportFrom):
+            root = (node.module or "").split(".")[0]
+            click_imported |= root == "click"
+            typer_imported |= root == "typer"
+            argparse_imported |= root == "argparse"
+        elif isinstance(node, ast.Assign) and isinstance(node.value, ast.Call):
+            func = node.value.func
+            # `app = typer.Typer(...)` or `app = Typer(...)`
+            is_typer = (isinstance(func, ast.Attribute) and func.attr == "Typer") or (
+                isinstance(func, ast.Name) and func.id == "Typer"
+            )
+            if is_typer:
+                for target in node.targets:
+                    if isinstance(target, ast.Name):
+                        typer_apps.add(target.id)
+
+    return typer_apps, click_imported, typer_imported, argparse_imported
+
+
+def _framework(
+    base: str | None, typer_apps: set[str], click_imp: bool, typer_imp: bool
+) -> str | None:
+    """Resolve which CLI framework a ``.command`` decorator belongs to."""
+    if base in typer_apps or base == "typer":
+        return "typer"
+    if base == "click":
+        return "click"
+    # `@cli.command` on a group variable — fall back to whatever the file imports.
+    if typer_imp and not click_imp:
+        return "typer"
+    if click_imp:
+        return "click"
+    return None
+
+
+def _decorated_commands(tree: ast.Module, path: str) -> list[dict]:
+    typer_apps, click_imp, typer_imp, _ = _scan_imports_and_apps(tree)
+    commands: list[dict] = []
+
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+
+        target = next(
+            (t for dec in node.decorator_list if (t := _command_decorator(dec)) is not None),
+            None,
+        )
+        if target is None:
+            continue
+
+        framework = _framework(_base_name(target.value), typer_apps, click_imp, typer_imp)
+        if framework is None:
+            continue
+
+        decorator = next(d for d in node.decorator_list if _command_decorator(d) is target)
+        name = None
+        help_text = ""
+        if isinstance(decorator, ast.Call):
+            name = _first_string_arg(decorator) or _string_kwarg(decorator, "name")
+            help_text = _string_kwarg(decorator, "help") or ""
+        name = name or node.name.replace("_", "-")
+        if not help_text:
+            help_text = _docstring_summary(node)
+
+        options = [f for dec in node.decorator_list if (f := _option_flag(dec))]
+        commands.append(
+            {
+                "name": name,
+                "framework": framework,
+                "help": help_text,
+                "options": options,
+                "path": path,
+                "line": node.lineno,
+            }
+        )
+
+    return commands
+
+
+def _argparse_commands(tree: ast.Module, path: str) -> list[dict]:
+    commands: list[dict] = []
+    for node in ast.walk(tree):
+        if not (isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)):
+            continue
+        if node.func.attr != "add_parser":
+            continue
+        name = _first_string_arg(node)
+        if not name:
+            continue
+        commands.append(
+            {
+                "name": name,
+                "framework": "argparse",
+                "help": _string_kwarg(node, "help") or "",
+                "options": [],
+                "path": path,
+                "line": node.lineno,
+            }
+        )
+    return commands
+
+
+def find_cli_commands(file_contents: dict[str, str], *, limit: int = 60) -> dict:
+    """Collect the CLI sub-commands a project exposes from its source.
+
+    Args:
+        file_contents: mapping of path to file text (as CodeABC already read it).
+        limit: how many commands to return in the sorted list.
+
+    Returns ``{"total", "frameworks", "commands"}`` where each command is
+    ``{"name", "framework", "help", "options", "path", "line"}`` and
+    ``framework`` is one of ``click`` / ``typer`` / ``argparse``.
+    """
+    seen: set[tuple[str, str]] = set()
+    commands: 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
+
+        _, _, _, argparse_imp = _scan_imports_and_apps(tree)
+        found = _decorated_commands(tree, path)
+        if argparse_imp:
+            found += _argparse_commands(tree, path)
+
+        for cmd in found:
+            key = (cmd["path"], cmd["name"])
+            if key in seen:
+                continue
+            seen.add(key)
+            commands.append(cmd)
+
+    commands.sort(key=lambda c: (c["path"], c["line"]))
+    frameworks = sorted({c["framework"] for c in commands})
+    return {"total": len(commands), "frameworks": frameworks, "commands": commands[:limit]}
+
+
+def render_commands_markdown(project_name: str, data: dict | None) -> str:
+    """Render the CLI command surface as Markdown, or ``""`` if none were found."""
+    commands = (data or {}).get("commands") or []
+    if not commands:
+        return ""
+
+    lines = [
+        f"# {project_name} — 能运行哪些命令（CLI 命令）",
+        "",
+        "> 入口点告诉你“用哪个命令启动”，这里告诉你“启动后能敲哪些子命令”——"
+        "作者用 argparse / click / typer 声明的子命令，以及每个命令的一句话说明。",
+        "",
+    ]
+    for cmd in commands:
+        head = f"- `{cmd['name']}`"
+        if cmd["help"]:
+            head += f" — {cmd['help']}"
+        head += f"  （{cmd['framework']}，{cmd['path']}）"
+        lines.append(head)
+        if cmd["options"]:
+            lines.append(f"  - 选项：{', '.join(f'`{o}`' for o in cmd['options'])}")
+
+    return "\n".join(lines).rstrip() + "\n"

backend/services/complexity.py

@@ -0,0 +1,111 @@
+"""Logic complexity: which files are the hardest to follow.
+
+The import-graph maps say which files are *central*; churn says which change
+*often*; this says which carry the most tangled *logic* — the files packed with
+branches, loops and nested conditions that a reader has to hold in their head.
+For someone learning a codebase, "where is the gnarliest logic" is a different
+and useful question from "what's central" or "what changes a lot".
+
+It approximates cyclomatic complexity from the Python AST: every decision point
+(an ``if``, ``for``, ``while``, ``except``, a boolean ``and``/``or``, a ternary,
+a comprehension filter, a ``match`` case) is one more independent path through
+the code, so more of them means more to reason about. ``scan_complexity`` is
+pure over the file contents and parses with the standard library, so it needs no
+repository; non-Python files and files that don't parse are skipped.
+"""
+
+from __future__ import annotations
+
+import ast
+
+# AST node types that introduce an extra branch (one more independent path).
+_BRANCH_NODES = (
+    ast.If,
+    ast.For,
+    ast.AsyncFor,
+    ast.While,
+    ast.ExceptHandler,
+    ast.With,
+    ast.AsyncWith,
+    ast.IfExp,  # a ... if cond else b
+    ast.Assert,
+    ast.comprehension,  # the `for` clause of a comprehension
+    ast.match_case,
+)
+
+
+def _file_complexity(tree: ast.AST) -> tuple[int, int]:
+    """Return (complexity, function_count) for a parsed module.
+
+    Complexity starts at 1 for the module's straight-line path and gains one for
+    each decision point; each boolean operator chain adds one per extra operand
+    (``a and b and c`` is two more branches), and each comprehension ``if`` adds
+    one too.
+    """
+    complexity = 1
+    functions = 0
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            functions += 1
+            complexity += 1
+        elif isinstance(node, _BRANCH_NODES):
+            complexity += 1
+        elif isinstance(node, ast.BoolOp):
+            # `a and b and c` has two operators after the first => two branches.
+            complexity += len(node.values) - 1
+        elif isinstance(node, ast.ListComp | ast.SetComp | ast.DictComp | ast.GeneratorExp):
+            # Filters inside the comprehension; the `for` clauses are counted as
+            # ast.comprehension above.
+            complexity += sum(len(gen.ifs) for gen in node.generators)
+    return complexity, functions
+
+
+def scan_complexity(file_contents: dict[str, str], *, limit: int = 15) -> dict:
+    """Rank the project's Python files by approximate logic complexity.
+
+    Args:
+        file_contents: mapping of path to file text (as CodeABC already read it).
+        limit: how many of the most complex files to return.
+
+    Returns ``{"total", "files"}`` where ``files`` is the most complex Python
+    files (descending), each ``{"path", "complexity", "functions", "reason"}``.
+    """
+    scored: 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
+        complexity, functions = _file_complexity(tree)
+        if complexity <= 1:
+            continue  # straight-line file, nothing to flag
+        reason = (
+            f"约 {complexity} 个判断分支，{functions} 个函数"
+            if functions
+            else f"约 {complexity} 个判断分支"
+        )
+        scored.append(
+            {"path": path, "complexity": complexity, "functions": functions, "reason": reason}
+        )
+
+    scored.sort(key=lambda f: (-f["complexity"], f["path"]))
+    return {"total": len(scored), "files": scored[:limit]}
+
+
+def render_complexity_markdown(project_name: str, data: dict | None) -> str:
+    """Render the complexity ranking as Markdown, or ``""`` if none."""
+    files = (data or {}).get("files") or []
+    if not files:
+        return ""
+
+    lines = [
+        f"# {project_name} — 逻辑复杂度（最难看懂的文件）",
+        "",
+        "> 按代码里「要分情况讨论」的地方（条件判断、循环、异常处理等）多少排序——"
+        "分支越多，逻辑越绕、越要小心读。这和“被很多文件依赖”“改得勤”是不同的角度。",
+        "",
+    ]
+    lines.extend(f"- `{f['path']}` — {f['reason']}（复杂度 {f['complexity']}）" for f in files)
+    return "\n".join(lines).rstrip() + "\n"