codaviz 0.5.0__py3-none-any.whl

codaviz/__init__.py

@@ -0,0 +1,7 @@
+"""codaviz — analyze and visualize complexity hotspots in Python codebases."""
+
+from __future__ import annotations
+
+from codaviz._version import __version__
+
+__all__ = ["__version__"]

codaviz/_version.py

@@ -0,0 +1,10 @@
+"""Resolve the installed package version (single source of truth: pyproject)."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("codaviz")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0"

codaviz/analysis/__init__.py

@@ -0,0 +1,12 @@
+"""Analysis orchestration: turn discovered files into a flat entity list.
+
+Builds PACKAGE, MODULE (SLOC + maintainability index), and FUNCTION (cyclomatic
+complexity) entities. Circular-import findings are computed separately by
+``analysis.imports`` (static AST, surfaced in the HTML report).
+"""
+
+from __future__ import annotations
+
+from codaviz.analysis.project import analyze_project
+
+__all__ = ["analyze_project"]

codaviz/analysis/complexity.py

@@ -0,0 +1,63 @@
+"""Per-function complexity: cyclomatic (mccabe) + cognitive (SonarSource).
+
+Cyclomatic complexity comes from the ``mccabe`` library, so the numbers match
+Ruff's C901 and ``python -m mccabe``. Cognitive complexity comes from the
+``cognitive_complexity`` library. End lines (for source snippets) come from the
+AST, joined to mccabe's per-function results by line number.
+
+Like Ruff/mccabe, nested closures and function-local-class methods are folded
+into their enclosing function rather than listed separately.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+from cognitive_complexity.api import get_cognitive_complexity
+from mccabe import PathGraphingAstVisitor
+
+
+@dataclass(frozen=True)
+class FunctionInfo:
+    """Complexity for a single function or method."""
+
+    name: str  # qualified name, e.g. "A.method"
+    lineno: int
+    endline: int
+    complexity: int  # cyclomatic (mccabe)
+    cognitive: int  # cognitive (SonarSource)
+
+
+def function_infos(source: str) -> list[FunctionInfo]:
+    """Return complexity records for the functions/methods in ``source``.
+
+    Raises ``SyntaxError`` if ``source`` is not valid Python.
+    """
+    tree = ast.parse(source)
+
+    visitor = PathGraphingAstVisitor()
+    visitor.preorder(tree, visitor)
+    cyclomatic = {g.lineno: (g.entity, g.complexity()) for g in visitor.graphs.values()}
+
+    nodes: dict[int, ast.FunctionDef | ast.AsyncFunctionDef] = {
+        node.lineno: node
+        for node in ast.walk(tree)
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+    }
+
+    infos = []
+    for lineno, (name, complexity) in sorted(cyclomatic.items()):
+        node = nodes.get(lineno)
+        if node is None:
+            continue
+        infos.append(
+            FunctionInfo(
+                name=name,
+                lineno=lineno,
+                endline=node.end_lineno or lineno,
+                complexity=complexity,
+                cognitive=get_cognitive_complexity(node),
+            ),
+        )
+    return infos

codaviz/analysis/imports.py

@@ -0,0 +1,171 @@
+"""Static circular-import detection (no code execution).
+
+Parses *module-level* import statements from the discovered files into a directed
+graph of internal modules, then reports strongly-connected components of size > 1
+(Tarjan). Imports inside functions/classes are ignored (they don't cause
+import-time cycles), as are ``if TYPE_CHECKING:`` blocks.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+    from pathlib import Path
+
+
+def find_import_cycles(root: Path, module_paths: Iterable[str]) -> list[list[str]]:
+    """Return circular-import groups as sorted lists of repo-relative module paths."""
+    root_is_package = (root / "__init__.py").is_file()
+    prefix = root.name + "." if root_is_package else ""
+
+    info: dict[str, tuple[str, bool]] = {}
+    for posix in module_paths:
+        name, is_pkg = _module_name(posix, prefix)
+        info[name] = (posix, is_pkg)
+
+    internal = set(info)
+    graph: dict[str, set[str]] = {name: set() for name in internal}
+    for name, (posix, is_pkg) in info.items():
+        try:
+            tree = ast.parse((root / posix).read_text(encoding="utf-8-sig"))
+        except (OSError, SyntaxError, ValueError):
+            continue
+        anchor = name if is_pkg else _parent(name)
+        for candidate in _imported(tree, anchor):
+            target = _resolve(candidate, internal)
+            if target is not None and target != name:
+                graph[name].add(target)
+
+    cycles = [sorted(info[n][0] for n in comp) for comp in _sccs(graph)]
+    cycles.sort(key=len, reverse=True)
+    return cycles
+
+
+def _module_name(posix: str, prefix: str) -> tuple[str, bool]:
+    parts = posix.split("/")
+    is_pkg = parts[-1] == "__init__.py"
+    if is_pkg:
+        parts = parts[:-1]
+    else:
+        parts[-1] = parts[-1].removesuffix(".py")
+    dotted = ".".join(parts)
+    return (prefix + dotted if dotted else prefix.rstrip(".")), is_pkg
+
+
+def _parent(name: str) -> str:
+    return name.rsplit(".", 1)[0] if "." in name else ""
+
+
+def _imported(tree: ast.Module, anchor: str) -> Iterator[str]:
+    for node in _iter_import_nodes(tree.body):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                yield alias.name
+        else:  # ast.ImportFrom
+            if node.level == 0:
+                base = node.module
+            else:
+                base = _resolve_relative(anchor, node.level, node.module)
+            if base is None:
+                continue
+            yield base
+            for alias in node.names:
+                yield base + "." + alias.name
+
+
+def _resolve_relative(anchor: str, level: int, module: str | None) -> str | None:
+    parts = anchor.split(".") if anchor else []
+    up = level - 1
+    if up > len(parts):
+        return None
+    base_parts = parts[: len(parts) - up] if up else list(parts)
+    if module:
+        base_parts += module.split(".")
+    return ".".join(base_parts) or None
+
+
+def _resolve(candidate: str, internal: set[str]) -> str | None:
+    parts = candidate.split(".")
+    while parts:
+        name = ".".join(parts)
+        if name in internal:
+            return name
+        parts.pop()
+    return None
+
+
+def _iter_import_nodes(body: list[ast.stmt]) -> Iterator[ast.Import | ast.ImportFrom]:
+    """Yield module-level import nodes, descending into module-level control flow."""
+    for node in body:
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            yield node
+        elif isinstance(node, ast.If):
+            if not _is_type_checking(node.test):
+                yield from _iter_import_nodes(node.body)
+            yield from _iter_import_nodes(node.orelse)
+        elif isinstance(node, ast.Try):
+            yield from _iter_import_nodes(node.body)
+            for handler in node.handlers:
+                yield from _iter_import_nodes(handler.body)
+            yield from _iter_import_nodes(node.orelse)
+            yield from _iter_import_nodes(node.finalbody)
+        elif isinstance(node, ast.With):
+            yield from _iter_import_nodes(node.body)
+
+
+def _is_type_checking(test: ast.expr) -> bool:
+    if isinstance(test, ast.Name):
+        return test.id == "TYPE_CHECKING"
+    return isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING"
+
+
+def _sccs(graph: dict[str, set[str]]) -> list[list[str]]:  # noqa: C901 - Tarjan SCC
+    """Tarjan's strongly-connected components (iterative); only components > 1 node."""
+    index: dict[str, int] = {}
+    low: dict[str, int] = {}
+    on_stack: set[str] = set()
+    stack: list[str] = []
+    components: list[list[str]] = []
+    counter = 0
+
+    for start, start_neighbors in graph.items():
+        if start in index:
+            continue
+        work = [(start, iter(start_neighbors))]
+        index[start] = low[start] = counter
+        counter += 1
+        stack.append(start)
+        on_stack.add(start)
+        while work:
+            node, successors = work[-1]
+            descended = False
+            for succ in successors:
+                if succ not in index:
+                    index[succ] = low[succ] = counter
+                    counter += 1
+                    stack.append(succ)
+                    on_stack.add(succ)
+                    work.append((succ, iter(graph[succ])))
+                    descended = True
+                    break
+                if succ in on_stack:
+                    low[node] = min(low[node], index[succ])
+            if descended:
+                continue
+            if low[node] == index[node]:
+                component = []
+                while True:
+                    member = stack.pop()
+                    on_stack.discard(member)
+                    component.append(member)
+                    if member == node:
+                        break
+                if len(component) > 1:
+                    components.append(component)
+            work.pop()
+            if work:
+                low[work[-1][0]] = min(low[work[-1][0]], low[node])
+    return components

codaviz/analysis/metrics.py

@@ -0,0 +1,22 @@
+"""Per-module metrics via radon: source lines (raw) and maintainability index."""
+
+from __future__ import annotations
+
+from radon.metrics import mi_visit
+from radon.raw import analyze as _raw_analyze
+
+
+def source_lines(source: str) -> int:
+    """Return the SLOC (source lines of code) for a module's source text.
+
+    Raises ``SyntaxError`` if ``source`` is not valid Python.
+    """
+    return _raw_analyze(source).sloc
+
+
+def maintainability_index(source: str) -> float:
+    """Return the maintainability index (0-100, higher is better) for ``source``.
+
+    Raises ``SyntaxError`` if ``source`` is not valid Python.
+    """
+    return round(mi_visit(source, multi=True), 2)

codaviz/analysis/project.py

@@ -0,0 +1,106 @@
+"""Build the flat entity list for a project from discovered files.
+
+Module entities carry SLOC + maintainability index; each function/method is its
+own FUNCTION entity carrying cyclomatic complexity. Module-level CC aggregation
+(max/sum over child functions) is derived by the report layer, not stored here,
+so the flat list stays the single source of truth.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from codaviz.analysis.complexity import function_infos
+from codaviz.analysis.metrics import maintainability_index, source_lines
+from codaviz.config import load_config
+from codaviz.discovery import discover
+from codaviz.model import Entity, EntityKind, Metrics
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def analyze_project(root: Path) -> list[Entity]:
+    """Analyze the project rooted at ``root`` and return a flat entity list."""
+    config = load_config(root)
+    extra_excludes: Sequence[str] = config.get("exclude", [])
+    include_tests = bool(config.get("include-tests", False))
+    files = discover(root, include_tests=include_tests, extra_excludes=extra_excludes)
+
+    entities: dict[str, Entity] = {}
+    for rel in files:
+        module_id = rel.as_posix()
+        # utf-8-sig strips a BOM; strict decoding surfaces non-UTF-8 files so we
+        # skip them instead of silently analysing mangled text. The read sits
+        # inside the per-file boundary so a stale/unreadable file never aborts.
+        try:
+            source = (root / rel).read_text(encoding="utf-8-sig")
+        except (OSError, UnicodeDecodeError) as exc:
+            print(f"codaviz: skipping {module_id}: {exc}", file=sys.stderr)
+            continue
+        parent_id = _ensure_packages(rel, entities)
+        metrics, functions = _analyze_module(source, module_id)
+        entities[module_id] = Entity(
+            id=module_id,
+            name=rel.name,
+            kind=EntityKind.MODULE,
+            path=module_id,
+            parent_id=parent_id,
+            metrics=metrics,
+        )
+        for function in functions:
+            entities[function.id] = function
+    return list(entities.values())
+
+
+def _analyze_module(source: str, module_id: str) -> tuple[Metrics, list[Entity]]:
+    """Compute module metrics and FUNCTION entities; degrade gracefully on errors."""
+    try:
+        metrics = Metrics(
+            sloc=source_lines(source),
+            mi=maintainability_index(source),
+        )
+        infos = function_infos(source)
+    except Exception as exc:  # noqa: BLE001 - one bad file must not abort the run
+        print(f"codaviz: skipping metrics for {module_id}: {exc}", file=sys.stderr)
+        return Metrics(), []
+
+    functions = [
+        Entity(
+            id=f"{module_id}::{info.name}#{info.lineno}",
+            name=info.name,
+            kind=EntityKind.FUNCTION,
+            path=module_id,
+            parent_id=module_id,
+            lineno=info.lineno,
+            endline=info.endline,
+            metrics=Metrics(cc=info.complexity, cognitive=info.cognitive),
+        )
+        for info in infos
+    ]
+    return metrics, functions
+
+
+def _ensure_packages(rel: Path, entities: dict[str, Entity]) -> str | None:
+    """Create PACKAGE entities for each ancestor dir of ``rel``; return parent id."""
+    parent = rel.parent
+    if parent == Path():
+        return None
+    parent_id: str | None = None
+    accumulated: list[str] = []
+    package_id = None
+    for part in parent.parts:
+        accumulated.append(part)
+        package_id = "/".join(accumulated)
+        if package_id not in entities:
+            entities[package_id] = Entity(
+                id=package_id,
+                name=part,
+                kind=EntityKind.PACKAGE,
+                path=package_id,
+                parent_id=parent_id,
+            )
+        parent_id = package_id
+    return package_id

codaviz/cli.py

@@ -0,0 +1,76 @@
+"""Command-line interface for codaviz."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from codaviz import __version__
+from codaviz.analysis import analyze_project
+from codaviz.config import load_config
+from codaviz.export.csv import to_csv
+from codaviz.export.json import to_json
+from codaviz.report import render_report
+
+app = App(
+    name="codaviz",
+    help="Analyze and visualize complexity hotspots in Python codebases.",
+    version=__version__,
+)
+
+
+@app.default
+def analyze(
+    path: Path = Path(),
+    *,
+    output: Annotated[Path | None, Parameter(name=["--output", "-o"])] = None,
+    output_format: Annotated[str, Parameter(name=["--format", "-f"])] = "html",
+    no_source: Annotated[bool, Parameter(negative="")] = False,
+) -> None:
+    """Analyze PATH and write a complexity report.
+
+    Parameters
+    ----------
+    path
+        Path to the Python project to analyze.
+    output
+        Output file path. Defaults to stdout for json/csv, report.html for html.
+    output_format
+        Output format: html, json, or csv.
+    no_source
+        Omit embedded source snippets from the report.
+    """
+    entities = analyze_project(path)
+
+    if output_format == "json":
+        text = to_json(entities)
+    elif output_format == "csv":
+        text = to_csv(entities)
+    elif output_format == "html":
+        config = load_config(path)
+        text = render_report(
+            entities,
+            root=str(path),
+            no_source=no_source,
+            max_complexity=int(config.get("max-complexity", 15)),
+            max_cognitive=int(config.get("max-cognitive", 15)),
+        )
+        if output is None:
+            output = Path("report.html")  # HTML goes to a file, never stdout
+    else:
+        print(f"codaviz: unknown format {output_format!r}", file=sys.stderr)
+        raise SystemExit(2)
+
+    if output is None:
+        print(text)
+    else:
+        output.write_text(text, encoding="utf-8")
+        print(f"codaviz: wrote {output}", file=sys.stderr)
+
+
+def main() -> None:
+    """Entry point for the ``codaviz`` console script."""
+    app()

codaviz/config.py

@@ -0,0 +1,19 @@
+"""Load codaviz configuration from the ``[tool.codaviz]`` table in pyproject.toml."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import tomllib
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def load_config(root: Path) -> dict[str, Any]:
+    """Return the ``[tool.codaviz]`` table from ``root/pyproject.toml`` (or ``{}``)."""
+    pyproject = root / "pyproject.toml"
+    if not pyproject.is_file():
+        return {}
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    return data.get("tool", {}).get("codaviz", {})

codaviz/discovery.py

@@ -0,0 +1,119 @@
+"""Discover analysable Python files.
+
+Inside a git repository we ask git for the project's ``.py`` files via
+``git ls-files --cached --others --exclude-standard``: this returns tracked
+*and* uncommitted files while honouring ``.gitignore`` (so a fresh checkout
+still works, and ignored trees like ``.venv`` are skipped). When the target is
+not a git repository we fall back to a pruning filesystem walk. Smart excludes
+(``.venv``, migrations, caches, ...) and ``[tool.codaviz]`` exclude globs are
+applied in both cases. Test files are excluded unless ``include_tests`` is set.
+"""
+
+from __future__ import annotations
+
+import subprocess  # noqa: S404
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+DEFAULT_EXCLUDE_DIRS = frozenset({
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "venv",
+    ".env",
+    "env",
+    "__pycache__",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".pytest_cache",
+    ".tox",
+    ".nox",
+    ".eggs",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "migrations",
+})
+
+_TEST_DIR_NAMES = frozenset({"test", "tests"})
+
+
+def discover(
+    root: Path,
+    *,
+    include_tests: bool = False,
+    extra_excludes: Sequence[str] = (),
+) -> list[Path]:
+    """Return repo-relative paths of analysable ``.py`` files under ``root``, sorted."""
+    git_files = _git_python_files(root)
+    if git_files is None:
+        print(
+            f"codaviz: {root} is not a git repository; "
+            "falling back to a filesystem walk.",
+            file=sys.stderr,
+        )
+        candidates = _walk_python_files(root)
+    else:
+        candidates = git_files
+    kept = [
+        rel
+        for rel in candidates
+        if not _is_excluded(rel, include_tests=include_tests, extra=extra_excludes)
+    ]
+    return sorted(kept)
+
+
+def _git_python_files(root: Path) -> list[Path] | None:
+    """Return git-known ``.py`` paths (tracked + uncommitted, ignored excluded).
+
+    Returns ``None`` when ``root`` is not inside a git repository.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "ls-files", "-z", "--cached", "--others", "--exclude-standard"],  # noqa: S607
+            cwd=root,
+            capture_output=True,
+            check=True,
+            text=True,
+        )
+    except (OSError, subprocess.CalledProcessError):
+        return None
+    files = (Path(name) for name in result.stdout.split("\0") if name)
+    return [p for p in files if p.suffix == ".py"]
+
+
+def _walk_python_files(root: Path) -> list[Path]:
+    """Walk the tree for ``.py`` files, pruning excluded directories as we go."""
+    found: list[Path] = []
+    for dirpath, dirnames, filenames in root.walk():
+        dirnames[:] = [d for d in dirnames if d not in DEFAULT_EXCLUDE_DIRS]
+        found.extend(
+            (dirpath / name).relative_to(root)
+            for name in filenames
+            if name.endswith(".py")
+        )
+    return found
+
+
+def _is_excluded(rel: Path, *, include_tests: bool, extra: Sequence[str]) -> bool:
+    parts = set(rel.parts)
+    if parts & DEFAULT_EXCLUDE_DIRS:
+        return True
+    if not include_tests and _looks_like_test(rel):
+        return True
+    return any(rel.match(pattern) for pattern in extra)
+
+
+def _looks_like_test(rel: Path) -> bool:
+    if _TEST_DIR_NAMES & set(rel.parts):
+        return True
+    name = rel.name
+    return (
+        name == "conftest.py" or name.startswith("test_") or name.endswith("_test.py")
+    )

codaviz/export/__init__.py

@@ -0,0 +1,6 @@
+"""Exporters: render the flat entity list to JSON or CSV.
+
+Implemented in Tasks 4 (JSON) and 6 (CSV).
+"""
+
+from __future__ import annotations

codaviz/export/csv.py

@@ -0,0 +1,53 @@
+"""Serialise the flat entity list to CSV (one row per entity)."""
+
+from __future__ import annotations
+
+import csv
+import io
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from codaviz.model import Entity
+
+FIELDS = (
+    "id",
+    "name",
+    "kind",
+    "path",
+    "parent_id",
+    "lineno",
+    "endline",
+    "sloc",
+    "cc",
+    "cognitive",
+    "mi",
+)
+
+
+def to_csv(entities: list[Entity]) -> str:
+    """Render the entity list as CSV with one row per entity.
+
+    Metrics are flattened into their own columns; absent values are blank.
+    """
+    out = io.StringIO()
+    writer = csv.DictWriter(
+        out,
+        fieldnames=FIELDS,
+        extrasaction="ignore",
+        lineterminator="\n",
+    )
+    writer.writeheader()
+    for entity in entities:
+        writer.writerow(
+            {
+                "id": entity.id,
+                "name": entity.name,
+                "kind": entity.kind.value,
+                "path": entity.path,
+                "parent_id": entity.parent_id,
+                "lineno": entity.lineno,
+                "endline": entity.endline,
+                **entity.metrics.as_dict(),
+            },
+        )
+    return out.getvalue()

codaviz/export/json.py

@@ -0,0 +1,14 @@
+"""Serialise the flat entity list to JSON."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from codaviz.model import Entity
+
+
+def to_json(entities: list[Entity], *, indent: int = 2) -> str:
+    """Render the entity list as a JSON array of objects."""
+    return json.dumps([entity.as_dict() for entity in entities], indent=indent)